@consiliency/agent-board-schema 1.2.0

package/migrations/20260710000000_agent_board_authbound_boundary.sql

@@ -0,0 +1,155 @@
+create or replace function agent_board.current_agent_id()
+returns uuid
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with credential_claim as (
+    select nullif(current_setting('request.jwt.claim.agent_credential_id', true), '') as credential_id_text
+  )
+  select a.id
+    from agent_board.agents a
+    cross join credential_claim cc
+   where a.auth_user_id = auth.uid()
+     and a.status = 'active'
+     and (
+       cc.credential_id_text is null
+       or (
+         cc.credential_id_text ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+         and exists (
+           select 1
+             from agent_board.agent_credentials ac
+            where ac.id = cc.credential_id_text::uuid
+              and ac.agent_id = a.id
+              and ac.revoked_at is null
+              and (ac.expires_at is null or ac.expires_at > now())
+         )
+       )
+     )
+   limit 1;
+$$;
+
+comment on function agent_board.current_agent_id() is 'Resolves auth.uid() to the active agent_board.agents.id and, when present, requires the JWT agent_credential_id claim to reference a non-revoked, non-expired credential for that agent.';
+
+grant usage on schema agent_board to service_role;
+grant select on agent_board.agents to service_role;
+grant select, update(last_used_at, updated_at) on agent_board.agent_credentials to service_role;
+
+create or replace function agent_board._signed_write_actor_id(
+  p_payload jsonb,
+  p_gateway_decision jsonb,
+  p_actor_field text
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+  v_payload_actor uuid;
+begin
+  v_actor := nullif(p_gateway_decision ->> 'agent_id', '')::uuid;
+  if v_actor is null then
+    raise exception 'actor_mismatch: signed write gateway actor is required' using errcode = '42501';
+  end if;
+
+  v_payload_actor := nullif(p_payload ->> p_actor_field, '')::uuid;
+  if v_payload_actor is not null and v_payload_actor <> v_actor then
+    raise exception 'actor_mismatch: signed write payload actor must match gateway actor' using errcode = '42501';
+  end if;
+
+  return v_actor;
+end;
+$$;
+
+create or replace function agent_board._record_signed_write_evidence(
+  p_source_kind text,
+  p_source_id uuid,
+  p_operation text,
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_evidence_id uuid;
+  v_agent_id uuid := nullif(p_gateway_decision ->> 'agent_id', '')::uuid;
+  v_status text := coalesce(nullif(p_gateway_decision ->> 'verification_status', ''), 'unsigned');
+begin
+  if v_agent_id is null then
+    raise exception 'actor_mismatch: signed write evidence requires gateway actor' using errcode = '42501';
+  end if;
+
+  if v_status not in ('unsigned', 'observed', 'warn', 'verified', 'failed') then
+    v_status := 'failed';
+  end if;
+
+  insert into agent_board.signature_evidence(
+    agent_id,
+    signing_key_id,
+    key_id,
+    key_version,
+    algorithm,
+    source_kind,
+    source_message_id,
+    source_task_event_id,
+    operation,
+    payload_digest,
+    canonicalization_version,
+    signature_digest,
+    verification_status,
+    failure_class,
+    signed_at,
+    verified_at,
+    nonce,
+    idempotency_key,
+    external_evidence_ref,
+    metadata
+  )
+  values (
+    v_agent_id,
+    nullif(p_gateway_decision ->> 'signing_key_id', '')::uuid,
+    nullif(p_gateway_decision ->> 'key_id', ''),
+    nullif(p_gateway_decision ->> 'key_version', '')::integer,
+    coalesce(nullif(p_gateway_decision ->> 'algorithm', ''), 'Ed25519'),
+    p_source_kind,
+    case when p_source_kind = 'message' then p_source_id else null end,
+    case when p_source_kind = 'task_event' then p_source_id else null end,
+    p_operation,
+    coalesce(nullif(p_gateway_decision ->> 'payload_digest', ''), 'sha256:unsigned'),
+    coalesce(nullif(p_gateway_decision ->> 'canonicalization_version', ''), 'agent-provenance-jcs.v1'),
+    nullif(p_gateway_decision ->> 'signature_digest', ''),
+    v_status,
+    nullif(p_gateway_decision ->> 'failure_class', ''),
+    nullif(p_gateway_decision ->> 'signed_at', '')::timestamptz,
+    nullif(p_gateway_decision ->> 'verified_at', '')::timestamptz,
+    nullif(p_gateway_decision ->> 'nonce', ''),
+    nullif(p_gateway_decision ->> 'idempotency_key', ''),
+    nullif(p_gateway_decision ->> 'external_evidence_ref', ''),
+    jsonb_build_object(
+      'gateway', 'signed-write',
+      'authbound', true,
+      'enforcementMode', coalesce(p_gateway_decision ->> 'enforcement_mode', 'observe'),
+      'redacted', true,
+      'metadata-safe', true
+    )
+  )
+  returning id into v_evidence_id;
+
+  update agent_board.signature_replay_state
+     set signature_evidence_id = v_evidence_id
+   where agent_id = v_agent_id
+     and operation = p_operation
+     and (
+       (nonce is not null and nonce = nullif(p_gateway_decision ->> 'nonce', ''))
+       or (idempotency_key is not null and idempotency_key = nullif(p_gateway_decision ->> 'idempotency_key', ''))
+     );
+
+  return v_evidence_id;
+end;
+$$;

package/migrations/20260710000100_agent_board_schema_version_rpc.sql

@@ -0,0 +1,14 @@
+create or replace function agent_board.get_schema_version()
+returns table(version integer)
+language sql
+stable
+security definer
+set search_path = agent_board, pg_temp
+as $$
+  select schema_version.version
+  from agent_board.schema_version
+  limit 1;
+$$;
+
+revoke all on function agent_board.get_schema_version() from public;
+grant execute on function agent_board.get_schema_version() to authenticated, service_role;

package/migrations/20260710000400_agent_board_nonfleet_identity.sql

@@ -0,0 +1,87 @@
+-- Non-fleet identity tables for delegation, workload exchange, and invitation APIs.
+-- Forward-only: do not apply linked or production migrations in NONFLEET phase.
+
+create table if not exists agent_board.nonfleet_sessions (
+  id text primary key,
+  session_id text not null,
+  identity_class text not null check (identity_class in ('ephemeral_child', 'hosted_workload', 'remote_sandbox', 'invited_external')),
+  agent_id uuid references agent_board.agents(id),
+  parent_agent_id uuid references agent_board.agents(id),
+  parent_credential_id uuid references agent_board.agent_credentials(id),
+  issuer text,
+  audience text,
+  repository text,
+  workflow_or_service text,
+  trust_domain text,
+  invitation_id text,
+  board_scope text,
+  repo_scope text,
+  task_scope text,
+  supervisor_allowed boolean not null default false,
+  elevated_admin_allowed boolean not null default false,
+  max_ttl_seconds integer not null default 3600,
+  issued_at timestamptz not null default now(),
+  expires_at timestamptz not null,
+  revoked_at timestamptz,
+  created_at timestamptz not null default now()
+);
+
+alter table agent_board.nonfleet_sessions
+  add column if not exists session_id text,
+  add column if not exists parent_credential_id uuid references agent_board.agent_credentials(id),
+  add column if not exists invitation_id text,
+  add column if not exists supervisor_allowed boolean not null default false,
+  add column if not exists elevated_admin_allowed boolean not null default false;
+
+alter table agent_board.nonfleet_sessions
+  alter column parent_credential_id type uuid using nullif(parent_credential_id::text, '')::uuid;
+
+create unique index if not exists idx_nonfleet_sessions_session_id on agent_board.nonfleet_sessions(session_id);
+create index if not exists idx_nonfleet_sessions_identity_class on agent_board.nonfleet_sessions(identity_class);
+create index if not exists idx_nonfleet_sessions_expires_at on agent_board.nonfleet_sessions(expires_at) where revoked_at is null;
+
+alter table agent_board.nonfleet_sessions enable row level security;
+drop policy if exists nonfleet_sessions_deny_anon on agent_board.nonfleet_sessions;
+drop policy if exists nonfleet_sessions_authenticated_read on agent_board.nonfleet_sessions;
+create policy nonfleet_sessions_deny_anon on agent_board.nonfleet_sessions for all to anon using (false);
+create policy nonfleet_sessions_authenticated_read on agent_board.nonfleet_sessions for select to authenticated
+  using (agent_id = agent_board.current_agent_id() or parent_agent_id = agent_board.current_agent_id());
+
+create table if not exists agent_board.nonfleet_invitations (
+  id text primary key,
+  trust_domain text not null,
+  invited_by_agent_id uuid not null references agent_board.agents(id),
+  accepting_agent_id uuid references agent_board.agents(id),
+  revoked_by_agent_id uuid references agent_board.agents(id),
+  board_scope text,
+  receive_policy text,
+  signing_posture text not null default 'require_for_external',
+  lifecycle_state text not null default 'pending' check (lifecycle_state in ('pending', 'accepted', 'expired', 'revoked', 'rejected')),
+  accepted_at timestamptz,
+  expires_at timestamptz not null,
+  revoked_at timestamptz,
+  created_at timestamptz not null default now()
+);
+
+alter table agent_board.nonfleet_invitations
+  add column if not exists invited_by_agent_id uuid references agent_board.agents(id),
+  add column if not exists revoked_by_agent_id uuid references agent_board.agents(id),
+  add column if not exists accepted_at timestamptz;
+
+alter table agent_board.nonfleet_invitations drop column if exists invited_by;
+
+create index if not exists idx_nonfleet_invitations_lifecycle on agent_board.nonfleet_invitations(lifecycle_state) where lifecycle_state = 'pending';
+
+alter table agent_board.nonfleet_invitations enable row level security;
+drop policy if exists nonfleet_invitations_deny_anon on agent_board.nonfleet_invitations;
+drop policy if exists nonfleet_invitations_authenticated_read on agent_board.nonfleet_invitations;
+create policy nonfleet_invitations_deny_anon on agent_board.nonfleet_invitations for all to anon using (false);
+create policy nonfleet_invitations_authenticated_read on agent_board.nonfleet_invitations for select to authenticated
+  using (invited_by_agent_id = agent_board.current_agent_id() or accepting_agent_id = agent_board.current_agent_id());
+
+revoke all on agent_board.nonfleet_sessions, agent_board.nonfleet_invitations from public, anon, authenticated;
+grant select on agent_board.nonfleet_sessions, agent_board.nonfleet_invitations to authenticated;
+grant select, insert, update on agent_board.nonfleet_sessions, agent_board.nonfleet_invitations to service_role;
+
+comment on table agent_board.nonfleet_sessions is 'Short-lived sessions for non-fleet identity classes: ephemeral children, hosted workloads, remote sandboxes, and invited external agents.';
+comment on table agent_board.nonfleet_invitations is 'Trust-domain invitations for explicitly invited third-party agents.';

package/migrations/20260710000401_agent_board_workload_providers.sql

@@ -0,0 +1,39 @@
+-- Workload provider registry for non-fleet identity exchange.
+-- Forward-only: do not apply linked or production migrations in NONFLEET phase.
+
+create table if not exists agent_board.workload_providers (
+  id text primary key default gen_random_uuid()::text,
+  issuer text not null,
+  audience text not null,
+  repository_claim text not null default 'repository',
+  max_session_ttl_seconds integer not null default 3600,
+  callback_support boolean not null default false,
+  pull_support boolean not null default true,
+  supported boolean not null default true,
+  policy_approved boolean not null default false,
+  allowed_repositories text[] not null default '{}',
+  allowed_workflows text[] not null default '{}',
+  allowed_board_scopes text[] not null default '{}',
+  created_at timestamptz not null default now(),
+  unique (issuer, audience)
+);
+
+alter table agent_board.workload_providers
+  add column if not exists policy_approved boolean not null default false,
+  add column if not exists allowed_repositories text[] not null default '{}',
+  add column if not exists allowed_workflows text[] not null default '{}',
+  add column if not exists allowed_board_scopes text[] not null default '{}';
+
+insert into agent_board.workload_providers (issuer, audience, repository_claim, max_session_ttl_seconds, callback_support, pull_support, supported)
+values
+  ('https://token.actions.githubusercontent.com', 'message-board', 'repository', 3600, true, true, true),
+  ('https://accounts.google.com', 'message-board', 'project_id', 3600, false, true, true),
+  ('https://sts.windows.net', 'message-board', 'unknown', 0, false, false, false),
+  ('https://login.microsoftonline.com', 'message-board', 'unknown', 0, false, false, false)
+on conflict (issuer, audience) do nothing;
+
+comment on table agent_board.workload_providers is 'Registry of supported and explicitly unsupported workload identity providers for non-fleet exchange.';
+
+revoke all on agent_board.workload_providers from public, anon, authenticated;
+grant select on agent_board.workload_providers to authenticated;
+grant select, insert, update on agent_board.workload_providers to service_role;

package/migrations/20260711000000_agent_board_provision_system_fail_closed.sql

@@ -0,0 +1,242 @@
+-- portal#203 — provision_agent must fail closed for system principals.
+--
+-- `agent_board.provision_agent` previously minted an auth user and issued a
+-- refresh credential for `p_kind = 'system'`, but `trg_sync_agent_principal_columns`
+-- (20260511000000) clears `auth_user_id` for system principals and the
+-- `agents_system_owner_shape` CHECK enforces it. The credential therefore can
+-- never bind an auth session, so `/api/agent-board/auth/exchange` returns
+-- `502 refresh_failed` for a token the RPC reported as valid.
+--
+-- Contract (issue option 1): reject credential issuance for system principals
+-- BEFORE minting anything. The raise sits ahead of `_ensure_agent_auth_user`
+-- and every insert, so no orphan `auth.users` row, agent row, or credential is
+-- created. System principals continue to exist as records created outside this
+-- credential-minting RPC (direct insert / migration); they simply cannot be
+-- issued exchangeable credentials.
+--
+-- Signature is byte-identical to the original definition so this replaces the
+-- function in place (grants survive CREATE OR REPLACE; no re-grant needed).
+--
+-- Defense in depth: the same un-exchangeable-credential class is also reachable
+-- through `rotate_agent_token` (and any future issuer), which likewise calls
+-- `_issue_agent_credential`. Rather than guard each entry point, reject system
+-- principals centrally in `_issue_agent_credential` — the single choke point
+-- every issuer funnels through — while keeping the earlier, clearer rejection in
+-- `provision_agent` (which also avoids creating an auth.users row up front).
+
+create or replace function agent_board._issue_agent_credential(
+  p_agent_id uuid,
+  p_credential_label text,
+  p_replaces_credential_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  credential_id uuid,
+  refresh_token text,
+  expires_at timestamptz,
+  created_at timestamptz,
+  replaces_credential_id uuid
+)
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_refresh_token text;
+  v_expires_at timestamptz := now() + interval '30 days';
+  v_created_at timestamptz := now();
+  v_credential_id uuid;
+begin
+  -- Fail closed for system principals. They have no auth binding (the sync
+  -- trigger clears auth_user_id and agents_system_owner_shape enforces it), so
+  -- any credential minted here is deterministically un-exchangeable. Rejecting
+  -- centrally covers provision_agent, rotate_agent_token, and any future issuer.
+  if exists (
+    select 1
+      from agent_board.agents a
+     where a.id = p_agent_id
+       and a.kind = 'system'::agent_board.agent_kind
+  ) then
+    raise exception 'cannot issue an exchangeable credential for a system principal (no auth binding)'
+      using errcode = '22023';
+  end if;
+
+  v_refresh_token := agent_board._mint_agent_refresh_token();
+
+  insert into agent_board.agent_credentials(
+    agent_id,
+    refresh_token_hash,
+    hash_version,
+    credential_label,
+    expires_at,
+    replaces_credential_id,
+    metadata,
+    created_at,
+    updated_at
+  )
+  values (
+    p_agent_id,
+    extensions.digest(v_refresh_token, 'sha256'),
+    1,
+    p_credential_label,
+    v_expires_at,
+    p_replaces_credential_id,
+    coalesce(p_metadata, '{}'::jsonb),
+    v_created_at,
+    v_created_at
+  )
+  returning id into v_credential_id;
+
+  if p_replaces_credential_id is not null then
+    update agent_board.agent_credentials
+       set revoked_at = coalesce(revoked_at, v_created_at),
+           rotated_at = coalesce(rotated_at, v_created_at),
+           replaced_by_credential_id = v_credential_id,
+           updated_at = v_created_at
+     where id = p_replaces_credential_id;
+  end if;
+
+  return query
+  select v_credential_id, v_refresh_token, v_expires_at, v_created_at, p_replaces_credential_id;
+end;
+$$;
+
+create or replace function agent_board.provision_agent(
+  p_slug text,
+  p_kind text,
+  p_scopes jsonb default '[]'::jsonb,
+  p_owner_user_id uuid default null
+)
+returns table(
+  agent_id uuid,
+  auth_user_id uuid,
+  credential_id uuid,
+  refresh_token text,
+  expires_at timestamptz,
+  created_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_slug text;
+  v_kind text;
+  v_owner_user_id uuid;
+  v_admin_user_id uuid;
+  v_auth_user_id uuid;
+  v_agent agent_board.agents%rowtype;
+  v_credential record;
+begin
+  v_admin_user_id := agent_board._require_platform_admin_user_id();
+  v_slug := agent_board._normalize_provision_slug(p_slug);
+  v_kind := lower(coalesce(trim(p_kind), ''));
+  v_owner_user_id := p_owner_user_id;
+
+  if v_kind not in ('human', 'agent', 'system') then
+    raise exception 'kind must be one of human, agent, or system' using errcode = '22023';
+  end if;
+
+  -- Fail closed: system principals have no auth binding (the sync trigger and
+  -- agents_system_owner_shape CHECK force auth_user_id to NULL), so any
+  -- credential minted here is deterministically un-exchangeable. Reject before
+  -- minting rather than returning an unusable-but-valid-looking token.
+  if v_kind = 'system' then
+    raise exception 'system principals cannot be issued exchangeable credentials; provision_agent does not support kind=system'
+      using errcode = '22023';
+  elsif v_owner_user_id is null then
+    raise exception 'owner_user_id is required for human and agent principals' using errcode = '22023';
+  elsif not exists (select 1 from auth.users where id = v_owner_user_id) then
+    raise exception 'owner user not found' using errcode = 'P0002';
+  end if;
+
+  select *
+    into v_agent
+    from agent_board.agents
+   where handle = v_slug
+   limit 1
+   for update;
+
+  v_auth_user_id := coalesce(v_agent.auth_user_id, agent_board._ensure_agent_auth_user(v_slug));
+
+  if v_agent.id is null then
+    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_slug,
+      agent_board._default_provision_display_name(v_slug),
+      'active',
+      v_auth_user_id,
+      v_owner_user_id,
+      jsonb_build_object(
+        'scopes', coalesce(p_scopes, '[]'::jsonb),
+        'provisionedByUserId', v_admin_user_id,
+        'provisionedAt', now()
+      )
+    )
+    returning * into v_agent;
+  else
+    update agent_board.agents a
+       set agent_type = v_kind,
+           kind = v_kind::agent_board.agent_kind,
+           status = 'active',
+           auth_user_id = v_auth_user_id,
+           owner_user_id = v_owner_user_id,
+           metadata = coalesce(a.metadata, '{}'::jsonb)
+             || jsonb_build_object(
+               'scopes', coalesce(p_scopes, '[]'::jsonb),
+               'provisionedByUserId', v_admin_user_id,
+               'provisionedAt', now()
+             ),
+           updated_at = now()
+     where a.id = v_agent.id
+     returning * into v_agent;
+  end if;
+
+  select *
+    into v_credential
+    from agent_board._issue_agent_credential(
+      v_agent.id,
+      'provisioned',
+      (
+        select ac.id
+          from agent_board.agent_credentials ac
+         where ac.agent_id = v_agent.id
+           and ac.revoked_at is null
+         order by ac.created_at desc
+         limit 1
+      ),
+      jsonb_build_object('issuedByUserId', v_admin_user_id, 'issuedAt', now(), 'scopes', coalesce(p_scopes, '[]'::jsonb))
+    );
+
+  return query
+  select v_agent.id, v_auth_user_id, v_credential.credential_id, v_credential.refresh_token, v_credential.expires_at, v_credential.created_at;
+end;
+$$;
+
+-- Data repair (idempotent, scoped): revoke any still-live credentials previously
+-- minted for system principals. They can never bind a session, so keeping them
+-- unrevoked only exposes un-exchangeable tokens. Touches only `revoked_at is null`
+-- credentials of `kind='system'` agents; a zero-row result is expected and fine.
+update agent_board.agent_credentials ac
+   set revoked_at = now(),
+       updated_at = now(),
+       metadata = coalesce(ac.metadata, '{}'::jsonb)
+         || jsonb_build_object(
+           'revokedReason', 'system_principal_fail_closed',
+           'revokedAt', now()
+         )
+  from agent_board.agents a
+ where a.id = ac.agent_id
+   and a.kind = 'system'::agent_board.agent_kind
+   and ac.revoked_at is null;