@cosmicdrift/kumiko-bundled-features 0.147.0 → 0.147.2

package/src/auth-mfa/__tests__/verify.integration.test.ts

@@ -0,0 +1,186 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createTestEnvelopeCipher,
+  expectErrorIncludes,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createUserFeature } from "../../user/feature";
+import { userEntity } from "../../user/schema/user";
+import { base32Decode } from "../base32";
+import { AuthMfaHandlers } from "../constants";
+import { createAuthMfaFeature } from "../feature";
+import { signMfaChallengeToken } from "../mfa-challenge-token";
+import { userMfaEntity } from "../schema/user-mfa";
+import { currentTotpCode } from "../totp";
+
+let stack: TestStack;
+
+const SETUP_TOKEN_SECRET = "test-mfa-setup-secret-at-least-32-bytes-long!!";
+const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
+
+// Handler access is `{ roles: ["all"] }`, matching how the framework route
+// dispatches with a guest identity — a literal here is enough since the
+// handler derives everything from the challenge-token payload, not from
+// event.user.
+const GUEST: SessionUser = {
+  id: "00000000-0000-0000-0000-000000000000",
+  tenantId: "00000000-0000-4000-8000-000000000001" as TenantId,
+  roles: ["all"],
+};
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher();
+  configureEntityFieldEncryption(encryption);
+  const resolver = createConfigResolver({ cipher: encryption });
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthMfaFeature({
+        setupTokenSecret: SETUP_TOKEN_SECRET,
+        issuer: "Kumiko Test",
+        challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+  });
+  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();
+});
+
+async function enableMfaFor(idSeed: number): Promise<{
+  user: ReturnType<typeof createTestUser>;
+  secret: Buffer;
+  recoveryCodes: string[];
+}> {
+  const user = createTestUser({ id: idSeed, roles: ["User"] });
+  const start = await stack.http.writeOk<{
+    setupToken: string;
+    otpauthUri: string;
+    recoveryCodes: string[];
+  }>(AuthMfaHandlers.enableStart, { accountLabel: `user-${idSeed}@example.com` }, user);
+  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) },
+    user,
+  );
+  return { user, secret, recoveryCodes: start.recoveryCodes };
+}
+
+function challengeFor(userId: string, tenantId: TenantId): string {
+  return signMfaChallengeToken({ userId, tenantId }, 10, CHALLENGE_TOKEN_SECRET).token;
+}
+
+describe("mfa verify — completes a two-step login", () => {
+  test("a valid TOTP code succeeds and returns the full session", async () => {
+    const { user, secret } = await enableMfaFor(1);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    const res = await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expect(res.session.id).toBe(user.id);
+    expect(res.session.tenantId).toBe(user.tenantId);
+  });
+
+  test("a wrong TOTP code is rejected", async () => {
+    const { user } = await enableMfaFor(2);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: "000000" },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_totp_code");
+  });
+
+  test("a valid recovery code succeeds, and the SAME code is rejected on replay", async () => {
+    const { user, recoveryCodes } = await enableMfaFor(3);
+    const code = recoveryCodes[0];
+    if (code === undefined) throw new Error("no recovery code minted");
+
+    const challengeA = challengeFor(user.id, user.tenantId);
+    const res = await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeA, code },
+      GUEST,
+    );
+    expect(res.session.id).toBe(user.id);
+
+    // Advisor-flagged trap: a recovery code must be single-use. Re-verify
+    // with a FRESH challenge token (a real attacker would just re-login)
+    // but the SAME recovery code — it must now be rejected because
+    // verify.write.ts persists remainingHashes on the row.
+    const challengeB = challengeFor(user.id, user.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeB, code },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_totp_code");
+  });
+
+  test("a challenge token cannot be replayed even with a still-valid TOTP code", async () => {
+    const { user, secret } = await enableMfaFor(4);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+
+    // Same challenge token, same (still time-window-valid) code — must be
+    // rejected because burnToken() marks it used on the first success.
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+
+  test("a malformed challenge token is rejected without leaking account state", async () => {
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken: "not-a-real-token", code: "123456" },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+
+  test("a challenge token for a user without MFA enabled is rejected", async () => {
+    const challengeToken = challengeFor("verify-never-enabled-1", GUEST.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: "123456" },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+});

package/src/auth-mfa/config.ts

@@ -0,0 +1,26 @@
+// Tenant-scoped enforcement policy: does a user need MFA to log in even if
+// they haven't opted in themselves? Default "optional" means the feature
+// is fully opt-in (existing tenants/users unaffected — no migration step).
+//
+// ponytail: "admins"/"all" HARD-BLOCK login for an unenrolled user (see
+// mfa-status-checker.ts's setupRequired branch) — there is no in-band way
+// for a blocked user to complete enrollment yet (that flow ships in PR3's
+// UI). Flipping this away from "optional" before PR3 locks out every
+// unenrolled matching user with no recovery path. Fine for a tenant that
+// enrolls its admins out-of-band first; a footgun otherwise.
+import { type ConfigKeyHandle, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine";
+
+export const MFA_REQUIRED_POLICIES = ["optional", "admins", "all"] as const;
+export type MfaRequiredPolicy = (typeof MFA_REQUIRED_POLICIES)[number];
+
+export const mfaRequiredConfigHandle: ConfigKeyHandle<"select"> = {
+  name: "auth-mfa:config:required",
+  type: "select",
+};
+
+export function mfaRequiredConfigKey() {
+  return createTenantConfig("select", {
+    default: "optional" satisfies MfaRequiredPolicy,
+    options: [...MFA_REQUIRED_POLICIES],
+  });
+}

package/src/auth-mfa/constants.ts

@@ -0,0 +1,25 @@
+// @runtime client
+// Pure constants — client-marked so auth-mfa/web/ may import handler QNs
+// and the screen id without pulling the feature's server runtime barrel.
+// Qualified write-handler names — feature is registered as "auth-mfa", each
+// short `name` below gets auto-prefixed to "auth-mfa:write:<name>" by
+// r.writeHandler. Exported so cross-feature wiring (login.write.ts,
+// run-prod-app.ts) can reference them without hardcoding the string.
+export const AUTH_MFA_FEATURE = "auth-mfa" as const;
+
+export const AuthMfaHandlers = {
+  enableStart: "auth-mfa:write:enable-start",
+  enableConfirm: "auth-mfa:write:enable-confirm",
+  disable: "auth-mfa:write:disable",
+  regenerateRecovery: "auth-mfa:write:regenerate-recovery",
+  verify: "auth-mfa:write:verify",
+} as const;
+
+export const MFA_SETUP_TOKEN_TTL_MINUTES = 10;
+export const MFA_CHALLENGE_TOKEN_TTL_MINUTES = 10;
+export const MFA_VERIFY_MAX_ATTEMPTS = 5;
+export const MFA_VERIFY_LOCKOUT_MINUTES = 5;
+
+// Dormant custom-screen id — see personal-access-tokens/feature.ts for the
+// same convention. App places it via r.nav in its logged-in settings area.
+export const MFA_ENABLE_SCREEN_ID = "auth-mfa-enable";

package/src/auth-mfa/db/queries.ts

@@ -0,0 +1,34 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+
+export type UserMfaRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly userId: string;
+  readonly totpSecret: string;
+  readonly recoveryCodes: { readonly hashes: readonly string[] };
+  readonly enabledAt: string;
+  readonly lastUsedAt: string | null;
+};
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// `totpSecret` is `encrypted: true` — a raw fetchOne would return ciphertext,
+// not the plaintext base32 secret. fetchOne only locates the row's id (no
+// decryption needed for that); executor.detail() does the real, decrypting
+// read the same way every other entity handler does.
+export async function findUserMfaRow(db: TenantDb, user: SessionUser): Promise<UserMfaRow | null> {
+  const idLookup = await fetchOne<{ id: string }>(db, userMfaTable, {
+    userId: user.id,
+    tenantId: user.tenantId,
+  });
+  if (!idLookup) return null;
+  const detail = await executor.detail({ id: idLookup.id }, user, db);
+  // @cast-boundary engine-payload — executor.detail returns a decrypted,
+  // untyped Record; the userMfa entity's own field shape narrows it.
+  return detail as UserMfaRow | null;
+}

package/src/auth-mfa/errors.ts

@@ -0,0 +1,73 @@
+import {
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+
+export const AuthMfaErrors = {
+  mfaAlreadyEnabled: "mfa_already_enabled",
+  mfaNotEnabled: "mfa_not_enabled",
+  invalidSetupToken: "invalid_setup_token",
+  invalidTotpCode: "invalid_totp_code",
+  invalidRecoveryCode: "invalid_recovery_code",
+  invalidChallengeToken: "invalid_challenge_token",
+  tooManyAttempts: "too_many_attempts",
+} as const;
+
+export function mfaAlreadyEnabled(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrors.mfaAlreadyEnabled, {
+      i18nKey: "authMfa.errors.mfaAlreadyEnabled",
+    }),
+  );
+}
+
+export function mfaNotEnabled(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrors.mfaNotEnabled, {
+      i18nKey: "authMfa.errors.mfaNotEnabled",
+    }),
+  );
+}
+
+export function invalidSetupToken(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrors.invalidSetupToken, {
+      i18nKey: "authMfa.errors.invalidSetupToken",
+    }),
+  );
+}
+
+export function invalidTotpCode(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrors.invalidTotpCode, {
+      i18nKey: "authMfa.errors.invalidTotpCode",
+    }),
+  );
+}
+
+export function invalidRecoveryCode(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrors.invalidRecoveryCode, {
+      i18nKey: "authMfa.errors.invalidRecoveryCode",
+    }),
+  );
+}
+
+export function invalidChallengeToken(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrors.invalidChallengeToken, {
+      i18nKey: "authMfa.errors.invalidChallengeToken",
+    }),
+  );
+}
+
+// retryAfterSeconds drives the login UI countdown — must stay > 0.
+export function tooManyAttempts(retryAfterSeconds: number): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrors.tooManyAttempts, {
+      i18nKey: "authMfa.errors.tooManyAttempts",
+      details: { retryAfterSeconds },
+    }),
+  );
+}

