@consiliency/agent-board-schema 1.27.0 → 1.35.0

package/migrations/20260915000100_agent_board_fedsession_stored_identity_gate.sql

@@ -0,0 +1,353 @@
+-- Consiliency/message-board#246 (change 1 of 3): the federated-human return path
+-- compares the caller's verified (issuer, subject) against the pair STORED on the
+-- agent it is about to hand back.
+--
+-- WHAT WAS WRONG. The owner uid is derived as
+-- sha256(p_issuer || '|' || p_subject), a concatenation with no length prefix and
+-- no escaping, so the pair is not recoverable from the preimage and two distinct
+-- principals can derive the SAME uid. Having derived it, step (7) selected ANY
+-- agent on that uid and returned it after checking exactly two things: that it was
+-- 'active' and that its kind was 'human'. NEITHER of those says the row belongs to
+-- the caller. Under a collision the second principal is handed a live session as
+-- the first, and step (11)'s audit insert then stamps the ATTACKER's (issuer,
+-- subject) onto the VICTIM's agent_id -- poisoning the stored evidence that
+-- enroll_federated_identity's #176/#244 resumption conjunction reads.
+--
+-- WHY THIS SHIPS BEFORE THE DERIVATION IS FIXED. The equality check defeats the
+-- collision WITH TODAY'S AMBIGUOUS ENCODING STILL IN PLACE: whichever principal
+-- reaches the uid second no longer matches the stamp and is refused. Making the
+-- derivation injective is a separate change -- it moves every existing
+-- fed-human-* handle, so it needs its own migration, an auth.users.email re-key
+-- for the live owner, and Portal coordination. This change needs none of that and
+-- closes the damage path on its own.
+--
+-- TWO RETURN SITES, NOT ONE. Step (7) is the one the issue quotes. Step (8)'s
+-- `exception when unique_violation` handler is a SECOND return of an existing row
+-- on the same uid, reached when a concurrent transaction commits the agent between
+-- (7)'s select and this insert; it re-selected on (uid, active, human) and returned
+-- that row with no stamp comparison either. Gating only (7) would reproduce the
+-- defect one level down, so both sites carry the same gate, in the same shape.
+--
+-- The shapes being identical does NOT mean one assertion can pin both, and an
+-- earlier draft of this comment said it could. A COUNT of the gate's occurrences is
+-- satisfied by two gates at (7) and none at (8) -- the pgTAP file builds exactly
+-- that body as a mutation, and the count stayed green. Each site is pinned
+-- POSITIONALLY instead, by splitting the catalog body on this handler's own
+-- `exception when unique_violation`, and the RAISE is pinned per site too: gating
+-- both sites while raising a different message at one of them is a distinct
+-- regression that the gate's position alone does not see.
+--
+-- FAIL CLOSED ON A MISSING STAMP, and the population was measured rather than
+-- assumed. Both gates are written `if not coalesce(<equality>, false)`: a row whose
+-- metadata->'federation' lacks issuer, or lacks subject, or lacks the object
+-- entirely, yields NULL, coalesces to false, and is REFUSED. All three shapes have
+-- their own fixture in the pgTAP file -- the missing-ISSUER-only case was added
+-- because this sentence named it while no fixture covered it, and the surviving
+-- subject conjunct would have refused a differing caller regardless. This mirrors enroll_federated_identity, whose ownership
+-- conjunction is coalesced to false for the same reason -- unproven ownership must
+-- read as not-owned. On the canonical project (mqccjfqngptkemnchlko, 2026-08-16)
+-- there is exactly 1 agent reachable on this path, it carries BOTH issuer and
+-- subject, and 0 rows reachable here lack a stamp; all 110 of its
+-- enrollment_federation_audit rows agree with that stamp on both fields, over 1
+-- distinct pair. The stamp has been written unconditionally by this path's own
+-- creation branch since it shipped (20260728000100:243), so a stamp-less row is not
+-- a shape this code produces.
+--
+-- THE GATE IS FIRST, DELIBERATELY. It precedes the status branch and the kind
+-- check, so a caller presenting a colliding pair gets ONE refusal regardless of
+-- whether the victim is active, suspended, human or not -- the ordering
+-- enroll_federated_identity uses for the key-squat, and for the same reason: a
+-- caller that does not own the identity must not learn anything else about it.
+--
+-- THE MESSAGE IS READ BY THE CALLER, not just by an operator.
+-- supabase/functions/portal-session/index.ts:374-378 catches ANY error from this
+-- RPC and returns `{error:"provision_rejected", detail:<message>}` with HTTP 403.
+-- So the message names NO handle, agent id, status, kind, or the other principal's
+-- issuer/subject -- only that the derived owner is already bound elsewhere, which
+-- the refusal itself already discloses. Log distinguishability comes from the
+-- phrase, which is unique in this schema, not from the SQLSTATE: 42501 is the
+-- honest class and is what every other AUTHORIZATION refusal in this function
+-- raises (the body also raises 22023 four times for malformed input and 40001 once
+-- for a retryable race -- neither is this refusal's class), while
+-- 23505 would be actively wrong (the client maps it to "conflicting active claim",
+-- packages/agent-board-client/src/client.ts:349).
+--
+-- NOT RESCOPED, AND THAT IS THE POINT. An obvious-looking alternative is to filter
+-- (7)'s select by the stamp so the owner always finds its own row. That is a HOLE:
+-- the mismatching caller would then fall through to step (8), whose insert
+-- unique-violates on the shared handle, whose handler re-selects on (uid, active,
+-- human) -- and hands back the victim's agent anyway. Refusing is the correct
+-- verdict, because under an ambiguous derivation the second principal has no owner
+-- of its own to be given.
+
+create or replace function agent_board._enroll_federated_human_after_revocation_gate(
+  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
+    -- (7a) #246 STORED-IDENTITY EQUALITY. The select above keys on the DERIVED uid
+    -- and nothing else, and the derivation is not injective, so `found` does not
+    -- mean "the caller's own agent". Require the pair this row was stamped with at
+    -- creation to equal the pair the caller presented. coalesce(..., false): a row
+    -- with no stored stamp yields NULL, which must read as NOT-mine, not as
+    -- unchecked. First, before the status and kind branches, so a mismatching
+    -- caller learns only that it was refused.
+    if not coalesce(
+         v_existing.metadata #>> '{federation,issuer}'  = p_issuer
+     and v_existing.metadata #>> '{federation,subject}' = p_subject, false) then
+      raise exception 'federated identity mismatch: the owner derived for this issuer/subject is already bound to a different verified identity; refusing to issue a session'
+        using errcode = '42501';
+    end if;
+    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;
+      v_agent := v_existing;
+      -- 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;
+      -- (auto-join before the idempotent return — see step 11 for the rationale).
+      perform agent_board._fedsession_autojoin_default_board(v_provider, v_agent.id);
+      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;
+      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
+      -- (8a) #246 STORED-IDENTITY EQUALITY, second return site. Same gate, same
+      -- shape, same message as (7a): this handler returns an EXISTING row on the
+      -- derived uid, so it needs the same proof that the row is the caller's. The
+      -- interleaving that reaches it is concurrency-only -- (7)'s unfiltered select
+      -- intercepts any already-committed row on this uid -- which is why this site
+      -- is pinned structurally by the class assertion rather than differentially by
+      -- a single-session test.
+      if not coalesce(
+           v_existing.metadata #>> '{federation,issuer}'  = p_issuer
+       and v_existing.metadata #>> '{federation,subject}' = p_subject, false) then
+        raise exception 'federated identity mismatch: the owner derived for this issuer/subject is already bound to a different verified identity; refusing to issue a session'
+          using errcode = '42501';
+      end if;
+      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) FEDSESSION auto-join (new). Baseline default-board membership for a fresh fed-human.
+  perform agent_board._fedsession_autojoin_default_board(v_provider, v_agent.id);
+
+  -- (11) 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;
+$$;
+
+-- `create or replace` with the UNCHANGED signature preserves both the ACL and the
+-- COMMENT (a `drop function` would discard both, and recreating a SECURITY DEFINER
+-- function grants EXECUTE to PUBLIC by default). The revoke below is therefore
+-- redundant TODAY and is restated anyway, so the migration remains correct if it is
+-- ever replayed against a catalog where this function does not already exist. The
+-- comment is not redundant: it is amended, because the gate this migration adds is
+-- part of the contract a reader of `\df+` should see.
+revoke all on function agent_board._enroll_federated_human_after_revocation_gate(text, text, text, jsonb, text)
+  from public, anon, authenticated, service_role;
+comment on function agent_board._enroll_federated_human_after_revocation_gate(text, text, text, jsonb, text) is
+  'Internal federated-human provisioner. Call only through enroll_federated_human, which holds the deterministic auth.users owner lock and rejects durable issuer/subject revocation markers. Returns an EXISTING agent on the derived owner uid only when that agent''s stored metadata.federation issuer AND subject equal the caller''s verified pair (message-board#246); a missing stamp is a refusal, not a pass, and both return sites -- the idempotent branch and the unique_violation race handler -- carry the gate.';