mcpose 2.0.2 → 3.0.0

package/src/middleware.ts

@@ -0,0 +1,101 @@
+/**
+ * Koa-style middleware composition for MCP request/response pipelines.
+ *
+ * `(req, next) => Promise<Res>` — call `next(req)` to delegate downstream.
+ * Middlewares wrap like an onion: outer runs before+after inner.
+ *
+ * `pipe([piiMW, auditMW])` execution order:
+ *   1. auditMW enter  → capture startTime
+ *   2. piiMW enter    → call next
+ *   3. upstream call  → raw response
+ *   4. piiMW exit     → redact PII
+ *   5. auditMW exit   → log clean result
+ */
+import { createProxyContext, type ProxyContext } from './proxyContext.js';
+
+/** Single middleware unit. May transform req before `next` or res after. */
+export type Middleware<Req, Res> = (
+  req: Req,
+  next: (req: Req) => Promise<Res>,
+  context: ProxyContext,
+) => Promise<Res>;
+
+type MiddlewarePipeline<Req, Res> = {
+  (req: Req, next: (req: Req) => Promise<Res>): Promise<Res>;
+  (
+    req: Req,
+    next: (req: Req) => Promise<Res>,
+    context: ProxyContext,
+  ): Promise<Res>;
+};
+
+/**
+ * Composes middlewares into one, outermost-first (Koa-style).
+ *
+ * @example
+ * const pipeline = compose([auditMW, piiMW]);
+ * const result = await pipeline(req, (r) => upstream.callTool(r.params));
+ */
+export function compose<Req, Res>(
+  middlewares: ReadonlyArray<Middleware<Req, Res>>,
+): MiddlewarePipeline<Req, Res> {
+  return (req, next, context: ProxyContext = createProxyContext()) => {
+    let index = -1;
+
+    const dispatch = (i: number, currentReq: Req): Promise<Res> => {
+      if (i <= index) {
+        return Promise.reject(new Error('next() called multiple times'));
+      }
+      index = i;
+
+      // Past the end of the pipeline, the terminal handler runs.
+      const fn: Middleware<Req, Res> = middlewares[i] ?? ((r) => next(r));
+
+      return Promise.resolve(
+        fn(currentReq, (r) => dispatch(i + 1, r), context),
+      );
+    };
+
+    return dispatch(0, req);
+  };
+}
+
+/**
+ * Like `compose` but in response-processing order (first = innermost).
+ * `pipe([piiMW, auditMW])` ≡ `compose([auditMW, piiMW])`.
+ * Used internally by mcpose core — consumers pass arrays to `ProxyOptions`.
+ */
+export function pipe<Req, Res>(
+  middlewares: ReadonlyArray<Middleware<Req, Res>>,
+): MiddlewarePipeline<Req, Res> {
+  return compose([...middlewares].reverse());
+}
+
+const PASS_THROUGH_OBSERVER = Symbol.for('mcpose.passThroughObserver');
+
+/**
+ * Marks a middleware as a pass-through observer: it still runs for tools
+ * listed in `ProxyOptions.passThroughTools`, which skip all other middleware.
+ *
+ * Use for middleware that must see every call regardless of pass-through
+ * status — audit logging, telemetry — never for middleware that transforms
+ * requests or responses (pass-through means "forward upstream as-is").
+ *
+ * Returns a new middleware; the input is not mutated.
+ */
+export function markPassThroughObserver<Req, Res>(
+  mw: Middleware<Req, Res>,
+): Middleware<Req, Res> {
+  const marked: Middleware<Req, Res> = (req, next, context) =>
+    mw(req, next, context);
+  Object.defineProperty(marked, PASS_THROUGH_OBSERVER, {
+    value: true,
+    enumerable: false,
+  });
+  return marked;
+}
+
+/** True when the middleware was wrapped by {@link markPassThroughObserver}. */
+export function isPassThroughObserver(mw: unknown): boolean {
+  return typeof mw === 'function' && PASS_THROUGH_OBSERVER in mw;
+}

package/src/proxyContext.ts

