drupal-mcp-connector 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.12.0] - 2026-09-02
+
+### Security
+- **W&L-operated policy-bundle promotion on the relay edge (#253).** Optional
+  `auth.promotions` maps a SHA-256 digest to a sealed portable document plus
+  two distinct operator ids. Eligible documents fan down the tenant-agent
+  channel after hello; the agent presents them to local enforcement
+  (verify / activate / attest). When the table is present, non-diagnostic
+  `tools/call` requires the bound `auth.policies` digest **and** a matching
+  agent attestation. The edge never mints a Sentinel HMAC key. Omitting
+  `auth.promotions` keeps the digest-only path. Lab/loopback only — not
+  tenant self-service or a hosted-service claim.
+
 ## [2.11.0] - 2026-09-02
 
 ### Security
@@ -1380,6 +1393,7 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.12.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.12.0
 [2.11.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.11.0
 [2.10.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.10.1
 [1.0.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v1.0.0

package/bin/drupal-mcp-edge.js

@@ -39,11 +39,14 @@
  * auth.actors (sub / azp -> Drupal user UUID) maps the inbound principal
  * to a Drupal actor for write-like tools. Optional auth.policies
  * (sub / azp -> SHA-256 digest) is the expected signed policy on the edge.
+ * Optional auth.promotions (digest -> sealed document + two operator ids)
+ * is the W&L-operated dual-control ledger; the edge fans eligible bundles
+ * to the tenant agent and requires a matching local attestation.
  */
 
 import { readFileSync } from "node:fs";
 import process from "node:process";
-import { getInboundActors, getInboundGrants, getInboundPolicies, getInboundTenantGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
+import { getInboundActors, getInboundGrants, getInboundPolicies, getInboundPromotions, getInboundTenantGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
 import { resolveInboundAuthConfig } from "../src/lib/http-auth.js";
 import { createRateLimiter } from "../src/lib/rate-limit.js";
 import {
@@ -131,6 +134,7 @@ try {
     tenantGrants: getInboundTenantGrants(),
     actors: getInboundActors(),
     policies: getInboundPolicies(),
+    promotions: getInboundPromotions(),
     sites,
     defaultSite: config.defaultSite,
     channelCredentials: createChannelCredentialStore({ filePath: channelFile }),

package/config/config.example.json

@@ -41,6 +41,9 @@
     "policies": {
       "_comment": "Optional. Map inbound sub or client_id (azp) to a SHA-256 digest of the expected signed Sentinel policy bundle, e.g. \"content-agent\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\". When present, non-diagnostic tools/call without a mapping are not_entitled. Caller policy/digest arguments are never authority. Omit to keep the prior path (no digest required at the edge). Local verify/activate stays on mcp_sentinel."
     },
+    "promotions": {
+      "_comment": "Optional W&L-operated dual-control ledger. Map a SHA-256 digest to { document, approvals } where document is the sealed portable Sentinel bundle (claims + digest + hmac-sha256 seal) and approvals is two distinct operator ids. When present, the edge fans eligible documents to the tenant agent; non-diagnostic tools/call require a matching local attestation. The edge never mints a seal. Omit to keep the digest-only path. Tenant self-service is not this table."
+    },
     "revocationFile": "",
     "introspectionUrl": "",
     "introspectionClientIdEnv": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/config.js

@@ -292,6 +292,22 @@ export function getInboundPolicies() {
   return entries.length ? Object.fromEntries(entries) : null;
 }
 
+/**
+ * W&L-operated dual-control promotion ledger keyed by SHA-256 digest.
+ * When present, the edge fans eligible sealed documents to the tenant agent.
+ * @returns {object|null}
+ */
+export function getInboundPromotions() {
+  const promotions = loadConfig().auth?.promotions;
+  if (!promotions || typeof promotions !== "object" || Array.isArray(promotions)) {
+    return null;
+  }
+  const entries = Object.entries(promotions)
+    .map(([key, value]) => [key.trim(), value])
+    .filter(([key]) => key && !key.startsWith("_"));
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
 // ---------------------------------------------------------------------------
 // Auth headers — never logged, never exposed in tool responses
 // ---------------------------------------------------------------------------

package/src/lib/policy-enforcement.js

@@ -0,0 +1,268 @@
+/**
+ * Tenant-side local policy enforcement (#253 / DEV-125).
+ *
+ * Loopback stand-in for mcp_sentinel `McpPolicyBundleRegistry`: mint / verify
+ * / activate / simulate / revoke / rollback / emergency deny. The relay edge
+ * never receives the signing key and never calls mint. A missing key cannot
+ * mint, verify, or activate — emergency deny still arms a deny floor without
+ * minting new authority.
+ */
+
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { SEAL_PREFIX } from "./policy-promotion.js";
+
+export const POLICY_BUNDLE_VERSION = 1;
+
+export const DEFAULT_BUNDLE_TTL = 86400 * 30;
+
+export const EMERGENCY_DENY = "*";
+
+export const EMERGENCY_DIGEST = "emergency-deny";
+
+function normalize(value) {
+  if (value === null || typeof value === "string" || typeof value === "number"
+    || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(normalize);
+  if (value && typeof value === "object") {
+    const source = new Map(Object.entries(value));
+    const bag = new Map();
+    for (const key of [...source.keys()].sort()) {
+      bag.set(key, normalize(source.get(key)));
+    }
+    return Object.fromEntries(bag);
+  }
+  throw new TypeError("Policy bundle claims may only contain scalars, lists and maps.");
+}
+
+/**
+ * Canonical JSON of claims (HMAC / digest input). Maps are key-sorted;
+ * lists keep caller order. Matches mcp_sentinel `McpPolicyBundle::canonicalJson`.
+ *
+ * @param {object} claims
+ * @returns {string}
+ */
+export function canonicalJson(claims) {
+  return JSON.stringify(normalize(claims));
+}
+
+/**
+ * Hex SHA-256 of the canonical claims.
+ *
+ * @param {object} claims
+ * @returns {string}
+ */
+export function digestOf(claims) {
+  return createHash("sha256").update(canonicalJson(claims)).digest("hex");
+}
+
+function safeEqual(left, right) {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+function deniedOperationsOf(claims) {
+  const denials = new Map(Object.entries(claims ?? {})).get("denials");
+  if (!denials || typeof denials !== "object" || Array.isArray(denials)) return [];
+  const ops = new Map(Object.entries(denials)).get("operations");
+  if (!Array.isArray(ops)) return [];
+  return ops.map(String);
+}
+
+function bundleFrom(claims, digest, seal) {
+  return Object.freeze({
+    claims,
+    digest,
+    seal,
+    version: () => Number(new Map(Object.entries(claims)).get("v") ?? 0),
+    expires: () => Number(new Map(Object.entries(claims)).get("expires") ?? 0),
+    deniedOperations: () => deniedOperationsOf(claims),
+    denies: (operation) => deniedOperationsOf(claims).includes(operation),
+    isExpired: (now) => {
+      const expires = Number(new Map(Object.entries(claims)).get("expires") ?? 0);
+      return expires > 0 && now >= expires;
+    },
+    toArray: () => ({ ...claims, digest, seal }),
+  });
+}
+
+/**
+ * In-process local enforcement used by the tenant agent in the loopback lab.
+ *
+ * @param {object} [options]
+ * @param {string|null} [options.signingKey] HMAC material. Null = disconnected.
+ * @param {() => number} [options.now] Unix seconds.
+ * @returns {object}
+ */
+export function createLocalPolicyEnforcement({
+  signingKey = null,
+  now = () => Math.floor(Date.now() / 1000),
+} = {}) {
+  let active = null;
+  let lastGood = null;
+  const revoked = new Map();
+
+  function canSeal() {
+    return typeof signingKey === "string" && signingKey.length > 0;
+  }
+
+  function isRevoked(digest) {
+    return revoked.has(digest);
+  }
+
+  function mint(deniedOperations = [], ttl = DEFAULT_BUNDLE_TTL) {
+    if (!canSeal()) return null;
+    const issued = now();
+    const unique = [...new Set((Array.isArray(deniedOperations) ? deniedOperations : [])
+      .map(String))];
+    const claims = {
+      denials: { operations: unique },
+      expires: issued + (ttl ?? DEFAULT_BUNDLE_TTL),
+      id: randomUUID(),
+      issued,
+      v: POLICY_BUNDLE_VERSION,
+    };
+    const digest = digestOf(claims);
+    const seal = SEAL_PREFIX + createHmac("sha256", signingKey).update(digest).digest("hex");
+    return bundleFrom(claims, digest, seal);
+  }
+
+  function verify(document) {
+    if (!canSeal()) return null;
+    if (!document || typeof document !== "object" || Array.isArray(document)) return null;
+    const bag = new Map(Object.entries(document));
+    const seal = bag.get("seal");
+    const claimedDigest = bag.get("digest");
+    bag.delete("seal");
+    bag.delete("digest");
+    const claims = Object.fromEntries(bag);
+    if (typeof seal !== "string" || !seal.startsWith(SEAL_PREFIX)) return null;
+    if (Number(new Map(Object.entries(claims)).get("v") ?? 0) !== POLICY_BUNDLE_VERSION) {
+      return null;
+    }
+    const digest = digestOf(claims);
+    if (!safeEqual(digest, typeof claimedDigest === "string" ? claimedDigest : "")) return null;
+    const expected = SEAL_PREFIX
+      + createHmac("sha256", signingKey).update(digest).digest("hex");
+    if (!safeEqual(expected, seal)) return null;
+    const bundle = bundleFrom(claims, digest, seal);
+    if (bundle.isExpired(now())) return null;
+    if (isRevoked(digest)) return null;
+    return bundle;
+  }
+
+  function attestation() {
+    return active;
+  }
+
+  function activeDigest() {
+    const digest = active && typeof active.digest === "string" ? active.digest : null;
+    return digest || null;
+  }
+
+  function emergencyDeny() {
+    if (active && typeof active.digest === "string") lastGood = active;
+    active = {
+      digest: EMERGENCY_DIGEST,
+      activated_at: now(),
+      previous: active && typeof active.digest === "string" ? active.digest : null,
+      emergency: true,
+      bundle: {
+        v: POLICY_BUNDLE_VERSION,
+        denials: { operations: [EMERGENCY_DENY] },
+        expires: 0,
+        id: EMERGENCY_DIGEST,
+        issued: now(),
+      },
+    };
+  }
+
+  function activateBundle(bundle) {
+    if (!canSeal() || !bundle) return null;
+    if (active && typeof active.digest === "string") lastGood = active;
+    const previous = active && typeof active.digest === "string" ? active.digest : null;
+    active = {
+      digest: bundle.digest,
+      activated_at: now(),
+      previous,
+      bundle: bundle.toArray(),
+    };
+    return {
+      digest: bundle.digest,
+      activated_at: active.activated_at,
+      previous,
+    };
+  }
+
+  /**
+   * Verify then activate a portable document. This is the agent hook.
+   *
+   * @param {object} document
+   * @returns {{ok: boolean, digest?: string, attested?: boolean, reason?: string}}
+   */
+  function activate(document) {
+    const bundle = verify(document);
+    if (!bundle) return { ok: false, reason: "unverified" };
+    const result = activateBundle(bundle);
+    if (!result) return { ok: false, reason: "cannot_activate" };
+    return { ok: true, digest: result.digest, attested: true };
+  }
+
+  function simulate(operation, localDenies, candidate = null) {
+    const digest = candidate?.digest ?? activeDigest();
+    if (localDenies) {
+      return { allow: false, reason: "local_deny", digest };
+    }
+    if (candidate === null && active && active.emergency) {
+      return {
+        allow: false,
+        reason: "emergency_deny",
+        digest: digest ?? EMERGENCY_DIGEST,
+      };
+    }
+    let bundle = candidate;
+    if (bundle === null) {
+      const document = active?.bundle ?? null;
+      bundle = document ? verify(document) : null;
+      if (bundle === null && digest) {
+        return { allow: false, reason: "bundle_unverified", digest };
+      }
+    }
+    if (bundle && (bundle.denies(operation) || bundle.denies(EMERGENCY_DENY))) {
+      return { allow: false, reason: "bundle_deny", digest: bundle.digest };
+    }
+    return { allow: true, reason: "allow", digest };
+  }
+
+  function revoke(digest) {
+    if (typeof digest !== "string" || !digest) return;
+    revoked.set(digest, now());
+    if (activeDigest() === digest) emergencyDeny();
+  }
+
+  function rollback() {
+    if (!lastGood || typeof lastGood.digest !== "string") return null;
+    if (isRevoked(lastGood.digest)) return null;
+    active = lastGood;
+    return lastGood;
+  }
+
+  return {
+    canSeal,
+    mint,
+    verify,
+    activate,
+    activateBundle,
+    attestation,
+    activeDigest,
+    simulate,
+    revoke,
+    rollback,
+    emergencyDeny,
+    isRevoked,
+  };
+}

package/src/lib/policy-promotion.js

@@ -0,0 +1,130 @@
+/**
+ * W&L-operated dual-control promotion ledger (#253 / DEV-125).
+ *
+ * The edge never mints a Sentinel HMAC seal. A promotion is an already-sealed
+ * portable document plus two distinct operator ids. Eligibility is the gate
+ * before the tenant agent may receive the artifact. Caller-supplied documents
+ * are never read here.
+ */
+
+export const POLICY_DIGEST = /^[0-9a-f]{64}$/i;
+
+export const SEAL_PREFIX = "hmac-sha256:";
+
+function tableHasKeys(table) {
+  return Object.keys(table).some((key) => {
+    const id = key.trim();
+    return id && !id.startsWith("_");
+  });
+}
+
+function uniqueApprovals(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const value of raw) {
+    const id = String(value).trim();
+    if (!id || id.startsWith("_") || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+function portableDocument(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const bag = new Map(Object.entries(raw));
+  const digest = typeof bag.get("digest") === "string"
+    ? bag.get("digest").trim().toLowerCase()
+    : "";
+  const seal = typeof bag.get("seal") === "string" ? bag.get("seal").trim() : "";
+  if (!POLICY_DIGEST.test(digest)) return null;
+  if (!seal.startsWith(SEAL_PREFIX) || seal.length <= SEAL_PREFIX.length) return null;
+  bag.set("digest", digest);
+  bag.set("seal", seal);
+  return Object.freeze(Object.fromEntries(bag));
+}
+
+/**
+ * Normalize `auth.promotions` (digest → sealed document + approvals).
+ * Comment keys and malformed rows are dropped. Duplicate operator ids in
+ * `approvals` count once. A row is eligible only with two distinct operators
+ * and a document whose claimed digest matches the map key.
+ *
+ * @param {object|null} promotions
+ * @returns {object|null}
+ */
+export function normalizePromotions(promotions) {
+  if (!promotions || typeof promotions !== "object" || Array.isArray(promotions)) {
+    return null;
+  }
+  const entries = [];
+  for (const [rawKey, value] of Object.entries(promotions)) {
+    const key = rawKey.trim().toLowerCase();
+    if (!key || key.startsWith("_") || !POLICY_DIGEST.test(key)) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const bag = new Map(Object.entries(value));
+    const document = portableDocument(bag.get("document"));
+    if (!document || document.digest !== key) continue;
+    const approvals = uniqueApprovals(bag.get("approvals"));
+    entries.push([key, Object.freeze({
+      digest: key,
+      document,
+      approvals: Object.freeze(approvals),
+      eligible: approvals.length >= 2,
+    })]);
+  }
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Whether a promotions table is in force (fail-closed even when every row
+ * is ineligible). Comment-only objects are not in force.
+ *
+ * @param {object|null} promotions
+ * @returns {boolean}
+ */
+export function promotionsRequired(promotions) {
+  if (!promotions || typeof promotions !== "object" || Array.isArray(promotions)) {
+    return false;
+  }
+  return tableHasKeys(promotions);
+}
+
+/**
+ * Eligible sealed documents ready to fan down.
+ *
+ * @param {object|null} promotions
+ * @returns {Array<{digest: string, document: object, approvals: string[]}>}
+ */
+export function eligiblePromotions(promotions) {
+  const table = normalizePromotions(promotions);
+  if (!table) return [];
+  return Object.values(table).filter((row) => row.eligible);
+}
+
+/**
+ * Look up one digest in the ledger.
+ *
+ * @param {object} params
+ * @param {string|null} [params.digest]
+ * @param {object|null} [params.promotions]
+ * @returns {{document: object|null, eligible: boolean, reason: "not_entitled"|null}}
+ */
+export function resolveEligiblePromotion({ digest = null, promotions = null } = {}) {
+  const required = promotionsRequired(promotions);
+  const table = normalizePromotions(promotions);
+  if (!table) {
+    return {
+      document: null,
+      eligible: false,
+      reason: required ? "not_entitled" : null,
+    };
+  }
+  const key = typeof digest === "string" ? digest.trim().toLowerCase() : "";
+  const record = key ? new Map(Object.entries(table)).get(key) : null;
+  if (!record || !record.eligible) {
+    return { document: null, eligible: false, reason: "not_entitled" };
+  }
+  return { document: record.document, eligible: true, reason: null };
+}

package/src/lib/relay/agent.js

@@ -16,6 +16,7 @@
 import { connect as netConnect } from "node:net";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { createConnectorServerFactory } from "../mcp-server.js";
+import { POLICY_DIGEST } from "../policy-promotion.js";
 import { runWithIdentity } from "../principal.js";
 import { attachFramer, forwardHeaders, writeFrame } from "./frames.js";
 
@@ -35,6 +36,9 @@ import { attachFramer, forwardHeaders, writeFrame } from "./frames.js";
  * @param {?() => void} [options.onChannelClose] Called when an established
  *   channel is lost (not on deliberate `drop`/`close`), so an entry point
  *   can fail loudly instead of idling disconnected.
+ * @param {?{activate: Function}} [options.policyEnforcement] Local Sentinel
+ *   hook. `activate(document)` verifies, activates, and attests. Missing
+ *   hook fail-closes a `policy-bundle` frame (no mint on this process).
  * @param {?{recordConnect: Function}} [options.ledger]
  * @returns {object}
  */
@@ -45,6 +49,7 @@ export function createRelayAgent({
   surface,
   connectFn = netConnect,
   onChannelClose = null,
+  policyEnforcement = null,
   ledger = null,
 }) {
   if (!host || !port) {
@@ -63,6 +68,41 @@ export function createRelayAgent({
   let socket = null;
   let agentInfo = null;
 
+  async function presentBundle(activeSocket, frame) {
+    let ok = false;
+    let digest = "";
+    let reason = "no_enforcement";
+    try {
+      if (policyEnforcement && typeof policyEnforcement.activate === "function") {
+        const result = await policyEnforcement.activate(frame.document);
+        const claimed = typeof result?.digest === "string"
+          ? result.digest.trim().toLowerCase()
+          : "";
+        ok = result?.ok === true && POLICY_DIGEST.test(claimed);
+        digest = ok ? claimed : "";
+        reason = ok
+          ? ""
+          : (typeof result?.reason === "string" && result.reason.trim()
+            ? result.reason.trim().slice(0, 64)
+            : "unverified");
+      }
+    } catch {
+      ok = false;
+      digest = "";
+      reason = "activate_failed";
+    }
+    try {
+      writeFrame(activeSocket, {
+        type: "policy-bundle-ack",
+        ok,
+        digest,
+        ...(ok ? {} : { reason }),
+      });
+    } catch {
+      activeSocket.destroy();
+    }
+  }
+
   async function serveFrame(activeSocket, frame) {
     if (frame.type !== "mcp-request") return;
     if (!frame.identity || typeof frame.identity !== "object" || Array.isArray(frame.identity)) {
@@ -138,6 +178,10 @@ export function createRelayAgent({
             resolve({ ok: false, reason: frame.reason });
             return;
           }
+          if (frame.type === "policy-bundle") {
+            void presentBundle(next, frame);
+            return;
+          }
           void serveFrame(next, frame);
         });
         next.on("error", reject);

package/src/lib/relay/edge.js

@@ -1,6 +1,7 @@
 /**
- * Relay northbound edge (#232, #242, #244, #247, #250) — DEV-294 AC4, DEV-122
- * isolation, DEV-124 tenant routing, DEV-123 actor mapping, DEV-125 policy digest.
+ * Relay northbound edge (#232, #242, #244, #247, #250, #253) — DEV-294 AC4,
+ * DEV-122 isolation, DEV-124 tenant routing, DEV-123 actor mapping, DEV-125
+ * policy digest and W&L-operated bundle promotion.
  *
  * Terminates northbound MCP over the OAuth resource server and fans requests
  * down outbound tenant-agent channels. The edge proposes; the tenant-side
@@ -38,6 +39,12 @@ import { createLocalRelay } from "../contracts/relay.js";
 import { createInboundHttpsAuth, SPOOFABLE_IDENTITY_HEADERS } from "../http-auth.js";
 import { createLegacySessionHandler, createMcpRequestHandler } from "../http-handler.js";
 import { isWriteLikeCall } from "../operations.js";
+import {
+  eligiblePromotions,
+  POLICY_DIGEST,
+  promotionsRequired,
+  resolveEligiblePromotion,
+} from "../policy-promotion.js";
 import { DIAGNOSTIC_TOOLS, resolveActor, resolveGrantedSites, resolvePolicy } from "../principal.js";
 import {
   attachFramer,
@@ -469,6 +476,10 @@ function jsonResponse(res, status, body) {
  * @param {object|null} [options.actors] Optional principal → Drupal actor
  *   table (`sub` / `azp` → `{ uuid, delegators? }`). When present, write-like
  *   tools/call require a mapping.
+ * @param {object|null} [options.policies] Optional principal → SHA-256 digest.
+ * @param {object|null} [options.promotions] Optional W&L-operated dual-control
+ *   ledger (digest → sealed document + two operator ids). When present,
+ *   non-diagnostic tools/call require a matching agent attestation.
  * @param {Array<{_name: string}>} options.sites Credential-free catalog.
  * @param {string} [options.defaultSite]
  * @param {{lookup: Function}} options.channelCredentials Agent channel store.
@@ -490,6 +501,7 @@ export async function startEdge({
   tenantGrants = null,
   actors = null,
   policies = null,
+  promotions = null,
   sites,
   defaultSite,
   channelCredentials,
@@ -525,6 +537,10 @@ export async function startEdge({
   const policyTable = policies && typeof policies === "object" && !Array.isArray(policies)
     ? policies
     : null;
+  const promotionTable = promotions && typeof promotions === "object" && !Array.isArray(promotions)
+    ? promotions
+    : null;
+  const promoRequired = promotionsRequired(promotionTable);
   if (typeof channelCredentials?.lookup !== "function") {
     throw new EdgeStartupError(
       "Relay edge requires an agent channel credential store; without one no "
@@ -550,7 +566,7 @@ export async function startEdge({
   const targetRelay = createLocalRelay({ sites: catalog, grants: grantTable, defaultSite });
   const broker = createRequestBroker({ timeoutMs: fanDownTimeoutMs });
 
-  /** @type {Map<string, {socket: object, token: string, agentId: string, sites: string[]|null}>} */
+  /** @type {Map<string, {socket: object, token: string, agentId: string, sites: string[]|null, attestedDigests: Set<string>, offeredDigests: Set<string>}>} */
   const sessions = new Map();
   const catalogNames = catalog.map((site) => site._name);
 
@@ -580,20 +596,47 @@ export async function startEdge({
         const existing = sessions.get(record.agentId);
         if (existing && existing.socket !== socket) existing.socket.destroy();
         agentId = record.agentId;
+        const offeredDigests = new Set();
         sessions.set(agentId, {
           socket,
           token: frame.token,
           agentId,
           sites: decision.sites,
+          attestedDigests: new Set(),
+          offeredDigests,
         });
-        writeFrame(socket, { type: "hello-ok", agent: { agentId } });
+        try {
+          for (const row of eligiblePromotions(promotionTable)) {
+            const wrote = writeFrame(socket, { type: "policy-bundle", document: row.document });
+            if (!wrote) throw new Error("policy-bundle write failed");
+            offeredDigests.add(row.digest);
+          }
+          writeFrame(socket, { type: "hello-ok", agent: { agentId } });
+        } catch {
+          sessions.delete(agentId);
+          agentId = null;
+          socket.destroy();
+        }
         return;
       }
-      if (frame.type === "mcp-response") {
-        if (!agentId) {
-          socket.destroy();
-          return;
+      if (!agentId) {
+        socket.destroy();
+        return;
+      }
+      if (frame.type === "policy-bundle-ack") {
+        const session = sessions.get(agentId);
+        const digest = typeof frame.digest === "string"
+          ? frame.digest.trim().toLowerCase()
+          : "";
+        if (
+          session && frame.ok === true && POLICY_DIGEST.test(digest)
+          && session.offeredDigests.has(digest)
+        ) {
+          session.attestedDigests.add(digest);
         }
+        return;
+      }
+      if (frame.type === "mcp-response") {
         broker.settle(frame, { owner: agentId });
         return;
       }
@@ -649,13 +692,17 @@ export async function startEdge({
       jsonResponse(res, 403, { error: "not_entitled" });
       return;
     }
+    const policyCall = isCall && (!toolName || !DIAGNOSTIC_TOOLS.has(toolName));
     if (
-      boundPolicy.required && boundPolicy.reason && isCall
-      && (!toolName || !DIAGNOSTIC_TOOLS.has(toolName))
+      boundPolicy.required && boundPolicy.reason && policyCall
     ) {
       jsonResponse(res, 403, { error: "not_entitled" });
       return;
     }
+    if (promoRequired && policyCall && !boundPolicy.policy) {
+      jsonResponse(res, 403, { error: "not_entitled" });
+      return;
+    }
 
     const selected = resolveTenantRoute({
       identity,
@@ -665,6 +712,17 @@ export async function startEdge({
       targetName,
       sessions: [...sessions.values()],
     });
+    if (promoRequired && policyCall) {
+      const promo = resolveEligiblePromotion({
+        digest: boundPolicy.policy,
+        promotions: promotionTable,
+      });
+      const attested = selected.session?.attestedDigests;
+      if (!promo.eligible || !attested || !attested.has(boundPolicy.policy)) {
+        jsonResponse(res, 403, { error: "not_entitled" });
+        return;
+      }
+    }
     if (!selected.session) {
       const entitled = selected.reason === "not_entitled";
       jsonResponse(res, entitled ? 403 : 503, {

package/src/lib/relay/frames.js

@@ -21,6 +21,8 @@ export const FRAME_TYPES = Object.freeze([
   "denied",
   "mcp-request",
   "mcp-response",
+  "policy-bundle",
+  "policy-bundle-ack",
 ]);
 
 const FRAME_TYPE_SET = new Set(FRAME_TYPES);