@cosmicdrift/kumiko-framework 0.116.1 → 0.119.0

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,

package/src/db/blind-index-cleanup.ts

@@ -0,0 +1,53 @@
+// Sofortiges Blind-Index-Nulling nach einem Subject-Erase (#818).
+//
+// Nach kms.eraseKey ist der Ciphertext unlesbar, aber die deterministische
+// bidx-Spalte bliebe bis zum nächsten Write/Rebuild matchbar — ein
+// Linkage-Fenster ("hat irgendeine Row den Wert X"). Dieser Sweep schließt
+// es sofort: der Ciphertext nennt sein Subject inline
+// (kumiko-pii:v1:<subjectKey>:...), also findet ein LIKE-Prefix-Match exakt
+// die Rows des erased Subjects — pro lookupable-Feld ein UPDATE.
+//
+// Rows, die der Forget-Lauf ohnehin via Executor löscht/anonymisiert,
+// bekommen ihren bidx dort automatisch neu berechnet; dieser Sweep deckt
+// die liegen bleibenden Rows ab (fremde Entities mit userOwned-Feldern).
+
+import { collectLookupableFields } from "../crypto/blind-index";
+import type { FeatureDefinition } from "../engine/types";
+import { toSnakeCase } from "../utils/case";
+import type { DbRunner } from "./connection";
+import { resolveTableName } from "./entity-table-meta";
+import { executeRawQuery } from "./queries/raw-sql";
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, (m) => `\\${m}`);
+}
+
+export async function nullBlindIndexesForSubject(
+  db: DbRunner,
+  features: ReadonlyMap<string, FeatureDefinition>,
+  subjectKey: string,
+): Promise<void> {
+  const likePattern = `kumiko-pii:v1:${escapeLikePattern(subjectKey)}:%`;
+  for (const feature of features.values()) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      const lookupable = collectLookupableFields(entity);
+      if (lookupable.length === 0) continue;
+      // Kein featureName-Prefix — der Dispatcher baut Entity-Tables ohne
+      // (buildEntityTable ohne featureName-Option), der Sweep muss dieselben
+      // Namen treffen.
+      const tableName = resolveTableName(entityName, entity, undefined);
+      for (const fieldName of lookupable) {
+        const snake = toSnakeCase(fieldName);
+        await executeRawQuery(
+          db,
+          `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`,
+          [likePattern],
+        );
+      }
+    }
+  }
+}

package/src/db/entity-table-meta.ts

@@ -18,6 +18,7 @@
 //      auf Sondercases beschränken (child-projection-tables ohne tenant,
 //      append-only-logs mit serial PK, aggregate-ID ohne DEFAULT, …).
 
+import { collectPiiSubjectFields } from "../crypto";
 import type {
   EntityDefinition,
   EntityIndexDef,
@@ -92,6 +93,10 @@ export type EntityTableMeta = {
   // trägt Verantwortung. Migration-Generator + Tooling können den
   // discriminator nutzen um Warnungen zu rendern ("X tables are unmanaged").
   readonly source: "managed" | "unmanaged";
+  // PII-Subject-annotated field names (pii/userOwned/tenantOwned). Set by
+  // buildEntityTableMeta so the registry can reject r.unmanagedTable stores
+  // whose direct writes would skip the executor's encryption (#820).
+  readonly piiSubjectFields?: readonly string[];
 };
 
 // Standard base-columns für event-sourced Read-Model-Tabellen. Spiegelt
@@ -153,7 +158,7 @@ function fieldToColumnMeta(
     case "text":
     case "longText": {
       const def = fieldDefaultLiteral(field);
-      return [
+      const cols: ColumnMeta[] = [
         {
           name: snake,
           pgType: "text",
@@ -161,6 +166,13 @@ function fieldToColumnMeta(
           ...(def !== undefined && { defaultSql: def }),
         },
       ];
+      // lookupable → HMAC-Blind-Index-Pendant. Nullable ist Pflicht:
+      // managedChangeRequiresRecreate würde eine NOT-NULL-Spalte ohne
+      // Default auf Bestandstabellen als DROP+Rebuild diffen.
+      if (field.type === "text" && field.lookupable === true) {
+        cols.push({ name: `${snake}_bidx`, pgType: "text", notNull: false });
+      }
+      return cols;
     }
     case "boolean": {
       const def = fieldDefaultLiteral(field);
@@ -305,10 +317,17 @@ export function buildEntityTableMeta(
   for (const c of baseCols) colByName.set(c.name, c);
 
   const fieldNameToSnake = new Map<string, string>();
+  const bidxSnakeByFieldSnake = new Map<string, string>();
   for (const [name, field] of Object.entries(entity.fields)) {
     const fieldCols = fieldToColumnMeta(name, field, entity);
     for (const c of fieldCols) colByName.set(c.name, c);
-    if (fieldCols.length === 1 && fieldCols[0]) fieldNameToSnake.set(name, fieldCols[0].name);
+    // Multi-column fields map to their primary column when its name IS the
+    // field's snake (text+bidx, money+currency) — matches the toSnakeCase
+    // fallback below, so explicit indexes keep resolving.
+    const primary = fieldCols[0];
+    if (primary && primary.name === toSnakeCase(name)) fieldNameToSnake.set(name, primary.name);
+    const bidxCol = fieldCols.find((c) => c.name.endsWith("_bidx"));
+    if (primary && bidxCol) bidxSnakeByFieldSnake.set(primary.name, bidxCol.name);
   }
 
   // Preserve base-col order, then any new user-col-names in fields-order.
@@ -347,6 +366,12 @@ export function buildEntityTableMeta(
     indexes.push({ name: `${tableName}_${snake}_idx`, columns: [snake] });
   }
 
+  // lookupable-Felder: Index auf der bidx-Spalte — der OR-Rewrite der
+  // Query-Compiler trifft sie bei jedem Equality-Lookup.
+  for (const bidxSnake of bidxSnakeByFieldSnake.values()) {
+    indexes.push({ name: `${tableName}_${bidxSnake}_idx`, columns: [bidxSnake] });
+  }
+
   // Explizit deklarierte indexes (EntityIndexDef). `def.where` ist ein
   // SqlExpression (`sql\`…\`` aus @cosmicdrift/kumiko-framework/db) —
   // renderbar via `.text`. Unbekannte where-Shapes bleiben needsManualWhere.
@@ -364,13 +389,33 @@ export function buildEntityTableMeta(
       ...(whereSql !== undefined && { whereSql }),
       ...(def.where !== undefined && whereSql === undefined && { needsManualWhere: true }),
     });
+    // Unique-Index über lookupable-Spalten: partielles bidx-Pendant, damit
+    // Uniqueness auch für verschlüsselte Rows greift. Das Original bleibt
+    // für Klartext-Alt-Rows; partial (IS NOT NULL) weil bidx bei erased/
+    // key-losen Rows NULL ist.
+    if (def.unique === true && def.where === undefined) {
+      const bidxCols = cols.map((c) => bidxSnakeByFieldSnake.get(c) ?? c);
+      if (bidxCols.some((c, i) => c !== cols[i])) {
+        const notNullParts = bidxCols
+          .filter((c, i) => c !== cols[i])
+          .map((c) => `"${c}" IS NOT NULL`);
+        indexes.push({
+          name: `${indexName}_bidx`,
+          columns: bidxCols,
+          unique: true,
+          whereSql: notNullParts.join(" AND "),
+        });
+      }
+    }
   }
 
+  const piiSubjectFields = collectPiiSubjectFields(entity);
   return {
     tableName,
     columns,
     indexes,
     source: "managed",
+    ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
   };
 }