@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/auth-mfa/changes.json

@@ -0,0 +1,62 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "MFA web client shares the login response mapper",
+    "detail": "The MFA web client reuses the shared `toLoginResponse` helper (now exported from the auth-email-password web barrel) for `landingPath` handling, so login, MFA verify and MFA setup confirm map the response identically."
+  },
+  {
+    "version": "0.329.0",
+    "type": "improvement",
+    "title": "kumiko-bundled-features is published as compiled JavaScript plus .d.ts",
+    "detail": "`kumiko-bundled-features` now ships `dist` (`.js` and `.d.ts`) instead of TypeScript source. Export keys are unchanged; only the targets behind them move to `dist`. The per-feature `changes.json` files stay in the tarball as source, because `kumiko upgrade` and `kumiko changes` read them from the installed package. The package now declares `jose`, `temporal-polyfill`, `uuid` and `zod` as dependencies, which its code already imported. `template-resolver/testing` needs Bun (it imports `kumiko-framework/testing`). The MFA setup screen imports `qrcode/lib/browser.js` with its extension so Node's ESM resolver finds it."
+  },
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "mfa-verify-attempts now delegates to shared/lockout-counter",
+    "detail": "No behavior change — same exported function/type names and Redis key prefixes as before the extraction."
+  },
+  {
+    "version": "0.259.0",
+    "type": "improvement",
+    "title": "Declarative auth-mfa-disable and auth-mfa-regenerate-recovery screens (fw#2844).",
+    "detail": "`auth-mfa-disable` (actionForm on auth-mfa:write:disable) and `auth-mfa-regenerate-recovery` (secretMint on auth-mfa:write:regenerate-recovery, one-time reveal of the new codes) join `auth-mfa-enable`, so a settings page can offer the full MFA lifecycle without client components — gate them on `auth-mfa:query:user-mfa:status` via a dashboard screen panel's `visibleWhen`. Exported ids MFA_DISABLE_SCREEN_ID, MFA_REGENERATE_RECOVERY_SCREEN_ID. Additive; handlers unchanged."
+  },
+  {
+    "version": "0.165.0",
+    "type": "fix",
+    "title": "KEK reencrypt job: rejects unrecognized envelopes",
+    "detail": "Reencrypt job now explicitly fails on non-envelope rows instead of silently passing through."
+  },
+  {
+    "version": "0.165.0",
+    "type": "fix",
+    "title": "MFA: fail-closed when ctx.redis is missing",
+    "detail": "Verify/enable-confirm operations now fail when Redis is unreachable instead of silently accepting."
+  },
+  {
+    "version": "0.150.0",
+    "type": "fix",
+    "title": "Fix `auth-mfa`'s two-step verify + enroll flow re-checking stale state and skipping repla…",
+    "detail": "Fix `auth-mfa`'s two-step verify + enroll flow re-checking stale state and skipping replay protection that `login.write.ts` already enforces: - `verify.write.ts` minted a session from a challenge token alone, without re-checking account status or tenant membership. A user restricted/deleted, or removed from the tenant, in the ~10-minute window between password login and MFA verify still got a full session — membership loss even silently fell back to global-only roles instead of refusing. Both gates now mirror `login.write.ts`. - `enable-confirm.write.ts` never burned the setup token on success: the same token could re-enable MFA with an old secret after a `disable` (replay), and two parallel confirms both hit the executor instead of the second seeing `mfa_already_enabled`. The token is now single-use, the same as `login.write.ts`'s magic-link tokens. - `auth-mfa` was missing `r.requires(\"tenant\")` despite `verify.write.ts` dispatching `tenant:query:memberships` — a mount without `tenant` now fails at boot instead of 500ing on first login. - Recovery codes are now normalized (uppercased, punctuation-stripped) before hashing and verifying, so a code retyped lowercase or without the dash still matches — this changes the stored hash format, safe because `auth-mfa` has no deployed consumer with enrolled users yet. Also fixes `samples/apps/user-data-rights-demo`'s forget-cleanup test, which asserted on the manual `runForgetCleanup` helper instead of driving the actually-registered cron job through its real `JobContext` wrapper."
+  },
+  {
+    "version": "0.149.1",
+    "type": "fix",
+    "title": "Fix `auth-mfa` crashing on enable/regenerate for any app with per-subject crypto-shreddin…",
+    "detail": "Fix `auth-mfa` crashing on enable/regenerate for any app with per-subject crypto-shredding (`configurePiiSubjectKms`) active: `recoveryCodes` was a `jsonb` field marked `userOwned`, but the PII-encryption pipeline requires a string value for any subject-owned field — every real enable-confirm write threw `PII field \"recoveryCodes\" must be a string, got object`. `recoveryCodes` is now a `createTextField({ encrypted: true, userOwned })` (JSON-stringified at the write/read boundary), matching `totpSecret`. That exposed a second, deeper bug: a field carrying both `encrypted: true` and a subject marker is written as `PII(envelope(plaintext))`, but `decryptForRead` peeled the layers in write order instead of reverse order, so the envelope cipher choked on a still-PII-wrapped string. Fixed `event-store-executor-context.ts`'s `decryptForRead` to unwrap PII first, then envelope — and updated `auth-mfa`'s KEK-reencrypt job (which reads raw rows, bypassing `decryptForRead`) to do the same. Also: `MfaEnableScreen` now takes an optional `onEnabled` callback, fired after a successful enable-confirm — hosts that compose it inside their own MFA-status view (like kumiko-studio's account-security screen) need it to know when to refetch and swap away from the embedded enable flow. - @cosmicdrift/kumiko-framework@0.149.1 - @cosmicdrift/kumiko-headless@0.149.1 - @cosmicdrift/kumiko-renderer@0.149.1 - @cosmicdrift/kumiko-dispatcher-live@0.149.1 - @cosmicdrift/kumiko-renderer-web@0.149.1"
+  },
+  {
+    "version": "0.149.0",
+    "type": "improvement",
+    "title": "`auth-mfa/web` gains `MfaDisableDialog`, `MfaRegenerateRecoveryDialog`, and `MfaRecoveryC…",
+    "detail": "`auth-mfa/web` gains `MfaDisableDialog`, `MfaRegenerateRecoveryDialog`, and `MfaRecoveryCodesReveal` — the disable/regenerate-recovery UI deferred from the initial MFA-UI PR (kumiko-framework#266). Also fixes `MfaEnableScreen`'s error banner, which templated the raw snake_case server error code straight into the i18n key (`auth.mfa.errors.invalid_totp_code`) instead of the camelCase key actually registered (`auth.mfa.errors.invalidCode`) — extracted into a shared `mfaManageErrorKey` helper, now used by all three write-triggering components."
+  },
+  {
+    "version": "0.149.0",
+    "type": "improvement",
+    "title": "`auth-mfa` gains a `status` query (`AuthMfaQueries.status`, wire QN `auth-mfa:query:user-…",
+    "detail": "`auth-mfa` gains a `status` query (`AuthMfaQueries.status`, wire QN `auth-mfa:query:user-mfa:status`) returning `{ enabled: boolean }` for the calling user — the one thing a settings/security screen needs to decide whether to show the enrollment flow or the disable/regenerate actions. No client-side signal carried this before."
+  }
+]

