@consiliency/agent-board-schema 1.5.0 → 1.9.0

package/migrations/20260724000200_agent_board_roomlink_enroll_binding.sql

@@ -0,0 +1,285 @@
+-- ROOMLINK Lane B: bind an invite code into federated enrollment.
+--
+-- Adds an OPTIONAL trailing p_invite_code to enroll_federated_identity and a widened
+-- return column invite_redeemed. After the agent + key + audit are established, when a
+-- non-empty code is present the RPC soft-honors it via _redeem_invite_for_agent inside
+-- a BEGIN/EXCEPTION subtransaction: a bad/expired/exhausted code rolls back ONLY the
+-- redeem sub-block (the agent-create persists) and enrollment still succeeds with
+-- invite_redeemed=false. This lets a stranger arrive with a shareable board link and
+-- land directly in the board in one call, while a bad code never blocks enrollment.
+--
+-- The return table WIDENS 8 -> 9 columns and the arity goes 13 -> 14, so
+-- create-or-replace cannot be used: the released 13-arg function (20260719001200) is
+-- DROPped and recreated here. The released 001200 bytes are NOT edited. A 13-positional
+-- or 13-named call still resolves (the new arg defaults null), so no old caller breaks.
+--
+-- Additive, forward-only. Writes no agent_board.schema_version (stays 8).
+
+drop function if exists agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[]);
+
+create or replace function agent_board.enroll_federated_identity(
+  p_issuer text,
+  p_audience text,
+  p_subject text,
+  p_human_identity_claim jsonb,
+  p_slug text,
+  p_agent_public_key text,
+  p_agent_public_key_format text,
+  p_agent_public_key_fingerprint text,
+  p_pop_verified boolean,
+  p_actor_sub text default null,
+  p_agent_kind text default 'agent',
+  p_requested_scopes text[] default '{}',
+  p_requested_board_scopes text[] default '{}',
+  p_invite_code text default null
+)
+returns table(
+  agent_id uuid,
+  auth_user_id uuid,
+  provider_id text,
+  signing_key_id uuid,
+  granted_scopes text[],
+  key_id text,
+  key_version int,
+  agent_handle text,
+  invite_redeemed boolean
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_slug text;
+  v_kind text;
+  v_provider agent_board.identity_providers%rowtype;
+  v_owner_user_id uuid;
+  v_auth_user_id uuid;
+  v_agent_handle text;
+  v_agent_id uuid;
+  v_signing_key_id uuid;
+  v_fingerprint text;
+  v_key_hex text;
+  v_raw_key bytea;
+  v_reencoded text;
+  v_key_id text := 'portal-enroll';
+  v_key_version int := 1;
+  v_requested_scopes text[] := coalesce(p_requested_scopes, '{}');
+  v_requested_board_scopes text[] := coalesce(p_requested_board_scopes, '{}');
+  v_invite_code text := nullif(trim(coalesce(p_invite_code, '')), '');
+  v_invite_redeemed boolean := false;
+begin
+  -- service_role-only (defense in depth on top of the execute-grant revocation).
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for enroll_federated_identity' using errcode = '42501';
+  end if;
+
+  -- A verified subject + human identity claim are always present from the EF.
+  if p_subject is null then
+    raise exception 'verified subject is required' using errcode = '22023';
+  end if;
+  if p_human_identity_claim is null then
+    raise exception 'human identity claim is required' using errcode = '22023';
+  end if;
+
+  -- (0) PoP gate — the EF Ed25519-verified the proof-of-possession over the token
+  -- bytes and passes true. Refuse false BEFORE any write (no agent/key/audit row).
+  if p_pop_verified is not true then
+    raise exception 'proof-of-possession was not verified; enrollment refused'
+      using errcode = '42501';
+  end if;
+
+  -- (1) Public-key shape gate. The enroll contract is raw Ed25519 (32 bytes -> 43
+  -- base64url chars).
+  if p_agent_public_key_format is distinct from 'raw_ed25519_base64url' then
+    raise exception 'agent public key format must be raw_ed25519_base64url' using errcode = '22023';
+  end if;
+  if p_agent_public_key is null or p_agent_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+    raise exception 'malformed agent public key: expected a 43-char base64url raw Ed25519 key'
+      using errcode = '22023';
+  end if;
+
+  -- (1a) B2 — decode base64url -> raw 32 bytes and REJECT any non-canonical encoding.
+  v_raw_key := decode(translate(p_agent_public_key, '-_', '+/') || '=', 'base64');
+  if octet_length(v_raw_key) <> 32 then
+    raise exception 'agent public key must decode to exactly 32 raw Ed25519 bytes'
+      using errcode = '22023';
+  end if;
+  v_reencoded := rtrim(translate(encode(v_raw_key, 'base64'), '+/', '-_'), '=');
+  if v_reencoded is distinct from p_agent_public_key then
+    raise exception 'agent public key is not canonical base64url (aliased encoding rejected)'
+      using errcode = '22023';
+  end if;
+
+  -- (1b) Reject the all-zero small-order placeholder over the RAW bytes.
+  if v_raw_key = decode(repeat('00', 32), 'hex') then
+    raise exception 'agent public key is the all-zero small-order placeholder and is rejected'
+      using errcode = '22023';
+  end if;
+
+  -- (2) Recompute-and-assert the fingerprint in-DB over the RAW 32 bytes.
+  v_fingerprint := 'sha256:' || rtrim(
+    translate(encode(extensions.digest(v_raw_key, 'sha256'), 'base64'), '+/', '-_'),
+    '=');
+  if p_agent_public_key_fingerprint is distinct from v_fingerprint then
+    raise exception 'agent public key fingerprint mismatch (recompute != supplied)'
+      using errcode = '22023';
+  end if;
+
+  -- (3) act.sub is audit-only, but when present it must be a real value.
+  if p_actor_sub is not null and length(trim(p_actor_sub)) = 0 then
+    raise exception 'actor sub, when present, must be non-empty' using errcode = '22023';
+  end if;
+
+  v_slug := agent_board._normalize_provision_slug(p_slug);
+  v_kind := lower(coalesce(trim(p_agent_kind), ''));
+
+  -- (4) allowlist lookup by (issuer, audience); must exist + supported + policy-approved.
+  select *
+    into v_provider
+    from agent_board.identity_providers
+   where issuer = p_issuer
+     and audience = p_audience
+   limit 1;
+  if v_provider.id is null then
+    raise exception 'issuer/audience not in the identity-provider allowlist' using errcode = '42501';
+  end if;
+  if not v_provider.supported then
+    raise exception 'identity provider is not supported' using errcode = '42501';
+  end if;
+  if not v_provider.policy_approved then
+    raise exception 'identity provider is not policy-approved' using errcode = '42501';
+  end if;
+
+  -- (5) scope-ceiling + kind gate. 'system' is never federatable.
+  if v_kind = 'system' then
+    raise exception 'the system kind cannot be federated' using errcode = '42501';
+  end if;
+  if v_kind not in ('human', 'agent') then
+    raise exception 'agent kind must be human or agent' using errcode = '22023';
+  end if;
+  if array_length(v_provider.allowed_agent_kinds, 1) is not null
+     and not (v_kind = any (v_provider.allowed_agent_kinds)) then
+    raise exception 'agent kind % is outside the provider ceiling', v_kind using errcode = '42501';
+  end if;
+  if not (v_requested_scopes <@ v_provider.allowed_scopes) then
+    raise exception 'requested scopes exceed the provider allowed_scopes ceiling' using errcode = '42501';
+  end if;
+  if not (v_requested_board_scopes <@ v_provider.allowed_board_scopes) then
+    raise exception 'requested board scopes exceed the provider allowed_board_scopes ceiling' using errcode = '42501';
+  end if;
+
+  -- (6) dedup on the enrolled key: a fingerprint already enrolled cannot be re-bound.
+  if exists (select 1 from agent_board.agent_signing_keys k where k.fingerprint = v_fingerprint) then
+    raise exception 'this signing key is already enrolled (duplicate fingerprint)'
+      using errcode = '23505';
+  end if;
+
+  -- (7) HUMAN OWNER — established idempotently per (issuer, sub).
+  v_owner_user_id := agent_board._ensure_agent_auth_user(
+    'fed-human-' || substr(encode(extensions.digest(convert_to(p_issuer || '|' || p_subject, 'UTF8'), 'sha256'), 'hex'), 1, 32));
+
+  -- (8) AGENT handle — unique per enrolled key.
+  v_key_hex := encode(extensions.digest(v_raw_key, 'sha256'), 'hex');
+  v_agent_handle := v_slug;
+  if exists (select 1 from agent_board.agents a where a.handle = v_agent_handle) then
+    v_agent_handle := v_slug || '-' || substr(v_key_hex, 1, 12);
+  end if;
+
+  -- (9) the agent's OWN board principal (session-usable via its enrolled key).
+  v_auth_user_id := agent_board._ensure_agent_auth_user(v_agent_handle);
+
+  -- (10) create the SEPARATE agent row (never keyed on sub; owner = the human).
+  insert into agent_board.agents(
+    agent_type,
+    kind,
+    handle,
+    display_name,
+    status,
+    auth_user_id,
+    owner_user_id,
+    metadata
+  )
+  values (
+    v_kind,
+    v_kind::agent_board.agent_kind,
+    v_agent_handle,
+    agent_board._default_provision_display_name(v_agent_handle),
+    'active',
+    v_auth_user_id,
+    v_owner_user_id,
+    jsonb_build_object(
+      'federation', jsonb_build_object(
+        'issuer', p_issuer,
+        'audience', p_audience,
+        'subject', p_subject,
+        'actorSub', p_actor_sub,
+        'providerId', v_provider.id,
+        'signingKeyFingerprint', v_fingerprint,
+        'requestedScopes', to_jsonb(v_requested_scopes),
+        'requestedBoardScopes', to_jsonb(v_requested_board_scopes),
+        'popVerified', true,
+        'enrolledAt', now()
+      )
+    )
+  )
+  returning id into v_agent_id;
+
+  -- (11) enroll the public key as active + proven (satisfies active_requires_proof).
+  insert into agent_board.agent_signing_keys(
+    id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint,
+    status, proof_state, metadata
+  )
+  values (
+    gen_random_uuid(), v_agent_id, v_key_id, v_key_version, p_agent_public_key,
+    p_agent_public_key_format, v_fingerprint,
+    'active', 'proven',
+    jsonb_build_object('enrolledVia', 'federated_identity', 'popVerified', true)
+  )
+  returning id into v_signing_key_id;
+
+  -- (12) one static claim-snapshot audit row (the verified claim contains act.sub).
+  insert into agent_board.enrollment_federation_audit(
+    issuer, audience, subject, human_identity_claim, provider_id,
+    agent_id, auth_user_id, requested_scopes, granted_scopes
+  )
+  values (
+    p_issuer, p_audience, p_subject, p_human_identity_claim, v_provider.id,
+    v_agent_id, v_auth_user_id, v_requested_scopes, v_requested_scopes
+  );
+
+  -- (13) ROOMLINK soft-honor: if a code is present, redeem it into a bounded board
+  -- membership for the freshly-created agent. Wrapped in a subtransaction so a
+  -- bad/expired/exhausted/unauthorized code rolls back ONLY this sub-block — the
+  -- agent-create above persists and enrollment still succeeds (invite_redeemed=false).
+  if v_invite_code is not null then
+    begin
+      perform agent_board._redeem_invite_for_agent(v_invite_code, v_agent_id);
+      v_invite_redeemed := true;
+    exception when others then
+      v_invite_redeemed := false;
+    end;
+  end if;
+
+  -- Server-authoritative identity: the client mints /session with the RETURNED
+  -- key_id/key_version/agent_handle (its private key stays in the keystore).
+  return query
+  select v_agent_id, v_auth_user_id, v_provider.id, v_signing_key_id, v_requested_scopes,
+         v_key_id, v_key_version, v_agent_handle, v_invite_redeemed;
+end;
+$$;
+
+comment on function agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text) is
+  'PoP-at-enrollment federated identity (ROOMLINK-extended). Same server-authoritative '
+  'identity establishment as 20260719001200, plus an OPTIONAL trailing p_invite_code: '
+  'when present the RPC soft-honors it via _redeem_invite_for_agent in a BEGIN/EXCEPTION '
+  'subtransaction (bad code -> enrollment still succeeds, invite_redeemed=false) and '
+  'RETURNS invite_redeemed. service_role-only; never returns a Portal token.';
+
+revoke all on function agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  from public, anon, authenticated;
+grant execute on function agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  to service_role;

