@j0hanz/superfetch 2.0.0 → 2.0.1

package/dist/http/server.js

@@ -1,16 +1,508 @@
+import { randomUUID } from 'node:crypto';
+import { setInterval as setIntervalPromise } from 'node:timers/promises';
 import { config, enableHttpMode } from '../config/index.js';
-import { logError, logInfo } from '../services/logger.js';
-import { errorHandler } from '../middleware/error-handler.js';
+import { FetchError } from '../errors/app-error.js';
+import * as cache from '../services/cache.js';
+import { runWithRequestContext } from '../services/context.js';
+import { destroyAgents } from '../services/fetcher.js';
+import { logDebug, logError, logInfo, logWarn } from '../services/logger.js';
+import { parseCachedPayload, resolveCachedPayloadContent, } from '../utils/cached-payload.js';
+import { getErrorMessage } from '../utils/error-details.js';
+import { generateSafeFilename } from '../utils/filename-generator.js';
 import { createAuthMetadataRouter, createAuthMiddleware } from './auth.js';
-import { createCorsMiddleware } from './cors.js';
-import { registerDownloadRoutes } from './download-routes.js';
 import { registerMcpRoutes } from './mcp-routes.js';
-import { createRateLimitMiddleware } from './rate-limit.js';
-import { assertHttpConfiguration } from './server-config.js';
-import { attachBaseMiddleware } from './server-middleware.js';
-import { createShutdownHandler, registerSignalHandlers, } from './server-shutdown.js';
-import { startSessionCleanupLoop } from './session-cleanup.js';
-import { createSessionStore } from './sessions.js';
+import { createSessionStore, getSessionId, startSessionCleanupLoop, } from './mcp-sessions.js';
+function getRateLimitKey(req) {
+    return req.ip ?? req.socket.remoteAddress ?? 'unknown';
+}
+function createCleanupInterval(store, options) {
+    const controller = new AbortController();
+    void startCleanupLoop(store, options, controller.signal).catch(handleCleanupError);
+    return controller;
+}
+function createRateLimitMiddleware(options) {
+    const store = new Map();
+    const cleanupController = createCleanupInterval(store, options);
+    const stop = () => {
+        cleanupController.abort();
+    };
+    const middleware = createRateLimitHandler(store, options);
+    return { middleware, stop, store };
+}
+function createRateLimitHandler(store, options) {
+    return (req, res, next) => {
+        if (shouldSkipRateLimit(req, options)) {
+            next();
+            return;
+        }
+        const now = Date.now();
+        const key = getRateLimitKey(req);
+        const resolution = resolveRateLimitEntry(store, key, now, options);
+        if (resolution.isNew) {
+            next();
+            return;
+        }
+        if (handleRateLimitExceeded(res, resolution.entry, now, options)) {
+            return;
+        }
+        next();
+    };
+}
+async function startCleanupLoop(store, options, signal) {
+    for await (const getNow of setIntervalPromise(options.cleanupIntervalMs, Date.now, { signal, ref: false })) {
+        evictStaleEntries(store, options, getNow());
+    }
+}
+function evictStaleEntries(store, options, now) {
+    for (const [key, entry] of store.entries()) {
+        if (now - entry.lastAccessed > options.windowMs * 2) {
+            store.delete(key);
+        }
+    }
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function handleCleanupError(error) {
+    if (isAbortError(error)) {
+        return;
+    }
+}
+function shouldSkipRateLimit(req, options) {
+    return !options.enabled || req.method === 'OPTIONS';
+}
+function resolveRateLimitEntry(store, key, now, options) {
+    const existing = store.get(key);
+    if (!existing || now > existing.resetTime) {
+        const entry = createNewEntry(now, options);
+        store.set(key, entry);
+        return { entry, isNew: true };
+    }
+    updateEntry(existing, now);
+    return { entry: existing, isNew: false };
+}
+function createNewEntry(now, options) {
+    return {
+        count: 1,
+        resetTime: now + options.windowMs,
+        lastAccessed: now,
+    };
+}
+function updateEntry(entry, now) {
+    entry.count += 1;
+    entry.lastAccessed = now;
+}
+function handleRateLimitExceeded(res, entry, now, options) {
+    if (entry.count <= options.maxRequests) {
+        return false;
+    }
+    const retryAfter = Math.max(1, Math.ceil((entry.resetTime - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    res.status(429).json({
+        error: 'Rate limit exceeded',
+        retryAfter,
+    });
+    return true;
+}
+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 = takeFirstHostValue(trimmed);
+    if (!first)
+        return null;
+    const ipv6 = stripIpv6Brackets(first);
+    if (ipv6)
+        return ipv6;
+    return stripPortIfPresent(first);
+}
+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)
+        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() {
+    const allowedHosts = buildAllowedHosts();
+    return (req, res, next) => {
+        const hostHeader = typeof req.headers.host === 'string' ? req.headers.host : '';
+        const normalized = normalizeHost(hostHeader);
+        if (!normalized || !allowedHosts.has(normalized)) {
+            respondHostNotAllowed(res);
+            return;
+        }
+        next();
+    };
+}
+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();
+    };
+}
+function createJsonParseErrorHandler() {
+    return (err, _req, res, next) => {
+        if (err instanceof SyntaxError && 'body' in err) {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32700,
+                    message: 'Parse error: Invalid JSON',
+                },
+                id: null,
+            });
+            return;
+        }
+        next();
+    };
+}
+function createContextMiddleware() {
+    return (req, _res, next) => {
+        const requestId = randomUUID();
+        const sessionId = getSessionId(req);
+        const context = sessionId === undefined ? { requestId } : { requestId, sessionId };
+        runWithRequestContext(context, () => {
+            next();
+        });
+    };
+}
+export function createCorsMiddleware() {
+    return (req, res, next) => {
+        // Handle OPTIONS preflight
+        if (req.method === 'OPTIONS') {
+            res.sendStatus(200);
+            return;
+        }
+        next();
+    };
+}
+function registerHealthRoute(app) {
+    app.get('/health', (_req, res) => {
+        res.json({
+            status: 'healthy',
+            name: config.server.name,
+            version: config.server.version,
+            uptime: process.uptime(),
+        });
+    });
+}
+export function attachBaseMiddleware(options) {
+    const { app, jsonParser, rateLimitMiddleware, corsMiddleware } = options;
+    app.use(createHostValidationMiddleware());
+    app.use(createOriginValidationMiddleware());
+    app.use(jsonParser);
+    app.use(createContextMiddleware());
+    app.use(createJsonParseErrorHandler());
+    app.use(corsMiddleware);
+    app.use('/mcp', rateLimitMiddleware);
+    registerHealthRoute(app);
+}
+const HASH_PATTERN = /^[a-f0-9.]+$/i;
+function validateNamespace(namespace) {
+    return namespace === 'markdown';
+}
+function validateHash(hash) {
+    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
+}
+function parseDownloadParams(req) {
+    const { namespace, hash } = req.params;
+    if (!namespace || !hash)
+        return null;
+    if (!validateNamespace(namespace))
+        return null;
+    if (!validateHash(hash))
+        return null;
+    return { namespace, hash };
+}
+function buildCacheKeyFromParams(params) {
+    return `${params.namespace}:${params.hash}`;
+}
+function respondBadRequest(res, message) {
+    res.status(400).json({
+        error: message,
+        code: 'BAD_REQUEST',
+    });
+}
+function respondNotFound(res) {
+    res.status(404).json({
+        error: 'Content not found or expired',
+        code: 'NOT_FOUND',
+    });
+}
+function respondServiceUnavailable(res) {
+    res.status(503).json({
+        error: 'Download service is disabled',
+        code: 'SERVICE_UNAVAILABLE',
+    });
+}
+function resolveDownloadPayload(params, cacheEntry) {
+    const payload = parseCachedPayload(cacheEntry.content);
+    if (!payload)
+        return null;
+    const content = resolveCachedPayloadContent(payload);
+    if (!content)
+        return null;
+    const safeTitle = typeof payload.title === 'string' ? payload.title : undefined;
+    const fileName = generateSafeFilename(cacheEntry.url, cacheEntry.title ?? safeTitle, params.hash, '.md');
+    return {
+        content,
+        contentType: 'text/markdown; charset=utf-8',
+        fileName,
+    };
+}
+function buildContentDisposition(fileName) {
+    const encodedName = encodeURIComponent(fileName).replace(/'/g, '%27');
+    return `attachment; filename="${fileName}"; filename*=UTF-8''${encodedName}`;
+}
+function sendDownloadPayload(res, payload) {
+    const disposition = buildContentDisposition(payload.fileName);
+    res.setHeader('Content-Type', payload.contentType);
+    res.setHeader('Content-Disposition', disposition);
+    res.setHeader('Cache-Control', `private, max-age=${config.cache.ttl}`);
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.send(payload.content);
+}
+function handleDownload(req, res) {
+    if (!config.cache.enabled) {
+        respondServiceUnavailable(res);
+        return;
+    }
+    const params = parseDownloadParams(req);
+    if (!params) {
+        respondBadRequest(res, 'Invalid namespace or hash format');
+        return;
+    }
+    const cacheKey = buildCacheKeyFromParams(params);
+    const cacheEntry = cache.get(cacheKey);
+    if (!cacheEntry) {
+        logDebug('Download request for missing cache key', { cacheKey });
+        respondNotFound(res);
+        return;
+    }
+    const payload = resolveDownloadPayload(params, cacheEntry);
+    if (!payload) {
+        logDebug('Download payload unavailable', { cacheKey });
+        respondNotFound(res);
+        return;
+    }
+    logDebug('Serving download', { cacheKey, fileName: payload.fileName });
+    sendDownloadPayload(res, payload);
+}
+export function registerDownloadRoutes(app) {
+    app.get('/mcp/downloads/:namespace/:hash', handleDownload);
+}
+function getStatusCode(fetchError) {
+    return fetchError ? fetchError.statusCode : 500;
+}
+function getErrorCode(fetchError) {
+    return fetchError ? fetchError.code : 'INTERNAL_ERROR';
+}
+function getFetchErrorMessage(fetchError) {
+    return fetchError ? fetchError.message : 'Internal Server Error';
+}
+function getErrorDetails(fetchError) {
+    if (fetchError && Object.keys(fetchError.details).length > 0) {
+        return fetchError.details;
+    }
+    return undefined;
+}
+function setRetryAfterHeader(res, fetchError) {
+    const retryAfter = resolveRetryAfter(fetchError);
+    if (retryAfter === undefined)
+        return;
+    res.set('Retry-After', retryAfter);
+}
+function buildErrorResponse(fetchError) {
+    const details = getErrorDetails(fetchError);
+    const response = {
+        error: {
+            message: getFetchErrorMessage(fetchError),
+            code: getErrorCode(fetchError),
+            statusCode: getStatusCode(fetchError),
+            ...(details && { details }),
+        },
+    };
+    // Never expose stack traces in production
+    return response;
+}
+function resolveRetryAfter(fetchError) {
+    if (fetchError?.statusCode !== 429)
+        return undefined;
+    const { retryAfter } = fetchError.details;
+    return isRetryAfterValue(retryAfter) ? String(retryAfter) : undefined;
+}
+function isRetryAfterValue(value) {
+    return typeof value === 'number' || typeof value === 'string';
+}
+export function errorHandler(err, req, res, next) {
+    if (res.headersSent) {
+        next(err);
+        return;
+    }
+    const fetchError = err instanceof FetchError ? err : null;
+    const statusCode = getStatusCode(fetchError);
+    logError(`HTTP ${statusCode}: ${err.message} - ${req.method} ${req.path}`, err);
+    setRetryAfterHeader(res, fetchError);
+    res.status(statusCode).json(buildErrorResponse(fetchError));
+}
+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);
+    }
+}
+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();
+}
+function registerSignalHandlers(shutdown) {
+    process.on('SIGINT', () => {
+        void shutdown('SIGINT');
+    });
+    process.on('SIGTERM', () => {
+        void shutdown('SIGTERM');
+    });
+}
 function startListening(app) {
     return app
         .listen(config.server.port, config.server.host, () => {
@@ -68,7 +560,12 @@ async function buildServerContext() {
 async function createAppWithMiddleware() {
     const { app, jsonParser } = await createExpressApp();
     const { rateLimitMiddleware, stopRateLimitCleanup, authMiddleware, corsMiddleware, } = buildMiddleware();
-    attachBaseMiddleware(app, jsonParser, rateLimitMiddleware, corsMiddleware);
+    attachBaseMiddleware({
+        app,
+        jsonParser,
+        rateLimitMiddleware,
+        corsMiddleware,
+    });
     attachAuthMetadata(app);
     assertHttpConfiguration();
     return { app, authMiddleware, stopRateLimitCleanup };

package/dist/http/session-cleanup.js

@@ -1,6 +1,6 @@
 import { setInterval as setIntervalPromise } from 'node:timers/promises';
 import { logInfo, logWarn } from '../services/logger.js';
-import { evictExpiredSessions } from './mcp-session.js';
+import { evictExpiredSessions } from './mcp-session-eviction.js';
 export function startSessionCleanupLoop(store, sessionTtlMs) {
     const controller = new AbortController();
     void runSessionCleanupLoop(store, sessionTtlMs, controller.signal).catch(handleSessionCleanupError);
@@ -8,11 +8,11 @@ export function startSessionCleanupLoop(store, sessionTtlMs) {
 }
 async function runSessionCleanupLoop(store, sessionTtlMs, signal) {
     const intervalMs = getCleanupIntervalMs(sessionTtlMs);
-    for await (const _ of setIntervalPromise(intervalMs, undefined, {
+    for await (const getNow of setIntervalPromise(intervalMs, Date.now, {
         signal,
         ref: false,
     })) {
-        handleSessionEvictions(store);
+        handleSessionEvictions(store, getNow());
     }
 }
 function getCleanupIntervalMs(sessionTtlMs) {
@@ -21,10 +21,13 @@ function getCleanupIntervalMs(sessionTtlMs) {
 function isAbortError(error) {
     return error instanceof Error && error.name === 'AbortError';
 }
-function handleSessionEvictions(store) {
+function handleSessionEvictions(store, now) {
     const evicted = evictExpiredSessions(store);
     if (evicted > 0) {
-        logInfo('Expired sessions evicted', { evicted });
+        logInfo('Expired sessions evicted', {
+            evicted,
+            timestamp: new Date(now).toISOString(),
+        });
     }
 }
 function handleSessionCleanupError(error) {

package/dist/middleware/error-handler.d.ts

@@ -1,2 +1,2 @@
 import type { NextFunction, Request, Response } from 'express';
-export declare function errorHandler(err: Error, req: Request, res: Response, _next: NextFunction): void;
+export declare function errorHandler(err: Error, req: Request, res: Response, next: NextFunction): void;

package/dist/middleware/error-handler.js

@@ -1,55 +1,56 @@
 import { FetchError } from '../errors/app-error.js';
 import { logError } from '../services/logger.js';
-function getStatusCode(err) {
-    return err instanceof FetchError ? err.statusCode : 500;
+function getStatusCode(fetchError) {
+    return fetchError ? fetchError.statusCode : 500;
 }
-function getErrorCode(err) {
-    return err instanceof FetchError ? err.code : 'INTERNAL_ERROR';
+function getErrorCode(fetchError) {
+    return fetchError ? fetchError.code : 'INTERNAL_ERROR';
 }
-function getErrorMessage(err) {
-    return err instanceof FetchError ? err.message : 'Internal Server Error';
+function getErrorMessage(fetchError) {
+    return fetchError ? fetchError.message : 'Internal Server Error';
 }
-function getErrorDetails(err) {
-    if (err instanceof FetchError && Object.keys(err.details).length > 0) {
-        return err.details;
+function getErrorDetails(fetchError) {
+    if (fetchError && Object.keys(fetchError.details).length > 0) {
+        return fetchError.details;
     }
     return undefined;
 }
-function setRetryAfterHeader(res, err) {
-    const retryAfter = resolveRetryAfter(err);
-    if (!retryAfter)
+function setRetryAfterHeader(res, fetchError) {
+    const retryAfter = resolveRetryAfter(fetchError);
+    if (retryAfter === undefined)
         return;
     res.set('Retry-After', retryAfter);
 }
-function buildErrorResponse(err) {
-    const details = getErrorDetails(err);
+function buildErrorResponse(fetchError) {
+    const details = getErrorDetails(fetchError);
     const response = {
         error: {
-            message: getErrorMessage(err),
-            code: getErrorCode(err),
-            statusCode: getStatusCode(err),
+            message: getErrorMessage(fetchError),
+            code: getErrorCode(fetchError),
+            statusCode: getStatusCode(fetchError),
             ...(details && { details }),
         },
     };
     // Never expose stack traces in production
     return response;
 }
-function resolveRetryAfter(err) {
-    if (!(err instanceof FetchError))
-        return null;
-    if (err.statusCode !== 429)
-        return null;
-    const { retryAfter } = err.details;
-    if (!isRetryAfterValue(retryAfter))
-        return null;
-    return String(retryAfter);
+function resolveRetryAfter(fetchError) {
+    if (fetchError?.statusCode !== 429)
+        return undefined;
+    const { retryAfter } = fetchError.details;
+    return isRetryAfterValue(retryAfter) ? String(retryAfter) : undefined;
 }
 function isRetryAfterValue(value) {
     return typeof value === 'number' || typeof value === 'string';
 }
-export function errorHandler(err, req, res, _next) {
-    const statusCode = getStatusCode(err);
+export function errorHandler(err, req, res, next) {
+    if (res.headersSent) {
+        next(err);
+        return;
+    }
+    const fetchError = err instanceof FetchError ? err : null;
+    const statusCode = getStatusCode(fetchError);
     logError(`HTTP ${statusCode}: ${err.message} - ${req.method} ${req.path}`, err);
-    setRetryAfterHeader(res, err);
-    res.status(statusCode).json(buildErrorResponse(err));
+    setRetryAfterHeader(res, fetchError);
+    res.status(statusCode).json(buildErrorResponse(fetchError));
 }

package/dist/resources/cached-content-params.d.ts

@@ -0,0 +1,5 @@
+export declare const CACHE_NAMESPACE = "markdown";
+export declare function resolveCacheParams(params: unknown): {
+    namespace: string;
+    urlHash: string;
+};