package/packages/bundled-features/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/packages/bundled-features/src/auth-mfa/constants.ts

@@ -0,0 +1,47 @@
+// @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",
+  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",
+} as const;
+
+export const AuthMfaQueries = {
+  status: "auth-mfa:query:user-mfa:status",
+} as const;
+
+// Write-failure codes minted server-side into UnprocessableError (errors.ts).
+// The client reads the i18n key straight off the write result
+// (res.error.i18nKey) instead of re-deriving it from these codes.
+export const AuthMfaErrorCodes = {
+  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 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;
+
+// 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";
+export const MFA_DISABLE_SCREEN_ID = "auth-mfa-disable";
+export const MFA_REGENERATE_RECOVERY_SCREEN_ID = "auth-mfa-regenerate-recovery";

package/packages/bundled-features/src/auth-mfa/db/queries.ts

@@ -0,0 +1,45 @@
+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 { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa.js";
+
+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`/`recoveryCodes` are `encrypted: true` — a raw fetchOne would
+// return ciphertext, not plaintext. 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. `recoveryCodes` is
+// stored as a JSON string (schema/user-mfa.ts — both encryption layers need
+// a string value) — parsed back into `{ hashes }` here, once, for every
+// caller instead of each handler re-parsing it. A parse failure here means
+// stored data is corrupt (post-decrypt, not user input) — fail loud.
+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);
+  if (!detail) return null;
+  // @cast-boundary engine-payload — executor.detail returns a decrypted,
+  // untyped Record; the userMfa entity's own field shape narrows it.
+  const row = detail as Omit<UserMfaRow, "recoveryCodes"> & { recoveryCodes: string };
+  const recoveryCodes = parseJsonOrThrow<{ hashes: readonly string[] }>(
+    row.recoveryCodes,
+    "user-mfa.recoveryCodes",
+  );
+  return { ...row, recoveryCodes };
+}

package/packages/bundled-features/src/auth-mfa/errors.ts

@@ -0,0 +1,66 @@
+import {
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { AuthMfaErrorCodes } from "./constants.js";
+
+export { AuthMfaErrorCodes as AuthMfaErrors } from "./constants.js";
+
+export function mfaAlreadyEnabled(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.mfaAlreadyEnabled, {
+      i18nKey: "auth.mfa.errors.mfaAlreadyEnabled",
+    }),
+  );
+}
+
+export function mfaNotEnabled(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.mfaNotEnabled, {
+      i18nKey: "auth.mfa.errors.mfaNotEnabled",
+    }),
+  );
+}
+
+export function invalidSetupToken(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidSetupToken, {
+      i18nKey: "auth.mfa.errors.invalidSetupToken",
+    }),
+  );
+}
+
+export function invalidTotpCode(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidTotpCode, {
+      i18nKey: "auth.mfa.errors.invalidTotpCode",
+    }),
+  );
+}
+
+export function invalidRecoveryCode(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidRecoveryCode, {
+      i18nKey: "auth.mfa.errors.invalidRecoveryCode",
+    }),
+  );
+}
+
+export function invalidChallengeToken(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidChallengeToken, {
+      i18nKey: "auth.mfa.errors.invalidChallengeToken",
+    }),
+  );
+}
+
+// retryAfterSeconds drives the login UI countdown — must stay > 0.
+export function tooManyAttempts(retryAfterSeconds: number): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.tooManyAttempts, {
+      i18nKey: "auth.mfa.errors.tooManyAttempts",
+      details: { retryAfterSeconds },
+    }),
+  );
+}

package/packages/bundled-features/src/auth-mfa/feature.ts

@@ -0,0 +1,251 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { mfaRequiredConfigKey } from "./config.js";
+import { createDisableHandler } from "./handlers/disable.write.js";
+import { createEnableConfirmHandler } from "./handlers/enable-confirm.write.js";
+import { createEnableConfirmPreauthHandler } from "./handlers/enable-confirm-preauth.write.js";
+import { createEnableStartHandler } from "./handlers/enable-start.write.js";
+import { createEnableStartPreauthHandler } from "./handlers/enable-start-preauth.write.js";
+import { mfaReencryptJob } from "./handlers/reencrypt.job.js";
+import { createRegenerateRecoveryHandler } from "./handlers/regenerate-recovery.write.js";
+import { mfaStatusQuery } from "./handlers/status.query.js";
+import { createMfaVerifyHandler } from "./handlers/verify.write.js";
+import { AUTH_MFA_FEATURE_I18N } from "./i18n.js";
+import { createMfaCodeVerifier, type MfaCodeVerifier } from "./mfa-code-verifier.js";
+import { createMfaStatusChecker, type MfaStatusChecker } from "./mfa-status-checker.js";
+import { userMfaEntity } from "./schema/user-mfa.js";
+import { mfaDisableScreen, mfaEnableScreen, mfaRegenerateRecoveryScreen } from "./screens.js";
+
+const REENCRYPT_ESCAPE_HATCH_REASON =
+  "re-encrypts MFA secrets of every tenant's users with the new master key";
+
+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;
+}
+
+// Reads the eagerly-built `verifyMfaCode` off a mounted auth-mfa feature's
+// exports — personal-access-tokens wires this in as its optional
+// mfaVerifier (re-auth gate for minting a token). Same no-bind-setter
+// reasoning as checkMfaStatus above.
+export function mfaVerifierFromFeature(feature: FeatureDefinition): MfaCodeVerifier | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "verifyMfaCode" in exports) {
+    const { verifyMfaCode } = exports as { verifyMfaCode: unknown };
+    if (typeof verifyMfaCode === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return verifyMfaCode as MfaCodeVerifier;
+    }
+  }
+  return undefined;
+}
+
+export type BindRevokeAllPatTokens = (revoker: (userId: string) => Promise<number>) => void;
+
+// Reads the late-bind setter off a mounted auth-mfa feature's exports —
+// run{Prod,Dev}App call this once the personal-access-tokens feature (if
+// mounted) has produced a concrete revoker, same wiring shape as
+// bindMfaRevokeAllOtherSessionsFromFeature.
+export function bindRevokeAllPatTokensFromFeature(
+  feature: FeatureDefinition,
+): BindRevokeAllPatTokens | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "bindRevokeAllPatTokens" in exports) {
+    const { bindRevokeAllPatTokens } = exports as { bindRevokeAllPatTokens: unknown };
+    if (typeof bindRevokeAllPatTokens === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return bindRevokeAllPatTokens as BindRevokeAllPatTokens;
+    }
+  }
+  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());
+
+    // Declarative secretMint screen — mint (no input) -> reveal QR/secret/
+    // recovery-codes -> confirm with a code. App places it via r.nav in its
+    // logged-in settings area (see personal-access-tokens/feature.ts for the
+    // same convention).
+    r.screen(mfaEnableScreen);
+    r.screen(mfaDisableScreen);
+    r.screen(mfaRegenerateRecoveryScreen);
+    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({
+      name: "reencrypt",
+      trigger: { manual: true },
+      escapeHatch: {
+        reason: REENCRYPT_ESCAPE_HATCH_REASON,
+      },
+      handler: (payload, ctx) =>
+        mfaReencryptJob(
+          payload,
+          ctx,
+          ctx.db.unsafeRaw(REENCRYPT_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+        ),
+    });
+
+    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);
+
+    // Same late-bind shape as sharedRevoker above, for the personal-access-
+    // tokens feature (if mounted). Wired to enable-confirm(-preauth)/disable
+    // only — regenerate-recovery doesn't change enrollment state, so it's
+    // out of scope for the "MFA-enable/disable" finding this mirrors.
+    let revokeAllPatTokens: ((userId: string) => Promise<number>) | undefined;
+    const sharedPatRevoker = (userId: string): Promise<number> =>
+      revokeAllPatTokens?.(userId) ?? 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,
+          revokeAllPatTokens: sharedPatRevoker,
+        }),
+      ),
+      enableConfirmPreauth: r.writeHandler(
+        createEnableConfirmPreauthHandler({
+          setupTokenSecret: opts.setupTokenSecret,
+          revokeAllOtherSessions: sharedRevoker,
+          revokeAllPatTokens: sharedPatRevoker,
+        }),
+      ),
+      disable: r.writeHandler(
+        createDisableHandler({
+          revokeAllOtherSessions: sharedRevoker,
+          revokeAllPatTokens: sharedPatRevoker,
+        }),
+      ),
+      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,
+    });
+
+    // No late-bind needed — same reasoning as checkMfaStatus: only needs the
+    // HandlerContext the caller already has.
+    const verifyMfaCode = createMfaCodeVerifier();
+
+    const bindRevokeAllOtherSessions: BindMfaRevokeAllOtherSessions = (revoker) => {
+      revokeAllOtherSessions = revoker;
+    };
+
+    const bindRevokeAllPatTokens: BindRevokeAllPatTokens = (revoker) => {
+      revokeAllPatTokens = revoker;
+    };
+
+    return {
+      handlers,
+      queries,
+      bindRevokeAllOtherSessions,
+      checkMfaStatus,
+      verifyMfaCode,
+      bindRevokeAllPatTokens,
+    };
+  });
+}

package/packages/bundled-features/src/auth-mfa/handlers/disable.write.ts

@@ -0,0 +1,83 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { findUserMfaRow } from "../db/queries.js";
+import { invalidTotpCode, mfaNotEnabled } from "../errors.js";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa.js";
+import { verifyMfaFactor } from "../verify-factor.js";
+
+export type DisableOptions = {
+  readonly revokeAllOtherSessions?: (
+    userId: string,
+    currentSid: string | undefined,
+  ) => Promise<number>;
+  // Wired late by run-prod-app once the personal-access-tokens feature (if
+  // mounted) is concrete. Absent when PAT isn't mounted: disabling MFA just
+  // doesn't revoke PAT tokens.
+  readonly revokeAllPatTokens?: (userId: string) => 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: {
+        reason:
+          "each signed-in user may disable only their own MFA enrollment after proving " +
+          "possession of a TOTP or recovery code; the handler looks up and removes the caller's own user-mfa row",
+      },
+    },
+    description:
+      "Removes the caller's TOTP enrollment for good after they prove possession with a TOTP or recovery code, and signs their other sessions and access tokens out; use it when a user wants two-factor authentication turned off.",
+    agent: { risk: "high" },
+    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);
+      }
+      if (opts.revokeAllPatTokens) {
+        await opts.revokeAllPatTokens(event.user.id);
+      }
+
+      return { isSuccess: true, data: { disabled: true } };
+    },
+  });
+}