@cosmicdrift/kumiko-bundled-features 0.160.0 → 0.162.0

package/src/auth-mfa/constants.ts

@@ -9,7 +9,9 @@ export const AUTH_MFA_FEATURE = "auth-mfa" as const;
 
 export const AuthMfaHandlers = {
   enableStart: "auth-mfa:write:enable-start",
+  enableStartPreauth: "auth-mfa:write:enable-start-preauth",
   enableConfirm: "auth-mfa:write:enable-confirm",
+  enableConfirmPreauth: "auth-mfa:write:enable-confirm-preauth",
   disable: "auth-mfa:write:disable",
   regenerateRecovery: "auth-mfa:write:regenerate-recovery",
   verify: "auth-mfa:write:verify",
@@ -34,6 +36,7 @@ export const AuthMfaErrorCodes = {
 
 export const MFA_SETUP_TOKEN_TTL_MINUTES = 10;
 export const MFA_CHALLENGE_TOKEN_TTL_MINUTES = 10;
+export const MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES = 10;
 export const MFA_VERIFY_MAX_ATTEMPTS = 5;
 export const MFA_VERIFY_LOCKOUT_MINUTES = 5;
 

package/src/auth-mfa/feature.ts

@@ -3,7 +3,9 @@ import { mfaRequiredConfigKey } from "./config";
 import { MFA_ENABLE_SCREEN_ID } from "./constants";
 import { createDisableHandler } from "./handlers/disable.write";
 import { createEnableConfirmHandler } from "./handlers/enable-confirm.write";
+import { createEnableConfirmPreauthHandler } from "./handlers/enable-confirm-preauth.write";
 import { createEnableStartHandler } from "./handlers/enable-start.write";
+import { createEnableStartPreauthHandler } from "./handlers/enable-start-preauth.write";
 import { mfaReencryptJob } from "./handlers/reencrypt.job";
 import { createRegenerateRecoveryHandler } from "./handlers/regenerate-recovery.write";
 import { mfaStatusQuery } from "./handlers/status.query";
@@ -119,12 +121,25 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
       enableStart: r.writeHandler(
         createEnableStartHandler({ setupTokenSecret: opts.setupTokenSecret, issuer: opts.issuer }),
       ),
+      enableStartPreauth: r.writeHandler(
+        createEnableStartPreauthHandler({
+          challengeTokenSecret: opts.challengeTokenSecret,
+          setupTokenSecret: opts.setupTokenSecret,
+          issuer: opts.issuer,
+        }),
+      ),
       enableConfirm: r.writeHandler(
         createEnableConfirmHandler({
           setupTokenSecret: opts.setupTokenSecret,
           revokeAllOtherSessions: sharedRevoker,
         }),
       ),
+      enableConfirmPreauth: r.writeHandler(
+        createEnableConfirmPreauthHandler({
+          setupTokenSecret: opts.setupTokenSecret,
+          revokeAllOtherSessions: sharedRevoker,
+        }),
+      ),
       disable: r.writeHandler(createDisableHandler({ revokeAllOtherSessions: sharedRevoker })),
       regenerateRecovery: r.writeHandler(
         createRegenerateRecoveryHandler({ revokeAllOtherSessions: sharedRevoker }),

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

@@ -0,0 +1,170 @@
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildSessionRoles,
+  createSystemUser,
+  defineWriteHandler,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { burnToken } from "../../shared";
+import { USER_STATUS, UserQueries } from "../../user";
+import { base32Decode } from "../base32";
+import { MFA_VERIFY_LOCKOUT_MINUTES, MFA_VERIFY_MAX_ATTEMPTS } from "../constants";
+import { findUserMfaRow } from "../db/queries";
+import { invalidSetupToken, invalidTotpCode, mfaAlreadyEnabled, tooManyAttempts } from "../errors";
+import { verifyMfaSetupToken } from "../mfa-setup-token";
+import {
+  clearMfaVerifyAttempts,
+  getMfaVerifyLockoutState,
+  recordFailedMfaVerifyAttempt,
+} from "../mfa-verify-attempts";
+import { encodeRecoveryCodes, userMfaEntity, userMfaTable } from "../schema/user-mfa";
+import { verifyTotp } from "../totp";
+
+export type EnableConfirmPreauthOptions = {
+  // Must match the secret enable-start-preauth.write.ts signs setupTokens
+  // with — same secret + format as the session-authed enable-confirm.
+  readonly setupTokenSecret: string;
+  readonly maxAttempts?: number;
+  readonly lockoutMinutes?: number;
+  // Wired late by run-prod-app, same shared callback as enable-confirm and
+  // enable-start's session-authed siblings.
+  readonly revokeAllOtherSessions?: (
+    userId: string,
+    currentSid: string | undefined,
+  ) => Promise<number>;
+};
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// Pre-auth twin of enable-confirm.write.ts: identity comes from the
+// verified setupToken (minted by enable-start-preauth.write.ts), not from
+// event.user — there is no session yet. Combines enable-confirm's
+// enrollment-completion logic with verify.write.ts's session-derivation
+// (membership lookup, status re-check, buildSessionRoles) since this IS
+// the completion of the blocked login, not just an enrollment step — a
+// successful call here logs the user in.
+export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOptions) {
+  const maxAttempts = opts.maxAttempts ?? MFA_VERIFY_MAX_ATTEMPTS;
+  const lockoutMinutes = opts.lockoutMinutes ?? MFA_VERIFY_LOCKOUT_MINUTES;
+
+  return defineWriteHandler({
+    name: "enable-confirm-preauth",
+    schema: z.object({
+      setupToken: z.string().min(1),
+      code: z.string().length(6),
+    }),
+    access: { roles: ["all"] },
+    handler: async (event, ctx) => {
+      const verify = verifyMfaSetupToken(event.payload.setupToken, opts.setupTokenSecret);
+      if (!verify.ok) return invalidSetupToken();
+      // A setupToken minted for the session-authed enable-start never
+      // carries tenantId (see mfa-setup-token.ts) — reject it here rather
+      // than falling back to a guest tenant, that token was never meant to
+      // reach this pre-auth endpoint.
+      const { userId, tenantId } = verify.payload;
+      if (tenantId === undefined) return invalidSetupToken();
+
+      // Same guessing surface as /auth/mfa/verify (a short TOTP code) and
+      // the same per-userId cap — deliberately shared counter, see
+      // mfa-verify-attempts.ts.
+      if (ctx.redis) {
+        const state = await getMfaVerifyLockoutState(ctx.redis, userId);
+        if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
+          const now = Date.now();
+          if (state.lockedUntil > now) {
+            const retryAfterSeconds = Math.max(1, Math.ceil((state.lockedUntil - now) / 1000));
+            return tooManyAttempts(retryAfterSeconds);
+          }
+        }
+      }
+
+      const secret = base32Decode(verify.payload.totpSecretBase32);
+      if (verifyTotp(secret, event.payload.code) === false) {
+        if (ctx.redis) {
+          await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
+        }
+        return invalidTotpCode();
+      }
+
+      // Burn the setup token on the first successful confirm — same
+      // single-use guarantee as enable-confirm.write.ts.
+      if (ctx.redis) {
+        const burnResult = await burnToken(ctx.redis, "mfa-setup", userId, verify.expiresAtMs);
+        if (burnResult === "already-used") return invalidSetupToken();
+      }
+
+      // "system" mode: no session exists yet, tenantId comes from the
+      // verified token, mirroring enable-start-preauth.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 result = await executor.create(
+        {
+          userId,
+          totpSecret: verify.payload.totpSecretBase32,
+          recoveryCodes: encodeRecoveryCodes(verify.payload.recoveryCodeHashes),
+          enabledAt: Temporal.Now.instant(),
+          lastUsedAt: null,
+        },
+        scopedUser,
+        scopedDb,
+      );
+      if (!result.isSuccess) return result;
+
+      if (ctx.redis) {
+        await clearMfaVerifyAttempts(ctx.redis, userId);
+      }
+
+      // No currentSid to exclude — this is the first session for this
+      // login, not a follow-up on an already-running one.
+      if (opts.revokeAllOtherSessions) {
+        await opts.revokeAllOtherSessions(userId, undefined);
+      }
+
+      // Re-derive the full session the way verify.write.ts does — the
+      // setupToken only proves "password + new TOTP secret", not roles;
+      // roles come from a fresh membership lookup, same as every other
+      // login-completing handler.
+      const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
+      const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+        id: userId,
+      })) as { roles?: string | null; status?: string } | null; // @cast-boundary engine-payload
+
+      if (!userRow) return invalidSetupToken();
+      if (
+        userRow?.status === USER_STATUS.Restricted ||
+        userRow?.status === USER_STATUS.DeletionRequested ||
+        userRow?.status === USER_STATUS.Deleted
+      ) {
+        return invalidSetupToken();
+      }
+
+      const globalRoles = parseRoles(userRow?.roles ?? null);
+
+      const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
+        userId,
+      })) as ReadonlyArray<{ tenantId: string; roles: readonly string[] }>; // @cast-boundary engine-payload
+      const membership = memberships.find((m) => m.tenantId === tenantId);
+      if (!membership) return invalidSetupToken();
+      // buildSessionRoles calls stripForbiddenMembershipRoles to strip reserved
+      // roles from the membership portion (globalRoles keeps SystemAdmin) —
+      // read-time backstop against a rebuild-resurrected role, same as
+      // verify.write.ts.
+      const mergedRoles = buildSessionRoles(globalRoles, membership.roles);
+
+      const baseSession: SessionUser = { id: userId, tenantId, roles: mergedRoles };
+      const claims = await ctx.resolveAuthClaims(baseSession);
+      const session: SessionUser =
+        Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
+
+      return { isSuccess: true, data: { kind: "mfa-preauth-confirm-success", session } };
+    },
+  });
+}

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-preauth-setup-token.ts

