@cosmicdrift/kumiko-bundled-features 0.161.0 → 0.162.0

package/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -0,0 +1,87 @@
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { base32Encode } from "../base32";
+import { MFA_SETUP_TOKEN_TTL_MINUTES } from "../constants";
+import { findUserMfaRow } from "../db/queries";
+import { invalidChallengeToken, mfaAlreadyEnabled } from "../errors";
+import { verifyMfaPreauthSetupToken } from "../mfa-preauth-setup-token";
+import { signMfaSetupToken } from "../mfa-setup-token";
+import { buildOtpauthUri } from "../otpauth-uri";
+import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes";
+import { generateTotpSecret } from "../totp";
+
+export type EnableStartPreauthOptions = {
+  // Verifies the incoming preauthSetupToken — must match login.write.ts's
+  // mfaStatusChecker (challengeTokenSecret), NOT setupTokenSecret.
+  readonly challengeTokenSecret: string;
+  // Signs the outgoing secret-carrying setupToken — same secret + token
+  // format as enable-start.write.ts, so the later pre-auth confirm step can
+  // verify it with the existing verifyMfaSetupToken.
+  readonly setupTokenSecret: string;
+  readonly issuer: string;
+};
+
+// Pre-auth twin of enable-start.write.ts: identity comes from a verified
+// preauthSetupToken (minted by login.write.ts when enforcement policy
+// blocks an unenrolled user), not from event.user — there is no session at
+// this point. Runs pre-session the same way verify.write.ts does (dispatched
+// by the framework's /auth/mfa/preauth-enable-start route with GUEST_USER).
+export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions) {
+  return defineWriteHandler({
+    name: "enable-start-preauth",
+    schema: z.object({
+      preauthSetupToken: z.string().min(1),
+      accountLabel: z.string().min(1).max(200),
+    }),
+    access: { roles: ["all"] },
+    handler: async (event, ctx) => {
+      const verified = verifyMfaPreauthSetupToken(
+        event.payload.preauthSetupToken,
+        opts.challengeTokenSecret,
+      );
+      // Same generic "sign in again" error as an expired/invalid MFA
+      // challenge token — both mean the login-flow token expired, no
+      // distinct i18n needed (see #1465's scoping comment).
+      if (!verified.ok) return invalidChallengeToken();
+      const { userId, tenantId } = verified.payload;
+
+      // "system" mode: the guest dispatch identity's own tenantId is
+      // meaningless here — the preauthSetupToken is the source of truth
+      // for which tenant's row to read, mirroring verify.write.ts.
+      const scopedDb = createTenantDb(ctx.db.raw, tenantId, "system");
+      const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
+      const existing = await findUserMfaRow(scopedDb, scopedUser);
+      if (existing) return mfaAlreadyEnabled();
+
+      const secret = generateTotpSecret();
+      const recoveryCodes = generateRecoveryCodes();
+      const recoveryCodeHashes = await hashRecoveryCodes(recoveryCodes);
+
+      const { token: setupToken } = signMfaSetupToken(
+        {
+          userId,
+          totpSecretBase32: base32Encode(secret),
+          recoveryCodeHashes,
+          tenantId,
+        },
+        MFA_SETUP_TOKEN_TTL_MINUTES,
+        opts.setupTokenSecret,
+      );
+
+      return {
+        isSuccess: true,
+        data: {
+          setupToken,
+          otpauthUri: buildOtpauthUri({
+            issuer: opts.issuer,
+            accountLabel: event.payload.accountLabel,
+            secret,
+          }),
+          // Plaintext — this is the one and only time these are shown.
+          recoveryCodes,
+        },
+      };
+    },
+  });
+}

package/src/auth-mfa/mfa-setup-token.ts

@@ -16,6 +16,11 @@ export type MfaSetupPayload = {
   readonly userId: string;
   readonly totpSecretBase32: string;
   readonly recoveryCodeHashes: readonly string[];
+  // Set only by enable-start-preauth.write.ts — the session-authed
+  // enable-start.write.ts has no tenantId to carry (event.user.tenantId
+  // already covers that path). The pre-auth confirm handler has no session
+  // to fall back on, so this is the only source of which tenant to scope to.
+  readonly tenantId?: string;
 };
 
 type EncodedBody = MfaSetupPayload & { readonly expiresAtMs: number };
