@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/crypto/kek-source.js

@@ -0,0 +1,122 @@
+// 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"];
+function isRetryableStatus(status) {
+    return status >= 500;
+}
+async function sleep(ms) {
+    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, keyId, token, region, fetchImpl, logPrefix) {
+    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;
+        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;
+        try {
+            body = (await response.json());
+        }
+        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, env, options, fetchImpl) {
+    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, env) {
+    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, options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const slots = options.slots ?? LEGACY_SLOTS;
+    const resolved = {};
+    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/dist/crypto/kms-adapter.d.ts

@@ -0,0 +1,26 @@
+import { type SubjectId } from "@cosmicdrift/kumiko-types/kms-adapter-types";
+import * as z from "zod";
+export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
+export declare const subjectIdSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    userId: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"tenant">;
+    tenantId: z.ZodPipe<z.ZodUUID, z.ZodTransform<string, string>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"record">;
+    entity: z.ZodString;
+    id: z.ZodUUID;
+}, z.core.$strip>], "kind">;
+export declare class KeyErasedError extends Error {
+    readonly subject: SubjectId;
+    constructor(subject: SubjectId);
+}
+export declare class KeyNotFoundError extends Error {
+    readonly subject: SubjectId;
+    constructor(subject: SubjectId);
+}
+export declare class KeyAlreadyExistsError extends Error {
+    readonly subject: SubjectId;
+    constructor(subject: SubjectId);
+}

package/dist/crypto/kms-adapter.js

@@ -0,0 +1,46 @@
+import { RECORD_ENTITY_PATTERN, subjectIdToKey, } from "@cosmicdrift/kumiko-types/kms-adapter-types";
+import * as z from "zod";
+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),
+    }),
+    z.object({
+        kind: z.literal("record"),
+        entity: z.string().regex(RECORD_ENTITY_PATTERN),
+        id: z.uuid(),
+    }),
+]);
+export class KeyErasedError extends Error {
+    subject;
+    constructor(subject) {
+        super(`Subject key erased: ${subjectIdToKey(subject)}`);
+        this.subject = subject;
+        this.name = "KeyErasedError";
+    }
+}
+export class KeyNotFoundError extends Error {
+    subject;
+    constructor(subject) {
+        super(`Subject key not found: ${subjectIdToKey(subject)}`);
+        this.subject = subject;
+        this.name = "KeyNotFoundError";
+    }
+}
+export class KeyAlreadyExistsError extends Error {
+    subject;
+    constructor(subject) {
+        super(`Subject key already exists: ${subjectIdToKey(subject)}`);
+        this.subject = subject;
+        this.name = "KeyAlreadyExistsError";
+    }
+}

package/dist/crypto/kms-wiring.d.ts

