mcp4openapi 0.2.8 → 0.3.1

package/dist/src/transport/http-transport.d.ts

@@ -0,0 +1,329 @@
+/**
+ * HTTP Streamable Transport for MCP
+ *
+ * Implements MCP Specification 2025-03-26
+ * https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+ *
+ * Why: Enables remote MCP server access with SSE streaming, session management,
+ * and resumability for reliable communication over HTTP.
+ */
+import type { Logger } from '../core/logger.js';
+import type { HttpTransportConfig, HttpProfileContext } from '../types/http-transport.js';
+import { MetricsCollector } from '../core/metrics.js';
+import type { SessionToolFilter, SessionToolFilterRequest } from '../types/http-transport.js';
+import type { ListedProfileDetails } from '../profile/profile-resolver.js';
+export declare class HttpTransport {
+    private app;
+    private server;
+    private config;
+    private logger;
+    private metrics;
+    private cleanupInterval;
+    private messageHandler;
+    private profileContextProvider;
+    private profileStates;
+    private oauthRedirectHostCache;
+    private warnedMissingOAuthRedirectEnvVars;
+    private profileHintsByClient;
+    private static readonly PROFILE_HINT_TTL_MS;
+    private profileIndexProvider;
+    constructor(config: HttpTransportConfig, logger: Logger);
+    getMetricsCollector(): MetricsCollector | null;
+    setProfileIndexProvider(provider: (() => Promise<ListedProfileDetails[]>) | null): void;
+    /**
+     * Setup Express middleware
+     *
+     * Why: Security (Origin validation, rate limiting), JSON parsing, session extraction, metrics
+     */
+    private setupMiddleware;
+    setProfileContextProvider(provider: (profileId: string) => Promise<HttpProfileContext | null>): void;
+    private getDefaultProfileId;
+    private buildDefaultProfileContext;
+    private getProfileState;
+    private getProfileIdForRequest;
+    private getProfileStateForRequest;
+    private hasWarnedAboutBinding;
+    /**
+     * Check if origin is allowed
+     *
+     * Why: Prevent DNS rebinding attacks
+     *
+     * Supports:
+     * - Exact hostname: 'example.com', 'api.example.com'
+     * - Wildcard subdomain: '*.example.com'
+     * - IPv4 CIDR: '192.168.1.0/24', '10.0.0.0/8'
+     * - IPv4 exact: '192.168.1.100'
+     */
+    private isAllowedOrigin;
+    private getOAuthRedirectHostPatterns;
+    private extractRedirectHostPatterns;
+    private resolveRedirectUriFromEnv;
+    private resolveProfileIdFromPath;
+    private getClientHintKey;
+    private storeProfileHint;
+    private resolveProfileIdFromHint;
+    private resolveProfileIdForOriginCheck;
+    private primeOAuthRedirectHosts;
+    private isAllowedOriginForRequest;
+    /**
+     * Match hostname against allowed origin pattern
+     *
+     * Supports:
+     * - Exact match: 'example.com' === 'example.com'
+     * - Wildcard: '*.example.com' matches 'api.example.com', 'web.example.com'
+     * - CIDR: '192.168.1.0/24' matches '192.168.1.1' through '192.168.1.254'
+     */
+    private matchOrigin;
+    /**
+     * Check if IP address is within CIDR range (IPv4 or IPv6)
+     *
+     * Example: '192.168.1.50' matches '192.168.1.0/24'
+     *          '2001:db8::1' matches '2001:db8::/32'
+     */
+    private matchCIDR;
+    /**
+     * Convert IPv4 address to 32-bit integer
+     *
+     * Example: '192.168.1.1' -> 3232235777
+     */
+    private ipv4ToInt;
+    /**
+     * Convert IPv6 address to 128-bit BigInt
+     */
+    private ipv6ToBigInt;
+    private ipv6Mask;
+    private stripIpv6Brackets;
+    /**
+     * Create configured rate limiter or a passthrough handler when disabled
+     *
+     * Why: Both MCP and metrics endpoints share the same rate limiting setup logic.
+     * Centralizing it keeps behaviour consistent and avoids drifting configuration.
+     */
+    private createRateLimiter;
+    private formatRateLimitMessage;
+    private getProfilePrefix;
+    private buildProfilePath;
+    private getServerOrigin;
+    private buildProfileUrl;
+    private normalizeResourcePath;
+    private resolveProfileInfoFromResourceUrl;
+    private resolveProfileIdFromResourceUrl;
+    getOAuthProtectedResourceUrl(profileId?: string): string;
+    private respondProfileNotFound;
+    /**
+     * Setup MCP endpoint routes
+     *
+     * Why: Single endpoint for POST (client→server) and GET (SSE stream)
+     */
+    private setupRoutes;
+    private getProfileIssuerUrl;
+    private getRequestOrigin;
+    private handleProfileIndex;
+    private handleOAuthProtectedResource;
+    private handleOAuthAuthorize;
+    private handleOAuthToken;
+    private handleOAuthCallback;
+    private handleOAuthAuthorizationServerMetadata;
+    private handleOAuthRegister;
+    /**
+     * Handle metrics endpoint
+     *
+     * Why: Prometheus scraping endpoint
+     */
+    private handleMetrics;
+    /**
+     * Validate authentication token by making a probe request to the API
+     *
+     * Supports all auth types: bearer, query, custom-header
+     * Returns true if token is valid, false otherwise
+     */
+    /**
+     * Builds a URL by intelligently combining base URL and endpoint
+     * Handles absolute URLs, absolute paths, and relative paths correctly
+     */
+    private buildUrl;
+    private validateAuthToken;
+    /**
+     * Validate token format and length
+     *
+     * Why centralized: Single source of truth for token validation rules
+     *
+     * Relaxed validation: Allow common API token characters including colons,
+     * to support various token formats (GitLab glpat-, YouTrack perm:, etc.)
+     */
+    private validateToken;
+    /**
+     * Extract and validate auth token from request headers
+     *
+     * Supports:
+     * - Authorization: Bearer <token>
+     * - X-API-Token: <token>
+     * - OAuth session (via mcp-session-id header)
+     *
+     * Why strict validation: Prevents header injection attacks
+     *
+     * Returns: { type: 'bearer' | 'oauth' | 'api-token', token: string, sessionId?: string }
+     */
+    private extractAuthToken;
+    /**
+     * Lazy initialization of ToolFilterService
+     */
+    private getToolFilterService;
+    /**
+     * Handle POST requests - Client sending messages to server
+     *
+     * MCP Spec: POST can contain requests, notifications, or responses
+     */
+    private handlePost;
+    /**
+     * Handle GET requests - Client opening SSE stream for server messages
+     *
+     * MCP Spec: GET opens SSE stream for server-initiated requests/notifications
+     */
+    private handleGet;
+    /**
+     * Handle DELETE requests - Client terminating session
+     *
+     * MCP Spec: DELETE explicitly terminates session
+     */
+    private handleDelete;
+    /**
+     * Start SSE response for a POST request
+     *
+     * Why: Returns response via SSE stream, allows server-initiated messages
+     */
+    private startSSEResponse;
+    /**
+     * Start SSE stream for GET request
+     *
+     * Why: Allows server to send requests/notifications to client
+     */
+    private startSSEStream;
+    /**
+     * Replay messages after Last-Event-ID
+     *
+     * Why: Resumability - client can reconnect and receive missed messages
+     */
+    private replayMessages;
+    /**
+     * Send message to client via SSE
+     *
+     * Why: Server-initiated requests/notifications
+     */
+    sendToClient(profileId: string, sessionId: string, message: unknown): void;
+    /**
+     * Determine message type (request, notification, response)
+     */
+    private getMessageType;
+    private getFilteringHeaderValue;
+    private getToolFilterHeaderValue;
+    /**
+     * Create new session
+     *
+     * Why: Stateful sessions for MCP protocol
+     */
+    private createSession;
+    /**
+     * Update session activity timestamp
+     */
+    private updateSessionActivity;
+    /**
+     * Destroy session and cleanup resources
+     *
+     * Why: Free memory, close streams
+     */
+    private destroySession;
+    /**
+     * Session destruction listeners for cleanup in other components
+     */
+    private sessionDestroyedListeners;
+    /**
+     * Register listener for session destruction events
+     *
+     * Why: Allows MCPServer to cleanup per-session HTTP clients
+     */
+    onSessionDestroyed(listener: (profileId: string, sessionId: string) => void): void;
+    /**
+     * Notify all listeners about session destruction
+     */
+    private notifySessionDestroyed;
+    /**
+     * Store OAuth tokens in internal map for later session initialization
+     *
+     * Why: Bridge between /oauth/token endpoint (where we see OAuthTokens)
+     * and session initialization (where we only see access token in Authorization header)
+     */
+    private storeOAuthTokens;
+    /**
+     * Cleanup expired sessions
+     *
+     * Why: Prevent memory leaks, enforce session timeout
+     *
+     * OAuth sessions with refresh tokens have extended or unlimited timeout
+     * to avoid forcing users to re-authenticate after periods of inactivity
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Get auth token from session
+     *
+     * Why public: Allows MCPServer to securely access session tokens without breaking encapsulation
+     */
+    getSessionToken(profileId: string, sessionId: string): string | undefined;
+    getSessionFiltering(profileId: string, sessionId: string): Record<string, string[]> | undefined;
+    getSessionFilteringHeader(profileId: string, sessionId: string): string | undefined;
+    getSessionToolFilterRequest(profileId: string, sessionId: string): SessionToolFilterRequest | undefined;
+    getSessionToolFilter(profileId: string, sessionId: string): SessionToolFilter | undefined;
+    getSessionToolFilterHeader(profileId: string, sessionId: string): string | undefined;
+    setSessionToolFilter(profileId: string, sessionId: string, toolFilter: SessionToolFilter): void;
+    recordGlobalToolFilterMetrics(summary: {
+        originalCount: number;
+        allowedCount: number;
+        removedCount: number;
+        patternCounts: Record<string, number>;
+    }): void;
+    recordSessionToolFilterMetrics(sessionId: string, allowedCount: number, request: SessionToolFilterRequest): void;
+    recordToolFilterRejection(tool: string, source: 'env' | 'session'): void;
+    /**
+     * Ensure session has a valid access token, refreshing if necessary
+     *
+     * Why: Transparently refresh expired OAuth tokens before making API calls
+     * Returns true if token is valid (or was successfully refreshed), false otherwise
+     */
+    ensureValidSessionToken(profileId: string, sessionId: string): Promise<boolean>;
+    /**
+     * Refresh access token using refresh token
+     *
+     * Why: Automatically renew expired OAuth access tokens without user intervention
+     * Returns true on success, false on failure
+     */
+    private refreshAccessToken;
+    /**
+     * Set message handler for processing incoming JSON-RPC messages
+     */
+    setMessageHandler(handler: (message: unknown, sessionId?: string, profileId?: string) => Promise<unknown>): void;
+    /**
+     * Check if OAuth provider is configured
+     */
+    hasOAuthProvider(profileId?: string): boolean;
+    /**
+     * Get server URL
+     */
+    getServerUrl(profileId?: string): string;
+    /**
+     * Get OAuth authorization URL
+     */
+    getOAuthAuthorizationUrl(profileId?: string): string;
+    /**
+     * Get OAuth scopes
+     */
+    getOAuthScopes(profileId?: string): string[];
+    /**
+     * Start HTTP server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop HTTP server
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=http-transport.d.ts.map

package/dist/src/transport/http-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-transport.d.ts","sourceRoot":"","sources":["../../../src/transport/http-transport.ts"],"names":[],"mappings":"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"}