@wtfalch/keys 0.2.1 → 0.3.0

package/README.md

@@ -27,3 +27,19 @@ Apply the additive `0004_keys_security.sql` migration in every consumer database
 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/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,15 +64,20 @@ 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 = 'signature_invalid' | 'conflict' | 'not_found' | 'revoked' | 'minter_not_found' | 'minter_revoked' | 'minter_expired' | WorkerErrorCode;
 export type RotateResult = {
@@ -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`. */

package/dist/issued/index.js

@@ -6,6 +6,7 @@ import { keyPrefixOf, mintSecret, rotateSecret, secretMatches } from './secret.j
 import { keysIssuedCredentials } from './tables.js';
 import { verifyIssuedRowSignature } from './verify.js';
 export { ID_PATTERN, SIGNED_PREFIX, } from '../worker-contract.js';
+export { createPostgresRateLimiter, } from './ratelimit.js';
 function rowsOf(result) {
     if (Array.isArray(result))
         return result;
@@ -27,7 +28,7 @@ function toSignableRow(row) {
     };
 }
 export function createCredentialIssuer(options) {
-    const { db, worker, credential, verifyKeys, audit, prefix } = options;
+    const { db, worker, credential, verifyKeys, audit, prefix, rateLimiter } = options;
     const now = options.now ?? (() => Date.now());
     const table = keysIssuedCredentials;
     async function loadById(id, handle = db) {
@@ -78,6 +79,7 @@ export function createCredentialIssuer(options) {
         if (request.expiresAt <= now()) {
             return { ok: false, reason: 'expires_at_past' };
         }
+        const environment = request.environment ?? 'live';
         let minterAttestation = null;
         if (request.minter !== null) {
             const minterRow = await loadById(request.minter);
@@ -90,6 +92,11 @@ export function createCredentialIssuer(options) {
                 return { ok: false, reason: 'minter_revoked' };
             if (minterRow.expiresAt <= now())
                 return { ok: false, reason: 'minter_expired' };
+            // #47: a test key can only mint a test key, a live key only a live
+            // one -- the pairing the issue asked for, not just a label.
+            if (minterRow.environment !== environment) {
+                return { ok: false, reason: 'environment_mismatch' };
+            }
             minterAttestation = {
                 row: toSignableRow(minterRow),
                 signature: fromBase64Url(minterRow.signature),
@@ -127,6 +134,8 @@ export function createCredentialIssuer(options) {
                         return 'minter_revoked';
                     if (parent.expiresAt <= now())
                         return 'minter_expired';
+                    if (parent.environment !== environment)
+                        return 'environment_mismatch';
                     if (!minterAttestation ||
                         parent.signature !== toBase64Url(minterAttestation.signature) ||
                         canonicalJson(toSignableRow(parent)) !== canonicalJson(minterAttestation.row)) {
@@ -143,6 +152,7 @@ export function createCredentialIssuer(options) {
                     signature: toBase64Url(result.signature),
                     signingGenerationId: result.generationId,
                     idempotencyKey: request.idempotencyKey ?? null,
+                    environment,
                 });
                 return null;
             });
@@ -173,6 +183,24 @@ export function createCredentialIssuer(options) {
         const row = await loadByPrefix(keyPrefix);
         if (!row)
             return { ok: false, reason: 'not_found' };
+        // #45: spent on every attempt against a known credential, matched
+        // secret or not -- an unlimited number of wrong guesses against an
+        // identified row would otherwise let an attacker brute-force it past
+        // any per-successful-use limit. Before the signature check below, so a
+        // flood of requests against one credential id never reaches the more
+        // expensive Ed25519 verify.
+        // A `rateLimiter.check` failure is NOT caught, unlike #46's usage
+        // write below: rate limiting is a security control the host opted
+        // into, and failing open on it (silently never limiting anything
+        // whenever its store is unreachable) is a worse failure mode than a
+        // loud one a host notices in its own staging environment the first
+        // time the migration is missing or the store is down.
+        if (rateLimiter) {
+            const limit = await rateLimiter.check(row.id, now());
+            if (limit.limited) {
+                return { ok: false, reason: 'rate_limited', retryAfterMs: limit.retryAfterMs };
+            }
+        }
         // Verified before anything else is trusted about the row: a signature
         // check over the row's CURRENT fields refuses a row a raw UPDATE
         // tampered with, whatever that tamper changed.
@@ -184,26 +212,34 @@ export function createCredentialIssuer(options) {
             return { ok: false, reason: 'revoked' };
         if (now() >= row.expiresAt)
             return { ok: false, reason: 'expired' };
-        if (secretMatches(secret, row.secretHash)) {
-            return {
-                ok: true,
-                id: row.id,
-                issuedById: row.issuedById,
-                grants: row.grants,
-            };
+        const matched = secretMatches(secret, row.secretHash) ||
+            (row.previousSecretHash !== null &&
+                row.previousValidUntil !== null &&
+                now() < row.previousValidUntil &&
+                secretMatches(secret, row.previousSecretHash));
+        if (!matched)
+            return { ok: false, reason: 'secret_mismatch' };
+        // #46: last-used/use-count, for an admin UI to read directly off the
+        // row -- best-effort. A write failure here is observability lost, not
+        // an authorization decision, so it must never turn an otherwise-genuine
+        // secret into a refusal; check() stays available for the one thing it
+        // exists to do even if this bookkeeping write cannot land.
+        try {
+            await db
+                .update(table)
+                .set({ lastUsedAt: new Date(now()), useCount: sql `${table.useCount} + 1` })
+                .where(eq(table.id, row.id));
         }
-        if (row.previousSecretHash !== null &&
-            row.previousValidUntil !== null &&
-            now() < row.previousValidUntil &&
-            secretMatches(secret, row.previousSecretHash)) {
-            return {
-                ok: true,
-                id: row.id,
-                issuedById: row.issuedById,
-                grants: row.grants,
-            };
+        catch {
+            // Swallowed by design -- see comment above.
         }
-        return { ok: false, reason: 'secret_mismatch' };
+        return {
+            ok: true,
+            id: row.id,
+            issuedById: row.issuedById,
+            grants: row.grants,
+            environment: row.environment,
+        };
     }
     async function rotate(id, opts) {
         const row = await loadById(id);
@@ -324,6 +360,7 @@ export function createCredentialIssuer(options) {
                 grants: row.grants,
                 expiresAt: row.expiresAt,
                 revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
+                environment: row.environment,
             });
             currentId = row.issuedById;
         }

package/dist/issued/ratelimit.d.ts

@@ -0,0 +1,34 @@
+import type { Db } from './index.js';
+/**
+ * #45: a per-issued-credential abuse limit. `packages/worker/src/ratelimit.ts`
+ * already limits per `hostId` + the HOST's own service credential; nothing
+ * limited an END USER's individual issued key until this. `check()` consults
+ * `CreateCredentialIssuerOptions.rateLimiter`, when one is given, keyed by
+ * the credential's own `id` -- once the row is found (so a known
+ * credential's budget is spent on every attempt, matched secret or not,
+ * not only on a successful one), before its secret is verified.
+ */
+export interface RateLimitResult {
+    readonly limited: boolean;
+    /** Milliseconds until the current window resets. Meaningful whether or not `limited`. */
+    readonly retryAfterMs: number;
+}
+export interface RateLimiter {
+    /** `now`: Unix milliseconds, the same clock `check()`'s own `now` option gives -- never read internally, so a fake clock in a test reaches this too. */
+    check(credentialId: string, now: number): Promise<RateLimitResult>;
+}
+export interface CreatePostgresRateLimiterOptions {
+    readonly db: Db;
+    /** Requests a single credential may make per window before `limited` is true. */
+    readonly limitPerWindow: number;
+    /** Milliseconds. Default 60_000. */
+    readonly windowMs?: number;
+}
+/**
+ * A fixed-window counter in the host's own Postgres, one bounded row per
+ * credential (`keys_issued_rate_limit_windows`, `0007_keys_rate_limit.sql`),
+ * atomically reset each window by a single upsert -- the same shape
+ * `packages/worker/src/ratelimit.ts`'s D1 `host_rate_limit_windows` uses, a
+ * level down: keyed by the end user's credential id, not the host's.
+ */
+export declare function createPostgresRateLimiter(options: CreatePostgresRateLimiterOptions): RateLimiter;

package/dist/issued/ratelimit.js

@@ -0,0 +1,49 @@
+import { sql } from 'drizzle-orm';
+function rowsOf(result) {
+    if (Array.isArray(result))
+        return result;
+    return (result.rows ?? []);
+}
+/**
+ * A fixed-window counter in the host's own Postgres, one bounded row per
+ * credential (`keys_issued_rate_limit_windows`, `0007_keys_rate_limit.sql`),
+ * atomically reset each window by a single upsert -- the same shape
+ * `packages/worker/src/ratelimit.ts`'s D1 `host_rate_limit_windows` uses, a
+ * level down: keyed by the end user's credential id, not the host's.
+ */
+export function createPostgresRateLimiter(options) {
+    const { db, limitPerWindow } = options;
+    const windowMs = options.windowMs ?? 60_000;
+    return {
+        async check(credentialId, now) {
+            const windowStart = Math.floor(now / windowMs) * windowMs;
+            const result = await db.execute(sql `
+        insert into keys_issued_rate_limit_windows (credential_id, window_start, count)
+        values (${credentialId}, ${windowStart}, 1)
+        on conflict (credential_id) do update set
+          window_start = excluded.window_start,
+          count = case
+            when keys_issued_rate_limit_windows.window_start = excluded.window_start
+            then keys_issued_rate_limit_windows.count + 1
+            else 1
+          end
+        returning window_start, count
+      `);
+            const [row] = rowsOf(result);
+            if (!row)
+                throw new Error('rate limit write returned no row');
+            // `count` is `integer` (int4), always JS-number-safe -- but a raw
+            // (non-query-builder) result is still driver-dependent about handing
+            // it back as a number or a numeric string, so `Number(...)` either
+            // way. `window_start` itself is never re-read from the row: the
+            // upsert always sets it to `excluded.window_start`, never
+            // conditionally kept, so it equals the `windowStart` just computed
+            // above.
+            const count = Number(row.count);
+            return {
+                limited: count > limitPerWindow,
+                retryAfterMs: windowStart + windowMs - now,
+            };
+        },
+    };
+}

package/dist/issued/tables.d.ts

@@ -16,6 +16,16 @@
  * a lazily-declared drizzle table needs an `AnyPgColumn` callback and buys
  * nothing this package's own tests check, since the constraint that actually
  * runs is the one in the SQL migration.
+ *
+ * `environment` (#47) is not part of `SignableRow` -- unsigned metadata, same
+ * footing as `idempotencyKey`/`createdAt`. `0005_keys_environment.sql`'s
+ * extended `keys_issued_guard()` trigger is what keeps it trustworthy: set
+ * once at `issue()`, immutable for the row's life.
+ *
+ * `lastUsedAt`/`useCount` (#46, `0006_keys_usage.sql`) are the one pair on
+ * this row that is NOT set-once: `check()` writes both on every successful
+ * verification, so -- unlike `environment` -- `keys_issued_guard()` leaves
+ * them out of its immutable-columns check.
  */
 export declare const keysIssuedCredentials: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "keys_issued_credentials";
@@ -208,6 +218,23 @@ export declare const keysIssuedCredentials: import("drizzle-orm/pg-core").PgTabl
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        environment: import("drizzle-orm/pg-core").PgColumn<{
+            name: "environment";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdAt: import("drizzle-orm/pg-core").PgColumn<{
             name: "created_at";
             tableName: "keys_issued_credentials";
@@ -242,6 +269,40 @@ export declare const keysIssuedCredentials: import("drizzle-orm/pg-core").PgTabl
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        lastUsedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "last_used_at";
+            tableName: "keys_issued_credentials";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        useCount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "use_count";
+            tableName: "keys_issued_credentials";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
     };
     dialect: "pg";
 }>;

package/dist/issued/tables.js

@@ -17,6 +17,16 @@ import { bigint, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
  * a lazily-declared drizzle table needs an `AnyPgColumn` callback and buys
  * nothing this package's own tests check, since the constraint that actually
  * runs is the one in the SQL migration.
+ *
+ * `environment` (#47) is not part of `SignableRow` -- unsigned metadata, same
+ * footing as `idempotencyKey`/`createdAt`. `0005_keys_environment.sql`'s
+ * extended `keys_issued_guard()` trigger is what keeps it trustworthy: set
+ * once at `issue()`, immutable for the row's life.
+ *
+ * `lastUsedAt`/`useCount` (#46, `0006_keys_usage.sql`) are the one pair on
+ * this row that is NOT set-once: `check()` writes both on every successful
+ * verification, so -- unlike `environment` -- `keys_issued_guard()` leaves
+ * them out of its immutable-columns check.
  */
 export const keysIssuedCredentials = pgTable('keys_issued_credentials', {
     id: text('id').primaryKey(),
@@ -30,6 +40,9 @@ export const keysIssuedCredentials = pgTable('keys_issued_credentials', {
     signature: text('signature').notNull(),
     signingGenerationId: text('signing_generation_id').notNull(),
     idempotencyKey: text('idempotency_key'),
+    environment: text('environment').notNull(),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     revokedAt: timestamp('revoked_at', { withTimezone: true }),
+    lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
+    useCount: bigint('use_count', { mode: 'number' }).notNull().default(0),
 });

package/dist/migrations/0005_keys_environment.sql

@@ -0,0 +1,52 @@
+-- #47: a built-in `environment` on every issued credential, so a host's
+-- sandbox/live split is a structured field rather than a convention the host
+-- invents on top of `key_prefix`. Additive; do not edit copied migrations.
+--
+-- Not part of SignableRow (worker-contract.ts): the Worker's signature never
+-- covers it, same footing as idempotency_key and created_at. What keeps it
+-- trustworthy despite that is keys_issued_guard() below, extended to refuse
+-- any UPDATE that changes it -- set once at issue(), for that row's life.
+--
+-- Backfilled 'live' on existing rows: every row minted before this migration
+-- was minted under a single, unqualified prefix, which today's default
+-- environment ('live') matches.
+alter table keys_issued_credentials
+  add column if not exists environment text not null default 'live';
+alter table keys_issued_credentials alter column environment drop default;
+
+do $$
+begin
+  if not exists (
+    select 1 from pg_constraint
+    where conname = 'keys_issued_credentials_environment_check'
+  ) then
+    alter table keys_issued_credentials
+      add constraint keys_issued_credentials_environment_check
+      check (environment in ('live', 'test'));
+  end if;
+end
+$$;
+
+-- Extends 0004's keys_issued_guard(): identity, lineage AND environment are
+-- immutable once a row is inserted.
+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
+      or new.environment is distinct from old.environment then
+      raise exception 'keys_issued_credentials: identity, lineage and environment 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
+$$;

package/dist/migrations/0006_keys_usage.sql

@@ -0,0 +1,26 @@
+-- #46: last-used and usage tracking on every issued credential, so an admin
+-- UI (manage) can tell which issued keys are live versus stale. Additive; do
+-- not edit copied migrations.
+--
+-- Neither column is part of SignableRow (worker-contract.ts) -- unsigned,
+-- same footing as environment/idempotency_key/created_at (0005) -- and, per
+-- keys_issued_guard() below, is NOT frozen the way those are: check() writes
+-- both on every successful verification, so they must stay ordinarily
+-- updatable rather than joining the identity/lineage/environment immutable
+-- set.
+alter table keys_issued_credentials
+  add column if not exists last_used_at timestamptz,
+  add column if not exists use_count bigint not null default 0;
+
+do $$
+begin
+  if not exists (
+    select 1 from pg_constraint
+    where conname = 'keys_issued_credentials_use_count_check'
+  ) then
+    alter table keys_issued_credentials
+      add constraint keys_issued_credentials_use_count_check
+      check (use_count >= 0);
+  end if;
+end
+$$;

package/dist/migrations/0007_keys_rate_limit.sql

@@ -0,0 +1,20 @@
+-- #45: a per-issued-credential rate limit window, backing
+-- `createPostgresRateLimiter` (`src/issued/ratelimit.ts`). Additive; do not
+-- edit copied migrations.
+--
+-- One bounded row per credential, atomically reset each window by the same
+-- upsert shape `packages/worker/src/ratelimit.ts`'s D1
+-- `host_rate_limit_windows` uses for the host's own service credential --
+-- this table is the same idea one level down, keyed by the END USER's
+-- issued credential id rather than the host's.
+--
+-- No foreign key to keys_issued_credentials: a row here outlives a revoked
+-- or even (in principle) a since-deleted credential without orphaning a
+-- constraint, and check() only ever looks one up by an id it already
+-- verified against a signed row.
+create table if not exists keys_issued_rate_limit_windows (
+  credential_id  text not null primary key,
+  window_start   bigint not null,
+  count          integer not null,
+  constraint keys_issued_rate_limit_windows_count_check check (count > 0)
+);

package/dist/webhooks.d.ts

@@ -0,0 +1,55 @@
+/**
+ * #48: outbound HTTP delivery for the events `./issued`'s `AuditCallback`
+ * and `./held`'s `audit: (event: KeyUsedEvent) => …` already carry
+ * in-process. `createWebhookDispatcher` is a drop-in for either option --
+ * both already call their callback with one JSON-serializable event object
+ * carrying a `name` -- so a stamped service (agora, manage, operator) can
+ * subscribe to key lifecycle events over HTTP instead of polling another
+ * service's database.
+ *
+ * `node:crypto`, not WebCrypto: this runs host-side only, the same posture
+ * as `secret.ts`.
+ */
+export interface WebhookDeliveryOptions {
+    readonly url: string;
+    /**
+     * HMAC-SHA256 over the raw JSON body, sent hex-encoded as
+     * `X-Keys-Signature`. Omit only when the endpoint's own network
+     * boundary (an internal-only URL, a bearer token baked into `url`) is
+     * the sole protection -- `verifyWebhookSignature` is how the receiver
+     * checks it.
+     */
+    readonly secret?: string;
+    /** Defaults to the global `fetch`. Tests pass a stub. */
+    readonly fetch?: typeof fetch;
+    /**
+     * Called with whatever made one delivery fail -- a thrown error, or an
+     * `Error` wrapping a non-2xx response -- and the event that failed to
+     * deliver. Never rethrown: a webhook subscriber's outage must never fail
+     * the `issue()`/`rotate()`/`revoke()`/`open()` call that produced the
+     * event. Delivery is fire-and-forget and best-effort, not at-least-once;
+     * a host that needs a retried or durable queue puts one in front of
+     * `url`, or wraps this callback itself.
+     */
+    readonly onDeliveryError?: (error: unknown, event: unknown) => void;
+}
+/**
+ * An `AuditCallback` (`./issued`) or `KeyUsedEvent` callback (`./held`) that
+ * POSTs the event as JSON to `options.url`.
+ */
+export declare function createWebhookDispatcher<TEvent extends {
+    readonly name: string;
+}>(options: WebhookDeliveryOptions): (event: TEvent) => Promise<void>;
+/** Hex HMAC-SHA256 of `body` under `secret`. What `X-Keys-Signature` carries. */
+export declare function signWebhookBody(body: string, secret: string): string;
+/**
+ * Constant-time check that `signature` (as received in `X-Keys-Signature`)
+ * matches `body` under `secret`. What a webhook receiver calls before
+ * trusting a delivered event.
+ *
+ * `body` must be the exact raw request body bytes (as text) the signature
+ * was computed over -- parsing it to JSON and re-serializing it before
+ * verifying, or trimming/normalizing whitespace, changes the bytes and the
+ * signature will not match even for a genuine delivery.
+ */
+export declare function verifyWebhookSignature(body: string, signature: string, secret: string): boolean;

package/dist/webhooks.js

@@ -0,0 +1,51 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * An `AuditCallback` (`./issued`) or `KeyUsedEvent` callback (`./held`) that
+ * POSTs the event as JSON to `options.url`.
+ */
+export function createWebhookDispatcher(options) {
+    const doFetch = options.fetch ?? fetch;
+    return async (event) => {
+        try {
+            const body = JSON.stringify(event);
+            const headers = { 'content-type': 'application/json' };
+            if (options.secret !== undefined) {
+                headers['x-keys-signature'] = signWebhookBody(body, options.secret);
+            }
+            const response = await doFetch(options.url, { method: 'POST', headers, body });
+            if (!response.ok) {
+                throw new Error(`webhook delivery to ${options.url} got HTTP ${response.status}`);
+            }
+        }
+        catch (err) {
+            options.onDeliveryError?.(err, event);
+        }
+    };
+}
+/** Hex HMAC-SHA256 of `body` under `secret`. What `X-Keys-Signature` carries. */
+export function signWebhookBody(body, secret) {
+    return createHmac('sha256', secret).update(body, 'utf8').digest('hex');
+}
+/**
+ * Constant-time check that `signature` (as received in `X-Keys-Signature`)
+ * matches `body` under `secret`. What a webhook receiver calls before
+ * trusting a delivered event.
+ *
+ * `body` must be the exact raw request body bytes (as text) the signature
+ * was computed over -- parsing it to JSON and re-serializing it before
+ * verifying, or trimming/normalizing whitespace, changes the bytes and the
+ * signature will not match even for a genuine delivery.
+ */
+export function verifyWebhookSignature(body, signature, secret) {
+    const expected = Buffer.from(signWebhookBody(body, secret), 'hex');
+    let presented;
+    try {
+        presented = Buffer.from(signature, 'hex');
+    }
+    catch {
+        return false;
+    }
+    if (presented.length !== expected.length)
+        return false;
+    return timingSafeEqual(presented, expected);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/keys",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",
@@ -22,6 +22,10 @@
       "types": "./dist/held/index.d.ts",
       "default": "./dist/held/index.js"
     },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "default": "./dist/webhooks.js"
+    },
     "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },