@consiliency/agent-board-schema 1.2.0

package/migrations/20260711000100_canary_signed_fleet_enforcement.sql

@@ -0,0 +1,234 @@
+create or replace function agent_board.evaluate_signed_write_fleet_policy(
+  p_operation text,
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(
+  allowed boolean,
+  actionable boolean,
+  denial_class text,
+  denied_recipient_agent_id uuid,
+  evaluated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := nullif(p_gateway_decision ->> 'agent_id', '')::uuid;
+  v_machine_id uuid;
+  v_board_id uuid;
+  v_recipient_ids uuid[] := '{}'::uuid[];
+  v_recipient_id uuid;
+  v_evidence_id uuid;
+  v_decision record;
+  v_status text := coalesce(nullif(p_gateway_decision ->> 'verification_status', ''), 'unsigned');
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'signed fleet policy evaluation requires service role' using errcode = '42501';
+  end if;
+  if v_actor is null then
+    raise exception 'actor_mismatch: signed write actor is required' using errcode = '42501';
+  end if;
+
+  select fma.machine_id
+    into v_machine_id
+    from agent_board.fleet_machine_agents fma
+    join agent_board.fleet_machines fm on fm.id = fma.machine_id
+   where fma.agent_id = v_actor
+     and fma.lifecycle_state = 'active'
+     and fm.lifecycle_state = 'active'
+   order by fma.updated_at desc
+   limit 1;
+
+  if v_machine_id is null then
+    return query select true, true, null::text, null::uuid, now();
+    return;
+  end if;
+
+  insert into agent_board.signature_evidence(
+    agent_id, signing_key_id, key_id, key_version, algorithm, source_kind,
+    operation, payload_digest, canonicalization_version, signature_digest,
+    verification_status, failure_class, signed_at, verified_at, nonce,
+    idempotency_key, external_evidence_ref, metadata
+  ) values (
+    v_actor,
+    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'),
+    'external',
+    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', ''),
+    case when v_status in ('unsigned', 'observed', 'warn', 'verified', 'failed') then v_status else 'failed' end,
+    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', ''),
+    'signed-write-preflight:' || coalesce(nullif(p_gateway_decision ->> 'idempotency_key', ''), nullif(p_gateway_decision ->> 'nonce', ''), gen_random_uuid()::text),
+    jsonb_build_object('gateway', 'signed-write-preflight', 'redacted', true, 'metadata-safe', true)
+  ) returning id into v_evidence_id;
+
+  if p_operation = 'send_direct_message' then
+    if nullif(p_payload ->> 'p_recipient_agent_id', '') is not null then
+      v_recipient_ids := array[(p_payload ->> 'p_recipient_agent_id')::uuid];
+    else
+      v_recipient_ids := agent_board._addressing_agent_ids_or_raise(v_actor, jsonb_build_array(p_payload -> 'p_recipient_descriptor'));
+    end if;
+  elsif p_operation = 'send_multicast_message' then
+    if p_payload ? 'p_recipient_agent_ids' then
+      select coalesce(array_agg(value::uuid), '{}'::uuid[]) into v_recipient_ids
+        from jsonb_array_elements_text(p_payload -> 'p_recipient_agent_ids');
+    else
+      v_recipient_ids := agent_board._addressing_agent_ids_or_raise(v_actor, p_payload -> 'p_recipient_descriptors');
+    end if;
+  elsif p_operation in ('post_board_message', 'create_tasking_delivery') then
+    if nullif(p_payload ->> 'p_board_id', '') is not null then
+      v_board_id := (p_payload ->> 'p_board_id')::uuid;
+    elsif nullif(p_payload ->> 'p_board_slug', '') is not null then
+      select id into v_board_id from agent_board.boards where slug = p_payload ->> 'p_board_slug' and status = 'active';
+    end if;
+    if p_operation = 'create_tasking_delivery' then
+      if p_payload ? 'p_recipient_agent_ids' then
+        select coalesce(array_agg(value::uuid), '{}'::uuid[]) into v_recipient_ids
+          from jsonb_array_elements_text(p_payload -> 'p_recipient_agent_ids');
+      elsif p_payload ? 'p_recipient_descriptors' and p_payload -> 'p_recipient_descriptors' <> 'null'::jsonb then
+        v_recipient_ids := agent_board._addressing_agent_ids_or_raise(v_actor, p_payload -> 'p_recipient_descriptors');
+      end if;
+    end if;
+    if v_board_id is not null then
+      select array(
+        select distinct recipient_id from (
+          select unnest(v_recipient_ids) as recipient_id
+          union
+          select bm.agent_id from agent_board.board_memberships bm
+           where bm.board_id = v_board_id and bm.membership_state in ('joined', 'subscribed')
+        ) recipients
+      ) into v_recipient_ids;
+    end if;
+  else
+    return query select true, true, null::text, null::uuid, now();
+    return;
+  end if;
+
+  if coalesce(cardinality(v_recipient_ids), 0) = 0 then
+    return query select false, false, 'recipient_policy_denied'::text, null::uuid, now();
+    return;
+  end if;
+
+  foreach v_recipient_id in array v_recipient_ids loop
+    select * into v_decision
+      from agent_board.evaluate_fleet_sender_policy(
+        v_actor,
+        v_recipient_id,
+        v_machine_id,
+        v_board_id,
+        p_operation,
+        v_evidence_id,
+        false
+      );
+    if not coalesce(v_decision.allowed, false) or not coalesce(v_decision.actionable, false) then
+      return query select false, false, coalesce(v_decision.denial_class, 'recipient_policy_denied'), v_recipient_id, now();
+      return;
+    end if;
+  end loop;
+
+  return query select true, true, null::text, null::uuid, now();
+end;
+$$;
+
+create or replace function agent_board.signed_send_multicast_message(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(message_id uuid, delivered_recipient_count integer, inbox_item_count integer, callback_outbox_count integer, signature_evidence_id uuid, verification_status text, created_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_author_agent_id');
+  v_evidence_id uuid;
+  v_recipient_ids uuid[];
+begin
+  if p_payload ? 'p_recipient_agent_ids' then
+    select array_agg(value::uuid) into v_recipient_ids from jsonb_array_elements_text(p_payload -> 'p_recipient_agent_ids');
+    select * into v_row from agent_board.send_multicast_message(
+      (p_payload ->> 'p_thread_id')::uuid, v_actor, v_recipient_ids,
+      p_payload ->> 'p_subject', p_payload ->> 'p_body', coalesce(p_payload ->> 'p_message_type', 'comment'),
+      coalesce(p_payload ->> 'p_priority', 'medium'), nullif(p_payload ->> 'p_idempotency_key', ''),
+      coalesce(p_payload -> 'p_metadata', '{}'::jsonb) || jsonb_build_object('signed_write', jsonb_build_object('verification_status', coalesce(p_gateway_decision ->> 'verification_status', 'unsigned'), 'redacted', true))
+    );
+  else
+    select * into v_row from agent_board.send_multicast_message(
+      (p_payload ->> 'p_thread_id')::uuid, v_actor, p_payload -> 'p_recipient_descriptors',
+      coalesce(p_payload ->> 'p_addressing_mode', 'addressing_v1'), p_payload ->> 'p_subject', p_payload ->> 'p_body',
+      coalesce(p_payload ->> 'p_message_type', 'comment'), coalesce(p_payload ->> 'p_priority', 'medium'),
+      nullif(p_payload ->> 'p_idempotency_key', ''), coalesce(p_payload -> 'p_metadata', '{}'::jsonb)
+    );
+  end if;
+  v_evidence_id := agent_board._record_signed_write_evidence('message', v_row.message_id, 'send_multicast_message', p_payload, p_gateway_decision);
+  return query select v_row.message_id, v_row.delivered_recipient_count, v_row.inbox_item_count, v_row.callback_outbox_count, v_evidence_id, coalesce(p_gateway_decision ->> 'verification_status', 'unsigned'), v_row.created_at;
+end;
+$$;
+
+create or replace function agent_board.signed_create_tasking_delivery(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(task_id uuid, created_event_id uuid, delivered_recipient_count integer, inbox_item_count integer, callback_outbox_count integer, signature_evidence_id uuid, verification_status text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_created_by_agent_id');
+  v_evidence_id uuid;
+  v_recipient_ids uuid[];
+begin
+  if p_payload ? 'p_recipient_agent_ids' or p_payload ? 'p_board_id' then
+    if p_payload ? 'p_recipient_agent_ids' then
+      select array_agg(value::uuid) into v_recipient_ids from jsonb_array_elements_text(p_payload -> 'p_recipient_agent_ids');
+    end if;
+    select * into v_row from agent_board.create_tasking_delivery(
+      (p_payload ->> 'p_thread_id')::uuid, v_actor, p_payload ->> 'p_title', p_payload ->> 'p_details',
+      v_recipient_ids, nullif(p_payload ->> 'p_board_id', '')::uuid, coalesce(p_payload ->> 'p_priority', 'medium'),
+      coalesce(p_payload ->> 'p_orchestration_mode', 'distributed'), nullif(p_payload ->> 'p_idempotency_key', ''),
+      coalesce(p_payload -> 'p_metadata', '{}'::jsonb) || jsonb_build_object('signed_write', jsonb_build_object('verification_status', coalesce(p_gateway_decision ->> 'verification_status', 'unsigned'), 'redacted', true))
+    );
+  else
+    select * into v_row from agent_board.create_tasking_delivery(
+      (p_payload ->> 'p_thread_id')::uuid, v_actor, p_payload ->> 'p_title', p_payload ->> 'p_details',
+      p_payload -> 'p_recipient_descriptors', p_payload ->> 'p_board_slug', coalesce(p_payload ->> 'p_addressing_mode', 'addressing_v1'),
+      coalesce(p_payload ->> 'p_priority', 'medium'), coalesce(p_payload ->> 'p_orchestration_mode', 'distributed'),
+      nullif(p_payload ->> 'p_idempotency_key', ''), coalesce(p_payload -> 'p_metadata', '{}'::jsonb)
+    );
+  end if;
+  v_evidence_id := agent_board._record_signed_write_evidence('task_event', v_row.created_event_id, 'create_tasking_delivery', p_payload, p_gateway_decision);
+  return query select v_row.task_id, v_row.created_event_id, v_row.delivered_recipient_count, v_row.inbox_item_count, v_row.callback_outbox_count, v_evidence_id, coalesce(p_gateway_decision ->> 'verification_status', 'unsigned'), v_row.created_at, v_row.updated_at;
+end;
+$$;
+
+revoke all on function agent_board.evaluate_signed_write_fleet_policy(text, jsonb, jsonb) from public, anon, authenticated;
+revoke all on function agent_board.signed_send_multicast_message(jsonb, jsonb) from public, anon, authenticated;
+revoke all on function agent_board.signed_create_tasking_delivery(jsonb, jsonb) from public, anon, authenticated;
+grant execute on function agent_board.evaluate_signed_write_fleet_policy(text, jsonb, jsonb) to service_role;
+grant execute on function agent_board.signed_send_multicast_message(jsonb, jsonb) to service_role;
+grant execute on function agent_board.signed_create_tasking_delivery(jsonb, jsonb) to service_role;
+
+revoke execute on function agent_board.send_direct_message(uuid, uuid, uuid, text, text, text, text, text, jsonb) from authenticated;
+revoke execute on function agent_board.send_direct_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb) from authenticated;
+revoke execute on function agent_board.send_multicast_message(uuid, uuid, uuid[], text, text, text, text, text, jsonb) from authenticated;
+revoke execute on function agent_board.send_multicast_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb) from authenticated;
+revoke execute on function agent_board.post_board_message(uuid, uuid, uuid, text, text, text, text, text, jsonb) from authenticated;
+revoke execute on function agent_board.post_board_message(uuid, uuid, text, text, text, text, text, text, text, jsonb) from authenticated;
+revoke execute on function agent_board.create_tasking_delivery(uuid, uuid, text, text, uuid[], uuid, text, text, text, jsonb) from authenticated;
+revoke execute on function agent_board.create_tasking_delivery(uuid, uuid, text, text, jsonb, text, text, text, text, text, jsonb) from authenticated;
+
+insert into agent_board.schema_version(version) values (5)
+on conflict ((true)) do update set version = greatest(agent_board.schema_version.version, excluded.version);

package/migrations/20260712000000_agent_board_bundle_endpoint_compat.sql

@@ -0,0 +1,97 @@
+-- MBENDPOINT — bundle-installation metadata + authenticated compatibility RPC.
+-- Message Board-owned FORWARD migration (IF-0-MBPLANE-ENDPOINT-ARTIFACT-1),
+-- appended after the frozen union. Additive: it does NOT change the
+-- client-facing agent_board.schema_version (7). The install record is written
+-- by the materializer / adopter at apply time via record_bundle_installation();
+-- it is never hardcoded to a not-yet-selected release here.
+
+-- Singleton identity of the installed @consiliency/agent-board-schema bundle.
+create table if not exists agent_board.bundle_installation (
+  id                   boolean primary key default true,
+  constraint bundle_installation_singleton check (id),
+  package_version      text not null,
+  bundle_digest        text not null,
+  schema_version       integer not null,
+  source_commit        text,
+  materializer_receipt text,
+  installed_at         timestamptz not null default now()
+);
+
+comment on table agent_board.bundle_installation is
+  'Singleton: identity of the installed @consiliency/agent-board-schema release. Written by the materializer at apply time; consumed by get_bundle_compatibility().';
+
+-- Written by the materializer/adopter at apply time to record the exact
+-- installed bundle. Service-role only.
+create or replace function agent_board.record_bundle_installation(
+  p_package_version      text,
+  p_bundle_digest        text,
+  p_schema_version       integer,
+  p_source_commit        text default null,
+  p_materializer_receipt text default null
+)
+returns void
+language sql
+security definer
+set search_path = agent_board, pg_temp
+as $$
+  insert into agent_board.bundle_installation as bi
+    (id, package_version, bundle_digest, schema_version, source_commit, materializer_receipt, installed_at)
+  values (true, p_package_version, p_bundle_digest, p_schema_version, p_source_commit, p_materializer_receipt, now())
+  on conflict (id) do update set
+    package_version      = excluded.package_version,
+    bundle_digest        = excluded.bundle_digest,
+    schema_version       = excluded.schema_version,
+    source_commit        = excluded.source_commit,
+    materializer_receipt = excluded.materializer_receipt,
+    installed_at         = now();
+$$;
+
+revoke all on function agent_board.record_bundle_installation(text, text, integer, text, text) from public, anon, authenticated;
+grant execute on function agent_board.record_bundle_installation(text, text, integer, text, text) to service_role;
+
+-- Authenticated compatibility health. Reports schema version, installed bundle
+-- identity, signed-write enforcement posture, and redacted readiness. Returns
+-- NO credential, secret, or row content.
+create or replace function agent_board.get_bundle_compatibility()
+returns jsonb
+language sql
+stable
+security definer
+set search_path = agent_board, pg_temp
+as $$
+  select jsonb_build_object(
+    'schema_version', (select version from agent_board.schema_version limit 1),
+    'installed_bundle_version', (select package_version from agent_board.bundle_installation limit 1),
+    'installed_bundle_digest', (select bundle_digest from agent_board.bundle_installation limit 1),
+    'installed_schema_version', (select schema_version from agent_board.bundle_installation limit 1),
+    'source_commit', (select source_commit from agent_board.bundle_installation limit 1),
+    -- Signed-write enforcement is active when the signed gateway exists AND
+    -- NONE of the four canary-revoked raw write RPCs are directly executable by
+    -- authenticated (writes must be channeled through the signed gateway). The
+    -- probe checks all four RPCs, not just one, so a partial re-grant on any of
+    -- them correctly reports enforcement as NOT fully active.
+    'signed_write_enforced', (
+      to_regprocedure('agent_board.signed_send_direct_message(jsonb, jsonb)') is not null
+      and not exists (
+        select 1 from information_schema.role_routine_grants
+         where routine_schema = 'agent_board'
+           and routine_name in (
+             'send_direct_message', 'send_multicast_message',
+             'post_board_message', 'create_tasking_delivery'
+           )
+           and grantee = 'authenticated'
+           and privilege_type = 'EXECUTE'
+      )
+    ),
+    -- Ready only once the materializer has recorded an install AND the schema
+    -- version handshake resolves.
+    'ready', (
+      (select version from agent_board.schema_version limit 1) is not null
+      and exists (select 1 from agent_board.bundle_installation)
+    ),
+    'checked_at', now()
+  );
+$$;
+
+revoke all on function agent_board.get_bundle_compatibility() from public, anon;
+grant execute on function agent_board.get_bundle_compatibility() to authenticated, service_role;

package/migrations/20260713000000_agent_board_rls_reassert_board_scoping.sql

@@ -0,0 +1,90 @@
+-- Forward corrective migration (rollback Class B) — reassert the board-scoping
+-- SELECT policies for delivery_recipients, inbox_items, and tasks to their
+-- canonical, board-scoped (qualified) form.
+--
+-- WHY: a production database can carry #208 drift bytes that predate/omit the
+-- 20260514000000 board-scoping fix, leaving these three policies collapsed to
+-- the LEAKING tautology (bm.board_id = bm.board_id / dr.source_task_id = dr.id)
+-- while its migration history claims 20260514000000 is applied — so version-ID
+-- recognition would skip re-running it. This new-ID migration reasserts the
+-- correct predicates. Effect of the leak: an authenticated agent who is a
+-- joined/subscribed member of ANY board could read delivery_recipients and
+-- inbox_items rows scoped to ANY OTHER board.
+--
+-- SCOPE: exactly the three policies the normalized catalog-equivalence check
+-- flagged as bundle-owned divergences (plans/MBPLANE-CATALOG-EQUIVALENCE-*).
+-- The 20260514000000 `boards` and `messages` policies are intentionally NOT
+-- reasserted here: `boards` was superseded by 20260515000000_agent_board_boardopt
+-- (reasserting the older form would revert board discovery), and prod's
+-- `messages` policy already matches the bundle. Idempotent; only TIGHTENS access
+-- (leaky -> board-scoped); no schema-shape change; does NOT write schema_version.
+
+drop policy if exists agent_board_authenticated_select_tasks on agent_board.tasks;
+create policy agent_board_authenticated_select_tasks
+on agent_board.tasks
+as permissive
+for select
+to authenticated
+using (
+  created_by_agent_id = agent_board.current_agent_id()
+  or assigned_agent_id = agent_board.current_agent_id()
+  or exists (
+    select 1
+      from agent_board.delivery_recipients dr
+     where dr.source_task_id = tasks.id
+       and (
+         dr.recipient_agent_id = agent_board.current_agent_id()
+         or (
+           dr.board_id is not null
+           and exists (
+             select 1
+               from agent_board.board_memberships bm
+              where bm.board_id = dr.board_id
+                and bm.agent_id = agent_board.current_agent_id()
+                and bm.membership_state in ('joined', 'subscribed')
+           )
+         )
+       )
+  )
+);
+
+drop policy if exists agent_board_authenticated_select_delivery_recipients on agent_board.delivery_recipients;
+create policy agent_board_authenticated_select_delivery_recipients
+on agent_board.delivery_recipients
+as permissive
+for select
+to authenticated
+using (
+  recipient_agent_id = agent_board.current_agent_id()
+  or (
+    board_id is not null
+    and exists (
+      select 1
+        from agent_board.board_memberships bm
+       where bm.board_id = delivery_recipients.board_id
+         and bm.agent_id = agent_board.current_agent_id()
+         and bm.membership_state in ('joined', 'subscribed')
+    )
+  )
+);
+
+drop policy if exists agent_board_authenticated_select_inbox_items on agent_board.inbox_items;
+create policy agent_board_authenticated_select_inbox_items
+on agent_board.inbox_items
+as permissive
+for select
+to authenticated
+using (
+  recipient_agent_id = agent_board.current_agent_id()
+  or (
+    board_id is not null
+    and visible_in_board_feed = true
+    and exists (
+      select 1
+        from agent_board.board_memberships bm
+       where bm.board_id = inbox_items.board_id
+         and bm.agent_id = agent_board.current_agent_id()
+         and bm.membership_state in ('joined', 'subscribed')
+    )
+  )
+);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@consiliency/agent-board-schema",
+  "version": "1.2.0",
+  "description": "Canonical, immutable, exact-pinnable agent_board schema bundle: ordered SQL migrations, digest + compatibility manifest, and deterministic materialize/plan/check tooling for adopters.",
+  "repository": "https://github.com/Consiliency/message-board.git",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./manifest": "./schema-manifest.json",
+    "./provenance": "./provenance.json"
+  },
+  "bin": {
+    "agent-board-schema": "./bin/agent-board-schema.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "migrations",
+    "tests",
+    "fixtures",
+    "schema-manifest.json",
+    "provenance.json",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "build:manifest": "node ../../scripts/build-schema-manifest.mjs",
+    "check:manifest": "node ../../scripts/build-schema-manifest.mjs --check",
+    "test": "vitest run",
+    "pack:smoke": "node ../../scripts/schema-packed-consumer-smoke.mjs"
+  }
+}