@@ -0,0 +1,108 @@
+import { randomUUID } from 'node:crypto';
+import type { Identity } from './identity.js';
+
+/**
+ * The proxy instance a request passed through, as resolved from
+ * `ProxyOptions.name`/`version` (defaults included). Provenance, not a
+ * principal: it is never an entry in `delegatedFrom` and takes no part in
+ * the caller-attribution model (ADR-0011, ADR-0012).
+ */
+export interface ProxyIdentity {
+  readonly name: string;
+  readonly version: string;
+}
+
+/**
+ * A policy decision already made, stamped on the context by the policy
+ * middleware (ADR-0017). It is a record, not a handle to query: core never
+ * evaluates policy itself, and a second evaluation path would let inner
+ * middleware ask a different question than the gate answered.
+ *
+ * `reason` carries the `RejectionReason` that accompanied a denial.
+ */
+export interface PolicyDecision {
+  readonly decision: 'allow' | 'deny';
+  readonly ruleId?: string;
+  readonly reason?: string;
+}
+
+/** Normalized request metadata that mcpose passes through middleware layers. */
+export interface ProxyContext {
+  requestId: string;
+  transport: 'stdio' | 'http';
+  sessionId?: string;
+  headers?: Readonly<Record<string, string>>;
+  signal?: AbortSignal;
+  /** Resolved caller identity. Present when {@link HttpProxyOptions.resolveIdentity} is configured. */
+  identity?: Identity;
+  /**
+   * Agent delegation chain, oldest-first. Populated from the inbound
+   * request's `_meta["mcpose/delegation"]` when a caller presents one
+   * (ADR-0016), or by a host that stamps its own, which wins.
+   *
+   * Attribution, never authorization: every entry extracted from the wire
+   * carries empty `roles` and `claims`, because a presented chain is written
+   * by the previous hop.
+   */
+  delegatedFrom?: Identity[];
+  /** The proxy instance handling this request. Stamped by {@link createProxyServer}. */
+  proxy?: ProxyIdentity;
+  /**
+   * The policy decision for this call. Stamped by the `@mcpose/policy`
+   * middleware before it calls `next` (allow) or throws (deny), so
+   * middleware running inside the policy layer can rely on
+   * `decision: 'allow'` (ADR-0017). Core never writes it.
+   */
+  policy?: PolicyDecision;
+}
+
+/**
+ * Canonical oldest-first delegation chain a host attaches to outbound calls
+ * made on behalf of the inbound caller (ADR-0011). Returns a fresh array and
+ * never mutates or aliases `ctx.delegatedFrom`, because the audit middleware
+ * reads the same context object when recording the inbound call.
+ *
+ * Core attaches this chain itself to every call it forwards to a backend, at
+ * `params._meta["mcpose/delegation"]` (ADR-0016). A local tool handler makes
+ * its own outbound calls, so its host attaches the chain: for an outbound MCP
+ * call, `serializeDelegationChain(outboundDelegationChain(context))` under
+ * `DELEGATION_META_KEY` produces exactly what core sends.
+ */
+export function outboundDelegationChain(ctx: ProxyContext): Identity[] {
+  return [
+    ...(ctx.delegatedFrom ?? []),
+    ...(ctx.identity === undefined ? [] : [ctx.identity]),
+  ];
+}
+
+/**
+ * Creates a middleware context with a fresh request ID.
+ *
+ * Every override may be passed explicitly as `undefined` — it means "not
+ * provided" and the key is dropped from the result, which is why the
+ * parameter is not a plain `Partial<ProxyContext>` under
+ * `exactOptionalPropertyTypes`.
+ */
+export function createProxyContext(
+  overrides: { [K in keyof ProxyContext]?: ProxyContext[K] | undefined } = {},
+): ProxyContext {
+  return {
+    // Deliberately `||`, not `??`: an empty-string requestId is useless for
+    // correlation, so it is regenerated like a missing one.
+    requestId: overrides.requestId || randomUUID(),
+    transport: overrides.transport ?? 'stdio',
+    ...(overrides.sessionId === undefined
+      ? {}
+      : { sessionId: overrides.sessionId }),
+    ...(overrides.headers === undefined ? {} : { headers: overrides.headers }),
+    ...(overrides.signal === undefined ? {} : { signal: overrides.signal }),
+    ...(overrides.identity === undefined
+      ? {}
+      : { identity: overrides.identity }),
+    ...(overrides.delegatedFrom === undefined
+      ? {}
+      : { delegatedFrom: overrides.delegatedFrom }),
+    ...(overrides.proxy === undefined ? {} : { proxy: overrides.proxy }),
+    ...(overrides.policy === undefined ? {} : { policy: overrides.policy }),
+  };
+}

package/src/rejection.ts

