mcp-trellis 1.0.0 → 2.1.0

package/dist/{methods.d.ts → mcp/methods.d.ts}

@@ -1,8 +1,13 @@
-import { type WwwAuthenticateOptions } from "./auth/bearer.js";
+import { type WwwAuthenticateOptions } from "../auth/bearer.js";
 import { type JsonRpcId, type JsonRpcRequest } from "./jsonrpc.js";
 import type { ToolRegistry } from "./registry.js";
 export type Principal = {
     id: string;
+    /**
+     * Granted scopes. The literal `"*"` is a wildcard that satisfies **every**
+     * tool `scope` check (see `hasScope`) — reserve it for trusted internal
+     * principals; never mint it for an external connector.
+     */
     scopes: string[];
     /** Optional host claims from `verifyToken` (tenant, plan, role, …). */
     claims?: Record<string, unknown> | undefined;
@@ -19,6 +24,12 @@ export type AuditEntry = {
 };
 export type McpPorts<TCtx> = {
     authenticate: (req: Request, method: string, tool?: string) => Promise<Principal | null>;
+    /**
+     * Builds the tool context. Called only for a `tools/call` that passed the
+     * unknown-tool and scope checks — never for `initialize`, `ping` or
+     * `tools/list`. `principal` is null only when a host adds `tools/call`
+     * to `publicMethods`.
+     */
     context: (req: Request, principal: Principal | null) => TCtx | Promise<TCtx>;
     /**
      * Opt-in metrics hook. Pass any function to receive tool results and auth
@@ -51,10 +62,46 @@ export type McpHandlerOptions<TCtx> = {
      * indefinitely — "can't fail" isn't "can't delay."
      */
     auditTimeoutMs?: number;
+    /**
+     * Browser `Origin` header allowlist for MCP (DNS rebinding / CSRF).
+     * Distinct from Node Host `allowedOrigins` on `asNodeHandler`.
+     * No `Origin` → allowed (native clients). Omitted/empty → reject any
+     * present `Origin`. `"*"` admits any Origin.
+     */
+    allowedRequestOrigins?: string[];
+    /**
+     * Filter `tools/list` down to tools the calling principal's scopes
+     * actually satisfy (an unscoped tool is always listed). Default
+     * **false** — every tool is always listed, `tools/call` is what enforces
+     * scope (with a **403** `insufficient_scope`, see `insufficientScope`).
+     * Turning this on trades that step-up signal away: a client can no
+     * longer discover "this tool exists, ask for its scope" from `tools/list`
+     * for a scope it doesn't hold — only worth it if listing a tool at all
+     * would leak something (its name, description, or schema) you don't want
+     * a lesser-scoped principal to see.
+     */
+    hideToolsOutsideScope?: boolean;
+};
+/** `McpHandlerOptions` after `createMcpHandler` resolved its defaults. */
+export type ResolvedMcpHandlerOptions<TCtx> = McpHandlerOptions<TCtx> & {
+    publicMethods: Set<string>;
+};
+/** `AuditEntry.error` values for requests the handler itself denied. */
+export declare const DENIAL_REASONS: {
+    readonly unauthorized: "unauthorized";
+    readonly queryStringToken: "query_string_token";
+    readonly originNotAllowed: "origin_not_allowed";
+    readonly unknownTool: "unknown_tool";
+    readonly missingScope: "missing_scope";
 };
 export declare const DEFAULT_PUBLIC_METHODS: Set<string>;
+/**
+ * JSON-RPC 2.0: a notification omits `id` (no response). MCP also treats
+ * `notifications/*` and legacy `initialized` as notifications even when an
+ * `id` is present. Orphan result-shaped bodies (no method/id) get 202 too.
+ */
 export declare const isNotification: (body: JsonRpcRequest) => boolean;
-export declare const resolveWww: <TCtx>(options: McpHandlerOptions<TCtx>, req: Request) => WwwAuthenticateOptions;
+export declare const resolveWwwAuthenticate: <TCtx>(options: McpHandlerOptions<TCtx>, request: Request) => WwwAuthenticateOptions;
 /**
  * `id` defaults to `null` for the transport-level call sites in
  * `dispatch.ts` — a body hasn't been parsed yet there, so there's no real
@@ -62,7 +109,16 @@ export declare const resolveWww: <TCtx>(options: McpHandlerOptions<TCtx>, req: R
  * method handlers) have one and must pass it, or a client correlating
  * responses by id sees `null` on every 401 regardless of what it sent.
  */
-export declare const unauthorized: (www: WwwAuthenticateOptions, message?: string, id?: JsonRpcId) => Response;
+export declare const unauthorized: (wwwAuthenticate: WwwAuthenticateOptions, message?: string, id?: JsonRpcId) => Response;
+/**
+ * RFC 6750 §3.1: a request that authenticated but lacks the required scope
+ * gets **403**, not 401 — 401 tells the client "authenticate", which a
+ * scope-step-up client obeys by re-running the exact same OAuth flow,
+ * getting back the exact same scopes, and retrying forever. 403 with
+ * `error="insufficient_scope"` says what's actually wrong: re-consent with
+ * a broader `scope` request, not re-authenticate.
+ */
+export declare const insufficientScope: (wwwAuthenticate: WwwAuthenticateOptions, scope: string, id?: JsonRpcId) => Response;
 /**
  * Invoke the audit metrics hook, swallowing any failure and racing it
  * against `auditTimeoutMs` so a hanging sink can't stall the response
@@ -72,13 +128,6 @@ export declare const unauthorized: (www: WwwAuthenticateOptions, message?: strin
  * an unhandled rejection whenever it does finish.
  */
 export declare const safeAudit: <TCtx>(options: McpHandlerOptions<TCtx>, entry: AuditEntry) => Promise<void>;
+/** True when `scope` is unset, granted, or covered by the `"*"` wildcard scope. */
 export declare const hasScope: (principal: Principal, scope: string | undefined) => boolean;
-export declare const dispatchRpc: <TCtx>(input: {
-    req: Request;
-    body: JsonRpcRequest;
-    options: McpHandlerOptions<TCtx>;
-    publicMethods: Set<string>;
-    /** Request start (captured in `createMcpHandler.fetch`), for denial-path audit timing. */
-    startedAt: number;
-}) => Promise<Response>;
 //# sourceMappingURL=methods.d.ts.map

package/dist/mcp/methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.d.ts","sourceRoot":"","sources":["../../src/mcp/methods.ts"],"names":[],"mappings":"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"}

package/dist/mcp/methods.js

@@ -0,0 +1,84 @@
+import { wwwAuthenticateHeader } from "../auth/bearer.js";
+import { DEFAULT_AUDIT_TIMEOUT_MS, jsonResponse, runAuditBounded } from "../http/http.js";
+import { JSONRPC_INSUFFICIENT_SCOPE, JSONRPC_UNAUTHORIZED, rpcError, } from "./jsonrpc.js";
+/** `AuditEntry.error` values for requests the handler itself denied. */
+export const DENIAL_REASONS = {
+    unauthorized: "unauthorized",
+    queryStringToken: "query_string_token",
+    originNotAllowed: "origin_not_allowed",
+    unknownTool: "unknown_tool",
+    missingScope: "missing_scope",
+};
+export const DEFAULT_PUBLIC_METHODS = new Set([
+    "initialize",
+    "ping",
+    "notifications/initialized",
+    "initialized",
+]);
+/**
+ * JSON-RPC 2.0: a notification omits `id` (no response). MCP also treats
+ * `notifications/*` and legacy `initialized` as notifications even when an
+ * `id` is present. Orphan result-shaped bodies (no method/id) get 202 too.
+ */
+export const isNotification = (body) => {
+    if (body.id === undefined) {
+        return typeof body.method === "string" || (body.method === undefined && "result" in body);
+    }
+    return ((typeof body.method === "string" && body.method.startsWith("notifications/")) ||
+        body.method === "initialized");
+};
+export const resolveWwwAuthenticate = (options, request) => typeof options.wwwAuthenticate === "function"
+    ? options.wwwAuthenticate(request)
+    : options.wwwAuthenticate;
+/**
+ * `id` defaults to `null` for the transport-level call sites in
+ * `dispatch.ts` — a body hasn't been parsed yet there, so there's no real
+ * id to echo. Call sites past that point (inside `dispatchRpc` and the
+ * method handlers) have one and must pass it, or a client correlating
+ * responses by id sees `null` on every 401 regardless of what it sent.
+ */
+export const unauthorized = (wwwAuthenticate, message = "Unauthorized", id = null) => jsonResponse({
+    data: rpcError(id, JSONRPC_UNAUTHORIZED, message),
+    status: 401,
+    headers: { "WWW-Authenticate": wwwAuthenticateHeader(wwwAuthenticate) },
+});
+/**
+ * RFC 6750 §3.1: a request that authenticated but lacks the required scope
+ * gets **403**, not 401 — 401 tells the client "authenticate", which a
+ * scope-step-up client obeys by re-running the exact same OAuth flow,
+ * getting back the exact same scopes, and retrying forever. 403 with
+ * `error="insufficient_scope"` says what's actually wrong: re-consent with
+ * a broader `scope` request, not re-authenticate.
+ */
+export const insufficientScope = (wwwAuthenticate, scope, id = null) => jsonResponse({
+    data: rpcError(id, JSONRPC_INSUFFICIENT_SCOPE, `Missing scope: ${scope}`),
+    status: 403,
+    headers: {
+        "WWW-Authenticate": wwwAuthenticateHeader({
+            ...wwwAuthenticate,
+            error: "insufficient_scope",
+            scope,
+        }),
+    },
+});
+/**
+ * Invoke the audit metrics hook, swallowing any failure and racing it
+ * against `auditTimeoutMs` so a hanging sink can't stall the response
+ * either — "can't fail a request" was already true; this adds "can't
+ * delay one" past a bound. The audit call keeps running in the background
+ * if the timer wins; its own `catch` below means it can never surface as
+ * an unhandled rejection whenever it does finish.
+ */
+export const safeAudit = async (options, entry) => {
+    const audit = options.ports.audit;
+    if (!audit)
+        return;
+    await runAuditBounded(() => audit(entry), options.auditTimeoutMs ?? DEFAULT_AUDIT_TIMEOUT_MS);
+};
+/** True when `scope` is unset, granted, or covered by the `"*"` wildcard scope. */
+export const hasScope = (principal, scope) => {
+    if (!scope)
+        return true;
+    return principal.scopes.includes(scope) || principal.scopes.includes("*");
+};
+//# sourceMappingURL=methods.js.map

package/dist/mcp/methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.js","sourceRoot":"","sources":["../../src/mcp/methods.ts"],"names":[],"mappings":"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"}

package/dist/{protocol.d.ts → mcp/protocol.d.ts}

@@ -1,9 +1,7 @@
 export declare const PROTOCOL_VERSIONS: Set<string>;
 /**
  * Answered on `initialize` when the client's requested version is missing
- * or unrecognized. The spec's guidance is to respond with a version the
- * server supports, preferring the latest — not the oldest one, which is
- * what this constant did before.
+ * or unrecognized: per the spec, the latest version this server supports.
  */
 export declare const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
 /**

package/dist/mcp/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/mcp/protocol.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,aAAsD,CAAC;AAErF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,eAAe,CAAC;AAE5D,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAMtE,CAAC"}

package/dist/{protocol.js → mcp/protocol.js}

@@ -1,9 +1,7 @@
 export const PROTOCOL_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
 /**
  * Answered on `initialize` when the client's requested version is missing
- * or unrecognized. The spec's guidance is to respond with a version the
- * server supports, preferring the latest — not the oldest one, which is
- * what this constant did before.
+ * or unrecognized: per the spec, the latest version this server supports.
  */
 export const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
 /**

package/dist/mcp/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/mcp/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAErF;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,YAAY,CAAC;AAE5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAgC,EAAU,EAAE;IAC9E,MAAM,SAAS,GAAG,MAAM,EAAE,eAAe,CAAC;IAC1C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACtE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,wBAAwB,CAAC;AAClC,CAAC,CAAC"}

package/dist/mcp/registry.d.ts

@@ -0,0 +1,58 @@
+import type { JsonSchema } from "./validate.js";
+export type ToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean | undefined;
+};
+export type ToolHandler<TCtx> = (ctx: TCtx, args: Record<string, unknown>) => Promise<ToolResult | string> | ToolResult | string;
+export type ToolDef<TCtx> = {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    /**
+     * Required scope, or `undefined`/omitted for "any authenticated
+     * principal, whatever its scopes." On a `createMcpApp` server advertising
+     * more than one scope, an omitted `scope` is a construction-time error —
+     * see `assertToolScopesConfigured` — precisely because "any authenticated
+     * principal" silently includes a principal with zero scopes, which is
+     * rarely the intent on a multi-scope server. Pass `scope: null` to state
+     * that intentionally instead of by omission.
+     */
+    scope?: string | null | undefined;
+    handler: ToolHandler<TCtx>;
+};
+export type ToolListEntry = {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+};
+export type ToolRegistry<TCtx> = {
+    /**
+     * `allowScope`, when passed, is consulted per tool with that tool's
+     * `scope` — omit a tool by returning `false`. Lets a caller (see
+     * `McpHandlerOptions.hideToolsOutsideScope`) filter `tools/list` by a
+     * principal's granted scopes without the registry itself knowing what a
+     * "principal" or "scope check" is — it only ever sees the raw `scope`
+     * value already on each `ToolDef`.
+     */
+    list: (allowScope?: (scope: string | null | undefined) => boolean) => ToolListEntry[];
+    get: (name: string) => ToolDef<TCtx> | undefined;
+    call: (name: string, ctx: TCtx, args: Record<string, unknown>) => Promise<ToolResult>;
+};
+export type RegistryOptions = {
+    /**
+     * Validate tools/call args against inputSchema. Default **true** since 2.0 —
+     * forgetting this was a silent injection path into handlers. Set `false`
+     * only when you intentionally skip schema checks.
+     */
+    validateArgs?: boolean | undefined;
+    /**
+     * Map tool exceptions to client-visible text.
+     * Default: `"Tool execution failed"` (no exception leakage).
+     */
+    onToolError?: ((error: unknown) => string) | undefined;
+};
+export declare const createToolRegistry: <TCtx>(tools: ToolDef<TCtx>[], options?: RegistryOptions) => ToolRegistry<TCtx>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/mcp/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/mcp/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,IAAI,IAAI,CAC9B,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,GAAG,UAAU,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,OAAO,CAAC,IAAI,IAAI;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,IAAI,IAAI;IAC/B;;;;;;;OAOG;IACH,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,KAAK,aAAa,EAAE,CAAC;IACtF,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IACjD,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACvF,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;CACxD,CAAC;AA8DF,eAAO,MAAM,kBAAkB,GAAI,IAAI,EACrC,OAAO,OAAO,CAAC,IAAI,CAAC,EAAE,EACtB,UAAS,eAAoB,KAC5B,YAAY,CAAC,IAAI,CAqCnB,CAAC"}

