@cosmicdrift/kumiko-framework 0.116.0 → 0.118.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.116.0",
+  "version": "0.118.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>",
@@ -131,6 +131,10 @@
       "types": "./src/secrets/index.ts",
       "default": "./src/secrets/index.ts"
     },
+    "./crypto": {
+      "types": "./src/crypto/index.ts",
+      "default": "./src/crypto/index.ts"
+    },
     "./schema-cli": {
       "types": "./src/schema-cli.ts",
       "default": "./src/schema-cli.ts"
@@ -181,7 +185,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.116.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.118.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/crypto/__tests__/kms-adapter-contract.ts

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+  isLocalKeyKmsAdapter,
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsAdapter,
+  type KmsContext,
+  type SubjectId,
+} from "../kms-adapter";
+
+const ctx: KmsContext = { requestId: "contract-test" };
+
+const userA: SubjectId = { kind: "user", userId: "6b2f4a0e-1c9d-4f3a-9d2e-000000000001" };
+const userB: SubjectId = { kind: "user", userId: "6b2f4a0e-1c9d-4f3a-9d2e-000000000002" };
+const tenantWithUserAId: SubjectId = {
+  kind: "tenant",
+  tenantId: "6b2f4a0e-1c9d-4f3a-9d2e-000000000001",
+};
+
+async function subjectDek(adapter: KmsAdapter, subject: SubjectId): Promise<Buffer> {
+  if (isLocalKeyKmsAdapter(adapter)) return adapter.getKey(subject, ctx);
+  // remote-crypto adapters never release keys — probe via roundtrip instead.
+  const probe = Buffer.from("contract-probe");
+  const encrypted = await adapter.encrypt(subject, probe, ctx);
+  return Buffer.from(await adapter.decrypt(subject, encrypted, ctx));
+}
+
+export function describeKmsAdapterContract(
+  name: string,
+  factory: () => KmsAdapter | Promise<KmsAdapter>,
+): void {
+  describe(`${name} — KmsAdapter contract`, () => {
+    let adapter: KmsAdapter;
+
+    beforeEach(async () => {
+      adapter = await factory();
+    });
+
+    test("createKey then getKey returns a 32-byte DEK", async () => {
+      await adapter.createKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const dek = await adapter.getKey(userA, ctx);
+      expect(dek.length).toBe(32);
+    });
+
+    test("getKey is stable — same subject, same key", async () => {
+      await adapter.createKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const first = await adapter.getKey(userA, ctx);
+      const second = await adapter.getKey(userA, ctx);
+      expect(first.equals(second)).toBe(true);
+    });
+
+    test("distinct subjects get distinct keys", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.createKey(userB, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const a = await adapter.getKey(userA, ctx);
+      const b = await adapter.getKey(userB, ctx);
+      expect(a.equals(b)).toBe(false);
+    });
+
+    test("user and tenant subjects with the same raw id are distinct", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.createKey(tenantWithUserAId, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const user = await adapter.getKey(userA, ctx);
+      const tenant = await adapter.getKey(tenantWithUserAId, ctx);
+      expect(user.equals(tenant)).toBe(false);
+    });
+
+    test("createKey twice throws KeyAlreadyExistsError", async () => {
+      await adapter.createKey(userA, ctx);
+      await expect(adapter.createKey(userA, ctx)).rejects.toBeInstanceOf(KeyAlreadyExistsError);
+    });
+
+    test("getKey for an unknown subject throws KeyNotFoundError", async () => {
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyNotFoundError);
+    });
+
+    test("eraseKey makes getKey throw KeyErasedError", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyErasedError);
+    });
+
+    test("eraseKey is idempotent — second call is a no-op", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyErasedError);
+    });
+
+    test("eraseKey for an unknown subject is a no-op", async () => {
+      await adapter.eraseKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyNotFoundError);
+    });
+
+    test("createKey after eraseKey throws — the tombstone blocks a new key", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      await expect(adapter.createKey(userA, ctx)).rejects.toBeInstanceOf(KeyAlreadyExistsError);
+    });
+
+    test("erasing one subject leaves other subjects intact", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.createKey(userB, ctx);
+      await adapter.eraseKey(userA, ctx);
+      const dek = await subjectDek(adapter, userB);
+      expect(dek.length).toBeGreaterThan(0);
+    });
+
+    test("remote-crypto adapters roundtrip encrypt/decrypt", async () => {
+      if (isLocalKeyKmsAdapter(adapter)) return;
+      await adapter.createKey(userA, ctx);
+      const plaintext = Buffer.from("marc@example.com");
+      const ciphertext = await adapter.encrypt(userA, plaintext, ctx);
+      expect(Buffer.from(ciphertext).equals(plaintext)).toBe(false);
+      const roundtrip = await adapter.decrypt(userA, ciphertext, ctx);
+      expect(Buffer.from(roundtrip).equals(plaintext)).toBe(true);
+    });
+
+    test("health reports ok for a reachable adapter", async () => {
+      const health = await adapter.health();
+      expect(health.ok).toBe(true);
+      expect(health.latencyMs).toBeGreaterThanOrEqual(0);
+    });
+  });
+}