@@ -0,0 +1,37 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Structured reason for a rejected call.
+ *
+ * Placed in the MCP error `data` field — the top-level error code is
+ * unchanged (`MethodNotFound` / `InvalidRequest`) so existing clients are
+ * unaffected. Agents and audit middleware can inspect `error.data.rejectionReason`
+ * for programmatic handling and compliance logging.
+ *
+ * @stable
+ */
+export 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: no `<backendKey>__` name prefix or `mcpose://<backendKey>/` URI prefix names a configured backend
+  | 'POLICY_DENIED' // @mcpose/policy: a rule denied, or no rule allowed (ADR-0017)
+  | 'IDENTITY_UNRESOLVED' // identity could not be established; @mcpose/policy is its first emitter (ADR-0017)
+  | 'CONSENT_MISSING' // v3: GDPR/CCPA consent gate blocked the call
+  | 'SENSITIVITY_BLOCKED' // @mcpose/policy: a sensitivity-tier rule blocked the call (ADR-0017)
+  | 'DELEGATION_INVALID' // the presented delegation chain is malformed (ADR-0016)
+  | 'BUDGET_EXCEEDED' // @mcpose/policy: the per-session call budget is exhausted (ADR-0017)
+  | 'SESSION_LIMIT' // max concurrent sessions reached (HTTP 503)
+  | 'BODY_LIMIT'; // request body exceeded maxBodyBytes (HTTP 413)
+
+/**
+ * Creates an `McpError` with the rejection reason embedded in `error.data`.
+ * The top-level `code` is unchanged so clients that only inspect the code
+ * are unaffected.
+ */
+export function rejectionMcpError(
+  reason: RejectionReason,
+  code: ErrorCode,
+  message: string,
+): McpError {
+  return new McpError(code, message, { rejectionReason: reason });
+}

package/src/sanitizeCatalog.ts