package/dist/mcp/registry.js

@@ -0,0 +1,81 @@
+import { missingObjectType, unsupportedKeywords, validateAgainstSchema } from "./validate.js";
+const DEFAULT_TOOL_ERROR = "Tool execution failed";
+/**
+ * Map a tool exception to client-visible text.
+ * A throwing or non-string `onToolError` falls back to the redacted default —
+ * a mapper must never turn a tool failure into a transport failure.
+ */
+const resolveToolError = (caught, onToolError) => {
+    if (!onToolError)
+        return DEFAULT_TOOL_ERROR;
+    try {
+        const mapped = onToolError(caught);
+        return typeof mapped === "string" && mapped.length > 0 ? mapped : DEFAULT_TOOL_ERROR;
+    }
+    catch {
+        return DEFAULT_TOOL_ERROR;
+    }
+};
+const asToolResult = (out) => {
+    if (typeof out === "string") {
+        return { content: [{ type: "text", text: out }], isError: false };
+    }
+    return out;
+};
+const errorResult = (message) => ({
+    content: [{ type: "text", text: message }],
+    isError: true,
+});
+/** Throws with every violation listed at once, rather than failing on the first tool found. */
+const assertToolSchemasValid = (tools) => {
+    const keywordViolations = tools.flatMap((tool) => unsupportedKeywords(tool.inputSchema).map((path) => `${tool.name}: unsupported JSON Schema keyword at ${path}`));
+    if (keywordViolations.length > 0) {
+        throw new Error(`validateArgs: true but inputSchema uses unsupported keywords:\n` +
+            keywordViolations.join("\n") +
+            "\nRemove the keyword, enforce it in the handler, or set validateArgs: false");
+    }
+    // `properties`/`required` without `type: "object"` validates nothing at
+    // that node, and passes the keyword check above. See `missingObjectType`.
+    const typeViolations = tools.flatMap((tool) => missingObjectType(tool.inputSchema).map((path) => `${tool.name}: ${path} uses properties/required without type: "object"`));
+    if (typeViolations.length > 0) {
+        throw new Error(`validateArgs: true but inputSchema implies an object shape without declaring it:\n` +
+            typeViolations.join("\n") +
+            '\nAdd type: "object" (or include it in a union), or set validateArgs: false');
+    }
+};
+export const createToolRegistry = (tools, options = {}) => {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    if (byName.size !== tools.length) {
+        throw new Error("duplicate tool names in registry");
+    }
+    const validateArgs = options.validateArgs !== false;
+    if (validateArgs)
+        assertToolSchemasValid(tools);
+    return {
+        list: (allowScope) => tools
+            .filter((tool) => !allowScope || allowScope(tool.scope))
+            .map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+        })),
+        get: (name) => byName.get(name),
+        call: async (name, ctx, args) => {
+            const tool = byName.get(name);
+            if (!tool)
+                return errorResult(`Unknown tool: ${name}`);
+            if (validateArgs) {
+                const errors = validateAgainstSchema(args, tool.inputSchema);
+                if (errors.length > 0)
+                    return errorResult(errors.join("; "));
+            }
+            try {
+                return asToolResult(await tool.handler(ctx, args));
+            }
+            catch (caught) {
+                return errorResult(resolveToolError(caught, options.onToolError));
+            }
+        },
+    };
+};
+//# sourceMappingURL=registry.js.map

