@cosmicdrift/kumiko-bundled-features 0.148.0 → 0.149.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.148.0",
+  "version": "0.149.1",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -114,11 +114,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.148.0",
-    "@cosmicdrift/kumiko-framework": "0.148.0",
-    "@cosmicdrift/kumiko-headless": "0.148.0",
-    "@cosmicdrift/kumiko-renderer": "0.148.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.148.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.149.1",
+    "@cosmicdrift/kumiko-framework": "0.149.1",
+    "@cosmicdrift/kumiko-headless": "0.149.1",
+    "@cosmicdrift/kumiko-renderer": "0.149.1",
+    "@cosmicdrift/kumiko-renderer-web": "0.149.1",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

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

@@ -17,7 +17,7 @@ import { configValuesTable } from "../../config/table";
 import { createUserFeature } from "../../user/feature";
 import { userEntity } from "../../user/schema/user";
 import { base32Decode } from "../base32";
-import { AuthMfaHandlers } from "../constants";
+import { AuthMfaHandlers, AuthMfaQueries } from "../constants";
 import { createAuthMfaFeature } from "../feature";
 import { userMfaEntity } from "../schema/user-mfa";
 import { currentTotpCode } from "../totp";
@@ -147,4 +147,27 @@ describe("enable-start + enable-confirm round trip", () => {
     );
     expectErrorIncludes(err, "invalid_setup_token");
   });
+
+  test("status query reflects enrollment before and after enable-confirm", async () => {
+    const user = createTestUser({ id: "status-query-1", roles: ["User"] });
+
+    const before = await stack.http.queryOk<{ enabled: boolean }>(AuthMfaQueries.status, {}, user);
+    expect(before.enabled).toBe(false);
+
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "status@example.com" },
+      user,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const code = currentTotpCode(base32Decode(secretParam));
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code },
+      user,
+    );
+
+    const after = await stack.http.queryOk<{ enabled: boolean }>(AuthMfaQueries.status, {}, user);
+    expect(after.enabled).toBe(true);
+  });
 });

package/src/auth-mfa/__tests__/pii-subject-encryption.integration.test.ts

