@consiliency/agent-board-schema 1.40.0 → 1.42.0

package/tests/agent_board_board_claim_policy.test.sql

@@ -0,0 +1,228 @@
+-- Board-settable claim policy: a board may decline OUR lock, never grant itself ANOTHER OWNER'S
+-- resource.
+--
+-- THE ASK. A board's work may be coordinated by somebody else's locking — a repository lock, a
+-- scheduler lease, an external mutex. If their lock already granted the work, our TTL cap or quota
+-- rejecting the acquire is us breaking a system that was working. So the enforcement is opt-out
+-- and the board owner holds the switch.
+--
+-- BCP-6 IS THE ASSERTION THIS FILE EXISTS FOR. Everything else here checks that the opt-out
+-- works; BCP-6 checks that it does not work on the things it must never reach. `advisory` disables
+-- the OWNERLESS guards (file/tool/custom lease cap + per-agent quota) and must leave the
+-- fleet-authority gate on machine/repository/repo_file untouched — that gate answers "may this
+-- agent claim this resource at all", which is authorization, not a locking convenience.
+--
+-- Structurally that holds because the opt-out sits inside the `v_ownerless` branch and the fleet
+-- kinds are gated far above it. BCP-6 asserts it anyway: "it is in the right branch" is exactly
+-- the kind of reasoning that stops being true when someone moves a line, and this file would
+-- otherwise be a set of tests that only ever prove the permissive direction.
+--
+-- BCP-5 IS THE SECOND ONE THAT MATTERS. A claim reaches its board through its thread. So the
+-- obvious hole is a claim that simply omits the thread — if that inherited "no board, therefore no
+-- enforcement", any agent could opt itself out by passing null. It resolves to 'inherit' instead,
+-- and BCP-5 pins that the fleet-wide flags still govern.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(13);
+
+-- ---------------------------------------------------------------------------
+-- Fixture: one board with an owner and a non-owner member, a board-linked thread, and a
+-- thread with NO board (for BCP-5).
+-- ---------------------------------------------------------------------------
+create temp table _bcp (
+  board uuid, owner_agent uuid, owner_user uuid,
+  member_agent uuid, member_user uuid,
+  thread uuid, free_thread uuid
+) on commit drop;
+
+do $$
+declare
+  v_sfx text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_owner uuid := gen_random_uuid();
+  v_member uuid := gen_random_uuid();
+  v_owner_user uuid; v_member_user uuid;
+  v_board uuid; v_thread uuid := gen_random_uuid(); v_free uuid := gen_random_uuid();
+begin
+  v_owner_user  := public.ensure_github_user('bcp-own-' || v_sfx, 'bcp-own-' || v_sfx || '@example.test', 'bcp-own-' || v_sfx, 'BCP Owner');
+  v_member_user := public.ensure_github_user('bcp-mem-' || v_sfx, 'bcp-mem-' || v_sfx || '@example.test', 'bcp-mem-' || v_sfx, 'BCP Member');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_owner,  'agent', 'bcp-own-' || v_sfx, 'BCP Owner',  'active', v_owner_user,  v_owner_user),
+         (v_member, 'agent', 'bcp-mem-' || v_sfx, 'BCP Member', 'active', v_member_user, v_member_user);
+
+  -- create_board seeds the creator's owner membership (ROOMOWN).
+  perform set_config('request.jwt.claim.role', 'authenticated', true);
+  perform set_config('request.jwt.claim.sub', v_owner_user::text, true);
+  select board_id into v_board
+    from agent_board.create_board(v_owner, 'bcp-' || v_sfx, 'BCP Board', 'claim policy', '{}'::jsonb, 'private');
+
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values (v_board, v_member, 'joined', v_owner, 'member');
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values (v_thread, 'coordination', v_owner, 'BCP board thread', v_board),
+         (v_free,   'coordination', v_owner, 'BCP boardless thread', null);
+
+  insert into _bcp values (v_board, v_owner, v_owner_user, v_member, v_member_user, v_thread, v_free);
+end $$;
+
+-- The fleet-wide guards must be ON for any of the opt-out assertions to mean anything: with them
+-- off, everything succeeds and every permissive assertion below would pass vacuously.
+insert into agent_board.claimgate_enforcement_flags(scope_key, enabled)
+values ('ownerless_guards', true)
+on conflict (scope_key) do update set enabled = true;
+
+-- ---------------------------------------------------------------------------
+-- BCP-1..2: the column.
+-- ---------------------------------------------------------------------------
+select is(
+  (select claim_policy from agent_board.boards where id = (select board from _bcp)),
+  'inherit',
+  'BCP-1: a newly created board defaults to inherit, so this migration changes no existing behaviour');
+
+-- Scored by extracting the constraint's OWN literal list, not by checking that two known words
+-- appear in it. The weaker spelling passes against a vocabulary that also admits a third value --
+-- a review seat pointed out the first version of this assertion did exactly that.
+select is(
+  (select string_agg(m[1], ',' order by m[1])
+     from pg_constraint c,
+          lateral regexp_matches(pg_get_constraintdef(c.oid), '''([a-z-]+)''', 'g') m
+    where c.conrelid = 'agent_board.boards'::regclass
+      and c.conname = 'boards_claim_policy_check'),
+  'advisory,inherit',
+  'BCP-2: the vocabulary is EXACTLY inherit and advisory -- a third admitted value fails here');
+
+-- ---------------------------------------------------------------------------
+-- BCP-3..4: the opt-out, in both directions. Both use an over-cap lease, so the ONLY difference
+-- between them is the board policy.
+-- ---------------------------------------------------------------------------
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'advisory') $$,
+  'BCP-3a: a board owner may set advisory (lives_ok, so a raise fails HERE rather than aborting)');
+
+select lives_ok(
+  $$ select * from agent_board.acquire_claim(
+       (select owner_agent from _bcp), 'file', 'bcp-over-cap-advisory',
+       now() + interval '400 days', null, (select thread from _bcp)) $$,
+  'BCP-3b: with advisory, an OVER-CAP ownerless lease is allowed — their lock governs, not ours');
+
+do $$
+begin
+  perform agent_board.set_board_claim_policy((select board from _bcp), 'inherit');
+end $$;
+
+select throws_ok(
+  $$ select * from agent_board.acquire_claim(
+       (select owner_agent from _bcp), 'file', 'bcp-over-cap-inherit',
+       now() + interval '400 days', null, (select thread from _bcp)) $$,
+  '22023',
+  null,
+  'BCP-4: with inherit, the SAME over-cap lease is rejected — so BCP-3b is the policy working, not the guard being absent');
+
+-- ---------------------------------------------------------------------------
+-- BCP-5: no board means no opt-out. A claim that omits the thread must not inherit permissiveness.
+-- ---------------------------------------------------------------------------
+select throws_ok(
+  $$ select * from agent_board.acquire_claim(
+       (select owner_agent from _bcp), 'file', 'bcp-no-thread',
+       now() + interval '400 days', null, null) $$,
+  '22023',
+  null,
+  'BCP-5: a claim with NO thread cannot opt itself out by omission — it resolves to inherit and the fleet flags govern');
+
+select is(
+  agent_board._claimgate_board_claim_policy(null),
+  'inherit',
+  'BCP-5b: the resolver itself answers inherit for a null thread rather than NULL, so the comparison in acquire_claim can never be NULL-swallowed');
+
+select is(
+  agent_board._claimgate_board_claim_policy((select free_thread from _bcp)),
+  'inherit',
+  'BCP-5c: and inherit for a real thread that is not board-linked');
+
+-- ---------------------------------------------------------------------------
+-- BCP-6: THE SECURITY BOUNDARY. advisory must NOT reach the fleet-authority gate.
+--
+-- Scored from the catalog rather than by attempting a machine claim, because a behavioural probe
+-- here would need a full fleet-registration fixture and would prove only that ONE machine claim
+-- was refused. This asks the structural question instead: does the board policy appear anywhere
+-- the fleet kinds are decided? It must appear ONLY inside the ownerless branch.
+-- ---------------------------------------------------------------------------
+select is(
+  (select coalesce(string_agg(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 ('_can_claim_resource', '_claimgate_kind_enforced', '_claimgate_promotion_blockers')
+      and agent_board_test.stripped_body(p.oid, true) ~ '_claimgate_board_claim_policy'),
+  '',
+  'BCP-6 SECURITY: the board policy is reachable from NO fleet-authority function — a board may decline our lock, never grant itself another owner''s resource');
+
+-- ---------------------------------------------------------------------------
+-- BCP-7..8: who may set it. Mirrors set_board_role_gate's gate exactly.
+-- ---------------------------------------------------------------------------
+select throws_ok(
+  format($$ select set_config('request.jwt.claim.sub', %L, true);
+            select agent_board.set_board_claim_policy(%L, 'advisory') $$,
+         (select member_user from _bcp)::text, (select board from _bcp)::text),
+  '42501',
+  null,
+  'BCP-7: a non-owner MEMBER may not set the claim policy');
+
+select throws_ok(
+  format($$ select set_config('request.jwt.claims', '', true);
+            select set_config('request.jwt.claim.sub', '', true);
+            select set_config('request.jwt.claim.role', '', true);
+            select agent_board.set_board_claim_policy(%L, 'advisory') $$, (select board from _bcp)::text),
+  '42501',
+  null,
+  'BCP-8: an unresolved principal (service_role) is not an owner and is refused — same carve-out as set_board_role_gate');
+
+-- ---------------------------------------------------------------------------
+-- BCP-9: an unknown value is refused by the RPC with the vocabulary, not by the column CHECK with
+-- a constraint name. A caller asking for 'off' should be told what the options are.
+-- ---------------------------------------------------------------------------
+select throws_ok(
+  format($$ select set_config('request.jwt.claim.role', 'authenticated', true);
+            select set_config('request.jwt.claim.sub', %L, true);
+            select agent_board.set_board_claim_policy(%L, 'off') $$,
+         (select owner_user from _bcp)::text, (select board from _bcp)::text),
+  '22023',
+  null,
+  'BCP-9: an unknown policy is refused as a bad argument, naming the vocabulary — not as a raw CHECK violation');
+
+-- ---------------------------------------------------------------------------
+-- BCP-10: A FLEET-REVOKED OWNER IS STILL AN OWNER BY MEMBERSHIP. This function shipped its first
+-- version WITHOUT this check while its own commit message claimed to mirror set_board_role_gate
+-- "exactly" -- a review seat found it by reading both functions side by side instead of taking
+-- the claim. Fleet revocation deliberately leaves agents.status = 'active' (the ledger row is the
+-- only authority signal), so the membership test in BCP-7/8 passes for a revoked owner and cannot
+-- stand alone.
+--
+-- Disabling a board's claim enforcement is an authority write in the same class as flipping the
+-- role gate, so it owes the same post-UPDATE revocation assertion.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  -- revoke as an operator (service_role: no resolved actor)
+  perform set_config('request.jwt.claims', '', true);
+  perform set_config('request.jwt.claim.sub', '', true);
+  perform set_config('request.jwt.claim.role', '', true);
+  perform agent_board.revoke_fleet_subject(
+    'agent', (select owner_agent from _bcp), (select owner_agent from _bcp),
+    'BCP-10 revocation', '{}'::jsonb);
+end $$;
+
+select throws_ok(
+  format($$ select set_config('request.jwt.claim.role', 'authenticated', true);
+            select set_config('request.jwt.claim.sub', %L, true);
+            select agent_board.set_board_claim_policy(%L, 'advisory') $$,
+         (select owner_user from _bcp)::text, (select board from _bcp)::text),
+  '42501',
+  null,
+  'BCP-10: a FLEET-REVOKED owner may not disable claim enforcement, even though the board still lists them as owner and their agent row is still active');
+
+select * from finish();
+rollback;

package/tests/agent_board_ledger_authority.test.sql

@@ -539,12 +539,19 @@ select is(
         or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.board_memberships\M[^;]*\mset\M[^;]*\mrole\s*='
         or agent_board_test.stripped_body(p.oid) ~* '(insert\s+into|update)\s+agent_board\.board_authority_ceilings\M'
         or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mrole_gate_enforced\s*='
+        -- BOARDCLAIMPOLICY: boards.claim_policy is the same SHAPE of authority as
+        -- role_gate_enforced above -- a board-level switch deciding what a later gate does
+        -- (there the creator-identity exemption, here whether our ownerless claim guards apply
+        -- at all). Counting it as an authority write is what makes the pairing assertion below
+        -- hold, and is why set_board_claim_policy carries the ledger check.
+        or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mclaim_policy\s*='
         or agent_board_test.stripped_body(p.oid) ~* 'insert\s+into\s+agent_board\.board_invite_tokens\M')),
   '_fedsession_autojoin_default_board,_redeem_unbounded_invite_for_agent,'
   || '_upsert_board_membership_state,bootstrap_board_owner_memberships,create_board,'
-  || 'create_invite_link,grant_board_role,set_board_authority_ceiling,set_board_role_gate',
+  || 'create_invite_link,grant_board_role,set_board_authority_ceiling,set_board_claim_policy,'
+  || 'set_board_role_gate',
   'the functions that WRITE a board-authority relation — in ANY shape, including a mintable '
-  'invite preset_role — are exactly these nine');
+  'invite preset_role — are exactly these ten');
 
 -- EITHER helper counts as consulting the ledger: the invite redeem path calls the UNLOCKED
 -- predicate (see the migration header), so a side that matched only the share-locking assert
