@j0hanz/superfetch 1.2.5 → 2.0.0

package/dist/http/mcp-session.js

@@ -5,7 +5,9 @@ import { config } from '../config/index.js';
 import { logError, logInfo, logWarn } from '../services/logger.js';
 import { getErrorMessage } from '../utils/error-utils.js';
 import { createMcpServer } from '../server.js';
+import { sendJsonRpcError } from './jsonrpc-http.js';
 import { createSlotTracker, ensureSessionCapacity, reserveSessionSlot, respondBadRequest, respondServerBusy, } from './mcp-session-helpers.js';
+import { createTimeoutController, createTransportAdapter, } from './mcp-session-transport.js';
 import {} from './sessions.js';
 function startSessionInitTimeout(transport, tracker, clearInitTimeout, timeoutMs) {
     if (timeoutMs <= 0)
@@ -25,68 +27,23 @@ function startSessionInitTimeout(transport, tracker, clearInitTimeout, timeoutMs
     timeout.unref();
     return timeout;
 }
-function handleSessionInitialized(id, transport, options, tracker, clearInitTimeout) {
-    clearInitTimeout();
-    tracker.markInitialized();
-    tracker.releaseSlot();
-    const now = Date.now();
-    options.sessionStore.set(id, {
-        transport,
-        createdAt: now,
-        lastSeen: now,
-    });
-    logInfo('Session initialized', { sessionId: id });
-}
-function handleSessionClosed(id, options) {
-    options.sessionStore.remove(id);
-    logInfo('Session closed', { sessionId: id });
-}
-function handleTransportClose(transport, options, tracker, clearInitTimeout) {
-    clearInitTimeout();
-    if (!tracker.isInitialized()) {
-        tracker.releaseSlot();
-    }
-    if (transport.sessionId) {
-        options.sessionStore.remove(transport.sessionId);
-    }
-}
-function createTransportForNewSession(options) {
-    const tracker = createSlotTracker();
-    let initTimeout = null;
-    const clearInitTimeout = () => {
-        if (!initTimeout)
-            return;
-        clearTimeout(initTimeout);
-        initTimeout = null;
-    };
-    const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () => randomUUID(),
-        onsessioninitialized: (id) => {
-            handleSessionInitialized(id, transport, options, tracker, clearInitTimeout);
-        },
-        onsessionclosed: (id) => {
-            handleSessionClosed(id, options);
-        },
-    });
-    transport.onclose = () => {
-        handleTransportClose(transport, options, tracker, clearInitTimeout);
-    };
-    initTimeout = startSessionInitTimeout(transport, tracker, clearInitTimeout, config.server.sessionInitTimeoutMs);
-    return { transport, releaseSlot: tracker.releaseSlot, clearInitTimeout };
-}
-function findExistingTransport(sessionId, options) {
-    if (!sessionId) {
-        return null;
+async function connectTransportOrThrow(transport, clearInitTimeout, releaseSlot) {
+    const mcpServer = createMcpServer();
+    const transportAdapter = createTransportAdapter(transport);
+    try {
+        await mcpServer.connect(transportAdapter);
     }
-    const existingSession = options.sessionStore.get(sessionId);
-    if (!existingSession) {
-        return null;
+    catch (error) {
+        clearInitTimeout();
+        releaseSlot();
+        void transport.close().catch((closeError) => {
+            logWarn('Failed to close transport after connect error', {
+                error: getErrorMessage(closeError),
+            });
+        });
+        logError('Failed to initialize MCP session', error instanceof Error ? error : undefined);
+        throw error;
     }
-    options.sessionStore.touch(sessionId);
-    return existingSession.transport;
-}
-function shouldInitializeSession(sessionId, body) {
-    return !sessionId && isInitializeRequest(body);
 }
 async function createAndConnectTransport(options, res) {
     if (!ensureSessionCapacity(options.sessionStore, options.maxSessions, res, evictOldestSession)) {
@@ -96,25 +53,55 @@ async function createAndConnectTransport(options, res) {
         respondServerBusy(res);
         return null;
     }
-    const { transport, releaseSlot, clearInitTimeout } = createTransportForNewSession(options);
-    const mcpServer = createMcpServer();
-    try {
-        await mcpServer.connect(transport);
-    }
-    catch (error) {
+    const tracker = createSlotTracker();
+    const timeoutController = createTimeoutController();
+    const { clear: clearInitTimeout } = timeoutController;
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    transport.onclose = () => {
         clearInitTimeout();
-        releaseSlot();
-        logError('Failed to initialize MCP session', error instanceof Error ? error : undefined);
-        throw error;
+        if (!tracker.isInitialized()) {
+            tracker.releaseSlot();
+        }
+    };
+    timeoutController.set(startSessionInitTimeout(transport, tracker, clearInitTimeout, config.server.sessionInitTimeoutMs));
+    await connectTransportOrThrow(transport, clearInitTimeout, tracker.releaseSlot);
+    const { sessionId } = transport;
+    if (typeof sessionId !== 'string') {
+        clearInitTimeout();
+        tracker.releaseSlot();
+        respondBadRequest(res);
+        return null;
     }
+    clearInitTimeout();
+    tracker.markInitialized();
+    tracker.releaseSlot();
+    const now = Date.now();
+    options.sessionStore.set(sessionId, {
+        transport,
+        createdAt: now,
+        lastSeen: now,
+    });
+    transport.onclose = () => {
+        options.sessionStore.remove(sessionId);
+        logInfo('Session closed');
+    };
+    logInfo('Session initialized');
     return transport;
 }
 export async function resolveTransportForPost(_req, res, body, sessionId, options) {
-    const existingTransport = findExistingTransport(sessionId, options);
-    if (existingTransport) {
-        return existingTransport;
+    if (sessionId) {
+        const existingSession = options.sessionStore.get(sessionId);
+        if (existingSession) {
+            options.sessionStore.touch(sessionId);
+            return existingSession.transport;
+        }
+        // Client supplied a session id but it doesn't exist; Streamable HTTP: invalid session IDs => 404.
+        sendJsonRpcError(res, -32600, 'Session not found', 404);
+        return null;
     }
-    if (!shouldInitializeSession(sessionId, body)) {
+    if (!isInitializeRequest(body)) {
         respondBadRequest(res);
         return null;
     }

package/dist/http/mcp-validation.d.ts

@@ -1,2 +1,3 @@
 import type { McpRequestBody } from '../config/types/runtime.js';
+export declare function isJsonRpcBatchRequest(body: unknown): boolean;
 export declare function isMcpRequestBody(body: unknown): body is McpRequestBody;

package/dist/http/mcp-validation.js

@@ -1,13 +1,14 @@
-function isRecord(value) {
-    return value !== null && typeof value === 'object';
+import { z } from 'zod';
+const paramsSchema = z.looseObject({});
+const mcpRequestSchema = z.looseObject({
+    jsonrpc: z.literal('2.0'),
+    method: z.string().min(1),
+    id: z.union([z.string(), z.number()]).optional(),
+    params: paramsSchema.optional(),
+});
+export function isJsonRpcBatchRequest(body) {
+    return Array.isArray(body);
 }
 export function isMcpRequestBody(body) {
-    if (!isRecord(body) || Array.isArray(body))
-        return false;
-    const { method, id, jsonrpc, params } = body;
-    const methodValid = method === undefined || typeof method === 'string';
-    const idValid = id === undefined || typeof id === 'string' || typeof id === 'number';
-    const jsonrpcValid = jsonrpc === undefined || jsonrpc === '2.0';
-    const paramsValid = params === undefined || typeof params === 'object';
-    return methodValid && idValid && jsonrpcValid && paramsValid;
+    return mcpRequestSchema.safeParse(body).success;
 }

package/dist/http/protocol-policy.d.ts

@@ -0,0 +1,2 @@
+import type { Request, Response } from 'express';
+export declare function ensureMcpProtocolVersionHeader(req: Request, res: Response): boolean;

package/dist/http/protocol-policy.js

@@ -0,0 +1,31 @@
+import { sendJsonRpcError } from './jsonrpc-http.js';
+const MCP_PROTOCOL_VERSION_HEADER = 'mcp-protocol-version';
+const MCP_PROTOCOL_VERSIONS = {
+    defaultVersion: '2025-03-26',
+    supported: new Set(['2025-03-26', '2025-11-25']),
+};
+function getHeaderValue(req, headerNameLower) {
+    const value = req.headers[headerNameLower];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return null;
+}
+function setHeaderValue(req, headerNameLower, value) {
+    // Express exposes req.headers as a plain object, but the type is readonly-ish.
+    req.headers[headerNameLower] = value;
+}
+export function ensureMcpProtocolVersionHeader(req, res) {
+    const raw = getHeaderValue(req, MCP_PROTOCOL_VERSION_HEADER);
+    const version = raw?.trim();
+    if (!version) {
+        setHeaderValue(req, MCP_PROTOCOL_VERSION_HEADER, MCP_PROTOCOL_VERSIONS.defaultVersion);
+        return true;
+    }
+    if (!MCP_PROTOCOL_VERSIONS.supported.has(version)) {
+        sendJsonRpcError(res, -32600, `Unsupported MCP-Protocol-Version: ${version}`, 400);
+        return false;
+    }
+    return true;
+}

package/dist/http/rate-limit.js

@@ -13,7 +13,11 @@ export function createRateLimitMiddleware(options) {
     const stop = () => {
         cleanupController.abort();
     };
-    const middleware = (req, res, next) => {
+    const middleware = createRateLimitHandler(store, options);
+    return { middleware, stop, store };
+}
+function createRateLimitHandler(store, options) {
+    return (req, res, next) => {
         if (shouldSkipRateLimit(req, options)) {
             next();
             return;
@@ -30,7 +34,6 @@ export function createRateLimitMiddleware(options) {
         }
         next();
     };
-    return { middleware, stop, store };
 }
 async function startCleanupLoop(store, options, signal) {
     for await (const _ of setIntervalPromise(options.cleanupIntervalMs, undefined, { signal, ref: false })) {

package/dist/http/server-config.d.ts

@@ -0,0 +1 @@
+export declare function assertHttpConfiguration(): void;

package/dist/http/server-config.js

@@ -0,0 +1,40 @@
+import { config } from '../config/index.js';
+import { logError } from '../services/logger.js';
+export function assertHttpConfiguration() {
+    ensureBindAllowed();
+    ensureStaticTokens();
+    if (config.auth.mode === 'oauth') {
+        ensureOauthConfiguration();
+    }
+}
+function ensureBindAllowed() {
+    const isLoopback = ['127.0.0.1', '::1', 'localhost'].includes(config.server.host);
+    if (!config.security.allowRemote && !isLoopback) {
+        logError('Refusing to bind to non-loopback host without ALLOW_REMOTE=true', { host: config.server.host });
+        process.exit(1);
+    }
+    if (config.security.allowRemote && config.auth.mode !== 'oauth') {
+        logError('Remote HTTP mode requires OAuth configuration; refusing to start');
+        process.exit(1);
+    }
+}
+function ensureStaticTokens() {
+    if (config.auth.mode === 'static' && config.auth.staticTokens.length === 0) {
+        logError('At least one static access token is required for HTTP mode');
+        process.exit(1);
+    }
+}
+function ensureOauthConfiguration() {
+    if (!config.auth.issuerUrl || !config.auth.authorizationUrl) {
+        logError('OAUTH_ISSUER_URL and OAUTH_AUTHORIZATION_URL are required for OAuth mode');
+        process.exit(1);
+    }
+    if (!config.auth.tokenUrl) {
+        logError('OAUTH_TOKEN_URL is required for OAuth mode');
+        process.exit(1);
+    }
+    if (!config.auth.introspectionUrl) {
+        logError('OAUTH_INTROSPECTION_URL is required for OAuth mode');
+        process.exit(1);
+    }
+}

package/dist/http/server-middleware.d.ts

@@ -1,9 +1,2 @@
-import type { Express, NextFunction, Request, RequestHandler, Response } from 'express';
-export declare function buildCorsOptions(): {
-    allowedOrigins: string[];
-    allowAllOrigins: boolean;
-};
-export declare function createJsonParseErrorHandler(): (err: Error, _req: Request, res: Response, next: NextFunction) => void;
-export declare function createContextMiddleware(): (req: Request, _res: Response, next: NextFunction) => void;
-export declare function registerHealthRoute(app: Express): void;
-export declare function attachBaseMiddleware(app: Express, jsonParser: RequestHandler, rateLimitMiddleware: RequestHandler, authMiddleware: RequestHandler, corsMiddleware: RequestHandler): void;
+import type { Express, RequestHandler } from 'express';
+export declare function attachBaseMiddleware(app: Express, jsonParser: RequestHandler, rateLimitMiddleware: RequestHandler, corsMiddleware: RequestHandler): void;

package/dist/http/server-middleware.js

@@ -1,45 +1,93 @@
 import { randomUUID } from 'node:crypto';
 import { config } from '../config/index.js';
-import { bindToRequestContext, runWithRequestContext, } from '../services/context.js';
+import { runWithRequestContext } from '../services/context.js';
 import { getSessionId } from './sessions.js';
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+function getNonEmptyStringHeader(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed === '' ? null : trimmed;
+}
+function respondHostNotAllowed(res) {
+    res.status(403).json({
+        error: 'Host not allowed',
+        code: 'HOST_NOT_ALLOWED',
+    });
+}
+function respondOriginNotAllowed(res) {
+    res.status(403).json({
+        error: 'Origin not allowed',
+        code: 'ORIGIN_NOT_ALLOWED',
+    });
+}
+function tryParseOriginHostname(originHeader) {
+    try {
+        return new URL(originHeader).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function takeFirstHostValue(value) {
+    const first = value.split(',')[0];
+    if (!first)
+        return null;
+    const trimmed = first.trim();
+    return trimmed ? trimmed : null;
+}
+function stripIpv6Brackets(value) {
+    if (!value.startsWith('['))
+        return null;
+    const end = value.indexOf(']');
+    if (end === -1)
+        return null;
+    return value.slice(1, end);
+}
+function stripPortIfPresent(value) {
+    const colonIndex = value.indexOf(':');
+    if (colonIndex === -1)
+        return value;
+    return value.slice(0, colonIndex);
+}
 function normalizeHost(value) {
     const trimmed = value.trim().toLowerCase();
     if (!trimmed)
         return null;
-    const first = trimmed.split(',')[0]?.trim();
+    const first = takeFirstHostValue(trimmed);
     if (!first)
         return null;
-    if (first.startsWith('[')) {
-        const end = first.indexOf(']');
-        if (end === -1)
-            return null;
-        return first.slice(1, end);
-    }
-    const colonIndex = first.indexOf(':');
-    if (colonIndex !== -1) {
-        return first.slice(0, colonIndex);
-    }
-    return first;
+    const ipv6 = stripIpv6Brackets(first);
+    if (ipv6)
+        return ipv6;
+    return stripPortIfPresent(first);
 }
-function buildAllowedHosts() {
-    const allowedHosts = new Set();
-    const raw = process.env.ALLOWED_HOSTS ?? '';
-    for (const entry of raw.split(',')) {
-        const normalized = normalizeHost(entry);
-        if (normalized) {
-            allowedHosts.add(normalized);
-        }
-    }
+function isWildcardHost(host) {
+    return host === '0.0.0.0' || host === '::';
+}
+function addLoopbackHosts(allowedHosts) {
     for (const host of LOOPBACK_HOSTS) {
         allowedHosts.add(host);
     }
+}
+function addConfiguredHost(allowedHosts) {
     const configuredHost = normalizeHost(config.server.host);
-    if (configuredHost &&
-        configuredHost !== '0.0.0.0' &&
-        configuredHost !== '::') {
-        allowedHosts.add(configuredHost);
+    if (!configuredHost)
+        return;
+    if (isWildcardHost(configuredHost))
+        return;
+    allowedHosts.add(configuredHost);
+}
+function addExplicitAllowedHosts(allowedHosts) {
+    for (const host of config.security.allowedHosts) {
+        allowedHosts.add(host);
     }
+}
+function buildAllowedHosts() {
+    const allowedHosts = new Set();
+    addLoopbackHosts(allowedHosts);
+    addConfiguredHost(allowedHosts);
+    addExplicitAllowedHosts(allowedHosts);
     return allowedHosts;
 }
 function createHostValidationMiddleware() {
@@ -48,23 +96,29 @@ function createHostValidationMiddleware() {
         const hostHeader = typeof req.headers.host === 'string' ? req.headers.host : '';
         const normalized = normalizeHost(hostHeader);
         if (!normalized || !allowedHosts.has(normalized)) {
-            res.status(403).json({
-                error: 'Host not allowed',
-                code: 'HOST_NOT_ALLOWED',
-            });
+            respondHostNotAllowed(res);
             return;
         }
         next();
     };
 }
-export function buildCorsOptions() {
-    const allowedOrigins = process.env.ALLOWED_ORIGINS
-        ? process.env.ALLOWED_ORIGINS.split(',').map((o) => o.trim())
-        : [];
-    const allowAllOrigins = process.env.CORS_ALLOW_ALL === 'true';
-    return { allowedOrigins, allowAllOrigins };
+function createOriginValidationMiddleware() {
+    const allowedHosts = buildAllowedHosts();
+    return (req, res, next) => {
+        const originHeader = getNonEmptyStringHeader(req.headers.origin);
+        if (!originHeader) {
+            next();
+            return;
+        }
+        const originHostname = tryParseOriginHostname(originHeader);
+        if (!originHostname || !allowedHosts.has(originHostname)) {
+            respondOriginNotAllowed(res);
+            return;
+        }
+        next();
+    };
 }
-export function createJsonParseErrorHandler() {
+function createJsonParseErrorHandler() {
     return (err, _req, res, next) => {
         if (err instanceof SyntaxError && 'body' in err) {
             res.status(400).json({
@@ -80,18 +134,17 @@ export function createJsonParseErrorHandler() {
         next();
     };
 }
-export function createContextMiddleware() {
+function createContextMiddleware() {
     return (req, _res, next) => {
         const requestId = randomUUID();
         const sessionId = getSessionId(req);
         const context = sessionId === undefined ? { requestId } : { requestId, sessionId };
         runWithRequestContext(context, () => {
-            const boundNext = bindToRequestContext(next);
-            boundNext();
+            next();
         });
     };
 }
-export function registerHealthRoute(app) {
+function registerHealthRoute(app) {
     app.get('/health', (_req, res) => {
         res.json({
             status: 'healthy',
@@ -101,13 +154,13 @@ export function registerHealthRoute(app) {
         });
     });
 }
-export function attachBaseMiddleware(app, jsonParser, rateLimitMiddleware, authMiddleware, corsMiddleware) {
+export function attachBaseMiddleware(app, jsonParser, rateLimitMiddleware, corsMiddleware) {
     app.use(createHostValidationMiddleware());
+    app.use(createOriginValidationMiddleware());
     app.use(jsonParser);
     app.use(createContextMiddleware());
     app.use(createJsonParseErrorHandler());
     app.use(corsMiddleware);
     app.use('/mcp', rateLimitMiddleware);
-    app.use(authMiddleware);
     registerHealthRoute(app);
 }

package/dist/http/server-shutdown.d.ts

@@ -0,0 +1,4 @@
+import type { Express } from 'express';
+import type { SessionStore } from './sessions.js';
+export declare function createShutdownHandler(server: ReturnType<Express['listen']>, sessionStore: SessionStore, sessionCleanupController: AbortController, stopRateLimitCleanup: () => void): (signal: string) => Promise<void>;
+export declare function registerSignalHandlers(shutdown: (signal: string) => Promise<void>): void;

package/dist/http/server-shutdown.js

@@ -0,0 +1,43 @@
+import { destroyAgents } from '../services/fetcher/agents.js';
+import { logError, logInfo, logWarn } from '../services/logger.js';
+import { getErrorMessage } from '../utils/error-utils.js';
+export function createShutdownHandler(server, sessionStore, sessionCleanupController, stopRateLimitCleanup) {
+    return (signal) => shutdownServer(signal, server, sessionStore, sessionCleanupController, stopRateLimitCleanup);
+}
+async function shutdownServer(signal, server, sessionStore, sessionCleanupController, stopRateLimitCleanup) {
+    logInfo(`${signal} received, shutting down gracefully...`);
+    stopRateLimitCleanup();
+    sessionCleanupController.abort();
+    await closeSessions(sessionStore);
+    destroyAgents();
+    closeServer(server);
+    scheduleForcedShutdown(10000);
+}
+async function closeSessions(sessionStore) {
+    const sessions = sessionStore.clear();
+    await Promise.allSettled(sessions.map((session) => session.transport.close().catch((error) => {
+        logWarn('Failed to close session during shutdown', {
+            error: getErrorMessage(error),
+        });
+    })));
+}
+function closeServer(server) {
+    server.close(() => {
+        logInfo('HTTP server closed');
+        process.exit(0);
+    });
+}
+function scheduleForcedShutdown(timeoutMs) {
+    setTimeout(() => {
+        logError('Forced shutdown after timeout');
+        process.exit(1);
+    }, timeoutMs).unref();
+}
+export function registerSignalHandlers(shutdown) {
+    process.on('SIGINT', () => {
+        void shutdown('SIGINT');
+    });
+    process.on('SIGTERM', () => {
+        void shutdown('SIGTERM');
+    });
+}