@consiliency/agent-board-schema 1.2.0 → 1.4.0

package/migrations/20260717000400_agent_board_delegation_policies.sql

@@ -0,0 +1,175 @@
+-- MBAUTHZ SL-4 (Lane D): delegation policies, board authority ceilings, and the
+-- _grant_within_ceiling helper.
+--
+-- Additive, no send-path behavior change. MBAUTHZ OWNS this schema + helper;
+-- MBSENDAUTHZ (later phase) only consumes it. The board ceiling is a SEPARATE
+-- table keyed on board_id (maintainer decision), NOT a boards column; a board
+-- with no ceiling row defaults to 'owner' (unchanged behavior).
+
+-- 1. delegation_policies -----------------------------------------------------
+create table if not exists agent_board.delegation_policies (
+  id uuid primary key default gen_random_uuid(),
+  root_agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  mode text not null default 'independent_auth' check (mode in ('independent_auth', 'root_minted')),
+  max_depth int not null default 1,
+  max_active_children int,
+  allowed_scopes jsonb,
+  -- The grant/working clock (hours-scale), NOT the <=15-min session-token clock.
+  child_ttl_ceiling interval not null default interval '8 hours',
+  require_child_signing_key boolean not null default true,
+  revoked_at timestamptz,
+  created_at timestamptz not null default now()
+);
+
+comment on table agent_board.delegation_policies is
+  'Per-root-agent delegation policy. child_ttl_ceiling is the hours-scale grant/working clock, not the session-token clock.';
+
+create index if not exists idx_agent_board_delegation_policies_root
+  on agent_board.delegation_policies(root_agent_id)
+  where revoked_at is null;
+
+alter table agent_board.delegation_policies enable row level security;
+
+drop policy if exists agent_board_authenticated_select_delegation_policies on agent_board.delegation_policies;
+create policy agent_board_authenticated_select_delegation_policies
+on agent_board.delegation_policies
+as permissive
+for select
+to authenticated
+using (root_agent_id = agent_board.current_agent_id());
+
+grant select on agent_board.delegation_policies to authenticated;
+grant select, insert, update on agent_board.delegation_policies to service_role;
+
+-- 2. board_authority_ceilings (separate table; not a boards column) ---------
+create table if not exists agent_board.board_authority_ceilings (
+  board_id uuid primary key references agent_board.boards(id) on delete cascade,
+  max_grantable_role text not null default 'owner' check (max_grantable_role in ('owner', 'admin', 'member', 'observer')),
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+comment on table agent_board.board_authority_ceilings is
+  'Optional per-board cap on the highest role a grantor may grant. No row means no explicit ceiling, resolved as owner (unchanged behavior).';
+
+alter table agent_board.board_authority_ceilings enable row level security;
+
+drop policy if exists agent_board_authenticated_select_board_authority_ceilings on agent_board.board_authority_ceilings;
+create policy agent_board_authenticated_select_board_authority_ceilings
+on agent_board.board_authority_ceilings
+as permissive
+for select
+to authenticated
+using (agent_board._current_agent_has_board_access(board_id));
+
+grant select on agent_board.board_authority_ceilings to authenticated;
+grant select, insert, update on agent_board.board_authority_ceilings to service_role;
+
+-- 3. _grant_within_ceiling ---------------------------------------------------
+-- Role partial order owner>admin>member>observer. A grant is permitted iff the
+-- grantee role does not outrank the grantor's own board role AND does not
+-- outrank the board's ceiling (default owner when no ceiling row exists).
+create or replace function agent_board._grant_within_ceiling(
+  p_grantor_agent_id uuid,
+  p_board_id uuid,
+  p_grantee_role text
+)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with ranks(role, rank) as (
+    values ('owner', 4), ('admin', 3), ('member', 2), ('observer', 1)
+  ),
+  grantor as (
+    select r.rank
+      from agent_board.board_memberships bm
+      join ranks r on r.role = bm.role
+     where bm.board_id = p_board_id
+       and bm.agent_id = p_grantor_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+     order by r.rank desc
+     limit 1
+  ),
+  ceiling as (
+    select coalesce(
+      (select r.rank
+         from agent_board.board_authority_ceilings c
+         join ranks r on r.role = c.max_grantable_role
+        where c.board_id = p_board_id),
+      4  -- no row -> owner
+    ) as rank
+  ),
+  grantee as (
+    select rank from ranks where role = p_grantee_role
+  )
+  select
+    (select rank from grantee) is not null
+    and exists (select 1 from grantor)
+    and (select rank from grantee) <= (select rank from grantor)
+    and (select rank from grantee) <= (select rank from ceiling)
+$$;
+
+comment on function agent_board._grant_within_ceiling(uuid, uuid, text) is
+  'True iff p_grantee_role does not outrank the grantor''s active board role nor the board ceiling (default owner). MBAUTHZ owns this; MBSENDAUTHZ consumes it.';
+
+revoke all on function agent_board._grant_within_ceiling(uuid, uuid, text) from public, anon;
+grant execute on function agent_board._grant_within_ceiling(uuid, uuid, text) to authenticated, service_role;
+
+-- 4. set_board_authority_ceiling (owner-settable cap) ------------------------
+-- #13: the board owner (the human root's delegated authority) can set the per-board
+-- ceiling. Permitted ONLY when the caller (current_agent_id()) holds an owner
+-- board_memberships row for that board; every other caller raises 42501. The
+-- grantee-bounded _grant_within_ceiling semantics above are unchanged — this only
+-- lets the owner set the stored ceiling row that _grant_within_ceiling reads.
+-- service_role (current_agent_id() = null) is intentionally NOT an owner here; it
+-- retains its direct table-write grant for operator provisioning.
+create or replace function agent_board.set_board_authority_ceiling(
+  p_board_id uuid,
+  p_max_grantable_role text
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if p_max_grantable_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'max_grantable_role must be one of owner/admin/member/observer' using errcode = '22023';
+  end if;
+
+  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 board authority ceiling' using errcode = '42501';
+  end if;
+
+  insert into agent_board.board_authority_ceilings(board_id, max_grantable_role)
+  values (p_board_id, p_max_grantable_role)
+  on conflict (board_id) do update
+    set max_grantable_role = excluded.max_grantable_role,
+        updated_at = now();
+
+  return query
+  select p_board_id, p_max_grantable_role;
+end;
+$$;
+
+comment on function agent_board.set_board_authority_ceiling(uuid, text) is
+  'Owner-gated setter for a board''s authority ceiling: upserts board_authority_ceilings only when current_agent_id() is an owner of the board (else raises 42501). Leaves _grant_within_ceiling semantics unchanged.';
+
+revoke all on function agent_board.set_board_authority_ceiling(uuid, text) from public, anon;
+grant execute on function agent_board.set_board_authority_ceiling(uuid, text) to authenticated, service_role;

package/migrations/20260718000100_agent_board_send_authz_config.sql

@@ -0,0 +1,172 @@
+-- MBSENDAUTHZ SL-0 (preamble): shared send-authz enforcement config + telemetry.
+--
+-- Additive, dormant. Creates the single-writer shared objects that SL-1/SL-2/SL-3
+-- consume:
+--   * agent_board.fleet_send_enforcement_flags  — per-sender-fleet-scope mode flag
+--     (absent row => fail_open_preserved, i.e. current behavior unchanged).
+--   * agent_board.nonfleet_sender_allowlist     — legitimate non-fleet system flows,
+--     consulted only under deny mode. Structure is code; population is operational.
+--   * agent_board.send_authz_telemetry (+ recorder) — per-call authz telemetry with
+--     the frozen EF-vs-host origin discriminator that MBDELEG's host-bypass drain
+--     gate reads.
+--   * agent_board._resolve_send_fleet_scope / _send_fleet_scope_mode — the fleet
+--     scope resolver + flag-mode lookup.
+--
+-- No send-path behavior changes here: these objects are only wired into the send
+-- path by SL-1 (bypass telemetry) and SL-2 (non-fleet default-deny). schema_version
+-- is intentionally NOT bumped (phase is dormant/additive).
+
+-- 1. fleet_send_enforcement_flags (IF-0-MBSENDAUTHZ-2) -----------------------
+-- Board-native (agent_board.*), deliberately NOT public.app_settings. Absent row
+-- for a scope => fail_open_preserved (preserves current behavior for that scope).
+create table if not exists agent_board.fleet_send_enforcement_flags (
+  scope_key text primary key,
+  mode text not null default 'fail_open_preserved'
+    check (mode in ('fail_open_preserved', 'observe', 'deny')),
+  updated_at timestamptz not null default now()
+);
+
+comment on table agent_board.fleet_send_enforcement_flags is
+  'Per-sender-fleet-scope send enforcement mode. Absent row => fail_open_preserved (current behavior). observe => allow + record would_be_deny; deny => deny non-allowlisted non-fleet senders. Operator-managed (service_role).';
+
+alter table agent_board.fleet_send_enforcement_flags enable row level security;
+grant select, insert, update, delete on agent_board.fleet_send_enforcement_flags to service_role;
+
+-- 2. nonfleet_sender_allowlist (IF-0-MBSENDAUTHZ-6) --------------------------
+-- Enumerates legitimate non-fleet system flows; consulted only under deny mode.
+-- Structure is code; population is operational (derived from the observe pass).
+create table if not exists agent_board.nonfleet_sender_allowlist (
+  agent_id uuid primary key references agent_board.agents(id) on delete cascade,
+  reason text not null,
+  created_at timestamptz not null default now()
+);
+
+comment on table agent_board.nonfleet_sender_allowlist is
+  'Tight allowlist of legitimate non-fleet system senders. Consulted only under deny mode: a non-fleet sender is admitted iff it has a row here. Population is operational (derived from the observe pass).';
+
+alter table agent_board.nonfleet_sender_allowlist enable row level security;
+grant select, insert, update, delete on agent_board.nonfleet_sender_allowlist to service_role;
+
+-- 3. send_authz_telemetry (IF-0-MBSENDAUTHZ-5) ------------------------------
+-- Per-call authz telemetry. origin is the frozen EF-vs-host discriminator that
+-- MBDELEG's "zero host-originated service_role" drain gate reads.
+create table if not exists agent_board.send_authz_telemetry (
+  id uuid primary key default gen_random_uuid(),
+  kind text not null check (kind in ('service_role_bypass', 'would_be_deny')),
+  origin text not null check (origin in ('ef', 'host', 'unknown')),
+  actor_agent_id uuid,
+  board_id uuid,
+  operation text,
+  scope_key text,
+  denial_class text,
+  metadata jsonb not null default '{}'::jsonb,
+  recorded_at timestamptz not null default now()
+);
+
+comment on table agent_board.send_authz_telemetry is
+  'Per-call send authorization telemetry. kind=service_role_bypass (a service_role guarded-bypass send) or would_be_deny (a non-fleet send that deny mode would have blocked). origin (ef|host|unknown) is the frozen host-vs-EF discriminator MBDELEG drains against.';
+
+create index if not exists idx_agent_board_send_authz_telemetry_kind_origin
+  on agent_board.send_authz_telemetry(kind, origin, recorded_at desc);
+
+alter table agent_board.send_authz_telemetry enable row level security;
+grant select, insert on agent_board.send_authz_telemetry to service_role;
+
+create or replace function agent_board._record_send_authz_telemetry(
+  p_kind text,
+  p_origin text,
+  p_actor_agent_id uuid,
+  p_board_id uuid,
+  p_operation text,
+  p_scope_key text,
+  p_denial_class text,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_id uuid;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'send authz telemetry recording requires service role' using errcode = '42501';
+  end if;
+  insert into agent_board.send_authz_telemetry(
+    kind, origin, actor_agent_id, board_id, operation, scope_key, denial_class, metadata
+  ) values (
+    p_kind,
+    case when p_origin in ('ef', 'host') then p_origin else 'unknown' end,
+    p_actor_agent_id,
+    p_board_id,
+    p_operation,
+    p_scope_key,
+    p_denial_class,
+    coalesce(p_metadata, '{}'::jsonb)
+  ) returning id into v_id;
+  return v_id;
+end;
+$$;
+
+comment on function agent_board._record_send_authz_telemetry(text, text, uuid, uuid, text, text, text, jsonb) is
+  'Service_role-only recorder for send_authz_telemetry. Normalizes origin to ef|host|unknown. Called internally by the send RPCs (bypass) and the fleet policy (would_be_deny).';
+
+revoke all on function agent_board._record_send_authz_telemetry(text, text, uuid, uuid, text, text, text, jsonb) from public, anon, authenticated;
+grant execute on function agent_board._record_send_authz_telemetry(text, text, uuid, uuid, text, text, text, jsonb) to service_role;
+
+-- 4. fleet scope resolver + flag-mode lookup (IF-0-MBSENDAUTHZ-3) ------------
+-- Trust-domain-derived scope where the sender is fleet-resolvable (mirrors the
+-- active-machine resolution in evaluate_signed_write_fleet_policy), else the single
+-- catch-all 'nonfleet' bucket (the v_machine_id is null population).
+create or replace function agent_board._resolve_send_fleet_scope(
+  p_actor uuid
+)
+returns text
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(
+    (select 'fleet:' || ftd.slug
+       from agent_board.fleet_machine_agents fma
+       join agent_board.fleet_machines fm on fm.id = fma.machine_id
+       join agent_board.fleet_trust_domains ftd on ftd.id = fm.trust_domain_id
+      where fma.agent_id = p_actor
+        and fma.lifecycle_state = 'active'
+        and fm.lifecycle_state = 'active'
+      order by fma.updated_at desc
+      limit 1),
+    'nonfleet'
+  )
+$$;
+
+comment on function agent_board._resolve_send_fleet_scope(uuid) is
+  'Resolves a sender to its trust-domain-derived fleet scope key, or the catch-all ''nonfleet'' bucket when the sender has no active fleet machine.';
+
+revoke all on function agent_board._resolve_send_fleet_scope(uuid) from public, anon, authenticated;
+grant execute on function agent_board._resolve_send_fleet_scope(uuid) to service_role;
+
+create or replace function agent_board._send_fleet_scope_mode(
+  p_scope_key text
+)
+returns text
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(
+    (select mode
+       from agent_board.fleet_send_enforcement_flags
+      where scope_key = p_scope_key),
+    'fail_open_preserved'
+  )
+$$;
+
+comment on function agent_board._send_fleet_scope_mode(text) is
+  'Resolves the enforcement mode for a sender-fleet-scope key, defaulting to fail_open_preserved when no flag row exists.';
+
+revoke all on function agent_board._send_fleet_scope_mode(text) from public, anon, authenticated;
+grant execute on function agent_board._send_fleet_scope_mode(text) to service_role;