@consiliency/agent-board-schema 1.50.0 → 1.51.0

package/tests/agent_board_signing_challenge_pending_cap.test.sql

@@ -1,23 +1,71 @@
--- MBHARDEN SL-1 pgTAP: issue_signing_key_challenge enforces a per-key cap of
--- N=16 concurrently-pending challenges; <=16 issue as before, the 17th is
--- rejected, and expired/consumed challenges do not count toward the cap.
+-- issue_signing_key_challenge bounds a key to N=16 concurrently-pending challenges,
+-- and AT the bound it supersedes the oldest pending challenge instead of refusing.
+--
+-- WHY THIS FILE CHANGED SHAPE (F1, code-review-2026-09-01). It used to assert that the
+-- 17th pending challenge was REJECTED. That rejection was the defect: /session step
+-- "challenge" is verify_jwt=false and needs only a directory-visible handle and key id,
+-- so sixteen requests denied a key every further challenge, and the client stopped its
+-- refresh loop on the resulting 403. The bound is unchanged and still asserted; what is
+-- asserted now is that arrival is never refused.
+--
+-- It also stopped standing on `select pass(...)`. Three of this file's four assertions
+-- were unconditional passes placed after a DO block that raised on failure — an ok line
+-- that says nothing about what it ran beside, and the exact construct review finding F51
+-- names. Every assertion below reads state back out of the table.
+--
+-- WHY EVERY `DO` BLOCK HERE TRAPS INSTEAD OF RAISING, which is the part that is easy to
+-- undo. Rewriting the passes into real assertions is only half the job, and the half that
+-- is visible. The other half was found by MUTATING: reverting the supersede so the RPC
+-- raises `challenge_pending_cap` again made this file report NOTHING. A bare call to a
+-- raising RPC inside a `DO` block aborts the whole transaction, so pgTAP printed `1..18`,
+-- then `ok 1`, `ok 2`, `ok 3`, then twenty lines of `current transaction is aborted` — and
+-- ZERO `not ok`. Three of eighteen assertions ran and nothing said so. That is AGENTS.md
+-- rule 3 exactly, and it is worse than it sounds: the shipped code path never raises, so
+-- this only appears when someone mutates, and a `grep not ok` over the failing run comes
+-- back clean.
+--
+-- So every block that calls the RPC wraps it in `begin … exception when others then …`
+-- and records the OUTCOME (an id, or `sqlerrm`) into the `pcap_state` temp table, which a
+-- named assertion then checks. A raise becomes a value, not an abort. With the trap in
+-- place the same mutation emits 20 of 20 with a named `not ok`, the first being #4.
+--
+-- "Every block" is now literally true, and was not when first written: the SEED loop below
+-- called the RPC sixteen times bare. It happens not to raise under either mutation this
+-- file is cited for (sixteen issues are UNDER the cap), so nothing caught it — which is
+-- the point. A block that cannot raise TODAY is one cap constant away from being the block
+-- that silently stops the file, and "every" in a comment is a claim, not a description.
+--
+-- Two smaller traps in the same family, both of which abort identically and both of which
+-- cost a debugging round here:
+--   * `v_c := null` on a plpgsql `record` raises `record "v_c" is not assigned yet` — the
+--     exception HANDLER was aborting the transaction. Use a scalar (`v_id uuid`).
+--   * Writing `pcap_state` while still under `set local role service_role` raises
+--     `permission denied for table pcap_state`: the temp table belongs to the session
+--     user. Every temp-table write below therefore happens after `reset role`.
+--
+-- If you add a probe here that can raise, trap it. An untrapped one does not fail loudly;
+-- it silently stops the file.
 create extension if not exists pgtap with schema extensions;
 set search_path = extensions, public, agent_board;
 
 begin;
 
-select plan(4);
+select plan(20);
 
 select has_function(
   'agent_board', 'issue_signing_key_challenge', array['uuid', 'text', 'interval'],
   'issue_signing_key_challenge exists');
+select has_function(
+  'agent_board', 'mint_fleet_agent_session', array['uuid', 'text', 'uuid', 'uuid', 'integer'],
+  'mint_fleet_agent_session exists');
 
--- Block 1: 16 pending challenges are allowed; the 17th is rejected by the cap.
+-- Seed one agent + key, then fill the key's sixteen pending slots.
 do $$
 declare
   v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
   v_i int;
   v_c record;
