@cosmicdrift/kumiko-framework 0.118.0 → 0.120.0

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

@@ -0,0 +1,216 @@
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine/factories";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import { KeyNotFoundError, type KmsContext, subjectIdFromKey } from "../kms-adapter";
+import {
+  decryptPiiFieldValues,
+  encryptPiiFieldValues,
+  isPiiCiphertext,
+  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(`kumiko-pii:v1: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(`kumiko-pii:v1: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(`kumiko-pii:v1: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(`kumiko-pii:v1: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,
+    );
+  });
+});

package/src/crypto/blind-index.ts

@@ -0,0 +1,114 @@
+// 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, values[name]);
+  }
+  return out;
+}
+
+async function blindIndexForValue(key: Uint8Array, 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, {
+    requestId: requestContext.get()?.requestId ?? "blind-index",
+  });
+  const plain = decrypted["value"];
+  if (typeof plain !== "string" || plain === PII_ERASED_SENTINEL) return null;
+  return computeBlindIndex(key, plain);
+}

package/src/crypto/event-pii.ts

@@ -0,0 +1,69 @@
+// PII on custom-event payloads (#799). Entity CRUD events get their PII
+// encrypted by the executor; events written via ctx.appendEvent / MSP-apply /
+// low-level append() (delivery attempt-log, jobs run-logger) had no encrypt
+// path at all. `r.defineEvent(name, schema, { piiFields })` declares which
+// payload fields are PII and which payload field names the owning user;
+// createRegistry publishes the catalog and append() — the single write funnel
+// into kumiko_events — encrypts every catalogued field. No caller can forget.
+
+import { requestContext } from "../api/request-context";
+import type { EventPiiFields } from "../engine/types/handlers";
+import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption";
+
+export type EventPiiCatalog = ReadonlyMap<string, EventPiiFields>;
+
+// Boot-injected like configurePiiSubjectKms — createRegistry calls this with
+// the catalog collected from all defineEvent registrations.
+let catalog: EventPiiCatalog = new Map();
+
+export function configureEventPiiCatalog(next: EventPiiCatalog): void {
+  catalog = next;
+}
+
+export function configuredEventPiiCatalog(): EventPiiCatalog {
+  return catalog;
+}
+
+/** @internal test-only */
+export function resetEventPiiCatalogForTests(): void {
+  catalog = new Map();
+}
+
+// Encrypts catalogued payload fields under the owning user's DEK. No-op when
+// the event type is uncatalogued or no subject KMS is configured (plaintext
+// rollout mode — the hard boot gate governs whether that is acceptable).
+// A null/absent subject field (system cron runs, recipient-less skip
+// attempts) leaves the value plaintext: there is no user key to shred.
+export async function encryptEventPayloadPii(
+  eventType: string,
+  payload: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const piiFields = catalog.get(eventType);
+  if (!piiFields) return payload;
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return payload;
+
+  let out: Record<string, unknown> | undefined;
+  for (const [field, spec] of Object.entries(piiFields)) {
+    const value = payload[field];
+    if (value === null || value === undefined) continue;
+    if (typeof value !== "string") {
+      throw new Error(
+        `Event "${eventType}" piiFields."${field}" must be a string payload field, got ${typeof value}`,
+      );
+    }
+    const subjectId = payload[spec.subjectField];
+    if (typeof subjectId !== "string" || subjectId.length === 0) continue;
+    const encrypted = await encryptPiiValueForSubject(
+      kms,
+      { kind: "user", userId: subjectId },
+      value,
+      { requestId: requestContext.get()?.requestId ?? "append-event" },
+    );
+    if (encrypted !== value) {
+      out ??= { ...payload };
+      out[field] = encrypted;
+    }
+  }
+  return out ?? payload;
+}

package/src/crypto/index.ts

