drupal-mcp-connector 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -7,6 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.10.0] - 2026-08-27
+
+### Security
+- **Lab fan-down strips caller credential headers (#229).** The
+  outbound-relay lab harness framed the northbound request's headers down
+  the tenant tunnel verbatim, including `Authorization` — invisible in the
+  lab (the stub is in-process and the lab northbound carries no bearer),
+  but the wrong pattern for anyone wiring the README's optional live hop.
+  `Authorization`, `Cookie`, and `Proxy-Authorization` are now stripped,
+  with hop-by-hop headers, before framing; a test asserts marker
+  credentials never appear in any frame crossing the tunnel. The lab
+  README now states plainly that the lab northbound does not authenticate
+  the caller (the lab credential authenticates the agent channel) — the
+  product edge's northbound OAuth is DEV-294 work, not this harness.
+
+### Added
+- **Deployment documentation for the relay edge and tenant-agent entry
+  points (#232).** `docs/deployment.md` gains the outbound-path section:
+  startup requirements, credential-header stripping, channel credentials,
+  and the issuer claim requirements.
+- **Relay edge and tenant-agent entry points (#232).** `drupal-mcp-edge`
+  terminates northbound MCP on the inbound OAuth resource server — the only
+  authentication arm on this entry point; a missing issuer/audience is fatal
+  at any bind host, including loopback — and fans requests down an outbound
+  tenant channel. The edge requires a non-empty `auth.grants` table and an
+  agent channel credential store to start, resolves the authoritative target
+  per request before fan-down, strips caller credential and
+  identity-assertion headers before framing (the frame carries the validated
+  identity object only), and holds no site credentials — a catalog entry
+  carrying credential material refuses startup. `drupal-mcp-agent` dials out
+  (it never listens), authenticates the channel with its own issued,
+  revocable credential, and serves the real connector tool surface, so site
+  credentials exist only in the tenant process. Northbound is stateless MCP
+  2026-07-28 with no session ids in either direction; revocation of both the
+  northbound principal and the agent channel is per-request with no grace
+  window. The frame codec lives at `src/lib/relay/frames.js` with hard size,
+  teardown, and timeout bounds. These are entry points and libraries only;
+  nothing here is a hosted service.
+- **Lab-only outbound-relay harness (DEV-293).** Isolated under
+  `lab/outbound-relay/` with tests in `tests/lab/`. A tenant agent dials out
+  to a loopback relay; one MCP 2026-07-28 Streamable-HTTP request (stateless,
+  no `Mcp-Session-Id`) reaches an in-process stub private Drupal; reconnect
+  keeps the same tunnel identity; revocation is checked per request (next
+  request denied, no grace window). This is not a public surface, not a
+  hosted-service claim, and not DEV-294. Hosted MCP is unstarted.
+
+## [2.9.0] - 2026-08-26
+
+### Fixed
+- **Adapter-contract execute trusts a fresh evaluation (#181).**
+  Manifest digests are always hashed (caller-supplied digests are ignored).
+  `execute` re-evaluates and will not honor a forged allow. Actor-bound
+  approvals cannot be consumed without that actor. Vendor keys are rejected
+  on `hints`. `propose` and `policyDigest` use the same relay hint keys as
+  evaluate. A required-evidence failure after a backend write rolls the
+  mutation back. `publish` with an id updates that entity instead of
+  creating a duplicate.
+
+### Added
+- **Provider-neutral adapter contracts and a Drupal conformance kit (#181).**
+  Versioned evaluator, relay, approval, evidence-sink, and system-of-record
+  contracts live at `src/lib/contracts/` (contract 1.0). Typed decisions
+  (`deny` / `allow` / `allow_with_obligations` / `require_approval`), stable
+  reason codes, obligations, and execution receipts are verified at that
+  seam. Final target-side denial stays authoritative: an upstream allow
+  cannot widen local policy. Model and agent vendors are outside the
+  contract. The Drupal adapter is the only system-of-record implementation;
+  JSON:API and GraphQL remain transport adapters. The offline conformance
+  kit covers allowed and denied actions, hostile input, tenant escape,
+  required-evidence write failure, replay, and post-condition discrepancy.
+  See [docs/adapter-contracts.md](docs/adapter-contracts.md).
+
 ## [2.8.0] - 2026-08-25
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 
 Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
-**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.4** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
+**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to the current release (2.6.1 first fixed this), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
 
 ---
 
@@ -308,6 +308,7 @@ an operator channel: keep the agent's credentials off it, and pin
 | [Threat Model](docs/threat-model.md) | Trust boundaries, threats & mitigations, residual risks, and the security-pass results |
 | [Deployment](docs/deployment.md) | Run the HTTPS transport in production: Docker, systemd, launchd, reverse proxy, pre-exposure checklist |
 | [Integration Contract](docs/integration-contract.md) | The connector ↔ Drupal-governance contract (identity, OAuth scopes, compatibility) |
+| [Adapter Contracts](docs/adapter-contracts.md) | Provider-neutral evaluator / relay / approval / evidence / SoR contracts and the Drupal conformance kit |
 | [Versioning & Stability](docs/versioning.md) | Semver policy: the stable surface, deprecation process, MCP protocol + Node support |
 | [Whitepaper](docs/whitepaper.md) | Vision, personas, and use cases |
 

package/bin/drupal-mcp-agent.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * drupal-mcp-agent — relay tenant agent entry point (#232).
+ *
+ * Dials OUT to the relay edge's agent channel and serves the real connector
+ * server (the full governed tool surface, dispatched through the same
+ * middleware as every other transport) over the framed tunnel. This process
+ * never listens: southbound site credentials exist only here, tenant-side.
+ * The channel is authenticated with the agent's own issued, revocable
+ * credential — never a northbound token, never a site credential.
+ *
+ * Environment variables:
+ *   MCP_EDGE_HOST         Relay edge host. Required.
+ *   MCP_EDGE_AGENT_PORT   Relay edge agent-channel port. Required.
+ *   MCP_CHANNEL_TOKEN     Issued channel credential (or MCP_CHANNEL_TOKEN_FILE).
+ *                         Required. The edge stores only its SHA-256 digest.
+ *   MCP_EDGE_ALLOW_TCP    "1" permits a plain TCP channel to loopback only
+ *                         (dev). The default channel is TLS.
+ *
+ * On a lost channel the process exits non-zero — fail loudly and let the
+ * supervisor restart it rather than idling disconnected.
+ */
+
+import { readFileSync } from "node:fs";
+import { connect as netConnect } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+import process from "node:process";
+import { CLIENT_VERSION, listSiteNames, loadConfig } from "../src/lib/config.js";
+import { callTool, listResolvableSiteConfigs } from "../src/lib/dispatch.js";
+import { filterDiscoverableTools } from "../src/lib/governance.js";
+import {
+  loadLocalSecrets,
+  secretLoadFatalMessage,
+  secretTableMismatchMessage,
+} from "../src/lib/load-secrets.js";
+import {
+  filterPromptsByPrincipal,
+  filterResourcesByPrincipal,
+  filterToolsByPrincipal,
+  getRequestIdentity,
+  visibleSiteTargets,
+} from "../src/lib/principal.js";
+import { createRelayAgent } from "../src/lib/relay/agent.js";
+import { buildToolPrompts, getToolPromptMessages } from "../src/lib/tool-prompts.js";
+import { allDefinitions, definitionsByName } from "../src/tools/index.js";
+
+function fatal(message) {
+  console.error(`[drupal-mcp-agent] FATAL: ${message}`);
+  process.exit(1);
+}
+
+const host = process.env.MCP_EDGE_HOST || "";
+const port = Number(process.env.MCP_EDGE_AGENT_PORT || 0);
+if (!host || !port) {
+  fatal("Set MCP_EDGE_HOST and MCP_EDGE_AGENT_PORT to the relay edge's agent channel.");
+}
+
+const tokenFile = process.env.MCP_CHANNEL_TOKEN_FILE || "";
+const token = process.env.MCP_CHANNEL_TOKEN
+  // eslint-disable-next-line security/detect-non-literal-fs-filename -- credential path comes from the operator's environment, not user input
+  || (tokenFile ? readFileSync(tokenFile, "utf8").trim() : "");
+if (!token) {
+  fatal(
+    "The tenant agent requires its issued channel credential: set "
+    + "MCP_CHANNEL_TOKEN or MCP_CHANNEL_TOKEN_FILE.",
+  );
+}
+
+// Apply config/secrets.map before any site resolution, exactly like the
+// primary entry point: this process is where site credentials live.
+const secretLoad = loadLocalSecrets();
+const secretFatal = secretLoadFatalMessage(secretLoad);
+if (secretFatal) fatal(secretFatal);
+const secretMismatch = secretTableMismatchMessage(secretLoad);
+if (secretMismatch) {
+  console.error(`[drupal-mcp-agent] WARNING: ${secretMismatch}`);
+} else if (secretLoad.unset.length) {
+  console.error(
+    "[drupal-mcp-agent] WARNING: config.json names secret env vars that are unset: "
+    + `${secretLoad.unset.join(", ")}. Those sites will fail closed.`,
+  );
+}
+
+try {
+  loadConfig();
+} catch (error) {
+  fatal(error instanceof Error ? error.message : "configuration load failed");
+}
+
+// ---------------------------------------------------------------------------
+// Connector surface — the real governed tool surface. Workflow prompts and
+// the templated resources stay on the primary entry point; the governed
+// surface here is tools (full), the sites resource, and per-tool prompts.
+// ---------------------------------------------------------------------------
+
+const RESOURCES = [{
+  uri: "drupal://sites",
+  name: "Configured Drupal Sites",
+  description: "All named Drupal site profiles (no credentials).",
+  mimeType: "application/json",
+}];
+
+const TOOL_PROMPTS = buildToolPrompts(allDefinitions);
+
+async function discoverableTools() {
+  const sites = listResolvableSiteConfigs();
+  const identity = getRequestIdentity();
+  const governed = await filterDiscoverableTools(allDefinitions, sites);
+  return filterToolsByPrincipal(governed, sites, identity);
+}
+
+const surface = {
+  serverInfo: { name: "drupal-mcp-connector", version: CLIENT_VERSION },
+  tools: {
+    definitions: allDefinitions,
+    list: discoverableTools,
+    call: callTool,
+  },
+  resources: {
+    definitions: RESOURCES,
+    list: async () => {
+      const sites = listResolvableSiteConfigs();
+      return filterResourcesByPrincipal(RESOURCES, getRequestIdentity(), sites);
+    },
+    read: async (uri) => {
+      if (uri === "drupal://sites") {
+        return visibleSiteTargets(
+          getRequestIdentity(),
+          listResolvableSiteConfigs(),
+          listSiteNames(),
+        );
+      }
+      throw new Error(`Unknown resource URI: ${uri}`);
+    },
+  },
+  prompts: {
+    definitions: TOOL_PROMPTS,
+    list: async () => {
+      const identity = getRequestIdentity();
+      const tools = await discoverableTools();
+      return filterPromptsByPrincipal(TOOL_PROMPTS, identity, tools);
+    },
+    get: (name, args) => getToolPromptMessages(name, args, definitionsByName),
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Channel — TLS by default; plain TCP only to loopback, by explicit opt-in.
+// ---------------------------------------------------------------------------
+
+const allowTcp = process.env.MCP_EDGE_ALLOW_TCP === "1";
+const isLoopbackEdge = host === "127.0.0.1" || host === "::1" || host === "localhost";
+let connectFn;
+if (allowTcp) {
+  if (!isLoopbackEdge) {
+    fatal("MCP_EDGE_ALLOW_TCP permits a plain channel to loopback only. Use TLS.");
+  }
+  connectFn = netConnect;
+} else {
+  connectFn = (options, onConnect) =>
+    tlsConnect({ ...options, servername: host }, onConnect);
+}
+
+const agent = createRelayAgent({
+  host,
+  port,
+  token,
+  surface,
+  connectFn,
+  onChannelClose: () => {
+    fatal("The channel to the relay edge was lost. Exiting for a supervised restart.");
+  },
+});
+
+let hello;
+try {
+  hello = await agent.dial();
+} catch (error) {
+  fatal(`Could not dial the relay edge at ${host}:${port}: `
+    + `${error instanceof Error ? error.message : "unknown error"}`);
+}
+if (!hello.ok) {
+  fatal(`The relay edge denied the channel credential (${hello.reason}).`);
+}
+
+console.error(
+  `[drupal-mcp-agent v${CLIENT_VERSION}] Outbound channel to ${host}:${port} `
+  + `established as "${hello.agent?.agentId ?? "unknown"}" · `
+  + `${allDefinitions.length} tools · ${RESOURCES.length} resources · `
+  + `${TOOL_PROMPTS.length} prompts`,
+);

package/bin/drupal-mcp-edge.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * drupal-mcp-edge — relay northbound edge entry point (#232).
+ *
+ * Terminates northbound MCP on the inbound OAuth resource server and fans
+ * requests down the outbound tenant-agent channel (see src/lib/relay/edge.js).
+ * There is no shared-bearer and no unauthenticated mode on this entry point:
+ * MCP_AUTH_TOKEN and MCP_ALLOW_UNAUTHENTICATED are ignored, and a missing
+ * issuer/audience is fatal at every bind host including loopback. The edge
+ * holds no site credentials; its site catalog is names and base URLs only.
+ *
+ * Environment variables:
+ *   MCP_RESOURCE_ISSUER / MCP_RESOURCE_AUDIENCE / MCP_RESOURCE
+ *                     Inbound OAuth resource server (or config auth.issuer /
+ *                     auth.audience / auth.resource). Required.
+ *   MCP_CHANNEL_CREDENTIALS_FILE
+ *                     Agent channel credential store (or config
+ *                     relay.channelCredentialsFile). Required. JSON:
+ *                     {"agents": {"<id>": {"tokenSha256": "<hex>"}}}
+ *   MCP_EDGE_PORT     Northbound port (default: MCP_PORT / config tls.port).
+ *   MCP_EDGE_AGENT_PORT
+ *                     Agent channel port (default: northbound port + 1).
+ *   MCP_BIND_HOST     Northbound bind when TLS is present (default 0.0.0.0).
+ *   MCP_EDGE_AGENT_BIND_HOST
+ *                     Agent channel bind (default: the northbound bind).
+ *   TLS_CERT_PATH / TLS_KEY_PATH
+ *                     TLS material for both listeners.
+ *   MCP_ALLOW_HTTP    "1" permits plain loopback listeners (dev only).
+ *   MCP_RATE_LIMIT / MCP_RATE_WINDOW_SEC
+ *                     Northbound /mcp rate limit (same defaults as the
+ *                     primary entry point).
+ *
+ * Config: auth.grants (client id -> [site names]) is mandatory; the edge
+ * refuses to start without it.
+ */
+
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import { getInboundGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
+import { resolveInboundAuthConfig } from "../src/lib/http-auth.js";
+import { createRateLimiter } from "../src/lib/rate-limit.js";
+import {
+  createChannelCredentialStore,
+  startEdge,
+} from "../src/lib/relay/edge.js";
+
+function fatal(message) {
+  console.error(`[drupal-mcp-edge] FATAL: ${message}`);
+  process.exit(1);
+}
+
+let config;
+try {
+  config = loadConfig();
+} catch (error) {
+  fatal(error instanceof Error ? error.message : "configuration load failed");
+}
+
+const inboundCfg = resolveInboundAuthConfig(config);
+if (!inboundCfg.issuer || !inboundCfg.audience) {
+  fatal(
+    "The relay edge requires an inbound OAuth resource server: set auth.issuer and "
+    + "auth.audience (or MCP_RESOURCE_ISSUER / MCP_RESOURCE_AUDIENCE). There is no "
+    + "shared-bearer or unauthenticated mode on this entry point, at any bind host "
+    + "including loopback.",
+  );
+}
+
+const grants = getInboundGrants();
+if (!grants) {
+  fatal(
+    "The relay edge refuses to start without a non-empty auth.grants table "
+    + "(client id -> [site names]).",
+  );
+}
+
+const channelFile = process.env.MCP_CHANNEL_CREDENTIALS_FILE
+  || config.relay?.channelCredentialsFile
+  || "";
+if (!channelFile) {
+  fatal(
+    "The relay edge requires an agent channel credential store: set "
+    + "MCP_CHANNEL_CREDENTIALS_FILE (or relay.channelCredentialsFile).",
+  );
+}
+
+// The catalog is passed as configured; startEdge refuses any entry carrying
+// credential material, so a tenant config deployed to an edge host fails
+// closed instead of quietly holding site secrets.
+const sites = Object.entries(config.sites ?? {})
+  .map(([name, site]) => ({ _name: name, ...site }));
+
+const tlsCfg = getTlsConfig();
+let tls = null;
+if (tlsCfg.certPath && tlsCfg.keyPath) {
+  tls = {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- TLS cert/key path comes from operator-controlled config, not user input
+    cert: readFileSync(tlsCfg.certPath),
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- TLS cert/key path comes from operator-controlled config, not user input
+    key: readFileSync(tlsCfg.keyPath),
+  };
+}
+const allowHttp = process.env.MCP_ALLOW_HTTP === "1";
+const bindHost = tls ? (process.env.MCP_BIND_HOST || "0.0.0.0") : "127.0.0.1";
+const agentBindHost = process.env.MCP_EDGE_AGENT_BIND_HOST || bindHost;
+const isLoopbackBind = bindHost === "127.0.0.1" || bindHost === "::1" || bindHost === "localhost";
+
+const port = Number(process.env.MCP_EDGE_PORT || tlsCfg.port);
+const agentPort = Number(process.env.MCP_EDGE_AGENT_PORT || port + 1);
+
+// Northbound rate limiting, same defaults as the primary entry point (#141).
+const rateWindowSec = Number(process.env.MCP_RATE_WINDOW_SEC || 60);
+const rateLimitEnv = process.env.MCP_RATE_LIMIT;
+const rateLimitDefault = (tls && !isLoopbackBind) ? 120 : 0;
+const rateLimit = rateLimitEnv === undefined || rateLimitEnv === ""
+  ? rateLimitDefault
+  : Number(rateLimitEnv);
+
+let edge;
+try {
+  edge = await startEdge({
+    auth: inboundCfg,
+    grants,
+    sites,
+    defaultSite: config.defaultSite,
+    channelCredentials: createChannelCredentialStore({ filePath: channelFile }),
+    bindHost,
+    agentBindHost,
+    port,
+    agentPort,
+    tls,
+    allowHttpLoopback: allowHttp,
+    rateLimiter: rateLimit > 0
+      ? createRateLimiter({ limit: rateLimit, windowMs: rateWindowSec * 1000 })
+      : null,
+  });
+} catch (error) {
+  fatal(error instanceof Error ? error.message : "edge startup failed");
+}
+
+console.error(
+  `[drupal-mcp-edge] Northbound ${edge.northboundUrl} · `
+  + `agent channel ${agentBindHost}:${edge.agentPort} · `
+  + `issuer ${inboundCfg.issuer}`,
+);
+if (rateLimit > 0) {
+  console.error(
+    `[drupal-mcp-edge] Rate limiting: ${rateLimit} req / ${rateWindowSec}s per client IP on /mcp.`,
+  );
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.8.0",
+  "version": "2.10.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",
   "bin": {
     "drupal-mcp-connector": "src/index.js",
-    "drupal-mcp-verify": "bin/drupal-mcp-verify.js"
+    "drupal-mcp-verify": "bin/drupal-mcp-verify.js",
+    "drupal-mcp-edge": "bin/drupal-mcp-edge.js",
+    "drupal-mcp-agent": "bin/drupal-mcp-agent.js"
   },
   "files": [
     "src/",

package/src/lib/contracts/approval.js

@@ -0,0 +1,72 @@
+/**
+ * Approval-interface contract (#181).
+ *
+ * An approval binds to an action-manifest digest and a single actor. It is
+ * one-use. Replay, digest mismatch, or actor mismatch invalidate it.
+ */
+
+import { randomUUID } from "node:crypto";
+import { ContractError, REASON } from "./decisions.js";
+
+/**
+ * @typedef {Object} ApprovalInterface
+ * @property {(manifest: object, actor?: string) => {approvalId: string, digest: string}} issue
+ * @property {(approvalId: string, digest: string, actor?: string) => {approvalId: string, digest: string}} consume
+ */
+
+/**
+ * In-process one-use approval ledger.
+ * @returns {ApprovalInterface & {size: () => number}}
+ */
+export function createMemoryApproval() {
+  const store = new Map();
+
+  return Object.freeze({
+    /**
+     * @param {object} manifest
+     * @param {string} [actor]
+     * @returns {{approvalId: string, digest: string}}
+     */
+    issue(manifest, actor) {
+      if (!manifest?.digest) {
+        throw new ContractError("Approval requires a manifest digest.", REASON.APPROVAL_REQUIRED);
+      }
+      const approvalId = randomUUID();
+      store.set(approvalId, {
+        digest: manifest.digest,
+        actor: actor ?? null,
+        used: false,
+      });
+      return { approvalId, digest: manifest.digest };
+    },
+
+    /**
+     * @param {string} approvalId
+     * @param {string} digest
+     * @param {string} [actor]
+     * @returns {{approvalId: string, digest: string}}
+     */
+    consume(approvalId, digest, actor) {
+      if (!approvalId) {
+        throw new ContractError("Approval required.", REASON.APPROVAL_REQUIRED);
+      }
+      const entry = store.get(approvalId);
+      if (!entry || entry.used) {
+        throw new ContractError("Approval already used or unknown.", REASON.REPLAY);
+      }
+      if (entry.digest !== digest) {
+        throw new ContractError("Approval digest mismatch.", REASON.REPLAY);
+      }
+      if (entry.actor && entry.actor !== actor) {
+        throw new ContractError("Approval actor mismatch.", REASON.REPLAY);
+      }
+      store.set(approvalId, { ...entry, used: true });
+      return { approvalId, digest };
+    },
+
+    /** @returns {number} */
+    size() {
+      return store.size;
+    },
+  });
+}

package/src/lib/contracts/decisions.js

@@ -0,0 +1,139 @@
+/**
+ * Typed decisions, stable reason codes, and the narrowing compose rule (#181).
+ *
+ * An upstream allow cannot widen a local or target deny. Obligations union
+ * only when both sides allow. Model and agent vendor keys are not part of
+ * any contract record.
+ */
+
+/** Stable contract-level reason codes. Do not invent a parallel set. */
+export const REASON = Object.freeze({
+  POLICY_DENIED: "policy_denied",
+  TARGET_DENIED: "target_denied",
+  TENANT_ESCAPE: "tenant_escape",
+  HOSTILE_INPUT: "hostile_input",
+  EVIDENCE_WRITE_FAILED: "evidence_write_failed",
+  REPLAY: "replay_detected",
+  POSTCONDITION: "postcondition_discrepancy",
+  APPROVAL_REQUIRED: "approval_required",
+  INCOMPATIBLE_CONTRACT: "incompatible_contract_version",
+  VENDOR_FIELD: "vendor_field_rejected",
+});
+
+/** Keys that name a model or agent vendor. They stay outside the contract. */
+export const VENDOR_FIELD_NAMES = Object.freeze([
+  "model",
+  "modelVendor",
+  "agentVendor",
+  "agentFramework",
+  "llmProvider",
+  "openai",
+  "anthropic",
+  "vendor",
+]);
+
+const VENDOR_FIELD_SET = new Set(VENDOR_FIELD_NAMES);
+
+/**
+ * Decision / proposal error that carries a stable reason code.
+ */
+export class ContractError extends Error {
+  /**
+   * @param {string} message Operator-facing description (no secrets).
+   * @param {string} reason Stable machine reason.
+   */
+  constructor(message, reason) {
+    super(message);
+    this.name = "ContractError";
+    this.reason = reason;
+  }
+}
+
+/**
+ * Reject records that carry a model or agent vendor key.
+ *
+ * @param {object} record Candidate identity, proposal, or manifest.
+ * @returns {void}
+ * @throws {ContractError}
+ */
+export function assertNoVendorFields(record) {
+  if (record === null || typeof record !== "object" || Array.isArray(record)) {
+    return;
+  }
+  const keys = Object.keys(record);
+  for (const key of keys) {
+    if (VENDOR_FIELD_SET.has(key)) {
+      throw new ContractError(
+        "Model and agent vendor fields are outside the adapter contract.",
+        REASON.VENDOR_FIELD,
+      );
+    }
+  }
+}
+
+/**
+ * @param {Array<{type: string, value?: string}>} left
+ * @param {Array<{type: string, value?: string}>} right
+ * @returns {Array<{type: string, value?: string}>}
+ */
+export function unionObligations(left = [], right = []) {
+  const seen = new Set();
+  const out = [];
+  for (const item of [...left, ...right]) {
+    if (!item || typeof item.type !== "string") continue;
+    const key = `${item.type}:${item.value ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(Object.freeze({ type: item.type, value: item.value }));
+  }
+  return out;
+}
+
+const RESULT_RANK = new Map([
+  ["deny", 0],
+  ["require_approval", 1],
+  ["allow_with_obligations", 2],
+  ["allow", 3],
+]);
+
+/**
+ * Compose an optional upstream decision with the local / target decision.
+ * Local deny is authoritative. Upstream allow never widens a local deny.
+ *
+ * @param {object|null|undefined} upstream Upstream evaluator decision.
+ * @param {object} local Local / target-side decision.
+ * @returns {object} Frozen composed decision.
+ */
+export function composeDecisions(upstream, local) {
+  if (!upstream) return local;
+  if (local.result === "deny") return local;
+  if (upstream.result === "deny") return upstream;
+
+  const localRank = RESULT_RANK.get(local.result) ?? 0;
+  const upstreamRank = RESULT_RANK.get(upstream.result) ?? 0;
+  const narrower = localRank <= upstreamRank ? local : upstream;
+  const obligations = unionObligations(upstream.obligations, local.obligations);
+
+  if (narrower.result === "require_approval") {
+    return Object.freeze({
+      ...narrower,
+      result: "require_approval",
+      obligations: Object.freeze(obligations),
+    });
+  }
+
+  if (obligations.length > 0 || narrower.result === "allow_with_obligations") {
+    return Object.freeze({
+      ...local,
+      result: "allow_with_obligations",
+      reason: local.reason,
+      obligations: Object.freeze(obligations),
+    });
+  }
+
+  return Object.freeze({
+    ...local,
+    result: "allow",
+    obligations: Object.freeze([]),
+  });
+}