@consiliency/agent-board-schema 1.24.0 → 1.25.0

package/migrations/20260906000100_agent_board_enroll_resumption.sql

@@ -0,0 +1,749 @@
+-- Consiliency/message-board#176 -- ENROLL RESUMPTION.
+--
+-- WHAT HAPPENED, LIVE. An agent enrolled. `/enroll` SUCCEEDED: agent row, signing
+-- key, human owner, proof_state=proven, all committed. Post-enroll provisioning then
+-- failed (#173) and the client reported the WHOLE operation failed. Every retry after
+-- that was refused with `23505 this signing key is already enrolled (duplicate
+-- fingerprint)`, surfaced as an opaque 403. The agent held a valid identity for hours
+-- while the tooling insisted it had none, and its loop could never succeed.
+--
+-- WHAT ALREADY EXISTS, AND WHY IT DID NOT SAVE THE VICTIM. 20260901000100 (merged the
+-- day AFTER #176 was filed) wrapped the creator in a replay path that DOES return the
+-- existing identity for an exact re-presentation. That path is gated on a
+-- `metadata.federation.replay` STAMP the wrapper writes at creation time. Every
+-- identity enrolled BEFORE that migration -- including the #176 victim -- has no stamp,
+-- so `v_replay is null` sent it straight to
+-- `23505 enrollment replay conflicts with the frozen identity contract`: a different
+-- message for the same dead end. The trap is still shut for exactly the enrollments
+-- that fell into it.
+--
+-- THE FIX, in one sentence: an already-enrolled key presented by the principal that
+-- OWNS it is a RESUMPTION, not a violation. There is ONE resumption implementation and
+-- it stays in the wrapper (agent_board.enroll_federated_identity). The internal creator
+-- deliberately does NOT grow a second one -- a twin predicate is how this repo has
+-- drifted before, and the creator lacks the wrapper's claim-projection equality gate,
+-- so a resumption decided there would rest on bare parameters.
+--
+-- WHERE THE OWNERSHIP TEST GETS ITS PRINCIPAL, and why that source is EVIDENCE.
+-- The DB session here is service_role (the /enroll edge function), which is the
+-- verifier: it validated the Portal JWT signature and projected the verified claim.
+-- `p_issuer`/`p_subject` are therefore trusted ONLY because the wrapper already
+-- equality-gates them against the verified claim projection it was handed
+-- (`p_human_identity_claim ->> 'iss'`, `->> subject_claim`, and the normalized `aud`
+-- must all match, above -- that gate is unchanged and runs BEFORE anything here).
+-- Ownership is then decided by comparing that gated principal against evidence WRITTEN
+-- AT THE ORIGINAL ENROLLMENT, never against a caller argument describing who acted:
+--   (i)   agents.owner_user_id equals the auth user DERIVED from
+--         sha256(issuer|subject) -- the same one-way derivation step (7) used to mint
+--         it, so a different principal derives a different owner and cannot collide;
+--   (ii)  agents.metadata->'federation'->>'issuer'/'subject'/'providerId', written by
+--         step (10) from the EF-verified inputs of the ORIGINAL enrollment;
+--   (iii) a matching agent_board.enrollment_federation_audit row (agent, issuer,
+--         subject, provider) -- the original enrollment's own audit record.
+-- (ii) and (iii) are REQUIRED. (i) is required WHENEVER IT EXISTS: a non-null
+-- owner_user_id that disagrees with the derived one is a hard refusal, and the single
+-- exemption is a row with NO owner_user_id at all, which predates the owner model
+-- entirely (the atomic-fleet backfill fixture is exactly that shape and replaying it is
+-- released, asserted behaviour). Stated positively, because an exemption asserted only
+-- by absence is how this repo has been bitten: such a row still proves ownership through
+-- (ii) and (iii), which name the principal on their own, and reaching them at all
+-- requires a claim the edge function VERIFIED for that same issuer and subject. The
+-- exemption therefore narrows corroboration without widening who may resume, and it is
+-- pinned in BOTH directions (a null-owner row resumes for its owner; the same row still
+-- refuses a different subject).
+-- The whole predicate is `coalesce(<conjunction>, false)`, because a NULL from any
+-- missing evidence must read as NOT-OWNED, not as an untaken `if not`.
+-- The derived-owner lookup is a pure SELECT against auth.users by the derived email --
+-- it must NOT call _ensure_agent_auth_user, which would MINT an owner row for whatever
+-- principal a squat attempt claimed.
+--
+-- THE THREE OUTCOMES, each with its own message:
+--   (a) NOT owned by the caller -> raise 23505. This is the key-squat the check exists
+--       to prevent and it is checked FIRST, so a non-owner learns nothing about the
+--       key's state. The message names NO handle: telling a squatter which agent holds
+--       the key it just probed is the leak this ordering avoids.
+--   (b) owned, but the identity is not resumable (key or agent inactive, unproven,
+--       public key/format drift, or an audit row recording no granted scopes) -> raise
+--       23505 naming the handle. Resumption never revives a revoked or unproven
+--       identity, and the granted-scopes disjunct is what keeps this branch reachable
+--       on its own rather than implied by (iii).
+--   (c) owned, resumable, and a replay STAMP is present but a frozen field differs ->
+--       raise 23505 naming the handle and saying enrollment need not be repeated. The
+--       frozen contract is NOT loosened; only its message improves.
+--   otherwise -> return the existing identity (idempotent success), which is the
+--   resumption #176 asks for. `v_replay is null` (a pre-20260901000100 enrollment) is
+--   no longer a raise: (i)-(iii) are the whole basis, and they are exactly the evidence
+--   those rows do carry.
+--
+-- WHAT IS DELIBERATELY LEFT OUT. A legacy (unstamped) resumption does NOT write a
+-- `federation.replay` stamp. The stamp's `requestedSlug` is not recoverable from stored
+-- evidence -- only the RESULTING handle was persisted, and it may carry a collision
+-- suffix -- so a stamp built here would have to take the slug from the CURRENT request,
+-- which is not evidence of the original one and would freeze the contract around
+-- whatever the retry happened to send. Unstamped rows therefore keep resuming on
+-- (i)-(iii) every time. Consequence, stated plainly: for those rows a same-owner retry
+-- with a different slug or scope request resumes instead of raising. It cannot escalate
+-- -- `granted_scopes` is returned from the ORIGINAL audit row, never from the request --
+-- and it is the recovery #176 exists to provide.
+--
+-- LOCK ORDER (#194) IS UNCHANGED, and this migration acquires nothing new. The two
+-- additions are read-only: a `select ... from auth.users` by email (no FOR UPDATE, no
+-- row lock) and a `select 1 from enrollment_federation_audit` existence probe. Both sit
+-- AFTER the existing invite -> board -> fingerprint-advisory -> owner sequence, inside
+-- the region that already holds `for update of a, k` on the agent and key. The whole
+-- #194 header from 20260903000100 (board before owner; the FK this route never names;
+-- the FOR KEY SHARE reasoning; the two advisory edges) still applies verbatim and is
+-- reproduced at each of the two acquisition sites below.
+--
+-- The internal creator's step (6) still raises -- it is a backstop that the wrapper's
+-- dedup makes unreachable in practice (the wrapper is its ONLY caller; verified from
+-- pg_proc, and onboard_federated_fleet_agent calls the WRAPPER, not the creator) -- but
+-- the raise is now ACTIONABLE: it names the existing handle and says enrollment need
+-- not be repeated, which is the issue's minimum ask.
+--
+-- Both functions are recreated with CREATE OR REPLACE (ACL and COMMENT survive); the
+-- grants and comments are restated below regardless, per the repo rule. The bodies are
+-- byte-identical to 20260903000100 apart from the deltas described above.
+
+-- 1. the internal one-time creator (renamed core).
+create or replace function agent_board._enroll_federated_identity_once(
+  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;
+  v_invite_board_id uuid;
+  v_existing_handle text;
+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
+  -- HERE. #176: this is a BACKSTOP, not the resumption decision. enroll_federated_identity
+  -- is this function's only caller (pg_proc-verified) and it resolves an already-enrolled
+  -- fingerprint before ever reaching here, so a caller that lands on this raise reached the
+  -- internal creator directly. Resumption is deliberately NOT duplicated into this
+  -- function: it has no claim-projection equality gate, so an ownership decision made here
+  -- would rest on bare parameters rather than on the verified claim. What DID change is
+  -- that the raise is actionable -- it names the identity that already holds the key and
+  -- says enrollment need not be repeated.
+  --
+  -- The GATE is still the unchanged `exists` over agent_signing_keys alone. The handle is
+  -- looked up separately, for the MESSAGE only, through a join that a hypothetical
+  -- agent-less key would not satisfy: folding that join into the gate would have turned a
+  -- rendering nicety into a hole that lets such a key be re-bound.
+  if exists (select 1 from agent_board.agent_signing_keys k where k.fingerprint = v_fingerprint) then
+    select a.handle into v_existing_handle
+      from agent_board.agent_signing_keys k
+      join agent_board.agents a on a.id = k.agent_id
+     where k.fingerprint = v_fingerprint
+     limit 1;
+    raise exception 'this signing key is already enrolled (duplicate fingerprint) as agent "%"; enrollment need not be repeated; call agent_board.enroll_federated_identity, which RESUMES an enrollment whose key is owned by the same verified (issuer, subject)',
+      coalesce(v_existing_handle, '(unknown)')
+      using errcode = '23505';
+  end if;
+
+  -- #194 LOCK ORDER -- BOARD BEFORE OWNER, and the reason is an FK this function
+  -- never names. The redemption below inserts board_memberships, which takes FOR
+  -- KEY SHARE on the invite's agent_board.boards row through
+  -- board_memberships_board_id_fkey. That acquisition used to land AFTER the
+  -- auth.users owner lock, inverting against enroll_federated_human and
+  -- onboard_federated_fleet_agent -- both of which take board -> owner -- and the
+  -- resulting cycle was reproduced as `deadlock detected ... while locking tuple
+  -- in relation "boards"`. Acquire the invite row and its board here, in the same
+  -- relative order _redeem_unbounded_invite_for_agent and
+  -- onboard_federated_fleet_agent take them (invite -> board), and in the SAME mode
+  -- the redemption itself uses, so the redemption below acquires nothing new. Absence is deliberately NOT fatal: a missing,
+  -- revoked, expired or exhausted code still falls through to redemption, which
+  -- stays the sole authority on invite usability (soft-honor contract).
+  if v_invite_code is not null then
+    select bit.board_id into v_invite_board_id
+      from agent_board.board_invite_tokens bit
+     where bit.code = v_invite_code
+     for update;
+    if v_invite_board_id is not null then
+      perform 1 from agent_board.boards b
+       where b.id = v_invite_board_id
+       for key share;
+    end if;
+  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
+      -- #194: a serialization failure is NOT "the invite was not redeemed".
+      -- Swallowing class 40 here reported enrollment SUCCESS to the caller with
+      -- invite_redeemed=false and no membership row, while the deadlock counter
+      -- ticked and no error reached the client. Re-raise the whole class
+      -- (40001 serialization_failure, 40P01 deadlock_detected, 40003, 40002)
+      -- and keep the soft-honor contract for every deterministic failure.
+      if left(sqlstate, 2) = '40' then
+        raise;
+      end if;
+      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_once(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text) is
+  'Internal one-time federated-identity creator (the released 20260724000200/20260822000100 implementation, renamed by 20260901000100). Call only through enroll_federated_identity, which holds the invite/board and owner locks. Takes the invite row and its board BEFORE the owner is provisioned so the board -> owner order holds even on a direct service_role call (#194); the optional trailing p_invite_code is still soft-honored via _redeem_invite_for_agent in a BEGIN/EXCEPTION subtransaction (bad code -> enrollment still succeeds, invite_redeemed=false), EXCEPT for SQLSTATE class 40, which propagates rather than being reported as a non-redemption. CREATES ONLY: step (6) still refuses an already-enrolled fingerprint unconditionally and does NOT resume (#176) -- resumption has exactly one implementation and it lives in enroll_federated_identity, which is this function''s only caller and which gates the (issuer, subject) against the verified claim projection first. The step (6) raise names the agent that already holds the key and says enrollment need not be repeated.';
+revoke all on function agent_board._enroll_federated_identity_once(
+  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_once(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  to service_role;
+
+-- 2. the replay wrapper -- the route the Portal /enroll endpoint calls.
+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 $$
+#variable_conflict use_column
+declare
+  v_fingerprint text;
+  v_existing record;
+  v_created record;
+  v_replay jsonb;
+  v_invite_redeemed boolean := false;
+  v_slug text;
+  v_kind text := lower(btrim(coalesce(p_agent_kind, 'agent')));
+  v_requested_scopes text[] := coalesce(p_requested_scopes, '{}');
+  v_requested_board_scopes text[] := coalesce(p_requested_board_scopes, '{}');
+  v_provider agent_board.identity_providers%rowtype;
+  v_invite_board_id uuid;
+  v_claim_audience jsonb;
+  v_owner_user_id uuid;
+  -- #176 resumption. `v_derived_owner_user_id` is the auth user the CALLER's verified
+  -- (issuer, subject) derives to; `v_creation_federation` is the federation object the
+  -- ORIGINAL enrollment stamped on the agent; `v_owned_by_caller` is the conjunction of
+  -- the three stored-evidence tests, coalesced so missing evidence reads as NOT-owned.
+  v_derived_owner_user_id uuid;
+  v_creation_federation jsonb;
+  v_owned_by_caller boolean;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for enroll_federated_identity' using errcode = '42501';
+  end if;
+  if p_pop_verified is not true then
+    raise exception 'proof-of-possession was not verified' using errcode = '42501';
+  end if;
+  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;
+
+  select * into v_provider from agent_board.identity_providers ip
+   where ip.issuer = p_issuer and ip.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;
+
+  v_claim_audience := agent_board._normalized_federation_audience(p_human_identity_claim);
+  if p_human_identity_claim ->> 'iss' is distinct from p_issuer
+     or p_human_identity_claim ->> v_provider.subject_claim is distinct from p_subject
+     or v_claim_audience is null
+     or not (v_claim_audience ? p_audience) then
+    raise exception 'verified stable claim projection does not match enrollment inputs' using errcode = '22023';
+  end if;
+  if p_agent_public_key_format is distinct from 'raw_ed25519_base64url'
+     or p_agent_public_key is null or p_agent_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+    raise exception 'malformed agent public key' using errcode = '22023';
+  end if;
+  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' using errcode = '22023';
+  end if;
+  v_slug := agent_board._normalize_provision_slug(p_slug);
+
+  if not v_provider.supported or not v_provider.policy_approved then
+    raise exception 'identity provider is not approved' using errcode = '42501';
+  end if;
+  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' using errcode = '42501';
+  end if;
+  if not (v_requested_scopes <@ v_provider.allowed_scopes)
+     or not (v_requested_board_scopes <@ v_provider.allowed_board_scopes) then
+    raise exception 'requested scopes exceed the provider ceiling' using errcode = '42501';
+  end if;
+
+  if nullif(btrim(coalesce(p_invite_code, '')), '') is not null and exists (
+    select 1 from agent_board.board_invite_tokens bit
+    join agent_board.fleet_onboarding_invite_bounds b on b.invite_id = bit.id
+    where bit.code = btrim(p_invite_code)
+  ) then
+    raise exception 'fleet invite requires atomic fleet onboarding' using errcode = '42501';
+  end if;
+
+
+  -- #194 LOCK ORDER -- BOARD BEFORE OWNER, and the reason is an FK this function
+  -- never names. The redemption below inserts board_memberships, which takes FOR
+  -- KEY SHARE on the invite's agent_board.boards row through
+  -- board_memberships_board_id_fkey. That acquisition used to land AFTER the
+  -- auth.users owner lock, inverting against enroll_federated_human and
+  -- onboard_federated_fleet_agent -- both of which take board -> owner -- and the
+  -- resulting cycle was reproduced as `deadlock detected ... while locking tuple
+  -- in relation "boards"`. Acquire the invite row and its board here, in the same
+  -- relative order _redeem_unbounded_invite_for_agent and
+  -- onboard_federated_fleet_agent take them (invite -> board), and in the SAME mode
+  -- the redemption itself uses, so the redemption below acquires nothing new. Absence is deliberately NOT fatal: a missing,
+  -- revoked, expired or exhausted code still falls through to redemption, which
+  -- stays the sole authority on invite usability (soft-honor contract).
+  if nullif(btrim(coalesce(p_invite_code, '')), '') is not null then
+    select bit.board_id into v_invite_board_id
+      from agent_board.board_invite_tokens bit
+     where bit.code = nullif(btrim(coalesce(p_invite_code, '')), '')
+     for update;
+    if v_invite_board_id is not null then
+      perform 1 from agent_board.boards b
+       where b.id = v_invite_board_id
+       for key share;
+    end if;
+  end if;
+
+  perform pg_advisory_xact_lock(hashtextextended(v_fingerprint, 0));
+
+  select a.owner_user_id into v_owner_user_id
+    from agent_board.agent_signing_keys k
+    join agent_board.agents a on a.id = k.agent_id
+   where k.fingerprint = v_fingerprint;
+  v_owner_user_id := coalesce(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)
+  ));
+  perform 1 from auth.users u where u.id = v_owner_user_id for update;
+  if exists (
+    select 1 from agent_board.fleet_human_revocations r
+     where r.issuer = p_issuer and r.subject = p_subject
+  ) then
+    raise exception 'human owner has been revoked' using errcode = '42501';
+  end if;
+
+  -- #176 (i): the auth user the CALLER's verified (issuer, subject) derives to, by the
+  -- SAME one-way derivation _enroll_federated_identity_once step (7) used to mint the
+  -- owner. Resolved by a PURE LOOKUP against the deterministic email
+  -- _ensure_agent_auth_user builds -- calling that function here would MINT an owner row
+  -- for whatever principal a squat attempt claimed. Read-only: no FOR UPDATE, no row
+  -- lock, so the #194 board -> owner order above is untouched.
+  select u.id into v_derived_owner_user_id
+    from auth.users u
+   where lower(u.email) = format('agent+%s@agent-board.local',
+           'fed-human-' || substr(encode(extensions.digest(convert_to(p_issuer || '|' || p_subject, 'UTF8'), 'sha256'), 'hex'), 1, 32))
+   limit 1;
+
+  select a.id as agent_id, a.auth_user_id, a.handle, a.agent_type, a.status,
+         a.metadata, a.owner_user_id, k.id as signing_key_id, k.key_id, k.key_version,
+         k.public_key, k.public_key_format, k.status as key_status, k.proof_state,
+         (select e.granted_scopes
+            from agent_board.enrollment_federation_audit e
+           where e.agent_id = a.id
+             and e.issuer = p_issuer
+             and e.subject = p_subject
+             and e.provider_id = v_provider.id) as granted_scopes
+    into v_existing
+    from agent_board.agent_signing_keys k
+    join agent_board.agents a on a.id = k.agent_id
+   where k.fingerprint = v_fingerprint
+   for update of a, k;
+
+  if found then
+    v_replay := v_existing.metadata #> '{federation,replay}';
+    v_creation_federation := v_existing.metadata #> '{federation}';
+
+    -- #176 OWNERSHIP, from evidence written at the ORIGINAL enrollment -- never from a
+    -- caller argument asserting who acted. (i) the one-way-derived owner, (ii) the
+    -- creation-time federation stamp, (iii) the original enrollment's audit row. All
+    -- three must agree, and the whole conjunction is coalesced to FALSE: any NULL here
+    -- (absent metadata, absent owner) means ownership is UNPROVEN, and unproven must
+    -- read as not-owned rather than leaving the `if not` below untaken.
+    v_owned_by_caller := coalesce(
+          v_creation_federation ->> 'issuer' = p_issuer
+      and v_creation_federation ->> 'subject' = p_subject
+      and v_creation_federation ->> 'providerId' = v_provider.id
+      and exists (
+        select 1
+          from agent_board.enrollment_federation_audit e
+         where e.agent_id = v_existing.agent_id
+           and e.issuer = p_issuer
+           and e.subject = p_subject
+           and e.provider_id = v_provider.id
+      )
+      -- (i) is REQUIRED WHENEVER IT EXISTS and is the one conjunct with an exemption,
+      -- so its claim is stated positively rather than left as "unless". A row whose
+      -- owner_user_id is NULL predates the owner model entirely (the atomic-fleet
+      -- backfill fixture is exactly that shape, and replaying such a row is released,
+      -- asserted behaviour): (i) is UNAVAILABLE there, not contradicted. It is also not
+      -- the binding that does the work. (ii) and (iii) already name the principal, and
+      -- reaching them at all requires a claim the edge function VERIFIED for that same
+      -- issuer and subject, so a null owner narrows corroboration without widening who
+      -- may resume. A NON-NULL owner that disagrees with the derived one is a hard
+      -- refusal, which is what keeps this from being a hole.
+      and (
+        v_existing.owner_user_id is null
+        or (v_derived_owner_user_id is not null
+            and v_existing.owner_user_id = v_derived_owner_user_id)
+      ), false);
+
+    -- (a) THE KEY-SQUAT this check exists to prevent, and the FIRST thing decided, so a
+    -- caller that does not own the key learns nothing else about it. No handle is named:
+    -- telling a squatter which agent holds the key it just probed is the leak this
+    -- ordering avoids. Everything below runs only for the proven owner.
+    if not v_owned_by_caller then
+      raise exception 'this signing key is already enrolled to a different principal; enrollment is refused; generate a NEW key rather than re-presenting this one'
+        using errcode = '23505';
+    end if;
+
+    -- (b) the owner is asking to resume, but the identity is not in a resumable state.
+    -- Resumption returns an existing identity; it never revives a revoked, unproven or
+    -- drifted one, and it never invents an audit trail that is not there.
+    if v_existing.public_key is distinct from p_agent_public_key
+       or v_existing.public_key_format is distinct from p_agent_public_key_format
+       or v_existing.key_status <> 'active'
+       or v_existing.proof_state <> 'proven'
+       or v_existing.status <> 'active'
+       or v_existing.granted_scopes is null then
+      raise exception 'this signing key is already enrolled to you as agent "%", but that identity is not resumable (its key or agent is inactive or unproven, its stored public key differs, or its enrollment audit records no granted scopes); enrollment need not be repeated; report this handle to an operator',
+        v_existing.handle using errcode = '23505';
+    end if;
+
+    -- (c) a STAMPED enrollment (20260901000100 and later) still holds its frozen identity
+    -- contract exactly as before -- the check is unchanged, only its message improves to
+    -- name the handle and say the enrollment already exists. An UNSTAMPED enrollment
+    -- (every identity created before 20260901000100, including the #176 victim) has no
+    -- frozen contract to check and resumes on the ownership evidence alone; that absence
+    -- used to be the raise that trapped it.
+    if v_replay is not null
+       and (v_replay ->> 'issuer' is distinct from p_issuer
+         or v_replay -> 'audience' is distinct from v_claim_audience
+         or v_replay ->> 'subject' is distinct from p_subject
+         or v_replay ->> 'requestedSlug' is distinct from v_slug
+         or v_replay ->> 'agentKind' is distinct from v_kind
+         or v_replay -> 'actorSub' is distinct from coalesce(to_jsonb(p_actor_sub), 'null'::jsonb)
+         or v_replay -> 'requestedScopes' is distinct from to_jsonb(v_requested_scopes)
+         or v_replay -> 'requestedBoardScopes' is distinct from to_jsonb(v_requested_board_scopes)
+         or v_replay ->> 'providerId' is distinct from v_provider.id) then
+      raise exception 'this signing key is already enrolled to you as agent "%" (enrollment need not be repeated), but this request differs from that enrollment''s frozen identity contract (slug, agent kind, actor or requested scopes); re-send the original inputs, or use the existing identity as-is',
+        v_existing.handle using errcode = '23505';
+    end if;
+
+    if nullif(btrim(coalesce(p_invite_code, '')), '') is not null then
+      begin
+        perform agent_board._redeem_invite_for_agent(btrim(p_invite_code), v_existing.agent_id);
+        v_invite_redeemed := true;
+      exception when others then
+        -- #194: a serialization failure is NOT "the invite was not redeemed".
+        -- Swallowing class 40 here reported enrollment SUCCESS to the caller with
+        -- invite_redeemed=false and no membership row, while the deadlock counter
+        -- ticked and no error reached the client. Re-raise the whole class
+        -- (40001 serialization_failure, 40P01 deadlock_detected, 40003, 40002)
+        -- and keep the soft-honor contract for every deterministic failure.
+        if left(sqlstate, 2) = '40' then
+          raise;
+        end if;
+        v_invite_redeemed := false;
+      end;
+    end if;
+
+    -- provider_id comes from STORED evidence, not the request: the replay stamp when
+    -- there is one, otherwise the creation-time federation object. The ownership gate
+    -- already pinned that value to v_provider.id, so the two agree by construction --
+    -- but reading it from the row keeps the returned receipt sourced where every other
+    -- returned field is.
+    return query select v_existing.agent_id, v_existing.auth_user_id,
+      coalesce(v_replay ->> 'providerId', v_creation_federation ->> 'providerId'), v_existing.signing_key_id,
+      v_existing.granted_scopes, v_existing.key_id, v_existing.key_version,
+      v_existing.handle, v_invite_redeemed;
+    return;
+  end if;
+
+  select * into v_created from agent_board._enroll_federated_identity_once(
+    p_issuer, p_audience, p_subject, p_human_identity_claim, p_slug,
+    p_agent_public_key, p_agent_public_key_format, p_agent_public_key_fingerprint,
+    p_pop_verified, p_actor_sub, p_agent_kind, v_requested_scopes,
+    v_requested_board_scopes, p_invite_code
+  );
+
+  update agent_board.agents a
+     set metadata = jsonb_set(a.metadata, '{federation,replay}', jsonb_build_object(
+       'issuer', p_issuer, 'audience', v_claim_audience, 'subject', p_subject,
+       'providerId', v_created.provider_id,
+       'actorSub', coalesce(to_jsonb(p_actor_sub), 'null'::jsonb),
+       'requestedSlug', v_slug, 'agentKind', v_kind,
+       'requestedScopes', to_jsonb(v_requested_scopes),
+       'requestedBoardScopes', to_jsonb(v_requested_board_scopes)
+     ), true)
+   where a.id = v_created.agent_id;
+
+  return query select v_created.agent_id, v_created.auth_user_id,
+    v_created.provider_id, v_created.signing_key_id, v_created.granted_scopes,
+    v_created.key_id, v_created.key_version, v_created.agent_handle,
+    v_created.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
+  'Service-role federated enrollment with exact fingerprint replay AND owner-scoped resumption (#176). An already-enrolled key re-presented by the principal that OWNS it RESUMES: the existing agent identity is returned so a client whose post-enroll provisioning failed can finish, rather than being refused forever. Ownership is decided against evidence written at the ORIGINAL enrollment: the creation-time federation stamp (issuer/subject/providerId) and the enrollment_federation_audit row are both REQUIRED, and agents.owner_user_id must equal the auth user derived from sha256(issuer|subject) whenever that column is populated (a null owner_user_id predates the owner model and is the one exemption; such a row still resumes only for the principal the stamp and audit row name). The caller''s (issuer, subject) is trusted only because it is equality-gated against the verified claim projection above; the conjunction is coalesced to false so unproven ownership is not-owned. A key held by a DIFFERENT principal still raises 23505 and the message names no handle. Stable owner, actor, slug, kind, and scope inputs stay frozen for a STAMPED enrollment (unchanged check, message now names the handle); an enrollment predating the stamp has no frozen contract and resumes on the ownership evidence alone, returning its ORIGINAL granted_scopes. Rotating presentation claims are revalidated upstream but are not equality-gated. Fleet-bounded codes are rejected before writes. Takes the invite row and its board (invite -> board) BEFORE the auth.users owner lock so every federated write route agrees on board -> owner (#194); the resumption additions are read-only and acquire no lock. A serialization failure or deadlock during redemption propagates instead of being reported as invite_redeemed=false.';
+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;