@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260818000100_agent_board_fleet_machines_rls_correlation.sql

@@ -0,0 +1,43 @@
+-- #132 — fleet_machines authenticated SELECT policy: fix the dead binding arm.
+--
+-- The policy `agent_board_authenticated_select_fleet_machines` gated its EXISTS subquery on
+-- `fma.machine_id = fma.id` — a fleet_machine_agents SELF-comparison (machine_id FKs
+-- fleet_machines.id; fma.id is the junction PK), so it is NEVER true and a bound agent could
+-- never SELECT its own machine via the binding arm (only the owner arm worked).
+--
+-- The naive fix (`fma.machine_id = fleet_machines.id`) INFINITELY RECURSES: fleet_machine_agents'
+-- own SELECT policy references fleet_machines back, so a correlated subquery over the binding
+-- table re-enters this policy. (The original never recursed only because its dead comparison
+-- meant the subquery never evaluated against real rows.) Break the cycle with a SECURITY DEFINER
+-- helper that reads the binding table with RLS bypassed — the same technique the other
+-- policy-helper predicates use.
+--
+-- Additive, forward-only; policy + internal helper. schema_version stays 8.
+
+create or replace function agent_board._current_agent_bound_to_machine(p_machine_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1
+      from agent_board.fleet_machine_agents fma
+     where fma.machine_id = p_machine_id
+       and fma.agent_id = agent_board.current_agent_id()
+       and fma.lifecycle_state = 'active'
+  )
+$$;
+comment on function agent_board._current_agent_bound_to_machine(uuid) is
+  '#132: does the current agent hold an ACTIVE fleet_machine_agents binding on this machine? SECURITY DEFINER so the fleet_machines SELECT policy can consult the binding table without recursing into its RLS (which references fleet_machines back). Session-derived; PUBLIC EXECUTE revoked.';
+revoke all on function agent_board._current_agent_bound_to_machine(uuid) from public, anon;
+grant execute on function agent_board._current_agent_bound_to_machine(uuid) to authenticated, service_role;
+
+drop policy if exists agent_board_authenticated_select_fleet_machines on agent_board.fleet_machines;
+create policy agent_board_authenticated_select_fleet_machines on agent_board.fleet_machines
+  as permissive for select to authenticated
+  using (
+    owner_agent_id = agent_board.current_agent_id()
+    or agent_board._current_agent_bound_to_machine(id)
+  );

package/migrations/20260819000100_agent_board_resolve_noop_retire.sql