@@ -0,0 +1,120 @@
+/**
+ * Egress sanitizer for the tool catalog: `tools/list` forwards upstream
+ * descriptions verbatim into model context, and real upstreams leak org
+ * slugs and internal hostnames there. See ADR-0010.
+ */
+
+import type { ListToolsMiddleware } from './core.js';
+
+/** Matches http(s) URLs; always stripped regardless of `patterns`. */
+const URL_PATTERN = /\bhttps?:\/\/[^\s"'<>()[\]]+/g;
+
+/** Options for {@link sanitizeToolDescriptions}. */
+export interface SanitizeToolDescriptionsOptions {
+  /**
+   * Extra patterns to remove. A string replaces every literal occurrence;
+   * a RegExp is normalized to global, with any sticky flag dropped, so
+   * every match is replaced.
+   */
+  patterns?: ReadonlyArray<string | RegExp>;
+  /** Replacement text for every match. Default: `''` (plain removal). */
+  replacement?: string;
+}
+
+/**
+ * Rebuilds a schema node with every string-valued `description` property
+ * sanitized, at any depth through plain objects and arrays. Returns the
+ * original node when nothing changed.
+ */
+function sanitizeSchema(
+  node: unknown,
+  sanitize: (text: string) => string,
+): unknown {
+  if (Array.isArray(node)) {
+    const mapped = node.map((item) => sanitizeSchema(item, sanitize));
+    return mapped.some((item, i) => item !== node[i]) ? mapped : node;
+  }
+  if (node === null || typeof node !== 'object') return node;
+  const entries = Object.entries(node).map(([key, value]) => [
+    key,
+    key === 'description' && typeof value === 'string'
+      ? sanitize(value)
+      : sanitizeSchema(value, sanitize),
+  ]);
+  return entries.some(
+    ([key, value]) =>
+      value !== (node as Record<string, unknown>)[key as string],
+  )
+    ? Object.fromEntries(entries)
+    : node;
+}
+
+/**
+ * A {@link ListToolsMiddleware} that sanitizes tool descriptions and every
+ * `description` field nested in `inputSchema` / `outputSchema`. Names,
+ * titles, and schema structure are untouched, because clients route on
+ * them.
+ *
+ * Always strips http(s) URLs; `patterns` adds more. Place it **last** in
+ * `listToolsMiddleware` so it sanitizes the output of other list
+ * middleware and local tools.
+ *
+ * @example
+ * listToolsMiddleware: [
+ *   sanitizeToolDescriptions({
+ *     patterns: ['acme-corp', /\bi-[0-9a-f]{8,17}\b/],
+ *     replacement: '[redacted]',
+ *   }),
+ * ]
+ */
+export function sanitizeToolDescriptions(
+  options: SanitizeToolDescriptionsOptions = {},
+): ListToolsMiddleware {
+  const replacement = options.replacement ?? '';
+  const patterns: ReadonlyArray<string | RegExp> = [
+    URL_PATTERN,
+    // Rebuild with exactly one `g` and no `y`: String.replace with a
+    // sticky regex only replaces matches anchored at index 0, so a sticky
+    // pattern would silently leak later occurrences.
+    ...(options.patterns ?? []).map((p) =>
+      p instanceof RegExp
+        ? new RegExp(p.source, p.flags.replace(/[gy]/g, '') + 'g')
+        : p,
+    ),
+  ];
+  // replaceAll treats a string pattern literally and requires the g flag
+  // on a RegExp, which the normalization above guarantees.
+  const sanitize = (text: string): string =>
+    patterns.reduce<string>((acc, p) => acc.replaceAll(p, replacement), text);
+
+  return async (req, next) => {
+    const result = await next(req);
+    const tools = result.tools.map((tool) => {
+      const description =
+        typeof tool.description === 'string'
+          ? sanitize(tool.description)
+          : tool.description;
+      const inputSchema = sanitizeSchema(
+        tool.inputSchema,
+        sanitize,
+      ) as typeof tool.inputSchema;
+      const outputSchema = sanitizeSchema(
+        tool.outputSchema,
+        sanitize,
+      ) as typeof tool.outputSchema;
+      return description === tool.description &&
+        inputSchema === tool.inputSchema &&
+        outputSchema === tool.outputSchema
+        ? tool
+        : {
+            ...tool,
+            ...(description === undefined ? {} : { description }),
+            inputSchema,
+            ...(outputSchema === undefined ? {} : { outputSchema }),
+          };
+    });
+    return tools.some((tool, i) => tool !== result.tools[i])
+      ? { ...result, tools }
+      : result;
+  };
+}

package/src/sessionRegistry.ts

@@ -0,0 +1,142 @@
+/**
+ * Shared session registry: the transport-level record of live session ids,
+ * so a resume can survive a proxy restart or reach another instance (#155).
+ */
+import * as http from 'node:http';
+import * as net from 'node:net';
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  isInitializeRequest,
+  type InitializeRequestParams,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { Identity } from './identity.js';
+
+/**
+ * Everything another instance needs to take over a session. Plain JSON: an
+ * adapter serializes it as is, so `identity.claims` must survive a JSON
+ * round-trip.
+ */
+export interface SessionRecord {
+  /**
+   * The client's `initialize` params, verbatim. A resuming instance replays
+   * them into a fresh SDK transport, so the rebuilt session negotiates exactly
+   * what the original did: protocol version, client capabilities, clientInfo.
+   */
+  initialize: InitializeRequestParams;
+  /**
+   * The identity `resolveIdentity` produced at initialize. Never re-resolved
+   * on resume; `validateSession` still runs on every routed request.
+   */
+  identity?: Identity;
+  /**
+   * Epoch milliseconds after which the session is dead on every instance.
+   * Fixed at creation from `sessionTtlMs` and absent when that is `Infinity`.
+   * A resuming instance honours the remaining lifetime, not its own TTL.
+   */
+  expiresAt?: number;
+}
+
+/**
+ * Where `startHttpProxy` keeps its session records when one is supplied. The
+ * local in-memory map stays authoritative for sessions this instance holds;
+ * the registry is consulted only for an id this instance does not know.
+ *
+ * `@mcpose/store-redis` and `@mcpose/store-postgres` ship implementations
+ * alongside their `EventStore`s. Share the event store too, or a resumed
+ * session has a live id and no replay history.
+ */
+export interface SessionRegistry {
+  /**
+   * Persists a record. Awaited before the client learns its session id, so a
+   * rejection fails the initialize with a 500 rather than handing out an id
+   * that no other instance could honour.
+   */
+  set(sessionId: string, record: SessionRecord): Promise<void>;
+  /** `undefined` for an unknown or expired id. */
+  get(sessionId: string): Promise<SessionRecord | undefined>;
+  /**
+   * Called on client DELETE and TTL expiry. Never on server shutdown: a
+   * session that outlives the process is the point of the registry.
+   */
+  delete(sessionId: string): Promise<void>;
+}
+
+/**
+ * Pulls the `initialize` params out of a POST body the SDK has already
+ * accepted as an initialize request, so a parse failure here is a bug in the
+ * SDK's acceptance, not client input to be tolerated.
+ */
+export function initializeParamsOf(body: string): InitializeRequestParams {
+  const parsed: unknown = JSON.parse(body);
+  const messages = Array.isArray(parsed) ? parsed : [parsed];
+  const initialize = messages.find(isInitializeRequest);
+  if (initialize === undefined) {
+    throw new Error('mcpose: initialize request not found in accepted body');
+  }
+  return initialize.params;
+}
+
+/**
+ * Drives a fresh transport through the SDK's own initialize path with the
+ * stored params, so it accepts `sessionId` on later requests. The SDK cannot
+ * rehydrate a transport and its initialized flag is private, so the public
+ * request path is the one that survives an SDK bump.
+ *
+ * The request never touches a socket: the SDK's Node adapter reads method,
+ * url, headers and the body stream, and the response is captured rather than
+ * written anywhere. `Host` and `Origin` are copied from the request being
+ * resumed so the transport's DNS-rebinding check sees what the client sent.
+ *
+ * @returns the status and body the SDK answered, for the caller to relay if
+ * the transport did not come up.
+ */
+export function replayInitialize(
+  transport: StreamableHTTPServerTransport,
+  params: InitializeRequestParams,
+  headers: { host?: string; origin?: string },
+): Promise<{ status: number; body: string }> {
+  const body = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 0,
+    method: 'initialize',
+    params,
+  });
+  const req = new http.IncomingMessage(new net.Socket());
+  req.method = 'POST';
+  req.url = '/';
+  req.headers = {
+    'content-type': 'application/json',
+    'content-length': String(Buffer.byteLength(body)),
+    accept: 'application/json, text/event-stream',
+    ...(headers.host === undefined ? {} : { host: headers.host }),
+    ...(headers.origin === undefined ? {} : { origin: headers.origin }),
+  };
+  // The SDK's adapter reads the raw header list, not the parsed record.
+  req.rawHeaders = Object.entries(req.headers).flatMap(([name, value]) => [
+    name,
+    String(value),
+  ]);
+  req.push(body);
+  req.push(null);
+
+  const res = new http.ServerResponse(req);
+  let out = '';
+  const append = (chunk: unknown): void => {
+    if (typeof chunk === 'string') out += chunk;
+    else if (chunk instanceof Uint8Array) out += Buffer.from(chunk).toString();
+  };
+  // No socket: a real write would buffer forever and report back-pressure,
+  // and 'finish' would never fire. Capture instead.
+  res.write = (chunk: unknown) => {
+    append(chunk);
+    return true;
+  };
+  const done = new Promise<{ status: number; body: string }>((resolve) => {
+    res.end = ((chunk?: unknown) => {
+      append(chunk);
+      resolve({ status: res.statusCode, body: out });
+      return res;
+    }) as typeof res.end;
+  });
+  return transport.handleRequest(req, res).then(() => done);
+}

