@consiliency/agent-board-schema 1.9.0 → 1.10.0

package/fixtures/already-applied.json

@@ -312,6 +312,10 @@
     {
       "id": "20260727000100_agent_board_roomuiapi",
       "sha256": "9c938c40115aa25f464bbb9d177f9f85214fb84f7b37abe5ae9df5b6a2485141"
+    },
+    {
+      "id": "20260728000100_agent_board_enroll_federated_human",
+      "sha256": "5f300449c29ec05c2cd3c2cd7eca622ca41e8b32b8856c5bc0695b5750a196e7"
     }
   ]
 }

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.9.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",

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.9.0",
+  "packageVersion": "1.10.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 78,
-  "aggregateSha256": "4b6a5435c11341549636dfec4273c5bdc5773be23f8b8667ea816927e9412f87",
+  "migrationCount": 79,
+  "aggregateSha256": "6e82ca1943a3848b3f7c871e97cdf82387194ac361e965111785e236a0e850fd",
   "migrations": [
     {
       "order": 0,
@@ -750,6 +750,15 @@
       "sourceRef": "message-board",
       "bytes": 5217,
       "sha256": "9c938c40115aa25f464bbb9d177f9f85214fb84f7b37abe5ae9df5b6a2485141"
+    },
+    {
+      "order": 78,
+      "id": "20260728000100_agent_board_enroll_federated_human",
+      "filename": "20260728000100_agent_board_enroll_federated_human.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 15404,
+      "sha256": "5f300449c29ec05c2cd3c2cd7eca622ca41e8b32b8856c5bc0695b5750a196e7"
     }
   ],
   "excludedBridge": {

package/src/tooling.test.mjs

@@ -37,9 +37,9 @@ describe('manifest integrity', () => {
     expect(manifest.schemaVersion).toBe(8);
     expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
   });
-  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI forward migrations (migrationCount = prior 77 + 1 = 78)', () => {
+  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION forward migrations (migrationCount = prior 78 + 1 = 79)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(78);
+    expect(manifest.migrationCount).toBe(79);
     // 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,
@@ -91,6 +91,10 @@ describe('manifest integrity', () => {
       // list_board_pending_memberships + SECURITY INVOKER resolve_agent_handle).
       // schema stays 8.
       '20260727000100_agent_board_roomuiapi.sql',
+      // FEDSESSION: service_role no-PoP federated-HUMAN provisioning (enroll_federated_human)
+      // backing the /portal-session Option A self-signed access-token minter. Additive
+      // (adds a nullable mode column to enrollment_federation_audit); schema stays 8.
+      '20260728000100_agent_board_enroll_federated_human.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }

package/tests/agent_board_enrollment_audit_content.test.sql

@@ -76,10 +76,13 @@ select is(
         -- ("X is an aggregate function"); restrict to callable functions +
         -- procedures (the RPC surface this invariant is about).
         and p.prokind in ('f', 'p')
-        and p.proname <> 'enroll_federated_identity'
+        -- The federation enroll RPCs WRITE the audit (enroll_federated_human added by
+        -- FEDSESSION, F-6); the invariant is that nothing on the send/session read path
+        -- touches it (asserted specifically in the next case).
+        and p.proname not in ('enroll_federated_identity', 'enroll_federated_human')
    ) d
    where lower(d.def) like '%enrollment_federation_audit%'),
-  0, 'no agent_board RPC other than enroll_federated_identity references enrollment_federation_audit');
+  0, 'no agent_board RPC other than the federation enroll RPCs references enrollment_federation_audit');
 select is(
   (select count(*)::int from (
      select pg_get_functiondef(p.oid) as def

package/tests/agent_board_fedsession.test.sql

@@ -0,0 +1,314 @@
+-- FEDSESSION pgTAP: enroll_federated_human() — service_role no-PoP federated-HUMAN
+-- provisioning (Option A minter substrate).
+--
+-- Proves: the 5-arg signature + service_role-only privs; one provision mints a kind=human
+-- SELF-owned agent (auth_user_id = owner_user_id = a synthetic uid) with a real auth.users
+-- row + NO signing key + a mode='fedsession' audit row; the verified email lives ONLY in
+-- auth.users.raw_user_meta_data (provenance-tagged, MERGED preserving slug) with just the
+-- boolean email_verified in agents.metadata (no '@' anywhere in agents.metadata);
+-- idempotency + L-4b (one agent per synthetic uid); current_agent_id() resolves the
+-- no-credential session to the agent; the IDLINK shared-uid invariant against
+-- enroll_federated_identity; and the provider/kind/subject/non-service rejection matrix.
+-- Runs as postgres (service_role-equivalent), mirroring
+-- agent_board_enroll_federated_identity.test.sql + agent_board_localauth.test.sql.
+
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(36);
+
+-- ---------------------------------------------------------------------------
+-- Phase 0 (superuser): function metadata + privileges
+-- ---------------------------------------------------------------------------
+-- 1
+select has_function(
+  'agent_board', 'enroll_federated_human',
+  array['text','text','text','jsonb','text'],
+  'enroll_federated_human(text,text,text,jsonb,text) exists');
+-- 2
+select function_privs_are(
+  'agent_board', 'enroll_federated_human', array['text','text','text','jsonb','text'],
+  'service_role', array['EXECUTE'], 'service_role may EXECUTE enroll_federated_human');
+-- 3
+select function_privs_are(
+  'agent_board', 'enroll_federated_human', array['text','text','text','jsonb','text'],
+  'authenticated', array[]::text[], 'authenticated may NOT EXECUTE enroll_federated_human');
+-- 4
+select function_privs_are(
+  'agent_board', 'enroll_federated_human', array['text','text','text','jsonb','text'],
+  'anon', array[]::text[], 'anon may NOT EXECUTE enroll_federated_human');
+
+-- ---------------------------------------------------------------------------
+-- Fixtures + provision identity A (email_verified) and B (unverified)
+-- ---------------------------------------------------------------------------
+create temp table _f (
+  s text, iss text, aud text,
+  sub_a text, email_a text, sub_b text
+) on commit drop;
+grant all on table _f to authenticated, service_role;
+
+create temp table _r (
+  label text, agent_id uuid, auth_user_id uuid, owner_user_id uuid,
+  handle text, kind text, status text, created_at timestamptz
+) on commit drop;
+grant all on table _r to authenticated, service_role;
+
+do $$
+declare
+  s text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_iss text; v_agent uuid; v_auth uuid; v_owner uuid; v_handle text;
+  v_kind text; v_status text; v_created timestamptz;
+begin
+  v_iss := 'https://fed-hs-' || s || '.test';
+  insert into _f values (
+    s, v_iss, 'message-board',
+    'portal-user-' || s, 'alice-' || s || '@example.test', 'portal-user2-' || s);
+
+  -- Approved provider that permits BOTH agent + human (agent needed for the IDLINK case).
+  insert into agent_board.identity_providers
+    (issuer, audience, supported, policy_approved, allowed_scopes, allowed_board_scopes, allowed_agent_kinds)
+  values
+    (v_iss, 'message-board', true, true, '{board:send}', '{board:x}', '{agent,human}');
+
+  -- Provision A (verified email present in the claim).
+  select e.agent_id, e.auth_user_id, e.handle, e.kind, e.status, e.created_at
+    into v_agent, v_auth, v_handle, v_kind, v_status, v_created
+    from agent_board.enroll_federated_human(
+      v_iss, 'message-board', 'portal-user-' || s,
+      jsonb_build_object('sub', 'portal-user-' || s, 'email', 'alice-' || s || '@example.test',
+                         'email_verified', true, 'name', 'Alice ' || s),
+      'Alice ' || s) e;
+  select a.owner_user_id into v_owner from agent_board.agents a where a.id = v_agent;
+  insert into _r values ('A', v_agent, v_auth, v_owner, v_handle, v_kind, v_status, v_created);
+
+  -- Provision B (DIFFERENT identity, email_verified=false).
+  select e.agent_id, e.auth_user_id, e.handle, e.kind, e.status, e.created_at
+    into v_agent, v_auth, v_handle, v_kind, v_status, v_created
+    from agent_board.enroll_federated_human(
+      v_iss, 'message-board', 'portal-user2-' || s,
+      jsonb_build_object('sub', 'portal-user2-' || s, 'email', 'bob-' || s || '@example.test',
+                         'email_verified', false),
+      null) e;
+  select a.owner_user_id into v_owner from agent_board.agents a where a.id = v_agent;
+  insert into _r values ('B', v_agent, v_auth, v_owner, v_handle, v_kind, v_status, v_created);
+end
+$$;
+
+-- One provision mints a kind=human, self-owned, active agent -----------------------------
+-- 5
+select is((select count(*)::int from _r where label = 'A'), 1, 'provision A returned exactly one row');
+-- 6
+select is((select kind from _r where label = 'A'), 'human', 'agent A kind = human');
+-- 7
+select is(
+  (select a.agent_type from agent_board.agents a where a.id = (select agent_id from _r where label='A')),
+  'human', 'agent A agent_type = human');
+-- 8
+select is((select status from _r where label = 'A'), 'active', 'agent A status = active');
+-- 9
+select is(
+  (select auth_user_id from _r where label='A'),
+  (select owner_user_id from _r where label='A'),
+  'agent A is self-owned (auth_user_id = owner_user_id = the synthetic uid)');
+-- 10
+select is(
+  (select count(*)::int from auth.users u where u.id = (select auth_user_id from _r where label='A')),
+  1, 'the synthetic auth.users row for agent A exists');
+-- 11
+select is(
+  (select handle from _r where label='A'),
+  'fed-human-' || substr(
+    encode(extensions.digest(convert_to((select iss from _f) || '|' || (select sub_a from _f), 'UTF8'), 'sha256'), 'hex'),
+    1, 32),
+  'handle = fed-human-<sha256(issuer|subject)[:32]> (byte-identical to enroll_federated_identity)');
+
+-- metadata carries the federation snapshot, boolean-only email, no PII --------------------
+-- 12
+select is(
+  (select a.metadata->'federation'->>'issuer' from agent_board.agents a where a.id=(select agent_id from _r where label='A')),
+  (select iss from _f), 'metadata.federation.issuer round-trips');
+-- 13
+select is(
+  (select a.metadata->'federation'->>'subject' from agent_board.agents a where a.id=(select agent_id from _r where label='A')),
+  (select sub_a from _f), 'metadata.federation.subject round-trips');
+-- 14
+select is(
+  (select a.metadata->'federation'->>'mode' from agent_board.agents a where a.id=(select agent_id from _r where label='A')),
+  'fedsession', 'metadata.federation.mode = fedsession');
+-- 15
+select is(
+  (select a.metadata->'federation'->>'email_verified' from agent_board.agents a where a.id=(select agent_id from _r where label='A')),
+  'true', 'verified identity -> metadata.federation.email_verified = true');
+-- 16
+select ok(
+  (select a.metadata::text not like '%@%' from agent_board.agents a where a.id=(select agent_id from _r where label='A')),
+  'agent A metadata carries NO plaintext email/@ (PII stays out of fleet-readable metadata)');
+
+-- verified email + slug live (merged) in auth.users.raw_user_meta_data --------------------
+-- 17
+select is(
+  (select u.raw_user_meta_data->>'fedsession_email' from auth.users u where u.id=(select auth_user_id from _r where label='A')),
+  (select email_a from _f), 'verified email is stored in auth.users.raw_user_meta_data');
+-- 18
+select is(
+  (select u.raw_user_meta_data->>'fedsession_email_provenance' from auth.users u where u.id=(select auth_user_id from _r where label='A')),
+  'portal-claim-unverified', 'stored email is tagged provenance=portal-claim-unverified (F-12)');
+-- 19 (F-4 merge preserved _ensure_agent_auth_user's slug)
+select is(
+  (select u.raw_user_meta_data->>'slug' from auth.users u where u.id=(select auth_user_id from _r where label='A')),
+  (select handle from _r where label='A'),
+  'raw_user_meta_data merge preserved the _ensure_agent_auth_user slug (no overwrite)');
+
+-- NO signing key; audit row written ------------------------------------------------------
+-- 20
+select is(
+  (select count(*)::int from agent_board.agent_signing_keys k where k.agent_id=(select agent_id from _r where label='A')),
+  0, 'agent A holds NO agent_signing_keys row (humans hold no key)');
+-- 21
+select is(
+  (select count(*)::int from agent_board.enrollment_federation_audit e
+     where e.agent_id=(select agent_id from _r where label='A') and e.mode='fedsession'),
+  1, 'provision A wrote exactly one mode=fedsession audit row');
+
+-- Identity B: unverified boolean + PII guard ---------------------------------------------
+-- 22
+select is(
+  (select a.metadata->'federation'->>'email_verified' from agent_board.agents a where a.id=(select agent_id from _r where label='B')),
+  'false', 'unverified identity -> metadata.federation.email_verified = false');
+-- 23
+select ok(
+  (select a.metadata::text not like '%@%' from agent_board.agents a where a.id=(select agent_id from _r where label='B')),
+  'agent B metadata carries NO plaintext email/@');
+
+-- Idempotency + L-4b ---------------------------------------------------------------------
+-- 24
+select is(
+  (select e.agent_id from agent_board.enroll_federated_human(
+     (select iss from _f), 'message-board', (select sub_a from _f),
+     jsonb_build_object('sub', (select sub_a from _f), 'email_verified', true), 'Alice again') e),
+  (select agent_id from _r where label='A'),
+  're-provision of the same (issuer,sub) is idempotent (same agent_id)');
+-- 25
+select is(
+  (select count(*)::int from agent_board.agents a where a.auth_user_id=(select auth_user_id from _r where label='A')),
+  1, 'still exactly one agent on the synthetic uid (L-4b)');
+-- 26
+select is(
+  (select count(*)::int from agent_board.agents a
+     where a.owner_user_id=(select auth_user_id from _r where label='A') and a.kind <> 'human'),
+  0, 'no non-human agent was ever created on this owner uid (kind is structural)');
+
+-- IDLINK: enroll_federated_identity for the SAME (issuer,sub) shares the owner uid --------
+create temp table _idlink (owner uuid) on commit drop;
+do $$
+declare
+  f record;
+  v_pub text; v_fp text; v_agent uuid;
+begin
+  select * into f from _f;
+  -- A deterministic canonical 32-byte raw key + its raw-byte fingerprint (same construction
+  -- as the enroll_federated_identity B1 harness).
+  v_pub := rtrim(translate(encode(extensions.digest(convert_to('idlink-'||f.s,'UTF8'),'sha256'),'base64'),'+/','-_'),'=');
+  v_fp := 'sha256:' || rtrim(translate(encode(extensions.digest(decode(translate(v_pub,'-_','+/')||'=','base64'),'sha256'),'base64'),'+/','-_'),'=');
+  select e.agent_id into v_agent
+    from agent_board.enroll_federated_identity(
+      f.iss, 'message-board', f.sub_a, jsonb_build_object('sub', f.sub_a),
+      'idlink-'||f.s, v_pub, 'raw_ed25519_base64url', v_fp,
+      true, null, 'agent', '{board:send}', '{}') e;
+  insert into _idlink select a.owner_user_id from agent_board.agents a where a.id = v_agent;
+end
+$$;
+-- 27
+select is(
+  (select owner from _idlink),
+  (select auth_user_id from _r where label='A'),
+  'IDLINK: enroll_federated_identity for the same (issuer,sub) shares the fed-human owner uid');
+
+-- current_agent_id() resolves the no-credential session to the fed-human agent -----------
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select auth_user_id::text from _r where label='A'), true);
+-- 28
+select is(
+  agent_board.current_agent_id(),
+  (select agent_id from _r where label='A'),
+  'current_agent_id() (no agent_credential_id claim) resolves to the fed-human agent');
+-- 29 (non-service caller: authenticated lacks EXECUTE -> 42501)
+select throws_ok(
+  $$ select agent_board.enroll_federated_human('https://x.test','message-board','portal-x','{}'::jsonb,null) $$,
+  '42501', null, 'a non-service (authenticated) caller is rejected with 42501');
+reset role;
+-- Clear BOTH request.jwt GUCs: reset role alone leaves request.jwt.claim.role set (it
+-- persists as is_local), so auth.role() would stay 'authenticated' and _is_service_role()
+-- would wrongly reject the following superuser calls (they must run as service_role-equiv).
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+-- Provider / kind / subject rejection matrix (superuser) ---------------------------------
+-- 30 unknown (issuer, audience)
+select throws_ok(
+  (select format($q$select agent_board.enroll_federated_human('https://nope-%s.test','message-board',%L,%L::jsonb,null)$q$,
+     s, sub_a, jsonb_build_object('sub', sub_a)::text) from _f),
+  '42501', null, 'unknown (issuer,audience) is rejected');
+-- 31 null verified subject
+select throws_ok(
+  (select format($q$select agent_board.enroll_federated_human(%L,'message-board',NULL,%L::jsonb,null)$q$,
+     iss, jsonb_build_object('x', 1)::text) from _f),
+  '22023', null, 'a null verified subject is rejected');
+-- 32 subject contains a '|' (F-11 preimage-injection guard)
+select throws_ok(
+  (select format($q$select agent_board.enroll_federated_human(%L,'message-board',%L,%L::jsonb,null)$q$,
+     iss, 'portal|evil', jsonb_build_object('sub','portal|evil')::text) from _f),
+  '22023', null, 'a subject containing a pipe separator is rejected (F-11)');
+-- 32b subject is email-shaped ('@') (F-11 PII backstop; subject is stored fleet-readable)
+select throws_ok(
+  (select format($q$select agent_board.enroll_federated_human(%L,'message-board',%L,%L::jsonb,null)$q$,
+     iss, 'evil@example.test', jsonb_build_object('sub','evil@example.test')::text) from _f),
+  '22023', null, 'an email-shaped (@) subject is rejected before it reaches fleet-readable metadata (F-11)');
+
+-- provider present but NOT policy_approved -> 42501
+do $$
+declare s2 text := replace(substr(gen_random_uuid()::text,1,8),'-','');
+begin
+  insert into agent_board.identity_providers
+    (issuer, audience, supported, policy_approved, allowed_scopes, allowed_board_scopes, allowed_agent_kinds)
+  values ('https://fed-unapproved-'||s2||'.test','message-board', true, false, '{}','{}','{human}');
+  insert into _f(s,iss,aud,sub_a,email_a,sub_b)
+    values ('U'||s2, 'https://fed-unapproved-'||s2||'.test','message-board','portal-u-'||s2,null,null);
+end $$;
+-- 33
+select throws_ok(
+  (select format($q$select agent_board.enroll_federated_human(%L,'message-board',%L,%L::jsonb,null)$q$,
+     iss, sub_a, jsonb_build_object('sub', sub_a)::text) from _f where s like 'U%'),
+  '42501', null, 'an un-approved (policy_approved=false) provider is rejected');
+
+-- provider approved but allowed_agent_kinds EXCLUDES human (non-empty {agent}) -> 42501
+do $$
+declare s3 text := replace(substr(gen_random_uuid()::text,1,8),'-','');
+begin
+  insert into agent_board.identity_providers
+    (issuer, audience, supported, policy_approved, allowed_scopes, allowed_board_scopes, allowed_agent_kinds)
+  values ('https://fed-nohuman-'||s3||'.test','message-board', true, true, '{}','{}','{agent}');
+  insert into _f(s,iss,aud,sub_a,email_a,sub_b)
+    values ('N'||s3, 'https://fed-nohuman-'||s3||'.test','message-board','portal-n-'||s3,null,null);
+end $$;
+-- 34
+select throws_ok(
+  (select format($q$select agent_board.enroll_federated_human(%L,'message-board',%L,%L::jsonb,null)$q$,
+     iss, sub_a, jsonb_build_object('sub', sub_a)::text) from _f where s like 'N%'),
+  '42501', null, 'a non-empty allowed_agent_kinds that excludes human is rejected');
+
+-- Non-active identity cannot re-provision (no self-reactivation; F-13 lever) --------------
+update agent_board.agents set status='suspended', updated_at=now()
+  where id = (select agent_id from _r where label='A');
+-- 35
+select throws_ok(
+  (select format($q$select agent_board.enroll_federated_human(%L,'message-board',%L,%L::jsonb,null)$q$,
+     iss, sub_a, jsonb_build_object('sub', sub_a)::text) from _f where sub_a like 'portal-user-%'),
+  '42501', null, 'a suspended (non-active) fed-human cannot re-provision a session (42501)');
+
+select finish();
+
+rollback;