package/dist/mcp/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/mcp/registry.ts"],"names":[],"mappings":"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"}

package/dist/mcp/rpc-handlers.d.ts

@@ -0,0 +1,11 @@
+/** JSON-RPC method handlers and authenticated dispatch. */
+import { type JsonRpcRequest } from "./jsonrpc.js";
+import { type ResolvedMcpHandlerOptions } from "./methods.js";
+export declare const dispatchRpc: <TCtx>(input: {
+    req: Request;
+    body: JsonRpcRequest;
+    options: ResolvedMcpHandlerOptions<TCtx>;
+    /** Request start (captured in `createMcpHandler.fetch`), for denial-path audit timing. */
+    startedAt: number;
+}) => Promise<Response>;
+//# sourceMappingURL=rpc-handlers.d.ts.map

package/dist/mcp/rpc-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-handlers.d.ts","sourceRoot":"","sources":["../../src/mcp/rpc-handlers.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAI3D,OAAO,EAIL,KAAK,cAAc,EAGpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAOL,KAAK,yBAAyB,EAI/B,MAAM,cAAc,CAAC;AA8ItB,eAAO,MAAM,WAAW,GAAU,IAAI,EAAE,OAAO;IAC7C,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,yBAAyB,CAAC,IAAI,CAAC,CAAC;IACzC,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;CACnB,KAAG,OAAO,CAAC,QAAQ,CAkCnB,CAAC"}

