@consiliency/agent-board-schema 1.10.0 → 1.22.0

package/migrations/20260730000100_agent_board_gatenull_service_role_bypass.sql

@@ -0,0 +1,369 @@
+-- GATENULL — distinguish the service_role bypass from an unresolvable authenticated principal.
+-- Tracks message-board#58.
+--
+-- THE DEFECT. Board-mutating RPCs use `if v_actor is not null then <authz> end if` as the
+-- service_role bypass, where `v_actor := agent_board.current_agent_id()`. current_agent_id()
+-- resolves only an ACTIVE agent, so it returns NULL for TWO very different callers:
+--   (1) a genuine service_role / operator call — the bypass is intended; and
+--   (2) an AUTHENTICATED principal with no active agent — a suspended/revoked agent holding a
+--       still-valid JWT, a signed-in human with no agents row at all, or an active agent whose
+--       JWT `agent_credential_id` claim names a revoked/expired credential.
+-- Class (2) therefore takes the service_role bypass and skips authorization entirely.
+--
+-- SEVERITY IS NOT SESSION-BOUNDED (corrected during panel review). LOCALAUTH (20260726000100)
+-- exists so browser humans sign in with THIS project's own Supabase Auth; such a user, BEFORE
+-- self_enroll_human, is role=authenticated with no agents row — i.e. class (2) — while holding a
+-- GoTrue session with a REFRESH token, renewable indefinitely. A suspended human is refused
+-- reactivation (20260726000100:63-81) and so remains in class (2) permanently. Confirmed against
+-- the live board in a rolled-back transaction: a signed-in principal with NO agent row joined a
+-- private `invite_only` board with no invite, via the join_board visibility guard below.
+--
+-- THE FIX (deliberately MINIMAL — panel rejected a broader rewrite). Each function gains ONE
+-- guard, placed FIRST, and every existing `if v_actor is not null then ...` block is left
+-- BYTE-IDENTICAL:
+--
+--     if v_actor is null and not agent_board._is_service_role() then
+--       raise exception 'current agent principal not resolved' using errcode = '42501';
+--     end if;
+--
+-- After it, a non-service caller is guaranteed to have a non-null actor, so the untouched
+-- `if v_actor is not null then <authz>` block now runs for EVERY authenticated caller. Behavior
+-- is unchanged for: service_role with a null actor (create-on-behalf-of preserved), service_role
+-- WITH a non-null actor (the checks keep running exactly as today — a broader
+-- `if not _is_service_role()` wrapper would have WRONGLY skipped them, and would have turned
+-- tests/agent_board_board_role.test.sql red), and any authenticated caller with an active agent.
+-- Exactly one class changes: class (2) now fails closed.
+--
+-- GUARD PLACEMENT is deliberate: FIRST, before any table lookup. Raising at the original guard
+-- site would leave `P0002 'board not found'` reachable ahead of the 42501, giving an
+-- unauthorized principal a board/agent existence oracle. Only class (2) sees the reordering, and
+-- that class currently has full write access — so nothing legitimate regresses.
+--
+-- MESSAGE reuses the canonical 'current agent principal not resolved' / 42501 of
+-- _resolved_actor_agent_id (20260512000000:35-38) rather than minting a fifth phrasing.
+--
+-- SCOPE (audited at HEAD by last-definer; three panel seats independently confirmed no fifth
+-- function carries this pattern): join_board (TWO sites), request_join_board, invite_board_member,
+-- resolve_board_request. The issue named only the latter two. Bodies are reproduced from their
+-- HEAD definers — invite/resolve from ROOMDELEG 20260725000100 (NOT the superseded 20260717000100
+-- copies, which would silently revert the R-DELEG-1 creator-bypass fix), join/request from
+-- 20260515000000. Signatures and RETURNS TABLE lists are reproduced VERBATIM: a changed arg list
+-- would create an OVERLOAD instead of replacing, a changed return list hard-errors.
+--
+-- RELATED, NOT FIXED HERE: update_board_membership has NO authorization at all (a strictly
+-- stronger primitive for the same attacker) — hardened in the sibling migration 20260730000200
+-- (MEMBSTATE, #75). Caller-supplied actor override in resolve_recipients /
+-- expand_recipients_dry_run is a different family — #76 (ACTORSPOOF).
+--
+-- Additive, forward-only. Body-only change with unchanged signatures, so NO PostgREST reload is
+-- required. Writes no agent_board.schema_version (stays 8).
+
+-- 1. join_board — TWO guarded sites (actor-mismatch, and the visibility/joinability gate). ------
+create or replace function agent_board.join_board(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text default 'joined',
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  if p_membership_state not in ('joined', 'subscribed') then
+    raise exception 'join_board only accepts joined or subscribed' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if p_created_by_agent_id is not null and not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent not found' using errcode = 'P0002';
+  end if;
+
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    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;
+
+  if v_actor is not null and v_actor <> p_agent_id and v_actor <> v_board.created_by_agent_id then
+    raise exception 'board membership actor mismatch' using errcode = '42501';
+  end if;
+
+  -- NULLFIX (CR): v_existing_state is NULL when the caller has NO membership row, and the original
+  -- guard then evaluated to NULL — `not (false or false or NULL)` is NULL, not TRUE — so `if NULL
+  -- then` never fired and ANY resolvable actor self-joined ANY board, private ones included. That
+  -- (not the null-actor bypass) was the true root cause of the live "joined a private invite_only
+  -- board with no invite" finding, and it is reachable by an ACTIVE agent, which the GATENULL guard
+  -- above cannot touch. coalesce() makes the absent-row case FALSE so the raise fires.
+  -- A 'removed' agent is also excluded from self-joining even an OPEN board: re-entry after a kick
+  -- must go through invite/approval (the R-LINK-7 principle, 20260724000100:315-335), and
+  -- _upsert_board_membership_state does not reset `role`, so a re-joining removed owner/admin would
+  -- otherwise return at its former rank.
+  if v_actor is not null
+     and v_actor = p_agent_id
+     and v_board.created_by_agent_id <> v_actor
+     and not (
+       coalesce(v_existing_state, '') <> 'removed'
+       and (
+         v_board.visibility = 'open'
+         or (v_board.visibility = 'invite_only' and coalesce(v_existing_state, '') = 'invited')
+         or coalesce(v_existing_state, '') in ('joined', 'subscribed')
+       )
+     ) then
+    raise exception 'board is not joinable by this agent' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    coalesce(p_created_by_agent_id, p_agent_id),
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;
+
+-- 2. request_join_board ------------------------------------------------------------------------
+create or replace function agent_board.request_join_board(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  select * into v_board
+    from agent_board.boards
+   where id = p_board_id
+     and status = 'active'
+     and visibility in ('open', 'invite_only');
+
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null and v_actor <> p_agent_id then
+    raise exception 'board request actor mismatch' using errcode = '42501';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    'requested',
+    p_agent_id,
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;
+
+-- 3. invite_board_member (body from ROOMDELEG 20260725000100 — R-DELEG-1 preserved) -------------
+create or replace function agent_board.invite_board_member(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_created_by_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null then
+    if v_board.role_gate_enforced then
+      -- Gate ON: NO creator exemption. Every actor (including a demoted creator)
+      -- must hold an active owner/admin membership.
+      if 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.membership_state in ('joined', 'subscribed')
+           and bm.role in ('owner', 'admin')
+      ) then
+        raise exception 'board invite requires owner or admin role' using errcode = '42501';
+      end if;
+    elsif v_actor <> v_board.created_by_agent_id then
+      -- Gate OFF: creator bypasses; any other actor needs an active membership.
+      if 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.membership_state in ('joined', 'subscribed')
+      ) then
+        raise exception 'board invite requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    'invited',
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;
+
+-- 4. resolve_board_request (body from ROOMDELEG 20260725000100 — R-DELEG-1 preserved) -----------
+create or replace function agent_board.resolve_board_request(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, left_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  if p_membership_state not in ('joined', 'subscribed', 'removed') then
+    raise exception 'resolve_board_request only accepts joined, subscribed, or removed' using errcode = '22023';
+  end if;
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null then
+    if v_board.role_gate_enforced then
+      -- Gate ON: NO creator exemption. Every actor (including a demoted creator)
+      -- must hold an active owner/admin membership.
+      if 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.membership_state in ('joined', 'subscribed')
+           and bm.role in ('owner', 'admin')
+      ) then
+        raise exception 'board request resolution requires owner or admin role' using errcode = '42501';
+      end if;
+    elsif v_actor <> v_board.created_by_agent_id then
+      -- Gate OFF: creator bypasses; any other actor needs an active membership.
+      if 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.membership_state in ('joined', 'subscribed')
+      ) then
+        raise exception 'board request resolution requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    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;
+
+  -- NULLFIX (CR): same NULL-falsy hazard — with NO membership row v_existing_state is NULL and
+  -- `NULL not in (...)` is NULL, so the raise never fired and a caller could "resolve" an agent
+  -- that had never requested or been invited STRAIGHT to joined, bypassing the whole request path
+  -- (reachable by any active member on a gate-OFF board, incl. via `rooms approve --agent-id`).
+  if coalesce(v_existing_state, '') not in ('requested', 'invited') then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.left_at, v_membership.updated_at;
+end;
+$$;
+
+-- Re-assert grants (create or replace preserves them, but be explicit so a fresh replay is
+-- order-independent) — house convention, 20260725000100:229-232.
+revoke all on function agent_board.join_board(uuid, uuid, text, uuid, jsonb) from public, anon;
+revoke all on function agent_board.request_join_board(uuid, uuid, jsonb) from public, anon;
+revoke all on function agent_board.invite_board_member(uuid, uuid, uuid, jsonb) from public, anon;
+revoke all on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) from public, anon;
+grant execute on function agent_board.join_board(uuid, uuid, text, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.request_join_board(uuid, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.invite_board_member(uuid, uuid, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) to authenticated, service_role;

package/migrations/20260730000200_agent_board_membstate_authz.sql

@@ -0,0 +1,195 @@
+-- MEMBSTATE — give update_board_membership an authorization model. Tracks message-board#75.
+--
+-- THE DEFECT. agent_board.update_board_membership (HEAD: 20260515000000_agent_board_boardopt.sql
+-- :203-238) is SECURITY DEFINER, granted to `authenticated` (:486), and performs NO authorization
+-- of any kind — its only precondition is that a (board_id, agent_id) membership row EXISTS. It
+-- then hands that row to _upsert_board_membership_state, which accepts any of
+-- requested|invited|joined|subscribed|left|removed.
+--
+-- This is NOT the GATENULL (#58) null-actor pattern and is strictly worse: it needs no bypass at
+-- all. An ordinary ACTIVE authenticated principal (current_agent_id() resolves, _is_service_role()
+-- false) can rewrite ANY membership on ANY board. All four plan-panel seats independently flagged
+-- it; both chains were confirmed against the live board in rolled-back transactions:
+--
+--   1. EVICTION / TAKEOVER — update_board_membership(board, <owner>, 'removed') by an agent with
+--      NO membership on that board succeeded; the owner's state became 'removed', stripping the
+--      `joined` standing that the owner-loop RLS and every owner-gated RPC key on.
+--   2. SELF-APPROVAL INTO A PRIVATE BOARD — request_join_board(invite_only board, self) (a
+--      legitimate call producing 'requested') followed by update_board_membership(board, self,
+--      'joined') succeeded, and the board feed then read successfully. This bypasses the entire
+--      invite/approval path (invite_board_member / resolve_board_request / invite links) that the
+--      authority model exists to enforce, and defeats the ROOMDELEG role gate for the join path.
+--
+-- It also re-opens, on a direct path, the kicked-agent re-entry hazard that _redeem_invite_for_agent
+-- deliberately defends on the invite path (R-LINK-7, 20260724000100:315-335).
+--
+-- THE MODEL. A purpose-built gate (the panel explicitly rejected reusing GATENULL's transform here
+-- — that only distinguishes the null actor and would leave every ACTIVE-caller chain above open):
+--
+--   * service_role / operator            -> unchanged full power (create/modify-on-behalf-of).
+--   * authenticated, unresolved actor    -> 42501, same posture and message as GATENULL (#58).
+--   * authenticated acting on ITS OWN row-> only SELF-SERVICE transitions:
+--         joined <-> subscribed, and joined|subscribed|invited|requested -> left. NOT from
+--         'removed': erasing a 'removed' marker would launder a kick into invite-link re-entry
+--         (R-LINK-7, 20260724000100:323-335), since memberships are updated IN PLACE.
+--     Notably NOT requested|invited|left|removed -> joined|subscribed: promotion into a board is
+--     the approval path's job (join_board / resolve_board_request / redeem_invite_link), which
+--     enforces visibility, invite state, gates and ceilings. This is what closes chain 2 and the
+--     kicked-agent re-entry.
+--   * authenticated acting on ANOTHER agent's row -> requires an ACTIVE owner/admin membership on
+--     that board AND strict rank superiority over the target (owner=4 > admin=3 > member=2 >
+--     observer=1). There is deliberately NO creator exemption here (unlike invite_board_member /
+--     resolve_board_request): this RPC is the schema's ONLY eviction path — no sibling can move a
+--     JOINED member to removed — so a demoted or removed original creator must not retain eviction
+--     power, and an admin must not be able to evict the owner. This closes chain 1.
+--
+-- ORDERING / DISCLOSURE. The unresolved-actor 42501 is raised FIRST, and for a caller acting on
+-- ANOTHER agent's row the board + owner/admin authority check runs BEFORE the membership lookup —
+-- so an unauthorized caller cannot distinguish P0002 'board membership not found' from 42501 and
+-- cannot probe whether an arbitrary (board_id, agent_id) pair has a membership row. The self
+-- branch takes NO board lookup at all, so leave_board keeps working on an ARCHIVED board
+-- (20260512000002:154-158 delegates here); P0002 'board membership not found' is otherwise
+-- preserved for every caller that reaches it.
+--
+-- COMPATIBILITY. No signature or RETURNS TABLE change (a changed arg list would create an OVERLOAD
+-- rather than replace; a changed return list hard-errors), so no client/mcp/cli surface change and
+-- no PostgREST reload. `leave_board` (20260512000002) remains the ergonomic self-`left` path and is
+-- untouched; the self-service transitions above deliberately keep update_board_membership able to
+-- express it too, so no existing legitimate caller loses a capability.
+--
+-- Additive, forward-only. Writes no agent_board.schema_version (stays 8).
+
+create or replace function agent_board.update_board_membership(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, left_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_board agent_board.boards%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+  v_is_service boolean := agent_board._is_service_role();
+  v_existing_state text;
+  v_target_role text;
+  v_actor_role text;
+begin
+  -- (1) Unresolved principal fails closed (GATENULL #58 posture). Raised before any lookup so this
+  -- cannot be used as a membership-existence oracle.
+  if v_actor is null and not v_is_service then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  -- (2) AUTHORITY BEFORE DISCLOSURE. For a caller acting on ANOTHER agent's row the owner/admin
+  -- check runs BEFORE the membership lookup, so an unauthorized caller cannot distinguish
+  -- P0002 'board membership not found' from 42501 and thus cannot probe whether an arbitrary
+  -- (board_id, agent_id) pair has a membership row. (The self branch legitimately learns about its
+  -- own membership, and the service path is the operator.)
+  if not v_is_service and v_actor <> p_agent_id then
+    select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+    if v_board.id is null then
+      raise exception 'board not found' using errcode = 'P0002';
+    end if;
+    select bm.role
+      into v_actor_role
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+       and bm.agent_id = v_actor
+       and bm.membership_state in ('joined', 'subscribed')
+     limit 1;
+    if v_actor_role is null or v_actor_role not in ('owner', 'admin') then
+      raise exception 'board membership change requires owner or admin role'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- (3) Pre-existing precondition, preserved. Also captures the target's CURRENT role for the
+  -- rank check below.
+  select bm.membership_state, bm.role
+    into v_existing_state, v_target_role
+    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;
+  if v_existing_state is null then
+    raise exception 'board membership not found' using errcode = 'P0002';
+  end if;
+
+  -- (4) MEMBSTATE authorization. Skipped ONLY for a genuine service_role/operator caller; every
+  -- authenticated caller (whose actor is guaranteed non-null by step 1) is gated.
+  if not v_is_service then
+    if v_actor = p_agent_id then
+      -- SELF-SERVICE. Deliberately NO board lookup on this branch: the board row is only needed
+      -- for the authority checks below, and requiring an ACTIVE board here would strand an agent
+      -- holding a live membership on an ARCHIVED board with no way to leave it (leave_board
+      -- delegates straight into this RPC, 20260512000002:154-158).
+      --
+      -- Leaving is permitted only FROM a live/pending state, and joined<->subscribed may be
+      -- toggled. Promotion INTO the board is NOT permitted — that belongs to the approval path.
+      -- The 'removed' exclusion is load-bearing: allowing removed -> left would let a kicked agent
+      -- erase the 'removed' marker (memberships are updated IN PLACE, so the row IS the record),
+      -- which is exactly the marker _redeem_invite_for_agent's R-LINK-7 defense reads
+      -- (20260724000100:323-335) — i.e. it would launder a kick into invite-link re-entry.
+      if not (
+        (p_membership_state = 'left'
+         and v_existing_state in ('joined', 'subscribed', 'invited', 'requested'))
+        or (p_membership_state in ('joined', 'subscribed')
+            and v_existing_state in ('joined', 'subscribed'))
+      ) then
+        raise exception 'self membership change not permitted; use the join/approval path'
+          using errcode = '42501';
+      end if;
+    else
+      -- ACTING ON ANOTHER AGENT'S MEMBERSHIP. The board-active check and the ACTIVE owner/admin
+      -- requirement already ran in step (2) (authority before disclosure). This RPC is the
+      -- schema's only eviction path — no sibling can move a JOINED member to removed
+      -- (resolve_board_request only resolves requested/invited, 20260725000100:212) — so it is
+      -- gated more strictly than its siblings, with NO creator exemption: a bare
+      -- created_by_agent_id is deliberately NOT sufficient. ROOMOWN seeds the creator's owner
+      -- membership at create_board time (20260723000100), so a legitimate creator holds one, while
+      -- a DEMOTED or REMOVED creator must not retain eviction power (the R-DELEG-1 lesson).
+      --
+      -- STRICT RANK SUPERIORITY (owner=4 > admin=3 > member=2 > observer=1). Without it an admin
+      -- could evict the OWNER, or admins could evict each other.
+      if agent_board._role_rank(v_actor_role)
+         <= agent_board._role_rank(coalesce(v_target_role, '')) then
+        raise exception 'board membership change requires a higher board role than the target'
+          using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  select * into v_membership
+    from agent_board._upsert_board_membership_state(
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      null,
+      p_metadata
+    );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.left_at, v_membership.updated_at;
+end;
+$$;
+
+comment on function agent_board.update_board_membership(uuid, uuid, text, jsonb) is
+  'Updates a board membership state. MEMBSTATE (#75): service_role retains full '
+  'modify-on-behalf-of; an authenticated caller with an unresolved actor fails closed (42501); a '
+  'caller acting on its OWN membership may only leave or toggle joined<->subscribed (promotion '
+  'into a board belongs to the join/approval path, so a requested/invited/left/removed principal '
+  'cannot self-approve or re-enter); a caller acting on ANOTHER agent''s membership must hold an '
+  'active owner/admin membership AND strictly higher board rank than the target (no creator '
+  'exemption: this is the only eviction path, so a demoted creator keeps no power and an admin '
+  'cannot evict the owner).';
+
+-- Re-assert grants (create or replace preserves them, but be explicit so a fresh replay is
+-- order-independent) — house convention, 20260725000100:229-232.
+revoke all on function agent_board.update_board_membership(uuid, uuid, text, jsonb) from public, anon;
+grant execute on function agent_board.update_board_membership(uuid, uuid, text, jsonb) to authenticated, service_role;

package/migrations/20260731000100_agent_board_agentsdir_column_scope.sql

@@ -0,0 +1,88 @@
+-- AGENTSDIR — stop exposing identity-linkage columns of agent_board.agents to `authenticated`.
+-- Tracks message-board#80.
+--
+-- THE DEFECT. The SELECT policy on agent_board.agents is
+--   agent_board_authenticated_select_agents USING (agent_board.current_agent_id() is not null)
+-- (20260512000003_agent_board_auth_rls.sql:48-54) — effectively TRUE for any principal that
+-- resolves to an active agent. Combined with a TABLE-LEVEL `grant select` to `authenticated` and
+-- PostgREST exposing the agent_board schema, ANY authenticated JWT reads EVERY agent row and
+-- EVERY column. Measured live as role `authenticated` with RLS enforced: 6 of 6 agents visible,
+-- 5 exposing auth_user_id.
+--
+-- Post-FEDSESSION every Portal-federated human has an agents row, so this is cross-tenant: one
+-- signed-in human enumerates every other human and agent on the deployment.
+--
+-- WHY COLUMN SCOPE, NOT ROW SCOPE. The 4-seat plan panel unanimously rejected row-scoping, and
+-- each objection was reproduced live before this migration was written:
+--   * `agents` IS the product's participant directory by contract — specs/schema.md:179 ("the
+--     canonical participant directory for both humans and automation"), and specs/read-models.md
+--     designates v_agent_dashboard the sanctioned substitute precisely so clients need not read
+--     this table. Handle/display_name are the feature, not the leak.
+--   * A co-member row predicate is DEAD CODE: board_memberships' own SELECT policy is self-scoped
+--     (20260515000000:465-472) and RLS applies inside a policy's USING expression, so a join to
+--     another agent's membership row can never match. Verified: a board owner was invisible to
+--     their own co-member.
+--   * ~18 views INNER JOIN agents, so an invisible row DELETES the row rather than hiding a name.
+--     Verified: after an author left a board, v_board_feed went 1 -> 0 — historical messages
+--     vanished for everyone still on the board. Same class would drop stranger-created `open`
+--     boards from discovery (v_board_directory) and escalations from the supervision feed
+--     (v_open_escalations).
+--   * Row scope kills invite-by-handle: resolve_agent_handle is SECURITY INVOKER and bounded by
+--     this very policy (20260727000100:119), so you could only invite people you ALREADY share a
+--     board with — which is what an invite creates.
+--   * Board co-membership is not a trust boundary anyway: a creator can force-join any agent
+--     without consent (message-board#82, verified live), so it is manufacturable in two calls.
+-- What actually leaks is IDENTITY LINKAGE, which is a column property:
+--   auth_user_id / owner_user_id  — raw auth.users UUIDs, cross-linkable to Portal identity
+--   parent_agent_id / root_agent_id — the delegation lineage graph
+--   metadata — the field LOCALAUTH deliberately keeps plaintext email OUT of precisely because
+--              this table is broadly readable (20260726000100:15-22)
+-- No view granted to `authenticated` projects ANY of those columns, and no client/CLI/MCP package
+-- reads this table directly (they go through views and RPCs) — so scoping columns removes the
+-- exposure at ~zero product risk.
+--
+-- MECHANISM NOTE (this is why the migration is shaped this way). A column-level
+-- `revoke select (col, ...)` is a NO-OP while a table-level `grant select` exists — the
+-- table-level grant covers every column, including ones added later. Verified live: the
+-- "revoke columns" form left auth_user_id readable. The table-level grant must be revoked FIRST
+-- and only the permitted columns re-granted.
+--
+-- MAINTENANCE OBLIGATION: because the grant is now an explicit column list, a future
+-- `alter table agent_board.agents add column ...` is NOT readable by `authenticated` until it is
+-- added here. That is the correct fail-closed default; a new column must be a deliberate decision.
+--
+-- NOT CHANGED: the row policy itself (unchanged — see above), the service_role ALL policy
+-- (`using (true)`), and every SECURITY DEFINER RPC (they run as the table owner, RLS- and
+-- grant-exempt, so list_board_pending_memberships et al. keep returning handles/display names).
+-- `anon` holds no grants on this table and none are added.
+--
+-- BREAKING (fail-loud, intended): `select *` on agent_board.agents as `authenticated` now raises
+-- 42501 rather than returning narrowed rows. No in-repo consumer does this; a non-SDK consumer
+-- (e.g. the Portal) doing `select=*` will break visibly rather than silently leaking.
+--
+-- Additive, forward-only. Grants/RLS only — no function, table or column changes. Writes no
+-- agent_board.schema_version (stays 8). No PostgREST reload required (no signature change), but a
+-- reload is harmless.
+
+revoke select on agent_board.agents from authenticated;
+
+grant select (
+  id,
+  handle,
+  display_name,
+  kind,
+  agent_type,
+  status,
+  created_at,
+  updated_at
+) on agent_board.agents to authenticated;
+
+comment on table agent_board.agents is
+  'Canonical participant directory for humans and automation. READ POSTURE (AGENTSDIR, #80): '
+  '`authenticated` may select ONLY the directory columns (id, handle, display_name, kind, '
+  'agent_type, status, created_at, updated_at). The identity-linkage columns — auth_user_id, '
+  'owner_user_id, parent_agent_id, root_agent_id — and metadata are NOT granted to '
+  '`authenticated`, because raw auth.users UUIDs and the delegation lineage are cross-tenant '
+  'identity linkage and metadata is an acknowledged PII-hazard field. service_role and '
+  'SECURITY DEFINER RPCs are unaffected. A NEWLY ADDED COLUMN IS NOT READABLE by `authenticated` '
+  'until explicitly granted here — fail closed by design.';