drupal-mcp-connector 0.6.1

package/src/lib/config.js

@@ -0,0 +1,257 @@
+/**
+ * Config loading, site resolution, and auth header generation.
+ *
+ * Security notes:
+ *   - Credentials are loaded once, cached in memory, never logged.
+ *   - validateBaseUrl() enforces HTTPS for non-localhost connections.
+ *   - All exported functions are pure — no side effects beyond the cache.
+ */
+
+import { readFileSync }                  from "fs";
+import { resolve }                       from "path";
+import { validateBaseUrl }               from "./validate.js";
+import { SecurityError }                 from "./security.js";
+import { getAccessToken }                from "./oauth.js";
+
+/** Connector version for the X-MCP-Client identity label. Keep in sync with package.json. */
+export const CLIENT_VERSION = "0.6.0";
+
+/**
+ * Identity headers sent on every outbound Drupal request. Lets governance layers
+ * label/identify connector traffic. ON by default; set MCP_CLIENT_ID to override
+ * the value, or to "" to disable entirely.
+ * @returns {Object<string,string>} Header map (empty when the identity is disabled).
+ */
+export function clientHeaders() {
+  const id = process.env.MCP_CLIENT_ID ?? `drupal-mcp-connector/${CLIENT_VERSION}`;
+  if (!id) return {};
+  return { "X-MCP-Client": id, "User-Agent": id };
+}
+
+/**
+ * If a site declares apiTokenEnv and has no explicit apiToken, source the token
+ * from that environment variable (keeps secrets out of the config file).
+ * @param {object} site Raw site config.
+ * @returns {object} The site, possibly with apiToken populated from the env var.
+ */
+export function resolveApiToken(site) {
+  if (site.apiToken || !site.apiTokenEnv) return site;
+  const fromEnv = new Map(Object.entries(process.env)).get(site.apiTokenEnv) || "";
+  return { ...site, apiToken: fromEnv };
+}
+
+/**
+ * If a site declares an oauth block, source the client secret from the named
+ * env var when no explicit clientSecret is set, and apply defaults for tokenUrl
+ * and grant. Keeps the secret out of the config file.
+ * @param {object} site Raw site config.
+ * @returns {object} The site with a normalized oauth block (unchanged if no oauth).
+ */
+export function resolveOauth(site) {
+  if (!site.oauth) return site;
+  const oauth = { ...site.oauth };
+  if (!oauth.clientSecret && oauth.clientSecretEnv) {
+    oauth.clientSecret = new Map(Object.entries(process.env)).get(oauth.clientSecretEnv) || "";
+  }
+  oauth.tokenUrl = oauth.tokenUrl || "/oauth/token";
+  oauth.grant = oauth.grant || "client_credentials";
+  return { ...site, oauth };
+}
+
+/**
+ * Whether a site has a usable OAuth2 client-credentials block (clientId plus a
+ * resolved clientSecret). Used to satisfy the strong-auth requirement.
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+function hasValidOauth(site) {
+  return Boolean(site.oauth?.clientId && site.oauth?.clientSecret);
+}
+
+/**
+ * Opt-in strong-auth enforcement. When site.requireSecureAuth is true, the site
+ * must use HTTPS and either a Bearer apiToken or a valid OAuth2 client-credentials
+ * block — anonymous and basic auth are rejected.
+ * @param {object} site Resolved site config.
+ * @returns {void}
+ * @throws {SecurityError} if the site is not HTTPS, or lacks a Bearer/OAuth credential.
+ */
+export function assertSecureAuth(site) {
+  if (!site.requireSecureAuth) return;
+  if (!String(site.baseUrl || "").startsWith("https://")) {
+    throw new SecurityError(`Site "${site._name}": requireSecureAuth is set but baseUrl is not HTTPS.`);
+  }
+  if (!site.apiToken && !hasValidOauth(site)) {
+    throw new SecurityError(
+      `Site "${site._name}": 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."
+    );
+  }
+}
+
+/** In-memory cache of the parsed config; populated once by loadConfig(). */
+let _config = null;
+
+// ---------------------------------------------------------------------------
+// Load + validate config
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and validate the connector config, caching the result for the process
+ * lifetime. Reads config/config.json when present; otherwise falls back to a
+ * single-site config built from environment variables.
+ * @returns {object} The parsed, validated config object.
+ * @throws {Error|SecurityError} if validation fails (see validateConfig).
+ */
+export function loadConfig() {
+  if (_config) return _config;
+
+  // Config file takes priority; env vars are the single-site fallback.
+  try {
+    const configPath = resolve(process.cwd(), "config", "config.json");
+    _config = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch {
+    _config = {
+      defaultSite: "default",
+      sites: {
+        default: {
+          baseUrl:         process.env.DRUPAL_BASE_URL      || "",
+          apiToken:        process.env.DRUPAL_API_TOKEN     || "",
+          username:        process.env.DRUPAL_USERNAME       || "",
+          password:        process.env.DRUPAL_PASSWORD       || "",
+          graphqlEndpoint: process.env.DRUPAL_GRAPHQL_ENDPOINT || "/graphql",
+        },
+      },
+    };
+  }
+
+  validateConfig(_config);
+  return _config;
+}
+
+/**
+ * Validate a config object in place, normalizing each site's baseUrl and warning
+ * on weak/ambiguous credential setups.
+ * @param {object} cfg Parsed config.
+ * @returns {void}
+ * @throws {Error} if `sites` is missing/malformed or a site lacks baseUrl.
+ * @throws {SecurityError} if a non-localhost baseUrl is not HTTPS (via validateBaseUrl).
+ */
+function validateConfig(cfg) {
+  if (!cfg.sites || typeof cfg.sites !== "object") {
+    throw new Error("Config error: 'sites' must be an object.");
+  }
+
+  for (const [name, site] of Object.entries(cfg.sites)) {
+    if (!site.baseUrl) {
+      throw new Error(`Config error: site "${name}" is missing "baseUrl".`);
+    }
+
+    // Enforce HTTPS for non-localhost — throws SecurityError for plain HTTP
+    site.baseUrl = validateBaseUrl(site.baseUrl, name);
+
+    if (!site.apiToken && !(site.username && site.password) && !site.oauth) {
+      console.warn(
+        `[drupal-mcp-connector] Warning: site "${name}" has no apiToken, username/password, or oauth block. ` +
+        "Unauthenticated requests will be limited to public content."
+      );
+    }
+
+    if (site.apiToken && site.username) {
+      console.warn(
+        `[drupal-mcp-connector] Warning: site "${name}" has both apiToken and username set. ` +
+        "apiToken takes priority. Remove the unused credential."
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Site resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a named site config, falling back to the default.
+ * @param {string|undefined} siteName
+ * @returns {object} Site config with _name injected.
+ * @throws if the site name is unknown.
+ */
+export function getSiteConfig(siteName) {
+  const cfg  = loadConfig();
+  const name = siteName || cfg.defaultSite;
+  const site = new Map(Object.entries(cfg.sites)).get(name);
+
+  if (!site) {
+    const available = Object.keys(cfg.sites).join(", ");
+    throw new Error(`Unknown site: "${name}". Configured sites: ${available}`);
+  }
+
+  const resolved = resolveOauth(resolveApiToken({ ...site, _name: name }));
+  assertSecureAuth(resolved);
+  return resolved;
+}
+
+/**
+ * List the configured site names.
+ * @returns {string[]}
+ */
+export function listSiteNames() {
+  return Object.keys(loadConfig().sites);
+}
+
+// ---------------------------------------------------------------------------
+// Auth headers — never logged, never exposed in tool responses
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the Authorization header for a site.
+ * Bearer token takes priority over Basic auth.
+ * @param {object} site
+ * @returns {object} Headers object
+ */
+export function authHeaders(site) {
+  if (site.apiToken) {
+    return { Authorization: `Bearer ${site.apiToken}` };
+  }
+  if (site.username && site.password) {
+    const creds = Buffer.from(`${site.username}:${site.password}`).toString("base64");
+    return { Authorization: `Basic ${creds}` };
+  }
+  return {};
+}
+
+/**
+ * Async variant of authHeaders. For OAuth2 sites it resolves a Bearer token
+ * from the token manager (acquiring/refreshing as needed); for all other sites
+ * it falls back to the synchronous static-credential path.
+ * @param {object} site
+ * @returns {Promise<object>} Headers object
+ */
+export async function authHeadersAsync(site) {
+  if (site.oauth) {
+    return { Authorization: `Bearer ${await getAccessToken(site)}` };
+  }
+  return authHeaders(site);
+}
+
+// ---------------------------------------------------------------------------
+// TLS config (for HTTP transport mode)
+// ---------------------------------------------------------------------------
+
+/** Default HTTPS listen port for the HTTP transport when none is configured. */
+const DEFAULT_TLS_PORT = 3443;
+
+/**
+ * Returns TLS cert + key paths and listen port from config or environment
+ * variables. Used by the HTTP transport to set up HTTPS.
+ * @returns {{certPath: string|null, keyPath: string|null, port: number}}
+ */
+export function getTlsConfig() {
+  const cfg = loadConfig();
+  return {
+    certPath: cfg.tls?.certPath || process.env.TLS_CERT_PATH || null,
+    keyPath:  cfg.tls?.keyPath  || process.env.TLS_KEY_PATH  || null,
+    port:     Number(cfg.tls?.port || process.env.MCP_PORT || DEFAULT_TLS_PORT),
+  };
+}

package/src/lib/drupal-fetch.js

@@ -0,0 +1,144 @@
+/**
+ * Authenticated HTTP wrappers for Drupal JSON:API and file uploads.
+ */
+
+import fetch from "node-fetch";
+import { createReadStream, statSync } from "fs";
+import { basename } from "path";
+import { authHeadersAsync, clientHeaders } from "./config.js";
+import { clearToken } from "./oauth.js";
+
+const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
+
+/**
+ * Standard JSON:API request against a site.
+ *
+ * For OAuth2 sites, a 401 triggers a single retry: the cached token is cleared,
+ * re-acquired, and the request is replayed once before the error surfaces.
+ * @param {object} site Resolved site config (provides baseUrl + auth).
+ * @param {string} path Path appended to site.baseUrl (e.g. "/jsonapi/node/article").
+ * @param {object} [options] node-fetch options (method, body, extra headers).
+ * @returns {Promise<object|null>} Parsed JSON body, or null for a 204 No Content.
+ * @throws {Error} on any non-2xx response, with Drupal error detail when available.
+ */
+export async function drupalFetch(site, path, options = {}) {
+  const url = `${site.baseUrl}${path}`;
+
+  async function attempt() {
+    return fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": JSON_API_CONTENT_TYPE,
+        Accept: JSON_API_CONTENT_TYPE,
+        ...clientHeaders(),
+        ...(await authHeadersAsync(site)),
+        ...(options.headers || {}),
+      },
+    });
+  }
+
+  let res = await attempt();
+
+  // OAuth sites: a 401 may mean the token expired server-side. Refresh once.
+  if (res.status === 401 && site.oauth) {
+    clearToken(site);
+    res = await attempt();
+  }
+
+  if (!res.ok) {
+    const body = await res.text();
+    let detail = body;
+    try {
+      const parsed = JSON.parse(body);
+      // Drupal JSON:API surfaces errors in errors[].detail
+      if (parsed.errors?.length) {
+        detail = parsed.errors.map((e) => e.detail || e.title).join("; ");
+      }
+    } catch { /* use raw body */ }
+    throw new Error(`Drupal ${res.status} on ${options.method || "GET"} ${path}: ${detail}`);
+  }
+
+  if (res.status === 204) return null; // No Content (e.g. DELETE success)
+  return res.json();
+}
+
+/**
+ * GraphQL request — posts a JSON body to the site's GraphQL endpoint.
+ * @param {object} site Resolved site config (provides baseUrl + auth).
+ * @param {object} body GraphQL request body, e.g. { query, variables }.
+ * @returns {Promise<object>} Parsed GraphQL JSON response.
+ * @throws {Error} on any non-2xx response (clears the OAuth token cache on 401).
+ */
+export async function drupalGraphqlFetch(site, body) {
+  const endpoint = site.graphqlEndpoint || "/graphql";
+  const url = `${site.baseUrl}${endpoint}`;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...clientHeaders(),
+      ...(await authHeadersAsync(site)),
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    // OAuth sites: a 401 likely means the token expired server-side. Clear the
+    // cached token so the next request re-acquires, then surface the error.
+    if (res.status === 401 && site.oauth) clearToken(site);
+    const text = await res.text();
+    throw new Error(`GraphQL request failed ${res.status}: ${text}`);
+  }
+
+  return res.json();
+}
+
+/**
+ * File upload via Drupal's JSON:API file upload endpoint.
+ *
+ * Endpoint pattern:
+ *   POST /jsonapi/{entity_type}/{bundle}/{field_name}
+ *
+ * With headers:
+ *   Content-Type: application/octet-stream
+ *   Content-Disposition: file; filename="foo.jpg"
+ *
+ * Returns a File entity (not a Media entity — call createMedia next).
+ * @param {object} site Resolved site config (provides baseUrl + auth).
+ * @param {string} entityType Target entity type (e.g. "media").
+ * @param {string} bundle Target bundle (e.g. "image").
+ * @param {string} fieldName File field on the bundle (e.g. "field_media_image").
+ * @param {string} filePath Local path to the file to upload.
+ * @returns {Promise<object>} Parsed JSON:API File entity response.
+ * @throws {Error} on any non-2xx response.
+ */
+export async function drupalUploadFile(site, entityType, bundle, fieldName, filePath) {
+  const filename = basename(filePath);
+  // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a caller-supplied local upload path (validated upstream); fs access is the intended behavior
+  const stat = statSync(filePath);
+  const url = `${site.baseUrl}/jsonapi/${entityType}/${bundle}/${fieldName}`;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/octet-stream",
+      "Content-Disposition": `file; filename="${filename}"`,
+      Accept: JSON_API_CONTENT_TYPE,
+      ...clientHeaders(),
+      ...(await authHeadersAsync(site)),
+    },
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a caller-supplied local upload path (validated upstream); fs access is the intended behavior
+    body: createReadStream(filePath),
+    // node-fetch requires explicit size for streams to set Content-Length
+    size: stat.size,
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`File upload failed ${res.status}: ${body}`);
+  }
+
+  return res.json();
+}

package/src/lib/errors.js

@@ -0,0 +1,38 @@
+/**
+ * Error utilities for consistent MCP tool error responses.
+ */
+
+/**
+ * Wrap a thrown error into the MCP CallTool error response shape.
+ * @param {Error|*} err The caught error (or any thrown value).
+ * @returns {{content: Array<{type: string, text: string}>, isError: true}}
+ */
+export function toolError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true,
+  };
+}
+
+/**
+ * Wrap a successful result into the MCP CallTool response shape (JSON-stringified).
+ * @param {*} data Serializable result payload.
+ * @returns {{content: Array<{type: string, text: string}>}}
+ */
+export function toolResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+/**
+ * Wrap a plain string message (for confirmations, warnings, etc.).
+ * @param {string} text Message text.
+ * @returns {{content: Array<{type: string, text: string}>}}
+ */
+export function toolMessage(text) {
+  return {
+    content: [{ type: "text", text }],
+  };
+}

package/src/lib/http-auth.js

@@ -0,0 +1,27 @@
+/**
+ * Optional bearer-token authentication for the HTTPS MCP transport.
+ * makeBearerCheck(token) returns a predicate over the Authorization header.
+ * A falsy token disables auth (predicate always true) — opt-in by design.
+ */
+
+import { timingSafeEqual } from "crypto";
+
+/**
+ * Build a predicate that validates an HTTP Authorization header against an
+ * expected bearer token.
+ * @param {?string} token Expected token; falsy disables auth (predicate is always true).
+ * @returns {(authorizationHeader: any) => boolean} True when the header carries the token.
+ */
+export function makeBearerCheck(token) {
+  if (!token) return () => true; // auth disabled
+  const expected = Buffer.from(String(token));
+  return (authorizationHeader) => {
+    if (typeof authorizationHeader !== "string") return false;
+    const prefix = "Bearer ";
+    if (!authorizationHeader.startsWith(prefix)) return false;
+    const provided = Buffer.from(authorizationHeader.slice(prefix.length));
+    // Length check first: timingSafeEqual throws on unequal-length buffers, and
+    // the comparison itself stays constant-time to avoid leaking the token.
+    return provided.length === expected.length && timingSafeEqual(provided, expected);
+  };
+}

package/src/lib/oauth.js

@@ -0,0 +1,177 @@
+/**
+ * OAuth2 token manager for the client_credentials grant against Drupal
+ * simple_oauth.
+ *
+ * Security notes:
+ *   - The client secret is read from the resolved site config (sourced from an
+ *     env var, see resolveOauth). It is sent only in the token request body and
+ *     is never logged or included in thrown errors.
+ *   - Tokens are cached in memory per site and silently re-acquired before
+ *     expiry (60s skew) or when forcibly cleared on a 401.
+ */
+
+import fetch from "node-fetch";
+
+/** Re-acquire this many ms before the stated expiry to absorb clock skew. */
+const EXPIRY_SKEW_MS = 60_000;
+
+/**
+ * Per-site token cache, keyed by site._name. A value is either a resolved
+ * { token, expiresAt, refreshToken } entry or an in-flight Promise of one
+ * (so concurrent acquires share a single token request).
+ */
+const cache = new Map();
+
+/**
+ * Error thrown when the token endpoint returns a non-2xx response.
+ * Carries the HTTP status but never the client secret.
+ */
+export class OAuthError extends Error {
+  /**
+   * @param {string} message Human-readable error (never includes the secret).
+   * @param {number} [status] HTTP status from the token endpoint, if any.
+   */
+  constructor(message, status) {
+    super(message);
+    this.name = "OAuthError";
+    this.status = status;
+  }
+}
+
+/**
+ * Build the url-encoded token request body for either grant.
+ * @param {object} oauth Resolved oauth block (clientId, clientSecret, grant, scopes).
+ * @param {boolean} useRefresh Use the refresh_token grant instead of the base grant.
+ * @param {?string} refreshToken Refresh token to send when useRefresh is true.
+ * @returns {string} application/x-www-form-urlencoded body.
+ */
+function buildBody(oauth, useRefresh, refreshToken) {
+  const params = new URLSearchParams();
+  if (useRefresh) {
+    params.set("grant_type", "refresh_token");
+    params.set("refresh_token", refreshToken);
+  } else {
+    params.set("grant_type", oauth.grant || "client_credentials");
+  }
+  params.set("client_id", oauth.clientId);
+  params.set("client_secret", oauth.clientSecret);
+  if (Array.isArray(oauth.scopes) && oauth.scopes.length > 0) {
+    params.set("scope", oauth.scopes.join(" "));
+  }
+  return params.toString();
+}
+
+/**
+ * Perform a single token-endpoint request and normalize the response.
+ * @param {object} site Resolved site config with an oauth block.
+ * @param {boolean} useRefresh Whether to use the refresh_token grant.
+ * @param {?string} refreshToken Refresh token for the refresh grant.
+ * @returns {Promise<{token: string, expiresAt: number, refreshToken: ?string}>}
+ * @throws {OAuthError} on a non-2xx response or a missing access_token.
+ */
+async function requestToken(site, useRefresh, refreshToken) {
+  const { oauth } = site;
+  const url = `${site.baseUrl}${oauth.tokenUrl || "/oauth/token"}`;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body: buildBody(oauth, useRefresh, refreshToken),
+  });
+
+  if (!res.ok) {
+    throw new OAuthError(
+      `OAuth token request to ${site._name} failed with status ${res.status}.`,
+      res.status
+    );
+  }
+
+  const data = await res.json();
+  if (!data.access_token || typeof data.access_token !== "string") {
+    throw new OAuthError(
+      `OAuth token response from ${site._name} is missing access_token.`,
+      res.status
+    );
+  }
+  const expiresIn = Number(data.expires_in) || 0;
+  return {
+    token: data.access_token,
+    expiresAt: Date.now() + expiresIn * 1000,
+    refreshToken: data.refresh_token || null,
+  };
+}
+
+/**
+ * Acquire a token, attempting the refresh grant when a refresh token is cached.
+ * If the refresh grant fails (revoked/expired), fall back once to a fresh
+ * client_credentials grant; only surface the error if that also fails.
+ * @param {object} site Resolved site config with an oauth block.
+ * @param {boolean} useRefresh Attempt the refresh grant first.
+ * @param {?string} refreshToken Refresh token for the refresh grant.
+ * @returns {Promise<{token: string, expiresAt: number, refreshToken: ?string}>}
+ * @throws {OAuthError} if the base grant fails.
+ */
+async function acquireToken(site, useRefresh, refreshToken) {
+  if (!useRefresh) {
+    return requestToken(site, false, null);
+  }
+  try {
+    return await requestToken(site, true, refreshToken);
+  } catch {
+    return requestToken(site, false, null);
+  }
+}
+
+/**
+ * Return a valid access token for the site, acquiring or refreshing as needed.
+ * Concurrent callers share a single in-flight token request via the cache.
+ * @param {object} site Resolved site config with an oauth block.
+ * @returns {Promise<string>} A non-expired access token.
+ * @throws {OAuthError} if a token cannot be acquired.
+ */
+export async function getAccessToken(site) {
+  const key = site._name;
+  const cached = cache.get(key);
+
+  // A cached entry may be a resolved token object or an in-flight Promise from a
+  // concurrent acquire; normalize before reading its fields.
+  if (cached) {
+    const resolved = await Promise.resolve(cached);
+    if (Date.now() < resolved.expiresAt - EXPIRY_SKEW_MS) {
+      return resolved.token;
+    }
+  }
+
+  const useRefresh = Boolean(cached && !(cached instanceof Promise) && cached.refreshToken);
+  const refreshToken = useRefresh ? cached.refreshToken : null;
+
+  // Store the in-flight Promise before awaiting so concurrent callers share one
+  // request. Replace with the resolved entry on success; clear on failure so a
+  // transient error does not poison the cache.
+  const pending = acquireToken(site, useRefresh, refreshToken)
+    .then((entry) => {
+      cache.set(key, entry);
+      return entry;
+    })
+    .catch((err) => {
+      cache.delete(key);
+      throw err;
+    });
+  cache.set(key, pending);
+
+  const entry = await pending;
+  return entry.token;
+}
+
+/**
+ * Drop any cached token for the site, forcing a fresh acquire on the next call.
+ * Used by the 401 retry path.
+ * @param {object} site Resolved site config (keyed by site._name).
+ * @returns {void}
+ */
+export function clearToken(site) {
+  cache.delete(site._name);
+}