merge: integrate the v1.23 security settings and MFA wave

# Conflicts:
#	messages/de.json
#	messages/en.json
#	messages/es.json
#	messages/fr.json
#	messages/it.json
#	messages/pl.json
#	src/lib/openapi/routes/auth.ts
#	src/lib/query-keys/auth.ts

src/app/api/auth/mfa/webauthn/verify/__tests__/route.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NextRequest } from "next/server";
+
+vi.mock("@/lib/api-handler", () => ({
+  apiHandler: (fn: unknown) => fn,
+}));
+
+vi.mock("@/lib/db", () => ({
+  prisma: { user: { findUnique: vi.fn() } },
+}));
+
+vi.mock("@/lib/db-compat", () => ({
+  ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@/lib/rate-limit", () => ({
+  checkAuthSurfaceRateLimit: vi.fn(),
+  rateLimitHeaders: vi.fn(() => ({})),
+}));
+
+vi.mock("@/lib/auth/mfa/challenge", () => ({
+  loadActiveChallenge: vi.fn(),
+  recordChallengeFailure: vi.fn().mockResolvedValue({ exhausted: false }),
+  claimChallenge: vi.fn(),
+}));
+
+vi.mock("@/lib/auth/mfa/webauthn", () => ({
+  verifyMfaAuthentication: vi.fn(),
+}));
+
+vi.mock("@/lib/auth/login-response", () => ({
+  finishLogin: vi.fn(),
+}));
+
+vi.mock("@/lib/auth/audit", () => ({
+  auditLog: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@/lib/logging/context", () => ({
+  annotate: vi.fn(),
+}));
+
+import { POST } from "../route";
+import { prisma } from "@/lib/db";
+import { checkAuthSurfaceRateLimit } from "@/lib/rate-limit";
+import {
+  loadActiveChallenge,
+  claimChallenge,
+  recordChallengeFailure,
+} from "@/lib/auth/mfa/challenge";
+import { verifyMfaAuthentication } from "@/lib/auth/mfa/webauthn";
+import { finishLogin } from "@/lib/auth/login-response";
+
+function makeRequest(body: Record<string, unknown>): NextRequest {
+  return new NextRequest("http://localhost/api/auth/mfa/webauthn/verify", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+const VALID_BODY = {
+  mfaTicket: "ticket-1",
+  challengeId: "ch-1",
+  credential: {
+    id: "cred-1",
+    rawId: "cred-1",
+    type: "public-key",
+    response: {},
+  },
+};
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.mocked(checkAuthSurfaceRateLimit).mockResolvedValue({
+    allowed: true,
+    ip: "203.0.113.1",
+  } as never);
+  vi.mocked(loadActiveChallenge).mockResolvedValue({
+    id: "mfa-1",
+    userId: "user-1",
+    kind: "login",
+    attempts: 0,
+    expiresAt: new Date(Date.now() + 60_000),
+  } as never);
+  vi.mocked(prisma.user.findUnique).mockResolvedValue({
+    id: "user-1",
+    username: "u",
+    onboardingCompletedAt: new Date(),
+  } as never);
+  vi.mocked(recordChallengeFailure).mockResolvedValue({
+    exhausted: false,
+    attempts: 1,
+  } as never);
+  vi.mocked(finishLogin).mockResolvedValue(
+    new Response(JSON.stringify({ data: { user: { id: "user-1" } } }), {
+      status: 200,
+    }),
+  );
+});
+
+describe("POST /api/auth/mfa/webauthn/verify", () => {
+  it("finishes login when the assertion verifies and the ticket is claimed", async () => {
+    vi.mocked(verifyMfaAuthentication).mockResolvedValue(true as never);
+    vi.mocked(claimChallenge).mockResolvedValue(true as never);
+
+    const res = await POST(makeRequest(VALID_BODY));
+
+    expect(res.status).toBe(200);
+    expect(verifyMfaAuthentication).toHaveBeenCalledWith(
+      "ch-1",
+      "user-1",
+      VALID_BODY.credential,
+    );
+    expect(claimChallenge).toHaveBeenCalledWith("mfa-1");
+    expect(finishLogin).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mfaVerified: true,
+        source: "mfa.webauthn.verify",
+      }),
+    );
+  });
+
+  it("rejects with 401 and burns an attempt when the assertion fails", async () => {
+    vi.mocked(verifyMfaAuthentication).mockResolvedValue(false as never);
+
+    const res = await POST(makeRequest(VALID_BODY));
+
+    expect(res.status).toBe(401);
+    expect(recordChallengeFailure).toHaveBeenCalledWith("mfa-1");
+    expect(claimChallenge).not.toHaveBeenCalled();
+    expect(finishLogin).not.toHaveBeenCalled();
+  });
+
+  it("rejects with 401 for an unknown / expired ticket", async () => {
+    vi.mocked(loadActiveChallenge).mockResolvedValue(null as never);
+
+    const res = await POST(makeRequest(VALID_BODY));
+
+    expect(res.status).toBe(401);
+    expect(verifyMfaAuthentication).not.toHaveBeenCalled();
+  });
+
+  it("does not mint a session if the ticket claim is lost (concurrent)", async () => {
+    vi.mocked(verifyMfaAuthentication).mockResolvedValue(true as never);
+    vi.mocked(claimChallenge).mockResolvedValue(false as never);
+
+    const res = await POST(makeRequest(VALID_BODY));
+
+    expect(res.status).toBe(401);
+    expect(finishLogin).not.toHaveBeenCalled();
+  });
+
+  it("returns 429 when rate limited", async () => {
+    vi.mocked(checkAuthSurfaceRateLimit).mockResolvedValue({
+      allowed: false,
+      ip: "203.0.113.1",
+    } as never);
+
+    const res = await POST(makeRequest(VALID_BODY));
+    expect(res.status).toBe(429);
+  });
+});

