drupal-mcp-connector 2.17.0 → 2.18.0

package/src/lib/module-tools.js

@@ -0,0 +1,241 @@
+/** Module-owned schemas and behavior, exposed only by explicit local tool policy. */
+import { createHash } from "node:crypto";
+import Ajv from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { listServerTools, callServerTool, toolResultData } from "./server-tools.js";
+import { listResolvableSiteConfigs, securityMiddleware } from "./dispatch.js";
+import { getRequestIdentity, principalHasScope, resolveGrantedSites } from "./principal.js";
+import { resolveSecurityConfig, SecurityError } from "./security.js";
+import { assertSourceGovernance, GovernanceError } from "./governance.js";
+import { DataFlowBudgetError } from "./data-flow.js";
+import { toolError } from "./errors.js";
+import { withResolvedTarget } from "./site-target.js";
+
+const PREFIX = "drupal_module_";
+const OPERATIONS = new Set(["read", "write", "delete"]);
+const CAPABILITIES = new Map([
+  ["publish", "allowPublish"], ["configRead", "allowConfigRead"],
+  ["configWrite", "allowConfigWrite"], ["graphql", "allowGraphql"],
+]);
+const MAX_BYTES = 262144;
+const MAX_TOOLS = 256;
+
+function bounded(value, limit = MAX_BYTES) {
+  if (Buffer.byteLength(JSON.stringify(value) ?? "") > limit) {
+    throw new SecurityError("Module tool payload exceeds the protocol ceiling.");
+  }
+}
+
+function entries(sites) {
+  const result = new Map();
+  for (const site of sites) {
+    const config = site.serverTools?.modules;
+    if (!config) continue;
+    if (!/^[a-z][a-z0-9_]{0,23}$/.test(config.namespace ?? "")) {
+      throw new SecurityError("Module tools require a stable namespace.");
+    }
+    for (const [alias, policy] of Object.entries(config.tools ?? {})) {
+      if (!/^[a-z][a-z0-9_]{0,47}$/.test(alias) || !policy ||
+          !/^[A-Za-z0-9_.-]{1,128}$/.test(policy.name ?? "") ||
+          !/^[a-z][a-z0-9_:-]{0,63}$/.test(policy.scope ?? "") ||
+          !OPERATIONS.has(policy.operation) || !Array.isArray(policy.capabilities) ||
+          policy.capabilities.some((cap) => !CAPABILITIES.has(cap) && cap !== "rawSql")) {
+        throw new SecurityError("Invalid module tool policy.");
+      }
+      const name = `${PREFIX}${policy.operation}_${config.namespace}__${alias}`;
+      if (result.has(name) || result.size >= MAX_TOOLS) {
+        throw new SecurityError("Duplicate module namespace or excessive tool policy entries.");
+      }
+      result.set(name, { name, alias, site, policy });
+    }
+  }
+  return result;
+}
+
+function allowed(entry, identity, sites, grants) {
+  const { site, policy } = entry;
+  if (identity && (!principalHasScope(identity, policy.scope) ||
+      !resolveGrantedSites(identity, sites, grants).some((s) => s._name === site._name))) return false;
+  const sec = resolveSecurityConfig(site);
+  if (policy.operation !== "read" && sec.readOnly) return false;
+  if (policy.operation === "delete" && !sec.allowDestructive) return false;
+  return policy.capabilities.every((cap) => cap === "rawSql"
+    ? site.drushSsh?.rawSql === "governed"
+    : Boolean(new Map(Object.entries(sec)).get(CAPABILITIES.get(cap))));
+}
+
+function validator(schema) {
+  if (!schema || schema.type !== "object") throw new Error("Object schema required.");
+  bounded(schema, 65536);
+  // Providers may put constraints beside nullable oneOf types. strictTypes
+  // rejects that valid JSON Schema shape; runtime type checks still apply.
+  const ajv = new Ajv({ strict: true, strictTypes: false, allErrors: false, ownProperties: true });
+  addFormats(ajv);
+  const check = ajv.compile(schema);
+  if (check.$async) throw new Error("Async schemas are unavailable.");
+  return check;
+}
+
+async function catalog(site, list) {
+  // Extensions always require source governance, including development sites.
+  await assertSourceGovernance({ ...site, requireGovernance: true });
+  const found = new Map();
+  const seen = new Set();
+  let cursor;
+  let bytes = 0;
+  for (let page = 0; page < 16; page++) {
+    const result = await list(site, cursor);
+    bounded(result);
+    bytes += Buffer.byteLength(JSON.stringify(result));
+    if (bytes > MAX_BYTES || !Array.isArray(result?.tools)) throw new Error("Invalid module catalog.");
+    for (const tool of result.tools) {
+      if (typeof tool?.name !== "string" || found.has(tool.name) || found.size >= MAX_TOOLS) {
+        throw new Error("Invalid or duplicate module tool.");
+      }
+      found.set(tool.name, tool);
+    }
+    if (result.nextCursor === undefined || result.nextCursor === null) return found;
+    if (typeof result.nextCursor !== "string" || seen.has(result.nextCursor)) throw new Error("Invalid catalog cursor.");
+    cursor = result.nextCursor;
+    seen.add(cursor);
+  }
+  throw new Error("Module catalog page limit exceeded.");
+}
+
+function describe(entry, remote) {
+  const input = validator(remote.inputSchema);
+  const output = remote.outputSchema ? validator(remote.outputSchema) : null;
+  const revision = createHash("sha256").update(JSON.stringify({
+    input: remote.inputSchema, output: remote.outputSchema ?? null, policy: entry.policy,
+  })).digest("hex");
+  return { input, output, revision, definition: {
+    name: entry.name,
+    description: `${String(remote.description ?? remote.name).slice(0, 4096)} [${entry.site._name}]`,
+    inputSchema: {
+      type: "object", additionalProperties: false, required: ["catalogRevision", "arguments"],
+      properties: {
+        catalogRevision: { type: "string", const: revision },
+        arguments: { ...remote.inputSchema, $id: remote.inputSchema.$id ?? `urn:module:input:${revision}` },
+      },
+    },
+    annotations: {
+      readOnlyHint: entry.policy.operation === "read",
+      destructiveHint: entry.policy.operation !== "read",
+      idempotentHint: false, openWorldHint: true,
+    },
+    ...(remote.outputSchema ? { outputSchema: {
+      type: "object", required: ["result", "_target"],
+      properties: {
+        result: { ...remote.outputSchema, $id: remote.outputSchema.$id ?? `urn:module:output:${revision}` },
+        _target: { type: "object" },
+      },
+    } } : {}),
+  } };
+}
+
+/** Reserved module names never fall back to built-in handlers. */
+export function isModuleTool(name) {
+  return typeof name === "string" && name.startsWith(PREFIX);
+}
+
+/** Resolves a local binding without granting access or contacting its provider. */
+export function resolveModuleBinding(site, binding, required) {
+  const bindings = new Map(Object.entries(site.serverTools?.bindings ?? {}));
+  const alias = bindings.get(binding);
+  const entry = [...entries([site]).values()].find((item) => item.alias === alias);
+  if (!entry || entry.policy.operation !== required.operation ||
+      entry.policy.scope !== required.scope ||
+      !required.capabilities.every((cap) => entry.policy.capabilities.includes(cap))) {
+    throw new SecurityError("Module binding is missing or does not satisfy the operation contract.");
+  }
+  return entry;
+}
+
+/**
+ * Build a registry without cross-request catalog or authorization caches.
+ * Transport injection lets unrelated fixture providers prove generic dispatch.
+ */
+export function createModuleToolRegistry({ list = listServerTools, call = callServerTool } = {}) {
+  const registry = {
+    /** Invoke a locally bound compatibility operation through normal discovery. */
+    async callBinding(site, binding, args, required, context = {}) {
+      const entry = resolveModuleBinding(site, binding, required);
+      const ctx = { ...context, sites: [site] };
+      const definition = (await registry.list(ctx)).find((item) => item.name === entry.name);
+      if (!definition) throw new SecurityError("Bound module tool is unavailable for this caller.");
+      const result = await registry.call(entry.name, {
+        arguments: args,
+        catalogRevision: definition.inputSchema.properties.catalogRevision.const,
+      }, ctx);
+      if (result.isError) throw new SecurityError("Bound module tool refused the request; no fallback was attempted.");
+      // Compatibility callers consume the original Tool API result, not the
+      // module registry's result/target envelope. Keep the established shape.
+      const data = result.structuredContent.result;
+      return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data };
+    },
+    async list(context = {}) {
+      const sites = context.sites ?? listResolvableSiteConfigs();
+      const identity = context.identity === undefined ? getRequestIdentity() : context.identity;
+      const enabled = [...entries(sites).values()].filter((entry) => allowed(entry, identity, sites, context.grants));
+      const catalogs = new Map();
+      const definitions = [];
+      for (const entry of enabled) {
+        if (!catalogs.has(entry.site._name)) {
+          try {
+            const found = await securityMiddleware(entry.name, { site: entry.site._name },
+              () => catalog(entry.site, list), { ...context, sites, identity, moduleTool: entry.policy });
+            catalogs.set(entry.site._name, found);
+          }
+          catch {
+            // A failed catalog fetch invalidates this provider for the request.
+            catalogs.set(entry.site._name, new Map());
+          }
+        }
+        try {
+          const remote = catalogs.get(entry.site._name).get(entry.policy.name);
+          if (remote) definitions.push(describe(entry, remote).definition);
+        } catch {
+          // A malformed schema disables only that action, not its siblings.
+        }
+      }
+      return definitions.sort((a, b) => a.name.localeCompare(b.name));
+    },
+    async call(name, args, context = {}) {
+      try {
+        const sites = context.sites ?? listResolvableSiteConfigs();
+        const identity = context.identity === undefined ? getRequestIdentity() : context.identity;
+        const entry = entries(sites).get(name);
+        if (!entry || !allowed(entry, identity, sites, context.grants)) throw new SecurityError("Module tool is not enabled for this caller.");
+        bounded(args);
+        if (!args || Object.keys(args).some((key) => !["arguments", "catalogRevision"].includes(key))) {
+          throw new SecurityError("Invalid module tool arguments.");
+        }
+        const invokeContext = { ...context, sites, identity, moduleTool: entry.policy };
+        return await securityMiddleware(name, { site: entry.site._name }, async () => {
+          const remote = (await catalog(entry.site, list)).get(entry.policy.name);
+          if (!remote) throw new SecurityError("Module tool is no longer available.");
+          const spec = describe(entry, remote);
+          if (args.catalogRevision !== spec.revision || !spec.input(args.arguments)) {
+            throw new SecurityError("Module tool schema changed or arguments are invalid. Refresh tools/list.");
+          }
+          const result = await call(entry.site, entry.policy.name, args.arguments, {
+            maxBytes: MAX_BYTES, preserveErrors: true, retryRejected: entry.policy.operation === "read",
+          });
+          bounded(result);
+          if (!Array.isArray(result?.content) || result.content.some((item) => item.type !== "text")) {
+            throw new Error("Unsupported module result content.");
+          }
+          const data = toolResultData(result);
+          const failed = result.isError === true || data?.success === false;
+          if (!failed && spec.output && !spec.output(data)) throw new Error("Invalid module output schema.");
+          const structuredContent = withResolvedTarget({ result: data }, invokeContext.resolvedTarget);
+          return { content: [{ type: "text", text: JSON.stringify(structuredContent) }], structuredContent, isError: failed };
+        }, invokeContext);
+      } catch (error) {
+        const safe = error instanceof SecurityError || error instanceof GovernanceError || error instanceof DataFlowBudgetError;
+        return toolError(safe ? error : new Error("Module tool unavailable or returned an invalid response. No fallback was attempted."));
+      }
+    },
+  };
+  return registry;
+}

