@consiliency/agent-board-schema 1.10.0 → 1.12.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Canonical, immutable, exact-pinnable agent_board schema bundle: ordered SQL migrations, digest + compatibility manifest, and deterministic materialize/plan/check tooling for adopters.",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",

package/schema-manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent_board_schema_manifest.v1",
   "interface": "IF-0-MBPLANE-BUNDLE-1",
   "package": "@consiliency/agent-board-schema",
-  "packageVersion": "1.10.0",
+  "packageVersion": "1.12.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 79,
-  "aggregateSha256": "6e82ca1943a3848b3f7c871e97cdf82387194ac361e965111785e236a0e850fd",
+  "migrationCount": 82,
+  "aggregateSha256": "f6248b647fc1de859d68650ad8f9e88964820642da712893476429a4edb341f9",
   "migrations": [
     {
       "order": 0,
@@ -759,6 +759,33 @@
       "sourceRef": "message-board",
       "bytes": 15404,
       "sha256": "5f300449c29ec05c2cd3c2cd7eca622ca41e8b32b8856c5bc0695b5750a196e7"
+    },
+    {
+      "order": 79,
+      "id": "20260729000100_agent_board_fedsession_autojoin_default_board",
+      "filename": "20260729000100_agent_board_fedsession_autojoin_default_board.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 18252,
+      "sha256": "6f3a2db6c7349119b3893fe530788236ef5ccf4e6b0f3e21235497b8b7b232c0"
+    },
+    {
+      "order": 80,
+      "id": "20260730000100_agent_board_gatenull_service_role_bypass",
+      "filename": "20260730000100_agent_board_gatenull_service_role_bypass.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 17187,
+      "sha256": "db8b2a93996c1d61bd34fc58a5e4b3056563c53bb2eb20cbb4a3b0b799a0d91e"
+    },
+    {
+      "order": 81,
+      "id": "20260730000200_agent_board_membstate_authz",
+      "filename": "20260730000200_agent_board_membstate_authz.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 11567,
+      "sha256": "a4d935614f970a946f27a5925c0166e1d41510a82078e559fb769f4ea39afc2e"
     }
   ],
   "excludedBridge": {

package/src/tooling.test.mjs

@@ -37,9 +37,9 @@ describe('manifest integrity', () => {
     expect(manifest.schemaVersion).toBe(8);
     expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
   });
-  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION forward migrations (migrationCount = prior 78 + 1 = 79)', () => {
+  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE forward migrations (migrationCount = prior 80 + 2 = 82)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(79);
+    expect(manifest.migrationCount).toBe(82);
     // MBSESSION switched enforcement on (scoped-send re-grant): the client-visible
     // schema version bumped to 8. MBDELEG tightens delegation and MBFED adds only
     // enrollment-only additive surface (identity_providers registry, enrollment audit,
@@ -95,6 +95,16 @@ describe('manifest integrity', () => {
       // backing the /portal-session Option A self-signed access-token minter. Additive
       // (adds a nullable mode column to enrollment_federation_audit); schema stays 8.
       '20260728000100_agent_board_enroll_federated_human.sql',
+      // FEDSESSION-AUTOJOIN: per-issuer default_board_id + auto-join a fresh fed-human to it
+      // (baseline member, first-time-only, non-fatal) inside enroll_federated_human. Additive;
+      // schema stays 8.
+      '20260729000100_agent_board_fedsession_autojoin_default_board.sql',
+      // GATENULL (#58): service_role-bypass hardening — an authenticated principal with no
+      // ACTIVE agent no longer takes the null-actor bypass on the four board-mutating RPCs.
+      '20260730000100_agent_board_gatenull_service_role_bypass.sql',
+      // MEMBSTATE (#75): update_board_membership gains an authorization model (it previously
+      // had none) — self-service transitions only, owner/admin for another agent's row.
+      '20260730000200_agent_board_membstate_authz.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }