drupal-mcp-connector 2.13.1 → 2.14.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.14.0] - 2026-09-06
+
+### Added
+- **Laboratory tenant offboarding on the relay edge (#267).**
+  `offboardTenant` fail-closes unless a tenant-scoped assessor snapshot
+  can be taken, then overwrite-removes the channel digest, drops the
+  grant and session, and tombstones the principal. Revoke and destroy
+  rows are independently anchored only after that teardown succeeds.
+  `GET /assessor` cites P9.9 only when those anchored rows match the
+  digest frozen at export. The held pack stays independently verifiable
+  after access is removed. A former principal sees `offboarded`; a
+  stranger stays `not_entitled`. The pack never writes `passed`.
+  Lab/loopback only — not a hosted-service or design-partner admission
+  claim.
+- **Laboratory tenant onboarding on the relay edge (#265).** Optional
+  `auth.approvalRequiredTools` issues a one-use approval before fan-down
+  for named tools; a later `tools/call` with `arguments.approvalId`
+  consumes it (stripped before the tenant sees it). `GET /assessor` cites
+  P9.8 when one tenant pack holds anchored allow, deny, and
+  approval-gated executions against the live policy digest. Omit the
+  list to keep the prior path. A table the edge cannot read refuses
+  startup. Lab/loopback only — not a hosted-service or design-partner
+  admission claim.
+
+### Security
+- **Independently verifiable evidence on the relay edge (#261).** Optional
+  `auth.evidenceAnchor` (`url` + pinned Ed25519 `publicKey`) submits a
+  minimized receipt digest to a notary process (`drupal-mcp-anchor`) whose
+  private key the edge never holds. One governed execution reconciles by
+  stable identifiers (identity, delegation, decision, obligations,
+  approval, local execution, target revision, receipt — explicit `none:*`
+  absences count). `GET /assessor` serves the caller's own tenant pack:
+  data-minimized, bound to the live policy digest, controls cite evidence
+  ids or stay `residual`, never `passed`. A table the edge cannot pin, or
+  a ledger without a pin, refuses startup. Omitting the table keeps the
+  2.13.0 path (`/assessor` is 404). Lab/loopback only — not a hosted-service
+  or design-partner admission claim. Audit Chain NDJSON remains the
+  off-system stream, not this anchor.
+
 ## [2.13.1] - 2026-09-05
 
 ### Fixed
@@ -1431,6 +1470,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.14.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.0
 [2.13.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.1
 [2.13.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.0
 [2.12.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.12.0

package/bin/drupal-mcp-anchor.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * drupal-mcp-anchor — independent Ed25519 notary (#261).
+ *
+ * Separate process from the relay edge. Holds the private key and never
+ * shares it. Prints the public pin the edge must configure in
+ * `auth.evidenceAnchor.publicKey`. Loopback only. Not a hosted-service
+ * or design-partner admission claim. Audit Chain NDJSON is the off-system
+ * stream, not this process.
+ *
+ * Environment variables:
+ *   MCP_ANCHOR_PORT   Listen port (default 0 = ephemeral; printed).
+ *   MCP_ANCHOR_BIND   Bind host (default 127.0.0.1). Non-loopback refused.
+ */
+
+import process from "node:process";
+import { createNotary, startAnchorServer } from "../src/lib/anchor.js";
+
+function fatal(message) {
+  console.error(`[drupal-mcp-anchor] FATAL: ${message}`);
+  process.exit(1);
+}
+
+const bindHost = process.env.MCP_ANCHOR_BIND || "127.0.0.1";
+const loopback = bindHost === "127.0.0.1" || bindHost === "::1" || bindHost === "localhost";
+if (!loopback) {
+  fatal(
+    "The notary binds loopback only. Set MCP_ANCHOR_BIND to 127.0.0.1 "
+    + "(or omit it). A separately administered production host is not chosen here.",
+  );
+}
+
+const portRaw = process.env.MCP_ANCHOR_PORT;
+const port = portRaw === undefined || portRaw === "" ? 0 : Number(portRaw);
+if (!Number.isInteger(port) || port < 0) {
+  fatal("MCP_ANCHOR_PORT must be a non-negative integer (0 = ephemeral).");
+}
+
+const notary = createNotary();
+const server = await startAnchorServer({ notary, bindHost, port });
+
+console.error(
+  `[drupal-mcp-anchor] Listening ${server.url} · keyId ${notary.keyId}`,
+);
+console.error("[drupal-mcp-anchor] Pin this public key on the edge (auth.evidenceAnchor.publicKey):");
+console.error(notary.publicPin);
+
+function shutdown() {
+  server.close().then(() => process.exit(0), () => process.exit(1));
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/bin/drupal-mcp-edge.js

@@ -51,13 +51,21 @@
  * to the tenant agent and requires a matching local attestation. Optional
  * auth.quotas (tenant / principal request windows plus an abuse lock)
  * fails closed at the edge with zero frames on any refusal; a table the
- * edge cannot read refuses startup.
+ * edge cannot read refuses startup. Optional auth.evidenceAnchor
+ * ({ url, publicKey }) pins an independent Ed25519 notary; GET /assessor
+ * then serves one tenant-scoped pack bound to the live policy digest. A
+ * pin the edge cannot read refuses startup. Omit to keep the prior path
+ * (404 on /assessor). Optional auth.approvalRequiredTools issues a
+ * one-use approval before fan-down for named tools. Lab/loopback only —
+ * not a hosted-service claim.
  */
 
 import { readFileSync } from "node:fs";
 import process from "node:process";
 import {
   getInboundActors,
+  getInboundApprovalRequiredTools,
+  getInboundEvidenceAnchor,
   getInboundGrants,
   getInboundPolicies,
   getInboundPromotions,
@@ -168,6 +176,7 @@ if (usageRaw !== undefined && usageRaw !== null) {
 }
 const usage = usageMaxRecords > 0 ? createUsageLedger({ maxRecords: usageMaxRecords }) : null;
 const quotas = getInboundQuotas();
+const evidenceAnchor = getInboundEvidenceAnchor();
 
 let edge;
 try {
@@ -180,6 +189,8 @@ try {
     promotions: getInboundPromotions(),
     quotas,
     usage,
+    evidenceAnchor,
+    approvalRequiredTools: getInboundApprovalRequiredTools(),
     sites,
     defaultSite: config.defaultSite,
     channelCredentials: createChannelCredentialStore({ filePath: channelFile }),
@@ -215,3 +226,8 @@ if (usage) {
 if (quotas) {
   console.error("[drupal-mcp-edge] Quotas: auth.quotas in force; unlisted tenants / principals are refused.");
 }
+if (evidenceAnchor) {
+  console.error(
+    "[drupal-mcp-edge] Evidence: independent notary pin in force; GET /assessor serves one tenant pack.",
+  );
+}

package/config/config.example.json

@@ -47,6 +47,12 @@
     "quotas": {
       "_comment": "Optional, drupal-mcp-edge only. { tenants: { \"<agent id>\": { requests, windowSec } }, principals: { \"<sub or client_id>\": { requests, windowSec } }, abuse: { denials, windowSec, lockSec } }. When a tenants or principals table names any id, an id without a row is not_entitled; an exhausted window is 429 quota_exceeded with Retry-After; a principal that earns `denials` refusals inside windowSec is 429 abuse_locked for lockSec. Every refusal is zero frames on any tunnel. A shared tenant window running out never feeds an individual principal's abuse lock. A table the edge cannot read refuses startup and names the offending path. Omit to keep the prior path (no quota at the edge). Counting is measured usage, not pricing."
     },
+    "evidenceAnchor": {
+      "_comment": "Optional, drupal-mcp-edge only. Independent Ed25519 notary the edge never holds the private key for: { url, publicKey } (publicKey is SPKI DER, standard base64; url is https, or http on loopback). When present, every settled receipt is reconciled by stable identifiers and submitted to that notary; GET /assessor serves one tenant-scoped, data-minimized pack bound to the live policy digest. A table the edge cannot pin refuses startup. Omit to keep the prior path (404 on /assessor). Lab/loopback only — not a hosted-service or design-partner admission claim. Run `drupal-mcp-anchor` to mint a pin."
+    },
+    "approvalRequiredTools": {
+      "_comment": "Optional, drupal-mcp-edge only. Array of tool names that require a one-use approval the edge issues before fan-down, e.g. [\"drupal_create_node\"]. A later tools/call with arguments.approvalId consumes that ticket (stripped before the tenant sees it). Omit to keep the prior path (no edge approval gate). A table the edge cannot read refuses startup. Lab/loopback only — not a hosted-service or design-partner admission claim."
+    },
     "revocationFile": "",
     "introspectionUrl": "",
     "introspectionClientIdEnv": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.13.1",
+  "version": "2.14.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",
@@ -8,7 +8,8 @@
     "drupal-mcp-connector": "src/index.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"
+    "drupal-mcp-agent": "bin/drupal-mcp-agent.js",
+    "drupal-mcp-anchor": "bin/drupal-mcp-anchor.js"
   },
   "files": [
     "src/",

package/src/lib/anchor.js

@@ -0,0 +1,338 @@
+/**
+ * Independent evidence notary (#261).
+ *
+ * Ed25519 inclusions over a receipt digest. The private key never lives on
+ * the relay edge; verification needs only the pinned public key and the
+ * inclusion. This is not Audit Chain, not a Drupal table, and not a
+ * hosted-service claim. A shared-host lab process is a named residual —
+ * production placement on a separately administered host is not chosen here.
+ */
+
+import { createHash, createPublicKey, generateKeyPairSync, randomUUID, sign, verify } from "node:crypto";
+import { createServer as createHttpServer } from "node:http";
+
+const DIGEST = /^[0-9a-f]{64}$/i;
+const SCHEMA = "sentinel-anchor-v1";
+const ALGORITHM = "Ed25519";
+
+/**
+ * @param {import("node:crypto").KeyObject} publicKey
+ * @returns {string} SPKI DER, standard base64.
+ */
+export function pinPublicKey(publicKey) {
+  return publicKey.export({ type: "spki", format: "der" }).toString("base64");
+}
+
+/**
+ * @param {string} pin
+ * @returns {import("node:crypto").KeyObject}
+ */
+export function loadPinnedPublicKey(pin) {
+  if (typeof pin !== "string" || !pin.trim()) {
+    throw new TypeError("Pinned public key is required.");
+  }
+  const key = createPublicKey({
+    key: Buffer.from(pin.trim(), "base64"),
+    type: "spki",
+    format: "der",
+  });
+  if (key.asymmetricKeyType !== "ed25519") {
+    throw new TypeError("Pinned public key must be Ed25519.");
+  }
+  return key;
+}
+
+/**
+ * Listen URL for a bound server. IPv6 literals are bracketed so
+ * `MCP_ANCHOR_BIND=::1` prints a usable URL.
+ *
+ * @param {{address?: string, port?: number, family?: string|number}} address
+ * @param {string} [scheme]
+ * @returns {string}
+ */
+export function formatBoundUrl(address, scheme = "http") {
+  const host = typeof address?.address === "string" ? address.address : "";
+  const port = address?.port;
+  const family = address?.family;
+  const ipv6 = family === "IPv6" || family === 6 || host.includes(":");
+  const hostname = ipv6 ? `[${host}]` : host;
+  return `${scheme}://${hostname}:${port}`;
+}
+
+/**
+ * @param {import("node:crypto").KeyObject} publicKey
+ * @returns {string}
+ */
+export function keyIdOf(publicKey) {
+  return createHash("sha256").update(pinPublicKey(publicKey)).digest("hex").slice(0, 16);
+}
+
+/**
+ * Mint a notary keypair. The private key is for the notary process only.
+ * @returns {{publicKey: import("node:crypto").KeyObject, privateKey: import("node:crypto").KeyObject, keyId: string, publicPin: string}}
+ */
+export function generateNotaryKeys() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  return {
+    publicKey,
+    privateKey,
+    keyId: keyIdOf(publicKey),
+    publicPin: pinPublicKey(publicKey),
+  };
+}
+
+/**
+ * Canonical bytes the signature covers. Signature itself is excluded.
+ * @param {{anchorId: string, receiptDigest: string, signedAt: string, keyId: string}} inclusion
+ * @returns {Buffer}
+ */
+export function canonicalInclusion(inclusion) {
+  return Buffer.from(
+    `v1\n${inclusion.anchorId}\n${inclusion.receiptDigest}\n${inclusion.signedAt}\n${inclusion.keyId}`,
+    "utf8",
+  );
+}
+
+/**
+ * @param {import("node:crypto").KeyObject|string} publicKeyOrPin
+ * @param {object} inclusion
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function verifyInclusion(publicKeyOrPin, inclusion) {
+  if (!inclusion || typeof inclusion !== "object" || Array.isArray(inclusion)) {
+    return { ok: false, reason: "malformed_inclusion" };
+  }
+  if (inclusion.schema !== SCHEMA || inclusion.algorithm !== ALGORITHM) {
+    return { ok: false, reason: "unsupported_inclusion" };
+  }
+  if (typeof inclusion.anchorId !== "string" || !inclusion.anchorId) {
+    return { ok: false, reason: "malformed_inclusion" };
+  }
+  if (typeof inclusion.receiptDigest !== "string" || !DIGEST.test(inclusion.receiptDigest)) {
+    return { ok: false, reason: "malformed_inclusion" };
+  }
+  if (typeof inclusion.signedAt !== "string" || !inclusion.signedAt) {
+    return { ok: false, reason: "malformed_inclusion" };
+  }
+  if (typeof inclusion.keyId !== "string" || !inclusion.keyId) {
+    return { ok: false, reason: "malformed_inclusion" };
+  }
+  if (typeof inclusion.signature !== "string" || !inclusion.signature) {
+    return { ok: false, reason: "malformed_inclusion" };
+  }
+  let key;
+  try {
+    key = typeof publicKeyOrPin === "string" ? loadPinnedPublicKey(publicKeyOrPin) : publicKeyOrPin;
+  } catch {
+    return { ok: false, reason: "unpinned_key" };
+  }
+  if (keyIdOf(key) !== inclusion.keyId) {
+    return { ok: false, reason: "key_mismatch" };
+  }
+  let signature;
+  try {
+    signature = Buffer.from(inclusion.signature, "base64");
+  } catch {
+    return { ok: false, reason: "malformed_inclusion" };
+  }
+  try {
+    if (!verify(null, canonicalInclusion(inclusion), key, signature)) {
+      return { ok: false, reason: "bad_signature" };
+    }
+  } catch {
+    return { ok: false, reason: "bad_signature" };
+  }
+  return { ok: true };
+}
+
+/**
+ * In-process notary. Holds the private key. The edge must never receive it.
+ *
+ * @param {object} [options]
+ * @param {import("node:crypto").KeyObject} [options.privateKey]
+ * @param {import("node:crypto").KeyObject} [options.publicKey]
+ * @param {string} [options.keyId]
+ * @param {() => Date} [options.now]
+ * @returns {object}
+ */
+export function createNotary({
+  privateKey,
+  publicKey,
+  keyId,
+  now = () => new Date(),
+} = generateNotaryKeys()) {
+  if (!privateKey || !publicKey) {
+    throw new TypeError("createNotary requires an Ed25519 keypair.");
+  }
+  const id = keyId || keyIdOf(publicKey);
+  const publicPin = pinPublicKey(publicKey);
+  const records = [];
+
+  return Object.freeze({
+    keyId: id,
+    publicPin,
+    /**
+     * @param {string} digest sha256 hex of the minimized execution.
+     * @returns {object}
+     */
+    include(digest) {
+      const receiptDigest = typeof digest === "string" ? digest.trim().toLowerCase() : "";
+      if (!DIGEST.test(receiptDigest)) {
+        throw new TypeError("Notary include() requires a SHA-256 hex digest.");
+      }
+      const unsigned = {
+        schema: SCHEMA,
+        anchorId: randomUUID(),
+        receiptDigest,
+        signedAt: now().toISOString(),
+        keyId: id,
+        algorithm: ALGORITHM,
+      };
+      const signature = sign(null, canonicalInclusion(unsigned), privateKey).toString("base64");
+      const inclusion = Object.freeze({ ...unsigned, signature });
+      records.push(inclusion);
+      return inclusion;
+    },
+    /** @returns {object[]} */
+    records() {
+      return records.slice();
+    },
+  });
+}
+
+function jsonResponse(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  }).end(payload);
+}
+
+/**
+ * Loopback HTTP notary. POST /anchor {digest} → inclusion. GET /keys → pin.
+ *
+ * @param {object} options
+ * @param {ReturnType<typeof createNotary>} options.notary
+ * @param {string} [options.bindHost]
+ * @param {number} [options.port]
+ * @returns {Promise<{url: string, port: number, close: Function}>}
+ */
+export function startAnchorServer({ notary, bindHost = "127.0.0.1", port = 0 }) {
+  if (!notary || typeof notary.include !== "function") {
+    throw new TypeError("startAnchorServer requires a notary.");
+  }
+  const server = createHttpServer((req, res) => {
+    const path = String(req.url || "/").split("?")[0];
+    if (req.method === "GET" && path === "/keys") {
+      jsonResponse(res, 200, {
+        algorithm: ALGORITHM,
+        keyId: notary.keyId,
+        publicKey: notary.publicPin,
+      });
+      return;
+    }
+    if (req.method === "POST" && path === "/anchor") {
+      let raw = "";
+      req.on("data", (chunk) => { raw += chunk; });
+      req.on("end", () => {
+        let body;
+        try {
+          body = raw ? JSON.parse(raw) : {};
+        } catch {
+          jsonResponse(res, 400, { error: "malformed" });
+          return;
+        }
+        try {
+          jsonResponse(res, 200, notary.include(body?.digest));
+        } catch {
+          jsonResponse(res, 400, { error: "invalid_digest" });
+        }
+      });
+      return;
+    }
+    res.writeHead(404).end("Not found");
+  });
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, bindHost, () => {
+      const address = server.address();
+      resolve({
+        url: formatBoundUrl(address),
+        port: address.port,
+        close: () => new Promise((done) => server.close(() => done())),
+      });
+    });
+  });
+}
+
+/**
+ * Edge-side client. Verifies every inclusion against the pinned public key.
+ * Never learns or holds the notary private key.
+ *
+ * @param {object} options
+ * @param {string} [options.url]
+ * @param {string} options.publicKey Pinned SPKI base64.
+ * @param {(digest: string) => object|Promise<object>} [options.submit]
+ * @param {typeof fetch} [options.fetchFn]
+ * @param {number} [options.timeoutMs]
+ * @returns {{submit: Function, publicPin: string}}
+ */
+export function createAnchorClient({
+  url = "",
+  publicKey,
+  submit = null,
+  fetchFn = fetch,
+  timeoutMs = 2000,
+} = {}) {
+  const key = loadPinnedPublicKey(publicKey);
+  const publicPin = pinPublicKey(key);
+  const timeout = Number.isInteger(timeoutMs) && timeoutMs > 0 ? timeoutMs : 2000;
+
+  async function post(digest) {
+    if (typeof submit === "function") {
+      return submit(digest);
+    }
+    const base = String(url || "").replace(/\/+$/, "");
+    if (!base) {
+      return { ok: false, reason: "anchor_unavailable" };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetchFn(`${base}/anchor`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ digest }),
+        signal: controller.signal,
+      });
+      if (!response.ok) return { ok: false, reason: "anchor_unavailable" };
+      return await response.json();
+    } catch {
+      return { ok: false, reason: "anchor_unavailable" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return Object.freeze({
+    publicPin,
+    /**
+     * @param {string} digest
+     * @returns {Promise<{ok: true, inclusion: object}|{ok: false, reason: string}>}
+     */
+    async submit(digest) {
+      const receiptDigest = typeof digest === "string" ? digest.trim().toLowerCase() : "";
+      if (!DIGEST.test(receiptDigest)) {
+        return { ok: false, reason: "invalid_digest" };
+      }
+      const raw = await post(receiptDigest);
+      if (raw && raw.ok === false && raw.reason) return raw;
+      const checked = verifyInclusion(key, raw);
+      if (!checked.ok) return { ok: false, reason: checked.reason };
+      if (raw.receiptDigest !== receiptDigest) {
+        return { ok: false, reason: "digest_mismatch" };
+      }
+      return { ok: true, inclusion: raw };
+    },
+  });
+}

package/src/lib/config.js

@@ -332,6 +332,45 @@ export function getInboundQuotas() {
   return entries.length ? Object.fromEntries(entries) : null;
 }
 
+/**
+ * Independent evidence notary pin (`auth.evidenceAnchor`).
+ * When present, the relay edge fails closed: a table it cannot pin refuses
+ * startup. Validation lives in evidence.js (`normalizeEvidenceAnchor`).
+ * @returns {object|null|unknown} Null when omitted or comment-only; the
+ *   comment-stripped table when it is an object; otherwise the configured
+ *   value unchanged so `startEdge()` refuses to start on it instead of
+ *   running without an independent anchor.
+ */
+export function getInboundEvidenceAnchor() {
+  const raw = loadConfig().auth?.evidenceAnchor;
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== "object" || Array.isArray(raw)) return raw;
+  const entries = Object.entries(raw)
+    .map(([key, value]) => [key.trim(), value])
+    .filter(([key]) => key && !key.startsWith("_"));
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+/**
+ * Tool names that require a one-use edge approval before fan-down
+ * (`auth.approvalRequiredTools`). When present, the relay edge fails
+ * closed: a table it cannot read refuses startup. Validation lives in
+ * edge.js (`normalizeApprovalRequiredTools`).
+ * @returns {string[]|null|unknown}
+ */
+export function getInboundApprovalRequiredTools() {
+  const raw = loadConfig().auth?.approvalRequiredTools;
+  if (raw === undefined || raw === null) return null;
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw === "object") {
+    const entries = Object.entries(raw)
+      .map(([key, value]) => [key.trim(), value])
+      .filter(([key]) => key && !key.startsWith("_"));
+    return entries.length ? raw : null;
+  }
+  return raw;
+}
+
 // ---------------------------------------------------------------------------
 // Auth headers — never logged, never exposed in tool responses
 // ---------------------------------------------------------------------------

package/src/lib/contracts/approval.js

@@ -64,6 +64,11 @@ export function createMemoryApproval() {
       return { approvalId, digest };
     },
 
+    /** Drop every unused and consumed ticket. Used by laboratory offboard. */
+    purge() {
+      store.clear();
+    },
+
     /** @returns {number} */
     size() {
       return store.size;