toolfunnel 0.3.0

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

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mcp/servers/mock-upstream/server.js
+ *
+ * A tiny, ZERO-DEPENDENCY stdio MCP server bundled inside ToolFunnel's own `mcp/` tree so it
+ * travels with the install (the "toolbox" stays self-contained and portable). It exists to
+ * demonstrate ToolFunnel attaching and forwarding (proxying) an upstream MCP: attach it as an
+ * upstream, expose its tools, and watch ToolFunnel forward calls to it through the policy gate.
+ *
+ * Attach it with a RELATIVE arg path (the aggregator resolves it against the gateway root and
+ * 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
+ *   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.)
+ *
+ * Tools exposed (real upstream names):
+ *   - ping              -> "pong"
+ *   - add  { a, b }     -> a + b
+ *   - echo { text }     -> text
+ *
+ * Replies to `initialize`, ignores `notifications/initialized`, answers `tools/list` and
+ * `tools/call`, 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' };
+
+const TOOLS = [
+  {
+    name: 'ping',
+    description: 'Health check — returns the string "pong".',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'add',
+    description: 'Add two numbers and return the sum.',
+    inputSchema: {
+      type: 'object',
+      properties: { a: { type: 'number' }, b: { type: 'number' } },
+      required: ['a', 'b'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'echo',
+    description: 'Echo back the supplied text.',
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string' } },
+      required: ['text'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'crash',
+    description: 'Exit the process immediately (simulates an upstream crash — for reconnect testing).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+];
+
+/** Write one JSON-RPC message as a newline-delimited line — the MCP stdio framing. */
+function writeMessage(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+/** Standard MCP tools/call result envelope. */
+function textResult(text, isError) {
+  return { content: [{ type: 'text', text: String(text) }], isError: isError === true };
+}
+
+/** Dispatch one parsed JSON-RPC message. Notifications (no id) get no reply. */
+function handleMessage(msg) {
+  if (!msg || typeof msg !== 'object') return;
+  const id = msg.id;
+  const method = msg.method;
+  const params = msg.params || {};
+
+  // Notifications carry no id and must never be answered.
+  if (id === undefined || id === null) return;
+
+  switch (method) {
+    case 'initialize':
+      return writeMessage({
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          serverInfo: SERVER_INFO,
+          capabilities: { tools: {} },
+        },
+      });
+
+    case 'tools/list':
+      return writeMessage({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
+
+    case 'tools/call': {
+      const name = params.name;
+      const args = params.arguments || {};
+      try {
+        if (name === 'ping') {
+          return writeMessage({ jsonrpc: '2.0', id, result: textResult('pong') });
+        }
+        if (name === 'add') {
+          const a = Number(args.a);
+          const b = Number(args.b);
+          if (!isFinite(a) || !isFinite(b)) {
+            return writeMessage({ jsonrpc: '2.0', id, result: textResult('add requires numeric a and b', true) });
+          }
+          return writeMessage({ jsonrpc: '2.0', id, result: textResult(String(a + b)) });
+        }
+        if (name === 'echo') {
+          const text = typeof args.text === 'string' ? args.text : JSON.stringify(args.text);
+          return writeMessage({ jsonrpc: '2.0', id, result: textResult(text) });
+        }
+        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
+          // reconnect. Exercised by reconnect.test.js.
+          process.exit(1);
+        }
+        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) });
+      }
+    }
+
+    default:
+      // Unknown method -> a well-formed JSON-RPC method-not-found error.
+      return writeMessage({
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32601, message: 'Method not found: ' + method },
+      });
+  }
+}
+
+// ── Newline-delimited JSON reader over stdin (the MCP stdio framing) ─────────────────
+let buffer = '';
+
+process.stdin.on('data', (chunk) => {
+  buffer += chunk.toString('utf8');
+  // Drain every complete line currently buffered (one JSON-RPC message per line).
+  let nl;
+  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
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch (_e) {
+      continue; // skip an unparseable line rather than crash
+    }
+    try {
+      handleMessage(msg);
+    } catch (_e) {
+      /* a handler must never take the server down */
+    }
+  }
+});
+
+process.stdin.on('end', () => process.exit(0));
+process.stdin.resume();

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "toolfunnel",
+  "version": "0.3.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",
+    "model-context-protocol",
+    "mcp-gateway",
+    "mcp-proxy",
+    "mcp-server",
+    "ai",
+    "agents",
+    "llm",
+    "tools",
+    "claude",
+    "anthropic",
+    "aggregator",
+    "token-efficiency"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "src/mcp/server.js",
+  "bin": {
+    "toolfunnel": "bin/toolfunnel.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/toolfunnel.js",
+    "http": "node bin/toolfunnel.js --http",
+    "install-oauth": "node bin/toolfunnel.js install-oauth",
+    "test": "node test/run-all.js",
+    "test:integration": "node test/integration-real-mcp.test.js && node test/integration-http-client.test.js"
+  },
+  "dependencies": {},
+  "author": "rendeverance",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rendeverance/toolfunnel.git"
+  },
+  "homepage": "https://github.com/Rendeverance/toolfunnel#readme",
+  "bugs": {
+    "url": "https://github.com/Rendeverance/toolfunnel/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "tools/tools.register.json",
+    "tools/scripts/",
+    "mcp/expose.example.json",
+    "mcp/servers/",
+    "hooks/hooks.manifest.json",
+    "hooks/scripts/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "jose": "^5.10.0"
+  }
+}

