@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/src/crypto/index.ts

@@ -1,84 +0,0 @@
-export {
-  blindIndexFieldName,
-  collectLookupableFields,
-  computeBlindIndex,
-  computeBlindIndexValues,
-  configureBlindIndexKey,
-  configuredBlindIndexKey,
-  decodeBlindIndexKey,
-} from "./blind-index";
-export {
-  configuredEventPiiCatalog,
-  configureEventPiiCatalog,
-  type EventPiiCatalog,
-  encryptEventPayloadPii,
-} from "./event-pii";
-export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
-export { isSelfPiiField } from "./is-self-pii-field";
-export { type KekSourceEnv, type KekSourceOptions, resolvePlatformKeks } from "./kek-source";
-export {
-  isLocalKeyKmsAdapter,
-  KeyAlreadyExistsError,
-  KeyErasedError,
-  KeyNotFoundError,
-  type KmsAdapter,
-  type KmsContext,
-  type KmsHealth,
-  type LocalKeyKmsAdapter,
-  RECORD_ENTITY_PATTERN,
-  type RemoteCryptoKmsAdapter,
-  type SubjectDek,
-  type SubjectId,
-  type SubjectKey,
-  subjectIdFromKey,
-  subjectIdSchema,
-  subjectIdToKey,
-  subjectKeyForRecord,
-  subjectKeyForTenant,
-  subjectKeyForUser,
-} from "./kms-adapter";
-export {
-  type ActiveKmsWiring,
-  buildPgKmsOptions,
-  type KmsWiring,
-  type KmsWiringEnv,
-  type KmsWiringOptions,
-  type KmsWiringRelease,
-  type PgKmsRotationEnv,
-  type PlaintextPiiWiring,
-  requireKmsWiring,
-  requireKmsWiringAsync,
-  resolveKmsWiring,
-  resolveKmsWiringAsync,
-} from "./kms-wiring";
-export {
-  createPgKmsAdapter,
-  PgKmsAdapter,
-  type PgKmsAdapterOptions,
-  type RewrapOptions,
-  type RewrapResult,
-  rewrapSubjectKeys,
-} from "./pg-kms-adapter";
-export {
-  configuredPiiSubjectKms,
-  configurePiiSubjectKms,
-  decryptPiiFieldValues,
-  decryptPiiValueForSubject,
-  type EncryptPiiOptions,
-  encryptPiiFieldValues,
-  encryptPiiValueForSubject,
-  isPiiCiphertext,
-  PII_CIPHERTEXT_PREFIX,
-  PII_ERASED_SENTINEL,
-} from "./pii-field-encryption";
-export {
-  createRequestKmsCache,
-  type RequestKmsCache,
-} from "./request-kms-cache";
-export {
-  collectPiiSubjectFields,
-  collectSearchableSubjectFields,
-  type ResolveSubjectOptions,
-  resolveSubjectForField,
-  SubjectResolutionError,
-} from "./subject-resolver";

package/src/crypto/is-self-pii-field.ts

@@ -1,8 +0,0 @@
-import type { EntityDefinition } from "../engine/types/fields";
-
-type AnyField = EntityDefinition["fields"][string];
-
-/** True when the field's own row id is the PII subject (`pii: true`). */
-export function isSelfPiiField(field: AnyField): boolean {
-  return "pii" in field && field.pii === true;
-}

package/src/crypto/kek-source.ts

