@wtfalch/keys 0.1.0 → 0.3.0

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,27 @@ 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.
+
+## Issued-key environments
+
+Every issued credential carries a built-in `environment`, `'live'` or `'test'` (default `'live'`), passed on `issue()` and reported by `check()` and `lineageOf()`. A credential can only mint a child in its own environment — `issue()` returns `{ ok: false, reason: 'environment_mismatch' }` otherwise. Apply `0005_keys_environment.sql` alongside `0004_keys_security.sql`.
+
+## Issued-key usage tracking
+
+Every successful `check()` stamps `lastUsedAt` and increments `useCount` on the credential's row — read them off `KeysIssuedCredentialRow` directly (an admin UI's own query, not a new `check()` return field). The write is best-effort: it never turns a genuine secret into a refusal, and a revoked, expired, tampered or wrong-secret check never bumps it. Apply `0006_keys_usage.sql` alongside `0004_keys_security.sql` and `0005_keys_environment.sql`.
+
+## Per-issued-key rate limits
+
+`CreateCredentialIssuerOptions.rateLimiter` (optional) is consulted on every `check()`, keyed by the credential's own `id` — spent on every attempt against a known credential, matched secret or not, so an unlimited number of wrong guesses can't get around it. Refused as `{ ok: false, reason: 'rate_limited', retryAfterMs }`. `createPostgresRateLimiter({ db, limitPerWindow, windowMs? })` is a ready-made fixed-window limiter backed by the host's own Postgres (`0007_keys_rate_limit.sql`, applied alongside `0004`–`0006`); bring your own `RateLimiter` for anything else (Redis, D1, …). Omit it and `check()` behaves exactly as before this existed — this was previously only enforced on the host's own service credential (`packages/worker/src/ratelimit.ts`), never on an individual end-user issued key.
+
+## Outbound webhooks
+
+`@wtfalch/keys/webhooks`'s `createWebhookDispatcher({ url, secret? })` returns a function that POSTs a lifecycle event as JSON — a drop-in for `./issued`'s `audit` option (`credential.minted` / `.rotated` / `.revoked`) or `./held`'s (`key.used`). With `secret`, the body is HMAC-SHA256-signed into an `X-Keys-Signature` header; the receiver checks it with `verifyWebhookSignature(body, signature, secret)`. Delivery is fire-and-forget and best-effort — a subscriber outage never fails the call that produced the event, it only calls `onDeliveryError`.

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

@@ -1,7 +1,16 @@
 import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
 import type { SerializedCredential, VerifyKeys, WorkerClient, WorkerErrorCode } from '../worker-contract.js';
+import type { RateLimiter } from './ratelimit.js';
 export { ID_PATTERN, SIGNED_PREFIX, type RequestMeta, type SerializedCredential, type SignableRow, type SignedKind, type SignedRow, type SignRowRequest, type SignRowResult, type SignRowSuccess, type VerifyKeys, type WorkerClient, type WorkerError, type WorkerErrorCode, type WorkerFailure, } from '../worker-contract.js';
+export { createPostgresRateLimiter, type CreatePostgresRateLimiterOptions, type RateLimiter, type RateLimitResult, } from './ratelimit.js';
 export type Db = PgDatabase<PgQueryResultHKT, any, any>;
+/**
+ * #47: a built-in sandbox/live split, so a stamped host does not invent its
+ * own convention on top of `prefix`. Stored on the row (`environment`,
+ * immutable once set) but never signed -- `prefix` alone still decides what
+ * a presented secret is, same as before this existed.
+ */
+export type KeyEnvironment = 'live' | 'test';
 export interface AuditEvent {
     readonly name: 'credential.minted' | 'credential.rotated' | 'credential.revoked';
     readonly credentialId: string;
@@ -22,6 +31,13 @@ export interface CreateCredentialIssuerOptions<TGrant> {
     readonly audit?: AuditCallback;
     /** This host's split-secret prefix, e.g. `ai_live_`. Fixed per issuer; never inferred from a row. */
     readonly prefix: string;
+    /**
+     * #45: an abuse limit `check()` consults per credential `id`, spent on
+     * every attempt (matched secret or not) once a row is found. Omit it and
+     * `check()` behaves exactly as before this existed. `createPostgresRateLimiter`
+     * (this module) is a ready-made one backed by the host's own `db`.
+     */
+    readonly rateLimiter?: RateLimiter;
     /** Unix milliseconds. Defaults to `Date.now`; a test passes a fake clock. */
     readonly now?: () => number;
 }
@@ -32,8 +48,12 @@ export interface IssueRequest<TGrant> {
     /** Unix milliseconds. Required: refused when missing or already past, never clamped to the minter's own. */
     readonly expiresAt: number;
     readonly idempotencyKey?: string;
+    /** Default `'live'`. A child must match its minter's environment -- see `IssueRefusalReason`. */
+    readonly environment?: KeyEnvironment;
 }
-export type IssueRefusalReason = 'expires_at_required' | 'expires_at_past' | 'minter_not_found' | 'minter_revoked' | 'minter_expired' | WorkerErrorCode;
+export type IssueRefusalReason = 'expires_at_required' | 'expires_at_past' | 'minter_not_found' | 'minter_revoked' | 'minter_expired'
+/** #47: `request.environment` (or its `'live'` default) does not match the minter row's own. */
+ | 'environment_mismatch' | WorkerErrorCode;
 export type IssueResult = {
     readonly ok: true;
     readonly id: string;
@@ -44,17 +64,22 @@ export type IssueResult = {
     readonly ok: false;
     readonly reason: IssueRefusalReason;
 };
-export type CheckRefusalReason = 'not_found' | 'signature_invalid' | 'revoked' | 'expired' | 'secret_mismatch';
+export type CheckRefusalReason = 'not_found' | 'signature_invalid' | 'revoked' | 'expired' | 'secret_mismatch'
+/** #45: `rateLimiter` refused this credential id for the current window. */
+ | 'rate_limited';
 export type CheckResult<TGrant> = {
     readonly ok: true;
     readonly id: string;
     readonly issuedById: string | null;
     readonly grants: readonly TGrant[];
+    readonly environment: KeyEnvironment;
 } | {
     readonly ok: false;
     readonly reason: CheckRefusalReason;
+    /** Only meaningful with `reason: 'rate_limited'`. */
+    readonly retryAfterMs?: number;
 };
-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;
@@ -68,6 +93,7 @@ export interface CredentialLink<TGrant> {
     readonly grants: readonly TGrant[];
     readonly expiresAt: number;
     readonly revokedAt: number | null;
+    readonly environment: KeyEnvironment;
 }
 export interface CredentialIssuer<TGrant> {
     /** Calls `worker.signRow`. */