toolfunnel 0.4.0 → 0.6.0

package/mcp/servers/mock-upstream/server.js

@@ -13,7 +13,7 @@
  * the isolation guard requires it to stay inside the tree):
  *   upstream: { id: "mock", command: "node", args: ["mcp/servers/mock-upstream/server.js"] }
  *
- * Protocol: JSON-RPC 2.0 over stdio with NEWLINE-DELIMITED framing — one compact JSON object per
+ * Protocol: JSON-RPC 2.0 over stdio with NEWLINE-DELIMITED framing - one compact JSON object per
  *   line, "\n"-terminated, the MCP stdio transport every real SDK-based server speaks. We read lines
  *   on stdin and answer in kind on stdout. (This fixture used to parse LSP Content-Length framing,
  *   matching an old client bug; both were corrected together so the mock represents a REAL server.)
@@ -22,24 +22,31 @@
  *   - ping              -> "pong"
  *   - add  { a, b }     -> a + b
  *   - echo { text }     -> text
+ *   - blocks            -> a MULTI-BLOCK result with structuredContent (envelope-fidelity fixture)
  *
- * Replies to `initialize`, ignores `notifications/initialized`, answers `tools/list` and
- * `tools/call`, never crashes on a bad frame, and exits cleanly on stdin EOF.
+ * Replies to `initialize`, ignores `notifications/initialized`, answers `tools/list`,
+ * `tools/call` and `resources/list` (one fixed resource - forward-fidelity fixture),
+ * never crashes on a bad frame, and exits cleanly on stdin EOF.
  *
  * Node built-ins only. CommonJS.
  */
 
 const PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = { name: 'mock-upstream', version: '1.0.0' };