package/src/auth-mfa/feature.ts

@@ -0,0 +1,146 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+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 { createEnableStartHandler } from "./handlers/enable-start.write";
+import { mfaReencryptJob } from "./handlers/reencrypt.job";
+import { createRegenerateRecoveryHandler } from "./handlers/regenerate-recovery.write";
+import { createMfaVerifyHandler } from "./handlers/verify.write";
+import { AUTH_MFA_FEATURE_I18N } from "./i18n";
+import { createMfaStatusChecker, type MfaStatusChecker } from "./mfa-status-checker";
+import { userMfaEntity } from "./schema/user-mfa";
+
+export type AuthMfaFeatureOptions = {
+  // HMAC secret for the stateless enable-flow token (carries the generated
+  // TOTP secret + recovery-code hashes between enable.start and
+  // enable.confirm). Distinct secret from any other token flow in the app —
+  // do not reuse passwordReset.hmacSecret.
+  readonly setupTokenSecret: string;
+  // otpauth:// URI issuer — shown in the user's authenticator app next to
+  // the account label ("Kumiko: jane@example.com").
+  readonly issuer: string;
+  // HMAC secret for the login-flow challenge token (carries {userId,
+  // tenantId} between the password-check and /auth/mfa/verify). Distinct
+  // secret from setupTokenSecret — a compromised setup-token secret must
+  // not also forge login challenges.
+  readonly challengeTokenSecret: string;
+};
+
+export type BindMfaRevokeAllOtherSessions = (
+  revoker: (userId: string, currentSid: string | undefined) => Promise<number>,
+) => void;
+
+// Reads the late-bind setter off a mounted auth-mfa feature's exports —
+// mirrors sessions' own bindAutoRevokeFromFeature. run{Prod,Dev}App call
+// this once the sessions feature (if mounted) has produced a concrete
+// sessionRevokeAllOthers callback.
+export function bindMfaRevokeAllOtherSessionsFromFeature(
+  feature: FeatureDefinition,
+): BindMfaRevokeAllOtherSessions | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "bindRevokeAllOtherSessions" in exports) {
+    const { bindRevokeAllOtherSessions } = exports as {
+      bindRevokeAllOtherSessions: unknown;
+    };
+    if (typeof bindRevokeAllOtherSessions === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return bindRevokeAllOtherSessions as BindMfaRevokeAllOtherSessions;
+    }
+  }
+  return undefined;
+}
+
+// Reads the eagerly-built `checkMfaStatus` off a mounted auth-mfa feature's
+// exports — no bind-setter needed (see the comment where it's built).
+export function mfaStatusCheckerFromFeature(
+  feature: FeatureDefinition,
+): MfaStatusChecker | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "checkMfaStatus" in exports) {
+    const { checkMfaStatus } = exports as { checkMfaStatus: unknown };
+    if (typeof checkMfaStatus === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return checkMfaStatus as MfaStatusChecker;
+    }
+  }
+  return undefined;
+}
+
+export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefinition {
+  return defineFeature("auth-mfa", (r) => {
+    r.describe(
+      "TOTP-based two-factor authentication: enable/disable flow with QR-code setup, 8 single-use recovery codes, and (once wired into a login flow) a second login step after password verification. Secrets are envelope-encrypted at rest via the same MasterKeyProvider as `secrets`/`config`.",
+    );
+    r.uiHints({
+      displayLabel: "2FA / TOTP",
+      category: "identity",
+      recommended: true,
+    });
+    r.requires("user");
+    r.requires("config");
+    r.config({ keys: { required: mfaRequiredConfigKey() } });
+
+    // Dormant custom-screen — the client maps MFA_ENABLE_SCREEN_ID to
+    // MfaEnableScreen (see personal-access-tokens/feature.ts for the same
+    // convention). App places it via r.nav in its logged-in settings area.
+    r.screen({
+      id: MFA_ENABLE_SCREEN_ID,
+      type: "custom",
+      renderer: { react: { __component: "MfaEnableScreen" } },
+      access: { openToAll: true },
+    });
+    r.translations({ keys: AUTH_MFA_FEATURE_I18N });
+
+    // KEK-rotation for totpSecret (entity-field encryption). Manual
+    // trigger — ops runs it once after adding a new master key version,
+    // same operator workflow as config's own reencrypt job.
+    r.job("reencrypt", { trigger: { manual: true } }, mfaReencryptJob);
+
+    r.entity("user-mfa", userMfaEntity);
+
+    // Late-bound by run-prod-app once the sessions feature (if mounted) has
+    // produced a concrete `sessionRevokeAllOthers` callback — mirrors
+    // sessions' own bindAutoRevokeOnPasswordChange. Shared by every handler
+    // that changes MFA state (enable/disable/regenerate), so each one's
+    // "log out every other session" behavior tracks the same wiring.
+    let revokeAllOtherSessions:
+      | ((userId: string, currentSid: string | undefined) => Promise<number>)
+      | undefined;
+    const sharedRevoker = (userId: string, currentSid: string | undefined): Promise<number> =>
+      revokeAllOtherSessions?.(userId, currentSid) ?? Promise.resolve(0);
+
+    const handlers = {
+      enableStart: r.writeHandler(
+        createEnableStartHandler({ setupTokenSecret: opts.setupTokenSecret, issuer: opts.issuer }),
+      ),
+      enableConfirm: r.writeHandler(
+        createEnableConfirmHandler({
+          setupTokenSecret: opts.setupTokenSecret,
+          revokeAllOtherSessions: sharedRevoker,
+        }),
+      ),
+      disable: r.writeHandler(createDisableHandler({ revokeAllOtherSessions: sharedRevoker })),
+      regenerateRecovery: r.writeHandler(
+        createRegenerateRecoveryHandler({ revokeAllOtherSessions: sharedRevoker }),
+      ),
+      verify: r.writeHandler(
+        createMfaVerifyHandler({ challengeTokenSecret: opts.challengeTokenSecret }),
+      ),
+    };
+
+    // No late-bind needed (unlike sharedRevoker) — this checker only needs
+    // the HandlerContext the CALLER already has (login.write.ts runs it
+    // from inside its own dispatcher call), not a raw db handle assembled
+    // at app-boot time.
+    const checkMfaStatus = createMfaStatusChecker({
+      challengeTokenSecret: opts.challengeTokenSecret,
+    });
+
+    const bindRevokeAllOtherSessions: BindMfaRevokeAllOtherSessions = (revoker) => {
+      revokeAllOtherSessions = revoker;
+    };
+
+    return { handlers, bindRevokeAllOtherSessions, checkMfaStatus };
+  });
+}