+  v_ids uuid[] := '{}';
 begin
   insert into agent_board.agents(id, agent_type, handle, display_name)
   values (v_agent, 'agent', 'pcap-agent', 'PCAP Agent');
@@ -27,60 +75,367 @@ begin
     v_agent, 'primary', 1, public.test_pubkey('pcap-primary'), 'raw_ed25519_base64url',
     public.test_key_fingerprint('pcap-primary'));
 
+  -- Issue as service_role, then RESET before back-dating: service_role holds SELECT
+  -- only on agent_signing_key_challenges, so the UPDATE must run as the owner.
+  -- created_at is set explicitly rather than relying on clock order, because every
+  -- row in one statement-less loop can share a now().
   set local role service_role;
-
   for v_i in 1..16 loop
-    select * into v_c
-      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
-    if v_c.challenge_id is null then
-      raise exception 'pending challenge % was not issued below the cap', v_i;
-    end if;
+    -- Trapped like every other call site here. These sixteen are below the cap and do not
+    -- raise today; if a change makes one raise, this leaves v_ids short and assertion 3
+    -- fails BY NAME instead of the raise aborting the transaction and emitting nothing.
+    begin
+      select * into v_c
+        from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+      v_ids := array_append(v_ids, v_c.challenge_id);
+    exception when others then
+      exit;
+    end;
   end loop;
+  reset role;
+
+  for v_i in 1..coalesce(array_length(v_ids, 1), 0) loop
+    update agent_board.agent_signing_key_challenges
+       set created_at = now() - make_interval(secs => (17 - v_i))
+     where id = v_ids[v_i];
+  end loop;
+end
+$$;
+reset role;
+
+-- 1. The bound is reached, and every one of the sixteen is genuinely pending.
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and proof_state = 'pending' and consumed_at is null and expires_at > now()),
+  16,
+  'sixteen challenges issue below the cap and are all pending');
+
+-- Remember which row is the oldest before the 17th arrives.
+create temporary table pcap_state as
+select (select id from agent_board.agent_signing_key_challenges
+         where agent_id = '00000000-0000-0000-0000-0000000000c1'
+           and proof_state = 'pending' and consumed_at is null
+         order by created_at, id limit 1) as oldest_id,
+       null::uuid as seventeenth_id,
+       null::uuid as next_oldest_id,
+       null::uuid as victim_id,
+       null::text as lapse_note;
+
+-- 2. The 17th request is SERVED, not refused. This is the assertion that inverts.
+do $$
+declare
+  v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
+  v_id uuid;
+begin
+  set local role service_role;
+  begin
+    select c.challenge_id into v_id
+      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes') c;
+  exception when others then
+    -- Trapped, never re-raised: a bare call to a raising RPC aborts the whole
+    -- transaction, and pgTAP then emits NO `not ok` -- only a short assertion count
+    -- (AGENTS.md rule 3). Leaving the id null makes the assertion below fail BY NAME.
+    v_id := null;
+  end;
+  reset role;
+  update pcap_state set seventeenth_id = v_id;
+end
+$$;
+reset role;
+
+select isnt(
+  (select seventeenth_id from pcap_state), null,
+  'the 17th request at the cap is served, not refused (challenge_pending_cap is not raised)');
+
+-- 3. The resource bound the cap exists for is still held.
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and proof_state = 'pending' and consumed_at is null and expires_at > now()),
+  16,
+  'the per-key pending bound is still 16 after the 17th issues');
+
+-- 4-7. The evicted row is the OLDEST one, closed out in the shape the
+-- consumed-shape CHECK requires, and it names what superseded it.
+select is(
+  (select proof_state from agent_board.agent_signing_key_challenges
+    where id = (select oldest_id from pcap_state)),
+  'expired',
+  'the oldest pending challenge is closed out as expired');
+select ok(
+  (select consumed_at is not null from agent_board.agent_signing_key_challenges
+    where id = (select oldest_id from pcap_state)),
+  'the superseded row carries consumed_at (agent_signing_key_challenges_consumed_shape)');
+-- `ok(a = b)`, NOT `is(a, b)`. pgTAP's `is` is IS NOT DISTINCT FROM, so under the
+-- revert-supersede mutation — where nothing is evicted and nothing is issued, leaving
+-- BOTH sides null — `is(null, null)` PASSES. This assertion was cited in the PR as one of
+-- the nine that mutation fails, and it was in fact vacuous there: a probe that scores
+-- 0-vs-0 and reads as agreement. `=` yields NULL when either side is null, and pgTAP
+-- fails a NULL result, so the null case now reads `not ok`.
+select ok(
+  (select (metadata->>'superseded_by')::uuid from agent_board.agent_signing_key_challenges
+    where id = (select oldest_id from pcap_state))
+    = (select seventeenth_id from pcap_state),
+  'the superseded row names the challenge that superseded it');
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and metadata ? 'superseded_by'),
+  1,
+  'exactly one row was evicted -- the oldest, and only the oldest');
 