+// `title` is a fidelity fixture: the 2025-06-18 spec added serverInfo.title, and the wrap must
+// deliver it VERBATIM (a whitelist in wrappedIdentity used to eat it - wrap-lab, 2026-07-17).
+const SERVER_INFO = { name: 'mock-upstream', version: '1.0.0', title: 'Mock Upstream Fixture' };
 
 const TOOLS = [
   {
     name: 'ping',
-    description: 'Health check — returns the string "pong".',
+    description: 'Health check - returns the string "pong".',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
   },
   {
+    // title + annotations are fidelity fixtures: real servers ship them (and newer fields), and a
+    // transparent wrap must advertise the def BYTE-IDENTICAL (a projection used to drop both).
     name: 'add',
+    title: 'Add Numbers',
     description: 'Add two numbers and return the sum.',
     inputSchema: {
       type: 'object',
@@ -47,6 +54,7 @@ const TOOLS = [
       required: ['a', 'b'],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   },
   {
     name: 'echo',
@@ -58,14 +66,39 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'blocks',
+    description: 'Return a multi-block result with structuredContent (envelope-fidelity fixture).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
   {
     name: 'crash',
-    description: 'Exit the process immediately (simulates an upstream crash — for reconnect testing).',
+    description: 'Exit the process immediately (simulates an upstream crash - for reconnect testing).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'prog',
+    description: 'Progress fixture: emits two notifications/progress against the request _meta progressToken, then returns.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'slowtool',
+    description: 'In-flight tools/call fixture: replies after 2s - the cancel-translation window for the TOOL path.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'elicit',
+    description: 'Elicitation fixture (Bridge B): sends a server-initiated elicitation/create mid-call, holds the call open, completes from the answer.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
   },
 ];
 
-/** Write one JSON-RPC message as a newline-delimited line — the MCP stdio framing. */
+// Outstanding SERVER->CLIENT requests this mock has issued (Bridge B fixture): id -> callback fed
+// with the client's response ({ result } or { error }).
+const outstandingServerRequests = new Map();
+let nextServerRequestId = 9001;
+
+/** Write one JSON-RPC message as a newline-delimited line - the MCP stdio framing. */
 function writeMessage(msg) {
   process.stdout.write(JSON.stringify(msg) + '\n');
 }
@@ -82,24 +115,111 @@ function handleMessage(msg) {
   const method = msg.method;
   const params = msg.params || {};
 
-  // Notifications carry no id and must never be answered.
-  if (id === undefined || id === null) return;
+  // Notifications carry no id and must never be answered. Cancel-fidelity fixture: when
+  // TF_MOCK_CANCEL_LOG is set, RECORD each received notifications/cancelled requestId - a
+  // gateway test can then prove which id (translated or raw) actually reached this server.
+  if (id === undefined || id === null) {
+    if (method === 'notifications/cancelled' && process.env.TF_MOCK_CANCEL_LOG) {
+      try {
+        require('node:fs').appendFileSync(process.env.TF_MOCK_CANCEL_LOG, String(params.requestId) + '\n');
+      } catch (_e) { /* fixture logging must never crash the mock */ }
+    }
+    return;
+  }
+
+  // A message with an id and NO method is a client RESPONSE - route it to the outstanding
+  // server-initiated request it answers (Bridge B fixture). Unknown ids are dropped.
+  if (method === undefined) {
+    const cb = outstandingServerRequests.get(id);
+    if (cb) {
+      outstandingServerRequests.delete(id);
+      try { cb(msg); } catch (_e) { /* fixture callback must never crash the mock */ }
+    }
+    return;
+  }
 
   switch (method) {
     case 'initialize':
+      // Identity-mirroring fixture: RECORD the clientInfo each connect presents when
+      // TF_MOCK_CLIENTINFO_LOG is set. A wire test reads the log across a reconnect - first
+      // entry = the gateway's boot identity, last entry = the mirrored downstream client.
+      if (process.env.TF_MOCK_CLIENTINFO_LOG) {
+        try {
+          require('node:fs').appendFileSync(process.env.TF_MOCK_CLIENTINFO_LOG,
+            JSON.stringify((params && params.clientInfo) || null) + '\n');
+        } catch (_e) { /* fixture logging must never crash the mock */ }
+      }
       return writeMessage({
         jsonrpc: '2.0',
         id,
         result: {
           protocolVersion: PROTOCOL_VERSION,
           serverInfo: SERVER_INFO,
-          capabilities: { tools: {} },
+          // resources.subscribe: the per-URI update fixture - a legacy server only emits
+          // resources/updated AFTER a resources/subscribe, which is exactly the channel the
+          // gateway must forward, replay on reconnect, and bridge back.
+          capabilities: { tools: {}, resources: { subscribe: true } },
         },
       });
 
     case 'tools/list':
       return writeMessage({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
 
+    case 'server/discover':
+      // Era-probe fixture: TF_MOCK_DISCOVER_EMPTY=1 makes this server ACK unknown methods with `{}`
+      // - the "permissive legacy server" shape. A strict dual-era client probe must treat that as
+      // LEGACY (no supportedVersions listing the modern version). Default: honest -32601.
+      if (process.env.TF_MOCK_DISCOVER_EMPTY === '1') {
+        return writeMessage({ jsonrpc: '2.0', id, result: {} });
+      }
+      return writeMessage({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found: ' + method } });
+
+    case 'resources/list':
+      // Forward-fidelity fixture: a distinctive verbatim result so a gateway test can PROVE a
+      // forwarded non-tool method really reached this server (and came back untouched).
+      return writeMessage({
+        jsonrpc: '2.0', id,
+        result: { resources: [{ uri: 'mock://upstream/readme', name: 'readme', mimeType: 'text/plain' }] },
+      });
+
+    case 'resources/subscribe': {
+      // Per-URI update fixture. Ack, RECORD the subscribe when TF_MOCK_SUB_LOG is set (a replay
+      // test counts subscribes across a process swap - a fresh process logging a fresh subscribe
+      // PROVES the gateway replayed it), then emit one resources/updated shortly after.
+      const uri = typeof params.uri === 'string' ? params.uri : '';
+      if (process.env.TF_MOCK_SUB_LOG) {
+        try {
+          require('node:fs').appendFileSync(process.env.TF_MOCK_SUB_LOG, uri + '\n');
+        } catch (_e) { /* fixture logging must never crash the mock */ }
+      }
+      writeMessage({ jsonrpc: '2.0', id, result: {} });
+      setTimeout(() => writeMessage({
+        jsonrpc: '2.0', method: 'notifications/resources/updated', params: { uri },
+      }), 150);
+      return;
+    }
+
+    case 'resources/read': {
+      const uri = params.uri;
+      if (uri === 'mock://upstream/slow') {
+        // In-flight fixture: reply after 2s so a gateway test has a WIDE window to fire a
+        // cancel at a genuinely outstanding forwarded request (400ms made W1 a flake candidate
+        // on a loaded runner).
+        setTimeout(() => writeMessage({
+          jsonrpc: '2.0', id,
+          result: { contents: [{ uri, mimeType: 'text/plain', text: 'slow done' }] },
+        }), 2000);
+        return;
+      }
+      if (uri === 'mock://upstream/readme') {
+        return writeMessage({
+          jsonrpc: '2.0', id,
+          result: { contents: [{ uri, mimeType: 'text/plain', text: 'mock upstream readme' }] },
+        });
+      }
+      return writeMessage({ jsonrpc: '2.0', id, error: { code: -32602, message: 'Unknown resource: ' + uri } });
+    }
+
     case 'tools/call': {
       const name = params.name;
       const args = params.arguments || {};
@@ -119,12 +239,72 @@ function handleMessage(msg) {
           const text = typeof args.text === 'string' ? args.text : JSON.stringify(args.text);
           return writeMessage({ jsonrpc: '2.0', id, result: textResult(text) });
         }
+        if (name === 'blocks') {
+          // Envelope-fidelity fixture: two content blocks AND structuredContent. A transparent
+          // forward must deliver this envelope VERBATIM - any re-shaping collapses it.
+          return writeMessage({
+            jsonrpc: '2.0', id,
+            result: {
+              content: [
+                { type: 'text', text: 'first block' },
+                { type: 'text', text: 'second block' },
+              ],
+              structuredContent: { first: 'first block', second: 'second block' },
+              isError: false,
+            },
+          });
+        }
         if (name === 'crash') {
           // Simulate an upstream crash: exit WITHOUT replying. The gateway's in-flight request
-          // rejects and its McpClient.onClose fires → the aggregator schedules a background
+          // rejects and its McpClient.onClose fires -> the aggregator schedules a background
           // reconnect. Exercised by reconnect.test.js.
           process.exit(1);
         }
+        if (name === 'slowtool') {
+          // The tool-path twin of mock://upstream/slow: a genuinely outstanding tools/call for
+          // cancel-translation tests.
+          setTimeout(() => writeMessage({ jsonrpc: '2.0', id, result: textResult('slowtool done') }), 2000);
+          return;
+        }
+        if (name === 'elicit') {
+          // Bridge B fixture: ask the CLIENT a question mid-call, hold the tools/call open, and
+          // complete it from the answer - exactly what a real eliciting legacy server does.
+          const reqId = nextServerRequestId++;
+          outstandingServerRequests.set(reqId, (resp) => {
+            const res = resp && resp.result;
+            if (resp && resp.error) {
+              return writeMessage({ jsonrpc: '2.0', id, result: textResult('elicit error: ' + resp.error.message, true) });
+            }
+            const action = res && res.action;
+            if (action === 'accept') {
+              const colour = res.content && res.content.colour;
+              return writeMessage({ jsonrpc: '2.0', id, result: textResult('colour: ' + colour) });
+            }
+            return writeMessage({ jsonrpc: '2.0', id, result: textResult(String(action || 'no action')) });
+          });
+          // NO `mode` field - deliberately. Real pre-MRTR legacy upstreams send only
+          // {message, requestedSchema}; the BRIDGE must inject mode:"form" for the modern shape,
+          // and a fixture that includes it would mask that translation.
+          writeMessage({
+            jsonrpc: '2.0', id: reqId, method: 'elicitation/create',
+            params: {
+              message: 'Pick a colour',
+              requestedSchema: { type: 'object', properties: { colour: { type: 'string' } }, required: ['colour'] },
+            },
+          });
+          return; // the tools/call reply comes from the callback above
+        }
+        if (name === 'prog') {
+          // Progress fixture: a real server correlates progress via the REQUEST's _meta
+          // progressToken. If the gateway stripped _meta on the forward, token is
+          // undefined and no progress is emitted - the test's zero-count is the failure signal.
+          const token = params._meta && params._meta.progressToken;
+          if (token !== undefined) {
+            writeMessage({ jsonrpc: '2.0', method: 'notifications/progress', params: { progressToken: token, progress: 1, total: 2 } });
+            writeMessage({ jsonrpc: '2.0', method: 'notifications/progress', params: { progressToken: token, progress: 2, total: 2 } });
+          }
+          return writeMessage({ jsonrpc: '2.0', id, result: textResult(token !== undefined ? 'prog done (token seen)' : 'prog done (NO token)') });
+        }
         return writeMessage({ jsonrpc: '2.0', id, result: textResult('unknown tool: ' + name, true) });
       } catch (err) {
         return writeMessage({ jsonrpc: '2.0', id, result: textResult('error: ' + ((err && err.message) || err), true) });
@@ -151,7 +331,7 @@ process.stdin.on('data', (chunk) => {
   while ((nl = buffer.indexOf('\n')) !== -1) {
     const line = buffer.slice(0, nl).replace(/\r$/, '').trim();
     buffer = buffer.slice(nl + 1);
-    if (line.length === 0) continue; // blank separator line — ignore
+    if (line.length === 0) continue; // blank separator line - ignore
     let msg;
     try {
       msg = JSON.parse(line);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfunnel",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A zero-dependency MCP gateway: host your own tools, forward and curate tools from other MCP servers, expose them leanly to cut agent token cost, and gate every call through your own policy hooks before it runs.",
   "keywords": [
     "mcp",

package/src/auth/config.js

@@ -1,174 +1,174 @@
-'use strict';
-
-/**
- * auth/config.js — the toggle + settings for OPTIONAL OAuth 2.1 resource-server validation.
- *
- * DEFAULT OFF (the gateway is loopback-only and unauthenticated until you turn this on). Nothing
- * is read or required unless auth has been explicitly enabled via setConfig(). A MISSING config
- * file means disabled — the safe default — so a fresh checkout authenticates nothing and pulls in
- * no dependency.
- *
- * Design rules (mirrors src/core/logger.js — the proven config pattern):
- *   - Zero RUNTIME dependencies. Node built-ins only (fs, path). The jose library is pulled in ONLY
- *     by the validator (src/auth/resource-server.js), ONLY when auth is enabled, and is installed
- *     on demand (CLI `install-oauth` / the UI button). This module never touches jose.
- *   - Config is read FRESH on every call (no caching), so a toggle/edit takes effect for the very
- *     next request without a reconnect or restart — exactly like the logger + tool-state overlays.
- *   - Nothing here throws. A bad/unreadable/malformed config degrades to the safe default (disabled)
- *     so a misconfiguration can never crash the transport.
- *
- * Config file: <root>/auth/auth.config.json  (NOT created until setConfig() writes it)
- *   {
- *     "enabled": false,
- *     "issuer": "https://auth.example.com",      // the OAuth 2.1 / OIDC authorization server
- *     "audience": "https://gateway.example.com", // THIS gateway's resource URI — RFC 8707 audience
- *                                                //   binding; the confused-deputy defence
- *     "jwksUri": "https://auth.example.com/.well-known/jwks.json", // explicit JWKS; else derived
- *                                                //   from the issuer via OIDC discovery
- *     "algorithms": ["RS256", "ES256"],          // the PINNED signature-algorithm allowlist
- *     "requiredScopes": [],                      // optional — every listed scope must be present
- *     "clockToleranceSec": 30                    // exp/nbf skew tolerance (seconds)
- *   }
- *
- * CommonJS only.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-/** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root — see
- *  src/core/config-home.js). Auth config is user-state, so it lives with the home. */
-const { resolveConfigHome } = require('../core/config-home');
-const ROOT = resolveConfigHome();
-
-/** The toggle/config file. NOT created until setConfig() writes it. */
-const CONFIG_PATH = path.join(ROOT, 'auth', 'auth.config.json');
-
-/** Safe defaults — used whenever the config file is absent or unreadable. */
-const DEFAULTS = Object.freeze({
-  enabled: false,
-  issuer: '',
-  audience: '',
-  jwksUri: '',
-  algorithms: ['RS256', 'ES256'],
-  requiredScopes: [],
-  clockToleranceSec: 30,
-});
-
-/** A string field, defaulting to '' when not a non-empty string. */
-function str(v, dflt) {
-  return typeof v === 'string' && v.length > 0 ? v : dflt;
-}
-
-/** A string[] field — keep only non-empty strings; fall back to `dflt` when not a usable array. */
-function strArray(v, dflt) {
-  if (!Array.isArray(v)) return dflt.slice();
-  const out = v.filter((x) => typeof x === 'string' && x.length > 0);
-  return out.length > 0 ? out : dflt.slice();
-}
-
-/**
- * getConfig — the resolved auth config. Reads the file fresh; a missing/unreadable/malformed file
- * resolves to the safe defaults (disabled). NEVER throws.
- *
- * @returns {{ enabled:boolean, issuer:string, audience:string, jwksUri:string,
- *             algorithms:string[], requiredScopes:string[], clockToleranceSec:number }}
- */
-function getConfig() {
-  try {
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      return cloneDefaults();
-    }
-    const clock = Number(parsed.clockToleranceSec);
-    return {
-      enabled: parsed.enabled === true,
-      issuer: str(parsed.issuer, DEFAULTS.issuer),
-      audience: str(parsed.audience, DEFAULTS.audience),
-      jwksUri: str(parsed.jwksUri, DEFAULTS.jwksUri),
-      algorithms: strArray(parsed.algorithms, DEFAULTS.algorithms),
-      requiredScopes: strArray(parsed.requiredScopes, DEFAULTS.requiredScopes),
-      // Clamp to a sane, non-negative tolerance; a >5min skew signals a clock problem, not validity.
-      clockToleranceSec:
-        Number.isFinite(clock) && clock >= 0 ? Math.min(Math.floor(clock), 300) : DEFAULTS.clockToleranceSec,
-    };
-  } catch (_err) {
-    // Missing file = disabled (the safe default); also covers unreadable/malformed.
-    return cloneDefaults();
-  }
-}
-
-/** A fresh, mutation-safe copy of the defaults (arrays cloned so a caller can't poison the frozen one). */
-function cloneDefaults() {
-  return {
-    enabled: DEFAULTS.enabled,
-    issuer: DEFAULTS.issuer,
-    audience: DEFAULTS.audience,
-    jwksUri: DEFAULTS.jwksUri,
-    algorithms: DEFAULTS.algorithms.slice(),
-    requiredScopes: DEFAULTS.requiredScopes.slice(),
-    clockToleranceSec: DEFAULTS.clockToleranceSec,
-  };
-}
-
-/**
- * configError — a human-readable reason the CURRENT config could not gate requests, or null if it
- * is coherent enough to enforce. Used by the transport + UI to fail CLOSED with a clear message
- * rather than silently mis-validating. Only meaningful when `enabled` is true.
- *
- * Enforcement requires: an issuer, an audience (the RFC 8707 confused-deputy defence — a gateway
- * that does not bind tokens to its own resource URI is exploitable), at least one pinned algorithm,
- * and a key source (explicit jwksUri OR an issuer to derive one from via OIDC discovery).
- *
- * @param {object} [cfg]  defaults to getConfig()
- * @returns {string|null}
- */
-function configError(cfg) {
-  const c = cfg || getConfig();
-  if (!c.enabled) return null; // disabled → nothing to enforce, no error
-  if (!c.issuer) return 'auth enabled but "issuer" is not set';
-  if (!c.audience) return 'auth enabled but "audience" (this gateway\'s resource URI) is not set — required to bind tokens (RFC 8707)';
-  if (!Array.isArray(c.algorithms) || c.algorithms.length === 0) return 'auth enabled but no signature "algorithms" are pinned';
-  // (A key source is always available: issuer is mandatory above, and jwksUri is derived from it
-  // via OIDC discovery when not given — so no separate jwksUri-or-issuer check is needed here.)
-  return null;
-}
-
-/**
- * setConfig — atomically merge a patch into auth/auth.config.json (temp + rename). Merges with the
- * current resolved config so a partial patch (e.g. { enabled: true }) preserves the other fields.
- * Creates the auth/ dir and the file if absent — this is the ONLY function that creates it.
- *
- * @param {object} patch  any subset of the config fields
- * @returns {object} the merged, written config
- */
-function setConfig(patch) {
-  const current = getConfig();
-  const p = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {};
-
-  const next = {
-    enabled: typeof p.enabled === 'boolean' ? p.enabled : current.enabled,
-    issuer: typeof p.issuer === 'string' ? p.issuer : current.issuer,
-    audience: typeof p.audience === 'string' ? p.audience : current.audience,
-    jwksUri: typeof p.jwksUri === 'string' ? p.jwksUri : current.jwksUri,
-    algorithms: Array.isArray(p.algorithms) ? strArray(p.algorithms, current.algorithms) : current.algorithms,
-    requiredScopes: Array.isArray(p.requiredScopes)
-      ? p.requiredScopes.filter((x) => typeof x === 'string' && x.length > 0)
-      : current.requiredScopes,
-    clockToleranceSec:
-      Number.isFinite(Number(p.clockToleranceSec)) && Number(p.clockToleranceSec) >= 0
-        ? Math.min(Math.floor(Number(p.clockToleranceSec)), 300)
-        : current.clockToleranceSec,
-  };
-
-  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-  // Atomic write: unique temp file in the same dir, then rename over the target.
-  const tmp = CONFIG_PATH + '.' + process.pid + '.' + Date.now() + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
-  fs.renameSync(tmp, CONFIG_PATH);
-
-  return next;
-}
-
-module.exports = { getConfig, setConfig, configError, CONFIG_PATH, DEFAULTS };
+'use strict';
+
+/**
+ * auth/config.js - the toggle + settings for OPTIONAL OAuth 2.1 resource-server validation.
+ *
+ * DEFAULT OFF (the gateway is loopback-only and unauthenticated until you turn this on). Nothing
+ * is read or required unless auth has been explicitly enabled via setConfig(). A MISSING config
+ * file means disabled - the safe default - so a fresh checkout authenticates nothing and pulls in
+ * no dependency.
+ *
+ * Design rules (mirrors src/core/logger.js - the proven config pattern):
+ *   - Zero RUNTIME dependencies. Node built-ins only (fs, path). The jose library is pulled in ONLY
+ *     by the validator (src/auth/resource-server.js), ONLY when auth is enabled, and is installed
+ *     on demand (CLI `install-oauth` / the UI button). This module never touches jose.
+ *   - Config is read FRESH on every call (no caching), so a toggle/edit takes effect for the very
+ *     next request without a reconnect or restart - exactly like the logger + tool-state overlays.
+ *   - Nothing here throws. A bad/unreadable/malformed config degrades to the safe default (disabled)
+ *     so a misconfiguration can never crash the transport.
+ *
+ * Config file: <root>/auth/auth.config.json  (NOT created until setConfig() writes it)
+ *   {
+ *     "enabled": false,
+ *     "issuer": "https://auth.example.com",      // the OAuth 2.1 / OIDC authorization server
+ *     "audience": "https://gateway.example.com", // THIS gateway's resource URI - RFC 8707 audience
+ *                                                //   binding; the confused-deputy defence
+ *     "jwksUri": "https://auth.example.com/.well-known/jwks.json", // explicit JWKS; else derived
+ *                                                //   from the issuer via OIDC discovery
+ *     "algorithms": ["RS256", "ES256"],          // the PINNED signature-algorithm allowlist
+ *     "requiredScopes": [],                      // optional - every listed scope must be present
+ *     "clockToleranceSec": 30                    // exp/nbf skew tolerance (seconds)
+ *   }
+ *
+ * CommonJS only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root - see
+ *  src/core/config-home.js). Auth config is user-state, so it lives with the home. */
+const { resolveConfigHome } = require('../core/config-home');
+const ROOT = resolveConfigHome();
+
+/** The toggle/config file. NOT created until setConfig() writes it. */
+const CONFIG_PATH = path.join(ROOT, 'auth', 'auth.config.json');
+
+/** Safe defaults - used whenever the config file is absent or unreadable. */
+const DEFAULTS = Object.freeze({
+  enabled: false,
+  issuer: '',
+  audience: '',
+  jwksUri: '',
+  algorithms: ['RS256', 'ES256'],
+  requiredScopes: [],
+  clockToleranceSec: 30,
+});
+
+/** A string field, defaulting to '' when not a non-empty string. */
+function str(v, dflt) {
+  return typeof v === 'string' && v.length > 0 ? v : dflt;
+}
+
+/** A string[] field - keep only non-empty strings; fall back to `dflt` when not a usable array. */
+function strArray(v, dflt) {
+  if (!Array.isArray(v)) return dflt.slice();
+  const out = v.filter((x) => typeof x === 'string' && x.length > 0);
+  return out.length > 0 ? out : dflt.slice();
+}
+
+/**
+ * getConfig - the resolved auth config. Reads the file fresh; a missing/unreadable/malformed file
+ * resolves to the safe defaults (disabled). NEVER throws.
+ *
+ * @returns {{ enabled:boolean, issuer:string, audience:string, jwksUri:string,
+ *             algorithms:string[], requiredScopes:string[], clockToleranceSec:number }}
+ */
+function getConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return cloneDefaults();
+    }
+    const clock = Number(parsed.clockToleranceSec);
+    return {
+      enabled: parsed.enabled === true,
+      issuer: str(parsed.issuer, DEFAULTS.issuer),
+      audience: str(parsed.audience, DEFAULTS.audience),
+      jwksUri: str(parsed.jwksUri, DEFAULTS.jwksUri),
+      algorithms: strArray(parsed.algorithms, DEFAULTS.algorithms),
+      requiredScopes: strArray(parsed.requiredScopes, DEFAULTS.requiredScopes),
+      // Clamp to a sane, non-negative tolerance; a >5min skew signals a clock problem, not validity.
+      clockToleranceSec:
+        Number.isFinite(clock) && clock >= 0 ? Math.min(Math.floor(clock), 300) : DEFAULTS.clockToleranceSec,
+    };
+  } catch (_err) {
+    // Missing file = disabled (the safe default); also covers unreadable/malformed.
+    return cloneDefaults();
+  }
+}
+
+/** A fresh, mutation-safe copy of the defaults (arrays cloned so a caller can't poison the frozen one). */
+function cloneDefaults() {
+  return {
+    enabled: DEFAULTS.enabled,
+    issuer: DEFAULTS.issuer,
+    audience: DEFAULTS.audience,
+    jwksUri: DEFAULTS.jwksUri,
+    algorithms: DEFAULTS.algorithms.slice(),
+    requiredScopes: DEFAULTS.requiredScopes.slice(),
+    clockToleranceSec: DEFAULTS.clockToleranceSec,
+  };
+}
+
+/**
+ * configError - a human-readable reason the CURRENT config could not gate requests, or null if it
+ * is coherent enough to enforce. Used by the transport + UI to fail CLOSED with a clear message
+ * rather than silently mis-validating. Only meaningful when `enabled` is true.
+ *
+ * Enforcement requires: an issuer, an audience (the RFC 8707 confused-deputy defence - a gateway
+ * that does not bind tokens to its own resource URI is exploitable), at least one pinned algorithm,
+ * and a key source (explicit jwksUri OR an issuer to derive one from via OIDC discovery).
+ *
+ * @param {object} [cfg]  defaults to getConfig()
+ * @returns {string|null}
+ */
+function configError(cfg) {
+  const c = cfg || getConfig();
+  if (!c.enabled) return null; // disabled -> nothing to enforce, no error
+  if (!c.issuer) return 'auth enabled but "issuer" is not set';
+  if (!c.audience) return 'auth enabled but "audience" (this gateway\'s resource URI) is not set - required to bind tokens (RFC 8707)';
+  if (!Array.isArray(c.algorithms) || c.algorithms.length === 0) return 'auth enabled but no signature "algorithms" are pinned';
+  // (A key source is always available: issuer is mandatory above, and jwksUri is derived from it
+  // via OIDC discovery when not given - so no separate jwksUri-or-issuer check is needed here.)
+  return null;
+}
+
+/**
+ * setConfig - atomically merge a patch into auth/auth.config.json (temp + rename). Merges with the
+ * current resolved config so a partial patch (e.g. { enabled: true }) preserves the other fields.
+ * Creates the auth/ dir and the file if absent - this is the ONLY function that creates it.
+ *
+ * @param {object} patch  any subset of the config fields
+ * @returns {object} the merged, written config
+ */
+function setConfig(patch) {
+  const current = getConfig();
+  const p = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {};
+
+  const next = {
+    enabled: typeof p.enabled === 'boolean' ? p.enabled : current.enabled,
+    issuer: typeof p.issuer === 'string' ? p.issuer : current.issuer,
+    audience: typeof p.audience === 'string' ? p.audience : current.audience,
+    jwksUri: typeof p.jwksUri === 'string' ? p.jwksUri : current.jwksUri,
+    algorithms: Array.isArray(p.algorithms) ? strArray(p.algorithms, current.algorithms) : current.algorithms,
+    requiredScopes: Array.isArray(p.requiredScopes)
+      ? p.requiredScopes.filter((x) => typeof x === 'string' && x.length > 0)
+      : current.requiredScopes,
+    clockToleranceSec:
+      Number.isFinite(Number(p.clockToleranceSec)) && Number(p.clockToleranceSec) >= 0
+        ? Math.min(Math.floor(Number(p.clockToleranceSec)), 300)
+        : current.clockToleranceSec,
+  };
+
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  // Atomic write: unique temp file in the same dir, then rename over the target.
+  const tmp = CONFIG_PATH + '.' + process.pid + '.' + Date.now() + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
+  fs.renameSync(tmp, CONFIG_PATH);
+
+  return next;
+}
+
+module.exports = { getConfig, setConfig, configError, CONFIG_PATH, DEFAULTS };