@consiliency/agent-board-schema 1.7.0 → 1.10.0

package/fixtures/already-applied.json

@@ -304,6 +304,18 @@
     {
       "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"
+    },
+    {
+      "id": "20260728000100_agent_board_enroll_federated_human",
+      "sha256": "5f300449c29ec05c2cd3c2cd7eca622ca41e8b32b8856c5bc0695b5750a196e7"
     }
   ]
 }

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/migrations/20260728000100_agent_board_enroll_federated_human.sql

@@ -0,0 +1,313 @@
+-- FEDSESSION (Option A): service_role no-PoP federated-HUMAN provisioning substrate.
+--
+-- WHAT: enroll_federated_human() is the DB half of the /portal-session Edge Function
+-- minter. A browser human who holds a live Portal OIDC session hits /portal-session; the
+-- EF RS256-verifies the Portal token (aud/exp/sig against the issuer JWKS), then calls
+-- THIS RPC (service_role) to establish a kind='human' agent keyed on (issuer, sub), and
+-- finally self-signs a bounded (<=15 min) board-native access token (the same HS256
+-- mechanism as /session — SESSION_SIGNING_SECRET == the project PostgREST JWT secret).
+--
+-- Option A = ACCESS-ONLY. There is NO GoTrue session and therefore NO refresh_token and
+-- NO revocable auth.sessions row. The browser re-mints from /portal-session on expiry
+-- (it holds a live Portal session throughout). This RPC never returns a token — the EF
+-- mints it — and never touches a Portal token itself.
+--
+-- WHY a new RPC (cannot reuse the existing federation paths):
+--   * enroll_federated_identity (20260719001200) HARD-REQUIRES p_pop_verified=true + a
+--     raw Ed25519 key. A human holds no signing key, so that path cannot apply.
+--   * self_enroll_human (20260726000100) binds the REAL auth.uid() (authenticated-only).
+--     The Portal human is not authenticated to THIS project, so there is no auth.uid().
+--   => a service_role, no-PoP, human-only RPC that mints a SYNTHETIC per-identity uid.
+--
+-- IDENTITY MODEL: the human is its OWN principal — auth_user_id = owner_user_id = a
+-- SYNTHETIC uid derived idempotently from (issuer, sub). This mirrors self_enroll_human's
+-- self-ownership, NOT enroll_federated_identity (where the human is only owner_user_id of
+-- a separate key-identified agent). The synthetic-uid handle uses the SAME byte-exact
+-- derivation as enroll_federated_identity:198-199, so a fed-human here and a federated
+-- IDENTITY enrollment for the SAME (issuer, sub) converge on ONE shared owner uid (the
+-- IDLINK substrate). L-4b (one agent per real auth user) is not violated: this uid is
+-- synthetic, and enroll_federated_identity never puts an agent ON that owner uid.
+--
+-- KIND ENFORCEMENT IS STRUCTURAL: there is NO p_agent_kind argument — this RPC ONLY ever
+-- inserts kind='human'/agent_type='human'. No agent_signing_keys row is created (humans
+-- hold no key). Authority stays membership/role-gated: merely holding a session grants no
+-- board access; current_agent_id() resolves auth.uid() -> the active human agent (with NO
+-- agent_credential_id claim, the null-credential branch), and RLS then gates by
+-- membership/role exactly as for any other principal.
+--
+-- F-13 REVOCATION LEVER (Option A's substitute for a revocable session row): suspend or
+-- revoke the fed-human agent (agents.status <> 'active'). current_agent_id() then resolves
+-- to NULL, so every RLS-gated read/write denies — any outstanding <=15-min token is inert
+-- at the AUTHORITY layer within one token lifetime. The non-active guard below ALSO blocks
+-- re-mint (no self-reactivation), so a suspended human cannot re-provision a fresh session.
+--
+-- F-10 TRUST BOUNDARY (named): Portal `sub`-issuance is the takeover boundary. A
+-- compromised or mis-issued Portal `sub` for a human = full takeover of that human on the
+-- board, INCLUDING ownership of any agent subtree the human owns (this fed-human is the
+-- owner_user_id of it). The board delegates that decision to the Portal by design.
+--
+-- F-14 FLAG: because the fed-human is owner_user_id of its subtree, a FUTURE "act-as-owned"
+-- RPC would turn this bounded session into act-as-fleet. No such RPC exists today; if one
+-- is ever added it MUST NOT be reachable from a fedsession-minted token.
+--
+-- PII (F-12): the verified email is written ONLY to auth.users.raw_user_meta_data
+-- (service-role-only), tagged provenance='portal-claim-unverified' (the board has NOT
+-- independently verified possession — an IDLINK link-time flow MUST re-verify before
+-- trusting it). agents.metadata.federation stores ONLY the boolean email_verified, NEVER
+-- the address: the agents SELECT RLS is not row-scoped, so a stored email would be a
+-- fleet-wide harvestable directory (the LOCALAUTH lesson, 20260726000100:15-22).
+--
+-- Additive, forward-only. Writes no agent_board.schema_version (stays 8).
+
+-- F-6: tag each federation-audit row with its provisioning mode. Additive nullable column
+-- (enroll_federated_identity's insert leaves it null; the audit-content pgTAP uses
+-- has_column, not a strict column-set pin, so this is safe). enroll_federated_human sets
+-- mode='fedsession' for accountability — Option A has no revocable session row, so the
+-- audit trail is the durable per-provision record.
+alter table agent_board.enrollment_federation_audit
+  add column if not exists mode text;
+
+create or replace function agent_board.enroll_federated_human(
+  p_issuer text,
+  p_audience text,
+  p_subject text,
+  p_human_identity_claim jsonb,
+  p_display_name text default null
+)
+returns table(
+  agent_id uuid,
+  auth_user_id uuid,
+  handle text,
+  kind text,
+  status text,
+  provider_id text,
+  created_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_provider agent_board.identity_providers%rowtype;
+  v_handle text;
+  v_uid uuid;
+  v_agent agent_board.agents%rowtype;
+  v_existing agent_board.agents%rowtype;
+  v_email text := nullif(trim(coalesce(p_human_identity_claim->>'email', '')), '');
+  v_email_verified boolean;
+begin
+  -- Derive the verified-email boolean from the claim (never trust it as board-proven
+  -- possession; it only records what the Portal asserted). A non-boolean/absent value
+  -- collapses to false.
+  begin
+    v_email_verified := coalesce((p_human_identity_claim->>'email_verified')::boolean, false);
+  exception when others then
+    v_email_verified := false;
+  end;
+
+  -- (1) service_role-only (defense in depth on top of the execute-grant revocation).
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for enroll_federated_human' using errcode = '42501';
+  end if;
+
+  -- (2) A verified subject + human identity claim are always present from the EF.
+  if p_subject is null then
+    raise exception 'verified subject is required' using errcode = '22023';
+  end if;
+  if p_human_identity_claim is null then
+    raise exception 'human identity claim is required' using errcode = '22023';
+  end if;
+
+  -- (3) F-11: the synthetic-uid preimage is issuer||'|'||subject. Guard the separator so a
+  -- subject cannot inject a '|' to collide two distinct (issuer, subject) pairs onto one
+  -- owner uid. ALSO reject an email-shaped subject ('@'): the subject is stored VERBATIM in
+  -- agents.metadata.federation.subject, and the agents SELECT RLS is not row-scoped, so an
+  -- email `sub` would be a fleet-harvestable PII leak — the exact hazard the email is kept
+  -- out of agents.metadata to avoid. The operator's ENROLL_SUBJECT_CLAIM must resolve to an
+  -- opaque id; this is the fail-closed backstop, and the pgTAP PII guard asserts BOTH the
+  -- '@'-rejection and metadata carrying no '@'.
+  if position('|' in p_subject) > 0 then
+    raise exception 'verified subject must not contain a pipe separator character'
+      using errcode = '22023';
+  end if;
+  if position('@' in p_subject) > 0 then
+    raise exception 'verified subject must be an opaque id, not an email/@-bearing value'
+      using errcode = '22023';
+  end if;
+
+  -- (4) provider gate on (issuer, audience): must exist + supported + policy_approved.
+  -- Defense in depth atop the EF's signature verify (mirrors 20260719001200:154-181).
+  select *
+    into v_provider
+    from agent_board.identity_providers
+   where issuer = p_issuer
+     and audience = p_audience
+   limit 1;
+  if v_provider.id is null then
+    raise exception 'issuer/audience not in the identity-provider allowlist' using errcode = '42501';
+  end if;
+  if not v_provider.supported then
+    raise exception 'identity provider is not supported' using errcode = '42501';
+  end if;
+  if not v_provider.policy_approved then
+    raise exception 'identity provider is not policy-approved' using errcode = '42501';
+  end if;
+
+  -- (5) HUMAN-ONLY ceiling. allowed_agent_kinds is permissive on empty/null (the ceiling
+  -- is "unset"); reject ONLY when it is non-empty AND does not include 'human'.
+  if array_length(v_provider.allowed_agent_kinds, 1) is not null
+     and not ('human' = any (v_provider.allowed_agent_kinds)) then
+    raise exception 'provider ceiling does not permit the human kind' using errcode = '42501';
+  end if;
+
+  -- (6) SYNTHETIC uid — byte-identical derivation to enroll_federated_identity:198-199
+  -- (extensions.digest, since the pinned search_path lacks extensions). Idempotent per
+  -- (issuer, sub) so re-provisioning converges to ONE owner auth.users row = the shared
+  -- IDLINK uid. Pass issuer/subject VERBATIM (no trim/normalize) to stay byte-identical.
+  v_handle := 'fed-human-' || substr(
+    encode(extensions.digest(convert_to(p_issuer || '|' || p_subject, 'UTF8'), 'sha256'), 'hex'),
+    1, 32);
+  v_uid := agent_board._ensure_agent_auth_user(v_handle);
+
+  -- (7) Idempotent + no-self-reactivation, keyed on auth_user_id = the synthetic uid (ANY
+  -- status). An ACTIVE row -> return it (idempotent). A NON-active row -> fail closed
+  -- (42501): a suspended/revoked human must NOT re-mint a session (mirrors
+  -- 20260726000100:78-81 and reinforces the F-13 revocation lever). F-5: assert the row is
+  -- human before returning it as a human session (a non-human agent on this owner uid must
+  -- never yield a "human" provision).
+  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
+      if v_existing.kind <> 'human' then
+        raise exception 'existing agent on this identity is not human; refusing human session'
+          using errcode = '42501';
+      end if;
+      -- Refresh the verified-email snapshot on re-provision (MERGE, see step 9).
+      if v_email is not null then
+        update auth.users u
+           set raw_user_meta_data = coalesce(u.raw_user_meta_data, '{}'::jsonb)
+             || jsonb_build_object(
+                  'fedsession_email', v_email,
+                  'fedsession_email_verified', v_email_verified,
+                  'fedsession_email_provenance', 'portal-claim-unverified')
+         where u.id = v_uid;
+      end if;
+      insert into agent_board.enrollment_federation_audit(
+        issuer, audience, subject, human_identity_claim, provider_id,
+        agent_id, auth_user_id, requested_scopes, granted_scopes, mode)
+      values (
+        p_issuer, p_audience, p_subject, p_human_identity_claim, v_provider.id,
+        v_existing.id, v_uid, '{}', '{}', 'fedsession');
+      return query
+      select v_existing.id, v_existing.auth_user_id, v_existing.handle,
+             v_existing.kind::text, v_existing.status, v_provider.id, v_existing.created_at;
+      return;
+    else
+      raise exception 'a non-active identity already exists for this human; contact an operator'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- (8) Create the kind='human' agent (self-owned: auth_user_id = owner_user_id = uid).
+  -- No agent_signing_keys row (humans hold no key). metadata.federation carries ONLY the
+  -- boolean email_verified — never the address (PII / fleet-readable RLS).
+  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(
+        'federation', jsonb_build_object(
+          'mode', 'fedsession',
+          'issuer', p_issuer,
+          'audience', p_audience,
+          'subject', p_subject,
+          'providerId', v_provider.id,
+          'email_verified', v_email_verified,
+          'enrolledAt', now()
+        )
+      )
+    )
+    returning * into v_agent;
+  exception when unique_violation then
+    -- Concurrent first-provision race on the synthetic uid. F-5: re-select the ACTIVE row
+    -- and ASSERT it is human (fail closed otherwise) — never return a non-human agent as a
+    -- human session.
+    select *
+      into v_existing
+      from agent_board.agents a
+     where a.auth_user_id = v_uid
+       and a.status = 'active'
+       and a.kind = 'human'
+     limit 1;
+    if found then
+      v_agent := v_existing;
+    else
+      raise exception 'could not provision federated human (race or non-human on owner uid), please retry'
+        using errcode = '40001';
+    end if;
+  end;
+
+  -- (9) F-12/F-4: store the verified email ONLY in auth.users.raw_user_meta_data
+  -- (service-role-only), MERGED so _ensure_agent_auth_user's {slug, issuer} is preserved,
+  -- tagged provenance='portal-claim-unverified'. The definer owner (postgres) owns auth.*.
+  if v_email is not null then
+    update auth.users u
+       set raw_user_meta_data = coalesce(u.raw_user_meta_data, '{}'::jsonb)
+         || jsonb_build_object(
+              'fedsession_email', v_email,
+              'fedsession_email_verified', v_email_verified,
+              'fedsession_email_provenance', 'portal-claim-unverified')
+     where u.id = v_uid;
+  end if;
+
+  -- (10) F-6: append the audit row (mode='fedsession'). No requested/granted scopes on the
+  -- human path (authority is membership/role, not enrollment scopes) -> empty arrays.
+  insert into agent_board.enrollment_federation_audit(
+    issuer, audience, subject, human_identity_claim, provider_id,
+    agent_id, auth_user_id, requested_scopes, granted_scopes, mode)
+  values (
+    p_issuer, p_audience, p_subject, p_human_identity_claim, v_provider.id,
+    v_agent.id, v_uid, '{}', '{}', 'fedsession');
+
+  return query
+  select v_agent.id, v_agent.auth_user_id, v_agent.handle,
+         v_agent.kind::text, v_agent.status, v_provider.id, v_agent.created_at;
+end;
+$$;
+
+comment on function agent_board.enroll_federated_human(text, text, text, jsonb, text) is
+  'FEDSESSION (Option A): service_role no-PoP federated-HUMAN provisioning. Re-gates the '
+  '(issuer,audience) provider allowlist/policy + the human-only ceiling, establishes a '
+  'kind=human self-owned agent (auth_user_id = owner_user_id = a SYNTHETIC uid derived '
+  'byte-identically to enroll_federated_identity per (issuer,sub) = the IDLINK substrate), '
+  'stores the verified email ONLY in auth.users.raw_user_meta_data (provenance '
+  'portal-claim-unverified) with only the boolean email_verified in agents.metadata, and '
+  'writes a mode=fedsession audit row. No signing key. Idempotent for an active identity; '
+  'a non-active identity fails closed (42501, no self-reactivation) — the F-13 revocation '
+  'lever (suspend the agent -> current_agent_id null -> RLS denies + re-mint blocked). '
+  'service_role-only; never returns or touches a Portal token.';
+
+revoke all on function agent_board.enroll_federated_human(text, text, text, jsonb, text)
+  from public, anon, authenticated;
+grant execute on function agent_board.enroll_federated_human(text, text, text, jsonb, text)
+  to service_role;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.7.0",
+  "version": "1.10.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",