mcp-trellis 0.2.1 → 1.0.0

package/README.md

@@ -9,27 +9,30 @@ Web-standard `Request` → `Response`. Same handler on Cloudflare Workers, Next.
 
 ## Why mcp-trellis
 
-Pick this when you want **the whole connector stack in one package** — the MCP
-handler *and* a real OAuth 2.1 authorization server — with no database to run
-and no vendor to sign up with:
+The whole connector stack in one package — MCP handler **and** OAuth 2.1 authorization server — with no database and no vendor signup. You own login, token minting, and storage; the library owns the protocol.
 
 | | mcp-trellis | Official MCP SDK | `workers-oauth-provider` | `@mcpauth/auth` | Auth0 / Clerk / Authlete |
 |---|---|---|---|---|---|
 | MCP handler | ✅ | ✅ | ❌ | ❌ | ❌ |
 | OAuth 2.1 authorization server | ✅ | ❌ bring your own | ✅ | ✅ | ✅ |
 | Runtime | any Web-standard | any Web-standard | Workers only | Node | — |
-| Database | none | — | KV (optional) | **required** — Prisma/Drizzle, with migrations | — |
+| Database | none | — | KV (optional) | **required** | — |
 | Runtime dependencies | **zero** | several | several | several | — |
 | Self-hosted | ✅ | ✅ | ✅ | ✅ | ❌ SaaS |
-| Named connector profiles (Claude / Gemini / Codex), enforced not just advertised | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Named connector profiles (Claude / Gemini / Codex), enforced | ✅ | ❌ | ❌ | ❌ | ❌ |
 
-Prefer the official SDK when you already have (or want) a separate
-authorization server — it doesn't ship one. Prefer `workers-oauth-provider`
-when you're committed to Workers and want Cloudflare's own implementation.
-Prefer a managed IdP (Auth0, Clerk, Authlete, WorkOS) when you'd rather pay
-than operate one. Prefer mcp-trellis when you want the protocol layer and the
-AS in one package, with **nothing to provision** — you still own login, token
-minting, and storage; the library owns the protocol.
+Prefer the official SDK when you already have a separate AS. Prefer
+`workers-oauth-provider` when you want Cloudflare's Workers-only
+implementation. Prefer a managed IdP when you'd rather pay than operate one.
+
+Named alternatives in the same problem space:
+
+- **`@mcpauth/auth` / `getmcpauth` / `mcp-auth`** — OAuth for MCP, typically
+  with a DB or a different runtime/stack assumption. mcp-trellis is the
+  **zero-dependency** option that ships the MCP handler **and** the OAuth 2.1
+  AS in one package.
+- **`fastmcp-oauth`** — OAuth helpers around FastMCP. mcp-trellis is host-agnostic
+  (`Request`/`Response`) and not tied to a particular MCP framework.
 
 ## Requirements
 
@@ -42,10 +45,9 @@ minting, and storage; the library owns the protocol.
 npm install mcp-trellis
 ```
 
-## 60-second server
+## Quick start
 
-One call mounts the MCP endpoint, the OAuth authorization server, and both
-discovery documents — and routes between them:
+One call mounts the MCP endpoint, the OAuth authorization server, and both discovery documents:
 
 ```ts
 import { createMcpApp } from "mcp-trellis";
