mcp-trellis 1.0.0 → 2.1.0

package/docs/compatibility.md

@@ -0,0 +1,84 @@
+# Compatibility evidence
+
+Updated 2026-09-14. Repository implementation and automated coverage are in good
+shape after the pre-prod security pass. **Vendor-client UI sessions are still
+Pending** — do not convert product rows to ✅ until a live Claude/ChatGPT/Codex/Gemini
+check below is filled in.
+
+| Product | Server profile | Repository evidence | Live evidence |
+|---|---|---|---|
+| Claude custom connector | `claude`: DCR / CIMD, public client, S256 PKCE; built-in callback | `test/oauth/policy/clients.test.ts`, `test/oauth/endpoints/dcr.test.ts`, `test/oauth/cimd/cimd.test.ts`, `test/oauth/crypto/pkce.test.ts`; saas-demo e2e + `scripts/prep-claude-oauth.mjs` | Pending (UI) |
+| ChatGPT | `codex`: public-client profile; exact hosted callback must be configured | Profile tests only; no ChatGPT UI test | Pending |
+| Codex | `codex`: public client, PKCE, loopback callbacks allowed | Profile/redirect tests; no actual Codex login run | Pending |
+| Gemini Enterprise | `gemini`: `clientStore`, pre-registration, `client_secret_basic` / `client_secret_post` | Client authentication tests; no Enterprise environment | Pending |
+
+The Gemini profile does not imply compatibility with Gemini CLI or every Gemini product. ChatGPT and Codex need separate live checks even though the package groups them under one profile.
+
+`src/mcp/protocol.ts` implements `2024-11-05`, `2025-03-26`, `2025-06-18`. Initialization defaults to `2025-06-18`; absent request headers use `2025-03-26`. This is an implementation inventory, not a claim to implement the latest revision. **CIMD is shipped opt-in** (`cimd: true` on `createMcpApp` / `createOAuthRouter`; off by default — see [security.md](security.md) SSRF ceiling). Live vendor UI evidence stays **Pending** until an operator connects a real client.
+
+## Demo deploy (Worker)
+
+Compile-checked Worker sketch: [`examples/cloudflare-worker.ts`](../examples/cloudflare-worker.ts).
+
+One-liner after you add a minimal `wrangler.toml` (name, `compatibility_date`, and secrets
+`OAUTH_CODE_SECRET` / `ACCESS_TOKEN_SECRET`):
+
+```bash
+npx wrangler secret put OAUTH_CODE_SECRET
+npx wrangler secret put ACCESS_TOKEN_SECRET
+npx wrangler deploy examples/cloudflare-worker.ts
+```
+
+Point a connector at `https://YOUR-WORKER/mcp` only after secrets and an origin
+allowlist match your route. This path proves the Worker mounts; it does **not**
+replace the live client rows below.
+
+## Host contract covered in-repo
+
+`examples/saas-demo` now mints refresh tokens and enforces RFC 6749 §6: requested
+refresh `scope` must be ⊆ the scopes originally bound to that refresh token
+(`isScopeSubset` pattern also in `examples/stores.ts`). Escalation →
+`invalid_grant`. Covered by `test/e2e/saas-demo.test.ts`.
+
+## Automated package smoke (not a vendor live pass)
+
+```bash
+npm run smoke:pack
+```
+
+Installs the local `npm pack` tarball in a temp directory and imports
+`createMcpApp` / `asNodeHandler`. Record date/commit when you run it before a
+release; it does **not** replace the live client row.
+
+| Date | Commit / package | Command | Result |
+|---|---|---|---|
+| 2026-09-12 | unreleased working tree (`1.1.0` pack) | `npm run smoke:pack` | Pass — `createMcpApp` + `asNodeHandler` import from tarball |
+
+## Evidence required for a live pass
+
+Record client product, version/build (or web UI and test date), account tier, package version/commit, hosting environment and configured callback. Capture discovery → registration → app login → consent → token exchange → initialize → tools/list → `list_my_projects`. Verify wrong audience/invalid token rejection and user isolation separately. Save sanitized output or recording; exclude cookies, passwords, codes and tokens.
+
+Against a public HTTPS demo (`PUBLIC_ORIGIN` + `DEMO_PASSWORD`):
+
+```bash
+npm run demo   # reverse-proxy to HTTPS; set PUBLIC_ORIGIN
+node scripts/prep-claude-oauth.mjs   # scripted OAuth + refresh scope + tool
+# Then open the vendor UI with MCP URL https://YOUR-HOST/mcp and record below.
+```
+
+| Date | Client/build | Package/commit | Protocol negotiated | Tool + expected result | Evidence | Result |
+|---|---|---|---|---|---|---|
+| — | — | — | — | — | — | Pending |
+
+## Under-ten-minute onboarding test
+
+Use a clean folder and the published npm tarball, start a timer at `npm install`, and stop at a real client's first correct user-scoped tool response. Record setup prerequisites, elapsed time, every edit and any error. A local source import or simulated OAuth flow is insufficient. Target: under ten minutes with hosting and a supported client account available; no time claim is published until measured.
+
+| Field | Value |
+|---|---|
+| Start (`npm install`) | — |
+| Stop (first correct tool in real client) | — |
+| Elapsed | — |
+| Prerequisites (hosting, account, callback) | — |
+| Edits / errors | — |
+| Result | Pending |

