toolfunnel 0.3.0 → 0.4.0

package/README.md

@@ -4,6 +4,10 @@
 
 > 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.
 
+**Zero code, zero dependencies: your own MCP server in 60 seconds** — from three ordinary scripts to a named, packaged, policy-gated MCP server (everything on screen is real output; see [demo/](demo/)):
+
+![ToolFunnel in 60 seconds: scripts → register → identity → live MCP server → npm package](demo/toolfunnel-demo.gif)
+
 
 ## The problem
 
@@ -25,7 +29,7 @@ ToolFunnel is one small MCP server that sits between your agent and everything e
 2. **Forwards other MCP servers - leanly.** Attach an upstream MCP and its tools appear in the same lean register as your own (briefs + instructions-on-demand), runnable through `toolfunnel_run_tool` and the gate. Curate which appear, promote a chosen few to top-level "every-turn" tools, or leave them lean by default. Every forwarded call still passes the gate.
 3. **Lean register** - the agent sees short tool *briefs*; the full instructions for a tool are fetched **on demand**, so context stays small. *(This is the token saver.)*
 4. **Server-side policy gate** - every server-side execution path fires your PreToolUse / PostToolUse hooks **inside the gateway**, so your policy works on *any* client, not just hosts that support hooks. The gate travels with the gateway, and **fails closed**.
-5. **Configure by file, UI, or in-band** - plain JSON files, an optional loopback web UI (`node bin/toolfunnel.js --ui`), or eight in-band **management functions** all add / curate / toggle tools, upstreams, and hooks - live, no restart.
+5. **Configure by file, UI, or in-band** - plain JSON files, an optional loopback web UI (`node bin/toolfunnel.js --ui`), or nine in-band **management functions** all add / curate / toggle tools, upstreams, and hooks - live, no restart - and package the whole setup for deployment.
 6. **Audit when you want it** - a toggleable JSONL log (**default off**) records tool runs, every gate allow/deny decision, and every upstream connect / disconnect / reconnect.
 7. **Live & self-healing** - attach/curate/toggle tools, upstreams, and hooks on a *running* gateway with no restart; and if an attached MCP's process dies, the gateway detects it and reconnects in the background with backoff.
 
@@ -84,7 +88,7 @@ They're just here to get you started - turn any of them off or delete them as yo
 
 ### Management functions
 
-The gateway can manage **itself**. Eight first-party tools in the `management` category let an agent (or the web UI) add, curate, and toggle the gateway's own configuration. They are ordinary register tools - reached through `toolfunnel_run_tool`, so every call passes the same gate as any other gateway tool (a single PreToolUse matcher such as `tf_.*` locks the whole management surface down, since each is named `tf_*`).
+The gateway can manage **itself**. Nine first-party tools in the `management` category let an agent (or the web UI) add, curate, toggle, and package the gateway's own configuration. They are ordinary register tools - reached through `toolfunnel_run_tool`, so every call passes the same gate as any other gateway tool (a single PreToolUse matcher such as `tf_.*` locks the whole management surface down, since each is named `tf_*`).
 
 | Function       | What it does                                                                 |
 |----------------|------------------------------------------------------------------------------|