@@ -49,7 +54,8 @@ function isEncodedBody(value: unknown): value is EncodedBody {
     typeof v["totpSecretBase32"] === "string" &&
     Array.isArray(v["recoveryCodeHashes"]) &&
     v["recoveryCodeHashes"].every((h) => typeof h === "string") &&
-    typeof v["expiresAtMs"] === "number"
+    typeof v["expiresAtMs"] === "number" &&
+    (v["tenantId"] === undefined || typeof v["tenantId"] === "string")
   );
 }
 

package/src/auth-mfa/web/__tests__/mfa-client.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
-import { verifyMfaChallenge } from "../mfa-client";
+import { confirmMfaSetupPreauth, startMfaSetupPreauth, verifyMfaChallenge } from "../mfa-client";
 
 beforeEach(() => {
   globalThis.fetch = mock(
@@ -116,3 +116,146 @@ describe("verifyMfaChallenge", () => {
     expect(res).toEqual({ kind: "failure", error: { reason: "mfa_verify_failed" } });
   });
 });
+
+describe("startMfaSetupPreauth", () => {
+  test("posts preauthSetupToken + accountLabel to /api/auth/mfa/preauth-enable-start", async () => {
+    const fetchMock = mock(async () =>
+      jsonResponse({
+        isSuccess: true,
+        setupToken: "setup-1",
+        otpauthUri: "otpauth://totp/App:user@example.com?secret=ABCD&issuer=App",
+        recoveryCodes: ["r1", "r2"],
+      }),
+    );
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    await startMfaSetupPreauth("preauth-1", "user@example.com");
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/auth/mfa/preauth-enable-start",
+      expect.objectContaining({
+        method: "POST",
+        credentials: "same-origin",
+        body: JSON.stringify({ preauthSetupToken: "preauth-1", accountLabel: "user@example.com" }),
+      }),
+    );
+  });
+
+  test("success → kind:success mit setupToken/otpauthUri/recoveryCodes", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({
+        isSuccess: true,
+        setupToken: "setup-1",
+        otpauthUri: "otpauth://totp/App:user@example.com?secret=ABCD&issuer=App",
+        recoveryCodes: ["r1", "r2"],
+      }),
+    ) as unknown as typeof fetch;
+
+    const res = await startMfaSetupPreauth("preauth-1", "user@example.com");
+
+    expect(res).toEqual({
+      kind: "success",
+      data: {
+        setupToken: "setup-1",
+        otpauthUri: "otpauth://totp/App:user@example.com?secret=ABCD&issuer=App",
+        recoveryCodes: ["r1", "r2"],
+      },
+    });
+  });
+
+  test("HTTP 429 → kind:failure reason:rate_limited", async () => {
+    globalThis.fetch = mock(
+      async () => new Response(null, { status: 429 }),
+    ) as unknown as typeof fetch;
+
+    const res = await startMfaSetupPreauth("preauth-1", "user@example.com");
+
+    expect(res).toEqual({ kind: "failure", error: { reason: "rate_limited" } });
+  });
+
+  test("error als String → kind:failure reason:<string>", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({ isSuccess: false, error: "invalid_challenge_token" }),
+    ) as unknown as typeof fetch;
+
+    const res = await startMfaSetupPreauth("preauth-1", "user@example.com");
+
+    expect(res).toEqual({ kind: "failure", error: { reason: "invalid_challenge_token" } });
+  });
+
+  test("error-Objekt ohne details.reason → fällt auf error.code zurück", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({ isSuccess: false, error: { code: "mfa_already_enabled" } }),
+    ) as unknown as typeof fetch;
+
+    const res = await startMfaSetupPreauth("preauth-1", "user@example.com");
+
+    expect(res).toEqual({ kind: "failure", error: { reason: "mfa_already_enabled" } });
+  });
+});
+
+describe("confirmMfaSetupPreauth", () => {
+  test("posts setupToken + code to /api/auth/mfa/preauth-confirm", async () => {
+    const fetchMock = mock(async () =>
+      jsonResponse({ isSuccess: true, token: "t", user: { id: "u1", tenantId: "t1", roles: [] } }),
+    );
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    await confirmMfaSetupPreauth("setup-1", "123456");
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/auth/mfa/preauth-confirm",
+      expect.objectContaining({
+        method: "POST",
+        credentials: "same-origin",
+        body: JSON.stringify({ setupToken: "setup-1", code: "123456" }),
+      }),
+    );
+  });
+
+  test("success → kind:success mit token+user", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({
+        isSuccess: true,
+        token: "test-token",
+        user: { id: "u1", tenantId: "t1", roles: ["User"] },
+      }),
+    ) as unknown as typeof fetch;
+
+    const res = await confirmMfaSetupPreauth("setup-1", "123456");
+
+    expect(res).toEqual({
+      kind: "success",
+      data: { token: "test-token", user: { id: "u1", tenantId: "t1", roles: ["User"] } },
+    });
+  });
+
+  test("HTTP 429 → kind:failure reason:rate_limited", async () => {
+    globalThis.fetch = mock(
+      async () => new Response(null, { status: 429 }),
+    ) as unknown as typeof fetch;
+
+    const res = await confirmMfaSetupPreauth("setup-1", "000000");
+
+    expect(res).toEqual({ kind: "failure", error: { reason: "rate_limited" } });
+  });
+
+  test("error-Objekt mit details.reason → reason + retryAfterSeconds übernommen", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({
+        isSuccess: false,
+        error: {
+          code: "mfa_setup_confirm_failed",
+          details: { reason: "too_many_attempts", retryAfterSeconds: 30 },
+        },
+      }),
+    ) as unknown as typeof fetch;
+
+    const res = await confirmMfaSetupPreauth("setup-1", "000000");
+
+    expect(res).toEqual({
+      kind: "failure",
+      error: { reason: "too_many_attempts", retryAfterSeconds: 30 },
+    });
+  });
+});