package/src/telemetry.ts

@@ -0,0 +1,46 @@
+import type { Identity } from './identity.js';
+import type { ProxyIdentity } from './proxyContext.js';
+import type { RejectionReason } from './rejection.js';
+
+/** Emitted after every tool call (success, error, or rejection). */
+export interface ToolCallTelemetryEvent {
+  type: 'tool_call';
+  requestId: string;
+  sessionId?: string;
+  tool: string;
+  duration_ms: number;
+  outcome: 'success' | 'error' | 'rejected';
+  /** Populated when `outcome` is `'rejected'`. */
+  rejectionReason?: RejectionReason;
+  identity?: Identity;
+  /** The proxy instance that handled the call (ADR-0012). */
+  proxy?: ProxyIdentity;
+}
+
+/**
+ * Emitted when one backend of a mesh fails a list call and the proxy
+ * returns the remaining backends' entries instead of failing the whole
+ * list (ADR-0013). Without an `onTelemetry` sink a degraded mesh is
+ * invisible, so an operator running one should wire it.
+ */
+export interface BackendDegradedTelemetryEvent {
+  type: 'backend_degraded';
+  requestId: string;
+  sessionId?: string;
+  /** The backend key whose entries are missing from the response. */
+  backend: string;
+  /** The list call that degraded. */
+  method: 'tools/list' | 'prompts/list' | 'resources/list';
+  /** Whatever the backend threw. */
+  error: unknown;
+  identity?: Identity;
+  /** The proxy instance that handled the call (ADR-0012). */
+  proxy?: ProxyIdentity;
+}
+
+/**
+ * An observability signal from the proxy, discriminated on `type`. Narrow
+ * on it before reading a member's own fields.
+ */
+export type TelemetryEvent =
+  ToolCallTelemetryEvent | BackendDegradedTelemetryEvent;