mcp-trellis 0.2.1 → 2.1.0

package/dist/server.js

@@ -1,12 +1,13 @@
 export { createMcpApp, } from "./app.js";
-export { CLIENT_PROFILES, DEFAULT_CLIENTS, authMethodsFor, redirectUrisFor, preRegisteredClients, hasDynamicClient, } from "./clients.js";
-export { createMcpHandler, } from "./dispatch.js";
 export { consoleAudit } from "./audit.js";
-export { createToolRegistry, } from "./registry.js";
-export { defineTool, apiTool, } from "./tools.js";
-export { rpcResult, rpcError, JSONRPC_PARSE_ERROR, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_INVALID_PARAMS, JSONRPC_INTERNAL_ERROR, JSONRPC_UNAUTHORIZED, } from "./jsonrpc.js";
-export { pickProtocolVersion, PROTOCOL_VERSIONS, DEFAULT_PROTOCOL_VERSION, } from "./protocol.js";
-export { parseBearer, timingSafeEqual, matchesAny, wwwAuthenticateHeader, rejectQueryToken, } from "./auth/bearer.js";
-export { validateAgainstSchema, JSON_SCHEMA_TYPES, SUPPORTED_SCHEMA_KEYWORDS, IGNORED_SCHEMA_KEYWORDS, unsupportedKeywords, } from "./validate.js";
-export { jsonResponse, emptyResponse, optionsResponse, corsHeaders, methodNotAllowed, } from "./http.js";
+export { parseBearer, rejectQueryToken, wwwAuthenticateHeader, } from "./auth/bearer.js";
+export { authMethodsFor, CLIENT_PROFILES, DEFAULT_CLIENTS, hasDynamicClient, preRegisteredClients, redirectUrisFor, } from "./clients.js";
+// Moved to `mcp-trellis/advanced`; deprecated aliases until 3.0.
+export * from "./deprecated.js";
+export { jsonResponse, } from "./http/http.js";
+export { createMcpHandler, } from "./mcp/dispatch.js";
+export { JSONRPC_INTERNAL_ERROR, JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, JSONRPC_UNAUTHORIZED, rpcError, rpcResult, } from "./mcp/jsonrpc.js";
+export { DEFAULT_PROTOCOL_VERSION, PROTOCOL_VERSIONS } from "./mcp/protocol.js";
+export { createToolRegistry, } from "./mcp/registry.js";
+export { apiTool, defineTool, } from "./mcp/tools.js";
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAKb,MAAM,UAAU,CAAC;AAclB,OAAO,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,gBAAgB,GAGjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,gBAAgB,GAOjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EACL,kBAAkB,GAOnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,UAAU,EACV,OAAO,GAKR,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,QAAQ,EACR,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,GAIrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,gBAAgB,GAEjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,GAEpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,gBAAgB,GACjB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAMb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACL,WAAW,EACX,gBAAgB,EAEhB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,eAAe,EAGf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,iEAAiE;AACjE,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAGL,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,gBAAgB,GAMjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EAIpB,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,GAOnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,OAAO,EAEP,UAAU,GAEX,MAAM,gBAAgB,CAAC"}

package/dist/util/defined.d.ts

@@ -0,0 +1,11 @@
+/** `keys` of `T` with `undefined` removed from each value type, all optional. */
+export type DefinedProps<T, K extends keyof T> = {
+    [P in K]?: Exclude<T[P], undefined>;
+};
+/**
+ * Copies only the listed keys whose value is not `undefined`. Under
+ * `exactOptionalPropertyTypes` an explicit `undefined` is not assignable to
+ * an optional property, so forwarding optional options needs exactly this.
+ */
+export declare const pickDefined: <T extends object, K extends keyof T>(source: T, keys: readonly K[]) => DefinedProps<T, K>;
+//# sourceMappingURL=defined.d.ts.map

package/dist/util/defined.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defined.d.ts","sourceRoot":"","sources":["../../src/util/defined.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;CAAE,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC7D,QAAQ,CAAC,EACT,MAAM,SAAS,CAAC,EAAE,KACjB,YAAY,CAAC,CAAC,EAAE,CAAC,CAOnB,CAAC"}

package/dist/util/defined.js

