Análise detalhada do sgcWebSockets WebAuthn Server

O componente TsgcWSAPIServer_WebAuthn é um módulo de servidor Delphi/FPC que implementa o lado relying-party do protocolo WebAuthn sobre HTTPS. Ele se integra ao TsgcWebSocketHTTPServer ou ao TsgcWebSocketServer e expõe endpoints no estilo REST para registro e autenticação. 

Mecânica dos endpoints

Por padrão, o componente registra rotas sob /sgcWebAuthn:

Os endpoints podem ser remapeados por meio de EndpointOptions para se ajustarem a esquemas de roteamento existentes. 

Propriedades principais

1. RelyingParty (RPID / RPName) – Nome DNS obrigatório que identifica o domínio lógico das credenciais. Garanta que ele corresponda ao domínio efetivo da sua aplicação.
2. Origins & TopOrigins – Listas separadas por ponto e vírgula de origens válidas. Origins cobre os domínios primários; TopOrigins é usado ao incorporar em iframes.
3. AllowCrossOrigins – Se definido como True, iframes de origem cruzada podem solicitar autenticação. Isso exige TopOrigins cuidadosamente curado e validação no lado do servidor.
4. Algorithms – Identificadores de algoritmo COSE suportados (por exemplo, ES256, RS256, EdDSA). Isso controla quais tipos de chave pública o servidor aceitará.
5. TimeoutMS – Timeout sugerido ao cliente para concluir operações WebAuthn.
6. UserVerification – Política para verificação do usuário (preferred, required, discouraged).
7. Attestation – Especifica se o attestation é none, indirect ou direct. O attestation direto exige validação da cadeia de certificados de attestation.
8. Metadata Service (MDS) – Quando habilitado, o componente consulta arquivos do FIDO Metadata Service para confirmar a confiabilidade do modelo do autenticador. Campos:
   • MDS_FileName – JSON de metadados em cache local (baixado da FIDO).
   • RootCert_FileName – Certificado raiz para verificar assinaturas de metadados.
9. ChallengeOptions – Permite comprimento personalizado e fonte de aleatoriedade para os desafios gerados.
10. CredentialStorage – Embora não seja uma propriedade direta, o componente espera que a aplicação persista as chaves públicas das credenciais, os contadores de assinatura e os user handles.

Ciclo de vida dos eventos

Registro

• OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): inspeciona o nome de usuário, aborta se inválido ou fornece informações do usuário.
• OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): modifica o desafio ou define critérios de seleção do autenticador antes de enviar ao cliente.
• OnWebAuthnRegistrationVerify(Sender, Credential, var Success): realiza verificações de attestation personalizadas ou veta o registro.
• OnWebAuthnRegistrationSuccessful(Sender, Credential): armazena o ID da credencial, a chave pública, o contador de assinatura e o user handle em seu banco de dados.
• OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): registra em log ou retorna erros mais descritivos.

Autenticação

• OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): consulta os IDs de credencial para o nome de usuário, decide os transportes permitidos (USB, NFC, BLE, interno).
• OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response): personaliza UserVerification, ajusta o comprimento do desafio ou incorpora metadados adicionais.
• OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): valida a progressão do contador de assinatura, aplica verificações de status da conta.
• OnWebAuthnAuthenticationSuccessful(Sender, Credential): atualiza o contador de assinatura e produz tokens de sessão.
• OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): implementa rate limiting, políticas de bloqueio e auditoria.

Esses eventos permitem controle refinado sobre cada etapa do protocolo, desde a geração de opções até o processamento de asserções.