@wtfalch/keys 0.1.0 → 0.2.1

package/README.md

@@ -9,7 +9,7 @@ authentication or authorisation of its own — every check runs through
 ## Install
 
 ```sh
-pnpm add @wtfalch/keys
+pnpm add @wtfalch/keys drizzle-orm@^0.45.2
 ```
 
 ## Dev
@@ -19,3 +19,11 @@ pnpm build
 pnpm typecheck
 pnpm test
 ```
+
+## Security upgrade
+
+Apply the additive `0004_keys_security.sql` migration in every consumer database before relying on the updated guards. All issuer processes must upgrade together for issuance/cascade serialization. See [the remediation and rollout notes](../../security/REMEDIATION.md).
+
+New bearer secrets have a 32-character base32 tail (160 random bits). Existing 20-character tails remain accepted. Rotation refuses invalid stored signatures and returns `conflict` if the row changes during signing.
+
+Held keys use active cache expiry (60 seconds by default) and retain at most 256 versions per instance. Set `cacheSeconds: 0` or `maxCacheEntries: 0` to disable caching. Call `dispose()` to zero cached keys, clear timers and refuse further operations. A local forget/revocation invalidates pending opens; other processes remain bounded by their own cache TTL. Plaintext callbacks can copy or return values, so their lifetime cannot be enforced by the SDK.

package/dist/held/index.d.ts

@@ -18,11 +18,11 @@ export type { ShredClock, ShredClockReason } from './shred.js';
 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
+ * `WorkerErrorCode` verbatim when the Worker is what refused; the
  * local codes are refusals this package makes itself, never sent by a
  * Worker.
  */
-export type HeldKeysErrorCode = WorkerErrorCode | 'not_found' | 'revoked' | 'unseal_failed';
+export type HeldKeysErrorCode = WorkerErrorCode | 'not_found' | 'revoked' | 'unseal_failed' | 'disposed' | 'invalidated';
 /**
  * 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
@@ -66,8 +66,10 @@ export interface CreateHeldKeysOptions {
     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. */
+    /** Seconds before active cache eviction and key zeroing. Default 60 (#224). 0 disables caching. */
     readonly cacheSeconds?: number;
+    /** Maximum cached versions. Default 256. Zero disables caching. */
+    readonly maxCacheEntries?: number;
     /** Unix milliseconds. Defaults to `Date.now`; tests pass a fake clock to move it without waiting. */
     readonly now?: () => number;
 }
@@ -77,9 +79,8 @@ export interface HeldKeys {
         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
+     * Opens one version and hands the plaintext to `use`. The callback can
+     * copy or return the value; this API cannot enforce its lifetime. 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.
@@ -87,6 +88,8 @@ export interface HeldKeys {
     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;
+    /** Zero all cached keys, cancel expiry timers, and refuse subsequent operations. */
+    dispose(): void;
     /**
      * The rewrap sweep: moves every version still under `kekIdOld` onto
      * `kekIdNew`. The raw data key never reaches this process.

package/dist/held/index.js

@@ -65,14 +65,25 @@ function gcmOpen(dataKey, iv, ciphertext, aad) {
 export function createHeldKeys(options) {
     const { db, worker, credential, audit } = options;
     const cacheMs = (options.cacheSeconds ?? 60) * 1000;
+    const maxCacheEntries = options.maxCacheEntries ?? 256;
+    if (!Number.isFinite(cacheMs) || cacheMs < 0 || cacheMs > 2_147_483_647) {
+        throw new RangeError('cacheSeconds must be finite, nonnegative and at most 2147483');
+    }
+    if (!Number.isSafeInteger(maxCacheEntries) || maxCacheEntries < 0) {
+        throw new RangeError('maxCacheEntries must be a nonnegative safe integer');
+    }
     const now = options.now ?? Date.now;
+    let disposed = false;
+    let epoch = 0;
     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.
+        clearTimeout(entry.timer);
         entry.dataKey.fill(0);
-        cache.delete(key);
+        if (cache.get(key) === entry)
+            cache.delete(key);
     }
     function cachedFor(binding) {
         if (cacheMs <= 0)
@@ -89,12 +100,40 @@ export function createHeldKeys(options) {
         }
         return hit;
     }
-    function remember(binding, dataKey, iv, ciphertext) {
-        if (cacheMs <= 0)
+    function remember(binding, dataKey, iv, ciphertext, until) {
+        if (cacheMs <= 0 || maxCacheEntries === 0 || until <= now())
             return;
-        cache.set(cacheKeyOf(binding), { dataKey, iv, ciphertext, until: now() + cacheMs });
+        const key = cacheKeyOf(binding);
+        const previous = cache.get(key);
+        if (previous)
+            evict(key, previous);
+        while (cache.size >= maxCacheEntries) {
+            const oldest = cache.entries().next().value;
+            if (oldest)
+                evict(oldest[0], oldest[1]);
+        }
+        const entry = {
+            dataKey: new Uint8Array(dataKey),
+            iv,
+            ciphertext,
+            until,
+            timer: setTimeout(() => evict(key, entry), Math.max(0, until - now())),
+        };
+        entry.timer.unref?.();
+        cache.set(key, entry);
+    }
+    function requireActive() {
+        if (disposed)
+            throw new HeldKeysError('disposed');
+    }
+    function dispose() {
+        disposed = true;
+        epoch++;
+        for (const [key, hit] of cache)
+            evict(key, hit);
     }
     function forget(binding) {
+        epoch++;
         const key = cacheKeyOf(binding);
         const hit = cache.get(key);
         if (hit)
@@ -102,6 +141,7 @@ export function createHeldKeys(options) {
     }
     /** Every cached version of one entry, evicted -- used on revoke, where the caller does not name a version. */
     function forgetEntry(entry) {
+        epoch++;
         const prefix = `${entry.tenantId} ${entry.entryId} `;
         for (const [key, hit] of cache) {
             if (key.startsWith(prefix))
@@ -109,6 +149,7 @@ export function createHeldKeys(options) {
         }
     }
     async function put(entry, value) {
+        requireActive();
         requireId(entry.tenantId, 'tenantId');
         requireId(entry.entryId, 'entryId');
         // Reserve the next version number under a row lock, and nothing else:
@@ -181,6 +222,8 @@ export function createHeldKeys(options) {
         return { version };
     }
     async function open(binding, use) {
+        requireActive();
+        const openingEpoch = epoch;
         requireId(binding.tenantId, 'tenantId');
         requireId(binding.entryId, 'entryId');
         requireVersion(binding.version);
@@ -224,20 +267,33 @@ export function createHeldKeys(options) {
         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);
+        const until = now() + cacheMs;
+        try {
+            requireActive();
+            if (epoch !== openingEpoch)
+                throw new HeldKeysError('invalidated');
+            const value = gcmOpen(dataKey, versionRow.iv, versionRow.ciphertext, encodeAad(binding));
+            await audit({
+                name: 'key.used',
+                tenantId: binding.tenantId,
+                entryId: binding.entryId,
+                version: binding.version,
+                requestId,
+                at: now(),
+            });
+            requireActive();
+            if (epoch !== openingEpoch)
+                throw new HeldKeysError('invalidated');
+            remember(binding, dataKey, versionRow.iv, versionRow.ciphertext, until);
+            dataKey.fill(0);
+            return use(value);
+        }
+        finally {
+            dataKey.fill(0);
+        }
     }
     async function rewrap(rewrapOptions) {
+        requireActive();
         const { kekIdOld, kekIdNew } = rewrapOptions;
         requireId(kekIdOld, 'kekIdOld');
         requireId(kekIdNew, 'kekIdNew');
@@ -271,10 +327,11 @@ export function createHeldKeys(options) {
             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)));
+                .where(and(eq(keysHeldVersions.tenantId, binding.tenantId), eq(keysHeldVersions.entryId, binding.entryId), eq(keysHeldVersions.version, binding.version), eq(keysHeldVersions.kekId, kekIdOld), eq(keysHeldVersions.wrappedKey, row.wrappedKey)));
         }
     }
     async function revokeEntry(entry) {
+        requireActive();
         requireId(entry.tenantId, 'tenantId');
         requireId(entry.entryId, 'entryId');
         // The `revoked_at is null` guard makes a second call a no-op rather than
@@ -288,6 +345,7 @@ export function createHeldKeys(options) {
         forgetEntry(entry);
     }
     async function archiveTenant(tenantId) {
+        requireActive();
         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
@@ -298,11 +356,12 @@ export function createHeldKeys(options) {
             .update(keysHeldEntries)
             .set({ tenantArchivedAt: sql `now()` })
             .where(and(eq(keysHeldEntries.tenantId, tenantId), sql `${keysHeldEntries.tenantArchivedAt} is null`));
+        epoch++;
         const prefix = `${tenantId} `;
         for (const [key, hit] of cache) {
             if (key.startsWith(prefix))
                 evict(key, hit);
         }
     }
-    return { put, open, forget, rewrap, revokeEntry, archiveTenant };
+    return { put, open, forget, dispose, rewrap, revokeEntry, archiveTenant };
 }

package/dist/issued/index.d.ts

@@ -54,7 +54,7 @@ export type CheckResult<TGrant> = {
     readonly ok: false;
     readonly reason: CheckRefusalReason;
 };
-export type RotateRefusalReason = 'not_found' | 'revoked' | 'minter_not_found' | 'minter_revoked' | 'minter_expired' | WorkerErrorCode;
+export type RotateRefusalReason = 'signature_invalid' | 'conflict' | 'not_found' | 'revoked' | 'minter_not_found' | 'minter_revoked' | 'minter_expired' | WorkerErrorCode;
 export type RotateResult = {
     readonly ok: true;
     readonly secret: string;

package/dist/issued/index.js

@@ -1,6 +1,7 @@
 import { and, eq, inArray, isNull } from 'drizzle-orm';
 import { sql } from 'drizzle-orm';
 import { fromBase64Url, toBase64Url } from './codec.js';
+import { canonicalJson } from './encoding.js';
 import { keyPrefixOf, mintSecret, rotateSecret, secretMatches } from './secret.js';
 import { keysIssuedCredentials } from './tables.js';
 import { verifyIssuedRowSignature } from './verify.js';
@@ -29,8 +30,8 @@ export function createCredentialIssuer(options) {
     const { db, worker, credential, verifyKeys, audit, prefix } = options;
     const now = options.now ?? (() => Date.now());
     const table = keysIssuedCredentials;
-    async function loadById(id) {
-        const [row] = await db.select().from(table).where(eq(table.id, id)).limit(1);
+    async function loadById(id, handle = db) {
+        const [row] = await handle.select().from(table).where(eq(table.id, id)).limit(1);
         return row;
     }
     async function loadByPrefix(keyPrefix) {
@@ -42,23 +43,29 @@ export function createCredentialIssuer(options) {
         return row;
     }
     /** Every descendant of `id`, `id` itself included. Mirrors valet's `subtreeOf` (`self-service.ts`). */
-    async function subtreeIds(id) {
-        const result = await db.execute(sql `
+    async function subtreeIds(id, handle) {
+        const result = await handle.execute(sql `
       with recursive descendants as (
-        select id from keys_issued_credentials where id = ${id}
+        select id from public.keys_issued_credentials where id = ${id}
         union
         select c.id
-          from keys_issued_credentials c
+          from public.keys_issued_credentials c
           join descendants d on c.issued_by_id = d.id
       )
       select id from descendants
     `);
         return rowsOf(result).map((r) => r.id);
     }
