@consiliency/agent-board-schema 1.9.0 → 1.12.0

package/fixtures/already-applied.json

@@ -312,6 +312,22 @@
     {
       "id": "20260727000100_agent_board_roomuiapi",
       "sha256": "9c938c40115aa25f464bbb9d177f9f85214fb84f7b37abe5ae9df5b6a2485141"
+    },
+    {
+      "id": "20260728000100_agent_board_enroll_federated_human",
+      "sha256": "5f300449c29ec05c2cd3c2cd7eca622ca41e8b32b8856c5bc0695b5750a196e7"
+    },
+    {
+      "id": "20260729000100_agent_board_fedsession_autojoin_default_board",
+      "sha256": "6f3a2db6c7349119b3893fe530788236ef5ccf4e6b0f3e21235497b8b7b232c0"
+    },
+    {
+      "id": "20260730000100_agent_board_gatenull_service_role_bypass",
+      "sha256": "db8b2a93996c1d61bd34fc58a5e4b3056563c53bb2eb20cbb4a3b0b799a0d91e"
+    },
+    {
+      "id": "20260730000200_agent_board_membstate_authz",
+      "sha256": "a4d935614f970a946f27a5925c0166e1d41510a82078e559fb769f4ea39afc2e"
     }
   ]
 }

package/migrations/20260728000100_agent_board_enroll_federated_human.sql

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