@@ -0,0 +1,15 @@
+/**
+ * Copies only the listed keys whose value is not `undefined`. Under
+ * `exactOptionalPropertyTypes` an explicit `undefined` is not assignable to
+ * an optional property, so forwarding optional options needs exactly this.
+ */
+export const pickDefined = (source, keys) => {
+    const picked = {};
+    for (const key of keys) {
+        const value = source[key];
+        if (value !== undefined)
+            picked[key] = value;
+    }
+    return picked;
+};
+//# sourceMappingURL=defined.js.map

package/dist/util/defined.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defined.js","sourceRoot":"","sources":["../../src/util/defined.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,MAAS,EACT,IAAkB,EACE,EAAE;IACtB,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAiC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/dist/util/json.d.ts

@@ -0,0 +1,3 @@
+/** A parsed JSON object — not `null`, not an array. */
+export declare const isJsonObject: (value: unknown) => value is Record<string, unknown>;
+//# sourceMappingURL=json.d.ts.map

package/dist/util/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/util/json.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACP,CAAC"}

package/dist/util/json.js

@@ -0,0 +1,3 @@
+/** A parsed JSON object — not `null`, not an array. */
+export const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+//# sourceMappingURL=json.js.map

package/dist/util/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/util/json.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAc,EAAoC,EAAE,CAC/E,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC"}

package/docs/ROADMAP.md

