drupal-mcp-connector 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-08-15
+
+### Added
+- **Secure-install verifier (`npm run verify`, #180).** Produces evidence that
+  an installation carries the secure, tenant-neutral defaults the governed
+  product claims, instead of asserting it in a README. The static half needs no
+  network or credentials and runs in CI: transport, principal authentication,
+  scope grant, source governance, role separation, entitlement, target
+  resolution and tenant neutrality. The live half (`--live --site <name>`)
+  proves the same claims against a running target and adds three **negative
+  probes** — a mass read, a configuration change and a live-content edit — that
+  pass only when the target refuses them (a mass read that is *bounded* rather
+  than refused also passes; a cap is the control working). The config probe
+  goes through the connector's own bridge client, so it exercises the real MCP
+  session and governed tool contract, and is skipped for a principal that
+  legitimately holds `mcp_config`. A thrown bridge error is classified before
+  it is scored: a tool refusal, a server-defined JSON-RPC error or a 401/403
+  is a decision and passes; a missing bridge, a session failure, a network
+  error or a malformed-call error never reached policy and is skipped. The
+  content probe takes an explicit `--content-target` and counts only a 403/401
+  as a refusal — a 404 means the publish gate was never reached, not that it
+  held. `--json` prints an evidence document
+  (connector version, redacted config digest, per-check outcome, the source's
+  own refusal codes) for a release record. A check that cannot run reports
+  `skipped` and fails the run, while a check that does not *apply* to this
+  shape of install (no OAuth, no tool bridge, an in-tier principal) reports
+  `n/a` and does not — a verifier a secure install can never pass is one people
+  stop running. Nothing secret ever reaches the output. See
+  `docs/verification.md`.
+- **Prompt injection and operator trust documented as managed residuals**
+  (`docs/threat-model.md`, `docs/verification.md`) and emitted with every
+  evidence document — the stack bounds the blast radius, it does not solve
+  them (#180).
+
+### Changed
+- **The shipped example configuration is tenant-neutral and secure by default**
+  (#180). Every hostname is documentation-reserved (RFC 2606/6761); the four
+  tiers are named as roles (production, staging, development, break-glass) and
+  each carries **its own OAuth client id and its own secret env var** — the
+  previous example shared one consumer and one development secret across tiers.
+  Staging and development now declare `requireGovernance`, and the permissive
+  `development` preset is confined to a loopback target. `bin/drupal-mcp-launch.sh`
+  reads its env-var → Keychain-item mapping from a table (overridable per
+  machine via `config/secrets.map`) instead of hardcoding one estate's items.
+  CI verifies the shipped example on every run.
+
+### Security
+- **The empty-scope bypass is closed for governed setups (#180).** An OAuth site
+  that named no scopes previously satisfied *every* scope gate, including
+  `mcp_config`: an empty list was read as "unconstrained". It is now read as an
+  unnamed grant and satisfies nothing, so a governed site must name the scopes
+  its token actually carries. A site with no OAuth block (a plain
+  `apiTokenEnv`/anonymous install) is unaffected and stays preset-only.
+
 ## [2.5.0] - 2026-08-14
 
 ### Fixed

package/README.md

@@ -291,6 +291,7 @@ an operator channel: keep the agent's credentials off it, and pin
 | [Tools Reference](docs/tools-reference.md) | Full reference for all 119 tools |
 | [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
 | [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
+| [Verification](docs/verification.md) | Prove a secure install: static + live checks, negative probes, evidence artefact, managed residuals |
 | [Threat Model](docs/threat-model.md) | Trust boundaries, threats & mitigations, residual risks, and the security-pass results |
 | [Deployment](docs/deployment.md) | Run the HTTPS transport in production: Docker, systemd, launchd, reverse proxy, pre-exposure checklist |
 | [Integration Contract](docs/integration-contract.md) | The connector ↔ Drupal-governance contract (identity, OAuth scopes, compatibility) |

package/bin/drupal-mcp-verify.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Secure-install verifier (#180).
+ *
+ * Produces evidence that this installation carries the secure, tenant-neutral
+ * defaults the governed product claims — rather than asserting it in a README.
+ *
+ *   npm run verify                          # static checks on config/config.json
+ *   npm run verify -- --config config/config.example.json
+ *   npm run verify -- --live --site production
+ *   npm run verify -- --live --site staging --json > evidence.json
+ *
+ * Exit code is 0 only when every check that ran passed AND none was skipped:
+ * a skipped check is not evidence. The JSON form is the artefact to attach to
+ * a release proof; it carries hosts, outcomes and refusal codes, never
+ * payloads, tokens or secrets.
+ */
+
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import fetch from "node-fetch";
+import { verifyStatic, verifyLive } from "../src/lib/verify.js";
+import { loadConfig, getSiteConfig, resolveOauth } from "../src/lib/config.js";
+import { callServerTool } from "../src/lib/server-tools.js";
+
+/** Parses `--flag`, `--key value` and `--key=value`. */
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      args._.push(arg);
+      continue;
+    }
+    const [key, inline] = arg.slice(2).split("=");
+    if (inline !== undefined) {
+      args[key] = inline;
+    } else if (argv[i + 1] && !argv[i + 1].startsWith("--")) {
+      args[key] = argv[++i];
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+const USAGE = `drupal-mcp-connector verify
+
+  --config <path>   Verify this configuration file instead of the loaded one.
+  --live            Also verify a running target (needs credentials in env).
+  --site <name>     Which site to verify live. Defaults to the default site.
+  --content-target <uuid>
+                    A node the live run may attempt a publish-bearing edit
+                    against. Without it that probe is skipped: a PATCH at a
+                    non-existent id returns 404 before any access check, so
+                    scoring it would claim the publish gate holds without
+                    reaching it. Use a NON-PRODUCTION target you would not
+                    mind being published if the gate fails.
+  --content-target-type <type>
+                    JSON:API resource type of that target (default node--article).
+  --json            Print the evidence document instead of a summary.
+  --help            Show this message.
+`;
+
+/** Human-readable one-line-per-check report. */
+function report(evidence) {
+  const mark = { pass: "PASS", fail: "FAIL", skipped: "SKIP", "n/a": "N/A " };
+  const lines = [
+    `${evidence.tool} (${evidence.mode}) — connector ${evidence.connectorVersion}`,
+    `subject: ${JSON.stringify(evidence.subject)}`,
+    "",
+  ];
+  for (const check of evidence.checks) {
+    lines.push(`  [${mark[check.status]}] ${check.id} — ${check.title}`);
+    for (const finding of check.findings) lines.push(`         ${finding}`);
+  }
+  lines.push("");
+  lines.push(
+    `  ${evidence.summary.pass} passed, ${evidence.summary.fail} failed, ` +
+    `${evidence.summary.skipped} skipped (unproven), ${evidence.summary.notApplicable} not applicable`,
+  );
+  lines.push("");
+  lines.push("  Managed residuals (not solved by this stack):");
+  for (const residual of evidence.residuals) lines.push(`    - ${residual.id}: ${residual.detail}`);
+  return lines.join("\n");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const config = args.config
+    ? JSON.parse(readFileSync(String(args.config), "utf8"))
+    : loadConfig();
+  const source = args.config ? String(args.config) : "config/config.json";
+
+  // Documentation keys (leading underscore) are prose, not configuration.
+  const strip = (value) => {
+    if (Array.isArray(value)) return value.map(strip);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(
+        Object.entries(value).filter(([k]) => !k.startsWith("_")).map(([k, v]) => [k, strip(v)]),
+      );
+    }
+    return value;
+  };
+
+  const evidence = [verifyStatic(strip(config), { source })];
+
+  if (args.live) {
+    const siteName = args.site ? String(args.site) : undefined;
+    // getSiteConfig resolves secrets from the environment; nothing is read
+    // from the config file itself.
+    const site = args.config
+      ? resolveOauth({ ...(config.sites?.[siteName ?? config.defaultSite] ?? {}), _name: siteName ?? config.defaultSite })
+      : getSiteConfig(siteName);
+    // The real bridge client, so the governed-tool probes exercise the real
+    // contract (MCP session, tool_api name, tool-level refusal) rather than a
+    // hand-rolled JSON-RPC body the server would reject as malformed.
+    evidence.push(
+      await verifyLive(site, {
+        transport: fetch,
+        callTool: callServerTool,
+        contentTarget: args["content-target"] ? String(args["content-target"]) : null,
+        contentTargetType: args["content-target-type"] ? String(args["content-target-type"]) : null,
+      }),
+    );
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(evidence.length === 1 ? evidence[0] : evidence, null, 2) + "\n");
+  } else {
+    process.stdout.write(evidence.map(report).join("\n\n") + "\n");
+  }
+
+  return evidence.every((e) => e.summary.ok) ? 0 : 1;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`verify: ${err?.message ?? err}\n`);
+    process.exit(2);
+  });

package/config/config.example.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Copy to config/config.json and fill in your values. This file is safe to commit. config.json is gitignored.",
+  "_comment": "Copy to config/config.json and fill in your values. This file is safe to commit; config.json is gitignored. Every hostname here is a documentation-reserved example (RFC 2606/6761) — replace them with your own. Verify a filled-in config with `npm run verify`.",
 
   "_api_modes": {
     "_comment": "Per-site 'api' selects the backend: 'graphql' | 'jsonapi' | a priority array like ['graphql','jsonapi']. Omit to auto-detect (probes both once). GraphQL is read-only (no mutations); writes require a JSON:API site.",
@@ -7,14 +7,14 @@
   },
 
   "_security_options": {
-    "_comment": "All optional. apiTokenEnv: read the Bearer token from this env var instead of apiToken (keeps secrets out of the config file). requireSecureAuth: reject anon/basic, require HTTPS+Bearer (recommended for production). requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel >= 2.4.0) verifies — no ungoverned JSON:API/GraphQL fallback; recommended wherever mcp_sentinel governs the site. 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_AUTH_TOKEN requires bearer auth on the HTTPS /mcp endpoint; MCP_BIND_HOST restricts the listen interface (with TLS). See docs/security-hardening.md."
   },
 
   "_governance_tiers": {
-    "_comment": "These four sites model the MCP agent governance tiers: least privilege keyed by environment. The Drupal side (mcp_sentinel) is authoritative; the per-site security preset is a defence-in-depth second layer. Tiers: content (prod/staging), developer (dev), admin/break-glass (dev-admin). serverTools wires the governed config tools (drupal_config_get/list/set); drushSsh is dev-only and whitelisted to config export/status. See docs/integration-contract.md."
+    "_comment": "The sites below model agent governance tiers as ROLES, not as a particular estate: least privilege keyed by environment. The Drupal side (mcp_sentinel) is authoritative; the per-site security preset is a defence-in-depth second layer. Tiers: content (production, staging), developer (development), admin/break-glass (loopback only). Each tier gets its OWN OAuth client and its OWN secret env var — sharing either makes a compromise of one role a compromise of all of them. serverTools wires the governed config tools (drupal_config_get/list/set); drushSsh is development-only and whitelisted to config export/status. See docs/integration-contract.md."
   },
 
-  "defaultSite": "prod",
+  "defaultSite": "production",
 
   "tls": {
     "_comment": "TLS is required for the HTTPS transport (MCP_TRANSPORT=https). Ignored in stdio mode.",
@@ -24,16 +24,16 @@
   },
 
   "sites": {
-    "prod": {
-      "_comment": "Content tier. Content/media/term CRUD; config read-only; cannot publish (server-side editorial gate). No drushSsh.",
-      "baseUrl":           "https://api.int.wilkesliberty.com",
+    "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.",
+      "baseUrl":           "https://drupal.example.com",
       "requireSecureAuth": true,
       "requireGovernance": true,
       "api":               "jsonapi",
       "oauth": {
         "tokenUrl":        "/oauth/token",
-        "clientId":        "mcp-agent",
-        "clientSecretEnv": "MCP_AGENT_CLIENT_SECRET",
+        "clientId":        "content-agent-production",
+        "clientSecretEnv": "MCP_CONTENT_PRODUCTION_SECRET",
         "scopes":          ["mcp_read", "mcp_write"],
         "grant":           "client_credentials"
       },
@@ -42,14 +42,15 @@
     },
 
     "staging": {
-      "_comment": "Content tier. Same capabilities as prod against the staging environment.",
-      "baseUrl":           "https://api-stg.int.wilkesliberty.com",
+      "_comment": "Content tier against the staging environment. Same capabilities as production, its own principal and its own secret.",
+      "baseUrl":           "https://drupal-staging.example.com",
       "requireSecureAuth": true,
+      "requireGovernance": true,
       "api":               "jsonapi",
       "oauth": {
         "tokenUrl":        "/oauth/token",
-        "clientId":        "mcp-agent",
-        "clientSecretEnv": "MCP_AGENT_CLIENT_SECRET_STG",
+        "clientId":        "content-agent-staging",
+        "clientSecretEnv": "MCP_CONTENT_STAGING_SECRET",
         "scopes":          ["mcp_read", "mcp_write"],
         "grant":           "client_credentials"
       },
@@ -57,23 +58,24 @@
       "security":    { "preset": "content-editor" }
     },
 
-    "dev": {
-      "_comment": "Developer tier (DDEV). Content + governed config read/write. Drush bridge is dev-only and whitelisted to config export/status; the agent mutates config via drupal_config_set, then exports to YAML for a PR.",
-      "baseUrl":           "https://api.wilkesliberty.dev",
+    "development": {
+      "_comment": "Developer tier. Content + governed config read/write. The drush bridge is development-only and whitelisted to config export/status; the agent mutates config via drupal_config_set, then exports to YAML for a pull request.",
+      "baseUrl":           "https://drupal.example.test",
       "requireSecureAuth": true,
+      "requireGovernance": true,
       "api":               "jsonapi",
       "oauth": {
         "tokenUrl":        "/oauth/token",
-        "clientId":        "mcp-agent",
-        "clientSecretEnv": "MCP_AGENT_CLIENT_SECRET_DEV",
+        "clientId":        "developer-agent-development",
+        "clientSecretEnv": "MCP_DEVELOPER_DEVELOPMENT_SECRET",
         "scopes":          ["mcp_read", "mcp_write", "mcp_config"],
         "grant":           "client_credentials"
       },
       "serverTools": { "url": "/mcp" },
       "drushSsh": {
-        "_comment": "Dev only. DDEV web-container SSH target. Whitelisted to config export/status — every other drupal_drush_* tool is blocked here. rawSql is omitted, so drupal_drush_sql_query is refused: raw SQL reads underneath Drupal's entity API and is only available via mcp_sentinel's governed command. To enable it, set rawSql:\"governed\", add \"mcp-sentinel:sql-query\" to allowedCommands, and set allow_raw_sql on the site's policy profile.",
-        "host":            "<ddev-web-container-ssh-host>",
-        "user":            "<ddev-ssh-user>",
+        "_comment": "Development only. SSH target of the local web container. Whitelisted to config export/status — every other drupal_drush_* tool is blocked here. rawSql is omitted, so drupal_drush_sql_query is refused: raw SQL reads underneath Drupal's entity API and is only available via mcp_sentinel's governed command. To enable it, set rawSql:\"governed\", add \"mcp-sentinel:sql-query\" to allowedCommands, and set allow_raw_sql on the site's policy profile.",
+        "host":            "<web-container-ssh-host>",
+        "user":            "<web-container-ssh-user>",
         "keyPath":         "~/.ssh/id_ed25519",
         "drupalRoot":      "/var/www/html/web",
         "port":            22,
@@ -81,7 +83,7 @@
       },
       "audit": {
         "_comment": "Optional. Controls drupal_report_broken_links live checking (off unless checkLive:true is passed). linkCheckAllowedHosts gates external hosts; same-origin links are always allowed when checking live.",
-        "linkCheckAllowedHosts": ["www.drupal.org", "wilkesliberty.com"],
+        "linkCheckAllowedHosts": ["www.drupal.org", "example.com"],
         "linkCheckConcurrency":  5,
         "linkCheckTimeoutMs":    5000,
         "linkCheckMaxLinks":     200
@@ -89,15 +91,15 @@
       "security": { "preset": "config-editor" }
     },
 
-    "dev-admin": {
-      "_comment": "Admin / break-glass tier (DDEV). All capabilities incl. destructive + config import — non-standing. Reuses the dev secret. No drushSsh (admin ops go through governed/approval-gated server tools).",
-      "baseUrl":           "https://api.wilkesliberty.dev",
+    "break-glass": {
+      "_comment": "Admin / break-glass tier — non-standing, and deliberately LOOPBACK ONLY: the permissive 'development' preset allows every operation including deletes and config import, so it is never pointed at a remote host in a shipped default. Its own principal and secret. No drushSsh (admin operations go through governed, approval-gated server tools).",
+      "baseUrl":           "https://localhost:8443",
       "requireSecureAuth": true,
       "api":               "jsonapi",
       "oauth": {
         "tokenUrl":        "/oauth/token",
-        "clientId":        "mcp-agent",
-        "clientSecretEnv": "MCP_AGENT_CLIENT_SECRET_DEV",
+        "clientId":        "admin-agent-breakglass",
+        "clientSecretEnv": "MCP_ADMIN_BREAKGLASS_SECRET",
         "scopes":          ["mcp_read", "mcp_write", "mcp_config", "mcp_admin"],
         "grant":           "client_credentials"
       },
@@ -107,7 +109,7 @@
   },
 
   "_security_presets": {
-    "development":       "All operations allowed, incl. config read/write. Local dev / break-glass only.",
+    "development":       "All operations allowed, incl. config read/write. Loopback / break-glass only.",
     "content-editor":    "Create/edit the full content set (node, media, taxonomy_term, paragraph, block_content, menu_link_content, redirect, path_alias, file). No deletes. Config read-only. Denies user + secrets/governance types.",
     "config-editor":     "content-editor + site-building config entities (read/introspection) + governed config read/write (Developer tier). Model changes go via the config bridge, not JSON:API.",
     "auditor":           "Read-only. All entity types. User PII fields redacted. Config read-only.",
@@ -134,7 +136,7 @@
   "_https_transport_registration": {
     "_comment": "For multi-client HTTP mode — register the HTTPS endpoint instead",
     "drupal": {
-      "url": "https://your-server:3443/mcp"
+      "url": "https://mcp.example.com:3443/mcp"
     }
   }
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.5.0",
-  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
+  "version": "2.6.0",
+  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal \u2014 dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
-    "drupal-mcp-connector": "src/index.js"
+    "drupal-mcp-connector": "src/index.js",
+    "drupal-mcp-verify": "bin/drupal-mcp-verify.js"
   },
   "files": [
     "src/",
@@ -55,7 +56,9 @@
     "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 ✓\"; done"
+    "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",
+    "verify": "node bin/drupal-mcp-verify.js",
+    "verify:example": "node bin/drupal-mcp-verify.js --config config/config.example.json"
   },
   "dependencies": {
     "@modelcontextprotocol/node": "^2.0.0",

package/src/lib/security.js

@@ -343,16 +343,39 @@ export function assertConfigWriteAllowed(secConfig) {
 }
 
 /**
- * Whether the site's OAuth token carries a given scope. When the site declares
- * no OAuth scopes (no agent channel configured), scope gating is a no-op and
- * this returns true so preset-only (non-OAuth) setups are unaffected.
+ * Whether the site's OAuth token carries a given scope. A governed setup that
+ * names no scopes carries none of them (#180) — an unnamed grant is not a
+ * wildcard. A preset-only, non-OAuth site keeps the permissive behaviour.
  * @param {object} site Resolved site config.
  * @param {string} scope OAuth scope machine id (e.g. "mcp_config").
  * @returns {boolean} True if the scope is present, or no scopes are configured.
  */
 export function hasScope(site, scope) {
   const scopes = site?.oauth?.scopes ?? [];
-  return scopes.length === 0 || scopes.includes(scope);
+  if (scopes.length > 0) return scopes.includes(scope);
+  // Empty or absent scopes. For a GOVERNED product setup — a site that claims
+  // source governance, or configures OAuth at all — that is not "every scope";
+  // it is an unnamed grant, and treating it as a wildcard was a bypass of the
+  // very gate the scopes exist to be (#180). Deny, so the operator has to name
+  // the scopes the token actually carries.
+  //
+  // An ungoverned install (a plain apiToken or anonymous site, no OAuth block)
+  // has no scope vocabulary to name and keeps the historical permissive
+  // behaviour: preset semantics alone decide there.
+  return !isGovernedSetup(site);
+}
+
+/**
+ * Whether a site is part of the governed product path.
+ *
+ * Either it declares the source-governance requirement, or it authenticates
+ * with OAuth — both mean the server is deciding on scopes, so the connector
+ * must not invent one.
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+export function isGovernedSetup(site) {
+  return site?.requireGovernance === true || Boolean(site?.oauth);
 }
 
 /**