package/src/auth-mfa/handlers/disable.write.ts

@@ -0,0 +1,51 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { findUserMfaRow } from "../db/queries";
+import { invalidTotpCode, mfaNotEnabled } from "../errors";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+import { verifyMfaFactor } from "../verify-factor";
+
+export type DisableOptions = {
+  readonly revokeAllOtherSessions?: (
+    userId: string,
+    currentSid: string | undefined,
+  ) => Promise<number>;
+};
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// A TOTP code or a recovery code both prove possession of the second
+// factor — either is accepted to turn MFA back off. Password alone is NOT
+// enough: that would make MFA worthless against exactly the "stolen
+// password" scenario it exists to defend.
+export function createDisableHandler(opts: DisableOptions) {
+  return defineWriteHandler({
+    name: "disable",
+    schema: z.object({ code: z.string().min(6).max(9) }),
+    access: { openToAll: true },
+    handler: async (event, ctx) => {
+      const row = await findUserMfaRow(ctx.db, event.user);
+      if (!row) return mfaNotEnabled();
+
+      const verify = await verifyMfaFactor(row, event.payload.code);
+      if (!verify.ok) return invalidTotpCode();
+
+      const result = await executor.delete({ id: row.id }, event.user, ctx.db);
+      if (!result.isSuccess) return result;
+
+      // Disabling MFA is a security-relevant state change — same
+      // auto-revoke as enable, in case the person doing this isn't the
+      // legitimate account owner (attacker with a stolen-but-not-yet-
+      // MFA-locked session, or a recovery code obtained via social
+      // engineering).
+      if (opts.revokeAllOtherSessions) {
+        await opts.revokeAllOtherSessions(event.user.id, event.user.sid);
+      }
+
+      return { isSuccess: true, data: { disabled: true } };
+    },
+  });
+}

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

