mcp-trellis 0.2.1 → 2.1.0

package/dist/http/origins.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Origin allowlisting — Host-derived Node origins (multi-tenant) and browser
+ * `Origin` headers on MCP (DNS rebinding / CSRF). Same predicate shape as
+ * redirect allowlisting — not secret comparison.
+ */
+export type OriginAllowlistOptions = {
+    /**
+     * Exact origins (`https://acme.example.com`) and/or `*.example.com`
+     * wildcards. Wildcards match https subdomains only (not the apex, not http).
+     * `"*"` admits any origin (loud opt-out).
+     *
+     * Empty/omitted list → admit all (only safe with a fixed `asNodeHandler`
+     * `origin`). Host-derived `asNodeHandler` requires a non-empty list at
+     * construction. Resolved origin outside the list → 400; a fixed `origin`
+     * absent from a non-empty list throws at construction.
+     */
+    allowedOrigins?: string[];
+};
+/**
+ * Host-derived / allowlist Origin check (Node `asNodeHandler` multi-tenant).
+ * Empty or omitted `allowedOrigins` → admit all (callers that derive origin
+ * from Host must require a non-empty list before reaching here).
+ * `"*"` admits any origin.
+ */
+export declare const isAllowedOrigin: (origin: string, options?: OriginAllowlistOptions) => boolean;
+/**
+ * Browser `Origin` on MCP Streamable HTTP (DNS rebinding / CSRF).
+ * No header → allow (native / server-to-server). Empty or omitted allowlist →
+ * deny any present Origin (secure default — opposite of `isAllowedOrigin`).
+ * `"*"` opts out.
+ */
+export declare const isAllowedRequestOrigin: (originHeader: string | null, allowedRequestOrigins?: string[]) => boolean;
+/** 403 when a present Origin fails the allowlist. `onDenied` runs first (audit). */
+export declare const requestOriginDenied: (request: Request, allowedRequestOrigins: string[] | undefined, onDenied?: () => Promise<void>) => Promise<Response | null>;
+/** When a non-wildcard allowlist admitted this Origin, reflect it on CORS. */
+export declare const reflectCorsIfNeeded: (response: Response, request: Request, allowedRequestOrigins: string[] | undefined) => Response;
+//# sourceMappingURL=origins.d.ts.map

package/dist/http/origins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origins.d.ts","sourceRoot":"","sources":["../../src/http/origins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAyCF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,EAAE,UAAS,sBAA2B,KAAG,OAMtF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,cAAc,MAAM,GAAG,IAAI,EAC3B,wBAAwB,MAAM,EAAE,KAC/B,OAIF,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,GAC9B,SAAS,OAAO,EAChB,uBAAuB,MAAM,EAAE,GAAG,SAAS,EAC3C,WAAW,MAAM,OAAO,CAAC,IAAI,CAAC,KAC7B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAMzB,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,GAC9B,UAAU,QAAQ,EAClB,SAAS,OAAO,EAChB,uBAAuB,MAAM,EAAE,GAAG,SAAS,KAC1C,QAMF,CAAC"}

package/dist/http/origins.js

