Multi-Factor Authentication

Hedhog supports three second-factor methods — TOTP (authenticator apps), email one-time codes, and WebAuthn (passkeys/security keys) — plus single-use recovery codes for account recovery. This is a fully implemented feature, built on speakeasy (TOTP), qrcode (QR generation), and @simplewebauthn/server (WebAuthn), all in libraries/core/src/profile/.

Status: ✅ Fully implemented — TOTP, Email OTP, WebAuthn, and recovery codes all work, including the login-challenge flow.

1. Make sure an email provider is configured if you'll allow Email OTP
2. Enroll TOTP yourself first: POST /profile/totp/generate → scan the QR code → POST /profile/totp/verify
3. Log out and back in — confirm the response returns requiresMfa: true before any token is issued, and that submitting the code completes login
4. Save the recovery codes shown at enrollment — there's no way to view them again later

All enrollment happens through /profile/* endpoints, scoped to the logged-in user:

Every enrolled method becomes a row in user_mfa (type ∈ totp, email, webauthn), with the secret/credential stored in a matching user_mfa_totp, user_mfa_email, or user_mfa_webauthn table.

This is the part that's easy to miss if you only read the enrollment endpoints: login itself does not call any /profile/mfa/* route. Once a password is verified for a user with at least one MFA method enrolled, AuthService returns:

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

instead of an access token. Your login UI must check for requiresMfa and prompt for the second factor using that short-lived mfaToken — not the user's session:

Only after one of these succeeds does the backend issue the real access/refresh token pair.

Configure these in Settings → Configurations → Authentication — MFA settings live in this group, not a dedicated "MFA" one.

Works with any RFC 6238 app: Google Authenticator, Authy, Microsoft Authenticator, 1Password, Bitwarden.

1. Client calls POST /profile/totp/generate — server returns { secret, otpauthUrl, qrCode }
2. User scans the qrCode (or manually enters secret) in their authenticator app
3. Client calls POST /profile/totp/verify with the first 6-digit code the app shows, plus the secret and a name for the device
4. Hedhog validates the code against the secret (honoring mfa-window/mfa-setp) and, only on success, persists the method and issues recovery codes if this is the user's first MFA method

If the code is always rejected even when freshly generated, the most common cause is real clock drift on the server or the user's phone — mfa-window absorbs a little of this, but not unlimited drift.

No app required — works for any user with a verified email.

1. POST /profile/mfa/email/verify sends a code (length per mfa-email-code-length) to the account's email
2. POST /profile/mfa/email/verify/confirm activates it once the user enters the code

At login, the equivalent pair is POST /auth/verify-mfa-code (methodType: 'email') and POST /auth/resend-mfa-code if the code expired or never arrived. Email OTP obviously depends on a working email provider — if mail delivery is broken, users enrolled only in email MFA will be locked out of login entirely, not just enrollment.

Standards-based, phishing-resistant second factor using the browser's native WebAuthn API (Touch ID, Windows Hello, hardware keys like YubiKey).

1. POST /profile/webauthn/generate returns registration options (name is the label shown for this device later)
2. The browser's navigator.credentials.create() call uses those options to produce an attestation
3. POST /profile/webauthn/verify with that attestation completes registration, storing the credential in user_mfa_webauthn

At login: POST /auth/webauthn/authenticate/generate (with mfaToken) returns assertion options for navigator.credentials.get(), and POST /auth/webauthn/authenticate/verify (with mfaToken + the resulting assertionResponse) completes login.

Generated automatically the first time a user enrolls any MFA method — 10 single-use codes, shown once, hashed with argon2 in user_recovery_code before storage (Hedhog never stores them in retrievable form, so there's no "view my recovery codes again" feature by design).

Tell users explicitly, at enrollment time, that losing both their second factor and their recovery codes means permanent lockout barring manual admin/database intervention — there is no "support resets your MFA" flow built in.

Try this once, in a non-production environment: use a recovery code to log in and confirm it actually works before you depend on it for real.

Every removal endpoint requires re-proving identity first — you cannot silently strip MFA from a hijacked session:

• Log out and log back in with a user who has MFA enrolled — confirm the response includes requiresMfa: true before any token is issued
• Submit the second factor and confirm you only now receive accessToken/refreshToken
• Test one recovery code as described above — don't wait until you're actually locked out to find out it doesn't work