@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/auth-mfa/feature.ts

@@ -0,0 +1,170 @@
+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 { 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";
+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");
+    // verify.write.ts dispatches "tenant:query:memberships" — without this
+    // the app boots clean and the first MFA login dies at runtime on an
+    // unknown handler instead of failing at mount time.
+    r.requires("tenant");
+    r.config("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 }),
+      ),
+      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 }),
+      ),
+      verify: r.writeHandler(
+        createMfaVerifyHandler({ challengeTokenSecret: opts.challengeTokenSecret }),
+      ),
+    };
+
+    const queries = {
+      status: r.queryHandler(mfaStatusQuery),
+    };
+
+    // 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, queries, bindRevokeAllOtherSessions, checkMfaStatus };
+  });
+}

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

@@ -0,0 +1,67 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+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();
+
+      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
+      // (#1467): without ctx.redis, verifyMfaFactor's TOTP-replay burn is
+      // skipped, and a code observed once (phishing proxy/shoulder-surfing)
+      // could be replayed within the ±1-step window to disable MFA outright.
+      // "no ctx.redis means no one gets through MFA login" doesn't cover
+      // this route — it's session-authed, and JWTs issued before Redis was
+      // unwired stay valid until they expire.
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "disable (mfa) requires ctx.redis for TOTP replay protection",
+          }),
+        );
+      }
+      const replay = { redis: ctx.redis, userId: event.user.id };
+      const verify = await verifyMfaFactor(row, event.payload.code, replay);
+      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-preauth.write.ts

@@ -0,0 +1,200 @@
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildSessionRoles,
+  createSystemUser,
+  defineWriteHandler,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+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();
+
+      // Fail closed: unlike verify.write.ts/enable-confirm.write.ts, this
+      // endpoint has NO gate before it (access: { roles: ["all"] }, no JWT,
+      // no prior challenge-token from a successful login) — its only secret
+      // is a 6-digit TOTP code. Silently skipping the brute-force cap and
+      // single-use burn when ctx.redis is absent would let the setup token
+      // be guessed against unboundedly until its TTL expires. The route's
+      // IP rate limiter is not a substitute: it's IP-scoped and resets on
+      // every success.
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message:
+              "enable-confirm-preauth requires ctx.redis for the brute-force cap and single-use burn",
+          }),
+        );
+      }
+
+      // 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.
+      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) {
+        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.
+      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();
+
+      // Status + membership must be verified BEFORE the entity-write below —
+      // an admin can restrict/delete the account or revoke its tenant
+      // membership in the window between preauth-enable-start and
+      // preauth-confirm (up to MFA_SETUP_TOKEN_TTL_MINUTES). Checking after
+      // the write left two irreversible side effects behind an
+      // already-signed, non-forgeable setupToken that then just returns
+      // invalidSetupToken(): the MFA row persisted and (formerly) all other
+      // sessions revoked — with mfaAlreadyEnabled() blocking any
+      // re-enrollment until an operator manually disables MFA. NOT fixed by
+      // this ordering: burnToken() above still runs before this check, so a
+      // mid-flight restricted/deleted user still burns their setup token
+      // (framework#1523/5) — moving the burn later would need care around
+      // the existing userId-unique-constraint backstop between the
+      // `existing` check above and executor.create() below.
+      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();
+
+      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;
+
+      // ctx.redis is guaranteed by the fail-closed check above.
+      await clearMfaVerifyAttempts(ctx.redis, userId);
+
+      // Re-derive the full session the way verify.write.ts does — the
+      // setupToken only proves "password + new TOTP secret", not roles;
+      // roles come from the membership lookup above, same as every other
+      // login-completing handler.
+      // 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;
+
+      // Last step before returning success: every gate above (status,
+      // membership, entity-write) has passed, so this is the point of no
+      // return anyway — revoking here instead of right after the write
+      // means a rejected confirm never touches the user's other sessions.
+      // 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);
+      }
+
+      return { isSuccess: true, data: { kind: "mfa-preauth-confirm-success", session } };
+    },
+  });
+}

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

@@ -0,0 +1,106 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { burnToken } from "../../shared";
+import { base32Decode } from "../base32";
+import { findUserMfaRow } from "../db/queries";
+import { invalidSetupToken, invalidTotpCode, mfaAlreadyEnabled } from "../errors";
+import { verifyMfaSetupToken } from "../mfa-setup-token";
+import { encodeRecoveryCodes, 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();
+
+      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
+      // (#1467): session-authed (lower risk — the caller already has a
+      // valid JWT), but silently skipping the single-use burn here would
+      // still let a double-confirm race complete twice instead of the
+      // second seeing invalidSetupToken(). Checked before the TOTP verify
+      // for the same reason the other two handlers check it early: fail
+      // closed before doing any of the guarded work, not partway through.
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "enable-confirm requires ctx.redis for the single-use setup-token burn",
+          }),
+        );
+      }
+
+      const secret = base32Decode(verify.payload.totpSecretBase32);
+      if (verifyTotp(secret, event.payload.code) === false) return invalidTotpCode();
+
+      // Burn the setup token on the first successful confirm — without this
+      // a `disable` doesn't retire it (re-enabling with the secret the user
+      // thinks they discarded), and two parallel confirms both proceed to
+      // executor.create instead of the second seeing mfa_already_enabled().
+      // ponytail: burned here, not unburned on a later executor.create
+      // failure (unlike login.write.ts's unburnToken pattern) — self-service
+      // enable-start always mints a fresh setup token on demand (no mailed
+      // link to go stale), so the realistic remaining failure path (a
+      // double-confirm race where executor.create itself fails, e.g. a
+      // concurrent mfa_already_enabled() write) is meant to leave the burn
+      // standing. Add unburnToken here if create-failure retries turn out
+      // to matter.
+      const burnResult = await burnToken(ctx.redis, "mfa-setup", event.user.id, verify.expiresAtMs);
+      if (burnResult === "already-used") return invalidSetupToken();
+
+      const existing = await findUserMfaRow(ctx.db, event.user);
+      if (existing) return mfaAlreadyEnabled();
+
+      const result = await executor.create(
+        {
+          userId: event.user.id,
+          totpSecret: verify.payload.totpSecretBase32,
+          // Stored as a JSON string — see schema/user-mfa.ts (recoveryCodes
+          // is an encrypted+userOwned text field, both layers need a string).
+          recoveryCodes: encodeRecoveryCodes(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-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,
+        },
+      };
+    },
+  });
+}