@@ -0,0 +1,87 @@
+/**
+ * Origin allowlisting — Host-derived Node origins (multi-tenant) and browser
+ * `Origin` headers on MCP (DNS rebinding / CSRF). Same predicate shape as
+ * redirect allowlisting — not secret comparison.
+ */
+import { jsonResponse, withReflectedCorsOrigin } from "./http.js";
+const originOf = (value) => {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return null;
+    }
+};
+const isExactOrigin = (origin, options) => {
+    const normalized = originOf(origin);
+    if (!normalized)
+        return false;
+    return Boolean(options.allowedOrigins?.some((entry) => {
+        if (entry.startsWith("*."))
+            return false;
+        return originOf(entry) === normalized;
+    }));
+};
+/** `*.example.com` matches `https://acme.example.com`, not the apex, not http. */
+const isWildcardSubdomain = (origin, options) => {
+    const patterns = options.allowedOrigins ?? [];
+    try {
+        const { protocol, hostname } = new URL(origin);
+        if (protocol !== "https:")
+            return false;
+        return patterns.some((entry) => {
+            if (!entry.startsWith("*."))
+                return false;
+            const suffix = entry.slice(1); // ".example.com"
+            return hostname.endsWith(suffix) && hostname.length > suffix.length;
+        });
+    }
+    catch {
+        return false;
+    }
+};
+const ORIGIN_PREDICATES = [isExactOrigin, isWildcardSubdomain];
+/**
+ * Host-derived / allowlist Origin check (Node `asNodeHandler` multi-tenant).
+ * Empty or omitted `allowedOrigins` → admit all (callers that derive origin
+ * from Host must require a non-empty list before reaching here).
+ * `"*"` admits any origin.
+ */
+export const isAllowedOrigin = (origin, options = {}) => {
+    if (!options.allowedOrigins || options.allowedOrigins.length === 0) {
+        return true;
+    }
+    if (options.allowedOrigins.includes("*"))
+        return true;
+    return ORIGIN_PREDICATES.some((predicate) => predicate(origin, options));
+};
+/**
+ * Browser `Origin` on MCP Streamable HTTP (DNS rebinding / CSRF).
+ * No header → allow (native / server-to-server). Empty or omitted allowlist →
+ * deny any present Origin (secure default — opposite of `isAllowedOrigin`).
+ * `"*"` opts out.
+ */
+export const isAllowedRequestOrigin = (originHeader, allowedRequestOrigins) => {
+    if (!originHeader)
+        return true;
+    if (!allowedRequestOrigins || allowedRequestOrigins.length === 0)
+        return false;
+    return isAllowedOrigin(originHeader, { allowedOrigins: allowedRequestOrigins });
+};
+/** 403 when a present Origin fails the allowlist. `onDenied` runs first (audit). */
+export const requestOriginDenied = async (request, allowedRequestOrigins, onDenied) => {
+    if (isAllowedRequestOrigin(request.headers.get("Origin"), allowedRequestOrigins)) {
+        return null;
+    }
+    await onDenied?.();
+    return jsonResponse({ data: { error: "origin not allowed" }, status: 403, cors: false });
+};
+/** When a non-wildcard allowlist admitted this Origin, reflect it on CORS. */
+export const reflectCorsIfNeeded = (response, request, allowedRequestOrigins) => {
+    const origin = request.headers.get("Origin");
+    if (!origin || !allowedRequestOrigins?.length || allowedRequestOrigins.includes("*")) {
+        return response;
+    }
+    return withReflectedCorsOrigin(response, origin);
+};
+//# sourceMappingURL=origins.js.map

package/dist/http/origins.js.map

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

package/dist/mcp/dispatch.d.ts

@@ -0,0 +1,7 @@
+import { type McpHandlerOptions } from "./methods.js";
+export type { AuditEntry, McpHandlerOptions, McpPorts, Principal, ServerInfo, } from "./methods.js";
+export type McpHandler = {
+    fetch: (request: Request) => Promise<Response>;
+};
+export declare const createMcpHandler: <TCtx>(handlerOptions: McpHandlerOptions<TCtx>) => McpHandler;
+//# sourceMappingURL=dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/mcp/dispatch.ts"],"names":[],"mappings":"AAmBA,OAAO,EAIL,KAAK,iBAAiB,EAKvB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChD,CAAC;AAkFF,eAAO,MAAM,gBAAgB,GAAI,IAAI,EAAE,gBAAgB,iBAAiB,CAAC,IAAI,CAAC,KAAG,UAwChF,CAAC"}

package/dist/mcp/dispatch.js