@@ -0,0 +1,86 @@
+// HMAC-signed token minted by login.write.ts when enforcement policy blocks
+// an unenrolled user (mfa-setup-required) — proves the password check
+// already succeeded, so a later pre-auth enable-start variant (#1231) can
+// let the user enroll without a full session. No secret material (unlike
+// mfa-setup-token.ts) — just enough to look the user back up.
+//
+// Same domain-separated HMAC shape as mfa-challenge-token.ts, distinct
+// signing string so this can never be replayed as a login challenge or
+// vice versa. Reuses challengeTokenSecret rather than adding a third
+// feature secret: both tokens assert the identical trust boundary
+// ("password already verified, short-lived follow-up allowed").
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+
+export type MfaPreauthSetupPayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+};
+
+type EncodedBody = MfaPreauthSetupPayload & { readonly expiresAtMs: number };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export function signMfaPreauthSetupToken(
+  payload: MfaPreauthSetupPayload,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): { token: string; expiresAt: Temporal.Instant } {
+  const expiresAt = now.add({ minutes: ttlMinutes });
+  const body: EncodedBody = { ...payload, expiresAtMs: expiresAt.epochMilliseconds };
+  const bodyB64 = Buffer.from(JSON.stringify(body)).toString("base64url");
+  const signature = sign(`mfa-preauth-setup:${bodyB64}`, secret);
+  return { token: `${bodyB64}.${signature}`, expiresAt };
+}
+
+export type VerifyMfaPreauthSetupResult =
+  | { readonly ok: true; readonly payload: MfaPreauthSetupPayload; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+function isEncodedBody(value: unknown): value is EncodedBody {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["userId"] === "string" &&
+    typeof v["tenantId"] === "string" &&
+    typeof v["expiresAtMs"] === "number"
+  );
+}
+
+export function verifyMfaPreauthSetupToken(
+  token: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyMfaPreauthSetupResult {
+  const parts = token.split(".");
+  if (parts.length !== 2) return { ok: false, reason: "malformed" };
+  const [bodyB64, providedSig] = parts;
+  if (!bodyB64 || !providedSig) return { ok: false, reason: "malformed" };
+
+  const expected = sign(`mfa-preauth-setup:${bodyB64}`, secret);
+  const expectedBuf = Buffer.from(expected, "base64url");
+  const providedBuf = Buffer.from(providedSig, "base64url");
+  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
+  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(bodyB64, "base64url").toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (!isEncodedBody(parsed)) return { ok: false, reason: "malformed" };
+
+  if (
+    Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(parsed.expiresAtMs)) > 0
+  ) {
+    return { ok: false, reason: "expired" };
+  }
+
+  const { expiresAtMs, ...payload } = parsed;
+  return { ok: true, payload, expiresAtMs };
+}

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/mfa-status-checker.ts