@@ -0,0 +1,137 @@
+// Regression test for a real crash found via manual browser testing in a
+// consumer app (kumiko-studio) that mounts the full GDPR/user-data-rights
+// stack: totpSecret and recoveryCodes are both `encrypted: true` +
+// `userOwned` (schema/user-mfa.ts) — the SECOND layer (per-subject
+// crypto-shredding, entity-field-encryption.ts's sibling pipeline) only
+// activates when `configurePiiSubjectKms` has been called, which none of
+// the other auth-mfa integration tests do. That gap let a real bug ship:
+// recoveryCodes used to be a `createJsonbField` (an object, not a string),
+// and `encryptPiiFieldValues` throws "PII field must be a string" for any
+// non-string userOwned field. enable-confirm failed for EVERY real deployment
+// with crypto-shredding configured, while every test here stayed green.
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createUserFeature } from "../../user/feature";
+import { userEntity } from "../../user/schema/user";
+import { base32Decode } from "../base32";
+import { AuthMfaHandlers } from "../constants";
+import { createAuthMfaFeature } from "../feature";
+import { userMfaEntity } from "../schema/user-mfa";
+import { currentTotpCode } from "../totp";
+
+let stack: TestStack;
+
+const SETUP_TOKEN_SECRET = "test-setup-token-secret-do-not-use-in-prod";
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher();
+  configureEntityFieldEncryption(encryption);
+  const resolver = createConfigResolver({ cipher: encryption });
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createAuthMfaFeature({
+        setupTokenSecret: SETUP_TOKEN_SECRET,
+        issuer: "Kumiko Test",
+        challengeTokenSecret: "test-mfa-challenge-secret-at-least-32-bytes!!",
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// The second, independent encryption layer — same activation recipe as
+// crypto-shredding/__tests__/forget-subject.integration.test.ts.
+beforeEach(() => {
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+describe("with per-subject PII crypto-shredding active", () => {
+  test("enable-confirm succeeds and persists both totpSecret and recoveryCodes", async () => {
+    const user = createTestUser({ id: "pii-enable-1", roles: ["User"] });
+
+    const start = await stack.http.writeOk<{
+      setupToken: string;
+      otpauthUri: string;
+      recoveryCodes: string[];
+    }>(AuthMfaHandlers.enableStart, { accountLabel: "pii-enable@example.com" }, user);
+
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const secret = base32Decode(secretParam);
+
+    const confirmed = await stack.http.writeOk<{ enabled: boolean }>(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code: currentTotpCode(secret) },
+      user,
+    );
+    expect(confirmed.enabled).toBe(true);
+
+    // recoveryCodes round-trips through both encryption layers correctly —
+    // a recovery code (not just the TOTP code) still authenticates.
+    const disableRes = await stack.http.writeOk<{ disabled: boolean }>(
+      AuthMfaHandlers.disable,
+      { code: start.recoveryCodes[0] },
+      user,
+    );
+    expect(disableRes.disabled).toBe(true);
+  });
+
+  test("regenerate-recovery re-encrypts the new codes without crashing", async () => {
+    const user = createTestUser({ id: "pii-regen-1", roles: ["User"] });
+
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "pii-regen@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,
+    );
+
+    const regenerated = await stack.http.writeOk<{ recoveryCodes: string[] }>(
+      AuthMfaHandlers.regenerateRecovery,
+      { code: currentTotpCode(secret) },
+      user,
+    );
+    expect(regenerated.recoveryCodes).toHaveLength(8);
+
+    const disableRes = await stack.http.writeOk<{ disabled: boolean }>(
+      AuthMfaHandlers.disable,
+      { code: regenerated.recoveryCodes[0] },
+      user,
+    );
+    expect(disableRes.disabled).toBe(true);
+  });
+});

package/src/auth-mfa/constants.ts

@@ -15,6 +15,10 @@ export const AuthMfaHandlers = {
   verify: "auth-mfa:write:verify",
 } as const;
 
+export const AuthMfaQueries = {
+  status: "auth-mfa:query:user-mfa:status",
+} 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;

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

@@ -1,6 +1,7 @@
 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";
 
 export type UserMfaRow = {
@@ -17,10 +18,14 @@ 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
+// `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.
+// 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,
@@ -28,7 +33,13 @@ export async function findUserMfaRow(db: TenantDb, user: SessionUser): Promise<U
   });
   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.
-  return detail as UserMfaRow | null;
+  const row = detail as Omit<UserMfaRow, "recoveryCodes"> & { recoveryCodes: string };
+  const recoveryCodes = parseJsonOrThrow<{ hashes: readonly string[] }>(
+    row.recoveryCodes,
+    "user-mfa.recoveryCodes",
+  );
+  return { ...row, recoveryCodes };
 }

package/src/auth-mfa/feature.ts

@@ -6,6 +6,7 @@ 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 { 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";
@@ -129,6 +130,10 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
       ),
     };
 
+    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
@@ -141,6 +146,6 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
       revokeAllOtherSessions = revoker;
     };
 
-    return { handlers, bindRevokeAllOtherSessions, checkMfaStatus };
+    return { handlers, queries, bindRevokeAllOtherSessions, checkMfaStatus };
   });
 }

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

@@ -46,7 +46,9 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
         {
           userId: event.user.id,
           totpSecret: verify.payload.totpSecretBase32,
-          recoveryCodes: { hashes: verify.payload.recoveryCodeHashes },
+          // Stored as a JSON string — see schema/user-mfa.ts (recoveryCodes
+          // is an encrypted+userOwned text field, both layers need a string).
+          recoveryCodes: JSON.stringify({ hashes: verify.payload.recoveryCodeHashes }),
           enabledAt: Temporal.Now.instant(),
           lastUsedAt: null,
         },

package/src/auth-mfa/handlers/reencrypt.job.ts

