@consiliency/agent-board-schema 1.24.0 → 1.27.0

package/tests/agent_board_signed_authority_provenance.test.sql

@@ -0,0 +1,477 @@
+-- #247 pgTAP: signed provenance for the two authority-granting writes.
+--
+-- The claim under test: `grant_board_role` and `set_board_authority_ceiling` can now be
+-- performed through a signed-write gateway that records a `signature_evidence` row, and the
+-- principal that row names is the one the write was actually AUTHORIZED as -- never a
+-- caller-supplied argument.
+--
+-- Methodology:
+--   * RPC probes are driven by the JWT claim blob only. SET LOCAL ROLE is never used: it
+--     would revoke _is_service_role() and mask the gateway branch behind a permission error
+--     on the function itself (same reason as agent_board_consent_emission).
+--   * Allow-side probes are lives_ok(...) followed by a SEPARATE state check. A bare
+--     `select ... from <raising rpc>(...)` aborts the transaction instead of failing, which
+--     would silently drop every later assertion (#113).
+--   * The payload deliberately names a DIFFERENT grantor than the gateway decision in the
+--     anti-forge cases. If provenance were keyed off the payload rather than the gateway's
+--     verified actor, those assertions flip.
+--   * The classification tripwires at the end are catalog-derived (pg_proc.proargnames),
+--     not a list written here: if a p_metadata parameter is ever added to one of the three
+--     RPCs classified as unable to carry client-side signing evidence, the assertion fails
+--     and NAMES the member, forcing reclassification rather than leaving the client-side
+--     exclusion silently stale.
+
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(40);
+
+create function pg_temp.claims(p_sub text) returns void language plpgsql as $$
+begin
+  perform set_config('request.jwt.claims', json_build_object('role','authenticated','sub',p_sub)::text, true);
+end $$;
+create function pg_temp.service() returns void language plpgsql as $$
+begin
+  perform set_config('request.jwt.claims', '', true);
+end $$;
+
+-- Fixture -------------------------------------------------------------------
+-- owner    = agent 1 (board owner, and the signer the gateway verifies)
+-- grantee  = agent 2 (an active member whose role the owner raises)
+-- outsider = agent 3 (a member with NO authority; the forged grantor in the M7 probes)
+
+insert into auth.users(id, instance_id, aud, role, email)
+select ('24700000-0000-0000-0000-' || lpad(n::text,12,'0'))::uuid,
+       '00000000-0000-0000-0000-000000000000', 'authenticated', 'authenticated',
+       'k247u'||n||'@t.test'
+from generate_series(1,3) n;
+
+insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id)
+select ('24710000-0000-4000-8000-' || lpad(n::text,12,'0'))::uuid,
+       'agent','agent','k247-agent-'||n,'K247 Agent '||n,'active',
+       ('24700000-0000-0000-0000-' || lpad(n::text,12,'0'))::uuid
+from generate_series(1,3) n;
+
+insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+values ('24720000-0000-4000-8000-000000000001','k247-board','K247 Board',
+        '24710000-0000-4000-8000-000000000001'::uuid, 'private','active');
+
+insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+values
+  ('24720000-0000-4000-8000-000000000001','24710000-0000-4000-8000-000000000001','owner','joined','24710000-0000-4000-8000-000000000001'),
+  ('24720000-0000-4000-8000-000000000001','24710000-0000-4000-8000-000000000002','member','joined','24710000-0000-4000-8000-000000000001'),
+  ('24720000-0000-4000-8000-000000000001','24710000-0000-4000-8000-000000000003','member','joined','24710000-0000-4000-8000-000000000001');
+
+insert into agent_board.agent_signing_keys(
+  id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+values (
+  '24730000-0000-4000-8000-000000000001',
+  '24710000-0000-4000-8000-000000000001',
+  'primary', 1,
+  public.test_pubkey('k247-primary'), 'raw_ed25519_base64url',
+  public.test_key_fingerprint('k247-primary'), 'active', 'proven');
+
+-- The gateway decision the wrappers are called with. `agent_id` is the VERIFIED signer.
+create function pg_temp.gw(p_actor text) returns jsonb language sql immutable as $$
+  select jsonb_build_object(
+    'agent_id', p_actor,
+    'signing_key_id', '24730000-0000-4000-8000-000000000001',
+    'key_id', 'primary',
+    'key_version', 1,
+    'algorithm', 'Ed25519',
+    'verification_status', 'verified',
+    'payload_digest', 'sha256:' || repeat('a', 64),
+    'signature_digest', 'sha256:' || repeat('b', 64),
+    'canonicalization_version', 'agent-provenance-jcs.v1',
+    'enforcement_mode', 'require_for_agent_writes',
+    'redacted', true);
+$$;
+
+-- ===========================================================================
+-- 1. The surface exists, and the DROP did not leave the ACL or COMMENT behind.
+--    (DROP FUNCTION discards both; a recreated SECURITY DEFINER function grants
+--    EXECUTE to PUBLIC by default. That hole opened for real in this repo once.)
+-- ===========================================================================
+
+select has_function('agent_board', 'signed_grant_board_role', array['jsonb','jsonb'],
+  'signed_grant_board_role wrapper exists');
+select has_function('agent_board', 'signed_set_board_authority_ceiling', array['jsonb','jsonb'],
+  'signed_set_board_authority_ceiling wrapper exists');
+select has_function('agent_board', 'set_board_authority_ceiling', array['uuid','text','uuid'],
+  'the ceiling setter carries the delegable actor parameter');
+
+select is(
+  (select string_agg(distinct coalesce(pg_get_userbyid(nullif(a.grantee,0)),'PUBLIC'), ','
+            order by coalesce(pg_get_userbyid(nullif(a.grantee,0)),'PUBLIC'))
+     from pg_proc p, aclexplode(p.proacl) a
+    where p.oid = 'agent_board.signed_grant_board_role(jsonb,jsonb)'::regprocedure
+      and a.privilege_type = 'EXECUTE'),
+  'postgres,service_role',
+  'signed_grant_board_role executes for service_role only (never PUBLIC/anon/authenticated)');
+
+select is(
+  (select string_agg(distinct coalesce(pg_get_userbyid(nullif(a.grantee,0)),'PUBLIC'), ','
+            order by coalesce(pg_get_userbyid(nullif(a.grantee,0)),'PUBLIC'))
+     from pg_proc p, aclexplode(p.proacl) a
+    where p.oid = 'agent_board.signed_set_board_authority_ceiling(jsonb,jsonb)'::regprocedure
+      and a.privilege_type = 'EXECUTE'),
+  'postgres,service_role',
+  'signed_set_board_authority_ceiling executes for service_role only');
+
+select is(
+  (select string_agg(distinct coalesce(pg_get_userbyid(nullif(a.grantee,0)),'PUBLIC'), ','
+            order by coalesce(pg_get_userbyid(nullif(a.grantee,0)),'PUBLIC'))
+     from pg_proc p, aclexplode(p.proacl) a
+    where p.oid = 'agent_board.set_board_authority_ceiling(uuid,text,uuid)'::regprocedure
+      and a.privilege_type = 'EXECUTE'),
+  'authenticated,postgres,service_role',
+  'the recreated ceiling setter restated its grants and did NOT keep PUBLIC EXECUTE');
+
+select isnt(
+  (select obj_description('agent_board.set_board_authority_ceiling(uuid,text,uuid)'::regprocedure, 'pg_proc')),
+  null,
+  'the recreated ceiling setter restated its COMMENT (DROP FUNCTION discards it)');
+
+select ok(
+  strpos(lower(agent_board_test.stripped_body('agent_board.set_board_authority_ceiling(uuid,text,uuid)'::regprocedure)),
+         'perform agent_board._lock_board_authority_ceiling(p_board_id)') > 0
+  and strpos(lower(agent_board_test.stripped_body('agent_board.set_board_authority_ceiling(uuid,text,uuid)'::regprocedure)),
+         'perform agent_board._lock_board_authority_ceiling(p_board_id)')
+    < strpos(lower(agent_board_test.stripped_body('agent_board.set_board_authority_ceiling(uuid,text,uuid)'::regprocedure)),
+         'insert into agent_board.board_authority_ceilings'),
+  'the recreated setter still takes the advisory lock before its gate and upsert');
+
+-- ===========================================================================
+-- 2. D4 -- the new parameter changes NO existing unsigned call.
+-- ===========================================================================
+
+select pg_temp.claims('24700000-0000-0000-0000-000000000001');
+
+select lives_ok(
+  $$select * from agent_board.set_board_authority_ceiling(
+      '24720000-0000-4000-8000-000000000001'::uuid, 'admin')$$,
+  'D4: the pre-#247 two-argument call by an authenticated owner still succeeds');
+
+select is(
+  (select max_grantable_role from agent_board.board_authority_ceilings
+    where board_id = '24720000-0000-4000-8000-000000000001'),
+  'admin',
+  'D4: and it wrote the ceiling it was asked for');
+
+select pg_temp.claims('24700000-0000-0000-0000-000000000003');
+
+select throws_like(
+  $$select * from agent_board.set_board_authority_ceiling(
+      '24720000-0000-4000-8000-000000000001'::uuid, 'owner')$$,
+  '%only a board owner%',
+  'D4: a non-owner is still refused by the owner gate, with the same message');
+
+-- The new parameter cannot be used to act as someone else while authenticated.
+select throws_like(
+  $$select * from agent_board.set_board_authority_ceiling(
+      '24720000-0000-4000-8000-000000000001'::uuid, 'owner',
+      '24710000-0000-4000-8000-000000000001'::uuid)$$,
+  '%must match current_agent_id()%',
+  'an authenticated caller cannot borrow another agent as p_actor_agent_id');
+
+-- ===========================================================================
+-- 3. signed_grant_board_role -- the write happens AND leaves evidence.
+-- ===========================================================================
+
+select pg_temp.service();
+
+select lives_ok(
+  $$select * from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_agent_id', '24710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000001'))$$,
+  'a signed grant by the verified board owner succeeds');
+
+select is(
+  (select role from agent_board.board_memberships
+    where board_id = '24720000-0000-4000-8000-000000000001'
+      and agent_id = '24710000-0000-4000-8000-000000000002'),
+  'admin',
+  'the signed grant actually raised the grantee role');
+
+select is(
+  (select count(*)::int from agent_board.signature_evidence
+    where operation = 'grant_board_role'),
+  1,
+  'the signed grant recorded exactly one signature_evidence row');
+
+select is(
+  (select agent_id from agent_board.signature_evidence where operation = 'grant_board_role'),
+  '24710000-0000-4000-8000-000000000001'::uuid,
+  'M7: the evidence row names the GATEWAY-VERIFIED grantor');
+
+select is(
+  (select verification_status from agent_board.signature_evidence where operation = 'grant_board_role'),
+  'verified',
+  'the evidence row carries the gateway verification status');
+
+select is(
+  (select external_evidence_ref from agent_board.signature_evidence where operation = 'grant_board_role'),
+  'board-authority:grant_board_role:24720000-0000-4000-8000-000000000001:24710000-0000-4000-8000-000000000002',
+  'the evidence ref is derived server-side from the board and grantee');
+
+-- The source-shape CHECK is asserted, not inferred from the insert having succeeded.
+select ok(
+  (select source_kind = 'external'
+            and source_message_id is null
+            and source_task_event_id is null
+            and source_artifact_id is null
+            and source_delivery_recipient_id is null
+            and external_evidence_ref is not null
+     from agent_board.signature_evidence where operation = 'grant_board_role'),
+  'the authority evidence row satisfies the external source shape the CHECK requires');
+
+-- ===========================================================================
+-- 4. M7 -- a caller-supplied grantor can never become the recorded principal.
+-- ===========================================================================
+
+select throws_like(
+  $$select * from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_agent_id', '24710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'owner',
+        'p_grantor_agent_id', '24710000-0000-4000-8000-000000000003'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000001'))$$,
+  '%actor_mismatch%',
+  'M7: a payload grantor that differs from the verified signer is refused outright');
+
+select is(
+  (select count(*)::int from agent_board.signature_evidence where operation = 'grant_board_role'),
+  1,
+  'M7: and the refused forge attempt recorded no second evidence row');
+
+select is(
+  (select role from agent_board.board_memberships
+    where board_id = '24720000-0000-4000-8000-000000000001'
+      and agent_id = '24710000-0000-4000-8000-000000000002'),
+  'admin',
+  'M7: and the refused forge attempt did not raise the grantee to owner');
+
+-- The DIVERGENCE case, which is the one M7 is really about. Above, the forged grantor had
+-- no authority, so a mutation that trusted the payload would still be stopped by the
+-- ceiling gate -- the damage would be caught downstream, not by provenance. Here the forged
+-- grantor is the OWNER and the verified signer is a mere member: a wrapper that took the
+-- grantor from the payload would perform a grant AUTHORIZED AS THE OWNER while
+-- _record_signed_write_evidence (which reads only the gateway actor) recorded it against
+-- the member. That row would be evidence naming a principal who did not authorize the
+-- write, which is worse than no row at all.
+select throws_like(
+  $$select * from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_agent_id', '24710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin',
+        'p_grantor_agent_id', '24710000-0000-4000-8000-000000000001'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000003'))$$,
+  '%actor_mismatch%',
+  'M7: a payload grantor with MORE authority than the verified signer is refused');
+
+select is(
+  (select count(*)::int from agent_board.signature_evidence where operation = 'grant_board_role'),
+  1,
+  'M7: the divergence attempt recorded no evidence row naming the wrong principal');
+
+-- The wrapper adds no authority: an unprivileged verified signer is still refused,
+-- by the SAME gates the unsigned function applies.
+select throws_like(
+  $$select * from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_agent_id', '24710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'owner'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000003'))$$,
+  '%exceeds grantor role or board authority ceiling%',
+  'the wrapper grants no authority: a member signer still cannot mint an owner');
+
+-- This probe named a 'failed' verification but carried NO agent_id, so it was refused for
+-- ACTOR ABSENCE and never once exercised the failed status -- a description claiming what no
+-- assertion backed. It is now two probes, each refused for the reason it names.
+select throws_like(
+  $$select * from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_agent_id', '24710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin'),
+      jsonb_build_object('verification_status','failed'))$$,
+  '%actor_mismatch%',
+  'a gateway decision naming no actor cannot write evidence at all');
+
+-- The status probe proper: the SAME decision the allow-side probes use -- verified signer,
+-- live key, an owner granting a role the inner gates permit -- with only verification_status
+-- flipped to 'failed'. Without the #269 verification check this grant COMPLETES and mints an
+-- evidence row recording 'failed' beside a mutation that succeeded.
+select throws_like(
+  $$select * from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_agent_id', '24710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000001')
+        || jsonb_build_object('verification_status','failed'))$$,
+  '%signer_not_verified%',
+  'a FAILED verification is refused for its STATUS, by a signer who is otherwise fully entitled');
+
+select is(
+  (select count(*)::int from agent_board.signature_evidence where operation = 'grant_board_role'),
+  1,
+  'and the failed-verification attempt minted no evidence row');
+
+-- ===========================================================================
+-- 5. signed_set_board_authority_ceiling.
+-- ===========================================================================
+
+select lives_ok(
+  $$select * from agent_board.signed_set_board_authority_ceiling(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_max_grantable_role', 'member'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000001'))$$,
+  'a signed ceiling change by the verified board owner succeeds');
+
+select is(
+  (select max_grantable_role from agent_board.board_authority_ceilings
+    where board_id = '24720000-0000-4000-8000-000000000001'),
+  'member',
+  'the signed ceiling change actually wrote the ceiling');
+
+select is(
+  (select agent_id from agent_board.signature_evidence
+    where operation = 'set_board_authority_ceiling'),
+  '24710000-0000-4000-8000-000000000001'::uuid,
+  'M7: the ceiling evidence row names the gateway-verified actor');
+
+select throws_like(
+  $$select * from agent_board.signed_set_board_authority_ceiling(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_max_grantable_role', 'owner'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000003'))$$,
+  '%only a board owner%',
+  'the ceiling wrapper grants no authority: a non-owner signer is still refused');
+
+select is(
+  (select count(*)::int from agent_board.signature_evidence
+    where operation = 'set_board_authority_ceiling'),
+  1,
+  'and the refused ceiling change recorded no evidence row');
+
+-- ===========================================================================
+-- 6. Classification tripwires (catalog-derived, CLAUDE.md rule 1).
+--
+--    The client classifies these three as unable to carry client-side signing
+--    evidence BECAUSE they declare no p_metadata parameter -- the client's
+--    attachSigningMetadata merges into p_metadata and nowhere else. That reason is
+--    asserted here positively and from pg_catalog. If a p_metadata parameter is ever
+--    added to one of them, this fails and names it, forcing the client-side
+--    classification to be revisited instead of going quietly stale.
+--
+--    WHERE THE CONVERSE CLASS IS ASSERTED -- not here, and pointing at it rather than
+--    leaving the gap this note used to record. "Every RPC the client signs into p_metadata
+--    declares that parameter" was FALSE for nine of the thirty-nine (append_task_event,
+--    delete_callback_endpoint, mark_read, raise_conflict, raise_escalation, release_claim,
+--    renew_claim, resolve_conflict, resolve_escalation -- all inherited from the pre-#247
+--    hand-written signed set), which is why it could not be written green when this file
+--    was authored. message-board#261 reclassified all nine and pinned the class:
+--    scripts/build-p-metadata-snapshot.mjs derives EVERY agent_board function from
+--    pg_catalog with no name filter, each with a declares_p_metadata boolean, into
+--    tests/catalog/p_metadata_parameters.json; `--check`s it against a live database in the
+--    same CI job that runs this suite; and the client's projection test asserts that every
+--    OVERLOAD of every signed RPC declares the parameter, naming any signature that does
+--    not. The class is pinned on the CLIENT side because that is where the signed set
+--    lives; this section stays the catalog-side tripwire for the three RPCs #247
+--    adjudicated.
+-- ===========================================================================
+
+select is(
+  (select string_agg(p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')', '; '
+            order by p.proname)
+     from pg_proc p
+     join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board'
+      and p.proname in ('grant_board_role','set_board_authority_ceiling','set_board_role_gate')
+      and not ('p_metadata' = any(coalesce(p.proargnames, array[]::text[])))),
+  'grant_board_role(p_board_id uuid, p_agent_id uuid, p_grantee_role text, p_grantor_agent_id uuid); '
+  || 'set_board_authority_ceiling(p_board_id uuid, p_max_grantable_role text, p_actor_agent_id uuid); '
+  || 'set_board_role_gate(p_board_id uuid, p_enforced boolean)',
+  'the three authority RPCs that cannot carry p_metadata.signed_write are exactly these, with these signatures');
+
+select is(
+  (select count(*)::int
+     from pg_proc p
+     join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board'
+      and p.proname in ('grant_board_role','set_board_authority_ceiling','set_board_role_gate')
+      and 'p_metadata' = any(coalesce(p.proargnames, array[]::text[]))),
+  0,
+  'none of the three has acquired a p_metadata parameter');
+
+select is(
+  (select string_agg(distinct p.proname, ',' order by p.proname)
+     from pg_proc p
+     join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board'
+      and p.proname in ('create_invite_link','create_fleet_onboarding_invite','create_or_find_thread')
+      and 'p_metadata' = any(coalesce(p.proargnames, array[]::text[]))),
+  'create_fleet_onboarding_invite,create_invite_link,create_or_find_thread',
+  -- NOT "the RPCs the client signs": create_or_find_thread is in this set and the client
+  -- classifies it unsigned-deliberate, and the client signs 39 RPCs, not three. The set is
+  -- exactly the three whose p_metadata premise #247 adjudicated -- two it now signs, one it
+  -- deliberately does not -- so the label states the set it actually queries. The wider
+  -- claim this once implied ("every signed RPC declares p_metadata") is NOT asserted here
+  -- and must not be read out of it; see the note above section 6.
+  'the three RPCs #247 adjudicated that declare p_metadata are exactly these');
+
+-- create_or_find_thread is classified unsigned-deliberate on the strength of being
+-- idempotent -- a key-collision returns the EXISTING thread rather than writing a new
+-- one. Asserted positively rather than left as an unexplained exclusion.
+--
+-- Driven through lives_ok + a captured result, NOT a bare `is((select ... from rpc(...)))`.
+-- create_or_find_thread is an ADMISSION rpc: the bare form ABORTS the transaction on a
+-- raise instead of failing it, and pgTAP then emits no `not ok` at all while the remaining
+-- assertions silently never run (#113, CLAUDE.md rule 3). The runner's lint did not flag
+-- the bare form here only because its MUT_RPCS list did not name this function; that list
+-- is corrected in the same change, so the next admission rpc used this way is caught by the
+-- lint rather than by a reviewer.
+create temporary table k247_idem(
+  seq int generated always as identity,
+  thread_id uuid,
+  reused boolean
+) on commit drop;
+
+select lives_ok($$
+  insert into k247_idem(thread_id, reused)
+  select thread_id, reused
+    from agent_board.create_or_find_thread(
+      '24710000-0000-4000-8000-000000000001'::uuid, 'K247 idem', 'k247-idem-key')
+$$, 'create_or_find_thread admits the first call for the key');
+
+select lives_ok($$
+  insert into k247_idem(thread_id, reused)
+  select thread_id, reused
+    from agent_board.create_or_find_thread(
+      '24710000-0000-4000-8000-000000000001'::uuid, 'K247 idem', 'k247-idem-key')
+$$, 'and admits an identical second call rather than raising');
+
+select is(
+  (select count(distinct thread_id)::int from k247_idem),
+  1,
+  'create_or_find_thread is idempotent on its key -- the stated reason it is deliberately unsigned');
+
+select is(
+  (select reused from k247_idem order by seq desc limit 1),
+  true,
+  'and it reports the reuse rather than performing a second authority-free write');
+
+select finish();
+
+rollback;