drupal-mcp-connector 2.19.0 → 2.20.0

package/src/tools/drush.js

@@ -26,7 +26,10 @@ import { readFileSync }  from "fs";
 import { homedir }       from "os";
 import { join, resolve, normalize } from "path";
 import { getSiteConfig } from "../lib/config.js";
-import { resolveSecurityConfig, assertNotReadOnly, SecurityError } from "../lib/security.js";
+import {
+  resolveSecurityConfig, assertNotReadOnly, assertDestructiveAllowed, assertModuleUninstallAllowed,
+  assertCoreExtensionChangeAllowed, isCoreExtensionConfig, SecurityError,
+} from "../lib/security.js";
 import { validateMachineName, validateSqlQuery, sanitizeSshArg } from "../lib/validate.js";
 
 // ---------------------------------------------------------------------------
@@ -128,8 +131,11 @@ function resolveKeyPath(rawPath) {
  * Exported so the audit tool groups can reuse the hardened bridge for their
  * drush fallback paths (e.g. config:status, pm:list, watchdog:show) without
  * re-implementing SSH handling.
+ *
+ * @param {{confirm?: "yes"|"no"}} [options] - how Drush confirmation prompts are
+ *   answered. Default "yes". "no" makes Drush cancel at any prompt.
  */
-export function sshDrush(site, drushArgs, timeoutMs = 30000) {
+export function sshDrush(site, drushArgs, timeoutMs = 30000, { confirm = "yes" } = {}) {
   const sshCfg  = getDrushConfig(site);
   assertCommandAllowed(sshCfg, drushArgs[0]);
   const keyPath = resolveKeyPath(sshCfg.keyPath);
@@ -143,7 +149,10 @@ export function sshDrush(site, drushArgs, timeoutMs = 30000) {
   // Build the command: cd to Drupal root, then run vendor drush with escaped args
   const escapedArgs = drushArgs.map(sanitizeSshArg).join(" ");
   const drushBin    = `${drupalRoot}/vendor/bin/drush`;
-  const command     = `cd ${sanitizeSshArg(drupalRoot)} && ${drushBin} ${escapedArgs} --yes`;
+  // Every prompt is answered for the non-interactive session: yes by default,
+  // no when the caller must not let Drush widen the operation (#346).
+  const answer      = confirm === "no" ? "--no" : "--yes";
+  const command     = `cd ${sanitizeSshArg(drupalRoot)} && ${drushBin} ${escapedArgs} ${answer}`;
 
   console.error(`[drush-bridge] ${site._name}: drush ${redactSecretArgs(drushArgs)}`);
 
@@ -175,9 +184,17 @@ export function sshDrush(site, drushArgs, timeoutMs = 30000) {
 
         stream.on("close", (code) => {
           if (code !== 0) {
-            settle(reject, new Error(
+            const failure = new Error(
               `Drush exited ${code}: ${(stderr.trim() || stdout.trim()).slice(0, 500)}`
-            ));
+            );
+            // Kept off the message: callers that need to read Drush's own
+            // output (the cascade list, #346) get it without it reaching the client.
+            Object.defineProperties(failure, {
+              exitCode: { value: code },
+              drushStdout: { value: stdout },
+              drushStderr: { value: stderr },
+            });
+            settle(reject, failure);
           } else {
             settle(resolve, stdout.trim());
           }
@@ -302,15 +319,94 @@ async function configExport({ site: siteName }) {
   return { success: true, message: "Configuration exported to sync directory." };
 }
 
+/**
+ * Read the config names `drush config:status` reports as changed.
+ *
+ * Drush prints nothing, `[]` or `{}` when active config matches the sync
+ * directory. Otherwise it prints an object keyed by config name, or a list of
+ * `{ name, state }` rows. Any other output is not understood.
+ * @param {string} output Trimmed stdout of `config:status --format=json`.
+ * @returns {?string[]} Changed config names, or null when the output is not understood.
+ */
+function changedConfigNames(output) {
+  if (!output) return [];
+  const data = parseDrush(output);
+  if (Array.isArray(data)) {
+    const names = data.map((row) => (row && typeof row === "object" ? row.name : undefined));
+    return names.every((name) => typeof name === "string" && name) ? names : null;
+  }
+  if (data && typeof data === "object") {
+    // Keyed by config name. A row's own `name` is read too, so an object keyed
+    // by row index cannot hide a config name from the check.
+    const rowNames = Object.values(data)
+      .map((row) => (row && typeof row === "object" ? row.name : undefined))
+      .filter((name) => typeof name === "string" && name);
+    return [...Object.keys(data), ...rowNames];
+  }
+  return null;
+}
+
+/**
+ * Refuse a config import that would change core.extension (#349).
+ *
+ * `config:import` uninstalls every module that core.extension in the sync
+ * directory no longer lists, and the bridge answers the prompt "yes". The
+ * connector cannot read the sync directory, so it cannot tell which modules
+ * those are. It reads `config:status`, a read-only command, and refuses when
+ * core.extension is among the changed objects. Fails closed: if the status
+ * cannot be read or understood, nothing is imported.
+ *
+ * The sync directory can change between this read and the import. The check
+ * narrows the path; it does not close a race with someone who can write there.
+ * @param {object} site Resolved site config.
+ * @param {object} sec Resolved security config.
+ * @returns {Promise<void>}
+ * @throws {SecurityError} if core.extension differs, or the status is unreadable.
+ */
+async function assertImportKeepsCoreExtension(site, sec) {
+  if (sec.allowCoreExtensionChange === true && !sec.coreExtensionChangeError) return;
+  const unchecked = "The config import was refused because core.extension could not be checked first. Nothing was imported.";
+  let output;
+  try {
+    output = await sshDrush(site, ["config:status", "--format=json"]);
+  } catch (err) {
+    if (err instanceof SecurityError) {
+      throw new SecurityError(
+        `${unchecked} The check runs \`drush config:status\`, a read-only command, and this site's ` +
+        "drushSsh.allowedCommands does not list it. An operator must add \"config:status\" to allowedCommands."
+      );
+    }
+    throw new SecurityError(`${unchecked} \`drush config:status\` failed: ${String(err?.message ?? err).slice(0, 300)}`);
+  }
+  const names = changedConfigNames(output);
+  if (!names) {
+    throw new SecurityError(`${unchecked} The output of \`drush config:status --format=json\` was not understood.`);
+  }
+  if (names.some(isCoreExtensionConfig)) {
+    assertCoreExtensionChangeAllowed(
+      sec,
+      "The config import was refused because core.extension differs between the site and the sync directory. " +
+      "Importing it installs and uninstalls modules, and can uninstall a protected one. " +
+      "The connector cannot read the sync directory, so it cannot tell which modules would change. Nothing was imported."
+    );
+  }
+}
+
 /**
  * Import config from the sync directory into the DB (`drush config:import`).
+ *
+ * Refused when core.extension differs, unless the operator set
+ * `security.allowCoreExtensionChange` (#349).
  * @param {object} args - { site? }.
  * @returns {Promise<{success: boolean, message: string}>}
- * @throws {SecurityError} If the site is read-only.
+ * @throws {SecurityError} If the site is read-only, core.extension differs, or
+ *   `config:status` cannot be read.
  */
 async function configImport({ site: siteName }) {
   const site = getSiteConfig(siteName);
-  assertNotReadOnly(resolveSecurityConfig(site), "drush config:import");
+  const sec = resolveSecurityConfig(site);
+  assertNotReadOnly(sec, "drush config:import");
+  await assertImportKeepsCoreExtension(site, sec);
   await sshDrush(site, ["config:import"]);
   return { success: true, message: "Configuration imported from sync directory." };
 }
@@ -366,25 +462,103 @@ async function securityUpdates({ site: siteName }) {
  * @throws {Error} If moduleName is not a valid machine name.
  */
 async function enableModule({ site: siteName, moduleName }) {
+  validateMachineName(moduleName, "moduleName"); // first: an invalid name never reaches a message
   const site = getSiteConfig(siteName);
   assertNotReadOnly(resolveSecurityConfig(site), `pm:enable ${moduleName}`);
-  validateMachineName(moduleName, "moduleName"); // throws if invalid
   await sshDrush(site, ["pm:enable", moduleName]);
   return { success: true, message: `Module "${moduleName}" enabled.` };
 }
 
 /**
- * Uninstall a module (`drush pm:uninstall`). Name is validated as a machine name.
+ * Drush prints this before it asks to confirm a cascading uninstall. The list
+ * may wrap over several lines. Case-sensitive on purpose: module names are
+ * lowercase, so the capture stops at the next sentence ("Do you want to…").
+ */
+const CASCADE_LIST_RE = /The following extensions will be uninstalled:\s*([a-z0-9_,\s]+)/;
+
+/**
+ * Read the modules Drush said it would uninstall from a cancelled run.
+ * @param {Error} failure Rejection from sshDrush().
+ * @returns {?string[]} Machine names, or null when Drush printed no list.
+ */
+function cascadeList(failure) {
+  return parseCascadeList(`${failure?.drushStdout ?? ""}\n${failure?.drushStderr ?? ""}`);
+}
+
+/**
+ * @param {string} output Drush output.
+ * @returns {?string[]} Machine names Drush said it would uninstall, or null.
+ */
+function parseCascadeList(output) {
+  const match = CASCADE_LIST_RE.exec(output);
+  if (!match) return null;
+  return match[1].split(",").map((name) => name.trim()).filter((name) => /^[a-z][a-z0-9_]*$/.test(name));
+}
+
+/**
+ * Uninstall a module (`drush pm:uninstall`).
+ *
+ * Refused for a module on the site's protected list (#346): the default list in
+ * `security.js`, plus `security.protectedModules`, minus the explicit
+ * `security.allowProtectedModuleUninstall`.
+ *
+ * `pm:uninstall` also uninstalls every module that depends on the named one,
+ * after a prompt. The bridge answers that prompt "no", so a cascade is
+ * cancelled by Drush and nothing is uninstalled; a protected module cannot be
+ * removed through one of its dependencies. The caller uninstalls each
+ * dependent by name, and each name goes through the same check.
+ *
  * @param {object} args - { site?, moduleName }.
- * @returns {Promise<{success: boolean, message: string}>}
- * @throws {SecurityError} If the site is read-only.
- * @throws {Error} If moduleName is not a valid machine name.
+ * @returns {Promise<{success: boolean, message: string, alsoUninstalled?: string[], warning?: string}>}
+ *   `alsoUninstalled` is set only if Drush ran a cascade despite the "no" answer.
+ * @throws {Error} If moduleName is not a valid machine name. Checked first, so
+ *   an invalid name never reaches a message.
+ * @throws {SecurityError} If the site is read-only, deletes are not allowed,
+ *   the module is protected, the protected-module config is malformed, or the
+ *   uninstall would cascade to dependents.
  */
 async function disableModule({ site: siteName, moduleName }) {
-  const site = getSiteConfig(siteName);
-  assertNotReadOnly(resolveSecurityConfig(site), `pm:uninstall ${moduleName}`);
   validateMachineName(moduleName, "moduleName");
-  await sshDrush(site, ["pm:uninstall", moduleName]);
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertNotReadOnly(sec, `pm:uninstall ${moduleName}`);
+  assertDestructiveAllowed(sec, "module", moduleName);
+  assertModuleUninstallAllowed(sec, moduleName);
+  let stdout;
+  try {
+    stdout = await sshDrush(site, ["pm:uninstall", moduleName], 30000, { confirm: "no" });
+  } catch (failure) {
+    const list = cascadeList(failure);
+    if (!list) throw failure;
+    const dependents = list.filter((name) => name !== moduleName);
+    if (dependents.length === 0) {
+      // Drush 13 prompts only for a cascade. Older releases prompt on every
+      // uninstall, and the "no" answer cancels those too.
+      throw new SecurityError(
+        `Drush asked to confirm uninstalling "${moduleName}" alone and the bridge answers "no", so nothing was uninstalled. ` +
+        "This Drush release prompts on every uninstall; the cascade guard needs Drush 13 or later on the site."
+      );
+    }
+    const guarded = dependents.filter((name) => sec.protectedModules.includes(name));
+    throw new SecurityError(
+      `Uninstalling "${moduleName}" would also uninstall: ${dependents.join(", ")}. ` +
+      "Nothing was uninstalled. " +
+      (guarded.length ? `Protected: ${guarded.join(", ")}. ` : "") +
+      "Uninstall each dependent by name first; each one goes through the protected-module check."
+    );
+  }
+  // Drush should have cancelled a cascade. If it printed a cascade list and
+  // still exited 0, say what it removed instead of reporting a clean uninstall.
+  const alsoUninstalled = (parseCascadeList(String(stdout ?? "")) ?? []).filter((name) => name !== moduleName);
+  if (alsoUninstalled.length) {
+    return {
+      success: true,
+      message: `Module "${moduleName}" uninstalled.`,
+      alsoUninstalled,
+      warning: "Drush did not cancel the cascade prompt, so these dependents were uninstalled too: " +
+        `${alsoUninstalled.join(", ")}. Check the Drush version on the site.`,
+    };
+  }
   return { success: true, message: `Module "${moduleName}" uninstalled.` };
 }
 
@@ -514,7 +688,7 @@ export const definitions = [
   { name: "drupal_drush_status",           description: "Get Drupal site status via `drush status` — version, DB, file paths, active config.", inputSchema: { type: "object", properties: { site: { type: "string" } } } },
   { name: "drupal_drush_config_status",    description: "Check if active config is in sync with the sync directory. Returns out-of-sync items if any.", inputSchema: { type: "object", properties: { site: { type: "string" } } } },
   { name: "drupal_drush_config_export",    description: "Export active configuration to the sync directory. Requires write access.", inputSchema: { type: "object", properties: { site: { type: "string" } } } },
-  { name: "drupal_drush_config_import",    description: "Import configuration from the sync directory into the database. Requires write access. Confirm with user before running on production.", inputSchema: { type: "object", properties: { site: { type: "string" } } } },
+  { name: "drupal_drush_config_import",    description: "Import configuration from the sync directory into the database. Requires write access. Confirm with user before running on production. Reads `drush config:status` first and refuses the import when `core.extension` differs, because such an import installs and uninstalls modules and can remove a protected one; nothing is imported, and the status read must be allowed in `drushSsh.allowedCommands`. Use drupal_drush_module_enable or drupal_drush_module_disable for a module change. Only an operator can allow it, with `allowCoreExtensionChange` in site config (see drupal_security_info).", inputSchema: { type: "object", properties: { site: { type: "string" } } } },
   { name: "drupal_drush_updatedb",         description: "Run pending database updates via `drush updatedb`. Always run after deploying module updates.", inputSchema: { type: "object", properties: { site: { type: "string" } } } },
   { name: "drupal_drush_security_updates", description: "List modules with known security advisories via `drush pm:security`.", inputSchema: { type: "object", properties: { site: { type: "string" } } } },
   {
@@ -529,7 +703,7 @@ export const definitions = [
   },
   {
     name: "drupal_drush_module_disable",
-    description: "Uninstall a Drupal module. Irreversible for module-stored data. Confirm with user.",
+    description: "Uninstall a Drupal module. Irreversible for module-stored data. Confirm with user. Refused for a protected module: governance, integrity, secrets, auth and API modules such as mcp_sentinel, audit_chain, key, simple_oauth and jsonapi (see `protectedModules` in drupal_security_info). Only an operator can change that list, in site config. Also refused when the uninstall would cascade to dependents: nothing is uninstalled, the dependents are named, and each must be uninstalled by name first.",
     inputSchema: { type: "object", required: ["moduleName"], properties: { site: { type: "string" }, moduleName: { type: "string", pattern: "^[a-z][a-z0-9_]*$" } } },
   },
   {

package/src/tools/entities.js

@@ -18,6 +18,7 @@ import {
 } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { dryRunChecks, PREFLIGHT_NONE } from "../lib/dry-run-checks.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
   redactCanonicalEntity, getSecuritySummary,
@@ -71,7 +72,12 @@ async function createEntity({ site: siteName, entityType, bundle, attributes = {
   assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
-  if (dryRun) return { dryRun: true, operation: "create", entityType, bundle, attributes, relationships: resolvedRelationships };
+  if (dryRun) {
+    return {
+      dryRun: true, operation: "create", entityType, bundle, attributes, relationships: resolvedRelationships,
+      ...dryRunChecks({ operation: "create", preflight: PREFLIGHT_NONE }),
+    };
+  }
   const created = await backend.createEntity({ entityType, bundle, attributes, relationships: resolvedRelationships });
   if (entityType === "paragraph") {
     const revisionId = await resolveParagraphRevisionId(backend, created, bundle);
@@ -125,6 +131,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
     return {
       dryRun: true, operation: "update", entityType, bundle, id,
       attributes: safeAttributes, relationships: resolvedRelationships,
+      ...dryRunChecks({ operation: "update", preflight: patchTarget.preflight }),
     };
   }
   const result = await updateEntityGuarded(backend, {
@@ -157,7 +164,12 @@ async function deleteEntity({ site: siteName, entityType, bundle, id, dryRun = f
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertDeleteAllowed(sec, entityType, bundle, id);
-  if (dryRun) return { dryRun: true, operation: "delete", entityType, bundle, id };
+  if (dryRun) {
+    return {
+      dryRun: true, operation: "delete", entityType, bundle, id,
+      ...dryRunChecks({ operation: "delete", preflight: PREFLIGHT_NONE }),
+    };
+  }
   const backend = await resolveBackend(site);
   await backend.deleteEntity({ entityType, bundle, id });
   return { success: true, deletedId: id, entityType, bundle };
@@ -277,14 +289,14 @@ export const definitions = [
         bundle:        { type: "string" },
         attributes:    { type: "object", description: "Field values keyed by Drupal machine name" },
         relationships: { type: "object", description: "Relationship data keyed by field name" },
-        dryRun:        { type: "boolean", default: false, description: "Validate and return a preview of the create without committing." },
+        dryRun:        { type: "boolean", default: false, description: "Return a preview of the payload without committing. Drupal does not evaluate the write: entity access, field access and entity validation are NOT checked, so the real create can still fail with a 403 or a validation 422. The result's `checks` block and `caveat` say what was and was not checked." },
         returning:     RETURNING_SCHEMA,
       },
     },
   },
   {
     name: "drupal_entity_update",
-    description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change. Published moderated targets without an explicit attributes.moderation_state default to moderation_state 'draft' (forward revision). Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved. On moderated targets a non-saving PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents.",
+    description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change. Published moderated targets without an explicit attributes.moderation_state default to moderation_state 'draft' (forward revision). Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved. On moderated targets a non-saving PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran.",
     inputSchema: {
       type: "object", required: ["entityType", "bundle", "id"],
       properties: {
@@ -295,7 +307,7 @@ export const definitions = [
         langcode:      { type: "string", description: "Target language for an unpublished working translation (nodes). Continues that translation via Sentinel." },
         attributes:    { type: "object" },
         relationships: { type: "object" },
-        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun." },
+        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun." },
         returning:     RETURNING_SCHEMA,
       },
     },
@@ -310,7 +322,7 @@ export const definitions = [
         entityType: { type: "string" },
         bundle:     { type: "string" },
         id:         { type: "string" },
-        dryRun:     { type: "boolean", default: false, description: "Validate and return a preview of the delete without committing." },
+        dryRun:     { type: "boolean", default: false, description: "Return a preview of the delete without committing. Drupal does not evaluate the delete: Drupal's delete access for the entity is NOT checked, only the connector's own policy. The result's `checks` block says so." },
       },
     },
   },

package/src/tools/fields.js

@@ -27,6 +27,17 @@ const SAMPLING_NOTE =
   "cardinality, allowed values, widget/storage settings) use the Drush bridge " +
   "(field config), which reads the Field API directly.";
 
+const NOT_VISIBLE_NOTE =
+  "These fields are defined in Drupal's Field API for this bundle but are absent from the sampled entity. " +
+  "JSON:API keeps the key of an empty field and leaves out a field the account may not view, so each one is " +
+  "most likely denied to this account. It may also be disabled or renamed in JSON:API. " +
+  "An absent field is not an empty field: do not read these as unset. The list covers configurable fields " +
+  "only (field_config, first 50) and one sampled entity, so it may be incomplete.";
+
+const DEFINITIONS_UNAVAILABLE_NOTE =
+  " Field definitions (JSON:API field_config) are not readable here, so a field this account may not view " +
+  "cannot be detected: JSON:API leaves a view-denied field out of the resource, and it is simply missing from this list.";
+
 const EMPTY_SCHEMA_NOTE =
   "No entities of this type/bundle exist yet, so sampling found no fields. " +
   "Create one entity, or use the Drush bridge (Field API), to introspect fields.";
@@ -75,8 +86,10 @@ function relationshipField(name) {
  * @param {object} args - { site?, type|entityType, bundle? }. `bundle` defaults
  *   to the entity type (matching Drupal's single-bundle types, e.g. `user`).
  * @returns {Promise<{entityType: string, bundle: string, resourceType?: string,
- *   approximate: true, fieldCount: number, fields: object[], note: string,
- *   authoritativeSource: string}>}
+ *   approximate: true, fieldCount: number, fields: object[],
+ *   fieldDefinitions: "available"|"unavailable",
+ *   notVisible?: Array<{name: string, translatable: boolean}>, notVisibleNote?: string,
+ *   note: string, authoritativeSource: string}>}
  * @throws {SecurityError} If reading the type/bundle is not permitted.
  * @throws {Error} If no entity type is given under either name.
  */
@@ -111,6 +124,20 @@ async function describeFields({ site: siteName, type, entityType: entityTypeArg,
 
   const sampledEmpty = fields.length === 0;
 
+  // #337: a view-denied field is left out of the JSON:API resource, so sampling
+  // never sees it. The Field API definitions already read above name the
+  // configurable fields of the bundle; any of those missing from the sampled
+  // KEYS (not values — an empty field keeps its key) is listed apart. Nothing
+  // is claimed when no entity was sampled or the definitions are unreadable.
+  const definitionsAvailable = translatableMap.size > 0;
+  const sampledNames = new Set(fields.map((field) => field.name));
+  const notVisible = definitionsAvailable && !sampledEmpty
+    ? [...translatableMap.entries()]
+      .filter(([name]) => !sampledNames.has(name))
+      .map(([name, value]) => ({ name, translatable: Boolean(value) }))
+      .sort((a, b) => a.name.localeCompare(b.name))
+    : null;
+
   return {
     entityType: schema.entityType ?? entityType,
     bundle: schema.bundle ?? resolvedBundle,
@@ -118,7 +145,12 @@ async function describeFields({ site: siteName, type, entityType: entityTypeArg,
     approximate: true,
     fieldCount: fields.length,
     fields,
-    note: sampledEmpty ? EMPTY_SCHEMA_NOTE : SAMPLING_NOTE,
+    fieldDefinitions: definitionsAvailable ? "available" : "unavailable",
+    ...(notVisible ? { notVisible } : {}),
+    ...(notVisible?.length ? { notVisibleNote: NOT_VISIBLE_NOTE } : {}),
+    note: sampledEmpty
+      ? EMPTY_SCHEMA_NOTE
+      : SAMPLING_NOTE + (definitionsAvailable ? "" : DEFINITIONS_UNAVAILABLE_NOTE),
     authoritativeSource: "drush-bridge (Drupal Field API)",
   };
 }
@@ -136,7 +168,11 @@ export const definitions = [
       "schema SAMPLING (an existing entity), so results are approximate — only " +
       "populated fields are visible and required/cardinality/allowedValues are " +
       "inferred from value shape. When JSON:API field_config is readable, translatable " +
-      "is copied from Field API; omitted means unknown, not false. Authoritative field " +
+      "is copied from Field API; omitted means unknown, not false. A field this account may not " +
+      "view is left out of the JSON:API resource, so it is NOT in `fields` and looks like a field that " +
+      "does not exist. When field_config is readable (`fieldDefinitions: 'available'`), fields defined " +
+      "for the bundle but absent from the sampled entity are listed apart as `notVisible`; when it is " +
+      "not, denied fields cannot be detected. Absent is not empty. Authoritative field " +
       "metadata comes from the Drush bridge (Field API). Use this before creating/updating entities to learn field names.",
     inputSchema: {
       type: "object",

package/src/tools/graphql.js

@@ -16,6 +16,7 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { drupalGraphqlFetch } from "../lib/drupal-fetch.js";
+import { cleanGraphqlErrors, describeGraphqlErrors } from "../lib/error-body.js";
 import {
   resolveSecurityConfig, assertGraphqlAllowed, assertGraphqlMutationAllowed,
 } from "../lib/security.js";
@@ -30,7 +31,8 @@ import {
  * @param {object} args - { site?, query, variables?, operationName? }.
  * @returns {Promise<{data: object, warnings?: string[]}>} On a clean response,
  *   just `data`. When the server returns errors alongside partial `data`, the
- *   error messages are surfaced as `warnings` rather than thrown.
+ *   error messages are surfaced as `warnings` rather than thrown. Each message
+ *   is cleaned and the list is bounded (see `cleanGraphqlErrors`).
  * @throws {Error} If the response carries errors and no data at all.
  */
 async function runGraphql({ site: siteName, query, variables = {}, operationName }) {
@@ -41,10 +43,11 @@ async function runGraphql({ site: siteName, query, variables = {}, operationName
   const json = await drupalGraphqlFetch(site, { query, variables, operationName });
 
   if (json.errors?.length) {
-    const messages = json.errors.map((e) => e.message).join("; ");
-    if (!json.data) throw new Error(`GraphQL errors: ${messages}`);
+    // The messages are untrusted text: cleaned and bounded, like the detail of
+    // a non-2xx response (#356). `data` is returned as received.
+    if (!json.data) throw new Error(`GraphQL errors: ${describeGraphqlErrors(json.errors)}`);
     // Partial result — return data AND surface errors as a warning
-    return { data: json.data, warnings: json.errors.map((e) => e.message) };
+    return { data: json.data, warnings: cleanGraphqlErrors(json.errors).map((e) => e.message) };
   }
 
   return { data: json.data };
@@ -90,6 +93,8 @@ async function introspectGraphql({ site: siteName, typeName }) {
       }
     `;
     const json = await drupalGraphqlFetch(site, { query, variables: { name: typeName } });
+    // A failed lookup is not a missing type: report what the server said.
+    if (!json.data?.__type && json.errors?.length) throw new Error(describeGraphqlErrors(json.errors));
     if (!json.data?.__type) throw new Error(`Type '${typeName}' not found in schema.`);
     return json.data.__type;
   }
@@ -112,7 +117,7 @@ async function introspectGraphql({ site: siteName, typeName }) {
   `;
   const json = await drupalGraphqlFetch(site, { query });
   if (json.errors?.length) {
-    throw new Error(json.errors.map((e) => e.message).join("; "));
+    throw new Error(describeGraphqlErrors(json.errors));
   }
 
   const schema = json.data.__schema;

package/src/tools/nodes.js

@@ -18,6 +18,7 @@ import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA, omit
 import { resolveErrRelationships, relationshipsWereSent, paragraphPinsFromEntity } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { dryRunChecks, PREFLIGHT_NONE } from "../lib/dry-run-checks.js";
 import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/sentinel-draft.js";
 import { paragraphResourceVersion } from "./paragraphs.js";
 import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
@@ -412,7 +413,10 @@ async function createNode({ site: siteName, type, title, body, summary, format,
   assertPublishAllowed(sec, attributes);
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
   if (dryRun) {
-    const preview = { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes, relationships: resolvedRelationships };
+    const preview = {
+      dryRun: true, operation: "create", entityType: "node", bundle: type, attributes, relationships: resolvedRelationships,
+      ...dryRunChecks({ operation: "create", preflight: PREFLIGHT_NONE }),
+    };
     return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(preview) : preview;
   }
   // Alias handling: an explicit `path.alias` is set as a manual alias; otherwise
@@ -497,6 +501,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
     const preview = {
       dryRun: true, operation: "update", entityType: "node", bundle: type, id,
       attributes, relationships: resolvedRelationships,
+      ...dryRunChecks({ operation: "update", preflight: patchTarget.preflight }),
     };
     return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(preview) : preview;
   }
@@ -556,7 +561,12 @@ async function deleteNode({ site: siteName, type, id, dryRun = false }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertDeleteAllowed(sec, "node", type, id);
-  if (dryRun) return { dryRun: true, operation: "delete", entityType: "node", bundle: type, id };
+  if (dryRun) {
+    return {
+      dryRun: true, operation: "delete", entityType: "node", bundle: type, id,
+      ...dryRunChecks({ operation: "delete", preflight: PREFLIGHT_NONE }),
+    };
+  }
   const backend = await resolveBackend(site);
   await backend.deleteEntity({ entityType: "node", bundle: type, id });
   return { success: true, deletedId: id };
@@ -627,14 +637,14 @@ export const definitions = [
         moderationState: { type: "string", description: "Moderation state for content_moderation types, e.g. 'draft' or 'published'. Takes precedence over status." },
         fields:  { type: "object", description: "Scalar/attribute field values keyed by Drupal machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Do NOT put entity-reference fields here — Drupal rejects them as attributes; use `relationships`." },
         relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value: { field_resource_type: { data: { type: 'taxonomy_term--resource_type', id: '<uuid>' } } }. Multi-value: { field_tags: { data: [{ type: 'taxonomy_term--tags', id: '<uuid>' }] } }." },
-        dryRun:  { type: "boolean", default: false, description: "Validate and return a preview of the write without committing." },
+        dryRun:  { type: "boolean", default: false, description: "Return a preview of the payload without committing. Drupal does not evaluate the write: entity access, field access and entity validation are NOT checked, so the real create can still fail with a 403 or a validation 422. The result's `checks` block and `caveat` say what was and was not checked." },
         returning: RETURNING_SCHEMA,
       },
     },
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. Published languages are not converted into drafts; dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.",
+    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. Published languages are not converted into drafts; dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -650,7 +660,7 @@ export const definitions = [
         langcode: { type: "string", description: "Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode." },
         fields:  { type: "object", description: "Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here." },
         relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot. Image alt on a translation uses the existing file UUID plus meta.alt; replacing the file is refused." },
-        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun." },
+        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun." },
         returning: RETURNING_SCHEMA,
       },
     },
@@ -664,7 +674,7 @@ export const definitions = [
         site: { type: "string" },
         type: { type: "string" },
         id:   { type: "string", description: "Node UUID" },
-        dryRun: { type: "boolean", default: false, description: "Validate and return a preview of the delete without committing." },
+        dryRun: { type: "boolean", default: false, description: "Return a preview of the delete without committing. Drupal does not evaluate the delete: Drupal's delete access for the entity is NOT checked, only the connector's own policy. The result's `checks` block says so." },
       },
     },
   },

package/src/tools/paragraphs.js

@@ -57,7 +57,7 @@ import {
  * @param {number|string|null|undefined} [revisionId] Current revision id.
  * @returns {{type: string, id: string, meta?: {target_revision_id: number}}}
  */
-export function embedRef(bundle, id, revisionId) {
+function embedRef(bundle, id, revisionId) {
   return embedParagraphRef(bundle, id, revisionId);
 }
 

package/src/tools/reports-config.js

@@ -20,7 +20,7 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveSecurityConfig, assertConfigReadAllowed } from "../lib/security.js";
 import { gatedReport } from "../lib/reports-support.js";
-import { callServerTool, callBoundModuleTool, SERVER_TOOLS, toolResultData } from "../lib/server-tools.js";
+import { callGovernedServerTool, callBoundModuleTool, toolResultData } from "../lib/server-tools.js";
 import { runPrivileged, serverToolsConfigured, drushConfigured } from "../lib/audit-sources.js";
 import { sshDrush, parseDrush } from "./drush.js";
 
@@ -71,7 +71,7 @@ async function readConfig(site, name) {
     }));
   }
   if (serverToolsConfigured(site)) {
-    try { return toolResultData(await callServerTool(site, SERVER_TOOLS.configGet, { name })); }
+    try { return toolResultData(await callGovernedServerTool(site, "configGet", { name })); }
     catch (err) { if (!drushConfigured(site)) throw err; }
   }
   return parseDrush(await sshDrush(site, ["config:get", name, "--format=json"]));
@@ -93,7 +93,7 @@ async function listConfigNames(site, prefix) {
     })));
   }
   if (serverToolsConfigured(site)) {
-    try { return pickConfigNames(toolResultData(await callServerTool(site, SERVER_TOOLS.configList, { prefix }))); }
+    try { return pickConfigNames(toolResultData(await callGovernedServerTool(site, "configList", { prefix }))); }
     catch (err) { if (!drushConfigured(site)) throw err; }
   }
   const out = await sshDrush(site, ["sql:query", `SELECT name FROM config WHERE collection = '' AND name LIKE '${prefix}%'`]);