Two-factor authentication

Status: Accepted (2026-09-15) · Amends: ADR-0024, ADR-0038, ADR-0042 · Amended by: ADR-0044 (a passkey also turns two-factor authentication on), ADR-0046 (Google and Apple sign-ins also ask for the second factor; accounts without a password confirm with a recent sign-in)

Context#

v0.3 (roadmap) adds strong authentication. ADR-0024 fixed the outline for 2FA: a TOTP secret encrypted at rest with a rotatable key, 10 hashed recovery codes, single-use rate-limited codes, an mfa_required challenge before a session exists, roles that require 2FA, and ops roles that always do. It named github.com/pquerna/otp for TOTP.

v0.2 left what this needs: sessions are created only at login (ADR-0038), permissions come from roles on every request, /ops/* checks permissions in its use cases, and seed data creates a platform_admin (ADR-0042). Threat model rows 15 (TOTP secret disclosure or replay) and 18 (privilege escalation to ops, whose required 2FA is still open) depend on this decision.

This ADR covers TOTP, recovery codes, the login challenge and the role policy. Passkeys and Google and Apple sign-in get their own ADRs; the challenge and session model here is built so a passkey can count as a second factor.

Options#

TOTP implementation#

When 2FA is required in development#

Decision#

TOTP option 2; development option 1 (chosen 2026-09-15).

Who owns what (as ADR-0038)#

No QR images are generated: the API returns the otpauth:// URI and clients render it.

Encryption keys#

Tables#

Enrollment#

Signing in#

1. POST /v1/auth/login checks the password as today. For a user with confirmed TOTP it creates no session and returns 202 with challenge_token (32 random bytes; only its hash is stored), methods (totp, recovery_code) and expires_at. Users without 2FA get 200 and a session, unchanged.
2. POST /v1/auth/login/mfa takes challenge_token, one of code or recovery_code, and transport. It returns 200 with a 2FA-verified session, like login. Wrong or expired challenges and wrong codes return 401 invalid_mfa with the same work; 5 attempts per challenge; the per-address login limiter also counts these attempts.
3. A TOTP code is accepted only for a step later than last_used_step, updated in the same statement that checks it, so a code can't be used twice, even by two instances at once. A used recovery code is marked in the same way and sends a "recovery code used" email naming how many are left.

Password reset doesn't bypass 2FA: it sets the password and ends sessions, and the next sign-in still asks for a code. Account deletion with 2FA also requires a code or recovery code.

Lost device and recovery codes: an operator runs go run ./cmd/api reset-mfa <email>, audited as the cli actor, which removes the user's 2FA and ends their sessions.

Role policy#

Seed data (amends ADR-0042)#

Seed also enrolls the administrator: it creates and confirms a TOTP secret and recovery codes through the use cases, and prints, once, next to the password, the setup key, the otpauth:// URI and the 10 recovery codes. Nothing is stored in plain text. The first aps dev still ends with a working /ops/*: add the key to an authenticator app, sign in, answer the challenge.

Audit actions and emails#

auth.mfa.totp_enrollment_started, auth.mfa.totp_enabled, auth.mfa.totp_disabled, auth.mfa.challenge_succeeded, auth.mfa.challenge_failed (reason), auth.mfa.recovery_code_used, auth.mfa.recovery_codes_regenerated, auth.mfa.reset (operator), auth.keys.rotated. Secrets, codes and recovery codes never appear in metadata or logs. Emails: 2FA turned on, 2FA turned off, recovery code used.

Error codes#

mfa_required (403), invalid_mfa (401), mfa_already_enabled (409), mfa_not_enabled (409), mfa_required_by_role (409), mfa_unavailable (503). Login's 202 response is a new success shape, so existing clients of apps without 2FA users see no change.

Why#

• Codes checked against a stored step and challenges stored as hashes keep a leaked database or a replayed code from signing anyone in.
• Encryption with key IDs lets a key be replaced without a flag day, and binding ciphertexts to users stops secret swapping between rows.
• Withholding permissions per session, rather than blocking sign-in, lets ops users enroll with the same account and gives clients a clear mfa_required.
• Seed enrollment keeps one rule for every environment without slowing the first run.

Trade-offs#

• An app now needs a managed encryption key; losing every key disables everyone's 2FA until operators reset it.
• Upgrading apps' ops users lose /ops/* until they enroll and sign in again.
• TOTP is phishable; passkeys (next ADR) are the phishing-resistant factor.
• Printing a TOTP key and recovery codes to a development terminal puts them in scrollback, like the seeded password.
• Per-instance rate limits (ADR-0038) still apply; the replay guard and challenge attempts are database-backed and shared.

Consequences#

• modules/auth gains TOTP, Keyring, recovery code helpers and Catalog.RequireMFA; core actor gains StepUp, Require, ErrForbidden and ErrStepUpRequired (public API, ADR-0015).
• The Full preset gains a migration, use cases, repository files and endpoints, reset-mfa and rotate-auth-keys commands, seed enrollment, and tests for replay, challenge limits, key rotation, role policy and seed.
• aps dev writes AUTH_ENCRYPTION_KEYS to .env when empty.
• Threat model rows 15 and 18 (required 2FA for ops) are addressed when this ships; ADR-0024's library list drops pquerna/otp.

Implementation notes (2026-09-15)#

• actor.Require also returns actor.ErrUnauthenticated, so a use case maps three outcomes. The ops module maps ErrStepUpRequired to its own ErrMFARequired (403 mfa_required), keeping its domain free of core imports.
• Login's 202 body carries only mfa: no user or session, so a password alone reveals nothing more about the account. user and session became optional fields of the login response.
• Attempts on POST /v1/auth/login/mfa count toward the per-address login limit; confirming, turning off and replacing recovery codes share a per-user limit.
• EnrollTOTP (operators, seed data) confirms a secret without a code and records step 0, so the first real code is accepted.
• auth_cleanup removes sign-in challenges a day after they expire.
• LoadConfig validates AUTH_ENCRYPTION_KEYS everywhere and requires it in production. Tests share one generated key per process, so two app instances on one database decrypt each other's secrets.
• aps dev fills an empty AUTH_ENCRYPTION_KEYS in .env with dev:<random key>, only for apps whose .env.example declares it and when the environment doesn't set it, and keeps .env at mode 0600.
• The migration is 20260915000004_auth_mfa.sql.
• Amended 2026-09-15 (with ADR-0044): the setup response also returns qr_code, a PNG data URL of the otpauth:// URI, so the API is usable with an authenticator app before any frontend exists. modules/auth gains TOTPQRCode on rsc.io/qr (no dependencies of its own); the "no QR images" line above is replaced.