@consiliency/agent-board-schema 1.38.0 → 1.40.0

package/fixtures/already-applied.json

@@ -548,6 +548,10 @@
     {
       "id": "20260919000100_agent_board_signed_write_model_key",
       "sha256": "464ae39acbd96330c5ad1c753fa1204ca290baa0d6f82d7d30d0ead4d2944d37"
+    },
+    {
+      "id": "20260920000100_agent_board_realtime_credential_claim",
+      "sha256": "670d6e97ca84ef74ebd10a6ee102c328005a28aa48f8668ba444ce31b714cf02"
     }
   ]
 }

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.38.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.38.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": 137,
-  "aggregateSha256": "bfe0b978234464938428a66199b75d2f8d028706517b4674f9ae11cae34c52d1",
+  "migrationCount": 138,
+  "aggregateSha256": "e5e6870533c69d20b446431b6fb19693588d9eb4bb55e1fb3f7f239afcfa76c0",
   "migrations": [
     {
       "order": 0,
@@ -1281,6 +1281,15 @@
       "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": {

package/src/tooling.test.mjs

@@ -38,9 +38,9 @@ describe('manifest integrity', () => {
     expect(manifest.schemaVersion).toBe(8);
     expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
   });
-  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 137)', () => {
+  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL + one RTCREDCLAIM forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 138)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(137);
+    expect(manifest.migrationCount).toBe(138);
     // MBSESSION switched enforcement on (scoped-send re-grant): the client-visible
     // schema version bumped to 8. MBDELEG tightens delegation and MBFED adds only
     // enrollment-only additive surface (identity_providers registry, enrollment audit,
@@ -222,6 +222,17 @@ describe('manifest integrity', () => {
       // names. Definition-only: CREATE OR REPLACE with the identical signature, grants and
       // COMMENT restated in the same migration.
       '20260919000100_agent_board_signed_write_model_key.sql',
+      // #341 RTCREDCLAIM. `current_agent_id()` read the agent_credential_id claim ONLY from
+      // `request.jwt.claim.agent_credential_id`, which PostgREST sets and Realtime does not --
+      // so on a postgres_changes subscription the claim read NULL, NULL took the permissive
+      // branch by design, and the branch requiring a non-revoked credential never executed.
+      // Credential revocation did not stop realtime delivery. Measured: a JWT carrying a bogus
+      // credential still received its rows in 542ms. The fix is the coalesce shape auth.uid()
+      // has always used -- read the per-claim GUC, else `request.jwt.claims ->> ...` -- which is
+      // exactly why auth.uid() survived the same gap. Nothing is loosened: absence in BOTH
+      // sources still takes the permissive branch. Definition-only: CREATE OR REPLACE with the
+      // identical signature, grants and COMMENT restated in the same migration.
+      '20260920000100_agent_board_realtime_credential_claim.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }

package/tests/agent_board_realtime_credential_claim.test.sql

@@ -0,0 +1,301 @@
+-- #341 — the credential branch of `current_agent_id()` must run on BOTH claim transports.
+--
+-- WHY THIS FILE EXISTS. `current_agent_id()` read the credential claim from exactly one place,
+-- `request.jwt.claim.agent_credential_id`, which PostgREST sets and Realtime does not. So for
+-- every `postgres_changes` subscriber the claim read NULL, NULL took the permissive branch by
+-- design, and the branch requiring a non-revoked credential never executed. Credential revocation
+-- did not stop realtime delivery.
+--
+-- The defect was invisible to every existing test because they all exercise the PostgREST-shaped
+-- context, where the per-claim GUC IS set. The assertions below therefore separate the two
+-- transports deliberately: the ones that matter set the whole-JSON GUC and NOTHING else, which is
+-- the context a Realtime subscriber actually gets.
+--
+-- WHAT EACH HALF PINS:
+--   * per-claim transport  -- pre-existing behaviour, asserted so the fix cannot regress it;
+--   * whole-JSON transport -- the fix. These fail on the pre-#341 body;
+--   * absence in BOTH      -- the permissive branch, which callers with no credential depend on.
+--     Asserted positively rather than assumed, because "the fix did not over-deny" is the half a
+--     revocation fix is most likely to get wrong.
+
+begin;
+select plan(17);
+
+-- ---------------------------------------------------------------------------
+-- Fixture: one auth user, one active agent bound to it, three credentials
+-- (valid / revoked / expired) belonging to that agent.
+-- ---------------------------------------------------------------------------
+insert into auth.users (id, instance_id, aud, role, email, created_at, updated_at)
+values (
+  '34100000-0000-4000-8000-000000000001',
+  '00000000-0000-0000-0000-000000000000',
+  'authenticated', 'authenticated', 'rtcred-subject@example.test', now(), now()
+);
+
+insert into agent_board.agents (id, agent_type, handle, display_name, status, metadata, auth_user_id)
+values (
+  '34100000-0000-4000-8000-000000000010',
+  'agent', 'rtcred-subject', 'Realtime Credential Subject', 'active', '{}'::jsonb,
+  '34100000-0000-4000-8000-000000000001'
+);
+
+insert into agent_board.agent_credentials
+  (id, agent_id, refresh_token_hash, hash_version, credential_label, expires_at, revoked_at)
+values
+  ('34100000-0000-4000-8000-000000000100', '34100000-0000-4000-8000-000000000010',
+   '\x3411'::bytea, 1, 'valid', now() + interval '1 day', null),
+  ('34100000-0000-4000-8000-000000000200', '34100000-0000-4000-8000-000000000010',
+   '\x3412'::bytea, 1, 'revoked', now() + interval '1 day', now() - interval '1 hour'),
+  ('34100000-0000-4000-8000-000000000300', '34100000-0000-4000-8000-000000000010',
+   '\x3413'::bytea, 1, 'expired', now() - interval '1 hour', null);
+
+-- ---------------------------------------------------------------------------
+-- A. PER-CLAIM GUC context. NOTE THE LABEL: an earlier version called this "PostgREST-shaped",
+--    which is wrong -- PostgREST removed these GUCs at v12 and sets only request.jwt.claims, so
+--    NO production transport produces this context; only direct SQL / set_config does. Kept
+--    anyway, because it pins the coalesce ORDER and the pre-existing branch semantics.
+-- ---------------------------------------------------------------------------
+select set_config('request.jwt.claim.sub', '34100000-0000-4000-8000-000000000001', true);
+select set_config('request.jwt.claims', '', true);
+select set_config('request.jwt.claim.agent_credential_id', '', true);
+
+select is(
+  (select agent_board.current_agent_id()),
+  '34100000-0000-4000-8000-000000000010'::uuid,
+  'A1 per-claim transport, no credential claim: resolves the agent (permissive branch)'
+);
+
+select set_config('request.jwt.claim.agent_credential_id', '34100000-0000-4000-8000-000000000100', true);
+select is(
+  (select agent_board.current_agent_id()),
+  '34100000-0000-4000-8000-000000000010'::uuid,
+  'A2 per-claim transport, VALID credential: resolves the agent'
+);
+
+select set_config('request.jwt.claim.agent_credential_id', '34100000-0000-4000-8000-000000000200', true);
+select is(
+  (select agent_board.current_agent_id()),
+  null::uuid,
+  'A3 per-claim transport, REVOKED credential: denies'
+);
+
+-- ---------------------------------------------------------------------------
+-- B. Realtime-shaped context: ONLY the whole-JSON GUC. These are the fix.
+--    Every per-claim GUC is cleared first, so a pass here cannot be produced by
+--    the source that already worked.
+-- ---------------------------------------------------------------------------
+select set_config('request.jwt.claim.sub', '', true);
+select set_config('request.jwt.claim.agent_credential_id', '', true);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  '34100000-0000-4000-8000-000000000010'::uuid,
+  'B1 realtime transport, claims carry no credential key: resolves (permissive branch preserved)'
+);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"34100000-0000-4000-8000-000000000100"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  '34100000-0000-4000-8000-000000000010'::uuid,
+  'B2 realtime transport, VALID credential in claims: resolves (fix does not over-deny)'
+);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"34100000-0000-4000-8000-000000000200"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  null::uuid,
+  'B3 realtime transport, REVOKED credential in claims: denies (the #341 defect)'
+);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"34100000-0000-4000-8000-000000000300"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  null::uuid,
+  'B4 realtime transport, EXPIRED credential in claims: denies'
+);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"99999999-9999-4999-8999-999999999999"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  null::uuid,
+  'B5 realtime transport, credential belonging to no agent: denies'
+);
+
+-- A credential that exists and is valid but belongs to a DIFFERENT agent must not authorize this
+-- one. The nearest principal that should still be refused, rather than a stranger: a stranger is
+-- refused by any check that looks at anything at all.
+insert into auth.users (id, instance_id, aud, role, email, created_at, updated_at)
+values (
+  '34100000-0000-4000-8000-000000000002',
+  '00000000-0000-0000-0000-000000000000',
+  'authenticated', 'authenticated', 'rtcred-other@example.test', now(), now()
+);
+insert into agent_board.agents (id, agent_type, handle, display_name, status, metadata, auth_user_id)
+values (
+  '34100000-0000-4000-8000-000000000020',
+  'agent', 'rtcred-other', 'Other Agent', 'active', '{}'::jsonb,
+  '34100000-0000-4000-8000-000000000002'
+);
+insert into agent_board.agent_credentials
+  (id, agent_id, refresh_token_hash, hash_version, credential_label, expires_at, revoked_at)
+values
+  ('34100000-0000-4000-8000-000000000400', '34100000-0000-4000-8000-000000000020',
+   '\x3414'::bytea, 1, 'other-valid', now() + interval '1 day', null);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"34100000-0000-4000-8000-000000000400"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  null::uuid,
+  'B6 realtime transport, valid credential owned by ANOTHER agent: denies'
+);
+
+-- ---------------------------------------------------------------------------
+-- C. Precedence and shape.
+-- ---------------------------------------------------------------------------
+-- Both sources present: the per-claim value is preferred. Asserted so the coalesce ORDER is
+-- pinned, not merely its membership. A revoked value in the ignored source must not deny.
+select set_config('request.jwt.claim.agent_credential_id', '34100000-0000-4000-8000-000000000100', true);
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"34100000-0000-4000-8000-000000000200"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  '34100000-0000-4000-8000-000000000010'::uuid,
+  'C1 both sources present: per-claim wins over whole-JSON'
+);
+
+-- The function must still be SECURITY DEFINER with a pinned search_path. A recreate that dropped
+-- either would change who it can read and what it resolves, silently.
+select is(
+  (select p.prosecdef 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 = 'current_agent_id'),
+  true,
+  'C2 current_agent_id remains SECURITY DEFINER'
+);
+
+-- ---------------------------------------------------------------------------
+-- E. MALFORMED CLAIM SHAPES MUST DENY, NOT RAISE.
+--
+-- A correctness seat measured that the UUID regex never guarded the cast: `::uuid` is evaluated
+-- at SQL-function startup, before any qual filtering, so a malformed claim raised 22P02 rather
+-- than denying -- on the OLD body too, which is why this migration removes the cast entirely and
+-- compares as text. Every one of these was RED before that change.
+-- ---------------------------------------------------------------------------
+select set_config('request.jwt.claim.agent_credential_id', '', true);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":""}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  '34100000-0000-4000-8000-000000000010'::uuid,
+  'E1 EMPTY-STRING claim is ABSENT on the whole-JSON arm too, matching the per-claim arm'
+);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"bogus"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  null::uuid,
+  'E2 NON-UUID credential claim denies cleanly instead of raising 22P02'
+);
+
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":42}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  null::uuid,
+  'E3 NUMERIC credential claim denies cleanly instead of raising 22P02'
+);
+
+-- Case-insensitivity is load-bearing now that the comparison is text: uuid::text is canonical
+-- LOWERCASE, so an uppercase claim would silently stop matching without lower().
+select set_config(
+  'request.jwt.claims',
+  '{"sub":"34100000-0000-4000-8000-000000000001","role":"authenticated","agent_credential_id":"34100000-0000-4000-8000-000000000100"}',
+  true
+);
+select is(
+  (select agent_board.current_agent_id()),
+  '34100000-0000-4000-8000-000000000010'::uuid,
+  'E4 UPPERCASE credential claim still matches (uuid::text is lowercase; lower() bridges it)'
+);
+
+-- ---------------------------------------------------------------------------
+-- D. THE CLASS. #341 is one site; this asserts it is the ONLY one, and keeps it that way.
+--
+-- A function that reads a per-claim GUC (`request.jwt.claim.<name>`) WITHOUT also reading the
+-- whole-JSON GUC has #341's defect by construction: PostgREST populates the first, Realtime only
+-- the second, so its check silently does not run for subscribers. Catalog-derived, so a NEW
+-- function with that shape fails this and NAMES ITSELF rather than needing anyone to remember.
+--
+-- `keep_literals => true` is REQUIRED and is the trap this repo documents: the GUC name is a
+-- STRING LITERAL, and stripped_body strips literals by default, so the default spelling matches
+-- nothing and the assertion passes vacuously.
+--
+-- Note `request.jwt.claim.` carries a trailing dot, so it does not also match `request.jwt.claims`.
+-- ---------------------------------------------------------------------------
+
+-- Population canary FIRST: an empty "no offenders" result must not be reachable by the class
+-- being empty. If nothing reads a per-claim GUC at all, this file is asserting nothing.
+select cmp_ok(
+  (select count(*)
+     from pg_catalog.pg_proc p
+     join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board'
+      and agent_board_test.stripped_body(p.oid, true) like '%request.jwt.claim.%'),
+  '>=',
+  1::bigint,
+  'D1 population canary: at least one agent_board function reads a per-claim JWT GUC'
+);
+
+select is_empty(
+  $$
+  select p.proname
+    from pg_catalog.pg_proc p
+    join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+   where n.nspname = 'agent_board'
+     and agent_board_test.stripped_body(p.oid, true) like '%request.jwt.claim.%'
+     and agent_board_test.stripped_body(p.oid, true) not like '%request.jwt.claims%'
+  $$,
+  'D2 no agent_board function reads a per-claim JWT GUC without also reading request.jwt.claims'
+);
+
+select finish();
+rollback;