@cosmicdrift/kumiko-bundled-features 0.161.0 → 0.162.0

package/src/auth-mfa/__tests__/enable-confirm-preauth.integration.test.ts

@@ -0,0 +1,253 @@
+// #1456: completes both the enrollment #1465 started AND the login that
+// mfa-setup-required blocked. Real HTTP through setupTestStack, exercising
+// the full chain: login → preauthSetupToken → preauth-enable-start →
+// preauth-confirm → the minted JWT actually authenticates a follow-up
+// request. That end-to-end seam is the thing a mocked test would fake.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  AuthErrors as AuthEmailPasswordErrors,
+  AuthHandlers as AuthEmailPasswordHandlers,
+  createAuthEmailPasswordFeature,
+} from "../../auth-email-password";
+import { ConfigHandlers, createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { hashPassword } from "../../shared";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenantMembership } from "../../tenant/testing";
+import { UserHandlers } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { base32Decode } from "../base32";
+import { mfaRequiredConfigHandle } from "../config";
+import { AuthMfaHandlers } from "../constants";
+import { createAuthMfaFeature, mfaStatusCheckerFromFeature } from "../feature";
+import { userMfaEntity } from "../schema/user-mfa";
+import { currentTotpCode } from "../totp";
+
+let stack: TestStack;
+
+const CHALLENGE_TOKEN_SECRET = "integration-test-challenge-token-secret-not-real-0001";
+const SETUP_TOKEN_SECRET = "integration-test-setup-token-secret-not-real-0002";
+const TENANT_ID: TenantId = testTenantId(420);
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  configureEntityFieldEncryption(encryption);
+  const resolver = createConfigResolver({ cipher: encryption });
+  const authMfaFeature = createAuthMfaFeature({
+    setupTokenSecret: SETUP_TOKEN_SECRET,
+    issuer: "Kumiko Test",
+    challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      authMfaFeature,
+      createAuthEmailPasswordFeature({
+        mfaStatusChecker: mfaStatusCheckerFromFeature(authMfaFeature),
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthEmailPasswordHandlers.login,
+      loginErrorStatusMap: {
+        [AuthEmailPasswordErrors.invalidCredentials]: 401,
+        [AuthEmailPasswordErrors.noMembership]: 403,
+      },
+      mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+      mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+});
+
+async function loginBlockedByEnforcement(
+  email = "unenrolled@example.com",
+): Promise<{ preauthSetupToken: string; userId: string }> {
+  const password = "correct-horse-battery-2026";
+  const hash = await hashPassword(password);
+  const created = await stack.http.writeOk<{ id: string }>(
+    UserHandlers.create,
+    { email, passwordHash: hash, displayName: "Unenrolled" },
+    createTestUser({ id: 421, tenantId: TENANT_ID, roles: ["SystemAdmin"] }),
+  );
+  await seedTenantMembership(stack.db, {
+    userId: created.id,
+    tenantId: TENANT_ID,
+    roles: ["User"],
+  });
+  await stack.http.writeOk(
+    ConfigHandlers.set,
+    { key: mfaRequiredConfigHandle.name, value: "all" },
+    createTestUser({ id: 422, tenantId: TENANT_ID, roles: ["Admin"] }),
+  );
+
+  const loginRes = await stack.http.raw("POST", "/api/auth/login", { email, password });
+  const loginBody = await loginRes.json();
+  return { preauthSetupToken: loginBody.preauthSetupToken as string, userId: created.id };
+}
+
+async function startEnrollment(
+  preauthSetupToken: string,
+  accountLabel: string,
+): Promise<{ setupToken: string; secret: Buffer }> {
+  const startRes = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+    preauthSetupToken,
+    accountLabel,
+  });
+  const startBody = await startRes.json();
+  const secretParam = new URLSearchParams(startBody.otpauthUri.split("?")[1]).get("secret") ?? "";
+  return { setupToken: startBody.setupToken as string, secret: base32Decode(secretParam) };
+}
+
+describe("POST /auth/mfa/preauth-confirm", () => {
+  test("completes enrollment + login: full chain, minted JWT authenticates a follow-up request", async () => {
+    const email = "chain@example.com";
+    const { preauthSetupToken } = await loginBlockedByEnforcement(email);
+    const { setupToken, secret } = await startEnrollment(preauthSetupToken, email);
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code: currentTotpCode(secret),
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.user.tenantId).toBe(TENANT_ID);
+
+    // The proof that matters: the minted JWT actually authenticates.
+    const meRes = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "user:query:user:me", payload: {} },
+      { Authorization: `Bearer ${body.token}` },
+    );
+    expect(meRes.status).toBe(200);
+  });
+
+  test("wrong TOTP code → invalid_totp_code, no enrollment persisted", async () => {
+    const email = "wrongcode@example.com";
+    const { preauthSetupToken } = await loginBlockedByEnforcement(email);
+    const { setupToken } = await startEnrollment(preauthSetupToken, email);
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code: "000000",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.details.reason).toBe("invalid_totp_code");
+    expect(body.token).toBeUndefined();
+  });
+
+  test("replaying the same setupToken after a successful confirm → invalid_setup_token (burned), not a second enrollment", async () => {
+    const email = "race@example.com";
+    const { preauthSetupToken } = await loginBlockedByEnforcement(email);
+    const { setupToken, secret } = await startEnrollment(preauthSetupToken, email);
+    const code = currentTotpCode(secret);
+
+    const first = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code,
+    });
+    expect(first.status).toBe(200);
+
+    // Same setupToken again — this integration stack wires real Redis, so
+    // the single-use burn from the first call rejects the replay before it
+    // ever reaches the already-enrolled DB check.
+    const second = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code,
+    });
+    expect(second.status).not.toBe(200);
+    const secondBody = await second.json();
+    expect(secondBody.error.details.reason).toBe("invalid_setup_token");
+  });
+
+  test("a session-issued setupToken (no tenantId) is rejected, not silently accepted", async () => {
+    const email = "sessionissued@example.com";
+    const password = "correct-horse-battery-2026";
+    const hash = await hashPassword(password);
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      { email, passwordHash: hash, displayName: "Session Issued" },
+      createTestUser({ id: 423, tenantId: TENANT_ID, roles: ["SystemAdmin"] }),
+    );
+    await seedTenantMembership(stack.db, {
+      userId: created.id,
+      tenantId: TENANT_ID,
+      roles: ["User"],
+    });
+    const sessionUser = createTestUser({ id: created.id, tenantId: TENANT_ID, roles: ["User"] });
+
+    // The session-authed enable-start signs a setupToken with the SAME
+    // secret + format, but never carries tenantId (see mfa-setup-token.ts).
+    // A malicious or confused client resubmitting it to the pre-auth
+    // endpoint must not be able to piggyback on tenantId inference.
+    const start = await stack.http.writeOk<{ setupToken: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: email },
+      sessionUser,
+    );
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken: start.setupToken,
+      code: "123456",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.details.reason).toBe("invalid_setup_token");
+  });
+
+  test("expired/garbage setupToken → invalid_setup_token, no session minted", async () => {
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken: "not-a-real-token",
+      code: "123456",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.token).toBeUndefined();
+  });
+});