package/migrations/20260725000100_agent_board_roomdeleg_role_gate.sql

@@ -0,0 +1,232 @@
+-- ROOMDELEG Lane A: owner-gated role-gate flip + creator-identity gate-bypass fix.
+--
+-- Additive, no schema_version bump (stays 8). Adds:
+--   * agent_board.set_board_role_gate(board, enforced) — lets a board OWNER flip the
+--     per-board boards.role_gate_enforced flag from their own authenticated session.
+--     Owner-membership gated (mirrors set_board_authority_ceiling's owner-gate + grant
+--     pattern; NOT its side-table upsert — this UPDATEs the boards row). service_role
+--     (current_agent_id() = null) is intentionally NOT an owner here; it retains its
+--     direct table-write grant for operator provisioning.
+--   * R-DELEG-1: create-or-replace invite_board_member / resolve_board_request so the
+--     creator-identity exemption does NOT apply when role_gate_enforced is true. The
+--     board creator (created_by_agent_id is immutable, so a DEMOTED creator kept its
+--     exemption) must, under an enforced gate, ALSO hold an active owner/admin
+--     membership like any other member. Gate-OFF behavior is byte-identical to today
+--     (creator bypasses; non-creator members need an active membership; a null actor /
+--     service_role still bypasses) so no existing test regresses.
+
+-- 1. set_board_role_gate (owner-settable per-board role gate) ------------------------
+-- NOTE: board status is NOT gated here (a role-gate flip is permitted on any board the
+-- caller owns regardless of status); this matches the sibling ceiling setter and is an
+-- accepted scope boundary for Lane A.
+create or replace function agent_board.set_board_role_gate(
+  p_board_id uuid,
+  p_enforced boolean
+)
+returns table(
+  board_id uuid,
+  role_gate_enforced boolean,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+  v_row agent_board.boards%rowtype;
+begin
+  if p_enforced is null then
+    raise exception 'p_enforced must not be null' using errcode = '22023';
+  end if;
+
+  -- Owner gate: only an active owner-role member may flip the gate. service_role
+  -- (current_agent_id() = null) is not an owner and is rejected here (it keeps its
+  -- direct table-write grant for operator provisioning).
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the role gate' using errcode = '42501';
+  end if;
+
+  update agent_board.boards b
+     set role_gate_enforced = p_enforced,
+         updated_at = now()
+   where b.id = p_board_id
+  returning * into v_row;
+
+  if v_row.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  return query
+  select v_row.id, v_row.role_gate_enforced, v_row.updated_at;
+end;
+$$;
+
+comment on function agent_board.set_board_role_gate(uuid, boolean) is
+  'Owner-gated setter for a board''s role_gate_enforced flag: UPDATEs boards.role_gate_enforced only when current_agent_id() is an active owner of the board (else 42501; null p_enforced -> 22023; missing board -> P0002). service_role is not an owner here.';
+
+revoke all on function agent_board.set_board_role_gate(uuid, boolean) from public, anon;
+grant execute on function agent_board.set_board_role_gate(uuid, boolean) to authenticated, service_role;
+
+-- 2. R-DELEG-1: role-gate-aware invite_board_member ---------------------------------
+-- Body is verbatim from 20260717000100 EXCEPT the actor gate-guard block: when the
+-- role gate is enforced the creator-identity exemption is dropped (the creator must
+-- then also hold an active owner/admin membership).
+create or replace function agent_board.invite_board_member(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_created_by_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null then
+    if v_board.role_gate_enforced then
+      -- Gate ON: NO creator exemption. Every actor (including a demoted creator)
+      -- must hold an active owner/admin membership.
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+           and bm.role in ('owner', 'admin')
+      ) then
+        raise exception 'board invite requires owner or admin role' using errcode = '42501';
+      end if;
+    elsif v_actor <> v_board.created_by_agent_id then
+      -- Gate OFF: creator bypasses; any other actor needs an active membership.
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+      ) then
+        raise exception 'board invite requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    'invited',
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;
+
+-- 3. R-DELEG-1: role-gate-aware resolve_board_request -------------------------------
+create or replace function agent_board.resolve_board_request(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, left_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if p_membership_state not in ('joined', 'subscribed', 'removed') then
+    raise exception 'resolve_board_request only accepts joined, subscribed, or removed' using errcode = '22023';
+  end if;
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null then
+    if v_board.role_gate_enforced then
+      -- Gate ON: NO creator exemption. Every actor (including a demoted creator)
+      -- must hold an active owner/admin membership.
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+           and bm.role in ('owner', 'admin')
+      ) then
+        raise exception 'board request resolution requires owner or admin role' using errcode = '42501';
+      end if;
+    elsif v_actor <> v_board.created_by_agent_id then
+      -- Gate OFF: creator bypasses; any other actor needs an active membership.
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+      ) then
+        raise exception 'board request resolution requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by bm.created_at desc
+   limit 1;
+
+  if v_existing_state not in ('requested', 'invited') then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.left_at, v_membership.updated_at;
+end;
+$$;
+
+-- Re-assert grants (create or replace preserves them, but be explicit so a fresh
+-- replay is order-independent).
+grant execute on function agent_board.invite_board_member(uuid, uuid, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) to authenticated, service_role;

