mcp-trellis 0.2.1 → 2.1.0

package/docs/guide.md

@@ -0,0 +1,441 @@
+# Guide
+
+Practical deep dive: architecture, host recipes, ports, tools, and multi-tenant
+connectors. For a working minimal server, start from the [README](../README.md).
+API tables and exports live in [reference.md](reference.md). Security guarantees
+and threat model: [security.md](security.md).
+
+[Architecture](#how-it-fits-together) · [Clients](#clients) · [Recipes](#recipes) ·
+[Compose the primitives](#advanced-compose-the-primitives) ·
+[Ports](#ports--what-you-implement) · [Consent](#consent) ·
+[Tool registry](#tool-registry) · [Multi-tenant](#multi-tenant-saas-connectors)
+
+## How it fits together
+
+What `createMcpApp` wires for you — two pieces, one deciding which requests go
+to the other:
+
+![Architecture: connector → edge → OAuth or MCP → your ports](diagrams/architecture.svg)
+
+Typical first-connection path:
+
+![Sequence: OAuth authorize and token, then MCP tool call](diagrams/first-connection.svg)
+
+You only touch this routing directly if you skip `createMcpApp` — see
+[Advanced: compose the primitives](#advanced-compose-the-primitives).
+
+## Clients
+
+Name the connector clients you serve; the AS is configured to match.
+
+| Client | Registration | Token endpoint auth | Notes |
+|--------|--------------|---------------------|-------|
+| `claude` | Dynamic (DCR), public + PKCE | `none` | Claude Custom Connectors callback is allowlisted for you |
+| `gemini` | **Pre-registered**, confidential | `client_secret_basic`, `client_secret_post` | Gemini Enterprise is registered with your org's IdP — supply `auth.clientStore` |
+| `codex` | OAuth 2.1 per MCP auth spec, public + PKCE | `none` | ChatGPT / Codex share one connector contract |
+
+```ts
+createMcpApp({
+  clients: ["claude", "gemini"],
+  auth: {
+    // …
+    clientStore: {
+      get: async (clientId) => lookupClient(clientId),
+      verifySecret: async (clientId, presented) =>
+        checkSecret(clientId, presented),
+    },
+  },
+});
+```
+
+Naming a pre-registered client without a `clientStore` throws at construction
+rather than failing at the first token exchange. Secret storage and comparison
+stay in your `clientStore` — the library never sees or persists credentials.
+
+Naming only pre-registered clients (`clients: ["gemini"]`, no `claude` /
+`codex`) sets `allowUnregisteredClients: false`: `/register` is unmounted
+and dropped from AS metadata, unknown ids are rejected with
+`unauthorized_client` at `authorize` and `invalid_client` at `token` and
+`revoke`. Naming `claude` or `codex` alongside `gemini` reopens dynamic
+registration.
+
+## Recipes
+
+### Cloudflare Worker, Next.js, Deno, Bun
+
+`createMcpApp` returns a plain `fetch`, so the same object mounts everywhere:
+
+```ts
+// Worker
+export default { fetch: (req: Request, env: Env) => buildApp(env).fetch(req) };
+
+// Next.js App Router — app/[[...mcp]]/route.ts
+export const GET = (req: Request) => app.fetch(req);
+export const POST = (req: Request) => app.fetch(req);
+export const OPTIONS = (req: Request) => app.fetch(req);
+
+// Node / Express / Cloud Run
+import { asNodeHandler } from "mcp-trellis/node";
+export const mcp = asNodeHandler(app, { origin: process.env.MCP_PUBLIC_ORIGIN! });
+```
+
+The Node bridge reads the request stream when `req.body` is absent, so raw
+`http.createServer` works without a body-parser. Runnable recipe:
+[`examples/http-server.ts`](../examples/http-server.ts).
+
+## Advanced: compose the primitives
+
+Skip `createMcpApp` when you want to own the routing. Same behavior, more wiring:
+
+```ts
+import { createMcpHandler, createToolRegistry, parseBearer } from "mcp-trellis";
+import { createOAuthRouter } from "mcp-trellis/oauth";
+
+type Ctx = { userId: string };
+type Env = { OAUTH_CODE_SECRET: string };
+
+const registry = createToolRegistry<Ctx>([
+  {
+    name: "ping_db",
+    description: "Health check",
+    inputSchema: { type: "object", properties: {} },
+    scope: "read",
+    handler: async () => "ok",
+  },
+]);
+
+const handler = createMcpHandler<Ctx>({
+  registry,
+  serverInfo: { name: "my-app", version: "1.0.0" },
+  instructions: "Tools available to authenticated clients.",
+  wwwAuthenticate: (req) => ({
+    realm: "my-app",
+    resourceMetadataUrl: `${new URL(req.url).origin}/.well-known/oauth-protected-resource/mcp`,
+  }),
+  ports: {
+    authenticate: async (req) => {
+      const token = parseBearer(req.headers.get("authorization"));
+      if (!token) return null;
+      // Reject tokens whose aud ≠ this server's canonical resource.
+      return { id: "user-1", scopes: ["read"] };
+    },
+    context: async (_req, principal) => ({
+      userId: principal?.id ?? "",
+    }),
+  },
+});
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const oauth = createOAuthRouter({
+      ports: {
+        codeSecret: env.OAUTH_CODE_SECRET,
+        resolveUser: async () => ({ id: "user-1" }),
+        loginUrl: (req, next) =>
+          `${new URL(req.url).origin}/login?next=${encodeURIComponent(next)}`,
+        mintAccessToken: async ({ userId, resource }) => ({
+          // Embed `resource` as the token audience (RFC 8707).
+          accessToken: await issueUserToken(userId, { aud: resource }),
+          expiresIn: 3600,
+          scope: "mcp",
+        }),
+      },
+    });
+
+    const oauthResponse = await oauth.tryHandle(request);
+    if (oauthResponse) return oauthResponse;
+    if (new URL(request.url).pathname === "/mcp") return handler.fetch(request);
+    return new Response("Not found", { status: 404 });
+  },
+};
+```
+
+### Next.js App Router
+
+Delegate Web `Request` straight through — same handler as above:
+
+```ts
+// app/mcp/route.ts
+import { handler, oauth } from "@/lib/mcp"; // your shared setup
+
+export async function GET(req: Request) {
+  const oauthResponse = await oauth.tryHandle(req);
+  if (oauthResponse) return oauthResponse;
+  return handler.fetch(req);
+}
+
+export async function POST(req: Request) {
+  const oauthResponse = await oauth.tryHandle(req);
+  if (oauthResponse) return oauthResponse;
+  return handler.fetch(req);
+}
+
+export async function OPTIONS() {
+  return handler.fetch(new Request("https://local/mcp", { method: "OPTIONS" }));
+}
+```
+
+Also mount `.well-known/*` and `/mcp/oauth/*` the same way (or route everything through one catch-all that calls `oauth.tryHandle` first).
+
+### Node HTTP `(req, res)`
+
+Express, Cloud Functions, Cloud Run, `http.createServer` — bridge with
+`asNodeHandler`. Runnable recipe: [`examples/http-server.ts`](../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
+
+The library stays protocol-shaped. Your app plugs in the seams:
+
+![Ports: library calls into your authenticate, context, resolveUser, mintAccessToken](diagrams/ports.svg)
+
+### App (`createMcpApp`)
+
+| Port | Role |
+|------|------|
+| `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`. 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?` | `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`)
+
+The lower-level handler. Here the audience check is **yours** — prefer
+`createMcpApp` unless you need the control. See [security.md](security.md).
+
+| Port | Role |
+|------|------|
+| `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, 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.
+
+Pass any function to get per-request metrics — do what you want with them
+(DB, APM, admin UI). The library never writes to stdout or a store on its
+own. `consoleAudit` is only a convenience for local / small deploys;
+[`examples/audit-store.ts`](../examples/audit-store.ts) shows a ring buffer and
+a DB-shaped sketch:
+
+```ts
+import { createMcpApp, consoleAudit } from "mcp-trellis";
+
+createMcpApp({ /* … */, audit: consoleAudit });
+
+// Or your own sink:
+createMcpApp({
+  /* … */,
+  audit: (entry) => {
+    // entry.source === "mcp" | "oauth"
+    void metrics.record(entry);
+  },
+});
+```
+
+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.
+
+`wwwAuthenticate` can be a static object or `(req) => …` when the PRM URL depends on origin.
+
+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` | 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`; 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 |
+| `audit?` | Opt-in **OAuth-side metrics hook** — mirrors the MCP-side one above. `/token`/`/revoke` collapse every client-auth failure to one generic `invalid_client` (an enumeration-oracle fix — see [security.md](security.md)), and a rejected `codeSecret` surfaces to the caller only as `server_error`. This is where you get the real reason back (`entry.reason`) without handing it to an unauthenticated caller. Throwing never fails the request |
+
+```ts
+import { hashClientSecret } from "mcp-trellis/oauth";
+
+// Once, when you provision a confidential client (e.g. Gemini Enterprise):
+const stored = await hashClientSecret(theSecretYouGenerated, codeSecretValue);
+// Save `stored` — never the plaintext secret — and return it from
+// clientStore.secretHash(clientId) at verify time.
+```
+
+Auth codes carry `userId`, `resource`, and the granted `scope`. Clients **must** send `resource` on authorize and token (MCP MUST) — omitting it is a **breaking** requirement vs earlier 0.1.x drafts that ignored the parameter. Advertised grants come only from the handlers you configure. AS metadata sets `resource_parameter_supported: true`.
+
+**Scope is negotiated:** `authorize` validates the requested `scope` against `scopes` (default `["mcp"]`) and rejects anything outside it with `invalid_scope`. An omitted `scope` grants `defaultScopes` — which defaults to the full advertised set **only when `scopes` has a single entry**. Once `scopes` names more than one, `createOAuthRouter` throws at construction unless you set `defaultScopes` explicitly: silently granting everything advertised to a client that asked for nothing is exactly the escalation least-privilege scoping exists to prevent. The auth code carries the grant, and `mintAccessToken` receives it — so `ToolDef.scope` and `principal.scopes` sit on a chain that actually reaches the OAuth layer.
+
+**Client authentication:** unknown `client_id`s are public (PKCE only) unless `allowUnregisteredClients` is `false` — then DCR is unmounted, dropped from metadata, and unrecognized ids are rejected (`unauthorized_client` at authorize, `invalid_client` at token and revoke). `createMcpApp` derives the flag from `clients` via `hasDynamicClient`. Separately, `requireRegisteredClients` (default **true** since 1.0) keeps DCR mounted but rejects any `client_id` that isn't `clientStore`-resolved or a sealed id this server itself issued via `/register` — see [security.md](security.md). Set `requireRegisteredClients: false` only when you intentionally accept invented public ids.
+
+### Consent
+
+`/authorize` never issues a code directly, even for a resolved session — it
+renders an approval interstitial and only issues the code once the user
+POSTs an explicit approval to `/consent`. This closes a cross-site flow
+where an attacker's page could otherwise walk a logged-in visitor through
+`/authorize` with an attacker-chosen `client_id` and a loopback
+`redirect_uri`, then catch the code on a local listener; PKCE alone does
+not stop this, because it proves possession of the verifier, not the
+identity of a legitimate client.
+
+| Option (`consent`) | Default | Role |
+|---|---|---|
+| `render?(input)` | built-in interstitial | Render your own approval page — return any `Response`, or redirect to a route you own. `input.ticket` is the opaque value your form must echo back as `consent_ticket` |
+| `preApprovedClientIds?` | `[]` | Skip the screen for these ids — **only** when `clientStore` actually resolves the id. A DCR or self-invented id is never trusted to pre-approve itself, no matter what's in this list |
+
+The built-in interstitial ships `Content-Security-Policy`,
+`X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, and HTML-escapes
+every reflected value (`client_id` and `redirect_uri` are attacker-
+controlled input up to this point). If you supply `render`, you own that
+hardening for your own markup.
+
+Approval tickets are sealed (AES-GCM, single-use via the same store as
+auth-code replay protection, 5-minute TTL) and re-checked against the
+resolved user at redemption — approving as one user and redeeming as
+another is rejected, and a ticket can never be presented at `/token` as an
+authorization code, or vice versa.
+
+## Tool registry
+
+Schema and handler live in one place — no parallel "defs" and "handlers" lists to keep in sync:
+
+```ts
+createToolRegistry(tools, { validateArgs: false }) // default: off, easy adoption
+// onToolError?: (exc) => string — default redacts to "Tool execution failed"
+```
+
+- Handler may return a `string` or `{ content, isError? }`
+- 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`, 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 a schema-valued
+  `additionalProperties` cannot silently look enforced
+
+### Wrapping an API as a tool
+
+`ToolDef` stays the primitive. `defineTool` and `apiTool` are optional sugar for
+the common case — turning "I have an API" into "I have an MCP tool" without
+hand-rolling arg validation or fetch/error plumbing each time:
+
+```ts
+import { apiTool } from "mcp-trellis";
+
+const getWeather = apiTool({
+  name: "get_weather",
+  description: "Current weather for a city",
+  inputSchema: {
+    type: "object",
+    properties: { city: { type: "string" } },
+    required: ["city"],
+  },
+  // any Standard Schema v1 validator (https://standardschema.dev)
+  input: citySchema,
+  request: (_ctx, { city }) =>
+    `https://api.example.com/weather?city=${encodeURIComponent(city)}`,
+  respond: async (res) => {
+    const data = await res.json();
+    return `${data.tempC}°C, ${data.condition}`;
+  },
+});
+```
+
+- **`inputSchema` stays required** — it's what `tools/list` actually advertises to
+  clients, and there's no library-agnostic way to derive JSON Schema from an
+  arbitrary Standard Schema validator. Keep the two in sync.
+- **`input`** (optional) parses and types `args` before your handler runs — any
+  [Standard Schema](https://standardschema.dev)-compliant validator works,
+  nothing library-specific. A validation failure returns `isError: true` with
+  the issues and never calls your handler.
+- **`apiTool`** builds on `defineTool`: give it `request` (build the outgoing
+  call from typed args) and optionally `respond` (shape a 2xx response;
+  default is the body as text). Non-2xx becomes `isError: true` automatically
+  — **status only by default, the upstream body is never forwarded** (it
+  could contain internal detail, tokens, or SQL an upstream error page
+  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.
+
+## Multi-tenant (SaaS connectors)
+
+Resource-per-tenant already works with **zero library change**.
+`canonicalResource(origin, resourcePath)` is derived per request, and the
+audience check in `createMcpApp` rejects a token minted for another origin
+before any tool runs. Deploy `acme.mcp.example.com` and
+`globex.mcp.example.com` as separate Hosts and cross-tenant token reuse is a
+protocol failure, not an application bug.
+
+For the in-tool half, derive the tenant from the request Host (or from the
+verified audience after the library check) in your `context` port — that is
+the isolation key. Optional `claims` from `verifyToken` (plan, role, …) are
+handy metadata on `principal`; they are **not** Host→tenant authorization.
+A forged `claims.tenant_id` with a matching audience must not change which
+tenant's data a tool can see.
+
+**Host caveat (API requirement).** On Node, multi-tenant needs a Host-derived
+origin (`trustProxy: true` without a fixed `origin`). That path **requires**
+a non-empty `allowedOrigins` at `asNodeHandler` construction — omit it and
+construction throws. Use exact origins and/or `*.example.com` wildcards for
+**https** subdomains; the **resolved** origin must match or the request
+returns **400** before any OAuth or MCP handling. Loud opt-out:
+`allowedOrigins: ["*"]` (admits any Host — only behind a proxy you trust to
+strip client `X-Forwarded-*`). A fixed `origin` absent from a non-empty list
+fails at construction; with a fixed `origin` the allowlist is optional
+defense-in-depth. Absolute-form request targets are rebased onto that
+validated origin, so a spoofed URL line cannot override it. A fixed `origin`
+is otherwise safe but collapses every tenant onto one resource, so it cannot
+do subdomain-per-tenant.
+
+On Cloudflare Workers (or any wildcard route), apply the equivalent
+allowlist check on `new URL(req.url).origin` before calling `app.fetch`
+(`isAllowedOrigin` from `mcp-trellis/node`, or the same module the Worker
+example imports).
+
+Typechecked sketch: [`examples/multi-tenant.ts`](../examples/multi-tenant.ts)
+(needs a Host matching `*.mcp.example.com` — loopback alone is rejected).
+Shared `codeStore` / revocation shapes: [`examples/stores.ts`](../examples/stores.ts)
+(atomic `setIfAbsent` for auth codes; Workers KV alone is not enough).
+`audit` metrics sink (ring + DB sketch): [`examples/audit-store.ts`](../examples/audit-store.ts).
+Worker mount: [`examples/cloudflare-worker.ts`](../examples/cloudflare-worker.ts)
+(typecheck-only in CI — no wrangler).

package/docs/reference.md

@@ -0,0 +1,210 @@
+# Reference
+
+Package surface, routes, MCP methods, status codes, options, and exports.
+Ports and recipes: [guide.md](guide.md). Security: [security.md](security.md).
+
+## Package surface
+
+| Import | What you get |
+|--------|----------------|
+| `mcp-trellis` | `createMcpApp`, client profiles, MCP handler, tool registry, bearer helpers, JSON-RPC helpers |
+| `mcp-trellis/oauth` | OAuth 2.1 AS router, discovery metadata, resource and redirect policy, client-secret hashing |
+| `mcp-trellis/node` | `asNodeHandler` + `resolveOrigin` for Node `(req, res)` |
+| `mcp-trellis/advanced` | Low-level primitives: PKCE, auth codes, client auth, scope/resource parsing, schema validation, HTTP utils. Less stable — may change in a minor release |
+
+`createMcpApp` is the batteries-included layer. `createMcpHandler` and
+`createOAuthRouter` remain exported and unchanged — reach for them when you want
+to own the routing or mount the two halves separately. See
+[compose the primitives](guide.md#advanced-compose-the-primitives).
+
+## Default OAuth routes
+
+With defaults `resourcePath: "/mcp"` and `oauthPath: "/mcp/oauth"`:
+
+| Path | Purpose |
+|------|---------|
+| `/.well-known/oauth-protected-resource` (+ `/mcp`) | Protected resource metadata |
+| `/.well-known/oauth-authorization-server` (+ `/mcp`) | Authorization server metadata |
+| `/mcp/oauth/register` | Dynamic client registration (unmounted when DCR is off). `redirect_uris`, if supplied, must be an array of at most 10 entries — a malformed body, a non-object body, a non-array `redirect_uris`, or too many entries all return **400** `invalid_client_metadata` (RFC 7591 §3.2.2) rather than silently falling back to the default callback. `redirect_uris` omitted entirely still falls back as documented below |
+| `/mcp/oauth/authorize` | Authorization endpoint — GET only. Renders a consent interstitial rather than redirecting directly; see `/consent` below and [security.md](security.md). Once `redirect_uri` is validated, every remaining error redirects to it with `?error=…` (RFC 6749 §4.1.2.1) rather than returning JSON; an invalid `redirect_uri` itself, and an oversized `state`, are the two exceptions and stay direct 400s |
+| `/mcp/oauth/consent` | POST only. Approves or denies a consent ticket issued by `/authorize` and, on approval, issues the code and redirects to `redirect_uri` |
+| `/mcp/oauth/token` | Token endpoint. JSON or form body |
+| `/mcp/oauth/revoke` | Token revocation (RFC 7009; mounted only when `revokeToken` is set). JSON or form body |
+
+## Supported MCP methods
+
+| Method | Auth | Notes |
+|--------|------|-------|
+| `initialize` | public | Negotiates protocol version; returns `capabilities.tools` |
+| `ping` | public | Empty result |
+| `tools/list` | Bearer | Lists registry entries |
+| `tools/call` | Bearer + scope | Runs the tool; no Bearer at all → 401, authenticated but missing scope → 403, `params.name` naming no registered tool → `-32602` (protocol error, not a tool result — see `docs/guide.md`) |
+| `notifications/*` | public | HTTP 202 empty body |
+
+Anything else → JSON-RPC `-32601`. Capabilities advertise **tools only**.
+
+## HTTP and JSON-RPC status codes
+
+| HTTP | When |
+|------|------|
+| **202** | Notification (empty body) |
+| **400** | Parse error, batch array, invalid request, `jsonrpc` not `"2.0"`, unsupported `MCP-Protocol-Version` |
+| **401** | Missing/invalid Bearer; includes `WWW-Authenticate`; echoes the real request id, not `null` |
+| **403** | Authenticated, but the token's scopes don't include the tool's `scope`; `WWW-Authenticate` carries `error="insufficient_scope"` and `scope="<required>"` (RFC 6750 §3.1) |
+| **405** | Wrong HTTP verb on MCP |
+| **413** | Request body over the cap — `/mcp` (1 MiB default), `/token`/`/revoke`/`/register` (64 KiB default) |
+
+| JSON-RPC code | Constant |
+|---------------|----------|
+| `-32700` | `JSONRPC_PARSE_ERROR` |
+| `-32600` | `JSONRPC_INVALID_REQUEST` (batches) |
+| `-32601` | `JSONRPC_METHOD_NOT_FOUND` |
+| `-32602` | `JSONRPC_INVALID_PARAMS` (unrecognized `tools/call` `params.name`) |
+| `-32603` | `JSONRPC_INTERNAL_ERROR` |
+| `-32001` | `JSONRPC_UNAUTHORIZED` |
+
+## `createMcpHandler` options
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `registry` | yes | From `createToolRegistry` |
+| `ports` | yes | `authenticate`, `context`, optional `audit` — see [Ports](guide.md#ports--what-you-implement) |
+| `serverInfo` | yes | `{ name, version }` |
+| `wwwAuthenticate` | yes | Static or `(req) => …` for RFC 9728 PRM URL |
+| `instructions` | no | Returned on `initialize` |
+| `publicMethods` | no | Default: `initialize`, `ping`, notifications |
+| `auditTimeoutMs` | no | Max time to wait for `ports.audit` before responding anyway. Default 1000ms — see [security.md](security.md) |
+| `allowedRequestOrigins` | no | Browser `Origin` allowlist. Omitted → reject any present `Origin`; no header → allow; `"*"` opts out. Distinct from Node Host `allowedOrigins` |
+
+`ports.audit` fires on tool results and on auth denials (bad token, missing
+scope, query-string token, rejected browser Origin as `origin_not_allowed`),
+plus the 500 path when a host port throws.
+Malformed JSON, bad `jsonrpc`, unsupported `MCP-Protocol-Version`, oversized
+bodies, and batch requests return JSON-RPC client errors without an audit
+entry — those are protocol errors, not auth denials.
+
+## `createOAuthRouter` options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `ports` | — | Required OAuth ports — see [Ports](guide.md#ports--what-you-implement) |
+| `resourcePath` | `"/mcp"` | MCP resource path in PRM. Normalized once at construction (a trailing slash is stripped); construction throws if it starts with `/.well-known` or equals `oauthPath` |
+| `oauthPath` | `"/mcp/oauth"` | Prefix for authorize / token / register / revoke |
+| `realm` | — | Optional realm string |
+| `scopes` | `["mcp"]` | Advertised in metadata, and the ceiling `authorize` validates against |
+| `defaultScopes` | full `scopes` | Scopes granted when a client omits `scope` entirely. **Required at construction** once `scopes` has more than one entry — the router throws rather than silently granting everything advertised. Must be a subset of `scopes` |
+| `tokenEndpointAuthMethods` | `["none"]` | Advertised client auth methods |
+| `allowUnregisteredClients` | `true` | `false` requires `clientStore`, unmounts DCR, and rejects unknown `client_id`s (`unauthorized_client` / `invalid_client`) |
+| `requireRegisteredClients` | `true` | Reject any `client_id` that isn't `clientStore`-resolved or self-sealed via this server's own `/register` (see [security.md](security.md)). DCR stays mounted, unlike `allowUnregisteredClients: false` — a client just can't invent an id out of thin air. Enforced at `/authorize`, and at `/token`'s `refresh_token` grant and `/revoke` (the `authorization_code` grant's `client_id` is already bound into the sealed code at `/authorize` time, so it's covered indirectly there) |
+| `redirect` | see below | Redirect URI allowlist |
+| `consent` | see below | Consent/approval policy for `/authorize` |
+| `auditTimeoutMs` | `1000` | Max time to wait for `ports.audit` before responding anyway — same as MCP |
+
+**`redirect` (`RedirectAllowlistOptions`):**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `extra` | `[]` | Exact-match redirect URIs |
+| `allowLoopback` | `true` | Allow `http:` loopback — `127.0.0.1`, `[::1]` (any port). `localhost` and `https:` loopback are not accepted — see [security.md](security.md) |
+| `allowClaude` | `true` | Allow the Claude.ai Custom Connector callback |
+
+Pre-registered clients, and DCR-issued clients whose id was sealed by this
+server's own `/register`, bypass this allowlist entirely — they are
+validated against their own bound `redirectUris`.
+
+**`consent` (`ConsentOptions`):**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `render` | built-in interstitial | Render the approval page yourself — return any `Response`, including a redirect to your own route. Receives a `ConsentRequest` with the validated `clientId`, `redirectUri`, `scope`, `resource`, `user`, and an opaque `ticket` to embed in your form's `consent_ticket` field |
+| `preApprovedClientIds` | `[]` | Client ids that skip the interstitial and go straight to code issuance. Only honored when `clientStore` actually resolves the id — a DCR or self-invented id is never trusted to skip it |
+
+## `createMcpApp` options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `serverInfo`, `tools`, `auth` | — | Required |
+| `clients` | `["claude"]` | Connector profiles to serve |
+| `resourcePath` | `"/mcp"` | MCP endpoint path |
+| `oauthPath` | `` `${resourcePath}/oauth` `` | OAuth prefix |
+| `scopes` | `["mcp"]` | Scopes this server grants |
+| `defaultScopes` | full `scopes` | Same as `OAuthRouterOptions.defaultScopes` — required once `scopes` has more than one entry |
+| `realm` | `serverInfo.name` | `WWW-Authenticate` realm |
+| `extraRedirectUris` | `[]` | Callbacks beyond the client profiles |
+| `allowLoopback` | `true` | Allow loopback redirects — see the narrowed `http:`-only, no-`localhost` behavior in [security.md](security.md) |
+| `consent` | built-in interstitial | Same as `OAuthRouterOptions.consent` — override the approval page or pre-approve specific client ids |
+| `requireRegisteredClients` | `true` | Same as `OAuthRouterOptions.requireRegisteredClients` — inventing a public `client_id` is rejected unless it comes from `clientStore` or this server's own `/register` |
+| `instructions`, `validateArgs`, `onToolError`, `context`, `audit`, `auditTimeoutMs`, `allowedRequestOrigins` | — | Passed through to the MCP handler. Top-level `audit` is a unified MCP+OAuth sink (`source`); `auth.audit` overrides OAuth only. `auditTimeoutMs` applies to both |
+| `hideToolsOutsideScope` | `false` | Filter `tools/list` to tools the calling principal's scopes actually satisfy (an unscoped tool, or one with `scope: null`, is always listed). `tools/call` already enforces scope on its own (403 `insufficient_scope`) regardless of this setting — turning it on only changes what's discoverable via `tools/list` |
+
+**A tool's `scope` (`ToolDef.scope`):** required scope, `null` for "any authenticated
+principal, deliberately" or omitted for the same at runtime. On a server
+advertising more than one `scopes` entry, `createMcpApp` **refuses to
+construct** if any tool omits `scope` — an omission there means "any
+authenticated principal, including one holding none of the advertised
+scopes," which is rarely the intent once there's more than one scope to
+have gotten wrong. Pass `scope: null` to state the omission on purpose.
+A single-scope server has no such ambiguity and is unaffected.
+
+## Exports
+
+<details>
+<summary><code>mcp-trellis</code></summary>
+
+- `createMcpApp`, `createMcpHandler`, `createToolRegistry`
+- `consoleAudit` — convenience unified `audit` sink that logs to the console (pass any function for metrics / DB / APM)
+- `UnifiedAuditEntry` — `{ source: "mcp" } & AuditEntry` \| `{ source: "oauth" } & OAuthAuditEntry`
+- `defineTool`, `apiTool` — typed, validated tool authoring on top of `ToolDef`. `apiTool`'s `timeoutMs` (default 30000, or `false` to disable) and `maxResponseBytes` (default 1 MiB) bound the upstream call; either surfaces as `isError: true`, not a thrown exception
+- `CLIENT_PROFILES`, `DEFAULT_CLIENTS`, `authMethodsFor`, `redirectUrisFor`, `preRegisteredClients`, `hasDynamicClient`
+- `parseBearer`, `wwwAuthenticateHeader`, `rejectQueryToken`
+- `rpcResult`, `rpcError`, JSON-RPC error constants
+- `PROTOCOL_VERSIONS`, `DEFAULT_PROTOCOL_VERSION`
+- `jsonResponse({ data, status?, headers?, cors? })` — type `JsonResponseInput` exported
+- Types: `McpApp`, `McpAppOptions`, `McpAppAuth`, `VerifiedToken`, `ClientName`, `ClientProfile`, `McpHandler`, `McpHandlerOptions`, `McpPorts`, `Principal`, `AuditEntry`, `ServerInfo`, `ToolDef`, `ToolHandler`, `ToolResult`, `ToolRegistry`, `JsonSchema`, `StandardSchemaV1`, `DefineToolOptions`, `ApiToolOptions`, `ApiRequest`, `ClientStore`, `RegisteredClient`, `CodeStore`, `MintAccessTokenInput`, `RefreshAccessTokenInput`, `RevokeTokenInput`, `MintedToken`, `OAuthUser`, …
+
+</details>
+
+<details>
+<summary><code>mcp-trellis/oauth</code></summary>
+
+- `createOAuthRouter`
+- `authorizationServerMetadata`, `protectedResourceMetadata`, `mcpWwwAuthenticate`
+- `canonicalResource`, `resourcesEqual`, `DEFAULT_RESOURCE_PATH`
+- `isAllowedRedirectUri`, `CLAUDE_CALLBACK`
+- `isCimdClientId`, `resolveCimdClient`
+- `hashClientSecret`, `verifyClientSecret` — for `ClientStore.secretHash` (hash once at registration time; the library verifies)
+- `GRANT_TYPES`, `OAUTH_ERRORS`, `DEFAULT_SCOPE`, `TOKEN_ENDPOINT_AUTH_METHODS`
+- Types: `OAuthUser`, `MintedToken`, `OAuthPorts`, `OAuthAuditEntry`, `OAuthRouterOptions`, `OAuthErrorInfo`, `AuthCodeRecord`, `CodeStore`, `ClientStore`, `RegisteredClient`, `ClientAssertion`, `ClientAuth`, `TokenEndpointAuthMethod`, `MintAccessTokenInput`, `RefreshAccessTokenInput`, `RevokeTokenInput`, `ConsentOptions`, `ConsentRequest`
+
+</details>
+
+<details>
+<summary><code>mcp-trellis/advanced</code></summary>
+
+Building blocks for hosts assembling their own transport or OAuth flow. Less stable than the entries above.
+
+- `timingSafeEqual`, `matchesAny`
+- `validateAgainstSchema`, `JSON_SCHEMA_TYPES`, `SUPPORTED_SCHEMA_KEYWORDS`, `IGNORED_SCHEMA_KEYWORDS`, `unsupportedKeywords`, `missingObjectType`
+- `pickProtocolVersion`, `ASSUMED_HEADER_PROTOCOL_VERSION`
+- `emptyResponse`, `optionsResponse`, `corsHeaders`, `methodNotAllowed`
+- `issueAuthCode`, `consumeAuthCode` (pass `codeStore`; omitting it is deprecated), `newClientId`
+- `verifyPkceS256`, `sha256Base64Url`, `randomBase64Url`
+- `readClientAuth`, `firstClientAuthError`
+- `firstResourceError`, `resourceErrorInfo`, `normalizeConfiguredPath`
+- `parseScope`, `formatScope`, `requestedScopes`, `firstScopeError`, `scopeErrorInfo`
+- `advertisedScopes`, `defaultScopes`, `registeredClientsRequired`, `unregisteredClientsAllowed` — resolve the effective option value
+- `buildErrorRedirectUrl` — the RFC 6749 §4.1.2.1 error-redirect builder `/authorize` uses
+- Types: `AuthCodeRecord`, `CodeStore`, `ClientAuth`
+
+**Deprecated in 2.1:** every symbol above is still importable from `mcp-trellis` or `mcp-trellis/oauth`, where it used to live, as a `@deprecated` alias. Those aliases are removed in 3.0.
+
+</details>
+
+<details>
+<summary><code>mcp-trellis/node</code></summary>
+
+- `asNodeHandler`, `resolveOrigin`, `isAllowedOrigin`, `toWebRequest`, `sendWebResponse`, `readNodeBody`
+- Types: `NodeRequestLike`, `NodeResponseLike`, `ToWebRequestOptions`, `ResolveOriginOptions`, `AsNodeHandlerOptions`, `OriginAllowlistOptions`
+- `InvalidOriginError` — thrown by `resolveOrigin` for a Host/`X-Forwarded-*` header that can't safely become an origin (missing, carrying a path/query/fragment/credentials, malformed, or a non-`http(s)` scheme). `asNodeHandler` answers it with **400**, not the generic 500 it gives an actual unexpected failure
+
+</details>