@@ -6,9 +6,10 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { type MfaRequiredPolicy, mfaRequiredConfigHandle, mfaRequiredConfigKey } from "./config";
-import { MFA_CHALLENGE_TOKEN_TTL_MINUTES } from "./constants";
+import { MFA_CHALLENGE_TOKEN_TTL_MINUTES, MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES } from "./constants";
 import { findUserMfaRow } from "./db/queries";
 import { signMfaChallengeToken } from "./mfa-challenge-token";
+import { signMfaPreauthSetupToken } from "./mfa-preauth-setup-token";
 
 export type MfaStatusCheckResult =
   | { readonly required: false }
@@ -17,7 +18,7 @@ export type MfaStatusCheckResult =
   // yet. Distinct from `required: true` (which means "enrolled, prove it
   // now") — see config.ts's ponytail note on why this hard-blocks login
   // with no in-band recovery until PR3's enrollment-during-login UI ships.
-  | { readonly setupRequired: true };
+  | { readonly setupRequired: true; readonly preauthSetupToken: string };
 
 // Consumed by auth-email-password's login.write.ts via `mfaStatusChecker`
 // (a generic callback type declared THERE, not here — auth-email-password
@@ -67,9 +68,17 @@ export function createMfaStatusChecker(opts: {
       scopedDb,
     )) ?? "optional") as MfaRequiredPolicy | "optional";
     if (policy === "optional") return { required: false };
-    if (policy === "all") return { setupRequired: true };
+    const buildSetupToken = (): string =>
+      signMfaPreauthSetupToken(
+        { userId, tenantId },
+        MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES,
+        opts.challengeTokenSecret,
+      ).token;
+    if (policy === "all") return { setupRequired: true, preauthSetupToken: buildSetupToken() };
     // policy === "admins"
     const isAdmin = roles.some((role) => access.admin.includes(role));
-    return isAdmin ? { setupRequired: true } : { required: false };
+    return isAdmin
+      ? { setupRequired: true, preauthSetupToken: buildSetupToken() }
+      : { required: false };
   };
 }

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 },
+    });
+  });
+});