@j0hanz/superfetch 1.2.5 → 2.0.1

package/dist/http/auth.js

@@ -1,38 +1,269 @@
+import { InvalidTokenError, ServerError, } from '@modelcontextprotocol/sdk/server/auth/errors.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 { timingSafeEqualUtf8 } from '../utils/crypto.js';
-function normalizeHeaderValue(header) {
-    return Array.isArray(header) ? header[0] : header;
+import { isRecord } from '../utils/guards.js';
+const STATIC_TOKEN_TTL_SECONDS = 60 * 60 * 24;
+function stripHash(url) {
+    const copy = new URL(url.href);
+    copy.hash = '';
+    return copy.href;
+}
+function parseScopes(value) {
+    if (typeof value === 'string') {
+        return value
+            .split(' ')
+            .map((scope) => scope.trim())
+            .filter((scope) => scope.length > 0);
+    }
+    if (Array.isArray(value)) {
+        return value.filter((scope) => typeof scope === 'string');
+    }
+    return [];
 }
-function timingSafeEquals(a, b) {
-    return timingSafeEqualUtf8(a, b);
+function parseResourceUrl(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (!URL.canParse(value))
+        return undefined;
+    return new URL(value);
 }
-function isAuthorizedRequest(req, authToken) {
-    if (!authToken)
-        return false;
-    const bearerToken = getBearerToken(req);
-    if (bearerToken) {
-        return timingSafeEquals(bearerToken, authToken);
+function parseAudResource(aud) {
+    if (typeof aud === 'string') {
+        return parseResourceUrl(aud);
+    }
+    if (Array.isArray(aud)) {
+        for (const entry of aud) {
+            const parsed = parseResourceUrl(entry);
+            if (parsed)
+                return parsed;
+        }
     }
-    const apiKeyHeader = getApiKeyHeader(req);
-    return apiKeyHeader ? timingSafeEquals(apiKeyHeader, authToken) : false;
+    return undefined;
 }
-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 extractResource(data) {
+    const resource = parseResourceUrl(data.resource);
+    if (resource)
+        return resource;
+    return parseAudResource(data.aud);
+}
+function extractScopes(data) {
+    if (data.scope !== undefined) {
+        return parseScopes(data.scope);
+    }
+    if (data.scopes !== undefined) {
+        return parseScopes(data.scopes);
+    }
+    if (data.scp !== undefined) {
+        return parseScopes(data.scp);
+    }
+    return [];
+}
+function readExpiresAt(data) {
+    const expiresAt = typeof data.exp === 'number' ? data.exp : Number.NaN;
+    if (!Number.isFinite(expiresAt)) {
+        throw new InvalidTokenError('Token has no expiration time');
+    }
+    return expiresAt;
+}
+function resolveClientId(data) {
+    if (typeof data.client_id === 'string')
+        return data.client_id;
+    if (typeof data.cid === 'string')
+        return data.cid;
+    if (typeof data.sub === 'string')
+        return data.sub;
+    return 'unknown';
+}
+function ensureResourceMatch(resource) {
+    if (resource && stripHash(resource) !== stripHash(config.auth.resourceUrl)) {
+        throw new InvalidTokenError('Token resource mismatch');
+    }
+    return resource;
+}
+function buildIntrospectionAuthInfo(token, data) {
+    const resource = ensureResourceMatch(extractResource(data));
+    return {
+        token,
+        clientId: resolveClientId(data),
+        scopes: extractScopes(data),
+        expiresAt: readExpiresAt(data),
+        resource: resource ?? config.auth.resourceUrl,
+        extra: data,
+    };
+}
+function buildBasicAuthHeader(clientId, clientSecret) {
+    const secret = clientSecret ?? '';
+    const basic = Buffer.from(`${clientId}:${secret}`, 'utf8').toString('base64');
+    return `Basic ${basic}`;
+}
+function buildIntrospectionRequest(token, resourceUrl, clientId, clientSecret) {
+    const body = new URLSearchParams({
+        token,
+        token_type_hint: 'access_token',
+        resource: stripHash(resourceUrl),
+    }).toString();
+    const headers = {
+        'content-type': 'application/x-www-form-urlencoded',
+    };
+    if (clientId) {
+        headers.authorization = buildBasicAuthHeader(clientId, clientSecret);
+    }
+    return { body, headers };
+}
+async function requestIntrospection(introspectionUrl, request, timeoutMs) {
+    const response = await fetch(introspectionUrl, {
+        method: 'POST',
+        headers: request.headers,
+        body: request.body,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new ServerError(`Token introspection failed: ${response.status}`);
+    }
+    return response.json();
+}
+function parseIntrospectionPayload(payload) {
+    if (!isRecord(payload) || Array.isArray(payload)) {
+        throw new ServerError('Invalid introspection response');
+    }
+    if (payload.active !== true) {
+        throw new InvalidTokenError('Token is inactive');
+    }
+    return payload;
+}
+async function verifyWithIntrospection(token) {
+    const { auth } = config;
+    if (!auth.introspectionUrl) {
+        throw new ServerError('Token introspection is not configured');
+    }
+    const request = buildIntrospectionRequest(token, auth.resourceUrl, auth.clientId, auth.clientSecret);
+    const payload = await requestIntrospection(auth.introspectionUrl, request, auth.introspectionTimeoutMs);
+    return buildIntrospectionAuthInfo(token, parseIntrospectionPayload(payload));
+}
+function buildStaticAuthInfo(token) {
+    return {
+        token,
+        clientId: 'static-token',
+        scopes: config.auth.requiredScopes,
+        expiresAt: Math.floor(Date.now() / 1000) + STATIC_TOKEN_TTL_SECONDS,
+        resource: config.auth.resourceUrl,
+    };
+}
+function verifyStaticToken(token) {
+    if (config.auth.staticTokens.length === 0) {
+        throw new InvalidTokenError('No static tokens configured');
+    }
+    const matched = config.auth.staticTokens.some((candidate) => timingSafeEqualUtf8(candidate, token));
+    if (!matched) {
+        throw new InvalidTokenError('Invalid token');
+    }
+    return buildStaticAuthInfo(token);
+}
+function normalizeHeaderValue(header) {
+    return Array.isArray(header) ? header[0] : header;
 }
 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/host-allowlist.d.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from 'express';
+export declare function createHostValidationMiddleware(): RequestHandler;
+export declare function createOriginValidationMiddleware(): RequestHandler;

package/dist/http/host-allowlist.js

@@ -0,0 +1,117 @@
+import { config } from '../config/index.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 = 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;
+}
+export 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();
+    };
+}
+export 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();
+    };
+}

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,9 @@
-import type { Express } from 'express';
-import { type McpSessionOptions } from './mcp-session.js';
+import type { Express, Request, Response } from 'express';
+import type { McpRequestBody } from '../config/types/runtime.js';
+import { type McpSessionOptions } from './mcp-sessions.js';
+export declare function isJsonRpcBatchRequest(body: unknown): boolean;
+export declare function isMcpRequestBody(body: unknown): body is McpRequestBody;
+export declare function ensureMcpProtocolVersionHeader(req: Request, res: Response): boolean;
+export declare function ensurePostAcceptHeader(req: Request): void;
+export declare function acceptsEventStream(req: Request): boolean;
 export declare function registerMcpRoutes(app: Express, options: McpSessionOptions): void;
-export { evictExpiredSessions } from './mcp-session.js';