@@ -0,0 +1,67 @@
+import { type KekSourceOptions } from "./kek-source.js";
+import { type PgKmsAdapter, type PgKmsAdapterOptions } from "./pg-kms-adapter.js";
+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;
+};
+/** 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 declare function buildPgKmsOptions(env: PgKmsRotationEnv): PgKmsAdapterOptions;
+/** 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 declare function resolveKmsWiring(env: KmsWiringEnv, options?: KmsWiringOptions): KmsWiring;
+/** 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 declare function requireKmsWiring(env: KmsWiringEnv, options?: KmsWiringOptions): ActiveKmsWiring;
+/** 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 declare function resolveKmsWiringAsync(env: KmsWiringEnv, options?: KmsWiringOptions & KekSourceOptions): Promise<KmsWiring>;
+/** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
+export declare function requireKmsWiringAsync(env: KmsWiringEnv, options?: KmsWiringOptions & KekSourceOptions): Promise<ActiveKmsWiring>;

package/dist/crypto/kms-wiring.js

@@ -0,0 +1,125 @@
+// 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 { resolvePlatformKeks } from "./kek-source.js";
+import { createPgKmsAdapter, } from "./pg-kms-adapter.js";
+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, fieldName) {
+    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) {
+    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, logPrefix) {
+    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, options = {}) {
+    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, options = {}) {
+    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, options = {}) {
+    return resolveKmsWiring(await resolvePlatformKeks(env, options), options);
+}
+/** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
+export async function requireKmsWiringAsync(env, options = {}) {
+    return requireKmsWiring(await resolvePlatformKeks(env, options), options);
+}

package/dist/crypto/pg-kms-adapter.d.ts

@@ -0,0 +1,55 @@
+import { type KmsContext, type KmsHealth, type LocalKeyKmsAdapter, type SubjectDek, type SubjectId } from "./kms-adapter.js";
+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;
+    /** 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;
+}
+export declare class PgKmsAdapter implements LocalKeyKmsAdapter {
+    readonly capabilities: {
+        readonly mode: "local-key";
+    };
+    private readonly sql;
+    private readonly kek;
+    private readonly kekVersion;
+    private readonly previousKeks;
+    private schemaReady;
+    constructor(options: PgKmsAdapterOptions);
+    createKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+    getKey(subject: SubjectId, _ctx: KmsContext): Promise<SubjectDek>;
+    private kekFor;
+    eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+    health(): Promise<KmsHealth>;
+    close(): Promise<void>;
+    private ensureSchema;
+    private createSchema;
+}
+export declare function createPgKmsAdapter(options: PgKmsAdapterOptions): PgKmsAdapter;
+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;
+    }>;
+}
+export declare function rewrapSubjectKeys(options: RewrapOptions): Promise<RewrapResult>;

package/dist/crypto/pg-kms-adapter.js

@@ -0,0 +1,232 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import postgres from "postgres";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "../db/api.js";
+import { KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, subjectIdToKey, } from "./kms-adapter.js";
+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, dek) {
+    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, wrapped) {
+    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) {
+    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";
+// pg_advisory_xact_lock key for createSchema — serializes concurrent cold-start
+// DDL across processes sharing one subject-keys DB.
+const SCHEMA_ADVISORY_LOCK_KEY = 0x6b_6d_73_31; // 'kms1'
+function isPgUniqueViolation(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === PG_UNIQUE_VIOLATION);
+}
+// 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 {
+    capabilities = { mode: "local-key" };
+    sql;
+    kek;
+    kekVersion;
+    previousKeks;
+    schemaReady;
+    constructor(options) {
+        this.kek = decodePlatformKek(options.platformKek);
+        this.kekVersion = options.kekVersion ?? 1;
+        const previous = new Map();
+        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
+            // idempotent IF NOT EXISTS — notices are pure boot-log noise.
+            onnotice: () => { },
+        });
+    }
+    async createKey(subject, ctx) {
+        await this.ensureSchema();
+        const wrapped = wrapDek(this.kek, randomBytes(32));
+        try {
+            await this.sql `
+        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;
+        }
+    }
+    async getKey(subject, _ctx) {
+        await this.ensureSchema();
+        const rows = await this.sql `
+      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.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.
+    kekFor(version, subject) {
+        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, ctx) {
+        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() {
+        const start = Date.now();
+        await this.ensureSchema();
+        await this.sql `SELECT 1`;
+        return { ok: true, latencyMs: Date.now() - start };
+    }
+    async close() {
+        await this.sql.end({ timeout: DEFAULT_DB_CLOSE_TIMEOUT_SECONDS });
+    }
+    ensureSchema() {
+        // 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;
+    }
+    async createSchema() {
+        await this.sql.begin(async (tx) => {
+            await tx `SELECT pg_advisory_xact_lock(${SCHEMA_ADVISORY_LOCK_KEY})`;
+            await tx `
+        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 tx `
+        CREATE INDEX IF NOT EXISTS kumiko_subject_keys_erased_idx
+        ON kumiko_subject_keys (erased_at) WHERE erased_at IS NOT NULL`;
+            await tx `
+        CREATE INDEX IF NOT EXISTS kumiko_subject_keys_audit_idx
+        ON kumiko_subject_keys (created_at, erased_at)`;
+        });
+    }
+}
+export function createPgKmsAdapter(options) {
+    return new PgKmsAdapter(options);
+}
+// 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) {
+    const toKek = decodePlatformKek(options.toKek);
+    const fromKeks = new Map();
+    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: [],
+    };
+    try {
+        let cursor = "";
+        for (;;) {
+            const rows = await sql `
+        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;
+}