@cosmicdrift/kumiko-framework 0.118.0 → 0.120.0

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

@@ -0,0 +1,195 @@
+// PII field encryption with per-subject DEKs (crypto-shredding, #724 phase C).
+// Same executor hook points as `encrypted: true`, but the key belongs to the
+// 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)>
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { EntityDefinition } from "../engine/types/fields";
+import type { TenantId } from "../engine/types/identifiers";
+import {
+  isLocalKeyKmsAdapter,
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsAdapter,
+  type KmsContext,
+  type LocalKeyKmsAdapter,
+  type SubjectDek,
+  type SubjectId,
+  subjectIdFromKey,
+  subjectIdToKey,
+} from "./kms-adapter";
+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 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);
+}
+
+function encryptValue(subject: SubjectId, dek: SubjectDek, plaintext: string): string {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv("aes-256-gcm", dek, iv);
+  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);
+  // subjectKey itself contains ":" ("user:<id>") — base64 never does, so the
+  // last ":" is always the key/blob separator.
+  const sep = rest.lastIndexOf(":");
+  if (sep === -1) throw new Error(`Malformed PII ciphertext (no subject/blob separator)`);
+  return {
+    subject: subjectIdFromKey(rest.slice(0, sep)),
+    blob: Buffer.from(rest.slice(sep + 1), "base64"),
+  };
+}
+
+function decryptValue(dek: SubjectDek, blob: Buffer): 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);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+
+// First write to a PII field of a new subject creates the key implicitly
+// (user-signup / tenant-create need no extra hook). The AlreadyExists catch
+// covers the concurrent-first-write race; a tombstoned subject re-throws
+// KeyErasedError from the final getKey — writes to a forgotten subject fail.
+async function getOrCreateDek(
+  kms: LocalKeyKmsAdapter,
+  subject: SubjectId,
+  ctx: KmsContext,
+): Promise<SubjectDek> {
+  try {
+    return await kms.getKey(subject, ctx);
+  } catch (e) {
+    if (!(e instanceof KeyNotFoundError)) throw e;
+  }
+  try {
+    await kms.createKey(subject, ctx);
+  } catch (e) {
+    if (!(e instanceof KeyAlreadyExistsError)) throw e;
+  }
+  return kms.getKey(subject, ctx);
+}
+
+// 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.
+export async function encryptPiiValueForSubject(
+  kms: LocalKeyKmsAdapter,
+  subject: SubjectId,
+  value: string,
+  kmsCtx: KmsContext,
+): Promise<string> {
+  if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) return value;
+  const dek = await getOrCreateDek(kms, subject, kmsCtx);
+  return encryptValue(subject, dek, value);
+}
+
+export interface EncryptPiiOptions {
+  readonly onlyKeys?: Iterable<string>;
+  // Write-time tenant for tenantOwned fields on rows without a tenantId column.
+  readonly tenantId?: TenantId;
+  // Row to resolve subjects from when `row` is a partial (update changes may
+  // carry a pii field without its ownerField — the merged row still has it).
+  readonly subjectSource?: Record<string, unknown>;
+}
+
+export async function encryptPiiFieldValues(
+  row: Record<string, unknown>,
+  entity: EntityDefinition,
+  piiFields: readonly string[],
+  kms: LocalKeyKmsAdapter,
+  kmsCtx: KmsContext,
+  opts: EncryptPiiOptions = {},
+): Promise<Record<string, unknown>> {
+  if (piiFields.length === 0) return row;
+  const only = opts.onlyKeys ? new Set(opts.onlyKeys) : null;
+  const subjectSource = opts.subjectSource ?? row;
+  const out = { ...row };
+  for (const name of piiFields) {
+    if (only && !only.has(name)) continue;
+    if (!(name in out)) continue;
+    const value = out[name];
+    if (value === null || value === undefined) continue;
+    // Re-encrypt paths (update previous, detail cache) may see values that
+    // are already ciphertext or the erased sentinel — both stay as-is.
+    if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) continue;
+    if (typeof value !== "string") {
+      throw new Error(`PII field "${name}" must be a string, got ${typeof value}`);
+    }
+    const subject = resolveSubjectForField(entity, name, subjectSource, {
+      ...(opts.tenantId !== undefined && { tenantId: opts.tenantId }),
+    });
+    // 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);
+  }
+  return out;
+}
+
+export async function decryptPiiFieldValues(
+  row: Record<string, unknown>,
+  piiFields: readonly string[],
+  kms: LocalKeyKmsAdapter,
+  kmsCtx: KmsContext,
+): Promise<Record<string, unknown>> {
+  if (piiFields.length === 0) return row;
+  const out = { ...row };
+  for (const name of piiFields) {
+    const value = out[name];
+    // 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);
+    try {
+      out[name] = decryptValue(await kms.getKey(subject, kmsCtx), blob);
+    } catch (e) {
+      // KeyNotFound deliberately propagates: ciphertext without a key row
+      // means the key store is wrong (not shredded) — fail loud.
+      if (!(e instanceof KeyErasedError)) throw e;
+      out[name] = PII_ERASED_SENTINEL;
+    }
+  }
+  return out;
+}
+
+// Boot-injected app-wide subject KMS, mirroring configureEntityFieldEncryption:
+// run{Prod,Dev}App call configurePiiSubjectKms once; executors resolve lazily.
+// Absent adapter = engine off (pii fields stay plaintext, pre-phase-C
+// behavior) — the hard boot gate arrives with the prod-grade PgKmsAdapter
+// (phase E); until then no production deployment can satisfy it.
+let injectedKms: LocalKeyKmsAdapter | undefined;
+
+export function configurePiiSubjectKms(adapter: KmsAdapter | undefined): void {
+  if (adapter !== undefined && !isLocalKeyKmsAdapter(adapter)) {
+    throw new Error(
+      "PII field encryption requires a local-key KMS adapter — remote-crypto " +
+        "(Vault transit) support lands with the BYOK adapter.",
+    );
+  }
+  injectedKms = adapter;
+}
+
+export function configuredPiiSubjectKms(): LocalKeyKmsAdapter | undefined {
+  return injectedKms;
+}
+
+/** @internal test-only */
+export function resetPiiSubjectKmsForTests(): void {
+  injectedKms = undefined;
+}

