drupal-mcp-connector 2.6.0 → 2.7.0

package/.claude/commands/drupal-list-sites.md

@@ -1,10 +1,10 @@
 ---
-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."
 allowed-tools: mcp__drupal__drupal_list_sites
 ---
 
 Call the `mcp__drupal__drupal_list_sites` MCP tool.
 
-List all named Drupal sites configured in config.json. Useful for multi-site setups.
+List the Drupal sites this principal may address. Each target includes the authoritative site name and base URL.
 
 This tool takes no arguments — call it directly (ignore `$ARGUMENTS`).

package/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.0] - 2026-08-17
+
+### Security
+- **Discovery and invocation follow the inbound principal (#178).** On
+  HTTPS resource-server requests the validated JWT — not caller `site`,
+  `environment`, `tenant`, `target`, or `scope` arguments — decides which
+  tools, resources, prompts, and sites are visible or callable. Empty
+  inbound scopes are no grants. `auth.grants` maps a client id to site
+  names; a present map is fail-closed for unknown clients. GraphQL and
+  raw SQL stay hidden unless an entitled site's preset actually allows
+  them. Stdio and loopback without a resource-server identity keep the
+  existing local-operator surface. `drupal_list_sites` now also returns
+  `targets` with the authoritative name and base URL.
+- **Network-facing HTTPS is an OAuth protected resource (#177).** `/mcp`
+  validates inbound JWTs against a configured issuer (RFC 8414 / OIDC
+  discovery + JWKS): issuer, audience/resource, expiry and required scopes.
+  RFC 9728 metadata is served at `/.well-known/oauth-protected-resource`.
+  A revocation file (`jti` / `sub`) is re-read when it changes, so a revoke
+  does not require a restart. Optional RFC 7662 introspection is fail-closed
+  when configured. Discovery requires the metadata `issuer` to match the
+  configured identifier (RFC 8414 §3.3), uses the RFC 8414 well-known path
+  for issuers that have a path component, and refuses HTTP issuers,
+  `jwks_uri`s, and introspection URLs. Trailing slashes on the issuer
+  identifier do not break JWT verification. RFC 9728 `authorization_servers`
+  advertises the issuer string returned by discovery. A thrown authenticator, a corrupt revocation file, or a
+  failed introspection returns `401` instead of hanging the request.
+  Caller-supplied identity headers never become the principal. The inbound
+  access token is never forwarded to Drupal. `MCP_AUTH_TOKEN` remains valid
+  only on loopback; a network-facing bind that still relies on the shared
+  secret refuses to start.
+
+### Changed
+- **Versioning policy states the post-1.0 guarantees it actually operates under
+  (#195).** `docs/versioning.md` still opened with a pre-1.0 section explaining
+  that minor releases might break the stable surface because the project was on
+  `0.x`, and pointed at a closed tracking issue. The package has been past 1.0
+  for some time, so the document told operators the compatibility guarantees
+  were not yet in force when they were. The stable-surface list, deprecation
+  policy and runtime support were already correct and are unchanged.
+
+### Fixed
+- **Whitepaper no longer calls the companion governance module pre-1.0/alpha
+  (#195).** `docs/whitepaper.md` described `drupal/mcp_sentinel` as alpha and
+  requiring Drupal `^10.3 || ^11`. It is a shipping module at 2.9.0 with a floor
+  of `^10.6 || ^11.3` on PHP 8.3 or newer — the stale constraint would have sent
+  a reader to install it on a combination it does not support.
+
+## [2.6.1] - 2026-08-17
+
+### Fixed
+- **A process no longer starts when every secret named by the active config
+  is unset (#199).** After 2.6.0, a client that spawned `node src/index.js`
+  (skipping the launcher) or whose `config.json` still used older
+  `clientSecretEnv` names could start with zero resolved sites and advertise
+  only `drupal_list_sites` and `drupal_governance_status`. The diagnostic
+  then told the operator to provide an oauth block that was already there.
+  2.6.1 loads `config/secrets.map` (or the shipped example table) inside
+  `node`; names the unset variable; classifies
+  `drupal_governance_status` failures; and **refuses to start** when every
+  named secret is missing. On 2.6.0 the same recovery is: launch via
+  `bin/drupal-mcp-launch.sh` with a `config/secrets.map`
+  (`ENV_VAR=keychain-item`), then restart the MCP client.
+
 ## [2.6.0] - 2026-08-15
 
 ### Added

package/README.md

@@ -9,6 +9,8 @@
 
 Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
+**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.0** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
+
 ---
 
 ## What It Does
@@ -156,7 +158,7 @@ Additional connector-side gates (2.1+ / 2.2+):
 - **Entity allowlists** apply to specialized tools (`drupal_*_node`, media, taxonomy), not only `drupal_entity_*`.
 - **Publish gate:** `status: true` and `moderation_state: "published"` require `allowPublish`. Media create defaults **unpublished**. Published moderated node updates without a moderation state default to **draft** (forward revision).
 - **Uploads** only from `MCP_UPLOAD_ROOT` (or the process cwd); sensitive paths (`.env*`, `.ssh`, connector `config.json`) are refused.
-- **HTTPS:** non-loopback binds require `MCP_AUTH_TOKEN` (or `MCP_ALLOW_UNAUTHENTICATED=1` behind a trusted proxy); non-loopback TLS defaults to 120 req/min rate limiting.
+- **HTTPS:** non-loopback binds require an inbound OAuth resource server (`auth.issuer` + `auth.audience`), not `MCP_AUTH_TOKEN`. `MCP_AUTH_TOKEN` remains valid on loopback. `MCP_ALLOW_UNAUTHENTICATED=1` is only for a trusted proxy. Non-loopback TLS defaults to 120 req/min rate limiting. Inbound JWT scopes (and optional `auth.grants`) filter which tools, resources, prompts, and sites a principal can discover or invoke.
 - **GraphQL is off by default.** `drupal_graphql` / introspect require `security.allowGraphql` (true only on the `development` preset). Raw GraphQL results still bypass entity allowlists and field redaction — prefer JSON:API entity tools when connector policy must hold. Mutations also need `allowGraphqlMutations`.
 
 Full detail: **[docs/security.md](docs/security.md)** and **[docs/security-hardening.md](docs/security-hardening.md)**.

package/config/config.example.json

@@ -7,7 +7,7 @@
   },
 
   "_security_options": {
-    "_comment": "apiTokenEnv / oauth.clientSecretEnv: read credentials from the environment, never from this file. requireSecureAuth: reject anon/basic, require HTTPS+Bearer — set it on every remote site. requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel) verifies — no ungoverned JSON:API/GraphQL fallback. Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_AUTH_TOKEN requires bearer auth on the HTTPS /mcp endpoint; MCP_BIND_HOST restricts the listen interface (with TLS). See docs/security-hardening.md."
+    "_comment": "apiTokenEnv / oauth.clientSecretEnv: read credentials from the environment, never from this file. requireSecureAuth: reject anon/basic, require HTTPS+Bearer — set it on every remote site. requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel) verifies — no ungoverned JSON:API/GraphQL fallback. Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_BIND_HOST restricts the listen interface (with TLS). Network-facing HTTPS /mcp requires the top-level auth block (issuer + audience), not MCP_AUTH_TOKEN. MCP_AUTH_TOKEN remains valid only on loopback. See docs/security-hardening.md."
   },
 
   "_governance_tiers": {
@@ -23,6 +23,21 @@
     "port":     3443
   },
 
+  "auth": {
+    "_comment": "Inbound OAuth resource-server for MCP_TRANSPORT=https when the process binds beyond loopback. The issuer is any standards-based authorization server (RFC 8414 / OIDC) — not a vendor-specific product. Tokens are JWTs validated against the issuer's JWKS. Optional: revocationFile (JSON {jti,sub}, re-read without restart) and introspectionUrl (RFC 7662). Env overrides: MCP_RESOURCE_ISSUER, MCP_RESOURCE_AUDIENCE, MCP_RESOURCE, MCP_REVOCATION_FILE, MCP_INTROSPECTION_URL.",
+    "issuer":   "https://idp.example.com",
+    "audience": "https://mcp.example.com/mcp",
+    "resource": "https://mcp.example.com/mcp",
+    "requiredScopes": ["mcp_read"],
+    "grants": {
+      "_comment": "Optional. Map inbound OAuth client_id (azp) to site names, e.g. \"content-agent\": [\"production\", \"staging\"]. When the map names any client, unknown clients receive no sites. Omit this object (or leave only this comment) to let every resolvable site stay visible; inbound scopes still gate the tool surface."
+    },
+    "revocationFile": "",
+    "introspectionUrl": "",
+    "introspectionClientIdEnv": "",
+    "introspectionClientSecretEnv": ""
+  },
+
   "sites": {
     "production": {
       "_comment": "Content tier. Content/media/term CRUD; config read-only; cannot publish (the source-side editorial gate decides publication, not the agent). No drushSsh.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.6.0",
-  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal \u2014 dual-protocol JSON:API and GraphQL.",
+  "version": "2.7.0",
+  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -56,7 +56,7 @@
     "test:watch": "vitest",
     "audit": "npm audit --audit-level=high",
     "check": "npm run lint && npm run audit",
-    "syntax-check": "for f in src/lib/*.js src/tools/*.js src/index.js; do node --input-type=module --check < $f && echo \"$f \u2713\"; done",
+    "syntax-check": "for f in src/lib/*.js src/tools/*.js src/index.js; do node --input-type=module --check < $f && echo \"$f ✓\"; done",
     "verify": "node bin/drupal-mcp-verify.js",
     "verify:example": "node bin/drupal-mcp-verify.js --config config/config.example.json"
   },
@@ -64,6 +64,7 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "graphql": "^17.0.0",
+    "jose": "^6.2.9",
     "node-fetch": "^3.3.2",
     "ssh2": "^1.16.0"
   },

package/src/index.js

@@ -15,7 +15,9 @@
  *   DRUPAL_BASE_URL   Single-site fallback baseUrl
  *   DRUPAL_API_TOKEN  Single-site fallback Bearer token
  *   MCP_ALLOW_HTTP    Set to "1" to allow plain HTTP on localhost only (dev)
- *   MCP_AUTH_TOKEN    Bearer token required on /mcp in https mode (warns if unset)
+ *   MCP_AUTH_TOKEN    Loopback-only shared bearer for /mcp (not accepted network-facing)
+ *   MCP_RESOURCE_ISSUER / MCP_RESOURCE_AUDIENCE / MCP_RESOURCE
+ *                     Inbound OAuth resource-server (required beyond loopback)
  *   MCP_BIND_HOST     Bind address for https mode when TLS is present
  *                     (default: "0.0.0.0"; ignored without TLS, which forces loopback)
  *   MCP_RATE_LIMIT    Max /mcp requests per window per client IP (0/unset = off)
@@ -31,18 +33,48 @@ import { createMcpHandler } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { toNodeHandler } from "@modelcontextprotocol/node";
 
-import { listSiteNames, getTlsConfig, CLIENT_VERSION } from "./lib/config.js";
-import { makeBearerCheck } from "./lib/http-auth.js";
+import { listSiteNames, getTlsConfig, loadConfig, CLIENT_VERSION } from "./lib/config.js";
+import { loadLocalSecrets, secretLoadFatalMessage } from "./lib/load-secrets.js";
+import {
+  makeBearerCheck,
+  resolveInboundAuthConfig,
+  resolveInboundAuthMode,
+  createInboundHttpsAuth,
+} from "./lib/http-auth.js";
 import { createLegacySessionHandler, createMcpRequestHandler } from "./lib/http-handler.js";
 import { createConnectorServerFactory } from "./lib/mcp-server.js";
 import { createRateLimiter } from "./lib/rate-limit.js";
 import { callTool, listResolvableSiteConfigs } from "./lib/dispatch.js";
 import { filterDiscoverableTools } from "./lib/governance.js";
+import {
+  assertPrincipalEntitlement,
+  filterPromptsByPrincipal,
+  filterResourcesByPrincipal,
+  filterToolsByPrincipal,
+  getRequestIdentity,
+  visibleSiteTargets,
+} from "./lib/principal.js";
 
 // Tools — aggregated (single source of truth, side-effect-free) and per-tool prompts
 import { allDefinitions, allHandlers, definitionsByName } from "./tools/index.js";
 import { buildToolPrompts, getToolPromptMessages } from "./lib/tool-prompts.js";
 
+// Apply config/secrets.map (or the shipped example table) before any site
+// resolution. MCP clients spawn this file directly; the shell launcher is
+// not guaranteed to have run.
+const secretLoad = loadLocalSecrets();
+const secretFatal = secretLoadFatalMessage(secretLoad);
+if (secretFatal) {
+  console.error(`[drupal-mcp-connector] FATAL: ${secretFatal}`);
+  process.exit(1);
+}
+if (secretLoad.unset.length) {
+  console.error(
+    "[drupal-mcp-connector] WARNING: config.json names secret env vars that are unset: " +
+    `${secretLoad.unset.join(", ")}. Those sites will fail closed.`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // MCP Resources — browsable, always-fresh site context
 // ---------------------------------------------------------------------------
@@ -78,21 +110,43 @@ const RESOURCES = [
  * @returns {Promise<object>} The resource data (later JSON-serialized).
  * @throws {Error} If the URI matches no known resource.
  */
+async function discoverableTools() {
+  const sites = listResolvableSiteConfigs();
+  const identity = getRequestIdentity();
+  const governed = await filterDiscoverableTools(allDefinitions, sites);
+  return filterToolsByPrincipal(governed, sites, identity);
+}
+
 async function readResource(uri) {
+  const identity = getRequestIdentity();
+  const sites = listResolvableSiteConfigs();
+
   // drupal://sites
   if (uri === "drupal://sites") {
-    return { sites: listSiteNames() };
+    return visibleSiteTargets(identity, sites, listSiteNames());
   }
 
   // drupal://{site}/content-types
   const ctMatch = uri.match(/^drupal:\/\/([^/]+)\/content-types$/);
   if (ctMatch) {
+    assertPrincipalEntitlement({
+      toolName: "drupal_list_content_types",
+      args: { site: ctMatch[1] },
+      identity,
+      sites,
+    });
     return allHandlers.drupal_list_content_types({ site: ctMatch[1] });
   }
 
   // drupal://{site}/security-policy
   const spMatch = uri.match(/^drupal:\/\/([^/]+)\/security-policy$/);
   if (spMatch) {
+    assertPrincipalEntitlement({
+      toolName: "drupal_security_info",
+      args: { site: spMatch[1] },
+      identity,
+      sites,
+    });
     return allHandlers.drupal_security_info({ site: spMatch[1] });
   }
 
@@ -236,12 +290,24 @@ const buildConnectorServer = createConnectorServerFactory({
   serverInfo: { name: "drupal-mcp-connector", version: CLIENT_VERSION },
   tools: {
     definitions: allDefinitions,
-    list: () => filterDiscoverableTools(allDefinitions, listResolvableSiteConfigs()),
+    list: discoverableTools,
     call: callTool,
   },
-  resources: { definitions: RESOURCES, read: readResource },
+  resources: {
+    definitions: RESOURCES,
+    list: async () => {
+      const sites = listResolvableSiteConfigs();
+      return filterResourcesByPrincipal(RESOURCES, getRequestIdentity(), sites);
+    },
+    read: readResource,
+  },
   prompts: {
     definitions: ALL_PROMPTS,
+    list: async () => {
+      const identity = getRequestIdentity();
+      const tools = await discoverableTools();
+      return filterPromptsByPrincipal(ALL_PROMPTS, identity, tools);
+    },
     get: (name, args) => WORKFLOW_PROMPT_NAMES.has(name)
       ? getPromptMessages(name, args)
       : getToolPromptMessages(name, args, definitionsByName),
@@ -273,15 +339,7 @@ if (transport === "stdio") {
   const allowHttp  = process.env.MCP_ALLOW_HTTP === "1";
 
   const authToken   = process.env.MCP_AUTH_TOKEN || "";
-  const checkAuth   = makeBearerCheck(authToken);
   const allowUnauth = process.env.MCP_ALLOW_UNAUTHENTICATED === "1";
-  if (!authToken) {
-    console.error(
-      "[drupal-mcp-connector] WARNING: the /mcp endpoint is UNAUTHENTICATED. " +
-      "Set MCP_AUTH_TOKEN to require a bearer token, or front it with a trusted " +
-      "boundary (private network / auth proxy). Acceptable only behind such a boundary."
-    );
-  }
 
   // Security headers applied to every response
   function applySecurityHeaders(res) {
@@ -332,15 +390,42 @@ if (transport === "stdio") {
   const bindHost = hasTls ? (process.env.MCP_BIND_HOST || "0.0.0.0") : "127.0.0.1";
   const isLoopbackBind = bindHost === "127.0.0.1" || bindHost === "::1" || bindHost === "localhost";
 
-  // #141: fail closed when HTTPS is network-facing without a bearer token.
-  // Loopback binds and explicit MCP_ALLOW_UNAUTHENTICATED=1 remain for local/proxy setups.
-  if (!authToken && !isLoopbackBind && !allowUnauth) {
+  const inboundCfg = resolveInboundAuthConfig(loadConfig());
+  const inboundMode = resolveInboundAuthMode({
+    bindHost,
+    allowUnauth,
+    sharedToken: authToken,
+    resourceServer: inboundCfg,
+  });
+  if (inboundMode.mode === "fatal") {
+    console.error(`[drupal-mcp-connector] FATAL: ${inboundMode.reason}`);
+    process.exit(1);
+  }
+
+  let checkAuth = makeBearerCheck(inboundMode.mode === "shared_bearer" ? authToken : "");
+  let authenticate = null;
+  let protectedResource = null;
+  if (inboundMode.mode === "resource_server") {
+    try {
+      const inbound = await createInboundHttpsAuth({ inboundCfg });
+      authenticate = inbound.authenticate;
+      protectedResource = inbound.protectedResource;
+      checkAuth = () => false;
+      console.error(
+        `[drupal-mcp-connector] Inbound OAuth resource server: issuer ${inboundCfg.issuer}`
+      );
+    } catch (error) {
+      console.error(
+        "[drupal-mcp-connector] FATAL: inbound issuer discovery failed.\n" +
+        `  ${error instanceof Error ? error.message : "unknown error"}`
+      );
+      process.exit(1);
+    }
+  } else if (inboundMode.mode === "unauthenticated" && !allowUnauth) {
     console.error(
-      "[drupal-mcp-connector] FATAL: MCP_AUTH_TOKEN is required when binding beyond loopback.\n" +
-      "  Set MCP_AUTH_TOKEN, bind to 127.0.0.1 (default without MCP_BIND_HOST), or set\n" +
-      "  MCP_ALLOW_UNAUTHENTICATED=1 only behind a trusted auth boundary."
+      "[drupal-mcp-connector] WARNING: the /mcp endpoint is UNAUTHENTICATED. " +
+      "Acceptable only on loopback or behind a trusted auth boundary."
     );
-    process.exit(1);
   }
 
   // Optional fixed-window rate limiting on /mcp, keyed by client IP.
@@ -376,6 +461,8 @@ if (transport === "stdio") {
   });
   const requestHandler = createMcpRequestHandler({
     checkAuth,
+    authenticate,
+    protectedResource,
     modernHandler,
     legacyHandler,
     toolCount: allDefinitions.length,

package/src/lib/config.js

@@ -85,8 +85,26 @@ export function assertSecureAuth(site) {
     throw new SecurityError(`Site "${site._name}": requireSecureAuth is set but baseUrl is not HTTPS.`);
   }
   if (!site.apiToken && !hasValidOauth(site)) {
+    const siteName = site._name ?? "";
+    if (site.oauth?.clientSecretEnv && !site.oauth.clientSecret) {
+      throw new SecurityError(
+        `Site "${siteName}": requireSecureAuth is set but oauth.clientSecretEnv ` +
+        `"${site.oauth.clientSecretEnv}" is not set in the environment.`
+      );
+    }
+    if (site.apiTokenEnv && !site.apiToken) {
+      throw new SecurityError(
+        `Site "${siteName}": requireSecureAuth is set but apiTokenEnv ` +
+        `"${site.apiTokenEnv}" is not set in the environment.`
+      );
+    }
+    if (site.oauth && !site.oauth.clientId) {
+      throw new SecurityError(
+        `Site "${siteName}": requireSecureAuth is set but the oauth block has no clientId.`
+      );
+    }
     throw new SecurityError(
-      `Site "${site._name}": requireSecureAuth is set but no Bearer apiToken or OAuth2 client ` +
+      `Site "${siteName}": requireSecureAuth is set but no Bearer apiToken or OAuth2 client ` +
       "credentials are configured (anonymous and basic auth are not permitted). " +
       "Provide apiToken/apiTokenEnv or an oauth block."
     );
@@ -203,6 +221,29 @@ export function listSiteNames() {
   return Object.keys(loadConfig().sites);
 }
 
+/**
+ * Configured default site name (used only as a hint after entitlement).
+ * @returns {string}
+ */
+export function getDefaultSiteName() {
+  return loadConfig().defaultSite;
+}
+
+/**
+ * Server-resolved inbound site grants keyed by OAuth client id.
+ * A missing or empty map means "no grant table" (every resolvable site).
+ * A present map is fail-closed: unknown clients receive no sites.
+ * @returns {object|null}
+ */
+export function getInboundGrants() {
+  const grants = loadConfig().auth?.grants;
+  if (!grants || typeof grants !== "object" || Array.isArray(grants)) return null;
+  const entries = Object.entries(grants)
+    .filter(([clientId, sites]) => !clientId.startsWith("_") && Array.isArray(sites))
+    .map(([clientId, sites]) => [clientId, sites.map(String)]);
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
 // ---------------------------------------------------------------------------
 // Auth headers — never logged, never exposed in tool responses
 // ---------------------------------------------------------------------------

package/src/lib/dispatch.js

@@ -16,6 +16,7 @@ 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 { assertPrincipalEntitlement, getRequestIdentity } from "./principal.js";
 import { allHandlers } from "../tools/index.js";
 
 /**
@@ -59,17 +60,41 @@ function extractEntityType(toolName, args) {
  * @param {string}   toolName - The MCP tool name.
  * @param {object}   args     - Tool arguments (may carry `site`, `id`, etc.).
  * @param {Function} handler  - The resolved tool handler.
+ * @param {object}   [context] Optional inbound identity / grant overrides (tests).
  * @returns {Promise<*>} The handler's result.
  * @throws {GovernanceError} If the site requires source governance and the
  *   contract is not verified — checked FIRST, so no assertion below can be
  *   read as an ungoverned fallback verdict.
  * @throws {SecurityError} If the resolved policy forbids the inferred operation.
  */
-export async function securityMiddleware(toolName, args, handler) {
-  // Tools with no site context skip per-site checks
-  if (toolName === "drupal_list_sites") return handler(args);
+export async function securityMiddleware(toolName, args, handler, context = {}) {
+  const rawArgs = args ?? {};
+  const identity = context.identity !== undefined ? context.identity : getRequestIdentity();
+  let nextArgs = rawArgs;
 
-  const site = getSiteConfig(args?.site);
+  if (identity) {
+    const resolved = assertPrincipalEntitlement({
+      toolName,
+      args: rawArgs,
+      identity,
+      sites: context.sites ?? listResolvableSiteConfigs(),
+      grants: context.grants,
+      defaultSite: context.defaultSite,
+    });
+    if (resolved) {
+      nextArgs = { ...rawArgs, site: resolved.name };
+    }
+  }
+
+  // Tools with no site context skip per-site checks. governance_status
+  // without a hint reports every granted/configured site and must not
+  // resolve (or fail on) the configured default first.
+  if (toolName === "drupal_list_sites") return handler(nextArgs);
+  if (toolName === "drupal_governance_status" && !nextArgs.site) {
+    return handler(nextArgs);
+  }
+
+  const site = getSiteConfig(nextArgs.site);
 
   // Source-governance gate (#176). The diagnostic tools stay callable while
   // governance fails — they are how an operator learns which condition failed.
@@ -81,15 +106,15 @@ export async function securityMiddleware(toolName, args, handler) {
   const op   = inferOperation(toolName);
 
   if (op === "delete") {
-    assertDestructiveAllowed(sec, extractEntityType(toolName, args), args?.id ?? "?");
+    assertDestructiveAllowed(sec, extractEntityType(toolName, nextArgs), nextArgs?.id ?? "?");
     assertNotReadOnly(sec, toolName);
   } else if (op === "write") {
     assertNotReadOnly(sec, toolName);
-  } else if (op === "graphql" && args?.query) {
-    assertGraphqlMutationAllowed(sec, args.query);
+  } else if (op === "graphql" && nextArgs?.query) {
+    assertGraphqlMutationAllowed(sec, nextArgs.query);
   }
 
-  return handler(args);
+  return handler(nextArgs);
 }
 
 /**
@@ -98,9 +123,10 @@ export async function securityMiddleware(toolName, args, handler) {
  *
  * @param {string} name - The MCP tool name.
  * @param {object} args - The tool arguments.
+ * @param {object} [context] Optional inbound identity / grant overrides.
  * @returns {Promise<object>} An MCP tool result payload.
  */
-export async function callTool(name, args) {
+export async function callTool(name, args, context = {}) {
   // eslint-disable-next-line security/detect-object-injection -- name is an MCP tool name from validated schema; allHandlers is a closed dispatch table built at startup
   const handler = allHandlers[name];
 
@@ -111,7 +137,7 @@ export async function callTool(name, args) {
   }
 
   try {
-    const result = await securityMiddleware(name, args ?? {}, handler);
+    const result = await securityMiddleware(name, args ?? {}, handler, context);
     return toolResult(result);
   } catch (err) {
     // Translate known error classes into clear, non-leaky isError responses;