@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

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

@@ -1,553 +0,0 @@
-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