@consiliency/agent-board-schema 1.12.0 → 1.22.0

package/migrations/20260822000100_agent_board_mint_harden.sql

@@ -0,0 +1,710 @@
+-- =============================================================================
+-- MINTHARDEN (#138) — child-key fingerprint integrity + EF-mediated authenticated
+-- minting (completes ROOMDELEG-2 / #59).
+-- =============================================================================
+-- Four defects, one class, closed together (CLAUDE.md rule #1 — enumerate from the
+-- catalog, not a list):
+--
+--   1. RAW-BYTE FINGERPRINT. mint_delegated_child derived a signing-key fingerprint
+--      over the base64url STRING (`digest(convert_to(key,'UTF8'))`, 20260718001000:203)
+--      while enroll_federated_identity was migrated to the RAW 32 bytes (20260719001200).
+--      Same key, two fingerprints => agent_signing_keys.fingerprint UNIQUE did NOT dedup
+--      mint vs enroll, defeating the squat backstop. This migration extracts ONE
+--      derivation — `_raw_key_fingerprint(text)` — and routes BOTH writers through it.
+--      A catalog-derived pgTAP sweep (pg_get_functiondef) pins that no fingerprint-
+--      INSERTing function bypasses it, so a new divergent writer names itself.
+--
+--   2. TABLE-BOUNDARY TRIGGER. The function sweep only catches FUNCTION writers; direct
+--      or dynamic DML bypasses it. A BEFORE INSERT OR UPDATE trigger on
+--      agent_signing_keys recomputes the fingerprint from public_key for the raw format
+--      and RAISES on mismatch — the invariant is enforced at the table boundary.
+--
+--   3. NON-POSITIVE TTL FLOOR. mint accepted p_ttl <= 0, minting an immediately-expired
+--      grant that escapes the max_active_children count while still provisioning an
+--      auth user + agent + key — a fan-out bypass once the authenticated path opens.
+--
+--   4. EF-MEDIATED AUTHENTICATED MINTING (topology A, maintainer-frozen 2026-07-31).
+--      There is NO in-DB Ed25519 verifier, so mint STAYS service_role-only; direct
+--      authenticated EXECUTE remains REVOKED. The authenticated product surface is the
+--      Edge Function supabase/functions/mint-child, which verifies the root's session
+--      JWT + the child-key proof-of-possession signature (domain-separated) and calls
+--      this RPC with p_self_service=true and the session-bound root identity. On that
+--      path the RPC does NOT trust the stored policy caps (a root can self-widen its
+--      operator_vetted row, #142): it RE-CLAMPS max_active_children to
+--      least(coalesce(stored,25),25) and the TTL ceiling to <= 24h, and applies a
+--      per-root provisioning RATE cap (the concurrent max_active_children cap does not
+--      stop mint->expire->mint cumulative fan-out).
+--
+-- F2 (non-blocking, documented): policy revocation is NOT a sticky kill-switch under
+-- self-service — a root can re-upsert a fresh unrevoked policy row. Agent deactivation
+-- (_agent_principal_active) is the durable lockdown lever; revoked_at on a policy is not.
+--
+-- Additive, forward-only. schema_version stays 8 (helper + trigger + one table + two
+-- function recreations; no data-shape change here — the backfill ships in 20260822000200).
+-- The mint signature widens 5 -> 6 args (trailing p_self_service boolean default false),
+-- so the 5-arg function is DROPped and recreated; existing 4-/5-positional callers still
+-- resolve (the new arg defaults false => the pre-existing operator behavior is unchanged).
+-- =============================================================================
+
+-- ---------------------------------------------------------------------------
+-- 1. _raw_key_fingerprint — the ONE canonical raw-byte fingerprint derivation.
+--    Decodes base64url -> raw 32 bytes, REJECTS a non-canonical (aliased) encoding,
+--    and returns 'sha256:' over the RAW bytes. Byte-identical to enroll's derivation
+--    (20260724000200:120-123) and the client child_keygen keyRef.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._raw_key_fingerprint(p_public_key text)
+returns text
+language plpgsql
+immutable
+set search_path = agent_board, public
+as $$
+declare
+  v_raw bytea;
+  v_reencoded text;
+begin
+  if p_public_key is null or p_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+    raise exception 'malformed public key: expected a 43-char base64url raw Ed25519 key'
+      using errcode = '22023';
+  end if;
+  -- 43 base64url chars encode 32 bytes with a single '=' pad for the standard alphabet.
+  v_raw := decode(translate(p_public_key, '-_', '+/') || '=', 'base64');
+  if octet_length(v_raw) <> 32 then
+    raise exception 'public key must decode to exactly 32 raw Ed25519 bytes'
+      using errcode = '22023';
+  end if;
+  -- A 32-byte key has 2 don't-care low bits, so up to 4 distinct base64url strings
+  -- decode to the same key. Require the canonical re-encode to equal the input so ONE
+  -- keypair maps to exactly ONE fingerprint (dedup + squat backstop across all writers).
+  v_reencoded := rtrim(translate(encode(v_raw, 'base64'), '+/', '-_'), '=');
+  if v_reencoded is distinct from p_public_key then
+    raise exception 'public key is not canonical base64url (aliased encoding rejected)'
+      using errcode = '22023';
+  end if;
+  return 'sha256:' || rtrim(translate(encode(extensions.digest(v_raw, 'sha256'), 'base64'), '+/', '-_'), '=');
+end;
+$$;
+
+comment on function agent_board._raw_key_fingerprint(text) is
+  'The single canonical raw-byte signing-key fingerprint derivation: decode base64url -> '
+  'raw 32 bytes, reject a non-canonical (aliased) encoding, return sha256:base64url over '
+  'the RAW bytes. Every agent_signing_keys.fingerprint writer (mint_delegated_child, '
+  'enroll_federated_identity) MUST derive through this — a catalog sweep pins it.';
+
+revoke all on function agent_board._raw_key_fingerprint(text) from public, anon, authenticated;
+grant execute on function agent_board._raw_key_fingerprint(text) to service_role;
+
+-- ---------------------------------------------------------------------------
+-- 2. Table-boundary integrity trigger. Recompute the fingerprint from public_key for
+--    the raw format and raise on mismatch, catching direct/dynamic DML the function
+--    sweep cannot see. Skips unrelated UPDATEs (neither key nor fingerprint changed) so
+--    a legacy row predating the backfill stays operable until 20260822000200 corrects it.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._enforce_raw_key_fingerprint()
+returns trigger
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_expected text;
+begin
+  if new.public_key_format is distinct from 'raw_ed25519_base64url' then
+    return new;
+  end if;
+  -- Skip only a genuinely unrelated UPDATE: neither the key, the fingerprint, NOR the
+  -- format changed. Validating every transition INTO the raw format (format changed) closes
+  -- the toggle bypass — flip a raw row to a non-raw format with a bogus fingerprint (non-raw
+  -- rows skip validation), then flip back keeping key+fingerprint, and without the format
+  -- clause the short-circuit would smuggle the mismatch through.
+  if tg_op = 'UPDATE'
+     and new.public_key is not distinct from old.public_key
+     and new.fingerprint is not distinct from old.fingerprint
+     and new.public_key_format is not distinct from old.public_key_format then
+    return new;
+  end if;
+  v_expected := agent_board._raw_key_fingerprint(new.public_key);
+  if new.fingerprint is distinct from v_expected then
+    raise exception 'agent_signing_keys.fingerprint (%) does not match the canonical raw-byte derivation of public_key (expected %)',
+      new.fingerprint, v_expected
+      using errcode = '23514';
+  end if;
+  return new;
+end;
+$$;
+
+comment on function agent_board._enforce_raw_key_fingerprint() is
+  'BEFORE INSERT OR UPDATE trigger on agent_signing_keys: for raw_ed25519_base64url keys, '
+  'asserts fingerprint = _raw_key_fingerprint(public_key), catching direct/dynamic DML the '
+  'pg_get_functiondef sweep misses. Skips unrelated UPDATEs so pre-backfill legacy rows stay operable.';
+
+revoke all on function agent_board._enforce_raw_key_fingerprint() from public, anon, authenticated;
+
+drop trigger if exists trg_agent_signing_keys_raw_fingerprint on agent_board.agent_signing_keys;
+create trigger trg_agent_signing_keys_raw_fingerprint
+  before insert or update on agent_board.agent_signing_keys
+  for each row
+  execute function agent_board._enforce_raw_key_fingerprint();
+
+-- ---------------------------------------------------------------------------
+-- 3. Per-root provisioning RATE cap (authenticated mint path). Mirrors
+--    check_and_bump_enroll_rate (20260719000300): records+allows while under the cap in
+--    the rolling window, returns false (recording nothing) at/over it. The concurrent
+--    max_active_children cap bounds LIVE children; this bounds cumulative
+--    mint->expire->mint fan-out of agents/auth.users rows.
+-- ---------------------------------------------------------------------------
+create table if not exists agent_board.child_mint_rate_events (
+  id uuid primary key default gen_random_uuid(),
+  root_agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  created_at timestamptz not null default now()
+);
+
+comment on table agent_board.child_mint_rate_events is
+  'Per-root rolling-window provisioning rate-cap events for the authenticated (EF-mediated) '
+  'mint_delegated_child path. Bounds cumulative mint->expire->mint fan-out the concurrent '
+  'max_active_children cap cannot.';
+
+create index if not exists idx_agent_board_child_mint_rate_root_created
+  on agent_board.child_mint_rate_events(root_agent_id, created_at desc);
+
+grant select, insert on agent_board.child_mint_rate_events to service_role;
+
+create or replace function agent_board._check_and_bump_child_mint_rate(
+  p_root_agent_id uuid,
+  p_limit integer,
+  p_window interval
+)
+returns boolean
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_count integer;
+begin
+  if p_root_agent_id is null then
+    raise exception 'root agent id is required' using errcode = '22023';
+  end if;
+  if p_limit is null or p_limit < 0 then
+    raise exception 'child mint rate limit must be non-negative' using errcode = '22023';
+  end if;
+
+  select count(*)
+    into v_count
+    from agent_board.child_mint_rate_events e
+   where e.root_agent_id = p_root_agent_id
+     and e.created_at > now() - coalesce(p_window, interval '1 hour');
+
+  if v_count >= p_limit then
+    return false;
+  end if;
+
+  insert into agent_board.child_mint_rate_events(root_agent_id) values (p_root_agent_id);
+  return true;
+end;
+$$;
+
+comment on function agent_board._check_and_bump_child_mint_rate(uuid, integer, interval) is
+  'Rolling per-root provisioning rate cap for the authenticated mint path: records+allows '
+  'while under p_limit in p_window, rejects (without recording) at/over the cap. service_role-only.';
+
+revoke all on function agent_board._check_and_bump_child_mint_rate(uuid, integer, interval) from public, anon, authenticated;
+grant execute on function agent_board._check_and_bump_child_mint_rate(uuid, integer, interval) to service_role;
+
+-- ---------------------------------------------------------------------------
+-- 4. mint_delegated_child — recreated. Signature widens to add a trailing
+--    p_self_service boolean default false (the EF-forwarded authenticated-path flag).
+--    STAYS service_role-only (topology A); direct authenticated EXECUTE remains revoked.
+--    Verbatim from 20260718001000 except: raw-byte fingerprint via _raw_key_fingerprint,
+--    non-positive-TTL floor, and the self-service F1 re-clamp + per-root rate cap.
+-- ---------------------------------------------------------------------------
+drop function if exists agent_board.mint_delegated_child(uuid, text, jsonb, text, interval);
+
+create or replace function agent_board.mint_delegated_child(
+  p_root_agent_id uuid,
+  p_child_slug text,
+  p_requested_scopes jsonb,
+  p_child_public_key text default null,
+  p_ttl interval default null,
+  p_self_service boolean default false
+)
+returns table(
+  child_agent_id uuid,
+  grant_expires_at timestamptz,
+  signing_key_id uuid
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_policy agent_board.delegation_policies%rowtype;
+  v_root agent_board.agents%rowtype;
+  v_slug text;
+  v_requested jsonb := coalesce(p_requested_scopes, '[]'::jsonb);
+  v_allowed jsonb;
+  v_active_children int;
+  v_child_auth_user_id uuid;
+  v_child_id uuid;
+  v_key_id uuid := null;
+  v_grant_expires_at timestamptz;
+  v_effective_max int;
+  v_ceiling interval;
+  -- Per-root provisioning rate cap for the authenticated (self-service) path.
+  v_rate_limit constant int := 25;
+  v_rate_window constant interval := interval '1 hour';
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'mint_delegated_child is service_role-only' using errcode = '42501';
+  end if;
+
+  -- Non-positive TTL floor: an immediately-expired grant escapes the
+  -- max_active_children count while still provisioning an auth user/agent/key.
+  if p_ttl is not null and p_ttl <= interval '0' then
+    raise exception 'non_positive_ttl: requested grant TTL must be positive' using errcode = '22023';
+  end if;
+
+  v_slug := agent_board._normalize_provision_slug(p_child_slug);
+
+  -- Root must exist.
+  select * into v_root from agent_board.agents where id = p_root_agent_id;
+  if not found then
+    raise exception 'root agent not found' using errcode = 'P0002';
+  end if;
+
+  -- Root policy must exist, be unrevoked, and be root_minted. #11: take a row lock
+  -- on the policy up front so a concurrent mint against the same root serializes
+  -- here — the max_active_children count->insert below cannot then be raced past
+  -- the ceiling (TOCTOU close).
+  select * into v_policy
+    from agent_board.delegation_policies dp
+   where dp.root_agent_id = p_root_agent_id
+     and dp.revoked_at is null
+   order by dp.created_at desc
+   limit 1
+   for update;
+  if not found then
+    raise exception 'no active delegation policy for root agent' using errcode = '42501';
+  end if;
+  if v_policy.mode <> 'root_minted' then
+    raise exception 'delegation policy mode is not root_minted (independent_auth children self-provision)' using errcode = '42501';
+  end if;
+
+  -- Root principal must be active (self + lineage).
+  if not agent_board._agent_principal_active(p_root_agent_id) then
+    raise exception 'principal_inactive: root agent principal is not fully active' using errcode = '42501';
+  end if;
+
+  -- max_depth = 1 / no transitive minting: p_root_agent_id must be a TRUE lineage
+  -- root (unparented) and must not itself be a delegated child.
+  if v_root.parent_agent_id is not null then
+    raise exception 'max_depth: only a true lineage root may mint (no transitive delegation)' using errcode = '42501';
+  end if;
+  if exists (select 1 from agent_board.delegation_grants g where g.child_agent_id = p_root_agent_id) then
+    raise exception 'max_depth: a delegated child may not mint further children' using errcode = '42501';
+  end if;
+
+  -- Scope subset: requested ⊆ allowed (JSON array containment). A NULL allowed_scopes
+  -- means the root carries no delegable scope, so only an empty request is a subset.
+  v_allowed := coalesce(v_policy.allowed_scopes, '[]'::jsonb);
+  if not (v_allowed @> v_requested) then
+    raise exception 'scope_exceeded: requested scopes are not a subset of the root allowed_scopes' using errcode = '42501';
+  end if;
+
+  -- max_active_children: the root's live (non-revoked, unexpired) grant count must
+  -- remain within the ceiling after this mint.
+  if p_self_service then
+    -- F1: never trust the stored caps on the authenticated (EF-forwarded) path. A root
+    -- can self-widen its own operator_vetted policy row (#142), so re-clamp at mint —
+    -- NULL is treated as the 25-child ceiling, and any stored value above 25 is clamped
+    -- down. The authenticated path can NEVER mint uncapped.
+    v_effective_max := least(coalesce(v_policy.max_active_children, 25), 25);
+    select count(*) into v_active_children
+      from agent_board.delegation_grants g
+     where g.root_agent_id = p_root_agent_id
+       and g.revoked_at is null
+       and g.grant_expires_at > now();
+    if v_active_children >= v_effective_max then
+      raise exception 'max_active_children: root has reached its active delegated-child ceiling' using errcode = '42501';
+    end if;
+  elsif v_policy.max_active_children is not null then
+    -- Operator path: trusted caps as supplied (NULL = unbounded, operator's choice).
+    select count(*) into v_active_children
+      from agent_board.delegation_grants g
+     where g.root_agent_id = p_root_agent_id
+       and g.revoked_at is null
+       and g.grant_expires_at > now();
+    if v_active_children >= v_policy.max_active_children then
+      raise exception 'max_active_children: root has reached its active delegated-child ceiling' using errcode = '42501';
+    end if;
+  end if;
+
+  -- Per-root provisioning RATE cap (authenticated path only): bounds cumulative
+  -- mint->expire->mint fan-out. Enforced after the gates so only would-be-successful
+  -- mints consume budget, before any provisioning.
+  if p_self_service then
+    if not agent_board._check_and_bump_child_mint_rate(p_root_agent_id, v_rate_limit, v_rate_window) then
+      raise exception 'mint_rate_exceeded: root has reached its provisioning rate cap for the current window' using errcode = '42501';
+    end if;
+  end if;
+
+  -- Provision the child: parent = root = p_root_agent_id, same owner_user_id, own
+  -- auth binding (distinct auth_user_id for the active-unique index).
+  v_child_auth_user_id := agent_board._ensure_agent_auth_user(v_slug);
+
+  insert into agent_board.agents(
+    agent_type, kind, handle, display_name, status,
+    auth_user_id, owner_user_id, parent_agent_id, root_agent_id, metadata
+  )
+  values (
+    'agent', 'agent'::agent_board.agent_kind, v_slug,
+    agent_board._default_provision_display_name(v_slug), 'active',
+    v_child_auth_user_id, v_root.owner_user_id, p_root_agent_id, p_root_agent_id,
+    jsonb_build_object('delegatedByRootAgentId', p_root_agent_id, 'grantedScopes', v_requested)
+  )
+  returning id into v_child_id;
+
+  -- Scoped REVOCABLE signing key when the policy requires it. #5: the child's
+  -- public key MUST be supplied by the caller (generated client-side; the private
+  -- key never touches the DB). We NEVER seed a placeholder/zero key and NEVER
+  -- generate a key in-DB. status='active' + proof_state='proven' so the child can
+  -- immediately re-sign with the private key it already holds. The fingerprint is
+  -- derived over the RAW 32 bytes via _raw_key_fingerprint (single-sourced with enroll;
+  -- rejects a non-canonical alias) so the same key hashes identically across writers.
+  if v_policy.require_child_signing_key then
+    if p_child_public_key is null then
+      raise exception 'a child public key is required when the delegation policy requires a signing key' using errcode = '22023';
+    end if;
+    -- Raw Ed25519 public keys are 32 bytes => 43 base64url chars (no padding).
+    if p_child_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+      raise exception 'malformed child public key: expected a 43-char base64url raw Ed25519 key' using errcode = '22023';
+    end if;
+    -- Reject the all-''A'' key: 43 base64url ''A''s decode to 32 zero bytes (a
+    -- small-order point), which is exactly the retired placeholder.
+    if p_child_public_key = repeat('A', 43) then
+      raise exception 'child public key is the all-zero small-order placeholder and is rejected' using errcode = '22023';
+    end if;
+
+    insert into agent_board.agent_signing_keys(
+      id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint,
+      status, proof_state, metadata
+    )
+    values (
+      gen_random_uuid(), v_child_id, 'delegated-ephemeral', 1, p_child_public_key,
+      'raw_ed25519_base64url',
+      agent_board._raw_key_fingerprint(p_child_public_key),
+      'active', 'proven',
+      jsonb_build_object('ephemeral', true, 'scopes', v_requested)
+    )
+    returning id into v_key_id;
+  end if;
+
+  -- Grant row: ceiling-bounded hours-scale working clock. On the authenticated path the
+  -- TTL ceiling is itself re-clamped to <= 24h (F1) — the stored ceiling is not trusted.
+  if p_self_service then
+    v_ceiling := least(coalesce(v_policy.child_ttl_ceiling, interval '24 hours'), interval '24 hours');
+  else
+    v_ceiling := v_policy.child_ttl_ceiling;
+  end if;
+  v_grant_expires_at := now() + least(coalesce(p_ttl, v_ceiling), v_ceiling);
+
+  insert into agent_board.delegation_grants(
+    child_agent_id, root_agent_id, parent_agent_id, delegation_policy_id,
+    granted_scopes, grant_expires_at
+  )
+  values (
+    v_child_id, p_root_agent_id, p_root_agent_id, v_policy.id,
+    v_requested, v_grant_expires_at
+  );
+
+  return query select v_child_id, v_grant_expires_at, v_key_id;
+end;
+$$;
+
+comment on function agent_board.mint_delegated_child(uuid, text, jsonb, text, interval, boolean) is
+  'Mints a bounded root_minted delegated child (scope ⊆ root allowed_scopes, max_depth=1, '
+  'policy-row-locked max_active_children, positive ceiling-bounded grant TTL) enrolling the '
+  'CALLER-SUPPLIED Ed25519 public key with a RAW-byte fingerprint (_raw_key_fingerprint; '
+  'private key stays client-side). service_role-only. p_self_service marks the EF-forwarded '
+  'authenticated path: it re-clamps max_active_children to least(coalesce(stored,25),25) and '
+  'the TTL ceiling to <=24h (stored caps are NOT trusted — a root can self-widen its policy, '
+  '#142) and applies a per-root provisioning rate cap. Direct authenticated EXECUTE stays revoked.';
+
+revoke all on function agent_board.mint_delegated_child(uuid, text, jsonb, text, interval, boolean) from public, anon, authenticated;
+grant execute on function agent_board.mint_delegated_child(uuid, text, jsonb, text, interval, boolean) to service_role;
+
+-- ---------------------------------------------------------------------------
+-- 5. enroll_federated_identity — recreated to derive its fingerprint through the SAME
+--    _raw_key_fingerprint helper (single source of truth for the catalog sweep). The
+--    14-arg (ROOMLINK) function from 20260724000200 is reproduced VERBATIM except the
+--    fingerprint COMPUTATION (its inline raw-byte block) is replaced by the helper call;
+--    the released 20260724000200 bytes are NOT edited. Signature is unchanged, so no
+--    caller and no existence assertion moves.
+-- ---------------------------------------------------------------------------
+drop function if exists agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text);
+
+create or replace function agent_board.enroll_federated_identity(
+  p_issuer text,
+  p_audience text,
+  p_subject text,
+  p_human_identity_claim jsonb,
+  p_slug text,
+  p_agent_public_key text,
+  p_agent_public_key_format text,
+  p_agent_public_key_fingerprint text,
+  p_pop_verified boolean,
+  p_actor_sub text default null,
+  p_agent_kind text default 'agent',
+  p_requested_scopes text[] default '{}',
+  p_requested_board_scopes text[] default '{}',
+  p_invite_code text default null
+)
+returns table(
+  agent_id uuid,
+  auth_user_id uuid,
+  provider_id text,
+  signing_key_id uuid,
+  granted_scopes text[],
+  key_id text,
+  key_version int,
+  agent_handle text,
+  invite_redeemed boolean
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_slug text;
+  v_kind text;
+  v_provider agent_board.identity_providers%rowtype;
+  v_owner_user_id uuid;
+  v_auth_user_id uuid;
+  v_agent_handle text;
+  v_agent_id uuid;
+  v_signing_key_id uuid;
+  v_fingerprint text;
+  v_key_hex text;
+  v_raw_key bytea;
+  v_reencoded text;
+  v_key_id text := 'portal-enroll';
+  v_key_version int := 1;
+  v_requested_scopes text[] := coalesce(p_requested_scopes, '{}');
+  v_requested_board_scopes text[] := coalesce(p_requested_board_scopes, '{}');
+  v_invite_code text := nullif(trim(coalesce(p_invite_code, '')), '');
+  v_invite_redeemed boolean := false;
+begin
+  -- 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_identity' using errcode = '42501';
+  end if;
+
+  -- 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;
+
+  -- (0) PoP gate — the EF Ed25519-verified the proof-of-possession over the token
+  -- bytes and passes true. Refuse false BEFORE any write (no agent/key/audit row).
+  if p_pop_verified is not true then
+    raise exception 'proof-of-possession was not verified; enrollment refused'
+      using errcode = '42501';
+  end if;
+
+  -- (1) Public-key shape gate. The enroll contract is raw Ed25519 (32 bytes -> 43
+  -- base64url chars).
+  if p_agent_public_key_format is distinct from 'raw_ed25519_base64url' then
+    raise exception 'agent public key format must be raw_ed25519_base64url' using errcode = '22023';
+  end if;
+  if p_agent_public_key is null or p_agent_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+    raise exception 'malformed agent public key: expected a 43-char base64url raw Ed25519 key'
+      using errcode = '22023';
+  end if;
+
+  -- (1a) B2 — decode base64url -> raw 32 bytes and REJECT any non-canonical encoding.
+  v_raw_key := decode(translate(p_agent_public_key, '-_', '+/') || '=', 'base64');
+  if octet_length(v_raw_key) <> 32 then
+    raise exception 'agent public key must decode to exactly 32 raw Ed25519 bytes'
+      using errcode = '22023';
+  end if;
+  v_reencoded := rtrim(translate(encode(v_raw_key, 'base64'), '+/', '-_'), '=');
+  if v_reencoded is distinct from p_agent_public_key then
+    raise exception 'agent public key is not canonical base64url (aliased encoding rejected)'
+      using errcode = '22023';
+  end if;
+
+  -- (1b) Reject the all-zero small-order placeholder over the RAW bytes.
+  if v_raw_key = decode(repeat('00', 32), 'hex') then
+    raise exception 'agent public key is the all-zero small-order placeholder and is rejected'
+      using errcode = '22023';
+  end if;
+
+  -- (2) Recompute-and-assert the fingerprint in-DB over the RAW 32 bytes. Derived through
+  -- the shared _raw_key_fingerprint helper (single source of truth; catalog-sweep-pinned).
+  v_fingerprint := agent_board._raw_key_fingerprint(p_agent_public_key);
+  if p_agent_public_key_fingerprint is distinct from v_fingerprint then
+    raise exception 'agent public key fingerprint mismatch (recompute != supplied)'
+      using errcode = '22023';
+  end if;
+
+  -- (3) act.sub is audit-only, but when present it must be a real value.
+  if p_actor_sub is not null and length(trim(p_actor_sub)) = 0 then
+    raise exception 'actor sub, when present, must be non-empty' using errcode = '22023';
+  end if;
+
+  v_slug := agent_board._normalize_provision_slug(p_slug);
+  v_kind := lower(coalesce(trim(p_agent_kind), ''));
+
+  -- (4) allowlist lookup by (issuer, audience); must exist + supported + policy-approved.
+  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) scope-ceiling + kind gate. 'system' is never federatable.
+  if v_kind = 'system' then
+    raise exception 'the system kind cannot be federated' using errcode = '42501';
+  end if;
+  if v_kind not in ('human', 'agent') then
+    raise exception 'agent kind must be human or agent' using errcode = '22023';
+  end if;
+  if array_length(v_provider.allowed_agent_kinds, 1) is not null
+     and not (v_kind = any (v_provider.allowed_agent_kinds)) then
+    raise exception 'agent kind % is outside the provider ceiling', v_kind using errcode = '42501';
+  end if;
+  if not (v_requested_scopes <@ v_provider.allowed_scopes) then
+    raise exception 'requested scopes exceed the provider allowed_scopes ceiling' using errcode = '42501';
+  end if;
+  if not (v_requested_board_scopes <@ v_provider.allowed_board_scopes) then
+    raise exception 'requested board scopes exceed the provider allowed_board_scopes ceiling' using errcode = '42501';
+  end if;
+
+  -- (6) dedup on the enrolled key: a fingerprint already enrolled cannot be re-bound.
+  if exists (select 1 from agent_board.agent_signing_keys k where k.fingerprint = v_fingerprint) then
+    raise exception 'this signing key is already enrolled (duplicate fingerprint)'
+      using errcode = '23505';
+  end if;
+
+  -- (7) HUMAN OWNER — established idempotently per (issuer, sub).
+  v_owner_user_id := agent_board._ensure_agent_auth_user(
+    'fed-human-' || substr(encode(extensions.digest(convert_to(p_issuer || '|' || p_subject, 'UTF8'), 'sha256'), 'hex'), 1, 32));
+
+  -- (8) AGENT handle — unique per enrolled key.
+  v_key_hex := encode(extensions.digest(v_raw_key, 'sha256'), 'hex');
+  v_agent_handle := v_slug;
+  if exists (select 1 from agent_board.agents a where a.handle = v_agent_handle) then
+    v_agent_handle := v_slug || '-' || substr(v_key_hex, 1, 12);
+  end if;
+
+  -- (9) the agent's OWN board principal (session-usable via its enrolled key).
+  v_auth_user_id := agent_board._ensure_agent_auth_user(v_agent_handle);
+
+  -- (10) create the SEPARATE agent row (never keyed on sub; owner = the human).
+  insert into agent_board.agents(
+    agent_type,
+    kind,
+    handle,
+    display_name,
+    status,
+    auth_user_id,
+    owner_user_id,
+    metadata
+  )
+  values (
+    v_kind,
+    v_kind::agent_board.agent_kind,
+    v_agent_handle,
+    agent_board._default_provision_display_name(v_agent_handle),
+    'active',
+    v_auth_user_id,
+    v_owner_user_id,
+    jsonb_build_object(
+      'federation', jsonb_build_object(
+        'issuer', p_issuer,
+        'audience', p_audience,
+        'subject', p_subject,
+        'actorSub', p_actor_sub,
+        'providerId', v_provider.id,
+        'signingKeyFingerprint', v_fingerprint,
+        'requestedScopes', to_jsonb(v_requested_scopes),
+        'requestedBoardScopes', to_jsonb(v_requested_board_scopes),
+        'popVerified', true,
+        'enrolledAt', now()
+      )
+    )
+  )
+  returning id into v_agent_id;
+
+  -- (11) enroll the public key as active + proven (satisfies active_requires_proof).
+  insert into agent_board.agent_signing_keys(
+    id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint,
+    status, proof_state, metadata
+  )
+  values (
+    gen_random_uuid(), v_agent_id, v_key_id, v_key_version, p_agent_public_key,
+    p_agent_public_key_format, v_fingerprint,
+    'active', 'proven',
+    jsonb_build_object('enrolledVia', 'federated_identity', 'popVerified', true)
+  )
+  returning id into v_signing_key_id;
+
+  -- (12) one static claim-snapshot audit row (the verified claim contains act.sub).
+  insert into agent_board.enrollment_federation_audit(
+    issuer, audience, subject, human_identity_claim, provider_id,
+    agent_id, auth_user_id, requested_scopes, granted_scopes
+  )
+  values (
+    p_issuer, p_audience, p_subject, p_human_identity_claim, v_provider.id,
+    v_agent_id, v_auth_user_id, v_requested_scopes, v_requested_scopes
+  );
+
+  -- (13) ROOMLINK soft-honor: if a code is present, redeem it into a bounded board
+  -- membership for the freshly-created agent. Wrapped in a subtransaction so a
+  -- bad/expired/exhausted/unauthorized code rolls back ONLY this sub-block — the
+  -- agent-create above persists and enrollment still succeeds (invite_redeemed=false).
+  if v_invite_code is not null then
+    begin
+      perform agent_board._redeem_invite_for_agent(v_invite_code, v_agent_id);
+      v_invite_redeemed := true;
+    exception when others then
+      v_invite_redeemed := false;
+    end;
+  end if;
+
+  -- Server-authoritative identity: the client mints /session with the RETURNED
+  -- key_id/key_version/agent_handle (its private key stays in the keystore).
+  return query
+  select v_agent_id, v_auth_user_id, v_provider.id, v_signing_key_id, v_requested_scopes,
+         v_key_id, v_key_version, v_agent_handle, v_invite_redeemed;
+end;
+$$;
+
+comment on function agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text) is
+  'PoP-at-enrollment federated identity (ROOMLINK-extended). Same server-authoritative '
+  'identity establishment as 20260724000200, with the fingerprint derived through the shared '
+  '_raw_key_fingerprint helper (single source of truth; catalog-sweep-pinned). Optional '
+  'trailing p_invite_code soft-honored via _redeem_invite_for_agent in a BEGIN/EXCEPTION '
+  'subtransaction (bad code -> enrollment still succeeds, invite_redeemed=false). '
+  'service_role-only; never returns a Portal token.';
+
+revoke all on function agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  from public, anon, authenticated;
+grant execute on function agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  to service_role;