@@ -90,9 +92,9 @@ const app = createMcpApp({
 export default { fetch: (req: Request) => app.fetch(req) };
 ```
 
-You return the token's `audience`; **the library rejects tokens minted for a
-different resource** before any tool runs. That check is the one preventing
-confused-deputy attacks, so it is not yours to remember.
+You return the token's `audience`; **the library rejects tokens minted for a different resource** before any tool runs. Details: [docs/security.md](docs/security.md).
+
+A real `/authorize` walk includes an approval step: a resolved session doesn't redirect straight back with a code, it renders a consent screen first (built in, or your own via `consent`). First-time integrators clicking through by hand should expect an HTML page there, not an immediate redirect — see [Consent](docs/guide.md#consent).
 
 Smoke-test with `initialize` (public — no Bearer needed):
 
@@ -102,562 +104,44 @@ curl -s http://127.0.0.1:8787/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'
 ```
 
-## Client compatibility
+```json
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"demo","version":"1.0.0"},"instructions":""}}
+```
 
-Name the connector clients you serve; the AS is configured to match.
+## Clients
 
 | 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),
-    },
-  },
-});
-```
+| `claude` | Dynamic (DCR), public + PKCE | `none` | Claude Custom Connectors callback allowlisted |
+| `gemini` | **Pre-registered**, confidential | `client_secret_basic`, `client_secret_post` | Supply `auth.clientStore` |
+| `codex` | OAuth 2.1 per MCP auth spec, public + PKCE | `none` | ChatGPT / Codex share one contract |
 
-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.
+Pre-registered clients, DCR enforcement, and `clientStore` wiring: [docs/guide.md#clients](docs/guide.md#clients).
 
-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.
+## Architecture
 
-## How it fits together
-
-What `createMcpApp` wires for you — two pieces, one deciding which requests go
-to the other:
+`createMcpApp` wires MCP and OAuth and routes between them:
 
 ![Architecture: connector → edge → OAuth or MCP → your ports](docs/diagrams/architecture.svg)
 
-Typical first-connection path:
-
 ![Sequence: OAuth authorize and token, then MCP tool call](docs/diagrams/first-connection.svg)
 
-You only touch this routing directly if you skip `createMcpApp` — see
-[Advanced: compose the primitives](#advanced-compose-the-primitives).
-
-## Package surface
-
-| Import | What you get |
-|--------|----------------|
-| `mcp-trellis` | `createMcpApp`, client profiles, MCP handler, tool registry, bearer helpers, HTTP utils |
-| `mcp-trellis/oauth` | OAuth 2.1 AS router, PKCE, auth codes, client auth, metadata |
-| `mcp-trellis/node` | `asNodeHandler` + `resolveOrigin` for Node `(req, res)` |
-
-`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.
-
-### 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) |
-| `/mcp/oauth/authorize` | Authorization endpoint |
-| `/mcp/oauth/token` | Token endpoint |
-| `/mcp/oauth/revoke` | Token revocation (RFC 7009; mounted only when `revokeToken` is set) |
-
-## 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:
+Host recipes, ports, tools, and multi-tenant: [docs/guide.md](docs/guide.md).
 
