@cosmicdrift/kumiko-bundled-features 0.149.0 → 0.149.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.149.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.149.0",
-    "@cosmicdrift/kumiko-framework": "0.149.0",
-    "@cosmicdrift/kumiko-headless": "0.149.0",
-    "@cosmicdrift/kumiko-renderer": "0.149.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.149.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__/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/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/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/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/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/mfa-enable-screen.tsx

@@ -36,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();
@@ -89,6 +100,7 @@ export function MfaEnableScreen({ embedded = false }: MfaEnableScreenProps = {})
     }
     setEnabled(true);
     setSetup(null);
+    onEnabled?.();
   };
 
   const content = (