package/dist/mcp/rpc-handlers.js

@@ -0,0 +1,133 @@
+/** JSON-RPC method handlers and authenticated dispatch. */
+import { jsonResponse } from "../http/http.js";
+import { isJsonObject } from "../util/json.js";
+import { JSONRPC_INVALID_PARAMS, JSONRPC_METHOD_NOT_FOUND, rpcError, rpcResult, } from "./jsonrpc.js";
+import { DENIAL_REASONS, hasScope, insufficientScope, resolveWwwAuthenticate, safeAudit, unauthorized, } from "./methods.js";
+import { pickProtocolVersion } from "./protocol.js";
+/** The one shape every "tools/call" outcome — unknown tool, missing scope, or a real call — audits. */
+const auditToolCall = (options, input) => safeAudit(options, {
+    method: "tools/call",
+    tool: input.tool,
+    principalId: input.principal?.id,
+    ok: input.ok,
+    error: input.error,
+    durationMs: Date.now() - input.startedAt,
+});
+const parseToolCallArgs = (body) => {
+    const params = body.params ?? {};
+    const name = String(params.name ?? "");
+    const args = isJsonObject(params.arguments) ? params.arguments : {};
+    return { name, args };
+};
+/**
+ * A name that doesn't refer to any registered tool is a malformed request,
+ * not a tool execution outcome — MCP distinguishes protocol errors (a
+ * standard JSON-RPC error response) from a tool's own isError: true result,
+ * and "no such tool" belongs to the former. `ToolRegistry.call`'s own
+ * "Unknown tool: …" text-result fallback stays as is for direct callers of
+ * that API outside this dispatch.
+ */
+const unknownToolResponse = async (options, input) => {
+    await auditToolCall(options, {
+        ...input,
+        tool: input.name,
+        ok: false,
+        error: DENIAL_REASONS.unknownTool,
+    });
+    return jsonResponse({
+        data: rpcError(input.id, JSONRPC_INVALID_PARAMS, `Unknown tool: ${input.name}`),
+    });
+};
+const missingScopeResponse = async (req, options, input) => {
+    await auditToolCall(options, {
+        ...input,
+        tool: input.name,
+        ok: false,
+        error: DENIAL_REASONS.missingScope,
+    });
+    const wwwAuthenticate = resolveWwwAuthenticate(options, req);
+    // No principal at all (only reachable when a host adds "tools/call" to
+    // `publicMethods`) → 401, nothing was presented to authenticate with.
+    // A principal that authenticated but lacks the tool's scope → 403
+    // insufficient_scope (RFC 6750 §3.1) — see `insufficientScope`'s doc.
+    return input.principal
+        ? insufficientScope(wwwAuthenticate, input.scope, input.id)
+        : unauthorized(wwwAuthenticate, `Missing scope: ${input.scope}`, input.id);
+};
+const METHODS = {
+    initialize: async ({ id, body, options }) => jsonResponse({
+        data: rpcResult(id, {
+            protocolVersion: pickProtocolVersion(body.params),
+            capabilities: { tools: {} },
+            serverInfo: options.serverInfo,
+            instructions: options.instructions ?? "",
+        }),
+    }),
+    ping: async ({ id }) => jsonResponse({ data: rpcResult(id, {}) }),
+    "tools/list": async ({ id, options, principal }) => {
+        const allowScope = options.hideToolsOutsideScope
+            ? (scope) => !scope || (principal ? hasScope(principal, scope) : false)
+            : undefined;
+        return jsonResponse({ data: rpcResult(id, { tools: options.registry.list(allowScope) }) });
+    },
+    "tools/call": async ({ req, body, id, principal, options, startedAt }) => {
+        const { name, args } = parseToolCallArgs(body);
+        const tool = options.registry.get(name);
+        if (!tool)
+            return unknownToolResponse(options, { name, principal, id, startedAt });
+        if (tool.scope && (!principal || !hasScope(principal, tool.scope))) {
+            return missingScopeResponse(req, options, {
+                name,
+                principal,
+                id,
+                startedAt,
+                scope: tool.scope,
+            });
+        }
+        // Built only for a call that will actually run: `initialize`, `ping`,
+        // `tools/list` and denied calls never reach the host's `context` port.
+        const ctx = await options.ports.context(req, principal);
+        const toolStartedAt = Date.now();
+        const result = await options.registry.call(name, ctx, args);
+        await auditToolCall(options, {
+            tool: name,
+            principal,
+            ok: !result.isError,
+            error: result.isError ? result.content[0]?.text : undefined,
+            startedAt: toolStartedAt,
+        });
+        return jsonResponse({ data: rpcResult(id, result) });
+    },
+};
+export const dispatchRpc = async (input) => {
+    const { req, body, options, startedAt } = input;
+    // Shape-validated in `handlePost` before routing — method is a non-empty string.
+    const method = typeof body.method === "string" ? body.method : "";
+    // Notifications omit `id`; explicit null is a valid request id (JSON-RPC).
+    const id = body.id === undefined ? null : body.id;
+    const toolName = method === "tools/call" ? String(body.params?.name ?? "") : undefined;
+    // Notifications (including every `notifications/*`) already got 202 in `handlePost`.
+    const isPublic = options.publicMethods.has(method);
+    let principal = null;
+    if (!isPublic) {
+        principal = await options.ports.authenticate(req, method, toolName);
+        if (!principal) {
+            await safeAudit(options, {
+                method,
+                tool: toolName,
+                ok: false,
+                error: DENIAL_REASONS.unauthorized,
+                durationMs: Date.now() - startedAt,
+            });
+            return unauthorized(resolveWwwAuthenticate(options, req), undefined, id);
+        }
+    }
+    const handler = METHODS[method];
+    if (!handler) {
+        return jsonResponse({
+            data: rpcError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${method}`),
+        });
+    }
+    return handler({ req, body, id, principal, options, startedAt });
+};
+//# sourceMappingURL=rpc-handlers.js.map

package/dist/mcp/rpc-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-handlers.js","sourceRoot":"","sources":["../../src/mcp/rpc-handlers.ts"],"names":[],"mappings":"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"}

package/dist/{tools.d.ts → mcp/tools.d.ts}

@@ -42,7 +42,8 @@ type ToolCore = {
     description: string;
     /** Advertised via tools/list. Required — see module doc for why. */
     inputSchema: JsonSchema;
-    scope?: string | undefined;
+    /** See `ToolDef.scope` — pass `null` to explicitly opt out of a scope check. */
+    scope?: string | null | undefined;
 };
 type ToolHandler<TCtx, Args> = (ctx: TCtx, args: Args) => Promise<ToolResult | string> | ToolResult | string;
 type ValidatedInput<Input> = {
@@ -76,6 +77,24 @@ type ApiExtra<TCtx, Args> = {
      */
     onError?: (res: Response) => Promise<ToolResult | string> | ToolResult | string;
     fetch?: typeof fetch;
+    /**
+     * Abort the upstream request after this many ms. Default 30000. An
+     * upstream that never responds otherwise hangs the tool call (and the
+     * MCP request behind it) indefinitely. Pass `false` to disable — the
+     * request then relies entirely on whatever signal (if any) is already on
+     * the `Request` your `request` callback returns; a timeout firing surfaces
+     * as `isError: true`, not a thrown exception `onToolError` would redact.
+     */
+    timeoutMs?: number | false;
+    /**
+     * Cap the upstream response body at this many bytes before it ever
+     * reaches `respond`/`onError`/the default error path — an unbounded
+     * `res.text()` on an attacker-influenced or merely oversized upstream
+     * response is the same memory-exhaustion shape an unbounded *incoming*
+     * request body is (see `body.ts`). Default 1 MiB. Exceeding it surfaces
+     * as `isError: true`, not a thrown exception `onToolError` would redact.
+     */
+    maxResponseBytes?: number;
 };
 export type ApiToolOptions<TCtx, Input = Record<string, unknown>> = (ToolCore & ValidatedInput<Input> & ApiExtra<TCtx, Input>) | (ToolCore & RawInput & ApiExtra<TCtx, Record<string, unknown>>);
 /**

package/dist/mcp/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}