+    // One short database-wide lifecycle lock. Never held across a Worker call.
+    // The cascade snapshot and child publication must share the same lock; row
+    // locks on only the immediate parent miss concurrent ancestor revocations.
+    async function lockLifecycle(tx) {
+        await tx.execute(sql `select pg_advisory_xact_lock(1801812339, 1)`);
+    }
     async function emit(event) {
         await audit?.(event);
     }
-    async function issue(request) {
+    async function issue(request, attempt = 0) {
         if (request.idempotencyKey) {
             const existing = await loadByIdempotencyKey(request.idempotencyKey);
             if (existing) {
@@ -110,17 +117,37 @@ export function createCredentialIssuer(options) {
         if (!result.ok)
             return { ok: false, reason: result.error.code };
         try {
-            await db.insert(table).values({
-                id,
-                issuedById: candidate.issuedById,
-                keyPrefix: candidate.keyPrefix,
-                secretHash: candidate.secretHash,
-                grants: candidate.grants,
-                expiresAt: candidate.expiresAt,
-                signature: toBase64Url(result.signature),
-                signingGenerationId: result.generationId,
-                idempotencyKey: request.idempotencyKey ?? null,
+            const refusal = await db.transaction(async (tx) => {
+                await lockLifecycle(tx);
+                if (request.minter !== null) {
+                    const parent = await loadById(request.minter, tx);
+                    if (!parent)
+                        return 'minter_not_found';
+                    if (parent.revokedAt !== null)
+                        return 'minter_revoked';
+                    if (parent.expiresAt <= now())
+                        return 'minter_expired';
+                    if (!minterAttestation ||
+                        parent.signature !== toBase64Url(minterAttestation.signature) ||
+                        canonicalJson(toSignableRow(parent)) !== canonicalJson(minterAttestation.row)) {
+                        return 'bad_minter_signature';
+                    }
+                }
+                await tx.insert(table).values({
+                    id,
+                    issuedById: candidate.issuedById,
+                    keyPrefix: candidate.keyPrefix,
+                    secretHash: candidate.secretHash,
+                    grants: candidate.grants,
+                    expiresAt: candidate.expiresAt,
+                    signature: toBase64Url(result.signature),
+                    signingGenerationId: result.generationId,
+                    idempotencyKey: request.idempotencyKey ?? null,
+                });
+                return null;
             });
+            if (refusal)
+                return { ok: false, reason: refusal };
         }
         catch (err) {
             // A concurrent issue() with the same idempotencyKey won the race: the
@@ -131,6 +158,9 @@ export function createCredentialIssuer(options) {
                     return { ok: true, id: existing.id, keyPrefix: existing.keyPrefix, secret: null };
                 }
             }
+            if (attempt < 3 && isUniqueViolation(err) && (await loadByPrefix(candidate.keyPrefix))) {
+                return issue(request, attempt + 1);
+            }
             throw err;
         }
         await emit({ name: 'credential.minted', credentialId: id, requestId, at: now() });
@@ -181,6 +211,14 @@ export function createCredentialIssuer(options) {
             return { ok: false, reason: 'not_found' };
         if (row.revokedAt !== null)
             return { ok: false, reason: 'revoked' };
+        if (!(await verifyIssuedRowSignature(toSignableRow(row), fromBase64Url(row.signature), verifyKeys))) {
+            return { ok: false, reason: 'signature_invalid' };
+        }
+        if (!Number.isSafeInteger(opts.graceMs) ||
+            opts.graceMs < 0 ||
+            !Number.isSafeInteger(now() + opts.graceMs)) {
+            return { ok: false, reason: 'bad_request' };
+        }
         const minted = rotateSecret(row.keyPrefix);
         const previousValidUntil = now() + opts.graceMs;
         const candidate = {
@@ -217,30 +255,55 @@ export function createCredentialIssuer(options) {
         });
         if (!result.ok)
             return { ok: false, reason: result.error.code };
-        await db
-            .update(table)
-            .set({
-            secretHash: candidate.secretHash,
-            previousSecretHash: candidate.previousSecretHash,
-            previousValidUntil: candidate.previousValidUntil,
-            signature: toBase64Url(result.signature),
-            signingGenerationId: result.generationId,
-        })
-            .where(eq(table.id, id));
+        const refusal = await db.transaction(async (tx) => {
+            await lockLifecycle(tx);
+            const [current] = await tx.select().from(table).where(eq(table.id, id)).for('update');
+            if (!current)
+                return 'not_found';
+            if (current.revokedAt !== null)
+                return 'revoked';
+            if (current.signature !== row.signature ||
+                canonicalJson(toSignableRow(current)) !== canonicalJson(toSignableRow(row))) {
+                return 'conflict';
+            }
+            if (row.issuedById !== null) {
+                const parent = await loadById(row.issuedById, tx);
+                if (!parent)
+                    return 'minter_not_found';
+                if (parent.revokedAt !== null)
+                    return 'minter_revoked';
+                if (parent.expiresAt <= now())
+                    return 'minter_expired';
+            }
+            await tx
+                .update(table)
+                .set({
+                secretHash: candidate.secretHash,
+                previousSecretHash: candidate.previousSecretHash,
+                previousValidUntil: candidate.previousValidUntil,
+                signature: toBase64Url(result.signature),
+                signingGenerationId: result.generationId,
+            })
+                .where(eq(table.id, id));
+            return null;
+        });
+        if (refusal)
+            return { ok: false, reason: refusal };
         await emit({ name: 'credential.rotated', credentialId: id, requestId, at: now() });
         return { ok: true, secret: minted.secret };
     }
     async function revoke(id, opts = {}) {
-        const cascade = opts.cascade ?? true;
-        const ids = cascade ? await subtreeIds(id) : [id];
-        if (ids.length === 0)
-            return [];
-        const revokedAt = new Date(now());
-        const revokedRows = await db
-            .update(table)
-            .set({ revokedAt })
-            .where(and(inArray(table.id, ids), isNull(table.revokedAt)))
-            .returning({ id: table.id });
+        const revokedRows = await db.transaction(async (tx) => {
+            await lockLifecycle(tx);
+            const ids = (opts.cascade ?? true) ? await subtreeIds(id, tx) : [id];
+            if (ids.length === 0)
+                return [];
+            return tx
+                .update(table)
+                .set({ revokedAt: new Date(now()) })
+                .where(and(inArray(table.id, ids), isNull(table.revokedAt)))
+                .returning({ id: table.id });
+        });
         for (const r of revokedRows) {
             await emit({ name: 'credential.revoked', credentialId: r.id, at: now() });
         }
@@ -269,5 +332,8 @@ export function createCredentialIssuer(options) {
     return { issue, check, rotate, revoke, lineageOf };
 }
 function isUniqueViolation(err) {
-    return err?.code === '23505';
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    return e.code === '23505' || (e.cause !== err && isUniqueViolation(e.cause));
 }

package/dist/issued/secret.js

@@ -2,12 +2,12 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 /**
  * The split-secret format, carried over from valet's `src/lib/auth/keys.ts`:
  *
- *   <prefix><8-char public id><20-byte secret tail>
+ *   <prefix><8-char public id><32-char tail encoding 20 random bytes>
  *
  * The prefix through the public id is stored in the clear and is what a
  * lookup indexes on; the tail is never stored, only the SHA-256 hash of the
  * whole secret. `prefix` is host-supplied here (valet hardcodes `vk_live_`;
- * a package used by several hosts cannot), everything after it is fixed.
+ * a package used by several hosts cannot), legacy 20-character tails remain accepted during migration.
  *
  * `node:crypto` rather than WebCrypto: this is a Node-side, host-only
  * mechanic (unlike encoding.ts, nothing here runs in the Worker), and
@@ -15,6 +15,8 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
  */
 const PUBLIC_ID_LEN = 8;
 const SECRET_BYTES = 20;
+const SECRET_CHARS = 32;
+const LEGACY_SECRET_CHARS = 20;
 /** Crockford-ish base32: no padding, no vowels-to-digits confusion in logs. */
 const ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz';
 function encode(bytes) {
@@ -33,7 +35,19 @@ export function mintSecret(prefix) {
 }
 /** A fresh tail under an EXISTING `keyPrefix`: what rotate() calls, so the row keeps its indexed identity. */
 export function rotateSecret(keyPrefix) {
-    const tail = encode(randomBytes(SECRET_BYTES));
+    // Encode all 160 random bits, instead of discarding three bits per byte.
+    const bytes = randomBytes(SECRET_BYTES);
+    let tail = '';
+    let bits = 0;
+    let buffer = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            tail += ALPHABET[(buffer >>> bits) & 31];
+        }
+    }
     const secret = `${keyPrefix}${tail}`;
     return { secret, keyPrefix, secretHash: hashSecret(secret) };
 }
@@ -48,8 +62,8 @@ export function rotateSecret(keyPrefix) {
 export function keyPrefixOf(presented, prefix) {
     if (!presented.startsWith(prefix))
         return null;
-    const expected = prefix.length + PUBLIC_ID_LEN + SECRET_BYTES;
-    if (presented.length !== expected)
+    const tailLength = presented.length - prefix.length - PUBLIC_ID_LEN;
+    if (tailLength !== SECRET_CHARS && tailLength !== LEGACY_SECRET_CHARS)
         return null;
     return presented.slice(0, prefix.length + PUBLIC_ID_LEN);
 }

package/dist/migrations/0004_keys_security.sql

@@ -0,0 +1,246 @@
+-- Security review K01/K07. Additive upgrade; do not edit copied migrations.
+-- Explicit relation qualification defeats caller-owned temporary relations.
+-- The runtime role must not own these objects or have CREATE on public.
+create or replace function public.keys_shred_expired()
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public, pg_temp
+as $$
+declare
+  shredded integer;
+begin
+  update public.keys_held_versions kv
+     set wrapped_key = null
+    from public.keys_held_entries ke
+   where kv.tenant_id = ke.tenant_id
+     and kv.entry_id = ke.entry_id
+     and kv.wrapped_key is not null
+     and (
+       (kv.retired_at is not null
+         and now() >= kv.retired_at + (public.keys_shred_delay_days() || ' days')::interval)
+       or (ke.revoked_at is not null
+         and now() >= ke.revoked_at + (public.keys_shred_delay_days() || ' days')::interval)
+       or (ke.tenant_archived_at is not null
+         and now() >= ke.tenant_archived_at + (public.keys_shred_delay_days() || ' days')::interval)
+     );
+  get diagnostics shredded = row_count;
+  return shredded;
+end
+$$;
+revoke all on function public.keys_shred_expired() from public;
+
+create or replace function public.keys_held_versions_guard() returns trigger
+language plpgsql
+set search_path = pg_catalog, public, pg_temp
+as $$
+declare
+  is_rewrap boolean;
+  is_retire boolean;
+  is_shred boolean;
+begin
+  if tg_op = 'INSERT' then
+    -- Nothing that inserts a row -- put(), or keys_held_versions_retire_predecessors
+    -- below, which never inserts -- ever does so with retired_at set; this
+    -- guards a raw INSERT bypassing that, the same way the UPDATE branch
+    -- below guards a raw UPDATE.
+    if new.retired_at is not null then
+      new.retired_at := clock_timestamp();
+    end if;
+    return new;
+  elsif tg_op = 'DELETE' then
+    raise exception 'keys_held_versions is append-only: delete refused';
+  elsif tg_op = 'TRUNCATE' then
+    raise exception 'keys_held_versions is append-only: truncate refused';
+  elsif tg_op = 'UPDATE' then
+    -- Stamp: retired_at moving from NULL to non-null is forced to now(),
+    -- whatever the caller sent. Must run before the shape checks below, so
+    -- is_retire/is_shred see the real value, not a forged one.
+    if old.retired_at is null and new.retired_at is not null then
+      new.retired_at := clock_timestamp();
+    end if;
+    -- Once set, retired_at is fixed: no re-dating, no clearing.
+    if old.retired_at is not null and new.retired_at is distinct from old.retired_at then
+      raise exception 'keys_held_versions is append-only: retired_at may not be re-dated or cleared once set';
+    end if;
+
+    if new.tenant_id is distinct from old.tenant_id
+      or new.entry_id is distinct from old.entry_id
+      or new.version is distinct from old.version
+      or new.iv is distinct from old.iv
+      or new.ciphertext is distinct from old.ciphertext
+      or new.created_at is distinct from old.created_at
+    then
+      raise exception 'keys_held_versions is append-only: tenant_id, entry_id, version, iv, ciphertext and created_at may never change';
+    end if;
+
+    -- rewrap: an operator sweep (#217), run with an operator database
+    -- handle -- see the file header, item 3. The data key moves to a new
+    -- kek generation; wrapped_key and kek_id change together, retired_at
+    -- untouched either way. The guard cannot verify the new wrapped_key is
+    -- a genuine rewrap of the old one -- only Postgres-visible shape, never
+    -- content -- which is exactly why the runtime role no longer has
+    -- UPDATE at all (see Grants): this shape check is a guard against a
+    -- fumbled operator statement, not a security boundary on its own.
+    is_rewrap := old.wrapped_key is not null
+      and new.wrapped_key is not null
+      and new.wrapped_key is distinct from old.wrapped_key
+      and new.kek_id is distinct from old.kek_id
+      and new.retired_at is not distinct from old.retired_at;
+
+    -- retire: keys_held_versions_retire_predecessors, below, the only
+    -- thing that performs this write now. retired_at moves from NULL to a
+    -- value (now stamped, above), once, with nothing else about the row
+    -- changing.
+    is_retire := old.retired_at is null
+      and new.retired_at is not null
+      and new.wrapped_key is not distinct from old.wrapped_key
+      and new.kek_id is not distinct from old.kek_id;
+
+    -- shred (keys_shred_expired(), or an operator's own ordinary UPDATE
+    -- with the same shape -- the trigger cannot and does not distinguish
+    -- the two): the shape alone is not enough -- this row's own stored
+    -- clocks, which can no longer be forged (see the file header), must
+    -- already show public.keys_shred_delay_days() elapsed, the same predicate
+    -- keys_shred_expired()'s WHERE clause applies.
+    is_shred := old.wrapped_key is not null
+      and new.wrapped_key is null
+      and new.kek_id is not distinct from old.kek_id
+      and new.retired_at is not distinct from old.retired_at
+      and (
+        (new.retired_at is not null
+          and now() >= new.retired_at + (public.keys_shred_delay_days() || ' days')::interval)
+        or exists (
+          select 1 from public.keys_held_entries ke
+           where ke.tenant_id = new.tenant_id
+             and ke.entry_id = new.entry_id
+             and (
+               (ke.revoked_at is not null
+                 and now() >= ke.revoked_at + (public.keys_shred_delay_days() || ' days')::interval)
+               or (ke.tenant_archived_at is not null
+                 and now() >= ke.tenant_archived_at + (public.keys_shred_delay_days() || ' days')::interval)
+             )
+        )
+      );
+
+    if not (is_rewrap or is_retire or is_shred) then
+      raise exception 'keys_held_versions is append-only: an update must be exactly a rewrap (wrapped_key and kek_id together), a retire (retired_at NULL to non-null, once), or a shred of a row genuinely eligible for public.keys_shred_delay_days() -- refused, including un-retiring, un-shredding, shredding early, and any change to ciphertext or iv';
+    end if;
+  end if;
+  return new;
+end
+$$;
+
+-- Serialize publication before INSERT takes a snapshot of other versions.
+-- Reservations may finish out of order; current_version remains the reservation
+-- counter, not a promise that that version was successfully published.
+create or replace function public.keys_held_versions_publish_guard() returns trigger
+language plpgsql
+security definer
+set search_path = pg_catalog, public, pg_temp
+as $$
+declare
+  revoked timestamptz;
+begin
+  select revoked_at into revoked from public.keys_held_entries
+   where tenant_id = new.tenant_id and entry_id = new.entry_id for update;
+  if revoked is not null then
+    raise exception 'held entry is revoked';
+  end if;
+  if exists (select 1 from public.keys_held_versions
+      where tenant_id = new.tenant_id and entry_id = new.entry_id and version > new.version) then
+    new.retired_at := clock_timestamp();
+  end if;
+  return new;
+end
+$$;
+drop trigger if exists keys_held_versions_publish on public.keys_held_versions;
+create trigger keys_held_versions_publish before insert on public.keys_held_versions
+for each row execute function public.keys_held_versions_publish_guard();
+
+create or replace function public.keys_held_versions_retire_predecessors() returns trigger
+language plpgsql
+security definer
+set search_path = pg_catalog, public, pg_temp
+as $$
+begin
+  update public.keys_held_versions set retired_at = clock_timestamp()
+   where tenant_id = new.tenant_id and entry_id = new.entry_id
+     and version < new.version and retired_at is null;
+  return null;
+end
+$$;
+
+-- A transaction's start time is caller-controlled by holding it open. Stamp
+-- clocks at the actual write, so long transactions cannot backdate eligibility.
+create or replace function public.keys_held_entries_clock_guard() returns trigger
+language plpgsql
+set search_path = pg_catalog, public, pg_temp
+as $$
+begin
+  if tg_op = 'INSERT' then
+    if new.revoked_at is not null then
+      new.revoked_at := clock_timestamp();
+    end if;
+    if new.tenant_archived_at is not null then
+      new.tenant_archived_at := clock_timestamp();
+    end if;
+    return new;
+  elsif tg_op = 'UPDATE' then
+    if old.revoked_at is null and new.revoked_at is not null then
+      new.revoked_at := clock_timestamp();
+    end if;
+    if old.revoked_at is not null and new.revoked_at is distinct from old.revoked_at then
+      raise exception 'keys_held_entries: revoked_at may not be re-dated or cleared once set';
+    end if;
+
+    if old.tenant_archived_at is null and new.tenant_archived_at is not null then
+      new.tenant_archived_at := clock_timestamp();
+    end if;
+    if old.tenant_archived_at is not null and new.tenant_archived_at is distinct from old.tenant_archived_at then
+      raise exception 'keys_held_entries: tenant_archived_at may not be re-dated or cleared once set';
+    end if;
+  end if;
+  return new;
+end
+$$;
+
+-- K03: keep issued revocations irreversible under ordinary table privileges.
+-- Retaining IDs also prevents deleting and reinserting a revoked signed row.
+create or replace function public.keys_issued_guard() returns trigger
+language plpgsql
+set search_path = pg_catalog, public, pg_temp
+as $$
+begin
+  if tg_op in ('DELETE', 'TRUNCATE') then
+    raise exception 'keys_issued_credentials: delete and truncate refused';
+  end if;
+  if tg_op = 'UPDATE' then
+    if new.id is distinct from old.id or new.issued_by_id is distinct from old.issued_by_id
+      or new.key_prefix is distinct from old.key_prefix then
+      raise exception 'keys_issued_credentials: identity and lineage are immutable';
+    end if;
+    if old.revoked_at is not null and new.revoked_at is distinct from old.revoked_at then
+      raise exception 'keys_issued_credentials: revocation is permanent';
+    end if;
+  end if;
+  return new;
+end
+$$;
+drop trigger if exists keys_issued_guard_update on public.keys_issued_credentials;
+create trigger keys_issued_guard_update before update or delete on public.keys_issued_credentials
+for each row execute function public.keys_issued_guard();
+drop trigger if exists keys_issued_guard_truncate on public.keys_issued_credentials;
+create trigger keys_issued_guard_truncate before truncate on public.keys_issued_credentials
+for each statement execute function public.keys_issued_guard();
+
+do $$
+declare rt text := current_database() || '_rt';
+begin
+  revoke create on schema public from public;
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke create on schema public from %I', rt);
+    execute format('revoke delete, truncate on public.keys_issued_credentials from %I', rt);
+  end if;
+end
+$$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/keys",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "The estate's own bearer keys, issued to callers and held on their behalf: two entries, issued and held, nothing stored in common.",
   "repository": {
     "type": "git",
@@ -39,12 +39,12 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "drizzle-orm": ">=0.39.0"
+    "drizzle-orm": ">=0.45.2"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
-    "drizzle-orm": "^0.39.3",
+    "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.5",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"