drupal-mcp-connector 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.8.0",
+  "version": "2.9.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/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([]),
+  });
+}