@wtfalch/keys 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @wtfalch/keys
+
+`@wtfalch/keys` issues the estate's own bearer keys to callers and holds keys
+other parties issued to the estate, injecting held keys into a running
+service at request time and into a build at build time. It owns no
+authentication or authorisation of its own — every check runs through
+`@wtfalch/auth` and `@wtfalch/authz`.
+
+## Install
+
+```sh
+pnpm add @wtfalch/keys
+```
+
+## Dev
+
+```sh
+pnpm build
+pnpm typecheck
+pnpm test
+```

package/dist/bin/copy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Migrations in this estate are hand-written SQL, numbered per app, applied
+ * by psql on boot, additive. A package cannot own a number in an app's
+ * sequence, so this copies any migration the app has not yet copied into the
+ * app's `drizzle/` as the next numbers and records which in a manifest. The
+ * same mechanism `@wtfalch/audit`, `@wtfalch/threads` and `@wtfalch/reporting`
+ * use; the manifest name differs.
+ *
+ * `./held` and `./issued` each ship their own numbered migration
+ * (`0001_keys_issued.sql`, `0002_keys_held.sql`) into this package's shared
+ * `src/migrations/`, whichever lands first -- so this copies every `.sql`
+ * file present, not one hardcoded name.
+ */
+export declare const MANIFEST = ".keys-migrations.json";
+export interface Manifest {
+    /** package file name -> the name it was copied to in the app */
+    copied: Record<string, string>;
+}
+export interface CopyResult {
+    copied: Array<{
+        from: string;
+        to: string;
+    }>;
+    manifest: Manifest;
+}
+export declare function copyMigrations(opts: {
+    from: string;
+    to: string;
+    version?: string;
+}): CopyResult;
+export declare function describeCopy(result: CopyResult): string;