@@ -96,6 +100,7 @@ The gateway can manage **itself**. Eight first-party tools in the `management` c
 | `tf_hook_set`  | Enable, disable, or remove a hook (live toggles via the `hooks.state.json` overlay). |
 | `tf_list`      | List register tools, upstream MCPs, or hooks with their live active state (read-only). Hidden tools are omitted by default - pass `{ includeHidden: true }` to show them. |
 | `tf_log`       | Enable, disable, or check the [audit log](#activity--audit-log) (`{ action: enable\|disable\|status }`). |
+| `tf_pack`      | Package the live setup into a deployment artifact under `dist/` - a portable config home, or a publishable npm package wrapping toolfunnel. See [Packaging](#packaging-ship-your-own-mcp). |
 
 Tool / hook register edits are **live** (re-read per call, no reconnect). Upstream attach/curate changes are picked up live too: the gateway watches its config and reloads - reconnecting upstreams and emitting `notifications/tools/list_changed` - with no restart.
 
@@ -301,7 +306,7 @@ toolfunnel/
    └─ toolfunnel.log.jsonl  #   the JSONL records (default path)
 ```
 
-Rule of thumb: `src/` is the gateway machinery; `tools/`, `mcp/`, and `hooks/` are where your configuration lives. The engine resolves these top-level paths relative to the repo root.
+Rule of thumb: `src/` is the gateway machinery; `tools/`, `mcp/`, and `hooks/` are where your configuration lives. By default these resolve relative to the repo root — or point them anywhere with a **config home** (`--config-dir` / `TOOLFUNNEL_HOME`): an empty home is seeded from the shipped defaults on first use and never overwritten after, so an `npm update` can never eat your tools. See [docs/packaging.md](docs/packaging.md).
 
 ## Configuration
 
@@ -309,16 +314,29 @@ All config is plain JSON under the repo - edit it by hand, through the [config w
 
 | File                              | Purpose                                                                 |
 |-----------------------------------|-------------------------------------------------------------------------|
-| `tools/tools.register.json`   | The first-party tool register (`{ version, description, tools: [...] }`) - 7 demos + 8 management functions |
+| `tools/tools.register.json`   | The first-party tool register (`{ version, description, tools: [...] }`) - 7 demos + 9 management functions. Entries may carry an `inputSchema`, advertised verbatim when the tool is promoted hot |
 | `tools/tools.state.json`      | The visibility-matrix overlay, keyed by surfaced name → `{ enabled?, hidden?, hot? }`. Default-ON for `enabled` (empty `{}` enables everything), default-OFF for `hot`/`hidden` (meta-tools default `hot`-ON). Read fresh per call - no restart needed |
 | `hooks/hooks.manifest.json`   | The policy gate (`{ version, hooks: [] }`). An empty `hooks` array = allow-all |
 | `hooks/hooks.state.json`      | Optional live enable/disable overlay for hooks; an entry here wins over the manifest's seed `enabled` |
 | `mcp/expose.json`             | Upstream MCP servers + the curated set of their tools to expose (`{ version, upstreams: [], expose: [] }`). **Empty by default**, so the gateway connects to nothing |
 | `mcp/expose.example.json`     | An annotated sample showing how to wire an upstream and expose two of its tools |
 | `logs/log.config.json`        | The audit-log toggle (`{ enabled, path }`). **Default OFF**; created only when logging is enabled |
+| `toolfunnel.json`             | Optional identity + defaults: `{ serverName, serverVersion, httpPort, uiPort, requires }`. Absent = the gateway is plain `toolfunnel`. This is how a packaged MCP introduces itself as ITSELF |
+
+## Packaging: ship your own MCP
+
+Everything you build here — tools, curation, upstream selections, policy hooks, identity — lives
+in one folder (the config home), and one management call packages it:
+
+- `tf_pack { format: "home" }` → a portable setup: zip it, git it, or run it with `--config-dir`.
+- `tf_pack { format: "npm", name: "my-mcp" }` → a **publishable npm package** that depends on
+  toolfunnel (never forks it), bundles your setup, and gives your users `npx my-mcp` — your
+  server, your name in the handshake, your tools and schemas, **your gate enforced on their
+  machine regardless of client**.
+
+Declare runtime needs (`python`, `git`, …) in `toolfunnel.json` `requires` and the gateway warns
+at startup about anything missing. Full story: [docs/packaging.md](docs/packaging.md).
 
 ## License
 
 [MIT](LICENSE)
-</content>
-</invoke>

package/bin/toolfunnel.js

@@ -39,13 +39,40 @@ if (args.includes('--help') || args.includes('-h')) {
       '  toolfunnel --ui               Start the config web UI (127.0.0.1:9777)',
       '  toolfunnel --ui --port <n>    Bind a specific UI port (0 = OS-assigned)',
       '  toolfunnel install-oauth      Install the optional OAuth 2.1 dependency (jose)',
+      '  toolfunnel --config-dir <dir> Use <dir> as the CONFIG HOME (see below)',
       '  toolfunnel --help             Show this help',
       '',
+      'CONFIG HOME: the mutable config (tools/ mcp/ hooks/ auth/ logs/ toolfunnel.json) lives in',
+      'the config home — by default the package root (a git clone works as before), or the value',
+      'of --config-dir / the TOOLFUNNEL_HOME env var. An empty home is seeded from the shipped',
+      'defaults on first use and is NEVER overwritten after — so an npm update cannot eat your',
+      'tools. This is also how a wrapped MCP ships its own bundled setup.',
+      '',
+      'Identity + port defaults can be set in an OPTIONAL toolfunnel.json in the config home:',
+      '  { "serverName": "my-mcp", "serverVersion": "1.0.0", "httpPort": 9998, "uiPort": 9777 }',
+      'A --port flag always wins over the config value.',
+      '',
     ].join('\n')
   );
   process.exit(0);
 }
 
+// Resolve + seed the config home FIRST — before any src/ module is required — so every
+// module-load-time anchor (register/expose/hooks paths, auth + log config, identity) reads the
+// same resolved home. Precedence: --config-dir > TOOLFUNNEL_HOME env > the package root.
+const { initConfigHome } = require('../src/core/config-home');
+const configHome = initConfigHome({ dir: flagValue('--config-dir', '') }).home;
+
+// Advisory runtime preflight: the home's toolfunnel.json may declare `requires` (python, git, …)
+// for the tools it ships. A missing/old runtime breaks only the tools that need it, so each
+// problem is one loud stderr line and the gateway starts anyway. Never fatal, never throws.
+try {
+  const { checkRequires } = require('../src/core/requires');
+  for (const p of checkRequires(configHome)) {
+    process.stderr.write('[toolfunnel] REQUIRES: ' + p.problem + '\n');
+  }
+} catch (_e) { /* preflight must never stop the gateway */ }
+
 if (args[0] === 'install-oauth') {
   // Opt-in OAuth: pull the single audited dependency (jose) on demand. Keeps the default install
   // at zero runtime dependencies — you only ever fetch jose if you decide you need OAuth.
@@ -68,9 +95,13 @@ if (args[0] === 'install-oauth') {
     });
 } else if (args.includes('--ui')) {
   const { createUiServer } = require('../src/ui/server');
+  const { loadServerConfig } = require('../src/core/server-config');
+  const { resolveConfigHome } = require('../src/core/config-home');
+  const cfg = loadServerConfig(resolveConfigHome());
   const host = flagValue('--host', '127.0.0.1');
-  const parsedPort = parseInt(flagValue('--port', '9777'), 10);
-  const port = Number.isInteger(parsedPort) ? parsedPort : 9777;
+  // Precedence: --port flag > toolfunnel.json uiPort > 9777 (loadServerConfig folds in the default).
+  const parsedPort = parseInt(flagValue('--port', String(cfg.uiPort)), 10);
+  const port = Number.isInteger(parsedPort) ? parsedPort : cfg.uiPort;
   const server = createUiServer({ host, port });
   server
     .start()
@@ -88,9 +119,13 @@ if (args[0] === 'install-oauth') {
   process.on('SIGTERM', shutdown);
 } else if (args.includes('--http')) {
   const { createHttpMcpServer } = require('../src/mcp/http-transport');
+  const { loadServerConfig } = require('../src/core/server-config');
+  const { resolveConfigHome } = require('../src/core/config-home');
+  const cfg = loadServerConfig(resolveConfigHome());
   const host = flagValue('--host', '127.0.0.1');
-  const parsedPort = parseInt(flagValue('--port', '9998'), 10);
-  const port = Number.isInteger(parsedPort) ? parsedPort : 9998;
+  // Precedence: --port flag > toolfunnel.json httpPort > 9998 (loadServerConfig folds in the default).
+  const parsedPort = parseInt(flagValue('--port', String(cfg.httpPort)), 10);
+  const port = Number.isInteger(parsedPort) ? parsedPort : cfg.httpPort;
   const server = createHttpMcpServer({ host, port });
   server
     .start()

package/docs/KNOWN_BUGS.md

@@ -0,0 +1,225 @@
+# ToolFunnel — 0.4.0 Board (bugs + features)
+
+> Items 1–5: findings from a full source review on **2026-07-03** (v0.3.0, commit `1c5841c`),
+> each ranked, located, explained, and paired with a proposed fix.
+> **All five FIXED 2026-07-06** in commit `6c9821c` (suite 23/23) — the detail sections below are
+> kept as the record of what was wrong and why the fix took the shape it did.
+> Items 6–9: the 0.4.0 feature board (identity, verification passes, packaging).
+>
+> **Context for future-me:** the core gate architecture reviewed as *sound* — see
+> "What is already solid" at the bottom before re-auditing. Do not re-review the
+> whole tree; start from this list.
+
+---
+
+## The board
+
+| # | Kind | Area | One-liner | Status |
+|---|------|------|-----------|--------|
+| 1 | **High** bug | UI server | Config UI could bind off-loopback with NO auth and NO refusal — unauthenticated LAN RCE surface | **FIXED** `6c9821c` |
+| 2 | Low bug | mcp-client (win) | `winLaunch` cmd.exe metacharacter interpretation — "no injection surface" comment was overstated | **FIXED** `6c9821c` (honest caveat) |
+| 3 | Low bug | aggregator | `_scheduleReconnect` logged `reconnect_slow` every 30s forever instead of once at the transition | **FIXED** `6c9821c` |
+| 4 | Low bug | http-transport | Streaming (chunked) over-cap body didn't get the clean `-32700` — and the "engineered" declared-CL path had the same RST flaw | **FIXED** `6c9821c` (half-close) |
+| 5 | Defensive | auth/resource-server | OIDC discovery followed redirects with no origin-check on the discovered `jwks_uri` | **FIXED** `6c9821c` (origin pin) |
+| 6 | Feature | mcp/server | Configurable server identity — `serverName`/`serverVersion` **and the default `--http`/`--ui` ports** — so a wrapped MCP introduces itself under ITS name and ships its own port defaults. Defaults unchanged. | **DONE** `a734f4b` (toolfunnel.json) |
+| 7 | Verify | protocol/register | Confirm the SCHEMA a hot-promoted register tool advertises is the author's real inputSchema (README promises "your own tools and schemas") | **DONE** `4c219e4` — plumbing was sound; tf_tool_add DROPPED the field (fixed), validated + documented now |
+| 8 | Verify | reload | Confirm `tools.register.json` edits are picked up live — the file-watchers are proven for `mcp/expose.json` + hooks; direct register edits may need a reload path | **DONE** `4c219e4` — was a REAL BUG (startup snapshot); Registry.reload() + tools/ watcher + state list_changed |
+| 9 | Feature | packaging | External config home (`TOOLFUNNEL_HOME` / `--config-dir`) + the full packaging story — see below | **DONE** `108db4e` (home) + `bc88c53` (tf_pack + requires) + `a1fa845` (docs) |
+
+---
+
+## 9. The packaging story (the 0.4.0 headline)
+
+**The problem:** an npm/npx install keeps its config *inside the package directory* — an
+`npm update` EATS the user's tools, hooks, and curation. Config must live in a home of its own.
+
+**Four pieces, in dependency order:**
+
+1. **Config home** — `TOOLFUNNEL_HOME` env var / `--config-dir` flag; default stays the repo root
+   for a git clone (unchanged), but an npm-installed gateway defaults to a per-user home. The
+   enabler for everything below.
+2. **Tool-pack** — a pack IS a zipped config home. Docs, not code: the layout already travels
+   (`tools/` + `tools.register.json` + `mcp/expose.json` + `hooks/`).
+3. **npm-wrap** — docs + a worked example, no core code: a third party publishes THEIR package
+   with **`toolfunnel` as a dependency (caret range — DEPEND, NEVER COPY)**, their pack bundled,
+   and a 2-line `bin` that points toolfunnel at the bundled config home → `npx their-mcp`.
+   - Their own runtime deps go in THEIR `package.json` — npm installs the whole tree on npx;
+     script tools resolve `require()` relative to themselves. We add no machinery.
+   - Why depend-not-copy: every install of their MCP is a toolfunnel download; our security
+     fixes reach every wrapped MCP via normal `npm update`; no stale forks. (This batch's UI-bind
+     fix is the worked example of why.)
+4. **requires-preflight** — a `requires` field in the pack manifest (JSON only) checked with
+   `child_process` version probes + a hand-rolled version compare; friendly missing-runtime
+   errors ("this pack needs python ≥3.10").
+
+**★ HARD CONSTRAINT: ToolFunnel itself gains ZERO runtime dependencies from any of this.**
+JSON manifest (no yaml), hand-rolled version compare (no semver), node built-ins only.
+
+**Packs are COMPOSITE** (already true today — `mcp/expose.json` lives in the config home):
+own scripts + upstream MCP references + curation in one pack.
+- Upstreams travel as REFERENCES (npx self-fetches them; pin versions in the pack).
+- Curation travels — ship the 4 chosen tools, not the whole upstream server.
+- **THE GATE TRAVELS** — a shipped pack enforces its policy hooks on the recipient's machine
+  regardless of which MCP client they use. Nobody else can say this sentence.
+- Audit honesty: packs spawn commands. The docs say it plainly — read the `expose.json` of
+  anything you install.
+
+---
+
+## 1. [HIGH] UI server binds off-loopback with no auth and no refusal
+
+**Files:** `src/ui/server.js` (`createUiServer().start()`, `isLoopbackHost`), `bin/toolfunnel.js` (`--ui --host`)
+
+**The asymmetry.** `src/mcp/http-transport.js` `start()` refuses to bind a non-loopback host
+unless OAuth is enabled:
+
+> `refusing to bind non-loopback host "<host>" without OAuth enabled — enable auth (and install jose) before exposing the gateway off localhost.`
+
+The **UI server has no equivalent guard.** `createUiServer().start()` binds whatever `host`
+it is handed, and `bin/toolfunnel.js` passes `--ui --host <anything>` straight through to it.
+
+**Why the existing check does not cover it.** `isLoopbackHost()` inside the UI's `onRequest`
+tests only the **`Host` request header**, which is fully attacker-controlled. It defends against
+*browser* DNS-rebinding (the browser sets the Host to the attacker's domain), but does **nothing**
+against a direct, non-browser client that simply sends `Host: localhost` / `Host: 127.0.0.1`.
+
+**Why it matters more than the transport.** The config UI is the one surface that can *spawn
+processes and mutate the security posture*:
+- `POST /api/mcp/add` + `POST /api/mcp/discover` construct an `Aggregator` and **connect the
+  configured upstream — i.e. spawn the configured command** (`aggregator.discover` → `_connectOne`
+  → `clientFactory` → `McpClient.connect`).
+- `POST /api/tools/add` / `/api/tools/update` **write tool scripts** to `tools/scripts/`.
+- `POST /api/tools/hook` / `/api/hooks/*` **toggle the gate hooks.**
+
+So `toolfunnel --ui --host 0.0.0.0` (a plausible "let me reach the config UI from my other
+machine" move) exposes an **unauthenticated, process-spawning, script-writing console to the
+LAN**. The HTTP transport learned this exact lesson; the UI never got the same stitch.
+
+**Fix.** The UI has no auth path at all, so the correct behaviour is a hard refusal, mirroring the
+transport's guard. In `createUiServer().start()`, before `httpServer.listen(...)`:
+
+```js
+if (!isLoopbackHost(host)) {
+  return Promise.reject(new Error(
+    `refusing to bind the config UI to non-loopback host "${host}" — the UI is ` +
+    `unauthenticated and can spawn processes / write scripts. It is loopback-only by design.`
+  ));
+}
+```
+
+(Note: `isLoopbackHost` currently returns `true` for an *empty/missing* value — fine for a Host
+*header*, but for a *bind address* an empty host should not be treated as loopback. Use a stricter
+check on the bind arg, or default-and-validate the bind host explicitly.)
+
+**Test to add:** `createUiServer({ host: '0.0.0.0' }).start()` rejects; `'127.0.0.1'`, `'localhost'`,
+`'::1'` resolve.
+
+---
+
+## 2. [LOW] `winLaunch` cmd.exe metacharacter interpretation — comment overstates safety
+
+**File:** `src/mcp/mcp-client.js` (`winLaunch`)
+
+On Windows, a non-`.exe` upstream command is routed through `cmd.exe /c <command> <args…>` with
+`shell:false` (the CVE-2024-27980 `.cmd` workaround). The code comment claims:
+
+> "The args stay DISCRETE (Node escapes each one under shell:false) so nothing is shell-concatenated
+> — no injection surface on this privileged path."
+
+**That guarantee is not quite real.** With `shell:false` and the command being `cmd.exe` (an
+`.exe`), Node applies its *standard argv quoting*, **not** cmd.exe metacharacter (`^`) escaping —
+that special-casing only fires when the *command itself* is the `.cmd`/`.bat`. So a config arg
+containing `& | > < "` can be reinterpreted by cmd.exe.
+
+**Real-world risk: near-zero.** These args come from `expose.json`, authored by the operator — the
+"attacker" would be the person who owns the config. But the comment claims a property the code does
+not provide.
+
+**Fix (pick one):**
+- Downgrade the comment to state the residual cmd.exe-parsing caveat honestly, **or**
+- Defensively quote each arg for cmd.exe, **or**
+- Prefer resolving the real interpreter path (`where npx` → the `node` + `npm-cli.js` shape, as
+  `auth/install.js` already does for npm) and spawn that directly with `shell:false`, avoiding
+  `cmd.exe` entirely.
+
+---
+
+## 3. [LOW] `_scheduleReconnect` spams `reconnect_slow` every 30s forever
+
+**File:** `src/mcp/aggregator.js` (`_scheduleReconnect`)
+
+Past `MAX_FAST_ATTEMPTS` (6) the method re-schedules with `Math.min(attempt + 1, MAX_FAST_ATTEMPTS)`
+→ the attempt counter **sticks at 6**. The entry logs `if (attempt === MAX_FAST_ATTEMPTS)`, so a
+permanently-dead-but-enabled upstream emits a `reconnect_slow` log line **every 30 seconds
+indefinitely**, rather than once at the fast→slow transition.
+
+**Fix.** Log the transition only. E.g. only log when entering the slow phase from the fast phase
+(track the previous attempt, or log inside the `attempt + 1` escalation exactly when it crosses
+`MAX_FAST_ATTEMPTS`, not on every subsequent capped re-entry).
+
+---
+
+## 4. [LOW] Streaming over-cap body misses the clean `-32700` the declared-CL path produces
+
+**File:** `src/mcp/http-transport.js` (`readBody`, `handleMcpPost`)
+
+The **declared-Content-Length** over-cap path is carefully engineered (`sendJsonAndClose`: announce
+`Connection: close`, flush the `-32700` body, *then* destroy the request in the `res.end` callback)
+so the client receives a clean parse-error before the close.
+
+The **streaming/chunked** over-cap path is not held to the same standard: `readBody` rejects and
+immediately `req.destroy()`s. Because `req` and `res` share the socket, the follow-up
+`sendJson(res, 200, makeError(...))` in `handleMcpPost`'s catch writes to a torn-down socket → the
+client sees `ECONNRESET` instead of the tidy `-32700`.
+
+**Not a crash** — every path here is defensive and the server survives. It is an inconsistency: two
+over-cap paths that should behave identically don't.
+
+**Fix.** Route the streaming over-cap case through the same flush-then-close sequence as
+`sendJsonAndClose` (don't `req.destroy()` before the response body has flushed).
+
+---
+
+## 5. [DEFENSIVE] OIDC discovery follows redirects with no origin-check on discovered `jwks_uri`
+
+**File:** `src/auth/resource-server.js` (`resolveJwksUri`, `fetchJson`)
+
+`fetchJson` uses `redirect: 'follow'`, and `resolveJwksUri` accepts whatever `jwks_uri` the issuer's
+discovery document advertises with no check that it shares the issuer's origin. The issuer is
+operator-configured (trusted), and audience binding is still enforced on the verified token, so this
+is standard OIDC behaviour and low-risk — but a defensive origin-pin on the discovered `jwks_uri`
+(and/or `redirect: 'error'` on discovery) would tighten the SSRF-adjacent surface.
+
+**Fix (optional hardening):** assert the discovered `jwks_uri` origin matches the issuer origin, or
+make it opt-out-able. Document the decision either way.
+
+---
+
+## What is already solid (do NOT re-audit from scratch)
+
+The review found the **gate architecture sound**. Confirmed on 2026-07-03:
+
+- **`gatedRun` fails CLOSED on every bad-wiring path** — no engine / junk engine return / engine
+  throw all → `blocked:true`, `execute()` never called. The load-bearing invariant ("a PreToolUse
+  deny prevents `execute()` from ever running") is real and centralised in one auditable place
+  (`src/mcp/gated-run.js`).
+- **The engine proxy reads `build.engine` live** (`src/mcp/server.js`), so a hot-reloaded hook gates
+  BOTH the `toolfunnel_run_tool`/lean path AND the curated-direct path — no stale-engine gap.
+- **OAuth validator does the things that matter** (`src/auth/resource-server.js`): pins the algorithm
+  allowlist (blocks alg-confusion + `alg:none`), enforces `audience` (RFC 8707 confused-deputy
+  defence) and `issuer`, requires `exp` present, never reads the token header to choose the alg.
+- **Isolation guard on path-shaped upstream args** (`aggregator.defaultClientFactory` / `isInside` /
+  `looksLikePath`) — a vendored upstream can't point outside the gateway root; the interpreter slot
+  is correctly exempt.
+- **Path-escape defences** in `registry.writeScript` and `defaultRunScript` (basename + in-root
+  assertion), and **atomic temp+rename writes** across registry / tool-state / expose-store / auth
+  config / logger.
+- **The hook matcher is correctly full-anchored** (`^(?:…)$` in `src/core/matcher.js`), so a gate on
+  `read` does NOT leak onto `read_file`; combined with the UI's `escapeRegex` on gate writes, that
+  path is right.
+- **`McpClient` framing was fixed** in v0.3.0 to newline-delimited JSON (was LSP `Content-Length`),
+  with dual-drain read tolerance — proven against `server-everything` / `server-filesystem` + the
+  official SDK client. Zombie-guard tree-kill on close.
+
+The v0.3.0 adversarial pass (backlog task #49) did real work on the OAuth/transport surface. Finding
+#1 above is the one gap that pass did not close (it hardened the *transport*, not the *UI*).

package/docs/packaging.md

@@ -0,0 +1,115 @@
+# Packaging: ship what you built
+
+ToolFunnel's config is a folder. That single fact is the whole packaging story: everything you
+build in a gateway — your tools and their scripts, which of them are promoted hot or hidden, the
+upstream MCPs you attached and the tools you chose to expose from them, the policy hooks that gate
+every call, and the identity the server introduces itself with — lives in one directory tree, the
+**config home**. Ship the tree and you have shipped the product.
+
+## The config home
+
+By default the home is the package/clone root — a git clone works exactly as it always did. Point
+the gateway elsewhere and the config lives there instead:
+
+```
+toolfunnel --config-dir D:\my-setup     # flag (wins)
+TOOLFUNNEL_HOME=D:\my-setup toolfunnel  # env var
+```
+
+An empty home is **seeded** on first use from the shipped defaults (the register + management
+scripts, an empty `mcp/expose.json`, the default hooks manifest) and is **never overwritten**
+afterwards — which is the point: with the home outside the package, `npm update toolfunnel`
+can never eat your tools.
+
+```
+<home>/
+  toolfunnel.json         # identity (serverName/serverVersion), port defaults, `requires`
+  tools/
+    tools.register.json   # your tool entries (incl. their inputSchema)
+    tools.state.json      # the hot/hidden/enabled curation — part of the product
+    scripts/              # the tool scripts
+  mcp/expose.json         # upstream references + curated exposure
+  hooks/                  # the policy gate: manifest + hook scripts
+```
+
+## `tf_pack` — one call to a deployment artifact
+
+The `tf_pack` management tool snapshots the LIVE setup into `<home>/dist/<name>/` — always a
+separate location, never the live tree. `auth/` (environment-specific) and `logs/` never ship.
+
+**`{ format: "home" }`** → a portable config home. Zip it, commit it to a repo, or run it as-is:
+
+```
+toolfunnel --config-dir path/to/the-pack
+```
+
+**`{ format: "npm", name: "my-mcp", version: "1.0.0" }`** → a publishable npm package:
+
+```
+dist/my-mcp/
+  package.json      # name, bin, files, dependencies: { "toolfunnel": "^0.4.0" }
+  bin/my-mcp.js     # 2 lines: pin --config-dir at ../home, delegate to toolfunnel
+  home/             # the bundled config home (identity rewritten to my-mcp@1.0.0)
+  README.md         # a stub to make your own
+```
+
+Review it, then `cd dist/my-mcp && npm publish`. Your users run `npx my-mcp` and get **your**
+server: your name in the MCP `initialize` handshake, your tools with your schemas, your curation,
+and — the part nobody else can say — **your gate**. The hooks travel inside the pack and enforce
+your policy on the recipient's machine regardless of which MCP client calls it.
+
+### Depend, never copy
+
+The generated package **depends on** `toolfunnel` (caret range) rather than vendoring it. Your own
+runtime dependencies go in **your** `package.json` exactly as with any npm package — npm installs
+the whole tree on `npx my-mcp`; toolfunnel itself adds zero. Why depending matters:
+
+- security and bug fixes reach every wrapped MCP through a normal `npm update` — no stale forks
+  carrying old bugs;
+- your package stays a few KB of config instead of a copied engine;
+- (and honestly) every install of your MCP counts as a toolfunnel download, which keeps the thing
+  you depend on alive.
+
+Your users can move the bundled home out of `node_modules` (so *their* edits survive *your*
+updates) via the `<NAME>_HOME` env var the generated launcher supports.
+
+## Declaring runtimes: `requires`
+
+Your tools may need runtimes the gateway doesn't (python, git, ffmpeg…). Declare them in the
+home's `toolfunnel.json` and they travel with every pack:
+
+```json
+{
+  "serverName": "my-mcp",
+  "requires": [
+    { "command": "python", "min": "3.10", "why": "the pdf-extract tools" },
+    { "command": "git" }
+  ]
+}
+```
+
+The gateway probes them once at startup and prints one clear stderr line per problem — found
+version vs needed, plus your `why`. Advisory by design: a missing runtime breaks only the tools
+that need it, so the server still starts and everything else keeps working.
+
+## Composite packs
+
+A pack is not just your own scripts. Because `mcp/expose.json` lives in the home, a pack carries
+**upstream references too**: "attach `@example/weather-mcp` (pin the version) and expose exactly
+these four tools under these names." The upstream itself travels as a *reference* — `npx` fetches
+it on the recipient's machine — while your **curation** and your **gate** travel as config. One
+pack = your tools + other people's servers, curated, renamed, and policed, as a single artifact.
+
+## Audit honesty
+
+Packs spawn commands — that is what they are for. Before you run anyone's pack (including one of
+ours), read **three files** — every command it can run is declared in plain JSON:
+
+- `tools/tools.register.json` — the tool invokes (scripts and shell commands);
+- `mcp/expose.json` — the upstream server commands it will spawn;
+- `toolfunnel.json` — the `requires` probes. Note these run **at gateway startup** (each declared
+  program is executed once with its version flag), which is why a `requires` command must be a
+  bare program name — the gateway rejects paths, spaces, and shell characters outright.
+
+Ship your own packs expecting the same scrutiny, and say so in your README (the `tf_pack` stub
+already does).

package/docs/releasing.md

@@ -0,0 +1,31 @@
+# Releasing
+
+The entire release surface is one command:
+
+```bash
+npm run release                          # patch bump: test → commit → tag → push → GitHub Release → npm publish
+npm run release -- minor                 # minor bump (or: major)
+npm run release -- --notes "headline"    # headline paragraph for the release notes
+npm run release -- --no-npm              # GitHub-only release (skip npm publish)
+npm run release -- --dry-run             # print the full plan, execute nothing
+```
+
+What it does, in order:
+
+1. **Preflight** — refuses to run on a dirty tree, off `main`, or behind `origin/main`.
+2. **Tests** — the full suite must pass or the release aborts before anything mutates.
+3. **Bump** — rewrites `package.json` (the server's `serverInfo.version` follows it automatically).
+4. **Commit + tag** — one commit (`vX.Y.Z: <headline>`), one annotated tag, both pushed.
+5. **GitHub Release** — created via the API. Auth comes per-use from `git credential fill`;
+   the token is never written to disk or printed. Release body = your `--notes` headline
+   plus the commit subjects since the previous tag.
+6. **npm publish** — interactive (you may be prompted for an OTP). If it fails, the GitHub
+   side is already complete; re-run `npm publish` by hand when ready.
+
+Policy: releases only ever **add**. Existing tags, GitHub Releases and published npm
+versions are never deleted, overwritten, or re-pointed. If a release is bad, ship a fixed
+version on top.
+
+Directory listings (Glama, awesome-mcp-servers and similar) crawl the GitHub side on
+their own schedules — publishing a GitHub Release is the strongest signal they consume.
+Nothing extra to do per release.

package/docs/setup.md

@@ -92,7 +92,7 @@ for you (section 5). A quick smoke test:
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | node bin/toolfunnel.js
 ```
 
-You should get one JSON line back with `"serverInfo":{"name":"toolfunnel","version":"0.3.0"}`
+You should get one JSON line back with `"serverInfo":{"name":"toolfunnel","version":"<current version>"}`
 and `"protocolVersion":"2024-11-05"`.
 
 > **Working directory doesn't matter.** ToolFunnel resolves its config (`tools/`, `mcp/`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfunnel",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -28,9 +28,11 @@
   },
   "scripts": {
     "start": "node bin/toolfunnel.js",
+    "build": "echo toolfunnel has no build step - zero-dependency, runs from source",
     "http": "node bin/toolfunnel.js --http",
     "install-oauth": "node bin/toolfunnel.js install-oauth",
     "test": "node test/run-all.js",
+    "release": "node scripts/release.js",
     "test:integration": "node test/integration-real-mcp.test.js && node test/integration-http-client.test.js"
   },
   "dependencies": {},

package/src/auth/config.js

@@ -36,8 +36,10 @@
 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 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');

package/src/auth/resource-server.js

@@ -112,7 +112,27 @@ async function resolveJwksUri(cfg, timeoutMs) {
   for (const url of candidates) {
     try {
       const doc = await fetchJson(url, timeoutMs);
-      if (doc && typeof doc.jwks_uri === 'string' && doc.jwks_uri.length > 0) return doc.jwks_uri;
+      if (doc && typeof doc.jwks_uri === 'string' && doc.jwks_uri.length > 0) {
+        // ORIGIN-PIN the discovered value. The ISSUER is operator-trusted config, but the discovery
+        // DOCUMENT arrives over the network — it must not be able to point key fetching at a
+        // foreign origin (key-substitution + SSRF-adjacent surface). Cross-origin JWKS hosting is
+        // real (e.g. Google's issuer and JWKS live on different hosts), so the escape hatch is an
+        // EXPLICIT trust statement: set "jwksUri" in the auth config and discovery is skipped.
+        let sameOrigin = false;
+        try {
+          sameOrigin = new URL(doc.jwks_uri).origin === new URL(cfg.issuer).origin;
+        } catch (_e) {
+          /* malformed URL on either side → treat as cross-origin → refuse */
+        }
+        if (!sameOrigin) {
+          throw new Error(
+            `discovered jwks_uri "${doc.jwks_uri}" is not on the issuer origin — refusing the ` +
+              'cross-origin discovery result. If your IdP intentionally hosts JWKS on a separate ' +
+              'origin, state that trust explicitly by setting "jwksUri" in auth/auth.config.json.'
+          );
+        }
+        return doc.jwks_uri;
+      }
       lastErr = new Error(`discovery doc at ${url} has no jwks_uri`);
     } catch (e) {
       lastErr = e;
@@ -121,13 +141,18 @@ async function resolveJwksUri(cfg, timeoutMs) {
   throw lastErr || new Error('OIDC discovery failed');
 }
 
-/** GET + parse JSON with a hard timeout. Throws on non-2xx, network error, or bad JSON. */
+/**
+ * GET + parse JSON with a hard timeout. Throws on non-2xx, network error, bad JSON — or a REDIRECT:
+ * discovery metadata must come from the exact well-known URL derived from the trusted issuer
+ * (following a redirect would let a bounced endpoint serve the document from anywhere, hollowing
+ * out the origin pin above). Only discovery uses this helper; the JWKS fetch itself is jose's.
+ */
 async function fetchJson(url, timeoutMs) {
   const ac = new AbortController();
   const ms = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 10000;
   const t = setTimeout(() => ac.abort(), ms);
   try {
-    const res = await fetch(url, { signal: ac.signal, redirect: 'follow' });
+    const res = await fetch(url, { signal: ac.signal, redirect: 'error' });
     if (!res || !res.ok) throw new Error(`GET ${url} -> HTTP ${res ? res.status : 'no-response'}`);
     return await res.json();
   } finally {