@@ -1,180 +0,0 @@
-// Resolves a caller-named set of secret slots from a Key Manager ciphertext
-// when no plaintext is set, so they need not sit in the pod env in the clear.
-// A slot's plaintext always wins over its ciphertext sibling, with no request
-// made at all. Any `*_CIPHERTEXT` in the env that names no requested slot is
-// ignored — a foreign ciphertext must never fail boot.
-
-const SCALEWAY_KEY_MANAGER_API_VERSION = "v1alpha1";
-const DEFAULT_REGION = "fr-par";
-const DECRYPT_TIMEOUT_MS = 5_000;
-const RETRY_DELAYS_MS = [200, 800];
-// Used when the caller names no slots. Apps that predate `kms` schema meta
-// rely on it; drop once every consumer declares its slots in the env schema.
-const LEGACY_SLOTS = ["PLATFORM_KEK", "PLATFORM_KEK_PREVIOUS", "KUMIKO_BLIND_INDEX_KEY"] as const;
-
-export type KekSourceEnv = {
-  readonly PLATFORM_KEK?: string | undefined;
-  readonly PLATFORM_KEK_CIPHERTEXT?: string | undefined;
-  readonly PLATFORM_KEK_PREVIOUS?: string | undefined;
-  readonly PLATFORM_KEK_PREVIOUS_CIPHERTEXT?: string | undefined;
-  readonly PLATFORM_KEK_PREVIOUS_VERSION?: string | undefined;
-  readonly PLATFORM_KEK_KMS_KEY_ID?: string | undefined;
-  readonly PLATFORM_KEK_KMS_TOKEN?: string | undefined;
-  readonly PLATFORM_KEK_KMS_REGION?: string | undefined;
-  readonly KUMIKO_BLIND_INDEX_KEY?: string | undefined;
-  readonly KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT?: string | undefined;
-  readonly [key: string]: string | undefined;
-};
-
-export type KekSourceOptions = {
-  readonly fetch?: typeof globalThis.fetch;
-  readonly logPrefix?: string;
-  /** Where the boot line naming the KEK source goes. Defaults to `console.info`. */
-  readonly log?: (message: string) => void;
-  /** Env names to resolve, e.g. `kmsSlotsOf(schema)`. Defaults to the three
-   *  platform slots. */
-  readonly slots?: readonly string[];
-};
-
-function isRetryableStatus(status: number): boolean {
-  return status >= 500;
-}
-
-async function sleep(ms: number): Promise<void> {
-  await new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// Scaleway's decrypt SLA is 99.5% — a bootpath that gives up on the first
-// transient 5xx or timeout trades a rare retry for a routine boot failure.
-// 4xx means the request itself is wrong (bad token, bad key id) and no
-// amount of retrying fixes that, so it fails fast instead of stalling boot.
-async function decryptCiphertext(
-  ciphertext: string,
-  keyId: string,
-  token: string,
-  region: string,
-  fetchImpl: typeof globalThis.fetch,
-  logPrefix: string | undefined,
-): Promise<string> {
-  const url = `https://api.scaleway.com/key-manager/${SCALEWAY_KEY_MANAGER_API_VERSION}/regions/${region}/keys/${keyId}/decrypt`;
-  const prefix = logPrefix ? `${logPrefix} ` : "";
-  const maxAttempts = RETRY_DELAYS_MS.length + 1;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    let response: Response;
-    try {
-      response = await fetchImpl(url, {
-        method: "POST",
-        headers: { "X-Auth-Token": token, "Content-Type": "application/json" },
-        body: JSON.stringify({ ciphertext }),
-        signal: AbortSignal.timeout(DECRYPT_TIMEOUT_MS),
-      });
-    } catch {
-      if (attempt < maxAttempts) {
-        await sleep(RETRY_DELAYS_MS[attempt - 1] ?? 0);
-        continue;
-      }
-      throw new Error(
-        `${prefix}Key Manager decrypt failed for key ${keyId}: network error or timeout`,
-      );
-    }
-
-    if (!response.ok) {
-      if (isRetryableStatus(response.status) && attempt < maxAttempts) {
-        await sleep(RETRY_DELAYS_MS[attempt - 1] ?? 0);
-        continue;
-      }
-      throw new Error(
-        `${prefix}Key Manager decrypt failed for key ${keyId}: HTTP ${response.status}`,
-      );
-    }
-
-    let body: { plaintext?: unknown };
-    try {
-      body = (await response.json()) as { plaintext?: unknown };
-    } catch {
-      throw new Error(
-        `${prefix}Key Manager decrypt for key ${keyId} returned an unparseable response`,
-      );
-    }
-    if (typeof body.plaintext !== "string") {
-      throw new Error(`${prefix}Key Manager decrypt for key ${keyId} returned no plaintext field`);
-    }
-    return body.plaintext;
-  }
-  throw new Error(`${prefix}Key Manager decrypt failed for key ${keyId}: retries exhausted`);
-}
-
-async function resolveSlot(
-  name: string,
-  env: KekSourceEnv,
-  options: KekSourceOptions,
-  fetchImpl: typeof globalThis.fetch,
-): Promise<string | undefined> {
-  const plaintext = env[name];
-  if (plaintext) return plaintext;
-  const ciphertext = env[`${name}_CIPHERTEXT`];
-  if (!ciphertext) return undefined;
-
-  const keyId = env.PLATFORM_KEK_KMS_KEY_ID;
-  const token = env.PLATFORM_KEK_KMS_TOKEN;
-  if (!keyId || !token) {
-    const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
-    throw new Error(
-      `${prefix}PLATFORM_KEK_KMS_KEY_ID / PLATFORM_KEK_KMS_TOKEN are all-or-none with a KEK ciphertext (slot ${name}) — a partial set means the KMS wiring is broken.`,
-    );
-  }
-  const region = env.PLATFORM_KEK_KMS_REGION ?? DEFAULT_REGION;
-  return decryptCiphertext(ciphertext, keyId, token, region, fetchImpl, options.logPrefix);
-}
-
-// A leftover plaintext beside a ciphertext boots green while nothing was
-// migrated, which is indistinguishable from a finished cutover unless the
-// boot says which source won. Never carries a key value, only its origin.
-function describeKekSource(name: string, env: KekSourceEnv): string | undefined {
-  const plaintext = env[name];
-  const ciphertext = env[`${name}_CIPHERTEXT`];
-  if (plaintext) {
-    return ciphertext
-      ? `${name} source=plaintext-env (ciphertext present and ignored)`
-      : `${name} source=plaintext-env`;
-  }
-  if (!ciphertext) return undefined;
-  const region = env.PLATFORM_KEK_KMS_REGION ?? DEFAULT_REGION;
-  return `${name} source=key-manager keyId=${env.PLATFORM_KEK_KMS_KEY_ID} region=${region}`;
-}
-
-// Each slot resolves independently so a rollback that clears one slot's
-// plaintext (leaving its ciphertext/_VERSION behind or gone) never blocks
-// another slot's fallback path — the trio check downstream still applies.
-export async function resolvePlatformKeks(
-  env: KekSourceEnv,
-  options: KekSourceOptions = {},
-): Promise<KekSourceEnv> {
-  const fetchImpl = options.fetch ?? globalThis.fetch;
-
-  const slots = options.slots ?? LEGACY_SLOTS;
-  const resolved: Record<string, string | undefined> = {};
-  for (const name of slots) {
-    resolved[name] = await resolveSlot(name, env, options, fetchImpl);
-  }
-
-  const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
-  // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-  const log = options.log ?? console.info;
-  for (const name of slots) {
-    const line = describeKekSource(name, env);
-    if (line) log(`${prefix}${line}`);
-  }
-
-  if (resolved["PLATFORM_KEK_PREVIOUS"] && !env.PLATFORM_KEK_PREVIOUS_VERSION) {
-    throw new Error(
-      `${prefix}PLATFORM_KEK_PREVIOUS_VERSION must be set when PLATFORM_KEK_PREVIOUS is set.`,
-    );
-  }
-
-  const changed = slots.some((name) => resolved[name] !== env[name]);
-  if (!changed) return env;
-
-  return { ...env, ...resolved };
-}

