@consiliency/agent-board-schema 1.24.0 → 1.27.0

package/migrations/20260907000100_agent_board_signed_authority_provenance.sql

@@ -0,0 +1,243 @@
+-- #247 — signed provenance for the authority-granting writes.
+--
+-- WHAT THIS CLOSES. `grant_board_role` and `set_board_authority_ceiling` are the two
+-- authority-granting writes in the bundle, and neither could carry signing provenance in
+-- any form. The client's `attachSigningMetadata` merges its evidence into `p_metadata`,
+-- and neither function declares that parameter (verified against their NEWEST definitions,
+-- 20260802000100 and 20260901000110 — not their first). Adding them to the client's signed
+-- set would have attached an undeclared argument: a PostgREST signature mismatch, not a
+-- silent no-op. So closing this is a schema change, not a client-list change.
+--
+-- MECHANISM (ratified 2026-08-12). These two get dedicated `signed_*` wrappers that call
+-- `_record_signed_write_evidence` and write a real, queryable `signature_evidence` row —
+-- the same mechanism as the five existing message/task signed writes, whose shape they
+-- follow rather than inventing a new one. The alternative (`p_metadata.signed_write` on
+-- the written row) records only that a client CLAIMED to sign; for "who granted this role,
+-- and can we prove it", only an evidence row answers the question.
+--
+-- PROVENANCE IS DERIVED, NEVER ASSERTED. `_signed_write_actor_id` takes the actor from the
+-- gateway's verified decision and raises `actor_mismatch` (42501) when a payload names a
+-- different principal. That resolved actor — not `p_payload ->> 'p_grantor_agent_id'` — is
+-- what the wrapper passes to the inner function AND what the evidence row names, because
+-- the newest `_record_signed_write_evidence` (20260710000000) reads its actor solely from
+-- `p_gateway_decision ->> 'agent_id'`. An evidence row recording the caller-supplied
+-- grantor would be worse than no evidence row, because it looks like proof.
+--
+-- WHY set_board_authority_ceiling GAINS A PARAMETER. Its owner gate reads
+-- `current_agent_id()` and nothing else, so it can only ever succeed for an authenticated
+-- session. The `signed_*` layer is service_role-only BY DESIGN: 20260812000100 (#118)
+-- revoked `_record_signed_write_evidence` from `authenticated` precisely because it mints
+-- attestation rows from caller-supplied fields, so granting a `signed_*` wrapper to
+-- `authenticated` would reopen that forge hole. A service_role-only wrapper therefore
+-- cannot satisfy a `current_agent_id()`-only gate, and the bundle's existing delegation
+-- mechanism is `_resolved_actor_agent_id` — exactly the shape `grant_board_role` already
+-- has. Hence the new `p_actor_agent_id`.
+--
+-- D4 — THIS CHANGES NO UNSIGNED CALL. `p_actor_agent_id` defaults to null, and when it is
+-- null the setter takes the pre-#247 path verbatim (`v_actor := current_agent_id()`), for
+-- EVERY role. The resolver engages only when a caller supplies the argument. Under
+-- `authenticated` the resolver additionally requires the supplied id to equal
+-- `current_agent_id()` (42501 otherwise), so the new parameter cannot be used to act as
+-- someone else. `create or replace` cannot add a parameter — it would leave a 2-arg and a
+-- 3-arg overload live simultaneously and make a named-argument PostgREST call ambiguous —
+-- so the setter is DROPped and recreated, with its `revoke`, its `grant` and its `comment`
+-- restated in this same migration (a DROP discards the ACL and the COMMENT, and a
+-- recreated SECURITY DEFINER function grants EXECUTE to PUBLIC by default).
+--
+-- EVIDENCE SHAPE. An authority write has no canonical source row to point at: the
+-- `signature_evidence` source columns are message / task_event / artifact /
+-- delivery_recipient. `source_kind = 'external'` is the constraint's existing shape for
+-- "no internal source row, identified by a ref", and 20260718000300 already records
+-- signed-write preflight evidence that way. The ref is synthesized SERVER-side from the
+-- resolved actor and the board and FORCED over any caller-supplied value — a caller ref is
+-- an assertion, a derived one is evidence. No table DDL is required.
+
+-- 1. set_board_authority_ceiling — delegable actor, so a service_role gateway can carry a
+--    signed grant on an owner's behalf. Everything else is verbatim from 20260901000110.
+drop function if exists agent_board.set_board_authority_ceiling(uuid, text);
+
+create or replace function agent_board.set_board_authority_ceiling(
+  p_board_id uuid,
+  p_max_grantable_role text,
+  p_actor_agent_id uuid default null
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+begin
+  if p_max_grantable_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'max_grantable_role must be one of owner/admin/member/observer' using errcode = '22023';
+  end if;
+
+  -- Same board-keyed advisory lock every ceiling READER for authorization takes.
+  -- Held to commit, it makes the insert of a first ceiling row serialize against a
+  -- concurrent authorization that would otherwise observe the pre-insert ABSENCE and
+  -- pass as default-owner. Taken before the owner gate so the gate and the write are
+  -- one critical section.
+  perform agent_board._lock_board_authority_ceiling(p_board_id);
+
+  -- #247. Actor resolution, NOT a widening of the gate. With p_actor_agent_id omitted this
+  -- is the pre-#247 expression for every role, so no existing caller changes behaviour
+  -- (D4). When it IS supplied, _resolved_actor_agent_id binds it: service_role takes the
+  -- argument (this is the signed_* gateway path, where the argument is the gateway-VERIFIED
+  -- signer, never a raw caller claim), while authenticated still resolves to
+  -- current_agent_id() and raises 42501 if the supplied id differs. The owner gate below is
+  -- untouched and remains the only thing that authorizes the write.
+  if p_actor_agent_id is null then
+    v_actor := agent_board.current_agent_id();
+  else
+    v_actor := agent_board._resolved_actor_agent_id(p_actor_agent_id, 'p_actor_agent_id');
+  end if;
+
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the board authority ceiling' using errcode = '42501';
+  end if;
+
+  insert into agent_board.board_authority_ceilings(board_id, max_grantable_role)
+  values (p_board_id, p_max_grantable_role)
+  on conflict (board_id) do update
+    set max_grantable_role = excluded.max_grantable_role,
+        updated_at = now();
+
+  return query
+  select p_board_id, p_max_grantable_role;
+end;
+$$;
+
+comment on function agent_board.set_board_authority_ceiling(uuid, text, uuid) is
+  'Owner-gated setter for a board''s authority ceiling: takes the board-keyed _lock_board_authority_ceiling advisory lock, then upserts board_authority_ceilings only when the resolved actor is an owner of the board (else raises 42501). The actor is current_agent_id() when p_actor_agent_id is omitted — the pre-#247 behaviour for every role — and _resolved_actor_agent_id(p_actor_agent_id) when it is supplied, which lets the service_role-only signed_set_board_authority_ceiling gateway act for the gateway-verified signer while still forcing an authenticated caller to match current_agent_id(). Leaves _grant_within_ceiling semantics unchanged.';
+
+revoke all on function agent_board.set_board_authority_ceiling(uuid, text, uuid) from public, anon;
+grant execute on function agent_board.set_board_authority_ceiling(uuid, text, uuid) to authenticated, service_role;
+
+-- 2. signed_grant_board_role — evidence-recording wrapper over the live grant chokepoint.
+create or replace function agent_board.signed_grant_board_role(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(
+  board_id uuid,
+  agent_id uuid,
+  role text,
+  signature_evidence_id uuid,
+  verification_status text,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid;
+  v_evidence_id uuid;
+  v_board uuid := (p_payload ->> 'p_board_id')::uuid;
+  v_grantee uuid := (p_payload ->> 'p_agent_id')::uuid;
+begin
+  -- The grantor is the gateway-verified signer. _signed_write_actor_id raises 42501 when
+  -- the gateway names no actor, and raises actor_mismatch when the payload names a
+  -- DIFFERENT one -- so a payload p_grantor_agent_id can never become the grantor. This
+  -- value is what grant_board_role binds (through its own _resolved_actor_agent_id) and
+  -- what the evidence row names; they cannot diverge.
+  v_actor := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_grantor_agent_id');
+
+  select *
+    into v_row
+    from agent_board.grant_board_role(
+      v_board,
+      v_grantee,
+      p_payload ->> 'p_grantee_role',
+      v_actor
+    );
+
+  v_evidence_id := agent_board._record_signed_write_evidence(
+    'external',
+    null,
+    'grant_board_role',
+    p_payload,
+    p_gateway_decision || jsonb_build_object(
+      'external_evidence_ref',
+      'board-authority:grant_board_role:' || v_board::text || ':' || v_grantee::text
+    )
+  );
+
+  return query
+  select v_row.board_id, v_row.agent_id, v_row.role, v_evidence_id,
+         coalesce(p_gateway_decision ->> 'verification_status', 'unsigned'), v_row.updated_at;
+end;
+$$;
+
+comment on function agent_board.signed_grant_board_role(jsonb, jsonb) is
+  '#247 signed-write gateway wrapper for grant_board_role. Resolves the grantor with _signed_write_actor_id (gateway actor required; a payload p_grantor_agent_id that differs raises actor_mismatch 42501), passes THAT principal to grant_board_role so the bound grantor and the recorded one cannot diverge, and records a signature_evidence row via _record_signed_write_evidence with source_kind=external and a server-derived external_evidence_ref naming the board and grantee. Adds no authority: grant_board_role''s membership, ceiling and TOCTOU gates are untouched. service_role only, like every other signed_* wrapper (#118).';
+
+-- 3. signed_set_board_authority_ceiling — evidence-recording wrapper over the ceiling setter.
+create or replace function agent_board.signed_set_board_authority_ceiling(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text,
+  signature_evidence_id uuid,
+  verification_status text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid;
+  v_evidence_id uuid;
+  v_board uuid := (p_payload ->> 'p_board_id')::uuid;
+begin
+  v_actor := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_actor_agent_id');
+
+  select *
+    into v_row
+    from agent_board.set_board_authority_ceiling(
+      v_board,
+      p_payload ->> 'p_max_grantable_role',
+      v_actor
+    );
+
+  v_evidence_id := agent_board._record_signed_write_evidence(
+    'external',
+    null,
+    'set_board_authority_ceiling',
+    p_payload,
+    p_gateway_decision || jsonb_build_object(
+      'external_evidence_ref',
+      'board-authority:set_board_authority_ceiling:' || v_board::text || ':' || v_actor::text
+    )
+  );
+
+  return query
+  select v_row.ceiling_board_id, v_row.ceiling_max_grantable_role, v_evidence_id,
+         coalesce(p_gateway_decision ->> 'verification_status', 'unsigned');
+end;
+$$;
+
+comment on function agent_board.signed_set_board_authority_ceiling(jsonb, jsonb) is
+  '#247 signed-write gateway wrapper for set_board_authority_ceiling. Resolves the actor with _signed_write_actor_id (gateway actor required; a differing payload p_actor_agent_id raises actor_mismatch 42501) and passes it as p_actor_agent_id, so the owner gate authorizes the SAME principal the evidence row names. Records a signature_evidence row via _record_signed_write_evidence with source_kind=external and a server-derived external_evidence_ref. Adds no authority: the owner gate still rejects any actor that is not an active board owner. service_role only, like every other signed_* wrapper (#118).';
+
+revoke all on function agent_board.signed_grant_board_role(jsonb, jsonb) from public, anon, authenticated;
+revoke all on function agent_board.signed_set_board_authority_ceiling(jsonb, jsonb) from public, anon, authenticated;
+
+grant execute on function agent_board.signed_grant_board_role(jsonb, jsonb) to service_role;
+grant execute on function agent_board.signed_set_board_authority_ceiling(jsonb, jsonb) to service_role;