@wtfalch/keys 0.1.0

package/dist/migrations/0003_keys_shred.sql

@@ -0,0 +1,361 @@
+-- @wtfalch/keys ./held: the crypto-shred sweep and its guard trigger (#232).
+-- Mirrors src/held/schema.ts's tenant_archived_at and src/held/shred.ts.
+--
+-- Applied by the host's own migrate script after this file is copied into
+-- its drizzle/ directory as the next number (keys-migrations); never edited
+-- there. Every statement is idempotent. Purely additive: adds one column,
+-- four functions, six triggers, one revoke and one grant. Nothing here
+-- drops or renames anything 0002 created.
+--
+-- What "eligible" means (app-template #225, revised answer): a
+-- keys_held_versions row's data key is destroyed once it has been eligible
+-- for keys_shred_delay_days() (30, matching the estate's backup retention;
+-- see #217's revised answer) -- retired past its own grace window, its entry
+-- revoked, or its tenant archived, whichever came first. retired_at is set
+-- once, by an AFTER INSERT trigger (this migration) when a new version
+-- supersedes it; revoked_at already exists on keys_held_entries (0002,
+-- revokeEntry); tenant_archived_at is the one new column this file adds,
+-- set once by archiveTenant() across every entry a tenant holds -- this
+-- package has no tenants table of its own, so "tenant archived" is
+-- recorded per entry rather than on a row it doesn't own.
+--
+-- keys_shred_expired() is SECURITY DEFINER and takes no row-targeting
+-- argument on purpose (#225's refutation, finding 1): a targeted
+-- (entry_id, version) function would turn an ordinary EXECUTE grant into a
+-- way to destroy a still-live secret on demand. This function recomputes
+-- eligibility itself from retired_at / revoked_at / tenant_archived_at, so
+-- calling it early or from a compromised process destroys nothing beyond
+-- what was already due -- PROVIDED those three columns are trustworthy,
+-- which is what the clock-stamping trigger below exists to guarantee.
+--
+-- Three separate guards protect three separate things:
+--
+-- 1. keys_held_versions_guard: every UPDATE on keys_held_versions must be
+--    exactly a rewrap (a non-null wrapped_key replaced by another non-null
+--    one, together with a kek_id change, nothing else different), a retire
+--    (retired_at NULL to non-null, once), or a shred of a row genuinely
+--    eligible for keys_shred_delay_days() (wrapped_key to NULL, kek_id and
+--    retired_at unchanged). Everything else is refused, including
+--    un-retiring, un-shredding (NULL back to a value), re-dating a retire,
+--    and any change to tenant_id, entry_id, version, iv, ciphertext or
+--    created_at.
+--
+--    Shape alone is not privilege: a real refutation on #232 (PR #8) proved
+--    the runtime role could satisfy the "rewrap" shape with GARBAGE --
+--    wrapped_key set to arbitrary bytes plus a real kek_id change -- because
+--    Postgres has no way to verify a rewrapped key's *content*, only its
+--    shape. That destroys the value at once (it can never be unwrapped
+--    again) with no clock started and nothing for shredClocks to alert on --
+--    worse than an early shred, which at least leaves a trace. The fix the
+--    plan already specified (#225: "The runtime role gets EXECUTE, never
+--    UPDATE") is privilege, not shape: the runtime role no longer has
+--    UPDATE on this table AT ALL (see Grants) -- SELECT and INSERT only, so
+--    rewrap and retire cannot be its own ordinary writes any more, and the
+--    guard's shape checks now matter only for whoever the host trusts with
+--    an operator handle (see item 3, Grants).
+--
+--    ciphertext and iv are refused here, matching the plan's own list.
+--    0002's held.test.ts constructs an AAD-mismatch fixture with a direct
+--    UPDATE of exactly those two columns; that test runs its one fixture
+--    statement with this trigger disabled (ALTER TABLE ... DISABLE
+--    TRIGGER, as the migration owner), with a comment saying so.
+--    Overwriting ciphertext/iv makes a value unopenable at once, the same
+--    effect as an early shred, so there is no case where leaving them
+--    unguarded is defensible.
+--
+-- 2. keys_held_versions_retire_predecessors / keys_held_entries_clock_guard:
+--    keys_shred_delay_days() elapsing means nothing if the clock it
+--    measures from can be forged. #225 revised: "The write that starts the
+--    clock is itself an alert through the housekeeping tick, so an operator
+--    can reverse a forged one before the shred fires" -- which only holds if
+--    the clock's own timestamp cannot predate the write that set it. A
+--    caller with ordinary INSERT/UPDATE privilege on these columns (the
+--    runtime role, for revoked_at / tenant_archived_at; nobody, now, for
+--    retired_at -- see item 3) could otherwise set one to a timestamp 31
+--    days in the past in one statement, and the very next
+--    keys_shred_expired() tick would shred it before any housekeeping-tick
+--    alert had a chance to fire, since the alert (src/held/shred.ts's
+--    shredClocks) only sees a clock once it exists, and this one would
+--    already read as 31 days old the moment it appeared. Both guards close
+--    this: on INSERT or UPDATE, a clock column moving from NULL to
+--    non-null is stamped to now() regardless of what value the caller
+--    sent, and once set, any further change to that same column -- a
+--    different value, or NULL -- is refused outright. A clock can start
+--    once, and only at the instant its own write actually ran.
+--
+-- 3. keys_held_versions_retire_predecessors: retired_at used to be set by
+--    an ordinary UPDATE inside put() (src/held/index.ts) -- which needed
+--    the runtime role to hold UPDATE on this table, the same privilege the
+--    refutation exploited for a garbage rewrap. Retiring is now a SIDE
+--    EFFECT of the INSERT put() already performs, not a second write: this
+--    AFTER INSERT, SECURITY DEFINER trigger retires the entry's other
+--    still-open versions itself, running as its owner rather than the
+--    inserting role, so the runtime role never needs UPDATE at all. Its own
+--    internal UPDATE still passes through keys_held_versions_guard (a
+--    trigger fires regardless of who -- or what -- issued the statement),
+--    lands on the "retire" shape, and gets the same now()-stamped,
+--    set-once clock as any other write to retired_at.
+--
+--    Rewrap has no equivalent side-effect path: it is a deliberate,
+--    infrequent operator sweep (#217), not something any INSERT or ordinary
+--    runtime activity should trigger on its own. src/held/index.ts's
+--    rewrap() stays in the API, documented as requiring an operator
+--    database handle -- the owner or migration role, never the runtime
+--    one. keys_held_versions_guard still limits even that role to the
+--    rewrap shape, as a guard against mistakes, not against malice: an
+--    operator is trusted with the privilege; the shape check just keeps a
+--    fumbled UPDATE from doing something else instead.
+--
+-- Grants, following @wtfalch/audit's pattern (src/migrations/0001_audit.sql):
+-- a host names its runtime role <database>_rt, and the DO block below is a
+-- no-op if that role doesn't exist -- the functions and triggers still exist
+-- and still protect the tables either way. The runtime role keeps its
+-- ordinary default SELECT and INSERT on keys_held_versions (put and open
+-- need them; nothing else does now) and its ordinary SELECT, INSERT, UPDATE
+-- on keys_held_entries (revokeEntry, archiveTenant, and the shred guard's
+-- own eligibility lookup all need them) -- this migration does not touch
+-- keys_held_entries' grants at all. UPDATE, DELETE and TRUNCATE on
+-- keys_held_versions are revoked from the runtime role: #225's revised
+-- answer keeps a shredded row (permanent but unreadable, matching ADR 0019
+-- and audit rows), so DELETE/TRUNCATE were never legitimate; UPDATE is
+-- revoked because every legitimate write to this table -- retire, shred --
+-- now runs through a SECURITY DEFINER function rather than the runtime
+-- role's own privilege, and the one write that still needs ordinary UPDATE
+-- (rewrap) is an operator's job, not the runtime role's (item 3). The
+-- runtime role gets EXECUTE on keys_shred_expired(), nothing wider.
+
+alter table keys_held_entries
+  add column if not exists tenant_archived_at timestamptz;
+
+-- Shared by keys_shred_expired() and keys_held_versions_guard, so the sweep
+-- and the guard's own re-check can never disagree about how long a clock
+-- must run. IMMUTABLE: a pure constant, safe to inline by the planner.
+create or replace function keys_shred_delay_days() returns integer
+language sql immutable as $$
+  select 30;
+$$;
+
+create or replace function keys_shred_expired()
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  shredded integer;
+begin
+  update keys_held_versions kv
+     set wrapped_key = null
+    from 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 + (keys_shred_delay_days() || ' days')::interval)
+       or (ke.revoked_at is not null
+         and now() >= ke.revoked_at + (keys_shred_delay_days() || ' days')::interval)
+       or (ke.tenant_archived_at is not null
+         and now() >= ke.tenant_archived_at + (keys_shred_delay_days() || ' days')::interval)
+     );
+  get diagnostics shredded = row_count;
+  return shredded;
+end
+$$;
+revoke all on function keys_shred_expired() from public;
+
+create or replace function keys_held_versions_guard() returns trigger
+language plpgsql 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 := now();
+    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 := now();
+    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 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 + (keys_shred_delay_days() || ' days')::interval)
+        or exists (
+          select 1 from 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 + (keys_shred_delay_days() || ' days')::interval)
+               or (ke.tenant_archived_at is not null
+                 and now() >= ke.tenant_archived_at + (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 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
+$$;
+drop trigger if exists keys_held_versions_stamp_insert on keys_held_versions;
+create trigger keys_held_versions_stamp_insert
+  before insert on keys_held_versions
+  for each row execute function keys_held_versions_guard();
+drop trigger if exists keys_held_versions_guarded_update on keys_held_versions;
+create trigger keys_held_versions_guarded_update
+  before update on keys_held_versions
+  for each row execute function keys_held_versions_guard();
+drop trigger if exists keys_held_versions_no_delete on keys_held_versions;
+create trigger keys_held_versions_no_delete
+  before delete on keys_held_versions
+  for each row execute function keys_held_versions_guard();
+drop trigger if exists keys_held_versions_no_truncate on keys_held_versions;
+create trigger keys_held_versions_no_truncate
+  before truncate on keys_held_versions
+  for each statement execute function keys_held_versions_guard();
+
+-- The retire-on-supersede write itself (file header, item 3): runs after
+-- put()'s own INSERT commits, as this function's owner rather than the
+-- inserting role, so the runtime role's INSERT privilege alone is enough to
+-- retire a superseded version -- it never needs UPDATE. "Predecessors"
+-- (plural) rather than "the previous version": retires every OTHER
+-- still-open version of this entry, not just NEW.version - 1, so the
+-- function stays correct even if versions were ever inserted out of order.
+create or replace function keys_held_versions_retire_predecessors() returns trigger
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+begin
+  update keys_held_versions
+     set retired_at = now()
+   where tenant_id = new.tenant_id
+     and entry_id = new.entry_id
+     and version <> new.version
+     and retired_at is null;
+  return null;
+end
+$$;
+drop trigger if exists keys_held_versions_retire_predecessors_insert on keys_held_versions;
+create trigger keys_held_versions_retire_predecessors_insert
+  after insert on keys_held_versions
+  for each row execute function keys_held_versions_retire_predecessors();
+
+-- The keys_held_entries half of the same clock-stamping guarantee, for
+-- revoked_at (0002) and tenant_archived_at (this file). Deliberately
+-- narrower than keys_held_versions_guard: it says nothing about
+-- current_version or any other column on this table, only that these two
+-- clocks can never be backdated, re-dated, or cleared once set.
+create or replace function keys_held_entries_clock_guard() returns trigger
+language plpgsql as $$
+begin
+  if tg_op = 'INSERT' then
+    if new.revoked_at is not null then
+      new.revoked_at := now();
+    end if;
+    if new.tenant_archived_at is not null then
+      new.tenant_archived_at := now();
+    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 := now();
+    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 := now();
+    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
+$$;
+drop trigger if exists keys_held_entries_clock_stamp_insert on keys_held_entries;
+create trigger keys_held_entries_clock_stamp_insert
+  before insert on keys_held_entries
+  for each row execute function keys_held_entries_clock_guard();
+drop trigger if exists keys_held_entries_clock_guard_update on keys_held_entries;
+create trigger keys_held_entries_clock_guard_update
+  before update on keys_held_entries
+  for each row execute function keys_held_entries_clock_guard();
+
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke update, delete, truncate on keys_held_versions from %I', rt);
+    execute format('grant execute on function keys_shred_expired() to %I', rt);
+  end if;
+end
+$$;