package/src/crypto/kms-adapter.ts

@@ -1,51 +0,0 @@
-import {
-  RECORD_ENTITY_PATTERN,
-  type SubjectId,
-  subjectIdToKey,
-} from "@cosmicdrift/kumiko-types/kms-adapter-types";
-import * as z from "zod";
-import type { TenantId } from "../engine/types/identifiers";
-
-export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
-
-// The KMS error classes live here and not in kumiko-types (#1629): callers
-// branch on them with `instanceof`, which needs a single copy of the class.
-
-// `satisfies z.ZodType<SubjectId>` binds this to the TS type at compile time
-// (fw#2801) — mint (subjectKeyForRecord) and shred (forget-subject) can no
-// longer drift apart on which subjects are valid, the way #2809 happened.
-export const subjectIdSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("user"), userId: z.uuid() }),
-  z.object({
-    kind: z.literal("tenant"),
-    // z.uuid() only proves string shape; TenantId is a nominal brand on top
-    // of that, minted here right after validation (@cast-boundary).
-    tenantId: z.uuid().transform((value) => value as TenantId),
-  }),
-  z.object({
-    kind: z.literal("record"),
-    entity: z.string().regex(RECORD_ENTITY_PATTERN),
-    id: z.uuid(),
-  }),
-]) satisfies z.ZodType<SubjectId>;
-
-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/kms-wiring.ts