package/src/crypto/__tests__/kms-adapter.contract.test.ts

@@ -0,0 +1,4 @@
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import { describeKmsAdapterContract } from "./kms-adapter-contract";
+
+describeKmsAdapterContract("InMemoryKmsAdapter", () => new InMemoryKmsAdapter());

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/in-memory-kms-adapter.ts

@@ -0,0 +1,50 @@
+import { randomBytes } from "node:crypto";
+import {
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsHealth,
+  type LocalKeyKmsAdapter,
+  type SubjectDek,
+  type SubjectId,
+  type SubjectKey,
+  subjectIdToKey,
+} from "./kms-adapter";
+
+interface KeyEntry {
+  key: Buffer | null;
+  erased: boolean;
+}
+
+// Non-persistent adapter for tests and dev mode. Erased entries stay as
+// tombstones so the create-after-erase contract holds within a process.
+export class InMemoryKmsAdapter implements LocalKeyKmsAdapter {
+  readonly capabilities = { mode: "local-key" } as const;
+
+  private readonly keys = new Map<SubjectKey, KeyEntry>();
+
+  async createKey(subject: SubjectId): Promise<void> {
+    const subjectKey = subjectIdToKey(subject);
+    if (this.keys.has(subjectKey)) throw new KeyAlreadyExistsError(subject);
+    this.keys.set(subjectKey, { key: randomBytes(32), erased: false });
+  }
+
+  async getKey(subject: SubjectId): Promise<SubjectDek> {
+    const entry = this.keys.get(subjectIdToKey(subject));
+    if (!entry) throw new KeyNotFoundError(subject);
+    if (entry.erased || entry.key === null) throw new KeyErasedError(subject);
+    return entry.key;
+  }
+
+  async eraseKey(subject: SubjectId): Promise<void> {
+    const entry = this.keys.get(subjectIdToKey(subject));
+    // skip: eraseKey is contractually idempotent — unknown subject is a no-op
+    if (!entry) return;
+    entry.key = null;
+    entry.erased = true;
+  }
+
+  async health(): Promise<KmsHealth> {
+    return { ok: true, latencyMs: 0 };
+  }
+}

package/src/crypto/index.ts

@@ -0,0 +1,28 @@
+export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
+export {
+  isLocalKeyKmsAdapter,
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsAdapter,
+  type KmsContext,
+  type KmsHealth,
+  type LocalKeyKmsAdapter,
+  type RemoteCryptoKmsAdapter,
+  type SubjectDek,
+  type SubjectId,
+  type SubjectKey,
+  subjectIdToKey,
+  subjectKeyForTenant,
+  subjectKeyForUser,
+} from "./kms-adapter";
+export {
+  createRequestKmsCache,
+  type RequestKmsCache,
+} from "./request-kms-cache";
+export {
+  collectPiiSubjectFields,
+  type ResolveSubjectOptions,
+  resolveSubjectForField,
+  SubjectResolutionError,
+} from "./subject-resolver";

package/src/crypto/kms-adapter.ts

