drupal-mcp-connector 2.19.1 → 2.20.0

package/src/lib/reports-support.js

@@ -64,6 +64,35 @@ export function fieldValue(entity, candidates) {
   return undefined;
 }
 
+/**
+ * Read a field off a canonical entity and say whether its KEY was there.
+ *
+ * JSON:API keeps the key of an empty field (value `null`, `[]`, or
+ * `data: null`) and leaves out the key of a field the account may not view.
+ * So an absent key and an empty value are different facts, and callers that
+ * count "missing" values must keep them apart (#337).
+ *
+ * Looks in `fields`, then `relationships`. Promoted base attributes (`title`,
+ * `status`, `langcode`, `created`, `changed`, and `path` as `url`) are always
+ * carried by the canonical shape, so they always read as present: a denied
+ * base attribute cannot be told from an empty one after promotion.
+ *
+ * @param {object} entity Canonical entity.
+ * @param {string} field Field machine name.
+ * @returns {{present: boolean, value: *}} `present` is about the key, not the value.
+ */
+export function fieldPresence(entity, field) {
+  const name = field === "path" ? "url" : field;
+  if (BASE_KEYS.has(name)) {
+    return { present: true, value: new Map(Object.entries(entity ?? {})).get(name) };
+  }
+  const fields = new Map(Object.entries(entity?.fields ?? {}));
+  if (fields.has(name)) return { present: true, value: fields.get(name) };
+  const relationships = new Map(Object.entries(entity?.relationships ?? {}));
+  if (relationships.has(name)) return { present: true, value: relationships.get(name) };
+  return { present: false, value: undefined };
+}
+
 /**
  * Whole days elapsed between a date and now.
  * @param {?(string|number|Date)} dateValue A date parseable by `new Date()`.
@@ -73,3 +102,49 @@ export function daysSince(dateValue) {
   if (!dateValue) return null;
   return Math.floor((Date.now() - new Date(dateValue).getTime()) / MS_PER_DAY);
 }
+
+/**
+ * Whether a canonical field or relationship value carries no content.
+ *
+ * Handles scalars, `{value}` text objects, arrays, relationship refs
+ * (`{id}` / `[{id}, …]` / `null`), and keyed objects such as a link
+ * (`{uri, title}`). A keyed object with at least one key and none of the
+ * known value keys counts as populated.
+ *
+ * @param {*} value A value read off an entity's base props, `fields`, or `relationships`.
+ * @returns {boolean} True when the value is absent or carries no content.
+ */
+export function isEmptyFieldValue(value) {
+  if (value === undefined || value === null || value === "") return true;
+  if (Array.isArray(value)) return value.every((item) => isEmptyFieldValue(item));
+  if (typeof value === "object") {
+    if ("id" in value) return !value.id;
+    if ("value" in value) return value.value === undefined || value.value === null || value.value === "";
+    if ("target_id" in value) return value.target_id === undefined || value.target_id === null;
+    if ("uri" in value) return !value.uri;
+    return Object.keys(value).length === 0;
+  }
+  return false;
+}
+
+/**
+ * Note attached to a report's `notVisible` list: requested fields whose key is
+ * absent from every sampled entity, so the report could not score them (#341).
+ */
+export const FIELDS_NOT_VISIBLE_NOTE =
+  "These fields are absent from every sampled entity (the key is missing, not empty). " +
+  "Each may be denied to this account or not exist on this bundle, or the name may be wrong. " +
+  "Drupal leaves a field the account may not view out of the response with no marker, so this report cannot tell whether any value is missing. " +
+  "They were not scored.";
+
+/**
+ * Normalize a caller's `fields` argument to distinct, non-empty field names.
+ * Arguments are not schema-validated before they reach a handler, so a single
+ * string is read as one name and non-string entries are dropped.
+ * @param {*} fields The raw `fields` argument.
+ * @returns {string[]} Field names, or [] when the caller named none.
+ */
+export function requestedFieldNames(fields) {
+  const list = typeof fields === "string" ? [fields] : (Array.isArray(fields) ? fields : []);
+  return [...new Set(list.filter((f) => typeof f === "string" && f.trim()).map((f) => f.trim()))];
+}

