@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/lib/mcp/protocol.js

@@ -0,0 +1,459 @@
+/**
+ * The MCP 2026-07-28 wire core.
+ *
+ * The published `@modelcontextprotocol/sdk` (1.32.1) declares
+ * `LATEST_PROTOCOL_VERSION = 2025-11-25` and does not list `2026-07-28` among its
+ * supported revisions, so this is the "separately reviewed, schema-conformant
+ * adaptation" MCP-01 permits where SDK support is incomplete. It is written
+ * against the revision's own requirements rather than by changing a version string
+ * on legacy behaviour, which MCP-01 explicitly says does not satisfy the
+ * requirement.
+ *
+ * What makes this revision different, and what this module exists to enforce:
+ *
+ * - **No handshake.** `tools/list` and `tools/call` must work as the FIRST
+ *   application request. There is no `initialize`, no
+ *   `notifications/initialized`, no prior discovery call and no `Mcp-Session-Id`
+ *   (P26-01). So there is no session state here to get wrong.
+ * - **Per-request metadata.** Version and capabilities travel in `params._meta` on
+ *   EVERY request, and are never inferred from an earlier one (P26-02). That is
+ *   why `_meta` is parsed per request and not cached.
+ * - **Server identity in results.** Every result envelope carries `resultType`,
+ *   and the revision's guidance puts `serverInfo` in result metadata.
+ * - **Errors stay in their lanes** (P26-04): a malformed protocol request is a
+ *   JSON-RPC error, while an application tool failure is a tool-error RESULT. A
+ *   failure wrapped as a successful payload is the specific mistake this prevents.
+ *
+ * @module @try-works/dsh-tool-mode/mcp/protocol
+ */
+/** The revision this server speaks. */
+export const PROTOCOL_VERSION = '2026-07-28';
+/**
+ * Revisions this server can also serve.
+ *
+ * Kept explicit and short. P26-03 requires an unsupported version to be answered
+ * with the supported list, so the list must be a fact rather than a guess.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = [PROTOCOL_VERSION];
+/** The `_meta` keys the revision defines. */
+export const META_KEYS = {
+    protocolVersion: 'io.modelcontextprotocol/protocolVersion',
+    clientInfo: 'io.modelcontextprotocol/clientInfo',
+    clientCapabilities: 'io.modelcontextprotocol/clientCapabilities',
+    serverInfo: 'io.modelcontextprotocol/serverInfo',
+};
+/**
+ * Error codes.
+ *
+ * The reserved range belongs to the protocol. P26-03 is explicit that custom
+ * 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. */
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+    /** MCP-reserved. */
+    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 {
+    name = 'WireError';
+    code;
+    /** Structured detail, as the revision's schema defines for the code. */
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        if (data !== undefined)
+            this.data = data;
+    }
+}
+/** Whether a numeric code lies in the range reserved for the protocol. */
+export function isReservedErrorCode(code) {
+    // JSON-RPC's own band plus MCP's -32000..-32099 allocation.
+    return (code >= -32768 && code <= -32000);
+}
+/**
+ * Parse `params._meta` from a request (P26-02).
+ *
+ * Missing required metadata is `invalid params`, not a defaulted value: inferring
+ * a version or a capability from a preceding request is exactly what P26-02
+ * forbids, and defaulting is inference with extra steps.
+ *
+ * The REQUIRED set is taken from the pinned revision schema's `RequestMetaObject`,
+ * which requires `clientCapabilities` and `protocolVersion` — and NOT `clientInfo`.
+ * Requiring `clientInfo` here would reject a request the schema admits, which is a
+ * conformance failure in the opposite direction from accepting too much.
+ *
+ * @param params - the request parameters.
+ * @returns the parsed metadata.
+ * @throws WireError `-32602` when a required key is absent or malformed.
+ */
+export function parseRequestMetadata(params) {
+    const meta = params?._meta;
+    if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) {
+        throw new WireError(ERROR_CODES.invalidParams, 'params._meta is required on every modern request and must be an object');
+    }
+    const record = meta;
+    const protocolVersion = record[META_KEYS.protocolVersion];
+    if (typeof protocolVersion !== 'string' || protocolVersion.length === 0) {
+        throw new WireError(ERROR_CODES.invalidParams, `params._meta["${META_KEYS.protocolVersion}"] is required and must be a string`);
+    }
+    const capabilities = record[META_KEYS.clientCapabilities];
+    if (typeof capabilities !== 'object' || capabilities === null || Array.isArray(capabilities)) {
+        throw new WireError(ERROR_CODES.invalidParams, `params._meta["${META_KEYS.clientCapabilities}"] is required and must be an object`);
+    }
+    // Optional in the schema, so absent is admitted; present-but-malformed is not,
+    // because a client that sends half an Implementation has sent a broken one.
+    const clientInfo = record[META_KEYS.clientInfo];
+    let info = { name: 'unknown', version: 'unknown' };
+    if (clientInfo !== undefined) {
+        if (typeof clientInfo !== 'object' || clientInfo === null) {
+            throw new WireError(ERROR_CODES.invalidParams, `params._meta["${META_KEYS.clientInfo}"], when present, must be an object`);
+        }
+        const candidate = clientInfo;
+        if (typeof candidate.name !== 'string' || typeof candidate.version !== 'string') {
+            throw new WireError(ERROR_CODES.invalidParams, 'clientInfo needs a name and a version');
+        }
+        info = { name: candidate.name, version: candidate.version };
+    }
+    return {
+        protocolVersion,
+        // Self-reported and therefore for DIAGNOSTICS only: P26-02 is explicit that
+        // clientInfo is not authentication, so nothing here is ever used to authorize.
+        clientInfo: info,
+        clientCapabilities: capabilities,
+    };
+}
+/**
+ * Negotiate the protocol version for one request (P26-03).
+ *
+ * @param metadata - the request metadata.
+ * @returns the negotiated version.
+ * @throws WireError `-32022` carrying the official `supported` and `requested` data.
+ */
+export function negotiateVersion(metadata) {
+    if (!SUPPORTED_PROTOCOL_VERSIONS.includes(metadata.protocolVersion)) {
+        throw new WireError(ERROR_CODES.unsupportedProtocolVersion, `unsupported protocol version ${metadata.protocolVersion}`, 
+        // The revision defines this data shape; a bare message would leave the client
+        // unable to choose a version it can speak.
+        { supported: [...SUPPORTED_PROTOCOL_VERSIONS], requested: metadata.protocolVersion });
+    }
+    return metadata.protocolVersion;
+}
+/**
+ * The advertised-feature matrix (P26-12).
+ *
+ * P26-12 forbids advertising Tasks, sampling, resource subscriptions, prompts or
+ * UI extensions merely because an SDK exports their types. Declaring the matrix as
+ * data — with `implemented: false` where that is the truth — means the server
+ * cannot advertise a feature it does not have by accident.
+ */
+export const ADVERTISED_FEATURES = [
+    { feature: 'tools', implemented: true },
+    { feature: 'server/discover', implemented: true },
+    /**
+     * 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 },
+    { feature: 'elicitation', implemented: false },
+    { feature: 'roots', implemented: false },
+    { feature: 'prompts', implemented: false },
+    { 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 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(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).
+ *
+ * @param required - capability names the client declared as required.
+ * @returns the unsupported names, empty when all are supported.
+ */
+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));
+}
+/**
+ * Validate and normalize an operator-configured catalog cache policy (P26-14).
+ *
+ * The default is the unchanged safe behavior: `{ cacheScope: 'private', ttlMs: 0 }`.
+ * Invalid configuration is REFUSED with a named error rather than silently rewritten:
+ * emitting a non-private scope would understate the authorization boundary, and a
+ * negative/non-finite TTL is not a cache policy at all.
+ * @param policy - the configured TTL/scope, both optional.
+ * @returns the validated policy.
+ * @throws Error named `INVALID_CATALOG_CACHE_TTL` or `INVALID_CATALOG_CACHE_SCOPE`.
+ */
+export function normalizeCachePolicy(policy) {
+    const ttlMs = policy?.ttlMs ?? 0;
+    if (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs) || ttlMs < 0) {
+        throw new Error('INVALID_CATALOG_CACHE_TTL: catalog cache ttlMs must be a finite, non-negative '
+            + `number of milliseconds; received ${String(ttlMs)}`);
+    }
+    const cacheScope = policy?.cacheScope ?? 'private';
+    if (cacheScope !== 'private') {
+        throw new Error('INVALID_CATALOG_CACHE_SCOPE: catalog cacheScope must be "private" because '
+            + 'tools/list and server/discover are authorization-filtered; received '
+            + `${JSON.stringify(cacheScope)}`);
+    }
+    return { cacheScope: 'private', ttlMs };
+}
+/**
+ * The caching fields every cacheable result must carry (P26-14).
+ *
+ * Taken from the pinned schema's `CacheableResult`, which REQUIRES `cacheScope` and
+ * `ttlMs` on `DiscoverResult` and `ListToolsResult` alike. The policy defaults to
+ * private/0 and can carry an operator-configured non-zero TTL; the scope itself is
+ * validated to stay `private` ({@link normalizeCachePolicy}).
+ * @param policy - the catalog cache policy, or undefined for private/0.
+ * @returns the caching fields.
+ */
+export function cacheableResultFields(policy) {
+    return normalizeCachePolicy(policy);
+}
+/**
+ * Build a successful result envelope (P26-04).
+ *
+ * Every modern result carries `resultType`, and `serverInfo` rides in result
+ * metadata per the revision's guidance — `ResultMetaObject` admits exactly that
+ * one key, which is what this writes.
+ * @param result - the method-specific fields.
+ * @param serverInfo - this server's identity.
+ * @returns the result object, including `resultType` and `_meta`.
+ */
+export function successResult(result, serverInfo) {
+    // The metadata is MERGED rather than replaced. A method-specific result may carry
+    // its own `_meta` members that the revision requires —
+    // `SubscriptionsListenResult` must contain
+    // `io.modelcontextprotocol/subscriptionId` — and overwriting the object dropped
+    // it, sending a result with a required field missing. A subscription test caught
+    // this; the pinned schema would have caught it too, and did not only because the
+    // fixture corpus has no subscription case yet.
+    const existing = typeof result._meta === 'object' && result._meta !== null
+        ? result._meta
+        : {};
+    return {
+        ...result,
+        resultType: 'complete',
+        _meta: {
+            ...existing,
+            [META_KEYS.serverInfo]: { name: serverInfo.name, version: serverInfo.version },
+        },
+    };
+}
+/**
+ * Build a tool-error RESULT (P26-04).
+ *
+ * The distinction this preserves is the whole point: an application failure is a
+ * successful protocol exchange carrying `isError`, while a malformed request is a
+ * JSON-RPC error. Wrapping a domain failure as protocol success, or an
+ * infrastructure failure as a successful domain payload, are both forbidden.
+ * @param message - a bounded, model-readable explanation.
+ * @returns the tool-error result.
+ */
+export function toolErrorResult(message) {
+    return {
+        // Truncated because a stack trace or an unbounded message would be neither
+        // model-readable nor safe to return.
+        isError: true,
+        content: [{ type: 'text', text: message.length > 2000 ? `${message.slice(0, 2000)}…` : message }],
+    };
+}
+/**
+ * Build a JSON-RPC error response.
+ *
+ * When the request id is UNKNOWN the `id` member is omitted rather than set to
+ * `null`. JSON-RPC 2.0 conventionally allows `id: null` for an undeterminable id,
+ * but the pinned revision schema types `RequestId` as `string | integer` and does
+ * not admit null — while `id` itself is optional. Omitting it is therefore the
+ * conformant way to say "unknown", and the independent probe caught this by
+ * rejecting a captured 401 whose id was null.
+ *
+ * @param id - the request id, or null when it could not be determined.
+ * @param error - the failure.
+ * @returns the response envelope.
+ */
+export function errorResponse(id, error) {
+    const data = 'data' in error ? error.data : undefined;
+    return {
+        jsonrpc: '2.0',
+        ...id === null ? {} : { id },
+        error: {
+            code: error.code,
+            message: error.message,
+            ...data === undefined ? {} : { data },
+        },
+    };
+}
+/**
+ * Decode the revision's Base64 sentinel encoding (P26-05).
+ *
+ * A header value may be encoded with the official `=?base64?…?=` sentinel, and it
+ * must be decoded BEFORE comparison. Comparing the encoded form would let a client
+ * present a value that decodes to something else entirely.
+ * @param value - the raw header value.
+ * @returns the decoded value.
+ */
+export function decodeHeaderValue(value) {
+    const match = /^=\?base64\?(.*)\?=$/s.exec(value);
+    if (match === null)
+        return value;
+    try {
+        return Buffer.from(match[1], 'base64').toString('utf8');
+    }
+    catch {
+        // A malformed sentinel is left as-is so the comparison against the body fails
+        // and reports a mismatch, rather than being silently accepted as something.
+        return value;
+    }
+}
+/**
+ * Check the required headers against the body (P26-05).
+ *
+ * Headers are checked against BODY FIELDS, so a request cannot claim one method in
+ * a header and another in its body. Every mismatch is `HeaderMismatch` (-32020),
+ * which the HTTP layer reports as 400.
+ * @param headers - the relevant request headers.
+ * @param body - the parsed request.
+ * @returns nothing when the headers agree.
+ * @throws WireError `-32020` naming the first disagreement.
+ */
+export function assertHeadersMatch(headers, body) {
+    const fail = (detail) => {
+        throw new WireError(ERROR_CODES.headerMismatch, detail);
+    };
+    const version = headers.protocolVersion === undefined ? undefined : decodeHeaderValue(headers.protocolVersion);
+    if (version === undefined) {
+        return fail('the MCP-Protocol-Version header is required');
+    }
+    const bodyVersion = body.params?._meta?.[META_KEYS.protocolVersion];
+    if (typeof bodyVersion === 'string' && version !== bodyVersion) {
+        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})`);
+    }
+    // `Mcp-Name` is required only for a named call. Requiring it universally would
+    // reject a correct `tools/list`, which has no name.
+    if (body.method === 'tools/call') {
+        const name = headers.name === undefined ? undefined : decodeHeaderValue(headers.name);
+        if (name === undefined)
+            return fail('the Mcp-Name header is required for tools/call');
+        const bodyName = body.params?.name;
+        if (typeof bodyName === 'string' && name !== bodyName) {
+            return fail(`the Mcp-Name header (${name}) does not match the request name (${bodyName})`);
+        }
+    }
+}
+/**
+ * Parse a newline-delimited stdio frame (P26-08).
+ *
+ * Stdio carries protocol traffic on stdout and diagnostics on stderr, so a line
+ * that is not a JSON object is a protocol error rather than something to log and
+ * skip: silently dropping it would leave a client waiting for a response that
+ * never comes.
+ * @param line - one line of input.
+ * @returns the parsed request, or undefined for a blank line.
+ * @throws WireError `-32700` when the line is not a JSON object.
+ */
+export function parseStdioLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        throw new WireError(ERROR_CODES.parseError, 'the frame is not valid JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new WireError(ERROR_CODES.invalidRequest, 'the frame is not a JSON-RPC object');
+    }
+    const request = parsed;
+    if (request.jsonrpc !== '2.0' || typeof request.method !== 'string') {
+        throw new WireError(ERROR_CODES.invalidRequest, 'the frame is not a JSON-RPC 2.0 request');
+    }
+    return request;
+}
+/**
+ * Serialize one stdio frame.
+ * @param message - the response or notification.
+ * @returns the line, newline-terminated.
+ */
+export function serializeStdioFrame(message) {
+    // A newline inside the JSON would produce two frames and desynchronise the
+    // stream, so the compact form is used and embedded newlines are escaped by
+    // JSON.stringify itself.
+    return `${JSON.stringify(message)}\n`;
+}
+//# sourceMappingURL=protocol.js.map

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-tool-mode/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-tool-mode/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,yDAgG/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"}