mcpose 2.1.1 → 3.1.0

package/README.md

@@ -2,30 +2,17 @@
 
 [![npm](https://img.shields.io/npm/v/mcpose)](https://www.npmjs.com/package/mcpose)
 [![license](https://img.shields.io/npm/l/mcpose)](https://github.com/amir-gorji/mcpose/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
-[![CI](https://github.com/amir-gorji/mcpose/actions/workflows/deploy.yml/badge.svg)](https://github.com/amir-gorji/mcpose/actions/workflows/deploy.yml)
+[![node](https://img.shields.io/node/v/mcpose)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-blue)](https://www.typescriptlang.org/)
+[![CI](https://github.com/amir-gorji/mcpose/actions/workflows/ci.yml/badge.svg)](https://github.com/amir-gorji/mcpose/actions/workflows/ci.yml)
 
 **The composable middleware proxy for MCP.**
 
-mcpose sits between a **client** (an LLM or agent) and an **upstream** MCP server, forwarding every tool, resource, and `list_tools` call through a **pipeline** of composable middleware. It is a transparent proxy: the client talks to mcpose exactly as it would talk to the upstream, while you intercept, transform, hide, or govern calls in between, without touching the upstream server.
+mcpose sits between a **client** (an LLM or agent) and an **upstream** MCP server, forwarding every tool, resource, and `list_tools` call through a **pipeline** of composable middleware.
+It is a transparent proxy: the client talks to mcpose exactly as it would talk to the upstream, while you intercept, transform, hide, or govern calls in between, without touching the upstream server.
 
-## When to reach for it
-
-- Add cross-cutting behavior (logging, PII redaction, identity resolution, rate limiting) to an MCP server you don't own.
-- Hide or gate specific tools/resources per caller.
-- Resolve a caller **identity** once per session and stamp it on every request.
-- Lay the foundation for compliance-grade audit trails with [`@mcpose/audit`](https://www.npmjs.com/package/@mcpose/audit).
-
-If you only need the audit chain or the compliance test helpers, see the ecosystem packages below; they build on this core.
-
-## Features
-
-- **Transparent proxy**: wrap any upstream MCP server without modifying it.
-- **Composable middleware pipeline** with a predictable onion model: each layer runs before *and* after the inner pipeline.
-- **Per-session identity resolution**: resolve a caller once, then stamp the `Identity` on every request in the session.
-- **Tool and resource governance**: hide or gate specific tools/resources per caller, or pass them straight through the pipeline.
-- **Dual transport**: serve over stdio (lightweight, process-local) or HTTP/SSE with mTLS, session limits, and SSE reconnect replay.
-- **ESM-first**: ships native ESM with first-class TypeScript types.
+This is the core package.
+For tamper-evident audit trails see [`@mcpose/audit`](https://www.npmjs.com/package/@mcpose/audit); for compliance assertions see [`@mcpose/testing`](https://www.npmjs.com/package/@mcpose/testing).
 
 ## Table of Contents
 
@@ -33,19 +20,47 @@ If you only need the audit chain or the compliance test helpers, see the ecosyst
 - [Features](#features)
 - [Install](#install)
 - [Quick start](#quick-start)
+- [Serving over HTTP/SSE](#serving-over-httpsse)
+  - [Surviving a restart](#surviving-a-restart)
 - [Core concepts](#core-concepts)
 - [API surface](#api-surface)
+  - [Backend config (`BackendConfig`)](#backend-config-backendconfig)
+  - [Proxy options (`ProxyOptions`)](#proxy-options-proxyoptions)
+  - [HTTP options (`HttpProxyOptions`)](#http-options-httpproxyoptions)
+  - [Context and identity](#context-and-identity)
+  - [Rejection reasons](#rejection-reasons)
+  - [Test helpers: `mcpose/testing`](#test-helpers-mcposetesting)
 - [The mcpose ecosystem](#the-mcpose-ecosystem)
 - [Documentation](#documentation)
 - [License](#license)
 
+## When to reach for it
+
+- Add cross-cutting behavior (logging, PII redaction, identity resolution, rate limiting) to an MCP server you do not own.
+- Hide or gate specific tools and resources per caller, with a structured reason rather than an opaque error.
+- Resolve a caller **identity** once per session and read it from every request in that session.
+- Lay the foundation for compliance-grade audit trails with [`@mcpose/audit`](https://www.npmjs.com/package/@mcpose/audit).
+
+If you own the single MCP server and need one hook in one place, a request handler in that server is simpler than a proxy hop.
+mcpose earns its keep when the concern is cross-cutting, the server is not yours, or the behavior has to be tested independently of any one server.
+
+## Features
+
+- **Transparent proxy**: wrap any upstream MCP server without modifying it.
+- **Composable middleware pipeline** with a predictable onion model: each layer runs before *and* after the layers inside it.
+- **Per-session identity resolution**: resolve a caller once, then read the same `Identity` from every request in the session.
+- **Tool and resource governance**: hide tools, gate them per caller, or pass them straight through the pipeline.
+- **Dual transport**: stdio (lightweight, process-local) or HTTP/SSE with mTLS, session limits, and SSE reconnect replay.
+- **ESM-first**: native ESM with first-class TypeScript types, and no runtime dependencies beyond the MCP SDK.
+
 ## Install
 
 ```bash
-npm install mcpose
+npm install mcpose @modelcontextprotocol/sdk
 ```
 
-Requires Node.js 18+. Ships ESM with TypeScript types.
+Requires Node.js 20+.
+`@modelcontextprotocol/sdk` (`^1.17.0`) is a peer dependency you install yourself.
 
 ## Quick start
 
@@ -55,7 +70,7 @@ Connect to an upstream over stdio, add one middleware, and serve the proxy:
 import { createBackendClient, startProxy } from 'mcpose';
 import type { ToolMiddleware } from 'mcpose';
 
-// 1. Connect to the upstream MCP server (stdio)
+// 1. Connect to the upstream MCP server (stdio).
 const backend = await createBackendClient({
   command: 'node',
   args: ['/path/to/backend-server.mjs'],
@@ -69,13 +84,15 @@ const loggingMW: ToolMiddleware = async (req, next) => {
   return result;
 };
 
-// 3. Start the proxy on stdio
-await startProxy(backend, {
-  toolMiddleware: [loggingMW],
-});
+// 3. Start the proxy on stdio.
+await startProxy(backend, { name: 'my-proxy', toolMiddleware: [loggingMW] });
 ```
 
-To serve over HTTP instead, with identity resolution, mTLS, session limits, and SSE reconnect replay, use `startHttpProxy`:
+Point your MCP client at this process instead of the upstream, and every tool call flows through `loggingMW`.
+
+## Serving over HTTP/SSE
+
+`startHttpProxy` adds per-session identity resolution, mTLS, session limits, and SSE reconnect replay:
 
 ```ts
 import { createBackendClient, startHttpProxy } from 'mcpose';
@@ -84,9 +101,9 @@ import { createBackendClient, startHttpProxy } from 'mcpose';
 //   extractJwt: a resolveIdentity function returning an Identity from the request
 const backend = await createBackendClient({ url: 'http://localhost:9000/mcp' });
 
-await startHttpProxy(
+const server = await startHttpProxy(
   backend,
-  { toolMiddleware: [loggingMW] },
+  { name: 'my-proxy', toolMiddleware: [loggingMW] },
   {
     port: 3000,
     resolveIdentity: extractJwt, // stamped on every ProxyContext in the session
@@ -95,26 +112,92 @@ await startHttpProxy(
 );
 ```
 
+The returned `http.Server` is already listening; call `.close()` to shut down.
+Active proxy sessions are closed before the underlying server finishes closing.
+
+Behavior worth knowing before you deploy it:
+
+- **The proxy binds loopback by default.** `host` defaults to `127.0.0.1`, DNS-rebinding protection is on for loopback binds with `allowedHosts` / `allowedOrigins` derived from the effective bind address and real listening port, and a non-loopback bind without `resolveIdentity` reports a startup warning through `onError`.
+  See [ADR-0005](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0005-loopback-bind-by-default.md).
+- **Session creation is restricted.** Only an `initialize` POST can create a session; a session-less GET or DELETE returns 400.
+- **Sessions can be re-validated per request.** `validateSession(req, { sessionId, identity })` runs on every routed request; return `false` or throw for a 401.
+  A throw is reported through `onError` first, so a broken validator shows up as an error rather than as a wave of 401s: the same is true of `onRequest` and `resolveIdentity`.
+  Use it to bind a session to its original credential, so a leaked `mcp-session-id` alone cannot take a session over.
+- **Credential headers never reach middleware.** `authorization`, `proxy-authorization`, `cookie`, `set-cookie`, and `x-api-key` are stripped from `ProxyContext.headers`, and with that from anything middleware logs.
+  `resolveIdentity` reads the raw `http.IncomingMessage`, so it still sees them.
+- **`onSessionClosed` fires on every session-end path**: client DELETE, TTL expiry, and server shutdown, so audit manifests flush in all three cases.
+  A returned promise is awaited, and `server.close()` does not complete until every session's hook has settled, so `await` the close before exiting the process.
+  A hook that throws or rejects is reported through `onError` and never breaks teardown.
+- **Limit breaches are structured.** 503 (session limit) and 413 (body limit) responses carry `error.data.rejectionReason` set to `SESSION_LIMIT` / `BODY_LIMIT`.
+- **SSE replay is scoped per stream and per session.** The in-memory store replays only events from the reconnecting stream; an unknown or already-evicted `Last-Event-ID` replays nothing.
+  Stream ids are namespaced as `<sessionId>:<streamId>` before they reach any `EventStore`, so one store shared by every session keeps their histories apart, and a `Last-Event-ID` presented from another session is rejected with a 400 rather than replayed.
+- **Sessions live in the process unless you share them.** Without a `sessionRegistry`, a resume against a restarted proxy or another instance is a 404 no matter how durable the event store is, because the session id itself is unknown there.
+  With one, a record of every session is written before the initialize response goes out, and an `mcp-session-id` this instance does not hold is looked up and rebuilt from it.
+  See [Surviving a restart](#surviving-a-restart).
+
+### Surviving a restart
+
+A durable `eventStore` keeps the replay history; a `sessionRegistry` keeps the session.
+[`@mcpose/store-redis`](https://github.com/amir-gorji/mcpose/blob/main/packages/store-redis/README.md) and [`@mcpose/store-postgres`](https://github.com/amir-gorji/mcpose/blob/main/packages/store-postgres/README.md) ship both halves, and you want them from the same backing store:
+
+```ts
+await startHttpProxy(backend, { name: 'my-proxy' }, {
+  eventStore: createRedisEventStore(redis),
+  sessionRegistry: createRedisSessionRegistry(redis),
+});
+```
+
+What a `SessionRegistry` holds is a `SessionRecord`: the client's `initialize` params verbatim, the `Identity` that `resolveIdentity` produced, and the deadline the session was given at creation.
+The record is plain JSON, so an `Identity` whose `claims` do not survive a JSON round-trip will not come back the way it went in.
+The rules that follow from that, per [ADR-0021](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0021-session-resume-replays-the-initialize.md):
+
+- **A resumed session negotiates what the original did.** The instance that resumes it replays the stored `initialize` through the SDK's own request path, so protocol version, client capabilities and client info are what the client sent, and the SDK's Host and Origin checks run against the resuming request.
+  If the SDK refuses that replay, the client gets the SDK's answer, not a 404.
+- **Identity is carried, not re-resolved.** `resolveIdentity` ran once, at initialize; `validateSession` still runs on every routed request, on the resumed instance too, so a leaked id is no easier to use after a restart.
+- **The deadline is fixed at creation.** A resumed session gets what is left of its original `sessionTtlMs`, never a fresh one, so a session cannot outlive its bound by hopping between instances.
+- **Client DELETE and TTL expiry delete the record; server shutdown keeps it.** A session that outlives the process is the point, and its deadline expires it on its own.
+  `onSessionClosed` fires on the shutting-down instance as before, and again on whichever instance finally closes the session.
+- **`maxSessions` is per instance.** It bounds the memory each process holds, so a resume against a full instance is a 503 and the record stays for another one.
+- **A registry failure fails closed.** An initialize whose record cannot be written is rejected (a 400 from the SDK, with the real error on `onError` and nothing about the backing store in the response), and a lookup that fails is a 500.
+  Sessions this instance already holds are never affected: the registry is read only for an id it does not know.
+
+Two things a registry does not do.
+It does not carry the audit chain: `@mcpose/audit` keeps its per-session state in memory, so the shutting-down instance seals its manifest and the resuming instance starts a new chain under the same session id.
+And it does not make a fleet without sticky routing safe from double work: two instances can both hold a live copy of one session, and both will fire `onSessionClosed` for it.
+
 ## Core concepts
 
-- **Middleware**: a single function `(req, next, ctx) => Promise<result>`. Call `next(req)` to delegate downstream; transform the request before, or the response after. Middlewares nest onion-style.
-- **Pipeline**: middlewares passed to `ProxyOptions` run in response-processing order (first = innermost). `[piiMW, auditMW]` redacts before it audits.
-- **ProxyContext**: per-request metadata threaded through the pipeline: `requestId`, `transport`, `sessionId`, resolved `identity`, and the agent `delegatedFrom` chain.
+- **Middleware**: a single function `(req, next, ctx) => Promise<result>`.
+  Call `next(req)` to delegate inward; transform the request before, or the response after.
+  Middlewares nest onion-style.
+- **Pipeline**: middleware passed to `ProxyOptions` runs in **response-processing order**, so the first element processes the response first and is therefore the innermost layer.
+  `[piiMW, auditMW]` redacts before it audits.
+  Reversing that order fails silently: `[auditMW, piiMW]` fills the audit store with unredacted payloads while the client still receives redacted data; see [the array order rule](https://github.com/amir-gorji/mcpose#array-order-the-one-surprising-rule).
+  Note that `compose()` uses the opposite, outermost-first convention, so the two are not interchangeable.
+  See [ADR-0002](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0002-proxy-options-array-response-processing-order.md).
+- **ProxyContext**: per-request metadata threaded through the pipeline: `requestId`, `transport`, `sessionId`, the resolved `identity`, the `delegatedFrom` delegation chain, and the `proxy` instance identity.
 
 ## API surface
 
 | Export | Purpose |
 |---|---|
 | `createBackendClient(config)` | Connect to an upstream over stdio (`command`/`args`) or HTTP (`url`). |
-| `startProxy(backend, options?)` | Serve the proxy over **stdio**. |
-| `startHttpProxy(backend, proxyOptions?, httpOptions?)` | Serve over **HTTP/SSE**: identity, mTLS, sessions, reconnect replay. |
-| `createProxyServer(backend, options?)` | Build the underlying `Server` without binding a transport. |
-| `compose(middlewares)` | Compose middlewares into one (outermost-first). |
-| `createProxyContext(overrides?)` | Construct a `ProxyContext` (useful in tests). |
+| `startProxy(backends, options)` | Serve the proxy over **stdio**. Resolves when the transport closes. |
+| `startHttpProxy(backends, proxyOptions, httpOptions?)` | Serve over **HTTP/SSE**: identity, mTLS, sessions, reconnect replay. Resolves with a listening `http.Server`. |
+| `createProxyServer(backends, options)` | Build the underlying `Server` without binding a transport. Throws on a blank `options.name` or if a backend is not connected, so a mis-wired proxy fails at startup rather than on the first call. |
+| `compose(middlewares)` | Compose middleware into one, **outermost-first**. |
+| `markPassThroughObserver(mw)` | Return a new middleware that still runs for `passThroughTools`. For observers only, never transformers. |
+| `rejectionMcpError(reason, code, message)` | Build an `McpError` carrying a `RejectionReason` in `error.data`. |
+| `createProxyContext(overrides?)` | Construct a `ProxyContext`. Useful in tests. |
 | `createInMemoryEventStore()` | Default SSE reconnect event store; swap for a `PersistentEventStore`. |
-| `hasToolContent(result)` | Type guard for tool-call results. |
+| `hasToolContent(result)` | Type guard narrowing `CompatibilityCallToolResult` to `CallToolResult`. |
+| `mapToolResult(result, handlers)` | Map every payload channel of a tool result (text blocks, non-text blocks, `structuredContent`) through required handlers, so a redaction cannot silently miss one. |
+| `dispatcherAwareBlock(options)` | `HiddenToolPredicate` blocking hidden tools both directly and through dispatcher (meta) tools. Fail-closed. |
+| `sanitizeToolDescriptions(options?)` | `ListToolsMiddleware` stripping URLs and configured patterns from tool and schema descriptions, because the catalog is an egress channel into model context. |
+
+**Key types:** `Middleware<Req, Res>`, `ToolMiddleware`, `ResourceMiddleware`, `PromptMiddleware`, `ListToolsMiddleware`, `ToolResultHandlers`, `ProxyContext`, `ProxyIdentity`, `Identity`, `BackendConfig`, `Backends`, `ProxyOptions`, `HttpProxyOptions`, `LocalTool`, `HiddenToolPredicate`, `DispatcherAwareBlockOptions`, `SanitizeToolDescriptionsOptions`, `RejectionReason`, `TelemetryEvent`, `ToolCallTelemetryEvent`, `BackendDegradedTelemetryEvent`, `PersistentEventStore`.
 
-**Key types:** `Middleware<Req, Res>`, `ToolMiddleware`, `ResourceMiddleware`, `ListToolsMiddleware`, `ProxyContext`, `Identity`, `BackendConfig`, `ProxyOptions`, `HttpProxyOptions`, `RejectionReason`, `TelemetryEvent`, `PersistentEventStore`.
+`PersistentEventStore` is an alias of the SDK's `EventStore` type, so any SDK-compatible store plugs in directly.
 
 ### Backend config (`BackendConfig`)
 
@@ -122,14 +205,13 @@ await startHttpProxy(
 
 | Field | Mode | Description |
 |---|---|---|
-| `command` | stdio | Shell command to spawn the backend (e.g. `"node"`). |
-| `args` | stdio | Args passed to `command` (e.g. `["/path/to/server.mjs"]`). |
+| `command` | stdio | Executable to spawn for the backend (e.g. `"node"`). |
+| `args` | stdio | Arguments passed to `command` (e.g. `["/path/to/server.mjs"]`). |
 | `url` | HTTP/SSE | URL of a running backend. Takes precedence over stdio. |
-| `headers` | HTTP/SSE | Custom HTTP headers sent on every request to the backend. |
-| `authProvider` | HTTP/SSE | `OAuthClientProvider` for interactive/browser OAuth and transparent token refresh. |
+| `headers` | HTTP/SSE | Custom headers sent on every request to the backend. Ignored in stdio mode. |
+| `authProvider` | HTTP/SSE | `OAuthClientProvider` for interactive OAuth with transparent token refresh. Ignored in stdio mode. |
 
-`headers` is HTTP/SSE only and is ignored in stdio mode.
-Use it to authenticate with the upstream, for example an API key or bearer token.
+Use `headers` to authenticate with the upstream using a static credential:
 
 ```ts
 const backend = await createBackendClient({
@@ -138,9 +220,8 @@ const backend = await createBackendClient({
 });
 ```
 
-For backends that require OAuth rather than a static token, pass an `authProvider`.
-mcpose forwards it to the HTTP/SSE transport, which runs the MCP OAuth flow (interactive/browser authorization with transparent token refresh), so you don't manage tokens yourself.
-Like `headers`, it is HTTP/SSE only and ignored in stdio mode.
+For upstreams that require OAuth rather than a static token, pass an `authProvider`.
+mcpose forwards it to the HTTP/SSE transport, which runs the MCP OAuth flow (browser authorization plus transparent refresh) so you do not manage tokens yourself.
 
 ```ts
 import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth';
@@ -149,39 +230,357 @@ const authProvider: OAuthClientProvider = {
   // redirectUrl, clientMetadata, and the token/authorization-code callbacks
 };
 
-const backend = await createBackendClient({
-  url: 'https://mcp.example.com/sse',
-  authProvider,
-});
+const backend = await createBackendClient({ url: 'https://mcp.example.com/sse', authProvider });
+```
+
+See [`oauth-upstream-client.ts`](https://github.com/amir-gorji/mcpose/blob/main/examples/oauth-upstream-client.ts) for a complete implementation.
+
+### Many upstreams: mesh mode (`Backends`)
+
+`createProxyServer`, `startProxy`, and `startHttpProxy` all take a `Backends`: either a single `BackendClient`, which is the 1:1 proxy described everywhere else in this document, or a `Record<string, BackendClient>` of named backends, which is **mesh mode**.
+
+```ts
+await startProxy(
+  {
+    crm: await createBackendClient({ url: 'https://crm.internal/mcp' }),
+    docs: await createBackendClient({ command: 'node', args: ['./docs-server.mjs'] }),
+  },
+  { name: 'my-proxy', hiddenTools: ['crm__delete_account'] },
+);
+```
+
+The record keys are **backend keys**, and a mesh exposes every upstream tool and prompt as `<backendKey>__<name>`: `crm__lookup`, `docs__search`.
+A key must be non-empty and must not itself contain `__`, so the first separator in an exposed name always splits key from upstream name, even for an upstream name that contains one.
+An empty record or an invalid key throws at `createProxyServer` (and at `startHttpProxy`, before the first session).
+
+| Behaviour | Mesh mode |
+|---|---|
+| Routing | By the `<backendKey>__` prefix, resolved at the innermost `next`, so middleware can re-route deliberately. |
+| Un-namespaced or unknown prefix | Rejected with `MethodNotFound` (`InvalidRequest` for a resource) and `BACKEND_UNROUTABLE`, thrown inside the pipeline so audit records it. There is no "resolve it if only one backend has that name" fallback. |
+| Configuration | Global and matched against the **namespaced** name. `hiddenTools: ['crm__delete_account']` hides one tool on one upstream; a `HiddenToolPredicate` can hide a whole backend with `name.startsWith('crm__')`. |
+| One backend down | `tools/list`, `prompts/list`, and `resources/list` return the live backends' entries and report a `backend_degraded` telemetry event naming the key. A call routed to a down backend fails only that call. |
+| Audit | One session and one pipeline span the mesh. Backend attribution comes from the namespaced `tool` field plus `ProxyContext.proxy`. |
+| Local tools | Not namespaced, because they belong to the proxy. A local tool named `crm__lookup` shadows the upstream tool exposed under that name. |
+| Capabilities | The union across backends, plus the `localTools` rule. `listChanged` is advertised when any backend advertises it, and every backend's notification is forwarded. |
+| Lists | Unpaginated: cursors are per-backend, so a mesh drains every backend and returns one complete page with no `nextCursor`. |
+| Resources | Exposed as `mcpose://<backendKey>/<uri>`, the upstream URI appended verbatim, so two backends serving the same URI never collide. `resources/read` accepts only that form, strips the prefix, and forwards the original URI; anything else is `BACKEND_UNROUTABLE`. `hiddenResources` and `passThroughResources` match the exposed URI ([ADR-0022](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0022-mesh-resources-under-the-mcpose-scheme.md)). |
+
+Degradation covers runtime failures, not startup: every backend in the record must already be connected, and `createProxyServer` throws and names the key of one that is not, exactly as it does for a single unconnected backend.
+Without an `onTelemetry` sink a degraded mesh is invisible, so wire one when you run a mesh.
+Backend keys are identifiers (`[A-Za-z0-9][A-Za-z0-9._-]*`, never containing `__`), because a key is spliced into tool names and into the authority of a resource URI.
+See [ADR-0013](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0013-multi-backend-composition.md) and [ADR-0022](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0022-mesh-resources-under-the-mcpose-scheme.md).
+
+### Proxy options (`ProxyOptions`)
+
+<details>
+<summary>Show the <code>ProxyOptions</code> interface</summary>
+
+```ts
+interface ProxyOptions {
+  name:                  string;  // Required, non-blank
+  version?:              string;
+  toolMiddleware?:       ReadonlyArray<ToolMiddleware>;
+  resourceMiddleware?:   ReadonlyArray<ResourceMiddleware>;
+  promptMiddleware?:     ReadonlyArray<PromptMiddleware>;
+  listToolsMiddleware?:  ReadonlyArray<ListToolsMiddleware>;
+  passThroughTools?:     ReadonlyArray<string>;
+  passThroughResources?: ReadonlyArray<string>;
+  hiddenTools?:          ReadonlyArray<string> | HiddenToolPredicate;
+  hiddenResources?:      ReadonlyArray<string>;
+  localTools?:           ReadonlyArray<LocalTool>;
+  stripRequestMeta?:     boolean;  // Default: true
+  stripResultMeta?:      boolean;  // Default: true
+  onTelemetry?:          (event: TelemetryEvent) => unknown;
+}
+
+interface LocalTool {
+  tool: Tool;  // advertised in tools/list
+  handler: (params: CallToolRequestParams, context: ProxyContext) => Promise<CallToolResult>;
+}
+```
+
+</details>
+
+- `name` and `version` set the MCP server identity returned in `initialize`.
+  `name` is required and an empty or whitespace-only one throws at `createProxyServer` (and at `startHttpProxy`, before the first session).
+  It is also recorded as provenance on every `ProxyContext`, audit event, and `ReplayManifest` ([ADR-0012](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0012-proxy-identity-recorded-as-provenance.md)), so a default would record a whole fleet under one name and give a trail attribution in appearance only.
+  `version` keeps its default of the mcpose library version; set your own when you ship a proxy.
+- `hiddenTools` / `hiddenResources` reject calls with a structured [`RejectionReason`](#rejection-reasons) in the MCP error `data` field.
+  The rejection is thrown *inside* the pipeline, so observing middleware such as audit records it; the upstream is never called.
+- `hiddenTools` also accepts a `HiddenToolPredicate` (`(name, args) => boolean`), because a name array cannot see through a dispatcher (meta-tool) that takes the real tool name as an argument.
+  The predicate receives `undefined` args during list filtering and always an object at call time, so it can keep the dispatcher listed while failing closed on a malformed call.
+  `dispatcherAwareBlock({ tools, dispatchers, argPath })` implements the common case and blocks whenever the target name is missing or is not a string.
+  See [ADR-0006](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0006-hidden-tools-accept-a-predicate.md).
+- `sanitizeToolDescriptions({ patterns?, replacement? })` builds a `ListToolsMiddleware` that strips http(s) URLs, plus any configured literal strings or regexes, from tool descriptions and from `description` fields nested in `inputSchema` / `outputSchema`, because the catalog is forwarded verbatim into model context and real upstreams leak org slugs and internal hostnames there.
+  Names, titles, and schema structure stay intact because clients route on them; place it last in `listToolsMiddleware` so it sanitizes the output of other list middleware and local tools.
+  See [ADR-0010](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0010-tool-catalog-egress-sanitizer.md).
+- `promptMiddleware` runs around every `prompts/get`, in both 1:1 and mesh mode, in the same response-processing order as the other middleware arrays.
+  Mesh routing and the `BACKEND_UNROUTABLE` rejection for an unroutable prompt name happen inside the innermost `next`, so an observing middleware such as `@mcpose/audit`'s `promptMiddleware` records every prompt call and every rejection.
+  `prompts/list` has no pipeline yet, so there is no prompt equivalent of `hiddenTools` or `passThroughTools`.
+  See [ADR-0014](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0014-prompt-calls-run-a-pipeline-and-are-audited.md).
+- `passThroughTools` / `passThroughResources` skip transforming middleware, but middleware wrapped in `markPassThroughObserver()` still runs for them.
+  A tool that is both hidden and pass-through stays hidden.
+- `localTools` are tools the proxy implements itself.
+  They appear in `tools/list` (first page only, so pagination does not duplicate them), route to their handler instead of the upstream, and still run through the full `toolMiddleware` pipeline, so audit and redaction apply to them.
+  Precedence: `hiddenTools` beats a local tool, a local tool beats (and shadows) an upstream tool of the same name, and `passThroughTools` does not apply to local tools.
+  The proxy advertises the `tools` capability when `localTools` is non-empty even if the upstream has none, and a duplicate local tool name throws at `createProxyServer`.
+  A handler runs with the proxy's own credentials, so attribute any outbound calls it makes via `outboundDelegationChain(context)`, and bound a call with `AbortSignal.any([ctx.signal, AbortSignal.timeout(ms)].filter((s) => s !== undefined))` inside the handler.
+  See [ADR-0007](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0007-local-tools-run-the-full-pipeline.md) and [ADR-0011](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0011-proxy-originated-call-attribution.md).
+- `stripRequestMeta` (default `true`) removes `params._meta` from every forwarded request, tool calls, resource reads, list and prompt calls alike, because MCP clients put correlation identifiers there (VS Code sends `progressToken`, a W3C `traceparent`, and `vscode/conversationId`) and the upstream is frequently a third party.
+  The strip happens at the proxy boundary before the pipeline, so middleware can still add `_meta` deliberately, and it applies to pass-through tools too; disable only globally with `stripRequestMeta: false`.
+  Progress relay is unaffected: the proxy reads the client's progress token from the request `extra`, and the SDK client stamps its own token on the upstream request.
+  See [ADR-0008](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0008-strip-request-meta.md).
+- `stripResultMeta` (default `true`) is the response-direction mirror: top-level `_meta` is removed from every result returned from the upstream, because upstreams stamp correlation identifiers there (the SDK stamps `io.modelcontextprotocol/related-task`) and the client is a third party to them.
+  The strip happens at the upstream boundary inside the innermost `next`, so middleware sees the stripped result and middleware-added `_meta` still reaches the client.
+  Local tool results and nested `_meta` (per-tool in `tools[]`, per-block in `content`) are untouched; disable only globally with `stripResultMeta: false`.
+  See [ADR-0009](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0009-strip-result-meta.md).
+- `onTelemetry` receives a `TelemetryEvent`, a union discriminated on `type`.
+  A `'tool_call'` event fires after every tool call with timing, outcome, tool name, and identity; results with `isError: true` are reported as outcome `'error'`.
+  A `'backend_degraded'` event fires when one backend of a mesh drops out of a list call (`tools/list`, `prompts/list`, or `resources/list`), naming the backend key, the method, and the error.
+  Both variants carry an optional `proxy: ProxyIdentity`, the same frozen `{ name, version }` stamped on `ProxyContext` (ADR-0012), so a fleet of proxies feeding one telemetry sink can attribute events to an instance.
+  A sink that throws, or whose returned promise rejects, is logged but never fails the call; the sink is not awaited, so a slow one does not delay it either.
+  [`@mcpose/otel`](https://github.com/amir-gorji/mcpose/blob/main/packages/otel/README.md) maps both variants onto OpenTelemetry spans if you do not want to write the sink yourself.
+
+### HTTP options (`HttpProxyOptions`)
+
+<details>
+<summary>Show the <code>HttpProxyOptions</code> interface and <code>startHttpProxy()</code> signature</summary>
+
+```ts
+interface HttpProxyOptions {
+  port?: number;         // Default: 3000
+  host?: string;         // Default: '127.0.0.1' (loopback); non-loopback is a deliberate opt-in
+  path?: string;         // Default: '/mcp'
+  onRequest?: (req: http.IncomingMessage, res: http.ServerResponse) => boolean | Promise<boolean>;
+  onError?: (err: unknown) => unknown;
+  maxBodyBytes?: number; // Default: 4 MB (4,194,304); excess returns 413; Infinity opts out
+  maxSessions?: number;  // Default: 1000; excess requests return 503; Infinity opts out
+  sessionTtlMs?: number; // Default: 30 minutes (1,800,000); max finite 2,147,483,647; Infinity opts out
+  /** Resolves caller identity once per session. A throw reports through onError and aborts the session with 401. */
+  resolveIdentity?: (req: http.IncomingMessage) => Identity | Promise<Identity>;
+  /** Re-validates an existing session on every routed request. Return false, or throw (reported through onError), for a 401. */
+  validateSession?: (
+    req: http.IncomingMessage,
+    session: { sessionId: string; identity?: Identity },
+  ) => boolean | Promise<boolean>;
+  /** mTLS: Node's https.ServerOptions (key, cert, ca, requestCert, rejectUnauthorized). */
+  tlsOptions?: https.ServerOptions;
+  /** SSE reconnect replay store. Defaults to in-memory. Pass null to disable. */
+  eventStore?: PersistentEventStore | null;
+  /** Shared record of live sessions, so a resume survives a restart or reaches another instance. */
+  sessionRegistry?: SessionRegistry;
+  /** Called when a session closes: client DELETE, TTL expiry, or server shutdown. A returned promise is awaited. */
+  onSessionClosed?: (sessionId: string) => unknown;
+  /** Hosts allowed in the Host header. Default: derived from the bind address and real port on loopback. */
+  allowedHosts?: string[];
+  /** Origins allowed in the Origin header. Default: derived, matching allowedHosts. */
+  allowedOrigins?: string[];
+  /** SDK Host/Origin checks. Default: true on a loopback bind, false otherwise. */
+  enableDnsRebindingProtection?: boolean;
+}
+
+function startHttpProxy(
+  backend: BackendClient,
+  options: ProxyOptions,
+  httpOptions?: HttpProxyOptions,
+): Promise<http.Server>;
+```
+
+</details>
+
+`httpOptions` is meaningful only for HTTP/SSE transport; omit it when serving over stdio.
+
+**Session lifecycle is bounded by default.**
+`maxSessions` defaults to 1000 and `sessionTtlMs` defaults to 30 minutes, the same safe-by-default posture `maxBodyBytes` already had at 4 MB.
+Unlimited sessions that never expire are a memory exhaustion path open to any client that can initialize, and each live session also pins whatever per-session state a host keeps beside it.
+Both are overridable, and `Infinity` is the explicit opt-out for either.
+`maxSessions: 0` is not an opt-out: it already means "reject every session", so it keeps that meaning.
+A `maxSessions` below zero, a `sessionTtlMs` of zero or below, or a `maxBodyBytes` that is below zero or is not a number at all, throws at startup rather than quietly enforcing something other than what the option reads as.
+So does a finite `sessionTtlMs` above 2,147,483,647 ms (about 24.8 days), Node's maximum timer delay: `setTimeout` would otherwise clamp it to 1 ms and expire every session immediately, so anything longer must use `Infinity`.
+A `maxBodyBytes` of `NaN`, which is what `Number(process.env.MAX_BODY_BYTES)` gives for an unset key, compares false against every body size, so mcpose reads and serves a body far larger than the cap it was configured with instead of answering 413.
+`maxBodyBytes: 0` and `maxBodyBytes: Infinity` keep their literal meanings: reject every POST body, and no cap.
+
+This is a behavior change: both options used to be opt-in, so a proxy started with defaults accepted unlimited sessions that never expired.
+A long-lived deployment that relied on that must now pass `sessionTtlMs: Infinity`, `maxSessions: Infinity`, or values that match its own limits.
+TTL expiry fires `onSessionClosed`, so a host holding per-session state should wire that hook rather than assume sessions only end on a client DELETE.
+`allowedHosts`, `allowedOrigins`, and `enableDnsRebindingProtection` are forwarded to the SDK transport, which only validates against a non-empty list; that is why mcpose derives enforcing defaults for a loopback bind instead of shipping an inert flag.
+An explicit `allowedHosts` or `allowedOrigins` is used verbatim and never merged with the derived list.
+See [ADR-0005](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0005-loopback-bind-by-default.md) and the network posture section of [`SECURITY.md`](https://github.com/amir-gorji/mcpose/blob/main/SECURITY.md).
+The behavioral notes in [Serving over HTTP/SSE](#serving-over-httpsse) apply to all of these.
+
+### Context and identity
+
+Every middleware receives a normalized `ProxyContext` as its third argument.
+
+<details>
+<summary>Show <code>ProxyContext</code>, <code>Identity</code>, and the middleware types</summary>
+
+```ts
+interface ProxyContext {
+  requestId: string;
+  transport: 'stdio' | 'http';
+  sessionId?: string;
+  headers?: Readonly<Record<string, string>>;
+  signal?: AbortSignal;
+  /** Resolved caller identity. Present when resolveIdentity is configured. */
+  identity?: Identity;
+  /** Agent delegation chain, oldest-first. Extracted from the inbound request, or stamped by the host. */
+  delegatedFrom?: Identity[];
+  /** The proxy instance handling this request. Stamped by createProxyServer. */
+  proxy?: ProxyIdentity;
+  /** The policy decision for this call, stamped by @mcpose/policy. */
+  policy?: PolicyDecision;
+}
+
+interface PolicyDecision {
+  decision: 'allow' | 'deny';
+  ruleId?: string;   // the rule that produced the decision, when one did
+  reason?: string;   // the RejectionReason accompanying a denial
+}
+
+interface ProxyIdentity {
+  name: string;     // ProxyOptions.name, required and non-blank
+  version: string;  // ProxyOptions.version, defaulted to the mcpose library version
+}
+
+interface Identity {
+  sub: string;
+  type: 'human' | 'agent' | 'service';
+  displayName?: string;
+  roles: string[];
+  claims: Record<string, unknown>;
+  resolvedAt: string;  // ISO 8601
+  source: 'jwt' | 'mtls' | 'apikey' | 'custom';
+}
+
+type Middleware<Req, Res> = (
+  req: Req,
+  next: (req: Req) => Promise<Res>,
+  context: ProxyContext,
+) => Promise<Res>;
+
+type ToolMiddleware      = Middleware<CallToolRequest, CompatibilityCallToolResult>;
+type ResourceMiddleware  = Middleware<ReadResourceRequest, ReadResourceResult>;
+type PromptMiddleware    = Middleware<GetPromptRequest, GetPromptResult>;
+type ListToolsMiddleware = Middleware<ListToolsRequest, ListToolsResult>;
+```
+
+</details>
+
+`sessionId` is present on HTTP transport only.
+Over stdio there is no session concept, which is why `@mcpose/audit` produces no `ReplayManifest` there.
+
+`proxy` records which proxy instance handled the request, resolved from `ProxyOptions.name` and `version` including their defaults.
+It is provenance, not a principal: it never appears in `delegatedFrom` and takes no part in the caller-attribution model, per [ADR-0012](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0012-proxy-identity-recorded-as-provenance.md).
+
+`policy` holds a decision already made, not a handle to query.
+Core never writes it: [`@mcpose/policy`](https://www.npmjs.com/package/@mcpose/policy) stamps it before calling `next` or throwing, so middleware running inside the policy layer can rely on `decision: 'allow'`, per [ADR-0017](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0017-policy-engine-contract.md).
+It was published as `policy?: never` through v2 and widened to `PolicyDecision` in v3, a breaking change for anyone who narrowed it.
+
+### The delegation chain
+
+`delegatedFrom` records agent-to-agent handoffs, oldest-first.
+Core populates it from the inbound request: a caller presents its chain at `params._meta["mcpose/delegation"]`, read at the proxy boundary before the request-`_meta` strip so it survives a chained proxy, per [ADR-0016](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0016-delegation-chain-wire-format.md).
+A chain your host application stamps on the context takes precedence: core fills the field only when the host left it unset.
+
+```json
+{ "v": 1, "chain": [{ "sub": "agent-a", "type": "agent" }] }
 ```
 
-### Governance options (`ProxyOptions`)
+Each entry carries `sub` (required, non-empty string) and `type` (`human` | `agent` | `service`), plus optional `displayName`, `resolvedAt`, and `source`.
+
+**The chain is attribution, never authorization.**
+Extraction produces an `Identity` with `roles: []` and `claims: {}` for every entry, unconditionally, and ignores any it finds on the wire.
+A presented chain is written by the previous hop, so nothing in it may grant a privilege; authorization comes only from the identity this proxy resolves itself through `resolveIdentity`.
+Entries are not signed: a proxy trusts a presented chain exactly as much as it trusts the immediate caller it authenticated, who vouches for the history it forwards.
+
+A malformed payload rejects the call with `DELEGATION_INVALID` (`InvalidRequest`), thrown inside the pipeline so audit middleware records the attempt.
+Malformed means an unknown `v`, a `chain` that is not an array, more than 32 entries, an entry that is not an object, a missing or empty or non-string `sub`, or a `type` outside the union.
+An absent payload is not an error and leaves `delegatedFrom` unset.
+
+A chain that loops back through this proxy rejects with `DELEGATION_INVALID` too.
+A chain loops when the `sub` of the identity the proxy resolved for the caller already appears in the chain that same caller presents: the authenticated caller is a link in the history it hands over, so the call has cycled.
+The check runs after identity resolution and inside the pipeline, so the rejection is audited against the identity that tripped it.
+With no resolved identity there is nothing to look for, which is the stdio case: only the structural validation above applies there.
+
+What loop detection does not cover: core sees only the calls it forwards itself.
+A cycle that closes through a local tool handler's own outbound call is invisible to it, because that call is host code that may not be MCP at all, which is why [ADR-0011](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0011-proxy-originated-call-attribution.md) rejected a hop counter and why the 32-entry cap is a parse bound rather than a depth policy.
+A deployment that legitimately re-enters the same proxy has no opt-out: re-entry under the same resolved identity is the cycle, and a switch to allow it would make the control decorative.
+Resolve a distinct identity for the re-entering hop, or do not route the call back through the proxy it already passed.
+
+For the outbound direction, `outboundDelegationChain(context)` returns the oldest-first chain (`delegatedFrom` plus the current identity), per [ADR-0011](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0011-proxy-originated-call-attribution.md).
+Core attaches it to every call it forwards to a backend, so the backend sees the chain the proxy can vouch for and never the caller's own copy, which the strip removed.
+A local tool handler calls out through your code, so your host attaches it: for an outbound MCP call, `serializeDelegationChain(outboundDelegationChain(context))` placed at `_meta[DELEGATION_META_KEY]` is exactly what core sends.
+The serializer drops `roles` and `claims` too, so a chain never leaves this proxy carrying privileges.
 
-`hiddenTools` / `hiddenResources` reject calls with a structured [`RejectionReason`](https://github.com/amir-gorji/mcpose#rejectionreason) in the MCP error `data` field; `passThroughTools` skip the pipeline entirely; `onTelemetry` emits per-call timing and outcome.
+Loop detection and the `@mcpose/testing` continuity assertion follow in [#125](https://github.com/amir-gorji/mcpose/issues/125) and [#126](https://github.com/amir-gorji/mcpose/issues/126).
+
+### Rejection reasons
+
+Every blocked call embeds a `RejectionReason` in the MCP error `data` field.
+The top-level error code is unchanged, so clients that only inspect the code are unaffected, while audit middleware and agents can branch on `error.data.rejectionReason`.
+
+Use `rejectionMcpError(reason, code, message)` to reject from your own middleware in the same structured shape the proxy uses.
+A `data.rejectionReason` outside the union is not a rejection: `onTelemetry` and the audit middleware both report that call as an ordinary `error`.
+
+<details>
+<summary>Show the <code>RejectionReason</code> union</summary>
+
+```ts
+type RejectionReason =
+  | 'TOOL_HIDDEN'           // tool exists but is hidden from this caller
+  | 'RESOURCE_HIDDEN'       // resource exists but is hidden from this caller
+  | 'BACKEND_UNROUTABLE'    // mesh mode: the name or URI prefix names no configured backend
+  | 'POLICY_DENIED'         // @mcpose/policy: a rule denied, or no rule allowed
+  | 'IDENTITY_UNRESOLVED'   // identity could not be established
+  | 'CONSENT_MISSING'       // v3: GDPR/CCPA consent gate blocked the call
+  | 'SENSITIVITY_BLOCKED'   // @mcpose/policy: a sensitivity-tier rule blocked the call
+  | 'DELEGATION_INVALID'    // the presented delegation chain is malformed
+  | 'BUDGET_EXCEEDED'       // @mcpose/policy: the per-session call budget is exhausted
+  | 'SESSION_LIMIT'         // max concurrent sessions reached (HTTP 503)
+  | 'BODY_LIMIT';           // request body exceeded maxBodyBytes (HTTP 413)
+```
+
+</details>
+
+`POLICY_DENIED`, `SENSITIVITY_BLOCKED`, and `BUDGET_EXCEEDED` are emitted by [`@mcpose/policy`](https://www.npmjs.com/package/@mcpose/policy), which is also the first emitter of `IDENTITY_UNRESOLVED` without owning it ([ADR-0017](https://github.com/amir-gorji/mcpose/blob/main/docs/adr/0017-policy-engine-contract.md)).
+The values still marked v3 are reserved: the union is declared ahead of the middleware that will emit them so that `error.data` consumers written today keep compiling.
 
 ### Test helpers: `mcpose/testing`
 
-The core package exposes proxy/middleware test utilities under a subpath:
+The core package exposes proxy and middleware test utilities under a subpath:
 
 ```ts
-import { createMockBackendClient, runToolMiddleware } from 'mcpose/testing';
+import {
+  createMockBackendClient,
+  runToolMiddleware,
+  runListToolsMiddleware,
+  runResourceMiddleware,
+} from 'mcpose/testing';
 ```
 
-> **Not to be confused with** [`@mcpose/testing`](https://www.npmjs.com/package/@mcpose/testing), the separate package of compliance-chain assertions.
+`createMockBackendClient()` returns an in-memory backend stub with capability lookup and notification hooks.
+It works with both `createProxyServer()` and `startHttpProxy()` tests, so an example or test suite needs no real upstream.
+`runToolMiddleware()`, `runListToolsMiddleware()`, and `runResourceMiddleware()` drive a single middleware in isolation; each takes the middleware, the request, a `next`, and an optional `ProxyContext` that defaults to a fresh `createProxyContext()`, so tests never pass `undefined as never` for the context argument.
+`runToolMiddleware()` additionally narrows away the legacy `{ toolResult }` shape; the list and resource results have no legacy variant, so the other two have nothing to narrow.
+
+> **Not to be confused with** [`@mcpose/testing`](https://www.npmjs.com/package/@mcpose/testing), a separate package of compliance assertions over audit chains.
+> This subpath mocks the proxy; that package verifies the audit trail.
 
 ## The mcpose ecosystem
 
 | Package | What it adds |
 |---|---|
 | **`mcpose`** (this package) | Proxy core: pipeline, transports, identity, governance. |
-| [`@mcpose/audit`](https://www.npmjs.com/package/@mcpose/audit) | Tamper-evident, HMAC-chained audit events + Merkle `ReplayManifest`. |
-| [`@mcpose/testing`](https://www.npmjs.com/package/@mcpose/testing) | Runner-agnostic compliance assertions for the audit chain. |
+| [`@mcpose/audit`](https://www.npmjs.com/package/@mcpose/audit) | Tamper-evident HMAC-chained audit events and a signed Merkle `ReplayManifest`. |
+| [`@mcpose/testing`](https://www.npmjs.com/package/@mcpose/testing) | Runner-agnostic compliance assertions over an audit trail. |
 
 ## Documentation
 
-- [Full README & API reference](https://github.com/amir-gorji/mcpose#readme)
-- [CONTEXT.md](https://github.com/amir-gorji/mcpose/blob/main/CONTEXT.md): canonical domain glossary
+- [Project README](https://github.com/amir-gorji/mcpose#readme): concepts, comparison, guides, and examples
+- [`CONTEXT.md`](https://github.com/amir-gorji/mcpose/blob/main/CONTEXT.md): the canonical domain glossary
 - [Architecture decision records](https://github.com/amir-gorji/mcpose/tree/main/docs/adr)
+- [Runnable examples](https://github.com/amir-gorji/mcpose/tree/main/examples)
 
 ## License