package/src/lib/security.js

@@ -53,6 +53,19 @@ import { parse } from "graphql";
  *
  *  globalRedactedFields string[]         stripped from every response, every type
  *
+ *  protectedModules    string[]          module machine names ADDED to the default
+ *                                        protected list (DEFAULT_PROTECTED_MODULES).
+ *                                        drupal_drush_module_disable refuses them (#346).
+ *  allowProtectedModuleUninstall string[] explicit opt-out: names REMOVED from the
+ *                                        protected list. The only way to shrink it.
+ *                                        A malformed value in either key refuses
+ *                                        every uninstall rather than being ignored.
+ *  allowCoreExtensionChange boolean      false on every preset. true lets
+ *                                        drupal_config_set write core.extension and
+ *                                        lets drupal_drush_config_import run when
+ *                                        core.extension differs (#349). Anything but
+ *                                        true or false keeps both refused.
+ *
  *  declaredCeiling     string            narrow-only X-MCP-Declared-Ceiling
  *                                        (public|internal|restricted). Invalid
  *                                        values are dropped, never widened.
@@ -244,6 +257,98 @@ const PRESETS = {
  * @param {object} site Site config (reads site.security).
  * @returns {object} Effective security config used by the assert/redact helpers.
  */
+/**
+ * Modules drupal_drush_module_disable refuses to uninstall, on every preset
+ * (#346). Uninstalling one removes a control the connector relies on, and
+ * Drupal drops the module's hook_schema tables on uninstall, so an audit log or
+ * stored keys go with it. Operators extend the list with
+ * `security.protectedModules` and shrink it only with the explicit
+ * `security.allowProtectedModuleUninstall`.
+ */
+export const DEFAULT_PROTECTED_MODULES = Object.freeze([
+  // Governance and integrity.
+  "mcp_sentinel", "audit_chain", "field_guard", "file_gate",
+  // Secrets and authentication.
+  "key", "encrypt", "simple_oauth", "consumers",
+  // The API and governed tool surface the connector talks to.
+  "jsonapi", "serialization", "mcp_server", "mcp_server_tool_bridge", "tool",
+  // The editorial gate that decides publication.
+  "content_moderation", "workflows",
+]);
+
+/** Drupal module machine name. Same rule as validateMachineName(), kept local to avoid an import cycle. */
+const MODULE_NAME_RE = /^[a-z][a-z0-9_]{0,127}$/;
+
+/**
+ * Read one module-list key from raw site security config.
+ * @param {object} raw site.security.
+ * @param {string} key Config key.
+ * @param {string[]} problems Collects a message per malformed key.
+ * @returns {string[]} The valid names (empty when the key is absent or malformed).
+ */
+function readModuleList(raw, key, problems) {
+  const value = new Map(Object.entries(raw)).get(key);
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    problems.push(`security.${key} must be an array of module machine names.`);
+    return [];
+  }
+  const valid = value.filter((name) => typeof name === "string" && MODULE_NAME_RE.test(name));
+  if (valid.length !== value.length) {
+    problems.push(
+      `security.${key} has ${value.length - valid.length} entr${value.length - valid.length === 1 ? "y that is" : "ies that are"} ` +
+      "not a module machine name (lowercase letters, digits and underscores)."
+    );
+    // A malformed opt-out never removes anything; a malformed extension still adds its valid names.
+    return key === "allowProtectedModuleUninstall" ? [] : valid;
+  }
+  return valid;
+}
+
+/**
+ * Resolve the effective protected-module list for a site.
+ * @param {object} raw site.security.
+ * @returns {{modules: string[], optOuts: string[], error: ?string}} `error` is
+ *   set when either key is malformed; callers must then refuse every uninstall.
+ */
+function resolveProtectedModules(raw) {
+  const problems = [];
+  const added = readModuleList(raw, "protectedModules", problems);
+  const optOuts = readModuleList(raw, "allowProtectedModuleUninstall", problems);
+  const removed = new Set(optOuts);
+  const modules = [...new Set([...DEFAULT_PROTECTED_MODULES, ...added])].filter((name) => !removed.has(name)).sort();
+  return { modules, optOuts: [...removed].sort(), error: problems.length ? problems.join(" ") : null };
+}
+
+/** The config object that lists installed modules and themes. */
+export const CORE_EXTENSION_CONFIG = "core.extension";
+
+/**
+ * Whether a config name addresses core.extension. Surrounding space and case
+ * are ignored: a source that trims the name would otherwise be reached by a
+ * padded one.
+ * @param {*} name Config object name.
+ * @returns {boolean}
+ */
+export function isCoreExtensionConfig(name) {
+  return typeof name === "string" && name.trim().toLowerCase() === CORE_EXTENSION_CONFIG;
+}
+
+/**
+ * Resolve the explicit opt-in for changing core.extension (#349).
+ * @param {object} raw site.security.
+ * @returns {{allowed: boolean, error: ?string}} `error` is set when the value
+ *   is neither true nor false; the change then stays refused.
+ */
+function resolveCoreExtensionOptIn(raw) {
+  const value = new Map(Object.entries(raw)).get("allowCoreExtensionChange");
+  if (value === undefined || value === null) return { allowed: false, error: null };
+  if (typeof value !== "boolean") {
+    return { allowed: false, error: "security.allowCoreExtensionChange must be true or false." };
+  }
+  return { allowed: value, error: null };
+}
+
 /** Default when `security.preset` is omitted — least privilege, not open mode (#140). */
 export const DEFAULT_SECURITY_PRESET = "production-strict";
 
@@ -254,6 +359,9 @@ export function resolveSecurityConfig(site) {
   const presetName = raw.preset ?? DEFAULT_SECURITY_PRESET;
   const preset = PRESETS[presetName] ?? PRESETS[DEFAULT_SECURITY_PRESET];
 
+  const protectedModules = resolveProtectedModules(raw);
+  const coreExtension = resolveCoreExtensionOptIn(raw);
+
   // Merge: explicit keys in site.security override the preset
   return {
     readOnly:              raw.readOnly              ?? preset.readOnly,
@@ -272,6 +380,13 @@ export function resolveSecurityConfig(site) {
     ],
     declaredCeiling:       raw.declaredCeiling ?? preset.declaredCeiling,
     readBudgets:           raw.readBudgets ?? preset.readBudgets ?? null,
+    // Not a preset value: the default list applies on every preset (#346).
+    protectedModules:        protectedModules.modules,
+    protectedModuleOptOuts:  protectedModules.optOuts,
+    protectedModulesError:   protectedModules.error,
+    // Not a preset value either: strict on every preset (#349).
+    allowCoreExtensionChange: coreExtension.allowed,
+    coreExtensionChangeError: coreExtension.error,
   };
 }
 
@@ -430,6 +545,119 @@ export function assertDestructiveAllowed(secConfig, entityType, id) {
   }
 }
 
+/**
+ * Gate a module uninstall (drupal_drush_module_disable) against the site's
+ * protected-module list (#346). Fails closed: a security config that is
+ * malformed, or that never went through resolveSecurityConfig(), refuses every
+ * uninstall.
+ * @param {object} secConfig Resolved security config.
+ * @param {string} moduleName Module machine name, already validated.
+ * @returns {void}
+ * @throws {SecurityError} if the module is protected or the list cannot be trusted.
+ */
+export function assertModuleUninstallAllowed(secConfig, moduleName) {
+  if (secConfig?.protectedModulesError || !Array.isArray(secConfig?.protectedModules)) {
+    throw new SecurityError(
+      "Module uninstall is blocked because this site's protected-module config cannot be read. " +
+      `${secConfig?.protectedModulesError ?? "The protected-module list is missing."} ` +
+      "No module can be uninstalled through the connector until an operator fixes it."
+    );
+  }
+  if (secConfig.protectedModules.includes(moduleName)) {
+    throw new SecurityError(
+      `Module "${moduleName}" is protected and cannot be uninstalled through the connector. ` +
+      "Uninstalling it removes a control the connector relies on, and Drupal drops the module's tables on uninstall. " +
+      `To allow it, an operator must add "${moduleName}" to security.allowProtectedModuleUninstall for this site.`
+    );
+  }
+}
+
+/**
+ * Gate a change to core.extension (#349). The object lists installed modules
+ * and themes, so a write to it, or a config import that changes it, can
+ * uninstall a protected module without going through
+ * assertModuleUninstallAllowed(). Refused on every preset unless the operator
+ * set `security.allowCoreExtensionChange: true`. Fails closed: a malformed
+ * value, or a config that never went through resolveSecurityConfig(), refuses.
+ * @param {object} secConfig Resolved security config.
+ * @param {string} refusal What is being refused and why, as full sentences.
+ * @returns {void}
+ * @throws {SecurityError} unless the operator opted in.
+ */
+export function assertCoreExtensionChangeAllowed(secConfig, refusal) {
+  if (secConfig?.allowCoreExtensionChange === true && !secConfig.coreExtensionChangeError) return;
+  throw new SecurityError(
+    `${refusal} ` +
+    "To install or uninstall a module use drupal_drush_module_enable or drupal_drush_module_disable, " +
+    "which check the protected-module list. " +
+    (secConfig?.coreExtensionChangeError
+      ? `This site's opt-in cannot be read: ${secConfig.coreExtensionChangeError} It stays refused until an operator fixes it.`
+      : "To allow it, an operator must set security.allowCoreExtensionChange = true for this site.")
+  );
+}
+
+/**
+ * Check a drupal_config_set value for core.extension against the protected
+ * module list (#349). Runs only after assertCoreExtensionChangeAllowed().
+ *
+ * The value is a map of top-level keys, and the source also accepts a dotted
+ * key such as `module.devel`. A `module` key replaces the whole module map, so
+ * every protected module in `currentModules` must still be in it. A dotted key
+ * under `module.` that names a protected module is refused outright.
+ *
+ * @param {object} secConfig Resolved security config.
+ * @param {object} value The submitted map of config keys to values.
+ * @param {?string[]} currentModules Machine names installed now, or null when
+ *   the caller has not read them. Needed only when `value` has a `module` key.
+ * @returns {{needsCurrentModules: boolean}} `needsCurrentModules` is true when
+ *   the value replaces the module map and `currentModules` was not given; the
+ *   caller reads the list and calls again.
+ * @throws {SecurityError} if the write would remove or alter a protected
+ *   module, or the protected-module list cannot be trusted.
+ */
+export function assertCoreExtensionValueKeepsProtected(secConfig, value, currentModules = null) {
+  if (secConfig?.protectedModulesError || !Array.isArray(secConfig?.protectedModules)) {
+    throw new SecurityError(
+      "The write to core.extension is blocked because this site's protected-module config cannot be read. " +
+      `${secConfig?.protectedModulesError ?? "The protected-module list is missing."}`
+    );
+  }
+  const entries = value && typeof value === "object" && !Array.isArray(value) ? Object.entries(value) : [];
+  const protectedSet = new Set(secConfig.protectedModules);
+
+  const dotted = entries
+    .map(([key]) => /^module\.([^.]+)/.exec(key)?.[1])
+    .filter((name) => name !== undefined && protectedSet.has(name));
+  if (dotted.length) {
+    throw new SecurityError(
+      `The write to core.extension changes the entry of protected module${dotted.length === 1 ? "" : "s"} ` +
+      `${[...new Set(dotted)].sort().join(", ")}. Nothing was written. ` +
+      "To allow it, an operator must name the module in security.allowProtectedModuleUninstall for this site."
+    );
+  }
+
+  const moduleEntry = entries.find(([key]) => key === "module");
+  if (!moduleEntry) return { needsCurrentModules: false };
+  const next = moduleEntry[1];
+  if (!next || typeof next !== "object" || Array.isArray(next)) {
+    throw new SecurityError(
+      "The write to core.extension is refused: `module` must be a map of module machine names to weights. Nothing was written."
+    );
+  }
+  if (!Array.isArray(currentModules)) return { needsCurrentModules: true };
+
+  const kept = new Set(Object.keys(next));
+  const removed = currentModules.filter((name) => protectedSet.has(name) && !kept.has(name)).sort();
+  if (removed.length) {
+    throw new SecurityError(
+      `The write to core.extension would remove protected module${removed.length === 1 ? "" : "s"} ${removed.join(", ")}. ` +
+      "Nothing was written. " +
+      "To allow it, an operator must name the module in security.allowProtectedModuleUninstall for this site."
+    );
+  }
+  return { needsCurrentModules: false };
+}
+
 /**
  * Whether a set of write attributes carries a publish action.
  *
@@ -751,5 +979,10 @@ export function getSecuritySummary(site) {
     entityRules:           cfg.entityRules,
     globalRedactedFields:  cfg.globalRedactedFields,
     declaredCeiling:       cfg.declaredCeiling ?? null,
+    protectedModules:      cfg.protectedModules,
+    protectedModuleOptOuts: cfg.protectedModuleOptOuts,
+    ...(cfg.protectedModulesError ? { protectedModulesError: cfg.protectedModulesError } : {}),
+    allowCoreExtensionChange: cfg.allowCoreExtensionChange,
+    ...(cfg.coreExtensionChangeError ? { coreExtensionChangeError: cfg.coreExtensionChangeError } : {}),
   };
 }

package/src/lib/sentinel-draft.js

@@ -9,6 +9,7 @@
  */
 
 import { entityRevisionId } from "./write-revision.js";
+import { httpStatusOf } from "./error-status.js";
 
 const LANGCODE_RE = /^[a-z][a-z0-9_-]{0,11}$/;
 const MISSING_DRAFT_ENDPOINT =
@@ -19,7 +20,6 @@ const MISSING_TRANSLATION_ENDPOINT =
   "Update MCP Sentinel; no canonical langcode PATCH was attempted.";
 const MISSING_DRAFT_RE = /does not provide Sentinel's governed draft endpoint/;
 const MISSING_TRANSLATION_RE = /does not provide Sentinel's governed draft-translation endpoint/;
-const DRUPAL_ABSENCE_RE = /Drupal (404|405)\b/;
 
 /**
  * Whether a backend can issue Sentinel's JSON:API draft/translation routes.
@@ -70,7 +70,8 @@ export function isMissingTranslationEndpoint(error) {
  * @returns {Error}
  */
 function missingEndpointError(error, message) {
-  if (DRUPAL_ABSENCE_RE.test(String(error?.message))) {
+  const status = httpStatusOf(error);
+  if (status === 404 || status === 405) {
     return new Error(message, { cause: error });
   }
   return error instanceof Error ? error : new Error(String(error));

package/src/lib/server-tools.js

@@ -18,8 +18,8 @@
  * Config (per site):
  *   "serverTools": { "url": "/mcp" }   // path is resolved against site.baseUrl
  *
- * Tools are NOT functional until the Drupal-side governed config tools ship;
- * until then the server returns a tool-not-found error, surfaced verbatim.
+ * The governed config tools work only when the source advertises them to this
+ * account in `tools/list`; otherwise the call fails closed before it is sent.
  */
 
 import fetch from "node-fetch";
@@ -27,6 +27,7 @@ import { createHmac, randomBytes } from "node:crypto";
 import { authHeadersAsync, clientHeaders, CLIENT_NAME, CLIENT_VERSION } from "./config.js";
 import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial, getDataFlowContext } from "./data-flow.js";
 import { clearToken } from "./oauth.js";
+import { cleanErrorText, describeErrorBody } from "./error-body.js";
 
 /** Calls a configured module binding through the registry, without fallback. */
 export async function callBoundModuleTool(site, binding, args, required) {
@@ -37,19 +38,103 @@ export async function callBoundModuleTool(site, binding, args, required) {
 }
 
 /**
- * Canonical server-side tool names for governed config operations.
+ * Tool API ids of the governed config tools (mcp_sentinel's McpConfigGet/List/Set
+ * plugins). These are ids, not wire names: the bridge decides the wire name, so
+ * it is resolved from the source's `tools/list` (see resolveServerToolName).
+ */
+export const SERVER_TOOL_IDS = Object.freeze({
+  configGet:  "mcp_sentinel_config_get",
+  configList: "mcp_sentinel_config_list",
+  configSet:  "mcp_sentinel_config_set",
+});
+
+/**
+ * Wire-name prefixes the Drupal tool bridge has used for a Tool API tool, in
+ * order of preference. Current mcp_server releases join the `tool_api` base id
+ * and the tool id with `__`; older ones used a dot.
+ */
+const WIRE_PREFIXES = ["tool_api__", "tool_api."];
+
+/** Upper bound on `tools/list` pages read while resolving a name. */
+const MAX_CATALOG_PAGES = 16;
+
+/**
+ * Wire names a bridge may advertise for a Tool API id, preferred first.
+ * @param {string} id Tool API id, e.g. `mcp_sentinel_config_set`.
+ * @returns {string[]} Candidate wire names.
+ */
+export function serverToolCandidates(id) {
+  return WIRE_PREFIXES.map((prefix) => `${prefix}${id}`);
+}
+
+/**
+ * Read every tool name the source advertises to this caller.
+ * @param {object} site Resolved site config.
+ * @param {Function} [list] Catalog page reader `(site, cursor) => {tools, nextCursor}`.
+ * @returns {Promise<Set<string>>} Advertised tool names.
+ * @throws {Error} on a malformed page, a repeated cursor, or too many pages.
+ */
+export async function advertisedServerToolNames(site, list = listServerTools) {
+  const names = new Set();
+  const seen = new Set();
+  let cursor;
+  for (let page = 0; page < MAX_CATALOG_PAGES; page++) {
+    const result = await list(site, cursor);
+    if (!Array.isArray(result?.tools)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" is malformed: tools/list returned no tools array.`);
+    }
+    for (const tool of result.tools) {
+      if (typeof tool?.name === "string") names.add(tool.name);
+    }
+    if (result.nextCursor === undefined || result.nextCursor === null) return names;
+    if (typeof result.nextCursor !== "string" || seen.has(result.nextCursor)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" returned an invalid or repeated cursor.`);
+    }
+    cursor = result.nextCursor;
+    seen.add(cursor);
+  }
+  throw new Error(`Server-tool catalog for site "${site._name}" exceeds ${MAX_CATALOG_PAGES} pages.`);
+}
+
+/**
+ * Resolve the wire name the source advertises for a governed config tool.
  *
- * Drupal's mcp_server_tool_bridge exposes every Tool-API tool through the MCP
- * protocol under the derivative name `tool_api.<mcp_tool_config id>`, so the
- * governed config tools registered against mcp_sentinel's McpConfigGet/List/Set
- * plugins surface as `tool_api.mcp_sentinel_config_*`. Keep the mapping here so
- * a server-side rename is a one-line change.
+ * Fails closed: when the catalog lists none of the candidate names, no name is
+ * guessed and nothing is called.
+ * @param {object} site Resolved site config.
+ * @param {string} binding Key of SERVER_TOOL_IDS (`configGet` | `configList` | `configSet`).
+ * @param {{list?: Function}} [deps] Injectable catalog page reader.
+ * @returns {Promise<string>} The advertised wire name.
+ * @throws {Error} if the binding is unknown or the tool is not advertised.
  */
-export const SERVER_TOOLS = {
-  configGet:  "tool_api.mcp_sentinel_config_get",
-  configList: "tool_api.mcp_sentinel_config_list",
-  configSet:  "tool_api.mcp_sentinel_config_set",
-};
+export async function resolveServerToolName(site, binding, { list = listServerTools } = {}) {
+  const id = new Map(Object.entries(SERVER_TOOL_IDS)).get(binding);
+  if (!id) throw new Error(`Unknown server tool binding "${binding}".`);
+  const candidates = serverToolCandidates(id);
+  const advertised = await advertisedServerToolNames(site, list);
+  const name = candidates.find((candidate) => advertised.has(candidate));
+  if (!name) {
+    throw new Error(
+      `Server tool "${id}" is not advertised by the source for site "${site._name}" ` +
+      `(looked for ${candidates.join(" and ")} in tools/list). No call was made. ` +
+      "Register and enable it as an mcp_tool_config entity, check that this account holds the scope the tool requires, " +
+      "or map it under serverTools.bindings. See docs/integration-contract.md."
+    );
+  }
+  return name;
+}
+
+/**
+ * Call a governed config tool by the wire name the source advertises for it.
+ * @param {object} site Resolved site config.
+ * @param {string} binding Key of SERVER_TOOL_IDS.
+ * @param {object} [args] Tool arguments.
+ * @returns {Promise<*>} The tool's structured result.
+ * @throws {Error} if the tool is not advertised, or as callServerTool.
+ */
+export async function callGovernedServerTool(site, binding, args = {}) {
+  return callServerTool(site, await resolveServerToolName(site, binding), args);
+}
 
 /** MCP protocol version advertised on the handshake and every subsequent POST. */
 const MCP_PROTOCOL_VERSION = "2025-06-18";
@@ -158,6 +243,73 @@ function parseSse(text) {
   return found;
 }
 
+/**
+ * Message for a non-2xx bridge response.
+ *
+ * The body is untrusted: an HTML error page from Drupal, PHP or a proxy, a
+ * server path or a backtrace. Only a cleaned, bounded detail is shown (see
+ * `describeErrorBody`). The prefix holds the HTTP status and always ends with a
+ * colon — the documented message shape (`httpStatusOf`, and
+ * `classifyBridgeError` when the error has no marker).
+ *
+ * A body that is a JSON-RPC error keeps its integer code and its cleaned
+ * message, so a refusal sent with a 401 or 403 stays readable.
+ * @param {string} prefix Message start, e.g. "Server-tool call x failed 502".
+ * @param {object} res node-fetch Response with `ok === false`.
+ * @param {string} rawText Response body.
+ * @param {?object} body Parsed JSON-RPC body, if any.
+ * @returns {string} Bounded message.
+ */
+function failedResponseMessage(prefix, res, rawText, body) {
+  const rpcError = body?.error;
+  if (rpcError && typeof rpcError === "object") {
+    const code = Number.isInteger(rpcError.code) ? ` ${rpcError.code}` : "";
+    const message = cleanErrorText(rpcError.message) || "the server returned no error message";
+    return `${prefix}: JSON-RPC error${code}: ${message}`;
+  }
+  const detail = describeErrorBody(rawText, res.headers?.get?.("content-type") ?? null);
+  return `${prefix}: ${detail || "the server returned an empty body"}`;
+}
+
+/**
+ * Message for a JSON-RPC `error` object.
+ *
+ * `error.code` is kept when it is an integer, because callers read it.
+ * `error.message` is cleaned and bounded. `error.data` is never read: with
+ * verbose errors on it holds a backtrace.
+ * @param {string} subject Message start, e.g. "Server-tool x".
+ * @param {*} rpcError JSON-RPC error object from the response.
+ * @returns {string} Bounded message.
+ */
+function rpcErrorMessage(subject, rpcError) {
+  const code = Number.isInteger(rpcError?.code) ? ` (${rpcError.code})` : "";
+  const detail = cleanErrorText(rpcError?.message) || "the server returned no error message";
+  return `${subject} error${code}: ${detail}`;
+}
+
+/**
+ * Build a bridge error that says what failed.
+ *
+ * The message ends with a response body or tool text, so code that branches on
+ * the failure reads these properties, never the message (#361):
+ *  - `bridgeFailure`: `"session"` (the handshake failed; no tool was reached),
+ *    `"http"` (non-2xx on the request), `"rpc"` (JSON-RPC error object) or
+ *    `"tool"` (the tool ran and its result has `isError`);
+ *  - `status`: the HTTP status, on a non-2xx response only (see `httpStatusOf`);
+ *  - `rpcCode`: the JSON-RPC `error.code`, when it is an integer.
+ * @param {string} message Error message.
+ * @param {"session"|"http"|"rpc"|"tool"} failure What failed.
+ * @param {{status?: number, rpcCode?: *}} [facts] Response status or JSON-RPC code.
+ * @returns {Error} The marked error.
+ */
+function bridgeError(message, failure, { status, rpcCode } = {}) {
+  const error = new Error(message);
+  error.bridgeFailure = failure;
+  if (Number.isInteger(status)) error.status = status;
+  if (Number.isInteger(rpcCode)) error.rpcCode = rpcCode;
+  return error;
+}
+
 /**
  * Perform the MCP session handshake against the server and cache the resulting
  * session id: `initialize` (read the `Mcp-Session-Id` response header) followed
@@ -197,18 +349,21 @@ async function initializeSession(site, endpoint, key) {
 
   const { body, rawText } = await readBody(res);
   if (!res.ok) {
-    throw new Error(`Server-tool session initialize failed ${res.status}: ${rawText}`);
+    throw bridgeError(
+      failedResponseMessage(`Server-tool session initialize failed ${res.status}`, res, rawText, body),
+      "session",
+      { status: res.status },
+    );
   }
   if (body?.error) {
-    const { code, message } = body.error;
-    const hasCode = code !== undefined && code !== null;
-    throw new Error(`Server-tool session initialize error${hasCode ? ` (${code})` : ""}: ${message}`);
+    throw bridgeError(rpcErrorMessage("Server-tool session initialize", body.error), "session", { rpcCode: body.error?.code });
   }
 
   const sessionId = res.headers.get("mcp-session-id");
   if (!sessionId) {
-    throw new Error(
-      `Server-tool session initialize for site "${site._name}" returned no Mcp-Session-Id header.`
+    throw bridgeError(
+      `Server-tool session initialize for site "${site._name}" returned no Mcp-Session-Id header.`,
+      "session",
     );
   }
 
@@ -265,7 +420,7 @@ function isSessionError(res, body) {
  * OAuth sites clears and re-acquires the token then replays (same session); a
  * server-side session expiry re-initialises the session then replays.
  * @param {object} site Resolved site config (provides baseUrl + auth).
- * @param {string} toolName Server-side MCP tool name (see SERVER_TOOLS).
+ * @param {string} toolName Server-side MCP wire name (see resolveServerToolName).
  * @param {object} [args] Tool arguments object.
  * @returns {Promise<*>} The tool's structured result.
  * @throws {Error} on transport failure, JSON-RPC error, or tool error.
@@ -330,23 +485,29 @@ async function requestServerTool(site, method, params, options) {
     if (!res.ok) {
       const mapped = sourceBudgetDenial(rawText);
       if (mapped) throw mapped;
-      throw new Error(`Server-tool call ${toolName} failed ${res.status}: ${rawText}`);
+      throw bridgeError(
+        failedResponseMessage(`Server-tool call ${toolName} failed ${res.status}`, res, rawText, body),
+        "http",
+        { status: res.status },
+      );
     }
 
     // JSON-RPC transport-level error.
     if (body?.error) {
-      const { code, message } = body.error;
-      const hasCode = code !== undefined && code !== null;
-      throw new Error(`Server-tool ${toolName} error${hasCode ? ` (${code})` : ""}: ${message}`);
+      throw bridgeError(rpcErrorMessage(`Server-tool ${toolName}`, body.error), "rpc", { rpcCode: body.error?.code });
     }
 
     // MCP tools/call result: { content: [...], isError?: boolean }.
     const result = body?.result;
     if (result?.isError && !options.preserveErrors) {
-      const detail = extractTextContent(result) || "tool reported an error";
-      const mapped = sourceBudgetDenial(detail);
+      // The budget code is looked for in the whole text, before it is cut.
+      const text = extractTextContent(result);
+      const mapped = sourceBudgetDenial(text);
       if (mapped) throw mapped;
-      throw new Error(`Server-tool ${toolName} reported an error: ${detail}`);
+      // The tool's own words are for the caller (a governed refusal explains
+      // itself), so they are kept: cleaned and bounded, never relayed raw.
+      const detail = cleanErrorText(text) || "tool reported an error";
+      throw bridgeError(`Server-tool ${toolName} reported an error: ${detail}`, "tool");
     }
     return result;
   }