package/src/auth/config.js

@@ -0,0 +1,172 @@
+'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');
+
+/** Repo root: <root>/src/auth/config.js -> two dirs up. */
+const ROOT = path.resolve(__dirname, '..', '..');
+
+/** 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 };

package/src/auth/install.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * auth/install.js — install the OPTIONAL OAuth dependency (`jose`) on demand.
+ *
+ * The whole point of ToolFunnel's zero-dependency stance is that a default install pulls NOTHING.
+ * OAuth is opt-in, so its one library is installed only when a user decides they need it — via the
+ * CLI (`toolfunnel install-oauth`) or the admin-UI button, both of which call installJose() here.
+ *
+ * It shells out to the user's own `npm` to install the PINNED jose version into the gateway
+ * package's own node_modules (resolved from this file's location, NOT process.cwd(), so it lands
+ * beside the engine wherever ToolFunnel is installed). It uses `--no-save` — the goal is simply to
+ * make `require('jose')` resolvable; there is no manifest to update, and this keeps ToolFunnel's
+ * own `dependencies: {}` untouched in every install shape.
+ *
+ * WINDOWS NOTE: do NOT spawn `npm.cmd`. Since the CVE-2024-27980 mitigation, spawning a `.cmd`
+ * without a shell throws `EINVAL`; and spawning it WITH a shell is unreliable on portable Node
+ * installs — the `npm.cmd` shim misresolves its own path under cmd.exe ("Cannot find module
+ * …\node_modules\npm\bin\npm-cli.js"). The robust, cross-platform approach is to run npm's JS entry
+ * (`npm-cli.js`, located beside the running node binary) with `process.execPath` directly —
+ * `shell:false`, no shim, no PATH lookup, no cwd sensitivity. We fall back to a shell-spawned `npm`
+ * only if `npm-cli.js` can't be located; the spec is allowlist-validated so that fallback can't inject.
+ *
+ * NEVER throws — it resolves to a structured { ok, code, stdout, stderr, message } so the CLI/UI can
+ * report the outcome cleanly even when npm is missing or the network is down.
+ *
+ * CommonJS only; Node built-ins (child_process, path, fs) + the pin from resource-server.js.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const { JOSE_PIN, isJoseInstalled, _resetJoseCache } = require('./resource-server');
+
+/** The gateway package root: <root>/src/auth/install.js -> two dirs up. npm runs here so jose lands
+ *  in the engine's own node_modules regardless of the caller's cwd. */
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+
+/** npm is `npm.cmd` on Windows, `npm` elsewhere. We spawn it as a child rather than require()-ing. */
+const IS_WIN = process.platform === 'win32';
+const NPM_BIN = IS_WIN ? 'npm.cmd' : 'npm';
+
+/** A strict allowlist for an npm version spec. Covers what a single-package install actually uses —
+ *  `name@<exact|caret|tilde|x-range|dist-tag>` and scoped names — and NOTHING a shell could act on, so
+ *  the fallback shell path can never inject. Comparator/whitespace ranges (`>=1 <2`, `1 || 2`) and the
+ *  `*` wildcard are deliberately OUT: `> < = | *` and spaces are shell-meaningful. This is fine — the
+ *  gateway only ever installs the caret-pinned `jose@^5.10.0`. Anything outside the set is refused
+ *  before npm is ever invoked. */
+const SPEC_RE = /^[A-Za-z0-9@._/^~+-]+$/;
+
+/**
+ * Locate npm's JS entry (`npm-cli.js`) so it can be run with `node` directly, bypassing the
+ * `npm.cmd`/`npm` shim. Checks the layouts beside the running node binary (Windows/portable, then
+ * POSIX), then the Windows per-user global. Returns the absolute path, or null if not found.
+ * @returns {string|null}
+ */
+function findNpmCli() {
+  const dir = path.dirname(process.execPath);
+  const candidates = [
+    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),                    // Windows / portable
+    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),       // POSIX (/usr/bin -> /usr/lib)
+  ];
+  if (process.env.APPDATA) {
+    candidates.push(path.join(process.env.APPDATA, 'npm', 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  }
+  for (const c of candidates) {
+    try { if (fs.existsSync(c)) return c; } catch (_e) { /* ignore */ }
+  }
+  return null;
+}
+
+/**
+ * installJose — run `npm install jose@<PIN>` in the gateway package root. Resolves a structured
+ * result; never rejects. A 5-minute hard timeout guards against a hung registry.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs]  default 300000 (5 min).
+ * @param {string} [opts.spec]       override the install spec (tests). Default `jose@<JOSE_PIN>`.
+ * @returns {Promise<{ ok:boolean, code:(number|null), stdout:string, stderr:string, message:string }>}
+ */
+function installJose(opts) {
+  const o = opts || {};
+  const spec = typeof o.spec === 'string' && o.spec.length > 0 ? o.spec : `jose@${JOSE_PIN}`;
+  const timeoutMs = Number.isFinite(o.timeoutMs) && o.timeoutMs > 0 ? o.timeoutMs : 300000;
+
+  if (isJoseInstalled()) {
+    return Promise.resolve({ ok: true, code: 0, stdout: '', stderr: '', message: `jose already installed (${spec})` });
+  }
+
+  // Refuse a spec carrying anything outside the strict allowlist BEFORE any shell is involved.
+  if (!SPEC_RE.test(spec)) {
+    return Promise.resolve({ ok: false, code: null, stdout: '', stderr: '', message: `refusing to install: invalid package spec "${spec}"` });
+  }
+
+  return new Promise((resolve) => {
+    let child;
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      // On ANY failure, attach the guaranteed-correct manual fallback. Auto-install can't be made
+      // universal — npm-cli.js sits in different places relative to `node` across install methods
+      // (Homebrew/Volta/Docker/odd nvm). But the user definitely has a working npm (they used it to
+      // install/run the gateway), so a copyable command they run in their OWN shell always works.
+      // The UI + CLI surface result.message, so a failed auto-install becomes an actionable next
+      // step rather than a dead end.
+      if (result && result.ok !== true) {
+        result.manualCommand = 'npm install jose@' + JOSE_PIN;
+        result.cwd = PKG_ROOT;
+        if (typeof result.message === 'string' && result.message.indexOf('manually') === -1) {
+          result.message += ` — or install it manually: run \`${result.manualCommand}\` in ${PKG_ROOT}`;
+        }
+      }
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => {
+      try { if (child) child.kill('SIGKILL'); } catch (_e) { /* ignore */ }
+      done({ ok: false, code: null, stdout, stderr, message: `npm install timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+    if (typeof timer.unref === 'function') timer.unref();
+
+    try {
+      const npmCli = findNpmCli();
+      if (npmCli) {
+        // PREFERRED: run npm's JS entry with the current node binary — no shell, no .cmd shim, no
+        // PATH/cwd sensitivity. This is what actually works on a portable/Windows Node install.
+        child = spawn(process.execPath, [npmCli, 'install', spec, '--no-save'], {
+          cwd: PKG_ROOT,
+          env: process.env,
+          windowsHide: true,
+          shell: false,
+        });
+      } else if (IS_WIN) {
+        // Fallback (npm-cli.js not found): shell out to npm.cmd. The spec is allowlist-validated
+        // above and double-quoted so cmd.exe can't act on the `^` in a caret range or inject.
+        child = spawn(`"${NPM_BIN}" install "${spec}" --no-save`, {
+          cwd: PKG_ROOT,
+          env: process.env,
+          windowsHide: true,
+          shell: true,
+        });
+      } else {
+        child = spawn(NPM_BIN, ['install', spec, '--no-save'], {
+          cwd: PKG_ROOT,
+          env: process.env,
+          windowsHide: true,
+          shell: false,
+        });
+      }
+    } catch (e) {
+      return done({ ok: false, code: null, stdout, stderr, message: `failed to spawn npm: ${(e && e.message) || e}` });
+    }
+
+    if (child.stdout) child.stdout.on('data', (d) => { stdout += d.toString(); });
+    if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (e) => {
+      done({ ok: false, code: null, stdout, stderr, message: `npm not runnable: ${(e && e.message) || e}` });
+    });
+    child.on('close', (code) => {
+      // Clear the lazy cache so a freshly-installed jose is picked up WITHOUT a process restart.
+      try { _resetJoseCache(); } catch (_e) { /* ignore */ }
+      const ok = code === 0 && isJoseInstalled();
+      done({
+        ok,
+        code,
+        stdout,
+        stderr,
+        message: ok
+          ? `installed ${spec}`
+          : `npm install exited ${code}${isJoseInstalled() ? '' : ' (jose still not loadable)'}`,
+      });
+    });
+  });
+}
+
+module.exports = { installJose, findNpmCli, SPEC_RE, PKG_ROOT, NPM_BIN };