package/docs/diagrams/mcp-trellis-architecture.html

@@ -0,0 +1,305 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>mcp-trellis · Architecture</title>
+  <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Hebrew:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    :root {
+      --color-paper:   #f5f5fb;
+      --color-ink:     #1e1f29;
+      --color-muted:   #55566b;
+      --color-accent:  #5b5bf0;
+      --font-sans:     'Noto Sans Hebrew', system-ui, sans-serif;
+      --font-mono:     ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace;
+    }
+
+    body {
+      font-family: var(--font-sans);
+      background: var(--color-paper);
+      color: var(--color-ink);
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 3rem 2rem;
+    }
+
+    .frame { max-width: 1280px; width: 100%; }
+
+    .eyebrow {
+      font-family: var(--font-mono);
+      font-size: 0.66rem;
+      font-weight: 500;
+      letter-spacing: 0.18em;
+      text-transform: uppercase;
+      color: var(--color-muted);
+      margin-bottom: 0.5rem;
+    }
+
+    h1 {
+      font-family: var(--font-sans);
+      font-size: clamp(1.5rem, 2.4vw + 0.75rem, 2rem);
+      font-weight: 700;
+      letter-spacing: -0.02em;
+      line-height: 1.15;
+      color: var(--color-ink);
+      margin-bottom: 1.5rem;
+    }
+
+    svg { width: 100%; min-width: 960px; display: block; }
+  </style>
+</head>
+<body>
+  <div class="frame">
+    <p class="eyebrow">Architecture · mcp-trellis</p>
+    <h1>Host-agnostic MCP + OAuth 2.1</h1>
+
+    <svg viewBox="0 0 1280 760" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="mcp-trellis-architecture-title mcp-trellis-architecture-desc">
+      <title id="mcp-trellis-architecture-title">mcp-trellis architecture</title>
+      <desc id="mcp-trellis-architecture-desc">Connectors reach an edge host, then createMcpApp routes OAuth and MCP traffic to library handlers and your login, token, store, and tool ports.</desc>
+      <defs>
+        <marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#55566b"/></marker>
+        <marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#5b5bf0"/></marker>
+        <marker id="arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#4545c8"/></marker>
+      </defs>
+
+      <rect width="100%" height="100%" fill="#f5f5fb"/>
+
+      <!-- Zones (before arrows) -->
+      <rect x="40" y="96" width="168" height="400" rx="8"
+            fill="rgba(30,31,41,0.02)" stroke="rgba(30,31,41,0.10)" stroke-width="0.8"/>
+      <rect x="84" y="100" width="80" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="124" y="109" fill="rgba(30,31,41,0.40)" font-size="7" font-family="ui-monospace, monospace"
+            text-anchor="middle" letter-spacing="0.14em">CONNECTORS</text>
+
+      <rect x="440" y="56" width="480" height="520" rx="8"
+            fill="rgba(30,31,41,0.02)" stroke="rgba(30,31,41,0.10)" stroke-width="0.8"/>
+      <rect x="624" y="60" width="112" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="680" y="69" fill="rgba(30,31,41,0.40)" font-size="7" font-family="ui-monospace, monospace"
+            text-anchor="middle" letter-spacing="0.14em">MCP-TRELLIS</text>
+
+      <rect x="980" y="96" width="260" height="440" rx="8"
+            fill="rgba(30,31,41,0.02)" stroke="rgba(30,31,41,0.10)" stroke-width="0.8"/>
+      <rect x="1052" y="100" width="116" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="1110" y="109" fill="rgba(30,31,41,0.40)" font-size="7" font-family="ui-monospace, monospace"
+            text-anchor="middle" letter-spacing="0.14em">YOUR PORTS</text>
+
+      <!-- Arrows -->
+      <!-- Clients → Edge (link) -->
+      <line x1="192" y1="172" x2="248" y2="172" stroke="#4545c8" stroke-width="1.2" marker-end="url(#arrow-link)"/>
+      <line x1="192" y1="292" x2="248" y2="292" stroke="#4545c8" stroke-width="1.2" marker-end="url(#arrow-link)"/>
+      <line x1="192" y1="412" x2="248" y2="412" stroke="#4545c8" stroke-width="1.2" marker-end="url(#arrow-link)"/>
+
+      <!-- Edge → createMcpApp (accent primary) -->
+      <path d="M 392,292 H 480 Q 488,292 488,284 V 120 Q 488,112 496,112 H 592"
+            fill="none" stroke="#5b5bf0" stroke-width="1.4" marker-end="url(#arrow-accent)"/>
+
+      <!-- createMcpApp → OAuth / MCP -->
+      <path d="M 640,144 V 168 H 558 Q 550,168 550,176 V 200"
+            fill="none" stroke="#55566b" stroke-width="1.2" marker-end="url(#arrow)"/>
+      <path d="M 720,144 V 168 H 802 Q 810,168 810,176 V 200"
+            fill="none" stroke="#55566b" stroke-width="1.2" marker-end="url(#arrow)"/>
+
+      <!-- OAuth → Consent / Discovery -->
+      <line x1="550" y1="280" x2="550" y2="312" stroke="#5b5bf0" stroke-width="1.2" marker-end="url(#arrow-accent)"/>
+      <line x1="550" y1="376" x2="550" y2="408" stroke="#55566b" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#arrow)"/>
+
+      <!-- MCP → Audience → Registry -->
+      <line x1="810" y1="280" x2="810" y2="312" stroke="#55566b" stroke-width="1.2" marker-end="url(#arrow)"/>
+      <line x1="810" y1="376" x2="810" y2="408" stroke="#55566b" stroke-width="1.2" marker-end="url(#arrow)"/>
+
+      <!-- Library → Ports (distinct Auth attach points: MINT@160, VERIFY@184) -->
+      <path d="M 640,228 H 680 Q 688,228 688,220 V 168 Q 688,160 696,160 H 1000"
+            fill="none" stroke="#4545c8" stroke-width="1.2" marker-end="url(#arrow-link)"/>
+      <path d="M 640,256 H 680 Q 688,256 688,264 V 288 Q 688,296 696,296 H 1000"
+            fill="none" stroke="#55566b" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#arrow)"/>
+      <path d="M 900,344 H 940 Q 948,344 948,336 V 192 Q 948,184 956,184 H 1000"
+            fill="none" stroke="#55566b" stroke-width="1.2" marker-end="url(#arrow)"/>
+      <line x1="900" y1="440" x2="1000" y2="440" stroke="#55566b" stroke-width="1.2" marker-end="url(#arrow)"/>
+
+      <!-- Arrow labels (6–10px gap above stroke) -->
+      <rect x="204" y="152" width="36" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="222" y="161" fill="#4545c8" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">HTTPS</text>
+
+      <rect x="500" y="92" width="48" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="524" y="101" fill="#5b5bf0" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">FETCH</text>
+
+      <rect x="568" y="148" width="40" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="588" y="157" fill="#55566b" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">OAUTH</text>
+
+      <rect x="744" y="148" width="32" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="760" y="157" fill="#55566b" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">MCP</text>
+
+      <rect x="560" y="288" width="52" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="586" y="297" fill="#5b5bf0" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">APPROVE</text>
+
+      <rect x="560" y="384" width="40" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="580" y="393" fill="#8d8ea3" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">META</text>
+
+      <rect x="820" y="288" width="36" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="838" y="297" fill="#55566b" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">AUD</text>
+
+      <rect x="820" y="384" width="48" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="844" y="393" fill="#55566b" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">SCOPE</text>
+
+      <rect x="820" y="140" width="40" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="840" y="149" fill="#4545c8" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">MINT</text>
+
+      <rect x="924" y="276" width="44" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="946" y="285" fill="#8d8ea3" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">STORE</text>
+
+      <rect x="880" y="164" width="48" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="904" y="173" fill="#55566b" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">VERIFY</text>
+
+      <rect x="928" y="420" width="40" height="12" rx="2" fill="#f5f5fb"/>
+      <text x="948" y="429" fill="#55566b" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.06em">CALL</text>
+
+      <!-- Nodes: Connectors -->
+      <rect x="56" y="140" width="136" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="56" y="140" width="136" height="64" rx="6" fill="rgba(85,86,107,0.10)" stroke="#8d8ea3" stroke-width="1"/>
+      <rect x="64" y="148" width="40" height="12" rx="2" fill="transparent" stroke="rgba(141,142,163,0.40)" stroke-width="0.8"/>
+      <text x="84" y="157" fill="#8d8ea3" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">CLIENT</text>
+      <text x="124" y="176" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Claude</text>
+      <text x="124" y="192" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">DCR + PKCE</text>
+
+      <rect x="56" y="260" width="136" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="56" y="260" width="136" height="64" rx="6" fill="rgba(85,86,107,0.10)" stroke="#8d8ea3" stroke-width="1"/>
+      <rect x="64" y="268" width="40" height="12" rx="2" fill="transparent" stroke="rgba(141,142,163,0.40)" stroke-width="0.8"/>
+      <text x="84" y="277" fill="#8d8ea3" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">CLIENT</text>
+      <text x="124" y="296" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Gemini</text>
+      <text x="124" y="312" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">pre-reg secret</text>
+
+      <rect x="56" y="380" width="136" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="56" y="380" width="136" height="64" rx="6" fill="rgba(85,86,107,0.10)" stroke="#8d8ea3" stroke-width="1"/>
+      <rect x="64" y="388" width="40" height="12" rx="2" fill="transparent" stroke="rgba(141,142,163,0.40)" stroke-width="0.8"/>
+      <text x="84" y="397" fill="#8d8ea3" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">CLIENT</text>
+      <text x="124" y="416" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Codex</text>
+      <text x="124" y="432" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">OAuth 2.1 PKCE</text>
+
+      <!-- Edge host -->
+      <rect x="248" y="148" width="144" height="320" rx="6" fill="#f5f5fb"/>
+      <rect x="248" y="148" width="144" height="320" rx="6" fill="rgba(30,31,41,0.03)" stroke="rgba(30,31,41,0.30)" stroke-width="1"/>
+      <rect x="256" y="156" width="36" height="12" rx="2" fill="transparent" stroke="rgba(30,31,41,0.22)" stroke-width="0.8"/>
+      <text x="274" y="165" fill="#8d8ea3" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">EDGE</text>
+      <text x="320" y="292" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Your host</text>
+      <text x="320" y="312" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">Workers · Next</text>
+      <text x="320" y="328" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">Node · Deno · Bun</text>
+      <text x="320" y="352" fill="#8d8ea3" font-size="8" font-family="ui-monospace, monospace" text-anchor="middle">Request → Response</text>
+
+      <!-- createMcpApp (focal) -->
+      <rect x="592" y="80" width="176" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="592" y="80" width="176" height="64" rx="6" fill="#efeeff" stroke="#5b5bf0" stroke-width="1"/>
+      <rect x="600" y="88" width="36" height="12" rx="2" fill="transparent" stroke="rgba(91,91,240,0.50)" stroke-width="0.8"/>
+      <text x="618" y="97" fill="#5b5bf0" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">APP</text>
+      <text x="680" y="116" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">createMcpApp</text>
+      <text x="680" y="132" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">oauth.tryHandle → /mcp</text>
+
+      <!-- OAuth AS -->
+      <rect x="460" y="200" width="180" height="80" rx="6" fill="#f5f5fb"/>
+      <rect x="460" y="200" width="180" height="80" rx="6" fill="#ffffff" stroke="#1e1f29" stroke-width="1"/>
+      <rect x="468" y="208" width="28" height="12" rx="2" fill="transparent" stroke="rgba(30,31,41,0.40)" stroke-width="0.8"/>
+      <text x="482" y="217" fill="#1e1f29" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">AS</text>
+      <text x="550" y="240" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">OAuth router</text>
+      <text x="550" y="256" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">/authorize · /token</text>
+      <text x="550" y="268" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">/register · /revoke</text>
+
+      <!-- Consent (security, 2nd accent) -->
+      <rect x="460" y="312" width="180" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="460" y="312" width="180" height="64" rx="6" fill="rgba(91,91,240,0.05)" stroke="rgba(91,91,240,0.50)" stroke-width="1" stroke-dasharray="4,4"/>
+      <rect x="468" y="320" width="48" height="12" rx="2" fill="transparent" stroke="rgba(91,91,240,0.40)" stroke-width="0.8"/>
+      <text x="492" y="329" fill="#5b5bf0" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">SECURE</text>
+      <text x="550" y="348" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Consent</text>
+      <text x="550" y="364" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">POST …/consent</text>
+
+      <!-- Discovery -->
+      <rect x="460" y="408" width="180" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="460" y="408" width="180" height="64" rx="6" fill="rgba(30,31,41,0.02)" stroke="rgba(30,31,41,0.20)" stroke-width="1" stroke-dasharray="4,3"/>
+      <rect x="468" y="416" width="36" height="12" rx="2" fill="transparent" stroke="rgba(30,31,41,0.25)" stroke-width="0.8"/>
+      <text x="486" y="425" fill="#8d8ea3" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">META</text>
+      <text x="550" y="444" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Discovery</text>
+      <text x="550" y="460" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">.well-known/*</text>
+
+      <!-- MCP Handler -->
+      <rect x="720" y="200" width="180" height="80" rx="6" fill="#f5f5fb"/>
+      <rect x="720" y="200" width="180" height="80" rx="6" fill="#ffffff" stroke="#1e1f29" stroke-width="1"/>
+      <rect x="728" y="208" width="36" height="12" rx="2" fill="transparent" stroke="rgba(30,31,41,0.40)" stroke-width="0.8"/>
+      <text x="746" y="217" fill="#1e1f29" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">MCP</text>
+      <text x="810" y="240" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">MCP handler</text>
+      <text x="810" y="256" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">JSON-RPC /mcp</text>
+      <text x="810" y="268" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">initialize · tools/*</text>
+
+      <!-- Audience gate (ink dashed — accent reserved for createMcpApp + Consent) -->
+      <rect x="720" y="312" width="180" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="720" y="312" width="180" height="64" rx="6" fill="rgba(30,31,41,0.02)" stroke="rgba(30,31,41,0.30)" stroke-width="1" stroke-dasharray="4,4"/>
+      <rect x="728" y="320" width="36" height="12" rx="2" fill="transparent" stroke="rgba(30,31,41,0.30)" stroke-width="0.8"/>
+      <text x="746" y="329" fill="#55566b" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">GATE</text>
+      <text x="810" y="348" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Audience check</text>
+      <text x="810" y="364" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">RFC 8707 aud</text>
+
+      <!-- Tool registry -->
+      <rect x="720" y="408" width="180" height="64" rx="6" fill="#f5f5fb"/>
+      <rect x="720" y="408" width="180" height="64" rx="6" fill="rgba(30,31,41,0.05)" stroke="#55566b" stroke-width="1"/>
+      <rect x="728" y="416" width="40" height="12" rx="2" fill="transparent" stroke="rgba(85,86,107,0.50)" stroke-width="0.8"/>
+      <text x="748" y="425" fill="#55566b" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">REG</text>
+      <text x="810" y="444" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Tool registry</text>
+      <text x="810" y="460" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">scope-gated call</text>
+
+      <!-- Your ports -->
+      <rect x="1000" y="140" width="220" height="72" rx="6" fill="#f5f5fb"/>
+      <rect x="1000" y="140" width="220" height="72" rx="6" fill="rgba(85,86,107,0.10)" stroke="#8d8ea3" stroke-width="1"/>
+      <rect x="1008" y="148" width="40" height="12" rx="2" fill="transparent" stroke="rgba(141,142,163,0.40)" stroke-width="0.8"/>
+      <text x="1028" y="157" fill="#8d8ea3" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">AUTH</text>
+      <text x="1110" y="176" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Auth ports</text>
+      <text x="1110" y="192" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">resolve · mint · verify</text>
+
+      <rect x="1000" y="260" width="220" height="72" rx="6" fill="#f5f5fb"/>
+      <rect x="1000" y="260" width="220" height="72" rx="6" fill="rgba(30,31,41,0.05)" stroke="#55566b" stroke-width="1"/>
+      <rect x="1008" y="268" width="44" height="12" rx="2" fill="transparent" stroke="rgba(85,86,107,0.50)" stroke-width="0.8"/>
+      <text x="1030" y="277" fill="#55566b" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">STORE</text>
+      <text x="1110" y="296" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Stores</text>
+      <text x="1110" y="312" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">clientStore · codeStore</text>
+
+      <rect x="1000" y="380" width="220" height="72" rx="6" fill="#f5f5fb"/>
+      <rect x="1000" y="380" width="220" height="72" rx="6" fill="#ffffff" stroke="#1e1f29" stroke-width="1"/>
+      <rect x="1008" y="388" width="40" height="12" rx="2" fill="transparent" stroke="rgba(30,31,41,0.40)" stroke-width="0.8"/>
+      <text x="1028" y="397" fill="#1e1f29" font-size="7" font-family="ui-monospace, monospace" text-anchor="middle" letter-spacing="0.08em">TOOLS</text>
+      <text x="1110" y="416" fill="#1e1f29" font-size="12" font-weight="600" font-family="'Noto Sans Hebrew', sans-serif" text-anchor="middle">Tool handlers</text>
+      <text x="1110" y="432" fill="#55566b" font-size="9" font-family="ui-monospace, monospace" text-anchor="middle">your business logic</text>
+
+      <!-- Legend -->
+      <line x1="40" y1="640" x2="1240" y2="640" stroke="rgba(30,31,41,0.10)" stroke-width="0.8"/>
+      <text x="40" y="660" fill="#55566b" font-size="8" font-family="ui-monospace, monospace" letter-spacing="0.14em">LEGEND</text>
+
+      <rect x="40" y="676" width="14" height="10" rx="2" fill="#efeeff" stroke="#5b5bf0" stroke-width="1"/>
+      <text x="60" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">Focal router</text>
+
+      <rect x="168" y="676" width="14" height="10" rx="2" fill="#ffffff" stroke="#1e1f29" stroke-width="1"/>
+      <text x="188" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">Library handler</text>
+
+      <rect x="316" y="676" width="14" height="10" rx="2" fill="rgba(91,91,240,0.05)" stroke="rgba(91,91,240,0.50)" stroke-width="1" stroke-dasharray="3,2"/>
+      <text x="336" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">Security control</text>
+
+      <rect x="468" y="676" width="14" height="10" rx="2" fill="rgba(30,31,41,0.05)" stroke="#55566b" stroke-width="1"/>
+      <text x="488" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">Store / registry</text>
+
+      <rect x="620" y="676" width="14" height="10" rx="2" fill="rgba(30,31,41,0.03)" stroke="rgba(30,31,41,0.30)" stroke-width="1"/>
+      <text x="640" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">Edge host</text>
+
+      <rect x="732" y="676" width="14" height="10" rx="2" fill="rgba(85,86,107,0.10)" stroke="#8d8ea3" stroke-width="1"/>
+      <text x="752" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">External / port</text>
+
+      <line x1="880" y1="680" x2="908" y2="680" stroke="#5b5bf0" stroke-width="1.4" marker-end="url(#arrow-accent)"/>
+      <text x="916" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">Primary</text>
+
+      <line x1="1000" y1="680" x2="1028" y2="680" stroke="#4545c8" stroke-width="1.2" marker-end="url(#arrow-link)"/>
+      <text x="1036" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">HTTP / mint</text>
+
+      <line x1="1140" y1="680" x2="1168" y2="680" stroke="#55566b" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#arrow)"/>
+      <text x="1176" y="684" fill="#55566b" font-size="8" font-family="'Noto Sans Hebrew', sans-serif">Optional</text>
+    </svg>
+  </div>
+</body>
+</html>