@@ -1,12 +1,20 @@
-// KEK-rotation job for userMfa.totpSecret (entity-field encryption, same
-// MasterKeyProvider as secrets/config — see schema/user-mfa.ts). Modeled
-// directly on config/handlers/reencrypt.job.ts: entity-field encryption
-// stores a StoredEnvelope JSON string per value (no separate kekVersion
-// column, unlike secrets' DEK-wrap model), so rotation means decrypt under
-// the OLD key, then let the executor's own write-path re-encrypt under
-// provider.currentVersion() — the same auto-encrypt every enable-confirm
-// write already goes through (see enable-confirm.write.ts: it passes
-// PLAINTEXT to executor.create, never a manually-built envelope).
+// KEK-rotation job for userMfa.totpSecret + recoveryCodes (entity-field
+// encryption, same MasterKeyProvider as secrets/config — see
+// schema/user-mfa.ts). Modeled directly on config/handlers/reencrypt.job.ts:
+// entity-field encryption stores a StoredEnvelope JSON string per value (no
+// separate kekVersion column, unlike secrets' DEK-wrap model), so rotation
+// means decrypt under the OLD key, then let the executor's own write-path
+// re-encrypt under provider.currentVersion() — the same auto-encrypt every
+// enable-confirm write already goes through (see enable-confirm.write.ts: it
+// passes PLAINTEXT to executor.create, never a manually-built envelope).
+//
+// Both fields also carry `userOwned` — the executor's own encryptForStorage
+// wraps them PII(envelope(plaintext)) (see event-store-executor-context.ts).
+// This job reads raw rows via selectMany (bypassing the executor's
+// decryptForRead), so it must peel that PII layer itself before the envelope
+// cipher ever sees the value, mirroring decryptForRead's PII-then-envelope
+// order — an envelope decrypt on a still-PII-wrapped string throws
+// "legacy single-key format" instead of rotating anything.
 //
 // Idempotent: re-running skips rows already on the current kekVersion.
 // Every write is a normal executor.update — after a full run even a
@@ -16,6 +24,11 @@
 // projection instead of appending a real `.updated` event).
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  collectPiiSubjectFields,
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import {
   configuredEntityFieldEncryption,
   createEventStoreExecutor,
@@ -37,6 +50,8 @@ const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
   entityName: "user-mfa",
 });
 
+const piiFieldNames = collectPiiSubjectFields(userMfaEntity);
+
 export type MfaReencryptJobPayload = {
   readonly batchSize?: number;
   readonly maxDurationMs?: number;
@@ -91,6 +106,9 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
     });
   }
   const db = ctx.db as DbConnection; // @cast-boundary db-operator
+  // Undefined = per-subject crypto-shredding isn't configured for this app —
+  // both fields are then plain envelope strings, no PII layer to peel.
+  const piiKms = configuredPiiSubjectKms();
 
   const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
   const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
@@ -113,6 +131,7 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
     tenantId: string;
     version: number;
     totpSecret: string;
+    recoveryCodes: string;
   };
 
   let alreadyCurrent = 0;
