@wtfalch/keys 0.1.0 → 0.3.0

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/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.1.0",
+  "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"
   },
@@ -39,12 +43,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"