@consiliency/agent-board-schema 1.9.0 → 1.12.0

package/migrations/20260729000100_agent_board_fedsession_autojoin_default_board.sql

@@ -0,0 +1,364 @@
+-- FEDSESSION auto-join: give a freshly provisioned federated human BASELINE board standing.
+--
+-- WHY: a Portal human who signs in for the first time gets a kind='human' fed-agent via
+-- enroll_federated_human, but with NO board_memberships — so the Portal room-ops UI renders
+-- over an empty dashboard and every owner-loop write 403s until they create/join a board.
+-- The self-service path (create_board self-seeds the caller as owner) covers OWNED boards;
+-- this migration adds the complementary default: an OPERATOR-DESIGNATED, per-issuer default
+-- board that fresh fed-humans auto-join at provision time so they land with participation
+-- standing.
+--
+-- MODEL (chosen over per-human manual grants): the default board is designated PER ISSUER on
+-- the identity_providers row (new nullable default_board_id). NULL => no auto-join (the exact
+-- current behavior; this migration is inert until an operator designates a board). The
+-- auto-join is:
+--   * BASELINE role only ('member' — never owner/admin): merely landing in the default board
+--     confers no board authority beyond participation. Owner authority stays with create_board
+--     / grant_board_role.
+--   * FIRST-TIME-ONLY & idempotent: it inserts only when the fed-human has NO membership row
+--     for that board AT ALL (any state). A human who deliberately LEFT the default board is
+--     NOT silently re-joined, and re-provisioning never duplicates a membership. The NOT EXISTS
+--     guard is intentionally BROADER than the live partial unique index
+--     idx_agent_board_board_memberships_active_unique ((board_id, agent_id) WHERE
+--     membership_state in ('joined','subscribed'), 20260505000000): the guard also covers
+--     'left'/'removed' rows (which the partial index does NOT), which is what gives the
+--     first-time-only / left-respect semantics. That partial index is the CONCURRENCY backstop:
+--     two concurrent re-provisions of the same already-provisioned human can both pass NOT
+--     EXISTS, and the second insert then trips the index — the helper catches that
+--     unique_violation to a no-op (mirroring enroll_federated_human's step-8 agent-insert race
+--     handling) so auto-join stays non-fatal (never duplicates AND never aborts the mint).
+--   * NEVER fatal: it runs only when the designated board EXISTS and is status='active'. A
+--     missing/inactive/mis-designated board silently skips the join so provisioning (and the
+--     Option A session mint) still succeeds. Auto-join is a convenience, never a gate.
+--
+-- SCOPE: additive + forward-only. Does NOT change the enroll_federated_human signature, the
+-- IF-0-FEDSESSION-1 session response, the synthetic-uid/IDLINK derivation, the provider/kind
+-- gates, the PII handling, or the audit. Only NEW: the default_board_id column + the auto-join
+-- block. The /portal-session Edge Function is unchanged (it calls the same RPC). Writes no
+-- agent_board.schema_version (stays 8).
+
+-- (A) Per-issuer default board designation. NULL => no auto-join (inert). ON DELETE SET NULL so
+-- retiring the board gracefully disables auto-join instead of blocking the delete.
+alter table agent_board.identity_providers
+  add column if not exists default_board_id uuid
+    references agent_board.boards(id) on delete set null;
+
+comment on column agent_board.identity_providers.default_board_id is
+  'FEDSESSION auto-join target: the board a freshly provisioned federated human is auto-joined '
+  'to (baseline member role) at enroll_federated_human time. NULL disables auto-join for this '
+  'issuer (default). Operator/service_role-only (authenticated has no INSERT/UPDATE on '
+  'identity_providers); the board must exist and be active for the join to fire. OPERATOR '
+  'CAVEAT: member = RLS-gated read AND post, and designation grants that standing to EVERY '
+  'future federated human of this issuer WITHOUT the board owner''s consent (a compromised/'
+  'high-volume approved issuer thus inflates membership, bounded by /portal-session''s '
+  'per-source rate cap). Designate ONLY a board intended as a shared landing/commons for this '
+  'issuer and whose owner you control.';
+
+-- (B) Recreate enroll_federated_human with the auto-join block. Body is byte-identical to
+-- 20260728000100 EXCEPT: step (7) sets v_agent := v_existing to unify the return, and a new
+-- step (auto-join) runs before BOTH return paths.
+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;
+      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
+      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;
+$$;
+
+-- (C) The auto-join helper. SECURITY DEFINER internal (service_role/postgres only — it is
+-- only ever called from enroll_federated_human, itself service_role-gated). Idempotent,
+-- first-time-only, active-board-only, non-fatal. Kept as a helper so BOTH provision paths
+-- (idempotent re-provision + first insert) share one byte-identical implementation.
+create or replace function agent_board._fedsession_autojoin_default_board(
+  p_provider agent_board.identity_providers,
+  p_agent_id uuid
+)
+returns void
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  if p_provider.default_board_id is null then
+    return;
+  end if;
+  -- The NOT EXISTS below is FIRST-TIME-ONLY (any existing membership row, incl. 'left'/
+  -- 'removed', suppresses the auto-join so a human who deliberately left is not re-joined).
+  -- Under concurrency it is NOT sufficient on its own: two concurrent re-provisions of the
+  -- same already-provisioned human can both pass NOT EXISTS, and the second insert then trips
+  -- the partial unique index idx_agent_board_board_memberships_active_unique. Catch that
+  -- unique_violation to a no-op (mirrors enroll_federated_human's step-8 agent-insert race
+  -- handling) so auto-join is NEVER fatal to the session mint and never duplicates.
+  begin
+    insert into agent_board.board_memberships(
+      board_id, agent_id, role, membership_state, created_by_agent_id, metadata)
+    select p_provider.default_board_id, p_agent_id, 'member', 'joined', p_agent_id,
+           jsonb_build_object('source', 'fedsession-autojoin', 'providerId', p_provider.id)
+    where exists (
+        select 1 from agent_board.boards b
+         where b.id = p_provider.default_board_id
+           and b.status = 'active')
+      and not exists (
+        select 1 from agent_board.board_memberships m
+         where m.board_id = p_provider.default_board_id
+           and m.agent_id = p_agent_id);
+  exception when unique_violation then
+    null;  -- concurrent auto-join won the race; its membership stands. Non-fatal.
+  end;
+end;
+$$;
+
+comment on function agent_board._fedsession_autojoin_default_board(agent_board.identity_providers, uuid) is
+  'FEDSESSION internal: idempotently auto-join a freshly provisioned federated human to the '
+  'provider''s designated default_board_id (baseline member role, joined). First-time-only '
+  '(any existing membership row suppresses it, so a human who left is not re-joined), '
+  'active-board-only, non-fatal. service_role/postgres only (called from enroll_federated_human).';
+
+revoke all on function agent_board._fedsession_autojoin_default_board(agent_board.identity_providers, uuid)
+  from public, anon, authenticated;
+grant execute on function agent_board._fedsession_autojoin_default_board(agent_board.identity_providers, uuid)
+  to service_role;
+
+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, '
+  'auto-joins the provider''s designated default board (baseline member; first-time-only, '
+  'non-fatal), 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;