@@ -131,22 +150,43 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
   }
 
   async function migrateRow(row: UserMfaRow): Promise<"migrated" | "skipped" | "failed"> {
-    if (!needsReencrypt(row.totpSecret, targetVersion)) {
+    const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+
+    // Peel the PII layer first (if active) so needsReencrypt/cipher.decrypt
+    // below only ever see envelope strings, same order as decryptForRead.
+    let envelopeValues: { totpSecret: string; recoveryCodes: string } = row;
+    if (piiKms) {
+      const unwrapped = await decryptPiiFieldValues(row, piiFieldNames, piiKms, {
+        requestId: "auth-mfa-reencrypt-job",
+        tenantId,
+      });
+      envelopeValues = unwrapped as { totpSecret: string; recoveryCodes: string }; // @cast-boundary engine-payload
+    }
+
+    const totpNeedsRotation = needsReencrypt(envelopeValues.totpSecret, targetVersion);
+    const recoveryNeedsRotation = needsReencrypt(envelopeValues.recoveryCodes, targetVersion);
+    if (!totpNeedsRotation && !recoveryNeedsRotation) {
       alreadyCurrent++;
       return "skipped";
     }
 
-    const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
     // decrypt failure (missing legacy key, unknown kekVersion, tamper)
     // throws → counted as failed via onRowError; the row stays untouched.
-    const plaintext = await cipher.decrypt(row.totpSecret, { tenantId });
+    const changes: Record<string, string> = {};
+    if (totpNeedsRotation) {
+      changes["totpSecret"] = await cipher.decrypt(envelopeValues.totpSecret, { tenantId });
+    }
+    if (recoveryNeedsRotation) {
+      changes["recoveryCodes"] = await cipher.decrypt(envelopeValues.recoveryCodes, { tenantId });
+    }
 
     const actor: SessionUser = { id: "system", tenantId, roles: SYSTEM_ROLES };
     // PLAINTEXT here, not a manually-built envelope — the executor's own
     // write-path (encryptForStorage) re-encrypts under the CURRENT
-    // injected cipher/KEK, exactly like every other write to this field.
+    // injected cipher/KEK (and re-wraps the PII layer under the same,
+    // unrotated subject DEK), exactly like every other write to this field.
     const result = await executor.update(
-      { id: row.id, version: row.version, changes: { totpSecret: plaintext } },
+      { id: row.id, version: row.version, changes },
       actor,
       tdbFor(tenantId),
     );

package/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -44,7 +44,7 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
         {
           id: row.id,
           version: row.version,
-          changes: { recoveryCodes: { hashes: newHashes } },
+          changes: { recoveryCodes: JSON.stringify({ hashes: newHashes }) },
         },
         event.user,
         ctx.db,

package/src/auth-mfa/handlers/status.query.ts

@@ -0,0 +1,23 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { userMfaTable } from "../schema/user-mfa";
+
+// "Is MFA enabled for me" — the one thing a settings screen needs before it
+// can decide whether to show the enrollment flow or the disable/regenerate
+// actions. No client-side signal (session/JWT) carries this today, so
+// without this query every app builds its own row-existence check via a
+// side channel. Plain fetchOne — no need for the entity's decrypting
+// executor.detail() (see db/queries.ts's findUserMfaRow), existence is all
+// the caller wants.
+export const mfaStatusQuery = defineQueryHandler({
+  name: "user-mfa:status",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const row = await fetchOne<{ id: string }>(ctx.db, userMfaTable, {
+      userId: query.user.id,
+    });
+    return { enabled: row !== undefined };
+  },
+});

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

@@ -94,7 +94,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
           {
             id: row.id,
             version: row.version,
-            changes: { recoveryCodes: { hashes: verify.remainingHashes } },
+            changes: { recoveryCodes: JSON.stringify({ hashes: verify.remainingHashes }) },
           },
           scopedUser,
           scopedDb,

package/src/auth-mfa/index.ts

@@ -1,6 +1,11 @@
 export { base32Decode } from "./base32";
 export { type MfaRequiredPolicy, mfaRequiredConfigHandle } from "./config";
-export { AUTH_MFA_FEATURE, AuthMfaHandlers, MFA_ENABLE_SCREEN_ID } from "./constants";
+export {
+  AUTH_MFA_FEATURE,
+  AuthMfaHandlers,
+  AuthMfaQueries,
+  MFA_ENABLE_SCREEN_ID,
+} from "./constants";
 export type {
   AuthMfaFeatureOptions,
   BindMfaRevokeAllOtherSessions,

package/src/auth-mfa/schema/user-mfa.ts

@@ -1,7 +1,6 @@
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
-  createJsonbField,
   createTextField,
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -27,10 +26,18 @@ export const userMfaEntity = createEntity({
       encrypted: true,
       userOwned: { ownerField: "userId" },
     }),
-    // { hashes: string[] } — argon2id hashes of unredeemed recovery codes.
+    // JSON-stringified `{ hashes: string[] }` (argon2id hashes of unredeemed
+    // recovery codes) — both encryption layers (entity-field envelope +
+    // per-subject crypto-shred, same as totpSecret above) require a string
+    // value, so callers JSON.stringify on write and JSON.parse on read
+    // (see db/queries.ts's findUserMfaRow) rather than storing jsonb here.
     // A redeemed code's hash is removed from the array (see disable/regen
     // handlers), so array length also IS the remaining-codes count.
-    recoveryCodes: createJsonbField({ userOwned: { ownerField: "userId" } }),
+    recoveryCodes: createTextField({
+      required: true,
+      encrypted: true,
+      userOwned: { ownerField: "userId" },
+    }),
     enabledAt: createTimestampField({ required: true }),
     lastUsedAt: createTimestampField(),
   },

package/src/auth-mfa/web/i18n.ts

@@ -35,6 +35,25 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.enable.cancel": "Abbrechen",
     "auth.mfa.enable.confirm": "Aktivieren",
     "auth.mfa.enable.success": "Zwei-Faktor-Authentifizierung ist jetzt aktiv.",
+    "auth.mfa.disable.title": "Zwei-Faktor-Authentifizierung deaktivieren",
+    "auth.mfa.disable.description":
+      "Bestätige mit einem Code aus deiner Authenticator-App oder einem Recovery-Code. Dein Konto ist danach nur noch durch dein Passwort geschützt.",
+    "auth.mfa.disable.code": "Code aus der Authenticator-App oder Recovery-Code",
+    "auth.mfa.disable.confirm": "Deaktivieren",
+    "auth.mfa.disable.cancel": "Abbrechen",
+    "auth.mfa.disable.trigger": "Zwei-Faktor-Authentifizierung deaktivieren",
+    "auth.mfa.regenerate.title": "Neue Recovery-Codes erzeugen",
+    "auth.mfa.regenerate.description":
+      "Bestätige mit einem Code aus deiner Authenticator-App. Alle bisherigen Recovery-Codes werden sofort ungültig.",
+    "auth.mfa.regenerate.code": "Code aus der Authenticator-App",
+    "auth.mfa.regenerate.confirm": "Neu erzeugen",
+    "auth.mfa.regenerate.cancel": "Abbrechen",
+    "auth.mfa.regenerate.trigger": "Neue Recovery-Codes erzeugen",
+    "auth.mfa.regenerate.newCodesTitle": "Deine neuen Recovery-Codes",
+    "auth.mfa.regenerate.newCodesHint":
+      "Speichere diese Codes an einem sicheren Ort. Die alten Codes funktionieren ab sofort nicht mehr.",
+    "auth.mfa.regenerate.acknowledge": "Ich habe die neuen Recovery-Codes gespeichert.",
+    "auth.mfa.regenerate.done": "Fertig",
   },
   en: {
     "screen:auth-mfa-enable.title": "Two-factor authentication",
@@ -65,6 +84,25 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.enable.cancel": "Cancel",
     "auth.mfa.enable.confirm": "Enable",
     "auth.mfa.enable.success": "Two-factor authentication is now enabled.",
+    "auth.mfa.disable.title": "Disable two-factor authentication",
+    "auth.mfa.disable.description":
+      "Confirm with a code from your authenticator app or a recovery code. Your account will then be protected by your password alone.",
+    "auth.mfa.disable.code": "Code from your authenticator app or a recovery code",
+    "auth.mfa.disable.confirm": "Disable",
+    "auth.mfa.disable.cancel": "Cancel",
+    "auth.mfa.disable.trigger": "Disable two-factor authentication",
+    "auth.mfa.regenerate.title": "Generate new recovery codes",
+    "auth.mfa.regenerate.description":
+      "Confirm with a code from your authenticator app. All existing recovery codes stop working immediately.",
+    "auth.mfa.regenerate.code": "Code from your authenticator app",
+    "auth.mfa.regenerate.confirm": "Generate new codes",
+    "auth.mfa.regenerate.cancel": "Cancel",
+    "auth.mfa.regenerate.trigger": "Generate new recovery codes",
+    "auth.mfa.regenerate.newCodesTitle": "Your new recovery codes",
+    "auth.mfa.regenerate.newCodesHint":
+      "Save these codes somewhere safe. The old codes stop working immediately.",
+    "auth.mfa.regenerate.acknowledge": "I've saved my new recovery codes.",
+    "auth.mfa.regenerate.done": "Done",
   },
 };
 

