drupal-mcp-connector 2.19.0 → 2.20.0

package/src/lib/dispatch.js

@@ -15,10 +15,10 @@ import { resolveSecurityConfig, assertNotReadOnly,
 import { toolError, toolResult } from "./errors.js";
 import { BackendCapabilityError, BackendResolutionError } from "./backends/errors.js";
 import { inferOperation } from "./operations.js";
-import { assertSourceGovernance, GovernanceError, GOVERNANCE_DIAGNOSTIC_TOOLS } from "./governance.js";
+import { assertSourceGovernance, GovernanceError } from "./governance.js";
 import {
-  assertPrincipalEntitlement, callerTargetHints, getRequestIdentity,
-  principalHasScope, resolveAuthoritativeTarget,
+  assertPrincipalEntitlement, callerTargetHints, DIAGNOSTIC_TOOLS,
+  getRequestIdentity, principalHasScope, resolveAuthoritativeTarget,
 } from "./principal.js";
 import { assertExplicitSiteForWrite, withResolvedTarget } from "./site-target.js";
 import { buildDataFlowContext, consumeBudgetIfEnforced, runWithDataFlow } from "./data-flow.js";
@@ -55,7 +55,7 @@ export function listResolvableSiteConfigs() {
  * @returns {?{site: object, source: string, name: string}}
  * @throws {SecurityError}
  */
-export function resolveCallTarget(toolName, rawArgs, context = {}) {
+function resolveCallTarget(toolName, rawArgs, context = {}) {
   if (toolName === "drupal_list_sites") return null;
   if (toolName === "drupal_governance_status" && callerTargetHints(rawArgs).length === 0) {
     return null;
@@ -157,7 +157,7 @@ export async function securityMiddleware(toolName, args, handler, context = {})
   const assertCallAllowed = async () => {
     // Source-governance gate (#176). The diagnostic tools stay callable while
     // governance fails — they are how an operator learns which condition failed.
-    if (!GOVERNANCE_DIAGNOSTIC_TOOLS.has(toolName)) {
+    if (!DIAGNOSTIC_TOOLS.has(toolName)) {
       await assertSourceGovernance(site);
     }
 
@@ -188,7 +188,7 @@ export async function securityMiddleware(toolName, args, handler, context = {})
     await assertCallAllowed();
     // Charge only after governance and policy gates pass, so an outage or a
     // local deny cannot exhaust the window. Diagnostics do not consume.
-    if (!GOVERNANCE_DIAGNOSTIC_TOOLS.has(toolName)) {
+    if (!DIAGNOSTIC_TOOLS.has(toolName)) {
       consumeBudgetIfEnforced("chained_action");
     }
     return handler(nextArgs);

package/src/lib/drupal-fetch.js

@@ -1,5 +1,6 @@
 /**
  * Authenticated HTTP wrappers for Drupal JSON:API and file uploads.
+ * Northbound node-fetch calls share a 30s abort timeout (`DRUPAL_FETCH_TIMEOUT_MS`).
  */
 
 import fetch from "node-fetch";
@@ -19,9 +20,32 @@ import {
   sanitizeUploadFilename,
   validateMachineName,
 } from "./validate.js";
+import { describeErrorBody, cleanGraphqlErrors, ERROR_DOCUMENT_MAX_CHARS } from "./error-body.js";
 
 const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
 
+/** Default northbound Drupal HTTP timeout in milliseconds. Matches `sshDrush`. */
+export const DRUPAL_FETCH_TIMEOUT_MS = 30_000;
+
+/**
+ * node-fetch with the shared abort timeout. A caller `signal` wins.
+ * @param {string} url Fully-qualified request URL.
+ * @param {object} [options] node-fetch options (method, body, headers, signal).
+ * @returns {Promise<object>} node-fetch Response.
+ * @throws {Error} when the default timeout fires (`AbortError` remapped).
+ */
+async function timedDrupalFetch(url, options = {}) {
+  const signal = options.signal ?? AbortSignal.timeout(DRUPAL_FETCH_TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...options, signal });
+  } catch (err) {
+    if (err?.name === "AbortError" && !options.signal) {
+      throw new Error(`Drupal request timed out after ${DRUPAL_FETCH_TIMEOUT_MS / 1000}s`);
+    }
+    throw err;
+  }
+}
+
 /**
  * Read a 2xx body once. Prefers text() so byte accounting can see the payload;
  * falls back to json() for test doubles that only implement that.
@@ -41,6 +65,45 @@ async function readOkBody(res) {
   return { json: await res.json(), text: "" };
 }
 
+/**
+ * Build the error for a non-2xx response.
+ *
+ * The body is untrusted: it may be an HTML error page from Drupal, PHP or a
+ * proxy, or carry a server path, another user's filename or a backtrace. Only a
+ * cleaned, bounded detail is surfaced (see `describeErrorBody`); the prefix,
+ * which holds the HTTP status, is always kept because callers match on it
+ * (#343, #345).
+ * @param {object} res node-fetch Response with `ok === false`.
+ * @param {string} prefix Message start, e.g. "Drupal 404 on GET /jsonapi/x".
+ * @param {object} [options] Passed to `describeErrorBody`.
+ * @returns {Promise<Error>} A source budget denial, or the described failure
+ *   with the HTTP status on its `status` property. Callers that branch on the
+ *   status read it with `httpStatusOf()`, never from the message text (#355).
+ */
+async function failedResponseError(res, prefix, options) {
+  let body;
+  try {
+    body = await res.text();
+  } catch {
+    return withStatus(new Error(`${prefix} (response body could not be read)`), res.status);
+  }
+  const mapped = sourceBudgetDenial(body);
+  if (mapped) return mapped;
+  const detail = describeErrorBody(body, res.headers?.get?.("content-type") ?? null, options);
+  return withStatus(new Error(detail ? `${prefix}: ${detail}` : `${prefix} (empty response body)`), res.status);
+}
+
+/**
+ * Set the HTTP status on an error.
+ * @param {Error} error Error to mark.
+ * @param {number} status HTTP status of the response.
+ * @returns {Error} The same error.
+ */
+function withStatus(error, status) {
+  error.status = status;
+  return error;
+}
+
 /**
  * Standard JSON:API request against a site.
  *
@@ -50,7 +113,10 @@ async function readOkBody(res) {
  * @param {string} path Path appended to site.baseUrl (e.g. "/jsonapi/node/article").
  * @param {object} [options] node-fetch options (method, body, extra headers).
  * @returns {Promise<object|null>} Parsed JSON body, or null for a 204 No Content.
- * @throws {Error} on any non-2xx response, with Drupal error detail when available.
+ * @throws {Error} on any non-2xx response. The message is
+ *   `Drupal <status> on <method> <path>: <detail>`, where the detail is the
+ *   cleaned, bounded `errors[].detail` text (see `describeErrorBody`). The raw
+ *   body and any HTML page are never included.
  */
 export async function drupalFetch(site, path, options = {}) {
   const url = `${site.baseUrl}${path}`;
@@ -61,7 +127,7 @@ export async function drupalFetch(site, path, options = {}) {
     consumeBudgetIfEnforced("request", 1, { retry: isRetry || paid });
     if (collection) consumeBudgetIfEnforced("page", 1, { retry: isRetry || paid });
     paid = true;
-    return fetch(url, {
+    return timedDrupalFetch(url, {
       ...options,
       headers: {
         "Content-Type": JSON_API_CONTENT_TYPE,
@@ -83,18 +149,11 @@ export async function drupalFetch(site, path, options = {}) {
   }
 
   if (!res.ok) {
-    const body = await res.text();
-    const mapped = sourceBudgetDenial(body);
-    if (mapped) throw mapped;
-    let detail = body;
-    try {
-      const parsed = JSON.parse(body);
-      // Drupal JSON:API surfaces errors in errors[].detail
-      if (parsed.errors?.length) {
-        detail = parsed.errors.map((e) => e.detail || e.title).join("; ");
-      }
-    } catch { /* use raw body */ }
-    throw new Error(`Drupal ${res.status} on ${options.method || "GET"} ${path}: ${detail}`);
+    throw await failedResponseError(
+      res,
+      `Drupal ${res.status} on ${options.method || "GET"} ${path}`,
+      { maxChars: ERROR_DOCUMENT_MAX_CHARS },
+    );
   }
 
   if (res.status === 204) return null; // No Content (e.g. DELETE success)
@@ -107,15 +166,22 @@ export async function drupalFetch(site, path, options = {}) {
  * GraphQL request — posts a JSON body to the site's GraphQL endpoint.
  * @param {object} site Resolved site config (provides baseUrl + auth).
  * @param {object} body GraphQL request body, e.g. { query, variables }.
- * @returns {Promise<object>} Parsed GraphQL JSON response.
+ * @returns {Promise<object>} Parsed GraphQL JSON response. `data` is returned
+ *   as received. GraphQL reports a failed query as HTTP 200 with an `errors`
+ *   array; that array is replaced by its cleaned, bounded form (see
+ *   `cleanGraphqlErrors`): `message`, `path`, `locations` and the machine
+ *   values of `extensions` only (#356).
  * @throws {Error} on any non-2xx response (clears the OAuth token cache on 401).
+ *   The message is `GraphQL request failed <status>: <detail>`, where the detail
+ *   is the cleaned, bounded `errors[].message` text (see `describeErrorBody`).
+ *   The raw body and any HTML page are never included.
  */
 export async function drupalGraphqlFetch(site, body) {
   const endpoint = site.graphqlEndpoint || "/graphql";
   const url = `${site.baseUrl}${endpoint}`;
 
   consumeBudgetIfEnforced("request");
-  const res = await fetch(url, {
+  const res = await timedDrupalFetch(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -131,14 +197,20 @@ export async function drupalGraphqlFetch(site, body) {
     // OAuth sites: a 401 likely means the token expired server-side. Clear the
     // cached token so the next request re-acquires, then surface the error.
     if (res.status === 401 && site.oauth) clearToken(site);
-    const text = await res.text();
-    const mapped = sourceBudgetDenial(text);
-    if (mapped) throw mapped;
-    throw new Error(`GraphQL request failed ${res.status}: ${text}`);
+    throw await failedResponseError(
+      res,
+      `GraphQL request failed ${res.status}`,
+      { maxChars: ERROR_DOCUMENT_MAX_CHARS },
+    );
   }
 
   const { json, text } = await readOkBody(res);
   accountNorthboundBody(json, text);
+  if (json && typeof json === "object" && !Array.isArray(json) && "errors" in json) {
+    json.errors = cleanGraphqlErrors(json.errors);
+    // An empty list is not an error; consumers test `json.errors` for truth.
+    if (!json.errors.length) delete json.errors;
+  }
   return json;
 }
 
@@ -159,7 +231,9 @@ export async function drupalGraphqlFetch(site, body) {
  * @param {string} fieldName File field on the bundle (e.g. "field_media_image").
  * @param {string} filePath Local path to the file to upload.
  * @returns {Promise<object>} Parsed JSON:API File entity response.
- * @throws {Error} on any non-2xx response.
+ * @throws {Error} on any non-2xx response. The message keeps the HTTP status and a
+ *   cleaned, bounded detail from the body (see `describeErrorBody`); the raw body
+ *   and any HTML page are never included.
  */
 export async function drupalUploadFile(site, entityType, bundle, fieldName, filePath) {
   // #137: machine-name segments + path allowlist before any FS or network I/O.
@@ -173,7 +247,7 @@ export async function drupalUploadFile(site, entityType, bundle, fieldName, file
   const url = `${site.baseUrl}/jsonapi/${encodeURIComponent(entityType)}/${encodeURIComponent(bundle)}/${encodeURIComponent(fieldName)}`;
 
   consumeBudgetIfEnforced("request");
-  const res = await fetch(url, {
+  const res = await timedDrupalFetch(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/octet-stream",
@@ -190,10 +264,7 @@ export async function drupalUploadFile(site, entityType, bundle, fieldName, file
   });
 
   if (!res.ok) {
-    const body = await res.text();
-    const mapped = sourceBudgetDenial(body);
-    if (mapped) throw mapped;
-    throw new Error(`File upload failed ${res.status}: ${body}`);
+    throw await failedResponseError(res, `File upload failed ${res.status}`);
   }
 
   return res.json();

package/src/lib/dry-run-checks.js

@@ -0,0 +1,78 @@
+/**
+ * What a `dryRun` preview actually checked (#336).
+ *
+ * A preview that returns without a refusal reads as "this write will work".
+ * That is only true for the checks that ran, and most previews run few of
+ * them. Every dryRun result carries a `checks` block naming each check as
+ * `checked` or `not_checked`, plus a `caveat` sentence when anything was left
+ * out. `checked` always means "ran and passed": a failed check throws, so it
+ * never reaches a preview.
+ *
+ * Three server-side preflights exist:
+ *
+ *  - `sentinel_draft` — Sentinel's non-saving draft endpoint. It receives the
+ *    real attributes and relationships, applies them through core field
+ *    access, validates the entity, and returns before saving. It predicts a
+ *    field-access or validation refusal.
+ *  - `core_patch_guard` — a core JSON:API PATCH with no fields and a
+ *    non-matching `data.id`. The route checks entity update access and core
+ *    checks the working-copy guard, then rejects the id. Core evaluates field
+ *    access and validation only after the id check, so this probe says
+ *    nothing about the submitted fields.
+ *  - `none` — Drupal evaluated nothing about the write. The connector may
+ *    still have read from Drupal (the existing entity, field definitions).
+ */
+
+/** No server-side preflight ran. */
+export const PREFLIGHT_NONE = "none";
+
+/** Core's PATCH working-copy guard was probed with an empty, id-mismatched body. */
+export const PREFLIGHT_CORE_GUARD = "core_patch_guard";
+
+/** Sentinel's non-saving draft endpoint evaluated the real payload. */
+export const PREFLIGHT_SENTINEL_DRAFT = "sentinel_draft";
+
+const CHECKED = "checked";
+const NOT_CHECKED = "not_checked";
+
+const CAVEAT_CORE_GUARD =
+  "Field access and entity validation were NOT checked. The server-side probe carried no fields: " +
+  "it checked entity update access and core's working-copy guard only. " +
+  "The real write can still fail with a field-access 403 or a validation 422.";
+
+const CAVEAT_NONE_WRITE =
+  "Drupal did not evaluate this write. Entity access, field access and entity validation were NOT checked. " +
+  "This preview shows the payload the connector would send after its own policy checks; " +
+  "the real write can still fail with a 403 or a validation 422.";
+
+const CAVEAT_NONE_DELETE =
+  "Drupal did not evaluate this delete. Drupal's delete access for this entity was NOT checked; " +
+  "only the connector's own policy was. The real delete can still fail with a 403 or 404.";
+
+/**
+ * Describe what a dryRun preview checked.
+ *
+ * Fails closed: an unknown or missing `preflight` is reported as `none`, so a
+ * caller that forgets to pass it cannot claim a check that did not run.
+ *
+ * @param {object} args
+ * @param {"create"|"update"|"delete"|string} args.operation Previewed operation.
+ * @param {?string} [args.preflight] One of the PREFLIGHT_* constants.
+ * @returns {{checks: {serverPreflight: string, connectorPolicy: string, entityAccess: string, revisionGuard: string, fieldAccess: string, entityValidation: string}, caveat?: string}}
+ */
+export function dryRunChecks({ operation, preflight } = {}) {
+  const sentinel = preflight === PREFLIGHT_SENTINEL_DRAFT;
+  const core = preflight === PREFLIGHT_CORE_GUARD;
+  const contacted = sentinel || core;
+  const checks = {
+    serverPreflight: sentinel ? PREFLIGHT_SENTINEL_DRAFT : core ? PREFLIGHT_CORE_GUARD : PREFLIGHT_NONE,
+    connectorPolicy: CHECKED,
+    entityAccess: contacted ? CHECKED : NOT_CHECKED,
+    revisionGuard: contacted ? CHECKED : NOT_CHECKED,
+    fieldAccess: sentinel ? CHECKED : NOT_CHECKED,
+    entityValidation: sentinel ? CHECKED : NOT_CHECKED,
+  };
+  if (sentinel) return { checks };
+  if (core) return { checks, caveat: CAVEAT_CORE_GUARD };
+  return { checks, caveat: operation === "delete" ? CAVEAT_NONE_DELETE : CAVEAT_NONE_WRITE };
+}