drupal-mcp-connector 2.19.0 → 2.20.0

package/src/lib/verify.js

@@ -20,6 +20,8 @@
 import { createHash } from "node:crypto";
 import { CLIENT_VERSION } from "./config.js";
 import { resolveInboundAuthConfig, resolveInboundAuthMode } from "./http-auth.js";
+import { httpStatusOf } from "./error-status.js";
+import { advertisedServerToolNames, serverToolCandidates, SERVER_TOOL_IDS } from "./server-tools.js";
 
 /** Check outcome vocabulary.
  *
@@ -30,9 +32,9 @@ import { resolveInboundAuthConfig, resolveInboundAuthMode } from "./http-auth.js
  * and does not fail it: a verifier a secure install can never pass is a
  * verifier people stop running.
  */
-export const PASS = "pass";
-export const FAIL = "fail";
-export const SKIPPED = "skipped";
+const PASS = "pass";
+const FAIL = "fail";
+const SKIPPED = "skipped";
 export const NOT_APPLICABLE = "n/a";
 
 /** Every static check, in report order. */
@@ -473,9 +475,6 @@ export const LIVE_CHECKS = [
 /** A page size no governed profile should ever serve in one response. */
 const MASS_READ_LIMIT = 5000;
 
-/** The governed config-write tool, under the bridge's derivative name. */
-const CONFIG_SET_TOOL = "tool_api.mcp_sentinel_config_set";
-
 /** Joins a base URL and a path without doubling or dropping the separator. */
 function joinUrl(baseUrl, path) {
   return `${String(baseUrl).replace(/\/+$/, "")}/${String(path).replace(/^\/+/, "")}`;
@@ -518,6 +517,41 @@ async function attempt(transport, url, init = {}) {
   }
 }
 
+/** Standard JSON-RPC codes: the call itself was wrong, so nothing decided. */
+const STANDARD_RPC_CODES = new Set([-32700, -32600, -32601, -32602, -32603]);
+
+// The bridge client's documented message shapes, anchored at the start. A tool
+// name holds no whitespace, so text after the prefix can never change which
+// shape a message is.
+const SESSION_FAILURE_RE = /^Server-tool session initialize /;
+const HTTP_FAILURE_RE = /^Server-tool call \S+ failed \d{3}(?!\w)/;
+const TOOL_ERROR_RE = /^Server-tool \S+ reported an error:/;
+const RPC_ERROR_RE = /^Server-tool \S+ error \((-?\d+)\):/;
+
+/**
+ * What failed in a bridge call, read from the error the bridge client threw.
+ *
+ * The client marks its errors (`bridgeFailure`, plus `status` or `rpcCode`), and
+ * those properties decide. An error with no marker is read from the start of a
+ * documented message only. The rest of a message is a response body or tool
+ * text: a status, a JSON-RPC code or the words "reported an error" found there
+ * describe nothing about this call (#361).
+ * @param {unknown} error Thrown value.
+ * @param {string} message Its message.
+ * @returns {{kind: "session"|"http"|"tool"|"rpc"|null, status?: ?number, code?: ?number}}
+ */
+function bridgeFailureOf(error, message) {
+  const marker = typeof error?.bridgeFailure === "string" ? error.bridgeFailure : null;
+  if (marker === "session" || (!marker && SESSION_FAILURE_RE.test(message))) return { kind: "session" };
+  if (marker === "http" || (!marker && HTTP_FAILURE_RE.test(message))) {
+    return { kind: "http", status: httpStatusOf(error) };
+  }
+  if (marker === "tool" || (!marker && TOOL_ERROR_RE.test(message))) return { kind: "tool" };
+  if (marker === "rpc") return { kind: "rpc", code: Number.isInteger(error.rpcCode) ? error.rpcCode : null };
+  const rpc = marker ? null : RPC_ERROR_RE.exec(message);
+  return rpc ? { kind: "rpc", code: Number(rpc[1]) } : { kind: null };
+}
+
 /**
  * Whether a thrown bridge error is a POLICY refusal or an unexercised probe.
  *
@@ -526,11 +560,17 @@ async function attempt(transport, url, init = {}) {
  * them mean the source decided:
  *
  *  - a tool-level error (the tool ran and refused)            → refused
- *  - a server-defined JSON-RPC error (-32000..-32099)         → refused
+ *  - a server-defined JSON-RPC error (not a standard code)    → refused
  *  - an HTTP 401/403 on the tools/call                        → refused
  *  - a standard JSON-RPC error (method not found, bad params) → unexercised
+ *  - a JSON-RPC error with no readable code                   → unexercised
  *  - any other HTTP status (400, 404, 5xx)                    → unexercised
- *  - no bridge configured, session init, network failure      → unexercised
+ *  - no bridge configured, session init, token, network       → unexercised
+ *
+ * The HTTP status comes from the error's `status` property (`httpStatusOf`),
+ * and only for a failure of the tools/call itself: the token endpoint and the
+ * session handshake answer 401 and 403 too, before any tool is reached. A
+ * status is never read from the response body.
  *
  * Scoring an unexercised probe as a refusal is how a verifier produces a green
  * document for an install that never proved anything.
@@ -541,32 +581,36 @@ async function attempt(transport, url, init = {}) {
 export function classifyBridgeError(error) {
   const message = String(error?.message ?? error);
   const detail = message.slice(0, 200);
+  const failure = bridgeFailureOf(error, message);
+  const refused =
+    failure.kind === "tool" ||
+    (failure.kind === "http" && (failure.status === 401 || failure.status === 403)) ||
+    (failure.kind === "rpc" && failure.code !== null && !STANDARD_RPC_CODES.has(failure.code));
+  return { outcome: refused ? "refused" : "unexercised", detail };
+}
 
-  // The tool ran and reported an error: the canonical governed refusal.
-  if (/ reported an error:/.test(message)) return { outcome: "refused", detail };
-
-  // JSON-RPC error at the tools/call. Server-defined codes are decisions;
-  // the standard codes mean the call itself was wrong.
-  const rpc = message.match(/ error \((-?\d+)\):/);
-  if (rpc) {
-    const code = Number(rpc[1]);
-    const isStandard = [-32700, -32600, -32601, -32602, -32603].includes(code);
-    // A session-initialize error never reached the tool, whatever its code.
-    if (/session initialize/.test(message)) return { outcome: "unexercised", detail };
-    return isStandard ? { outcome: "unexercised", detail } : { outcome: "refused", detail };
-  }
-
-  // HTTP status on the tools/call: an authorisation status is a decision.
-  const http = message.match(/^Server-tool call .* failed (\d{3}):/);
-  if (http) {
-    const status = Number(http[1]);
-    return status === 401 || status === 403
-      ? { outcome: "refused", detail }
-      : { outcome: "unexercised", detail };
-  }
+/**
+ * Whether a status is a 4xx: the target answered and declined the request.
+ * @param {?number} status HTTP status, or null when there was no answer.
+ * @returns {boolean}
+ */
+function isClientErrorStatus(status) {
+  return Number.isInteger(status) && status >= 400 && status <= 499;
+}
 
-  // Bridge not configured, session initialise failure, transport error.
-  return { outcome: "unexercised", detail };
+/**
+ * Whether a failed mass read is a refusal by the source.
+ *
+ * 401, 403 and 429 are decisions. Any other 4xx counts only when the body
+ * carries the source's own refusal code (e.g. `read_budget_exceeded`). A 404
+ * means the collection does not exist, and a 5xx or no answer means the request
+ * failed; none of those reached the read control.
+ * @param {{status: ?number, codes: string[]}} result Reduced transport attempt.
+ * @returns {boolean}
+ */
+function isMassReadRefusal({ status, codes }) {
+  if (status === 401 || status === 403 || status === 429) return true;
+  return isClientErrorStatus(status) && status !== 404 && codes.length > 0;
 }
 
 /** Builds a live check result, carrying what was observed. */
@@ -593,11 +637,13 @@ function liveCheck(id, title, findings, observed = null, { skipped = false, notA
  * non-production environment first.
  *
  * @param {object} site Resolved site config (with oauth.clientSecret resolved).
- * @param {{transport: Function, now?: () => Date}} deps
+ * @param {{transport: Function, callTool?: Function, listTools?: Function, now?: () => Date}} deps
  *   `transport` is fetch-shaped and injectable so this is testable offline.
+ *   `callTool` and `listTools` are the bridge client's `tools/call` and
+ *   `tools/list`; without `listTools` the config probe cannot pass.
  * @returns {Promise<object>} Evidence document. Never contains secrets or payloads.
  */
-export async function verifyLive(site, { transport, callTool = null, contentTarget = null, contentTargetType = null, now = () => new Date() }) {
+export async function verifyLive(site, { transport, callTool = null, listTools = null, contentTarget = null, contentTargetType = null, now = () => new Date() }) {
   const baseUrl = String(site?.baseUrl ?? "");
   const checks = [];
   const httpsOk = baseUrl.startsWith("https://") || isLoopback(baseUrl);
@@ -663,24 +709,31 @@ export async function verifyLive(site, { transport, callTool = null, contentTarg
       tokenError = String(err?.message ?? err);
     }
     const anonymous = await attempt(transport, joinUrl(baseUrl, "/drupal-mcp/readiness"));
+    const authFindings = [];
+    if (!token) {
+      authFindings.push(
+        `the principal did not obtain a usable access token (status ${tokenStatus ?? "none"}` +
+          `${tokenError ? `, ${tokenError}` : ""}).`,
+      );
+    }
+    if (anonymous.ok) {
+      authFindings.push("a governed path answered an anonymous request; authentication is not being enforced.");
+    }
+    // A server failure or no answer is not a refusal: the anonymous request
+    // never reached an access decision, so the claim is not proven either way.
+    const anonymousUndecided = !anonymous.ok && !isClientErrorStatus(anonymous.status);
     checks.push(
       liveCheck(
         "principal_auth",
         "The principal authenticates, and anonymous access is refused",
-        (() => {
-          const findings = [];
-          if (!token) {
-            findings.push(
-              `the principal did not obtain a usable access token (status ${tokenStatus ?? "none"}` +
-                `${tokenError ? `, ${tokenError}` : ""}).`,
-            );
-          }
-          if (anonymous.ok) {
-            findings.push("a governed path answered an anonymous request; authentication is not being enforced.");
-          }
-          return findings;
-        })(),
+        authFindings,
         { tokenStatus, anonymousStatus: anonymous.status },
+        authFindings.length === 0 && anonymousUndecided
+          ? {
+            skipped: true,
+            skipReason: `the anonymous request was not refused, it failed (status ${anonymous.status ?? "none"}), which proves nothing about whether anonymous access is refused.`,
+          }
+          : {},
       ),
     );
   }
@@ -724,7 +777,7 @@ export async function verifyLive(site, { transport, callTool = null, contentTarg
 
   // --- entitlement filtering ----------------------------------------------
   // Through the connector's own bridge client, so the probe exercises the real
-  // contract: an MCP session, the governed tool's `tool_api.*` name and its
+  // contract: an MCP session, the governed tool's advertised wire name and its
   // argument shape, and a refusal surfaced as a tool/JSON-RPC error rather
   // than an HTTP status. A hand-rolled JSON-RPC body would "pass" for the
   // wrong reason — the server would reject it as malformed, not as denied.
@@ -732,25 +785,67 @@ export async function verifyLive(site, { transport, callTool = null, contentTarg
   const holdsConfigScope = scopes.includes("mcp_config");
 
   /**
-   * Attempts a governed config write. Returns {served, detail}: `served` true
-   * means the write was accepted, which for an out-of-tier principal is the
-   * finding.
+   * Attempts a governed config write. Returns {served, outcome, detail,
+   * advertised, tool}: `served` true means the write was accepted, which for an
+   * out-of-tier principal is the finding.
+   *
+   * The source catalog is read first. A call to a name the source does not
+   * publish fails too, and that failure is indistinguishable from a refusal, so
+   * a refusal only counts for a tool the catalog lists. An unadvertised name is
+   * still attempted, because a served write is a finding either way; anything
+   * short of served is then `unexercised`, never a pass.
    */
   const attemptConfigWrite = async () => {
+    let candidates;
     try {
       // The negative probe must reach source authorization, not merely prove
       // that the connector hides out-of-tier tools from discovery.
-      const tool = site.serverTools?.bindings === undefined ? CONFIG_SET_TOOL
-        : (await import("./module-tools.js")).resolveModuleBinding(site, "configSet", {
+      candidates = site.serverTools?.bindings === undefined
+        ? serverToolCandidates(SERVER_TOOL_IDS.configSet)
+        : [(await import("./module-tools.js")).resolveModuleBinding(site, "configSet", {
           operation: "write", scope: "mcp_config", capabilities: ["configWrite"],
-        }).policy.name;
-      await callTool(site, tool, { name: "system.site", data: { name: "verification probe" } });
-      return { served: true, outcome: "served", detail: "accepted" };
+        }).policy.name];
     } catch (err) {
-      // Not every throw is a refusal — see classifyBridgeError.
       const { outcome, detail } = classifyBridgeError(err);
-      return { served: false, outcome, detail };
+      return { served: false, outcome, detail, advertised: false, tool: null };
     }
+
+    let names = null;
+    let catalogProblem = null;
+    if (typeof listTools !== "function") {
+      catalogProblem = "the source catalog could not be read: no tools/list reader was supplied.";
+    } else {
+      try {
+        names = await advertisedServerToolNames(site, listTools);
+      } catch (err) {
+        catalogProblem = `the source catalog could not be read: ${String(err?.message ?? err).slice(0, 200)}`;
+      }
+    }
+    const tool = names ? candidates.find((name) => names.has(name)) ?? null : null;
+    const advertised = tool !== null;
+
+    for (const name of advertised ? [tool] : candidates) {
+      try {
+        await callTool(site, name, { name: "system.site", data: { name: "verification probe" } });
+        return { served: true, outcome: "served", detail: "accepted", advertised, tool: name };
+      } catch (err) {
+        if (advertised) {
+          // Not every throw is a refusal — see classifyBridgeError.
+          const { outcome, detail } = classifyBridgeError(err);
+          return { served: false, outcome, detail, advertised, tool: name };
+        }
+      }
+    }
+    return {
+      served: false,
+      outcome: "unexercised",
+      advertised: false,
+      tool: null,
+      detail: catalogProblem ??
+        `the config write tool is not advertised by the source to this principal (looked for ${candidates.join(" and ")} in tools/list), ` +
+        "so a failed call cannot be told apart from a refusal. Check that the tool is registered and enabled; " +
+        "a source that filters discovery by entitlement hides it from this principal, so confirm the name with a principal that holds mcp_config.",
+    };
   };
 
   let configWrite = null;
@@ -776,7 +871,7 @@ export async function verifyLive(site, { transport, callTool = null, contentTarg
       configWrite.outcome === "unexercised"
         ? liveCheck("entitlement_filtering", "Out-of-tier operations are filtered for this principal", [], configWrite, {
           skipped: true,
-          skipReason: `the governed tool call never ran, so no policy decision was observed: ${configWrite.detail}`,
+          skipReason: `no policy decision on the governed tool call was observed, so nothing was proven: ${configWrite.detail}`,
         })
         : liveCheck(
           "entitlement_filtering",
@@ -823,8 +918,16 @@ export async function verifyLive(site, { transport, callTool = null, contentTarg
       (() => {
         const observed = { status: massRead.status, codes: massRead.codes, items: massRead.count };
         const title = `A ${MASS_READ_LIMIT}-item read is refused or bounded`;
-        // Refused outright: the control fired.
-        if (!massRead.ok) return liveCheck("probe_mass_read", title, [], observed);
+        // Refused outright: the control fired. Only a status the source chose
+        // counts. A 5xx, a 404 or no answer never reached the read control.
+        if (!massRead.ok) {
+          return isMassReadRefusal(massRead)
+            ? liveCheck("probe_mass_read", title, [], observed)
+            : liveCheck("probe_mass_read", title, [], observed, {
+              skipped: true,
+              skipReason: `the read failed (status ${massRead.status ?? "none"}), which is not a refusal and proves nothing about the read bound.`,
+            });
+        }
         // Served, but bounded well below what was asked for: also the control
         // firing — a cap is a bound, and reporting it as unbounded would train
         // operators to ignore the verifier.

package/src/tools/config.js

@@ -20,18 +20,27 @@ import {
   assertConfigReadAllowed,
   assertConfigWriteAllowed,
   assertConfigScope,
+  assertCoreExtensionChangeAllowed,
+  assertCoreExtensionValueKeepsProtected,
+  isCoreExtensionConfig,
   hasScope,
+  CORE_EXTENSION_CONFIG,
+  SecurityError,
 } from "../lib/security.js";
-import { callServerTool, callBoundModuleTool, SERVER_TOOLS } from "../lib/server-tools.js";
+import { callGovernedServerTool, callBoundModuleTool, toolResultData } from "../lib/server-tools.js";
 
-/** Compatibility names use an approved module binding when configured. */
+/**
+ * Compatibility names use an approved module binding when configured. Without
+ * bindings, the wire name comes from the source's own tools/list; a tool the
+ * source does not advertise fails closed before any call.
+ */
 async function configTool(site, binding, args, operation, capability) {
   if (site.serverTools?.bindings !== undefined) {
     return callBoundModuleTool(site, binding, args, {
       operation, scope: "mcp_config", capabilities: [capability],
     });
   }
-  return callServerTool(site, new Map(Object.entries(SERVER_TOOLS)).get(binding), args);
+  return callGovernedServerTool(site, binding, args);
 }
 
 // ---------------------------------------------------------------------------
@@ -65,6 +74,56 @@ async function configList({ site: siteName, prefix }) {
   return configTool(site, "configList", args, "read", "configRead");
 }
 
+/**
+ * Read the machine names of the modules installed now, through the governed
+ * config read. Used only to check a core.extension write (#349).
+ * @param {object} site Resolved site config.
+ * @param {object} sec Resolved security config.
+ * @returns {Promise<string[]>} Installed module machine names.
+ * @throws {SecurityError} if the list cannot be read or understood. The caller
+ *   then writes nothing.
+ */
+async function readInstalledModules(site, sec) {
+  const blocked = "The write to core.extension is refused because the current module list could not be read, " +
+    "so the connector cannot tell whether a protected module would be removed. Nothing was written.";
+  let data;
+  try {
+    assertConfigReadAllowed(sec);
+    data = toolResultData(await configTool(site, "configGet", { name: CORE_EXTENSION_CONFIG }, "read", "configRead"));
+  } catch (err) {
+    throw new SecurityError(`${blocked} Reason: ${String(err?.message ?? err).slice(0, 300)}`);
+  }
+  // The source's config tool answers { name, data }; a plain config map is read too.
+  const modules = [data?.data?.module, data?.module]
+    .find((candidate) => candidate && typeof candidate === "object" && !Array.isArray(candidate));
+  if (!modules) throw new SecurityError(`${blocked} Reason: the read returned no module map.`);
+  return Object.keys(modules);
+}
+
+/**
+ * Gate a drupal_config_set on core.extension (#349). A write there can install
+ * or uninstall any module or theme without Drupal's install and uninstall
+ * steps, and it bypasses the protected-module list. It is refused unless the
+ * operator opted in; with the opt-in, a value that would remove or alter a
+ * protected module is still refused.
+ * @param {object} site Resolved site config.
+ * @param {object} sec Resolved security config.
+ * @param {object} value The submitted map of config keys to values.
+ * @returns {Promise<void>}
+ * @throws {SecurityError} if the write is refused.
+ */
+async function assertCoreExtensionWriteAllowed(site, sec, value) {
+  assertCoreExtensionChangeAllowed(
+    sec,
+    "drupal_config_set does not write core.extension. A write there can install or uninstall any module or theme " +
+    "without running Drupal's install and uninstall steps, and it bypasses the protected-module list. Nothing was written."
+  );
+  const { needsCurrentModules } = assertCoreExtensionValueKeepsProtected(sec, value);
+  if (needsCurrentModules) {
+    assertCoreExtensionValueKeepsProtected(sec, value, await readInstalledModules(site, sec));
+  }
+}
+
 /**
  * Set a configuration value. Governed and audited server-side; the connector
  * additionally enforces the config-write cap before dispatching.
@@ -73,9 +132,14 @@ async function configList({ site: siteName, prefix }) {
  * server-side tool (mcp_sentinel McpConfigSetTool) takes that map under the key
  * `data` and applies a partial `$editable->set($key, $value)` per entry, so we
  * translate `value` → `data` at the call site.
+ *
+ * A write to `core.extension` is refused unless the operator set
+ * `security.allowCoreExtensionChange` (#349). The check runs here, before the
+ * binding path and the unbound path split.
  * @param {object} args - { site?, name, value }.
  * @returns {Promise<*>} The server tool's result.
- * @throws {SecurityError} if the site is read-only or config writes are disabled.
+ * @throws {SecurityError} if the site is read-only, config writes are disabled,
+ *   or the write targets core.extension without the operator's opt-in.
  */
 async function configSet({ site: siteName, name, value }) {
   const site = getSiteConfig(siteName);
@@ -83,6 +147,7 @@ async function configSet({ site: siteName, name, value }) {
   assertConfigScope(site, `config:set ${name}`);
   assertNotReadOnly(sec, `config:set ${name}`);
   assertConfigWriteAllowed(sec);
+  if (isCoreExtensionConfig(name)) await assertCoreExtensionWriteAllowed(site, sec, value);
   return configTool(site, "configSet", { name, data: value }, "write", "configWrite");
 }
 
@@ -181,7 +246,7 @@ export const definitions = [
   },
   {
     name: "drupal_config_set",
-    description: "Set a Drupal configuration value via the governed server-side config tool. Audited and gated server-side; requires the config-editor (Developer) tier. Then export to YAML for a PR.",
+    description: "Set a Drupal configuration value via the governed server-side config tool. Audited and gated server-side; requires the config-editor (Developer) tier. Then export to YAML for a PR. Refused for `core.extension`, which lists installed modules and themes: use drupal_drush_module_enable or drupal_drush_module_disable instead. Only an operator can allow it, with `allowCoreExtensionChange` in site config (see drupal_security_info), and a value that removes a protected module is still refused.",
     inputSchema: {
       type: "object",
       required: ["name", "value"],