package/dist/bin/copy.js

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/**
+ * Migrations in this estate are hand-written SQL, numbered per app, applied
+ * by psql on boot, additive. A package cannot own a number in an app's
+ * sequence, so this copies any migration the app has not yet copied into the
+ * app's `drizzle/` as the next numbers and records which in a manifest. The
+ * same mechanism `@wtfalch/audit`, `@wtfalch/threads` and `@wtfalch/reporting`
+ * use; the manifest name differs.
+ *
+ * `./held` and `./issued` each ship their own numbered migration
+ * (`0001_keys_issued.sql`, `0002_keys_held.sql`) into this package's shared
+ * `src/migrations/`, whichever lands first -- so this copies every `.sql`
+ * file present, not one hardcoded name.
+ */
+export const MANIFEST = '.keys-migrations.json';
+const NUMBERED = /^(\d{4})_(.+\.sql)$/;
+function readManifest(dir) {
+    const file = join(dir, MANIFEST);
+    if (!existsSync(file))
+        return { copied: {} };
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return { copied: parsed.copied ?? {} };
+}
+function nextNumber(dir) {
+    let max = -1;
+    for (const name of readdirSync(dir)) {
+        const m = NUMBERED.exec(name);
+        if (m?.[1])
+            max = Math.max(max, Number(m[1]));
+    }
+    return max + 1;
+}
+export function copyMigrations(opts) {
+    mkdirSync(opts.to, { recursive: true });
+    const manifest = readManifest(opts.to);
+    const copied = [];
+    const sources = readdirSync(opts.from)
+        .filter((n) => NUMBERED.test(n))
+        .sort();
+    let next = nextNumber(opts.to);
+    for (const name of sources) {
+        if (manifest.copied[name])
+            continue;
+        const rest = NUMBERED.exec(name)?.[2] ?? name;
+        const target = `${String(next).padStart(4, '0')}_${rest}`;
+        const body = readFileSync(join(opts.from, name), 'utf8');
+        const header = `-- Copied from @wtfalch/keys${opts.version ? ` ${opts.version}` : ''} (migrations/${name}) by keys-migrations.\n-- Do not edit here; the next package version ships the next file.\n\n`;
+        writeFileSync(join(opts.to, target), header + body);
+        manifest.copied[name] = target;
+        copied.push({ from: name, to: target });
+        next += 1;
+    }
+    writeFileSync(join(opts.to, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { copied, manifest };
+}
+export function describeCopy(result) {
+    if (result.copied.length === 0)
+        return 'keys-migrations: nothing to copy';
+    return result.copied.map((c) => `keys-migrations: ${c.from} -> ${basename(c.to)}`).join('\n');
+}

package/dist/bin/migrations.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/migrations.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copyMigrations, describeCopy } from './copy.js';
+/**
+ * `keys-migrations [dir]`: copy this package's migrations the app has not
+ * yet copied into `dir` (default `drizzle`) as the next numbers. Idempotent;
+ * run it after every upgrade of @wtfalch/keys, then commit what it wrote.
+ *
+ * Ships every `.sql` file under `dist/migrations/` -- both `./held`'s and
+ * `./issued`'s, whichever this package version carries.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const from = join(here, '..', 'migrations');
+const to = resolve(process.cwd(), process.argv[2] ?? 'drizzle');
+const { version } = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
+console.log(describeCopy(copyMigrations({ from, to, version })));

package/dist/held/aad.d.ts

@@ -0,0 +1,13 @@
+import { type KeyBinding } from '../worker-contract.js';
+/**
+ * `encodeAad(binding)`, exactly as `worker-contract.ts` specifies it: the
+ * UTF-8 bytes of `wtfalch-keys:aad:v1\n` + `JSON.stringify([tenantId,
+ * entryId, version])`. Both the wrapped data key (checked by the Worker) and
+ * the value's own ciphertext (checked here) use this as associated data, so a
+ * row copied to another tenant or relabelled to another version fails the
+ * GCM tag on both layers.
+ *
+ * `TextEncoder` rather than `Buffer`: the Worker imports this file too, and
+ * it runs on `workerd`, not Node.
+ */
+export declare function encodeAad(binding: KeyBinding): Uint8Array;

package/dist/held/aad.js

@@ -0,0 +1,25 @@
+import { AAD_PREFIX, ID_PATTERN } from '../worker-contract.js';
+/**
+ * `encodeAad(binding)`, exactly as `worker-contract.ts` specifies it: the
+ * UTF-8 bytes of `wtfalch-keys:aad:v1\n` + `JSON.stringify([tenantId,
+ * entryId, version])`. Both the wrapped data key (checked by the Worker) and
+ * the value's own ciphertext (checked here) use this as associated data, so a
+ * row copied to another tenant or relabelled to another version fails the
+ * GCM tag on both layers.
+ *
+ * `TextEncoder` rather than `Buffer`: the Worker imports this file too, and
+ * it runs on `workerd`, not Node.
+ */
+export function encodeAad(binding) {
+    if (!ID_PATTERN.test(binding.tenantId)) {
+        throw new RangeError(`encodeAad: tenantId does not match ID_PATTERN: ${binding.tenantId}`);
+    }
+    if (!ID_PATTERN.test(binding.entryId)) {
+        throw new RangeError(`encodeAad: entryId does not match ID_PATTERN: ${binding.entryId}`);
+    }
+    if (!Number.isInteger(binding.version) || binding.version < 1) {
+        throw new RangeError(`encodeAad: version must be a positive integer: ${binding.version}`);
+    }
+    const json = JSON.stringify([binding.tenantId, binding.entryId, binding.version]);
+    return new TextEncoder().encode(`${AAD_PREFIX}${json}`);
+}

package/dist/held/index.d.ts

@@ -0,0 +1,134 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import { type KeyBinding, type SerializedCredential, type WorkerClient, type WorkerError, type WorkerErrorCode } from '../worker-contract.js';
+export { encodeAad } from './aad.js';
+export type { KeyBinding, WorkerClient, WorkerError, WorkerErrorCode } from '../worker-contract.js';
+export type { KeysHeldEntryRow, KeysHeldVersionRow } from './schema.js';
+export { shredClocks, shredExpired } from './shred.js';
+export type { ShredClock, ShredClockReason } from './shred.js';
+/**
+ * `./held`: the ciphertext half of a held key, in the host's own database
+ * (#216), plus the 60-second data-key cache and the callback-shaped `open`
+ * (#224). Encrypting and decrypting with the data key is local AES-256-GCM;
+ * only wrap/unwrap/rewrap cross the network, to the Worker.
+ *
+ * The host's own drizzle handle or a transaction open on it. postgres-js in
+ * hosts, PGlite in this package's own tests; the queries use nothing
+ * driver-specific -- the same shape `@wtfalch/audit`'s `Handle` uses.
+ */
+export type HeldKeysDb = PgDatabase<PgQueryResultHKT, any, any>;
+/**
+ * Every way `./held` refuses a call. `code` carries the Worker's own
+ * `WorkerErrorCode` verbatim when the Worker is what refused; the three
+ * local codes are refusals this package makes itself, never sent by a
+ * Worker.
+ */
+export type HeldKeysErrorCode = WorkerErrorCode | 'not_found' | 'revoked' | 'unseal_failed';
+/**
+ * Thrown by `put`, `open` and `rewrap`. Never carries a value or a key --
+ * only what a caller can act on: which entry, which code, and (for
+ * `rate_limited`) how long to wait.
+ */
+export declare class HeldKeysError extends Error {
+    readonly code: HeldKeysErrorCode;
+    readonly retryAfterMs?: number;
+    constructor(code: HeldKeysErrorCode, message?: string, retryAfterMs?: number);
+    static fromWorker(error: WorkerError): HeldKeysError;
+}
+/**
+ * What `open` writes to the host's own audit log on a cache miss, and only
+ * on a cache miss: a hit reuses a value already logged once, and per #224 /
+ * ADR 0019 a reuse is never logged, host or Worker.
+ */
+export interface KeyUsedEvent {
+    readonly name: 'key.used';
+    readonly tenantId: string;
+    readonly entryId: string;
+    readonly version: number;
+    /** The same id sent to the Worker's `unwrap` call, so #218's reconciliation can pair the two rows. */
+    readonly requestId: string;
+    /** Unix milliseconds. */
+    readonly at: number;
+}
+export interface HeldEntryRef {
+    readonly tenantId: string;
+    readonly entryId: string;
+}
+export interface CreateHeldKeysOptions {
+    /**
+     * The runtime role's ordinary connection for `put`, `open`, `forget`,
+     * `revokeEntry` and `archiveTenant` -- it has SELECT and INSERT on
+     * `keys_held_versions`, never UPDATE (#232's migration; #225: "The
+     * runtime role gets EXECUTE, never UPDATE"). Build a SEPARATE
+     * `createHeldKeys` with an operator handle (the migration/owner role) to
+     * call `rewrap` -- see that method's own doc.
+     */
+    readonly db: HeldKeysDb;
+    readonly worker: Pick<WorkerClient, 'wrap' | 'unwrap' | 'rewrap'>;
+    readonly credential: SerializedCredential;
+    readonly audit: (event: KeyUsedEvent) => void | Promise<void>;
+    /** Seconds a fetched data key is held in this process before a cache hit no longer serves it. Default 60 (#224). 0 disables caching. */
+    readonly cacheSeconds?: number;
+    /** Unix milliseconds. Defaults to `Date.now`; tests pass a fake clock to move it without waiting. */
+    readonly now?: () => number;
+}
+export interface HeldKeys {
+    /** Seals a new version under `entry`, creating the entry on its first call. */
+    put(entry: HeldEntryRef, value: string): Promise<{
+        readonly version: number;
+    }>;
+    /**
+     * Opens one version and hands the plaintext to `use`, never returning it.
+     * The callback narrows *scope* -- the value cannot be assigned to a
+     * variable that outlives the call -- but it cannot zero a JS string: a
+     * `.toString()`, a template literal, or a copy `use` itself makes can
+     * still outlive this call. That is a limit of the language, not a gap in
+     * this function.
+     */
+    open<T>(binding: KeyBinding, use: (value: string) => Promise<T>): Promise<T>;
+    /** Drops and zeroes one cached data key, if one is cached for this exact version. */
+    forget(binding: KeyBinding): void;
+    /**
+     * The rewrap sweep: moves every version still under `kekIdOld` onto
+     * `kekIdNew`. The raw data key never reaches this process.
+     *
+     * An operator sweep (#217), not a runtime action: call this only on a
+     * `HeldKeys` built with an operator database handle -- the migration or
+     * owner role, never the runtime one. The runtime role has no UPDATE on
+     * `keys_held_versions` at all (#232's migration), so calling `rewrap`
+     * against a runtime-role `db` fails with a permission error at the first
+     * row. `keys_held_versions_guard` still limits even an operator to the
+     * rewrap shape (`wrapped_key` and `kek_id` changing together, nothing
+     * else), as a guard against a fumbled statement, not against malice --
+     * Postgres cannot verify a rewrapped key's content, only its shape, so
+     * the operator's own privilege is what makes this call trustworthy.
+     */
+    rewrap(options: {
+        readonly kekIdOld: string;
+        readonly kekIdNew: string;
+    }): Promise<void>;
+    /**
+     * Marks an entry revoked. This process's own cache is cleared at once, so
+     * its next `open` for this entry is a database read and refuses. A
+     * rotation (`put`) clears the same way. Neither reaches a sibling
+     * process's cache: per #224, a process already holding this entry's data
+     * key keeps opening it from that cache until the key's own TTL runs out,
+     * at most `cacheSeconds` (default 60) after it was fetched -- the same
+     * rule app-template's `core.ts` states for its cache ("on another
+     * instance the TTL bounds how long a replaced value can still be handed
+     * out").
+     */
+    revokeEntry(entry: HeldEntryRef): Promise<void>;
+    /**
+     * Marks every entry this tenant holds archived, once each -- a second
+     * call re-dates nothing already archived (#225 revised, "the earliest of
+     * those timestamps"). This package has no `tenants` table of its own, so
+     * the mark lives on `keys_held_entries.tenant_archived_at` per entry,
+     * rather than on a row it doesn't own. It is one of the three inputs
+     * `keys_shred_expired()` (#232) reads to start a version's 30-day shred
+     * clock; it does not by itself refuse `open` -- whether a departed
+     * tenant's calls are refused is `@wtfalch/authz`'s decision, not this
+     * package's.
+     */
+    archiveTenant(tenantId: string): Promise<void>;
+}
+export declare function createHeldKeys(options: CreateHeldKeysOptions): HeldKeys;

package/dist/held/index.js

@@ -0,0 +1,308 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from 'node:crypto';
+import { and, eq, sql } from 'drizzle-orm';
+import { ID_PATTERN, } from '../worker-contract.js';
+import { encodeAad } from './aad.js';
+import { keysHeldEntries, keysHeldVersions } from './schema.js';
+export { encodeAad } from './aad.js';
+export { shredClocks, shredExpired } from './shred.js';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const ALGORITHM = 'aes-256-gcm';
+/**
+ * Thrown by `put`, `open` and `rewrap`. Never carries a value or a key --
+ * only what a caller can act on: which entry, which code, and (for
+ * `rate_limited`) how long to wait.
+ */
+export class HeldKeysError extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, message, retryAfterMs) {
+        super(message ?? `held keys: ${code}`);
+        this.name = 'HeldKeysError';
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+    }
+    static fromWorker(error) {
+        return new HeldKeysError(error.code, error.message, error.retryAfterMs);
+    }
+}
+function cacheKeyOf(binding) {
+    return `${binding.tenantId} ${binding.entryId} ${binding.version}`;
+}
+function requireId(value, label) {
+    if (!ID_PATTERN.test(value)) {
+        throw new HeldKeysError('bad_request', `${label} does not match ID_PATTERN: ${value}`);
+    }
+}
+function requireVersion(version) {
+    if (!Number.isInteger(version) || version < 1) {
+        throw new HeldKeysError('bad_request', `version must be a positive integer: ${version}`);
+    }
+}
+function gcmSeal(dataKey, plaintext, aad) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(ALGORITHM, dataKey, iv);
+    cipher.setAAD(aad);
+    const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return { iv, ciphertext: Buffer.concat([body, cipher.getAuthTag()]) };
+}
+function gcmOpen(dataKey, iv, ciphertext, aad) {
+    if (ciphertext.length < TAG_BYTES)
+        throw new HeldKeysError('unseal_failed');
+    const tag = ciphertext.subarray(ciphertext.length - TAG_BYTES);
+    const body = ciphertext.subarray(0, ciphertext.length - TAG_BYTES);
+    const decipher = createDecipheriv(ALGORITHM, dataKey, iv);
+    decipher.setAAD(aad);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(body), decipher.final()]).toString('utf8');
+    }
+    catch {
+        // Never the underlying error: an attacker learns nothing from why a tag failed.
+        throw new HeldKeysError('unseal_failed', 'that version could not be opened with the given data key');
+    }
+}
+export function createHeldKeys(options) {
+    const { db, worker, credential, audit } = options;
+    const cacheMs = (options.cacheSeconds ?? 60) * 1000;
+    const now = options.now ?? Date.now;
+    const cache = new Map();
+    function evict(key, entry) {
+        // Not a guarantee -- the runtime may have copied it -- but it shortens
+        // the window in which a heap dump holds an evicted data key, same as
+        // app-template's envelope.ts.
+        entry.dataKey.fill(0);
+        cache.delete(key);
+    }
+    function cachedFor(binding) {
+        if (cacheMs <= 0)
+            return undefined;
+        const key = cacheKeyOf(binding);
+        const hit = cache.get(key);
+        if (!hit)
+            return undefined;
+        // TTL only, never a version re-check: re-reading the row on every hit
+        // would cost the database round trip caching exists to avoid (#224).
+        if (hit.until <= now()) {
+            evict(key, hit);
+            return undefined;
+        }
+        return hit;
+    }
+    function remember(binding, dataKey, iv, ciphertext) {
+        if (cacheMs <= 0)
+            return;
+        cache.set(cacheKeyOf(binding), { dataKey, iv, ciphertext, until: now() + cacheMs });
+    }
+    function forget(binding) {
+        const key = cacheKeyOf(binding);
+        const hit = cache.get(key);
+        if (hit)
+            evict(key, hit);
+    }
+    /** Every cached version of one entry, evicted -- used on revoke, where the caller does not name a version. */
+    function forgetEntry(entry) {
+        const prefix = `${entry.tenantId} ${entry.entryId} `;
+        for (const [key, hit] of cache) {
+            if (key.startsWith(prefix))
+                evict(key, hit);
+        }
+    }
+    async function put(entry, value) {
+        requireId(entry.tenantId, 'tenantId');
+        requireId(entry.entryId, 'entryId');
+        // Reserve the next version number under a row lock, and nothing else:
+        // the lock is released the instant this short transaction commits, so a
+        // slow or unreachable Worker (the next step, outside any lock) cannot
+        // hold up a concurrent revokeEntry or another put on the same entry.
+        // Losing a version number to a failed wrap is harmless; holding a
+        // Postgres lock open across a network call to the Worker is not.
+        const version = await db.transaction(async (tx) => {
+            await tx
+                .insert(keysHeldEntries)
+                .values({ tenantId: entry.tenantId, entryId: entry.entryId, currentVersion: 0 })
+                .onConflictDoNothing();
+            const [row] = await tx
+                .select({
+                currentVersion: keysHeldEntries.currentVersion,
+                revokedAt: keysHeldEntries.revokedAt,
+            })
+                .from(keysHeldEntries)
+                .where(and(eq(keysHeldEntries.tenantId, entry.tenantId), eq(keysHeldEntries.entryId, entry.entryId)))
+                .for('update');
+            if (!row)
+                throw new HeldKeysError('not_found', 'the entry vanished mid-transaction');
+            if (row.revokedAt)
+                throw new HeldKeysError('revoked', `entry ${entry.entryId} is revoked`);
+            const next = row.currentVersion + 1;
+            await tx
+                .update(keysHeldEntries)
+                .set({ currentVersion: next })
+                .where(and(eq(keysHeldEntries.tenantId, entry.tenantId), eq(keysHeldEntries.entryId, entry.entryId)));
+            return next;
+        });
+        const binding = { tenantId: entry.tenantId, entryId: entry.entryId, version };
+        const result = await worker.wrap({ requestId: randomUUID(), credential, binding });
+        if (!result.ok)
+            throw HeldKeysError.fromWorker(result.error);
+        const dataKey = result.dataKey;
+        try {
+            const aad = encodeAad(binding);
+            const sealed = gcmSeal(dataKey, Buffer.from(value, 'utf8'), aad);
+            await db.insert(keysHeldVersions).values({
+                tenantId: entry.tenantId,
+                entryId: entry.entryId,
+                version,
+                kekId: result.kekId,
+                wrappedKey: Buffer.from(result.wrappedKey),
+                iv: sealed.iv,
+                ciphertext: sealed.ciphertext,
+            });
+            // Retiring the version this one supersedes is a side effect of the
+            // INSERT above, not a second write here: keys_held_versions_retire_predecessors
+            // (#232's migration), an AFTER INSERT, SECURITY DEFINER trigger, sets
+            // retired_at on the entry's other still-open versions itself. That
+            // keeps this write off the runtime role's own privileges entirely --
+            // #225: "The runtime role gets EXECUTE, never UPDATE" -- which this
+            // package's own put() used to violate by updating retired_at
+            // directly. If the Worker call above had failed, the reserved version
+            // number is lost (already harmless, per the comment above) and the
+            // INSERT above never runs, so the trigger never fires and the
+            // still-current old version is correctly never retired.
+        }
+        finally {
+            dataKey.fill(0);
+        }
+        // A stale cache entry for a now-superseded version is harmless (a
+        // different cache key), but a rotation invalidates anything cached for
+        // this entry so a replica does not keep handing out a value a human
+        // just believed they overwrote, beyond this cache's TTL.
+        forgetEntry(entry);
+        return { version };
+    }
+    async function open(binding, use) {
+        requireId(binding.tenantId, 'tenantId');
+        requireId(binding.entryId, 'entryId');
+        requireVersion(binding.version);
+        const cached = cachedFor(binding);
+        if (cached) {
+            const value = gcmOpen(cached.dataKey, cached.iv, cached.ciphertext, encodeAad(binding));
+            return use(value);
+        }
+        const [entryRow] = await db
+            .select({ revokedAt: keysHeldEntries.revokedAt })
+            .from(keysHeldEntries)
+            .where(and(eq(keysHeldEntries.tenantId, binding.tenantId), eq(keysHeldEntries.entryId, binding.entryId)))
+            .limit(1);
+        if (!entryRow)
+            throw new HeldKeysError('not_found', `there is no entry ${binding.entryId}`);
+        if (entryRow.revokedAt)
+            throw new HeldKeysError('revoked', `entry ${binding.entryId} is revoked`);
+        const [versionRow] = await db
+            .select({
+            kekId: keysHeldVersions.kekId,
+            wrappedKey: keysHeldVersions.wrappedKey,
+            iv: keysHeldVersions.iv,
+            ciphertext: keysHeldVersions.ciphertext,
+        })
+            .from(keysHeldVersions)
+            .where(and(eq(keysHeldVersions.tenantId, binding.tenantId), eq(keysHeldVersions.entryId, binding.entryId), eq(keysHeldVersions.version, binding.version)))
+            .limit(1);
+        if (!versionRow)
+            throw new HeldKeysError('not_found', `there is no version ${binding.version}`);
+        if (versionRow.wrappedKey === null) {
+            throw new HeldKeysError('not_found', `version ${binding.version} has been shredded`);
+        }
+        const requestId = randomUUID();
+        const result = await worker.unwrap({
+            requestId,
+            credential,
+            kekId: versionRow.kekId,
+            wrappedKey: versionRow.wrappedKey,
+            binding,
+        });
+        if (!result.ok)
+            throw HeldKeysError.fromWorker(result.error);
+        const dataKey = result.dataKey;
+        const aad = encodeAad(binding);
+        const value = gcmOpen(dataKey, versionRow.iv, versionRow.ciphertext, aad);
+        await audit({
+            name: 'key.used',
+            tenantId: binding.tenantId,
+            entryId: binding.entryId,
+            version: binding.version,
+            requestId,
+            at: now(),
+        });
+        remember(binding, dataKey, versionRow.iv, versionRow.ciphertext);
+        return use(value);
+    }
+    async function rewrap(rewrapOptions) {
+        const { kekIdOld, kekIdNew } = rewrapOptions;
+        requireId(kekIdOld, 'kekIdOld');
+        requireId(kekIdNew, 'kekIdNew');
+        const rows = await db
+            .select({
+            tenantId: keysHeldVersions.tenantId,
+            entryId: keysHeldVersions.entryId,
+            version: keysHeldVersions.version,
+            wrappedKey: keysHeldVersions.wrappedKey,
+        })
+            .from(keysHeldVersions)
+            .where(and(eq(keysHeldVersions.kekId, kekIdOld), sql `${keysHeldVersions.wrappedKey} is not null`));
+        for (const row of rows) {
+            if (row.wrappedKey === null)
+                continue; // shredded between the read above and this row; nothing to rewrap
+            const binding = {
+                tenantId: row.tenantId,
+                entryId: row.entryId,
+                version: row.version,
+            };
+            const result = await worker.rewrap({
+                requestId: randomUUID(),
+                credential,
+                kekIdOld,
+                kekIdNew,
+                wrappedKey: row.wrappedKey,
+                binding,
+            });
+            if (!result.ok)
+                throw HeldKeysError.fromWorker(result.error);
+            await db
+                .update(keysHeldVersions)
+                .set({ kekId: kekIdNew, wrappedKey: Buffer.from(result.wrappedKey) })
+                .where(and(eq(keysHeldVersions.tenantId, binding.tenantId), eq(keysHeldVersions.entryId, binding.entryId), eq(keysHeldVersions.version, binding.version)));
+        }
+    }
+    async function revokeEntry(entry) {
+        requireId(entry.tenantId, 'tenantId');
+        requireId(entry.entryId, 'entryId');
+        // The `revoked_at is null` guard makes a second call a no-op rather than
+        // re-dating the revocation: an operator investigating an incident wants
+        // the first time this entry went dark, not the last time someone called
+        // revokeEntry on an already-revoked one.
+        await db
+            .update(keysHeldEntries)
+            .set({ revokedAt: sql `now()` })
+            .where(and(eq(keysHeldEntries.tenantId, entry.tenantId), eq(keysHeldEntries.entryId, entry.entryId), sql `${keysHeldEntries.revokedAt} is null`));
+        forgetEntry(entry);
+    }
+    async function archiveTenant(tenantId) {
+        requireId(tenantId, 'tenantId');
+        // Every row for this tenant not already archived, in one statement --
+        // the `is null` guard is what makes a second call a no-op per row
+        // rather than re-dating it, same reasoning as revokeEntry above. A new
+        // entry put() after this call is not retroactively covered; that
+        // matches revokeEntry's own entry-scoped (not tenant-scoped) reach.
+        await db
+            .update(keysHeldEntries)
+            .set({ tenantArchivedAt: sql `now()` })
+            .where(and(eq(keysHeldEntries.tenantId, tenantId), sql `${keysHeldEntries.tenantArchivedAt} is null`));
+        const prefix = `${tenantId} `;
+        for (const [key, hit] of cache) {
+            if (key.startsWith(prefix))
+                evict(key, hit);
+        }
+    }
+    return { put, open, forget, rewrap, revokeEntry, archiveTenant };
+}