@@ -0,0 +1,283 @@
+# mcp-trellis — roadmap
+
+Status: 2026-09-14. Written against MCP spec revision `2026-07-28`.
+
+## What this library is
+
+> **Existing SaaS → authenticated AI connector SDK** — MCP + self-hosted OAuth
+> AS in one npm install, on any Web-standard runtime, with no database and no
+> vendor.
+
+The differentiating axis is **clients**, not runtimes. Runtime portability is
+table stakes; the official SDK has it too. What nobody in TypeScript ships is
+both halves — the MCP handler *and* a self-hosted OAuth authorization server —
+in one package you can drop into a Next.js route or a Deno server.
+
+Contrast composition stacks that split the MCP runtime from the identity
+product (e.g. xmcp + Scalekit): those are 2–3 products to wire; mcp-trellis is
+one package with BYO-auth ports.
+
+| | Portable runtime | Self-hosted AS | One npm install | Zero-dep |
+|---|---|---|---|---|
+| Official SDK v2 | yes | **no** | yes (handler only) | no |
+| `workers-oauth-provider` | Workers only | yes | yes | — |
+| Auth0 / Authlete / Clerk | yes | **no** (SaaS) | no (IdP + MCP) | — |
+| Better Auth | yes | yes | yes, but full stack + DB | no |
+| **xmcp** | yes | **no** (compose) | no — pair with IdP | — |
+| **Scalekit** | yes | managed connector IdP | no — pair with MCP runtime | — |
+| **WorkOS Standalone Connect** | yes | managed | no — IdP + your MCP | — |
+| **Descope** | yes | managed | no — IdP + your MCP | — |
+| **mcp-trellis** | yes | yes | **yes** (handler + AS) | yes |
+
+The official SDK explicitly does not provide an authorization server — it offers
+SDK-level opt-ins and expects you to bring the infrastructure. That gap is the
+product.
+
+### The rule that decides design questions
+
+**If a user can forget to do something and the result is a security hole, it
+goes in the code, not the README.** Audience validation moved into
+`createMcpApp` for exactly this reason.
+
+### The acceptance test
+
+From `npm install` to a connected client: **under 15 lines and one secret.**
+Anything that forces the user to route requests, read an RFC, or install a
+second package fails.
+
+---
+
+## Shipped
+
+**Phase 0 — trust.** Query-string tokens now cover RFC 6750's `access_token`;
+audit fires on every denial including transport-level ones, and a throwing audit
+port can no longer fail a request; tool exceptions are redacted by default;
+a relative `loginUrl` resolves instead of throwing; explicit `id: null` returns
+a proper JSON-RPC error.
+
+**Phase 1 — the app layer and the Gemini unblock.**
+
+- `createMcpApp` — one call mounts tools, the AS, both discovery documents, and
+  the routing between them. `createMcpHandler` / `createOAuthRouter` stay
+  exported for anyone who wants to compose the pieces.
+- **Audience validation is enforced by the library.** `verifyToken` returns the
+  token's audience; `createMcpApp` compares it against `canonicalResource` and
+  rejects mismatches before any tool runs.
+- **Client profiles** (`claude` / `gemini` / `codex`) compose the redirect
+  allowlist and the advertised token-endpoint auth methods. Client-specific
+  knowledge is the asset, so it lives in the library.
+- **Confidential clients and pre-registration** via a `clientStore` port —
+  `client_secret_basic` and `client_secret_post`. This is what Gemini Enterprise
+  needs, and it was previously impossible: the AS advertised `["none"]` only.
+  Secret storage and comparison stay in the port; credentials never enter the
+  library.
+- **Naming only confidential clients is enforced, not just advertised.**
+  The first cut of this let `clients: ["gemini"]` configure the AS's metadata
+  while leaving DCR and the loopback allowlist wide open — a self-registered
+  public client could still complete a normal PKCE flow and get a token,
+  quietly defeating the "confidential clients only" intent. Fixed:
+  `allowUnregisteredClients: false` (derived automatically by `createMcpApp`
+  when no configured client registers dynamically) unmounts `/register`, drops
+  it from AS metadata, and rejects any `client_id` the `clientStore` doesn't
+  resolve — `unauthorized_client` at `authorize`, `invalid_client` at `token`.
+  Public type break: `AuthorizationServerMetadata.registration_endpoint` is
+  now optional (`string | undefined`), omitted when DCR is off.
+- **Scope threaded end-to-end.** `authorize` validates the requested scope
+  against the advertised set, the auth code carries the grant, and
+  `mintAccessToken` receives it. `ToolDef.scope` finally sits on a chain that
+  reaches the OAuth layer.
+- Node adapter drains the request stream when `req.body` is absent, so raw
+  `http.createServer` works without a body-parser.
+- `[::1]` added to the loopback redirect allowlist.
+- **`defineTool` / `apiTool`.** The library was easy to run but not easy to
+  *author tools for* — every tool hand-wrote its own JSON Schema disconnected
+  from its handler's types, and every API-backed tool re-invented fetch/error
+  plumbing. `defineTool` adds optional Standard Schema v1 parsing in front of
+  parsing in front of a handler — typed args, validation failures short-circuit
+  before the handler runs. `apiTool` builds on it: give it `request` (+
+  optional `respond`) and get a working REST-call tool, non-2xx handled as
+  `isError` automatically. `inputSchema` (JSON Schema, for `tools/list`) stays
+  required and separate — no library-agnostic way exists to derive it from an
+  arbitrary Standard Schema validator, so the two must be kept in sync by hand.
+- **No host port can crash `fetch`.** Nothing guarded `authenticate`,
+  `context`, `resolveUser`, `mintAccessToken`, `clientStore`, etc. — any of
+  them throwing turned `.fetch()` into a rejected promise instead of a
+  `Response`, with the fallout depending on the runtime (a generic error page
+  on Workers, a hung socket with no response ever sent on raw
+  `http.createServer`). `createMcpHandler`, `createOAuthRouter`,
+  `createMcpApp`, and `asNodeHandler` now each catch at their own boundary and
+  return a real `500` instead.
+
+- **RFC 7009 token revocation.** The library never stores access or refresh
+  tokens, so revocation is a host port — `revokeToken` — advertised and mounted
+  only when implemented (same honest-advertisement pattern as refresh).
+  Well-formed authenticated `POST /revoke` returns 200 even if the token is
+  unknown (`invalid_request` 400 and `invalid_client` 401 still apply).
+  Stolen-token invalidation lives in the host store that `verifyToken` and
+  `refreshAccessToken` consult.
+
+- **Claims on `Principal`.** Optional `claims` from `verifyToken` /
+  `VerifiedToken` flow into `context` (plan/role metadata — not the
+  Host→tenant isolation key). Host-origin allowlisting (`allowedOrigins` on
+  `asNodeHandler`) is **required** when origin is Host-derived. Separately,
+  browser `Origin` on MCP is gated by `allowedRequestOrigins` (fail-closed
+  when the header is present; native clients omit it).
+
+- **`validateArgs` fail-fast.** With `validateArgs: true`, unsupported JSON
+  Schema keywords throw at `createToolRegistry` construction instead of
+  silently looking enforced. Default (off) is unchanged.
+
+**Phase 2 — the authorize endpoint (0.2.2 / 0.3.0).**
+
+- **Consent step at `/authorize`.** A resolved session no longer issues a
+  code and redirects on its own; it renders an approval interstitial (built
+  in, or your own via `consent.render`) and only issues a code after an
+  explicit `POST ${oauthPath}/consent` approval. Closes a cross-site flow
+  where an attacker-controlled page could otherwise walk a logged-in user
+  through `/authorize` with an attacker-chosen `client_id`/`code_challenge`
+  and a loopback `redirect_uri`, catching the code with a local listener —
+  PKCE alone does not defend against this, it proves possession of the
+  verifier, not the identity of a legitimate client. Approval tickets are
+  AES-GCM sealed (`sealed.ts`), single-use, and re-checked against the
+  resolved user at redemption.
+- **DCR `client_id` is bound to its own `redirect_uris`**, zero storage — the
+  id issued by `/register` is a sealed, self-verifying assertion of the list
+  it registered. Stops a substituted `redirect_uri` on a legitimate
+  connector's id (not impersonation via self-registration — the consent step
+  above is what stops that). `requireRegisteredClients` (default `true`
+  since 1.0) is the stricter default, and a direct stepping stone to CIMD below.
+- **`codeSecret` is validated** — minimum 32 characters, and the literal
+  values this package's own docs/examples publish are denylisted by name.
+  It is the single key that can forge an auth code, consent ticket, or DCR
+  client assertion for any userId/scope/resource, and had no validation at
+  all before this.
+- **Loopback redirect allowlist narrowed** — `localhost` and `https:`
+  loopback are no longer accepted (RFC 8252 §8.3); a `redirect_uri` carrying
+  a fragment or embedded credentials is rejected for every predicate, not
+  only loopback.
+- **`defaultScopes` required for multi-scope servers.** `createOAuthRouter`
+  now throws at construction when `scopes` has more than one entry and
+  `defaultScopes` is unset, instead of silently granting the full advertised
+  set to a client that asked for nothing.
+- **`timingSafeEqual("", "")` now returns `false`**, not `true` — a public
+  export, so a host comparing a presented secret against an unset stored one
+  no longer authenticates.
+- **Request body size limits** on `/mcp`, `/token`, `/revoke`, and
+  `/register` — previously unbounded on every one of them.
+
+**Phase 3 — credentials and correctness (0.4.0).**
+
+- **Auth codes sealed (AES-GCM), not signed-only.** v1 (HMAC) codes were
+  readable by anyone who saw one; v2 codes are encrypted too. Soft
+  migration in 0.4.0 / 0.5.0 (read both, write v2); **1.0.0 drops v1 reading**.
+- **`ClientStore.secretHash`**, preferred over `verifySecret`: return a
+  stored hash from the new `hashClientSecret` and the library does the
+  comparison with the same constant-time primitive it uses everywhere
+  else. Keyed by `codeSecret` — no second secret to manage.
+- **Client-auth enumeration oracle closed.** `/token` and `/revoke`
+  collapsed five distinguishable error messages into one; a locked-down
+  server also pays a fixed-cost dummy comparison for an unknown
+  `client_id`, so response timing can't distinguish "unknown" from
+  "known, wrong secret" either. Unaffected: public-client traffic, and
+  `/authorize`'s deliberately-still-descriptive `unauthorized_client`.
+- **`/revoke` accepts JSON**, matching `/token` — previously form-only,
+  so a JSON revoke silently failed while the caller believed it worked.
+- **`apiTool` no longer forwards the upstream error body by default** —
+  status only; opt in via the new `onError`.
+- **`missingObjectType`** — a schema using `properties`/`required`
+  without `type: "object"` now throws at construction under
+  `validateArgs: true`, and is enforced at runtime by dispatching on the
+  value's actual shape rather than trusting a schema author remembered to
+  declare `type`.
+- **Union `type` arrays** (`type: ["string", "null"]`) now evaluate
+  correctly — previously always failed.
+- **`/authorize` errors redirect to the client's callback** (RFC 6749
+  §4.1.2.1) once `redirect_uri` is validated, instead of a bare JSON body
+  the connector never parses — this was silently connector-breaking.
+
+**Phase 4 — protocol correctness and observability (0.5.0).**
+
+- **`jsonrpc` validated on every `/mcp` request** — `-32600` on anything
+  but exactly `"2.0"`, including a missing field. Previously accepted
+  silently.
+- **`MCP-Protocol-Version` header read and validated**, per the
+  2025-06-18 spec — unsupported → 400, missing → assumed `2025-03-26`
+  (the spec's own compatibility default), not checked on `initialize`
+  (which is what negotiates the version). Previously only appeared in the
+  CORS allow-list, never actually read.
+- **`initialize` defaults to the newest supported protocol version**
+  (`2025-06-18`) for a missing/unrecognized request, not the oldest.
+- **401 responses echo the real request id** instead of hardcoding `null`.
+- **`/mcp/` routes identically to `/mcp`.** `canonicalResource` normalizes
+  its `resourcePath` argument internally, so route matching, `/authorize`,
+  and `/token` all agree — previously only some call sites normalized a
+  trailing slash and others read a raw, unnormalized value.
+- **`createOAuthRouter` refuses to construct** if `oauthPath` would equal
+  `resourcePath` (they'd shadow each other) or if `resourcePath` starts
+  with `/.well-known` (reserved for discovery documents).
+- **`auditTimeoutMs`** (default 1000ms) — a hanging `ports.audit` can no
+  longer stall a response indefinitely; it already couldn't fail one.
+- **`OAuthPorts.audit` / `McpAppAuth.audit`** — the OAuth-side twin of the
+  MCP audit hook. Sees the real reason behind a collapsed `invalid_client`
+  or a rejected `codeSecret`, which the caller never does.
+
+**2.0 — CIMD, unified audit, recipes.**
+
+- **CIMD (Client ID Metadata Documents)** — opt-in (`cimd: true`). HTTPS URL
+  `client_id`s are fetched and validated with SSRF hardening (public hosts
+  only, size / redirect / timeout caps). Advertises
+  `client_id_metadata_document_supported`. Optional `cimdCache` port.
+  Off by default until connect-pinned fetch closes the DNS-rebinding ceiling.
+- **Unified `audit` sink** on `createMcpApp` — one callback for MCP and
+  OAuth events (`source: "mcp" | "oauth"`); `auth.audit` remains an
+  OAuth-only override.
+- **Framework recipes** — `examples/nextjs-route.ts`, `examples/express.ts`.
+- Fail-closed defaults: `allowInMemoryCodeStore` / `validateArgs`.
+- **RFC 9207 `iss`** on authorize / error redirects; AS metadata advertises
+  `authorization_response_iss_parameter_supported`.
+
+---
+
+## Next
+
+### 1. Protocol currency — `2026-07-28`
+
+Deferred deliberately: Claude, Gemini, and Codex all work against current
+revisions today, and the official SDK already covers dual-era for anyone who
+needs it now. But a batteries-included server that speaks an outdated revision
+is worse than useless, so this becomes mandatory once real clients move.
+
+Work: remove `initialize` / `ping`, add `server/discover` (MUST), carry protocol
+version and client capabilities in `_meta` per request, `resultType` on every
+result, `ttlMs` / `cacheScope` on `tools/list`, `Mcp-Method` / `Mcp-Name`
+headers, deterministic `tools/list` ordering. Add `2025-11-25` and `2026-07-28`
+to the version table and stop defaulting to the oldest revision.
+
+---
+
+## Non-goals
+
+Backed by the spec, not just by our own scoping:
+
+- **No sampling / roots / logging** — deprecated in `2026-07-28`
+- **No sessions** — removed from the protocol
+- **No SSE resumability** — removed from the transport
+- **No HTTP+SSE transport** — deprecated; Gemini Enterprise refuses it outright
+- **No login UI, token store, or IdP** — the ports stay the product. The
+  `/authorize` consent/approval screen is shipped (built in, overridable),
+  since it's a security control determined by protocol data the library
+  already holds, not by your IdP or branding; login itself stays yours
+- **No resources / prompts** — a real limitation; revisit on demand
+- **No DPoP** — sender-constrained tokens; connectors use bearer + PKCE
+- **No PAR (RFC 9126)** — pushed authorization requests
+- **No `client_credentials`** — connectors are user-delegated; this AS is authorization_code (+ optional refresh)
+
+Deferred until asked: MRTR (`input_required`), `subscriptions/listen`,
+`io.modelcontextprotocol/tasks`.
+
+## Known gaps
+
+Tracked, not scheduled: `pruneMemory` scans the whole jti map on every code
+consume; `mcpWwwAuthenticate` and `wwwAuthenticateHeader` build the same
+header twice. (Unsupported JSON Schema keywords under `validateArgs: true`
+now throw at `createToolRegistry` construction — no longer a silent gap.)

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 |