@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/src/bun-db/__tests__/select-many-retry.test.ts

@@ -0,0 +1,79 @@
+// #1163: Bun.SQL can hand out a closed connection under load (AbortError
+// "The connection was closed."). Pure reads retry exactly once on a fresh
+// pool checkout; tx handles, non-matching errors, and genuine user aborts
+// must NOT retry.
+
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "../../db/table-builder";
+import { selectMany } from "../query";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin?: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[], opts: { tx?: boolean } = {}): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [{ id: "r1", title: "ok", tenant_id: "t1", inserted_at: null, updated_at: null }];
+    },
+  };
+  // A top-level pool client has begin(); a transaction handle does not.
+  if (!opts.tx)
+    client.begin = () => {
+      throw new Error("not used in test");
+    };
+  return client;
+}
+
+const table = buildEntityTable("note", {
+  fields: { title: { type: "text", required: true } },
+});
+
+describe("selectMany — closed-connection retry (#1163)", () => {
+  test("retries once on AbortError 'connection was closed' and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()]);
+    const rows = await selectMany(db, table);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.title).toBe("ok");
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()]);
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(2);
+  });
+
+  test("never retries on a transaction handle (no begin)", async () => {
+    const db = fakeClient([closedConnectionError()], { tx: true });
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry a genuine user abort (different message)", async () => {
+    const userAbort = Object.assign(new Error("The operation was aborted."), {
+      name: "AbortError",
+    });
+    const db = fakeClient([userAbort]);
+    await expect(selectMany(db, table)).rejects.toThrow("operation was aborted");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry generic query errors", async () => {
+    const syntax = Object.assign(new Error("syntax error at or near"), { name: "PostgresError" });
+    const db = fakeClient([syntax]);
+    await expect(selectMany(db, table)).rejects.toThrow("syntax error");
+    expect(db.calls).toBe(1);
+  });
+});

package/src/bun-db/query.ts

@@ -562,6 +562,38 @@ function buildWhereClause(
   return { sqlText: conditions.join(" AND "), values };
 }
 
+// #1163: under load the Bun.SQL pool can hand out a connection the server
+// already closed ("The connection was closed.", AbortError code 20) — no
+// validate-on-checkout exists. One retry re-checks out a fresh connection;
+// safe for pure reads. Tx handles are never retried: their transaction is
+// dead once the connection dropped, and a retry would run on the same dead
+// handle. Detection is name+message (not name alone) so a genuine user
+// abort (AbortSignal cancel) is NOT retried.
+function isClosedConnectionError(err: unknown): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const e = err as { name?: unknown; message?: unknown };
+  return (
+    e.name === "AbortError" &&
+    typeof e.message === "string" &&
+    /connection was closed/i.test(e.message)
+  );
+}
+
+async function unsafeRead<TRow>(
+  db: AnyDb,
+  sqlText: string,
+  params: readonly unknown[],
+): Promise<readonly TRow[]> {
+  const raw = asRawClient(db);
+  try {
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  } catch (err) {
+    // TransactionSql has savepoint(), only a top-level pool client has begin().
+    if (typeof raw.begin !== "function" || !isClosedConnectionError(err)) throw err;
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  }
+}
+
 // biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
 export async function selectMany<TRow = any>(
   db: AnyDb,
@@ -598,7 +630,7 @@ export async function selectMany<TRow = any>(
     }
     sqlText += ` LIMIT ${options.limit}`;
   }
-  const raw = (await asRawClient(db).unsafe(sqlText, values)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeRead(db, sqlText, values)) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -832,7 +864,7 @@ export async function countWhere(
     sqlText += ` WHERE ${w.sqlText}`;
     values = w.values;
   }
-  const rows = (await asRawClient(db).unsafe(sqlText, values)) as readonly { count: number }[];
+  const rows = (await unsafeRead(db, sqlText, values)) as readonly { count: number }[];
   return rows[0]?.count ?? 0;
 }
 

package/src/consumer-cli.ts