@@ -0,0 +1,68 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { base32Decode } from "../base32";
+import { invalidSetupToken, invalidTotpCode } from "../errors";
+import { verifyMfaSetupToken } from "../mfa-setup-token";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+import { verifyTotp } from "../totp";
+
+export type EnableConfirmOptions = {
+  readonly setupTokenSecret: string;
+  // Wired late by run-prod-app once the sessions feature (if mounted) is
+  // concrete — see sessions/session-callbacks.ts. Absent when sessions
+  // isn't mounted: enabling MFA just doesn't revoke other sessions.
+  readonly revokeAllOtherSessions?: (
+    userId: string,
+    currentSid: string | undefined,
+  ) => Promise<number>;
+};
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
+  return defineWriteHandler({
+    name: "enable-confirm",
+    schema: z.object({
+      setupToken: z.string().min(1),
+      code: z.string().length(6),
+    }),
+    access: { openToAll: true },
+    handler: async (event, ctx) => {
+      const verify = verifyMfaSetupToken(event.payload.setupToken, opts.setupTokenSecret);
+      if (!verify.ok) return invalidSetupToken();
+      // A setup token minted for one user can't be redeemed by another —
+      // guards against a leaked/shared token, not just tampering (the HMAC
+      // already rules that out).
+      if (verify.payload.userId !== event.user.id) return invalidSetupToken();
+
+      const secret = base32Decode(verify.payload.totpSecretBase32);
+      if (!verifyTotp(secret, event.payload.code)) return invalidTotpCode();
+
+      const result = await executor.create(
+        {
+          userId: event.user.id,
+          totpSecret: verify.payload.totpSecretBase32,
+          recoveryCodes: { hashes: verify.payload.recoveryCodeHashes },
+          enabledAt: Temporal.Now.instant(),
+          lastUsedAt: null,
+        },
+        event.user,
+        ctx.db,
+      );
+      if (!result.isSuccess) return result;
+
+      // Confirming enable proves possession of a second factor — every
+      // other session (a stolen-cookie attacker included) gets logged out.
+      // The session that just did this confirm keeps running.
+      if (opts.revokeAllOtherSessions) {
+        await opts.revokeAllOtherSessions(event.user.id, event.user.sid);
+      }
+
+      return { isSuccess: true, data: { enabled: true } };
+    },
+  });
+}

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