package/src/auth-mfa/__tests__/enable-start-preauth.integration.test.ts

@@ -0,0 +1,214 @@
+// #1465: a user blocked at login by MFA enforcement (mfa-setup-required,
+// see #1455) can generate a TOTP secret + QR without a session, using the
+// preauthSetupToken login.write.ts issued. Real HTTP through
+// setupTestStack, exercising the full chain: login → preauthSetupToken →
+// POST /auth/mfa/preauth-enable-start → a setupToken that #1456's
+// (not-yet-built) confirm step will consume via verifyMfaSetupToken.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  AuthErrors as AuthEmailPasswordErrors,
+  AuthHandlers as AuthEmailPasswordHandlers,
+  createAuthEmailPasswordFeature,
+} from "../../auth-email-password";
+import { ConfigHandlers, createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { hashPassword } from "../../shared";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenantMembership } from "../../tenant/testing";
+import { UserHandlers } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { base32Decode } from "../base32";
+import { mfaRequiredConfigHandle } from "../config";
+import { AuthMfaHandlers } from "../constants";
+import { createAuthMfaFeature, mfaStatusCheckerFromFeature } from "../feature";
+import { signMfaPreauthSetupToken } from "../mfa-preauth-setup-token";
+import { verifyMfaSetupToken } from "../mfa-setup-token";
+import { userMfaEntity } from "../schema/user-mfa";
+import { currentTotpCode } from "../totp";
+
+let stack: TestStack;
+
+const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
+const SETUP_TOKEN_SECRET = "test-mfa-setup-token-secret-at-least-32-bytes!!";
+const TENANT_ID: TenantId = testTenantId(410);
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  configureEntityFieldEncryption(encryption);
+  const resolver = createConfigResolver({ cipher: encryption });
+  const authMfaFeature = createAuthMfaFeature({
+    setupTokenSecret: SETUP_TOKEN_SECRET,
+    issuer: "Kumiko Test",
+    challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      authMfaFeature,
+      createAuthEmailPasswordFeature({
+        mfaStatusChecker: mfaStatusCheckerFromFeature(authMfaFeature),
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthEmailPasswordHandlers.login,
+      loginErrorStatusMap: {
+        [AuthEmailPasswordErrors.invalidCredentials]: 401,
+        [AuthEmailPasswordErrors.noMembership]: 403,
+      },
+      mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+});
+
+async function loginBlockedByEnforcement(): Promise<{
+  preauthSetupToken: string;
+  userId: string;
+}> {
+  const password = "correct-horse-battery-2026";
+  const hash = await hashPassword(password);
+  const created = await stack.http.writeOk<{ id: string }>(
+    UserHandlers.create,
+    { email: "unenrolled@example.com", passwordHash: hash, displayName: "Unenrolled" },
+    createTestUser({ id: 411, tenantId: TENANT_ID, roles: ["SystemAdmin"] }),
+  );
+  await seedTenantMembership(stack.db, {
+    userId: created.id,
+    tenantId: TENANT_ID,
+    roles: ["User"],
+  });
+  await stack.http.writeOk(
+    ConfigHandlers.set,
+    { key: mfaRequiredConfigHandle.name, value: "all" },
+    createTestUser({ id: 412, tenantId: TENANT_ID, roles: ["Admin"] }),
+  );
+
+  const loginRes = await stack.http.raw("POST", "/api/auth/login", {
+    email: "unenrolled@example.com",
+    password,
+  });
+  const loginBody = await loginRes.json();
+  return { preauthSetupToken: loginBody.preauthSetupToken as string, userId: created.id };
+}
+
+describe("POST /auth/mfa/preauth-enable-start", () => {
+  test("generates a TOTP secret + QR from a valid preauthSetupToken, no session minted", async () => {
+    const { preauthSetupToken } = await loginBlockedByEnforcement();
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+      preauthSetupToken,
+      accountLabel: "unenrolled@example.com",
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+    expect(body.token).toBeUndefined();
+    expect(typeof body.setupToken).toBe("string");
+    expect(typeof body.otpauthUri).toBe("string");
+    expect(body.otpauthUri).toContain("otpauth://totp/");
+    expect(Array.isArray(body.recoveryCodes)).toBe(true);
+    expect(body.recoveryCodes).toHaveLength(8);
+
+    // The returned setupToken must compose with the EXISTING enable-confirm
+    // verification path (verifyMfaSetupToken) — proves #1465 and #1456
+    // actually chain together, not just that each returns *a* string.
+    const verified = verifyMfaSetupToken(body.setupToken, SETUP_TOKEN_SECRET);
+    expect(verified.ok).toBe(true);
+    if (verified.ok) {
+      expect(typeof verified.payload.totpSecretBase32).toBe("string");
+      expect(verified.payload.recoveryCodeHashes).toHaveLength(8);
+    }
+  });
+
+  test("expired/garbage preauthSetupToken → invalid_challenge_token, no secret leaked", async () => {
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+      preauthSetupToken: "not-a-real-token",
+      accountLabel: "unenrolled@example.com",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.setupToken).toBeUndefined();
+  });
+
+  test("already-enrolled user gets mfa_already_enabled, not a fresh secret", async () => {
+    const { userId } = await loginBlockedByEnforcement();
+    const sessionUser = createTestUser({ id: userId, tenantId: TENANT_ID, roles: ["User"] });
+
+    // Really enrolls — via the existing session-authed enable-start/confirm
+    // pair, not a synthetic DB insert — so this test breaks if enrollment
+    // detection ever drifts from what a real enroll actually persists.
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "unenrolled@example.com" },
+      sessionUser,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const secret = base32Decode(secretParam);
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code: currentTotpCode(secret) },
+      sessionUser,
+    );
+
+    // A fresh preauthSetupToken for the SAME already-enrolled user — the
+    // login flow itself would no longer issue one (mfaStatusChecker sees
+    // the row and returns `required: true`, not `setupRequired`), so this
+    // mints one directly to isolate the handler's own already-enrolled
+    // check from that unrelated login-side branch.
+    const { token: freshPreauthToken } = signMfaPreauthSetupToken(
+      { userId, tenantId: TENANT_ID },
+      10,
+      CHALLENGE_TOKEN_SECRET,
+    );
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+      preauthSetupToken: freshPreauthToken,
+      accountLabel: "unenrolled@example.com",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.details.reason).toBe("mfa_already_enabled");
+    expect(body.setupToken).toBeUndefined();
+  });
+});

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",

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