@@ -0,0 +1,87 @@
+// Shared core for the standalone consumer-ops CLI (status | restart).
+//
+// A dead event consumer (halt-on-poison after maxAttempts) previously had no
+// recovery surface in the standalone prod bundle — only raw SQL against
+// kumiko_event_consumers. Mirrors schema-cli.ts's shape (single runXCli(argv,
+// out) entry point, own DB connection) so `kumiko-consumer` ships the same
+// way `kumiko-schema` does.
+
+import { createDbConnection } from "./db";
+import { getConsumerState, restartConsumer } from "./pipeline";
+import { ensureTemporalPolyfill } from "./time";
+
+export type ConsumerCliOut = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+function parseInstanceIdFlag(argv: readonly string[]): string | undefined {
+  const i = argv.indexOf("--instance-id");
+  return i === -1 ? undefined : argv[i + 1];
+}
+
+export async function runConsumerCli(
+  argv: readonly string[],
+  out: ConsumerCliOut,
+): Promise<number> {
+  // The standalone bundle never runs runProdApp/runDevApp's boot, which is
+  // where Temporal normally gets installed — ConsumerRecoveryState.updatedAt
+  // is a Temporal.Instant, so without this every subcommand throws "Temporal
+  // is not defined" (same failure mode as schema-cli, see its polyfill test).
+  await ensureTemporalPolyfill();
+  const sub = argv[0];
+
+  if (sub !== "status" && sub !== "restart") {
+    out.log("");
+    out.log("  Subcommands:");
+    out.log("    status <name> [--instance-id <id>]   Zeigt Status + Cursor eines Consumers");
+    out.log("    restart <name> [--instance-id <id>]  Reaktiviert einen dead-Consumer (idle)");
+    out.log("");
+    return sub === undefined ? 0 : 1;
+  }
+
+  const name = argv[1];
+  if (!name) {
+    out.err(`  Usage: consumer ${sub} <name> [--instance-id <id>]`);
+    return 1;
+  }
+  const instanceId = parseInstanceIdFlag(argv);
+
+  const dbUrl = process.env["DATABASE_URL"];
+  if (!dbUrl) {
+    out.err("  DATABASE_URL not set.");
+    return 1;
+  }
+  const { db, close } = createDbConnection(dbUrl);
+  try {
+    if (sub === "status") {
+      const state = await getConsumerState(db, name, instanceId);
+      if (!state) {
+        out.err(`  Consumer "${name}" (instance_id="${instanceId ?? "__shared__"}") not found.`);
+        return 1;
+      }
+      out.log("");
+      out.log(`  ${state.name} (instance_id="${state.instanceId}")`);
+      out.log(`    status:      ${state.status}`);
+      out.log(`    cursor:      ${state.lastProcessedEventId}`);
+      out.log(`    attempts:    ${state.attempts}`);
+      out.log(`    rearmCount:  ${state.rearmCount}`);
+      out.log(`    lastError:   ${state.lastError ?? "-"}`);
+      out.log(`    updatedAt:   ${state.updatedAt.toString()}`);
+      out.log("");
+      return 0;
+    }
+
+    // restart
+    const result = await restartConsumer(db, name, instanceId);
+    out.log("");
+    out.log(`  ✓ ${result.name} (instance_id="${result.instanceId}") → ${result.status}`);
+    out.log("");
+    return 0;
+  } catch (e) {
+    out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  } finally {
+    await close();
+  }
+}