@@ -0,0 +1,110 @@
+import type { TenantId } from "../engine/types/identifiers";
+
+// The subject a DEK belongs to. User data is shredded on user-forget,
+// tenant data on tenant-destroy — two erase triggers, two subject kinds.
+export type SubjectId =
+  | { readonly kind: "user"; readonly userId: string }
+  | { readonly kind: "tenant"; readonly tenantId: TenantId };
+
+// Compact storage key ("user:<uuid>" / "tenant:<uuid>") — primary key in
+// adapter backends and cache key in the request-level DEK cache.
+export type SubjectKey = string;
+
+export function subjectKeyForUser(userId: string): SubjectKey {
+  return `user:${userId}`;
+}
+
+export function subjectKeyForTenant(tenantId: TenantId): SubjectKey {
+  return `tenant:${tenantId}`;
+}
+
+export function subjectIdToKey(subject: SubjectId): SubjectKey {
+  return subject.kind === "user"
+    ? subjectKeyForUser(subject.userId)
+    : subjectKeyForTenant(subject.tenantId);
+}
+
+export interface KmsContext {
+  readonly tenantId?: TenantId;
+  readonly requestId: string;
+  readonly userId?: string;
+  readonly eraseReason?: string;
+}
+
+export interface KmsHealth {
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  readonly details?: Record<string, unknown>;
+}
+
+// 32-byte AES-256 data-encryption key, unwrapped and ready for local use.
+export type SubjectDek = Buffer;
+
+interface KmsAdapterBase {
+  /**
+   * Creates a fresh subject key. Throws KeyAlreadyExistsError when the
+   * subject already has one — including an erased tombstone: a shredded
+   * subject must never get a new key, or forget could be undone by
+   * re-encrypting under it.
+   */
+  createKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+
+  /**
+   * Erases the key material immediately; the tombstone row stays for the
+   * audit trail. Idempotent — repeat calls and unknown subjects are no-ops.
+   */
+  eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+
+  /** Probe for boot + readiness. Throws when the backend is unreachable. */
+  health(): Promise<KmsHealth>;
+}
+
+// Backends that hand out the plaintext DEK (Pg, InMemory). Encrypt/decrypt
+// happens locally; DEKs are cacheable per request.
+export interface LocalKeyKmsAdapter extends KmsAdapterBase {
+  readonly capabilities: { readonly mode: "local-key" };
+
+  /**
+   * Throws KeyErasedError after eraseKey (callers render "[[erased]]"),
+   * KeyNotFoundError when the subject never had a key (typically a bug).
+   */
+  getKey(subject: SubjectId, ctx: KmsContext): Promise<SubjectDek>;
+}
+
+// Backends that never release key material (Vault transit, cloud KMS).
+// Every encrypt/decrypt is a round-trip; nothing is cacheable.
+export interface RemoteCryptoKmsAdapter extends KmsAdapterBase {
+  readonly capabilities: { readonly mode: "remote-crypto" };
+
+  encrypt(subject: SubjectId, plaintext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
+
+  /** Same error contract as LocalKeyKmsAdapter.getKey. */
+  decrypt(subject: SubjectId, ciphertext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
+}
+
+export type KmsAdapter = LocalKeyKmsAdapter | RemoteCryptoKmsAdapter;
+
+export function isLocalKeyKmsAdapter(adapter: KmsAdapter): adapter is LocalKeyKmsAdapter {
+  return adapter.capabilities.mode === "local-key";
+}
+
+export class KeyErasedError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key erased: ${subjectIdToKey(subject)}`);
+    this.name = "KeyErasedError";
+  }
+}
+
+export class KeyNotFoundError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key not found: ${subjectIdToKey(subject)}`);
+    this.name = "KeyNotFoundError";
+  }
+}
+
+export class KeyAlreadyExistsError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key already exists: ${subjectIdToKey(subject)}`);
+    this.name = "KeyAlreadyExistsError";
+  }
+}

package/src/crypto/request-kms-cache.ts

@@ -0,0 +1,38 @@
+import type {
+  KmsContext,
+  LocalKeyKmsAdapter,
+  SubjectDek,
+  SubjectId,
+  SubjectKey,
+} from "./kms-adapter";
+import { subjectIdToKey } from "./kms-adapter";
+
+// Per-request DEK cache: a list rendering 50 comments of one author does one
+// adapter round-trip, not 50. Only meaningful for local-key adapters —
+// remote-crypto backends never release keys, every call is a round-trip.
+export interface RequestKmsCache {
+  getKey(subject: SubjectId, ctx: KmsContext): Promise<SubjectDek>;
+  /** Drops one subject's cached DEK — called when its key is shredded mid-request. */
+  invalidate(subject: SubjectId): void;
+  clear(): void;
+}
+
+export function createRequestKmsCache(adapter: LocalKeyKmsAdapter): RequestKmsCache {
+  const cache = new Map<SubjectKey, SubjectDek>();
+  return {
+    async getKey(subject, ctx) {
+      const subjectKey = subjectIdToKey(subject);
+      const hit = cache.get(subjectKey);
+      if (hit !== undefined) return hit;
+      const dek = await adapter.getKey(subject, ctx);
+      cache.set(subjectKey, dek);
+      return dek;
+    },
+    invalidate(subject) {
+      cache.delete(subjectIdToKey(subject));
+    },
+    clear() {
+      cache.clear();
+    },
+  };
+}

package/src/crypto/subject-resolver.ts

@@ -0,0 +1,91 @@
+import type { EntityDefinition } from "../engine/types/fields";
+import type { TenantId } from "../engine/types/identifiers";
+import type { SubjectId } from "./kms-adapter";
+
+// Thrown when a field IS pii-annotated but the row can't name its subject —
+// that must surface as an error, not fall back to plaintext.
+export class SubjectResolutionError extends Error {
+  constructor(
+    public readonly fieldName: string,
+    reason: string,
+  ) {
+    super(`Cannot resolve PII subject for field "${fieldName}": ${reason}`);
+    this.name = "SubjectResolutionError";
+  }
+}
+
+export interface ResolveSubjectOptions {
+  // Write-time tenant scope — consulted for tenantOwned fields when the row
+  // itself carries no tenantId column.
+  readonly tenantId?: TenantId;
+}
+
+function nonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Maps a pii-annotated field to the subject whose key encrypts it.
+ * Returns null for fields without any PII annotation (stored plaintext).
+ *
+ * Precedence for multi-annotated fields mirrors the erase triggers:
+ * userOwned (user-forget) > tenantOwned (tenant-destroy) > pii (self).
+ */
+export function resolveSubjectForField(
+  entity: EntityDefinition,
+  fieldName: string,
+  row: Record<string, unknown>,
+  opts: ResolveSubjectOptions = {},
+): SubjectId | null {
+  const field = entity.fields[fieldName];
+  if (!field) throw new SubjectResolutionError(fieldName, "field is not defined on the entity");
+
+  if ("userOwned" in field && field.userOwned !== undefined) {
+    const ownerField = field.userOwned.ownerField;
+    const userId = nonEmptyString(row[ownerField]);
+    if (userId === null) {
+      throw new SubjectResolutionError(
+        fieldName,
+        `owner field "${ownerField}" is empty on the row`,
+      );
+    }
+    return { kind: "user", userId };
+  }
+
+  if ("tenantOwned" in field && field.tenantOwned === true) {
+    const tenantId = nonEmptyString(row["tenantId"]) ?? opts.tenantId;
+    if (tenantId === undefined) {
+      throw new SubjectResolutionError(
+        fieldName,
+        "row has no tenantId column and no write-time tenantId was provided",
+      );
+    }
+    return { kind: "tenant", tenantId };
+  }
+
+  if ("pii" in field && field.pii === true) {
+    // pii: true = the entity itself is the subject (user.email belongs to
+    // that user row). Serial ids are stringified — subject keys are text.
+    const id = row["id"];
+    const userId = nonEmptyString(id) ?? (typeof id === "number" ? String(id) : null);
+    if (userId === null) {
+      throw new SubjectResolutionError(fieldName, "row has no id to use as the pii self-subject");
+    }
+    return { kind: "user", userId };
+  }
+
+  return null;
+}
+
+// The field names an encrypt engine must process for an entity — precomputed
+// once at executor build time, like the sensitiveFields set.
+export function collectPiiSubjectFields(entity: EntityDefinition): readonly string[] {
+  return Object.entries(entity.fields)
+    .filter(
+      ([, field]) =>
+        ("userOwned" in field && field.userOwned !== undefined) ||
+        ("tenantOwned" in field && field.tenantOwned === true) ||
+        ("pii" in field && field.pii === true),
+    )
+    .map(([name]) => name);
+}

package/src/engine/types/handlers.ts

@@ -267,6 +267,10 @@ type SharedContextFields = {
   // job which deliberately operates outside the per-call audit trail (it
   // processes rows system-wide, not a per-user read).
   readonly masterKeyProvider?: import("../../secrets").MasterKeyProvider;
+  // Subject-key adapter for crypto-shredding (GDPR Art. 17). Present when
+  // the app wired a KmsAdapter at boot; the PII envelope engine and the
+  // forget pipeline reach for it. Absent = crypto-shredding not enabled.
+  readonly kms?: import("../../crypto").KmsAdapter;
   // Observability: optional at the outer boundary, always populated by the
   // time a handler receives its ctx (Noop fallback when no provider is
   // configured, so handler code can call ctx.tracer/ctx.metrics without