@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260802000100_agent_board_rolereset_reentry_clamp.sql

@@ -0,0 +1,237 @@
+-- MBROLERESET — role is not identity across membership re-entry. Closes message-board#79.
+--
+-- THEME: an elevated board role must not survive a non-active -> active transition. Today
+-- `_upsert_board_membership_state` never writes `role` (INSERT omits it; UPDATE omits it), so
+-- a removed/left/requested/invited row that re-enters as joined|subscribed keeps whatever role
+-- was last written — including a prior admin/owner, and including grants applied while the row
+-- was still non-active (the re-arm half of #79). Separately, `grant_board_role` matches any
+-- membership row by board_id+agent_id alone, so a grant onto a removed row succeeds and parks
+-- the elevated role for the next re-entry.
+--
+-- CHANGE 1 — re-entry role clamp in `_upsert_board_membership_state` (UPDATE branch only).
+-- When the target state is joined|subscribed AND the pre-read origin is NOT already
+-- joined|subscribed, set role = 'member' (the table default at 20260717000100:13-15). Hardcoded
+-- — do not read information_schema.columns.column_default at runtime (it returns the quoted
+-- expression '''member''::text', not the value, and assigning it trips the CHECK). The INSERT
+-- branch is intentionally untouched: no-prior-row entry already omits role and takes the table
+-- default. Active -> active (joined <-> subscribed) preserves role, including owner.
+--
+-- This clamp is NECESSARY but NOT a chokepoint. Four raw-INSERT writers bypass
+-- `_upsert_board_membership_state` entirely and are deferred to a follow-up phase (MBROWID):
+--   * create_board owner seed          (20260723000100:103-106)
+--   * bootstrap_board_owner_memberships (20260723000100:149-152)
+--   * _redeem_invite_for_agent         (20260724000100:345-360)
+--   * _fedsession_autojoin_default_board (20260729000100:319-330)
+-- Those paths intentionally write non-default roles (owner / preset admin). A trigger on
+-- board_memberships is FORBIDDEN for the same reason: a BEFORE INSERT/UPDATE trigger would
+-- also fire for those four seeders and erase their intentional roles. The clamp lives in the
+-- mutator only.
+--
+-- No service_role exemption. An operator re-activating an evicted agent gets the default role;
+-- elevation is an explicit subsequent grant_board_role call.
+--
+-- CHANGE 2 — active-membership filter in `grant_board_role` (pre-check AND UPDATE).
+-- Both places gain `and bm.membership_state in ('joined','subscribed')`. Pre-check alone leaves
+-- a TOCTOU window (eviction between check and UPDATE); UPDATE alone leaves v_updated NULL so
+-- RETURN QUERY emits a bogus all-null row. Error message and errcode stay exactly
+-- 'grantee has no membership on this board' / P0002. Grantor binding
+-- (_resolved_actor_agent_id) and _grant_within_ceiling are unchanged — no privilege-escalation
+-- regression.
+--
+-- SOLE-OWNER LOCKOUT (documented limitation, not a defect of this migration): a sole owner who
+-- self-leaves is clamped to 'member' on rejoin, and grant_board_role CANNOT restore them --
+-- it checks _grant_within_ceiling unconditionally with no service_role bypass, so an operator
+-- must nominate a grantor that already holds rank, and by construction none exists.
+-- Recovery DOES exist and is an RPC: leave again (so the creator holds no ACTIVE membership),
+-- then call bootstrap_board_owner_memberships(), which raw-inserts a joined/owner row for a
+-- creator lacking one (20260723000100:138-166). Exercised end-to-end by assertion 23 of
+-- tests/agent_board_rolereset.test.sql. An earlier draft of this header claimed there was NO
+-- RPC recovery; that was refuted during review and is corrected here rather than shipped into
+-- immutable released bytes.
+--
+-- Additive, forward-only. No signature change. Last-definer rule: bodies are copied forward from
+-- 20260801000100 (_upsert) and 20260723000200 (grant_board_role) and modified in place.
+
+-- 1. _upsert_board_membership_state: re-entry role clamp on the UPDATE branch only ------------
+create or replace function agent_board._upsert_board_membership_state(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns agent_board.board_memberships
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_metadata jsonb;
+begin
+  if p_membership_state not in ('requested', 'invited', 'joined', 'subscribed', 'left', 'removed') then
+    raise exception 'invalid board membership state' using errcode = '22023';
+  end if;
+
+  -- Metadata must be a JSON OBJECT. Previously a scalar/array was stored verbatim on insert and
+  -- concatenated on update; the reserved-key strip below iterates keys, so a non-object would raise
+  -- an opaque internal error. Fail explicitly instead. Reachable from the CLI `--metadata`, which
+  -- parses arbitrary JSON — this is a deliberate, declared behavior change for ALL mutator callers.
+  if jsonb_typeof(coalesce(p_metadata, '{}'::jsonb)) <> 'object' then
+    raise exception 'board membership metadata must be a JSON object' using errcode = '22023';
+  end if;
+
+  -- Reserved namespace: `ops_*` keys are operational state (the retention sweep's skip marker
+  -- `ops_retained_at`, read for board_memberships at 20260513000001:122) and must never be writable
+  -- by a caller whose own row they govern. Strip them from caller input; operational writers set
+  -- the column directly.
+  select coalesce(jsonb_object_agg(e.key, e.value), '{}'::jsonb)
+    into v_metadata
+    from jsonb_each(coalesce(p_metadata, '{}'::jsonb)) as e(key, value)
+   where e.key not like 'ops\_%';
+
+  select *
+    into v_membership
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by bm.created_at desc
+   limit 1
+   for update;
+
+  if v_membership.id is null then
+    -- INSERT branch intentionally omits `role` so a no-prior-row entry takes the table default
+    -- (20260717000100:13-15). Do not write role here — an explicit write is wrong.
+    insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, left_at, metadata)
+    values (
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      p_created_by_agent_id,
+      case when p_membership_state in ('left', 'removed') then now() else null end,
+      v_metadata
+    )
+    returning * into v_membership;
+  else
+    update agent_board.board_memberships bm
+       set membership_state = p_membership_state,
+           created_by_agent_id = coalesce(p_created_by_agent_id, bm.created_by_agent_id),
+           -- PRESERVE the first departure time. Restamping it would let the departing agent (or a
+           -- re-kicking owner) push its own row past the retention cutoff (20260513000001:121).
+           left_at = case
+                       when p_membership_state in ('left', 'removed') then
+                         case
+                           -- SAME terminal state re-asserted: preserve the FIRST departure time so a
+                           -- repeat call cannot push the retention cutoff forward.
+                           when v_membership.membership_state = p_membership_state
+                             then coalesce(v_membership.left_at, now())
+                           -- GENUINE transition (notably left -> removed, an owner barring
+                           -- invite-link re-entry for an already-departed agent) stamps NOW. R-LINK-7
+                           -- deliberately does not block voluntary 'left' (20260724000100:321-322),
+                           -- so this is the real kick moment; inheriting the earlier departure would
+                           -- both lose the audit answer and make the marker row retention-eligible
+                           -- prematurely.
+                           else now()
+                         end
+                       else null
+                     end,
+           -- ROLERESET (#79): clamp role to the table default on non-active -> active re-entry.
+           -- Hardcoded 'member' (column default at 20260717000100:13-15); do not read
+           -- information_schema at runtime. Active -> active preserves bm.role (including owner).
+           -- Unconditional — no service_role exemption.
+           role = case
+                    when p_membership_state in ('joined', 'subscribed')
+                     and v_membership.membership_state not in ('joined', 'subscribed')
+                    then 'member'
+                    else bm.role
+                  end,
+           metadata = coalesce(bm.metadata, '{}'::jsonb) || v_metadata,
+           updated_at = now()
+     where bm.id = v_membership.id
+     returning * into v_membership;
+  end if;
+
+  return v_membership;
+end;
+$$;
+
+comment on function agent_board._upsert_board_membership_state(uuid, uuid, text, uuid, jsonb) is
+  'UNAUTHORIZED PRIMITIVE — accepts any membership state; every caller MUST gate. ROLERESET '
+  '(#79): on the UPDATE path only, clamps role to the table default (''member'', '
+  '20260717000100:13-15) when transitioning from a non-active origin into joined|subscribed; '
+  'INSERT omits role and takes the table default. Active->active preserves role. LEAVEIDEM '
+  '(#81): preserves the FIRST left_at across repeated terminal transitions (the retention sweep '
+  'keys on left_at, 20260513000001:121) and strips the reserved `ops_*` metadata namespace from '
+  'caller input (the sweep skips rows carrying ops_retained_at). Not a chokepoint — raw-INSERT '
+  'seeders (create_board owner, bootstrap, invite redeem, fedsession autojoin) bypass this '
+  'function and are out of scope (MBROWID).';
+
+-- 2. grant_board_role: refuse grants onto non-active memberships (pre-check + UPDATE) ---------
+create or replace function agent_board.grant_board_role(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_grantee_role text,
+  p_grantor_agent_id uuid default null
+)
+returns table(board_id uuid, agent_id uuid, role text, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_grantor uuid;
+  v_updated agent_board.board_memberships%rowtype;
+begin
+  if p_grantee_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'invalid grantee role' using errcode = '22023';
+  end if;
+
+  -- Grantor is the RESOLVED actor. service_role -> supplied arg; authenticated ->
+  -- current_agent_id() and raises 42501 if null (suspended/unmapped) or if the
+  -- supplied arg <> current_agent_id(). This closes the single-principal escalation.
+  v_grantor := agent_board._resolved_actor_agent_id(p_grantor_agent_id, 'p_grantor_agent_id');
+
+  if not exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = p_board_id and bm.agent_id = p_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+  ) then
+    raise exception 'grantee has no membership on this board' using errcode = 'P0002';
+  end if;
+
+  -- Ceiling consumption: grantee-bounded against min(grantor role, board ceiling).
+  if not agent_board._grant_within_ceiling(v_grantor, p_board_id, p_grantee_role) then
+    raise exception 'grant exceeds grantor role or board authority ceiling' using errcode = '42501';
+  end if;
+
+  update agent_board.board_memberships bm
+     set role = p_grantee_role,
+         updated_at = now()
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('joined', 'subscribed')
+   returning * into v_updated;
+
+  -- CR finding: the state predicate above closes the unauthorized WRITE, but on its own it
+  -- CREATES a false-success path. If an eviction commits between the pre-check and this
+  -- UPDATE (the TOCTOU window the mirrored predicate exists for), the UPDATE matches zero
+  -- rows, v_updated stays NULL, and the RETURN QUERY below would emit ONE ALL-NULL ROW with
+  -- no error -- a caller that checks "did I get a row back?" reads that as a completed grant.
+  -- Fail closed with the same P0002 the pre-check raises, so the serial and racing cases are
+  -- indistinguishable to the caller.
+  if not found then
+    raise exception 'grantee has no membership on this board' using errcode = 'P0002';
+  end if;
+
+  return query
+  select v_updated.board_id, v_updated.agent_id, v_updated.role, v_updated.updated_at;
+end;
+$$;
+
+comment on function agent_board.grant_board_role(uuid, uuid, text, uuid) is
+  'Live board-role grant chokepoint. Grantor is the resolved actor (_resolved_actor_agent_id: '
+  'service_role uses the supplied arg, authenticated uses current_agent_id() and fails closed on '
+  'null/mismatch). Requires an ACTIVE grantee membership (joined|subscribed; P0002 otherwise) — '
+  'predicate on both the pre-check and the UPDATE (TOCTOU). Then enforces '
+  '_grant_within_ceiling(grantor, board, grantee_role) before setting board_memberships.role. '
+  'ROLERESET (#79): non-active rows cannot be re-armed with an elevated role.';