@@ -0,0 +1,166 @@
+-- MBCONSENT resolve/request no-op polish (#116, Fable #114 Part B).
+--
+-- B1 — approve-no-op left the pending row dangling. When an owner "approves" a subject who is
+-- ALREADY active, resolve_board_request returns the active row untouched (the Option-1 no-op) but
+-- did not retire the redundant requested/invited row, so pending listings kept showing a request
+-- the owner believes resolved (only a reject cleared it). Fix: retire the redundant pending row to
+-- 'left' (recoverable) in the no-op path, routed through the emitting sink so the write hits the
+-- ledger (the emission-completeness invariant). The emitted event is board-authored (actor !=
+-- subject) and therefore NEUTRAL for consent — it records the pending request's retirement without
+-- touching the subject's consent-present status, which the untouched active row carries. B4
+-- (target state / p_metadata ignored on the no-op path)
+-- and B2 (with two pending rows only the newest resolves) are documented in-place — behaviour
+-- unchanged, deliberately.
+--
+-- CREATE OR REPLACE with the same body plus the B1 retire; grants re-asserted. schema_version
+-- stays 8. Additive, forward-only.
+
+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 timestamp with time zone, updated_at timestamp with time zone)
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_effective_state text;
+  v_board agent_board.boards%rowtype;
+  v_membership_id uuid;
+  v_active_id uuid;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  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
+      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
+      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;
+
+  -- Lock the WHOLE (board, agent) set first so a concurrent self-withdrawal on ANY physical row
+  -- serialises behind this resolution (#109's race is per-(board,agent), not per-row).
+  perform 1
+     from agent_board.board_memberships bm
+    where bm.board_id = p_board_id
+      and bm.agent_id = p_agent_id
+    order by bm.id
+      for update;
+
+  -- Select the PENDING row explicitly (not the total-order winner). B2 (#116): with TWO pending
+  -- rows (a requested AND an invited) for one subject this resolves the NEWEST; the older dangles.
+  -- Inherent to the multi-row model — resolution is one act on one row.
+  select bm.id
+    into v_membership_id
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('requested', 'invited')
+   order by bm.created_at desc, bm.id desc
+   limit 1;
+
+  select bm.id
+    into v_active_id
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('joined', 'subscribed')
+   order by bm.created_at desc, bm.id desc
+   limit 1;
+
+  if v_membership_id is null then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  -- OPTION 1 FALLBACK (#109 A3): approving a subject who is ALREADY active is a no-op success,
+  -- not a promotion of the pending row into collision with the active one. Return the active row
+  -- untouched. Rejection still falls through to act on the pending row.
+  --
+  -- B4 (#116): the no-op path intentionally IGNORES the requested target state and p_metadata —
+  -- approving with target 'subscribed' a 'joined' active row returns 'joined' (a self-toggle
+  -- belongs to update_board_membership, which is where the old path coupled the metadata write to
+  -- a demotion). Nothing legitimate is lost.
+  if p_membership_state in ('joined', 'subscribed') and v_active_id is not null then
+    -- B1 (#116): retire the redundant pending row so it stops showing in pending listings. The
+    -- subject is already active via v_active_id (untouched); route the retire through the sink so
+    -- the write EMITS (the emission-completeness invariant requires every membership write to hit
+    -- the ledger) — a board-authored 'left' event, which is NEUTRAL for consent (not the subject's
+    -- own act) and does not affect the subject's consent-present status carried by the active row.
+    -- 'left' is recoverable. Previously only a reject cleared this, leaving an owner-visible
+    -- dangling request after a no-op approve.
+    perform agent_board._upsert_board_membership_state(
+      p_board_id, p_agent_id, 'left', p_created_by_agent_id, p_metadata, v_membership_id, 'noop_superseded'
+    );
+
+    return query
+    select bm.id, bm.board_id, bm.agent_id, bm.membership_state, bm.left_at, bm.updated_at
+      from agent_board.board_memberships bm
+     where bm.id = v_active_id;
+    return;
+  end if;
+
+  -- REJECTSEM (#89): a rejection is NOT an eviction — resolve only acts on a PENDING row, so a
+  -- refusal lands on 'left' (recoverable), never 'removed' (which bars self-re-entry). Applied to
+  -- both requested and invited origins.
+  v_effective_state := case when p_membership_state = 'removed' then 'left'
+                            else p_membership_state end;
+
+  -- #82: promotion into an active state requires the subject's own consent act (the sole
+  -- consent-predicate read site). Authenticated only; service_role keeps the operator carve-out.
+  if v_actor is not null
+     and v_effective_state in ('joined', 'subscribed')
+     and not agent_board._membership_consent_present(p_board_id, p_agent_id) then
+    raise exception 'admitting % requires an act by that agent', p_agent_id
+      using errcode = '42501';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    v_effective_state,
+    p_created_by_agent_id,
+    p_metadata,
+    v_membership_id,
+    case when p_membership_state = 'removed' then 'reject_withdrawn' else null end
+  );
+
+  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;
+$function$;
+
+revoke all on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) from public, anon;
+grant execute on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) to authenticated, service_role;

package/migrations/20260820000100_agent_board_roomdeleg_lane_b.sql

@@ -0,0 +1,206 @@
+-- =============================================================================
+-- ROOMDELEG-2 / Lane B (#59) — self-service delegation policy writer for an
+-- authenticated human-root (partial: policy writer only; minter deferred).
+-- =============================================================================
+-- Lane A (#57) shipped owner-gated set_board_role_gate. Lane B opens self-service
+-- delegation to an authenticated human-agent root. This migration ships the SAFE half —
+-- the policy writer — and DEFERS opening the minter (section 3 explains why):
+--
+--   upsert_delegation_policy (NEW)     — write the root's own policy. SHIPS HERE.
+--   mint_delegated_child (gate widened) — DEFERRED to #138 (needs child-key PoP +
+--                                         raw-byte fingerprint first; see section 3).
+--
+-- BLOCKING DECISION (4-seat panel, ratified): there is NO `_grant_within_ceiling`-analog
+-- for delegation SCOPES, and building one would be worse than not having it. A catalog
+-- enumeration of every reader of delegation scope found that NO resource gate consumes
+-- `allowed_scopes`: mint reads only grant liveness; the obsgate authoring/task/claims
+-- gates and the send-authz layer gate on board membership/role and fleet origin, never
+-- on granted scope. So `allowed_scopes` is ADVISORY — a scope-ceiling would cap a value
+-- with zero enforcement effect, making mint's `requested ⊆ allowed_scopes` guard LOOK
+-- non-vacuous while pinning nothing (the "succeeds where it should not" failure class).
+-- Real capability is gated downstream: a child with self-declared scopes `["*"]` can do
+-- nothing until an authority ADMITS it to a board (bounded by _grant_within_ceiling and
+-- the board's ceiling), its session stays live, and its signing key is unrevoked.
+--
+-- Keeping "advisory" HONEST rather than a latent landmine: the frozen scope model
+-- (20260718001000) declares a root's scope IS `allowed_scopes`, so a future phase may
+-- start consuming it — at which point rows self-declared under this regime would silently
+-- become load-bearing. Defuse it STRUCTURALLY with a provenance column: the authenticated
+-- self-service path always stamps `scope_attestation='self_declared'` (session-derived,
+-- never caller-supplied — the same doctrine as event provenance). Any future consumer
+-- MUST require `operator_vetted` or apply a real ceiling at consumption time.
+--
+-- The fields that DO have teeth are hard-clamped on the self-service path (a root could
+-- otherwise self-set keyless children / unbounded fan-out / an inflated TTL):
+--   require_child_signing_key : pinned true          (keyless children erode signed-write evidence)
+--   max_active_children       : non-null, 1..25      (each mint provisions an auth.users row)
+--   child_ttl_ceiling         : positive, <= 24h
+--   max_depth                 : pinned 1             (no transitive minting; mint also enforces it)
+-- Actor binding: root == current_agent_id() via _resolved_actor_agent_id (strict for v1;
+-- owner-parity widening is compatible later, a contraction would not be). service_role
+-- keeps the operator carve-out (trusted; scopes operator_vetted; caps as supplied).
+--
+-- schema_version stays 8: additive (one column + one new function + one gate widening).
+-- =============================================================================
+
+-- ---------------------------------------------------------------------------
+-- 1. Scope provenance column. Existing rows were all service_role-written, so the
+--    `default 'operator_vetted'` backfills them correctly on ALTER.
+-- ---------------------------------------------------------------------------
+alter table agent_board.delegation_policies
+  add column if not exists scope_attestation text not null default 'operator_vetted'
+    check (scope_attestation in ('operator_vetted', 'self_declared'));
+
+comment on column agent_board.delegation_policies.scope_attestation is
+  'Provenance of allowed_scopes. self_declared = written by the root itself via the '
+  'authenticated upsert_delegation_policy self-service path — scopes are ADVISORY, NOT '
+  'operator-vetted authority. operator_vetted = written by service_role. A future gate '
+  'that consumes allowed_scopes as capability MUST require operator_vetted (or apply a '
+  'real ceiling at consumption); it must NEVER trust self_declared scopes as authority. '
+  'Stamped from the session, never from a caller argument. Existing rows backfilled '
+  'operator_vetted (all were service_role-written).';
+
+-- ---------------------------------------------------------------------------
+-- 2. upsert_delegation_policy — the authenticated self-service policy writer.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.upsert_delegation_policy(
+  p_root_agent_id uuid,
+  p_mode text default 'root_minted',
+  p_allowed_scopes jsonb default null,
+  p_max_active_children int default null,
+  p_child_ttl_ceiling interval default null,
+  p_require_child_signing_key boolean default null
+)
+returns agent_board.delegation_policies
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $$
+declare
+  v_actor uuid;
+  v_is_service boolean := agent_board._is_service_role();
+  v_attestation text;
+  v_mode text;
+  v_max_children int;
+  v_ttl interval;
+  v_require_key boolean;
+  v_existing agent_board.delegation_policies%rowtype;
+  v_policy agent_board.delegation_policies%rowtype;
+begin
+  -- Actor bound to the SESSION: authenticated -> current_agent_id() and p_root must
+  -- match it; service_role -> the supplied p_root (create-on-behalf-of). The binding is
+  -- derived from the session, never trusted from the parameter (Lane A's coalesce lesson).
+  v_actor := agent_board._resolved_actor_agent_id(p_root_agent_id, 'p_root_agent_id');
+
+  if not exists (select 1 from agent_board.agents where id = v_actor) then
+    raise exception 'root agent not found' using errcode = 'P0002';
+  end if;
+
+  -- Serialize concurrent self-service writes for the SAME root. The find-then-branch
+  -- below takes `for update`, but a `for update` over ZERO rows locks nothing, so two
+  -- concurrent FIRST upserts could each insert an active policy row (same-actor, not a
+  -- cross-root escalation, but it makes latest-policy selection ambiguous). A per-root
+  -- transaction advisory lock is the mutex — dedicated namespace, no coupling to the
+  -- agents row other flows may lock.
+  perform pg_advisory_xact_lock(hashtext('agent_board.delegation_policy:' || v_actor::text));
+
+  if p_mode is not null and p_mode not in ('independent_auth', 'root_minted') then
+    raise exception 'invalid delegation policy mode' using errcode = '22023';
+  end if;
+  v_mode := coalesce(p_mode, 'root_minted');
+
+  if v_is_service then
+    -- OPERATOR path: trusted. Scopes are operator-vetted; caps as supplied (table
+    -- defaults apply for nulls).
+    v_attestation := 'operator_vetted';
+    v_max_children := p_max_active_children;
+    v_ttl := coalesce(p_child_ttl_ceiling, interval '8 hours');
+    v_require_key := coalesce(p_require_child_signing_key, true);
+  else
+    -- SELF-SERVICE path: dangerous fields are CLAMPED, not trusted, and the scopes are
+    -- accepted but STAMPED self_declared.
+    v_attestation := 'self_declared';
+    -- require_child_signing_key: PINNED true regardless of input.
+    v_require_key := true;
+    -- max_active_children: NON-NULL, bounded 1..25.
+    v_max_children := coalesce(p_max_active_children, 5);
+    if v_max_children < 1 or v_max_children > 25 then
+      raise exception 'max_active_children must be between 1 and 25 for self-service delegation policies' using errcode = '22023';
+    end if;
+    -- child_ttl_ceiling: positive, capped at 24h (default 8h).
+    v_ttl := coalesce(p_child_ttl_ceiling, interval '8 hours');
+    if v_ttl <= interval '0' then
+      raise exception 'child_ttl_ceiling must be positive' using errcode = '22023';
+    end if;
+    if v_ttl > interval '24 hours' then
+      raise exception 'child_ttl_ceiling may not exceed 24 hours for self-service delegation policies' using errcode = '22023';
+    end if;
+  end if;
+
+  -- Upsert the root's CURRENT active policy. There is no unique on root_agent_id and the
+  -- mint reads the latest unrevoked row, so find-then-branch under a row lock rather than
+  -- ON CONFLICT: a concurrent self-service write serializes here. max_depth is PINNED 1 on
+  -- both branches — the mint enforces it structurally, but pinning the stored field stops a
+  -- future depth-aware mint inheriting an inflated value.
+  select * into v_existing
+    from agent_board.delegation_policies dp
+   where dp.root_agent_id = v_actor
+     and dp.revoked_at is null
+   order by dp.created_at desc
+   limit 1
+   for update;
+
+  if found then
+    update agent_board.delegation_policies dp
+       set mode = v_mode,
+           max_depth = 1,
+           max_active_children = v_max_children,
+           allowed_scopes = coalesce(p_allowed_scopes, '[]'::jsonb),
+           child_ttl_ceiling = v_ttl,
+           require_child_signing_key = v_require_key,
+           scope_attestation = v_attestation
+     where dp.id = v_existing.id
+    returning * into v_policy;
+  else
+    insert into agent_board.delegation_policies(
+      root_agent_id, mode, max_depth, max_active_children, allowed_scopes,
+      child_ttl_ceiling, require_child_signing_key, scope_attestation
+    )
+    values (
+      v_actor, v_mode, 1, v_max_children, coalesce(p_allowed_scopes, '[]'::jsonb),
+      v_ttl, v_require_key, v_attestation
+    )
+    returning * into v_policy;
+  end if;
+
+  return v_policy;
+end;
+$$;
+
+comment on function agent_board.upsert_delegation_policy(uuid, text, jsonb, int, interval, boolean) is
+  'Self-service writer for a root''s delegation policy (ROOMDELEG-2 / #59). authenticated: '
+  'actor bound root == current_agent_id(); scopes accepted but stamped scope_attestation='
+  '''self_declared'' (ADVISORY — see the column comment); require_child_signing_key pinned '
+  'true, max_active_children clamped 1..25, child_ttl_ceiling clamped <=24h, max_depth pinned '
+  '1. service_role: create-on-behalf-of, operator_vetted, caps as supplied. Upserts the root''s '
+  'latest unrevoked policy row.';
+
+revoke all on function agent_board.upsert_delegation_policy(uuid, text, jsonb, int, interval, boolean) from public, anon, authenticated;
+grant execute on function agent_board.upsert_delegation_policy(uuid, text, jsonb, int, interval, boolean) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 3. mint_delegated_child — DEFERRED.
+-- ---------------------------------------------------------------------------
+-- Opening mint to authenticated is INTENTIONALLY NOT done here. mint stamps a
+-- caller-supplied child public key as proof_state='proven' with NO proof-of-possession,
+-- and derives its fingerprint over the base64url STRING rather than the raw key bytes
+-- (20260718001000:203). Under the current service_role-only gate that is operator-trusted;
+-- but opening it to authenticated would let any root register a VICTIM's public key as its
+-- child's "proven" key — and because the string-fingerprint differs from enroll's raw-byte
+-- fingerprint (fixed for enroll in 20260719001200), the agent_signing_keys.fingerprint
+-- UNIQUE backstop does not dedup across the two paths, so the squat sails past it.
+--
+-- Mint therefore stays service_role-only until that class is closed. The mint-opening +
+-- child-key PoP + raw-byte fingerprint (catalog-enumerated across every fingerprint writer)
+-- + the non-positive-TTL floor land together in the hardening tracked by #138. This PR ships
+-- only the self-service POLICY writer, which handles no keys and adds no signing surface.