@consiliency/agent-board-schema 1.7.0 → 1.9.0

package/fixtures/already-applied.json

@@ -304,6 +304,14 @@
     {
       "id": "20260725000100_agent_board_roomdeleg_role_gate",
       "sha256": "23c1b1545540232bbd94a47cdcbdf30e6294fd714c4d961a0a273a018d4c3398"
+    },
+    {
+      "id": "20260726000100_agent_board_localauth_self_enroll",
+      "sha256": "38bcc86f0e6d4ad38bc76f5abe719456f5faa2ac5bd2ab24813c61d0160da664"
+    },
+    {
+      "id": "20260727000100_agent_board_roomuiapi",
+      "sha256": "9c938c40115aa25f464bbb9d177f9f85214fb84f7b37abe5ae9df5b6a2485141"
     }
   ]
 }

package/migrations/20260726000100_agent_board_localauth_self_enroll.sql

@@ -0,0 +1,172 @@
+-- LOCALAUTH: Portal-free standalone human self-enrollment.
+--
+-- WHAT: self_enroll_human() lets a browser human who has signed in with the
+-- target Supabase project's OWN auth (magic-link/OTP/OAuth/passkey) bind their
+-- auth.uid() to a kind='human' agent_board.agents row from their own
+-- authenticated session — no Portal, no service_role, no operator step per user.
+--
+-- IDENTITY MODEL: the human is SELF-owned (owner_user_id = auth_user_id =
+-- auth.uid()). Contrast enroll_federated_identity, where auth_user_id is a
+-- synthetic per-agent uid and owner_user_id is the real human. The only trusted
+-- identity input is auth.uid(); there is NO auth_user_id/agent_id argument, so a
+-- caller cannot self-assign someone else's identity. Spoofing auth.uid() would
+-- require the JWT-signing secret or the service_role key — that is inherent to
+-- Supabase, not a boundary introduced here.
+--
+-- PII: metadata.localauth stores ONLY a boolean email_verified (derived from
+-- auth.users.email_confirmed_at), never the plaintext email. The agents SELECT
+-- RLS is not row-scoped, so a stored email would be a fleet-wide harvestable
+-- directory. The canonical human email lives in auth.users (bound via the
+-- agent's auth_user_id); an IDLINK flow reads it there via service_role AND MUST
+-- RE-VERIFY email ownership at link time (email_confirmed_at can be admin- or
+-- auto-set, so it is not by itself proof of possession).
+--
+-- OPERATOR / SCOPE (L-10): enabling a Supabase Auth sign-in method in the target
+-- project is a net-new OPERATOR config task. The sign-in UI / browser app is
+-- EXTERNAL / consumer-owned — there is no in-repo frontend. LOCALAUTH ships the
+-- RPC + the zero-node `@consiliency/agent-board-client/localauth` helper ONLY.
+--
+-- Additive, forward-only. Writes no schema_version (stays 8).
+
+create or replace function agent_board.self_enroll_human(
+  p_display_name text default null
+)
+returns table(
+  agent_id uuid,
+  handle text,
+  kind text,
+  status text,
+  auth_user_id uuid,
+  created_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_uid uuid := auth.uid();
+  v_existing agent_board.agents%rowtype;
+  v_email_confirmed_at timestamptz;
+  v_email_verified boolean;
+  v_handle text;
+  v_agent agent_board.agents%rowtype;
+begin
+  -- Fail closed: no authenticated Supabase user -> no identity to bind. This also
+  -- covers service_role and any superuser/operator path (auth.uid() is null for
+  -- them), which is intentional: LOCALAUTH is a self-service authenticated path.
+  if v_uid is null then
+    raise exception 'self_enroll_human requires an authenticated Supabase user (auth.uid() is null)'
+      using errcode = '42501';
+  end if;
+
+  -- Idempotency + no-self-reactivation guard, keyed on auth_user_id (ANY status).
+  -- An ACTIVE row -> return it (idempotent, no duplicate). A NON-active row
+  -- (status <> 'active', i.e. inactive or suspended per the agents status enum)
+  -- -> fail closed: a deactivated/suspended human must NOT self-reactivate; an
+  -- operator must restore them.
+  select * into v_existing
+    from agent_board.agents a
+   where a.auth_user_id = v_uid
+   order by (a.status = 'active') desc, a.created_at asc
+   limit 1;
+  if found then
+    if v_existing.status = 'active' then
+      return query
+      select v_existing.id, v_existing.handle, v_existing.kind::text,
+             v_existing.status, v_existing.auth_user_id, v_existing.created_at;
+      return;
+    else
+      raise exception 'a non-active identity already exists for this user; contact an operator'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- Verified-email as a BOOLEAN only. Read email_confirmed_at server-side (never
+  -- trust an unverified JWT email claim); store the derived boolean, never the
+  -- address.
+  select u.email_confirmed_at into v_email_confirmed_at
+    from auth.users u
+   where u.id = v_uid;
+  v_email_verified := v_email_confirmed_at is not null;
+
+  -- Deterministic globally-unique handle: 16 hex (64-bit) of sha256(uid).
+  v_handle := 'local-human-' || substr(encode(extensions.digest(v_uid::text, 'sha256'), 'hex'), 1, 16);
+
+  begin
+    insert into agent_board.agents(
+      agent_type,
+      kind,
+      handle,
+      display_name,
+      status,
+      auth_user_id,
+      owner_user_id,
+      metadata
+    )
+    values (
+      'human',
+      'human'::agent_board.agent_kind,
+      v_handle,
+      coalesce(nullif(trim(p_display_name), ''), 'Human'),
+      'active',
+      v_uid,
+      v_uid,
+      jsonb_build_object(
+        'localauth', jsonb_build_object(
+          'self_enrolled_at', now(),
+          'email_verified', v_email_verified
+        )
+      )
+    )
+    returning * into v_agent;
+  exception when unique_violation then
+    -- Concurrent first-enroll race: another session inserted the active row for
+    -- this uid between our select and insert. Re-select and return it.
+    select * into v_existing
+      from agent_board.agents a
+     where a.auth_user_id = v_uid
+       and a.status = 'active'
+     limit 1;
+    if found then
+      return query
+      select v_existing.id, v_existing.handle, v_existing.kind::text,
+             v_existing.status, v_existing.auth_user_id, v_existing.created_at;
+      return;
+    end if;
+    -- Not the uid race -> a genuine handle collision (astronomically rare for a
+    -- 64-bit hash). Surface a clean, distinct, retryable error rather than the
+    -- opaque raw unique_violation.
+    raise exception 'could not self-enroll (handle collision), please retry'
+      using errcode = '40001';
+  end;
+
+  return query
+  select v_agent.id, v_agent.handle, v_agent.kind::text,
+         v_agent.status, v_agent.auth_user_id, v_agent.created_at;
+end;
+$$;
+
+comment on function agent_board.self_enroll_human(text) is
+  'Portal-free self-service: binds auth.uid() to a kind=human agent (self-owned: '
+  'owner_user_id = auth_user_id = auth.uid()). Idempotent for an active identity; '
+  'a non-active identity fails closed (42501, no self-reactivation). Stores only a '
+  'BOOLEAN metadata.localauth.email_verified (never the plaintext email). Fails '
+  'closed with 42501 when auth.uid() is null (unauthenticated / service_role / '
+  'operator). authenticated-only; not a signed write.';
+
+-- authenticated-only. service_role is explicitly revoked (belt-and-suspenders on
+-- top of the auth.uid()-null fail-close): the service path is
+-- enroll_federated_identity, not this self-service RPC.
+revoke all on function agent_board.self_enroll_human(text) from public, anon, service_role;
+grant execute on function agent_board.self_enroll_human(text) to authenticated;
+
+-- L-4b DB backstop: one agent per REAL auth user, enforced at the DB (not just the
+-- app guard above). SAFE because federated agents use SYNTHETIC per-agent uids
+-- (_ensure_agent_auth_user), so only real-uid rows are ever constrained. This is a
+-- DIFFERENT guarantee than the pre-existing partial-unique
+-- idx_agent_board_agents_auth_user_id_active_unique (which is scoped to
+-- status='active'); this one admits at most one row per uid EVER. On real data a
+-- failure here means a genuine duplicate — correct fail-loud.
+create unique index if not exists idx_agent_board_agents_auth_user_id_unique
+  on agent_board.agents(auth_user_id)
+  where auth_user_id is not null;

package/migrations/20260727000100_agent_board_roomuiapi.sql

@@ -0,0 +1,122 @@
+-- ROOMUIAPI: two read RPCs the room console/CLI need. Additive, no schema_version
+-- bump (stays 8). Adds:
+--   * agent_board.list_board_pending_memberships(p_board_id) — owner/admin-gated
+--     reader that returns the board's pending (requested + invited) memberships,
+--     latest-row-per-agent. board_memberships SELECT RLS is self-scoped, so a board
+--     owner/admin cannot see EITHER pending state today; this reader is the sole
+--     window. FLAT owner/admin gate ALWAYS, fail-closed on a null actor (mirrors
+--     set_board_role_gate 20260725000100:46-55; NOT the write-RPC `if v_actor is not
+--     null` bypass). Deliberately STRICTER than resolve_board_request: enumerating
+--     requesters is disclosure, so no creator-identity exemption and no gate-off
+--     relaxation. service_role (current_agent_id() = null) hits 42501 here; operators
+--     read the table directly, bypassing RLS.
+--   * agent_board.resolve_agent_handle(p_handle) — SECURITY INVOKER handle->identity
+--     resolver. Runs under caller RLS, so by construction it cannot exceed
+--     agent_board_authenticated_select_agents (20260512000003:49-54, which already
+--     lets any authenticated active agent read every handle) — zero new exposure. The
+--     status='active' filter is a UI affordance (invite accepts any status), not a
+--     security boundary. Returns 0-or-1 row.
+
+-- 1. list_board_pending_memberships (owner/admin-gated pending reader) --------------
+create or replace function agent_board.list_board_pending_memberships(
+  p_board_id uuid
+)
+returns table(
+  membership_id uuid,
+  board_id uuid,
+  agent_id uuid,
+  handle text,
+  display_name text,
+  agent_type text,
+  membership_state text,
+  role text,
+  created_by_agent_id uuid,
+  requested_at timestamptz,
+  updated_at timestamptz
+)
+language plpgsql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- FLAT owner/admin gate, ALWAYS. Fail closed on a null actor (suspended/unmapped
+  -- principal, or service_role) — mirrors set_board_role_gate, NOT the write-RPC
+  -- `if v_actor is not null` bypass. Authz precedes disclosure.
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role in ('owner', 'admin')
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner or admin may list pending memberships' using errcode = '42501';
+  end if;
+
+  -- Latest row per agent (in-place upserts append; the newest created_at is current
+  -- state), scoped to this board, filtered to the pending set. The dedup subquery is
+  -- ALSO scoped to p_board_id so no other board's rows can leak in.
+  return query
+  select
+    latest.id,
+    latest.board_id,
+    latest.agent_id,
+    a.handle,
+    a.display_name,
+    a.agent_type,
+    latest.membership_state,
+    latest.role,
+    latest.created_by_agent_id,
+    latest.created_at as requested_at,
+    latest.updated_at
+  from (
+    select distinct on (bm.agent_id) bm.*
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+     order by bm.agent_id, bm.created_at desc
+  ) latest
+  join agent_board.agents a on a.id = latest.agent_id
+  where latest.membership_state in ('requested', 'invited')
+  order by latest.created_at desc;
+end;
+$$;
+
+comment on function agent_board.list_board_pending_memberships(uuid) is
+  'Owner/admin-gated reader for a board''s pending (requested + invited) memberships, latest-row-per-agent. FLAT owner/admin gate ALWAYS, fail-closed on a null actor (else 42501). Board-scoped: gate + dedup subquery both filter p_board_id. service_role hits 42501 (null current_agent_id()); operators read the table directly.';
+
+revoke all on function agent_board.list_board_pending_memberships(uuid) from public, anon;
+grant execute on function agent_board.list_board_pending_memberships(uuid) to authenticated, service_role;
+
+-- 2. resolve_agent_handle (SECURITY INVOKER handle resolver) ------------------------
+create or replace function agent_board.resolve_agent_handle(
+  p_handle text
+)
+returns table(
+  agent_id uuid,
+  handle text,
+  display_name text,
+  agent_type text
+)
+language sql
+stable
+security invoker
+set search_path = agent_board, public
+as $$
+  -- limit 1 is deterministic only via the UNIQUE handle constraint
+  -- (20260502000000:8); at most one active agent can own a given handle.
+  select a.id, a.handle, a.display_name, a.agent_type
+    from agent_board.agents a
+   where a.handle = p_handle
+     and a.status = 'active'
+   limit 1;
+$$;
+
+comment on function agent_board.resolve_agent_handle(text) is
+  'SECURITY INVOKER handle->identity resolver: returns the 0-or-1 active agent for a handle, under caller RLS (cannot exceed agent_board_authenticated_select_agents). status=active is a UI affordance, not a security boundary. limit 1 deterministic via the UNIQUE handle constraint.';
+
+revoke all on function agent_board.resolve_agent_handle(text) from public, anon;
+grant execute on function agent_board.resolve_agent_handle(text) to authenticated, service_role;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.7.0",
+  "version": "1.9.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.7.0",
+  "packageVersion": "1.9.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 76,
-  "aggregateSha256": "fca8d220460ac16309d9a2d76cfa6f9ccc395e1c52c90c7cbd4bd5f04bbc42dc",
+  "migrationCount": 78,
+  "aggregateSha256": "4b6a5435c11341549636dfec4273c5bdc5773be23f8b8667ea816927e9412f87",
   "migrations": [
     {
       "order": 0,
@@ -732,6 +732,24 @@
       "sourceRef": "message-board",
       "bytes": 9521,
       "sha256": "23c1b1545540232bbd94a47cdcbdf30e6294fd714c4d961a0a273a018d4c3398"
+    },
+    {
+      "order": 76,
+      "id": "20260726000100_agent_board_localauth_self_enroll",
+      "filename": "20260726000100_agent_board_localauth_self_enroll.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 7323,
+      "sha256": "38bcc86f0e6d4ad38bc76f5abe719456f5faa2ac5bd2ab24813c61d0160da664"
+    },
+    {
+      "order": 77,
+      "id": "20260727000100_agent_board_roomuiapi",
+      "filename": "20260727000100_agent_board_roomuiapi.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 5217,
+      "sha256": "9c938c40115aa25f464bbb9d177f9f85214fb84f7b37abe5ae9df5b6a2485141"
     }
   ],
   "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 forward migrations (migrationCount = prior 75 + 1 = 76)', () => {
+  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 forward migrations (migrationCount = prior 77 + 1 = 78)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(76);
+    expect(manifest.migrationCount).toBe(78);
     // 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,
@@ -84,6 +84,13 @@ describe('manifest integrity', () => {
       // ROOMDELEG Lane A: owner-gated set_board_role_gate + creator-identity gate-bypass
       // fix on invite_board_member/resolve_board_request. schema stays 8.
       '20260725000100_agent_board_roomdeleg_role_gate.sql',
+      // LOCALAUTH: Portal-free standalone human self-enroll (self_enroll_human RPC +
+      // one-agent-per-real-auth-user backstop). schema stays 8.
+      '20260726000100_agent_board_localauth_self_enroll.sql',
+      // ROOMUIAPI: two read RPCs for the room console/CLI (owner/admin-gated
+      // list_board_pending_memberships + SECURITY INVOKER resolve_agent_handle).
+      // schema stays 8.
+      '20260727000100_agent_board_roomuiapi.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }

package/tests/agent_board_localauth.test.sql

@@ -0,0 +1,171 @@
+-- LOCALAUTH pgTAP: self_enroll_human() — Portal-free human self-enrollment.
+--
+-- Harness mirrors agent_board_authbound_boundary.test.sql: seed auth.users via
+-- public.ensure_github_user, fake an authenticated caller with
+--   set local role authenticated + set_config('request.jwt.claim.sub', <uid>),
+-- so auth.uid() = sub. reset role -> superuser (auth.uid() null / service_role).
+--
+-- CRITICAL harness notes:
+--  * L-7: `reset role` does NOT null auth.uid(); request.jwt.claim.sub is set
+--    is_local=true and PERSISTS. Cases 12/13 explicitly clear the sub GUC before
+--    asserting 42501, else the RPC finds the prior uid's agent (vacuous pass).
+--  * L-8: ensure_github_user sets email_confirmed_at = now() unconditionally, so
+--    the unverified case nulls it first.
+
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(17);
+
+-- ---------------------------------------------------------------------------
+-- Phase 0 (superuser): function metadata + seed
+-- ---------------------------------------------------------------------------
+
+-- 1
+select has_function('agent_board', 'self_enroll_human', array['text'], 'self_enroll_human(text) exists');
+-- 2
+select function_privs_are('agent_board', 'self_enroll_human', array['text'], 'authenticated', array['EXECUTE'],
+  'authenticated may EXECUTE self_enroll_human');
+-- 3
+select function_privs_are('agent_board', 'self_enroll_human', array['text'], 'anon', array[]::text[],
+  'anon may NOT EXECUTE self_enroll_human');
+
+create temp table _lfix (
+  user_a uuid,
+  user_b uuid,
+  user_c uuid,
+  agent_a uuid,
+  agent_a2 uuid
+) on commit drop;
+grant all on table _lfix to authenticated, service_role;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_a uuid;
+  v_b uuid;
+  v_c uuid;
+begin
+  -- verified user (email_confirmed_at defaults to now())
+  v_a := public.ensure_github_user(
+    'localauth-a-' || v_suffix,
+    'localauth-a-' || v_suffix || '@example.test',
+    'localauth-a-' || v_suffix,
+    'LOCALAUTH A ' || v_suffix);
+
+  -- unverified user: L-8 — null out the unconditionally-set email_confirmed_at
+  v_b := public.ensure_github_user(
+    'localauth-b-' || v_suffix,
+    'localauth-b-' || v_suffix || '@example.test',
+    'localauth-b-' || v_suffix,
+    'LOCALAUTH B ' || v_suffix);
+  update auth.users set email_confirmed_at = null where id = v_b;
+
+  -- user with a pre-existing SUSPENDED human agent (no self-reactivation case)
+  v_c := public.ensure_github_user(
+    'localauth-c-' || v_suffix,
+    'localauth-c-' || v_suffix || '@example.test',
+    'localauth-c-' || v_suffix,
+    'LOCALAUTH C ' || v_suffix);
+  insert into agent_board.agents(agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values ('human', 'human', 'localauth-suspended-' || v_suffix, 'Suspended Human', 'suspended', v_c, v_c);
+
+  insert into _lfix(user_a, user_b, user_c) values (v_a, v_b, v_c);
+end
+$$;
+
+-- ---------------------------------------------------------------------------
+-- Phase 1 (authenticated as user_a): enroll + auth-context assertions
+-- ---------------------------------------------------------------------------
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select user_a::text from _lfix), true);
+
+do $$
+declare
+  v_first uuid;
+  v_second uuid;
+begin
+  select s.agent_id into v_first from agent_board.self_enroll_human('Alice') s;
+  -- idempotent second call for the same uid returns the SAME agent
+  select s.agent_id into v_second from agent_board.self_enroll_human('Alice Again') s;
+  update _lfix set agent_a = v_first, agent_a2 = v_second;
+end
+$$;
+
+-- 4 (part 1 of case 8): current_agent_id() resolves to the freshly-enrolled agent
+select is(agent_board.current_agent_id(), (select agent_a from _lfix),
+  'current_agent_id() (no agent_credential_id claim) resolves to the self-enrolled agent');
+-- 5 (case 9): idempotent — second enroll returned the same agent_id
+select is((select agent_a2 from _lfix), (select agent_a from _lfix),
+  'second self_enroll_human for the same uid is idempotent (same agent_id)');
+
+-- ---------------------------------------------------------------------------
+-- Phase 2 (authenticated as user_b): enroll unverified user
+-- ---------------------------------------------------------------------------
+select set_config('request.jwt.claim.sub', (select user_b::text from _lfix), true);
+select agent_board.self_enroll_human(null);
+
+-- ---------------------------------------------------------------------------
+-- Phase 3 (superuser): row-shape assertions without RLS in the way
+-- ---------------------------------------------------------------------------
+reset role;
+
+-- 6/7/8 (case 4): the enrolled row is a human bound to the uid
+select is((select kind::text from agent_board.agents where id = (select agent_a from _lfix)),
+  'human', 'self-enrolled agent kind = human');
+select is((select agent_type from agent_board.agents where id = (select agent_a from _lfix)),
+  'human', 'self-enrolled agent agent_type = human');
+select is((select auth_user_id from agent_board.agents where id = (select agent_a from _lfix)),
+  (select user_a from _lfix), 'self-enrolled agent auth_user_id = auth.uid()');
+-- 9 (case 5): self-owned
+select is((select owner_user_id from agent_board.agents where id = (select agent_a from _lfix)),
+  (select user_a from _lfix), 'self-enrolled agent owner_user_id = auth.uid() (self-owned)');
+-- 10 (case 6): active
+select is((select status from agent_board.agents where id = (select agent_a from _lfix)),
+  'active', 'self-enrolled agent status = active');
+-- 11 (case 7): verified user -> email_verified BOOLEAN true (never a plaintext email)
+select is((select metadata->'localauth'->>'email_verified' from agent_board.agents where id = (select agent_a from _lfix)),
+  'true', 'verified user -> metadata.localauth.email_verified = true');
+-- 12 (case 10): exactly one active row for the uid
+select is((select count(*) from agent_board.agents where auth_user_id = (select user_a from _lfix) and status = 'active'),
+  1::bigint, 'exactly one active agent per uid');
+-- 13 (case 11): unverified user -> email_verified BOOLEAN false
+select is((select metadata->'localauth'->>'email_verified' from agent_board.agents where auth_user_id = (select user_b from _lfix)),
+  'false', 'unverified user -> metadata.localauth.email_verified = false');
+-- 14 (case 15 / L-4b): the DB backstop unique index exists
+select ok(exists(
+  select 1 from pg_indexes
+   where schemaname = 'agent_board'
+     and indexname = 'idx_agent_board_agents_auth_user_id_unique'),
+  'L-4b one-agent-per-real-auth-user backstop index exists');
+
+-- ---------------------------------------------------------------------------
+-- Phase 4: fail-closed cases
+-- ---------------------------------------------------------------------------
+
+-- 15 (case 12): authenticated role but NO subject (L-7: clear the sub GUC) -> 42501
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', '', true);
+select throws_ok($$ select agent_board.self_enroll_human(null) $$, '42501',
+  null, 'unauthenticated (no auth.uid()) is rejected with 42501');
+
+-- 16 (case 13): service-role / superuser (reset role) + cleared sub -> 42501
+reset role;
+select set_config('request.jwt.claim.sub', '', true);
+select throws_ok($$ select agent_board.self_enroll_human(null) $$, '42501',
+  null, 'service-role / superuser (auth.uid() null) is rejected with 42501');
+
+-- 17 (case 14): a pre-existing non-active identity cannot self-reactivate -> 42501
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select user_c::text from _lfix), true);
+select throws_ok($$ select agent_board.self_enroll_human(null) $$, '42501',
+  null, 'a suspended (non-active) identity cannot self-reactivate (42501)');
+
+select finish();
+
+rollback;

package/tests/agent_board_roomuiapi.test.sql

@@ -0,0 +1,225 @@
+-- ROOMUIAPI pgTAP: owner/admin-gated list_board_pending_memberships reader +
+-- SECURITY INVOKER resolve_agent_handle resolver.
+--
+-- Runs as the postgres db role; request.jwt.claim.role toggles _is_service_role()
+-- ('authenticated' => false) and request.jwt.claim.sub picks the acting agent.
+-- Fixture style mirrors agent_board_roomdeleg.test.sql (ensure_github_user,
+-- set_config role/sub, suspended-agent-as-null-actor trick).
+--
+-- Pending fixture rows (requested/invited/admin/board-B/dedup/demote-leave) are
+-- seeded by DIRECT INSERT into board_memberships (runs as postgres, bypassing RLS +
+-- the owner-gate coupling of request_join_board/invite_board_member). The owner
+-- membership comes from create_board's ROOMOWN seed.
+--
+-- HAND-COUNTED plan: R1,R2,R3,R4,R5,R6,R7,R8,U-4,H1,H2,H3 = 12 assertions, one each.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(12);
+
+create temp table _roomuiapi_fixture (
+  board_a uuid,
+  board_b uuid,
+  alice uuid,            -- creator, seeded owner of board A (and B)
+  admin uuid,            -- role 'admin' on board A
+  plainmember uuid,      -- role 'member', joined on board A (PRIVACY CRUX actor)
+  nomember uuid,         -- active agent, no membership on board A
+  suspended uuid,        -- suspended agent WITH a valid auth user (null actor)
+  demoteleave uuid,      -- current row role=member/state=left (U-4 gate reject)
+  requester uuid,        -- pending 'requested' on board A
+  invitee uuid,          -- pending 'invited' on board A
+  dedup uuid,            -- older 'requested' + newer 'joined' (R8: not returned)
+  boardb_requester uuid, -- pending 'requested' on board B (R7 isolation)
+  requester_handle text,
+  suspended_handle text,
+  alice_user uuid,
+  admin_user uuid,
+  plainmember_user uuid,
+  nomember_user uuid,
+  suspended_user uuid,
+  demoteleave_user uuid
+) on commit drop;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_alice_user uuid;
+  v_admin_user uuid;
+  v_plainmember_user uuid;
+  v_nomember_user uuid;
+  v_suspended_user uuid;
+  v_demoteleave_user uuid;
+  v_alice uuid := gen_random_uuid();
+  v_admin uuid := gen_random_uuid();
+  v_plainmember uuid := gen_random_uuid();
+  v_nomember uuid := gen_random_uuid();
+  v_suspended uuid := gen_random_uuid();
+  v_demoteleave uuid := gen_random_uuid();
+  v_requester uuid := gen_random_uuid();
+  v_invitee uuid := gen_random_uuid();
+  v_dedup uuid := gen_random_uuid();
+  v_boardb_requester uuid := gen_random_uuid();
+  v_board_a uuid;
+  v_board_b uuid;
+begin
+  v_alice_user := public.ensure_github_user('ru-alice-' || v_suffix, 'ru-alice-' || v_suffix || '@example.test', 'ru-alice-' || v_suffix, 'RU Alice');
+  v_admin_user := public.ensure_github_user('ru-admin-' || v_suffix, 'ru-admin-' || v_suffix || '@example.test', 'ru-admin-' || v_suffix, 'RU Admin');
+  v_plainmember_user := public.ensure_github_user('ru-member-' || v_suffix, 'ru-member-' || v_suffix || '@example.test', 'ru-member-' || v_suffix, 'RU Member');
+  v_nomember_user := public.ensure_github_user('ru-nomember-' || v_suffix, 'ru-nomember-' || v_suffix || '@example.test', 'ru-nomember-' || v_suffix, 'RU NoMember');
+  v_suspended_user := public.ensure_github_user('ru-susp-' || v_suffix, 'ru-susp-' || v_suffix || '@example.test', 'ru-susp-' || v_suffix, 'RU Suspended');
+  v_demoteleave_user := public.ensure_github_user('ru-demo-' || v_suffix, 'ru-demo-' || v_suffix || '@example.test', 'ru-demo-' || v_suffix, 'RU DemoteLeave');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_alice, 'agent', 'ru-alice-' || v_suffix, 'RU Alice', 'active', v_alice_user, v_alice_user),
+    (v_admin, 'agent', 'ru-admin-' || v_suffix, 'RU Admin', 'active', v_admin_user, v_admin_user),
+    (v_plainmember, 'agent', 'ru-member-' || v_suffix, 'RU Member', 'active', v_plainmember_user, v_plainmember_user),
+    (v_nomember, 'agent', 'ru-nomember-' || v_suffix, 'RU NoMember', 'active', v_nomember_user, v_nomember_user),
+    -- Suspended agent WITH a valid auth user: current_agent_id() filters status='active'
+    -- so it resolves to null while auth.uid() still maps (fail-closed test).
+    (v_suspended, 'agent', 'ru-susp-' || v_suffix, 'RU Suspended', 'suspended', v_suspended_user, v_suspended_user),
+    (v_demoteleave, 'agent', 'ru-demo-' || v_suffix, 'RU DemoteLeave', 'active', v_demoteleave_user, v_demoteleave_user),
+    (v_requester, 'agent', 'ru-requester-' || v_suffix, 'RU Requester', 'active', null, null),
+    (v_invitee, 'agent', 'ru-invitee-' || v_suffix, 'RU Invitee', 'active', null, null),
+    (v_dedup, 'agent', 'ru-dedup-' || v_suffix, 'RU Dedup', 'active', null, null),
+    (v_boardb_requester, 'agent', 'ru-brequester-' || v_suffix, 'RU BRequester', 'active', null, null);
+
+  -- Alice creates both boards (service_role null-actor here -> supplied arg honored);
+  -- create_board seeds Alice's joined owner membership (ROOMOWN) on each.
+  select board_id into v_board_a
+    from agent_board.create_board(v_alice, 'roomuiapi-a-' || v_suffix, 'ROOMUIAPI Board A', 'reader test', '{}'::jsonb, 'private');
+  select board_id into v_board_b
+    from agent_board.create_board(v_alice, 'roomuiapi-b-' || v_suffix, 'ROOMUIAPI Board B', 'isolation', '{}'::jsonb, 'private');
+
+  -- Direct-insert the remaining board A memberships (bypasses RLS + owner-gate).
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_board_a, v_admin, 'joined', v_alice, 'admin'),
+    (v_board_a, v_plainmember, 'joined', v_alice, 'member'),
+    (v_board_a, v_requester, 'requested', v_requester, 'member'),
+    (v_board_a, v_invitee, 'invited', v_alice, 'member');
+
+  -- U-4: demote-and-leave. Under in-place upsert an agent keeps ONE row; here the
+  -- current row is role=member/state=left, so the plain-exists owner/admin gate must
+  -- reject it (no stale owner/joined row lingers to falsely satisfy exists()).
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role, left_at)
+  values
+    (v_board_a, v_demoteleave, 'left', v_alice, 'member', now());
+
+  -- R8 dedup: EXPLICIT distinct created_at (the whole suite runs in one begin; so
+  -- default now() is constant). Older 'requested' + newer 'joined' -> latest row is
+  -- 'joined' -> the reader's distinct-on-latest drops this agent from the pending set.
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role, created_at)
+  values
+    (v_board_a, v_dedup, 'requested', v_dedup, 'member', now() - interval '1 hour'),
+    (v_board_a, v_dedup, 'joined', v_alice, 'member', now());
+
+  -- Board B: its own pending requester (R7 cross-board isolation).
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_board_b, v_boardb_requester, 'requested', v_boardb_requester, 'member');
+
+  insert into _roomuiapi_fixture values
+    (v_board_a, v_board_b, v_alice, v_admin, v_plainmember, v_nomember, v_suspended,
+     v_demoteleave, v_requester, v_invitee, v_dedup, v_boardb_requester,
+     'ru-requester-' || v_suffix, 'ru-susp-' || v_suffix,
+     v_alice_user, v_admin_user, v_plainmember_user, v_nomember_user, v_suspended_user, v_demoteleave_user);
+end
+$$;
+
+select set_config('request.jwt.claim.role', 'authenticated', true);
+
+-- === list_board_pending_memberships ===============================================
+-- R1: owner (Alice) reads board A -> exactly the 2 pending rows (requested+invited).
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select count(*)::int from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture))),
+  2, 'R1: the owner sees exactly the two pending memberships (requested + invited)');
+
+-- R2: admin reads board A -> same 2 pending rows.
+select set_config('request.jwt.claim.sub', (select admin_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select count(*)::int from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture))),
+  2, 'R2: an admin sees the two pending memberships');
+
+-- R3: the owner sees the requester's handle (content, not just count).
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select p.handle
+     from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture)) p
+    where p.agent_id = (select requester from _roomuiapi_fixture)),
+  (select requester_handle from _roomuiapi_fixture),
+  'R3: the owner sees the requester''s handle in the pending row');
+
+-- R4: a plain joined member is rejected -> 42501 (PRIVACY CRUX).
+select set_config('request.jwt.claim.sub', (select plainmember_user from _roomuiapi_fixture)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'R4: a plain joined member cannot enumerate pending memberships');
+
+-- R5: a non-member (unmapped sub) is rejected -> 42501.
+select set_config('request.jwt.claim.sub', gen_random_uuid()::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'R5: a non-member is rejected');
+
+-- R6: a suspended principal (current_agent_id() null) is rejected -> 42501 (fail-closed).
+select set_config('request.jwt.claim.sub', (select suspended_user from _roomuiapi_fixture)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'R6: a suspended principal (null actor) is rejected (fail-closed)');
+
+-- R7: owner of A reading board A does NOT see board B's requester (cross-board isolation).
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select count(*)::int
+     from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture)) p
+    where p.agent_id = (select boardb_requester from _roomuiapi_fixture)),
+  0, 'R7: board B''s requester is absent from board A''s pending list (cross-board isolation)');
+
+-- R8: the dedup agent (latest row 'joined', older 'requested') is NOT returned.
+select is(
+  (select count(*)::int
+     from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture)) p
+    where p.agent_id = (select dedup from _roomuiapi_fixture)),
+  0, 'R8: an agent whose latest row is joined (older requested) is not returned (dedup)');
+
+-- U-4: demote-and-leave actor (current row role=member/state=left) is rejected -> 42501.
+select set_config('request.jwt.claim.sub', (select demoteleave_user from _roomuiapi_fixture)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'U-4: a demoted-and-left actor (latest row member/left) is rejected by the gate');
+
+-- === resolve_agent_handle (SECURITY INVOKER) ======================================
+-- H1: exact active handle -> the agent_id.
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select r.agent_id
+     from agent_board.resolve_agent_handle((select requester_handle from _roomuiapi_fixture)) r),
+  (select requester from _roomuiapi_fixture),
+  'H1: the resolver maps an exact active handle to the agent_id');
+
+-- H2: unknown handle -> 0 rows.
+select is(
+  (select count(*)::int
+     from agent_board.resolve_agent_handle('ru-does-not-exist-' || gen_random_uuid()::text)),
+  0, 'H2: an unknown handle resolves to zero rows');
+
+-- H3: a suspended agent's handle -> 0 rows (status='active' filter).
+select is(
+  (select count(*)::int
+     from agent_board.resolve_agent_handle((select suspended_handle from _roomuiapi_fixture))),
+  0, 'H3: a suspended agent''s handle resolves to zero rows (active filter)');
+
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+select finish();
+
+rollback;