@cosmicdrift/kumiko-framework 0.119.0 → 0.121.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.119.0",
+  "version": "0.121.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -185,7 +185,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.119.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.121.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/crypto/__tests__/event-pii.test.ts

@@ -0,0 +1,161 @@
+// Event-PII catalog (#799): defineEvent({ piiFields }) → createRegistry
+// publishes the catalog → encryptEventPayloadPii encrypts under the owning
+// user's DEK. append() applies this on every write path; the pure pieces
+// are testable without a database.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createRegistry, defineFeature } from "../../engine";
+import {
+  configuredEventPiiCatalog,
+  configureEventPiiCatalog,
+  encryptEventPayloadPii,
+  resetEventPiiCatalogForTests,
+} from "../event-pii";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  configurePiiSubjectKms,
+  decryptPiiFieldValues,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+  resetPiiSubjectKmsForTests,
+} from "../pii-field-encryption";
+
+const attemptSchema = z.object({
+  recipientId: z.string().nullable(),
+  recipientAddress: z.string().nullable(),
+  status: z.string(),
+});
+
+const EVENT_TYPE = "mailer:event:attempt";
+
+function catalogWithAttempt(): void {
+  configureEventPiiCatalog(
+    new Map([[EVENT_TYPE, { recipientAddress: { subjectField: "recipientId" } }]]),
+  );
+}
+
+afterEach(() => {
+  resetEventPiiCatalogForTests();
+  resetPiiSubjectKmsForTests();
+});
+
+describe("defineEvent piiFields validation", () => {
+  test("valid piiFields land on the EventDef and in the registry catalog", () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema, {
+        piiFields: { recipientAddress: { subjectField: "recipientId" } },
+      });
+    });
+    createRegistry([feature]);
+    expect(configuredEventPiiCatalog().get(EVENT_TYPE)).toEqual({
+      recipientAddress: { subjectField: "recipientId" },
+    });
+  });
+
+  test("pii field not on the payload schema throws at definition time", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { nope: { subjectField: "recipientId" } },
+        });
+      }),
+    ).toThrow(/piiFields references "nope"/);
+  });
+
+  test("unknown subjectField throws at definition time", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { subjectField: "ownerId" } },
+        });
+      }),
+    ).toThrow(/piiFields references "ownerId"/);
+  });
+
+  test("field cannot be its own subjectField", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { subjectField: "recipientAddress" } },
+        });
+      }),
+    ).toThrow(/cannot use itself as subjectField/);
+  });
+
+  test("events without piiFields do not enter the catalog", () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema);
+    });
+    createRegistry([feature]);
+    expect(configuredEventPiiCatalog().size).toBe(0);
+  });
+});
+
+describe("encryptEventPayloadPii", () => {
+  const payload = { recipientId: "u-1", recipientAddress: "u1@example.com", status: "sent" };
+
+  test("uncatalogued event type returns the payload untouched (same reference)", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    expect(await encryptEventPayloadPii("other:event:x", payload)).toBe(payload);
+  });
+
+  test("no KMS configured → plaintext passthrough (rollout mode)", async () => {
+    catalogWithAttempt();
+    expect(await encryptEventPayloadPii(EVENT_TYPE, payload)).toBe(payload);
+  });
+
+  test("encrypts under the subject's DEK; subject fk stays plaintext", async () => {
+    catalogWithAttempt();
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+
+    const out = await encryptEventPayloadPii(EVENT_TYPE, payload);
+    expect(isPiiCiphertext(out["recipientAddress"])).toBe(true);
+    expect(String(out["recipientAddress"])).toContain("user:u-1");
+    expect(out["recipientId"]).toBe("u-1");
+    expect(out["status"]).toBe("sent");
+
+    const back = await decryptPiiFieldValues(out, ["recipientAddress"], kms, {
+      requestId: "test",
+    });
+    expect(back["recipientAddress"]).toBe("u1@example.com");
+  });
+
+  test("null subject field → value stays plaintext (no user key to shred)", async () => {
+    catalogWithAttempt();
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const systemPayload = {
+      recipientId: null,
+      recipientAddress: "ops@example.com",
+      status: "sent",
+    };
+    expect(await encryptEventPayloadPii(EVENT_TYPE, systemPayload)).toBe(systemPayload);
+  });
+
+  test("null pii value passes through", async () => {
+    catalogWithAttempt();
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const skipped = { recipientId: "u-1", recipientAddress: null, status: "skipped" };
+    expect(await encryptEventPayloadPii(EVENT_TYPE, skipped)).toBe(skipped);
+  });
+
+  test("idempotent: ciphertext and erased sentinel stay as-is", async () => {
+    catalogWithAttempt();
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const once = await encryptEventPayloadPii(EVENT_TYPE, payload);
+    const twice = await encryptEventPayloadPii(EVENT_TYPE, once);
+    expect(twice["recipientAddress"]).toBe(once["recipientAddress"]);
+
+    const erased = { ...payload, recipientAddress: PII_ERASED_SENTINEL };
+    const out = await encryptEventPayloadPii(EVENT_TYPE, erased);
+    expect(out["recipientAddress"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("non-string pii value is a loud error, not a silent skip", async () => {
+    catalogWithAttempt();
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const broken = { recipientId: "u-1", recipientAddress: 42, status: "sent" };
+    expect(encryptEventPayloadPii(EVENT_TYPE, broken)).rejects.toThrow(/must be a string/);
+  });
+});

package/src/crypto/__tests__/kek-rotation.integration.test.ts

@@ -0,0 +1,180 @@
+// KEK rotation (#818 step 7): mid-rotation an adapter with the NEW active
+// KEK + previousKeks reads old-generation rows; rewrapSubjectKeys migrates
+// the estate to the new generation; afterwards previousKeks can be dropped.
+// Erased tombstones stay untouched, unknown generations fail loud as a
+// CONFIG error (not a shredded subject).
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import postgres from "postgres";
+import { createTestDb } from "../../stack/db";
+import type { KmsContext, SubjectId } from "../kms-adapter";
+import { createPgKmsAdapter, rewrapSubjectKeys } from "../pg-kms-adapter";
+
+const baseUrl = process.env["TEST_DATABASE_URL"];
+if (!baseUrl) throw new Error("Missing required env var: TEST_DATABASE_URL");
+
+const testDb = await createTestDb();
+const DB_URL = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+
+const KEK_V1 = Buffer.alloc(32, 1).toString("base64");
+const KEK_V2 = Buffer.alloc(32, 2).toString("base64");
+const ctx: KmsContext = { requestId: "kek-rotation-test" };
+const freshUser = (): SubjectId => ({ kind: "user", userId: randomUUID() });
+
+const raw = postgres(DB_URL, { max: 1, onnotice: () => {} });
+
+afterAll(async () => {
+  await raw.end();
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  const boot = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+  await boot.health();
+  await boot.close();
+  await raw`TRUNCATE kumiko_subject_keys`;
+});
+
+async function seedV1Keys(count: number): Promise<SubjectId[]> {
+  const v1 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+  const subjects: SubjectId[] = [];
+  for (let i = 0; i < count; i++) {
+    const subject = freshUser();
+    await v1.createKey(subject, ctx);
+    subjects.push(subject);
+  }
+  await v1.close();
+  return subjects;
+}
+
+describe("KEK rotation", () => {
+  test("mid-rotation adapter (new active + previousKeks) reads v1 rows; new writes carry v2", async () => {
+    const [oldSubject] = await seedV1Keys(1);
+    if (!oldSubject) throw new Error("seed failed");
+
+    const rotating = createPgKmsAdapter({
+      databaseUrl: DB_URL,
+      platformKek: KEK_V2,
+      kekVersion: 2,
+      previousKeks: { 1: KEK_V1 },
+    });
+    const dek = await rotating.getKey(oldSubject, ctx);
+    expect(dek.length).toBe(32);
+
+    const newSubject = freshUser();
+    await rotating.createKey(newSubject, ctx);
+    const versions = await raw<Array<{ kek_version: number }>>`
+      SELECT kek_version FROM kumiko_subject_keys ORDER BY kek_version`;
+    expect(versions.map((r) => r.kek_version)).toEqual([1, 2]);
+    await rotating.close();
+  });
+
+  test("unknown generation without previousKeks is a loud config error", async () => {
+    const [oldSubject] = await seedV1Keys(1);
+    if (!oldSubject) throw new Error("seed failed");
+
+    const misconfigured = createPgKmsAdapter({
+      databaseUrl: DB_URL,
+      platformKek: KEK_V2,
+      kekVersion: 2,
+    });
+    expect(misconfigured.getKey(oldSubject, ctx)).rejects.toThrow(/pass previousKeks/);
+    await misconfigured.close();
+  });
+
+  test("previousKeks newer than the active version is rejected at construction", () => {
+    expect(() =>
+      createPgKmsAdapter({
+        databaseUrl: DB_URL,
+        platformKek: KEK_V1,
+        kekVersion: 1,
+        previousKeks: { 2: KEK_V2 },
+      }),
+    ).toThrow(/must be older/);
+  });
+
+  test("rewrapSubjectKeys migrates the estate; DEKs stay identical; idempotent", async () => {
+    const subjects = await seedV1Keys(3);
+    const v1 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+    const before = await Promise.all(subjects.map((s) => v1.getKey(s, ctx)));
+    await v1.close();
+
+    const result = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+      batchSize: 2,
+    });
+    expect(result.failures).toEqual([]);
+    expect(result.rewrapped).toBe(3);
+
+    // The rotated estate is fully readable with ONLY the new KEK — and the
+    // unwrapped DEKs are byte-identical (stored ciphertext stays decryptable).
+    const v2 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V2, kekVersion: 2 });
+    const after = await Promise.all(subjects.map((s) => v2.getKey(s, ctx)));
+    for (const [i, dek] of after.entries()) {
+      expect(dek.equals(before[i] as Buffer)).toBe(true);
+    }
+    await v2.close();
+
+    const second = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+    });
+    expect(second.scanned).toBe(0);
+    expect(second.rewrapped).toBe(0);
+  });
+
+  test("erased tombstones are skipped and stay erased", async () => {
+    const [gone] = await seedV1Keys(1);
+    if (!gone) throw new Error("seed failed");
+    const v1 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+    await v1.eraseKey(gone, ctx);
+    await v1.close();
+
+    const result = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+    });
+    expect(result.skippedErased).toBe(1);
+    expect(result.rewrapped).toBe(0);
+
+    const rows = await raw<Array<{ cipher_key: Uint8Array | null }>>`
+      SELECT cipher_key FROM kumiko_subject_keys`;
+    expect(rows[0]?.cipher_key).toBeNull();
+  });
+
+  test("dryRun counts but writes nothing", async () => {
+    await seedV1Keys(2);
+    const dry = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+      dryRun: true,
+    });
+    expect(dry.rewrapped).toBe(2);
+    const versions = await raw<Array<{ kek_version: number }>>`
+      SELECT DISTINCT kek_version FROM kumiko_subject_keys`;
+    expect(versions.map((r) => r.kek_version)).toEqual([1]);
+  });
+
+  test("missing fromKek for a generation lands in failures, not a crash", async () => {
+    await seedV1Keys(1);
+    const result = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: {},
+      toKek: KEK_V2,
+      toKekVersion: 2,
+    });
+    expect(result.rewrapped).toBe(0);
+    expect(result.failures).toHaveLength(1);
+    expect(result.failures[0]?.reason).toContain("no fromKek configured");
+  });
+});

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

