drupal-mcp-connector 2.6.1 → 2.7.0

package/src/lib/mcp-server.js

@@ -7,6 +7,24 @@
 
 import { Server } from "@modelcontextprotocol/server";
 
+/**
+ * Whether a listed resource URI (possibly templated) covers a requested URI.
+ * @param {string} listed
+ * @param {string} requested
+ * @returns {boolean}
+ */
+function resourceUriIsListed(listed, requested) {
+  if (listed === requested) return true;
+  if (typeof listed !== "string" || !listed.includes("{site}")) return false;
+  const marker = "{site}";
+  const at = listed.indexOf(marker);
+  const prefix = listed.slice(0, at);
+  const suffix = listed.slice(at + marker.length);
+  if (!requested.startsWith(prefix) || !requested.endsWith(suffix)) return false;
+  const captured = requested.slice(prefix.length, requested.length - suffix.length);
+  return captured.length > 0 && !captured.includes("/");
+}
+
 /**
  * Create the server factory shared by HTTP and stdio transports.
  *
@@ -14,9 +32,9 @@ import { Server } from "@modelcontextprotocol/server";
  * @param {{name: string, version: string}} surface.serverInfo
  * @param {{definitions: Array<object>, list?: () => Promise<Array<object>>, call: (name: string, args: object, context: object) => Promise<object>}} surface.tools
  *   `definitions` is the full static surface (schema projection); the optional
- *   `list` hook decides what is DISCOVERABLE per request (governance gating).
- * @param {{definitions: Array<object>, read: (uri: string) => Promise<object>}} surface.resources
- * @param {{definitions: Array<object>, get: (name: string, args: object) => Array<object>}} surface.prompts
+ *   `list` hook decides what is DISCOVERABLE per request (governance + entitlement).
+ * @param {{definitions: Array<object>, list?: () => Promise<Array<object>>, read: (uri: string) => Promise<object>}} surface.resources
+ * @param {{definitions: Array<object>, list?: () => Promise<Array<object>>, get: (name: string, args: object) => Array<object>}} surface.prompts
  * @returns {(context: import("@modelcontextprotocol/server").McpRequestContext) => Server}
  */
 export function createConnectorServerFactory({ serverInfo, tools, resources, prompts }) {
@@ -37,9 +55,14 @@ export function createConnectorServerFactory({ serverInfo, tools, resources, pro
       return server.projectCallToolResult(result, toolDefinitions.get(name)?.outputSchema);
     });
 
-    server.setRequestHandler("resources/list", async () => ({ resources: resources.definitions }));
+    server.setRequestHandler("resources/list", async () => ({
+      resources: resources.list ? await resources.list() : resources.definitions,
+    }));
     server.setRequestHandler("resources/read", async (request) => {
       const { uri } = request.params;
+      const visible = resources.list ? await resources.list() : resources.definitions;
+      const listed = visible.some((resource) => resourceUriIsListed(resource.uri, uri));
+      if (!listed) throw new Error(`Unknown resource: "${uri}"`);
       try {
         const data = await resources.read(uri);
         return {
@@ -50,10 +73,13 @@ export function createConnectorServerFactory({ serverInfo, tools, resources, pro
       }
     });
 
-    server.setRequestHandler("prompts/list", async () => ({ prompts: prompts.definitions }));
+    server.setRequestHandler("prompts/list", async () => ({
+      prompts: prompts.list ? await prompts.list() : prompts.definitions,
+    }));
     server.setRequestHandler("prompts/get", async (request) => {
       const { name, arguments: args } = request.params;
-      const known = prompts.definitions.find((prompt) => prompt.name === name);
+      const visible = prompts.list ? await prompts.list() : prompts.definitions;
+      const known = visible.find((prompt) => prompt.name === name);
       if (!known) throw new Error(`Unknown prompt: "${name}"`);
       return { description: known.description, messages: prompts.get(name, args ?? {}) };
     });

package/src/lib/principal.js

@@ -0,0 +1,372 @@
+/**
+ * Inbound principal entitlement (#178).
+ *
+ * HTTPS resource-server requests carry a validated JWT identity. Discovery
+ * and invocation are filtered by that identity's server-resolved grants.
+ * Stdio, loopback shared-bearer, and unauthenticated loopback have no
+ * inbound principal and keep the existing site + source-governance filter
+ * so a local operator is not hollowed out.
+ *
+ * Caller-supplied site, environment, tenant, target, or scope fields are
+ * hints. They never become authority. Empty inbound scopes are no grants,
+ * not a wildcard.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getDefaultSiteName, getInboundGrants } from "./config.js";
+import { inferOperation } from "./operations.js";
+import { resolveSecurityConfig, SecurityError } from "./security.js";
+
+const identityStore = new AsyncLocalStorage();
+
+/** Caller fields that look like a target but are never authority. */
+export const TARGET_HINT_KEYS = Object.freeze(["site", "environment", "tenant", "target"]);
+
+/** Always discoverable; they are how an operator sees a denial. */
+export const DIAGNOSTIC_TOOLS = new Set([
+  "drupal_list_sites",
+  "drupal_governance_status",
+]);
+
+const CONFIG_TOOLS = new Set([
+  "drupal_config_get",
+  "drupal_config_list",
+  "drupal_config_set",
+  "drupal_drush_config_export",
+  "drupal_drush_config_import",
+  "drupal_drush_config_status",
+]);
+
+/** inferOperation() leaves these as "read"; they self-gate in-handler. */
+const WRITE_BY_NAME = new Set([
+  "drupal_entity_create",
+  "drupal_entity_update",
+  "drupal_entity_delete",
+]);
+
+const FREE_FORM_TOOLS = new Set([
+  "drupal_graphql",
+  "drupal_graphql_introspect",
+  "drupal_drush_sql_query",
+]);
+
+const WRITE_WORKFLOW_PROMPTS = new Set([
+  "drupal-create-article",
+  "drupal-seo-fix",
+  "drupal-user-cleanup",
+]);
+
+const READ_WORKFLOW_PROMPTS = new Set([
+  "drupal-content-audit",
+  "drupal-full-audit",
+]);
+
+/**
+ * Run `fn` with `identity` as the request principal (null = local operator).
+ * @param {object|null} identity
+ * @param {Function} fn
+ * @returns {*}
+ */
+export function runWithIdentity(identity, fn) {
+  return identityStore.run({ identity: identity ?? null }, fn);
+}
+
+/**
+ * The inbound identity for the current request, or null on stdio / loopback.
+ * @returns {object|null}
+ */
+export function getRequestIdentity() {
+  return identityStore.getStore()?.identity ?? null;
+}
+
+/**
+ * Inbound scope required to discover or invoke a tool. Diagnostics need none.
+ * @param {string} toolName
+ * @returns {string|null}
+ */
+export function requiredScopeForTool(toolName) {
+  if (DIAGNOSTIC_TOOLS.has(toolName)) return null;
+  if (toolName === "drupal_drush_sql_query") return "mcp_admin";
+  if (CONFIG_TOOLS.has(toolName)) return "mcp_config";
+  if (WRITE_BY_NAME.has(toolName)) return "mcp_write";
+  const op = inferOperation(toolName);
+  if (op === "write" || op === "delete") return "mcp_write";
+  return "mcp_read";
+}
+
+/**
+ * @param {object|null} identity
+ * @param {string|null} scope
+ * @returns {boolean}
+ */
+export function principalHasScope(identity, scope) {
+  if (!scope) return true;
+  return (identity?.scopes ?? []).includes(scope);
+}
+
+/**
+ * Site names this principal may address. Unknown names in a grant are dropped.
+ *
+ * @param {object|null} identity
+ * @param {string[]} configuredNames
+ * @param {object|null} [grants] `auth.grants` map; `undefined` reads config.
+ * @returns {string[]}
+ */
+export function resolveGrantedSiteNames(identity, configuredNames, grants) {
+  if (!identity) return [...configuredNames];
+  const known = new Set(configuredNames);
+  const grantMap = grants === undefined ? getInboundGrants() : grants;
+
+  if (grantMap) {
+    const listed = identity.clientId
+      ? new Map(Object.entries(grantMap)).get(identity.clientId)
+      : undefined;
+    if (!Array.isArray(listed)) return [];
+    return listed.map(String).filter((name) => known.has(name));
+  }
+
+  if (Array.isArray(identity.sites)) {
+    return identity.sites.map(String).filter((name) => known.has(name));
+  }
+
+  return [...configuredNames];
+}
+
+/**
+ * @param {object|null} identity
+ * @param {Array<{_name: string}>} sites
+ * @param {object|null} [grants]
+ * @returns {Array<object>}
+ */
+export function resolveGrantedSites(identity, sites, grants) {
+  const allowed = new Set(
+    resolveGrantedSiteNames(identity, sites.map((site) => site._name), grants),
+  );
+  return sites.filter((site) => allowed.has(site._name));
+}
+
+/**
+ * @param {object} site
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+function siteAllowsTool(site, toolName) {
+  const sec = resolveSecurityConfig(site);
+  if (toolName === "drupal_graphql" || toolName === "drupal_graphql_introspect") {
+    return Boolean(sec.allowGraphql);
+  }
+  if (toolName === "drupal_drush_sql_query") {
+    return site.drushSsh?.rawSql === "governed";
+  }
+  if (toolName === "drupal_config_set") {
+    return Boolean(sec.allowConfigWrite) && !sec.readOnly;
+  }
+  if (toolName === "drupal_config_get" || toolName === "drupal_config_list") {
+    return Boolean(sec.allowConfigRead);
+  }
+  const op = inferOperation(toolName);
+  const writeLike = op === "write" || op === "delete" || WRITE_BY_NAME.has(toolName);
+  if (writeLike && sec.readOnly) return false;
+  if ((op === "delete" || toolName === "drupal_entity_delete") && !sec.allowDestructive) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * @param {string} toolName
+ * @param {object|null} identity
+ * @param {Array<object>} sites
+ * @param {object|null} [grants]
+ * @returns {boolean}
+ */
+export function principalMayUseTool(toolName, identity, sites, grants) {
+  if (!identity) return true;
+  if (DIAGNOSTIC_TOOLS.has(toolName)) return true;
+  if (!principalHasScope(identity, requiredScopeForTool(toolName))) return false;
+  const entitled = resolveGrantedSites(identity, sites, grants);
+  if (!entitled.length) return false;
+  if (FREE_FORM_TOOLS.has(toolName)) {
+    return entitled.some((site) => siteAllowsTool(site, toolName));
+  }
+  return entitled.some((site) => siteAllowsTool(site, toolName));
+}
+
+/**
+ * @param {Array<{name: string}>} definitions
+ * @param {Array<object>} sites
+ * @param {object|null} identity
+ * @param {object|null} [grants]
+ * @returns {Array<object>}
+ */
+export function filterToolsByPrincipal(definitions, sites, identity, grants) {
+  if (!identity) return definitions;
+  return definitions.filter((definition) =>
+    principalMayUseTool(definition.name, identity, sites, grants));
+}
+
+/**
+ * @param {object} [args]
+ * @returns {Array<{key: string, value: string}>}
+ */
+export function callerTargetHints(args = {}) {
+  const found = [];
+  for (const key of TARGET_HINT_KEYS) {
+    const value = new Map(Object.entries(args ?? {})).get(key);
+    if (typeof value === "string" && value.trim()) {
+      found.push({ key, value: value.trim() });
+    }
+  }
+  return found;
+}
+
+/**
+ * @param {object} site
+ * @param {string} source
+ * @returns {{name: string, baseUrl?: string, source: string}}
+ */
+export function describeTarget(site, source) {
+  return {
+    name: site._name,
+    baseUrl: site.baseUrl,
+    source,
+  };
+}
+
+/**
+ * Public site list for tools/resources. Never includes credentials.
+ *
+ * @param {object|null} identity
+ * @param {Array<object>} resolvable
+ * @param {string[]} configuredNames
+ * @param {object|null} [grants]
+ * @returns {{sites: string[], targets: Array<{name: string, baseUrl?: string, source: string}>}}
+ */
+export function visibleSiteTargets(identity, resolvable, configuredNames, grants) {
+  const granted = identity ? resolveGrantedSites(identity, resolvable, grants) : resolvable;
+  const names = identity
+    ? granted.map((site) => site._name)
+    : [...configuredNames];
+  const byName = new Map(granted.map((site) => [site._name, site]));
+  const source = identity ? "grant" : "config";
+  return {
+    sites: names,
+    targets: names.map((name) => {
+      const site = byName.get(name);
+      return site ? describeTarget(site, source) : { name, source };
+    }),
+  };
+}
+
+/**
+ * Resolve the site this principal may use for a call.
+ *
+ * @param {object} args
+ * @param {object} identity
+ * @param {Array<object>} sites
+ * @param {{grants?: object|null, defaultSite?: string}} [options]
+ * @returns {{site: object, source: string, name: string}}
+ * @throws {SecurityError}
+ */
+export function resolveAuthoritativeTarget(args, identity, sites, options = {}) {
+  const grantMap = options.grants === undefined ? getInboundGrants() : options.grants;
+  const entitled = resolveGrantedSites(identity, sites, grantMap);
+  const hints = callerTargetHints(args);
+  const unique = [...new Set(hints.map((hint) => hint.value))];
+
+  if (unique.length > 1) {
+    throw new SecurityError(
+      "Conflicting caller target hints do not select a single granted target.",
+    );
+  }
+
+  if (unique.length === 1) {
+    const site = entitled.find((entry) => entry._name === unique[0]);
+    if (!site) {
+      throw new SecurityError("Not entitled to the requested target.");
+    }
+    return { site, source: "hint", name: site._name };
+  }
+
+  const defaultName = options.defaultSite ?? getDefaultSiteName();
+  const fromDefault = entitled.find((entry) => entry._name === defaultName);
+  if (fromDefault) {
+    return { site: fromDefault, source: "default", name: fromDefault._name };
+  }
+  if (entitled.length === 1) {
+    return { site: entitled[0], source: "grant", name: entitled[0]._name };
+  }
+
+  throw new SecurityError(
+    entitled.length
+      ? "No authoritative target could be resolved from the principal grant."
+      : "Principal is not entitled to any configured target.",
+  );
+}
+
+/**
+ * Deny unauthorized invocation. Returns the resolved target, or null for
+ * tools that do not address a site.
+ *
+ * @param {object} params
+ * @returns {{site: object, source: string, name: string}|null}
+ * @throws {SecurityError}
+ */
+export function assertPrincipalEntitlement({
+  toolName,
+  args,
+  identity,
+  sites,
+  grants,
+  defaultSite,
+}) {
+  if (!identity) return null;
+  if (!principalMayUseTool(toolName, identity, sites, grants)) {
+    throw new SecurityError(`Not entitled to invoke ${toolName}.`);
+  }
+  // list_sites has no target. governance_status without a hint reports every
+  // granted site — pinning it to the default would hide the rest.
+  if (toolName === "drupal_list_sites") return null;
+  if (toolName === "drupal_governance_status" && callerTargetHints(args).length === 0) {
+    return null;
+  }
+  return resolveAuthoritativeTarget(args, identity, sites, { grants, defaultSite });
+}
+
+/**
+ * @param {Array<object>} resources
+ * @param {object|null} identity
+ * @param {Array<object>} sites
+ * @param {object|null} [grants]
+ * @returns {Array<object>}
+ */
+export function filterResourcesByPrincipal(resources, identity, sites, grants) {
+  if (!identity) return resources;
+  const entitled = resolveGrantedSites(identity, sites, grants);
+  const canRead = principalHasScope(identity, "mcp_read") && entitled.length > 0;
+  return resources.filter((resource) => {
+    if (resource.uri === "drupal://sites") return true;
+    return canRead;
+  });
+}
+
+/**
+ * @param {Array<object>} prompts
+ * @param {object|null} identity
+ * @param {Array<{name: string}>} visibleTools
+ * @returns {Array<object>}
+ */
+export function filterPromptsByPrincipal(prompts, identity, visibleTools) {
+  if (!identity) return prompts;
+  const visible = new Set((visibleTools ?? []).map((tool) => tool.name));
+  return prompts.filter((prompt) => {
+    if (WRITE_WORKFLOW_PROMPTS.has(prompt.name)) {
+      return principalHasScope(identity, "mcp_write");
+    }
+    if (READ_WORKFLOW_PROMPTS.has(prompt.name)) {
+      return principalHasScope(identity, "mcp_read");
+    }
+    const toolName = prompt.name.replace(/-/g, "_");
+    return visible.has(toolName);
+  });
+}

package/src/lib/verify.js

@@ -19,6 +19,7 @@
 
 import { createHash } from "node:crypto";
 import { CLIENT_VERSION } from "./config.js";
+import { resolveInboundAuthConfig, resolveInboundAuthMode } from "./http-auth.js";
 
 /** Check outcome vocabulary.
  *
@@ -44,6 +45,7 @@ export const STATIC_CHECKS = [
   "entitlement",
   "target_resolution",
   "tenant_neutrality",
+  "inbound_auth",
 ];
 
 /**
@@ -222,13 +224,14 @@ export function configDigest(config) {
  * credentials, no side effects.
  *
  * @param {object} config Parsed connector configuration.
- * @param {{source?: string, now?: () => Date}} [options]
+ * @param {{source?: string, now?: () => Date, env?: NodeJS.ProcessEnv}} [options]
  *   `source` names what was verified (a path, or a label) for the evidence;
- *   `now` is injectable so a run is reproducible in tests.
+ *   `now` is injectable so a run is reproducible in tests;
+ *   `env` is the process environment under verification (defaults to `process.env`).
  * @returns {object} Evidence document: tool, version, subject, checks,
  *   residuals and a summary. Never contains secret values.
  */
-export function verifyStatic(config, { source = "config", now = () => new Date() } = {}) {
+export function verifyStatic(config, { source = "config", now = () => new Date(), env = process.env } = {}) {
   const sites = Object.entries(config?.sites ?? {});
   const named = (name, message) => `${name}: ${message}`;
   const nothingToCheck = sites.length === 0;
@@ -364,12 +367,44 @@ export function verifyStatic(config, { source = "config", now = () => new Date()
   const tenantNeutrality = check(
     "tenant_neutrality",
     "The configuration names no real tenant hosts or identifiers",
-    mentionedHosts(config?.sites ?? {})
+    mentionedHosts({ sites: config?.sites ?? {}, auth: config?.auth ?? {} })
       .filter(({ host }) => !isNeutralHost(host))
       .map(({ path, host }) => `${path}: "${host}" is not a documentation-reserved host; a shipped example must not name a real deployment.`),
     { skipped: nothingToCheck },
   );
 
+  const inbound = resolveInboundAuthConfig(config, env);
+  const inboundFindings = [];
+  if (inbound.issuer || inbound.audience || inbound.resource) {
+    if (!inbound.issuer) inboundFindings.push("auth.issuer is missing.");
+    else if (!String(inbound.issuer).startsWith("https://")) {
+      inboundFindings.push("auth.issuer is not HTTPS.");
+    }
+    if (!inbound.audience) inboundFindings.push("auth.audience is missing.");
+    if (inbound.resource && !String(inbound.resource).startsWith("https://")) {
+      inboundFindings.push("auth.resource is not HTTPS.");
+    }
+    if (inbound.introspectionUrl && !String(inbound.introspectionUrl).startsWith("https://")) {
+      inboundFindings.push("auth.introspectionUrl is not HTTPS.");
+    }
+  }
+  const transportName = env.MCP_TRANSPORT || "stdio";
+  if (transportName === "https" || transportName === "http") {
+    const decision = resolveInboundAuthMode({
+      bindHost: env.MCP_BIND_HOST || "0.0.0.0",
+      allowUnauth: env.MCP_ALLOW_UNAUTHENTICATED === "1",
+      sharedToken: env.MCP_AUTH_TOKEN || "",
+      resourceServer: inbound,
+    });
+    if (decision.mode === "fatal") inboundFindings.push(decision.reason);
+  }
+
+  const inboundAuth = check(
+    "inbound_auth",
+    "Network-facing HTTPS authenticates as an OAuth protected resource",
+    inboundFindings,
+  );
+
   const checks = [
     transport,
     principalAuth,
@@ -379,6 +414,7 @@ export function verifyStatic(config, { source = "config", now = () => new Date()
     entitlement,
     targetResolution,
     tenantNeutrality,
+    inboundAuth,
   ];
 
   const counts = checks.reduce(

package/src/tools/config.js

@@ -12,6 +12,7 @@
  */
 
 import { getSiteConfig } from "../lib/config.js";
+import { describeTarget, getRequestIdentity } from "../lib/principal.js";
 import {
   resolveSecurityConfig,
   getSecuritySummary,
@@ -117,8 +118,13 @@ async function whoami({ site: siteName }) {
   // When no OAuth scopes are configured, hasScope() is a no-op (preset-only).
   const canWrite  = !sec.readOnly && hasScope(site, "mcp_write");
   const canConfig = hasScope(site, "mcp_config");
+  const identity = getRequestIdentity();
   return {
     site: site._name,
+    target: describeTarget(site, siteName ? "hint" : "default"),
+    principal: identity
+      ? { sub: identity.sub, clientId: identity.clientId, scopes: [...(identity.scopes ?? [])] }
+      : null,
     tier: inferTier(site, sec),
     preset: summary.preset,
     scopes: site.oauth?.scopes ?? [],

package/src/tools/site.js

@@ -9,6 +9,7 @@
 import { getSiteConfig, listSiteNames } from "../lib/config.js";
 import { governanceStatus } from "../lib/governance.js";
 import { resolveBackend } from "../lib/backends/index.js";
+import { getRequestIdentity, resolveGrantedSiteNames, visibleSiteTargets } from "../lib/principal.js";
 
 // ---------------------------------------------------------------------------
 // Implementations
@@ -43,11 +44,21 @@ async function listContentTypes({ site: siteName }) {
 }
 
 /**
- * List all named sites from config.json. No backend call and no credentials.
- * @returns {Promise<{sites: string[]}>}
+ * List named sites this principal may address. No backend call and no credentials.
+ * `sites` stays a name list for compatibility; `targets` is the authoritative
+ * resolved-target record.
+ * @returns {Promise<{sites: string[], targets: Array<object>}>}
  */
 async function listConfiguredSites() {
-  return { sites: listSiteNames() };
+  const names = listSiteNames();
+  const resolvable = names.flatMap((name) => {
+    try {
+      return [getSiteConfig(name)];
+    } catch {
+      return [];
+    }
+  });
+  return visibleSiteTargets(getRequestIdentity(), resolvable, names);
 }
 
 /**
@@ -71,7 +82,10 @@ export function classifySiteResolutionFailure(message) {
 }
 
 async function getGovernanceStatus({ site: siteName } = {}) {
-  const names = siteName ? [siteName] : listSiteNames();
+  const identity = getRequestIdentity();
+  const configured = listSiteNames();
+  const allowed = identity ? resolveGrantedSiteNames(identity, configured) : configured;
+  const names = siteName ? [siteName] : allowed;
   const resolved = [];
   const unresolved = [];
   for (const name of names) {
@@ -123,7 +137,7 @@ export const definitions = [
   },
   {
     name: "drupal_list_sites",
-    description: "List all named Drupal sites configured in config.json. Useful for multi-site setups.",
+    description: "List the Drupal sites this principal may address. Each target includes the authoritative site name and base URL.",
     inputSchema: {
       type: "object",
       properties: {},