@@ -1,3 +1,20 @@
+export {
+  blindIndexFieldName,
+  collectLookupableFields,
+  computeBlindIndex,
+  computeBlindIndexValues,
+  configureBlindIndexKey,
+  configuredBlindIndexKey,
+  decodeBlindIndexKey,
+  resetBlindIndexKeyForTests,
+} from "./blind-index";
+export {
+  configuredEventPiiCatalog,
+  configureEventPiiCatalog,
+  type EventPiiCatalog,
+  encryptEventPayloadPii,
+  resetEventPiiCatalogForTests,
+} from "./event-pii";
 export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
 export {
   isLocalKeyKmsAdapter,
@@ -12,10 +29,28 @@ export {
   type SubjectDek,
   type SubjectId,
   type SubjectKey,
+  subjectIdFromKey,
   subjectIdToKey,
   subjectKeyForTenant,
   subjectKeyForUser,
 } from "./kms-adapter";
+export {
+  createPgKmsAdapter,
+  PgKmsAdapter,
+  type PgKmsAdapterOptions,
+} from "./pg-kms-adapter";
+export {
+  configuredPiiSubjectKms,
+  configurePiiSubjectKms,
+  decryptPiiFieldValues,
+  type EncryptPiiOptions,
+  encryptPiiFieldValues,
+  encryptPiiValueForSubject,
+  isPiiCiphertext,
+  PII_CIPHERTEXT_PREFIX,
+  PII_ERASED_SENTINEL,
+  resetPiiSubjectKmsForTests,
+} from "./pii-field-encryption";
 export {
   createRequestKmsCache,
   type RequestKmsCache,

package/src/crypto/kms-adapter.ts

@@ -24,6 +24,14 @@ export function subjectIdToKey(subject: SubjectId): SubjectKey {
     : subjectKeyForTenant(subject.tenantId);
 }
 
+export function subjectIdFromKey(key: SubjectKey): SubjectId {
+  if (key.startsWith("user:")) return { kind: "user", userId: key.slice("user:".length) };
+  if (key.startsWith("tenant:")) {
+    return { kind: "tenant", tenantId: key.slice("tenant:".length) as TenantId }; // @cast-boundary parse of a key this module minted
+  }
+  throw new Error(`Invalid subject key: ${key}`);
+}
+
 export interface KmsContext {
   readonly tenantId?: TenantId;
   readonly requestId: string;

package/src/crypto/pg-kms-adapter.ts

@@ -0,0 +1,173 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import postgres from "postgres";
+import {
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsContext,
+  type KmsHealth,
+  type LocalKeyKmsAdapter,
+  type SubjectDek,
+  type SubjectId,
+  subjectIdToKey,
+} from "./kms-adapter";
+
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+// Envelope layout [iv:12][tag:16][ct] — the platform KEK wraps each subject
+// DEK at rest, so a subject-keys-DB dump alone reveals no key material.
+function wrapDek(kek: Buffer, dek: Buffer): Buffer {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv("aes-256-gcm", kek, iv);
+  const ciphertext = Buffer.concat([cipher.update(dek), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
+}
+
+function unwrapDek(kek: Buffer, wrapped: Uint8Array): SubjectDek {
+  const envelope = Buffer.from(wrapped);
+  const iv = envelope.subarray(0, IV_LENGTH);
+  const tag = envelope.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+  const ciphertext = envelope.subarray(IV_LENGTH + TAG_LENGTH);
+  const decipher = createDecipheriv("aes-256-gcm", kek, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+function decodePlatformKek(base64: string): Buffer {
+  const kek = Buffer.from(base64, "base64");
+  if (kek.length !== 32) {
+    throw new Error(
+      `PgKmsAdapter: platformKek must decode to 32 bytes, got ${kek.length} — expected a base64-encoded AES-256 key (openssl rand -base64 32)`,
+    );
+  }
+  return kek;
+}
+
+const PG_UNIQUE_VIOLATION = "23505";
+
+function isPgUniqueViolation(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === PG_UNIQUE_VIOLATION
+  );
+}
+
+interface SubjectKeyRow {
+  cipher_key: Uint8Array | null;
+  erased: boolean;
+}
+
+export interface PgKmsAdapterOptions {
+  /** Connection string of the DEDICATED subject-keys cluster — never the app DB (its backup retention must stay shorter, see kms-adapter.md). */
+  readonly databaseUrl: string;
+  /** Base64-encoded 32-byte platform KEK (PLATFORM_KEK env var). */
+  readonly platformKek: string;
+  readonly maxConnections?: number;
+}
+
+// Default production adapter: DEKs live in a separate Postgres cluster,
+// KEK-wrapped at rest. Schema is created lazily on first use — the
+// subject-keys cluster has no drizzle migration pipeline of its own.
+export class PgKmsAdapter implements LocalKeyKmsAdapter {
+  readonly capabilities = { mode: "local-key" } as const;
+
+  private readonly sql: ReturnType<typeof postgres>;
+  private readonly kek: Buffer;
+  private schemaReady: Promise<void> | undefined;
+
+  constructor(options: PgKmsAdapterOptions) {
+    this.kek = decodePlatformKek(options.platformKek);
+    this.sql = postgres(options.databaseUrl, {
+      max: options.maxConnections ?? 4,
+      // The connection is exclusive to this adapter and its only DDL is
+      // idempotent IF NOT EXISTS — notices are pure boot-log noise.
+      onnotice: () => {},
+    });
+  }
+
+  async createKey(subject: SubjectId, ctx: KmsContext): Promise<void> {
+    await this.ensureSchema();
+    const wrapped = wrapDek(this.kek, randomBytes(32));
+    try {
+      await this.sql`
+        INSERT INTO kumiko_subject_keys (subject_id, cipher_key, created_by)
+        VALUES (${subjectIdToKey(subject)}, ${wrapped}, ${ctx.userId ?? null})`;
+    } catch (error) {
+      if (isPgUniqueViolation(error)) throw new KeyAlreadyExistsError(subject);
+      throw error;
+    }
+  }
+
+  async getKey(subject: SubjectId, _ctx: KmsContext): Promise<SubjectDek> {
+    await this.ensureSchema();
+    const rows = await this.sql<SubjectKeyRow[]>`
+      SELECT cipher_key, (erased_at IS NOT NULL) AS erased
+      FROM kumiko_subject_keys
+      WHERE subject_id = ${subjectIdToKey(subject)}`;
+    const row = rows[0];
+    if (!row) throw new KeyNotFoundError(subject);
+    if (row.erased || row.cipher_key === null) throw new KeyErasedError(subject);
+    return unwrapDek(this.kek, row.cipher_key);
+  }
+
+  async eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void> {
+    await this.ensureSchema();
+    // Guard on erased_at IS NULL keeps repeat erases from overwriting the
+    // original tombstone audit fields; unknown subjects update zero rows.
+    await this.sql`
+      UPDATE kumiko_subject_keys
+      SET cipher_key = NULL,
+          erased_at = now(),
+          erased_by = ${ctx.userId ?? null},
+          erase_reason = ${ctx.eraseReason ?? null}
+      WHERE subject_id = ${subjectIdToKey(subject)} AND erased_at IS NULL`;
+  }
+
+  async health(): Promise<KmsHealth> {
+    const start = Date.now();
+    await this.ensureSchema();
+    await this.sql`SELECT 1`;
+    return { ok: true, latencyMs: Date.now() - start };
+  }
+
+  async close(): Promise<void> {
+    await this.sql.end();
+  }
+
+  private ensureSchema(): Promise<void> {
+    // A failed attempt resets the memo so a transient DB outage does not
+    // poison the adapter for the rest of the process lifetime.
+    this.schemaReady ??= this.createSchema().catch((error) => {
+      this.schemaReady = undefined;
+      throw error;
+    });
+    return this.schemaReady;
+  }
+
+  private async createSchema(): Promise<void> {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS kumiko_subject_keys (
+        subject_id    TEXT        PRIMARY KEY,
+        cipher_key    BYTEA,
+        kek_version   INTEGER     NOT NULL DEFAULT 1,
+        created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+        created_by    TEXT,
+        erased_at     TIMESTAMPTZ,
+        erased_by     TEXT,
+        erase_reason  TEXT
+      )`;
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS kumiko_subject_keys_erased_idx
+      ON kumiko_subject_keys (erased_at) WHERE erased_at IS NOT NULL`;
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS kumiko_subject_keys_audit_idx
+      ON kumiko_subject_keys (created_at, erased_at)`;
+  }
+}
+
+export function createPgKmsAdapter(options: PgKmsAdapterOptions): PgKmsAdapter {
+  return new PgKmsAdapter(options);
+}