@j0hanz/superfetch 1.2.5 → 2.0.0

package/dist/http/auth.js

@@ -1,38 +1,110 @@
-import { timingSafeEqualUtf8 } from '../utils/crypto.js';
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import { getOAuthProtectedResourceMetadataUrl, mcpAuthMetadataRouter, } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { config } from '../config/index.js';
+import { verifyWithIntrospection } from './auth-introspection.js';
+import { verifyStaticToken } from './auth-static.js';
 function normalizeHeaderValue(header) {
     return Array.isArray(header) ? header[0] : header;
 }
-function timingSafeEquals(a, b) {
-    return timingSafeEqualUtf8(a, b);
-}
-function isAuthorizedRequest(req, authToken) {
-    if (!authToken)
-        return false;
-    const bearerToken = getBearerToken(req);
-    if (bearerToken) {
-        return timingSafeEquals(bearerToken, authToken);
-    }
-    const apiKeyHeader = getApiKeyHeader(req);
-    return apiKeyHeader ? timingSafeEquals(apiKeyHeader, authToken) : false;
-}
-function getBearerToken(req) {
-    const authHeader = normalizeHeaderValue(req.headers.authorization);
-    if (!authHeader?.startsWith('Bearer '))
-        return null;
-    const token = authHeader.slice('Bearer '.length).trim();
-    return token.length > 0 ? token : null;
-}
 function getApiKeyHeader(req) {
     const apiKeyHeader = normalizeHeaderValue(req.headers['x-api-key']);
     return apiKeyHeader ? apiKeyHeader.trim() : null;
 }
