@cosmicdrift/kumiko-framework 0.116.1 → 0.119.0

package/src/crypto/kms-adapter.ts

@@ -0,0 +1,118 @@
+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 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;
+  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/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);
+}

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

@@ -0,0 +1,181 @@
+// PII field encryption with per-subject DEKs (crypto-shredding, #724 phase C).
+// Same executor hook points as `encrypted: true`, but the key belongs to the
+// erase subject — kms.eraseKey(subject) makes every value unreadable at once.
+// Storage format is a sniffable string that fits existing text columns and
+// names its subject inline, so decrypt needs no schema change and no resolver:
+//   kumiko-pii:v1:<subjectKey>:<base64(iv|tag|ciphertext)>
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { EntityDefinition } from "../engine/types/fields";
+import type { TenantId } from "../engine/types/identifiers";
+import {
+  isLocalKeyKmsAdapter,
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsAdapter,
+  type KmsContext,
+  type LocalKeyKmsAdapter,
+  type SubjectDek,
+  type SubjectId,
+  subjectIdFromKey,
+  subjectIdToKey,
+} from "./kms-adapter";
+import { resolveSubjectForField } from "./subject-resolver";
+
+// Spec value (crypto-shredding.md) — renderers show it verbatim.
+export const PII_ERASED_SENTINEL = "[[erased]]";
+
+export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v1:";
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+
+export function isPiiCiphertext(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith(PII_CIPHERTEXT_PREFIX);
+}
+
+function encryptValue(subject: SubjectId, dek: SubjectDek, plaintext: string): string {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv("aes-256-gcm", dek, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const blob = Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
+  return `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subject)}:${blob.toString("base64")}`;
+}
+
+function parseCiphertext(value: string): { subject: SubjectId; blob: Buffer } {
+  const rest = value.slice(PII_CIPHERTEXT_PREFIX.length);
+  // subjectKey itself contains ":" ("user:<id>") — base64 never does, so the
+  // last ":" is always the key/blob separator.
+  const sep = rest.lastIndexOf(":");
+  if (sep === -1) throw new Error(`Malformed PII ciphertext (no subject/blob separator)`);
+  return {
+    subject: subjectIdFromKey(rest.slice(0, sep)),
+    blob: Buffer.from(rest.slice(sep + 1), "base64"),
+  };
+}
+
+function decryptValue(dek: SubjectDek, blob: Buffer): string {
+  const iv = blob.subarray(0, IV_LENGTH);
+  const tag = blob.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+  const ciphertext = blob.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+  const decipher = createDecipheriv("aes-256-gcm", dek, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+
+// First write to a PII field of a new subject creates the key implicitly
+// (user-signup / tenant-create need no extra hook). The AlreadyExists catch
+// covers the concurrent-first-write race; a tombstoned subject re-throws
+// KeyErasedError from the final getKey — writes to a forgotten subject fail.
+async function getOrCreateDek(
+  kms: LocalKeyKmsAdapter,
+  subject: SubjectId,
+  ctx: KmsContext,
+): Promise<SubjectDek> {
+  try {
+    return await kms.getKey(subject, ctx);
+  } catch (e) {
+    if (!(e instanceof KeyNotFoundError)) throw e;
+  }
+  try {
+    await kms.createKey(subject, ctx);
+  } catch (e) {
+    if (!(e instanceof KeyAlreadyExistsError)) throw e;
+  }
+  return kms.getKey(subject, ctx);
+}
+
+export interface EncryptPiiOptions {
+  readonly onlyKeys?: Iterable<string>;
+  // Write-time tenant for tenantOwned fields on rows without a tenantId column.
+  readonly tenantId?: TenantId;
+  // Row to resolve subjects from when `row` is a partial (update changes may
+  // carry a pii field without its ownerField — the merged row still has it).
+  readonly subjectSource?: Record<string, unknown>;
+}
+
+export async function encryptPiiFieldValues(
+  row: Record<string, unknown>,
+  entity: EntityDefinition,
+  piiFields: readonly string[],
+  kms: LocalKeyKmsAdapter,
+  kmsCtx: KmsContext,
+  opts: EncryptPiiOptions = {},
+): Promise<Record<string, unknown>> {
+  if (piiFields.length === 0) return row;
+  const only = opts.onlyKeys ? new Set(opts.onlyKeys) : null;
+  const subjectSource = opts.subjectSource ?? row;
+  const out = { ...row };
+  for (const name of piiFields) {
+    if (only && !only.has(name)) continue;
+    if (!(name in out)) continue;
+    const value = out[name];
+    if (value === null || value === undefined) continue;
+    // Re-encrypt paths (update previous, detail cache) may see values that
+    // are already ciphertext or the erased sentinel — both stay as-is.
+    if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) continue;
+    if (typeof value !== "string") {
+      throw new Error(`PII field "${name}" must be a string, got ${typeof value}`);
+    }
+    const subject = resolveSubjectForField(entity, name, subjectSource, {
+      ...(opts.tenantId !== undefined && { tenantId: opts.tenantId }),
+    });
+    // skip: collectPiiSubjectFields only yields annotated fields — null is unreachable, kept as a type guard
+    if (subject === null) continue;
+    const dek = await getOrCreateDek(kms, subject, kmsCtx);
+    out[name] = encryptValue(subject, dek, value);
+  }
+  return out;
+}
+
+export async function decryptPiiFieldValues(
+  row: Record<string, unknown>,
+  piiFields: readonly string[],
+  kms: LocalKeyKmsAdapter,
+  kmsCtx: KmsContext,
+): Promise<Record<string, unknown>> {
+  if (piiFields.length === 0) return row;
+  const out = { ...row };
+  for (const name of piiFields) {
+    const value = out[name];
+    // Pre-engine plaintext rows pass through unchanged (mixed-state reads
+    // work during rollout; backfill is tracked in kumiko-framework#799).
+    if (!isPiiCiphertext(value)) continue;
+    const { subject, blob } = parseCiphertext(value);
+    try {
+      out[name] = decryptValue(await kms.getKey(subject, kmsCtx), blob);
+    } catch (e) {
+      // KeyNotFound deliberately propagates: ciphertext without a key row
+      // means the key store is wrong (not shredded) — fail loud.
+      if (!(e instanceof KeyErasedError)) throw e;
+      out[name] = PII_ERASED_SENTINEL;
+    }
+  }
+  return out;
+}
+
+// Boot-injected app-wide subject KMS, mirroring configureEntityFieldEncryption:
+// run{Prod,Dev}App call configurePiiSubjectKms once; executors resolve lazily.
+// Absent adapter = engine off (pii fields stay plaintext, pre-phase-C
+// behavior) — the hard boot gate arrives with the prod-grade PgKmsAdapter
+// (phase E); until then no production deployment can satisfy it.
+let injectedKms: LocalKeyKmsAdapter | undefined;
+
+export function configurePiiSubjectKms(adapter: KmsAdapter | undefined): void {
+  if (adapter !== undefined && !isLocalKeyKmsAdapter(adapter)) {
+    throw new Error(
+      "PII field encryption requires a local-key KMS adapter — remote-crypto " +
+        "(Vault transit) support lands with the BYOK adapter.",
+    );
+  }
+  injectedKms = adapter;
+}
+
+export function configuredPiiSubjectKms(): LocalKeyKmsAdapter | undefined {
+  return injectedKms;
+}
+
+/** @internal test-only */
+export function resetPiiSubjectKmsForTests(): void {
+  injectedKms = undefined;
+}

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);
+}