+-- 8. A second request at the cap takes the NEXT-oldest, not the same row twice and
+-- not an arbitrary one.
+do $$
+declare
+  v_next uuid;
+  v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
+begin
+  select id into v_next from agent_board.agent_signing_key_challenges
+   where agent_id = v_agent and proof_state = 'pending' and consumed_at is null
+   order by created_at, id limit 1;
+  update pcap_state set next_oldest_id = v_next;
+  set local role service_role;
   begin
-    perform *
-      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
-    raise exception 'the 17th pending challenge was NOT rejected by the cap';
-  exception
-    when others then
-      if sqlerrm !~ 'challenge_pending_cap' then
-        raise;
-      end if;
+    perform * from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+  exception when others then
+    null;
   end;
+  reset role;
 end
 $$;
 reset role;
 
-select pass('16 pending challenges issue below the cap');
-select pass('the 17th concurrently-pending challenge is rejected (challenge_pending_cap)');
+select is(
+  (select proof_state from agent_board.agent_signing_key_challenges
+    where id = (select next_oldest_id from pcap_state)),
+  'expired',
+  'a second request at the cap evicts the NEXT-oldest row, not the same one twice');
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and metadata ? 'superseded_by'),
+  2,
+  'a second request at the cap evicts one row, not several');
+
+-- 9-10. An eviction is reported as an eviction, NOT as a replay. A client may retry
+-- challenge_superseded; it must never learn to retry nonce_replay, so the two must not
+-- share a message.
+select throws_matching(
+  $q$ select agent_board.mint_fleet_agent_session(
+        (select oldest_id from pcap_state),
+        (select challenge_nonce from agent_board.agent_signing_key_challenges
+          where id = (select oldest_id from pcap_state)),
+        (select id from agent_board.agent_signing_keys
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'),
+        '00000000-0000-0000-0000-0000000000c1'::uuid,
+        900) $q$,
+  'challenge_superseded',
+  'minting a superseded challenge raises challenge_superseded');
+
+-- A genuinely CONSUMED challenge still raises nonce_replay: the new branch narrowed
+-- nothing. Consume one of the still-pending rows by hand and mint it.
+update agent_board.agent_signing_key_challenges
+   set proof_state = 'consumed', consumed_at = now()
+ where id = (select id from agent_board.agent_signing_key_challenges
+              where agent_id = '00000000-0000-0000-0000-0000000000c1'
+                and proof_state = 'pending' and consumed_at is null
+              order by created_at desc, id limit 1);
+
+select throws_matching(
+  $q$ select agent_board.mint_fleet_agent_session(
+        (select id from agent_board.agent_signing_key_challenges
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'
+            and proof_state = 'consumed' and not (metadata ? 'superseded_by')
+          order by consumed_at desc limit 1),
+        (select challenge_nonce from agent_board.agent_signing_key_challenges
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'
+            and proof_state = 'consumed' and not (metadata ? 'superseded_by')
+          order by consumed_at desc limit 1),
+        (select id from agent_board.agent_signing_keys
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'),
+        '00000000-0000-0000-0000-0000000000c1'::uuid,
+        900) $q$,
+  'nonce_replay',
+  'a genuinely consumed challenge still raises nonce_replay, not challenge_superseded');
 
--- Expire one pending challenge (as owner), then a new challenge succeeds: expired
--- rows do not count toward the cap.
+-- 11-12. An EXPIRED-by-lapse pending row frees a slot without being evicted: expiry
+-- and eviction remain different things, and expiry still costs no one their challenge.
 update agent_board.agent_signing_key_challenges
    set expires_at = now() - interval '1 minute'
- where id = (
-   select id from agent_board.agent_signing_key_challenges
-    where agent_id = '00000000-0000-0000-0000-0000000000c1'
-      and proof_state = 'pending'
-    order by created_at
-    limit 1);
+ where id = (select id from agent_board.agent_signing_key_challenges
+              where agent_id = '00000000-0000-0000-0000-0000000000c1'
+                and proof_state = 'pending' and consumed_at is null
+              order by created_at desc, id limit 1);
 
 do $$
 declare
   v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
-  v_c record;
+  v_note text;
+begin
+  set local role service_role;
+  begin
+    perform * from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+    v_note := 'issued';
+  exception when others then
+    v_note := sqlerrm;
+  end;
+  -- The pcap_state write happens as the OWNER: service_role has no privilege on a
+  -- temp table created by the session user, and a permission error here would abort
+  -- the transaction exactly as an untrapped raise would.
+  reset role;
+  update pcap_state set lapse_note = v_note;
+end
+$$;
+reset role;
+
+select is(
+  (select lapse_note from pcap_state), 'issued',
+  'a lapsed pending row frees a slot, so the next request issues rather than raising');
+
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and metadata ? 'superseded_by'),
+  2,
+  'a lapsed pending row frees a slot with NO eviction (still 2 superseded)');
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and proof_state = 'pending' and consumed_at is null and expires_at > now()),
+  15,
+  'the pending set never exceeds the bound across evictions and lapses');
+
+-- 13. The grant surface is unchanged by the create-or-replace.
+select is(
+  (select array_agg(g order by g)
+     from unnest(array['anon', 'authenticated', 'service_role']) g
+    where has_function_privilege(
+      g, 'agent_board.issue_signing_key_challenge(uuid,text,interval)', 'execute')),
+  array['authenticated', 'service_role'],
+  'issue_signing_key_challenge stays authenticated + service_role, never anon');
+
+-- 14. THE DEADLOCK-FREEDOM CLAUSE, pinned positively.
+--
+-- The eviction writes agent_signing_key_challenges while this function holds the
+-- agent_signing_keys row; mint_fleet_agent_session takes that pair in the opposite
+-- order (challenge row FOR UPDATE at 20260718000600:73-76, key row FOR UPDATE at
+-- :95-100). `for update skip locked` is what keeps that from being a live ABBA:
+-- an issuer that never waits on a challenge row cannot close the cycle.
+--
+-- agent_board_fk_lock_edges.test.sql FKL-10 reports the PAIR (its detector is a
+-- static scan and cannot see a SKIP LOCKED, so the pair is listed there as known),
+-- which means removing this clause would fail NOTHING there. This is the named
+-- assertion that removing it fails. Read over stripped_body(), which removes
+-- comments and literals in one pass, so the prose above cannot satisfy the match --
+-- a comment satisfying a body scan is how a prior class assertion in this repo went
+-- green over an inverted lock.
+--
+-- A source scan has a floor, and this one is bounded rather than trusted: the
+-- BEHAVIOUR (an issuer skipping a mint-held row instead of waiting) is proved across
+-- two real sessions by tests/isolation/specs/challenge_supersede_lock_order.spec.
+-- Neither check covers the other -- a scan cannot observe a wait, and the golden
+-- cannot tell you which function the clause is missing from.
+select matches(
+  (select agent_board_test.stripped_body(
+            'agent_board.issue_signing_key_challenge(uuid,text,interval)'::regprocedure)),
+  'for\s+update\s+skip\s+locked',
+  'the eviction selects its victim FOR UPDATE SKIP LOCKED (no wait => no ABBA with mint_fleet_agent_session)');
+
+-- 19-20. THE RESIDUAL, PINNED RATHER THAN LEFT IN PROSE.
+--
+-- What this change closes is the HOLDABLE lockout: filling a key's sixteen slots and
+-- walking away no longer denies anything, because arrival is never refused. What it does
+-- NOT close is eviction under a SUSTAINED flood. A challenge issued now is the NEWEST, so
+-- it survives fifteen further issues and is evicted by the sixteenth -- and there is no
+-- per-key aggregate bound on how fast those sixteen arrive, because a per-key aggregate
+-- bound is exactly the holdable lever this change removed. Per source it is bounded by the
+-- `session:` rate cap; across N sources the sixteen land in 1/N of that time.
+--
+-- So a minter whose issue->mint gap exceeds the flood's rotation period loses its
+-- challenge, for as long as the flood runs. That is DoS-class -- it costs the attacker
+-- continuous traffic and stores nothing -- and it is a real residual, recorded here as an
+-- assertion instead of a sentence because a sentence is not re-checked (rule 5).
+--
+-- NOT A DUPLICATE OF #12. That one mints a row which was ALREADY the oldest of sixteen and
+-- was evicted by ONE further issue. This one starts from a challenge that is the NEWEST of
+-- its key and shows the whole queue rotating past it -- the property under discussion is
+-- that a LIVE minter can be rotated out, which #12's setup cannot exhibit.
+--
+-- The count is load-bearing and was measured, not assumed: with fifteen further issues
+-- both assertions below FAIL (the victim survives). Sixteen is the number.
+do $$
+declare
+  v_agent uuid := '00000000-0000-0000-0000-0000000000c2';
+  v_victim uuid;
+  v_i int;
 begin