@@ -0,0 +1,99 @@
+import { rejectQueryToken } from "../auth/bearer.js";
+import { BodyTooLargeError, DEFAULT_MCP_BODY_LIMIT, readBoundedText } from "../http/body.js";
+import { emptyResponse, errorReason, INTERNAL_ERROR, jsonResponse, methodNotAllowed, optionsResponse, } from "../http/http.js";
+import { reflectCorsIfNeeded, requestOriginDenied } from "../http/origins.js";
+import { JSONRPC_INTERNAL_ERROR, JSONRPC_PARSE_ERROR, JSONRPC_PAYLOAD_TOO_LARGE, protocolVersionHeaderError, rpcError, validateJsonRpcEnvelope, } from "./jsonrpc.js";
+import { DEFAULT_PUBLIC_METHODS, DENIAL_REASONS, isNotification, resolveWwwAuthenticate, safeAudit, unauthorized, } from "./methods.js";
+import { dispatchRpc } from "./rpc-handlers.js";
+const parseBody = async (request) => {
+    let text;
+    try {
+        text = await readBoundedText(request, DEFAULT_MCP_BODY_LIMIT);
+    }
+    catch (caught) {
+        if (caught instanceof BodyTooLargeError) {
+            return jsonResponse({
+                data: rpcError(null, JSONRPC_PAYLOAD_TOO_LARGE, "Payload too large"),
+                status: 413,
+            });
+        }
+        return jsonResponse({ data: rpcError(null, JSONRPC_PARSE_ERROR, "Parse error"), status: 400 });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return jsonResponse({ data: rpcError(null, JSONRPC_PARSE_ERROR, "Parse error"), status: 400 });
+    }
+};
+/** Transport-level denial: no JSON-RPC method has been parsed yet. */
+const auditDenial = (options, error, startedAt) => safeAudit(options, { method: "", ok: false, error, durationMs: Date.now() - startedAt });
+const denyQueryStringToken = async (request, options, startedAt) => {
+    if (rejectQueryToken(new URL(request.url))) {
+        await auditDenial(options, DENIAL_REASONS.queryStringToken, startedAt);
+        return unauthorized(resolveWwwAuthenticate(options, request), "Token in query string is rejected. Use Authorization Bearer.");
+    }
+    return null;
+};
+const handleGet = async (request, options, startedAt) => {
+    const denied = await denyQueryStringToken(request, options, startedAt);
+    if (denied)
+        return denied;
+    if (!request.headers.get("authorization")) {
+        await auditDenial(options, DENIAL_REASONS.unauthorized, startedAt);
+        return unauthorized(resolveWwwAuthenticate(options, request));
+    }
+    return methodNotAllowed("Use POST for MCP");
+};
+const handlePost = async (request, options, startedAt) => {
+    const denied = await denyQueryStringToken(request, options, startedAt);
+    if (denied)
+        return denied;
+    const parsed = await parseBody(request);
+    if (parsed instanceof Response)
+        return parsed;
+    const envelope = validateJsonRpcEnvelope(parsed);
+    if (envelope instanceof Response)
+        return envelope;
+    const versionError = protocolVersionHeaderError(request, envelope);
+    if (versionError)
+        return versionError;
+    if (isNotification(envelope))
+        return emptyResponse(202);
+    return dispatchRpc({ req: request, body: envelope, options, startedAt });
+};
+export const createMcpHandler = (handlerOptions) => {
+    const options = {
+        ...handlerOptions,
+        publicMethods: handlerOptions.publicMethods ?? DEFAULT_PUBLIC_METHODS,
+    };
+    const HTTP_METHODS = {
+        OPTIONS: () => optionsResponse(),
+        GET: (request, startedAt) => handleGet(request, options, startedAt),
+        POST: (request, startedAt) => handlePost(request, options, startedAt),
+    };
+    return {
+        fetch: async (request) => {
+            const startedAt = Date.now();
+            try {
+                const originDenied = await requestOriginDenied(request, options.allowedRequestOrigins, () => auditDenial(options, DENIAL_REASONS.originNotAllowed, startedAt));
+                if (originDenied)
+                    return originDenied;
+                const handler = HTTP_METHODS[request.method];
+                const response = await (handler ? handler(request, startedAt) : methodNotAllowed());
+                return reflectCorsIfNeeded(response, request, options.allowedRequestOrigins);
+            }
+            catch (caught) {
+                // A host port (authenticate/context/audit) threw. `fetch` must never
+                // reject — the caller gets an honest 500, not an unhandled rejection
+                // whose shape depends on which runtime is hosting this.
+                await auditDenial(options, errorReason(caught) || INTERNAL_ERROR, startedAt);
+                return reflectCorsIfNeeded(jsonResponse({
+                    data: rpcError(null, JSONRPC_INTERNAL_ERROR, "Internal error"),
+                    status: 500,
+                }), request, options.allowedRequestOrigins);
+            }
+        },
+    };
+};
+//# sourceMappingURL=dispatch.js.map

package/dist/mcp/dispatch.js.map

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

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

@@ -27,6 +27,16 @@ export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
 export declare const JSONRPC_INVALID_PARAMS = -32602;
 export declare const JSONRPC_INTERNAL_ERROR = -32603;
 export declare const JSONRPC_UNAUTHORIZED = -32001;
+export declare const JSONRPC_PAYLOAD_TOO_LARGE = -32002;
+/** Authenticated but missing required scope — paired with HTTP 403. */
+export declare const JSONRPC_INSUFFICIENT_SCOPE = -32003;
 export declare const rpcResult: (id: JsonRpcId, result: unknown) => JsonRpcSuccess;
 export declare const rpcError: (id: JsonRpcId, code: number, message: string) => JsonRpcFailure;
