@consiliency/agent-board-schema 1.2.0 → 1.4.0

package/tests/agent_board_revoke_agent_subtree.test.sql

@@ -0,0 +1,188 @@
+-- MBDELEG SL-1 pgTAP (IF-0-MBDELEG-3): DOWN-walking refresh-checked subtree cascade.
+--
+-- Proves the two linchpins and the survival contract:
+--   (a) REFRESH-BOUNDARY KILL: after a live child fleet_agent_session exists,
+--       revoke_agent_subtree(root) flips ONLY key+status+grant (NOT board membership),
+--       and a fresh mint_fleet_agent_session for that child RAISES within one <=15-min
+--       TTL (the re-mint fails; not old-token expiry).
+--   (b) INERT-LEDGER: a bare fleet_revocation_events row inserted directly (no key/status
+--       flip) does NOT stop mint_fleet_agent_session — the refresh path reads key/status,
+--       not the audit ledger.
+--   + revoke_agent_subtree kills the root + grant-derived descendants (keys + status +
+--     grants + audit rows), while a lineage-independent independent_auth principal (NULL
+--     parent, own active key+status, same owner) SURVIVES and still mints; and
+--     revoke_human_subtree(owner) is TOTAL — it also kills the independent principal.
+--
+-- Runs as postgres (service_role-equivalent).
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(19);
+
+create temp table _rev_fx (
+  owner_id uuid, admin uuid, r uuid, r_key uuid,
+  c uuid, c_key uuid, i uuid, i_key uuid, z uuid, z_key uuid, bd uuid,
+  ch_c1 uuid, ch_c2 uuid, ch_i1 uuid, ch_i2 uuid, ch_i3 uuid, ch_z uuid
+) on commit drop;
+
+do $$
+declare
+  s text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  u_owner uuid; u_admin uuid; u_r uuid; u_i uuid; u_z uuid;
+  v_admin uuid := gen_random_uuid(); v_r uuid := gen_random_uuid();
+  v_i uuid := gen_random_uuid(); v_z uuid := gen_random_uuid();
+  v_bd uuid := gen_random_uuid();
+  v_rkey uuid := gen_random_uuid(); v_ikey uuid := gen_random_uuid(); v_zkey uuid := gen_random_uuid();
+  v_c uuid; v_ckey uuid;
+  ch_c1 uuid := gen_random_uuid(); ch_c2 uuid := gen_random_uuid();
+  ch_i1 uuid := gen_random_uuid(); ch_i2 uuid := gen_random_uuid(); ch_i3 uuid := gen_random_uuid();
+  ch_z uuid := gen_random_uuid();
+begin
+  u_owner := public.ensure_github_user('rev-own-'||s, 'rev-own-'||s||'@example.test', 'rev-own-'||s, 'OWN');
+  u_admin := public.ensure_github_user('rev-adm-'||s, 'rev-adm-'||s||'@example.test', 'rev-adm-'||s, 'ADM');
+  u_r := public.ensure_github_user('rev-r-'||s, 'rev-r-'||s||'@example.test', 'rev-r-'||s, 'R');
+  u_i := public.ensure_github_user('rev-i-'||s, 'rev-i-'||s||'@example.test', 'rev-i-'||s, 'I');
+  u_z := public.ensure_github_user('rev-z-'||s, 'rev-z-'||s||'@example.test', 'rev-z-'||s, 'Z');
+
+  -- Admin (revoker; distinct owner so it is not swept by revoke_human_subtree(owner)).
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id)
+  values (v_admin, 'agent', 'rev-adm-'||s, 'ADM', 'active', u_admin);
+
+  -- Root R (owner = the human). Its own active key.
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_r, 'agent', 'rev-r-'||s, 'R', 'active', u_r, u_owner);
+  insert into agent_board.delegation_policies(root_agent_id, mode, max_active_children, allowed_scopes, child_ttl_ceiling, require_child_signing_key)
+  values (v_r, 'root_minted', 5, jsonb_build_array('scope:a'), interval '8 hours', true);
+  insert into agent_board.agent_signing_keys(id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values (v_rkey, v_r, 'primary', 1, repeat('A',43), 'raw_ed25519_base64url', 'sha256:'||rpad(replace(v_rkey::text,'-',''),43,'A'), 'active', 'proven');
+
+  -- Delegated child C under R (gets an ephemeral revocable key + a grant).
+  select child_agent_id, signing_key_id into v_c, v_ckey
+    from agent_board.mint_delegated_child(v_r, 'rev-c-'||s, jsonb_build_array('scope:a'),
+      rtrim(translate(encode(extensions.gen_random_bytes(32), 'base64'), '+/', '-_'), '='));
+
+  -- Give C a joined board membership; the cascade must NOT touch it.
+  insert into agent_board.boards(id, slug, name, created_by_agent_id)
+  values (v_bd, 'rev-bd-'||s, 'Rev Board', v_admin);
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, role)
+  values (v_bd, v_c, 'joined', 'member');
+
+  -- Give C a live legacy agent_credentials row; the cascade must revoke it (#3).
+  insert into agent_board.agent_credentials(agent_id, refresh_token_hash, hash_version, credential_label, expires_at)
+  values (v_c, extensions.digest('rev-c-cred-'||s, 'sha256'), 1, 'legacy', now() + interval '1 day');
+
+  -- Independent principal I: lineage-independent (NULL parent/root), own active key,
+  -- same human owner. Survives a root revoke; killed only by self or human revoke.
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_i, 'agent', 'rev-i-'||s, 'I', 'active', u_i, u_owner);
+  insert into agent_board.agent_signing_keys(id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values (v_ikey, v_i, 'primary', 1, repeat('A',43), 'raw_ed25519_base64url', 'sha256:'||rpad(replace(v_ikey::text,'-',''),43,'A'), 'active', 'proven');
+
+  -- Z: independent bystander (distinct owner) used only for the inert-ledger proof.
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_z, 'agent', 'rev-z-'||s, 'Z', 'active', u_z, u_z);
+  insert into agent_board.agent_signing_keys(id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values (v_zkey, v_z, 'primary', 1, repeat('A',43), 'raw_ed25519_base64url', 'sha256:'||rpad(replace(v_zkey::text,'-',''),43,'A'), 'active', 'proven');
+
+  -- Challenges (pending, unexpired), bound to (key, agent).
+  insert into agent_board.agent_signing_key_challenges(id, signing_key_id, agent_id, challenge_nonce, challenge_bytes, proof_state, expires_at)
+  values
+    (ch_c1, v_ckey, v_c, ch_c1::text, 'agent-signing-key-proof.v1:'||ch_c1||':n', 'pending', now() + interval '10 minutes'),
+    (ch_c2, v_ckey, v_c, ch_c2::text, 'agent-signing-key-proof.v1:'||ch_c2||':n', 'pending', now() + interval '10 minutes'),
+    (ch_i1, v_ikey, v_i, ch_i1::text, 'agent-signing-key-proof.v1:'||ch_i1||':n', 'pending', now() + interval '10 minutes'),
+    (ch_i2, v_ikey, v_i, ch_i2::text, 'agent-signing-key-proof.v1:'||ch_i2||':n', 'pending', now() + interval '10 minutes'),
+    (ch_i3, v_ikey, v_i, ch_i3::text, 'agent-signing-key-proof.v1:'||ch_i3||':n', 'pending', now() + interval '10 minutes'),
+    (ch_z, v_zkey, v_z, ch_z::text, 'agent-signing-key-proof.v1:'||ch_z||':n', 'pending', now() + interval '10 minutes');
+
+  insert into _rev_fx values (
+    u_owner, v_admin, v_r, v_rkey, v_c, v_ckey, v_i, v_ikey, v_z, v_zkey, v_bd,
+    ch_c1, ch_c2, ch_i1, ch_i2, ch_i3, ch_z
+  );
+end
+$$;
+
+-- Function existence.
+select has_function('agent_board', 'revoke_agent_subtree', array['uuid','uuid','text'], 'revoke_agent_subtree exists');
+select has_function('agent_board', 'revoke_human_subtree', array['uuid','uuid','text'], 'revoke_human_subtree exists');
+
+-- Phase 1: live sessions mint pre-revoke.
+select lives_ok(
+  (select format($q$select agent_board.mint_fleet_agent_session(%1$L::uuid, %1$L::text, %2$L::uuid, %3$L::uuid)$q$, ch_c1, c_key, c) from _rev_fx),
+  'child C mints a live fleet_agent_session while its lineage is active');
+select lives_ok(
+  (select format($q$select agent_board.mint_fleet_agent_session(%1$L::uuid, %1$L::text, %2$L::uuid, %3$L::uuid)$q$, ch_i1, i_key, i) from _rev_fx),
+  'independent principal I mints a live session pre-revoke');
+
+-- INERT-LEDGER: a bare audit row alone does NOT stop Z's mint.
+insert into agent_board.fleet_revocation_events(subject_kind, subject_id, agent_id, revoked_by_agent_id, revocation_reason)
+select 'agent', z, z, admin, 'bare-ledger-inert-test' from _rev_fx;
+select lives_ok(
+  (select format($q$select agent_board.mint_fleet_agent_session(%1$L::uuid, %1$L::text, %2$L::uuid, %3$L::uuid)$q$, ch_z, z_key, z) from _rev_fx),
+  'inert-ledger: a bare fleet_revocation_events row does NOT stop mint (refresh reads key/status, not the ledger)');
+
+-- Phase 2: DOWN-walking cascade from the root R.
+create temp table _rev_counts (revoked_agent_count int, revoked_key_count int) on commit drop;
+insert into _rev_counts
+select * from agent_board.revoke_agent_subtree((select r from _rev_fx), (select admin from _rev_fx), 'root revocation');
+
+select is((select revoked_agent_count from _rev_counts), 2, 'revoke_agent_subtree revoked 2 agents (root R + grant-derived child C)');
+select is((select revoked_key_count from _rev_counts), 2, 'revoke_agent_subtree revoked 2 signing keys (R primary + C ephemeral)');
+
+select is(
+  (select k.status from agent_board.agent_signing_keys k where k.id = (select c_key from _rev_fx)),
+  'revoked', 'child C signing key flipped to revoked');
+select is(
+  (select a.status from agent_board.agents a where a.id = (select c from _rev_fx)),
+  'revoked', 'child C agents.status flipped to revoked');
+select ok(
+  (select g.revoked_at is not null from agent_board.delegation_grants g where g.child_agent_id = (select c from _rev_fx)),
+  'child C delegation grant marked revoked');
+
+-- #3 fix: the cascade also revokes the descendant's legacy agent_credentials.
+select is(
+  (select count(*)::int from agent_board.agent_credentials ac
+     where ac.agent_id = (select c from _rev_fx) and ac.revoked_at is null),
+  0, 'cascade revoked child C''s agent_credentials (no live legacy credential remains)');
+
+-- NOT board membership: C's joined membership is untouched by the cascade.
+select is(
+  (select bm.membership_state from agent_board.board_memberships bm
+    where bm.agent_id = (select c from _rev_fx) and bm.board_id = (select bd from _rev_fx)),
+  'joined', 'cascade did NOT touch board membership (still joined)');
+
+-- Audit rows appended for C (agent + signing_key).
+select ok(
+  (select count(*) filter (where subject_kind = 'agent') >= 1
+      and count(*) filter (where subject_kind = 'signing_key') >= 1
+     from agent_board.fleet_revocation_events e where e.agent_id = (select c from _rev_fx)),
+  'cascade appended audit fleet_revocation_events rows for C (agent + signing_key)');
+
+-- REFRESH-BOUNDARY KILL [linchpin]: a fresh re-mint for C now RAISES (not old-token expiry).
+select throws_ok(
+  (select format($q$select agent_board.mint_fleet_agent_session(%1$L::uuid, %1$L::text, %2$L::uuid, %3$L::uuid)$q$, ch_c2, c_key, c) from _rev_fx),
+  '42501', null, 'refresh-boundary kill: a fresh re-mint for C AFTER revoke_agent_subtree raises');
+
+-- independent_auth SURVIVAL: I is untouched by revoke_agent_subtree(root) and still mints.
+select lives_ok(
+  (select format($q$select agent_board.mint_fleet_agent_session(%1$L::uuid, %1$L::text, %2$L::uuid, %3$L::uuid)$q$, ch_i2, i_key, i) from _rev_fx),
+  'independent principal I survives revoke_agent_subtree(root) and still mints');
+select is(
+  (select k.status from agent_board.agent_signing_keys k where k.id = (select i_key from _rev_fx)),
+  'active', 'independent principal I signing key remains active after root revoke');
+
+-- Phase 3: TOTAL human revocation kills I as well.
+select lives_ok(
+  (select format($q$select agent_board.revoke_human_subtree(%L::uuid, %L::uuid, 'human revocation')$q$, owner_id, admin) from _rev_fx),
+  'revoke_human_subtree runs for the human owner');
+select throws_ok(
+  (select format($q$select agent_board.mint_fleet_agent_session(%1$L::uuid, %1$L::text, %2$L::uuid, %3$L::uuid)$q$, ch_i3, i_key, i) from _rev_fx),
+  '42501', null, 'after revoke_human_subtree, independent principal I can no longer mint (total human revocation)');
+select is(
+  (select a.status from agent_board.agents a where a.id = (select i from _rev_fx)),
+  'revoked', 'revoke_human_subtree flipped the independent principal I to revoked');
+
+select finish();
+
+rollback;

package/tests/agent_board_schema_version.test.sql

@@ -10,8 +10,8 @@ SELECT is(
 
 SELECT is(
   (SELECT version FROM agent_board.schema_version),
-  7,
-  'schema_version.version is 7'
+  8,
+  'schema_version.version is 8'
 );
 
 SELECT throws_ok(

package/tests/agent_board_schema_version_rpc.test.sql

@@ -31,7 +31,7 @@ set local role authenticated;
 
 select is(
   (select version from agent_board.get_schema_version()),
-  7,
+  8,
   'authenticated agents receive the metadata-only schema version'
 );
 

package/tests/agent_board_scoped_send_regrant.test.sql

@@ -0,0 +1,138 @@
+-- MBSESSION SL-1 pgTAP: the 8 core send RPCs are re-granted to authenticated, the
+-- authenticated path derives the actor from current_agent_id() (rejecting a mismatched
+-- p_author_agent_id), real membership is evaluated with _is_service_role() false, a
+-- membership-revoked-mid-session send fails, and no send RPC references Portal
+-- issuer/JWKS (a write succeeds with no Portal dependency present).
+--
+-- Runs as postgres; request.jwt.claim.role toggles _is_service_role()
+-- ('authenticated' => false) and request.jwt.claim.sub picks the acting agent.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(15);
+
+create temp table _regrant_fixture (
+  board uuid,
+  member_agent uuid,
+  other_agent uuid,
+  recipient_agent uuid,
+  member_user uuid,
+  thread_member uuid,
+  thread_dm uuid
+) on commit drop;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_member_user uuid;
+  v_other_user uuid;
+  v_member uuid := gen_random_uuid();
+  v_other uuid := gen_random_uuid();
+  v_recipient uuid := gen_random_uuid();
+  v_board uuid;
+  v_thread_member uuid := gen_random_uuid();
+  v_thread_dm uuid := gen_random_uuid();
+begin
+  v_member_user := public.ensure_github_user('rg-member-' || v_suffix, 'rg-member-' || v_suffix || '@example.test', 'rg-member-' || v_suffix, 'RG Member');
+  v_other_user := public.ensure_github_user('rg-other-' || v_suffix, 'rg-other-' || v_suffix || '@example.test', 'rg-other-' || v_suffix, 'RG Other');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_member, 'agent', 'rg-member-' || v_suffix, 'RG Member', 'active', v_member_user, v_member_user),
+    (v_other, 'agent', 'rg-other-' || v_suffix, 'RG Other', 'active', v_other_user, v_other_user),
+    (v_recipient, 'agent', 'rg-recipient-' || v_suffix, 'RG Recipient', 'active', null, null);
+
+  select board_id into v_board
+    from agent_board.create_board(v_member, 'rg-board-' || v_suffix, 'RG Board', 'regrant test', '{}'::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_member, 'member');
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject)
+  values
+    (v_thread_member, 'coordination', v_member, 'RG member thread'),
+    (v_thread_dm, 'coordination', v_member, 'RG dm thread');
+
+  insert into _regrant_fixture values
+    (v_board, v_member, v_other, v_recipient, v_member_user, v_thread_member, v_thread_dm);
+end
+$$;
+
+-- 1. The 8 core send-RPC overloads are re-granted execute to authenticated. --------
+select function_privs_are(
+  'agent_board', 'send_direct_message', array['uuid','uuid','uuid','text','text','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'send_direct_message(uuid recipient) re-granted to authenticated');
+select function_privs_are(
+  'agent_board', 'send_direct_message', array['uuid','uuid','jsonb','text','text','text','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'send_direct_message(jsonb descriptor) re-granted to authenticated');
+select function_privs_are(
+  'agent_board', 'send_multicast_message', array['uuid','uuid','uuid[]','text','text','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'send_multicast_message(uuid[] recipients) re-granted to authenticated');
+select function_privs_are(
+  'agent_board', 'send_multicast_message', array['uuid','uuid','jsonb','text','text','text','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'send_multicast_message(jsonb descriptors) re-granted to authenticated');
+select function_privs_are(
+  'agent_board', 'post_board_message', array['uuid','uuid','uuid','text','text','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'post_board_message(uuid board) re-granted to authenticated');
+select function_privs_are(
+  'agent_board', 'post_board_message', array['uuid','uuid','text','text','text','text','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'post_board_message(text board_slug) re-granted to authenticated');
+select function_privs_are(
+  'agent_board', 'create_tasking_delivery', array['uuid','uuid','text','text','uuid[]','uuid','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'create_tasking_delivery(uuid[] recipients) re-granted to authenticated');
+select function_privs_are(
+  'agent_board', 'create_tasking_delivery', array['uuid','uuid','text','text','jsonb','text','text','text','text','text','jsonb'],
+  'authenticated', array['EXECUTE'], 'create_tasking_delivery(jsonb descriptors) re-granted to authenticated');
+
+-- 2. Authenticated path: _is_service_role() is false, real membership evaluated. ----
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select member_user from _regrant_fixture)::text, true);
+select is(agent_board._is_service_role(), false, 'authenticated path: _is_service_role() is false');
+
+select lives_ok(
+  (select format($q$select agent_board.post_board_message(%L::uuid, %L::uuid, %L::uuid, 'sub', 'body')$q$,
+     thread_member, member_agent, board) from _regrant_fixture),
+  'a non-observer board member send succeeds with real membership evaluated (Portal-offline write, no Portal dependency present)');
+
+-- 3. A caller-supplied actor that mismatches current_agent_id() is rejected. --------
+select throws_ok(
+  (select format($q$select agent_board.send_direct_message(%L::uuid, %L::uuid, %L::uuid, 'sub', 'body')$q$,
+     thread_dm, other_agent, recipient_agent) from _regrant_fixture),
+  '42501', null,
+  'send with p_author_agent_id <> current_agent_id() is rejected by _resolved_actor_agent_id');
+
+-- 4. A board-less direct send by the member also succeeds (no Portal dependency). ---
+select lives_ok(
+  (select format($q$select agent_board.send_direct_message(%L::uuid, %L::uuid, %L::uuid, 'sub', 'body')$q$,
+     thread_dm, member_agent, recipient_agent) from _regrant_fixture),
+  'a board-less direct send succeeds on the authenticated path (Portal-offline behavioral)');
+
+-- 5. Membership revoked mid-session: the same member board send now fails. ----------
+update agent_board.board_memberships
+   set membership_state = 'left', left_at = now()
+ where board_id = (select board from _regrant_fixture)
+   and agent_id = (select member_agent from _regrant_fixture);
+select throws_ok(
+  (select format($q$select agent_board.post_board_message(%L::uuid, %L::uuid, %L::uuid, 'sub', 'body')$q$,
+     thread_member, member_agent, board) from _regrant_fixture),
+  '42501', null,
+  'a membership-revoked-mid-session board send is rejected by the role gate');
+
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+-- 6. Portal-offline static: no send RPC body references a Portal issuer / JWKS. -----
+select ok(
+  position('portal' in lower(pg_get_functiondef(
+    'agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb)'::regprocedure))) = 0,
+  'post_board_message references no Portal issuer/URL');
+select ok(
+  position('jwks' in lower(pg_get_functiondef(
+    'agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb)'::regprocedure))) = 0,
+  'post_board_message references no JWKS');
+
+select finish();
+
+rollback;

package/tests/agent_board_send_authz_config.test.sql

@@ -0,0 +1,84 @@
+-- MBSENDAUTHZ SL-0 pgTAP: shared send-authz enforcement config + telemetry.
+--
+-- Runs as the postgres db role. request.jwt.claim.role toggles _is_service_role():
+-- unset/'' => service_role true (default here); 'authenticated' => false.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(20);
+
+-- Structure: fleet_send_enforcement_flags ------------------------------------
+select has_table('agent_board', 'fleet_send_enforcement_flags', 'fleet_send_enforcement_flags table exists');
+select has_column('agent_board', 'fleet_send_enforcement_flags', 'scope_key', 'flags has scope_key');
+select col_is_pk('agent_board', 'fleet_send_enforcement_flags', 'scope_key', 'scope_key is the primary key');
+select has_column('agent_board', 'fleet_send_enforcement_flags', 'mode', 'flags has mode');
+select col_has_check('agent_board', 'fleet_send_enforcement_flags', 'mode', 'mode is check-constrained');
+select has_column('agent_board', 'fleet_send_enforcement_flags', 'updated_at', 'flags has updated_at');
+
+-- Default mode is fail_open_preserved (absent explicit mode).
+insert into agent_board.fleet_send_enforcement_flags(scope_key) values ('sl0-default-scope');
+select is(
+  (select mode from agent_board.fleet_send_enforcement_flags where scope_key = 'sl0-default-scope'),
+  'fail_open_preserved', 'flag mode defaults to fail_open_preserved');
+
+-- Invalid mode is rejected by the CHECK.
+select throws_ok(
+  $$insert into agent_board.fleet_send_enforcement_flags(scope_key, mode) values ('sl0-bad', 'block')$$,
+  '23514', null, 'flags mode CHECK rejects an unknown mode');
+
+-- _send_fleet_scope_mode: default on no row, resolved value on a row -----------
+select is(
+  agent_board._send_fleet_scope_mode('sl0-no-such-scope'),
+  'fail_open_preserved', '_send_fleet_scope_mode defaults to fail_open_preserved on no row');
+insert into agent_board.fleet_send_enforcement_flags(scope_key, mode) values ('sl0-observe-scope', 'observe');
+select is(
+  agent_board._send_fleet_scope_mode('sl0-observe-scope'),
+  'observe', '_send_fleet_scope_mode returns the stored mode when a row exists');
+
+-- Structure: nonfleet_sender_allowlist ---------------------------------------
+select has_table('agent_board', 'nonfleet_sender_allowlist', 'nonfleet_sender_allowlist table exists');
+select col_is_pk('agent_board', 'nonfleet_sender_allowlist', 'agent_id', 'allowlist agent_id is the primary key');
+
+-- Structure: send_authz_telemetry + recorder ---------------------------------
+select has_table('agent_board', 'send_authz_telemetry', 'send_authz_telemetry table exists');
+select col_has_check('agent_board', 'send_authz_telemetry', 'kind', 'telemetry kind is check-constrained');
+select col_has_check('agent_board', 'send_authz_telemetry', 'origin', 'telemetry origin is check-constrained');
+
+-- Recorder inserts a row and normalizes an out-of-vocab origin to 'unknown'.
+do $$
+declare v_id uuid;
+begin
+  v_id := agent_board._record_send_authz_telemetry(
+    'service_role_bypass', 'garbage-origin', null, null, 'send_direct_message', 'nonfleet', null, '{}'::jsonb);
+end $$;
+select is(
+  (select origin from agent_board.send_authz_telemetry where operation = 'send_direct_message' order by recorded_at desc limit 1),
+  'unknown', 'recorder normalizes an out-of-vocab origin to unknown');
+select is(
+  (select kind from agent_board.send_authz_telemetry where operation = 'send_direct_message' order by recorded_at desc limit 1),
+  'service_role_bypass', 'recorder persists kind');
+
+-- Recorder is service_role-only: under an authenticated caller it raises 42501.
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select throws_ok(
+  $$select agent_board._record_send_authz_telemetry('service_role_bypass','ef',null,null,'send_direct_message','nonfleet',null,'{}'::jsonb)$$,
+  '42501', null, 'recorder rejects a non-service-role caller');
+select set_config('request.jwt.claim.role', '', true);
+
+-- Recorder execute privilege is revoked from authenticated.
+select function_privs_are(
+  'agent_board', '_record_send_authz_telemetry',
+  array['text', 'text', 'uuid', 'uuid', 'text', 'text', 'text', 'jsonb'],
+  'authenticated', array[]::text[],
+  'recorder execute is revoked from authenticated');
+
+-- _resolve_send_fleet_scope: a non-fleet actor maps to 'nonfleet' -------------
+select is(
+  agent_board._resolve_send_fleet_scope(gen_random_uuid()),
+  'nonfleet', '_resolve_send_fleet_scope maps a non-fleet (no active machine) actor to nonfleet');
+
+select finish();
+
+rollback;

package/tests/agent_board_send_authz_matrix.test.sql

@@ -0,0 +1,159 @@
+-- MBSENDAUTHZ SL-3 pgTAP: cross-cutting authorization matrix. Proves, in one
+-- suite, the board-role send gate (SL-1), the non-fleet default-deny + tight
+-- allowlist + per-scope flag toggle incl. the boardless path (SL-2/SL-0), and the
+-- grantee-bounded ceiling consumption in grant_board_role (SL-3 + MBAUTHZ helper).
+--
+-- Runs as the postgres db role; request.jwt.claim.role/.sub simulate callers.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(11);
+
+create temp table _mtx_fixture (
+  sb_board uuid,
+  sb_member uuid, sb_observer uuid,
+  sb_member_user uuid, sb_observer_user uuid,
+  thread_member uuid, thread_observer uuid,
+  nf_sender uuid, nf_allow uuid,
+  b1 uuid, g_owner uuid, g_admin uuid, g_grantee uuid,
+  b2 uuid, g2_owner uuid, g2_grantee uuid
+) on commit drop;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_sb_member_user uuid;
+  v_sb_observer_user uuid;
+  v_sb_member uuid := gen_random_uuid();
+  v_sb_observer uuid := gen_random_uuid();
+  v_sb_board uuid;
+  v_thread_member uuid := gen_random_uuid();
+  v_thread_observer uuid := gen_random_uuid();
+  v_nf_sender uuid := gen_random_uuid();
+  v_nf_allow uuid := gen_random_uuid();
+  v_b1 uuid; v_g_owner uuid := gen_random_uuid(); v_g_admin uuid := gen_random_uuid(); v_g_grantee uuid := gen_random_uuid();
+  v_b2 uuid; v_g2_owner uuid := gen_random_uuid(); v_g2_grantee uuid := gen_random_uuid();
+begin
+  v_sb_member_user := public.ensure_github_user('mtx-member-' || v_suffix, 'mtx-member-' || v_suffix || '@example.test', 'mtx-member-' || v_suffix, 'MTX Member');
+  v_sb_observer_user := public.ensure_github_user('mtx-observer-' || v_suffix, 'mtx-observer-' || v_suffix || '@example.test', 'mtx-observer-' || v_suffix, 'MTX Observer');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_sb_member, 'agent', 'mtx-member-' || v_suffix, 'MTX Member', 'active', v_sb_member_user, v_sb_member_user),
+    (v_sb_observer, 'agent', 'mtx-observer-' || v_suffix, 'MTX Observer', 'active', v_sb_observer_user, v_sb_observer_user);
+  insert into agent_board.agents(id, agent_type, handle, display_name)
+  values
+    (v_nf_sender, 'agent', 'mtx-nf-' || v_suffix, 'MTX NonFleet'),
+    (v_nf_allow, 'agent', 'mtx-nfa-' || v_suffix, 'MTX NonFleet Allow'),
+    (v_g_owner, 'agent', 'mtx-gowner-' || v_suffix, 'MTX Grant Owner'),
+    (v_g_admin, 'agent', 'mtx-gadmin-' || v_suffix, 'MTX Grant Admin'),
+    (v_g_grantee, 'agent', 'mtx-ggrantee-' || v_suffix, 'MTX Grant Grantee'),
+    (v_g2_owner, 'agent', 'mtx-g2owner-' || v_suffix, 'MTX Grant2 Owner'),
+    (v_g2_grantee, 'agent', 'mtx-g2grantee-' || v_suffix, 'MTX Grant2 Grantee');
+
+  -- Send board with member/observer roles + accessible threads.
+  select board_id into v_sb_board from agent_board.create_board(v_sb_member, 'mtx-sb-' || v_suffix, 'MTX Send Board', 'matrix', '{}'::jsonb, 'private');
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_sb_board, v_sb_member, 'joined', v_sb_member, 'member'),
+    (v_sb_board, v_sb_observer, 'joined', v_sb_member, 'observer');
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject)
+  values
+    (v_thread_member, 'coordination', v_sb_member, 'MTX member thread'),
+    (v_thread_observer, 'coordination', v_sb_observer, 'MTX observer thread');
+
+  -- Grant board B1: no ceiling row (ceiling defaults to owner).
+  select board_id into v_b1 from agent_board.create_board(v_g_owner, 'mtx-b1-' || v_suffix, 'MTX Grant B1', 'ceiling', '{}'::jsonb, 'private');
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_b1, v_g_owner, 'joined', v_g_owner, 'owner'),
+    (v_b1, v_g_admin, 'joined', v_g_owner, 'admin'),
+    (v_b1, v_g_grantee, 'joined', v_g_owner, 'observer');
+
+  -- Grant board B2: ceiling lowered to member.
+  select board_id into v_b2 from agent_board.create_board(v_g2_owner, 'mtx-b2-' || v_suffix, 'MTX Grant B2', 'ceiling', '{}'::jsonb, 'private');
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_b2, v_g2_owner, 'joined', v_g2_owner, 'owner'),
+    (v_b2, v_g2_grantee, 'joined', v_g2_owner, 'observer');
+  insert into agent_board.board_authority_ceilings(board_id, max_grantable_role) values (v_b2, 'member');
+
+  insert into _mtx_fixture values (
+    v_sb_board, v_sb_member, v_sb_observer, v_sb_member_user, v_sb_observer_user,
+    v_thread_member, v_thread_observer, v_nf_sender, v_nf_allow,
+    v_b1, v_g_owner, v_g_admin, v_g_grantee, v_b2, v_g2_owner, v_g2_grantee);
+end
+$$;
+
+-- A. Board-role send gate (authenticated path) -------------------------------
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select sb_observer_user from _mtx_fixture)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.post_board_message(%L::uuid, %L::uuid, %L::uuid, 's', 'b')$q$,
+     thread_observer, sb_observer, sb_board) from _mtx_fixture),
+  '42501', 'board send requires a non-observer board role',
+  'matrix: observer authenticated actor denied on a board send');
+select set_config('request.jwt.claim.sub', (select sb_member_user from _mtx_fixture)::text, true);
+select lives_ok(
+  (select format($q$select agent_board.post_board_message(%L::uuid, %L::uuid, %L::uuid, 's', 'b')$q$,
+     thread_member, sb_member, sb_board) from _mtx_fixture),
+  'matrix: member authenticated actor allowed on a board send');
+
+-- B/C. Non-fleet default-deny + tight allowlist + per-scope flag toggle -------
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+insert into agent_board.fleet_send_enforcement_flags(scope_key, mode) values ('nonfleet', 'deny');
+insert into agent_board.nonfleet_sender_allowlist(agent_id, reason) values ((select nf_allow from _mtx_fixture), 'matrix enumerated flow');
+
+select is(
+  (select allowed from agent_board.evaluate_signed_write_fleet_policy('send_direct_message', '{}'::jsonb,
+    jsonb_build_object('agent_id', (select nf_sender from _mtx_fixture)::text))),
+  false, 'matrix: deny mode blocks an unenrolled non-fleet sender');
+select is(
+  (select allowed from agent_board.evaluate_signed_write_fleet_policy('send_direct_message', '{}'::jsonb,
+    jsonb_build_object('agent_id', (select nf_allow from _mtx_fixture)::text))),
+  true, 'matrix: tight allowlist admits only the enumerated non-fleet sender');
+-- Boardless send_direct_message path is gated by the scope flag (scope before board).
+select is(
+  (select denial_class from agent_board.evaluate_signed_write_fleet_policy('send_direct_message', '{}'::jsonb,
+    jsonb_build_object('agent_id', (select nf_sender from _mtx_fixture)::text))),
+  'nonfleet_sender_denied', 'matrix: flag gates the boardless send_direct_message path under deny');
+-- Toggle the scope off: the same sender now passes (fail_open_preserved).
+update agent_board.fleet_send_enforcement_flags set mode = 'fail_open_preserved' where scope_key = 'nonfleet';
+select is(
+  (select allowed from agent_board.evaluate_signed_write_fleet_policy('send_direct_message', '{}'::jsonb,
+    jsonb_build_object('agent_id', (select nf_sender from _mtx_fixture)::text))),
+  true, 'matrix: flag toggle to fail_open_preserved re-admits the same non-fleet sender');
+
+-- D. Grantee-bounded ceiling consumption via grant_board_role -----------------
+-- B1 has no ceiling row (ceiling defaults to owner).
+select lives_ok(
+  (select format($q$select agent_board.grant_board_role(%L::uuid, %L::uuid, 'member', %L::uuid)$q$,
+     b1, g_grantee, g_admin) from _mtx_fixture),
+  'matrix: within-ceiling grant (admin grants member) is admitted');
+select throws_ok(
+  (select format($q$select agent_board.grant_board_role(%L::uuid, %L::uuid, 'owner', %L::uuid)$q$,
+     b1, g_grantee, g_admin) from _mtx_fixture),
+  '42501', 'grant exceeds grantor role or board authority ceiling',
+  'matrix: a grant exceeding the grantor role is rejected (grantee-bounded)');
+select lives_ok(
+  (select format($q$select agent_board.grant_board_role(%L::uuid, %L::uuid, 'admin', %L::uuid)$q$,
+     b1, g_grantee, g_owner) from _mtx_fixture),
+  'matrix: no-ceiling-row board treats ceiling as owner (owner grants admin admitted)');
+-- B2 ceiling is member: owner may not grant admin (over-ceiling).
+select throws_ok(
+  (select format($q$select agent_board.grant_board_role(%L::uuid, %L::uuid, 'admin', %L::uuid)$q$,
+     b2, g2_grantee, g2_owner) from _mtx_fixture),
+  '42501', 'grant exceeds grantor role or board authority ceiling',
+  'matrix: an over-ceiling grant is rejected even for an owner grantor');
+
+-- E. Dormancy: grant_board_role is revoked from authenticated -----------------
+select function_privs_are(
+  'agent_board', 'grant_board_role', array['uuid', 'uuid', 'text', 'uuid'],
+  'authenticated', array[]::text[], 'matrix: grant_board_role execute is revoked from authenticated');
+
+select finish();
+
+rollback;