package/src/auth-mfa/web/index.ts

@@ -9,7 +9,14 @@ export { authMfaClient } from "./client-plugin";
 export { defaultTranslations, mergeTranslations } from "./i18n";
 export type { MfaVerifyResult } from "./mfa-client";
 export { verifyMfaChallenge } from "./mfa-client";
+export type { MfaDisableDialogProps } from "./mfa-disable-dialog";
+export { MfaDisableDialog } from "./mfa-disable-dialog";
 export type { MfaEnableScreenProps } from "./mfa-enable-screen";
 export { MfaEnableScreen } from "./mfa-enable-screen";
+export { mfaManageErrorKey } from "./mfa-error-keys";
+export type { MfaRecoveryCodesRevealProps } from "./mfa-recovery-codes-reveal";
+export { MfaRecoveryCodesReveal } from "./mfa-recovery-codes-reveal";
+export type { MfaRegenerateRecoveryDialogProps } from "./mfa-regenerate-recovery-dialog";
+export { MfaRegenerateRecoveryDialog } from "./mfa-regenerate-recovery-dialog";
 export type { MfaVerifyScreenProps } from "./mfa-verify-screen";
 export { MfaVerifyScreen } from "./mfa-verify-screen";

package/src/auth-mfa/web/mfa-disable-dialog.tsx

