@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.40

package/dist/core/mcp/http-server.js

@@ -0,0 +1,553 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { EventEmitter } from 'node:events';
+import { MCP_ERROR_CODES, } from './server.js';
+const DEFAULT_LOCALHOST_ORIGINS = Object.freeze([
+    'http://localhost',
+    'http://127.0.0.1',
+    'http://[::1]',
+    'https://localhost',
+    'https://127.0.0.1',
+    'https://[::1]',
+]);
+const MAX_BODY_BYTES = 1024 * 1024; // 1 MiB
+const MAX_SSE_CLIENTS_DEFAULT = 32;
+/** Header name SSE clients + RPC callers use to scope events. */
+export const PUGI_CLIENT_ID_HEADER = 'x-pugi-client-id';
+/**
+ * Start the HTTP+SSE transport. Returns a handle once the listener is
+ * bound — the caller can `await` the close hook for graceful shutdown.
+ */
+export async function serveHttp(options) {
+    const host = options.host ?? '127.0.0.1';
+    const log = options.log ?? (() => { });
+    const bearerTokenAutoGenerated = options.bearerToken === undefined;
+    const bearerToken = options.bearerToken ?? randomBytes(32).toString('hex');
+    const sseClients = new Set();
+    const corsOrigins = buildCorsOrigins(options.corsOrigins);
+    const maxSseClients = options.maxSseClients ?? MAX_SSE_CLIENTS_DEFAULT;
+    const tokenBuffer = Buffer.from(bearerToken, 'utf8');
+    // Bind the listener FIRST so we can resolve the effective Host header
+    // allowlist (the OS-assigned ephemeral port — when port=0 — is only
+    // known after listen). The createServer + listen split below preserves
+    // that ordering: handlers created here, allowed hosts computed after
+    // listening, then attached via the closure.
+    let allowedHosts = new Set();
+    const httpServer = createServer((req, res) => {
+        handleRequest({
+            req,
+            res,
+            mcpServer: options.server,
+            tokenBuffer,
+            sseClients,
+            corsOrigins,
+            allowedHosts,
+            maxSseClients,
+            log,
+        }).catch((error) => {
+            log('error', `unhandled http error: ${error.message}`);
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify({ error: 'internal_error', message: error.message }));
+            }
+        });
+    });
+    // Wire server events -> SSE broadcast. The payload may include a
+    // `clientId` (string) injected by the request dispatcher; if so we
+    // route the event only to the matching SSE client. Untagged events
+    // (no clientId) still broadcast — preserves the single-tenant
+    // operator workflow that does not bother to send the header.
+    const onToolCall = (payload) => {
+        routeSse(sseClients, 'tool_call', { name: payload.name, args: payload.args }, payload.clientId);
+    };
+    const onToolResult = (payload) => {
+        routeSse(sseClients, 'tool_result', { name: payload.name, ok: payload.ok, summary: payload.summary }, payload.clientId);
+    };
+    options.server.events.on('tool_call', onToolCall);
+    options.server.events.on('tool_result', onToolResult);
+    // Heartbeat — keep proxies + browser readers alive. 15s matches the
+    // admin-api SSE keepalive interval; same intermediary defenses (CDNs
+    // that drop quiet streams at ~30s). Heartbeats are untagged — every
+    // listener gets them.
+    const heartbeatTimer = setInterval(() => {
+        routeSse(sseClients, 'heartbeat', { ts: new Date().toISOString() }, undefined);
+    }, 15_000);
+    // Don't block process exit on the timer.
+    if (typeof heartbeatTimer.unref === 'function')
+        heartbeatTimer.unref();
+    // Bind the listener.
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            httpServer.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            httpServer.off('error', onError);
+            resolve();
+        };
+        httpServer.once('error', onError);
+        httpServer.once('listening', onListening);
+        httpServer.listen(options.port, host);
+    });
+    // Compute the effective bound port + Host allowlist. `address()`
+    // returns the OS-assigned port when caller passed 0.
+    const address = httpServer.address();
+    const effectivePort = address && typeof address === 'object' ? address.port : options.port;
+    allowedHosts = buildAllowedHosts(host, effectivePort, options.allowedHosts);
+    const url = `http://${host}:${effectivePort}`;
+    log('info', `pugi mcp http listening at ${url}`);
+    const close = async () => {
+        clearInterval(heartbeatTimer);
+        options.server.events.off('tool_call', onToolCall);
+        options.server.events.off('tool_result', onToolResult);
+        for (const client of sseClients)
+            client.close();
+        sseClients.clear();
+        await new Promise((resolveClose) => httpServer.close(() => resolveClose()));
+    };
+    if (options.signal) {
+        if (options.signal.aborted) {
+            await close();
+        }
+        else {
+            options.signal.addEventListener('abort', () => {
+                void close();
+            }, { once: true });
+        }
+    }
+    return {
+        url,
+        bearerToken,
+        bearerTokenAutoGenerated,
+        server: httpServer,
+        close,
+    };
+}
+async function handleRequest(input) {
+    const { req, res, mcpServer, tokenBuffer, sseClients, corsOrigins, allowedHosts, maxSseClients, log } = input;
+    // P0 #3 — Host header allowlist defends against DNS rebinding. The
+    // attacker page rebinds attacker.com → 127.0.0.1 (TTL=0), then issues
+    // a same-origin (`Host: attacker.com`) fetch. CORS does not gate
+    // same-origin requests; only a Host check stops it.
+    const hostHeader = headerString(req, 'host');
+    if (!hostHeader || !allowedHosts.has(hostHeader.toLowerCase())) {
+        // 421 Misdirected Request — the canonical HTTP code for "this server
+        // does not answer for that Host". Matches the Ollama / Jupyter
+        // mitigation choices for the same attack class.
+        res.statusCode = 421;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({
+            error: 'host_not_allowed',
+            message: `pugi mcp serve: Host header "${hostHeader ?? '<missing>'}" is not in the allowlist`,
+        }));
+        return;
+    }
+    applyCorsHeaders(req, res, corsOrigins);
+    // Pre-flight.
+    if (req.method === 'OPTIONS') {
+        res.statusCode = 204;
+        res.end();
+        return;
+    }
+    const url = req.url ?? '/';
+    // Strip query string for routing — endpoints are query-agnostic today.
+    const [pathnameRaw, queryString = ''] = url.split('?');
+    const pathname = pathnameRaw ?? '/';
+    if (pathname === '/mcp/v1/health' && req.method === 'GET') {
+        sendJson(res, 200, { ok: true, service: 'pugi-mcp', version: '0.1.0' });
+        return;
+    }
+    // Auth gate for everything else.
+    if (!checkAuth(req, tokenBuffer)) {
+        sendJson(res, 401, {
+            error: 'auth_required',
+            message: 'missing or invalid Authorization: Bearer <token>',
+        });
+        return;
+    }
+    if (pathname === '/mcp/v1/events' && req.method === 'GET') {
+        handleSse(req, res, sseClients, maxSseClients, queryString);
+        return;
+    }
+    if (req.method !== 'POST') {
+        sendJson(res, 405, { error: 'method_not_allowed', message: `use POST for ${pathname}` });
+        return;
+    }
+    // P1 #4 — early Content-Length cap. Reject the body before we read a
+    // single byte so a 4 GB POST never reaches `readJsonBody`. Some
+    // clients (curl --data-binary @big.bin) omit Content-Length and chunk-
+    // encode; for those `readJsonBody` enforces the same cap mid-stream.
+    const declaredLength = Number.parseInt(headerString(req, 'content-length') ?? '', 10);
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_BODY_BYTES) {
+        res.statusCode = 413;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({
+            error: 'payload_too_large',
+            message: `request body declared ${declaredLength} bytes; cap is ${MAX_BODY_BYTES}`,
+        }));
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (error) {
+        sendJson(res, 400, {
+            error: 'invalid_json',
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    // Resolve callerId for per-connection SSE scoping. Header beats query
+    // string; missing both means "untagged" (broadcast semantics preserved).
+    const callerId = resolveCallerId(req, queryString);
+    switch (pathname) {
+        case '/mcp/v1/initialize':
+            await handleRpcShortcut(res, mcpServer, 'initialize', body, callerId);
+            // β4 r2 P2 #4 — auto-complete the MCP handshake on behalf of
+            // shortcut clients. The MCP wire spec separates `initialize`
+            // (capabilities exchange) from `notifications/initialized` (client
+            // confirms it is ready), and the server's `requireInitialized`
+            // gate refuses `tools/call` until BOTH have fired. The shortcut
+            // endpoints abstract over JSON-RPC framing so callers (curl,
+            // Postman, ad-hoc fetch from a Worker) never see the second leg —
+            // we fire it ourselves so a `POST /initialize` followed by
+            // `POST /call` works as the shortcut surface promises. The raw
+            // `/rpc` endpoint still requires the explicit notification because
+            // its contract is "drive the wire protocol yourself".
+            await mcpServer
+                .handleMessage({
+                jsonrpc: '2.0',
+                method: 'notifications/initialized',
+                // No `id` — notifications never carry one. The server
+                // dispatcher returns null for notifications, so this never
+                // produces a response we'd need to drop.
+                ...(callerId ? { meta: { clientId: callerId } } : {}),
+            })
+                .catch((error) => {
+                // Best-effort: a notification failure cannot fail the prior
+                // /initialize response (already written). Log and continue —
+                // the next /call will surface the underlying issue with a
+                // clean INVALID_REQUEST.
+                log('warn', `auto-initialized notification failed: ${error.message}`);
+            });
+            return;
+        case '/mcp/v1/list':
+            await handleRpcShortcut(res, mcpServer, 'tools/list', body ?? {}, callerId);
+            return;
+        case '/mcp/v1/call':
+            await handleRpcShortcut(res, mcpServer, 'tools/call', body, callerId);
+            return;
+        case '/mcp/v1/rpc':
+            await handleRpcPassthrough(res, mcpServer, body, callerId, log);
+            return;
+        default:
+            sendJson(res, 404, { error: 'not_found', message: `unknown endpoint: ${pathname}` });
+            return;
+    }
+}
+async function handleRpcShortcut(res, mcpServer, method, params, callerId) {
+    const request = {
+        jsonrpc: '2.0',
+        id: 1, // synthetic — the shortcut path never multiplexes
+        method,
+        ...(params !== undefined ? { params } : {}),
+        ...(callerId ? { meta: { clientId: callerId } } : {}),
+    };
+    const response = await mcpServer.handleMessage(request);
+    if (!response) {
+        sendJson(res, 204, null);
+        return;
+    }
+    // Map JSON-RPC errors to HTTP status to make the shortcut usable from
+    // curl + Postman without parsing the envelope.
+    const httpStatus = jsonRpcErrorToHttpStatus(response);
+    sendJson(res, httpStatus, response);
+}
+async function handleRpcPassthrough(res, mcpServer, body, callerId, log) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        sendJson(res, 400, {
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: MCP_ERROR_CODES.INVALID_REQUEST, message: 'request body must be a JSON object' },
+        });
+        return;
+    }
+    const candidate = body;
+    if (candidate.jsonrpc !== '2.0' || typeof candidate.method !== 'string') {
+        sendJson(res, 400, {
+            jsonrpc: '2.0',
+            id: candidate.id ?? null,
+            error: {
+                code: MCP_ERROR_CODES.INVALID_REQUEST,
+                message: 'invalid JSON-RPC envelope: jsonrpc=2.0 + string method required',
+            },
+        });
+        return;
+    }
+    const request = {
+        jsonrpc: '2.0',
+        method: candidate.method,
+        ...(candidate.id !== undefined ? { id: candidate.id } : {}),
+        ...(candidate.params !== undefined ? { params: candidate.params } : {}),
+        ...(callerId ? { meta: { clientId: callerId } } : {}),
+    };
+    try {
+        const response = await mcpServer.handleMessage(request);
+        if (!response) {
+            sendJson(res, 204, null);
+            return;
+        }
+        sendJson(res, jsonRpcErrorToHttpStatus(response), response);
+    }
+    catch (error) {
+        log('error', `rpc passthrough failed: ${error.message}`);
+        sendJson(res, 500, {
+            jsonrpc: '2.0',
+            id: candidate.id ?? null,
+            error: { code: MCP_ERROR_CODES.INTERNAL_ERROR, message: error.message },
+        });
+    }
+}
+function jsonRpcErrorToHttpStatus(response) {
+    if (!('error' in response))
+        return 200;
+    switch (response.error.code) {
+        case MCP_ERROR_CODES.METHOD_NOT_FOUND:
+            return 404;
+        case MCP_ERROR_CODES.INVALID_REQUEST:
+        case MCP_ERROR_CODES.INVALID_PARAMS:
+        case MCP_ERROR_CODES.PARSE_ERROR:
+            return 400;
+        case MCP_ERROR_CODES.PERMISSION_REFUSED:
+            return 403;
+        case MCP_ERROR_CODES.AUTH_REQUIRED:
+            return 401;
+        default:
+            return 500;
+    }
+}
+function handleSse(req, res, sseClients, maxSseClients, queryString) {
+    // P1 #4 — connection cap. A misbehaving caller cannot accumulate
+    // dangling SSE handles indefinitely; the 33rd connection bounces.
+    if (sseClients.size >= maxSseClients) {
+        res.statusCode = 503;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({
+            error: 'sse_capacity',
+            message: `pugi mcp serve: SSE client cap (${maxSseClients}) reached`,
+        }));
+        return;
+    }
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    const clientId = resolveCallerId(req, queryString);
+    // Surface the assigned/observed clientId in a comment frame so the
+    // listener can correlate it with subsequent tool-call POSTs.
+    res.write(`:ready clientId=${clientId ?? ''}\n\n`);
+    const client = {
+        res,
+        clientId,
+        close: () => {
+            try {
+                res.end();
+            }
+            catch {
+                // already closed
+            }
+        },
+    };
+    sseClients.add(client);
+    const cleanup = () => {
+        sseClients.delete(client);
+    };
+    req.on('close', cleanup);
+    req.on('error', cleanup);
+}
+/**
+ * Route an SSE event to the correct subset of clients.
+ *
+ *   - `targetClientId` undefined → broadcast (every connected client).
+ *     Used for heartbeats AND for tool events that omit the clientId
+ *     header (single-tenant operator default).
+ *   - `targetClientId` set → deliver only to clients that opened the
+ *     stream with the matching clientId. Other listeners (different
+ *     paired agents) do not see the event. This is the per-connection
+ *     confidentiality scope (β4 r1 P1 #5).
+ */
+function routeSse(sseClients, event, data, targetClientId) {
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const client of sseClients) {
+        if (targetClientId !== undefined && client.clientId !== targetClientId) {
+            continue;
+        }
+        try {
+            client.res.write(payload);
+        }
+        catch {
+            // Best-effort — the close listener cleans up.
+        }
+    }
+}
+/* ---------- helpers ---------------------------------------------------- */
+function applyCorsHeaders(req, res, origins) {
+    const origin = headerString(req, 'origin');
+    // Resolve the request origin against the allowlist. If the request
+    // has no Origin header (curl, server-to-server) we skip CORS — the
+    // bearer-token gate is the actual auth boundary. We deliberately
+    // never emit `Access-Control-Allow-Credentials: true` — no endpoint
+    // uses cookies, and the credentialed-fetch hole it created (paired
+    // with port-agnostic origins) was the β4 r1 P0 #2 root cause.
+    if (origin && originAllowed(origin, origins)) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', `Authorization, Content-Type, ${PUGI_CLIENT_ID_HEADER}`);
+        res.setHeader('Access-Control-Max-Age', '600');
+    }
+}
+function originAllowed(origin, allowlist) {
+    // Exact match is the only safe gate. The previous implementation did
+    // `origin.startsWith(candidate + ':')` which whitelisted EVERY port on
+    // localhost — combined with credentialed fetch (now removed) it
+    // created a cross-origin read primitive for any locally-running web
+    // server. We now require the operator to add the exact origin
+    // (including port) via `corsOrigins`, OR rely on the bare-host
+    // localhost defaults (no port → matches the browser's `http://localhost`
+    // canonical form).
+    return allowlist.has(origin);
+}
+function buildCorsOrigins(extra) {
+    const set = new Set(DEFAULT_LOCALHOST_ORIGINS);
+    if (!extra)
+        return set;
+    for (const origin of extra) {
+        if (origin === '*') {
+            throw new Error('pugi mcp serve --http: wildcard CORS origin "*" is not supported (use a specific origin)');
+        }
+        set.add(origin);
+    }
+    return set;
+}
+function buildAllowedHosts(host, port, extra) {
+    // Standard local-only allowlist. Lowercase normalised because the
+    // Host header is case-insensitive per RFC 7230 §5.4 — we lowercase
+    // both sides at compare-time too.
+    const set = new Set([
+        `127.0.0.1:${port}`,
+        `localhost:${port}`,
+        `[::1]:${port}`,
+        // Bind host may be 0.0.0.0 / non-loopback — still register it so
+        // the operator's intentional broader bind keeps working.
+        `${host.toLowerCase()}:${port}`,
+    ]);
+    if (extra) {
+        for (const entry of extra)
+            set.add(entry.toLowerCase());
+    }
+    return set;
+}
+function checkAuth(req, tokenBuffer) {
+    const header = headerString(req, 'authorization');
+    if (!header)
+        return false;
+    const match = /^Bearer\s+(.+)$/.exec(header.trim());
+    if (!match)
+        return false;
+    const supplied = Buffer.from(match[1] ?? '', 'utf8');
+    if (supplied.length !== tokenBuffer.length)
+        return false;
+    try {
+        return timingSafeEqual(supplied, tokenBuffer);
+    }
+    catch {
+        return false;
+    }
+}
+function headerString(req, name) {
+    const value = req.headers[name];
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+}
+/**
+ * Resolve the caller's stable clientId. Header is the canonical channel
+ * (clients that POST a tool call can declare it programmatically); the
+ * query string is the fallback for SSE GETs because browsers cannot set
+ * custom headers on `EventSource`.
+ *
+ * β4 r2 P2 #5 — GET requests ALWAYS get a stable id (auto-assigned via
+ * randomUUID when the caller supplied neither header nor query). Before
+ * this fix the `if (!queryString) return undefined` guard short-circuited
+ * BEFORE the GET-auto-assign branch, so a bare `GET /mcp/v1/events`
+ * (no query string at all) landed in the "untagged broadcast" routing
+ * bucket and received events meant for OTHER tagged clients.
+ *
+ * POSTs that omit it stay untagged on purpose (single-tenant operator
+ * default — the dispatcher emits untagged tool events that broadcast).
+ */
+function resolveCallerId(req, queryString) {
+    const headerValue = headerString(req, PUGI_CLIENT_ID_HEADER);
+    if (headerValue && headerValue.trim().length > 0)
+        return headerValue.trim();
+    if (queryString) {
+        const params = new URLSearchParams(queryString);
+        const fromQuery = params.get('clientId');
+        if (fromQuery && fromQuery.trim().length > 0)
+            return fromQuery.trim();
+    }
+    // β4 r2 P2 #5 — bare GET (no header, no query, OR query without a
+    // clientId param) still gets an auto-id so the SSE listener never
+    // shares the broadcast bucket with another subscriber. The auto-id
+    // is surfaced via the `:ready clientId=<uuid>\n\n` SSE comment in
+    // handleSse so the listener can copy it into subsequent POSTs.
+    if (req.method === 'GET')
+        return randomUUID();
+    return undefined;
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        total += buf.length;
+        if (total > MAX_BODY_BYTES) {
+            throw new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`);
+        }
+        chunks.push(buf);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    const raw = Buffer.concat(chunks).toString('utf8');
+    if (raw.trim().length === 0)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`invalid JSON body: ${error.message}`);
+    }
+}
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    if (body === null) {
+        res.end();
+        return;
+    }
+    res.end(JSON.stringify(body));
+}
+/* ---------- shared emitter for tests ----------------------------------- */
+/**
+ * Internal helper exposed for tests: build an in-memory EventEmitter
+ * that mirrors the broadcast surface. The real server uses
+ * `mcpServer.events` directly; tests that want to drive synthetic
+ * events without a full MCP round-trip use this.
+ */
+export function createTestEventBus() {
+    return new EventEmitter();
+}
+//# sourceMappingURL=http-server.js.map