package/src/crypto/__tests__/pii-field-encryption.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { createCipheriv, randomBytes } from "node:crypto";
 import { createEntity, createTextField } from "../../engine/factories";
 import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
 import {
@@ -62,7 +63,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
 
     const stored = await encryptPiiFieldValues(row, userLikeEntity, fields, kms, KMS_CTX);
     expect(isPiiCiphertext(stored["email"])).toBe(true);
-    expect(String(stored["email"])).toStartWith(`kumiko-pii:v1:user:${UUID_A}:`);
+    expect(String(stored["email"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_A}:`);
     expect(stored["role"]).toBe("admin");
     expect(row["email"]).toBe("marc@example.com");
 
@@ -95,7 +96,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       kms,
       KMS_CTX,
     );
-    expect(String(stored["body"])).toStartWith(`kumiko-pii:v1:user:${UUID_B}:`);
+    expect(String(stored["body"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_B}:`);
   });
 
   test("tenantOwned without tenantId column falls back to write-time tenant", async () => {
@@ -108,7 +109,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       KMS_CTX,
       { tenantId: UUID_B },
     );
-    expect(String(stored["brandColor"])).toStartWith(`kumiko-pii:v1:tenant:${UUID_B}:`);
+    expect(String(stored["brandColor"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}tenant:${UUID_B}:`);
   });
 
   test("subjectSource resolves the owner when the partial row lacks it (update changes)", async () => {
@@ -118,7 +119,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       onlyKeys: ["body"],
       subjectSource: { id: UUID_A, body: "edited", authorId: UUID_B },
     });
-    expect(String(stored["body"])).toStartWith(`kumiko-pii:v1:user:${UUID_B}:`);
+    expect(String(stored["body"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_B}:`);
   });
 
   test("erased subject: decrypt yields the sentinel, re-encrypt passes it through", async () => {
@@ -243,7 +244,7 @@ describe("piiEncrypted alias (kumiko-platform#457)", () => {
     const row = { id: UUID_A, tenantId: UUID_B, iban: "DE89370400440532013000" };
     const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX);
     expect(isPiiCiphertext(stored["iban"])).toBe(true);
-    expect(String(stored["iban"])).toStartWith(`kumiko-pii:v1:tenant:${UUID_B}:`);
+    expect(String(stored["iban"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}tenant:${UUID_B}:`);
 
     const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
     expect(read["iban"]).toBe("DE89370400440532013000");
@@ -274,27 +275,39 @@ describe("encryptPiiValueForSubject / decryptPiiValueForSubject (kumiko-platform
   test("round-trips a single value for a tenant subject", async () => {
     const kms = new InMemoryKmsAdapter();
     const subject = { kind: "tenant" as const, tenantId: UUID_B };
-    const stored = await encryptPiiValueForSubject(kms, subject, "DE89370400440532013000", KMS_CTX);
+    const stored = await encryptPiiValueForSubject(
+      kms,
+      subject,
+      "DE89370400440532013000",
+      KMS_CTX,
+      "iban",
+    );
     expect(isPiiCiphertext(stored)).toBe(true);
-    expect(stored).toStartWith(`kumiko-pii:v1:tenant:${UUID_B}:`);
+    expect(stored).toStartWith(`${PII_CIPHERTEXT_PREFIX}tenant:${UUID_B}:`);
 
-    const read = await decryptPiiValueForSubject(kms, stored, KMS_CTX);
+    const read = await decryptPiiValueForSubject(kms, stored, KMS_CTX, "iban");
     expect(read).toBe("DE89370400440532013000");
   });
 
   test("erased subject: decrypt yields the sentinel", async () => {
     const kms = new InMemoryKmsAdapter();
     const subject = { kind: "user" as const, userId: UUID_A };
-    const stored = await encryptPiiValueForSubject(kms, subject, "+49 151 00000000", KMS_CTX);
+    const stored = await encryptPiiValueForSubject(
+      kms,
+      subject,
+      "+49 151 00000000",
+      KMS_CTX,
+      "phone",
+    );
     await kms.eraseKey(subject);
 
-    const read = await decryptPiiValueForSubject(kms, stored, KMS_CTX);
+    const read = await decryptPiiValueForSubject(kms, stored, KMS_CTX, "phone");
     expect(read).toBe(PII_ERASED_SENTINEL);
   });
 
   test("plaintext passes through decrypt unchanged (pre-engine rows)", async () => {
     const kms = new InMemoryKmsAdapter();
-    const read = await decryptPiiValueForSubject(kms, "plain-value", KMS_CTX);
+    const read = await decryptPiiValueForSubject(kms, "plain-value", KMS_CTX, "value");
     expect(read).toBe("plain-value");
   });
 });
@@ -308,13 +321,56 @@ describe("cross-subject decrypt leak (kumiko-framework#1190)", () => {
     // existing "ciphertext without a key row fails loud" (KeyNotFoundError) case.
     await kms.createKey(subjectA);
 
-    const storedForB = await encryptPiiValueForSubject(kms, subjectB, "tenant-b-secret", KMS_CTX);
+    const storedForB = await encryptPiiValueForSubject(
+      kms,
+      subjectB,
+      "tenant-b-secret",
+      KMS_CTX,
+      "secret",
+    );
     const blob = storedForB.slice(storedForB.lastIndexOf(":") + 1);
     const forgedForA = `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subjectA)}:${blob}`;
 
-    const attempt = decryptPiiValueForSubject(kms, forgedForA, KMS_CTX);
+    const attempt = decryptPiiValueForSubject(kms, forgedForA, KMS_CTX, "secret");
     await expect(attempt).rejects.not.toBeInstanceOf(KeyNotFoundError);
     await expect(attempt).rejects.not.toBeInstanceOf(KeyErasedError);
     await expect(attempt).rejects.toThrow();
   });
 });
+
+describe("cross-field decrypt leak (kumiko-framework#1263)", () => {
+  test("ciphertext cut-and-pasted into a different field of the SAME subject fails GCM auth", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const subject = { kind: "user" as const, userId: UUID_A };
+    const storedAsEmail = await encryptPiiValueForSubject(
+      kms,
+      subject,
+      "secret@example.com",
+      KMS_CTX,
+      "email",
+    );
+
+    // Same subject, same DEK — only the declared field differs. Key
+    // selection alone can't catch this; AAD must.
+    const attempt = decryptPiiValueForSubject(kms, storedAsEmail, KMS_CTX, "phone");
+    await expect(attempt).rejects.toThrow();
+  });
+
+  test("legacy v1 ciphertext (no AAD) still decrypts under the matching subject/field", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const subject = { kind: "user" as const, userId: UUID_A };
+    await kms.createKey(subject);
+    const dek = await kms.getKey(subject);
+
+    // Hand-roll a pre-#1263 v1 blob (no setAAD) — real pre-migration rows
+    // look exactly like this.
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", dek, iv);
+    const ciphertext = Buffer.concat([cipher.update("legacy-value", "utf8"), cipher.final()]);
+    const blob = Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
+    const v1 = `kumiko-pii:v1:${subjectIdToKey(subject)}:${blob.toString("base64")}`;
+
+    const read = await decryptPiiValueForSubject(kms, v1, KMS_CTX, "email");
+    expect(read).toBe("legacy-value");
+  });
+});

package/src/crypto/blind-index.ts

@@ -93,22 +93,26 @@ export async function computeBlindIndexValues(
   const out: Record<string, unknown> = {};
   for (const name of lookupableFields) {
     if (!(name in values)) continue;
-    out[blindIndexFieldName(name)] = await blindIndexForValue(key, values[name]);
+    out[blindIndexFieldName(name)] = await blindIndexForValue(key, name, values[name]);
   }
   return out;
 }
 
-async function blindIndexForValue(key: Uint8Array, value: unknown): Promise<string | null> {
+async function blindIndexForValue(
+  key: Uint8Array,
+  field: string,
+  value: unknown,
+): Promise<string | null> {
   if (typeof value !== "string" || value === PII_ERASED_SENTINEL) return null;
   if (!isPiiCiphertext(value)) return computeBlindIndex(key, value);
   const kms = configuredPiiSubjectKms();
   // Ciphertext without a KMS can't be decrypted here; the same read would
   // also surface raw ciphertext — misconfiguration is caught at boot.
   if (kms === undefined) return null;
-  const decrypted = await decryptPiiFieldValues({ value }, ["value"], kms, {
+  const decrypted = await decryptPiiFieldValues({ [field]: value }, [field], kms, {
     requestId: requestContext.get()?.requestId ?? "blind-index",
   });
-  const plain = decrypted["value"];
+  const plain = decrypted[field];
   if (typeof plain !== "string" || plain === PII_ERASED_SENTINEL) return null;
   return computeBlindIndex(key, plain);
 }

package/src/crypto/event-pii.ts

@@ -59,6 +59,7 @@ export async function encryptEventPayloadPii(
       { kind: "user", userId: subjectId },
       value,
       { requestId: requestContext.get()?.requestId ?? "append-event" },
+      field,
     );
     if (encrypted !== value) {
       out ??= { ...payload };

package/src/crypto/pii-field-encryption.ts

@@ -3,7 +3,12 @@
 // erase subject — kms.eraseKey(subject) makes every value unreadable at once.
 // Storage format is a sniffable string that fits existing text columns and
 // names its subject inline, so decrypt needs no schema change and no resolver:
-//   kumiko-pii:v1:<subjectKey>:<base64(iv|tag|ciphertext)>
+//   kumiko-pii:v2:<subjectKey>:<base64(iv|tag|ciphertext)>
+// v2 GCM-binds the ciphertext to `subjectKey|field` as AAD (#1263) — subject
+// selects the DEK, field stops a cut-and-paste between two fields of the
+// SAME subject (same DEK, so key selection alone can't catch that) from
+// decrypting silently. v1 (no AAD) stays decrypt-only for pre-#1263 rows;
+// every new write emits v2.
 
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import type { EntityDefinition } from "../engine/types/fields";
@@ -26,24 +31,40 @@ import { resolveSubjectForField } from "./subject-resolver";
 // Spec value (crypto-shredding.md) — renderers show it verbatim.
 export const PII_ERASED_SENTINEL = "[[erased]]";
 
-export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v1:";
+const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
+export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
 const IV_LENGTH = 12;
 const AUTH_TAG_LENGTH = 16;
 
 export function isPiiCiphertext(value: unknown): value is string {
-  return typeof value === "string" && value.startsWith(PII_CIPHERTEXT_PREFIX);
+  return (
+    typeof value === "string" &&
+    (value.startsWith(PII_CIPHERTEXT_PREFIX) || value.startsWith(PII_CIPHERTEXT_PREFIX_V1))
+  );
 }
 
-function encryptValue(subject: SubjectId, dek: SubjectDek, plaintext: string): string {
+function buildAad(subject: SubjectId, field: string): Buffer {
+  return Buffer.from(`${subjectIdToKey(subject)}|${field}`, "utf8");
+}
+
+function encryptValue(
+  subject: SubjectId,
+  dek: SubjectDek,
+  plaintext: string,
+  field: string,
+): string {
   const iv = randomBytes(IV_LENGTH);
   const cipher = createCipheriv("aes-256-gcm", dek, iv);
+  cipher.setAAD(buildAad(subject, field));
   const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
   const blob = Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
   return `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subject)}:${blob.toString("base64")}`;
 }
 
-function parseCiphertext(value: string): { subject: SubjectId; blob: Buffer } {
-  const rest = value.slice(PII_CIPHERTEXT_PREFIX.length);
+function parseCiphertext(value: string): { subject: SubjectId; blob: Buffer; hasAad: boolean } {
+  const hasAad = value.startsWith(PII_CIPHERTEXT_PREFIX);
+  const prefix = hasAad ? PII_CIPHERTEXT_PREFIX : PII_CIPHERTEXT_PREFIX_V1;
+  const rest = value.slice(prefix.length);
   // subjectKey itself contains ":" ("user:<id>") — base64 never does, so the
   // last ":" is always the key/blob separator.
   const sep = rest.lastIndexOf(":");
@@ -51,14 +72,22 @@ function parseCiphertext(value: string): { subject: SubjectId; blob: Buffer } {
   return {
     subject: subjectIdFromKey(rest.slice(0, sep)),
     blob: Buffer.from(rest.slice(sep + 1), "base64"),
+    hasAad,
   };
 }
 
-function decryptValue(dek: SubjectDek, blob: Buffer): string {
+function decryptValue(
+  dek: SubjectDek,
+  blob: Buffer,
+  subject: SubjectId,
+  field: string,
+  hasAad: boolean,
+): string {
   const iv = blob.subarray(0, IV_LENGTH);
   const tag = blob.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
   const ciphertext = blob.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
   const decipher = createDecipheriv("aes-256-gcm", dek, iv);
+  if (hasAad) decipher.setAAD(buildAad(subject, field));
   decipher.setAuthTag(tag);
   return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
 }
@@ -87,31 +116,36 @@ async function getOrCreateDek(
 
 // Single-value encrypt for callers that resolve the subject themselves
 // (event-pii catalog, backfill). Ciphertext/sentinel inputs pass through —
-// idempotent like the field-map variant.
+// idempotent like the field-map variant. `field` names the value's storage
+// slot (payload field / config key) — part of the AAD, so it must match the
+// `field` passed to decryptPiiValueForSubject for the same value.
 export async function encryptPiiValueForSubject(
   kms: LocalKeyKmsAdapter,
   subject: SubjectId,
   value: string,
   kmsCtx: KmsContext,
+  field: string,
 ): Promise<string> {
   if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) return value;
   const dek = await getOrCreateDek(kms, subject, kmsCtx);
-  return encryptValue(subject, dek, value);
+  return encryptValue(subject, dek, value, field);
 }
 
 // Single-value decrypt for callers that don't have an entity/field-map to
 // pass through decryptPiiFieldValues (config values). The subject lives
 // inside the ciphertext itself, so no subject/scope resolution is needed
-// on this side — only the encrypt direction has to pick one.
+// on this side — only the encrypt direction has to pick one. `field` must
+// match the one used at encrypt time (AAD) or decrypt fails loud.
 export async function decryptPiiValueForSubject(
   kms: LocalKeyKmsAdapter,
   value: string,
   kmsCtx: KmsContext,
+  field: string,
 ): Promise<string> {
   if (!isPiiCiphertext(value)) return value;
-  const { subject, blob } = parseCiphertext(value);
+  const { subject, blob, hasAad } = parseCiphertext(value);
   try {
-    return decryptValue(await kms.getKey(subject, kmsCtx), blob);
+    return decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, field, hasAad);
   } catch (e) {
     if (!(e instanceof KeyErasedError)) throw e;
     return PII_ERASED_SENTINEL;
@@ -156,7 +190,7 @@ export async function encryptPiiFieldValues(
     // skip: collectPiiSubjectFields only yields annotated fields — null is unreachable, kept as a type guard
     if (subject === null) continue;
     const dek = await getOrCreateDek(kms, subject, kmsCtx);
-    out[name] = encryptValue(subject, dek, value);
+    out[name] = encryptValue(subject, dek, value, name);
   }
   return out;
 }
@@ -174,9 +208,9 @@ export async function decryptPiiFieldValues(
     // Pre-engine plaintext rows pass through unchanged (mixed-state reads
     // work during rollout; backfill is tracked in kumiko-framework#799).
     if (!isPiiCiphertext(value)) continue;
-    const { subject, blob } = parseCiphertext(value);
+    const { subject, blob, hasAad } = parseCiphertext(value);
     try {
-      out[name] = decryptValue(await kms.getKey(subject, kmsCtx), blob);
+      out[name] = decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, name, hasAad);
     } catch (e) {
       // KeyNotFound deliberately propagates: ciphertext without a key row
       // means the key store is wrong (not shredded) — fail loud.

package/src/db/__tests__/event-store-executor-context.pii-roundtrip.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decryptPiiFieldValues,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  type KmsContext,
+} from "../../crypto";
+import { createEntity, createTextField } from "../../engine";
+import { createTestUser, testUserId } from "../../stack/test-users";
+import { createTestEnvelopeCipher } from "../../testing";
+import { buildExecutorContext, type Table } from "../event-store-executor-context";
+
+const TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
+
+describe("event-store-executor-context — encryptForStorage/decryptForRead layering", () => {
+  const entity = createEntity({
+    table: "pii_roundtrip_test",
+    fields: {
+      userId: createTextField({ required: true }),
+      // Both markers at once — the auth-mfa.totpSecret/recoveryCodes shape
+      // that first surfaced the ordering bug (pii-subject-encryption
+      // integration test).
+      secretNote: createTextField({ encrypted: true, userOwned: { ownerField: "userId" } }),
+    },
+  });
+  const encryption = createTestEnvelopeCipher(TEST_KEY);
+  const kms = new InMemoryKmsAdapter();
+  const kmsCtx: KmsContext = { requestId: "test" };
+  const context = buildExecutorContext({} as Table, entity, {
+    entityName: "piiRoundtripTest",
+    encryption,
+    kms,
+  });
+  const user = createTestUser({ id: testUserId(1) });
+
+  test("round-trips through both layers", async () => {
+    const row = { userId: user.id, secretNote: "the actual secret" };
+    const stored = await context.encryptForStorage(row, user);
+    expect(stored["secretNote"]).not.toBe("the actual secret");
+
+    const read = await context.decryptForRead(stored);
+    expect(read["secretNote"]).toBe("the actual secret");
+  });
+
+  test("stores PII(envelope(plaintext)) — PII is the outer layer, not envelope", async () => {
+    const row = { userId: user.id, secretNote: "the actual secret" };
+    const stored = await context.encryptForStorage(row, user);
+    const storedNote = stored["secretNote"];
+
+    // Outer layer is PII ciphertext.
+    expect(isPiiCiphertext(storedNote)).toBe(true);
+
+    // Peeling only the outer (PII) layer must leave an envelope-ciphertext
+    // string underneath, not the plaintext directly — proves encryptForStorage
+    // wrapped the envelope-ciphertext with PII, not the raw plaintext.
+    const piiPeeled = await decryptPiiFieldValues(stored, ["secretNote"], kms, kmsCtx);
+    const innerValue = piiPeeled["secretNote"];
+    expect(innerValue).not.toBe("the actual secret");
+    expect(isPiiCiphertext(innerValue)).toBe(false);
+    await expect(encryption.decrypt(innerValue as string)).resolves.toBe("the actual secret");
+
+    // decryptForRead must peel PII first: feeding the stored value straight
+    // to the envelope cipher (skipping the PII unwrap) has to fail — this is
+    // the ordering bug the roundtrip guards against.
+    await expect(encryption.decrypt(storedNote as string)).rejects.toThrow();
+  });
+});