@@ -558,8 +565,8 @@ select is(
       and p.proname not in ('_assert_actor_not_fleet_revoked', '_actor_fleet_revoked')
       and agent_board_test.stripped_body(p.oid) ~ '\m(_assert_actor_not_fleet_revoked|_actor_fleet_revoked)\s*\('),
   '_redeem_unbounded_invite_for_agent,create_board,create_invite_link,grant_board_role,'
-  || 'set_board_authority_ceiling,set_board_role_gate',
-  'the functions that consult the fleet revocation ledger are exactly these six (#280 added '
+  || 'set_board_authority_ceiling,set_board_claim_policy,set_board_role_gate',
+  'the functions that consult the fleet revocation ledger are exactly these seven (#280 added '
   'create_board)');
 
 -- The gate proper: the two sets must differ by EXACTLY the three asserted exemptions, and any
@@ -588,6 +595,7 @@ select is(
              or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.board_memberships\M[^;]*\mset\M[^;]*\mrole\s*='
              or agent_board_test.stripped_body(p.oid) ~* '(insert\s+into|update)\s+agent_board\.board_authority_ceilings\M'
              or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mrole_gate_enforced\s*='
+            or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mclaim_policy\s*='
              or agent_board_test.stripped_body(p.oid) ~* 'insert\s+into\s+agent_board\.board_invite_tokens\M')
               <> (agent_board_test.stripped_body(p.oid) ~ '\m(_assert_actor_not_fleet_revoked|_actor_fleet_revoked)\s*\('))
      ) x),

package/tests/agent_board_signer_lifecycle.test.sql

@@ -511,7 +511,7 @@ select is(
     where n.nspname = 'agent_board'
       and p.proname like 'signed\_%'
       and agent_board_test.stripped_body(p.oid)
-          ~ '\m(send_direct_message|send_multicast_message|post_board_message|append_task_event|create_tasking_delivery)\s*\('),
+          ~ '\m(send_direct_message|send_multicast_message|post_board_message|_?append_task_event|create_tasking_delivery)\s*\('),
   'signed_append_task_event,signed_create_tasking_delivery,signed_post_board_message,'
   || 'signed_send_direct_message,signed_send_multicast_message',
   'the five exempt wrappers each perform a message/task write, which is why they are exempt');