-```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)
-(`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](docs/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` |
-| `revokeToken?` | RFC 7009; presence mounts `/revoke` and advertises `revocation_endpoint` |
-| `context?`, `audit?` | Same as the MCP ports below; `context` defaults to an empty object. Receives `principal.claims` when `verifyToken` set them |
-
-### MCP (`createMcpHandler`)
-
-The lower-level handler. Here the audience check is **yours** — prefer
-`createMcpApp` unless you need the control.
-
-| 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** (see Threat model) |
-| `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** every denial (bad token, missing scope, query-string token). `entry.method` is `""` for transport-level denials made before parsing. Throwing from this port never fails the request. Omit it and the library stays silent |
-
-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: { method, tool?, principalId?, ok, error?, durationMs }
-    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
-exceptions or stack traces, so console output is safe. For anything beyond
-stdout, write your own `audit` function — that is the intended production path.
+## Docs
 
-`wwwAuthenticate` can be a static object or `(req) => …` when the PRM URL depends on origin.
+| Doc | Contents |
+|-----|----------|
+| [docs/guide.md](docs/guide.md) | Architecture, clients, recipes, ports, tools, multi-tenant |
+| [docs/reference.md](docs/reference.md) | Routes, methods, status codes, options, exports |
+| [docs/security.md](docs/security.md) | Protocol promises, threat model, not in scope |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | What's next |
 
-By default `initialize`, `ping`, and notifications are public. Override `publicMethods` if every method must require Bearer.
+Examples: [`examples/`](examples/) — HTTP server, Worker, multi-tenant, stores, audit.
 
-### OAuth (`createOAuthRouter`)
-
-| Port | Role |
-|------|------|
-| `codeSecret` | HMAC secret for signed auth codes (string or `(req) => string`) |
-| `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` |
-| `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 |
-| `clientStore?` | Pre-registered clients: `get(clientId)` returns registered redirect URIs and auth method; `verifySecret(clientId, presented)` authenticates confidential clients. Credentials never enter the library |
-
-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 the full advertised set. 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`.
-
-## 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? }`
-- Unknown tools and thrown errors become `isError: true` (not transport errors)
-- 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`,
-  `$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
-
-### 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}`;
-  },
-});
-```
+## Contributing
 
-- **`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.
-  `fetch` is overridable — testing, request signing, a custom agent.
-- `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).
-
-## Reference
-
-### 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; missing scope → 401 |
-| `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 |
-| **401** | Missing/invalid Bearer; includes `WWW-Authenticate` |
-| **405** | Wrong HTTP verb on MCP |
-
-| JSON-RPC code | Constant |
-|---------------|----------|
-| `-32700` | `JSONRPC_PARSE_ERROR` |
-| `-32600` | `JSONRPC_INVALID_REQUEST` (batches) |
-| `-32601` | `JSONRPC_METHOD_NOT_FOUND` |
-| `-32602` | `JSONRPC_INVALID_PARAMS` |
-| `-32603` | `JSONRPC_INTERNAL_ERROR` |
-| `-32001` | `JSONRPC_UNAUTHORIZED` |
-
-### `createMcpHandler` options
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `registry` | yes | From `createToolRegistry` |
-| `ports` | yes | `authenticate`, `context`, optional `audit` |
-| `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 |
-
-### `createOAuthRouter` options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `ports` | — | Required OAuth ports (see above) |
-| `resourcePath` | `"/mcp"` | MCP resource path in PRM |
-| `oauthPath` | `"/mcp/oauth"` | Prefix for authorize / token / register / revoke |
-| `realm` | — | Optional realm string |
-| `scopes` | `["mcp"]` | Advertised in metadata, and the ceiling `authorize` validates against |
-| `tokenEndpointAuthMethods` | `["none"]` | Advertised client auth methods |
-| `allowUnregisteredClients` | `true` | `false` requires `clientStore`, unmounts DCR, and rejects unknown `client_id`s (`unauthorized_client` / `invalid_client`) |
-| `redirect` | see below | Redirect URI allowlist |
-
-**`redirect` (`RedirectAllowlistOptions`):**
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `extra` | `[]` | Exact-match redirect URIs |
-| `allowLoopback` | `true` | Allow `http(s)` loopback — `127.0.0.1`, `[::1]`, `localhost` |
-| `allowClaude` | `true` | Allow the Claude.ai Custom Connector callback |
-
-Pre-registered clients bypass this allowlist entirely — they are validated
-against their own `redirectUris` from `clientStore`.
-
-### `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 |
-| `realm` | `serverInfo.name` | `WWW-Authenticate` realm |
-| `extraRedirectUris` | `[]` | Callbacks beyond the client profiles |
-| `allowLoopback` | `true` | Allow loopback redirects |
-| `instructions`, `validateArgs`, `onToolError`, `context`, `audit` | — | Passed through |
-
-### Exports
-
-<details>
-<summary><code>mcp-trellis</code></summary>
-
-- `createMcpApp`, `createMcpHandler`, `createToolRegistry`
-- `consoleAudit` — convenience `audit` sink that logs to the console (pass any function for metrics / DB / APM)
-- `defineTool`, `apiTool` — typed, validated tool authoring on top of `ToolDef`
-- `CLIENT_PROFILES`, `DEFAULT_CLIENTS`, `authMethodsFor`, `redirectUrisFor`, `preRegisteredClients`, `hasDynamicClient`
-- `parseBearer`, `timingSafeEqual`, `matchesAny`, `wwwAuthenticateHeader`, `rejectQueryToken`
-- `validateAgainstSchema`, `JSON_SCHEMA_TYPES`, `SUPPORTED_SCHEMA_KEYWORDS`, `IGNORED_SCHEMA_KEYWORDS`, `unsupportedKeywords`
-- `rpcResult`, `rpcError`, JSON-RPC error constants
-- `pickProtocolVersion`, `PROTOCOL_VERSIONS`, `DEFAULT_PROTOCOL_VERSION`
-- `jsonResponse`, `emptyResponse`, `optionsResponse`, `corsHeaders`, `methodNotAllowed`
-- 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`, `firstResourceError`, `DEFAULT_RESOURCE_PATH`
-- `isAllowedRedirectUri`, `CLAUDE_CALLBACK`
-- `issueAuthCode`, `consumeAuthCode`, `newClientId`
-- `verifyPkceS256`, `sha256Base64Url`, `randomBase64Url`
-- `readClientAuth`, `firstClientAuthError`, `unregisteredClientsAllowed`
-- `parseScope`, `formatScope`, `requestedScopes`, `firstScopeError`
-- `GRANT_TYPES`, `OAUTH_ERRORS`, `DEFAULT_SCOPE`, `TOKEN_ENDPOINT_AUTH_METHODS`
-- Types: `OAuthUser`, `MintedToken`, `OAuthPorts`, `OAuthRouterOptions`, `AuthCodeRecord`, `CodeStore`, `ClientStore`, `RegisteredClient`, `ClientAuth`, `TokenEndpointAuthMethod`, `MintAccessTokenInput`, `RefreshAccessTokenInput`, `RevokeTokenInput`
-
-</details>
-
-<details>
-<summary><code>mcp-trellis/node</code></summary>
-
-- `asNodeHandler`, `resolveOrigin`, `isAllowedOrigin`, `toWebRequest`, `sendWebResponse`, `readNodeBody`
-- Types: `NodeRequestLike`, `NodeResponseLike`, `ToWebRequestOptions`, `ResolveOriginOptions`, `AsNodeHandlerOptions`, `OriginAllowlistOptions`
-
-</details>
-
-## Protocol promises
-
-- Notifications → HTTP **202** with an empty body
-- Batch arrays → `-32600` (MCP 2025-06-18)
-- Protocol version negotiated from client `initialize` params
-- Query-string tokens rejected (`token` and RFC 6750 `access_token`)
-- `tools/call` checks `principal.scopes` (`*` = all), and the OAuth grant that produced them is validated at `authorize`
-- With `createMcpApp`, tokens whose audience is not this server's canonical resource are rejected by the library
-- **`fetch` never rejects.** If a host port you supply (`authenticate`, `context`, `resolveUser`, `mintAccessToken`, `clientStore`, …) throws, `createMcpHandler`, `createOAuthRouter`, and `createMcpApp` all catch it and return a real `500` (`-32603` for MCP, `server_error` for OAuth) instead of an unhandled rejection — whose shape and whether it even reaches the client varies by runtime. `asNodeHandler` catches independently too, since on raw `http.createServer` a rejection there leaves the socket open with no response ever sent.
-
-## Threat model (library)
-
-This is a **library** threat model, not a third-party audit badge.
-
-| Risk | Mitigation |
-|------|------------|
-| Confused deputy (token usable at the wrong MCP) | RFC 8707: `resource` required on authorize + token; bound into the auth code; must equal this AS’s canonical resource (`canonicalResource(origin, resourcePath)`). Passed into `mintAccessToken` / `refreshAccessToken` so you can embed `aud`. |
-| Refresh token replayed at another resource on the same AS | Library cannot inspect opaque refresh tokens — **`refreshAccessToken` MUST reject tokens not originally issued for the given `resource`** |
-| Audience not enforced at the RS | **`createMcpApp` enforces this** — `verifyToken` returns the token's `audience` and the library rejects any mismatch against `canonicalResource(origin, resourcePath)`. With bare `createMcpHandler`, the check is yours. |
-| Open redirect after login | Your login page must validate `next` is same-origin before redirecting |
-| Auth-code replay across instances | Pass a shared `codeStore`; in-memory jti map is process-local only |
-| Origin spoofing on Node | Pass explicit `origin`, or `trustProxy: true` only behind a proxy that strips client `X-Forwarded-*`. Host-derived origin **requires** non-empty `allowedOrigins` on `asNodeHandler` (`["*"]` to opt out loudly) |
-| Scope escalation at authorize | Requested `scope` is validated against the advertised `scopes` and rejected with `invalid_scope`; the grant is bound into the auth code and handed to `mintAccessToken` |
-| Stolen access or refresh token | Host `revokeToken` (denylist or equivalent) that `verifyToken` and `refreshAccessToken` consult. Unknown / wrong-client tokens MUST no-op, not throw. Well-formed authenticated revoke is 200 even if the token is unknown |
-| Stolen confidential-client secret | `clientStore.verifySecret` owns comparison — store hashes, not plaintext. The library never sees or persists credentials |
-| Registration-free DCR | `/register` returns a random `client_id` that is **never stored**; any unknown `client_id` works with an allowlisted `redirect_uri`. Defensible for public clients with PKCE — the model dynamic connectors (Claude, Codex) actually need. Pre-registered clients bypass this entirely, bound to their own `redirectUris` and auth method. CIMD replaces this model |
-| Naming only confidential clients doesn't actually block public ones | `clients: ["gemini"]` (or `allowUnregisteredClients: false`) is **enforced**: DCR unmounted, dropped from AS metadata, unresolved `client_id` rejected with `unauthorized_client` at `authorize` and `invalid_client` at `token` and `revoke` |
-| DCR / token-endpoint abuse | Edge or reverse-proxy rate limiting on `/register` and `/token`. The library does not rate-limit |
-
-**Also designed in:** PKCE S256 (timing-safe, length-capped); HMAC auth codes bind `userId`, `clientId`, `redirectUri`, challenge, and `resource`; redirect allowlist + DCR filter; no query-string tokens (`token` and `access_token`); honest `grant_types_supported`; `/token` and `/revoke` omit CORS `*`; audit fires on auth/scope denial as well as tool results.
-
-**Known limits:** in-memory jti map is process-local (multi-instance needs `codeStore`); loopback redirect allowlist permits any path/port on `localhost` / `127.0.0.1` (expected for native clients); DCR does not bind credentials to a stored client record until CIMD.
-
-## Not in scope
-
-Explicitly **out** of this package (do not expect parity with full MCP hosts or enterprise AS products):
-
-- **Tools only** — no `resources/*`, no `prompts/*`, and capabilities advertise tools alone
-- **No server-initiated messages** — Streamable HTTP is served as a single JSON response per POST (which the spec permits, and which Gemini Enterprise requires). No SSE response streams, so no `notifications/progress` and no long-running tool keepalive
-- **No sessions** — removed from the protocol in `2026-07-28` anyway
-- **No enterprise-managed auth** — no ID-JAG, no IdP product integration; you wire login + minting
-- **No embedded product surface** — no token store, sessions, or login UI
-- **No stdio** transport; no batch JSON-RPC arrays
-- **No DPoP, PAR, or `client_credentials`** — this AS is authorization_code (+ optional refresh and revoke)
-- **No rate limiting** — put quotas on `/register` and `/token` at the edge or reverse proxy
-- **No paid external security audit** claimed here — see Threat model above
-
-See [docs/ROADMAP.md](docs/ROADMAP.md) for what is next — CIMD and the
-`2026-07-28` stateless core are the two open items.
-
-## Scripts
+PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ```bash
 npm test
@@ -665,10 +149,6 @@ npm run build
 npm run typecheck
 ```
 
-## Contributing
-
-PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
-
 ## License
 
 MIT