# TOTP-Based 2FA at Credential Login

**Task**: AZ-534_totp_2fa_login
**Name**: TOTP-based 2FA at credential login
**Description**: Add RFC 6238 TOTP enrollment, two-step `/login` flow, and recovery codes. MFA validated only at credential login (not on each refresh); access tokens stamp `amr` claim so future verifiers can require step-up MFA. Per-user opt-in initially; can be made mandatory by role via config.
**Complexity**: 5 points
**Dependencies**: None (touches `/login` so coordinate merge with AZ-537 rate-limit + AZ-531 dual-token)
**Component**: Admin API + Services + DataAccess
**Tracker**: AZ-534
**Epic**: AZ-529

## Problem

`/login` accepts password-only auth. CMMC requires multi-factor authentication for privileged accounts. There is no second-factor support today.

## Outcome

- TOTP (RFC 6238) enrollment + validation flow at credential login. No SMS, no email codes — TOTP only (offline-friendly, phishing-resistant against bulk SMS attacks).
- Recovery codes (10 single-use codes shown once at enrollment) for device-loss recovery.
- 2FA validated **only at credential login** — NOT on every refresh. The refresh chain proves "MFA was done in this session" via the `amr` claim.
- Access tokens stamp `amr: ["pwd","mfa"]` when MFA was completed; `amr: ["pwd"]` if password-only (e.g. CompanionPC service accounts that don't have MFA enrolled).
- Per-user opt-in initially; admin policy can require MFA for `Role in (Admin, ApiAdmin)` from a config flag.

## Scope

### Included

- New columns on `users`: `mfa_enabled (bool)`, `mfa_secret (text, encrypted)`, `mfa_recovery_codes (jsonb of hashed codes)`, `mfa_enrolled_at (timestamptz)`.
- `POST /users/me/mfa/enroll` — returns `{ secret, otpauth_url, qr_png_base64, recovery_codes }`. Requires authenticated session, requires re-auth via password in same request body.
- `POST /users/me/mfa/confirm` — body `{ code }`, completes enrollment by validating one TOTP code.
- `POST /users/me/mfa/disable` — body `{ password, code }`, removes secret and recovery codes.
- `/login` flow change: if user has `mfa_enabled=true`, return `{ mfa_required: true, mfa_token: <short-lived JWT> }` instead of access+refresh; client then calls `POST /login/mfa` with `{ mfa_token, code }` to get the real tokens.
- Recovery-code consumption: a recovery code may substitute for a TOTP code at `/login/mfa`; consumed code is marked used (single-use).
- Audit log entries for: enroll, confirm, disable, login-via-MFA, login-via-recovery-code.
- TOTP library: prefer `Otp.NET` (mature, no transitive deps). Verify version compatibility with .NET 10.

### Excluded

- WebAuthn / FIDO2 / hardware-key MFA — future ticket.
- Per-action step-up MFA (re-prompt for sensitive operations) — future ticket. AZ-533 mission-token issuance will start enforcing `amr=["pwd","mfa"]` after this lands.
- Admin-side reset of another user's MFA ("my user lost their phone") — future ticket; for now they go through recovery codes or DB intervention.
- UI changes — cross-workspace ticket later.

## Acceptance Criteria

**AC-1: Enrollment returns a usable TOTP secret**
Given an authenticated user without MFA
When `POST /users/me/mfa/enroll` is called with the user's password
Then response includes a 32-character base32 `secret`, a valid `otpauth://` URL, a PNG QR (base64), and 10 recovery codes (≥12 chars each, base32). DB has `mfa_enabled=false` until confirm.

**AC-2: Confirm completes enrollment**
Given the user scanned the QR and got a 6-digit code
When `POST /users/me/mfa/confirm` is called with the code
Then MFA is activated (`mfa_enabled=true`); subsequent logins require step 2.

**AC-3: Login two-step flow**
Given a user with MFA enabled
When `POST /login` is called with valid credentials
Then response is 200 with `{ mfa_required: true, mfa_token, expires_in: 300 }` — no access/refresh yet.
When `POST /login/mfa` is called with `mfa_token` + valid TOTP code
Then access + refresh tokens are issued; access token's `amr=["pwd","mfa"]`.

**AC-4: Recovery code works once**
Given the same MFA-enabled user
When `POST /login/mfa` is called with a recovery code instead of TOTP
Then login succeeds; `amr=["pwd","mfa","recovery"]`; the same code on the next login fails.

**AC-5: Disable requires password + current code**
Given a user with MFA enabled
When `POST /users/me/mfa/disable` is called with password + a valid TOTP code
Then MFA is disabled; subsequent `/login` returns access+refresh directly without step 2.

**AC-6: TOTP secret is encrypted at rest**
Given an enrolled user
When the `users.mfa_secret` column is read directly from Postgres
Then the value is ciphertext (uses the same encryption infra already in admin for sensitive fields).

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|-------------|-------------------|----------------|
| AC-1 | Auth user, no MFA | POST /users/me/mfa/enroll | 200 with secret, otpauth, QR, 10 recovery codes | — |
| AC-2 | Enrollment in progress | POST /users/me/mfa/confirm with valid code | MFA activated | — |
| AC-3 | MFA-enabled user | POST /login then POST /login/mfa | Two-step flow; amr=[pwd,mfa] | — |
| AC-4 | MFA-enabled user | POST /login/mfa with recovery code | Success once; amr=[pwd,mfa,recovery]; second use fails | — |
| AC-5 | MFA-enabled user | POST /users/me/mfa/disable | MFA off; /login returns tokens directly | — |
| AC-6 | Enrolled user | Read users.mfa_secret directly from DB | Ciphertext, not plaintext base32 | — |

## Risks / Notes

- TOTP code reuse: a single 30-second code window can be replayed within those 30 seconds. Mitigate by tracking last-used-time per user (small DB write per login). Optional in this ticket; flag for next hardening pass if not in scope.
- The two-step `/login` change is a wire-shape change for clients. Coordinate with UI workspace via cross-workspace ticket once admin lands.
- Touches the same `/login` code path as AZ-537 (rate limit) and AZ-531 (dual-token). Land AZ-531 first (changes response shape), then AZ-537 (adds limiter middleware), then this ticket (adds the two-step branch).