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

package/lib/mcp/http.js

@@ -17,15 +17,21 @@
  * @module @try-works/dsh-model-as-tool/mcp/http
  */
 import { timingSafeEqual } from 'node:crypto';
-import { assertHeadersMatch, ERROR_CODES, errorResponse, } from "./protocol.js";
-import { dispatch } from "./server.js";
-/** A conservative default: loopback, the illustrative port, a small body cap. */
+import { toWebRequest } from '@modelcontextprotocol/node';
+import { assertHeadersMatch, decodeHeaderValue, ERROR_CODES, errorResponse, negotiateVersion, parseRequestMetadata, unsupportedRequiredCapabilities, WireError, } from "./protocol.js";
+import { serveSdkV2Request } from "./sdk-v2.js";
+import { oauthChallenge, oauthErrorStatus } from "./oauth.js";
+import { createRateLimiter, DEFAULT_RATE_LIMIT_POLICY, } from "./rate-limit.js";
+import { resolveClientGrant } from "./client-grant.js";
+/** A conservative default: loopback, the illustrative port, a small body cap,
+ * and the default per-client rate limit (AT-12). */
 export const DEFAULT_HTTP_CONFIG = {
     path: '/mcp',
     host: '127.0.0.1',
     port: 3765,
     maxBodyBytes: 4 * 1024 * 1024,
     allowedOrigins: [],
+    rateLimit: DEFAULT_RATE_LIMIT_POLICY,
 };
 /** Whether an address is loopback. */
 export function isLoopback(address) {
@@ -60,33 +66,75 @@ function tokenMatches(presented, accepted) {
         return false;
     return timingSafeEqual(left, right);
 }
-/**
- * Build the request handler.
- *
- * Ordering is deliberate and matches P26-16's list: transport identity (loopback,
- * size, method, path) is settled before authentication, and authentication before
- * any protocol parsing. A request that is not from the loopback is refused without
- * its token being examined at all.
- * @param config - the transport configuration.
- * @param host - the MCP surface.
- * @returns the handler.
- */
-export function createHttpHandler(config, host) {
+/** Validate the Host header when the client supplies one. */
+function hostHeaderAllowed(header, config) {
+    if (header === undefined || header.length === 0)
+        return true;
+    const value = header.toLowerCase();
+    const authority = value.startsWith('[')
+        ? value.slice(1, value.indexOf(']'))
+        : (value.split(':')[0] ?? '');
+    const configured = config.host.toLowerCase();
+    const allowed = new Set([configured]);
+    if (isLoopback(configured)) {
+        allowed.add('localhost');
+        allowed.add('127.0.0.1');
+        allowed.add('::1');
+    }
+    return allowed.has(authority);
+}
+function createRequestGate(config, host) {
+    /**
+     * THE LIMITER IS PER-HANDLER STATE, in memory and unpersisted (AT-12).
+     *
+     * One limiter per bound endpoint, keyed by the authenticated client identity.
+     * Absent configuration means the DEFAULT policy applies, so the endpoint is
+     * bounded even when the operator configured nothing; `false` disables it; a
+     * policy overrides it. Construction validates the policy, so a broken
+     * configuration fails when the transport starts rather than mid-request.
+     */
+    const effectivePolicy = config.rateLimit === false
+        ? DEFAULT_RATE_LIMIT_POLICY
+        : (config.rateLimit ?? DEFAULT_RATE_LIMIT_POLICY);
+    const limiter = config.rateLimit === false
+        ? undefined
+        : createRateLimiter(effectivePolicy);
     return async (request) => {
+        // 0. DISCOVERY METADATA (RFC 8414/9728), when the OAuth scheme serves it.
+        // Metadata endpoints are the ONE thing served unauthenticated: a client must
+        // learn the issuer, audience and token endpoint BEFORE it can hold a token.
+        if (config.auth.scheme === 'oauth-resource-server') {
+            if (request.method === 'GET' && request.path === '/.well-known/oauth-protected-resource') {
+                return respond(200, config.auth.server.protectedResourceMetadata());
+            }
+            if (request.method === 'GET' && request.path === '/.well-known/oauth-authorization-server') {
+                return respond(200, config.auth.server.authorizationServerMetadata());
+            }
+        }
         // 1. Loopback only (MCP-02, SEC-02). Checked against the SOCKET address, not a
         // header: a header is caller-supplied, and trusting one would make the binding
         // decorative.
         if (!isLoopback(request.remoteAddress)) {
             return respond(403, { error: 'this endpoint serves loopback clients only' });
         }
+        if (!hostHeaderAllowed(request.headers.host, config)) {
+            return respond(403, { error: 'the Host header is not approved for this endpoint' });
+        }
         // 2. Size limit (SEC-02), measured on the received bytes.
         const bodyBytes = Buffer.byteLength(request.body, 'utf8');
         if (bodyBytes > config.maxBodyBytes) {
             // 413 rather than 400: the request may be perfectly well formed and merely
             // too large, and a client needs to tell those apart.
+            /**
+             * NO `id` — the pinned schema neither permits nor requires one here.
+             *
+             * This wrote `id: null`, which `RequestId` (`type: ["string","integer"]`) REJECTS:
+             * `null` is not a string and not an integer. `JSONRPCErrorResponse` requires only
+             * `["error","jsonrpc"]`, so the id is optional — and when the body was too large to
+             * read there is no id to echo anyway. Omitting it is both valid and honest.
+             */
             return respond(413, {
                 jsonrpc: '2.0',
-                id: null,
                 error: { code: ERROR_CODES.invalidRequest, message: `the request body exceeds ${config.maxBodyBytes} bytes` },
             });
         }
@@ -115,15 +163,82 @@ export function createHttpHandler(config, host) {
                 message: 'authentication is required',
             }), { 'www-authenticate': 'Bearer' });
         }
-        if (!tokenMatches(presented, config.auth.token)) {
-            // The message does not distinguish "unknown" from "expired": with a static
-            // token there is nothing to expire, and a more specific message would only
-            // help an attacker.
-            return respond(401, errorResponse(null, {
-                code: ERROR_CODES.invalidRequest,
-                message: 'the presented credential is not accepted',
-            }), { 'www-authenticate': 'Bearer' });
+        /** The AUTHENTICATED client identity, resolved once and used for rate limiting. */
+        let clientId;
+        if (config.auth.scheme === 'static-token') {
+            let matched;
+            if (tokenMatches(presented, config.auth.token))
+                matched = config.auth.clientId;
+            // SEC-01: a GENERATED static-token credential authenticates through the
+            // durable store, carrying its OWN client identity into grants and receipts.
+            if (matched === undefined && config.auth.registry !== undefined) {
+                matched = config.auth.registry.bySecret(presented)?.clientId;
+            }
+            if (matched === undefined) {
+                // The message does not distinguish "unknown" from "expired": with a static
+                // token there is nothing to expire, and a more specific message would only
+                // help an attacker.
+                return respond(401, errorResponse(null, {
+                    code: ERROR_CODES.invalidRequest,
+                    message: 'the presented credential is not accepted',
+                }), { 'www-authenticate': 'Bearer' });
+            }
+            clientId = matched;
+        }
+        else {
+            const verdict = await config.auth.server.verify(presented, config.auth.requiredScope);
+            if (!verdict.ok) {
+                // An RFC 6750 challenge names WHY: invalid_token vs insufficient_scope are
+                // different client instructions, and flattening them would misdirect a
+                // client that could otherwise self-correct. The STATUS follows §3.1 the
+                // same way: invalid_request 400, invalid_token 401, insufficient_scope
+                // 403 (the F4 gap was one flat 401 for all three).
+                return respond(oauthErrorStatus(verdict.error), errorResponse(null, {
+                    code: ERROR_CODES.invalidRequest,
+                    message: verdict.error.description,
+                }), { 'www-authenticate': oauthChallenge(verdict.error) });
+            }
+            clientId = verdict.token.clientId;
+        }
+        /**
+         * 5.5. Per-client rate limiting (AT-12), AFTER authentication and BEFORE the
+         * body is examined.
+         *
+         * A refused request is answered here without parsing, so a rate-limited caller
+         * cannot make the transport pay body-processing cost per attempt, and the
+         * counter is keyed on the identity the transport just proved — never the
+         * remote address, which every loopback client shares. Unauthenticated and
+         * malformed-credential requests were already refused at step 5 WITHOUT moving
+         * a counter: counting them would turn the limiter into an authentication
+         * oracle, where a 429 after N attempts tells a caller whether a credential
+         * exists.
+         *
+         * The `id` is OMITTED, exactly as the oversize-body refusal omits it: the body
+         * was never examined, so there is no id to echo, and the pinned `RequestId`
+         * does not admit `null`. The envelope is still a conformant
+         * `JSONRPCErrorResponse`, and `Retry-After` names when the window opens.
+         */
+        if (limiter !== undefined) {
+            const decision = limiter.admit(clientId);
+            if (!decision.admitted) {
+                return respond(429, errorResponse(null, {
+                    code: ERROR_CODES.rateLimited,
+                    message: `rate limit exceeded: at most ${effectivePolicy.maxRequests} `
+                        + `requests per client per ${Math.round(effectivePolicy.windowMs / 1000)}s window (AT-12)`,
+                    data: { retryAfterMs: decision.retryAfterMs },
+                }), { 'retry-after': String(Math.ceil(decision.retryAfterMs / 1000)) });
+            }
         }
+        /**
+         * 5.5. The per-client external grant (SEC-04), DERIVED here because the
+         * authentication verdict just happened: the grant is built from the verified
+         * client identity, the operator's grant configuration and the LIVE published
+         * surface — never from anything in the request body, which is what BASE-05
+         * forbids. The derived identity travels with the dispatch as CALLER identity,
+         * so the surface can authorize against the CLIENT's grant instead of the
+         * host's own interactive grant.
+         */
+        const caller = resolveClientGrant(clientId, config.grants, host.listTools().map(tool => tool.name));
         // 6. Parse, then check headers against the body (P26-05).
         let parsed;
         try {
@@ -136,6 +251,13 @@ export function createHttpHandler(config, host) {
             return respond(400, errorResponse(null, { code: ERROR_CODES.invalidRequest, message: 'the body is not a JSON-RPC object' }));
         }
         const wire = parsed;
+        if (wire.jsonrpc !== '2.0' || typeof wire.method !== 'string'
+            || (wire.id !== undefined && typeof wire.id !== 'string'
+                && !(typeof wire.id === 'number' && Number.isInteger(wire.id)))) {
+            return respond(400, errorResponse(null, {
+                code: ERROR_CODES.invalidRequest, message: 'the body is not a JSON-RPC 2.0 request or notification',
+            }));
+        }
         // Built conditionally rather than with explicit `undefined` values, because
         // `exactOptionalPropertyTypes` distinguishes "absent" from "present and
         // undefined" — and so does the header check, which treats a missing header
@@ -155,14 +277,102 @@ export function createHttpHandler(config, host) {
             // P26-05 names HTTP 400 and HeaderMismatch together.
             return respond(400, errorResponse(wire.id ?? null, { code: ERROR_CODES.headerMismatch, message }));
         }
-        // 7. Dispatch. A notification carries no id and is acknowledged with 202.
-        const outcome = await dispatch(wire, host, { signal: new AbortController().signal });
+        // Pinned metadata failures are transport rejections (HTTP 400), not SDK
+        // dispatch errors under HTTP 200. Keep the shared wire validation, not a
+        // second business dispatcher. Optional clientInfo remains optional.
+        if (wire.id !== undefined && wire.method !== 'initialize') {
+            try {
+                const metadata = parseRequestMetadata(wire.params);
+                negotiateVersion(metadata);
+                const declared = metadata.clientCapabilities.required;
+                const required = Array.isArray(declared)
+                    ? declared.filter((name) => typeof name === 'string') : [];
+                const unsupported = unsupportedRequiredCapabilities(required);
+                if (unsupported.length > 0) {
+                    throw new WireError(ERROR_CODES.unsupportedClientCapability, `the client requires unsupported capability: ${unsupported.join(', ')}`, { requiredCapabilities: Object.fromEntries(unsupported.map(name => [name, {}])) });
+                }
+            }
+            catch (error) {
+                if (!(error instanceof WireError))
+                    throw error;
+                return respond(400, errorResponse(wire.id, error));
+            }
+        }
+        // 7. The OFFICIAL v2 server handles the protocol, not our handwritten dispatch.
+        // This finite response-description interface cannot carry open subscriptions.
+        // Refuse before creating a subscription rather than swallowing notifications.
+        if (wire.id !== undefined && wire.method === 'subscriptions/listen') {
+            return respond(404, errorResponse(wire.id ?? null, {
+                code: ERROR_CODES.methodNotFound,
+                message: 'this HTTP transport does not offer open subscription streams',
+            }));
+        }
+        // Pinned Streamable HTTP defines NO client-to-server notifications;
+        // notifications/cancelled is stdio-only. 202/no body is mandatory only IF a
+        // notification is accepted. We implement no extension notification handlers,
+        // so explicitly refuse rather than silently dropping unsupported messages.
         if (wire.id === undefined) {
-            return { status: 202, headers: {}, body: '' };
+            return respond(400, errorResponse(null, {
+                code: ERROR_CODES.invalidRequest,
+                message: 'this stateless endpoint does not accept standalone notifications',
+            }));
+        }
+        const headers = new Headers();
+        for (const [name, value] of Object.entries(request.headers)) {
+            if (value !== undefined)
+                headers.set(name, value);
         }
-        // The dispatch `httpStatus` already distinguishes invalid params (400) from a
-        // protocol-level failure that still produced a well-formed response (200).
-        return respond(outcome.httpStatus, outcome.response);
+        // Normalize sentinel values only AFTER shared validation. The pinned
+        // transport requires Mcp-Method; do not synthesize a missing header here or
+        // bypass assertHeadersMatch's required-header/mismatch rejection.
+        if (headerInput.method !== undefined)
+            headers.set('mcp-method', decodeHeaderValue(headerInput.method));
+        if (headerInput.protocolVersion !== undefined) {
+            headers.set('mcp-protocol-version', decodeHeaderValue(headerInput.protocolVersion));
+        }
+        // The SDK already decodes Mcp-Name correctly (including non-ASCII and
+        // literal sentinels), so preserve its original wire encoding here.
+        return { caller, token: presented, headers };
+    };
+}
+/**
+ * Shared, guarded Fetch/stream core. The Node adapter's toNodeHandler is NOT
+ * used directly: its early 413 has a different wire envelope, it does not watch
+ * IncomingMessage.aborted, and its close/drain listeners are not removed.
+ * Use its official bounded Request conversion only AFTER our unchanged gate.
+ */
+export function createHttpStreamHandler(config, host) {
+    const gate = createRequestGate(config, host);
+    return async (request, signal) => {
+        const verdict = await gate(request);
+        if ('status' in verdict) {
+            return new Response(verdict.body, { status: verdict.status, headers: verdict.headers });
+        }
+        signal?.throwIfAborted();
+        const webRequest = await toWebRequest({
+            method: request.method,
+            url: config.path,
+            // Host was validated already; never let an untrusted authority affect URL
+            // construction. Keep the actual normalized headers on the Request below.
+            headers: { host: 'localhost' },
+            async *[Symbol.asyncIterator]() { yield Buffer.from(request.body, 'utf8'); },
+        }, undefined, {
+            maxRequestBodySize: config.maxBodyBytes,
+            ...signal === undefined ? {} : { signal },
+        });
+        return serveSdkV2Request(host, verdict.caller, new Request(webRequest, { headers: verdict.headers }), verdict.token);
+    };
+}
+/** Finite, materializing test facade; production sockets use the stream core. */
+export function createHttpHandler(config, host) {
+    const stream = createHttpStreamHandler(config, host);
+    return async (request) => {
+        const response = await stream(request);
+        return {
+            status: response.status,
+            headers: Object.fromEntries(response.headers.entries()),
+            body: await response.text(),
+        };
     };
 }
 /** Extract a bearer token from an Authorization header. */
@@ -175,13 +385,16 @@ function bearerOf(header) {
 /**
  * Whether this transport may claim OAuth conformance.
  *
- * It may not. `P26-15` permits a static-token mode while forbidding the claim, and
- * this returns false so a status report or a compatibility matrix cannot assert
- * otherwise by accident.
- * @returns always false, for the static-token scheme.
+ * The static-token scheme may not; the oauth-resource-server scheme may, because
+ * it verifies HS256 credentials, audience, expiry and scope against the embedded
+ * server and answers RFC 6750 challenges — a conformant subset, not an invention.
+ * The claim is per-DEPLOYMENT, which is what a status report needs: a host using
+ * static tokens must still report false.
+ * @param auth - the live auth configuration.
+ * @returns whether the live scheme may claim the OAuth 2.1 resource-server profile.
  */
-export function claimsOAuthConformance() {
-    return false;
+export function claimsOAuthConformance(auth) {
+    return auth.scheme === 'oauth-resource-server';
 }
 /**
  * The authentication profile this transport reports.
@@ -189,17 +402,79 @@ export function claimsOAuthConformance() {
  * A machine-readable statement of what is actually implemented, so a client or an
  * operator can tell custom authentication from the OAuth profile without reading
  * the source.
+ * @param auth - the live auth configuration.
  * @returns the auth profile description.
  */
-export function authProfile() {
+export function authProfile(auth) {
+    if (auth.scheme === 'static-token') {
+        return {
+            scheme: 'static-token',
+            // Stated explicitly rather than left to inference.
+            oauth21ResourceServer: false,
+            perClientRevocable: true,
+            note: 'Custom authentication. The OAuth 2.1 resource-server profile is not used and is not claimed.',
+        };
+    }
     return {
-        scheme: 'static-token',
-        // Stated explicitly rather than left to inference.
-        oauth21ResourceServer: false,
+        scheme: 'oauth-resource-server',
+        oauth21ResourceServer: true,
         perClientRevocable: true,
-        note: 'Custom authentication. The OAuth 2.1 resource-server profile is not implemented and is not claimed.',
+        issuer: auth.server.authorizationServerMetadata().issuer,
+        audience: auth.server.protectedResourceMetadata().resource,
+        note: 'OAuth 2.1 resource-server profile via the embedded local authorization server: '
+            + 'HS256 credentials, RFC 6750 challenges, audience/expiry/scope validation, per-client revocation.',
     };
 }
+/** Wait for capacity without stranding a promise on a disconnected socket. */
+function waitForDrain(outgoing, signal) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            outgoing.off('drain', onDrain);
+            outgoing.off('error', onError);
+            outgoing.off('close', onAbort);
+            signal.removeEventListener('abort', onAbort);
+        };
+        const onDrain = () => { cleanup(); resolve(); };
+        const onError = (error) => { cleanup(); reject(error); };
+        const onAbort = () => { cleanup(); reject(signal.reason ?? new Error('HTTP response closed')); };
+        outgoing.once('drain', onDrain);
+        outgoing.once('error', onError);
+        outgoing.once('close', onAbort);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted || outgoing.destroyed)
+            onAbort();
+    });
+}
+/** Pump bytes, never text-materialize SSE, and cancel even a blocked read. */
+async function writeStreamResponse(response, outgoing, signal) {
+    const reader = response.body?.getReader();
+    const onAbort = () => { void reader?.cancel(signal.reason).catch(() => { }); };
+    signal.addEventListener('abort', onAbort, { once: true });
+    let drained = false;
+    try {
+        signal.throwIfAborted();
+        outgoing.writeHead(response.status, Object.fromEntries(response.headers.entries()));
+        outgoing.flushHeaders();
+        if (reader !== undefined) {
+            while (true) {
+                const next = await reader.read();
+                signal.throwIfAborted();
+                if (next.done)
+                    break;
+                if (!outgoing.write(next.value))
+                    await waitForDrain(outgoing, signal);
+            }
+        }
+        drained = true;
+        outgoing.end();
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+        if (!drained)
+            await reader?.cancel(signal.reason).catch(() => { });
+        reader?.releaseLock();
+    }
+}
 /**
  * Bind the endpoint on loopback.
  *
@@ -220,38 +495,87 @@ export async function startHttpServer(config, host) {
             + 'A routable bind address would expose inference to the network.');
     }
     const { createServer } = await import('node:http');
-    const handler = createHttpHandler(config, host);
+    const handler = createHttpStreamHandler(config, host);
+    const active = new Set();
     const server = createServer((incoming, outgoing) => {
+        const abort = new AbortController();
+        active.add(abort);
+        const onAborted = () => { abort.abort(new Error('HTTP client disconnected')); };
+        const onClose = () => { if (!outgoing.writableFinished)
+            onAborted(); };
+        const cleanup = () => {
+            incoming.off('aborted', onAborted);
+            incoming.off('error', onAborted);
+            outgoing.off('close', onClose);
+            outgoing.off('error', onAborted);
+            active.delete(abort);
+        };
+        incoming.once('aborted', onAborted);
+        incoming.once('error', onAborted);
+        outgoing.once('close', onClose);
+        outgoing.once('error', onAborted);
         const chunks = [];
         let received = 0;
+        let refused = false;
         incoming.on('data', (chunk) => {
+            if (refused || abort.signal.aborted)
+                return;
             received += chunk.byteLength;
-            // The limit is enforced DURING the read, not after it: buffering an
-            // unbounded body in order to measure it defeats the limit.
+            // Bound DURING receipt, and free already buffered chunks on refusal.
             if (received > config.maxBodyBytes) {
-                outgoing.writeHead(413, { 'content-type': 'application/json' });
-                outgoing.end(JSON.stringify({ error: 'request body too large' }));
-                incoming.destroy();
+                refused = true;
+                chunks.length = 0;
+                outgoing.writeHead(413, { 'content-type': 'application/json', connection: 'close' });
+                outgoing.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: ERROR_CODES.invalidRequest,
+                        message: `the request body exceeds ${config.maxBodyBytes} bytes`,
+                    },
+                }));
+                cleanup();
                 return;
             }
             chunks.push(chunk);
         });
-        incoming.on('end', () => {
-            void handler({
-                method: incoming.method ?? 'POST',
-                path: (incoming.url ?? '/').split('?')[0],
-                headers: incoming.headers,
-                body: Buffer.concat(chunks).toString('utf8'),
-                remoteAddress: incoming.socket.remoteAddress ?? '',
-            }).then(response => {
-                outgoing.writeHead(response.status, response.headers);
-                outgoing.end(response.body);
-            }).catch((error) => {
-                // A handler that throws must not hang the connection.
-                outgoing.writeHead(500, { 'content-type': 'application/json' });
-                outgoing.end(JSON.stringify({ error: error instanceof Error ? error.message : 'internal error' }));
-            });
+        incoming.once('end', () => {
+            if (refused || abort.signal.aborted) {
+                cleanup();
+                return;
+            }
+            const body = Buffer.concat(chunks).toString('utf8');
+            chunks.length = 0;
+            void (async () => {
+                try {
+                    const response = await handler({
+                        method: incoming.method ?? 'POST',
+                        path: (incoming.url ?? '/').split('?')[0],
+                        headers: incoming.headers,
+                        body,
+                        remoteAddress: incoming.socket.remoteAddress ?? '',
+                    }, abort.signal);
+                    await writeStreamResponse(response, outgoing, abort.signal);
+                }
+                catch (error) {
+                    if (abort.signal.aborted || outgoing.destroyed)
+                        return;
+                    if (outgoing.headersSent) {
+                        // A partial SSE response cannot be replaced by a JSON error.
+                        outgoing.destroy(error instanceof Error ? error : new Error(String(error)));
+                    }
+                    else {
+                        outgoing.writeHead(500, { 'content-type': 'application/json' });
+                        outgoing.end(JSON.stringify({ error: error instanceof Error ? error.message : 'internal error' }));
+                    }
+                }
+                finally {
+                    cleanup();
+                }
+            })();
         });
+        // No 'end' event is guaranteed on a truncated upload.
+        incoming.once('close', () => { if (!incoming.complete)
+            cleanup(); });
     });
     await new Promise((resolve, reject) => {
         server.once('error', reject);
@@ -265,8 +589,12 @@ export async function startHttpServer(config, host) {
         port,
         url: `http://${config.host}:${port}${config.path}`,
         async close() {
+            for (const abort of active)
+                abort.abort(new Error('HTTP endpoint closed'));
             await new Promise((resolve, reject) => {
                 server.close(error => error === undefined ? resolve() : reject(error));
+                // server.close alone waits indefinitely for active/keep-alive sockets.
+                server.closeAllConnections();
             });
         },
     };