+/** Batch / jsonrpc version / shape — returns a Response or a validated request. */
+export declare const validateJsonRpcEnvelope: (parsed: unknown) => Response | JsonRpcRequest;
+/**
+ * Spec requires `MCP-Protocol-Version` past `initialize`. Unknown → 400.
+ * Missing → assume `2025-03-26` (header BC rule; see `protocol.ts`).
+ */
+export declare const protocolVersionHeaderError: (request: Request, jsonRpcRequest: JsonRpcRequest) => Response | null;
 //# sourceMappingURL=jsonrpc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../../src/mcp/jsonrpc.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,cAAc,CAAC;AAE9D,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAC1C,eAAO,MAAM,uBAAuB,SAAS,CAAC;AAC9C,eAAO,MAAM,wBAAwB,SAAS,CAAC;AAC/C,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAC7C,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAC7C,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAC3C,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,uEAAuE;AACvE,eAAO,MAAM,0BAA0B,SAAS,CAAC;AAEjD,eAAO,MAAM,SAAS,GAAI,IAAI,SAAS,EAAE,QAAQ,OAAO,KAAG,cAIzD,CAAC;AAEH,eAAO,MAAM,QAAQ,GAAI,IAAI,SAAS,EAAE,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,cAItE,CAAC;AAwCH,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,GAAI,QAAQ,OAAO,KAAG,QAAQ,GAAG,cAkBpE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,OAAO,EAChB,gBAAgB,cAAc,KAC7B,QAAQ,GAAG,IAYb,CAAC"}

package/dist/mcp/jsonrpc.js

@@ -0,0 +1,88 @@
+import { jsonResponse } from "../http/http.js";
+import { PROTOCOL_VERSIONS } from "./protocol.js";
+export const JSONRPC_PARSE_ERROR = -32700;
+export const JSONRPC_INVALID_REQUEST = -32600;
+export const JSONRPC_METHOD_NOT_FOUND = -32601;
+export const JSONRPC_INVALID_PARAMS = -32602;
+export const JSONRPC_INTERNAL_ERROR = -32603;
+export const JSONRPC_UNAUTHORIZED = -32001;
+export const JSONRPC_PAYLOAD_TOO_LARGE = -32002;
+/** Authenticated but missing required scope — paired with HTTP 403. */
+export const JSONRPC_INSUFFICIENT_SCOPE = -32003;
+export const rpcResult = (id, result) => ({
+    jsonrpc: "2.0",
+    id,
+    result,
+});
+export const rpcError = (id, code, message) => ({
+    jsonrpc: "2.0",
+    id,
+    error: { code, message },
+});
+const isJsonRpcId = (id) => id === null || typeof id === "string" || typeof id === "number";
+/**
+ * RFC-shaped JSON-RPC id for an error response — omitted → `null`; valid ids
+ * echoed; invalid shapes → `null` so we never reflect an illegal id.
+ */
+const errorId = (jsonRpcRequest) => {
+    if (jsonRpcRequest.id === undefined)
+        return null;
+    return isJsonRpcId(jsonRpcRequest.id) ? jsonRpcRequest.id : null;
+};
+/** Runtime JSON-RPC Request shape — types alone do not enforce this. */
+const jsonRpcShapeError = (jsonRpcRequest) => {
+    if (jsonRpcRequest.id !== undefined && !isJsonRpcId(jsonRpcRequest.id)) {
+        return jsonResponse({
+            data: rpcError(null, JSONRPC_INVALID_REQUEST, "id must be string, number, or null"),
+            status: 400,
+        });
+    }
+    const orphanResult = jsonRpcRequest.method === undefined &&
+        jsonRpcRequest.id === undefined &&
+        "result" in jsonRpcRequest;
+    if (orphanResult)
+        return null;
+    if (typeof jsonRpcRequest.method !== "string" || jsonRpcRequest.method.length === 0) {
+        return jsonResponse({
+            data: rpcError(errorId(jsonRpcRequest), JSONRPC_INVALID_REQUEST, "method must be a non-empty string"),
+            status: 400,
+        });
+    }
+    return null;
+};
+/** Batch / jsonrpc version / shape — returns a Response or a validated request. */
+export const validateJsonRpcEnvelope = (parsed) => {
+    if (Array.isArray(parsed)) {
+        return jsonResponse({
+            data: rpcError(null, JSONRPC_INVALID_REQUEST, "Batch requests not supported"),
+            status: 400,
+        });
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return jsonResponse({ data: rpcError(null, JSONRPC_PARSE_ERROR, "Parse error"), status: 400 });
+    }
+    const jsonRpcRequest = parsed;
+    if (jsonRpcRequest.jsonrpc !== "2.0") {
+        return jsonResponse({
+            data: rpcError(errorId(jsonRpcRequest), JSONRPC_INVALID_REQUEST, 'jsonrpc must be "2.0"'),
+            status: 400,
+        });
+    }
+    return jsonRpcShapeError(jsonRpcRequest) ?? jsonRpcRequest;
+};
+/**
+ * Spec requires `MCP-Protocol-Version` past `initialize`. Unknown → 400.
+ * Missing → assume `2025-03-26` (header BC rule; see `protocol.ts`).
+ */
+export const protocolVersionHeaderError = (request, jsonRpcRequest) => {
+    if (jsonRpcRequest.method === "initialize")
+        return null;
+    const header = request.headers.get("MCP-Protocol-Version");
+    if (!header || PROTOCOL_VERSIONS.has(header))
+        return null;
+    return jsonResponse({
+        data: rpcError(errorId(jsonRpcRequest), JSONRPC_INVALID_REQUEST, `Unsupported MCP-Protocol-Version: ${header}`),
+        status: 400,
+    });
+};
+//# sourceMappingURL=jsonrpc.js.map