src/app/api/auth/mfa/webauthn/verify/options/route.ts

@@ -0,0 +1,70 @@
+/**
+ * POST /api/auth/mfa/webauthn/verify/options
+ *
+ * Begin a mid-login second-factor security-key assertion. The caller presents
+ * the opaque `mfaTicket` from the `meta.mfaRequired` login response; the server
+ * resolves the password-identified user and returns assertion options scoped to
+ * that user's registered MFA security keys (never an empty allow-list — a
+ * non-resident credential is not discoverable).
+ *
+ * Anonymous surface (no session yet), rate-limited per IP. A single generic
+ * 401 covers every unknown / expired / consumed ticket so a guesser learns
+ * nothing.
+ */
+import { NextRequest } from "next/server";
+import { apiHandler } from "@/lib/api-handler";
+import { apiError, apiSuccess, safeJson } from "@/lib/api-response";
+import { annotate } from "@/lib/logging/context";
+import { ensureDbCompatibility } from "@/lib/db-compat";
+import { checkAuthSurfaceRateLimit, rateLimitHeaders } from "@/lib/rate-limit";
+import { loadActiveChallenge } from "@/lib/auth/mfa/challenge";
+import { createMfaAuthenticationOptions } from "@/lib/auth/mfa/webauthn";
+import { mfaWebauthnLoginOptionsSchema } 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,
+  );
+  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 = mfaWebauthnLoginOptionsSchema.safeParse(body);
+  if (!parsed.success) {
+    return apiError("Invalid request", 422);
+  }
+
+  const challenge = await loadActiveChallenge(parsed.data.mfaTicket);
+  if (!challenge) {
+    annotate({ action: { name: "auth.mfa.verify.invalid_ticket" } });
+    return apiError("Invalid or expired challenge", 401);
+  }
+
+  const result = await createMfaAuthenticationOptions(challenge.userId);
+  if (!result) {
+    // No registered security key for this account — the client should fall
+    // back to a TOTP / recovery code.
+    annotate({ action: { name: "auth.mfa.webauthn.no_key" } });
+    return apiError("No security key registered", 409);
+  }
+
+  annotate({ action: { name: "auth.mfa.webauthn.verify-options" } });
+  return apiSuccess({
+    options: result.options,
+    challengeId: result.challengeId,
+  });
+});

src/app/api/auth/mfa/webauthn/verify/route.ts

@@ -0,0 +1,127 @@
+/**
+ * POST /api/auth/mfa/webauthn/verify
+ *
+ * Complete a mid-login second-factor login challenge with a WebAuthn security
+ * key. The caller presents the login `mfaTicket` plus the assertion from
+ * /verify/options. On success the SAME session/token bundle the password path
+ * issues is returned (web → cookie; native → access+refresh), with the session
+ * stamped `mfaVerifiedAt`.
+ *
+ * Security invariants mirror /api/auth/mfa/verify (the TOTP path):
+ * - No session/token exists until the assertion verifies — the partial state
+ *   lives in the ticket, never in a half-built session.
+ * - The ticket is claimed once, atomically, only AFTER the assertion verifies.
+ * - A failed assertion increments the ticket attempt counter and burns it at
+ *   the cap. Anonymous surface is rate-limited per IP on top of the cap.
+ */
+import { NextRequest } from "next/server";
+import { apiHandler } from "@/lib/api-handler";
+import { apiError, safeJson } from "@/lib/api-response";
+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 { verifyMfaAuthentication } from "@/lib/auth/mfa/webauthn";
+import { mfaWebauthnLoginVerifySchema } 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: 64 * 1024,
+  });
+  if (jsonError) return jsonError;
+
+  const parsed = mfaWebauthnLoginVerifySchema.safeParse(body);
+  if (!parsed.success) {
+    return apiError("Invalid request", 422);
+  }
+  const { mfaTicket, challengeId, credential } = parsed.data;
+
+  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, onboardingCompletedAt: true },
+  });
+  if (!user) {
+    await recordChallengeFailure(challenge.id);
+    return apiError("Invalid or expired challenge", 401);
+  }
+
+  let verified = false;
+  try {
+    verified = await verifyMfaAuthentication(challengeId, user.id, credential);
+  } catch {
+    // A malformed / expired WebAuthn challenge is a failed attempt, not a 500.
+    verified = false;
+  }
+
+  if (!verified) {
+    const { exhausted } = await recordChallengeFailure(challenge.id);
+    await auditLog("auth.mfa.failed", {
+      userId: user.id,
+      ipAddress: ip,
+      details: { stage: "login", method: "webauthn", exhausted },
+    });
+    annotate({
+      action: { name: "auth.mfa.failed" },
+      meta: { method: "webauthn", exhausted },
+    });
+    return apiError("Security key verification failed", 401);
+  }
+
+  // Assertion verified — claim the ticket atomically. Only the single winning
+  // caller proceeds to mint a session.
+  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: "webauthn" },
+  });
+  annotate({
+    action: { name: "auth.mfa.verified" },
+    meta: { method: "webauthn" },
+  });
+
+  const ua = request.headers.get("user-agent");
+  return finishLogin({
+    user,
+    request,
+    ip,
+    userAgent: ua,
+    source: "mfa.webauthn.verify",
+    mfaVerified: true,
+  });
+});