package/docs/guide.md

@@ -181,7 +181,8 @@ Also mount `.well-known/*` and `/mcp/oauth/*` the same way (or route everything
 
 Express, Cloud Functions, Cloud Run, `http.createServer` — bridge with
 `asNodeHandler`. Runnable recipe: [`examples/http-server.ts`](../examples/http-server.ts)
-(`npx tsx examples/http-server.ts`).
+(set `OAUTH_CODE_SECRET` and `ACCESS_TOKEN_SECRET`, e.g. from `openssl rand -base64 32`,
+then `npx tsx examples/http-server.ts`).
 
 ## Ports — what you implement
 
@@ -196,13 +197,13 @@ The library stays protocol-shaped. Your app plugs in the seams:
 | `verifyToken(token, req)` | Decode a bearer and return `{ userId, scopes, audience, claims? }`, or `null`. **The library compares `audience` against this server's canonical resource** — you cannot forget the check. Optional `claims` are passed to `context` on `principal` |
 | `resolveUser`, `loginUrl`, `mintAccessToken`, `codeSecret` | Same as the OAuth ports below |
 | `clientStore?` | Pre-registered clients; required for confidential clients like Gemini |
-| `refreshAccessToken?` | If set, metadata advertises `refresh_token` |
+| `refreshAccessToken?` | If set, metadata advertises `refresh_token`. Receives `resource` and optional reduced `scope` — **MUST reject tokens not originally issued for that resource, and any `scope` outside the originally granted set** (see [security.md](security.md)) |
 | `revokeToken?` | RFC 7009; presence mounts `/revoke` and advertises `revocation_endpoint` |
 
 `consent?` (approval-page policy — see [Consent](#consent), below) and
 `defaultScopes?` sit as top-level `McpAppOptions`, not under `auth` — they
 are policy, not credentials, the same reasoning as `allowLoopback`.
-| `context?`, `audit?` | Same as the MCP ports below; `context` defaults to an empty object. Receives `principal.claims` when `verifyToken` set them |
+| `context?`, `audit?` | `context` defaults to `{}`. Top-level `audit` is a **unified** sink for MCP and OAuth (`entry.source` is `"mcp"` or `"oauth"`). `auth.audit` overrides OAuth delivery when both are set |
 
 ### MCP (`createMcpHandler`)
 
@@ -213,7 +214,7 @@ The lower-level handler. Here the audience check is **yours** — prefer
 |------|------|
 | `authenticate(req, method, tool?)` | Return `{ id, scopes, claims? }`, or `null` → 401 + `WWW-Authenticate`. **Must reject tokens whose audience is not this server's canonical resource** |
 | `context(req, principal)` | Build per-request ctx for tools (DB, env, …). Use `principal?.claims` for tenant / plan / role without re-decoding the bearer |
-| `audit?(entry)` | Opt-in **metrics hook**: pass any function to receive tool results **and** auth denials (bad token, missing scope, query-string token), plus the 500 path when a host port throws. `entry.method` is `""` for transport-level denials made before parsing. Protocol errors (malformed JSON, bad `jsonrpc`, unsupported protocol version, oversized body, batch) are **not** audited. Throwing from this port never fails the request, and neither does hanging — see `auditTimeoutMs` below. Omit it and the library stays silent |
+| `audit?(entry)` | Opt-in **metrics hook**: pass any function to receive tool results **and** auth denials (bad token, missing scope, query-string token, rejected browser Origin), plus the 500 path when a host port throws. `entry.method` is `""` for transport-level denials made before parsing (`query_string_token`, `unauthorized`, `origin_not_allowed`). Protocol errors (malformed JSON, bad `jsonrpc`, unsupported protocol version, oversized body, batch) are **not** audited. Throwing from this port never fails the request, and neither does hanging — see `auditTimeoutMs` below. Omit it and the library stays silent |
 
 `auditTimeoutMs` (default 1000ms) races `audit` against a timeout, so a
 slow sink can't stall a response past that bound either.
@@ -233,14 +234,14 @@ createMcpApp({ /* … */, audit: consoleAudit });
 createMcpApp({
   /* … */,
   audit: (entry) => {
-    // entry: { method, tool?, principalId?, ok, error?, durationMs }
+    // entry.source === "mcp" | "oauth"
     void metrics.record(entry);
   },
 });
 ```
 
-Failures (denials and tool exceptions) go to `console.error` when using
-`consoleAudit`; everything else to `console.log`. Entries never carry raw
+Failures (MCP denials and tool exceptions) go to `console.error` when using
+`consoleAudit`; MCP successes and OAuth events go to `console.log`. Entries never carry raw
 exceptions or stack traces, so console output is safe. For anything beyond
 stdout, write your own `audit` function — that is the intended production path.
 
@@ -248,15 +249,21 @@ stdout, write your own `audit` function — that is the intended production path
 
 By default `initialize`, `ping`, and notifications are public. Override `publicMethods` if every method must require Bearer.
 
+**Browser `Origin`.** MCP Streamable HTTP expects servers to validate the
+request `Origin` header. Pass `allowedRequestOrigins` on `createMcpHandler` /
+`createMcpApp`. Native connectors omit the header and are admitted. An omitted
+allowlist **rejects** any present `Origin` (use `["*"]` only if you mean it).
+This is separate from Node Host `allowedOrigins` on `asNodeHandler`.
+
 ### OAuth (`createOAuthRouter`)
 
 | Port | Role |
 |------|------|
-| `codeSecret` | HMAC secret for signed auth codes (string or `(req) => string`) |
+| `codeSecret` | Secret(s) sealing auth codes, consent tickets, and DCR client assertions, and keying `secretHash` (string, `string[]`, or `(req) => string \| string[]`). A single string works as before; pass an array to rotate keys — see [security.md](security.md#rotating-codesecret) |
 | `resolveUser` | Consenting user, or `null` → redirect to `loginUrl` |
 | `loginUrl` | Where unauthenticated authorize requests go |
 | `mintAccessToken` | Issue a **user-bound**, **audience-bound** access token (`resource` is the RFC 8707 URI) — never a shared god token |
-| `refreshAccessToken?` | If set, metadata advertises `refresh_token`; also receives `resource` |
+| `refreshAccessToken?` | If set, metadata advertises `refresh_token`; receives `resource` and optional client `scope` (advertised-scope check is library-side). **MUST reject refresh tokens not originally issued for that `resource`, and any `scope` outside the originally granted set** — opaque RT, same pattern as audience |
 | `revokeToken?` | If set, mounts `/revoke` and advertises `revocation_endpoint`. Well-formed authenticated revoke → 200 even if the token is unknown; `invalid_request` 400 and `invalid_client` 401 still apply |
 | `codeStore?` | Shared single-use jti store for multi-instance (`consume(jti, expMs)`); pruning in-memory default otherwise. Also backs consent-ticket single-use — see below |
 | `clientStore?` | Pre-registered clients: `get(clientId)` returns registered redirect URIs and auth method. Two ways to authenticate a confidential client's secret — **prefer `secretHash(clientId)`**: return a stored hash from `hashClientSecret`, and the library compares it with the same constant-time primitive it uses everywhere else; `verifySecret(clientId, presented)` is the fallback when you'd rather compare yourself. Credentials never enter the library either way |
@@ -315,17 +322,25 @@ createToolRegistry(tools, { validateArgs: false }) // default: off, easy adoptio
 ```
 
 - Handler may return a `string` or `{ content, isError? }`
-- Unknown tools and thrown errors become `isError: true` (not transport errors)
+- A thrown handler exception becomes `isError: true` (not a transport error)
+- `registry.call(name, ...)` itself returns `isError: true` for an unknown
+  `name` too — but the JSON-RPC `tools/call` dispatch (`createMcpHandler` /
+  `createMcpApp`) checks the name against the registry *before* calling it,
+  and answers an unrecognized one with a protocol-level `-32602` error
+  instead: MCP distinguishes "this request doesn't refer to a real tool"
+  from a tool's own execution outcome. The registry's `isError: true`
+  fallback only surfaces to a caller that invokes `registry.call` directly,
+  outside that dispatch.
 - Thrown exceptions are **redacted** by default (`"Tool execution failed"`); pass `onToolError` to map them. An `onToolError` that itself throws or returns a non-string falls back to the redacted default
 - Duplicate tool names throw at registry construction
 - Turn `validateArgs: true` once clients send schema-valid args. The evaluated
   subset is `type`, `enum`, `required`, `properties`, `items`, `minimum`,
-  `maximum`. Pure metadata (`description`, `title`, `$schema`, `$id`,
+  `maximum`, and boolean `additionalProperties`. Pure metadata (`description`, `title`, `$schema`, `$id`,
   `$comment`, `default`, `examples`, `deprecated`, `readOnly`, `writeOnly`,
   `format`) is allowed and never evaluated. Any other keyword is not
   evaluated — and with `validateArgs: true` `createToolRegistry` throws at
-  construction so a schema like `pattern` or `additionalProperties` cannot
-  silently look enforced
+  construction so a schema like `pattern` or a schema-valued
+  `additionalProperties` cannot silently look enforced
 
 ### Wrapping an API as a tool
 
@@ -370,6 +385,15 @@ const getWeather = apiTool({
   echoes back). Pass `onError(res)` to shape it yourself, e.g. include a
   redacted version of the body. `fetch` is overridable — testing, request
   signing, a custom agent.
+- **`timeoutMs`** (default `30000`) aborts the upstream call past that many
+  ms — an upstream that never responds otherwise hangs the tool call (and
+  the MCP request behind it) indefinitely. Pass `false` to disable; a
+  timeout firing surfaces as `isError: true` with a clear message, not a
+  thrown exception `onToolError` would redact.
+- **`maxResponseBytes`** (default 1 MiB) caps the upstream response body
+  before `respond`/`onError` ever see it — the same memory-exhaustion shape
+  an unbounded *incoming* request body is. Exceeding it also surfaces as
+  `isError: true`, not a thrown exception.
 - `defineTool` alone (without `request`/`respond`) is just the typed-args
   layer over a regular `ToolDef` — use it for anything, not only REST calls.