@@ -8,6 +8,13 @@ export {
   decodeBlindIndexKey,
   resetBlindIndexKeyForTests,
 } from "./blind-index";
+export {
+  configuredEventPiiCatalog,
+  configureEventPiiCatalog,
+  type EventPiiCatalog,
+  encryptEventPayloadPii,
+  resetEventPiiCatalogForTests,
+} from "./event-pii";
 export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
 export {
   isLocalKeyKmsAdapter,
@@ -31,6 +38,9 @@ export {
   createPgKmsAdapter,
   PgKmsAdapter,
   type PgKmsAdapterOptions,
+  type RewrapOptions,
+  type RewrapResult,
+  rewrapSubjectKeys,
 } from "./pg-kms-adapter";
 export {
   configuredPiiSubjectKms,
@@ -38,6 +48,7 @@ export {
   decryptPiiFieldValues,
   type EncryptPiiOptions,
   encryptPiiFieldValues,
+  encryptPiiValueForSubject,
   isPiiCiphertext,
   PII_CIPHERTEXT_PREFIX,
   PII_ERASED_SENTINEL,

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

@@ -57,6 +57,7 @@ function isPgUniqueViolation(error: unknown): boolean {
 
 interface SubjectKeyRow {
   cipher_key: Uint8Array | null;
+  kek_version: number;
   erased: boolean;
 }
 
@@ -65,6 +66,13 @@ export interface PgKmsAdapterOptions {
   readonly databaseUrl: string;
   /** Base64-encoded 32-byte platform KEK (PLATFORM_KEK env var). */
   readonly platformKek: string;
+  /** Version of `platformKek` as stored in kumiko_subject_keys.kek_version.
+   *  Bump on rotation; new wraps carry this version. Default 1. */
+  readonly kekVersion?: number;
+  /** Older KEKs by version, kept ONLY during a rotation window so rows not
+   *  yet re-wrapped stay readable. Drop after rewrapSubjectKeys reports the
+   *  estate fully on the active version (runbook: kek-rotation.md). */
+  readonly previousKeks?: Readonly<Record<number, string>>;
   readonly maxConnections?: number;
 }
 
@@ -76,10 +84,24 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
 
   private readonly sql: ReturnType<typeof postgres>;
   private readonly kek: Buffer;
+  private readonly kekVersion: number;
+  private readonly previousKeks: ReadonlyMap<number, Buffer>;
   private schemaReady: Promise<void> | undefined;
 
   constructor(options: PgKmsAdapterOptions) {
     this.kek = decodePlatformKek(options.platformKek);
+    this.kekVersion = options.kekVersion ?? 1;
+    const previous = new Map<number, Buffer>();
+    for (const [version, kek] of Object.entries(options.previousKeks ?? {})) {
+      const v = Number(version);
+      if (v >= this.kekVersion) {
+        throw new Error(
+          `PgKmsAdapter: previousKeks[${v}] must be older than the active kekVersion ${this.kekVersion}`,
+        );
+      }
+      previous.set(v, decodePlatformKek(kek));
+    }
+    this.previousKeks = previous;
     this.sql = postgres(options.databaseUrl, {
       max: options.maxConnections ?? 4,
       // The connection is exclusive to this adapter and its only DDL is
@@ -93,8 +115,8 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
     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})`;
+        INSERT INTO kumiko_subject_keys (subject_id, cipher_key, kek_version, created_by)
+        VALUES (${subjectIdToKey(subject)}, ${wrapped}, ${this.kekVersion}, ${ctx.userId ?? null})`;
     } catch (error) {
       if (isPgUniqueViolation(error)) throw new KeyAlreadyExistsError(subject);
       throw error;
@@ -104,13 +126,25 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
   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
+      SELECT cipher_key, kek_version, (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);
+    return unwrapDek(this.kekFor(row.kek_version, subject), row.cipher_key);
+  }
+
+  // Rows keep working mid-rotation: not-yet-rewrapped DEKs name their KEK
+  // generation and unwrap with the matching previous key. A version with no
+  // configured key is a hard config error — NOT a shredded subject.
+  private kekFor(version: number, subject: SubjectId): Buffer {
+    if (version === this.kekVersion) return this.kek;
+    const previous = this.previousKeks.get(version);
+    if (previous) return previous;
+    throw new Error(
+      `PgKmsAdapter: subject ${subjectIdToKey(subject)} is wrapped with KEK version ${version} but only version ${this.kekVersion}${this.previousKeks.size > 0 ? ` (+previous ${[...this.previousKeks.keys()].join(",")})` : ""} is configured — pass previousKeks during rotation (runbook: kek-rotation.md).`,
+    );
   }
 
   async eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void> {
@@ -171,3 +205,91 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
 export function createPgKmsAdapter(options: PgKmsAdapterOptions): PgKmsAdapter {
   return new PgKmsAdapter(options);
 }
+
+export interface RewrapOptions {
+  readonly databaseUrl: string;
+  /** Older KEKs by version — every version still present in the table must be covered. */
+  readonly fromKeks: Readonly<Record<number, string>>;
+  /** The new active KEK and its version (previous active version + 1). */
+  readonly toKek: string;
+  readonly toKekVersion: number;
+  readonly batchSize?: number;
+  readonly dryRun?: boolean;
+}
+
+export interface RewrapResult {
+  readonly scanned: number;
+  readonly rewrapped: number;
+  readonly skippedErased: number;
+  readonly failures: ReadonlyArray<{ readonly subjectId: string; readonly reason: string }>;
+}
+
+// One-time KEK rotation (runbook: kek-rotation.md). Unwraps every live DEK
+// wrapped with an older KEK generation and re-wraps it under the new KEK,
+// bumping kek_version. Idempotent: rows already on toKekVersion are not
+// selected; a second run reports 0. Erased tombstones (cipher_key NULL) are
+// never touched. The UPDATE is guarded on the row's old kek_version, so a
+// concurrent app writing fresh keys on the new version is never clobbered.
+export async function rewrapSubjectKeys(options: RewrapOptions): Promise<RewrapResult> {
+  const toKek = decodePlatformKek(options.toKek);
+  const fromKeks = new Map<number, Buffer>();
+  for (const [version, kek] of Object.entries(options.fromKeks)) {
+    fromKeks.set(Number(version), decodePlatformKek(kek));
+  }
+  const batchSize = options.batchSize ?? 200;
+  const sql = postgres(options.databaseUrl, { max: 2, onnotice: () => {} });
+
+  const result = {
+    scanned: 0,
+    rewrapped: 0,
+    skippedErased: 0,
+    failures: [] as Array<{ subjectId: string; reason: string }>,
+  };
+  try {
+    let cursor = "";
+    for (;;) {
+      const rows = await sql<
+        Array<{ subject_id: string; cipher_key: Uint8Array | null; kek_version: number }>
+      >`
+        SELECT subject_id, cipher_key, kek_version
+        FROM kumiko_subject_keys
+        WHERE kek_version <> ${options.toKekVersion} AND subject_id > ${cursor}
+        ORDER BY subject_id ASC
+        LIMIT ${batchSize}`;
+      if (rows.length === 0) break;
+
+      for (const row of rows) {
+        result.scanned++;
+        if (row.cipher_key === null) {
+          result.skippedErased++;
+          continue;
+        }
+        try {
+          const fromKek = fromKeks.get(row.kek_version);
+          if (!fromKek) {
+            throw new Error(`no fromKek configured for kek_version ${row.kek_version}`);
+          }
+          const rewrapped = wrapDek(toKek, unwrapDek(fromKek, row.cipher_key));
+          if (!options.dryRun) {
+            await sql`
+              UPDATE kumiko_subject_keys
+              SET cipher_key = ${rewrapped}, kek_version = ${options.toKekVersion}
+              WHERE subject_id = ${row.subject_id} AND kek_version = ${row.kek_version}`;
+          }
+          result.rewrapped++;
+        } catch (error) {
+          result.failures.push({
+            subjectId: row.subject_id,
+            reason: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+      const last = rows[rows.length - 1];
+      if (last === undefined) break;
+      cursor = last.subject_id;
+    }
+  } finally {
+    await sql.end();
+  }
+  return result;
+}

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

@@ -85,6 +85,20 @@ async function getOrCreateDek(
   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.