package/src/auth-mfa/web/__tests__/mfa-setup-preauth-screen.test.tsx

@@ -0,0 +1,202 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { defaultTranslations } from "../i18n";
+
+mock.module("qrcode/lib/browser", () => ({
+  default: { toString: mock(async () => "<svg></svg>") },
+}));
+
+const { MfaSetupPreauthScreen } = await import("../mfa-setup-preauth-screen");
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <PrimitivesProvider value={defaultPrimitives}>
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "de" })}
+        fallbackBundles={[defaultTranslations]}
+      >
+        {children}
+      </LocaleProvider>
+    </PrimitivesProvider>
+  );
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status });
+}
+
+const startBody = {
+  isSuccess: true,
+  setupToken: "setup-token-1",
+  otpauthUri: "otpauth://totp/App:user@example.com?secret=ABCD1234&issuer=App",
+  recoveryCodes: ["code-1", "code-2"],
+};
+const confirmBody = {
+  isSuccess: true,
+  token: "t",
+  user: { id: "u1", tenantId: "t1", roles: [] },
+};
+
+beforeEach(() => {
+  globalThis.fetch = mock(async (input: RequestInfo | URL) => {
+    const url = String(input);
+    if (url.includes("preauth-enable-start")) return jsonResponse(startBody);
+    if (url.includes("preauth-confirm")) return jsonResponse(confirmBody);
+    return jsonResponse({ isSuccess: false, error: "unexpected_url" }, 500);
+  }) as unknown as typeof fetch;
+});
+
+describe("MfaSetupPreauthScreen", () => {
+  test("rendert Titel + Start-Button, kein Setup-Bereich vor dem Start", () => {
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+    expect(screen.getByText("Zwei-Faktor-Authentifizierung erforderlich")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Einrichtung starten" })).toBeTruthy();
+    expect(screen.queryByLabelText(/^Code aus der Authenticator-App/)).toBeNull();
+  });
+
+  test("Start-Klick → postet preauthSetupToken+accountLabel, danach QR + Recovery-Codes", async () => {
+    const fetchMock = mock(async () => jsonResponse(startBody));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung starten" }));
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith(
+        "/api/auth/mfa/preauth-enable-start",
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({
+            preauthSetupToken: "preauth-1",
+            accountLabel: "user@example.com",
+          }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByText("ABCD1234")).toBeTruthy();
+    });
+    expect(screen.getByText(/code-1/)).toBeTruthy();
+    expect(screen.getByText(/code-2/)).toBeTruthy();
+  });
+
+  test("Bestätigen-Button bleibt disabled bis Recovery-Codes bestätigt + 6-stelliger Code eingegeben", async () => {
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung starten" }));
+    await waitFor(() => {
+      expect(screen.getByText("ABCD1234")).toBeTruthy();
+    });
+
+    const confirm = screen.getByRole("button", {
+      name: "Einrichtung abschließen",
+    }) as HTMLButtonElement;
+    expect(confirm.disabled).toBe(true);
+
+    fireEvent.click(screen.getByLabelText("Ich habe die Recovery-Codes gespeichert."));
+    expect(confirm.disabled).toBe(true);
+
+    fireEvent.change(screen.getByLabelText(/^Code aus der Authenticator-App/), {
+      target: { value: "123456" },
+    });
+    expect(confirm.disabled).toBe(false);
+  });
+
+  test("Bestätigen → postet setupToken+code, danach onSuccess", async () => {
+    const onSuccess = mock(() => {});
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen
+          preauthSetupToken="preauth-1"
+          accountLabel="user@example.com"
+          onSuccess={onSuccess}
+        />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung starten" }));
+    await waitFor(() => {
+      expect(screen.getByText("ABCD1234")).toBeTruthy();
+    });
+    fireEvent.click(screen.getByLabelText("Ich habe die Recovery-Codes gespeichert."));
+    fireEvent.change(screen.getByLabelText(/^Code aus der Authenticator-App/), {
+      target: { value: "123456" },
+    });
+
+    const fetchMock = globalThis.fetch as unknown as ReturnType<typeof mock>;
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung abschließen" }));
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith(
+        "/api/auth/mfa/preauth-confirm",
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({ setupToken: "setup-token-1", code: "123456" }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(onSuccess).toHaveBeenCalled();
+    });
+  });
+
+  test("enable-start schlägt fehl → übersetztes Fehler-Banner, kein Setup-Bereich", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({ isSuccess: false, error: "mfa_already_enabled" }),
+    ) as unknown as typeof fetch;
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung starten" }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Zwei-Faktor-Authentifizierung ist bereits aktiv.")).toBeTruthy();
+    });
+    expect(screen.queryByText("ABCD1234")).toBeNull();
+  });
+
+  test("onCancel gesetzt → 'Zurück zum Login'-Button vorhanden, klick ruft onCancel", () => {
+    const onCancel = mock(() => {});
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen
+          preauthSetupToken="preauth-1"
+          accountLabel="user@example.com"
+          onCancel={onCancel}
+        />
+      </Wrapper>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Zurück zum Login" }));
+    expect(onCancel).toHaveBeenCalled();
+  });
+
+  test("ohne onCancel → kein 'Zurück zum Login'-Button", () => {
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+    expect(screen.queryByRole("button", { name: "Zurück zum Login" })).toBeNull();
+  });
+});