package/src/db/__tests__/blind-index.integration.test.ts

@@ -0,0 +1,232 @@
+// Blind-Index end-to-end (#818): create/update schreiben die bidx-Spalte
+// (nie ins Event-Log), Equality-Lookups matchen über den OR-Rewrite sowohl
+// verschlüsselte als auch Klartext-Alt-Rows, Rebuild recomputet bidx aus
+// dem Ciphertext (erased → NULL), und der Forget-Sweep nullt sofort.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  computeBlindIndex,
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  decodeBlindIndexKey,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+  subjectIdToKey,
+} from "../../crypto";
+import { defineFeature } from "../../engine/define-feature";
+import { createEntity, createTextField } from "../../engine/factories";
+import { createRegistry } from "../../engine/registry";
+import { createEventsTable } from "../../event-store";
+import { rebuildProjection } from "../../pipeline";
+import { createProjectionStateTable } from "../../pipeline/projection-state";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { nullBlindIndexesForSubject } from "../blind-index-cleanup";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { asRawClient, fetchOne } from "../query";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const TEST_KEY_B64 = Buffer.alloc(32, 7).toString("base64");
+const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
+
+const personEntity = createEntity({
+  table: "read_bidx_persons",
+  fields: {
+    email: createTextField({ required: true, pii: true, lookupable: true }),
+    firstName: createTextField(),
+  },
+});
+const personFeature = defineFeature("bidxtest", (r) => {
+  r.entity("person", personEntity);
+});
+const personTable = buildEntityTable("person", personEntity);
+
+let testDb: TestDb;
+let tdb: TenantDb;
+let kms: InMemoryKmsAdapter;
+const adminUser = TestUsers.admin;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, personEntity, "person");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  tdb = createTenantDb(testDb.db, adminUser.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_bidx_persons, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+  configureBlindIndexKey(TEST_KEY_B64);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+const crud = createEventStoreExecutor(personTable, personEntity, { entityName: "person" });
+
+async function rawRow(id: string): Promise<Record<string, unknown>> {
+  const rows = await asRawClient(testDb.db).unsafe<Record<string, unknown>>(
+    `SELECT * FROM read_bidx_persons WHERE id = $1`,
+    [id],
+  );
+  const row = rows[0];
+  if (!row) throw new Error(`no row for ${id}`);
+  return row;
+}
+
+describe("blind-index write path", () => {
+  test("create: bidx in the row, ciphertext in the email column, NOTHING in the event", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const row = await rawRow(String(created.data.id));
+    expect(row["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+    expect(isPiiCiphertext(row["email"])).toBe(true);
+
+    // Executor-Response: plaintext email, kein bidx-Leak.
+    expect(created.data.data["email"]).toBe("marc@example.com");
+    expect("emailBidx" in created.data.data).toBe(false);
+
+    const events = await asRawClient(testDb.db).unsafe<{ payload: unknown }>(
+      `SELECT payload FROM kumiko_events WHERE aggregate_id = $1`,
+      [String(created.data.id)],
+    );
+    const payloadText = JSON.stringify(events.map((e) => e.payload));
+    expect(payloadText).not.toContain("bidx");
+  });
+
+  test("update recomputes bidx for the changed field", async () => {
+    const created = await crud.create({ email: "old@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    await crud.update(
+      { id: created.data.id, version: 1, changes: { email: "new@example.com" } },
+      adminUser,
+      tdb,
+    );
+    const row = await rawRow(String(created.data.id));
+    expect(row["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "new@example.com"));
+  });
+});
+
+describe("blind-index lookup (OR-rewrite)", () => {
+  test("fetchOne by plaintext email finds the encrypted row", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const hit = await fetchOne<Record<string, unknown>>(tdb, personTable, {
+      email: "marc@example.com",
+    });
+    expect(hit).toBeDefined();
+    expect(hit?.["id"]).toBe(created.data.id);
+    // Read-Strip: bidx nie am Caller.
+    expect(hit && "emailBidx" in hit).toBe(false);
+    expect(hit && "email_bidx" in hit).toBe(false);
+
+    expect(await fetchOne(tdb, personTable, { email: "other@example.com" })).toBeUndefined();
+  });
+
+  test("plaintext legacy row (written pre-rollout) still matches the same query", async () => {
+    // Rollout-Zustand VOR KMS+Key: Klartext-Row, bidx NULL.
+    resetPiiSubjectKmsForTests();
+    resetBlindIndexKeyForTests();
+    const legacy = await crud.create({ email: "legacy@example.com" }, adminUser, tdb);
+    if (!legacy.isSuccess) throw new Error("create failed");
+    const legacyRow = await rawRow(String(legacy.data.id));
+    expect(legacyRow["email"]).toBe("legacy@example.com");
+    expect(legacyRow["email_bidx"]).toBeNull();
+
+    // Rollout an: dieselbe Query matcht über den Plaintext-Arm.
+    configurePiiSubjectKms(kms);
+    configureBlindIndexKey(TEST_KEY_B64);
+    const hit = await fetchOne<Record<string, unknown>>(tdb, personTable, {
+      email: "legacy@example.com",
+    });
+    expect(hit?.["id"]).toBe(legacy.data.id);
+  });
+
+  test("list filter eq matches the encrypted row and strips bidx", async () => {
+    const created = await crud.create(
+      { email: "marc@example.com", firstName: "Marc" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const page = await crud.list(
+      { filter: { field: "email", op: "eq", value: "marc@example.com" } },
+      adminUser,
+      tdb,
+    );
+    expect(page.rows).toHaveLength(1);
+    expect(page.rows[0]?.["email"]).toBe("marc@example.com");
+    expect(page.rows[0] && "emailBidx" in page.rows[0]).toBe(false);
+
+    const miss = await crud.list(
+      { filter: { field: "email", op: "eq", value: "nobody@example.com" } },
+      adminUser,
+      tdb,
+    );
+    expect(miss.rows).toHaveLength(0);
+  });
+});
+
+describe("blind-index rebuild + forget", () => {
+  const implicitName = "bidxtest:projection:person-entity";
+
+  test("rebuild recomputes bidx from ciphertext (identical to live)", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    const liveBidx = (await rawRow(String(created.data.id)))["email_bidx"];
+
+    const registry = createRegistry([personFeature]);
+    expect(registry.getAllProjections().has(implicitName)).toBe(true);
+    await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    const rebuilt = await rawRow(String(created.data.id));
+    expect(rebuilt["email_bidx"]).toBe(liveBidx);
+    expect(rebuilt["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+  });
+
+  test("erased subject → rebuild sets bidx NULL, lookup stops matching", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+
+    const registry = createRegistry([personFeature]);
+    await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    const rebuilt = await rawRow(String(created.data.id));
+    expect(rebuilt["email_bidx"]).toBeNull();
+    expect(await fetchOne(tdb, personTable, { email: "marc@example.com" })).toBeUndefined();
+  });
+
+  test("nullBlindIndexesForSubject nulls bidx immediately (no rebuild needed)", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).not.toBeNull();
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+    const registry = createRegistry([personFeature]);
+    await nullBlindIndexesForSubject(
+      testDb.db,
+      registry.features,
+      subjectIdToKey({ kind: "user", userId: String(created.data.id) }),
+    );
+
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).toBeNull();
+    expect(await fetchOne(tdb, personTable, { email: "marc@example.com" })).toBeUndefined();
+  });
+});

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -1,7 +1,8 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { InMemoryKmsAdapter, PII_ERASED_SENTINEL } from "../../crypto";
 import { asRawClient } from "../../db/query";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
-import { append, createEventsTable } from "../../event-store";
+import { append, createEventsTable, loadEventsAfterVersion } from "../../event-store";
 import type { EntityCache } from "../../pipeline/entity-cache";
 import {
   createTestDb,
@@ -11,6 +12,7 @@ import {
   unsafeCreateEntityTable,
 } from "../../stack";
 import { createTestEnvelopeCipher } from "../../testing";
+import { applyEntityEvent } from "../apply-entity-event";
 import { resetEntityFieldEncryptionCacheForTests } from "../entity-field-encryption";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildEntityTable } from "../table-builder";
@@ -553,4 +555,170 @@ describe("event-store-executor — entity cache + encrypted fields", () => {
     const second = await cachedEncryptedCrud.detail({ id }, adminUser, tdb);
     expect(second?.["secretNote"]).toBe("cache-plaintext-note");
   });
+
+  // Regression twin pack for the list() path:
+  //   1. list decrypted BEFORE the snake→camel coercion, so any multi-word
+  //      encrypted/pii field (secret_note vs secretNote) came back as raw
+  //      ciphertext to the caller.
+  //   2. list's mset cached the decrypted rows — plaintext in Redis, the
+  //      exact leak the detail() path re-encrypts to avoid.
+  test("list() returns plaintext for camelCase encrypted fields and caches ciphertext", async () => {
+    const created = await cachedEncryptedCrud.create(
+      { email: "cache-list@test.de", secretNote: "list-plaintext-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+    const storeKey = `${adminUser.tenantId}:esExecEncrypted:${created.data.id}`;
+    store.clear();
+
+    const list = await cachedEncryptedCrud.list({}, adminUser, tdb);
+    const listed = list.rows.find((r) => r["id"] === created.data.id);
+    expect(listed?.["secretNote"]).toBe("list-plaintext-note");
+
+    const cachedRaw = store.get(storeKey);
+    expect(cachedRaw?.["secretNote"]).toBeDefined();
+    expect(cachedRaw?.["secretNote"]).not.toBe("list-plaintext-note");
+  });
+});
+
+// PII subject encryption (crypto-shredding, #724 phase C): pii/userOwned/
+// tenantOwned fields are encrypted with the erase subject's DEK. Event
+// payload AND projection row carry ciphertext (live == rebuild); erasing the
+// subject key renders every value as the [[erased]] sentinel without
+// touching the immutable log.
+const piiEntity = createEntity({
+  table: "read_es_exec_pii",
+  fields: {
+    email: createTextField({ required: true, pii: true }),
+    note: createTextField({ userOwned: { ownerField: "authorId" } }),
+    authorId: createTextField(),
+    plain: createTextField(),
+  },
+});
+const piiTable = buildEntityTable("esExecPii", piiEntity);
+
+describe("event-store-executor — pii subject encryption", () => {
+  const kms = new InMemoryKmsAdapter();
+  const crud = createEventStoreExecutor(piiTable, piiEntity, {
+    entityName: "esExecPii",
+    kms,
+  });
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTable(testDb.db, piiEntity, "esExecPii");
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_exec_pii RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("create: projection row + event payload are ciphertext, API reads plaintext", async () => {
+    const result = await crud.create({ email: "pii@test.de", plain: "visible" }, adminUser, tdb);
+    if (!result.isSuccess) throw new Error("create failed");
+    expect(result.data.data["email"]).toBe("pii@test.de");
+
+    const rawRows = (await asRawClient(testDb.db).unsafe(
+      `SELECT email, plain FROM read_es_exec_pii LIMIT 1`,
+    )) as Array<{ email: string; plain: string }>;
+    expect(rawRows[0]!.email).toStartWith(`kumiko-pii:v1:user:${result.data.id}:`);
+    expect(rawRows[0]!.plain).toBe("visible");
+
+    const events = (await asRawClient(testDb.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = 'esExecPii.created' LIMIT 1`,
+    )) as Array<{ payload: { email?: string } }>;
+    expect(events[0]?.payload.email).toStartWith("kumiko-pii:v1:");
+
+    const detail = await crud.detail({ id: result.data.id }, adminUser, tdb);
+    expect(detail?.["email"]).toBe("pii@test.de");
+    const list = await crud.list({}, adminUser, tdb);
+    expect(list.rows[0]?.["email"]).toBe("pii@test.de");
+  });
+
+  test("userOwned update without ownerField in changes resolves via the merged row", async () => {
+    const created = await crud.create(
+      { email: "owner@test.de", note: "v1", authorId: TestUsers.admin.id },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const updated = await crud.update(
+      { id: created.data.id, version: 1, changes: { note: "v2" } },
+      adminUser,
+      tdb,
+    );
+    if (!updated.isSuccess) throw new Error("update failed");
+    expect(updated.data.data["note"]).toBe("v2");
+
+    const rawRows = (await asRawClient(testDb.db).unsafe(
+      `SELECT note FROM read_es_exec_pii LIMIT 1`,
+    )) as Array<{ note: string }>;
+    expect(rawRows[0]!.note).toStartWith(`kumiko-pii:v1:user:${TestUsers.admin.id}:`);
+  });
+
+  test("eraseKey: detail renders the sentinel, stored events stay byte-identical", async () => {
+    const created = await crud.create({ email: "forget@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const eventsBefore = (await asRawClient(testDb.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = 'esExecPii.created' LIMIT 1`,
+    )) as Array<{ payload: { email?: string } }>;
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+
+    const detail = await crud.detail({ id: created.data.id }, adminUser, tdb);
+    expect(detail?.["email"]).toBe(PII_ERASED_SENTINEL);
+
+    const eventsAfter = (await asRawClient(testDb.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = 'esExecPii.created' LIMIT 1`,
+    )) as Array<{ payload: { email?: string } }>;
+    expect(eventsAfter[0]?.payload.email).toBe(eventsBefore[0]!.payload.email!);
+  });
+
+  test("rebuild after erase resurrects no plaintext (replay writes ciphertext, reads render sentinel)", async () => {
+    const created = await crud.create({ email: "rebuild@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+
+    // Same code path rebuildProjection replays: applyEntityEvent on the
+    // PERSISTED event (ciphertext payload). The response echo carries the
+    // plaintext payload since #820 and must not be used as a replay source.
+    const responseEvent = created.data.event as { payload: Record<string, unknown> } | undefined;
+    expect(responseEvent?.payload["email"]).toBe("rebuild@test.de");
+    await asRawClient(testDb.db).unsafe(`TRUNCATE read_es_exec_pii RESTART IDENTITY CASCADE`);
+    const [storedEvent] = await loadEventsAfterVersion(
+      testDb.db,
+      String(created.data.id),
+      adminUser.tenantId,
+      0,
+    );
+    if (!storedEvent) throw new Error("no persisted event for the aggregate");
+    const applied = await applyEntityEvent(storedEvent, piiTable, piiEntity, tdb.raw);
+    expect(applied.kind).toBe("applied");
+
+    const rawRows = (await asRawClient(testDb.db).unsafe(
+      `SELECT email FROM read_es_exec_pii LIMIT 1`,
+    )) as Array<{ email: string }>;
+    expect(rawRows[0]!.email).toStartWith("kumiko-pii:v1:");
+    expect(rawRows[0]!.email).not.toContain("rebuild@test.de");
+
+    const detail = await crud.detail({ id: created.data.id }, adminUser, tdb);
+    expect(detail?.["email"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("without a kms adapter the engine is off: plaintext row (pre-#724 behavior)", async () => {
+    const plainCrud = createEventStoreExecutor(piiTable, piiEntity, {
+      entityName: "esExecPii",
+    });
+    const created = await plainCrud.create({ email: "off@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const rawRows = (await asRawClient(testDb.db).unsafe(
+      `SELECT email FROM read_es_exec_pii LIMIT 1`,
+    )) as Array<{ email: string }>;
+    expect(rawRows[0]!.email).toBe("off@test.de");
+  });
 });

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -109,3 +109,42 @@ describe("lock-step — softDelete + explizite Indexes", () => {
     expect((fromBuilder?.indexes ?? []).length).toBeGreaterThanOrEqual(3);
   });
 });
+
+// Dritte Probe: lookupable-Feld (#818) — bidx-Spalte, bidx-Index und das
+// partielle Unique-Pendant müssen auf beiden Pfaden identisch entstehen.
+const entityWithLookupable = createEntity({
+  table: "read_lockstep_probe_bidx",
+  fields: {
+    email: { type: "text", required: true, pii: true, lookupable: true },
+    tenantSlug: { type: "text", required: true },
+  },
+  indexes: [{ columns: ["tenantSlug", "email"], unique: true }],
+});
+
+describe("lock-step — lookupable / blind-index (#818)", () => {
+  const fromBuilder = asEntityTableMeta(
+    buildEntityTable("lockstepProbeBidx", entityWithLookupable),
+  );
+  const fromMeta = buildEntityTableMeta("lockstepProbeBidx", entityWithLookupable);
+
+  test("identical columns inkl. nullable bidx-Spalte", () => {
+    expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(
+      byName<ColumnMeta>(fromMeta.columns),
+    );
+    const bidx = (fromMeta.columns ?? []).find((c) => c.name === "email_bidx");
+    expect(bidx).toEqual({ name: "email_bidx", pgType: "text", notNull: false });
+  });
+
+  test("identical indexes inkl. bidx-Index + partiellem Unique-Pendant", () => {
+    expect(byName<IndexMeta>(fromBuilder?.indexes ?? [])).toEqual(
+      byName<IndexMeta>(fromMeta.indexes),
+    );
+    const names = fromMeta.indexes.map((i) => i.name);
+    expect(names).toContain("read_lockstep_probe_bidx_email_bidx_idx");
+    const partial = fromMeta.indexes.find((i) => i.name.endsWith("_tenant_slug_email_unique_bidx"));
+    expect(partial).toBeDefined();
+    expect(partial?.unique).toBe(true);
+    expect(partial?.columns).toEqual(["tenant_slug", "email_bidx"]);
+    expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL');
+  });
+});

package/src/db/apply-entity-event.ts

@@ -49,6 +49,7 @@
 //   - "skipped" → Event ist kein Auto-Verb (Domain-Event auf demselben
 //     Aggregate). Caller no-op.
 
+import { collectLookupableFields, computeBlindIndexValues } from "../crypto/blind-index";
 import { deleteMany, insertOne, updateMany } from "../db/query";
 import type { EntityDefinition } from "../engine/types";
 import { InternalError } from "../errors";
@@ -116,6 +117,11 @@ export async function applyEntityEvent(
       }
       const row = await insertOne<DbRow>(tx, table, {
         ...event.payload,
+        // Blind-Index-Spalten aus dem Payload-Wert (ciphertext → decrypt →
+        // HMAC, plaintext → HMAC, erased → NULL). Hier statt im Executor,
+        // damit Live-Write und Rebuild denselben Wert produzieren und der
+        // deterministische HMAC nie im Event-Log landet.
+        ...(await computeBlindIndexValues(event.payload, collectLookupableFields(entity))),
         tenantId,
         id: event.aggregateId,
         version: event.version,
@@ -142,6 +148,8 @@ export async function applyEntityEvent(
         table,
         {
           ...changes,
+          // bidx nur für die geänderten lookupable-Felder (siehe created).
+          ...(await computeBlindIndexValues(changes, collectLookupableFields(entity))),
           version: event.version,
           modifiedAt: event.createdAt,
           modifiedById: event.createdBy,