From 6b3d3fd840cf6627a79e21c22d29df1ed2fbbe58 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Sat, 27 Jun 2026 19:56:30 +0200 Subject: [PATCH] feat(auth): branch login through a second-factor challenge When a password is accepted for an account with a confirmed TOTP factor, the login route no longer mints a session or token. It creates a single-use, ~5-minute MfaChallenge (the opaque ticket is stored only as a hash) and returns HTTP 200 with data:null, error:null and meta.mfaRequired + mfaTicket + methods. The client completes the login at POST /api/auth/mfa/verify with the ticket + a TOTP or recovery code, receiving the exact same token bundle the password path issues, with the session stamped second-factor-verified. - The ticket is claimed once, atomically, only after the factor verifies, so two concurrent submissions can mint at most one session; no session ever exists before factor two. - Wrong codes increment the ticket attempt counter and burn it at the cap (throttle, not an account lock); the anonymous verify surface is also rate-limited per IP. - meta.mfaRequired is returned only after a valid password and the invalid-credentials response is identical regardless of MFA state, so an attacker without the password cannot enumerate MFA. - The session/token tail is extracted to login-response.ts and shared by both the password path and the verify path, keeping the transport contract identical. OpenAPI registers the verify endpoint, the MFA management endpoints, and the mfaRequired login variant. --- docs/api/openapi.yaml | 325 +++++++++++++++++- .../api/auth/login/mfa-branch.test.ts | 131 +++++++ src/__tests__/api/auth/mfa/verify.test.ts | 156 +++++++++ src/app/api/auth/login/route.ts | 124 +++---- src/app/api/auth/mfa/verify/route.ts | 139 ++++++++ src/lib/auth/login-response.ts | 125 +++++++ src/lib/auth/mfa/__tests__/challenge.test.ts | 130 +++++++ src/lib/auth/mfa/challenge.ts | 133 +++++++ src/lib/openapi/routes/auth.ts | 181 +++++++++- tests/integration/mfa-login-flow.test.ts | 155 +++++++++ 10 files changed, 1508 insertions(+), 91 deletions(-) create mode 100644 src/__tests__/api/auth/login/mfa-branch.test.ts create mode 100644 src/__tests__/api/auth/mfa/verify.test.ts create mode 100644 src/app/api/auth/mfa/verify/route.ts create mode 100644 src/lib/auth/login-response.ts create mode 100644 src/lib/auth/mfa/__tests__/challenge.test.ts create mode 100644 src/lib/auth/mfa/challenge.ts create mode 100644 tests/integration/mfa-login-flow.test.ts diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 79e597122..4055a7446 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -1354,8 +1354,15 @@ paths: tags: - Auth summary: Email-or-username login (password) - description: "Browser callers receive a session cookie. Native callers (X-Client-Type: native or HealthLog-iOS UA - prefix) additionally receive a paired access + refresh token." + description: >- + Browser callers receive a session cookie. Native callers (X-Client-Type: native or HealthLog-iOS UA prefix) + additionally receive a paired access + refresh token. + + + v1.23 — when the account has a confirmed second factor, the response carries no session/token. It returns HTTP + 200 with `data: null, error: null` and `meta.mfaRequired: true` plus a single-use `meta.mfaTicket` and the + `meta.methods` list. The client must POST the ticket + a code to `/api/auth/mfa/verify` to obtain the token + bundle. Accounts without MFA are unchanged. requestBody: required: true content: @@ -1374,11 +1381,124 @@ paths: - password responses: "200": - description: Login succeeded. + description: Login succeeded (token bundle / cookie) — or a second factor is required (`meta.mfaRequired`). content: application/json: schema: - $ref: "#/components/schemas/LoginResponse" + anyOf: + - $ref: "#/components/schemas/LoginResponse" + - $ref: "#/components/schemas/MfaRequiredResponse" + "401": *a1 + "422": *a3 + "429": *a4 + /api/auth/mfa/verify: + post: + tags: + - Auth + summary: Complete a second-factor login challenge + description: Presents the `mfaTicket` from the login `meta.mfaRequired` response plus a TOTP or recovery code. On + success returns the SAME token bundle / session the password path issues, with the session marked + second-factor-verified. The ticket is single-use; wrong codes are throttled and the ticket is burned at the + attempt cap. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/MfaVerifyRequest" + responses: + "200": + description: Second factor verified — session + optional bearer issued. + content: + application/json: + schema: + $ref: "#/components/schemas/MfaVerifyResponse" + "401": *a1 + "422": *a3 + "429": *a4 + /api/auth/me/mfa/totp/setup: + post: + tags: + - Auth + summary: Begin TOTP enrollment (cookie session only) + description: Generates and stores a pending (encrypted) TOTP secret and returns the otpauth URI + Base32 secret. MFA is + not active until /confirm. Cookie-only — a Bearer token cannot enrol MFA. + responses: + "200": + description: Pending secret created. + content: + application/json: + schema: + $ref: "#/components/schemas/TotpSetupEnvelope" + "401": *a1 + "422": *a3 + "429": *a4 + /api/auth/me/mfa/totp/confirm: + post: + tags: + - Auth + summary: Confirm TOTP enrollment (cookie session only) + description: Verifies a code against the pending secret, activates the factor, and returns the one-time recovery codes. + Cookie-only. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + code: + type: string + pattern: ^\d{6}$ + required: + - code + responses: + "200": + description: Factor activated — recovery codes returned once. + content: + application/json: + schema: + $ref: "#/components/schemas/TotpConfirmEnvelope" + "401": *a1 + "422": *a3 + "429": *a4 + /api/auth/me/mfa/disable: + post: + tags: + - Auth + summary: Disable the second factor (step-up gated) + description: Requires a fresh second-factor step-up (cookie session) AND a current TOTP or recovery code. Clears the + secret and deletes recovery codes. Bearer can never satisfy the step-up gate. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/MfaDisableRequest" + responses: + "200": + description: Factor disabled. + content: + application/json: + schema: + $ref: "#/components/schemas/MfaDisableEnvelope" + "401": *a1 + "422": *a3 + "429": *a4 + /api/auth/me/mfa/recovery-codes/regenerate: + post: + tags: + - Auth + summary: Regenerate recovery codes (step-up gated) + description: Invalidates the entire prior recovery-code set and returns a fresh batch once. Step-up gated; Bearer can + never satisfy the gate. + responses: + "200": + description: Fresh recovery codes issued. + content: + application/json: + schema: + $ref: "#/components/schemas/MfaRecoveryRegenEnvelope" "401": *a1 "422": *a3 "429": *a4 @@ -7492,6 +7612,43 @@ paths: "429": *a4 components: schemas: + MfaVerifyRequest: + type: object + properties: + mfaTicket: + type: string + minLength: 1 + description: The opaque single-use ticket from the login response. + method: + default: totp + type: string + enum: + - totp + - recovery + code: + type: string + minLength: 6 + maxLength: 32 + required: + - mfaTicket + - code + description: Complete a second-factor login challenge and receive the same token bundle the password path issues. + MfaDisableRequest: + type: object + properties: + code: + type: string + minLength: 6 + maxLength: 32 + method: + default: totp + type: string + enum: + - totp + - recovery + required: + - code + description: Disable the second factor. Requires fresh step-up plus a current TOTP or recovery code. PasskeyLoginVerifyRequest: type: object properties: @@ -10660,6 +10817,166 @@ components: - tokenExpiresAt additionalProperties: false description: Native-client token bundle returned by login + refresh. Web cookie-only callers see only `user`. + MfaRequiredResponse: + type: object + properties: + data: + type: "null" + error: + type: "null" + meta: + type: object + properties: + mfaRequired: + type: boolean + const: true + mfaTicket: + type: string + description: Opaque, single-use, ~5-minute ticket to present to /api/auth/mfa/verify. + methods: + type: array + items: + type: string + enum: + - totp + - recovery + description: Second factors the account can complete the challenge with. + required: + - mfaRequired + - mfaTicket + - methods + additionalProperties: false + required: + - data + - error + - meta + additionalProperties: false + description: Password accepted but a second factor is required. Not an error and not a session — no token is issued + until /api/auth/mfa/verify succeeds. + MfaVerifyResponse: + type: object + properties: + data: + $ref: "#/components/schemas/AccessRefreshBundle" + error: + type: "null" + meta: + type: object + properties: + requestId: + type: string + additionalProperties: false + required: + - data + - error + additionalProperties: false + TotpSetupEnvelope: + type: object + properties: + data: + $ref: "#/components/schemas/TotpSetupResponse" + error: + type: "null" + meta: + type: object + properties: + requestId: + type: string + additionalProperties: false + required: + - data + - error + additionalProperties: false + TotpSetupResponse: + type: object + properties: + otpauthUri: + type: string + description: otpauth:// URI to render as a QR code (carries the secret). + totpSecret: + type: string + description: Base32 secret for manual entry. Pending until confirmed. + required: + - otpauthUri + - totpSecret + additionalProperties: false + TotpConfirmEnvelope: + type: object + properties: + data: + $ref: "#/components/schemas/MfaRecoveryCodesResponse" + error: + type: "null" + meta: + type: object + properties: + requestId: + type: string + additionalProperties: false + required: + - data + - error + additionalProperties: false + MfaRecoveryCodesResponse: + type: object + properties: + enabled: + type: boolean + recoveryCodes: + type: array + items: + type: string + description: Single-use recovery codes, shown once. Save them now. + recoveryCodesRemaining: + type: integer + minimum: -9007199254740991 + maximum: 9007199254740991 + required: + - recoveryCodes + - recoveryCodesRemaining + additionalProperties: false + MfaDisableEnvelope: + type: object + properties: + data: + $ref: "#/components/schemas/MfaToggleResponse" + error: + type: "null" + meta: + type: object + properties: + requestId: + type: string + additionalProperties: false + required: + - data + - error + additionalProperties: false + MfaToggleResponse: + type: object + properties: + enabled: + type: boolean + required: + - enabled + additionalProperties: false + MfaRecoveryRegenEnvelope: + type: object + properties: + data: + $ref: "#/components/schemas/MfaRecoveryCodesResponse" + error: + type: "null" + meta: + type: object + properties: + requestId: + type: string + additionalProperties: false + required: + - data + - error + additionalProperties: false PasskeyLoginVerifyResponse: type: object properties: diff --git a/src/__tests__/api/auth/login/mfa-branch.test.ts b/src/__tests__/api/auth/login/mfa-branch.test.ts new file mode 100644 index 000000000..e47fc51fd --- /dev/null +++ b/src/__tests__/api/auth/login/mfa-branch.test.ts @@ -0,0 +1,131 @@ +import { describe, it, expect, vi, beforeEach } from "vitest"; + +vi.mock("@/lib/db", () => ({ + prisma: { user: { findFirst: vi.fn() } }, +})); +vi.mock("@/lib/auth/password", () => ({ + verifyPassword: vi.fn().mockResolvedValue(true), +})); +vi.mock("@/lib/auth/audit", () => ({ + auditLog: vi.fn().mockResolvedValue(undefined), +})); +vi.mock("@/lib/auth/hmac", () => ({ hashToken: vi.fn(() => "h") })); +vi.mock("@/lib/db-compat", () => ({ + ensureDbCompatibility: vi.fn().mockResolvedValue(undefined), +})); +vi.mock("@/lib/logging/transports", () => ({ emitIfSampled: vi.fn() })); +vi.mock("@/lib/rate-limit", () => ({ + checkAuthSurfaceRateLimit: vi.fn().mockResolvedValue({ + allowed: true, + remaining: 4, + resetAt: Date.now() + 1e6, + ip: "203.0.113.7", + }), + rateLimitHeaders: vi.fn(() => ({})), +})); +vi.mock("@/lib/auth/login-response", () => ({ + finishLogin: vi.fn().mockResolvedValue( + new Response( + JSON.stringify({ data: { user: { id: "user-1" } }, error: null }), + { + status: 200, + headers: { "content-type": "application/json" }, + }, + ), + ), +})); +vi.mock("@/lib/auth/mfa/challenge", () => ({ + createMfaChallenge: vi.fn().mockResolvedValue({ + ticket: "opaque-ticket-value", + expiresAt: new Date(Date.now() + 5 * 60_000), + }), +})); +vi.mock("next/headers", () => ({ + headers: vi.fn(async () => ({ get: () => null })), + cookies: vi.fn(async () => ({ + get: () => undefined, + set: () => {}, + delete: () => {}, + })), +})); + +import { POST } from "@/app/api/auth/login/route"; +import { prisma } from "@/lib/db"; +import { finishLogin } from "@/lib/auth/login-response"; +import { createMfaChallenge } from "@/lib/auth/mfa/challenge"; + +function loginRequest() { + return new Request("http://localhost/api/auth/login", { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ + email: "user@example.com", + password: "correct-horse-battery", + }), + }) as unknown as Parameters[0]; +} + +const BASE_USER = { + id: "user-1", + username: "u", + email: "user@example.com", + passwordHash: "argon2-hash", + onboardingCompletedAt: new Date(), +}; + +beforeEach(() => { + vi.clearAllMocks(); +}); + +describe("login MFA branch", () => { + it("MFA user → returns mfaRequired + ticket and issues NO session", async () => { + vi.mocked(prisma.user.findFirst).mockResolvedValue({ + ...BASE_USER, + totpConfirmedAt: new Date(), + } as never); + + const res = await POST(loginRequest()); + expect(res.status).toBe(200); + const body = await res.json(); + + expect(body.data).toBeNull(); + expect(body.error).toBeNull(); + expect(body.meta.mfaRequired).toBe(true); + expect(body.meta.mfaTicket).toBe("opaque-ticket-value"); + expect(body.meta.methods).toEqual(["totp", "recovery"]); + + expect(createMfaChallenge).toHaveBeenCalledWith("user-1", "login"); + // The session/token tail is never reached. + expect(finishLogin).not.toHaveBeenCalled(); + }); + + it("non-MFA user → issues the session via finishLogin, no challenge", async () => { + vi.mocked(prisma.user.findFirst).mockResolvedValue({ + ...BASE_USER, + totpConfirmedAt: null, + } as never); + + const res = await POST(loginRequest()); + expect(res.status).toBe(200); + + expect(finishLogin).toHaveBeenCalledTimes(1); + expect(createMfaChallenge).not.toHaveBeenCalled(); + const arg = vi.mocked(finishLogin).mock.calls[0][0]; + expect(arg.source).toBe("login.password"); + expect(arg.mfaVerified).toBeUndefined(); + }); + + it("wrong password never reaches the MFA branch", async () => { + const { verifyPassword } = await import("@/lib/auth/password"); + vi.mocked(verifyPassword).mockResolvedValueOnce(false); + vi.mocked(prisma.user.findFirst).mockResolvedValue({ + ...BASE_USER, + totpConfirmedAt: new Date(), + } as never); + + const res = await POST(loginRequest()); + expect(res.status).toBe(401); + expect(createMfaChallenge).not.toHaveBeenCalled(); + expect(finishLogin).not.toHaveBeenCalled(); + }); +}); diff --git a/src/__tests__/api/auth/mfa/verify.test.ts b/src/__tests__/api/auth/mfa/verify.test.ts new file mode 100644 index 000000000..b16904be3 --- /dev/null +++ b/src/__tests__/api/auth/mfa/verify.test.ts @@ -0,0 +1,156 @@ +import { describe, it, expect, vi, beforeEach } from "vitest"; + +vi.mock("@/lib/db", () => ({ + prisma: { user: { findUnique: vi.fn() } }, +})); +vi.mock("@/lib/db-compat", () => ({ + ensureDbCompatibility: vi.fn().mockResolvedValue(undefined), +})); +vi.mock("@/lib/logging/transports", () => ({ emitIfSampled: vi.fn() })); +vi.mock("@/lib/auth/audit", () => ({ + auditLog: vi.fn().mockResolvedValue(undefined), +})); +vi.mock("@/lib/rate-limit", () => ({ + checkAuthSurfaceRateLimit: vi.fn().mockResolvedValue({ + allowed: true, + remaining: 9, + resetAt: Date.now() + 1e6, + ip: "203.0.113.9", + }), + rateLimitHeaders: vi.fn(() => ({})), +})); +vi.mock("@/lib/auth/login-response", () => ({ + finishLogin: vi + .fn() + .mockResolvedValue( + new Response( + JSON.stringify({ data: { user: { id: "user-1" } }, error: null }), + { status: 200, headers: { "content-type": "application/json" } }, + ), + ), +})); +vi.mock("@/lib/auth/mfa/challenge", () => ({ + loadActiveChallenge: vi.fn(), + recordChallengeFailure: vi + .fn() + .mockResolvedValue({ exhausted: false, attempts: 1 }), + claimChallenge: vi.fn(), +})); +vi.mock("@/lib/auth/mfa/verify-factor", () => ({ + verifyMfaFactor: vi.fn(), +})); +vi.mock("next/headers", () => ({ + headers: vi.fn(async () => ({ get: () => null })), + cookies: vi.fn(async () => ({ + get: () => undefined, + set: () => {}, + delete: () => {}, + })), +})); + +import { POST } from "@/app/api/auth/mfa/verify/route"; +import { prisma } from "@/lib/db"; +import { finishLogin } from "@/lib/auth/login-response"; +import { + loadActiveChallenge, + recordChallengeFailure, + claimChallenge, +} from "@/lib/auth/mfa/challenge"; +import { verifyMfaFactor } from "@/lib/auth/mfa/verify-factor"; + +function verifyRequest(body: unknown) { + return new Request("http://localhost/api/auth/mfa/verify", { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify(body), + }) as unknown as Parameters[0]; +} + +const GOOD_BODY = { mfaTicket: "tkt", method: "totp", code: "123456" }; +const ACTIVE_CHALLENGE = { + id: "ch-1", + userId: "user-1", + kind: "login", + attempts: 0, + expiresAt: new Date(Date.now() + 60_000), +}; +const MFA_USER = { + id: "user-1", + username: "u", + email: "user@example.com", + onboardingCompletedAt: new Date(), + totpConfirmedAt: new Date(), + totpSecretEncrypted: "v2.cipher", + totpLastStep: null, +}; + +beforeEach(() => { + vi.clearAllMocks(); +}); + +describe("POST /api/auth/mfa/verify", () => { + it("happy path: valid factor → claims ticket and issues the bundle", async () => { + vi.mocked(loadActiveChallenge).mockResolvedValue(ACTIVE_CHALLENGE as never); + vi.mocked(prisma.user.findUnique).mockResolvedValue(MFA_USER as never); + vi.mocked(verifyMfaFactor).mockResolvedValue({ ok: true, replay: false }); + vi.mocked(claimChallenge).mockResolvedValue(true); + + const res = await POST(verifyRequest(GOOD_BODY)); + expect(res.status).toBe(200); + + expect(claimChallenge).toHaveBeenCalledWith("ch-1"); + expect(finishLogin).toHaveBeenCalledTimes(1); + const arg = vi.mocked(finishLogin).mock.calls[0][0]; + expect(arg.mfaVerified).toBe(true); + expect(arg.source).toBe("mfa.verify"); + }); + + it("invalid ticket → 401, no session", async () => { + vi.mocked(loadActiveChallenge).mockResolvedValue(null); + const res = await POST(verifyRequest(GOOD_BODY)); + expect(res.status).toBe(401); + expect(finishLogin).not.toHaveBeenCalled(); + }); + + it("wrong code → records failure, 401, no session", async () => { + vi.mocked(loadActiveChallenge).mockResolvedValue(ACTIVE_CHALLENGE as never); + vi.mocked(prisma.user.findUnique).mockResolvedValue(MFA_USER as never); + vi.mocked(verifyMfaFactor).mockResolvedValue({ ok: false, replay: false }); + + const res = await POST(verifyRequest(GOOD_BODY)); + expect(res.status).toBe(401); + expect(recordChallengeFailure).toHaveBeenCalledWith("ch-1"); + expect(claimChallenge).not.toHaveBeenCalled(); + expect(finishLogin).not.toHaveBeenCalled(); + }); + + it("factor valid but claim lost (race) → 401, no session", async () => { + vi.mocked(loadActiveChallenge).mockResolvedValue(ACTIVE_CHALLENGE as never); + vi.mocked(prisma.user.findUnique).mockResolvedValue(MFA_USER as never); + vi.mocked(verifyMfaFactor).mockResolvedValue({ ok: true, replay: false }); + vi.mocked(claimChallenge).mockResolvedValue(false); + + const res = await POST(verifyRequest(GOOD_BODY)); + expect(res.status).toBe(401); + expect(finishLogin).not.toHaveBeenCalled(); + }); + + it("factor disabled between password and verify → failure, 401", async () => { + vi.mocked(loadActiveChallenge).mockResolvedValue(ACTIVE_CHALLENGE as never); + vi.mocked(prisma.user.findUnique).mockResolvedValue({ + ...MFA_USER, + totpConfirmedAt: null, + } as never); + + const res = await POST(verifyRequest(GOOD_BODY)); + expect(res.status).toBe(401); + expect(recordChallengeFailure).toHaveBeenCalledWith("ch-1"); + expect(verifyMfaFactor).not.toHaveBeenCalled(); + expect(finishLogin).not.toHaveBeenCalled(); + }); + + it("malformed body → 422", async () => { + const res = await POST(verifyRequest({ mfaTicket: "", code: "x" })); + expect(res.status).toBe(422); + }); +}); diff --git a/src/app/api/auth/login/route.ts b/src/app/api/auth/login/route.ts index c4e727ee0..d271cfd31 100644 --- a/src/app/api/auth/login/route.ts +++ b/src/app/api/auth/login/route.ts @@ -1,22 +1,16 @@ import { prisma } from "@/lib/db"; import { loginPasswordSchema } from "@/lib/validations/auth"; import { verifyPassword } from "@/lib/auth/password"; -import { createSession } from "@/lib/auth/session"; import { auditLog } from "@/lib/auth/audit"; import { hashToken } from "@/lib/auth/hmac"; -import { apiSuccess, apiError, safeJson } from "@/lib/api-response"; +import { apiError, safeJson } from "@/lib/api-response"; import { checkAuthSurfaceRateLimit, rateLimitHeaders } from "@/lib/rate-limit"; import { ensureDbCompatibility } from "@/lib/db-compat"; import { NextRequest, NextResponse } from "next/server"; import { apiHandler } from "@/lib/api-handler"; import { annotate } from "@/lib/logging/context"; -import { issueApiToken, isNativeClientRequest } from "@/lib/auth/issue-token"; -import { - resolveTokenPolicy, - shouldIssueBearerToken, - isCookielessNativeCaller, -} from "@/lib/auth/native-client"; -import { issueAccessAndRefresh } from "@/lib/auth/refresh-token"; +import { finishLogin } from "@/lib/auth/login-response"; +import { createMfaChallenge } from "@/lib/auth/mfa/challenge"; export const POST = apiHandler(async (request: NextRequest) => { // v1.4.43 W13 M-4 — `checkAuthSurfaceRateLimit` swaps to a tighter @@ -95,93 +89,55 @@ export const POST = apiHandler(async (request: NextRequest) => { } const ua = request.headers.get("user-agent"); - // v1.4.22 W5 reconcile (Sr-H1) — `createSession` now anchors the - // `hl_onboarding` cookie itself; pass the user's onboarding state - // through so the proxy can short-circuit the redirect before the - // page hydrates. - await createSession(user.id, user.onboardingCompletedAt == null, ip, ua); await auditLog("auth.login.password", { userId: user.id, ipAddress: ip, }); - annotate({ action: { name: "auth.login.password" } }); - - // v1.4 G4: Native callers (iOS, n8n, Health-Connect, unrecognised UAs) - // get a 24h access token + 60d rotating refresh token. Web UAs keep the - // legacy 90d Bearer (issued only when X-Client-Type: native is set — - // browser flows continue to use the session cookie). - if ( - shouldIssueBearerToken(request.headers) || - isNativeClientRequest(request.headers) - ) { - const policy = resolveTokenPolicy(request.headers); - const deviceId = request.headers.get("x-device-id"); - - // M-3 hardening: a 60-day refresh token is only ever delivered to a - // genuinely cookie-less native caller. A browser spoofing - // `X-Client-Type: native` (Mozilla UA or an inbound session cookie) - // falls through to the plain access-token path below — never handed a - // long-lived secret into a DOM/XSS-reachable context. - if ( - policy.refreshTokenDays !== null && - isCookielessNativeCaller(request.headers) - ) { - const bundle = await issueAccessAndRefresh({ - userId: user.id, - policy, - deviceId, - userAgent: ua, - ipAddress: ip, - source: "login.password", - }); - await auditLog("auth.token.autoissue.native", { - userId: user.id, - ipAddress: ip, - details: { source: "login.password", policy: "native" }, - }); - annotate({ - action: { name: "auth.token.autoissue.native" }, - meta: { token_policy: "native" }, - }); - return apiSuccess({ - user: { id: user.id, username: user.username }, - token: bundle.accessToken, - tokenExpiresAt: bundle.accessTokenExpiresAt.toISOString(), - refreshToken: bundle.refreshToken, - refreshTokenExpiresAt: bundle.refreshTokenExpiresAt.toISOString(), - }); - } - - // Web policy with explicit X-Client-Type:native (legacy iOS auto-login) - const issued = await issueApiToken({ - userId: user.id, - name: `web auto-login ${new Date().toISOString()}`, - permissions: ["*"], - expiresInDays: policy.accessTokenDays, - }); - await auditLog("auth.token.autoissue.native", { + // v1.23 — second-factor gate. The password is correct, but an account with + // a confirmed TOTP factor is NOT yet authenticated: no `Session` row and no + // token bundle is minted here. Instead a single-use, ~5-minute MFA ticket is + // returned (the partial state lives in the ticket, never in a half-built + // session) and the client completes the login at `/api/auth/mfa/verify`. + // + // Enumeration note: `meta.mfaRequired` is only ever returned AFTER a valid + // password, and the invalid-credentials response above is identical + // regardless of MFA state — an attacker without the password cannot learn + // whether an account has MFA. + if (user.totpConfirmedAt) { + const challenge = await createMfaChallenge(user.id, "login"); + await auditLog("auth.mfa.challenge", { userId: user.id, ipAddress: ip, - details: { - tokenId: issued.tokenId, - source: "login.password", - policy: "web", - }, + details: { source: "login.password" }, }); annotate({ - action: { name: "auth.token.autoissue.native" }, - meta: { token_policy: "web" }, - }); - return apiSuccess({ - user: { id: user.id, username: user.username }, - token: issued.token, - tokenExpiresAt: issued.expiresAt.toISOString(), + action: { name: "auth.mfa.challenge" }, + meta: { mfa_required: true }, }); + return NextResponse.json( + { + data: null, + error: null, + meta: { + mfaRequired: true, + mfaTicket: challenge.ticket, + methods: ["totp", "recovery"], + }, + }, + { status: 200 }, + ); } - return apiSuccess({ - user: { id: user.id, username: user.username }, + annotate({ action: { name: "auth.login.password" } }); + + // No second factor — issue the session/token exactly as before. + return finishLogin({ + user, + request, + ip, + userAgent: ua, + source: "login.password", }); }); diff --git a/src/app/api/auth/mfa/verify/route.ts b/src/app/api/auth/mfa/verify/route.ts new file mode 100644 index 000000000..adf7dfde8 --- /dev/null +++ b/src/app/api/auth/mfa/verify/route.ts @@ -0,0 +1,139 @@ +/** + * POST /api/auth/mfa/verify + * + * Complete a second-factor login challenge. The caller presents the opaque + * `mfaTicket` from the `meta.mfaRequired` login response plus a TOTP or + * recovery code. On success the **same** session/token bundle the password + * path issues is returned (web → session cookie; native → access+refresh), + * with the session stamped `mfaVerifiedAt`. + * + * Security-critical invariants: + * - No session or token exists until the factor passes — the partial state + * lived in the ticket, never in a half-built session. + * - The ticket is **claimed once, atomically**, only AFTER the factor + * verifies; two concurrent valid submissions can mint at most one session. + * - Wrong factors increment the ticket attempt counter and burn it at the + * cap (NIST throttle, not an account lock). Anonymous surface is rate- + * limited per IP on top of the per-ticket cap. + */ +import { NextRequest } from "next/server"; +import { apiError, safeJson } from "@/lib/api-response"; +import { apiHandler } from "@/lib/api-handler"; +import { annotate } from "@/lib/logging/context"; +import { auditLog } from "@/lib/auth/audit"; +import { prisma } from "@/lib/db"; +import { ensureDbCompatibility } from "@/lib/db-compat"; +import { checkAuthSurfaceRateLimit, rateLimitHeaders } from "@/lib/rate-limit"; +import { finishLogin } from "@/lib/auth/login-response"; +import { + loadActiveChallenge, + recordChallengeFailure, + claimChallenge, +} from "@/lib/auth/mfa/challenge"; +import { verifyMfaFactor } from "@/lib/auth/mfa/verify-factor"; +import { mfaVerifySchema } from "@/lib/validations/mfa"; + +export const dynamic = "force-dynamic"; + +export const POST = apiHandler(async (request: NextRequest) => { + const rl = await checkAuthSurfaceRateLimit( + request, + "auth:mfa-verify", + 10, + 15 * 60 * 1000, + ); + const ip = rl.ip ?? "unknown"; + if (!rl.allowed) { + return apiError("Too many attempts. Please try again later.", 429, { + headers: rateLimitHeaders(rl), + }); + } + + await ensureDbCompatibility(); + + const { data: body, error: jsonError } = await safeJson(request, { + maxBytes: 16 * 1024, + }); + if (jsonError) return jsonError; + + const parsed = mfaVerifySchema.safeParse(body); + if (!parsed.success) { + return apiError("Invalid request", 422); + } + const { mfaTicket, method, code } = parsed.data; + + // Resolve the ticket. A single generic 401 covers unknown / expired / + // consumed / over-cap so a ticket-guesser learns nothing. + const challenge = await loadActiveChallenge(mfaTicket); + if (!challenge) { + annotate({ action: { name: "auth.mfa.verify.invalid_ticket" } }); + return apiError("Invalid or expired challenge", 401); + } + + const user = await prisma.user.findUnique({ + where: { id: challenge.userId }, + select: { + id: true, + username: true, + email: true, + onboardingCompletedAt: true, + totpConfirmedAt: true, + totpSecretEncrypted: true, + totpLastStep: true, + }, + }); + + // The factor must still be active (it could have been disabled between the + // password step and this call). Treat anything else as a failed attempt. + if (!user || !user.totpConfirmedAt) { + await recordChallengeFailure(challenge.id); + annotate({ action: { name: "auth.mfa.verify.no_active_factor" } }); + return apiError("Invalid or expired challenge", 401); + } + + const factor = await verifyMfaFactor(user, method, code); + if (!factor.ok) { + const { exhausted } = await recordChallengeFailure(challenge.id); + await auditLog("auth.mfa.failed", { + userId: user.id, + ipAddress: ip, + details: { stage: "login", method, replay: factor.replay, exhausted }, + }); + annotate({ + action: { name: "auth.mfa.failed" }, + meta: { method, replay: factor.replay, exhausted }, + }); + return apiError("Invalid code", 401); + } + + // Factor verified — claim the ticket atomically. Only the single winning + // caller proceeds to mint a session; a concurrent claim loses here. + const claimed = await claimChallenge(challenge.id); + if (!claimed) { + annotate({ action: { name: "auth.mfa.verify.claim_lost" } }); + return apiError("Invalid or expired challenge", 401); + } + + await auditLog("auth.mfa.verified", { + userId: user.id, + ipAddress: ip, + details: { method }, + }); + if (method === "recovery") { + await auditLog("auth.mfa.recovery_used", { + userId: user.id, + ipAddress: ip, + }); + } + annotate({ action: { name: "auth.mfa.verified" }, meta: { method } }); + + const ua = request.headers.get("user-agent"); + return finishLogin({ + user, + request, + ip, + userAgent: ua, + source: "mfa.verify", + mfaVerified: true, + }); +}); diff --git a/src/lib/auth/login-response.ts b/src/lib/auth/login-response.ts new file mode 100644 index 000000000..519c1f81d --- /dev/null +++ b/src/lib/auth/login-response.ts @@ -0,0 +1,125 @@ +/** + * Shared "issue the authenticated response" tail used by both the password + * login route and the `/api/auth/mfa/verify` route. + * + * Keeping one implementation guarantees the transport contract is identical + * whether or not a second factor sat in the middle: a web caller gets a + * session cookie, a cookie-less native caller gets the access + refresh + * bundle, and a legacy `X-Client-Type: native` caller gets a plain access + * token. The only behavioural difference the second factor introduces is the + * `mfaVerifiedAt` stamp threaded onto the issued session (cookie path) so + * step-up freshness can read it. + * + * Bearer-issuing branches do not carry an `mfaVerifiedAt` equivalent — the + * step-up primitive (`requireFreshMfa`) is cookie-only by construction, the + * same structural boundary as `requireAdmin`, so a token transport can never + * satisfy step-up regardless. + */ +import type { NextRequest } from "next/server"; +import { apiSuccess } from "@/lib/api-response"; +import { auditLog } from "@/lib/auth/audit"; +import { createSession } from "@/lib/auth/session"; +import { issueApiToken, isNativeClientRequest } from "@/lib/auth/issue-token"; +import { + resolveTokenPolicy, + shouldIssueBearerToken, + isCookielessNativeCaller, +} from "@/lib/auth/native-client"; +import { issueAccessAndRefresh } from "@/lib/auth/refresh-token"; +import type { User } from "@/generated/prisma/client"; + +export interface FinishLoginParams { + user: Pick; + request: NextRequest; + ip: string; + userAgent: string | null; + /** Audit `source` discriminator, e.g. `"login.password"` / `"mfa.verify"`. */ + source: string; + /** + * When true the issued session is stamped `mfaVerifiedAt = now()` so + * step-up gates treat it as freshly second-factor-verified. Only the + * cookie path carries the stamp. + */ + mfaVerified?: boolean; +} + +/** + * Mint the session/token for an already-authenticated user and return the + * client response. Caller is responsible for the prior factor checks and for + * its own `auth.login.*` / `auth.mfa.*` audit entries; this writes only the + * token-issuance audit rows. + */ +export async function finishLogin( + params: FinishLoginParams, +): Promise { + const { user, request, ip, userAgent, source, mfaVerified } = params; + + if ( + shouldIssueBearerToken(request.headers) || + isNativeClientRequest(request.headers) + ) { + const policy = resolveTokenPolicy(request.headers); + const deviceId = request.headers.get("x-device-id"); + + // A 60-day refresh token is only ever delivered to a genuinely + // cookie-less native caller — a browser spoofing `X-Client-Type: native` + // falls through to the plain access-token path below. + if ( + policy.refreshTokenDays !== null && + isCookielessNativeCaller(request.headers) + ) { + const bundle = await issueAccessAndRefresh({ + userId: user.id, + policy, + deviceId, + userAgent, + ipAddress: ip, + source, + }); + await auditLog("auth.token.autoissue.native", { + userId: user.id, + ipAddress: ip, + details: { source, policy: "native" }, + }); + return apiSuccess({ + user: { id: user.id, username: user.username }, + token: bundle.accessToken, + tokenExpiresAt: bundle.accessTokenExpiresAt.toISOString(), + refreshToken: bundle.refreshToken, + refreshTokenExpiresAt: bundle.refreshTokenExpiresAt.toISOString(), + }); + } + + // Web policy with explicit X-Client-Type:native (legacy iOS auto-login). + const issued = await issueApiToken({ + userId: user.id, + name: `web auto-login ${new Date().toISOString()}`, + permissions: ["*"], + expiresInDays: policy.accessTokenDays, + }); + await auditLog("auth.token.autoissue.native", { + userId: user.id, + ipAddress: ip, + details: { tokenId: issued.tokenId, source, policy: "web" }, + }); + return apiSuccess({ + user: { id: user.id, username: user.username }, + token: issued.token, + tokenExpiresAt: issued.expiresAt.toISOString(), + }); + } + + // Browser path — session cookie. `createSession` anchors the onboarding + // cookie itself; thread the user's onboarding state through. + await createSession( + user.id, + user.onboardingCompletedAt == null, + ip, + userAgent, + mfaVerified ? new Date() : null, + ); + + return apiSuccess({ + user: { id: user.id, username: user.username }, + }); +} diff --git a/src/lib/auth/mfa/__tests__/challenge.test.ts b/src/lib/auth/mfa/__tests__/challenge.test.ts new file mode 100644 index 000000000..74e4bfc47 --- /dev/null +++ b/src/lib/auth/mfa/__tests__/challenge.test.ts @@ -0,0 +1,130 @@ +import { describe, it, expect, vi, beforeEach } from "vitest"; + +vi.mock("@/lib/db", () => ({ + prisma: { + mfaChallenge: { + create: vi.fn(), + findUnique: vi.fn(), + update: vi.fn(), + updateMany: vi.fn(), + }, + }, +})); + +// Stand-in for the real HMAC: deterministic but NOT containing the raw +// ticket, so the "raw ticket is never persisted" assertion is meaningful. +vi.mock("@/lib/auth/hmac", () => ({ + hashToken: vi.fn((t: string) => `H${t.length}`), +})); + +import { + createMfaChallenge, + loadActiveChallenge, + recordChallengeFailure, + claimChallenge, + MFA_CHALLENGE_ATTEMPT_CAP, +} from "../challenge"; +import { prisma } from "@/lib/db"; + +beforeEach(() => { + vi.clearAllMocks(); +}); + +function activeRow(overrides: Record = {}) { + return { + id: "ch-1", + userId: "user-1", + kind: "login", + attempts: 0, + expiresAt: new Date(Date.now() + 60_000), + consumedAt: null, + ...overrides, + }; +} + +describe("mfa challenge", () => { + it("mints a ticket and stores only its hash", async () => { + vi.mocked(prisma.mfaChallenge.create).mockResolvedValue({} as never); + const { ticket } = await createMfaChallenge("user-1", "login"); + expect(typeof ticket).toBe("string"); + expect(ticket.length).toBeGreaterThan(20); + const arg = vi.mocked(prisma.mfaChallenge.create).mock.calls[0][0]; + expect(arg.data.ticketHash).toBe(`H${ticket.length}`); + // Raw ticket is never persisted. + expect(JSON.stringify(arg)).not.toContain(ticket); + }); + + it("loads an active challenge by hash", async () => { + vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue( + activeRow() as never, + ); + const res = await loadActiveChallenge("tkt"); + expect(res?.id).toBe("ch-1"); + expect( + vi.mocked(prisma.mfaChallenge.findUnique).mock.calls[0][0], + ).toMatchObject({ where: { ticketHash: "H3" } }); + }); + + it("refuses a consumed ticket (single-use)", async () => { + vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue( + activeRow({ consumedAt: new Date() }) as never, + ); + expect(await loadActiveChallenge("tkt")).toBeNull(); + }); + + it("refuses an expired ticket (TTL)", async () => { + vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue( + activeRow({ expiresAt: new Date(Date.now() - 1000) }) as never, + ); + expect(await loadActiveChallenge("tkt")).toBeNull(); + }); + + it("refuses a ticket at the attempt cap", async () => { + vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue( + activeRow({ attempts: MFA_CHALLENGE_ATTEMPT_CAP }) as never, + ); + expect(await loadActiveChallenge("tkt")).toBeNull(); + }); + + it("refuses an unknown ticket", async () => { + vi.mocked(prisma.mfaChallenge.findUnique).mockResolvedValue(null as never); + expect(await loadActiveChallenge("nope")).toBeNull(); + }); + + it("burns the ticket when the attempt cap is reached", async () => { + vi.mocked(prisma.mfaChallenge.update).mockResolvedValue({ + attempts: MFA_CHALLENGE_ATTEMPT_CAP, + } as never); + vi.mocked(prisma.mfaChallenge.updateMany).mockResolvedValue({ + count: 1, + } as never); + const res = await recordChallengeFailure("ch-1"); + expect(res.exhausted).toBe(true); + // Burn sets consumedAt only while still null (claim-once guard). + expect(prisma.mfaChallenge.updateMany).toHaveBeenCalledWith({ + where: { id: "ch-1", consumedAt: null }, + data: { consumedAt: expect.any(Date) }, + }); + }); + + it("does not burn below the attempt cap", async () => { + vi.mocked(prisma.mfaChallenge.update).mockResolvedValue({ + attempts: 1, + } as never); + const res = await recordChallengeFailure("ch-1"); + expect(res.exhausted).toBe(false); + expect(prisma.mfaChallenge.updateMany).not.toHaveBeenCalled(); + }); + + it("claim-once: only the winning update returns true", async () => { + vi.mocked(prisma.mfaChallenge.updateMany).mockResolvedValueOnce({ + count: 1, + } as never); + expect(await claimChallenge("ch-1")).toBe(true); + + vi.mocked(prisma.mfaChallenge.updateMany).mockResolvedValueOnce({ + count: 0, + } as never); + expect(await claimChallenge("ch-1")).toBe(false); + }); +}); diff --git a/src/lib/auth/mfa/challenge.ts b/src/lib/auth/mfa/challenge.ts new file mode 100644 index 000000000..9e641982d --- /dev/null +++ b/src/lib/auth/mfa/challenge.ts @@ -0,0 +1,133 @@ +/** + * MfaChallenge — the short-lived, single-use login step-up ticket. + * + * When a password (or other primary credential) is accepted for an account + * that has a second factor enabled, **no session or token is issued**. + * Instead a challenge row is minted: the partial "password OK, awaiting + * factor 2" state lives entirely in this row, never in a half-built + * `Session`. The caller receives an opaque ticket; only its hash + * (`hashToken`) is stored, so a leaked database row cannot reconstruct a + * usable ticket. + * + * Guarantees enforced here: + * - **TTL** (~5 min) — `expiresAt`; an expired ticket is never loadable. + * - **Attempt cap** — `attempts` is incremented on every wrong factor and + * the ticket is burned (`consumedAt` set) once the cap is hit, forcing a + * fresh password login (NIST throttle, not an account lock). + * - **Claim-once** — consuming a ticket is an atomic guarded update + * (`consumedAt: null` in the WHERE), so two concurrent verifications can + * never both succeed and mint two sessions. The factor is verified first; + * the session is issued only after the claim wins. + */ +import { randomBytes } from "node:crypto"; +import { hashToken } from "@/lib/auth/hmac"; +import { prisma } from "@/lib/db"; + +/** Login step-up: the only `kind` Phase M exercises. */ +export type MfaChallengeKind = "login"; + +/** 5-minute ticket life — long enough to read a code, short enough to bound replay. */ +export const MFA_CHALLENGE_TTL_MS = 5 * 60 * 1000; +/** Wrong-factor attempts before the ticket is burned. */ +export const MFA_CHALLENGE_ATTEMPT_CAP = 5; + +export interface CreatedChallenge { + /** The opaque ticket handed to the client (never stored in the clear). */ + ticket: string; + expiresAt: Date; +} + +/** Mint a fresh single-use challenge for a user/kind. */ +export async function createMfaChallenge( + userId: string, + kind: MfaChallengeKind, +): Promise { + const ticket = randomBytes(32).toString("base64url"); + const expiresAt = new Date(Date.now() + MFA_CHALLENGE_TTL_MS); + await prisma.mfaChallenge.create({ + data: { + userId, + kind, + ticketHash: hashToken(ticket), + expiresAt, + }, + }); + return { ticket, expiresAt }; +} + +export interface ActiveChallenge { + id: string; + userId: string; + kind: string; + attempts: number; + expiresAt: Date; +} + +/** + * Resolve a presented ticket to its live challenge, or null when it is + * unknown / already consumed / expired / over the attempt cap. The lookup + * is by hash — the raw ticket is never compared against a stored plaintext. + */ +export async function loadActiveChallenge( + ticket: string, +): Promise { + const row = await prisma.mfaChallenge.findUnique({ + where: { ticketHash: hashToken(ticket) }, + select: { + id: true, + userId: true, + kind: true, + attempts: true, + expiresAt: true, + consumedAt: true, + }, + }); + if (!row) return null; + if (row.consumedAt !== null) return null; + if (row.expiresAt.getTime() <= Date.now()) return null; + if (row.attempts >= MFA_CHALLENGE_ATTEMPT_CAP) return null; + return { + id: row.id, + userId: row.userId, + kind: row.kind, + attempts: row.attempts, + expiresAt: row.expiresAt, + }; +} + +/** + * Record a failed factor attempt. Increments `attempts`; when the cap is + * reached the ticket is burned (`consumedAt` set) so it cannot be retried. + * Returns whether the ticket is now exhausted. + */ +export async function recordChallengeFailure( + challengeId: string, +): Promise<{ exhausted: boolean; attempts: number }> { + const updated = await prisma.mfaChallenge.update({ + where: { id: challengeId }, + data: { attempts: { increment: 1 } }, + select: { attempts: true }, + }); + const exhausted = updated.attempts >= MFA_CHALLENGE_ATTEMPT_CAP; + if (exhausted) { + await prisma.mfaChallenge.updateMany({ + where: { id: challengeId, consumedAt: null }, + data: { consumedAt: new Date() }, + }); + } + return { exhausted, attempts: updated.attempts }; +} + +/** + * Atomically claim the ticket. Returns true only for the single caller that + * transitions `consumedAt` from null → now. The factor MUST already be + * verified before this is called; the session is issued only when this + * returns true. + */ +export async function claimChallenge(challengeId: string): Promise { + const claimed = await prisma.mfaChallenge.updateMany({ + where: { id: challengeId, consumedAt: null }, + data: { consumedAt: new Date() }, + }); + return claimed.count === 1; +} diff --git a/src/lib/openapi/routes/auth.ts b/src/lib/openapi/routes/auth.ts index 77a6002ac..28736b8af 100644 --- a/src/lib/openapi/routes/auth.ts +++ b/src/lib/openapi/routes/auth.ts @@ -8,6 +8,11 @@ import { z } from "zod/v4"; import type { ZodOpenApiObject } from "zod-openapi"; import { loginPasswordSchema } from "@/lib/validations/auth"; +import { + mfaVerifySchema, + totpConfirmSchema, + mfaDisableSchema, +} from "@/lib/validations/mfa"; import { dataEnvelope, stdResponses } from "./shared"; // ── Sub-schemas owned here (route-specific shapes) ─────────────────── @@ -73,23 +78,193 @@ const accessRefreshBundle = z "Native-client token bundle returned by login + refresh. Web cookie-only callers see only `user`.", }); +// ── v1.23 second-factor (MFA) shapes ───────────────────────────────── + +const mfaRequiredEnvelope = z + .object({ + data: z.null(), + error: z.null(), + meta: z.object({ + mfaRequired: z.literal(true), + mfaTicket: z + .string() + .describe( + "Opaque, single-use, ~5-minute ticket to present to /api/auth/mfa/verify.", + ), + methods: z + .array(z.enum(["totp", "recovery"])) + .describe( + "Second factors the account can complete the challenge with.", + ), + }), + }) + .meta({ + id: "MfaRequiredResponse", + description: + "Password accepted but a second factor is required. Not an error and not a session — no token is issued until /api/auth/mfa/verify succeeds.", + }); + +const totpSetupResponse = z + .object({ + otpauthUri: z + .string() + .describe("otpauth:// URI to render as a QR code (carries the secret)."), + totpSecret: z + .string() + .describe("Base32 secret for manual entry. Pending until confirmed."), + }) + .meta({ id: "TotpSetupResponse" }); + +const recoveryCodesResponse = z + .object({ + enabled: z.boolean().optional(), + recoveryCodes: z + .array(z.string()) + .describe("Single-use recovery codes, shown once. Save them now."), + recoveryCodesRemaining: z.number().int(), + }) + .meta({ id: "MfaRecoveryCodesResponse" }); + +const mfaToggleResponse = z + .object({ enabled: z.boolean() }) + .meta({ id: "MfaToggleResponse" }); + export const authPaths: NonNullable = { "/api/auth/login": { post: { tags: ["Auth"], summary: "Email-or-username login (password)", description: - "Browser callers receive a session cookie. Native callers (X-Client-Type: native or HealthLog-iOS UA prefix) additionally receive a paired access + refresh token.", + "Browser callers receive a session cookie. Native callers (X-Client-Type: native or HealthLog-iOS UA prefix) additionally receive a paired access + refresh token.\n\n" + + "v1.23 — when the account has a confirmed second factor, the response carries no session/token. It returns HTTP 200 with `data: null, error: null` and `meta.mfaRequired: true` plus a single-use `meta.mfaTicket` and the `meta.methods` list. The client must POST the ticket + a code to `/api/auth/mfa/verify` to obtain the token bundle. Accounts without MFA are unchanged.", requestBody: { required: true, content: { "application/json": { schema: loginPasswordSchema } }, }, responses: { "200": { - description: "Login succeeded.", + description: + "Login succeeded (token bundle / cookie) — or a second factor is required (`meta.mfaRequired`).", content: { "application/json": { - schema: dataEnvelope(accessRefreshBundle, "LoginResponse"), + schema: z.union([ + dataEnvelope(accessRefreshBundle, "LoginResponse"), + mfaRequiredEnvelope, + ]), + }, + }, + }, + ...stdResponses, + }, + }, + }, + "/api/auth/mfa/verify": { + post: { + tags: ["Auth"], + summary: "Complete a second-factor login challenge", + description: + "Presents the `mfaTicket` from the login `meta.mfaRequired` response plus a TOTP or recovery code. On success returns the SAME token bundle / session the password path issues, with the session marked second-factor-verified. The ticket is single-use; wrong codes are throttled and the ticket is burned at the attempt cap.", + requestBody: { + required: true, + content: { "application/json": { schema: mfaVerifySchema } }, + }, + responses: { + "200": { + description: + "Second factor verified — session + optional bearer issued.", + content: { + "application/json": { + schema: dataEnvelope(accessRefreshBundle, "MfaVerifyResponse"), + }, + }, + }, + ...stdResponses, + }, + }, + }, + "/api/auth/me/mfa/totp/setup": { + post: { + tags: ["Auth"], + summary: "Begin TOTP enrollment (cookie session only)", + description: + "Generates and stores a pending (encrypted) TOTP secret and returns the otpauth URI + Base32 secret. MFA is not active until /confirm. Cookie-only — a Bearer token cannot enrol MFA.", + responses: { + "200": { + description: "Pending secret created.", + content: { + "application/json": { + schema: dataEnvelope(totpSetupResponse, "TotpSetupEnvelope"), + }, + }, + }, + ...stdResponses, + }, + }, + }, + "/api/auth/me/mfa/totp/confirm": { + post: { + tags: ["Auth"], + summary: "Confirm TOTP enrollment (cookie session only)", + description: + "Verifies a code against the pending secret, activates the factor, and returns the one-time recovery codes. Cookie-only.", + requestBody: { + required: true, + content: { "application/json": { schema: totpConfirmSchema } }, + }, + responses: { + "200": { + description: "Factor activated — recovery codes returned once.", + content: { + "application/json": { + schema: dataEnvelope( + recoveryCodesResponse, + "TotpConfirmEnvelope", + ), + }, + }, + }, + ...stdResponses, + }, + }, + }, + "/api/auth/me/mfa/disable": { + post: { + tags: ["Auth"], + summary: "Disable the second factor (step-up gated)", + description: + "Requires a fresh second-factor step-up (cookie session) AND a current TOTP or recovery code. Clears the secret and deletes recovery codes. Bearer can never satisfy the step-up gate.", + requestBody: { + required: true, + content: { "application/json": { schema: mfaDisableSchema } }, + }, + responses: { + "200": { + description: "Factor disabled.", + content: { + "application/json": { + schema: dataEnvelope(mfaToggleResponse, "MfaDisableEnvelope"), + }, + }, + }, + ...stdResponses, + }, + }, + }, + "/api/auth/me/mfa/recovery-codes/regenerate": { + post: { + tags: ["Auth"], + summary: "Regenerate recovery codes (step-up gated)", + description: + "Invalidates the entire prior recovery-code set and returns a fresh batch once. Step-up gated; Bearer can never satisfy the gate.", + responses: { + "200": { + description: "Fresh recovery codes issued.", + content: { + "application/json": { + schema: dataEnvelope( + recoveryCodesResponse, + "MfaRecoveryRegenEnvelope", + ), }, }, }, diff --git a/tests/integration/mfa-login-flow.test.ts b/tests/integration/mfa-login-flow.test.ts new file mode 100644 index 000000000..f646d7ad5 --- /dev/null +++ b/tests/integration/mfa-login-flow.test.ts @@ -0,0 +1,155 @@ +/** + * Integration guard for the second-factor login path against real Postgres. + * + * Unit tests mock Prisma, so they cannot prove the security-critical DB-backed + * invariants: that a verified TOTP step is actually persisted (replay guard), + * that the recovery-code burn is durable and one-time, and that the challenge + * ticket can be claimed exactly once. This exercises all three end to end. + */ +import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; +import * as OTPAuth from "otpauth"; + +import { getPrismaClient, truncateAllTables } from "./setup"; + +// hashToken (challenge ticket hashing) is fail-closed on a weak/absent key. +process.env.API_TOKEN_HMAC_KEY ??= + "test-hmac-key-test-hmac-key-test-hmac-key-0123456789"; + +vi.mock("@/lib/db-compat", () => ({ + ensureDbCompatibility: vi.fn().mockResolvedValue(undefined), +})); + +function codeAt(secretBase32: string, atMs: number): string { + const totp = new OTPAuth.TOTP({ + issuer: "HealthLog", + label: "HealthLog", + algorithm: "SHA1", + digits: 6, + period: 30, + secret: OTPAuth.Secret.fromBase32(secretBase32), + }); + return totp.generate({ timestamp: atMs }); +} + +let secret: string; +let encrypt: (s: string) => string; + +beforeAll(async () => { + ({ encrypt } = await import("@/lib/crypto")); + const { generateTotpSecret } = await import("@/lib/auth/mfa/totp"); + secret = generateTotpSecret(); +}); + +beforeEach(async () => { + await truncateAllTables(getPrismaClient()); +}); + +describe("MFA login flow (real Postgres)", () => { + it("TOTP verify persists the step and rejects a replay", async () => { + const { verifyMfaFactor } = await import("@/lib/auth/mfa/verify-factor"); + const prisma = getPrismaClient(); + + const user = await prisma.user.create({ + data: { + username: "totp-user", + email: "totp@example.test", + totpSecretEncrypted: encrypt(secret), + totpConfirmedAt: new Date(), + }, + }); + + // verifyMfaFactor verifies against the real wall clock, so the code must + // be generated for "now". + const code = codeAt(secret, Date.now()); + + const first = await verifyMfaFactor( + { id: user.id, totpSecretEncrypted: encrypt(secret), totpLastStep: null }, + "totp", + code, + ); + expect(first.ok).toBe(true); + + const afterFirst = await prisma.user.findUnique({ + where: { id: user.id }, + select: { totpLastStep: true }, + }); + expect(afterFirst?.totpLastStep).not.toBeNull(); + + // Replay the same code — the persisted step now floors it out. + const replay = await verifyMfaFactor( + { + id: user.id, + totpSecretEncrypted: encrypt(secret), + totpLastStep: afterFirst?.totpLastStep ?? null, + }, + "totp", + code, + ); + expect(replay.ok).toBe(false); + expect(replay.replay).toBe(true); + }); + + it("challenge is single-use and burns at the attempt cap", async () => { + const { + createMfaChallenge, + loadActiveChallenge, + claimChallenge, + recordChallengeFailure, + MFA_CHALLENGE_ATTEMPT_CAP, + } = await import("@/lib/auth/mfa/challenge"); + const prisma = getPrismaClient(); + + const user = await prisma.user.create({ + data: { username: "ch-user", email: "ch@example.test" }, + }); + + const { ticket } = await createMfaChallenge(user.id, "login"); + const active = await loadActiveChallenge(ticket); + expect(active).not.toBeNull(); + + // Claim-once: first claim wins, second loses, ticket no longer loadable. + expect(await claimChallenge(active!.id)).toBe(true); + expect(await claimChallenge(active!.id)).toBe(false); + expect(await loadActiveChallenge(ticket)).toBeNull(); + + // Attempt cap burns a fresh ticket. + const second = await createMfaChallenge(user.id, "login"); + const row = await loadActiveChallenge(second.ticket); + let exhausted = false; + for (let i = 0; i < MFA_CHALLENGE_ATTEMPT_CAP; i++) { + ({ exhausted } = await recordChallengeFailure(row!.id)); + } + expect(exhausted).toBe(true); + expect(await loadActiveChallenge(second.ticket)).toBeNull(); + }); + + it("recovery code is one-time-use and regeneration invalidates the set", async () => { + const { + generateRecoveryCodes, + persistRecoveryCodes, + verifyAndConsumeRecoveryCode, + countRemainingRecoveryCodes, + regenerateRecoveryCodes, + } = await import("@/lib/auth/mfa/recovery-codes"); + const prisma = getPrismaClient(); + + const user = await prisma.user.create({ + data: { username: "rec-user", email: "rec@example.test" }, + }); + + const codes = generateRecoveryCodes(); + await persistRecoveryCodes(prisma, user.id, codes); + expect(await countRemainingRecoveryCodes(user.id)).toBe(codes.length); + + // First use succeeds, second use of the same code fails. + expect(await verifyAndConsumeRecoveryCode(user.id, codes[0])).toBe(true); + expect(await verifyAndConsumeRecoveryCode(user.id, codes[0])).toBe(false); + expect(await countRemainingRecoveryCodes(user.id)).toBe(codes.length - 1); + + // Regeneration drops every prior code (including the one not yet used). + const fresh = await regenerateRecoveryCodes(user.id); + expect(await countRemainingRecoveryCodes(user.id)).toBe(fresh.length); + expect(await verifyAndConsumeRecoveryCode(user.id, codes[1])).toBe(false); + expect(await verifyAndConsumeRecoveryCode(user.id, fresh[0])).toBe(true); + }); +});