package/src/auth-mfa/web/i18n.ts

@@ -40,6 +40,13 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.enable.cancel": "Abbrechen",
     "auth.mfa.enable.confirm": "Aktivieren",
     "auth.mfa.enable.success": "Zwei-Faktor-Authentifizierung ist jetzt aktiv.",
+    "auth.mfa.setup.title": "Zwei-Faktor-Authentifizierung erforderlich",
+    "auth.mfa.setup.subtitle":
+      "Dein Konto verlangt Zwei-Faktor-Authentifizierung. Richte sie jetzt ein, um dich anzumelden.",
+    "auth.mfa.setup.intro":
+      "Scanne den QR-Code mit einer Authenticator-App (z.B. Google Authenticator, 1Password).",
+    "auth.mfa.setup.start": "Einrichtung starten",
+    "auth.mfa.setup.confirm": "Einrichtung abschließen",
     "auth.mfa.disable.title": "Zwei-Faktor-Authentifizierung deaktivieren",
     "auth.mfa.disable.description":
       "Bestätige mit einem Code aus deiner Authenticator-App oder einem Recovery-Code. Dein Konto ist danach nur noch durch dein Passwort geschützt.",
@@ -93,6 +100,13 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.enable.cancel": "Cancel",
     "auth.mfa.enable.confirm": "Enable",
     "auth.mfa.enable.success": "Two-factor authentication is now enabled.",
+    "auth.mfa.setup.title": "Two-factor authentication required",
+    "auth.mfa.setup.subtitle":
+      "Your account requires two-factor authentication. Set it up now to sign in.",
+    "auth.mfa.setup.intro":
+      "Scan the QR code with an authenticator app (e.g. Google Authenticator, 1Password).",
+    "auth.mfa.setup.start": "Start setup",
+    "auth.mfa.setup.confirm": "Complete setup",
     "auth.mfa.disable.title": "Disable two-factor authentication",
     "auth.mfa.disable.description":
       "Confirm with a code from your authenticator app or a recovery code. Your account will then be protected by your password alone.",

package/src/auth-mfa/web/index.ts

@@ -7,8 +7,12 @@
 export type { AuthMfaClientFeature, AuthMfaClientOptions } from "./client-plugin";
 export { authMfaClient } from "./client-plugin";
 export { defaultTranslations, mergeTranslations } from "./i18n";