@@ -1,208 +0,0 @@
-// Boot-time env validation for the subject-keys KMS, shared by every app that
-// mounts crypto-shredding. Lived copy-pasted in four apps before fw#1617; the
-// copies drifted apart in their parsers, which is the failure mode this module
-// exists to end.
-//
-// Split in two on purpose: `buildPgKmsOptions` is pure and unit-testable
-// (the rotation slot mapping is the part that silently corrupts data when it
-// is wrong), `resolveKmsWiring` is the boot entry point that also constructs
-// the adapter.
-
-import { type KekSourceOptions, resolvePlatformKeks } from "./kek-source";
-import { createPgKmsAdapter, type PgKmsAdapter, type PgKmsAdapterOptions } from "./pg-kms-adapter";
-
-// The index signature is what lets callers pass `process.env` directly. Without
-// it every member is optional, so TypeScript's weak-type detection rejects
-// ProcessEnv for having "no properties in common" — and each app would need
-// either a hand-written six-key mapping or a cast. An env map genuinely does
-// carry arbitrary keys, so the signature states a fact rather than loosening
-// the type for convenience.
-export type KmsWiringEnv = {
-  readonly PLATFORM_KEK?: string | undefined;
-  readonly SUBJECT_KEYS_DATABASE_URL?: string | undefined;
-  readonly KUMIKO_BLIND_INDEX_KEY?: string | undefined;
-  readonly PLATFORM_KEK_VERSION?: string | undefined;
-  readonly PLATFORM_KEK_PREVIOUS?: string | undefined;
-  readonly PLATFORM_KEK_PREVIOUS_VERSION?: string | undefined;
-  readonly [key: string]: string | undefined;
-};
-
-/** Narrowed form for `buildPgKmsOptions` — presence of the two required
- *  members is the caller's job (`resolveKmsWiring` does it via the trio check). */
-export type PgKmsRotationEnv = KmsWiringEnv & {
-  readonly PLATFORM_KEK: string;
-  readonly SUBJECT_KEYS_DATABASE_URL: string;
-};
-
-/** Releases what the wiring opened. Present on BOTH branches (a no-op on the
- *  plaintext fallback) so a short-lived process can `finally { await
- *  wiring.close() }` without narrowing first. Skipping it leaves the adapter's
- *  connection pool holding the event loop open and the process never exits —
- *  a long-running server is supposed to hold it, every ops script is not
- *  (fw#2551). */
-export type KmsWiringRelease = { readonly close: () => Promise<void> };
-
-export type ActiveKmsWiring = KmsWiringRelease & {
-  readonly kms: PgKmsAdapter;
-  readonly blindIndexKey: string;
-};
-
-/** Plaintext fallback carries its reason so the boot log says WHY PII is
- *  unencrypted — an app running like this by accident is a reportable breach. */
-export type PlaintextPiiWiring = KmsWiringRelease & { readonly allowPlaintextPii: string };
-
-export type KmsWiring = ActiveKmsWiring | PlaintextPiiWiring;
-
-export type KmsWiringOptions = {
-  /** Prefixes the all-or-none error. Use the app's existing boot-log prefix —
-   *  people grep for it in production logs. */
-  readonly logPrefix?: string;
-  /** Reason recorded when the trio is absent and plaintext PII is accepted. */
-  readonly plaintextReason?: string;
-};
-
-const DEFAULT_PLAINTEXT_REASON = "local dev without subject-keys KMS (fw#818)";
-
-// Number(raw) + Number.isInteger is the wrong parser for an env string:
-// Number.isInteger(1e21) is true, so "1e21" passes, and the value then
-// stringifies back to "1e+21" as a previousKeks object key — a lookup against
-// the integer kek_version column never hits that slot, silently leaving
-// rotation-window rows unreadable. Same class: "0x10" -> 16, " 2 " trimmed,
-// "-1"/"0" accepted as versions, values past MAX_SAFE_INTEGER rounded.
-// A digits-only regex closes all of these at once (phronexsis#323).
-function parseKekVersion(raw: string, fieldName: string): number {
-  if (!/^[0-9]+$/.test(raw)) {
-    throw new Error(`${fieldName} must be a positive integer, got "${raw}".`);
-  }
-  const version = Number(raw);
-  if (!Number.isSafeInteger(version) || version < 1) {
-    throw new Error(`${fieldName} must be a positive integer, got "${raw}".`);
-  }
-  return version;
-}
-
-/** Maps the KEK env vars onto adapter options, including which version slot an
- *  old KEK lands in during a rotation window.
- *
- *  Does NOT check that the previous version is older than the active one —
- *  `PgKmsAdapter`'s constructor already rejects `previousKeks[v] >= kekVersion`
- *  and stays the single source of that rule. */
-export function buildPgKmsOptions(env: PgKmsRotationEnv): PgKmsAdapterOptions {
-  const kekVersion = env.PLATFORM_KEK_VERSION
-    ? parseKekVersion(env.PLATFORM_KEK_VERSION, "PLATFORM_KEK_VERSION")
-    : 1;
-  if (!env.PLATFORM_KEK_PREVIOUS) {
-    if (env.PLATFORM_KEK_PREVIOUS_VERSION) {
-      throw new Error(
-        "PLATFORM_KEK_PREVIOUS must be set when PLATFORM_KEK_PREVIOUS_VERSION is set.",
-      );
-    }
-    return {
-      databaseUrl: env.SUBJECT_KEYS_DATABASE_URL,
-      platformKek: env.PLATFORM_KEK,
-      kekVersion,
-    };
-  }
-  if (!env.PLATFORM_KEK_PREVIOUS_VERSION) {
-    throw new Error("PLATFORM_KEK_PREVIOUS_VERSION must be set when PLATFORM_KEK_PREVIOUS is set.");
-  }
-  const previousVersion = parseKekVersion(
-    env.PLATFORM_KEK_PREVIOUS_VERSION,
-    "PLATFORM_KEK_PREVIOUS_VERSION",
-  );
-  return {
-    databaseUrl: env.SUBJECT_KEYS_DATABASE_URL,
-    platformKek: env.PLATFORM_KEK,
-    kekVersion,
-    previousKeks: { [previousVersion]: env.PLATFORM_KEK_PREVIOUS },
-  };
-}
-
-function assertTrioConsistent(env: KmsWiringEnv, logPrefix: string | undefined): boolean {
-  const trio = [env.PLATFORM_KEK, env.SUBJECT_KEYS_DATABASE_URL, env.KUMIKO_BLIND_INDEX_KEY];
-  const complete = trio.every(Boolean);
-  if (!complete && trio.some(Boolean)) {
-    throw new Error(
-      `${logPrefix ? `${logPrefix} ` : ""}PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / ` +
-        "KUMIKO_BLIND_INDEX_KEY are all-or-none — a partial set means the KMS wiring is broken.",
-    );
-  }
-  if (Boolean(env.PLATFORM_KEK_PREVIOUS) !== Boolean(env.PLATFORM_KEK_PREVIOUS_VERSION)) {
-    throw new Error(
-      `${logPrefix ? `${logPrefix} ` : ""}PLATFORM_KEK_PREVIOUS and ` +
-        "PLATFORM_KEK_PREVIOUS_VERSION must be set together " +
-        "(KEK rotation, runbook kek-rotation.md).",
-    );
-  }
-  if (!complete && (env.PLATFORM_KEK_PREVIOUS || env.PLATFORM_KEK_PREVIOUS_VERSION)) {
-    throw new Error(
-      `${logPrefix ? `${logPrefix} ` : ""}PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / ` +
-        "KUMIKO_BLIND_INDEX_KEY are all-or-none — rotation settings require the complete KMS wiring.",
-    );
-  }
-  return complete;
-}
-
-/** Boot wiring for apps that may run without a KMS (dev, local): complete trio
- *  yields the adapter, empty trio yields the plaintext fallback, partial throws.
- *
- *  Prod entry points that must never fall back: use `requireKmsWiring`. */
-export function resolveKmsWiring(env: KmsWiringEnv, options: KmsWiringOptions = {}): KmsWiring {
-  const complete = assertTrioConsistent(env, options.logPrefix);
-  if (complete && env.PLATFORM_KEK && env.SUBJECT_KEYS_DATABASE_URL && env.KUMIKO_BLIND_INDEX_KEY) {
-    const kms = createPgKmsAdapter(
-      buildPgKmsOptions({
-        ...env,
-        PLATFORM_KEK: env.PLATFORM_KEK,
-        SUBJECT_KEYS_DATABASE_URL: env.SUBJECT_KEYS_DATABASE_URL,
-      }),
-    );
-    return {
-      kms,
-      blindIndexKey: env.KUMIKO_BLIND_INDEX_KEY,
-      close: () => kms.close(),
-    };
-  }
-  return {
-    allowPlaintextPii: options.plaintextReason ?? DEFAULT_PLAINTEXT_REASON,
-    close: () => Promise.resolve(),
-  };
-}
-
-/** Same as `resolveKmsWiring` but the trio is mandatory — an absent trio throws
- *  instead of silently accepting plaintext PII. Separate function rather than a
- *  flag so the return type is the active wiring, with no narrowing at the call
- *  site. */
-export function requireKmsWiring(
-  env: KmsWiringEnv,
-  options: KmsWiringOptions = {},
-): ActiveKmsWiring {
-  const wiring = resolveKmsWiring(env, options);
-  if ("allowPlaintextPii" in wiring) {
-    throw new Error(
-      `${options.logPrefix ? `${options.logPrefix} ` : ""}PLATFORM_KEK / ` +
-        "SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY are required here — " +
-        "no plaintext-PII opt-out on this entry point.",
-    );
-  }
-  return wiring;
-}
-
-/** Same as `resolveKmsWiring`, but resolves `PLATFORM_KEK`/`PLATFORM_KEK_PREVIOUS`
- *  from a Key Manager ciphertext first when no plaintext is set — see
- *  `resolvePlatformKeks`. The validation stays in the sync function; this only
- *  adds the KEK-fetching step in front of it. */
-export async function resolveKmsWiringAsync(
-  env: KmsWiringEnv,
-  options: KmsWiringOptions & KekSourceOptions = {},
-): Promise<KmsWiring> {
-  return resolveKmsWiring(await resolvePlatformKeks(env, options), options);
-}
-
-/** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
-export async function requireKmsWiringAsync(
-  env: KmsWiringEnv,
-  options: KmsWiringOptions & KekSourceOptions = {},
-): Promise<ActiveKmsWiring> {
-  return requireKmsWiring(await resolvePlatformKeks(env, options), options);
-}