package/migrations/20260726000100_agent_board_localauth_self_enroll.sql

@@ -0,0 +1,172 @@
+-- LOCALAUTH: Portal-free standalone human self-enrollment.
+--
+-- WHAT: self_enroll_human() lets a browser human who has signed in with the
+-- target Supabase project's OWN auth (magic-link/OTP/OAuth/passkey) bind their
+-- auth.uid() to a kind='human' agent_board.agents row from their own
+-- authenticated session — no Portal, no service_role, no operator step per user.
+--
+-- IDENTITY MODEL: the human is SELF-owned (owner_user_id = auth_user_id =
+-- auth.uid()). Contrast enroll_federated_identity, where auth_user_id is a
+-- synthetic per-agent uid and owner_user_id is the real human. The only trusted
+-- identity input is auth.uid(); there is NO auth_user_id/agent_id argument, so a
+-- caller cannot self-assign someone else's identity. Spoofing auth.uid() would
+-- require the JWT-signing secret or the service_role key — that is inherent to
+-- Supabase, not a boundary introduced here.
+--
+-- PII: metadata.localauth stores ONLY a boolean email_verified (derived from
+-- auth.users.email_confirmed_at), never the plaintext email. The agents SELECT
+-- RLS is not row-scoped, so a stored email would be a fleet-wide harvestable
+-- directory. The canonical human email lives in auth.users (bound via the
+-- agent's auth_user_id); an IDLINK flow reads it there via service_role AND MUST
+-- RE-VERIFY email ownership at link time (email_confirmed_at can be admin- or
+-- auto-set, so it is not by itself proof of possession).
+--
+-- OPERATOR / SCOPE (L-10): enabling a Supabase Auth sign-in method in the target
+-- project is a net-new OPERATOR config task. The sign-in UI / browser app is
+-- EXTERNAL / consumer-owned — there is no in-repo frontend. LOCALAUTH ships the
+-- RPC + the zero-node `@consiliency/agent-board-client/localauth` helper ONLY.
+--
+-- Additive, forward-only. Writes no schema_version (stays 8).
+
+create or replace function agent_board.self_enroll_human(
+  p_display_name text default null
+)
+returns table(
+  agent_id uuid,
+  handle text,
+  kind text,
+  status text,
+  auth_user_id uuid,
+  created_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_uid uuid := auth.uid();
+  v_existing agent_board.agents%rowtype;
+  v_email_confirmed_at timestamptz;
+  v_email_verified boolean;
+  v_handle text;
+  v_agent agent_board.agents%rowtype;
+begin
+  -- Fail closed: no authenticated Supabase user -> no identity to bind. This also
+  -- covers service_role and any superuser/operator path (auth.uid() is null for
+  -- them), which is intentional: LOCALAUTH is a self-service authenticated path.
+  if v_uid is null then
+    raise exception 'self_enroll_human requires an authenticated Supabase user (auth.uid() is null)'
+      using errcode = '42501';
+  end if;
+
+  -- Idempotency + no-self-reactivation guard, keyed on auth_user_id (ANY status).
+  -- An ACTIVE row -> return it (idempotent, no duplicate). A NON-active row
+  -- (status <> 'active', i.e. inactive or suspended per the agents status enum)
+  -- -> fail closed: a deactivated/suspended human must NOT self-reactivate; an
+  -- operator must restore them.
+  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
+      return query
+      select v_existing.id, v_existing.handle, v_existing.kind::text,
+             v_existing.status, v_existing.auth_user_id, v_existing.created_at;
+      return;
+    else
+      raise exception 'a non-active identity already exists for this user; contact an operator'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- Verified-email as a BOOLEAN only. Read email_confirmed_at server-side (never
+  -- trust an unverified JWT email claim); store the derived boolean, never the
+  -- address.
+  select u.email_confirmed_at into v_email_confirmed_at
+    from auth.users u
+   where u.id = v_uid;
+  v_email_verified := v_email_confirmed_at is not null;
+
+  -- Deterministic globally-unique handle: 16 hex (64-bit) of sha256(uid).
+  v_handle := 'local-human-' || substr(encode(extensions.digest(v_uid::text, 'sha256'), 'hex'), 1, 16);
+
+  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(
+        'localauth', jsonb_build_object(
+          'self_enrolled_at', now(),
+          'email_verified', v_email_verified
+        )
+      )
+    )
+    returning * into v_agent;
+  exception when unique_violation then
+    -- Concurrent first-enroll race: another session inserted the active row for
+    -- this uid between our select and insert. Re-select and return it.
+    select * into v_existing
+      from agent_board.agents a
+     where a.auth_user_id = v_uid
+       and a.status = 'active'
+     limit 1;
+    if found then
+      return query
+      select v_existing.id, v_existing.handle, v_existing.kind::text,
+             v_existing.status, v_existing.auth_user_id, v_existing.created_at;
+      return;
+    end if;
+    -- Not the uid race -> a genuine handle collision (astronomically rare for a
+    -- 64-bit hash). Surface a clean, distinct, retryable error rather than the
+    -- opaque raw unique_violation.
+    raise exception 'could not self-enroll (handle collision), please retry'
+      using errcode = '40001';
+  end;
+
+  return query
+  select v_agent.id, v_agent.handle, v_agent.kind::text,
+         v_agent.status, v_agent.auth_user_id, v_agent.created_at;
+end;
+$$;
+
+comment on function agent_board.self_enroll_human(text) is
+  'Portal-free self-service: binds auth.uid() to a kind=human agent (self-owned: '
+  'owner_user_id = auth_user_id = auth.uid()). Idempotent for an active identity; '
+  'a non-active identity fails closed (42501, no self-reactivation). Stores only a '
+  'BOOLEAN metadata.localauth.email_verified (never the plaintext email). Fails '
+  'closed with 42501 when auth.uid() is null (unauthenticated / service_role / '
+  'operator). authenticated-only; not a signed write.';
+
+-- authenticated-only. service_role is explicitly revoked (belt-and-suspenders on
+-- top of the auth.uid()-null fail-close): the service path is
+-- enroll_federated_identity, not this self-service RPC.
+revoke all on function agent_board.self_enroll_human(text) from public, anon, service_role;
+grant execute on function agent_board.self_enroll_human(text) to authenticated;
+
+-- L-4b DB backstop: one agent per REAL auth user, enforced at the DB (not just the
+-- app guard above). SAFE because federated agents use SYNTHETIC per-agent uids
+-- (_ensure_agent_auth_user), so only real-uid rows are ever constrained. This is a
+-- DIFFERENT guarantee than the pre-existing partial-unique
+-- idx_agent_board_agents_auth_user_id_active_unique (which is scoped to
+-- status='active'); this one admits at most one row per uid EVER. On real data a
+-- failure here means a genuine duplicate — correct fail-loud.
+create unique index if not exists idx_agent_board_agents_auth_user_id_unique
+  on agent_board.agents(auth_user_id)
+  where auth_user_id is not null;