toolfunnel 0.3.0 → 0.5.0

package/docs/management.md

@@ -1,429 +0,0 @@
-# Management & execution modes
-
-ToolFunnel can manage *itself* through the same lean meta-tool surface it uses for everything
-else. Eight first-party **management functions** — all in the register `category: "management"` —
-let an agent (or a human, via the admin UI) add and toggle tools, register and curate upstream
-MCPs, configure the hook gate, list everything that is configured, and switch the activity log on
-or off. There is no separate admin API and no extra advertised tool: management runs through
-`toolfunnel_run_tool`, behind the **same `PreToolUse` gate** as any other tool. That is deliberate —
-the functions that *configure* the gateway are themselves gateable, which is the recursive-safety
-story this document ends on.
-
-This document is derived from the scripts that implement the functions
-(`tools/scripts/tf-*.js`), their register entries (`tools/tools.register.json`), and the register
-engine (`src/tools/registry.js`) — not from intent. For the hook gate itself see
-[`hooks-and-gating.md`](hooks-and-gating.md); for the register/upstream model see
-[`tools-and-upstreams.md`](tools-and-upstreams.md); for the manifest/overlay field reference see
-[`configuration.md`](configuration.md).
-
----
-
-## The management surface at a glance
-
-| Function | What it changes | Read/Write | Liveness |
-|---|---|---|---|
-| `tf_tool_add` | Adds a register entry (optionally writes its backing script). | write | live — meta-tools re-read the register every call |
-| `tf_tool_set` | Enables / disables / removes a register tool. | write | live |
-| `tf_mcp_add` | Registers an upstream MCP (optionally curates some of its tools). | write | curated-direct surface needs an aggregator reconnect |
-| `tf_mcp_set` | Enables / disables / removes an upstream MCP. | write | reconnect for the curated-direct surface |
-| `tf_hook_add` | Adds a hook manifest entry (e.g. a `PreToolUse` gate). | write | live for the gate (loaded per gated run) |
-| `tf_hook_set` | Enables / disables / removes a hook. | write | live |
-| `tf_list` | Lists tools, MCPs, or hooks with their live state. | read-only | n/a |
-| `tf_log` | Enables / disables / checks the JSONL audit log. | write | live |
-
-All eight are ordinary register entries whose `invoke` is `{ type:"script", path:"scripts/tf-*.js" }`,
-so they resolve to **gateway-run** mode (they execute server-side, on the host where ToolFunnel
-lives — see *Execution modes*, below) and they touch **only** files inside the ToolFunnel root
-(each script resolves its paths from its own `__dirname`, never from a caller-supplied path).
-
----
-
-## How an AI invokes a management function
-
-There is no special calling convention. A management function is reached exactly like every other
-register tool — through the run meta-tool:
-
-```jsonc
-toolfunnel_run_tool({ name: "tf_list", args: { kind: "tools" } })
-```
-
-- **`name`** is the exact tool name as returned by `toolfunnel_list_tools` (e.g. `"tf_tool_add"`).
-  For management functions the register `id` and display `name` are identical, so the distinction
-  never matters here.
-- **`args`** is the structured argument object for that function (the tables below). Omitted/empty
-  args arrive at the script as `null`/`{}`; each script reports bad input as a clean
-  `{ ok:false, error }` rather than crashing.
-- Discover them first with `toolfunnel_list_tools({ category: "management" })`; pull a single
-  function's argument doc with `toolfunnel_tool_instructions({ name: "tf_hook_add" })`.
-
-### The result envelope
-
-`toolfunnel_run_tool` returns the canonical gateway result, **not** the script's JSON directly.
-For a successful gateway-run call:
-
-```jsonc
-{
-  "ok": true,
-  "blocked": false,
-  "output": {
-    "ok": true,            // ← from the script (defaultRunScript: ok = exit code 0)
-    "code": 0,
-    "stdout": "{\"ok\":true,\"id\":\"echo-upper\",\"name\":\"Echo Upper\", ...}\n",
-    "stderr": ""
-  }
-}
-```
-
-The management function's own JSON payload (e.g. `{ ok:true, id, action, enabled, state }`) is the
-**single JSON line in `output.stdout`** — parse that to read what the function reported. A logical
-failure inside the script is still `output.stdout` with `{ ok:false, error }` and exit 0 (the script
-contract); the run itself succeeded.
-
-If a `PreToolUse` hook **denies** the call, you instead get the block envelope and the script never
-runs:
-
-```jsonc
-{ "ok": false, "blocked": true, "reason": "<hook's deny reason>", "output": null }
-```
-
----
-
-## The eight management functions
-
-Every script follows the same contract (`src/tools/registry.js::defaultRunScript`): args arrive as
-JSON in `TOOLFUNNEL_TOOL_ARGS`, the script prints **exactly one JSON object** to stdout and exits 0.
-Writes are atomic (temp file + fsync + rename). The shapes below are exactly what each script reads.
-
-### `tf_tool_add` — register a new tool
-
-Adds a register entry, and (optionally) writes the backing script in the same call so the entry
-never references a missing file. Change is **live** — the meta-tools re-read the register on the
-next call, no reconnect.
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `id` | string (required) | Stable, unique key. Fails if it already exists. |
-| `name` | string (required) | Display name. |
-| `summary` | string | The one line `toolfunnel_list_tools` shows — keep it tight. |
-| `category` | string | Grouping label (`text`, `crypto`, …). |
-| `instructions` | string | Full usage doc returned by `toolfunnel_tool_instructions`. |
-| `invoke` | object (required) | `{ type:"script", path:"scripts/<file>" }` or `{ type:"shell", command:"…" }`. |
-| `scriptText` | string | If given **and** `invoke.type === "script"`, the body is written to `tools/scripts/<basename>` first (path-guarded), then the entry is added. |
-
-Output: `{ ok:true, ...<the added entry>, scriptPath?: "<abs path>" }` (the `scriptPath` only when
-`scriptText` was written), or `{ ok:false, error }`.
-
-> **Mode note:** `tf_tool_add` does **not** accept a `mode` field — it always carries an `invoke`,
-> so the new tool resolves to **gateway-run** (the mode is inferred from the invoke). To make a tool
-> **reference**-mode, set its `mode` via the admin UI's per-tool mode control or by editing the
-> register entry directly (see *Execution modes*).
-
-```jsonc
-// Add a script tool AND author its script in one call:
-toolfunnel_run_tool({
-  name: "tf_tool_add",
-  args: {
-    id: "echo-upper",
-    name: "Echo Upper",
-    summary: "Uppercase the supplied text and echo it back.",
-    category: "text",
-    instructions: "Args: { text: string }. Returns { ok:true, upper }.",
-    invoke: { type: "script", path: "scripts/echo-upper.js" },
-    scriptText: "#!/usr/bin/env node\n'use strict';\nconst a=JSON.parse(process.env.TOOLFUNNEL_TOOL_ARGS||'null');\nprocess.stdout.write(JSON.stringify({ok:true,upper:String(a&&a.text||'').toUpperCase()})+'\\n');\n"
-  }
-})
-```
-
-### `tf_tool_set` — enable / disable / remove a tool
-
-Flips the active overlay or removes a tool entirely.
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `id` | string (required) | The register id. |
-| `action` | `"enable"` \| `"disable"` \| `"remove"` (required) | `enable`/`disable` flip the `tools/tools.state.json` active overlay (default ON); `remove` deletes the register entry **and** purges its state key. |
-
-Disabled tools are hidden from `toolfunnel_list_tools` (the entry stays in the register).
-Output: `{ ok:true, id, action, enabled, state }` for enable/disable, or
-`{ ok:true, id, action, removed:true, state }` for remove (`state` is the resulting overlay map).
-
-```jsonc
-toolfunnel_run_tool({ name: "tf_tool_set", args: { id: "echo-upper", action: "disable" } })
-```
-
-### `tf_mcp_add` — register an upstream MCP (and optionally curate it)
-
-Adds an `upstreams[]` entry to `mcp/expose.json` and, for each `expose[]` item, a curated-direct
-selection. The curated-direct surface is advertised at connect time, so **a new expose needs an
-aggregator reconnect to appear**; the upstream record itself is persisted immediately.
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `id` | string (required) | Unique upstream key referenced by exposes. |
-| `command` | string (required) | The interpreter/executable to spawn (`node`, `npx`, …). |
-| `args` | string[] | argv. Any **path-shaped** token must resolve inside the ToolFunnel root (isolation guard). |
-| `env` | object | Extra environment for the spawned process. |
-| `transport` | string (default `"stdio"`) | Connection transport. |
-| `enabled` | boolean (default `true`) | Whether the aggregator connects to it. |
-| `description` | string | Human-facing note for the UI. |
-| `expose` | array | `[{ tool, as?, category?, enabled? }]` — each item curates one upstream tool. `tool` is the upstream's real tool name; `as` is the downstream name (defaults to `<id>_<tool>`). |
-
-Output: `{ ok:true, upstream:{…}, exposed:[{…}] }`, or `{ ok:false, error }`. There is **no
-cross-step transaction**: if the upstream is added but a later `expose[]` item fails validation, the
-upstream and earlier exposes remain persisted and the failure is reported.
-
-```jsonc
-toolfunnel_run_tool({
-  name: "tf_mcp_add",
-  args: {
-    id: "mock",
-    command: "node",
-    args: ["mcp/servers/mock-upstream/server.js"],
-    description: "Bundled demo upstream (ping, add, echo).",
-    expose: [
-      { tool: "ping", as: "mock_ping", category: "demo" }
-    ]
-  }
-})
-```
-
-### `tf_mcp_set` — enable / disable / remove an upstream MCP
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `id` | string (required) | The upstream id. |
-| `action` | `"enable"` \| `"disable"` \| `"remove"` (required) | `enable`/`disable` toggle the upstream; `remove` deletes it and **cascade-removes** its `expose[]` entries. |
-
-A reconnect is needed for the curated-direct surface to reflect the change. All three actions throw
-on an unknown id (surfaced as `{ ok:false, error }`). Output: `{ ok:true, action, id, upstream:{…} }`
-for enable/disable, or `{ ok:true, action, id, removed:true }` for remove.
-
-```jsonc
-toolfunnel_run_tool({ name: "tf_mcp_set", args: { id: "example", action: "disable" } })
-```
-
-### `tf_hook_add` — add a hook (e.g. a `PreToolUse` gate)
-
-Registers a hook in `hooks/hooks.manifest.json` and, optionally, writes its inline script under
-`hooks/scripts/` (path-guarded). The manifest row is registered first; if the inline write fails the
-row is **rolled back** so a failed add leaves no orphan entry.
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `id` | string (required) | Format `"<kebab-event>/<name>"`, e.g. `"pre-tool-use/gate-danger"`. |
-| `event` | string (required) | One of the six lifecycle events; `PreToolUse` is the enforcement gate. |
-| `matcher` | string | Regex (full-match, anchored) against `tool_name`. `""`/`"*"` = always fire. |
-| `command` | string (required) | What the runner spawns. Use the portable `${HOOKS_DIR}` token, e.g. `node "${HOOKS_DIR}/scripts/gate.js"`. |
-| `script` | string | Path (relative to `hooks/`) used by the manager's open/edit. |
-| `timeout` | number | Seconds (default 60). |
-| `enabled` | boolean (default **`true`**) | The manifest seed; live toggles live in `hooks.state.json`. |
-| `description` | string | Human-facing note. |
-| `scriptText` | string | If given, the script body is authored under `hooks/scripts/`. |
-
-Output: `{ ok:true, id, hook:{…}, scriptWritten:bool }`, or `{ ok:false, error }`.
-
-> **Match the display name.** The `tool_name` a `PreToolUse` matcher sees for a first-party tool is
-> the register **display name** (it equals the id for management functions). Spaces are literal:
-> gate the `danger` demo (name `"Danger Demo"`) with `matcher: "Danger Demo"`, not `"danger"`.
-
-```jsonc
-// Gate the danger demo unless { confirm: true } is passed:
-toolfunnel_run_tool({
-  name: "tf_hook_add",
-  args: {
-    id: "pre-tool-use/gate-danger",
-    event: "PreToolUse",
-    matcher: "Danger Demo",
-    command: "node \"${HOOKS_DIR}/scripts/gate-danger.js\"",
-    script: "scripts/gate-danger.js",
-    timeout: 5,
-    description: "Deny Danger Demo unless args.confirm === true.",
-    scriptText: "#!/usr/bin/env node\nlet r='';process.stdin.on('data',c=>r+=c);process.stdin.on('end',()=>{let e={};try{e=JSON.parse(r||'{}')}catch(_){process.exit(2)}if(e.tool_input&&e.tool_input.confirm===true)process.exit(0);process.stderr.write('confirm required');process.exit(2)});\n"
-  }
-})
-```
-
-### `tf_hook_set` — enable / disable / remove a hook
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `id` | string (required) | The hook id. |
-| `action` | `"enable"` \| `"disable"` \| `"remove"` (required) | `enable`/`disable` write the `hooks.state.json` overlay (which **wins** over the manifest seed) and mirror the manifest; `remove` deletes the manifest entry and purges the overlay key (the script file is left in place). |
-
-Output: `{ ok:true, id, action, enabled }` for enable/disable, or `{ ok:true, id, action, removed }`
-for remove (`removed` is `false` if the id was already absent — information, not a fault).
-
-```jsonc
-toolfunnel_run_tool({ name: "tf_hook_set", args: { id: "pre-tool-use/gate-danger", action: "disable" } })
-```
-
-### `tf_list` — inventory (read-only)
-
-The one read function: "what is configured, and what is its live state?" across the three stores.
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `kind` | `"tools"` \| `"mcps"` \| `"hooks"` (required) | Which store to enumerate. |
-
-- `tools` → register briefs `{ id, name, summary, category }` annotated with `{ enabled, hidden }`.
-- `mcps` → one item per upstream (its full config incl. `enabled`) with its curated-direct
-  `exposed` entries nested (each carrying its resolved downstream `name` and `enabled`).
-- `hooks` → one item per manifest hook (full spec) with `enabled` resolved from the live overlay.
-
-Output: `{ ok:true, kind, items:[…] }`. No writes, no network, no process mutation.
-
-```jsonc
-toolfunnel_run_tool({ name: "tf_list", args: { kind: "hooks" } })
-```
-
-### `tf_log` — the activity / audit log
-
-Toggles ToolFunnel's JSONL audit log (tool runs + gate allow/deny decisions). **Default OFF.**
-
-| Arg | Type | Meaning |
-|---|---|---|
-| `action` | `"enable"` \| `"disable"` \| `"status"` (required) | Turn logging on/off, or report current state. |
-| `path` | string | Optional log path, honoured only on `enable`. |
-
-Output: `{ ok:true, action, enabled, path }` for enable/disable, or
-`{ ok:true, action, enabled, path, count }` for status (`count` = recent log entries). The same
-log is controllable from the UI **Logs** tab and via `logs/log.config.json`.
-
-```jsonc
-toolfunnel_run_tool({ name: "tf_log", args: { action: "enable" } })
-toolfunnel_run_tool({ name: "tf_log", args: { action: "status" } })
-```
-
----
-
-## Management runs gated — the recursive-safety story
-
-The management functions are not privileged. They are gateway-run tools, so every call funnels
-through the **same `gatedRun` `PreToolUse` gate** as `danger` or any curated upstream tool
-(`src/mcp/gated-run.js`). That means **a `PreToolUse` hook can restrict or deny a management call**,
-and the gateway can govern the tools that govern *it*.
-
-**Default is allow.** The shipped `hooks/hooks.manifest.json` has an empty `hooks` array, which is
-allow-all — no hook fires, so management functions run unrestricted out of the box. Safety here is
-**opt-in**: you add an enabled `PreToolUse` hook whose matcher matches the management tool name(s).
-Because the `tool_name` the gate sees is the register name (which equals the id for these
-functions), the matcher is the bare id or an alternation of ids — for example `tf_.*` to cover the
-whole family, or `tf_hook_set|tf_log` to guard just the two that could blind the gateway:
-
-```jsonc
-// Add a gate over the riskiest management functions: require { confirm: true }.
-toolfunnel_run_tool({
-  name: "tf_hook_add",
-  args: {
-    id: "pre-tool-use/gate-management",
-    event: "PreToolUse",
-    matcher: "tf_hook_set|tf_hook_add|tf_log|tf_tool_set",
-    command: "node \"${HOOKS_DIR}/scripts/gate-management.js\"",
-    script: "scripts/gate-management.js",
-    description: "Require confirm:true before changing hooks/logging/tools.",
-    scriptText: "#!/usr/bin/env node\nlet r='';process.stdin.on('data',c=>r+=c);process.stdin.on('end',()=>{let e={};try{e=JSON.parse(r||'{}')}catch(_){process.exit(2)}const a=e.tool_input&&e.tool_input.args;if(a&&a.confirm===true)process.exit(0);process.stderr.write('management change requires args.confirm:true');process.exit(2)});\n"
-  }
-})
-```
-
-Why this matters:
-
-- **The gate is uniform and unbypassable.** There is no back door that runs a management function
-  outside `gatedRun`, so a deny on `tf_*` is as enforced as a deny on any other tool.
-- **`tf_log` and the hook functions can themselves be gated.** As the `tf_log` instructions note,
-  "like any tool, `tf_log` can itself be disabled to revoke logging control." Gating `tf_hook_set`
-  / `tf_hook_add` likewise prevents an agent from quietly disabling the very gate that constrains
-  it. This is the recursive-safety property: the controls *and* the controls-on-the-controls live
-  in the same gated surface.
-- **Fail closed still holds.** If the gating hook errors or returns junk, the `PreToolUse` is
-  treated as a deny — a gate you can't trust to answer "allowed?" is never read as "allowed". A
-  management change can never slip through on a broken hook.
-
-One bootstrapping caveat to keep in mind: if you gate `tf_hook_set` behind a confirmation you can no
-longer toggle hooks *without* satisfying that confirmation — including the gate you just added. Keep
-the admin UI (`node bin/toolfunnel.js --ui`) or a direct manifest edit as your out-of-band escape
-hatch when you lock the hook functions down.
-
----
-
-## Execution modes: reference vs gateway-run
-
-Every register entry resolves to one of two **execution modes** (`src/tools/registry.js`,
-`resolveMode`). The mode decides *where the work happens* when `toolfunnel_run_tool` is called.
-
-### `gateway-run` — ToolFunnel executes it, server-side, behind the gate
-
-`mode: "gateway"`. ToolFunnel runs the tool's `invoke` itself: a `script` invoke spawns `node` on
-the host-local script; a `shell` invoke is handed to the gated runner which spawns the shell **only
-after `PreToolUse` allows**. The result comes back in the run envelope's `output`. This is the
-original behaviour and the mode of **every shipped tool**, including all eight management functions.
-
-Use gateway-run when:
-
-- the action must run **on the host where ToolFunnel lives** (its filesystem, its config, its
-  credentials) — the management functions are the canonical case;
-- you want the call **centrally gated, logged, and audited** through `gatedRun`;
-- the work is a deterministic host-local script or one-line command.
-
-### `reference` — ToolFunnel only *describes* it; the AI runs it
-
-`mode: "reference"`. ToolFunnel executes **nothing**. `toolfunnel_run_tool` short-circuits **before**
-the gate and returns the tool's instructions so the **connected AI performs the action in its own
-environment**:
-
-```jsonc
-{
-  "ok": true,
-  "mode": "reference",
-  "name": "deploy-notes",
-  "instructions": "<the entry's instructions string>",
-  "message": "reference tool — perform this in your own environment per the instructions"
-}
-```
-
-Because nothing runs server-side, **no `PreToolUse` hook fires for a reference tool** — there is no
-host-side side effect to gate; governance of the action is the AI's own environment's responsibility.
-A reference entry needs no `invoke` (there is nothing to execute), so it may omit it.
-
-Use reference when:
-
-- the AI is better placed to act — it has the right filesystem, tokens, or working directory;
-- you only want to hand the model **authoritative instructions** rather than run code centrally;
-- you explicitly do **not** want ToolFunnel to execute the action on the host.
-
-### The backward-compatible default (how the mode is inferred)
-
-An explicit, valid `mode` field always wins. When `mode` is **absent**, it is inferred so that every
-pre-existing tool keeps its original behaviour:
-
-| Entry | Inferred mode |
-|---|---|
-| `invoke.type === "script"` | `gateway` |
-| `invoke.type === "shell"` | `gateway` |
-| no executable invoke (and `mode` absent) | `reference` |
-
-Validation backs this up: with `mode` **absent** an `invoke` is still **required** (so an existing
-tool without a mode can never silently become a do-nothing reference). Only an **explicit**
-`mode: "reference"` relaxes the invoke requirement. An invalid `mode` value is rejected at load.
-
-### Setting a tool's mode
-
-- **New tools via `tf_tool_add`** always supply an `invoke`, so they come out **gateway-run** (the
-  inferred default). `tf_tool_add` does not take a `mode` argument.
-- **To switch a tool to `reference` (or back)**, use the admin UI's per-tool mode control
-  (`POST /api/tools/mode {id, mode}` → `registry.update(id,{mode})`), or edit the register entry's
-  `mode` field directly. Switching a tool that *has* an `invoke` to `reference` simply stops
-  ToolFunnel from executing it — the `invoke` is ignored while the mode is `reference`.
-
----
-
-## Quick reference
-
-```text
-Discover:   toolfunnel_list_tools({ category: "management" })
-Learn args: toolfunnel_tool_instructions({ name: "tf_hook_add" })
-Invoke:     toolfunnel_run_tool({ name: "<tf_*>", args: { … } })
-Read back:  parse output.stdout (the script's own { ok, … } JSON)
-Gate them:  a PreToolUse hook matching "tf_.*" (default = allow-all)
-Modes:      gateway-run = ToolFunnel executes (gated) · reference = AI executes (no gate)
-```