@@ -0,0 +1,70 @@
+// @runtime client
+// MfaDisableDialog — confirm-with-code before turning MFA off. Uses the
+// generic Dialog primitive (unlike MfaEnableScreen/MfaRegenerateRecovery-
+// Dialog): disable is single-step, no state to preserve after confirm, so
+// it doesn't hit the "Dialog always closes after onConfirm" problem that
+// ruled Dialog out for the multi-step enable/regenerate flows. Error
+// reporting still has to go through the parent (onError) rather than an
+// inline Banner, because Dialog closes in a `finally` regardless of
+// whether onConfirm's write succeeded — see profile-screen.tsx's
+// delete-account dialog for the same convention (StatusBanner rendered
+// by the caller, not the dialog).
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthMfaHandlers } from "../constants";
+import { mfaManageErrorKey } from "./mfa-error-keys";
+
+export type MfaDisableDialogProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly onDisabled: () => void;
+  readonly onError: (i18nKey: string) => void;
+};
+
+export function MfaDisableDialog({
+  open,
+  onOpenChange,
+  onDisabled,
+  onError,
+}: MfaDisableDialogProps): ReactNode {
+  const t = useTranslation();
+  const { Dialog, Field, Input } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [code, setCode] = useState("");
+
+  const confirm = async (): Promise<void> => {
+    const res = await dispatcher.write<{ disabled: boolean }>(AuthMfaHandlers.disable, { code });
+    setCode("");
+    if (!res.isSuccess) {
+      onError(mfaManageErrorKey(res.error.code));
+      return;
+    }
+    onDisabled();
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      variant="danger"
+      title={t("auth.mfa.disable.title")}
+      description={t("auth.mfa.disable.description")}
+      confirmLabel={t("auth.mfa.disable.confirm")}
+      cancelLabel={t("auth.mfa.disable.cancel")}
+      onConfirm={confirm}
+      testId="mfa-disable-dialog"
+    >
+      <Field id="mfa-disable-code" label={t("auth.mfa.disable.code")} required>
+        <Input
+          kind="text"
+          id="mfa-disable-code"
+          name="mfa-disable-code"
+          value={code}
+          onChange={setCode}
+          autoComplete="one-time-code"
+        />
+      </Field>
+    </Dialog>
+  );
+}

