@try-works/dsh-model-as-tool 0.1.3 → 0.4.0

package/lib/mcp/protocol.js

@@ -46,8 +46,15 @@ export const META_KEYS = {
  * Error codes.
  *
  * The reserved range belongs to the protocol. P26-03 is explicit that custom
- * errors must not be allocated there, so this module declares only codes the
- * revision defines and refuses to mint new ones in that band.
+ * errors must not be allocated there, and the pinned revision partitions the
+ * bands: `-32768..-32000` is JSON-RPC's own predefined-error allocation,
+ * `-32020..-32099` is reserved for MCP-defined codes (allocated sequentially,
+ * and this module declares exactly those the revision defines), while
+ * `-32000..-32019` is the IMPLEMENTATION-DEFINED sub-range — the specification
+ * will never define codes there, and receivers must not assume cross-
+ * implementation semantics. `rateLimited` lives in that sub-range deliberately:
+ * it is a documented implementation allocation, never a minted code in the
+ * reserved band.
  */
 export const ERROR_CODES = {
     /** Standard JSON-RPC. */
@@ -60,6 +67,16 @@ export const ERROR_CODES = {
     headerMismatch: -32020,
     unsupportedClientCapability: -32021,
     unsupportedProtocolVersion: -32022,
+    /**
+     * Implementation-defined (-32000..-32019, never allocated by the specification).
+     *
+     * The revision defines NO rate-limit error, so a refusal uses this documented
+     * implementation code rather than pretending the request was invalid (-32600) or
+     * minting a code in the MCP-reserved band. The HTTP 429 status carries the
+     * semantics; receivers that do not know this code still get a conformant
+     * `JSONRPCErrorResponse` envelope and a `Retry-After` header.
+     */
+    rateLimited: -32001,
 };
 /** Raised for a request that must be answered with a JSON-RPC error. */
 export class WireError extends Error {
@@ -158,10 +175,14 @@ export function negotiateVersion(metadata) {
 export const ADVERTISED_FEATURES = [
     { feature: 'tools', implemented: true },
     { feature: 'server/discover', implemented: true },
-    // Now implemented, for TOOL-catalog changes only. P26-12 forbids advertising a
-    // feature that is not implemented, and permits advertising one that is: the
-    // acknowledgement reports the supported subset, so the narrower reality is stated
-    // on the wire rather than implied here.
+    /**
+     * Implemented for TOOL-catalog changes only, and ONLY when a registry is composed.
+     *
+     * This row is re-decided by dvertisedFeatures(), which defaults it to alse:
+     * the production transport passes no registry, so the row as written here is the
+     * capability's SHAPE rather than a claim about the deployment. Declaring it true
+     * statically is what let an unservable feature be advertised.
+     */
     { feature: 'subscriptions/listen', implemented: true },
     { feature: 'tasks', implemented: false },
     { feature: 'sampling', implemented: false },
@@ -171,15 +192,37 @@ export const ADVERTISED_FEATURES = [
     { feature: 'resources/subscribe', implemented: false },
     { feature: 'logging', implemented: false },
 ];
+/**
+ * What the server may advertise, given what is ACTUALLY WIRED (P26-12).
+ *
+ * The static matrix declared `subscriptions/listen` as implemented unconditionally — while
+ * the only production transport never received a registry and therefore answered `-32601`
+ * for it. An advertised feature that no client can obtain is worse than an absent one: a
+ * client plans around it and fails later.
+ *
+ * The feature is now conditional on the wiring, and the DEFAULT is `false` because that is
+ * the production reality. A caller that has genuinely composed a subscription registry says
+ * so; nothing else can make the claim true by declaring it.
+ *
+ * @param wiring - which optional surfaces are composed.
+ * @returns the advertised-feature matrix for this deployment.
+ */
+export function advertisedFeatures(wiring = {}) {
+    return ADVERTISED_FEATURES.map(entry => 
+    // Only the composed feature is re-decided; everything else keeps its declared truth.
+    entry.feature === 'subscriptions/listen'
+        ? { feature: entry.feature, implemented: wiring.subscriptions === true }
+        : entry);
+}
 /**
  * The capabilities object this server may advertise.
  *
- * Derived from {@link ADVERTISED_FEATURES} rather than written twice, so the
- * matrix and the advertised capabilities cannot disagree.
- * @returns the capability names that are genuinely implemented.
+ * Derived from the matrix rather than written twice, so the two cannot disagree.
+ * @param wiring - which optional surfaces are composed.
+ * @returns the capability names that are genuinely implemented HERE.
  */
-export function implementedCapabilities() {
-    return ADVERTISED_FEATURES.filter(entry => entry.implemented).map(entry => entry.feature);
+export function implementedCapabilities(wiring = {}) {
+    return advertisedFeatures(wiring).filter(entry => entry.implemented).map(entry => entry.feature);
 }
 /**
  * Whether a client's REQUIRED capability is one this server supports (P26-03).
@@ -187,11 +230,11 @@ export function implementedCapabilities() {
  * @param required - capability names the client declared as required.
  * @returns the unsupported names, empty when all are supported.
  */
-export function unsupportedRequiredCapabilities(required) {
-    const implemented = new Set(implementedCapabilities());
-    // `tools` is the only capability a client can require of this server today; any
-    // other requirement cannot be met, and P26-03 wants that answered with -32021
-    // rather than attempted.
+export function unsupportedRequiredCapabilities(required, wiring = {}) {
+    const implemented = new Set(implementedCapabilities(wiring));
+    // The supported set is deployment-specific: `subscriptions/listen` is available only
+    // when the caller composed a subscription registry. A static default here rejected a
+    // capability that the very same dispatch call could serve.
     return required.filter(name => !implemented.has(name));
 }
 /**
@@ -327,6 +370,10 @@ export function assertHeadersMatch(headers, body) {
         return fail(`the MCP-Protocol-Version header (${version}) does not match the request body (${bodyVersion})`);
     }
     const method = headers.method === undefined ? undefined : decodeHeaderValue(headers.method);
+    // Pinned Streamable HTTP: Mcp-Method is REQUIRED for every request, not
+    // merely checked when supplied. Never synthesize a missing authority header.
+    if (body.id !== undefined && method === undefined)
+        return fail('the Mcp-Method header is required');
     if (method !== undefined && method !== body.method) {
         return fail(`the Mcp-Method header (${method}) does not match the request method (${body.method})`);
     }

package/lib/mcp/rate-limit.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Per-client request rate limiting for the MCP HTTP transport (AT-12).
+ *
+ * AT-12's named gap was that the host had ZERO rate limiting: an authenticated client could
+ * drive unbounded inference traffic, and nothing anywhere counted it. This module is the
+ * counter. Its discipline is deliberate:
+ *
+ * - **Keyed on the AUTHENTICATED client identity, never the socket.** The remote address is
+ *   caller-forgeable (proxies, NAT, header tricks) and the endpoint is loopback-only anyway,
+ *   so every client would share one address and one bucket. The identity comes from the
+ *   transport's resolved authentication — the static-token `clientId` or the OAuth subject —
+ *   which is the one thing the transport already proved.
+ * - **Fixed-window buckets.** One counter per client per window. Simpler to reason about than
+ *   a token bucket, and its boundary semantics are exactly testable: a client that exhausted
+ *   a window is admitted again when the next window opens, with `retryAfterMs` naming when.
+ * - **Bounded in-memory state, never persisted.** Entries carry only a window, a count and a
+ *   last-seen timestamp; when the map is at capacity a NEW client evicts the longest-idle
+ *   entry, so a deployment cannot be grown without limit by many short-lived clients. A
+ *   restart forgets everything, which is correct for a burst guard: persistence would turn
+ *   a request limiter into an availability policy.
+ * - **Counting is not an auth oracle.** The HTTP layer admits a client only AFTER the
+ *   credential was accepted; an unauthenticated or malformed-credential request is refused
+ *   before any counter moves. Counting authentication failures would let a caller learn
+ *   whether a credential exists from the timing of a 429, which is the leak this refuses.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/rate-limit
+ */
+/** The policy one deployment enforces. */
+export interface RateLimitPolicy {
+    /** Requests admitted per window for ONE client. */
+    readonly maxRequests: number;
+    /** Window length in milliseconds. */
+    readonly windowMs: number;
+    /** Most clients tracked; a new client at capacity evicts the longest-idle entry. */
+    readonly maxClients: number;
+}
+/**
+ * The default policy: 60 requests per client per minute, 10 000 tracked clients.
+ *
+ * Sensible for a loopback single-user endpoint while still bounding a runaway client; an
+ * operator overrides it through the transport configuration.
+ */
+export declare const DEFAULT_RATE_LIMIT_POLICY: RateLimitPolicy;
+/** The verdict of one admission. */
+export type RateLimitDecision = {
+    readonly admitted: true;
+} | {
+    readonly admitted: false;
+    readonly retryAfterMs: number;
+};
+/** A per-client limiter. */
+export interface RateLimiter {
+    /** Consume one request for a client, refusing it when the window is exhausted. */
+    admit(clientId: string): RateLimitDecision;
+    /** Requests still available to this client in the current window. */
+    remaining(clientId: string): number;
+    /** How many clients are currently tracked. */
+    trackedClients(): number;
+}
+/**
+ * Create a per-client fixed-window rate limiter.
+ * @param policy - the enforced policy; fields are validated at construction so a broken
+ *   configuration fails when the transport starts, not on the first request.
+ * @param now - a clock, injectable so window boundaries are testable.
+ * @returns the limiter.
+ */
+export declare function createRateLimiter(policy: RateLimitPolicy, now?: () => number): RateLimiter;
+//# sourceMappingURL=rate-limit.d.ts.map

package/lib/mcp/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/mcp/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,eAIvC,CAAA;AAED,oCAAoC;AACpC,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/D,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAC1C,qEAAqE;IACrE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACnC,8CAA8C;IAC9C,cAAc,IAAI,MAAM,CAAA;CACzB;AAmBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,GAAG,GAAE,MAAM,MAAiB,GAC3B,WAAW,CA8Db"}

package/lib/mcp/rate-limit.js

@@ -0,0 +1,114 @@
+/**
+ * Per-client request rate limiting for the MCP HTTP transport (AT-12).
+ *
+ * AT-12's named gap was that the host had ZERO rate limiting: an authenticated client could
+ * drive unbounded inference traffic, and nothing anywhere counted it. This module is the
+ * counter. Its discipline is deliberate:
+ *
+ * - **Keyed on the AUTHENTICATED client identity, never the socket.** The remote address is
+ *   caller-forgeable (proxies, NAT, header tricks) and the endpoint is loopback-only anyway,
+ *   so every client would share one address and one bucket. The identity comes from the
+ *   transport's resolved authentication — the static-token `clientId` or the OAuth subject —
+ *   which is the one thing the transport already proved.
+ * - **Fixed-window buckets.** One counter per client per window. Simpler to reason about than
+ *   a token bucket, and its boundary semantics are exactly testable: a client that exhausted
+ *   a window is admitted again when the next window opens, with `retryAfterMs` naming when.
+ * - **Bounded in-memory state, never persisted.** Entries carry only a window, a count and a
+ *   last-seen timestamp; when the map is at capacity a NEW client evicts the longest-idle
+ *   entry, so a deployment cannot be grown without limit by many short-lived clients. A
+ *   restart forgets everything, which is correct for a burst guard: persistence would turn
+ *   a request limiter into an availability policy.
+ * - **Counting is not an auth oracle.** The HTTP layer admits a client only AFTER the
+ *   credential was accepted; an unauthenticated or malformed-credential request is refused
+ *   before any counter moves. Counting authentication failures would let a caller learn
+ *   whether a credential exists from the timing of a 429, which is the leak this refuses.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/rate-limit
+ */
+/**
+ * The default policy: 60 requests per client per minute, 10 000 tracked clients.
+ *
+ * Sensible for a loopback single-user endpoint while still bounding a runaway client; an
+ * operator overrides it through the transport configuration.
+ */
+export const DEFAULT_RATE_LIMIT_POLICY = {
+    maxRequests: 60,
+    windowMs: 60_000,
+    maxClients: 10_000,
+};
+/** Read a positive integer policy field, refusing a value that would mis-count. */
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`rate limit ${name} must be a positive integer, not ${String(value)}`);
+    }
+    return value;
+}
+/**
+ * Create a per-client fixed-window rate limiter.
+ * @param policy - the enforced policy; fields are validated at construction so a broken
+ *   configuration fails when the transport starts, not on the first request.
+ * @param now - a clock, injectable so window boundaries are testable.
+ * @returns the limiter.
+ */
+export function createRateLimiter(policy, now = Date.now) {
+    const maxRequests = positiveInteger(policy.maxRequests, 'maxRequests');
+    const windowMs = positiveInteger(policy.windowMs, 'windowMs');
+    const maxClients = positiveInteger(policy.maxClients, 'maxClients');
+    const buckets = new Map();
+    /** Evict the longest-idle client, so the map stays bounded while new clients arrive. */
+    const evictIdle = () => {
+        let oldest;
+        for (const [id, bucket] of buckets) {
+            if (oldest === undefined || bucket.lastSeen < oldest.lastSeen) {
+                oldest = { id, lastSeen: bucket.lastSeen };
+            }
+        }
+        if (oldest !== undefined)
+            buckets.delete(oldest.id);
+    };
+    const bucketFor = (clientId, at) => {
+        const existing = buckets.get(clientId);
+        if (existing !== undefined)
+            return existing;
+        if (buckets.size >= maxClients)
+            evictIdle();
+        const created = { window: 0, count: 0, lastSeen: at };
+        buckets.set(clientId, created);
+        return created;
+    };
+    const currentWindow = (at) => Math.floor(at / windowMs);
+    return {
+        admit(clientId) {
+            const at = now();
+            const bucket = bucketFor(clientId, at);
+            bucket.lastSeen = at;
+            const window = currentWindow(at);
+            // A NEW WINDOW RESETS the count: the client exhausted the PREVIOUS window, not all time.
+            if (bucket.window !== window) {
+                bucket.window = window;
+                bucket.count = 0;
+            }
+            if (bucket.count >= maxRequests) {
+                return {
+                    admitted: false,
+                    // The client is admitted again at the next window boundary.
+                    retryAfterMs: windowMs - (at % windowMs),
+                };
+            }
+            bucket.count += 1;
+            return { admitted: true };
+        },
+        remaining(clientId) {
+            const bucket = buckets.get(clientId);
+            if (bucket === undefined)
+                return maxRequests;
+            if (bucket.window !== currentWindow(now()))
+                return maxRequests;
+            return Math.max(0, maxRequests - bucket.count);
+        },
+        trackedClients() {
+            return buckets.size;
+        },
+    };
+}
+//# sourceMappingURL=rate-limit.js.map

package/lib/mcp/sdk-v2.d.ts

@@ -0,0 +1,17 @@
+import type { ExternalCaller } from './client-grant.ts';
+import type { McpHost } from './server.ts';
+import { type WireRequest } from './protocol.ts';
+/**
+ * Construct official serving around a caller already verified by the transport.
+ * No credentials or grants are accepted from JSON-RPC params. Each factory call
+ * reads the LIVE surface and creates a fresh server; business execution and its
+ * accounting remain exclusively in host.callTool / createMcpHost.
+ */
+export declare function createSdkV2Handler(host: McpHost, caller: ExternalCaller, incoming?: WireRequest): import("@modelcontextprotocol/server").McpHttpHandler;
+/**
+ * Live Fetch face. The per-request SDK handler belongs to the response body:
+ * close it on drain, cancellation, abort or error, never when fetch returns SSE.
+ * Linking a controller also makes a Web reader's cancel abort business execution.
+ */
+export declare function serveSdkV2Request(host: McpHost, caller: ExternalCaller, request: Request, token: string): Promise<Response>;
+//# sourceMappingURL=sdk-v2.d.ts.map

package/lib/mcp/sdk-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-v2.d.ts","sourceRoot":"","sources":["../../src/mcp/sdk-v2.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAEjE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,WAAW,yDA2E/F;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CA+DnB"}

package/lib/mcp/sdk-v2.js

@@ -0,0 +1,181 @@
+/**
+ * Official SDK v2 serving adapter, not a second business dispatcher.
+ *
+ * Upstream main inspected at 9bc40e903fde15534ec06ff4c1347d47000dbe16:
+ * https://github.com/modelcontextprotocol/typescript-sdk/blob/9bc40e903fde15534ec06ff4c1347d47000dbe16/docs/serving/http.md
+ * That revision's packages/server/package.json is 2.3.1; runtime uses the exact
+ * npm release @modelcontextprotocol/server@2.3.1 (not a floating git dependency).
+ * Registry provenance: https://registry.npmjs.org/@modelcontextprotocol/server/2.3.1
+ * tarball SHA-1 a15440d5c06f3bad67360952fe58e6965b4a4ac7; integrity
+ * sha512-e59MfWuSssj6DoQ96JCTqdW1AXT5/XtnTl0WWd6MU1Ka434fFUGGosCLJbGNySDhHGvxQWoRWK137FXYFkYNWw==
+ * Protocol revision: 2026-07-28. Legacy handshakes/sessions are deliberately refused.
+ */
+import { createMcpHandler, fromJsonSchema, McpServer } from '@modelcontextprotocol/server';
+import { toolErrorResult } from "./protocol.js";
+/**
+ * Construct official serving around a caller already verified by the transport.
+ * No credentials or grants are accepted from JSON-RPC params. Each factory call
+ * reads the LIVE surface and creates a fresh server; business execution and its
+ * accounting remain exclusively in host.callTool / createMcpHost.
+ */
+export function createSdkV2Handler(host, caller, incoming) {
+    return createMcpHandler(({ authInfo }) => {
+        if (authInfo?.clientId !== caller.clientId) {
+            throw new Error('SDK serving requires the transport-verified caller');
+        }
+        const server = new McpServer(host.serverInfo, {
+            supportedProtocolVersions: ['2026-07-28'],
+            // Keep tools/list available for an empty caller-specific catalog; SDK
+            // handlers otherwise appear only after the first registerTool call.
+            capabilities: { tools: { listChanged: false } },
+        });
+        for (const tool of [...host.listTools()].sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!caller.allowedTools.includes(tool.name) || tool.importedFromMcp)
+                continue;
+            server.registerTool(tool.name, {
+                ...tool.title === undefined ? {} : { title: tool.title },
+                description: tool.description,
+                inputSchema: fromJsonSchema(tool.inputSchema),
+                // A definition with no declared result shape must register no
+                // outputSchema: the SDK's output validator converts ANY registered
+                // outputSchema plus an undefined structuredContent into a tool error
+                // ("has an output schema but no structured content was provided"),
+                // while the protocol dispatch serves the same host outcome as a
+                // content-only success (server.ts). An empty schema is the
+                // schema-less sentinel.
+                ...tool.outputSchema === undefined || Object.keys(tool.outputSchema).length === 0
+                    ? {}
+                    : { outputSchema: fromJsonSchema(tool.outputSchema) },
+            }, async (args, ctx) => {
+                const outcome = await host.callTool(tool.name, args, ctx.mcpReq.signal, caller);
+                if (outcome.isError === true) {
+                    // An application failure is a tool-error RESULT (P26-04), clamped
+                    // exactly like the protocol dispatch clamps it: toolErrorResult
+                    // bounds the message to 2000 chars + '…' (protocol.ts:358-365).
+                    // The installed SDK's CallToolResult.content is mutable, so the
+                    // readonly payload content is copied, as the denied-call path does.
+                    const failure = toolErrorResult(outcome.text);
+                    return { isError: failure.isError, content: [...failure.content] };
+                }
+                // The pinned 2026-07-28 schema types structuredContent as `unknown` —
+                // ANY JSON value (object, array, string, number, boolean, null:
+                // docs/tool-mode/specs/mcp-2026-07-28/schema.ts CallToolResult). The
+                // installed SDK's CallToolResultSchema is z.ZodUnknown and its 2026-era
+                // projection is identity, so no runtime guard or cast is needed;
+                // undefined means "no structured value" and is omitted.
+                return {
+                    content: [{ type: 'text', text: outcome.text }],
+                    ...outcome.structured === undefined ? {} : { structuredContent: outcome.structured },
+                };
+            });
+        }
+        // Withheld known tools must remain invisible to tools/list, but SEC-03
+        // requires policy denials in the tool-error lane. Override only this fresh
+        // request's denied-call handler; accepted calls retain McpServer's genuine
+        // registration/input/output pipeline. The shared host boundary owns the
+        // refusal and its accounting; no unauthorized tool is ever registered.
+        if (incoming !== undefined) {
+            const deniedName = incoming.params?.name;
+            if (incoming.method === 'tools/call' && typeof deniedName === 'string'
+                && !caller.allowedTools.includes(deniedName)
+                && host.listTools().some(tool => tool.name === deniedName && !tool.importedFromMcp)) {
+                server.server.setRequestHandler('tools/call', async (request, ctx) => {
+                    if (request.params.name !== deniedName)
+                        throw new Error('request-specific denial name changed');
+                    const outcome = await host.callTool(deniedName, request.params.arguments ?? {}, ctx.mcpReq.signal, caller);
+                    if (outcome.isError !== true)
+                        throw new Error('host accepted a tool outside the authenticated grant');
+                    return { isError: true, content: [...toolErrorResult(outcome.text).content] };
+                });
+            }
+        }
+        return server;
+    }, {
+        legacy: 'reject',
+        // NEVER 'json': that mode silently drops mid-call notifications. Auto keeps
+        // every message, upgrading the response to SSE if one is emitted.
+        responseMode: 'auto',
+    });
+}
+/**
+ * Live Fetch face. The per-request SDK handler belongs to the response body:
+ * close it on drain, cancellation, abort or error, never when fetch returns SSE.
+ * Linking a controller also makes a Web reader's cancel abort business execution.
+ */
+export async function serveSdkV2Request(host, caller, request, token) {
+    const incoming = await request.clone().json();
+    const handler = createSdkV2Handler(host, caller, incoming);
+    const abort = new AbortController();
+    let reader;
+    let stopped = false;
+    let closing;
+    const close = () => {
+        if (closing === undefined) {
+            stopped = true;
+            request.signal.removeEventListener('abort', onAbort);
+            closing = handler.close();
+        }
+        return closing;
+    };
+    const cancel = async (reason) => {
+        abort.abort(reason);
+        try {
+            await reader?.cancel(reason);
+        }
+        finally {
+            await close();
+        }
+    };
+    const onAbort = () => { void cancel(request.signal.reason).catch(() => { }); };
+    request.signal.addEventListener('abort', onAbort, { once: true });
+    if (request.signal.aborted)
+        onAbort();
+    try {
+        const response = await handler.fetch(new Request(request, { signal: abort.signal }), {
+            authInfo: { token, clientId: caller.clientId, scopes: [] },
+        });
+        if (response.body === null) {
+            await close();
+            return response;
+        }
+        reader = response.body.getReader();
+        if (abort.signal.aborted) {
+            await cancel(abort.signal.reason);
+            throw abort.signal.reason ?? new Error('request aborted');
+        }
+        const body = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const next = await reader.read();
+                    if (stopped) {
+                        controller.close();
+                        return;
+                    }
+                    if (next.done) {
+                        await close();
+                        reader.releaseLock();
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(next.value);
+                    }
+                }
+                catch (error) {
+                    await close();
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) { await cancel(reason); },
+        }, { highWaterMark: 0 });
+        return new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}
+//# sourceMappingURL=sdk-v2.js.map

package/lib/mcp/server.d.ts

@@ -15,6 +15,7 @@
  */
 import { type HeaderInput, type WireRequest } from './protocol.ts';
 import type { SubscriptionRegistry } from './subscriptions.ts';
+import type { ExternalCaller } from './client-grant.ts';
 /** One tool as the MCP surface describes it. */
 export interface McpToolDefinition {
     /** The caller-facing name. */
@@ -56,9 +57,11 @@ export interface McpHost {
      * @param name - the tool name.
      * @param args - the tool arguments.
      * @param signal - the caller's abort signal.
+     * @param caller - the AUTHENTICATED external caller and its derived grant (SEC-04),
+     *   resolved by the transport; absent for non-HTTP transports that carry no client.
      * @returns the outcome.
      */
-    callTool(name: string, args: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<ToolInvocationOutcome>;
+    callTool(name: string, args: Readonly<Record<string, unknown>>, signal: AbortSignal, caller?: ExternalCaller): Promise<ToolInvocationOutcome>;
 }
 /** One dispatched response. */
 export interface DispatchResult {
@@ -111,5 +114,12 @@ export declare function dispatch(request: WireRequest, host: McpHost, options?:
     readonly subscriptions?: SubscriptionRegistry;
     /** The authenticated client, which a subscription is bound to. */
     readonly clientId?: string;
+    /**
+     * The authenticated external caller and its derived grant (SEC-04).
+     *
+     * Resolved by the TRANSPORT after authentication, never read from the request body:
+     * a caller cannot supply or forge its own identity or grant (BASE-05).
+     */
+    readonly caller?: ExternalCaller;
 }): Promise<DispatchResult>;
 //# sourceMappingURL=server.d.ts.map

package/lib/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAaL,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9D,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACvD,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACxD,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAClC;AAED,wCAAwC;AACxC,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACxE;;;OAGG;IACH,SAAS,IAAI,SAAS,iBAAiB,EAAE,CAAA;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;CACrH;AAED,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;CACvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CACtB,GACL,OAAO,CAAC,cAAc,CAAC,CAsFzB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAaL,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACvD,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACxD,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAClC;AAED,wCAAwC;AACxC,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACxE;;;OAGG;IACH,SAAS,IAAI,SAAS,iBAAiB,EAAE,CAAA;IACzC;;;;;;;;OAQG;IACH,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,qBAAqB,CAAC,CAAA;CAClC;AAED,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;CACvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAA;CAC5B,GACL,OAAO,CAAC,cAAc,CAAC,CA2IzB"}