mcpose 3.0.0 → 3.1.0

package/src/core.ts

@@ -70,7 +70,7 @@ import {
   type SessionRegistry,
 } from './sessionRegistry.js';
 import type { EventStore } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { rejectionMcpError } from './rejection.js';
+import { isRejectionReason, rejectionMcpError } from './rejection.js';
 import type { RejectionReason } from './rejection.js';
 import { VERSION } from './version.js';
 
@@ -115,11 +115,24 @@ export type ListToolsMiddleware = Middleware<ListToolsRequest, ListToolsResult>;
  * This guard narrows `CompatibilityCallToolResult` to `CallToolResult`
  * (has `.content` array). Both union members carry `[x: string]: unknown`,
  * so this avoids unsafe casts.
+ *
+ * A guard, not an assertion: the union's two members are both objects, but a
+ * pipeline result is not the union. The legacy shape has no `.content`, and a
+ * handler that produced nothing at all (a local tool with a missing `return`,
+ * or a middleware that dropped the result) produces a nullish one, which has
+ * none either. Both answer `false` here. Throwing instead replaced whatever
+ * the pipeline produced with `TypeError: Cannot read properties of undefined
+ * (reading 'content')` — inside `mapToolResult`, and inside the `tools/call`
+ * handler's telemetry read of `result.isError`.
  */
 export function hasToolContent(
   r: CompatibilityCallToolResult,
 ): r is CallToolResult {
-  return Array.isArray(r.content);
+  return (
+    r !== null &&
+    typeof r === 'object' &&
+    Array.isArray((r as { content?: unknown }).content)
+  );
 }
 
 /**
@@ -202,10 +215,20 @@ export interface HttpProxyOptions {
   /**
    * Called on unhandled errors instead of console.error, and on every auth
    * hook that throws: the request still fails closed, and the operator still
-   * sees why.
+   * sees why. If this hook itself throws or returns a rejected promise, the
+   * failure is contained and changes nothing the caller sees.
+   */
+  onError?: (err: unknown) => unknown;
+  /**
+   * Maximum request body size in bytes. Excess POST bodies return 413.
+   * Default: 4 MB. Set to `Infinity` to opt out of the cap.
+   *
+   * `0` is a valid value and means "reject every POST body", so it is not the
+   * opt-out. The two shapes that are mistakes rather than choices throw at
+   * startup: a negative number returns 413 for every POST, and `NaN`, which is
+   * what `Number(process.env.MAX_BODY_BYTES)` returns for an unset key,
+   * compares false against every body size and so gates nothing at all.
    */
-  onError?: (err: unknown) => void;
-  /** Maximum request body size in bytes. Default: 4 MB. */
   maxBodyBytes?: number;
   /**
    * Maximum number of concurrent MCP sessions. Excess requests return 503.
@@ -494,12 +517,40 @@ export interface ProxyOptions {
    * Called after every tool call with timing and outcome data. Wire to any
    * custom telemetry sink, or to `createOtelTelemetry` from `@mcpose/otel`
    * for OpenTelemetry spans.
-   * A throwing sink is logged and never fails the tool call.
+   * A sink that throws, or whose returned promise rejects, is logged and never
+   * fails the tool call. The sink is not awaited, so a slow one does not delay
+   * the call either.
    */
-  onTelemetry?: (event: TelemetryEvent) => void;
+  onTelemetry?: (event: TelemetryEvent) => unknown;
 }
 
 type ProgressToken = string | number;