package/src/lib/node-draft-inventory.js

@@ -1,48 +1,5 @@
 /** Sentinel discovery for translation-only node revisions (#297). */
-import { readTranslationInventory } from "./draft-write.js";
-
-/**
- * Read optional inventory, falling back only when the endpoint is unsupported.
- * Permission, transport and malformed-response failures are not absence.
- * @param {object} backend
- * @param {{entityType: string, bundle: string, id: string}} ref
- * @returns {Promise<object|null>}
- */
-export async function readNodeDraftInventory(backend, ref) {
-  if ((ref.entityType !== "node" && ref.entityType !== "media")
-    || typeof backend.rawQuery !== "function"
-    || typeof backend.resourcePath !== "function") return null;
-  let inventory;
-  try {
-    inventory = await readTranslationInventory(backend, ref);
-  } catch (error) {
-    if (/does not provide Sentinel's governed draft-translation endpoint/.test(error.message)) return null;
-    throw error;
-  }
-  const validVid = (vid) => /^[1-9]\d*$/.test(String(vid ?? "")) && Number.isSafeInteger(Number(vid));
-  if (!validVid(inventory.live?.vid)
-    || (inventory.working && (!validVid(inventory.working.vid)
-      || !Array.isArray(inventory.working.translations)
-      || inventory.working.translations.some((row) => !row || typeof row.langcode !== "string"
-        || typeof row.status !== "boolean")))) {
-    throw new Error("Sentinel returned an invalid revision inventory. Re-read before updating.");
-  }
-  return inventory;
-}
-
-/**
- * Ensure inventory discovery does not turn a published language into a draft.
- * Sentinel still validates the revision pair and language on every request.
- * @param {object} inventory
- * @param {string|undefined} langcode
- */
-export function assertInventoryDraftLanguage(inventory, langcode) {
-  const rows = inventory.working?.translations ?? [];
-  if (!langcode && rows.length !== 1) {
-    throw new Error("This working revision contains translations. Pass an explicit langcode for an existing unpublished language; no draft was created.");
-  }
-  const row = langcode ? rows.find((item) => item.langcode === langcode) : rows[0];
-  if (!row || row.status !== false) {
-    throw new Error("The requested language is not an existing unpublished working draft. Published languages and other drafts were left unchanged.");
-  }
-}
+export {
+  assertInventoryDraftLanguage,
+  readNodeDraftInventory,
+} from "./sentinel-draft.js";

package/src/lib/operations.js

@@ -32,6 +32,11 @@ export const DESTRUCTIVE_PREFIXES = ["drupal_delete_", "drupal_drush_module_disa
  *   prefixes are checked first so they take precedence over plain write.
  */
 export function inferOperation(toolName) {
+  // Only the local module registry generates these names from approved policy.
+  // A forged name cannot resolve a handler; unknown reserved names are conservative.
+  if (toolName.startsWith("drupal_module_")) {
+    return /^drupal_module_(read|write|delete)_/.exec(toolName)?.[1] ?? "delete";
+  }
   if (DESTRUCTIVE_PREFIXES.some((p) => toolName.startsWith(p))) return "delete";
   if (WRITE_PREFIXES.some((p) => toolName.startsWith(p)))       return "write";
   if (toolName === "drupal_graphql")                            return "graphql";

package/src/lib/patch-preflight.js

@@ -24,8 +24,7 @@
 
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
 import { entityRevisionId } from "./write-revision.js";
-import { writeDraft } from "./draft-write.js";
-import { readNodeDraftInventory, assertInventoryDraftLanguage } from "./node-draft-inventory.js";
+import { writeDraft, readNodeDraftInventory, assertInventoryDraftLanguage } from "./sentinel-draft.js";
 
 /** Stable error code for a core working-copy / not-latest-revision block. */
 export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
@@ -61,16 +60,6 @@ export const PATCH_WORKING_COPY_STALE_MESSAGE =
   "The connector will not retry the canonical URL or discard the draft. " +
   "Re-read rel:working-copy and retry, or resolve the conflict in Drupal. See connector #166.";
 
-/**
- * Operator message for a core working-copy 400.
- * A resolvable working copy gets a new draft revision (#166) — this message is only
- * for the invisible-row case (#201).
- * @returns {string}
- */
-export function patchBlockedMessage() {
-  return PATCH_BLOCKED_MESSAGE;
-}
-
 /**
  * Thrown when the core working-copy PATCH guard rejects a canonical write
  * (or its probe) and no working copy is addressable (#201).
@@ -388,18 +377,21 @@ export async function preflightPatchWritable({
 /**
  * Resolve the PATCH target, then run the same probe the real write will use.
  * Callers inherit #166 targeting by going through this before dryRun or write.
+ * `langcode` always resolves Sentinel inventory and draft-preflights, even
+ * when the entity is unmoderated (media translations).
  *
  * @param {object} backend
- * @param {{entityType: string, bundle: string, id: string, existing?: ?object, attributes?: object}} args
+ * @param {{entityType: string, bundle: string, id: string, existing?: ?object, attributes?: object, relationships?: object, langcode?: string}} args
  * @returns {Promise<{resourceVersion: ?string, workingCopy: ?object, liveVid: ?number|string, workingVid: ?number|string}>}
  */
 export async function prepareGuardedPatch(backend, {
   entityType, bundle, id, existing, attributes, relationships, langcode,
 }) {
-  const target = shouldPreflightPatch({ existing, attributes })
+  const needsPreflight = shouldPreflightPatch({ existing, attributes });
+  const target = (needsPreflight || langcode)
     ? await resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing })
     : { resourceVersion: undefined, workingCopy: null, liveVid: null, workingVid: null };
-  if (shouldPreflightPatch({ existing, attributes }) && !target.resourceVersion) {
+  if (needsPreflight && !target.resourceVersion) {
     // Canonical path (no distinct working copy). The id-mismatch probe never
     // reaches Sentinel's save-time stale-default check; refuse here when the
     // possiblyPatchBlocked fingerprint is already readable (#273).