@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -0,0 +1,376 @@
+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 {
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsContext,
+  subjectIdFromKey,
+  subjectIdToKey,
+} from "../kms-adapter";
+import {
+  decryptPiiFieldValues,
+  decryptPiiValueForSubject,
+  encryptPiiFieldValues,
+  encryptPiiValueForSubject,
+  isPiiCiphertext,
+  PII_CIPHERTEXT_PREFIX,
+  PII_ERASED_SENTINEL,
+} from "../pii-field-encryption";
+import { collectPiiSubjectFields } from "../subject-resolver";
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+const UUID_B = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000b";
+const KMS_CTX: KmsContext = { requestId: "test" };
+
+const userLikeEntity = createEntity({
+  fields: {
+    email: createTextField({ required: true, pii: true }),
+    role: createTextField(),
+  },
+  table: "pii_users",
+});
+
+const commentEntity = createEntity({
+  fields: {
+    body: createTextField({ userOwned: { ownerField: "authorId" } }),
+    authorId: createTextField({ required: true }),
+  },
+  table: "pii_comments",
+});
+
+const brandingEntity = createEntity({
+  fields: {
+    brandColor: createTextField({ tenantOwned: true }),
+  },
+  table: "pii_branding",
+});
+
+describe("subjectIdFromKey", () => {
+  test("round-trips user and tenant keys, rejects garbage", () => {
+    expect(subjectIdFromKey(`user:${UUID_A}`)).toEqual({ kind: "user", userId: UUID_A });
+    expect(subjectIdFromKey(`tenant:${UUID_B}`)).toEqual({ kind: "tenant", tenantId: UUID_B });
+    expect(() => subjectIdFromKey("widget:x")).toThrow(/Invalid subject key/);
+  });
+});
+
+describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
+  test("pii self-subject: DB value is sniffable ciphertext, decrypt restores plaintext", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const fields = collectPiiSubjectFields(userLikeEntity);
+    const row = { id: UUID_A, email: "marc@example.com", role: "admin" };
+
+    const stored = await encryptPiiFieldValues(row, userLikeEntity, fields, kms, KMS_CTX);
+    expect(isPiiCiphertext(stored["email"])).toBe(true);
+    expect(String(stored["email"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_A}:`);
+    expect(stored["role"]).toBe("admin");
+    expect(row["email"]).toBe("marc@example.com");
+
+    const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
+    expect(read["email"]).toBe("marc@example.com");
+  });
+
+  test("first write auto-creates the subject key", async () => {
+    const kms = new InMemoryKmsAdapter();
+    await expect(kms.getKey({ kind: "user", userId: UUID_A })).rejects.toBeInstanceOf(
+      KeyNotFoundError,
+    );
+    await encryptPiiFieldValues(
+      { id: UUID_A, email: "a@b.c" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      KMS_CTX,
+    );
+    const dek = await kms.getKey({ kind: "user", userId: UUID_A });
+    expect(dek.length).toBe(32);
+  });
+
+  test("userOwned: ciphertext names the owner subject, not the row", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, body: "secret note", authorId: UUID_B },
+      commentEntity,
+      ["body"],
+      kms,
+      KMS_CTX,
+    );
+    expect(String(stored["body"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_B}:`);
+  });
+
+  test("tenantOwned without tenantId column falls back to write-time tenant", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, brandColor: "#ff0000" },
+      brandingEntity,
+      ["brandColor"],
+      kms,
+      KMS_CTX,
+      { tenantId: 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 () => {
+    const kms = new InMemoryKmsAdapter();
+    const changes = { body: "edited" };
+    const stored = await encryptPiiFieldValues(changes, commentEntity, ["body"], kms, KMS_CTX, {
+      onlyKeys: ["body"],
+      subjectSource: { id: UUID_A, body: "edited", authorId: 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 () => {
+    const kms = new InMemoryKmsAdapter();
+    const fields = ["email"] as const;
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, email: "gone@example.com" },
+      userLikeEntity,
+      fields,
+      kms,
+      KMS_CTX,
+    );
+    await kms.eraseKey({ kind: "user", userId: UUID_A });
+
+    const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
+    expect(read["email"]).toBe(PII_ERASED_SENTINEL);
+
+    const reStored = await encryptPiiFieldValues(read, userLikeEntity, fields, kms, KMS_CTX);
+    expect(reStored["email"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("write to an erased subject fails (forget is permanent)", async () => {
+    const kms = new InMemoryKmsAdapter();
+    await kms.createKey({ kind: "user", userId: UUID_A });
+    await kms.eraseKey({ kind: "user", userId: UUID_A });
+    await expect(
+      encryptPiiFieldValues(
+        { id: UUID_A, email: "new@b.c" },
+        userLikeEntity,
+        ["email"],
+        kms,
+        KMS_CTX,
+      ),
+    ).rejects.toThrow(/erased/);
+  });
+
+  test("legacy plaintext rows pass through decrypt unchanged", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const read = await decryptPiiFieldValues(
+      { id: UUID_A, email: "legacy@example.com" },
+      ["email"],
+      kms,
+      KMS_CTX,
+    );
+    expect(read["email"]).toBe("legacy@example.com");
+  });
+
+  test("already-ciphertext values are not double-encrypted (re-encrypt paths)", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const once = await encryptPiiFieldValues(
+      { id: UUID_A, email: "a@b.c" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      KMS_CTX,
+    );
+    const twice = await encryptPiiFieldValues(once, userLikeEntity, ["email"], kms, KMS_CTX);
+    expect(twice["email"]).toBe(once["email"]);
+  });
+
+  test("null values and fields outside onlyKeys are skipped", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, email: null, role: "x" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      KMS_CTX,
+    );
+    expect(stored["email"]).toBeNull();
+
+    const skipped = await encryptPiiFieldValues(
+      { id: UUID_A, email: "a@b.c" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      KMS_CTX,
+      { onlyKeys: ["role"] },
+    );
+    expect(skipped["email"]).toBe("a@b.c");
+  });
+
+  test("non-string pii value throws", async () => {
+    const kms = new InMemoryKmsAdapter();
+    await expect(
+      encryptPiiFieldValues({ id: UUID_A, email: 42 }, userLikeEntity, ["email"], kms, KMS_CTX),
+    ).rejects.toThrow(/must be a string/);
+  });
+
+  test("ciphertext without a key row fails loud (wrong key store, not shredded)", async () => {
+    const kmsA = new InMemoryKmsAdapter();
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, email: "a@b.c" },
+      userLikeEntity,
+      ["email"],
+      kmsA,
+      KMS_CTX,
+    );
+    const kmsB = new InMemoryKmsAdapter();
+    await expect(decryptPiiFieldValues(stored, ["email"], kmsB, KMS_CTX)).rejects.toBeInstanceOf(
+      KeyNotFoundError,
+    );
+  });
+});
+
+describe("piiEncrypted alias (kumiko-platform#457)", () => {
+  test("piiEncrypted + tenantOwned round-trips through the same subject-KMS pipeline", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const brandingWithAccess = createEntity({
+      fields: {
+        iban: createTextField({
+          piiEncrypted: true,
+          tenantOwned: true,
+          access: { read: ["TenantAdmin"] },
+        }),
+      },
+      table: "pii_branding_iban",
+    });
+    const fields = collectPiiSubjectFields(brandingWithAccess);
+    expect(fields).toEqual(["iban"]);
+
+    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(`${PII_CIPHERTEXT_PREFIX}tenant:${UUID_B}:`);
+
+    const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
+    expect(read["iban"]).toBe("DE89370400440532013000");
+  });
+
+  test("piiEncrypted field is covered by subject erasure (Art. 17, kumiko-platform#461)", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const brandingWithAccess = createEntity({
+      fields: {
+        iban: createTextField({ piiEncrypted: true, tenantOwned: true }),
+      },
+      table: "pii_branding_iban_erasure",
+    });
+    const fields = collectPiiSubjectFields(brandingWithAccess);
+    const row = { id: UUID_A, tenantId: UUID_B, iban: "DE89370400440532013000" };
+    const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX);
+
+    // Erasure is subject-keyed, not field-flag-keyed — kms.eraseKey doesn't
+    // know or care that this field is piiEncrypted vs. plain tenantOwned.
+    await kms.eraseKey({ kind: "tenant", tenantId: UUID_B });
+
+    const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
+    expect(read["iban"]).toBe(PII_ERASED_SENTINEL);
+  });
+});
+
+describe("encryptPiiValueForSubject / decryptPiiValueForSubject (kumiko-platform#459)", () => {
+  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,
+      "iban",
+    );
+    expect(isPiiCiphertext(stored)).toBe(true);
+    expect(stored).toStartWith(`${PII_CIPHERTEXT_PREFIX}tenant:${UUID_B}:`);
+
+    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,
+      "phone",
+    );
+    await kms.eraseKey(subject);
+
+    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, "value");
+    expect(read).toBe("plain-value");
+  });
+});
+
+describe("cross-subject decrypt leak (kumiko-framework#1190)", () => {
+  test("ciphertext forged to a different-but-valid subject's DEK fails GCM auth, not just KeyNotFound", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const subjectA = { kind: "tenant" as const, tenantId: UUID_A };
+    const subjectB = { kind: "tenant" as const, tenantId: UUID_B };
+    // Both subjects must have a real key — otherwise this only re-proves the
+    // 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,
+      "secret",
+    );
+    const blob = storedForB.slice(storedForB.lastIndexOf(":") + 1);
+    const forgedForA = `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subjectA)}:${blob}`;
+
+    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/__tests__/request-kms-cache.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  KeyErasedError,
+  type KmsContext,
+  type LocalKeyKmsAdapter,
+  type SubjectId,
+} from "../kms-adapter";
+import { createRequestKmsCache } from "../request-kms-cache";
+
+const ctx: KmsContext = { requestId: "cache-test" };
+const userA: SubjectId = { kind: "user", userId: "6b2f4a0e-1c9d-4f3a-9d2e-0000000000aa" };
+
+function countingAdapter(): { adapter: LocalKeyKmsAdapter; calls: () => number } {
+  const inner = new InMemoryKmsAdapter();
+  let getKeyCalls = 0;
+  const adapter: LocalKeyKmsAdapter = {
+    capabilities: { mode: "local-key" },
+    createKey: (subject) => inner.createKey(subject),
+    eraseKey: (subject) => inner.eraseKey(subject),
+    health: () => inner.health(),
+    getKey: (subject) => {
+      getKeyCalls++;
+      return inner.getKey(subject);
+    },
+  };
+  return { adapter, calls: () => getKeyCalls };
+}
+
+describe("createRequestKmsCache", () => {
+  test("second getKey for the same subject is served from cache", async () => {
+    const { adapter, calls } = countingAdapter();
+    await adapter.createKey(userA, ctx);
+    const cache = createRequestKmsCache(adapter);
+
+    const first = await cache.getKey(userA, ctx);
+    const second = await cache.getKey(userA, ctx);
+    expect(first.equals(second)).toBe(true);
+    expect(calls()).toBe(1);
+  });
+
+  test("invalidate drops the entry — next getKey hits the adapter again", async () => {
+    const { adapter, calls } = countingAdapter();
+    await adapter.createKey(userA, ctx);
+    const cache = createRequestKmsCache(adapter);
+
+    await cache.getKey(userA, ctx);
+    cache.invalidate(userA);
+    await cache.getKey(userA, ctx);
+    expect(calls()).toBe(2);
+  });
+
+  test("erase + invalidate surfaces KeyErasedError instead of a stale DEK", async () => {
+    const { adapter } = countingAdapter();
+    await adapter.createKey(userA, ctx);
+    const cache = createRequestKmsCache(adapter);
+
+    await cache.getKey(userA, ctx);
+    await adapter.eraseKey(userA, ctx);
+    cache.invalidate(userA);
+    await expect(cache.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyErasedError);
+  });
+
+  test("adapter errors are not cached — a failed lookup retries", async () => {
+    const { adapter, calls } = countingAdapter();
+    const cache = createRequestKmsCache(adapter);
+
+    await expect(cache.getKey(userA, ctx)).rejects.toThrow();
+    await adapter.createKey(userA, ctx);
+    const dek = await cache.getKey(userA, ctx);
+    expect(dek.length).toBe(32);
+    expect(calls()).toBe(2);
+  });
+});

package/src/crypto/__tests__/subject-resolver.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine/factories";
+import {
+  collectPiiSubjectFields,
+  resolveSubjectForField,
+  SubjectResolutionError,
+} from "../subject-resolver";
+
+const userLikeEntity = createEntity({
+  fields: {
+    email: createTextField({ required: true, pii: true }),
+    role: createTextField(),
+  },
+  table: "resolver_users",
+  idType: "uuid",
+});
+
+const commentEntity = createEntity({
+  fields: {
+    body: createTextField({ userOwned: { ownerField: "authorId" } }),
+    authorId: createTextField({ required: true }),
+  },
+  table: "resolver_comments",
+});
+
+const brandingEntity = createEntity({
+  fields: {
+    brandColor: createTextField({ tenantOwned: true }),
+  },
+  table: "resolver_branding",
+});
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+const UUID_B = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000b";
+
+describe("resolveSubjectForField", () => {
+  test("pii: true → the entity row itself is the user subject", () => {
+    const subject = resolveSubjectForField(userLikeEntity, "email", { id: UUID_A });
+    expect(subject).toEqual({ kind: "user", userId: UUID_A });
+  });
+
+  test("pii self-subject stringifies serial ids", () => {
+    const subject = resolveSubjectForField(userLikeEntity, "email", { id: 42 });
+    expect(subject).toEqual({ kind: "user", userId: "42" });
+  });
+
+  test("userOwned → subject comes from the owner reference field", () => {
+    const subject = resolveSubjectForField(commentEntity, "body", {
+      id: UUID_A,
+      authorId: UUID_B,
+    });
+    expect(subject).toEqual({ kind: "user", userId: UUID_B });
+  });
+
+  test("tenantOwned → subject from the row's tenantId column", () => {
+    const subject = resolveSubjectForField(brandingEntity, "brandColor", {
+      id: UUID_A,
+      tenantId: UUID_B,
+    });
+    expect(subject).toEqual({ kind: "tenant", tenantId: UUID_B });
+  });
+
+  test("tenantOwned falls back to the write-time tenantId option", () => {
+    const subject = resolveSubjectForField(
+      brandingEntity,
+      "brandColor",
+      { id: UUID_A },
+      { tenantId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "tenant", tenantId: UUID_B });
+  });
+
+  test("unannotated field → null (stays plaintext)", () => {
+    expect(resolveSubjectForField(userLikeEntity, "role", { id: UUID_A })).toBeNull();
+  });
+
+  test("empty owner reference throws instead of silently falling back to plaintext", () => {
+    expect(() => resolveSubjectForField(commentEntity, "body", { id: UUID_A })).toThrow(
+      SubjectResolutionError,
+    );
+  });
+
+  test("tenantOwned without any tenant scope throws", () => {
+    expect(() => resolveSubjectForField(brandingEntity, "brandColor", { id: UUID_A })).toThrow(
+      SubjectResolutionError,
+    );
+  });
+
+  test("pii row without id throws", () => {
+    expect(() => resolveSubjectForField(userLikeEntity, "email", {})).toThrow(
+      SubjectResolutionError,
+    );
+  });
+
+  test("unknown field name throws", () => {
+    expect(() => resolveSubjectForField(userLikeEntity, "nope", { id: UUID_A })).toThrow(
+      SubjectResolutionError,
+    );
+  });
+});
+
+describe("collectPiiSubjectFields", () => {
+  test("collects exactly the annotated fields", () => {
+    expect(collectPiiSubjectFields(userLikeEntity)).toEqual(["email"]);
+    expect(collectPiiSubjectFields(commentEntity)).toEqual(["body"]);
+    expect(collectPiiSubjectFields(brandingEntity)).toEqual(["brandColor"]);
+  });
+});

package/src/crypto/blind-index.ts

@@ -0,0 +1,118 @@
+// Blind-Index für PII-Equality-Lookups (kumiko-framework#818).
+// `lookupable: true` auf einem Subject-annotierten text-Feld erzeugt eine
+// generierte Spalte `<snake>_bidx` mit deterministischem HMAC über den
+// KLARTEXT-Wert — Equality-Queries matchen `(col = $1 OR col_bidx = $2)`
+// und funktionieren damit für Klartext-Alt-Rows UND verschlüsselte Rows.
+//
+// Wertformat: kumiko-bidx:v1:<base64url(HMAC-SHA256(key, value))>
+//
+// HMAC ist byte-exact ohne Normalisierung — repliziert exakt die heutige
+// case-sensitive Equality-Semantik (Lowercasing wäre eine Verhaltensänderung).
+//
+// Der Key ist bewusst ein EIGENER 32-Byte-Key (env: KUMIKO_BLIND_INDEX_KEY),
+// nicht vom PLATFORM_KEK abgeleitet und nicht Teil des KmsAdapter-Contracts —
+// BYOK-Adapter dürfen ihn nie sehen. Rotation = Recompute aller bidx-Spalten
+// (Rollout-Fahrplan Schritt 7).
+//
+// bidx-Werte leben NUR in der Projektion, nie in Event-Payloads: ein
+// deterministischer HMAC im immutablen Event wäre permanente Linkage und
+// bräche Forget. applyEntityEvent berechnet sie beim Apply (live + rebuild),
+// nach Key-Erase recomputet der Rebuild sie zu NULL.
+
+import { createHmac } from "node:crypto";
+import { requestContext } from "../api/request-context";
+import type { EntityDefinition } from "../engine/types/fields";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "./pii-field-encryption";
+
+const BLIND_INDEX_PREFIX = "kumiko-bidx:v1:";
+const BLIND_INDEX_KEY_LENGTH = 32;
+
+export function computeBlindIndex(key: Uint8Array, plaintext: string): string {
+  const mac = createHmac("sha256", key).update(plaintext, "utf8").digest("base64url");
+  return `${BLIND_INDEX_PREFIX}${mac}`;
+}
+
+export function decodeBlindIndexKey(base64Key: string): Uint8Array {
+  const decoded = Buffer.from(base64Key, "base64");
+  if (decoded.length !== BLIND_INDEX_KEY_LENGTH) {
+    throw new Error(
+      `Blind-index key must be ${BLIND_INDEX_KEY_LENGTH} bytes base64-encoded, got ${decoded.length} bytes. ` +
+        `Generate one: openssl rand -base64 32`,
+    );
+  }
+  return decoded;
+}
+
+// Boot-injected app-wide key, mirroring configurePiiSubjectKms: run{Prod,Dev}App
+// call configureBlindIndexKey once; query compilers + applyEntityEvent resolve
+// lazily. Absent key = blind-indexing off (bidx columns stay NULL, equality
+// lookups match plaintext rows only — pre-#818 behavior).
+let injectedKey: Uint8Array | undefined;
+
+export function configureBlindIndexKey(base64Key: string | undefined): void {
+  injectedKey = base64Key === undefined ? undefined : decodeBlindIndexKey(base64Key);
+}
+
+export function configuredBlindIndexKey(): Uint8Array | undefined {
+  return injectedKey;
+}
+
+/** @internal test-only */
+export function resetBlindIndexKeyForTests(): void {
+  injectedKey = undefined;
+}
+
+export function blindIndexFieldName(fieldName: string): string {
+  return `${fieldName}Bidx`;
+}
+
+// The field names that carry a blind index — precomputed per apply like
+// collectPiiSubjectFields. Only text fields qualify (boot-validated).
+export function collectLookupableFields(entity: EntityDefinition): readonly string[] {
+  return Object.entries(entity.fields)
+    .filter(([, field]) => field.type === "text" && field.lookupable === true)
+    .map(([name]) => name);
+}
+
+// bidx values for every lookupable field PRESENT in `values` (create payload
+// or update changes — absent fields stay untouched). Ciphertext values are
+// decrypted first so the HMAC always covers the plaintext; an erased subject
+// (or the erased sentinel) yields NULL — the lookup stops matching, which is
+// exactly the forget semantics.
+export async function computeBlindIndexValues(
+  values: Record<string, unknown>,
+  lookupableFields: readonly string[],
+): Promise<Record<string, unknown>> {
+  const key = configuredBlindIndexKey();
+  if (key === undefined || lookupableFields.length === 0) return {};
+  const out: Record<string, unknown> = {};
+  for (const name of lookupableFields) {
+    if (!(name in values)) continue;
+    out[blindIndexFieldName(name)] = await blindIndexForValue(key, name, values[name]);
+  }
+  return out;
+}
+
+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({ [field]: value }, [field], kms, {
+    requestId: requestContext.get()?.requestId ?? "blind-index",
+  });
+  const plain = decrypted[field];
+  if (typeof plain !== "string" || plain === PII_ERASED_SENTINEL) return null;
+  return computeBlindIndex(key, plain);
+}