+
+/**
+ * Hands one event to the telemetry sink. A sink that throws, or whose returned
+ * promise rejects, is logged here and nowhere else: the caller is already past
+ * the point where the tool call could fail, and a rejection that nobody observes
+ * ends the process on Node's default `--unhandled-rejections=throw`.
+ *
+ * The sink is called, not awaited, so a slow exporter cannot delay a tool call.
+ *
+ * `Promise.resolve` rather than an `instanceof Promise` test: a sink loaded from
+ * another realm (`node:vm`), or one handing back a non-native thenable, would
+ * fail the latter and leave its rejection unobserved all the same.
+ */
+function callTelemetrySink(
+  sink: ((event: TelemetryEvent) => unknown) | undefined,
+  event: TelemetryEvent,
+): void {
+  try {
+    Promise.resolve(sink?.(event)).catch((err: unknown) => {
+      console.error(err);
+    });
+  } catch (err) {
+    console.error(err);
+  }
+}
+
 type BackendRequestOptions = Parameters<BackendClient['listTools']>[1];
 // Structural mirror of the SDK's `RequestHandlerExtra`. The SDK declares its
 // optional members as `?: T | undefined`, so this type has to as well to stay
@@ -658,10 +709,10 @@ function getMiddlewareContext(
 }
 
 function getRejectionReason(err: unknown): RejectionReason | undefined {
-  const data = (err as { data?: { rejectionReason?: unknown } } | null)?.data;
-  return typeof data?.rejectionReason === 'string'
-    ? (data.rejectionReason as RejectionReason)
-    : undefined;
+  const reason = (err as { data?: { rejectionReason?: unknown } } | null)?.data
+    ?.rejectionReason;
+  // A reason outside the union is an ordinary failure, not a rejection (#238).
+  return isRejectionReason(reason) ? reason : undefined;
 }
 
 /**
@@ -957,24 +1008,18 @@ export function createProxyServer(
     method: BackendDegradedTelemetryEvent['method'],
     error: unknown,
   ): void => {
-    try {
-      options.onTelemetry?.({
-        type: 'backend_degraded',
-        requestId: context.requestId,
-        ...(context.sessionId === undefined
-          ? {}
-          : { sessionId: context.sessionId }),
-        backend: backendKey,
-        method,
-        error,
-        ...(context.identity === undefined
-          ? {}
-          : { identity: context.identity }),
-        ...(context.proxy === undefined ? {} : { proxy: context.proxy }),
-      });
-    } catch (err) {
-      console.error(err);
-    }
+    callTelemetrySink(options.onTelemetry, {
+      type: 'backend_degraded',
+      requestId: context.requestId,
+      ...(context.sessionId === undefined
+        ? {}
+        : { sessionId: context.sessionId }),
+      backend: backendKey,
+      method,
+      error,
+      ...(context.identity === undefined ? {} : { identity: context.identity }),
+      ...(context.proxy === undefined ? {} : { proxy: context.proxy }),
+    });
   };
 
   // ── Tool handlers ──────────────────────────────────────────────────────────
@@ -1062,26 +1107,21 @@ export function createProxyServer(
         outcome: ToolCallTelemetryEvent['outcome'],
         rejectionReason?: RejectionReason,
       ) => {
-        try {
-          options.onTelemetry?.({
-            type: 'tool_call',
-            requestId: context.requestId,
-            ...(context.sessionId === undefined
-              ? {}
-              : { sessionId: context.sessionId }),
-            tool: name,
-            duration_ms: Math.round(performance.now() - start),
-            outcome,
-            ...(rejectionReason === undefined ? {} : { rejectionReason }),
-            ...(context.identity === undefined
-              ? {}
-              : { identity: context.identity }),
-            ...(context.proxy === undefined ? {} : { proxy: context.proxy }),
-          });
-        } catch (err) {
-          // A throwing telemetry sink must never fail the tool call.
-          console.error(err);
-        }
+        callTelemetrySink(options.onTelemetry, {
+          type: 'tool_call',
+          requestId: context.requestId,
+          ...(context.sessionId === undefined
+            ? {}
+            : { sessionId: context.sessionId }),
+          tool: name,
+          duration_ms: Math.round(performance.now() - start),
+          outcome,
+          ...(rejectionReason === undefined ? {} : { rejectionReason }),
+          ...(context.identity === undefined
+            ? {}
+            : { identity: context.identity }),
+          ...(context.proxy === undefined ? {} : { proxy: context.proxy }),
+        });
       };
 
       // Hidden beats pass-through. The rejection is thrown by the innermost
@@ -1168,10 +1208,29 @@ export function createProxyServer(
           context,
         );
         // MCP signals tool-level failures in-band via isError, not by throwing.
+        // Three shapes reach here, and `hasToolContent` alone cannot tell them
+        // apart because it answers false for two of them:
+        //
+        //   - a CallToolResult: judge it by `isError`;
+        //   - the legacy `{ toolResult }` shape (protocol 2024-10-07): a valid
+        //     result with no `.content`, so `mapToolResult` passes it through —
+        //     a success;
+        //   - nothing at all, from a local tool with a missing `return` or a
+        //     middleware that dropped the result: the call produced no result,
+        //     so it is not a success.
+        //
+        // A result-less call used to reach the `catch` as a TypeError from
+        // `hasToolContent` and be recorded as an error; now that the guard
+        // answers false instead of throwing, the shape has to be distinguished
+        // here or a `&&` would report it as a clean one.
+        const isResultless =
+          result === null || result === undefined || typeof result !== 'object';
         emitTelemetry(
-          hasToolContent(result) && result.isError === true
+          isResultless
             ? 'error'
-            : 'success',
+            : hasToolContent(result) && result.isError === true
+              ? 'error'
+              : 'success',
         );
         return result;
       } catch (err) {
@@ -1550,6 +1609,21 @@ export function startHttpProxy(
       `mcpose: sessionTtlMs must be <= ${MAX_NODE_TIMER_DELAY_MS} or Infinity, got ${String(httpOptions.sessionTtlMs)}`,
     );
   }
+  // Resolved once, like the two limits above, so a bad value fails at startup
+  // instead of quietly gating nothing. A `NaN` cap compares false against both
+  // the declared `Content-Length` and the running byte count, so a body far
+  // larger than the configured limit passes this layer untouched.
+  // `Number(process.env.MAX_BODY_BYTES)` is the ordinary way a host wires an
+  // operator-supplied limit in, and it is NaN when the key is unset or
+  // misspelled; #264 rejected a non-finite `budget.maxCallsPerSession` for
+  // exactly this reason. `Infinity` opts out, and `0`, like `maxSessions: 0`,
+  // keeps its literal meaning instead of doubling as one.
+  const maxBodyBytes = httpOptions.maxBodyBytes ?? 4 * 1024 * 1024;
+  if (!(maxBodyBytes >= 0)) {
+    throw new Error(
+      `mcpose: maxBodyBytes must be >= 0 or Infinity, got ${String(httpOptions.maxBodyBytes)}`,
+    );
+  }
   // Filled in once the server is listening (the real port is only known
   // then); sessions are only created after that. The SDK transport
   // validates Host/Origin only against a non-empty list, so an enabled flag
@@ -1577,7 +1651,24 @@ export function startHttpProxy(
   let pendingSessions = 0;
 
   const reportError = (err: unknown): void => {
-    (httpOptions.onError ?? console.error)(err);
+    // `onError` is observability, so its own failure must change nothing, the
+    // same containment `onAuditError` applies to `@mcpose/audit`'s reporter
+    // (#172) and `createConsentMiddleware` applies to its resolver hook. Left
+    // unguarded, a throwing reporter replaced the 401 this file documents for
+    // a failed auth hook with a 500, aborted `destroySession` before it closed
+    // the proxy server, and threw out of the `server.on('error')` handler
+    // that exists precisely so a post-listen error does not crash the process.
+    // An async reporter that rejects after its first await escapes the same
+    // guard one tick later (#245): nobody observes the rejection, and Node's
+    // default --unhandled-rejections=throw ends the process, so the returned
+    // promise is adopted here too.
+    try {
+      Promise.resolve((httpOptions.onError ?? console.error)(err)).catch(() => {
+        // Nothing left to report it to.
+      });
+    } catch {
+      // Nothing left to report it to.
+    }
   };
 
   /**
@@ -1773,11 +1864,7 @@ export function startHttpProxy(
       }
 
       if (method === 'POST') {
-        const rejected = applyBodySizeLimit(
-          req,
-          res,
-          httpOptions.maxBodyBytes ?? 4 * 1024 * 1024,
-        );
+        const rejected = applyBodySizeLimit(req, res, maxBodyBytes);
         if (rejected) return;
       }
 
@@ -1955,7 +2042,7 @@ export function startHttpProxy(
 
     handle().catch((err) => {
       if (!res.headersSent) res.writeHead(500).end();
-      (httpOptions.onError ?? console.error)(err);
+      reportError(err);
     });
   };
 

package/src/rejection.ts

@@ -23,6 +23,31 @@ export type RejectionReason =
   | 'SESSION_LIMIT' // max concurrent sessions reached (HTTP 503)
   | 'BODY_LIMIT'; // request body exceeded maxBodyBytes (HTTP 413)
 
+// The `Record` annotation keeps this table and the union from drifting apart:
+// a missing or extra key is a compile error.
+const REJECTION_REASONS: Record<RejectionReason, true> = {
+  TOOL_HIDDEN: true,
+  RESOURCE_HIDDEN: true,
+  BACKEND_UNROUTABLE: true,
+  POLICY_DENIED: true,
+  IDENTITY_UNRESOLVED: true,
+  CONSENT_MISSING: true,
+  SENSITIVITY_BLOCKED: true,
+  DELEGATION_INVALID: true,
+  BUDGET_EXCEEDED: true,
+  SESSION_LIMIT: true,
+  BODY_LIMIT: true,
+};
+
+/**
+ * Narrows an untrusted value to `RejectionReason`.
+ * `Object.hasOwn`, not `in`: the value can come from an upstream error, so a
+ * prototype key like `constructor` must not pass as a member.
+ */
+export function isRejectionReason(value: unknown): value is RejectionReason {
+  return typeof value === 'string' && Object.hasOwn(REJECTION_REASONS, value);
+}
+
 /**
  * Creates an `McpError` with the rejection reason embedded in `error.data`.
  * The top-level `code` is unchanged so clients that only inspect the code

package/src/sanitizeCatalog.ts

@@ -6,8 +6,14 @@
 
 import type { ListToolsMiddleware } from './core.js';
 
-/** Matches http(s) URLs; always stripped regardless of `patterns`. */
-const URL_PATTERN = /\bhttps?:\/\/[^\s"'<>()[\]]+/g;
+/**
+ * Matches http(s) URLs; always stripped regardless of `patterns`.
+ * The `i` flag is load-bearing: URI schemes are case-insensitive
+ * (RFC 3986 §6.2.2), so an uppercase `HTTPS://` is the same URL, and a
+ * case-sensitive strip would let an upstream leak a hostname simply by
+ * capitalizing the scheme.
+ */
+const URL_PATTERN = /\bhttps?:\/\/[^\s"'<>()[\]]+/gi;
 
 /** Options for {@link sanitizeToolDescriptions}. */
 export interface SanitizeToolDescriptionsOptions {

package/src/sessionRegistry.ts

@@ -48,7 +48,7 @@ export interface SessionRecord {
 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
+   * rejection fails the initialize with a 400 rather than handing out an id
    * that no other instance could honour.
    */
   set(sessionId: string, record: SessionRecord): Promise<void>;

package/src/version.ts

@@ -3,4 +3,4 @@
  * `createRequire('../package.json')` lookup breaks when consumers bundle
  * the package). Kept in sync with package.json by `version.test.ts`.
  */
-export const VERSION = '3.0.0';
+export const VERSION = '3.1.0';