@@ -0,0 +1,66 @@
+import { defineWriteHandler } 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 { mfaAlreadyEnabled } from "../errors";
+import { signMfaSetupToken } from "../mfa-setup-token";
+import { buildOtpauthUri } from "../otpauth-uri";
+import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes";
+import { generateTotpSecret } from "../totp";
+
+export type EnableStartOptions = {
+  readonly setupTokenSecret: string;
+  readonly issuer: string;
+};
+
+// Stateless setup: no `userMfa` row is created here. The generated secret +
+// recovery-code hashes are signed into a short-lived `setupToken` (see
+// mfa-setup-token.ts) that `enable-confirm` verifies. An abandoned setup
+// (user closes the tab without entering a code) leaves zero trace — no
+// cleanup job needed for orphaned "pending MFA" rows.
+export function createEnableStartHandler(opts: EnableStartOptions) {
+  return defineWriteHandler({
+    name: "enable-start",
+    schema: z.object({
+      // Client-supplied label for the otpauth:// URI / authenticator-app
+      // entry (typically the user's own email) — avoids an extra DB lookup
+      // for something the already-authenticated client already knows about
+      // itself.
+      accountLabel: z.string().min(1).max(200),
+    }),
+    access: { openToAll: true },
+    handler: async (event, ctx) => {
+      const existing = await findUserMfaRow(ctx.db, event.user);
+      if (existing) return mfaAlreadyEnabled();
+
+      const secret = generateTotpSecret();
+      const recoveryCodes = generateRecoveryCodes();
+      const recoveryCodeHashes = await hashRecoveryCodes(recoveryCodes);
+
+      const { token: setupToken } = signMfaSetupToken(
+        {
+          userId: event.user.id,
+          totpSecretBase32: base32Encode(secret),
+          recoveryCodeHashes,
+        },
+        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,
+        },
+      };
+    },
+  });
+}