package/docs/oauth.md

@@ -1,103 +0,0 @@
-# OAuth 2.1 — optional resource-server validation
-
-ToolFunnel is **loopback-only and unauthenticated by default** — the right posture for a single
-operator on `localhost`. For a networked or multi-user deployment it can act as an **OAuth 2.1
-resource server**: it validates the bearer token on every HTTP request *before any tool runs*.
-
-This is **opt-in** and the only feature that adds a dependency.
-
-## The one dependency
-
-The core gateway has `"dependencies": {}`. Enabling OAuth adds exactly one library —
-[`jose`](https://www.npmjs.com/package/jose) — which is **itself zero-dependency**, audited, and the
-same library the official MCP SDK uses. It is **not** a runtime dependency of the package: it lives
-in `devDependencies` (for the test suite) and is **installed on demand**:
-
-```bash
-toolfunnel install-oauth        # runs: npm install jose@<pinned>
-```
-
-…or click **Install** in the UI's **Auth** tab. Everyone who does not enable OAuth pulls nothing.
-
-> **Why a library, not hand-rolled `node:crypto`?** Verifying a JWT securely is not the signature
-> math (`node:crypto` has that) — it is the protocol discipline around it: pinning the algorithm so
-> an attacker can't downgrade RS256→HS256, rejecting `alg:none`, ignoring attacker-controlled header
-> params, validating `iss`/`aud`/`exp`/`nbf`, and JWKS caching + rotation. Each is a known CVE class.
-> For the most security-sensitive code in the project, delegating to an audited library is the
-> deliberate, defensible call — and `jose` is itself zero-dependency, so the audit surface barely
-> moves. `jose` v5 (the CommonJS build, Node ≥ 18) is the pinned major.
-
-### Installing on demand — and the guaranteed manual fallback
-
-`toolfunnel install-oauth` and the UI **Install** button both call the same installer
-(`src/auth/install.js`). It is built to work where a naïve `npm install` breaks:
-
-- **It runs npm's own JS entry directly with `node`** — `node <…>/npm/bin/npm-cli.js install jose@<pin>
-  --no-save` with `shell:false`. It does **not** spawn `npm.cmd`. Since the CVE-2024-27980 mitigation,
-  spawning a `.cmd` without a shell throws `EINVAL`, and spawning it *through* a shell misresolves the
-  shim's own path on portable/Windows Node. Running `npm-cli.js` with the current node binary sidesteps
-  all of it — no shell, no PATH lookup, no cwd sensitivity. (`npm-cli.js` is located beside the running
-  `node`; if it genuinely can't be found, the installer falls back to a shell-spawned `npm`, with the
-  version spec validated against a strict allowlist so the fallback can never be injected.)
-- **It installs into the gateway's own `node_modules`** (resolved from the engine's location, not your
-  cwd) with `--no-save`, so `require('jose')` resolves wherever ToolFunnel is installed and the
-  package's `"dependencies": {}` stays untouched.
-- **It never dead-ends.** Auto-install can't be universal — `npm-cli.js` sits in different places across
-  Homebrew / Volta / Docker / odd nvm layouts. So on *any* failure the result carries a copyable
-  `manualCommand` (`npm install jose@<pin>`) and the directory to run it in, and the CLI/UI surface that
-  message. You always have a one-line command that works in your own shell. You can also just run that
-  command yourself up front — the gateway only needs `require('jose')` to resolve.
-
-## What it does
-
-When enabled, the HTTP transport:
-
-- **Validates** the `Authorization: Bearer <token>` on every request to `/mcp` (POST and the SSE GET)
-  and `/health`, via `jose.jwtVerify` with a **pinned algorithm allowlist**, an **enforced issuer**,
-  and an **enforced audience** bound to this gateway's resource URI (the RFC 8707 confused-deputy
-  defence). A failure returns `401` (or `403` for insufficient scope) with a
-  `WWW-Authenticate: Bearer resource_metadata="…"` challenge.
-- **Serves discovery** (unauthenticated) at `GET /.well-known/oauth-protected-resource` — the
-  RFC 9728 Protected Resource Metadata document naming the authorization server(s).
-- **Unlocks a safe non-loopback bind.** With auth **off**, the host refuses to bind a non-loopback
-  address (it would expose an unauthenticated gateway). With auth **on**, the token is the boundary,
-  so off-localhost binds are allowed. The host also **refuses to start** if auth is on but `jose` is
-  missing or the config is incoherent (fail-fast, with an actionable message).
-
-## Configuration — `auth/auth.config.json`
-
-Edit it in the UI's **Auth** tab, or directly. **Default OFF.** Read fresh per request (a toggle is
-live; no restart).
-
-| Field | Type | Meaning |
-|---|---|---|
-| `enabled` | boolean | Master switch. Default `false`. |
-| `issuer` | string | The OAuth 2.1 / OIDC authorization server (the `iss` tokens must carry). **Required when enabled.** |
-| `audience` | string | **This gateway's** resource URI. Tokens must be issued for it (`aud`). **Required when enabled** — without it tokens are unbound (the confused-deputy hole). |
-| `jwksUri` | string | Explicit JWKS endpoint. Optional — if blank it is discovered from the issuer via OIDC / RFC 8414 discovery. |
-| `algorithms` | string[] | The **pinned** signature-algorithm allowlist. Default `["RS256","ES256"]`. Pinning is the algorithm-confusion / `alg:none` defence. |
-| `requiredScopes` | string[] | Optional. Every listed scope must be present (`scope` or `scp` claim), else `403 insufficient_scope`. |
-| `clockToleranceSec` | number | `exp`/`nbf` skew tolerance, seconds. Default `30`, clamped to `[0, 300]`. |
-
-### Example (enabled)
-
-```json
-{
-  "enabled": true,
-  "issuer": "https://auth.example.com",
-  "audience": "https://gateway.example.com",
-  "jwksUri": "",
-  "algorithms": ["RS256", "ES256"],
-  "requiredScopes": [],
-  "clockToleranceSec": 30
-}
-```
-
-## Roles, and what is *not* yet implemented
-
-ToolFunnel implements the **resource-server** role (validating inbound tokens). The OAuth **client**
-leg — Dynamic Client Registration (RFC 7591), authorization-server-metadata discovery for *outbound*
-calls, step-up authorization — and the 2026 spec hardening (RFC 9207 issuer validation, credential
-binding) are **roadmap**, not shipped. So today ToolFunnel authenticates clients *to it*; it does not
-yet perform the full client-side flow *to upstreams that require OAuth*. See the
-[roadmap](../README.md#roadmap).