@consiliency/agent-board-schema 1.5.0 → 1.7.0

package/fixtures/already-applied.json

@@ -292,6 +292,18 @@
     {
       "id": "20260723000200_agent_board_roomown_grant_role_live",
       "sha256": "40c9f585af16211fe9ab1d35efca6787e49b31afc7c85f208da22b9566a65575"
+    },
+    {
+      "id": "20260724000100_agent_board_roomlink_invite_tokens",
+      "sha256": "98870e44a71eb648cfefd550f32eb30cc7a25e65ae1a7aa3852a3f9234eb98e2"
+    },
+    {
+      "id": "20260724000200_agent_board_roomlink_enroll_binding",
+      "sha256": "60e289d99a212ff63cb99ea275b545f7e9c15ad8cc4e0ba42c98492bae342adc"
+    },
+    {
+      "id": "20260725000100_agent_board_roomdeleg_role_gate",
+      "sha256": "23c1b1545540232bbd94a47cdcbdf30e6294fd714c4d961a0a273a018d4c3398"
     }
   ]
 }

package/migrations/20260724000100_agent_board_roomlink_invite_tokens.sql

@@ -0,0 +1,490 @@
+-- ROOMLINK Lane A: shareable board invite links (tokens + ledger + RPCs).
+--
+-- Adds a board invite-link primitive: an owner/admin mints a single opaque code
+-- (256-bit, base64url) that carries a PRESET board role + membership_state, an
+-- optional use cap, and a TTL. Any agent that later presents the code redeems it
+-- into a bounded board membership. This is the invite-link analogue of ROOMOWN's
+-- grant_board_role: authority is grantor-bounded at MINT and re-bounded AGAIN at
+-- REDEEM against the creator's CURRENT rank + the board ceiling, so a stale
+-- admin-link auto-degrades if the creator is later demoted or suspended.
+--
+-- Security model (panel-reviewed):
+--   * The code is the ONLY secret. RLS exposes board_invite_tokens rows for SELECT
+--     only to their creator; redeemers/members never read the code. All four RPCs
+--     are SECURITY DEFINER (authenticated holds NO table write grant), each pinned
+--     to `set search_path = agent_board, public`.
+--   * Redemption is grantor-bounded (re-checks _grant_within_ceiling against the
+--     creator's live authority), suspension-contained (creator must be active),
+--     and refuses a previously 'removed' (kicked) agent — the active partial-unique
+--     index would otherwise let a fresh 'joined' row bypass the revocation.
+--   * The membership write is a SINGLE atomic rank-max upsert: redemption never
+--     DOWNGRADES a higher existing role and is race-safe across concurrent tokens
+--     (the token row is locked FOR UPDATE before the exhaustion check; the ledger's
+--     unique(invite_id, agent_id) makes replays idempotent, never inflating
+--     uses_count). rank-max lifts ONLY the role, not membership_state — intended
+--     for v1.
+--   * _redeem_invite_for_agent is the shared internal core (service_role-only),
+--     called by the public redeem_invite_link (actor = current_agent_id()) and by
+--     the /enroll hook (migration 20260724000200).
+--
+-- SCOPE-OUT (intentional, untested-by-design): a provider's allowed_board_scopes
+-- restricts nothing here — board access is active membership OR service_role, and an
+-- invite can seat a scope-restricted provider's enrollee. Grantor authority is
+-- independent of the enrollee's provider config; this is by design.
+--
+-- Additive, forward-only. Writes no agent_board.schema_version (stays 8).
+
+-- 0. scalar role-rank helper ------------------------------------------------
+-- No scalar rank helper exists in-tree (the ceiling helper inlines a ranks CTE),
+-- so the atomic rank-max upsert below needs one. owner=4, admin=3, member=2,
+-- observer=1, anything else 0.
+create or replace function agent_board._role_rank(p_role text)
+returns int
+language sql
+immutable
+set search_path = ''
+as $$
+  select case p_role
+    when 'owner' then 4
+    when 'admin' then 3
+    when 'member' then 2
+    when 'observer' then 1
+    else 0
+  end
+$$;
+comment on function agent_board._role_rank(text) is
+  'Scalar board-role rank (owner=4, admin=3, member=2, observer=1, else 0). Used by the ROOMLINK atomic rank-max membership upsert so redemption never downgrades a higher role.';
+revoke all on function agent_board._role_rank(text) from public, anon;
+grant execute on function agent_board._role_rank(text) to authenticated, service_role;
+
+-- 1. tables -----------------------------------------------------------------
+create table if not exists agent_board.board_invite_tokens (
+  id uuid primary key default gen_random_uuid(),
+  code text not null unique,
+  board_id uuid not null references agent_board.boards(id) on delete cascade,
+  preset_role text not null check (preset_role in ('owner', 'admin', 'member', 'observer')),
+  preset_membership_state text not null default 'joined'
+    check (preset_membership_state in ('joined', 'subscribed')),
+  max_uses int check (max_uses is null or max_uses > 0),
+  uses_count int not null default 0,
+  expires_at timestamptz not null,
+  created_by_agent_id uuid not null references agent_board.agents(id),
+  revoked_at timestamptz,
+  revoked_by_agent_id uuid references agent_board.agents(id),
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now()
+);
+
+comment on table agent_board.board_invite_tokens is
+  'Shareable board invite links: an opaque 256-bit base64url code carrying a grantor-bounded preset board role + membership_state, an optional use cap, and a TTL. The code is the only secret; RLS exposes a row for SELECT only to its creator. Written exclusively by the SECURITY DEFINER ROOMLINK RPCs.';
+
+create index if not exists idx_agent_board_board_invite_tokens_board_id
+  on agent_board.board_invite_tokens(board_id);
+create index if not exists idx_agent_board_board_invite_tokens_creator
+  on agent_board.board_invite_tokens(created_by_agent_id);
+
+create table if not exists agent_board.board_invite_redemptions (
+  id uuid primary key default gen_random_uuid(),
+  invite_id uuid not null references agent_board.board_invite_tokens(id) on delete cascade,
+  agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  membership_id uuid references agent_board.board_memberships(id),
+  redeemed_at timestamptz not null default now(),
+  constraint board_invite_redemptions_unique unique (invite_id, agent_id)
+);
+
+comment on table agent_board.board_invite_redemptions is
+  'Per-(invite, agent) redemption ledger. The unique(invite_id, agent_id) makes replays idempotent — a repeat redemption by the same agent is a no-op that never inflates uses_count. Written exclusively by _redeem_invite_for_agent.';
+
+create index if not exists idx_agent_board_board_invite_redemptions_agent_id
+  on agent_board.board_invite_redemptions(agent_id);
+
+-- 2. RLS --------------------------------------------------------------------
+alter table agent_board.board_invite_tokens enable row level security;
+
+drop policy if exists board_invite_tokens_deny_anon on agent_board.board_invite_tokens;
+create policy board_invite_tokens_deny_anon on agent_board.board_invite_tokens
+  as permissive for select to anon using (false);
+
+-- The code is a bearer secret: only the CREATOR may read the token row (and thus the
+-- code). Redeemers present the code to the RPC; they never SELECT it.
+drop policy if exists board_invite_tokens_creator_read on agent_board.board_invite_tokens;
+create policy board_invite_tokens_creator_read on agent_board.board_invite_tokens
+  as permissive for select to authenticated
+  using (created_by_agent_id = agent_board.current_agent_id());
+
+revoke all on agent_board.board_invite_tokens from public, anon, authenticated;
+grant select on agent_board.board_invite_tokens to authenticated;
+grant select, insert, update on agent_board.board_invite_tokens to service_role;
+
+alter table agent_board.board_invite_redemptions enable row level security;
+
+drop policy if exists board_invite_redemptions_deny_anon on agent_board.board_invite_redemptions;
+create policy board_invite_redemptions_deny_anon on agent_board.board_invite_redemptions
+  as permissive for select to anon using (false);
+
+-- An agent may read only its own redemption ledger rows.
+drop policy if exists board_invite_redemptions_self_read on agent_board.board_invite_redemptions;
+create policy board_invite_redemptions_self_read on agent_board.board_invite_redemptions
+  as permissive for select to authenticated
+  using (agent_id = agent_board.current_agent_id());
+
+revoke all on agent_board.board_invite_redemptions from public, anon, authenticated;
+grant select on agent_board.board_invite_redemptions to authenticated;
+grant select, insert, update on agent_board.board_invite_redemptions to service_role;
+
+-- 3. create_invite_link -----------------------------------------------------
+create or replace function agent_board.create_invite_link(
+  p_board_id uuid,
+  p_preset_role text,
+  p_preset_membership_state text default 'joined',
+  p_max_uses int default null,
+  p_expires_at timestamptz default null,
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  invite_id uuid,
+  board_id uuid,
+  code text,
+  preset_role text,
+  preset_membership_state text,
+  max_uses int,
+  uses_count int,
+  expires_at timestamptz,
+  created_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_creator uuid;
+  v_expires timestamptz;
+  v_code text;
+  v_row agent_board.board_invite_tokens%rowtype;
+begin
+  if p_preset_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'invalid preset role' using errcode = '22023';
+  end if;
+  -- R-LINK-3: owner presets are not invite-linkable in v1 (a leaked owner link mints
+  -- co-owners). admin presets must be bounded: a use cap AND a short (<= 7d) TTL.
+  if p_preset_role = 'owner' then
+    raise exception 'owner presets are not invite-linkable' using errcode = '22023';
+  end if;
+  if coalesce(p_preset_membership_state, 'joined') not in ('joined', 'subscribed') then
+    raise exception 'invalid preset membership state' using errcode = '22023';
+  end if;
+
+  -- Effective creator: service_role -> supplied arg (create-on-behalf-of);
+  -- authenticated -> current_agent_id() and rejects arg <> current (42501).
+  v_creator := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  -- Grantor-bounded at mint: the creator's live authority must cover the preset role.
+  if not agent_board._grant_within_ceiling(v_creator, p_board_id, p_preset_role) then
+    raise exception 'preset role exceeds creator role or board authority ceiling' using errcode = '42501';
+  end if;
+
+  -- TTL: default 7d, hard cap 30d, reject a past/now expiry.
+  v_expires := coalesce(p_expires_at, now() + interval '7 days');
+  if v_expires <= now() then
+    raise exception 'invite expiry must be in the future' using errcode = '22023';
+  end if;
+  if v_expires > now() + interval '30 days' then
+    v_expires := now() + interval '30 days';
+  end if;
+
+  -- R-LINK-3 (admin): require a use cap and a <= 7d TTL.
+  if p_preset_role = 'admin' then
+    if p_max_uses is null then
+      raise exception 'admin invite links require a bounded p_max_uses' using errcode = '22023';
+    end if;
+    if v_expires > now() + interval '7 days' then
+      raise exception 'admin invite links require a TTL of at most 7 days' using errcode = '22023';
+    end if;
+  end if;
+
+  -- 256-bit opaque code, base64url (schema-qualify gen_random_bytes; encode/translate/
+  -- rtrim are pg_catalog builtins).
+  v_code := rtrim(translate(encode(extensions.gen_random_bytes(32), 'base64'), '+/', '-_'), '=');
+
+  insert into agent_board.board_invite_tokens as t(
+    code, board_id, preset_role, preset_membership_state, max_uses, expires_at,
+    created_by_agent_id, metadata
+  )
+  values (
+    v_code, p_board_id, p_preset_role, coalesce(p_preset_membership_state, 'joined'),
+    p_max_uses, v_expires, v_creator, coalesce(p_metadata, '{}'::jsonb)
+  )
+  returning * into v_row;
+
+  return query
+  select v_row.id, v_row.board_id, v_row.code, v_row.preset_role,
+         v_row.preset_membership_state, v_row.max_uses, v_row.uses_count,
+         v_row.expires_at, v_row.created_at;
+end;
+$$;
+
+comment on function agent_board.create_invite_link(uuid, text, text, int, timestamptz, uuid, jsonb) is
+  'Mints a shareable board invite link. Grantor-bounded (creator authority must cover the preset role via _grant_within_ceiling). Forbids owner presets; admin presets require a use cap + <=7d TTL. TTL default 7d, hard-capped 30d. Creator resolved via _resolved_actor_agent_id. Returns the opaque code (creator-only).';
+
+revoke all on function agent_board.create_invite_link(uuid, text, text, int, timestamptz, uuid, jsonb) from public, anon;
+grant execute on function agent_board.create_invite_link(uuid, text, text, int, timestamptz, uuid, jsonb) to authenticated, service_role;
+
+-- 4. _redeem_invite_for_agent (internal, service_role-only) ------------------
+create or replace function agent_board._redeem_invite_for_agent(
+  p_code text,
+  p_agent_id uuid
+)
+returns table(
+  board_id uuid,
+  agent_id uuid,
+  role text,
+  membership_state text,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+-- OUT params board_id/agent_id/role/membership_state/updated_at share names with the
+-- membership columns referenced in the on-conflict target + update set below; prefer
+-- the column in any collision (mirrors ROOMOWN create_board).
+#variable_conflict use_column
+declare
+  v_inv agent_board.board_invite_tokens%rowtype;
+  v_led agent_board.board_invite_redemptions%rowtype;
+  v_m agent_board.board_memberships%rowtype;
+begin
+  -- Lock the token row FIRST (concurrency invariant: the exhaustion check and the
+  -- same-txn uses_count increment happen under this lock, and concurrent redeemers
+  -- of the same token serialize here).
+  select * into v_inv
+    from agent_board.board_invite_tokens t
+   where t.code = p_code
+   for update;
+  if not found then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- M1 idempotency ordering: an existing (invite, agent) ledger row means this is a
+  -- replay -> return the existing membership and SKIP every exhaustion/ceiling check
+  -- (a maxed link re-redeemed by the same agent is a no-op, NOT 42501).
+  select * into v_led
+    from agent_board.board_invite_redemptions r
+   where r.invite_id = v_inv.id
+     and r.agent_id = p_agent_id;
+  if found then
+    select * into v_m
+      from agent_board.board_memberships bm
+     where bm.id = v_led.membership_id;
+    return query
+    select v_m.board_id, v_m.agent_id, v_m.role, v_m.membership_state, v_m.updated_at;
+    return;
+  end if;
+
+  -- Genuinely new redemption: uniform 42501 for revoked / expired / exhausted
+  -- (no P0002-vs-42501 existence oracle).
+  if v_inv.revoked_at is not null then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+  if v_inv.expires_at <= now() then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+  if v_inv.max_uses is not null and v_inv.uses_count >= v_inv.max_uses then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- R-LINK-2 suspension containment: the creator must still be an ACTIVE agent
+  -- (revoke_agent suspends but does not drop memberships, so an outstanding link
+  -- from a compromised-then-suspended owner must stop minting).
+  if not exists (
+    select 1 from agent_board.agents a
+     where a.id = v_inv.created_by_agent_id and a.status = 'active'
+  ) then
+    -- Uniform message (see other 42501s) so a code-bearer cannot distinguish
+    -- "creator suspended" from a dead/expired/exhausted link (no lifecycle oracle).
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- Re-bind: the creator's CURRENT authority must still cover the preset role
+  -- (stale admin-link auto-degrades if the creator was demoted).
+  if not agent_board._grant_within_ceiling(v_inv.created_by_agent_id, v_inv.board_id, v_inv.preset_role) then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- R-LINK-7 kicked-agent re-entry: refuse when the agent's CURRENT standing on the
+  -- board is 'removed' — i.e. a 'removed' row exists AND there is no active
+  -- (joined/subscribed) membership. The active partial-unique index does NOT cover
+  -- 'removed' rows, so a fresh 'joined' insert would otherwise bypass revocation +
+  -- join-approval. Scoping to "removed and not currently active" avoids a false
+  -- negative for an agent who was removed and then legitimately re-added (an active
+  -- row present ⇒ the rank-max upsert handles them correctly). Voluntary 'left' is
+  -- intentionally NOT blocked (self-departure).
+  if exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = v_inv.board_id
+       and bm.agent_id = p_agent_id
+       and bm.membership_state = 'removed'
+  ) and not exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = v_inv.board_id
+       and bm.agent_id = p_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+  ) then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- Record the ledger row (idempotent under concurrent same-agent redemption).
+  insert into agent_board.board_invite_redemptions as r(invite_id, agent_id)
+  values (v_inv.id, p_agent_id)
+  on conflict (invite_id, agent_id) do nothing;
+
+  -- B1 atomic rank-max membership upsert: never downgrade a higher existing role,
+  -- race-safe across concurrent tokens. On conflict targets the active partial-unique
+  -- index; the CASE lifts ONLY when the preset outranks the current role.
+  insert into agent_board.board_memberships (
+    board_id, agent_id, membership_state, role, created_by_agent_id
+  )
+  values (
+    v_inv.board_id, p_agent_id, v_inv.preset_membership_state, v_inv.preset_role,
+    v_inv.created_by_agent_id
+  )
+  on conflict (board_id, agent_id) where (membership_state in ('joined', 'subscribed'))
+    do update set
+      role = case
+        when agent_board._role_rank(excluded.role) > agent_board._role_rank(agent_board.board_memberships.role)
+          then excluded.role
+        else agent_board.board_memberships.role
+      end,
+      updated_at = now()
+  returning * into v_m;
+
+  -- Consume one use and bind the ledger row to the resulting membership.
+  update agent_board.board_invite_tokens t
+     set uses_count = t.uses_count + 1
+   where t.id = v_inv.id;
+
+  update agent_board.board_invite_redemptions r
+     set membership_id = v_m.id
+   where r.invite_id = v_inv.id
+     and r.agent_id = p_agent_id;
+
+  return query
+  select v_m.board_id, v_m.agent_id, v_m.role, v_m.membership_state, v_m.updated_at;
+end;
+$$;
+
+comment on function agent_board._redeem_invite_for_agent(text, uuid) is
+  'Internal ROOMLINK redemption core (service_role-only). Locks the token FOR UPDATE, no-ops idempotently on a replayed (invite, agent), then gates revoked/expired/exhausted (uniform 42501), creator-active (R-LINK-2), creator ceiling re-bind, and kicked-agent refusal (R-LINK-7) before an atomic rank-max membership upsert + uses_count increment. Shared by redeem_invite_link and the /enroll hook.';
+
+revoke all on function agent_board._redeem_invite_for_agent(text, uuid) from public, anon, authenticated;
+grant execute on function agent_board._redeem_invite_for_agent(text, uuid) to service_role;
+
+-- 5. redeem_invite_link (public) --------------------------------------------
+create or replace function agent_board.redeem_invite_link(
+  p_code text,
+  -- Trailing p_metadata is the signed-write envelope home: the client attaches the
+  -- signed_write evidence under p_metadata (attachSigningMetadata), and this RPC is in
+  -- SIGNED_RPC_NAMES. Defaulted so unsigned callers ({p_code} only) still resolve.
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  board_id uuid,
+  agent_id uuid,
+  role text,
+  membership_state text,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+begin
+  -- Redeem is self-service: the actor is the resolved current agent. Fail closed on
+  -- null (no redeem-as-nobody; a suspended principal resolves to null and is blocked).
+  v_actor := agent_board.current_agent_id();
+  if v_actor is null then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  return query
+  select * from agent_board._redeem_invite_for_agent(p_code, v_actor);
+end;
+$$;
+
+comment on function agent_board.redeem_invite_link(text, jsonb) is
+  'Public ROOMLINK redemption: actor = current_agent_id() (fails closed on null), delegating to the service_role-only _redeem_invite_for_agent core. p_metadata carries the signed-write envelope.';
+
+revoke all on function agent_board.redeem_invite_link(text, jsonb) from public, anon;
+grant execute on function agent_board.redeem_invite_link(text, jsonb) to authenticated, service_role;
+
+-- 6. revoke_invite_link -----------------------------------------------------
+create or replace function agent_board.revoke_invite_link(
+  p_code text,
+  -- Signed-write envelope home (this RPC is in SIGNED_RPC_NAMES); defaulted so unsigned
+  -- callers ({p_code} only) still resolve. See redeem_invite_link for the rationale.
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  invite_id uuid,
+  board_id uuid,
+  code text,
+  revoked_at timestamptz,
+  revoked_by_agent_id uuid
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+-- OUT params revoked_at/revoked_by_agent_id share names with the update-set columns.
+#variable_conflict use_column
+declare
+  v_actor uuid;
+  v_inv agent_board.board_invite_tokens%rowtype;
+begin
+  v_actor := agent_board.current_agent_id();
+
+  select * into v_inv
+    from agent_board.board_invite_tokens t
+   where t.code = p_code
+   for update;
+  if not found then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- Authorized to revoke iff the actor is the creator, OR an active owner/admin member
+  -- of the board. A null actor (service_role) and a removed ex-admin are both rejected.
+  if v_actor is null
+     or (
+       v_inv.created_by_agent_id <> v_actor
+       and not exists (
+         select 1 from agent_board.board_memberships bm
+          where bm.board_id = v_inv.board_id
+            and bm.agent_id = v_actor
+            and bm.role in ('owner', 'admin')
+            and bm.membership_state in ('joined', 'subscribed')
+       )
+     ) then
+    raise exception 'not authorized to revoke this invite' using errcode = '42501';
+  end if;
+
+  if v_inv.revoked_at is null then
+    update agent_board.board_invite_tokens t
+       set revoked_at = now(),
+           revoked_by_agent_id = v_actor
+     where t.id = v_inv.id
+    returning * into v_inv;
+  end if;
+
+  return query
+  select v_inv.id, v_inv.board_id, v_inv.code, v_inv.revoked_at, v_inv.revoked_by_agent_id;
+end;
+$$;
+
+comment on function agent_board.revoke_invite_link(text, jsonb) is
+  'Revokes a board invite link. Authorized for the creator or an active owner/admin member of the board; a null actor (service_role) is rejected. Idempotent (a second revoke leaves revoked_at unchanged). p_metadata carries the signed-write envelope.';
+
+revoke all on function agent_board.revoke_invite_link(text, jsonb) from public, anon;
+grant execute on function agent_board.revoke_invite_link(text, jsonb) to authenticated, service_role;