-export type { MfaVerifyResult } from "./mfa-client";
-export { verifyMfaChallenge } from "./mfa-client";
+export type {
+  MfaSetupPreauthStart,
+  MfaSetupPreauthStartResult,
+  MfaVerifyResult,
+} from "./mfa-client";
+export { confirmMfaSetupPreauth, startMfaSetupPreauth, verifyMfaChallenge } from "./mfa-client";
 export type { MfaDisableDialogProps } from "./mfa-disable-dialog";
 export { MfaDisableDialog } from "./mfa-disable-dialog";
 export type { MfaEnableScreenProps } from "./mfa-enable-screen";
@@ -17,5 +21,7 @@ export type { MfaRecoveryCodesRevealProps } from "./mfa-recovery-codes-reveal";
 export { MfaRecoveryCodesReveal } from "./mfa-recovery-codes-reveal";
 export type { MfaRegenerateRecoveryDialogProps } from "./mfa-regenerate-recovery-dialog";
 export { MfaRegenerateRecoveryDialog } from "./mfa-regenerate-recovery-dialog";
+export type { MfaSetupPreauthScreenProps } from "./mfa-setup-preauth-screen";
+export { MfaSetupPreauthScreen } from "./mfa-setup-preauth-screen";
 export type { MfaVerifyScreenProps } from "./mfa-verify-screen";
 export { MfaVerifyScreen } from "./mfa-verify-screen";

package/src/auth-mfa/web/mfa-client.ts

@@ -58,3 +58,116 @@ export async function verifyMfaChallenge(
     },
   };
 }
+
+export type MfaSetupPreauthStart = {
+  readonly setupToken: string;
+  readonly otpauthUri: string;
+  readonly recoveryCodes: readonly string[];
+};
+
+export type MfaSetupPreauthStartResult =
+  | { readonly kind: "success"; readonly data: MfaSetupPreauthStart }
+  | { readonly kind: "failure"; readonly error: LoginFailure };
+
+// Browser-Seite von POST /api/auth/mfa/preauth-enable-start — lets a user
+// blocked at login by MFA enforcement generate a TOTP secret/QR without a
+// session, using the preauthSetupToken login()'s mfa-setup-required result
+// carries. No JWT/cookie here (see auth-routes.ts's route comment) — the
+// response's setupToken is consumed by confirmMfaSetupPreauth below.
+export async function startMfaSetupPreauth(
+  preauthSetupToken: string,
+  accountLabel: string,
+): Promise<MfaSetupPreauthStartResult> {
+  const res = await fetch("/api/auth/mfa/preauth-enable-start", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ preauthSetupToken, accountLabel }),
+  });
+  if (res.status === 429) {
+    return { kind: "failure", error: { reason: "rate_limited" } };
+  }
+  // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
+  const body = (await res.json().catch(() => ({}))) as {
+    isSuccess?: boolean;
+    setupToken?: string;
+    otpauthUri?: string;
+    recoveryCodes?: readonly string[];
+    error?: { code?: string; message?: string; details?: { reason?: string } } | string;
+  };
+  if (
+    body.isSuccess === true &&
+    body.setupToken !== undefined &&
+    body.otpauthUri !== undefined &&
+    body.recoveryCodes !== undefined
+  ) {
+    return {
+      kind: "success",
+      data: {
+        setupToken: body.setupToken,
+        otpauthUri: body.otpauthUri,
+        recoveryCodes: body.recoveryCodes,
+      },
+    };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "setup_failed";
+  return {
+    kind: "failure",
+    error: { reason, ...(err?.message !== undefined && { message: err.message }) },
+  };
+}
+
+// Browser-Seite von POST /api/auth/mfa/preauth-confirm — completes both
+// the enrollment startMfaSetupPreauth began and the login mfa-setup-
+// required block. Response shape mirrors /auth/mfa/verify's (mints via
+// the same mintSessionAndRespond()), same as verifyMfaChallenge above —
+// kept as its own function rather than a shared helper so this file's
+// two already-tested request shapes stay independently editable.
+export async function confirmMfaSetupPreauth(
+  setupToken: string,
+  code: string,
+): Promise<MfaVerifyResult> {
+  const res = await fetch("/api/auth/mfa/preauth-confirm", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ setupToken, code }),
+  });
+  if (res.status === 429) {
+    return { kind: "failure", error: { reason: "rate_limited" } };
+  }
+  // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
+  const body = (await res.json().catch(() => ({}))) as {
+    isSuccess?: boolean;
+    token?: string;
+    user?: LoginResponse["user"];
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
+  };
+  if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
+    return { kind: "success", data: { token: body.token, user: body.user } };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "mfa_setup_confirm_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    kind: "failure",
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}