package/src/auth-mfa/web/mfa-enable-screen.tsx

@@ -14,6 +14,7 @@ import { type ReactNode, useState } from "react";
 // kumiko-lint-ignore cross-feature-import client-only hook, the feature's server barrel has no web/ re-export
 import { useSession } from "../../auth-email-password/web";
 import { AuthMfaHandlers } from "../constants";
+import { mfaManageErrorKey } from "./mfa-error-keys";
 
 type EnableStartResponse = {
   readonly setupToken: string;
@@ -35,9 +36,20 @@ function extractSecret(otpauthUri: string): string {
   return new URLSearchParams(query).get("secret") ?? "";
 }
 
-export type MfaEnableScreenProps = { readonly embedded?: boolean };
+export type MfaEnableScreenProps = {
+  readonly embedded?: boolean;
+  // Fired once enable-confirm succeeds — MfaEnableScreen has no query of its
+  // own to invalidate, so a host screen composing it alongside other MFA
+  // state (e.g. a status query gating which section renders) needs this to
+  // know when to refetch/swap views instead of leaving the success banner
+  // as a dead end.
+  readonly onEnabled?: () => void;
+};
 
-export function MfaEnableScreen({ embedded = false }: MfaEnableScreenProps = {}): ReactNode {
+export function MfaEnableScreen({
+  embedded = false,
+  onEnabled,
+}: MfaEnableScreenProps = {}): ReactNode {
   const t = useTranslation();
   const { Button, Banner, Field, Input, Section, Heading } = usePrimitives();
   const dispatcher = useDispatcher();
@@ -88,6 +100,7 @@ export function MfaEnableScreen({ embedded = false }: MfaEnableScreenProps = {})
     }
     setEnabled(true);
     setSetup(null);
+    onEnabled?.();
   };
 
   const content = (
@@ -95,7 +108,7 @@ export function MfaEnableScreen({ embedded = false }: MfaEnableScreenProps = {})
       <Heading>{t("auth.mfa.enable.title")}</Heading>
 
       {enabled && <Banner variant="info">{t("auth.mfa.enable.success")}</Banner>}
-      {error !== null && <Banner variant="error">{t(`auth.mfa.errors.${error}`)}</Banner>}
+      {error !== null && <Banner variant="error">{t(mfaManageErrorKey(error))}</Banner>}
 
       {!setup && !enabled && (
         <Section

package/src/auth-mfa/web/mfa-error-keys.ts

@@ -0,0 +1,25 @@
+// @runtime client
+// Shared error-code → i18n-key mapping for the account-management write
+// handlers (enable-confirm/disable/regenerate-recovery) — distinct from
+// mfa-verify-screen.tsx's own mapper, which covers the login-challenge
+// error surface (challenge_expired/rate_limited) that these handlers never
+// return. Centralized so enable/disable/regenerate stay in sync instead of
+// each re-deriving the key ad hoc (enable-screen used to template-string
+// the raw snake_case code straight into the key, which never matched the
+// camelCase keys actually registered below).
+export function mfaManageErrorKey(code: string): string {
+  switch (code) {
+    case "invalid_totp_code":
+      return "auth.mfa.errors.invalidCode";
+    case "invalid_recovery_code":
+      return "auth.mfa.errors.invalidRecoveryCode";
+    case "mfa_already_enabled":
+      return "auth.mfa.errors.mfaAlreadyEnabled";
+    case "mfa_not_enabled":
+      return "auth.mfa.errors.mfaNotEnabled";
+    case "invalid_setup_token":
+      return "auth.mfa.errors.invalidSetupToken";
+    default:
+      return "auth.mfa.errors.verifyFailed";
+  }
+}

package/src/auth-mfa/web/mfa-recovery-codes-reveal.tsx

@@ -0,0 +1,53 @@
+// @runtime client
+// MfaRecoveryCodesReveal — one-time display of a fresh recovery-code set,
+// with an acknowledge-then-dismiss gate (same UX as the codes block in
+// MfaEnableScreen). Standalone so MfaRegenerateRecoveryDialog's caller can
+// render it after the dialog closes — the codes only exist in memory for
+// this one render, never persisted anywhere the app could show them again.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+
+export type MfaRecoveryCodesRevealProps = {
+  readonly codes: readonly string[];
+  readonly onDismiss: () => void;
+};
+
+export function MfaRecoveryCodesReveal({
+  codes,
+  onDismiss,
+}: MfaRecoveryCodesRevealProps): ReactNode {
+  const t = useTranslation();
+  const { Button, Field, Input, Section } = usePrimitives();
+  const [acknowledged, setAcknowledged] = useState(false);
+
+  return (
+    <Section
+      testId="mfa-regenerate-reveal"
+      actions={
+        <Button variant="primary" onClick={onDismiss} disabled={!acknowledged}>
+          {t("auth.mfa.regenerate.done")}
+        </Button>
+      }
+    >
+      <div className="flex flex-col items-center gap-2 text-center">
+        <span className="text-sm font-semibold">{t("auth.mfa.regenerate.newCodesTitle")}</span>
+        <span className="text-xs text-muted-foreground">
+          {t("auth.mfa.regenerate.newCodesHint")}
+        </span>
+        <code className="inline-block whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+          {codes.join("\n")}
+        </code>
+      </div>
+      <Field id="mfa-regenerate-ack" label={t("auth.mfa.regenerate.acknowledge")}>
+        <Input
+          kind="boolean"
+          id="mfa-regenerate-ack"
+          name="mfa-regenerate-ack"
+          value={acknowledged}
+          onChange={setAcknowledged}
+        />
+      </Field>
+    </Section>
+  );
+}

package/src/auth-mfa/web/mfa-regenerate-recovery-dialog.tsx

@@ -0,0 +1,69 @@
+// @runtime client
+// MfaRegenerateRecoveryDialog — confirm-with-code, then the caller reveals
+// the new codes. The reveal itself can't live inside this Dialog: Dialog
+// closes in a `finally` right after onConfirm resolves (see profile-screen.
+// tsx's delete-account dialog for the same constraint), so there's no way
+// to keep it open to show the result. onRegenerated hands the new codes to
+// the caller, which is expected to render them via MfaRecoveryCodesReveal
+// (or equivalent) once the dialog has closed.
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthMfaHandlers } from "../constants";
+import { mfaManageErrorKey } from "./mfa-error-keys";
+
+export type MfaRegenerateRecoveryDialogProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly onRegenerated: (codes: readonly string[]) => void;
+  readonly onError: (i18nKey: string) => void;
+};
+
+export function MfaRegenerateRecoveryDialog({
+  open,
+  onOpenChange,
+  onRegenerated,
+  onError,
+}: MfaRegenerateRecoveryDialogProps): ReactNode {
+  const t = useTranslation();
+  const { Dialog, Field, Input } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [code, setCode] = useState("");
+
+  const confirm = async (): Promise<void> => {
+    const res = await dispatcher.write<{ recoveryCodes: readonly string[] }>(
+      AuthMfaHandlers.regenerateRecovery,
+      { code },
+    );
+    setCode("");
+    if (!res.isSuccess) {
+      onError(mfaManageErrorKey(res.error.code));
+      return;
+    }
+    onRegenerated(res.data.recoveryCodes);
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      title={t("auth.mfa.regenerate.title")}
+      description={t("auth.mfa.regenerate.description")}
+      confirmLabel={t("auth.mfa.regenerate.confirm")}
+      cancelLabel={t("auth.mfa.regenerate.cancel")}
+      onConfirm={confirm}
+      testId="mfa-regenerate-recovery-dialog"
+    >
+      <Field id="mfa-regenerate-code" label={t("auth.mfa.regenerate.code")} required>
+        <Input
+          kind="text"
+          id="mfa-regenerate-code"
+          name="mfa-regenerate-code"
+          value={code}
+          onChange={setCode}
+          autoComplete="one-time-code"
+        />
+      </Field>
+    </Dialog>
+  );
+}