-export function createAuthMiddleware(authToken) {
-    return (req, res, next) => {
-        if (isAuthorizedRequest(req, authToken)) {
+function createLegacyApiKeyMiddleware() {
+    return (req, _res, next) => {
+        if (config.auth.mode !== 'static') {
             next();
             return;
         }
-        res.set('WWW-Authenticate', 'Bearer realm="mcp", error="invalid_token", error_description="Missing or invalid credentials"');
-        res.status(401).json({ error: 'Unauthorized' });
+        if (!req.headers.authorization) {
+            const apiKey = getApiKeyHeader(req);
+            if (apiKey) {
+                req.headers.authorization = `Bearer ${apiKey}`;
+            }
+        }
+        next();
     };
 }
+async function verifyAccessToken(token) {
+    if (config.auth.mode === 'oauth') {
+        return verifyWithIntrospection(token);
+    }
+    return verifyStaticToken(token);
+}
+function resolveMetadataUrl() {
+    if (config.auth.mode !== 'oauth')
+        return null;
+    return getOAuthProtectedResourceMetadataUrl(new URL(config.auth.resourceUrl));
+}
+function resolveOptionalScopes(requiredScopes) {
+    return requiredScopes.length > 0 ? [...requiredScopes] : undefined;
+}
+function resolveOAuthMetadataParams(authConfig) {
+    const { issuerUrl, authorizationUrl, tokenUrl, revocationUrl, registrationUrl, requiredScopes, } = authConfig;
+    if (!issuerUrl || !authorizationUrl || !tokenUrl)
+        return null;
+    return {
+        issuerUrl,
+        authorizationUrl,
+        tokenUrl,
+        revocationUrl,
+        registrationUrl,
+        requiredScopes,
+    };
+}
+function buildBaseOAuthMetadata(params) {
+    return {
+        issuer: params.issuerUrl.href,
+        authorization_endpoint: params.authorizationUrl.href,
+        response_types_supported: ['code'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint: params.tokenUrl.href,
+        token_endpoint_auth_methods_supported: ['client_secret_post', 'none'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+    };
+}
+function applyOptionalScopes(metadata, requiredScopes) {
+    const scopesSupported = resolveOptionalScopes(requiredScopes);
+    if (scopesSupported !== undefined) {
+        metadata.scopes_supported = scopesSupported;
+    }
+}
+function applyOptionalEndpoint(metadata, key, url) {
+    if (!url)
+        return;
+    metadata[key] = url.href;
+}
+function buildOAuthMetadata(params) {
+    const oauthMetadata = buildBaseOAuthMetadata(params);
+    applyOptionalScopes(oauthMetadata, params.requiredScopes);
+    applyOptionalEndpoint(oauthMetadata, 'revocation_endpoint', params.revocationUrl);
+    applyOptionalEndpoint(oauthMetadata, 'registration_endpoint', params.registrationUrl);
+    return oauthMetadata;
+}
+export function createAuthMiddleware() {
+    const metadataUrl = resolveMetadataUrl();
+    const authHandler = requireBearerAuth({
+        verifier: { verifyAccessToken },
+        requiredScopes: config.auth.requiredScopes,
+        ...(metadataUrl ? { resourceMetadataUrl: metadataUrl } : {}),
+    });
+    const legacyHandler = createLegacyApiKeyMiddleware();
+    return (req, res, next) => {
+        legacyHandler(req, res, () => {
+            authHandler(req, res, next);
+        });
+    };
+}
+export function createAuthMetadataRouter() {
+    if (config.auth.mode !== 'oauth')
+        return null;
+    const oauthMetadataParams = resolveOAuthMetadataParams(config.auth);
+    if (!oauthMetadataParams)
+        return null;
+    return mcpAuthMetadataRouter({
+        oauthMetadata: buildOAuthMetadata(oauthMetadataParams),
+        resourceServerUrl: config.auth.resourceUrl,
+        scopesSupported: config.auth.requiredScopes,
+        resourceName: config.server.name,
+    });
+}

package/dist/http/cors.d.ts

@@ -1,7 +1,7 @@
 import type { NextFunction, Request, Response } from 'express';
-interface CorsOptions {
-    readonly allowedOrigins: string[];
-    readonly allowAllOrigins: boolean;
-}
-export declare function createCorsMiddleware(options: CorsOptions): (req: Request, res: Response, next: NextFunction) => void;
-export {};
+/**
+ * Creates a minimal CORS middleware.
+ * MCP clients are not browser-based, so CORS is not needed.
+ * This just handles OPTIONS preflight requests.
+ */
+export declare function createCorsMiddleware(): (req: Request, res: Response, next: NextFunction) => void;

package/dist/http/cors.js

@@ -1,35 +1,11 @@
-function isOriginAllowed(origin, options) {
-    if (!origin)
-        return true;
-    if (options.allowAllOrigins)
-        return true;
-    if (options.allowedOrigins.length === 0)
-        return false;
-    return options.allowedOrigins.includes(origin);
-}
-function isValidOrigin(origin) {
-    return URL.canParse(origin);
-}
-export function createCorsMiddleware(options) {
+/**
+ * Creates a minimal CORS middleware.
+ * MCP clients are not browser-based, so CORS is not needed.
+ * This just handles OPTIONS preflight requests.
+ */
+export function createCorsMiddleware() {
     return (req, res, next) => {
-        const origin = resolveOrigin(req);
-        if (origin) {
-            if (!isValidOrigin(origin)) {
-                res.status(403).json({
-                    error: 'Origin not allowed',
-                    code: 'ORIGIN_NOT_ALLOWED',
-                });
-                return;
-            }
-            if (!isOriginAllowed(origin, options)) {
-                res.status(403).json({
-                    error: 'Origin not allowed',
-                    code: 'ORIGIN_NOT_ALLOWED',
-                });
-                return;
-            }
-            applyCorsHeaders(res, origin);
-        }
+        // Handle OPTIONS preflight
         if (req.method === 'OPTIONS') {
             res.sendStatus(200);
             return;
@@ -37,14 +13,3 @@ export function createCorsMiddleware(options) {
         next();
     };
 }
-function resolveOrigin(req) {
-    return req.headers.origin;
-}
-function applyCorsHeaders(res, origin) {
-    res.vary('Origin');
-    res.header('Access-Control-Allow-Origin', origin);
-    res.header('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-    res.header('Access-Control-Allow-Headers', 'Content-Type, mcp-session-id, Authorization, X-API-Key');
-    res.header('Access-Control-Expose-Headers', 'mcp-session-id');
-    res.header('Access-Control-Max-Age', '86400');
-}

package/dist/http/download-routes.d.ts

@@ -1,14 +1,2 @@
 import type { Express } from 'express';
-import type { CacheEntry } from '../config/types/content.js';
-interface DownloadParams {
-    namespace: string;
-    hash: string;
-}
-interface DownloadPayload {
-    content: string;
-    contentType: string;
-    fileName: string;
-}
-export declare function resolveDownloadPayload(params: DownloadParams, cacheEntry: CacheEntry): DownloadPayload | null;
 export declare function registerDownloadRoutes(app: Express): void;
-export {};

package/dist/http/download-routes.js

@@ -1,11 +1,12 @@
 import { config } from '../config/index.js';
 import * as cache from '../services/cache.js';
 import { logDebug } from '../services/logger.js';
+import { parseCachedPayload, resolveCachedPayloadContent, } from '../utils/cached-payload.js';
 import { generateSafeFilename } from '../utils/filename-generator.js';
-const VALID_NAMESPACES = new Set(['markdown', 'url']);
+import { wrapAsync } from './async-handler.js';
 const HASH_PATTERN = /^[a-f0-9.]+$/i;
 function validateNamespace(namespace) {
-    return VALID_NAMESPACES.has(namespace);
+    return namespace === 'markdown';
 }
 function validateHash(hash) {
     return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
@@ -41,55 +42,18 @@ function respondServiceUnavailable(res) {
         code: 'SERVICE_UNAVAILABLE',
     });
 }
-function resolveContentType(namespace) {
-    return namespace === 'markdown'
-        ? 'text/markdown; charset=utf-8'
-        : 'application/x-ndjson; charset=utf-8';
-}
-function resolveExtension(namespace) {
-    return namespace === 'markdown' ? '.md' : '.jsonl';
-}
-function parseCachedPayload(raw) {
-    try {
-        const parsed = JSON.parse(raw);
-        return isCachedPayload(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-function isCachedPayload(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const record = value;
-    return ((record.content === undefined || typeof record.content === 'string') &&
-        (record.markdown === undefined || typeof record.markdown === 'string') &&
-        (record.title === undefined || typeof record.title === 'string'));
-}
-function resolvePayloadContent(payload, namespace) {
-    if (namespace === 'markdown') {
-        if (typeof payload.markdown === 'string') {
-            return payload.markdown;
-        }
-        if (typeof payload.content === 'string') {
-            return payload.content;
-        }
-        return null;
-    }
-    return typeof payload.content === 'string' ? payload.content : null;
-}
-export function resolveDownloadPayload(params, cacheEntry) {
+function resolveDownloadPayload(params, cacheEntry) {
     const payload = parseCachedPayload(cacheEntry.content);
     if (!payload)
         return null;
-    const content = resolvePayloadContent(payload, params.namespace);
+    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, resolveExtension(params.namespace));
+    const fileName = generateSafeFilename(cacheEntry.url, cacheEntry.title ?? safeTitle, params.hash, '.md');
     return {
         content,
-        contentType: resolveContentType(params.namespace),
+        contentType: 'text/markdown; charset=utf-8',
         fileName,
     };
 }
@@ -97,41 +61,40 @@ 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 Promise.resolve();
+        return;
     }
     const params = parseDownloadParams(req);
     if (!params) {
         respondBadRequest(res, 'Invalid namespace or hash format');
-        return Promise.resolve();
+        return;
     }
     const cacheKey = buildCacheKeyFromParams(params);
     const cacheEntry = cache.get(cacheKey);
     if (!cacheEntry) {
         logDebug('Download request for missing cache key', { cacheKey });
         respondNotFound(res);
-        return Promise.resolve();
+        return;
     }
     const payload = resolveDownloadPayload(params, cacheEntry);
     if (!payload) {
         logDebug('Download payload unavailable', { cacheKey });
         respondNotFound(res);
-        return Promise.resolve();
+        return;
     }
-    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');
     logDebug('Serving download', { cacheKey, fileName: payload.fileName });
-    res.send(payload.content);
-    return Promise.resolve();
+    sendDownloadPayload(res, payload);
 }
 export function registerDownloadRoutes(app) {
-    const asyncHandler = (fn) => (req, res, next) => {
-        Promise.resolve(fn(req, res)).catch(next);
-    };
-    app.get('/mcp/downloads/:namespace/:hash', asyncHandler(handleDownload));
+    app.get('/mcp/downloads/:namespace/:hash', wrapAsync(handleDownload));
 }

package/dist/http/jsonrpc-http.d.ts

@@ -0,0 +1,2 @@
+import type { Response } from 'express';
+export declare function sendJsonRpcError(res: Response, code: number, message: string, status?: number): void;

package/dist/http/jsonrpc-http.js

@@ -0,0 +1,10 @@
+export function sendJsonRpcError(res, code, message, status = 400) {
+    res.status(status).json({
+        jsonrpc: '2.0',
+        error: {
+            code,
+            message,
+        },
+        id: null,
+    });
+}

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

@@ -1,4 +1,3 @@
 import type { Express } from 'express';
 import { type McpSessionOptions } from './mcp-session.js';
 export declare function registerMcpRoutes(app: Express, options: McpSessionOptions): void;
-export { evictExpiredSessions } from './mcp-session.js';

package/dist/http/mcp-routes.js

@@ -1,31 +1,35 @@
 import { logError, logInfo } from '../services/logger.js';
+import { acceptsEventStream, ensurePostAcceptHeader } from './accept-policy.js';
+import { wrapAsync } from './async-handler.js';
+import { sendJsonRpcError } from './jsonrpc-http.js';
 import { resolveTransportForPost, } from './mcp-session.js';
-import { isMcpRequestBody } from './mcp-validation.js';
+import { isJsonRpcBatchRequest, isMcpRequestBody } from './mcp-validation.js';
+import { ensureMcpProtocolVersionHeader } from './protocol-policy.js';
 import { getSessionId } from './sessions.js';
-function sendJsonRpcError(res, code, message, status = 400) {
-    res.status(status).json({
-        jsonrpc: '2.0',
-        error: {
-            code,
-            message,
-        },
-        id: null,
-    });
-}
 function respondInvalidRequestBody(res) {
     sendJsonRpcError(res, -32600, 'Invalid Request: Malformed request body', 400);
 }
 function respondMissingSession(res) {
-    res.status(400).json({ error: 'Missing mcp-session-id header' });
+    sendJsonRpcError(res, -32600, 'Missing mcp-session-id header', 400);
 }
 function respondSessionNotFound(res) {
-    res.status(404).json({ error: 'Session not found' });
+    sendJsonRpcError(res, -32600, 'Session not found', 404);
+}
+function validatePostPayload(payload, res) {
+    if (isJsonRpcBatchRequest(payload)) {
+        sendJsonRpcError(res, -32600, 'Batch requests are not supported', 400);
+        return null;
+    }
+    if (!isMcpRequestBody(payload)) {
+        respondInvalidRequestBody(res);
+        return null;
+    }
+    return payload;
 }
 function logPostRequest(body, sessionId, options) {
     logInfo('[MCP POST]', {
         method: body.method,
         id: body.id,
-        sessionId: sessionId ?? 'none',
         isInitialize: body.method === 'initialize',
         sessionCount: options.sessionStore.size(),
     });
@@ -50,49 +54,58 @@ function dispatchTransportRequest(transport, req, res, body) {
         : transport.handleRequest(req, res);
 }
 function resolveSessionTransport(sessionId, options, res) {
+    const { sessionStore } = options;
     if (!sessionId) {
         respondMissingSession(res);
         return null;
     }
-    const session = options.sessionStore.get(sessionId);
+    const session = sessionStore.get(sessionId);
     if (!session) {
         respondSessionNotFound(res);
         return null;
     }
-    options.sessionStore.touch(sessionId);
+    sessionStore.touch(sessionId);
     return session.transport;
 }
 async function handlePost(req, res, options) {
+    ensurePostAcceptHeader(req);
+    if (!ensureMcpProtocolVersionHeader(req, res))
+        return;
     const sessionId = getSessionId(req);
-    const { body } = req;
-    if (!isMcpRequestBody(body)) {
-        respondInvalidRequestBody(res);
+    const payload = validatePostPayload(req.body, res);
+    if (!payload)
         return;
-    }
-    logPostRequest(body, sessionId, options);
-    const transport = await resolveTransportForPost(req, res, body, sessionId, options);
+    logPostRequest(payload, sessionId, options);
+    const transport = await resolveTransportForPost(req, res, payload, sessionId, options);
     if (!transport)
         return;
-    await handleTransportRequest(transport, req, res, body);
+    await handleTransportRequest(transport, req, res, payload);
 }
 async function handleGet(req, res, options) {
+    if (!ensureMcpProtocolVersionHeader(req, res))
+        return;
+    if (!acceptsEventStream(req)) {
+        res.status(406).json({
+            error: 'Not Acceptable',
+            code: 'ACCEPT_NOT_SUPPORTED',
+        });
+        return;
+    }
     const transport = resolveSessionTransport(getSessionId(req), options, res);
     if (!transport)
         return;
     await handleTransportRequest(transport, req, res);
 }
 async function handleDelete(req, res, options) {
+    if (!ensureMcpProtocolVersionHeader(req, res))
+        return;
     const transport = resolveSessionTransport(getSessionId(req), options, res);
     if (!transport)
         return;
     await handleTransportRequest(transport, req, res);
 }
 export function registerMcpRoutes(app, options) {
-    const asyncHandler = (fn) => (req, res, next) => {
-        Promise.resolve(fn(req, res)).catch(next);
-    };
-    app.post('/mcp', asyncHandler((req, res) => handlePost(req, res, options)));
-    app.get('/mcp', asyncHandler((req, res) => handleGet(req, res, options)));
-    app.delete('/mcp', asyncHandler((req, res) => handleDelete(req, res, options)));
+    app.post('/mcp', wrapAsync((req, res) => handlePost(req, res, options)));
+    app.get('/mcp', wrapAsync((req, res) => handleGet(req, res, options)));
+    app.delete('/mcp', wrapAsync((req, res) => handleDelete(req, res, options)));
 }
-export { evictExpiredSessions } from './mcp-session.js';

package/dist/http/mcp-session-helpers.d.ts

@@ -6,7 +6,6 @@ export interface SlotTracker {
     readonly isInitialized: () => boolean;
 }
 export declare function reserveSessionSlot(store: SessionStore, maxSessions: number): boolean;
-export declare function releaseSessionSlot(): void;
 export declare function createSlotTracker(): SlotTracker;
 export declare function ensureSessionCapacity(store: SessionStore, maxSessions: number, res: Response, evictOldest: (store: SessionStore) => boolean): boolean;
 export declare function respondServerBusy(res: Response): void;

package/dist/http/mcp-session-helpers.js

@@ -6,7 +6,7 @@ export function reserveSessionSlot(store, maxSessions) {
     inFlightSessions += 1;
     return true;
 }
-export function releaseSessionSlot() {
+function releaseSessionSlot() {
     if (inFlightSessions > 0) {
         inFlightSessions -= 1;
     }

package/dist/http/mcp-session-transport.d.ts

@@ -0,0 +1,7 @@
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+export declare function createTimeoutController(): {
+    clear: () => void;
+    set: (timeout: NodeJS.Timeout | null) => void;
+};
+export declare function createTransportAdapter(transport: StreamableHTTPServerTransport): Transport;

package/dist/http/mcp-session-transport.js

@@ -0,0 +1,57 @@
+export function createTimeoutController() {
+    let initTimeout = null;
+    return {
+        clear: () => {
+            if (!initTimeout)
+                return;
+            clearTimeout(initTimeout);
+            initTimeout = null;
+        },
+        set: (timeout) => {
+            initTimeout = timeout;
+        },
+    };
+}
+export function createTransportAdapter(transport) {
+    const adapter = buildTransportAdapter(transport);
+    attachTransportAccessors(adapter, transport);
+    return adapter;
+}
+function buildTransportAdapter(transport) {
+    return {
+        start: () => transport.start(),
+        send: (message, options) => transport.send(message, options),
+        close: () => transport.close(),
+    };
+}
+function createAccessorDescriptor(getter, setter) {
+    return {
+        get: getter,
+        ...(setter ? { set: setter } : {}),
+        enumerable: true,
+        configurable: true,
+    };
+}
+function createOnCloseDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onclose, (handler) => {
+        transport.onclose = handler;
+    });
+}
+function createOnErrorDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onerror, (handler) => {
+        transport.onerror = handler;
+    });
+}
+function createOnMessageDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onmessage, (handler) => {
+        transport.onmessage = handler;
+    });
+}
+function attachTransportAccessors(adapter, transport) {
+    Object.defineProperties(adapter, {
+        onclose: createOnCloseDescriptor(transport),
+        onerror: createOnErrorDescriptor(transport),
+        onmessage: createOnMessageDescriptor(transport),
+        sessionId: createAccessorDescriptor(() => transport.sessionId),
+    });
+}