@consiliency/agent-board-schema 1.35.0 → 1.40.0

package/migrations/20260919000100_agent_board_signed_write_model_key.sql

@@ -0,0 +1,107 @@
+-- SIGNEDWRITEMODEL (message-board#326) — a self-describing sibling for
+-- `signed_write_enforced` in the bundle/schema handshake.
+--
+-- THE PROBLEM. After #324 the flag has the right VALUE and the wrong NAME. It is
+-- called "signed write enforced" and it tests "the signed path is operator-only".
+-- Those are different propositions, and a boolean cannot say which one it means.
+-- The consequence is already written down in specs/operations.md: a reader must
+-- combine the flag with `installed_bundle_version` to know which MEANING they are
+-- looking at — below 1.37.0 it tests the model 20260718000800 abandoned, at or
+-- above it tests the current one. That works and it asks every reader to carry a
+-- version boundary in their head.
+--
+-- WHY NOT RENAME OR RETIRE, which is the strongest argument in this area.
+-- packages/agent-board-client/src/compatibility.ts recognises a health response
+-- with a runtime TYPE GUARD:
+--     "schema_version" in value && "signed_write_enforced" in value && "ready" in value
+-- Drop the key and every deployed client stops recognising a HEALTHY board's
+-- response as a health response at all. The other spelling of retirement — keep
+-- the key, pin it false/null forever — is a permanently-lying instrument, which is
+-- precisely the harm #310 names. Retirement loses both ways, which is why #324
+-- re-pointed rather than replaced, and why this migration ADDS.
+--
+-- WHY ADDING IS SAFE, and how far that claim goes. The guard requires those three
+-- keys to be PRESENT; it does not enumerate the payload. Checked rather than
+-- assumed: no consumer in this repository asserts an exhaustive key set over
+-- `get_bundle_compatibility()` — the pgTAP consumers read individual keys with
+-- `->>`, and the client reads named fields. A consumer OUTSIDE this repository
+-- that pins the whole object would still be broken by any added key, which is a
+-- property of adding keys and not of this one.
+--
+-- NOT PROPOSED: gating on it. A sound gate is constructible
+-- (`installed_bundle_version >= 1.37.0 AND flag true`) but semver strings need
+-- real comparison, and the recorded version is what the materializer WROTE, not
+-- necessarily what is APPLIED. That makes a good argument and a bad gate, so this
+-- ships as a decode hint like the boolean beside it.
+--
+-- FUTURE-PROOFING is the actual point. The next posture change adds a new VALUE
+-- here rather than silently re-pointing a boolean for a second time — which is
+-- exactly what #310 was.
+--
+-- CREATE OR REPLACE with the identical signature, so the existing ACL survives.
+-- The grants are restated anyway and the COMMENT rewritten, because a recreated
+-- SECURITY DEFINER function that does not restate them is the gate-bypass this
+-- repo has already shipped once (#118). `anon` is deliberately NOT granted.
+
+CREATE OR REPLACE FUNCTION agent_board.get_bundle_compatibility()
+ RETURNS jsonb
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO 'agent_board', 'pg_temp'
+AS $function$
+  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),
+    -- #326: which PROPOSITION the boolean below is answering, said out loud, so a
+    -- reader does not have to consult a version boundary to decode it. A constant
+    -- rather than a derivation: it names the model this bundle's predicate encodes,
+    -- which is a fact about the migration you are reading, not about the database.
+    'signed_write_model', 'operator-only-gateway',
+    -- #310: enforcement means the SIGNED path stays operator-only, not that the unsigned path is
+    -- unreachable. See 20260918000100's header for what this does and does not establish.
+    'signed_write_enforced', (
+      -- The anchor. A schema with no signed gateway grants none of them, which would make the
+      -- second clause vacuously true; requiring the gateway to exist is what stops "enforced"
+      -- from meaning "nothing to enforce".
+      exists (
+        select 1
+          from pg_catalog.pg_proc p
+          join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+         where n.nspname = 'agent_board'
+           and p.proname = 'signed_send_direct_message'
+      )
+      and not exists (
+        -- Catalog-derived over pg_proc ROWS: covers all seven gateways and every overload of
+        -- each, and asks the privilege RESOLVER rather than reading a direct-grant view.
+        select 1
+          from pg_catalog.pg_proc p
+          join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+         cross join (values ('authenticated'), ('anon')) as r(rolname)
+         where n.nspname = 'agent_board'
+           and p.proname like 'signed\_%'
+           and pg_catalog.has_function_privilege(r.rolname, p.oid, '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()
+  );
+$function$;
+
+-- Restated rather than relied upon. CREATE OR REPLACE preserves the ACL, but this repo has
+-- already shipped a gate-bypass by recreating a SECURITY DEFINER function without restating its
+-- privileges, so the rule is to restate them in the same migration every time. `anon` is
+-- deliberately NOT granted: it did not hold EXECUTE before this migration and must not gain it.
+revoke all on function agent_board.get_bundle_compatibility() from public;
+grant execute on function agent_board.get_bundle_compatibility() to authenticated;
+grant execute on function agent_board.get_bundle_compatibility() to service_role;
+
+comment on function agent_board.get_bundle_compatibility() is
+  'Bundle/schema handshake for adopters. `signed_write_model` NAMES the proposition the boolean beside it answers -- `operator-only-gateway` means "the signed gateway exists and no agent_board.signed_* function (all overloads, via has_function_privilege) is EXECUTE-able by authenticated or anon". Read the pair: the model says WHAT is being tested, `signed_write_enforced` says whether it HOLDS. PRESENCE of this key implies the current meaning and needs no semver comparison. ABSENCE does NOT imply the retired one: the boolean changed meaning at bundle 1.37.0 and this key starts at 1.38.0, so on exactly 1.37.x the key is absent while a FALSE is a REAL regression. Absent means consult installed_bundle_version, not "nothing to see". Neither field is a gate. Neither tests that a writer derives its actor from the session and gates -- that half is asserted in agent_board_signed_write_enforced.test.sql, and ONLY for the unsigned counterpart of a signed_* gateway, so a writer with no signed twin is outside both instruments. #310, #326.';

package/migrations/20260920000100_agent_board_realtime_credential_claim.sql

@@ -0,0 +1,119 @@
+-- #341 — `current_agent_id()`'s credential check never ran. Anywhere.
+--
+-- THE DEFECT, corrected after a correctness seat disproved this header's first version by
+-- measurement. The original text said PostgREST sets the per-claim GUCs and Realtime does not, so
+-- the credential branch was dead only for subscribers. That is FALSE, and the truth is worse.
+--
+-- Measured through a real PostgREST (v14.5) with a signed `authenticated` JWT carrying
+-- `agent_credential_id`, by a probe function called over HTTP:
+--
+--   per_claim_sub       : null
+--   per_claim_cred      : null
+--   whole_json_present  : true
+--   whole_json_has_cred : true
+--
+-- PostgREST REMOVED the legacy `request.jwt.claim.<name>` GUCs (the option went away in v12), and
+-- nothing in this repository sets them either. So the pre-fix body, which read ONLY that source,
+-- resolved the claim to NULL on EVERY transport. NULL takes the permissive branch by design, and
+-- the branch requiring a non-revoked, non-expired credential NEVER EXECUTED — not on Realtime,
+-- and not on the RPC path either.
+--
+-- CONSEQUENCE, stated plainly because the first version of this header understated its own fix:
+-- mid-JWT-lifetime credential revocation stopped nothing, anywhere. This migration does not
+-- "restore" a gate that worked on one path; it ACTIVATES the credential gate for the first time,
+-- on every path. That is a real behaviour change on the live RPC path, not only a subscription fix.
+--
+-- WHY AUTH.UID() SURVIVED THE SAME GAP, which is where the fix comes from. `auth.uid()` already
+-- reads BOTH sources and coalesces:
+--
+--   coalesce(
+--     nullif(current_setting('request.jwt.claim.sub', true), ''),
+--     (nullif(current_setting('request.jwt.claims', true), '')::jsonb ->> 'sub')
+--   )::uuid
+--
+-- The second source is populated on both transports, and carries custom claims. Verified on
+-- Realtime with a throwaway table whose RLS policy keyed ONLY on that GUC (a row wanting the JWT's
+-- value delivered, a row wanting a different value not), and on PostgREST by the probe above.
+--
+-- THE FIX is that same coalesce shape applied to the credential claim. Nothing is loosened:
+-- absence in BOTH sources still takes the permissive branch, which callers that legitimately have
+-- no credential depend on.
+--
+-- NO NEW RAISE PATH — and the first version of this header was wrong about that too. It claimed
+-- the cast to `jsonb` was "a way this function can now raise where it previously could not". The
+-- previous body raised as well: with a per-claim value of `bogus` it raises
+-- `invalid input syntax for type uuid (22P02)`, measured on the pre-fix body. The UUID regex does
+-- NOT guard the cast — the cast is evaluated at SQL-function startup, before any qual filtering,
+-- so a malformed value raises regardless of a conjunct that syntactically precedes it.
+--
+-- Rather than disclose that, this migration REMOVES the raise class: the credential is compared as
+-- TEXT against `ac.id::text`, so a malformed claim of any shape (`""`, `42`, `{"a":1}`, `bogus`)
+-- matches nothing and DENIES CLEANLY instead of erroring. `lower()` because `uuid::text` is
+-- canonical lowercase and the claim may not be. The regex is kept as a cheap pre-filter, and is
+-- now genuinely a filter rather than a guard that never guarded.
+--
+-- WHAT THIS DOES NOT DO. It does not make a Realtime payload trustworthy. Delivery is now gated on
+-- the same credential the RPC path checks, but the event body is still a replication row image and
+-- the subscription can silently miss events (`SUBSCRIBED` is reported before events actually flow —
+-- measured: on a cold Realtime container the first insert after SUBSCRIBED was dropped). Consumers
+-- must treat an event as "something changed, go fetch". That posture is asserted in the client.
+--
+-- CREATE OR REPLACE with the identical signature, so the ACL survives — verified before writing
+-- this: `authenticated` and `service_role` hold EXECUTE, `anon` does not, PUBLIC holds nothing.
+-- Restated anyway, because a recreated SECURITY DEFINER function that does not restate its
+-- privileges is a gate-bypass this repo has already shipped once.
+
+create or replace function agent_board.current_agent_id()
+returns uuid
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with credential_claim as (
+    -- #341: read BOTH sources. PostgREST sets the per-claim GUC; Realtime sets only the
+    -- whole-JSON one. Reading a single source made the credential branch dead code for every
+    -- Realtime subscriber. Mirrors auth.uid(), which has always coalesced for the same reason.
+    select coalesce(
+             nullif(current_setting('request.jwt.claim.agent_credential_id', true), ''),
+             -- The OUTER nullif is not redundant, and its absence was a transport inconsistency
+             -- caught by a test: the per-claim arm maps '' to absent, so without this the same
+             -- logical claim ("" ) would be ABSENT on one transport and a malformed credential
+             -- that DENIES on the other. Same input, different answer by transport, which is the
+             -- exact bug class #341 is about. Empty means absent on both, matching what omission
+             -- already permits.
+             nullif(nullif(current_setting('request.jwt.claims', true), '')::jsonb ->> 'agent_credential_id', '')
+           ) 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
+            -- TEXT comparison, never a cast of the untrusted claim: a malformed value must DENY,
+            -- not raise. `ac.id::text` is canonical lowercase, hence lower() on the claim.
+            where ac.id::text = lower(cc.credential_id_text)
+              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;
+$$;
+
+-- Restated rather than relied upon. `anon` is deliberately NOT granted: it did not hold EXECUTE
+-- before this migration and must not gain it.
+revoke all on function agent_board.current_agent_id() from public;
+grant execute on function agent_board.current_agent_id() to authenticated;
+grant execute on function agent_board.current_agent_id() to service_role;
+
+comment on function agent_board.current_agent_id() is
+  'Resolves auth.uid() to the active agent_board.agents.id and, when an agent_credential_id claim is present in EITHER the per-claim GUC (request.jwt.claim.agent_credential_id) or the whole-JSON GUC (request.jwt.claims), requires it to reference a non-revoked, non-expired credential for that agent. Reading only the per-claim source made the credential branch unreachable on EVERY transport, not just Realtime: PostgREST removed those legacy GUCs at v12 and nothing here sets them, so the claim read NULL and took the permissive branch everywhere. This migration ACTIVATES the credential gate for the first time rather than restoring it (#341). The claim is compared as TEXT against agent_credentials.id::text, so a malformed claim denies cleanly instead of raising 22P02. Absence in BOTH sources still takes the permissive branch, which callers that legitimately have no credential depend on.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.35.0",
+  "version": "1.40.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",

package/schema-manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent_board_schema_manifest.v1",
   "interface": "IF-0-MBPLANE-BUNDLE-1",
   "package": "@consiliency/agent-board-schema",
-  "packageVersion": "1.35.0",
+  "packageVersion": "1.40.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 134,
-  "aggregateSha256": "f63027fa44451c55a39fcc8f463df6ae6f4b92765578be053d8bf3b9a2bee07e",
+  "migrationCount": 138,
+  "aggregateSha256": "e5e6870533c69d20b446431b6fb19693588d9eb4bb55e1fb3f7f239afcfa76c0",
   "migrations": [
     {
       "order": 0,
@@ -1254,6 +1254,42 @@
       "sourceRef": "message-board",
       "bytes": 84162,
       "sha256": "d9f05e18094954f2e4ee32bf7b129f0a9ffc39bc800a5efa9cf7938e1555c8dc"
+    },
+    {
+      "order": 134,
+      "id": "20260917000100_agent_board_invite_no_downgrade",
+      "filename": "20260917000100_agent_board_invite_no_downgrade.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 24929,
+      "sha256": "c205a9a679dca059979972b49c89c3b1b3b8f8e2039bd7675a10578f49f9b35a"
+    },
+    {
+      "order": 135,
+      "id": "20260918000100_agent_board_signed_write_enforced_repoint",
+      "filename": "20260918000100_agent_board_signed_write_enforced_repoint.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 9965,
+      "sha256": "f76dd01744029bfd0088bd4f6cf6fa5cb93e3c9b7fa5559ad83857cf7f4eb8ce"
+    },
+    {
+      "order": 136,
+      "id": "20260919000100_agent_board_signed_write_model_key",
+      "filename": "20260919000100_agent_board_signed_write_model_key.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 7204,
+      "sha256": "464ae39acbd96330c5ad1c753fa1204ca290baa0d6f82d7d30d0ead4d2944d37"
+    },
+    {
+      "order": 137,
+      "id": "20260920000100_agent_board_realtime_credential_claim",
+      "filename": "20260920000100_agent_board_realtime_credential_claim.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 7556,
+      "sha256": "670d6e97ca84ef74ebd10a6ee102c328005a28aa48f8668ba444ce31b714cf02"
     }
   ],
   "excludedBridge": {