mcp-trellis 2.2.0 → 3.1.0

package/dist/util/own.js

@@ -0,0 +1,8 @@
+/**
+ * `record[key]` for an attacker-supplied `key`: only an own property counts.
+ * A plain object literal also answers `"constructor"`, `"toString"` and
+ * `"__proto__"` from `Object.prototype`, which would otherwise be mistaken
+ * for a registered handler.
+ */
+export const ownValue = (record, key) => Object.hasOwn(record, key) ? record[key] : undefined;
+//# sourceMappingURL=own.js.map

package/dist/util/own.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"own.js","sourceRoot":"","sources":["../../src/util/own.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAI,MAAmC,EAAE,GAAW,EAAiB,EAAE,CAC7F,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC"}

package/docs/ROADMAP.md

@@ -1,6 +1,7 @@
 # mcp-trellis — roadmap
 
-Status: 2026-09-14. Written against MCP spec revision `2026-07-28`.
+Status: 2026-11-07. Written against MCP spec revision `2026-07-28`. What shipped,
+version by version, is in [CHANGELOG.md](../CHANGELOG.md).
 
 ## What this library is
 
@@ -9,29 +10,15 @@ Status: 2026-09-14. Written against MCP spec revision `2026-07-28`.
 > 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.
+table stakes; the official SDK has it too. mcp-trellis puts both halves — the MCP
+handler *and* a self-hosted OAuth authorization server — in one zero-dependency
+package that reuses the session your app already has, so you can drop it 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 official TypeScript SDK v2 ships resource-server helpers only and never
+issues tokens. How mcp-trellis compares with Better Auth, `workers-oauth-provider`,
+Scalekit and WorkOS is in the
+[README](../README.md#compared-with-the-alternatives).
 
 ### The rule that decides design questions
 
@@ -41,202 +28,9 @@ goes in the code, not the README.** Audience validation moved into
 
 ### The acceptance test
 
-From `npm install` to a connected client: **under 15 lines and one secret.**
+From `npm install` to a connected client: **at most 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-saas/`, `examples/express.ts`.
-- **Reference MCP Registry server** — `examples/project-desk/`
-  (`io.github.amir1824/project-desk`, remotes only; not the SDK package).
-- Fail-closed defaults: `allowInMemoryCodeStore` / `validateArgs`.
-- **RFC 9207 `iss`** on authorize / error redirects; AS metadata advertises
-  `authorization_response_iss_parameter_supported`.
+second package fails. `npm run check:quickstart` enforces the line count.
 
 ---
 
@@ -244,10 +38,11 @@ a proper JSON-RPC error.
 
 ### 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.
+Deferred deliberately: the revisions implemented today (`2024-11-05`,
+`2025-03-26`, `2025-06-18`) are what clients negotiate with this library, see
+[compatibility.md](compatibility.md). 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
@@ -276,10 +71,3 @@ Backed by the spec, not just by our own scoping:
 
 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

@@ -1,6 +1,6 @@
 # Compatibility evidence
 
-Updated 2026-09-14. Repository implementation and automated coverage are in good
+Updated 2026-11-07. 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.
@@ -8,7 +8,7 @@ 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 |
+| ChatGPT | `codex`: public-client profile; ChatGPT's stable callback and its per-connector `https://chatgpt.com/connector/oauth/{id}` callback are allowed | 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 |
 
@@ -53,7 +53,19 @@ 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 |
+| 2026-11-07 | `3.1.0` release-branch working tree | `npm run smoke:pack` | Pass — `createMcpApp` + `asNodeHandler` import from tarball |
+
+## Production use (maintainer-reported)
+
+The maintainer reports that two of their own production MCP servers run on
+mcp-trellis and are connected to Claude. On 2026-11-07 a Claude session called a
+read tool on each of them over its connector and got a normal result (an empty
+list from one, 14 note paths from the other).
+
+This is **not** a logged live pass. The Claude build and plan, the mcp-trellis
+version those servers run, and the discovery, authorize and token exchange were
+not recorded, and it says nothing about ChatGPT, Codex or Gemini. The "Live
+evidence" column above stays Pending until a pass is recorded in the table below.
 
 ## Evidence required for a live pass
 

package/docs/guide.md

@@ -248,8 +248,15 @@ createMcpApp({
 
 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.
+exceptions or stack traces from your tools, so console output is safe: each
+caller-chosen value (`client_id`, tool name, error text) is cut to 200
+characters, control and invisible characters are escaped, and a value
+containing a space, `=` or a quote is printed as a quoted string, so it cannot
+forge a log line or a `key=value` field (`error="Tool execution failed"`,
+`reason="secretHash mismatch"`). Host-level failures that reach `audit` carry
+the exception's message. For anything beyond stdout, write your own `audit`
+function — that is the intended production path; the entries it receives
+are not escaped, so escape or parameterize them for your sink.
 
 `wwwAuthenticate` can be a static object or `(req) => …` when the PRM URL depends on origin.
 
@@ -323,7 +330,7 @@ authorization code, or vice versa.
 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
+createToolRegistry(tools) // validateArgs defaults to true; pass { validateArgs: false } to skip it
 // onToolError?: (exc) => string — default redacts to "Tool execution failed"
 ```
 
@@ -389,7 +396,11 @@ const getWeather = apiTool({
   — **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
+  redacted version of the body. Redirects are **not followed** by default
+  (`redirect: "manual"`; `"error"` and `"follow"` are available): `fetch`
+  forwards custom headers such as `X-Api-Key`, and a POST body on a 307/308,
+  to whatever `Location` the upstream names, and would let an open redirect
+  reach internal addresses. `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

package/docs/reference.md

@@ -107,6 +107,7 @@ entry — those are protocol errors, not auth denials.
 | `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 |
+| `allowChatgptConnector` | `false` | Allow ChatGPT's per-connector callback `https://chatgpt.com/connector/oauth/{id}` (one `[A-Za-z0-9_-]{1,128}` id, exact string match). `createMcpApp` turns it on for `clients: ["codex"]` |
 
 Pre-registered clients, and DCR-issued clients whose id was sealed by this
 server's own `/register`, bypass this allowlist entirely — they are
@@ -154,10 +155,10 @@ A single-scope server has no such ambiguity and is unaffected.
 - `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
+- `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. `redirect` (`"manual"` by default, `"error"`, or `"follow"`) controls upstream redirects — see the guide before enabling `"follow"`. An abort on the `Request` your `request` callback returns surfaces as `Request was cancelled`
 - `CLIENT_PROFILES`, `DEFAULT_CLIENTS`, `authMethodsFor`, `redirectUrisFor`, `preRegisteredClients`, `hasDynamicClient`
 - `parseBearer`, `wwwAuthenticateHeader`, `rejectQueryToken`
-- `signedTokenAuth` — one-secret convenience `McpAppAuth` (HMAC access tokens via HKDF; no refresh/revoke). Type `SignedTokenAuthOptions`
+- `signedTokenAuth` — one-secret convenience `McpAppAuth` (HMAC access tokens via HKDF). `secret` may be a list for rotation (first signs, all verify). Opt-in: `isUserActive(userId)` runs on every verified token and every refresh; `refreshTtlSeconds` adds single-use rotating refresh tokens and `/revoke` for them (needs `codeStore` and `isUserActive`). Access tokens are not revocable before `ttlSeconds`. Type `SignedTokenAuthOptions`
 - `rpcResult`, `rpcError`, JSON-RPC error constants
 - `PROTOCOL_VERSIONS`, `DEFAULT_PROTOCOL_VERSION`
 - `jsonResponse({ data, status?, headers?, cors? })` — type `JsonResponseInput` exported
@@ -197,7 +198,7 @@ Building blocks for hosts assembling their own transport or OAuth flow. Less sta
 - `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.
+**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 the next major release.
 
 </details>
 
@@ -205,6 +206,7 @@ Building blocks for hosts assembling their own transport or OAuth flow. Less sta
 <summary><code>mcp-trellis/node</code></summary>
 
 - `asNodeHandler`, `resolveOrigin`, `isAllowedOrigin`, `toWebRequest`, `sendWebResponse`, `readNodeBody`
+- `asNodeHandler` options: `origin`, `trustProxy`, `allowedOrigins`, and `allowedHosts` — the exact `Host` values to answer to (**400** otherwise). On by default for a loopback `origin` (`127.0.0.1` / `localhost` / `[::1]` on its port), to stop DNS rebinding; set it yourself for any other fixed origin or to add a LAN address
 - 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
 

package/docs/security.md

@@ -21,28 +21,31 @@ This is a **library** threat model, not a third-party audit badge.
 
 | Risk | Mitigation |
 |------|------------|
-| Attacker-driven cross-site authorization (a logged-in user visits an attacker page and is silently walked through `/authorize`, catching the code on an attacker-controlled `redirect_uri`) | **`/authorize` never issues a code directly.** A resolved session renders a consent interstitial (built in, hardened — CSP, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, escaped reflection — or your own via `consent.render`) and only issues a code after an explicit `POST ${oauthPath}/consent` approval. The approval ticket is sealed (AES-GCM, HKDF-derived per-type key, type bound in as AEAD data — see `sealed.ts`), single-use, 5-minute TTL, and re-checked against the resolved user at redemption; it can never be redeemed as an auth code or vice versa. PKCE alone does **not** defend against this — it proves possession of the verifier, not identity of a legitimate client — so this is a distinct control, not a restatement of PKCE. `preApprovedClientIds` skips the screen only for ids `clientStore` actually resolves; a DCR or self-invented id is never trusted to skip it. The built-in interstitial's CSP scopes `form-action` to `'self'` plus the validated `redirect_uri`'s own origin — Chromium enforces `form-action` across the redirect the approval POST produces, not just its immediate target, so a custom `consent.render` that sets its own CSP must do the same or the callback to the client's own origin gets silently blocked. |
+| Attacker-driven cross-site authorization (a logged-in user visits an attacker page and is silently walked through `/authorize`, catching the code on an attacker-controlled `redirect_uri`) | **`/authorize` never issues a code directly.** A resolved session renders a consent interstitial (built in, hardened — CSP, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, escaped reflection — or your own via `consent.render`) and only issues a code after an explicit `POST ${oauthPath}/consent` approval. The approval ticket is sealed (AES-GCM, HKDF-derived per-type key, type bound in as AEAD data — see `sealed.ts`), single-use, 5-minute TTL, and re-checked against the resolved user at redemption; it can never be redeemed as an auth code or vice versa. PKCE alone does **not** defend against this — it proves possession of the verifier, not identity of a legitimate client — so this is a distinct control, not a restatement of PKCE. `preApprovedClientIds` skips the screen only for ids `clientStore` actually resolves; a DCR or self-invented id is never trusted to skip it. The built-in interstitial's CSP scopes `form-action` to `'self'` plus the validated `redirect_uri`'s own origin (its scheme, e.g. `myapp:`, for a custom-scheme URI whose origin is opaque) — Chromium enforces `form-action` across the redirect the approval POST produces, not just its immediate target, so a custom `consent.render` that sets its own CSP must do the same or the callback to the client's own origin gets silently blocked. |
 | 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` (the auth code's single-use id) 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) |
+| 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). A fixed `origin` ignores the `Host` header, so a DNS-rebinding page could otherwise drive the whole OAuth flow from a victim's browser: for a loopback `origin` `asNodeHandler` rejects any other `Host` by default, and `allowedHosts` does the same for any origin |
 | A Host/`X-Forwarded-*` header carrying a path, query, fragment, or embedded credentials (`evil.test/../trusted.test`, `user:pass@evil.test`) building an origin string that merely looks well-formed | `resolveOrigin` always normalizes and validates through `URL`, rejecting any of those (plus a non-`http(s)` `X-Forwarded-Proto`) with `InvalidOriginError` — `asNodeHandler` answers it **400**, not the generic 500 an actual unexpected failure gets |
 | Browser `Origin` on MCP (DNS rebinding / CSRF) | `allowedRequestOrigins` on `createMcpHandler` / `createMcpApp`. No `Origin` header → allowed (native clients). Omitted allowlist → **reject** any present `Origin`. `"*"` opts out. Distinct from Node Host `allowedOrigins` |
 | 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` |
 | An unscoped tool silently callable by any authenticated principal, including one holding none of the advertised scopes — the gap `defaultScopes: []` alone doesn't close, since that only governs the token grant, not per-tool enforcement | `createMcpApp` refuses to construct once `scopes` has more than one entry if any tool omits `ToolDef.scope` — pass `scope: null` to state the omission on purpose. A single-scope server has no such ambiguity and is unaffected. `tools/call` itself always enforces whatever `scope` a tool does declare, independent of this guard (403 `insufficient_scope`) |
 | Scope reduction lost on refresh | Optional `scope` on the refresh token request is validated against advertised scopes and forwarded on `RefreshAccessTokenInput.scope`. **`refreshAccessToken` MUST enforce ⊆ originally granted scopes** (opaque RT — same pattern as `resource`). The token response omits `scope` when neither the port nor the grant supplies one (RFC 6749 §5.1) — clients must not assume the field is always present |
+| A removed or disabled user keeps a working connector | `signedTokenAuth` tokens are stateless, so they outlive the login session. `isUserActive` closes that; see [Sessions and expiry](#sessions-and-expiry) |
 | 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. **Prefer `clientStore.secretHash`** instead: return a stored hash from `hashClientSecret` and the library does the comparison with the same constant-time primitive it uses everywhere else, rather than a hand-rolled `stored === presented` in your own `verifySecret` being a timing oracle with no warning |
 | An unauthenticated caller enumerating which `client_id`s a locked-down server knows, via distinguishable `/token`/`/revoke` error text or response timing | Every client-auth failure at `/token` and `/revoke` collapses to one `invalid_client` / "client authentication failed" — previously up to five distinguishable messages named exactly why (wrong method, missing secret, misconfigured store, unknown id). Every rejection path in `firstClientAuthError` for a client_id that *is* known — wrong auth method, no secret presented, wrong secret, no `secretHash`/`verifySecret` on file — runs the same fixed-cost dummy or real comparison before returning, so response timing alone can't tell "known client, wrong method" apart from "known client, wrong secret." An unknown `client_id` on a locked-down server (`allowUnregisteredClients: false`) pays the identical fixed cost, so the crypto-verification cost itself can't distinguish "unknown" from "known, wrong secret" either. `/authorize`'s `unauthorized_client` is unchanged and stays descriptive — a human debugging a browser flow, not a bare API response, and a locked-down server already announces the same fact by omitting `registration_endpoint` |
 | Auth codes readable by anyone who sees one — browser history, `Referer`, proxy logs | Auth codes are sealed (AES-GCM, `sealed.ts`), not signed-only. Legacy v1 (HMAC-signed, not encrypted) codes are **rejected** since 1.0 — complete any rolling deploy before upgrading past 0.4.x |
 | An upstream API's error body leaking into the model or the audit log via `apiTool` | Default is status-only — the upstream response body is never forwarded on a non-2xx result, since it's a return value `onToolError` redaction never sees. Use `onError` for (a redacted version of) the body |
+| `apiTool` as a credential-forwarding / SSRF primitive via upstream redirects | Redirects are not followed by default (`redirect: "manual"`): `fetch` would forward custom auth headers (`X-Api-Key`) and a 307 body to the `Location` and could fetch an internal address, returning it to the model. `"follow"` is an explicit opt-in for a fully trusted upstream |
+| A tool call that amplifies a small request into a huge validation error | Validation stops after 20 violations and the message is capped at 2000 characters; audit copies of tool errors are capped at 1000 |
 | `/authorize` errors delivered as a bare JSON body a connector can't act on | RFC 6749 §4.1.2.1: once `redirect_uri` is validated, every remaining error (`unsupported_response_type`, PKCE, `invalid_scope`, `invalid_target`, …) redirects to the client's own callback with `?error=…&state=…` instead. `redirect_uri` validity itself, and an oversized `state`, stay direct JSON — the URI is what's in question in the first case, and reflecting an oversized `state` into its own error redirect would recreate the DoS the length cap exists to prevent |
-| DCR-issued `client_id` reused with a substituted `redirect_uri` | `/register` no longer returns a bare random id — the `client_id` **is** a sealed, self-verifying assertion of the exact `redirect_uris` it registered (`sealed.ts`, type `"client"`), with zero server-side storage. `/authorize` unseals it and binds the request to that list, the same protection a stored registration would give. This does not require the *identity* of the client to be verified — an attacker can still call `/register` and mint their own sealed id — so it stops URI substitution on a legitimate connector's id, not impersonation; the consent step above is what stops impersonation. `requireRegisteredClients` defaults to **true** since 1.0 (reject any `client_id` that isn't `clientStore`-resolved or self-sealed); set `false` only to accept invented public ids. Enforced at `/authorize`, and — since 1.2.0 — at `/token`'s `refresh_token` grant and at `/revoke` too, closing a gap where an invented `client_id` that never went through `/authorize` could still authenticate on either (the `authorization_code` grant was never actually exposed by this: a redeemable code's `client_id` is bound into its sealed payload at `/authorize` time, where the check already ran). Opt into CIMD with `cimd: true` for URL-shaped client_ids (off by default) |
-| CIMD fetch as SSRF proxy (attacker supplies `https://…` `client_id`) | **Off by default** (`cimd: true` to enable). When on: HTTPS-only fetch, private/loopback/link-local/NAT64/`::ffff:` blocked (incl. bracketed IPv6 **and full-form mapped encodings DNS may return**, e.g. `0:0:0:0:0:ffff:7f00:1`), DNS lookup required before fetch and re-checked after the body, unparseable IPv6 lookup results fail closed, 5 KB stream-capped body / 10 s per hop covering the body read / 3 same-origin redirects (cross-origin redirects rejected), public clients only, `http:` redirect_uris loopback-only (`127.0.0.1` / `[::1]`, never `localhost`). Also blocked: `192.0.0/24`, `198.18/15`, multicast/reserved `224/4`–`240/4`, IPv6 multicast `ff00::/8`, 6to4 `2002::/16`, IPv4-compatible `::a.b.c.d` (and full-form private embeds). `/token` and `/revoke` **re-resolve** CIMD — never accept URL-shaped ids by shape alone; pass `cimdCache` (strongly recommended) or every refresh/revoke re-fetches the document, and a failed re-resolve is audited as `cimd_resolve_failed`. **Ceiling:** TCP connect is not pinned to the looked-up addresses (zero-dep Web `fetch`); classic DNS rebinding between lookup and connect remains possible until a custom dispatcher pins the IP — do not treat CIMD as production-complete SSRF defense until then |
+| DCR-issued `client_id` reused with a substituted `redirect_uri` | `/register` no longer returns a bare random id — the `client_id` **is** a sealed, self-verifying assertion of the exact `redirect_uris` it registered (`sealed.ts`, type `"client"`), with zero server-side storage. `/authorize` unseals it and binds the request to that list, the same protection a stored registration would give. This does not require the *identity* of the client to be verified — an attacker can still call `/register` and mint their own sealed id — so it stops URI substitution on a legitimate connector's id, not impersonation; the consent step above is what stops impersonation. `requireRegisteredClients` defaults to **true** since 1.0 (reject any `client_id` that isn't `clientStore`-resolved or self-sealed); set `false` only to accept invented public ids. Enforced at `/authorize`, and — since 2.0.0 — at `/token`'s `refresh_token` grant and at `/revoke` too, closing a gap where an invented `client_id` that never went through `/authorize` could still authenticate on either (the `authorization_code` grant was never actually exposed by this: a redeemable code's `client_id` is bound into its sealed payload at `/authorize` time, where the check already ran). Opt into CIMD with `cimd: true` for URL-shaped client_ids (off by default) |
+| CIMD fetch as SSRF proxy (attacker supplies `https://…` `client_id`) | **Off by default** (`cimd: true` to enable). When on: HTTPS-only fetch, private/loopback/link-local/NAT64/`::ffff:` blocked (incl. bracketed IPv6 **and full-form mapped encodings DNS may return**, e.g. `0:0:0:0:0:ffff:7f00:1`), DNS lookup required before fetch and re-checked after the body, unparseable IPv6 lookup results fail closed, 5 KB stream-capped body / 10 s per hop covering the body read / 3 same-origin redirects (cross-origin redirects rejected), public clients only, `http:` redirect_uris loopback-only (`127.0.0.1` / `[::1]`, never `localhost`). Also blocked: `192.0.0/24`, `198.18/15`, multicast/reserved `224/4`–`240/4`, IPv6 multicast `ff00::/8`, 6to4 `2002::/16`, IPv4-compatible `::a.b.c.d` (and full-form private embeds). `/token` and `/revoke` **re-resolve** CIMD — never accept URL-shaped ids by shape alone; pass `cimdCache` (strongly recommended) or every refresh/revoke re-fetches the document, and a failed resolve is audited as `cimd_resolve_failed` at `/authorize`, `/token` and `/revoke` with a reason code (`http_status: status 403 (authorize)`; never an address, header, body or redirect target) while the connector gets one generic `unauthorized_client`. **Ceiling:** TCP connect is not pinned to the looked-up addresses (zero-dep Web `fetch`); classic DNS rebinding between lookup and connect remains possible until a custom dispatcher pins the IP — do not treat CIMD as production-complete SSRF defense until then |
 | 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`, **plus** a library-enforced request body cap (see "Also designed in") — the library does not rate-limit by request count, but an unbounded body was previously a memory-exhaustion vector on its own regardless of rate |
+| DCR / token-endpoint abuse | Edge or reverse-proxy rate limiting on `/register` and `/token` — and on `/authorize` when `cimd: true`, where each unresolvable `client_id` costs an outbound fetch and one `cimd_resolve_failed` audit entry — **plus** a library-enforced request body cap (see "Also designed in") — the library does not rate-limit by request count, but an unbounded body was previously a memory-exhaustion vector on its own regardless of rate |
 | A weak or copy-pasted `codeSecret` (it can forge an auth code — or, since 0.3.0, a consent ticket or DCR client assertion — for any userId/scope/resource) | Validated at the point of use: a string or array form throws at `createOAuthRouter` construction (every array entry checked, and the array itself must be non-empty), a function form on every call. Minimum 32 characters per entry, and the exact literals this package's own docs and examples have published are denylisted by name, as is any secret containing the examples' `do-not-reuse` marker — copy-paste is the realistic failure mode. The examples themselves read `MCP_SECRET` (or `OAUTH_CODE_SECRET` for the advanced multi-secret recipes) from the environment and ship no usable default, and a test fails if any `codeSecret` literal in `examples/`, `README.md` or `docs/` is one the library would accept. This only catches the obvious cases; a leaked or brute-forceable 32+ character secret is still a full bypass, same as before |
 | An operator unable to diagnose *why* a client was rejected, once `/token`/`/revoke` collapsed every failure to one generic `invalid_client` (see the enumeration-oracle row above) | `OAuthPorts.audit` (and `McpAppAuth.audit` on `createMcpApp`) — opt-in, sees the real reason (`"client requires client_secret_basic, got none"`, a rejected `codeSecret`'s actual message, …) that never reaches the caller. Same "never fails the request" guarantee as the MCP-side `audit` port |
 | A hanging `ports.audit` sink stalling every audited response indefinitely | `auditTimeoutMs` (default 1000ms) on both `McpHandlerOptions` and `OAuthRouterOptions` races the audit call against a timeout; "can't fail a request" already held, this adds "can't delay one" past a bound. A slow sink keeps running in the background and its own internal `catch` means it can never surface as an unhandled rejection later |
@@ -51,15 +54,68 @@ This is a **library** threat model, not a third-party audit badge.
 
 **Known limits:** in-memory jti map is process-local (multi-instance needs `codeStore`); the loopback redirect allowlist permits any path or port on `127.0.0.1`/`[::1]` over `http:` only — `localhost` and `https:` loopback are deliberately not accepted (RFC 8252 §8.3: `localhost` is DNS-resolvable, not a loopback guarantee, and native-app loopback redirects are `http:` only); DCR binds a client to its own `redirect_uris` via a sealed assertion but does not verify the *registrant's identity* (opt into CIMD with `cimd: true`); CIMD DNS checks do not pin the TCP connect (see CIMD SSRF row).
 
+## Sessions and expiry
+
+The connector holds a token, never the app's login cookie. What each event does
+to it, with `signedTokenAuth`:
+
+| Event | What the connector sees |
+|-------|-------------------------|
+| The app session ends (cookie expires, logout) | Nothing. The next `/authorize` redirects to `loginUrl`; a token already issued keeps working |
+| The access token reaches its `ttlSeconds` (default 1 h) | `401` with `WWW-Authenticate: Bearer …, error="invalid_token"` (one code for a bad signature, expiry, wrong audience or an inactive user). With a refresh token the client renews silently; without one the user goes through the browser again |
+| The user is removed, disabled or signed out everywhere | With `isUserActive`: `401` on the next MCP request, `invalid_grant` on the next refresh. Without it: the access token works until it expires. `isUserActive` runs on every request, only `true` passes, a throw is a `500`; keep it cheap or cached, a call that hangs stalls the request |
+| The user's role or scopes change | The token keeps the scopes granted at issue until it expires. Enforce current permissions in the data layer |
+| The user sits on the consent page over 5 minutes, the session ends before Approve, or Approve is posted twice | A short page in the browser (JSON for a caller that does not ask for `text/html`), status `400`. `consent.render` customizes the consent screen only |
+| `secret` becomes a list `[new, old]` | Old tokens and DCR `client_id`s keep working, new ones are signed with `new`. Remove `old` once its tokens have expired; until then it can still forge |
+| `initialize` and `ping` | Succeed with no token or a bad one, so a "connected" status proves nothing. A `GET /mcp` with an `Authorization` header is answered `405` without checking it. Only `tools/list` and `tools/call` check the token |
+
+Access tokens are bearer tokens: not bound to a client and not revocable before
+they expire, so keep `ttlSeconds` short.
+
+**Refresh (`refreshTtlSeconds`).** Off unless set. Refresh tokens are signed, not
+stored; the only state is a single-use mark per token in `codeStore`.
+
+- **Lifetime.** Absolute: fixed when the authorization code is redeemed and never extended by refreshing, so
+  the user approves again after `refreshTtlSeconds`. The last access token issued
+  can still run up to `ttlSeconds` past that.
+- **Single use.** Each refresh token works once and is replaced. `codeStore.consume`
+  must be atomic (Redis `SET NX EX`, a unique-key insert) with a TTL no shorter than
+  the token. The process-local store does not hold across instances and Workers KV
+  is not atomic, so neither gives single use. Pass the same `codeStore` instance to
+  `signedTokenAuth` as the router uses; it refuses to start without one. One mark
+  per refresh stays until the grant's expiry, so size the store and rate-limit
+  `/token` per `client_id`.
+- **Binding.** To the user, client, resource and scopes of the consent. A refresh
+  may narrow scope, never widen it. Narrowing applies to that one access token: the
+  successor refresh token keeps the original grant's scopes, so the next refresh can
+  ask for them again (RFC 6749 §6). Every failure is one `invalid_grant`, and every
+  check that depends on the caller's input runs before the token is burned, so a
+  wrong client cannot spend the rightful holder's token.
+- **Size.** A refresh token is capped at 4096 characters. Issuing a longer one (a
+  user id of roughly 2.8 KB of ASCII, or a very long scope list) throws: at the
+  first issuance that is a `500` at `/token` after the authorization code was
+  spent, on every login for that user. Keep user ids short.
+- **No grace window.** A client that loses a refresh response and retries is logged
+  out and re-authorizes, as it is if minting fails after the old token was burned.
+- **No token family.** Replaying a used token is refused, but the successor a thief
+  obtained first stays valid until its expiry or until `isUserActive` turns false.
+  For family revocation use an opaque server-side store
+  (`examples/project-desk/src/tokens.ts`).
+- **`/revoke`** burns a refresh token only and answers `200` for anything else,
+  including an access token. A store failure on a valid refresh token is a `500`, so
+  revoking the current refresh token never reports success while it still works.
+  Revoking one that was already replaced by a refresh is a no-op: it answers `200`
+  and the successor keeps working (see "No token family").
+
 ## Rotating codeSecret
 
 `codeSecret` is the one secret behind auth codes, consent tickets, DCR
 client assertions, and (when `clientStore.secretHash` is used)
-confidential-client secret hashes. Before 1.2.0 it was a single string —
+confidential-client secret hashes. Before 2.0.0 it was a single string —
 rotating it invalidated every DCR-issued `client_id` still in a connector's
 hands and every stored `secretHash`, with no way to phase the change in.
 
-Since 1.2.0, `codeSecret` also accepts an array:
+Since 2.0.0, `codeSecret` also accepts an array:
 
 ```ts
 codeSecret: [newSecret, oldSecret],

package/docs/troubleshooting.md

@@ -14,6 +14,10 @@
 | Wrong user's data | Data query ignores authenticated identity | Filter by verified principal and tenant; never trust a tool argument for ownership. |
 | Switching login does not switch connector user | Connector retains its previously issued token | Disconnect and reauthorize with the intended account. |
 | Initialization works but tools fail | Initialize is public | Test authenticated `tools/call`; initialize alone proves no auth flow. |
+| `unauthorized_client: CIMD client_id could not be resolved` | The connector is told one generic error on purpose; the cause is in your audit sink | Read the `cimd_resolve_failed` entry: `reason` is `<code>[: detail] (authorize\|token/revoke)`. `http_status: status 403` = the document host refused the fetch; `auth_method_unsupported` = its document excludes `none`; `dns_failed (ENOTFOUND)` / `dns_unavailable` = no DNS from this runtime, pass `cimdLookup`; `blocked_address` = it resolves to a non-public address; `timeout` = the host did not answer, or stalled mid-body, within 10 s. Pass `cimdCache` so refresh does not re-fetch. |
+| Connector asks to reconnect about every hour | The access token expired and there is no refresh token (`signedTokenAuth` default) | Set `refreshTtlSeconds` with `codeStore` and `isUserActive`, or raise `ttlSeconds`. See [Sessions and expiry](security.md#sessions-and-expiry) |
+| `401` with `error="invalid_token"` | A bearer was sent and rejected, whatever the reason ([Sessions and expiry](security.md#sessions-and-expiry)) | Reconnect. Check expiry and audience, then your `isUserActive` |
+| Approve shows "This approval request expired" / "Your sign-in changed or expired" / "already submitted" | Ticket older than 5 minutes, the app session ended before Approve, or the form was posted twice | Start the connection again from the connector |
 | Client requests an unsupported protocol | Package supports the revisions in `src/mcp/protocol.ts` | Record negotiation; do not claim a live pass from a successful HTTP status alone. |
 
 See [security responsibilities](security.md) before replacing production token verification with example code. Share sanitized errors in an issue, never access tokens or session cookies.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-trellis",
-  "version": "2.2.0",
-  "description": "Add authenticated remote MCP connectors to existing TypeScript SaaS apps using your existing users and auth.",
+  "version": "3.1.0",
+  "description": "Plug your existing SaaS's users, auth and permissions into MCP with OAuth 2.1, so Claude, ChatGPT and other AI clients can act on your app as that user.",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -31,7 +31,10 @@
     "saas",
     "remote-mcp",
     "byo-auth",
-    "ai-connector"
+    "ai-connector",
+    "mcp-auth",
+    "nextjs",
+    "express"
   ],
   "types": "./dist/server.d.ts",
   "exports": {
@@ -81,7 +84,7 @@
     "node": ">=20"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.11",
+    "@biomejs/biome": "2.6.3",
     "@types/node": "^26.4.1",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2"

package/dist/auth/signed-token.d.ts

@@ -1,26 +0,0 @@
-/**
- * Convenience auth: one secret seals OAuth codes (via `codeSecret`) and
- * signs short-lived access tokens. Domain separation is HKDF, not luck —
- * access-token HMAC uses `mcp-trellis:signed-access-token:v1`, distinct from
- * the sealed-code and client-secret-hash labels.
- *
- * ponytail: stateless tokens cannot be revoked before `exp`. No
- * `refreshAccessToken` / `revokeToken` — `/revoke` stays unmounted and
- * refresh unadvertised. Upgrade: supply those ports plus a store (see
- * `examples/project-desk/src/tokens.ts`).
- */
-import type { McpAppAuth } from "../app-options.js";
-import type { CodeStore } from "../oauth/crypto/codes.js";
-import type { OAuthUser } from "../oauth/types.js";
-export type SignedTokenAuthOptions = {
-    secret: string;
-    resolveUser: (request: Request) => Promise<OAuthUser | null>;
-    loginUrl: (request: Request, nextPath: string) => string;
-    /** Access-token lifetime in seconds. Default 3600. Must be finite and > 0. */
-    ttlSeconds?: number;
-    /** Passthrough — production still needs a shared store across instances. */
-    codeStore?: CodeStore;
-};
-/** Builds a complete `McpAppAuth` from one secret plus your session resolver. */
-export declare const signedTokenAuth: (options: SignedTokenAuthOptions) => McpAppAuth;
-//# sourceMappingURL=signed-token.d.ts.map