+  insert into agent_board.agents(id, agent_type, handle, display_name)
+  values (v_agent, 'agent', 'pcap-victim', 'PCAP Victim');
+  -- active + proven deliberately: mint checks the key AFTER the superseded branch, so an
+  -- inactive key would let assertion 20 pass on `key_revoked` instead of on the property.
+  insert into agent_board.agent_signing_keys(
+    agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values (
+    v_agent, 'primary', 1, public.test_pubkey('pcap-victim'), 'raw_ed25519_base64url',
+    public.test_key_fingerprint('pcap-victim'), 'active', 'proven');
+
   set local role service_role;
-  select * into v_c
-    from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
-  if v_c.challenge_id is null then
-    raise exception 'a new challenge was rejected even though an expired row freed a slot';
-  end if;
+  -- The victim obtains a challenge, exactly as a legitimate agent would.
+  begin
+    select c.challenge_id into v_victim
+      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes') c;
+  exception when others then
+    v_victim := null;   -- trapped: an untrapped raise kills the file (see the header)
+  end;
+  reset role;
+
+  -- Back-date the victim so "oldest" is unambiguous. `now()` is TRANSACTION start time, so
+  -- every row this pgTAP transaction inserts shares one created_at and the eviction's
+  -- `order by created_at, id` degenerates to uuid order -- which made the first version of
+  -- this block evict a random row and fail for a reason that had nothing to do with the
+  -- property. In production each issue is its own transaction and now() advances, so this
+  -- back-date restores the real ordering rather than inventing one. Owner-only UPDATE,
+  -- hence the reset above.
+  update agent_board.agent_signing_key_challenges
+     set created_at = now() - interval '1 hour'
+   where id = v_victim;
+
+  set local role service_role;
+  -- Sixteen further issues for the SAME key. The 16th finds the set full and evicts the
+  -- oldest, which by then is the victim's.
+  for v_i in 1..16 loop
+    begin
+      perform * from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+    exception when others then
+      null;
+    end;
+  end loop;
+  reset role;
+
+  update pcap_state set victim_id = v_victim;
 end
 $$;
 reset role;
 
-select pass('an expired pending challenge frees a slot under the cap');
+select is(
+  (select proof_state from agent_board.agent_signing_key_challenges
+    where id = (select victim_id from pcap_state)),
+  'expired',
+  'RESIDUAL: a live challenge is rotated out by sixteen later issues for the same key');
+
+select throws_matching(
+  $q$ select agent_board.mint_fleet_agent_session(
+        (select victim_id from pcap_state),
+        (select challenge_nonce from agent_board.agent_signing_key_challenges
+          where id = (select victim_id from pcap_state)),
+        (select id from agent_board.agent_signing_keys
+          where agent_id = '00000000-0000-0000-0000-0000000000c2'),
+        '00000000-0000-0000-0000-0000000000c2'::uuid,
+        900) $q$,
+  'challenge_superseded',
+  'RESIDUAL: that victim''s mint then fails -- a sustained flood evicts a slow minter (DoS-class, retryable, not a stored lockout)');
 
 select finish();