package/dist/mcp/jsonrpc.js.map

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

package/dist/mcp/methods.d.ts

@@ -0,0 +1,133 @@
+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;
+};
+/** Per-request metrics emitted through the optional `audit` port. */
+export type AuditEntry = {
+    /** JSON-RPC method, or `""` for transport-level rejections made before parsing. */
+    method: string;
+    tool?: string | undefined;
+    principalId?: string | undefined;
+    ok: boolean;
+    error?: string | undefined;
+    durationMs: number;
+};
+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
+     * denials (bad token, missing scope, query-string token), plus the 500
+     * path when a host port throws. Protocol errors (malformed JSON, bad
+     * `jsonrpc`, unsupported protocol version, oversized body, batch) are not
+     * audited. Omit it and the library stays silent — no stdout, no store.
+     * Do what you want with `entry` (DB, APM, admin UI). Throwing never fails
+     * the request, and neither does hanging — see
+     * `McpHandlerOptions.auditTimeoutMs`.
+     */
+    audit?: ((entry: AuditEntry) => void | Promise<void>) | undefined;
+};
+export type ServerInfo = {
+    name: string;
+    version: string;
+};
+export type McpHandlerOptions<TCtx> = {
+    registry: ToolRegistry<TCtx>;
+    ports: McpPorts<TCtx>;
+    serverInfo: ServerInfo;
+    instructions?: string;
+    wwwAuthenticate: WwwAuthenticateOptions | ((req: Request) => WwwAuthenticateOptions);
+    /** Methods that skip auth (default: initialize, ping, notifications/*). */
+    publicMethods?: Set<string>;
+    /**
+     * Max time to wait for `ports.audit` before giving up on it and
+     * responding anyway. Default 1000ms. A hanging audit sink can't fail a
+     * request (see `safeAudit`), but without this it could stall one
+     * 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 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
+ * 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 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
+ * 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 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;
+//# 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/mcp/protocol.d.ts

@@ -0,0 +1,16 @@
+export declare const PROTOCOL_VERSIONS: Set<string>;
+/**
+ * Answered on `initialize` when the client's requested version is missing
+ * or unrecognized: per the spec, the latest version this server supports.
+ */
+export declare const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * The assumed protocol version for a request that omits the
+ * `MCP-Protocol-Version` header — distinct from `DEFAULT_PROTOCOL_VERSION`
+ * above. This is the 2025-06-18 spec's own backwards-compatibility rule
+ * for the header specifically (introduced in that revision, so a header-less
+ * request predates it), not a "pick the newest" preference.
+ */
+export declare const ASSUMED_HEADER_PROTOCOL_VERSION = "2025-03-26";
+export declare const pickProtocolVersion: (params?: Record<string, unknown>) => string;
+//# sourceMappingURL=protocol.d.ts.map

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"}