Autenticação Multifator

O Hedhog suporta três métodos de segundo fator — TOTP (apps autenticadores), códigos de uso único por e-mail e WebAuthn (passkeys/chaves de segurança) — além de códigos de recuperação de uso único para recuperação de conta. Este é um recurso totalmente implementado, construído sobre speakeasy (TOTP), qrcode (geração de QR) e @simplewebauthn/server (WebAuthn), tudo em libraries/core/src/profile/.

Status: ✅ Totalmente implementado — TOTP, Email OTP, WebAuthn e códigos de recuperação funcionam, incluindo o fluxo de desafio de login.

1. Certifique-se de que um provedor de e-mail está configurado se você for permitir Email OTP
2. Registre o TOTP você mesmo primeiro: POST /profile/totp/generate → escaneie o QR code → POST /profile/totp/verify
3. Saia e entre novamente — confirme que a resposta retorna requiresMfa: true antes de qualquer token ser emitido, e que enviar o código completa o login
4. Salve os códigos de recuperação mostrados no registro — não há como visualizá-los novamente depois

Todo o registro acontece através dos endpoints /profile/*, restritos ao usuário logado:

Cada método registrado se torna uma linha em user_mfa (type ∈ totp, email, webauthn), com o secret/credencial armazenado em uma tabela user_mfa_totp, user_mfa_email ou user_mfa_webauthn correspondente.

Esta é a parte que passa fácil despercebida se você só ler os endpoints de registro: o login em si não chama nenhuma rota /profile/mfa/*. Uma vez que uma senha é verificada para um usuário com pelo menos um método de MFA registrado, o AuthService retorna:

{ "requiresMfa": true, "mfaToken": "..." }

em vez de um access token. Sua UI de login precisa checar por requiresMfa e solicitar o segundo fator usando esse mfaToken de curta duração — não a sessão do usuário:

Somente depois que um desses tem sucesso é que o backend emite o par real de access/refresh token.

Configure-as em Settings → Configurations → Authentication — as configurações de MFA ficam neste grupo, não em um "MFA" dedicado.

Funciona com qualquer app RFC 6238: Google Authenticator, Authy, Microsoft Authenticator, 1Password, Bitwarden.

1. O cliente chama POST /profile/totp/generate — o servidor retorna { secret, otpauthUrl, qrCode }
2. O usuário escaneia o qrCode (ou insere manualmente o secret) no seu app autenticador
3. O cliente chama POST /profile/totp/verify com o primeiro código de 6 dígitos que o app mostra, mais o secret e um name para o dispositivo
4. O Hedhog valida o código contra o secret (honrando mfa-window/mfa-setp) e, apenas em caso de sucesso, persiste o método e emite códigos de recuperação se este for o primeiro método de MFA do usuário

Se o código é sempre rejeitado mesmo recém-gerado, a causa mais comum é desvio de relógio real no servidor ou no telefone do usuário — mfa-window absorve um pouco disso, mas não desvio ilimitado.

Nenhum app necessário — funciona para qualquer usuário com um e-mail verificado.

1. POST /profile/mfa/email/verify envia um código (comprimento conforme mfa-email-code-length) para o e-mail da conta
2. POST /profile/mfa/email/verify/confirm o ativa assim que o usuário insere o código

No login, o par equivalente é POST /auth/verify-mfa-code (methodType: 'email') e POST /auth/resend-mfa-code se o código expirou ou nunca chegou. O Email OTP obviamente depende de um provedor de e-mail funcional — se a entrega de e-mails estiver quebrada, usuários registrados apenas em MFA por e-mail ficarão totalmente trancados para fora do login, não apenas do registro.

Segundo fator baseado em padrões e resistente a phishing, usando a API WebAuthn nativa do navegador (Touch ID, Windows Hello, chaves de hardware como a YubiKey).

1. POST /profile/webauthn/generate retorna opções de registro (name é o rótulo mostrado para este dispositivo depois)
2. A chamada navigator.credentials.create() do navegador usa essas opções para produzir um attestation
3. POST /profile/webauthn/verify com esse attestation completa o registro, armazenando a credencial em user_mfa_webauthn

No login: POST /auth/webauthn/authenticate/generate (com mfaToken) retorna opções de assertion para navigator.credentials.get(), e POST /auth/webauthn/authenticate/verify (com mfaToken + o assertionResponse resultante) completa o login.

Gerados automaticamente na primeira vez que um usuário registra qualquer método de MFA — 10 códigos de uso único, mostrados uma vez, com hash argon2 em user_recovery_code antes do armazenamento (o Hedhog nunca os armazena em forma recuperável, então não existe um recurso de "ver meus códigos de recuperação novamente", por design).

Diga aos usuários explicitamente, no momento do registro, que perder tanto o segundo fator quanto os códigos de recuperação significa bloqueio permanente, exceto por intervenção manual de admin/banco de dados — não há um fluxo de "o suporte redefine seu MFA" embutido.

Tente isto uma vez, em um ambiente não-produtivo: use um código de recuperação para fazer login e confirme que ele realmente funciona antes de depender dele de verdade.

Todo endpoint de remoção exige reprovar a identidade primeiro — você não pode remover silenciosamente o MFA de uma sessão sequestrada:

• Saia e entre novamente com um usuário que tem MFA registrado — confirme que a resposta inclui requiresMfa: true antes de qualquer token ser emitido
• Envie o segundo fator e confirme que só agora você recebe accessToken/refreshToken
• Teste um código de recuperação conforme descrito acima — não espere até estar realmente trancado para fora para descobrir que ele não funciona