drupal-mcp-connector 2.5.0 → 2.6.1

package/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **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

@@ -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.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
@@ -291,6 +293,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.1",
+  "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/index.js

@@ -32,6 +32,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { toNodeHandler } from "@modelcontextprotocol/node";
 
 import { listSiteNames, getTlsConfig, CLIENT_VERSION } from "./lib/config.js";
+import { loadLocalSecrets, secretLoadFatalMessage } from "./lib/load-secrets.js";
 import { makeBearerCheck } from "./lib/http-auth.js";
 import { createLegacySessionHandler, createMcpRequestHandler } from "./lib/http-handler.js";
 import { createConnectorServerFactory } from "./lib/mcp-server.js";
@@ -43,6 +44,22 @@ import { filterDiscoverableTools } from "./lib/governance.js";
 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
 // ---------------------------------------------------------------------------

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."
     );

package/src/lib/load-secrets.js

@@ -0,0 +1,158 @@
+/**
+ * Load connector secrets the same way for every entry point.
+ *
+ * MCP clients often spawn `node src/index.js` directly. The shell launcher
+ * cannot be the only place that applies `config/secrets.map`, or a process
+ * that skipped the launcher starts, resolves zero sites, and advertises only
+ * diagnostic tools — the 2.6.0/#180 failure on this machine.
+ *
+ * The default table matches config/config.example.json. A gitignored
+ * config/secrets.map replaces that table for a deployment whose env-var
+ * names differ. Per-item Keychain misses stay silent (inert break-glass).
+ * If the active config.json names secret env vars and none of them are set
+ * after this step, the caller must refuse to start.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Shipped env-var → Keychain-item pairs. Matches config/config.example.json. */
+export const DEFAULT_SECRET_PAIRS = Object.freeze([
+  ["MCP_CONTENT_PRODUCTION_SECRET", "drupal-mcp-content-production"],
+  ["MCP_CONTENT_STAGING_SECRET", "drupal-mcp-content-staging"],
+  ["MCP_DEVELOPER_DEVELOPMENT_SECRET", "drupal-mcp-developer-development"],
+  ["MCP_ADMIN_BREAKGLASS_SECRET", "drupal-mcp-admin-breakglass"],
+]);
+
+/**
+ * Parse a secrets.map body. `#` comments and malformed lines are ignored.
+ * @param {string} text
+ * @returns {Array<[string, string]>}
+ */
+export function parseSecretMap(text) {
+  const pairs = [];
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, "").trim();
+    if (!line || !line.includes("=")) continue;
+    const eq = line.indexOf("=");
+    const varName = line.slice(0, eq).trim();
+    const item = line.slice(eq + 1).trim();
+    if (varName && item) pairs.push([varName, item]);
+  }
+  return pairs;
+}
+
+/**
+ * Collect clientSecretEnv / apiTokenEnv names from a parsed config object.
+ * @param {object} cfg
+ * @returns {string[]}
+ */
+export function namedSecretEnvVars(cfg) {
+  const names = [];
+  const seen = new Set();
+  const walk = (value) => {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach(walk);
+      return;
+    }
+    for (const [key, val] of Object.entries(value)) {
+      if (key.startsWith("_")) continue;
+      if ((key === "clientSecretEnv" || key === "apiTokenEnv") && typeof val === "string") {
+        const name = val.trim();
+        if (name && !seen.has(name)) {
+          seen.add(name);
+          names.push(name);
+        }
+        continue;
+      }
+      walk(val);
+    }
+  };
+  walk(cfg);
+  return names;
+}
+
+/**
+ * Look up one macOS Keychain generic password. Returns "" when missing or
+ * when not on Darwin. Never throws. Never logs the value.
+ * @param {string} item
+ * @returns {string}
+ */
+export function lookupKeychainItem(item) {
+  if (process.platform !== "darwin" || !item) return "";
+  try {
+    const value = execFileSync("security", ["find-generic-password", "-s", item, "-w"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return String(value).replace(/\n$/, "");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Apply the secret table and report how the active config lines up with env.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @param {NodeJS.ProcessEnv} [options.env] Mutated when a lookup succeeds.
+ * @param {typeof readFileSync} [options.readFile]
+ * @param {(item: string) => string} [options.lookup]
+ * @returns {{pairs: number, resolved: number, named: string[], unset: string[]}}
+ */
+export function loadLocalSecrets({
+  cwd = process.cwd(),
+  env = process.env,
+  readFile = readFileSync,
+  lookup = lookupKeychainItem,
+} = {}) {
+  let pairs;
+  try {
+    pairs = parseSecretMap(readFile(join(cwd, "config", "secrets.map"), "utf8"));
+  } catch {
+    pairs = DEFAULT_SECRET_PAIRS;
+  }
+
+  let resolved = 0;
+  for (const [varName, item] of pairs) {
+    const current = new Map(Object.entries(env)).get(varName);
+    if (current) continue;
+    const value = lookup(item);
+    if (!value) continue;
+    Object.defineProperty(env, varName, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+    resolved += 1;
+  }
+
+  let named = [];
+  try {
+    named = namedSecretEnvVars(JSON.parse(readFile(join(cwd, "config", "config.json"), "utf8")));
+  } catch {
+    named = [];
+  }
+
+  const envMap = new Map(Object.entries(env));
+  const unset = named.filter((name) => !envMap.get(name));
+  return { pairs: pairs.length, resolved, named, unset };
+}
+
+/**
+ * Refuse to boot a server that can only advertise diagnostic tools.
+ * @param {{named: string[], unset: string[]}} loaded
+ * @returns {string|null} Fatal message, or null when start is allowed.
+ */
+export function secretLoadFatalMessage(loaded) {
+  if (!loaded.named.length || loaded.unset.length !== loaded.named.length) return null;
+  return (
+    `every clientSecretEnv/apiTokenEnv named in config.json is unset (${loaded.unset.join(", ")}). ` +
+    "Refusing to start. Map those names in config/secrets.map (ENV_VAR=keychain-item) " +
+    "or export them before launch."
+  );
+}