mcp4openapi 0.1.0 → 0.2.0

package/dist/src/http-transport.js

@@ -8,10 +8,15 @@
  * and resumability for reliable communication over HTTP.
  */
 import express from 'express';
+import https from 'https';
+import fs from 'fs';
 import crypto from 'crypto';
 import rateLimit from 'express-rate-limit';
 import { isInitializeRequest } from './jsonrpc-validator.js';
 import { MetricsCollector } from './metrics.js';
+import { ExternalOAuthProvider } from './oauth-provider.js';
+import { HTTP_STATUS, MIME_TYPES, OAUTH_PATHS, TIMEOUTS, OAUTH_RATE_LIMIT } from './constants.js';
+import { escapeHtmlSafe } from './validation-utils.js';
 // Default maximum token length (1000 characters)
 const DEFAULT_MAX_TOKEN_LENGTH = 1000;
 export class HttpTransport {
@@ -23,6 +28,10 @@ export class HttpTransport {
     metrics = null;
     cleanupInterval = null;
     messageHandler = null;
+    oauthProvider = null;
+    // Map access_token -> { refreshToken, expiresAt, clientId, scopes }
+    // Used to bridge /oauth/token endpoint (where we see OAuthTokens) and session initialization (where we only see access token)
+    oauthTokensByAccessToken = new Map();
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
@@ -33,6 +42,20 @@ export class HttpTransport {
                 prefix: 'mcp_',
             });
         }
+        // Initialize OAuth provider if configured
+        if (config.oauthConfig) {
+            this.logger.info('Initializing OAuth provider with config', { hasClientId: !!config.oauthConfig.client_id });
+            this.oauthProvider = new ExternalOAuthProvider(config.oauthConfig, logger);
+            // Note: authorizationEndpoint may be undefined at this point if config uses issuer-based discovery
+            // It will be resolved lazily on first OAuth operation (authorize/token)
+            this.logger.info('OAuth provider initialized', {
+                endpoint: this.oauthProvider.authorizationEndpoint || '(to be derived from issuer)',
+                hasIssuer: !!config.oauthConfig.issuer,
+            });
+        }
+        else {
+            this.logger.info('No OAuth config provided - OAuth provider not initialized');
+        }
         this.app = express();
         this.setupMiddleware();
         this.setupRoutes();
@@ -43,11 +66,62 @@ export class HttpTransport {
      * Why: Security (Origin validation, rate limiting), JSON parsing, session extraction, metrics
      */
     setupMiddleware() {
+        // Request logging (before any middleware)
+        this.app.use((req, res, next) => {
+            this.logger.debug('Request received', {
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                userAgent: req.get('user-agent'),
+                ip: req.ip,
+            });
+            next();
+        });
         // JSON body parser
         this.app.use(express.json());
         // Metrics: Track request start time
         this.app.use((req, res, next) => {
             req.startTime = Date.now();
+            // Log response
+            const originalSend = res.send;
+            const originalJson = res.json;
+            const logger = this.logger;
+            res.send = function (body) {
+                logger.debug('Outgoing response', {
+                    method: req.method,
+                    url: req.url,
+                    status: res.statusCode,
+                    contentType: res.get('content-type'),
+                    bodyLength: body ? body.length : 0,
+                    bodyPreview: typeof body === 'string' ? body.substring(0, 200) : '[object]'
+                });
+                return originalSend.call(this, body);
+            };
+            res.json = function (body) {
+                logger.debug('Outgoing JSON response', {
+                    method: req.method,
+                    url: req.url,
+                    status: res.statusCode,
+                    body
+                });
+                return originalJson.call(this, body);
+            };
+            next();
+        });
+        // Debug: Log all requests
+        this.app.use((req, res, next) => {
+            this.logger.debug('Incoming request', {
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                headers: {
+                    'user-agent': req.headers['user-agent'],
+                    'accept': req.headers.accept,
+                    'content-type': req.headers['content-type'],
+                    'authorization': req.headers.authorization ? '[REDACTED]' : undefined
+                },
+                ip: req.ip
+            });
             next();
         });
         // Security: Origin validation (DNS rebinding protection)
@@ -65,7 +139,7 @@ export class HttpTransport {
             // Validate Origin header for non-localhost
             if (origin && !this.isAllowedOrigin(origin)) {
                 this.logger.warn('Rejected request from disallowed origin', { origin, ip: req.ip });
-                return res.status(403).json({
+                return res.status(HTTP_STATUS.FORBIDDEN).json({
                     error: 'Forbidden',
                     message: 'Origin not allowed'
                 });
@@ -105,6 +179,18 @@ export class HttpTransport {
             if (hostname === this.config.host) {
                 return true;
             }
+            // Allow OAuth redirect URI host if configured
+            if (this.oauthProvider?.redirectUri) {
+                try {
+                    const redirectUrl = new URL(this.oauthProvider.redirectUri);
+                    if (hostname === redirectUrl.hostname) {
+                        return true;
+                    }
+                }
+                catch {
+                    // Invalid URL, ignore
+                }
+            }
             // Check custom allowed origins
             if (this.config.allowedOrigins && this.config.allowedOrigins.length > 0) {
                 for (const allowed of this.config.allowedOrigins) {
@@ -187,6 +273,39 @@ export class HttpTransport {
         }
         return result >>> 0; // Unsigned
     }
+    /**
+     * 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.
+     */
+    createRateLimiter(options) {
+        if (!options.enabled) {
+            return (_req, _res, next) => next();
+        }
+        const message = options.responseMessage ??
+            `Rate limit exceeded. Max ${options.maxRequests} requests per ${options.windowMs / 1000} seconds.`;
+        return rateLimit({
+            windowMs: options.windowMs,
+            max: options.maxRequests,
+            standardHeaders: true, // Return rate limit info in `RateLimit-*` headers
+            legacyHeaders: false, // Disable deprecated `X-RateLimit-*` headers
+            handler: (req, res) => {
+                this.logger.warn(options.logMessage, {
+                    ip: req.ip,
+                    path: req.path,
+                    method: req.method,
+                });
+                res.status(HTTP_STATUS.TOO_MANY_REQUESTS).json({
+                    error: 'Too Many Requests',
+                    message,
+                });
+            },
+        });
+    }
+    formatRateLimitMessage(scope, maxRequests, windowMs) {
+        return `Rate limit exceeded for ${scope}. Max ${maxRequests} requests per ${windowMs / 1000} seconds.`;
+    }
     /**
      * Setup MCP endpoint routes
      *
@@ -194,9 +313,308 @@ export class HttpTransport {
      */
     setupRoutes() {
         this.logger.info('Setting up HTTP routes');
-        // Security: Rate limiting setup
+        // Security: Rate limiting setup (needed for OAuth routes)
         const rateLimitEnabled = this.config.rateLimitEnabled !== false; // default: true
-        const windowMs = this.config.rateLimitWindowMs || 60000; // 1 minute
+        // Rate limiter for OAuth endpoints (stricter limits for security)
+        // OAuth endpoints are sensitive and should have lower limits than general API
+        // Configuration priority: profile > env vars > defaults
+        const oauthWindowMs = this.config.rateLimitOAuthWindowMs || OAUTH_RATE_LIMIT.WINDOW_MS;
+        const oauthMaxRequests = this.config.rateLimitOAuthMax || OAUTH_RATE_LIMIT.MAX_REQUESTS;
+        const oauthRateLimiter = this.createRateLimiter({
+            enabled: rateLimitEnabled,
+            windowMs: oauthWindowMs,
+            maxRequests: oauthMaxRequests,
+            logMessage: 'Rate limit exceeded for OAuth',
+            responseMessage: `Too many OAuth requests. Limit: ${oauthMaxRequests} requests per ${Math.round(oauthWindowMs / 60000)} minutes. Please try again later.`,
+        });
+        // OAuth 2.0 routes (if configured)
+        if (this.oauthProvider) {
+            // Build redirect URI
+            const redirectUri = this.oauthProvider.redirectUri ||
+                `http://${this.config.host}:${this.config.port}/oauth/callback`;
+            // Derive serverUrl from redirectUri
+            const baseUrl = new URL(redirectUri).origin;
+            const serverUrl = new URL(`${baseUrl}/mcp`);
+            // issuerUrl should be the base URL of the authorization server (e.g. https://gitlab.com),
+            // NOT the authorization endpoint (e.g. https://gitlab.com/oauth/authorize)
+            // We try to derive it from authorizationEndpoint if not explicitly configured
+            // Note: authorizationEndpoint might not be ready yet (async initialization),
+            // so we use serverUrl.origin as fallback
+            let issuerUrl;
+            try {
+                const authEndpoint = this.oauthProvider.authorizationEndpoint;
+                if (authEndpoint) {
+                    // Try to extract base URL from auth endpoint
+                    const authUrl = new URL(authEndpoint);
+                    issuerUrl = new URL(authUrl.origin);
+                }
+                else {
+                    // Fallback: use server origin (will be updated after async init)
+                    issuerUrl = new URL(serverUrl.origin);
+                }
+            }
+            catch (e) {
+                // Fallback: use server origin
+                issuerUrl = new URL(serverUrl.origin);
+            }
+            this.logger.info('Setting up OAuth routes', {
+                serverUrl: serverUrl.toString(),
+                issuerUrl: issuerUrl.toString(),
+                redirectUri,
+            });
+            // Install MCP OAuth router
+            // This adds standard OAuth endpoints:
+            // - /.well-known/oauth-authorization-server
+            // - /.well-known/oauth-protected-resource
+            // - /oauth/authorize
+            // - /oauth/token
+            // - /oauth/register (dynamic client registration)
+            // - /oauth/revoke (token revocation)
+            // Only register resource server endpoints, not authorization server endpoints
+            // since our MCP server is not an OAuth authorization server
+            this.app.get(OAUTH_PATHS.WELL_KNOWN_PROTECTED_RESOURCE, oauthRateLimiter, (req, res) => {
+                // Build metadata object with only defined fields (RFC 8707)
+                const metadata = {
+                    resource: serverUrl.href,
+                    authorization_servers: [serverUrl.origin], // We are the authorization server (proxy)
+                    bearer_methods_supported: ['header'],
+                };
+                // Optional: scopes_supported (only if scopes are defined)
+                if (this.oauthProvider?.scopes && this.oauthProvider.scopes.length > 0) {
+                    metadata.scopes_supported = this.oauthProvider.scopes;
+                }
+                // Optional: resource_name (from config, already has fallback in mcp-server.ts)
+                if (this.config.resourceName) {
+                    metadata.resource_name = this.config.resourceName;
+                }
+                // Optional: resource_documentation (from config, may be undefined)
+                if (this.config.resourceDocumentation) {
+                    metadata.resource_documentation = this.config.resourceDocumentation;
+                }
+                res.json(metadata);
+            });
+            // Authorization endpoint
+            // Initiates the OAuth flow by redirecting the user to the external provider
+            this.app.get(OAUTH_PATHS.AUTHORIZE, oauthRateLimiter, async (req, res) => {
+                try {
+                    const { response_type, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method } = req.query;
+                    if (!client_id || typeof client_id !== 'string') {
+                        res.status(HTTP_STATUS.BAD_REQUEST).send('Missing client_id');
+                        return;
+                    }
+                    if (!redirect_uri || typeof redirect_uri !== 'string') {
+                        res.status(HTTP_STATUS.BAD_REQUEST).send('Missing redirect_uri');
+                        return;
+                    }
+                    if (this.oauthProvider) {
+                        // Ensure provider is initialized before client validation
+                        // This registers configured client_id if present
+                        await this.oauthProvider.ensureEndpointsInitialized();
+                        // Find the client to validate configuration
+                        const client = await this.oauthProvider.clientsStore.getClient(client_id);
+                        if (!client) {
+                            res.status(HTTP_STATUS.BAD_REQUEST).send('Invalid client_id');
+                            return;
+                        }
+                        // Prepare parameters for provider authorization
+                        const scopeStr = (scope || '').trim();
+                        const params = {
+                            responseType: response_type || 'code',
+                            clientId: client_id,
+                            redirectUri: redirect_uri,
+                            scope: scopeStr ? scopeStr.split(' ') : [],
+                            state: state,
+                            codeChallenge: code_challenge,
+                            codeChallengeMethod: code_challenge_method,
+                            scopes: scopeStr ? scopeStr.split(' ') : [],
+                        };
+                        // Call provider authorize method which handles the redirect logic
+                        await this.oauthProvider.authorize(client, params, res);
+                    }
+                    else {
+                        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).send('OAuth provider not initialized');
+                    }
+                }
+                catch (error) {
+                    this.logger.error('OAuth authorize error', error instanceof Error ? error : new Error(String(error)));
+                    res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).send('OAuth authorization failed');
+                }
+            });
+            // Token endpoint
+            // Exchanges authorization code or refresh token for access token
+            this.app.post(OAUTH_PATHS.TOKEN, oauthRateLimiter, express.urlencoded({ extended: false }), async (req, res) => {
+                try {
+                    const { grant_type, code, redirect_uri, client_id, code_verifier, refresh_token } = req.body;
+                    this.logger.debug('OAuth token request', {
+                        grant_type,
+                        client_id,
+                        has_code: !!code,
+                        has_code_verifier: !!code_verifier,
+                        redirect_uri,
+                    });
+                    if (grant_type === 'authorization_code') {
+                        // Authorization Code Flow
+                        if (!code) {
+                            res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'invalid_request', error_description: 'Missing code' });
+                            return;
+                        }
+                        if (this.oauthProvider) {
+                            // Ensure provider is initialized before client validation
+                            await this.oauthProvider.ensureEndpointsInitialized();
+                            const client = await this.oauthProvider.clientsStore.getClient(client_id);
+                            if (!client) {
+                                res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'invalid_client' });
+                                return;
+                            }
+                            const tokens = await this.oauthProvider.exchangeAuthorizationCode(client, code, code_verifier, redirect_uri);
+                            // Store OAuth tokens for later session initialization
+                            this.storeOAuthTokens(tokens, client.client_id, client.scope?.split(' ') || []);
+                            res.json(tokens);
+                        }
+                        else {
+                            res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ error: 'server_error', error_description: 'OAuth provider not initialized' });
+                        }
+                    }
+                    else if (grant_type === 'refresh_token') {
+                        // Refresh Token Flow
+                        if (!refresh_token) {
+                            res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'invalid_request', error_description: 'Missing refresh_token' });
+                            return;
+                        }
+                        if (this.oauthProvider) {
+                            // Ensure provider is initialized before client validation
+                            await this.oauthProvider.ensureEndpointsInitialized();
+                            const client = await this.oauthProvider.clientsStore.getClient(client_id);
+                            if (!client) {
+                                res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'invalid_client' });
+                                return;
+                            }
+                            const tokens = await this.oauthProvider.exchangeRefreshToken(client, refresh_token);
+                            // Store OAuth tokens for later session initialization
+                            // Note: When refreshing, the old access token should be invalidated
+                            // but we don't track it here - the new token replaces it in the map
+                            this.storeOAuthTokens(tokens, client.client_id, client.scope?.split(' ') || []);
+                            res.json(tokens);
+                        }
+                        else {
+                            res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ error: 'server_error', error_description: 'OAuth provider not initialized' });
+                        }
+                    }
+                    else {
+                        this.logger.warn('Unsupported grant type', { grant_type, expected: 'authorization_code or refresh_token' });
+                        res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'unsupported_grant_type' });
+                        return;
+                    }
+                }
+                catch (error) {
+                    this.logger.error('OAuth token exchange error', error instanceof Error ? error : new Error(String(error)));
+                    res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'invalid_grant', error_description: String(error) });
+                }
+            });
+            // OAuth callback endpoint to receive tokens from authorization server
+            this.app.get(OAUTH_PATHS.CALLBACK, oauthRateLimiter, async (req, res) => {
+                try {
+                    const { code, state, error, error_description } = req.query;
+                    this.logger.info('OAuth callback received', {
+                        hasCode: !!code,
+                        hasState: !!state,
+                        error: error,
+                        errorDescription: error_description
+                    });
+                    if (error) {
+                        // Sanitize error messages to prevent XSS
+                        const safeError = escapeHtmlSafe(error);
+                        const safeErrorDesc = escapeHtmlSafe(error_description);
+                        res.status(HTTP_STATUS.BAD_REQUEST).json({
+                            error: safeError,
+                            error_description: safeErrorDesc || safeError
+                        });
+                        return;
+                    }
+                    if (!code || typeof code !== 'string') {
+                        res.status(HTTP_STATUS.BAD_REQUEST).send('Missing authorization code');
+                        return;
+                    }
+                    // Delegate to OAuth provider to handle token exchange and redirect back to client (Cursor)
+                    if (this.oauthProvider) {
+                        await this.oauthProvider.handleCallback(req, res);
+                    }
+                    else {
+                        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).send('OAuth provider not initialized');
+                    }
+                }
+                catch (error) {
+                    this.logger.error('OAuth callback error', error instanceof Error ? error : new Error(String(error)));
+                    if (!res.headersSent) {
+                        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).send('OAuth callback failed');
+                    }
+                }
+            });
+            // Provide authorization server metadata
+            // We advertise the MCP server itself as the authorization server (Proxy Mode)
+            // This allows us to handle the redirect dance between Cursor -> MCP -> GitLab -> MCP -> Cursor
+            this.app.get(OAUTH_PATHS.WELL_KNOWN_AUTHORIZATION_SERVER, async (req, res) => {
+                try {
+                    res.json({
+                        issuer: serverUrl.origin, // We are the issuer for the client
+                        authorization_endpoint: new URL(OAUTH_PATHS.AUTHORIZE, serverUrl.origin).href,
+                        token_endpoint: new URL(OAUTH_PATHS.TOKEN, serverUrl.origin).href,
+                        registration_endpoint: new URL(OAUTH_PATHS.REGISTER, serverUrl.origin).href,
+                        response_types_supported: ['code'],
+                        code_challenge_methods_supported: ['S256'],
+                        grant_types_supported: ['authorization_code', 'refresh_token'],
+                        scopes_supported: this.oauthProvider?.scopes || ['api'],
+                    });
+                }
+                catch (error) {
+                    this.logger.error('OAuth authorization server metadata error', error instanceof Error ? error : new Error(String(error)));
+                    res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).send('OAuth metadata failed');
+                }
+            });
+            // Dynamic Client Registration endpoint
+            // Cursor requires this to register itself with a redirect URI
+            this.app.post(OAUTH_PATHS.REGISTER, express.json(), async (req, res) => {
+                try {
+                    const { redirect_uris } = req.body;
+                    this.logger.info('Dynamic client registration request', { redirect_uris });
+                    // We don't actually strictly enforce registration in this proxy mode,
+                    // but we return a valid client configuration to satisfy the client.
+                    // We use a static client ID for the internal mapping.
+                    const clientId = 'mcp-proxy-client';
+                    const clientSecret = 'mcp-proxy-secret';
+                    // Register this client in our internal store so authorize requests pass validation
+                    if (this.oauthProvider) {
+                        const client = {
+                            client_id: clientId,
+                            client_secret: clientSecret,
+                            redirect_uris: redirect_uris || [],
+                            grant_types: ['authorization_code', 'refresh_token'],
+                            response_types: ['code'],
+                            scope: (this.oauthProvider.scopes || []).join(' '),
+                        };
+                        // We need to cast to any because registerClient might not be exposed on the interface
+                        // but we know ExternalOAuthProvider uses InMemoryClientsStore
+                        await this.oauthProvider.clientsStore.registerClient(client);
+                    }
+                    res.status(HTTP_STATUS.CREATED).json({
+                        client_id: clientId,
+                        client_secret: clientSecret,
+                        redirect_uris: redirect_uris,
+                        grant_types: ['authorization_code', 'refresh_token'],
+                        response_types: ['code'],
+                        scope: (this.oauthProvider?.scopes || []).join(' '),
+                        token_endpoint_auth_method: 'client_secret_post'
+                    });
+                }
+                catch (error) {
+                    this.logger.error('Client registration failed', error instanceof Error ? error : new Error(String(error)));
+                    res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ error: 'server_error', error_description: 'Registration failed' });
+                }
+            });
+            this.logger.info('OAuth routes registered');
+        }
+        // Security: Rate limiting setup (for MCP endpoints)
+        const windowMs = this.config.rateLimitWindowMs || TIMEOUTS.RATE_LIMIT_WINDOW_MS;
         const maxRequests = this.config.rateLimitMaxRequests || 100; // 100 req/min
         const metricsMaxRequests = this.config.rateLimitMetricsMax || 10; // 10 req/min for metrics
         if (rateLimitEnabled) {
@@ -207,42 +625,30 @@ export class HttpTransport {
             });
         }
         // Rate limiter for MCP/SSE endpoints (100 req/min by default)
-        const mcpRateLimiter = rateLimitEnabled ? rateLimit({
+        const mcpRateLimiter = this.createRateLimiter({
+            enabled: rateLimitEnabled,
             windowMs,
-            max: maxRequests,
-            standardHeaders: true, // Return rate limit info in `RateLimit-*` headers
-            legacyHeaders: false, // Disable `X-RateLimit-*` headers
-            handler: (req, res) => {
-                this.logger.warn('Rate limit exceeded', {
-                    ip: req.ip,
-                    path: req.path,
-                    method: req.method,
-                });
-                res.status(429).json({
-                    error: 'Too Many Requests',
-                    message: `Rate limit exceeded. Max ${maxRequests} requests per ${windowMs / 1000} seconds.`,
-                });
-            },
-        }) : (req, res, next) => next();
+            maxRequests,
+            logMessage: 'Rate limit exceeded',
+        });
         // Rate limiter for metrics endpoint (10 req/min by default)
-        const metricsRateLimiter = rateLimitEnabled ? rateLimit({
+        const metricsRateLimiter = this.createRateLimiter({
+            enabled: rateLimitEnabled,
             windowMs,
-            max: metricsMaxRequests,
-            standardHeaders: true,
-            legacyHeaders: false,
-            handler: (req, res) => {
-                this.logger.warn('Rate limit exceeded for metrics', {
-                    ip: req.ip,
-                    path: req.path,
-                });
-                res.status(429).json({
-                    error: 'Too Many Requests',
-                    message: `Rate limit exceeded for metrics. Max ${metricsMaxRequests} requests per ${windowMs / 1000} seconds.`,
-                });
-            },
-        }) : (req, res, next) => next();
+            maxRequests: metricsMaxRequests,
+            logMessage: 'Rate limit exceeded for metrics',
+            responseMessage: this.formatRateLimitMessage('metrics', metricsMaxRequests, windowMs),
+        });
         // Main MCP endpoint - POST for sending messages
         this.app.post('/mcp', mcpRateLimiter, this.handlePost.bind(this));
+        // Add OPTIONS handler for CORS preflight requests
+        this.app.options('/mcp', (req, res) => {
+            res.setHeader('Access-Control-Allow-Origin', req.headers.origin || '*');
+            res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Accept, Mcp-Session-Id');
+            res.setHeader('Access-Control-Max-Age', '86400'); // 24 hours
+            res.status(HTTP_STATUS.OK).send();
+        });
         this.logger.info('Registered POST /mcp route');
         // Main MCP endpoint - GET for SSE streaming
         this.app.get('/mcp', mcpRateLimiter, this.handleGet.bind(this));
@@ -281,10 +687,20 @@ export class HttpTransport {
         });
         // Debug: SSE route registered
         this.logger.info('SSE routes registered successfully');
-        // Default 404 handler
+        // Default 404 handler - MUST be last route registered
+        // This will catch all unmatched requests
         this.app.use((req, res) => {
-            console.log('=== Default 404 handler called for:', req.method, req.path);
-            res.status(404).send('<!DOCTYPE html>\n<html>\n<head><title>Error</title></head>\n<body><pre>Cannot ${req.method} ${req.path}</pre></body>\n</html>');
+            this.logger.warn('Unhandled request (404)', {
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                headers: req.headers,
+                ip: req.ip
+            });
+            res.status(HTTP_STATUS.NOT_FOUND).json({
+                error: 'Not Found',
+                message: `Endpoint ${req.method} ${req.path} not found`
+            });
         });
     }
     /**
@@ -296,7 +712,7 @@ export class HttpTransport {
         const startTime = Date.now();
         try {
             if (!this.metrics) {
-                res.status(404).json({ error: 'Not Found', message: 'Metrics disabled' });
+                res.status(HTTP_STATUS.NOT_FOUND).json({ error: 'Not Found', message: 'Metrics disabled' });
                 return;
             }
             const metrics = await this.metrics.getMetrics();
@@ -306,7 +722,86 @@ export class HttpTransport {
         }
         catch (error) {
             this.logger.error('Metrics endpoint error', error);
-            res.status(500).json({ error: 'Internal Server Error', message: error.message });
+            res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ error: 'Internal Server Error', message: error.message });
+        }
+    }
+    /**
+     * 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
+     */
+    buildUrl(endpoint, baseUrl) {
+        // If endpoint is already an absolute URL, use it as-is
+        if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+            return new URL(endpoint);
+        }
+        // If endpoint is an absolute path (starts with /), combine with origin of baseUrl
+        if (endpoint.startsWith('/')) {
+            const baseUrlObj = new URL(baseUrl);
+            return new URL(endpoint, baseUrlObj.origin);
+        }
+        // Otherwise, treat as relative path and append to baseUrl
+        // Ensure baseUrl ends with '/' for proper URL construction
+        const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/';
+        return new URL(endpoint, normalizedBaseUrl);
+    }
+    async validateAuthToken(authConfig, token, baseUrl) {
+        if (!authConfig.validation_endpoint) {
+            return true; // Skip validation if not configured
+        }
+        const url = this.buildUrl(authConfig.validation_endpoint, baseUrl);
+        const headers = {};
+        const method = authConfig.validation_method || 'GET';
+        const timeout = authConfig.validation_timeout_ms || 5000;
+        const urlString = url.toString();
+        // Apply auth based on type
+        switch (authConfig.type) {
+            case 'oauth':
+            case 'bearer':
+                headers['Authorization'] = `Bearer ${token}`;
+                break;
+            case 'custom-header':
+                if (authConfig.header_name) {
+                    headers[authConfig.header_name] = token;
+                }
+                break;
+            case 'query':
+                if (authConfig.query_param) {
+                    url.searchParams.set(authConfig.query_param, token);
+                }
+                break;
+        }
+        try {
+            this.logger.debug('Validating auth token', {
+                endpoint: urlString,
+                method,
+                authType: authConfig.type,
+            });
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const response = await fetch(url.toString(), {
+                method,
+                headers,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            const isValid = response.status >= 200 && response.status < 300;
+            this.logger.debug('Auth token validation result', {
+                status: response.status,
+                isValid,
+            });
+            return isValid;
+        }
+        catch (error) {
+            this.logger.warn(`Auth token validation failed: ${error.message}`, {
+                endpoint: authConfig.validation_endpoint,
+            });
+            return false;
         }
     }
     /**
@@ -338,10 +833,22 @@ export class HttpTransport {
      * 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 }
      */
     extractAuthToken(req) {
+        // 1. Check for OAuth session first (highest priority for authenticated sessions)
+        const sessionId = req.sessionId || req.headers['mcp-session-id'];
+        if (sessionId && this.sessions.has(sessionId)) {
+            const session = this.sessions.get(sessionId);
+            if (session && session.authToken) {
+                return { type: 'oauth', token: session.authToken, sessionId };
+            }
+        }
+        // 2. Check Authorization: Bearer header
         const authHeader = req.headers.authorization;
         if (authHeader) {
             // Relaxed Bearer token format validation - allow flexible whitespace
@@ -353,17 +860,18 @@ export class HttpTransport {
             }
             const token = match[1].trim();
             this.validateToken(token, 'Authorization token');
-            return token;
+            return { type: 'bearer', token };
         }
+        // 3. Check X-API-Token header (for custom implementations)
         const apiTokenHeader = req.headers['x-api-token'];
         if (apiTokenHeader) {
             if (typeof apiTokenHeader !== 'string') {
                 throw new Error('X-API-Token must be a string');
             }
             this.validateToken(apiTokenHeader, 'X-API-Token');
-            return apiTokenHeader;
+            return { type: 'api-token', token: apiTokenHeader };
         }
-        return undefined;
+        return { type: 'none' };
     }
     /**
      * Handle POST requests - Client sending messages to server
@@ -373,68 +881,171 @@ export class HttpTransport {
     async handlePost(req, res) {
         const startTime = Date.now();
         try {
+            this.logger.debug('handlePost called', { method: req.method, path: req.path, sessionId: req.sessionId, accept: req.headers.accept });
             const sessionId = req.sessionId;
             const body = req.body;
-            // Validate Accept header
+            // Validate Accept header per MCP Streamable HTTP specification
             const accept = req.headers.accept || '';
-            if (!accept.includes('application/json') && !accept.includes('text/event-stream')) {
-                res.status(406).json({ error: 'Not Acceptable', message: 'Must accept application/json or text/event-stream' });
+            // POST requests can return either JSON or SSE, so must accept both if specified
+            // GET requests return SSE, so must accept text/event-stream
+            const acceptsJson = accept.includes(MIME_TYPES.JSON) || accept === '*/*' || accept === '';
+            const acceptsEventStream = accept.includes(MIME_TYPES.EVENT_STREAM) || accept === '*/*' || accept === '';
+            if (req.method === 'GET' && accept && !acceptsEventStream) {
+                this.logger.debug('Accept header validation failed for GET, returning 406');
+                res.status(HTTP_STATUS.NOT_ACCEPTABLE).json({
+                    error: 'Not Acceptable',
+                    message: `GET requests must accept ${MIME_TYPES.EVENT_STREAM}`
+                });
+                return;
+            }
+            // For POST, be more flexible - allow if client accepts either JSON or SSE
+            if (req.method === 'POST' && accept && !acceptsJson && !acceptsEventStream) {
+                this.logger.debug('Accept header validation failed for POST, returning 406');
+                res.status(HTTP_STATUS.NOT_ACCEPTABLE).json({
+                    error: 'Not Acceptable',
+                    message: `POST requests must accept ${MIME_TYPES.JSON} or ${MIME_TYPES.EVENT_STREAM}`
+                });
                 return;
             }
             // Check if this is initialization (no session ID yet)
             const isInitialization = isInitializeRequest(body);
+            this.logger.debug('Session validation', { isInitialization, sessionId, bodyMethod: body?.method });
             // Validate session (except for initialization)
             if (!isInitialization && sessionId) {
                 const session = this.sessions.get(sessionId);
                 if (!session) {
-                    res.status(404).json({ error: 'Not Found', message: 'Session not found or expired' });
+                    res.status(HTTP_STATUS.NOT_FOUND).json({ error: 'Not Found', message: 'Session not found or expired' });
                     return;
                 }
                 this.updateSessionActivity(sessionId);
             }
             else if (!isInitialization && !sessionId) {
-                res.status(400).json({ error: 'Bad Request', message: 'Mcp-Session-Id header required (except for initialization)' });
+                this.logger.debug('Session validation failed: non-init request without sessionId');
+                res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'Bad Request', message: 'Mcp-Session-Id header required (except for initialization)' });
                 return;
             }
             // Determine message type
             const messageType = this.getMessageType(body);
+            this.logger.debug('Message type determined', { messageType, hasMessageHandler: !!this.messageHandler });
             // If only notifications/responses, return 202 Accepted
             if (messageType === 'notification-only' || messageType === 'response-only') {
                 if (this.messageHandler) {
                     await this.messageHandler(body);
                 }
-                res.status(202).send();
+                res.status(HTTP_STATUS.ACCEPTED).send();
                 return;
             }
             // If contains requests, process and return response
             if (messageType === 'request') {
                 if (!this.messageHandler) {
-                    res.status(500).json({ error: 'Internal Server Error', message: 'Message handler not configured' });
+                    res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ error: 'Internal Server Error', message: 'Message handler not configured' });
                     return;
                 }
                 // Create session on initialization
                 let newSessionId;
                 if (isInitialization) {
                     // Extract and validate auth token from headers
-                    const authToken = this.extractAuthToken(req);
-                    newSessionId = this.createSession(authToken);
+                    const authInfo = this.extractAuthToken(req);
+                    this.logger.debug('Auth token extracted', { authType: authInfo?.type, hasToken: !!authInfo?.token });
+                    // If OAuth is configured, require authentication for initialization
+                    // This ensures clients like Cursor properly handle OAuth flow
+                    if (this.oauthProvider && !authInfo.token) {
+                        this.logger.debug('OAuth configured but no token provided, triggering OAuth flow');
+                        const resourceMetadataUrl = new URL(OAUTH_PATHS.WELL_KNOWN_PROTECTED_RESOURCE, this.getServerUrl()).href;
+                        res.setHeader('WWW-Authenticate', `Bearer resource_metadata="${resourceMetadataUrl}", scope="${this.oauthProvider.scopes.join(' ')}"`);
+                        res.status(HTTP_STATUS.UNAUTHORIZED).json({
+                            error: 'Unauthorized',
+                            message: 'Authentication required for OAuth'
+                        });
+                        return;
+                    }
+                    // Allow initialization without token for non-OAuth scenarios
+                    // Validate token if auth is configured and token is provided
+                    if (authInfo && authInfo.token && this.config.authConfigs && this.config.baseUrl) {
+                        // Find matching auth config based on priority (authConfigs is sorted)
+                        // For 'bearer' token type, 'oauth' config is also a match
+                        const authConfig = this.config.authConfigs.find(c => c.type === authInfo.type ||
+                            (authInfo.type === 'bearer' && c.type === 'oauth'));
+                        if (authConfig && authConfig.validation_endpoint) {
+                            this.logger.info('Validating auth token during initialization', {
+                                authType: authConfig.type, // Use config type for logging
+                                endpoint: authConfig.validation_endpoint,
+                            });
+                            const isValid = await this.validateAuthToken(authConfig, authInfo.token, this.config.baseUrl);
+                            if (!isValid) {
+                                this.logger.warn('Auth token validation failed during initialization', {
+                                    authType: authInfo.type,
+                                });
+                                res.status(HTTP_STATUS.UNAUTHORIZED).json({
+                                    error: 'Unauthorized',
+                                    message: 'Invalid or expired authentication token'
+                                });
+                                return;
+                            }
+                            this.logger.info('Auth token validation successful');
+                        }
+                    }
+                    // Look up OAuth tokens if this is an OAuth token
+                    let refreshToken;
+                    let accessTokenExpiresAt;
+                    let scopes;
+                    let oauthClientId;
+                    if (authInfo.token && (authInfo.type === 'oauth' || authInfo.type === 'bearer')) {
+                        const tokenData = this.oauthTokensByAccessToken.get(authInfo.token);
+                        if (tokenData) {
+                            refreshToken = tokenData.refreshToken;
+                            accessTokenExpiresAt = tokenData.expiresAt;
+                            scopes = tokenData.scopes;
+                            oauthClientId = tokenData.clientId;
+                            this.logger.debug('Found OAuth token data for session', {
+                                hasRefreshToken: !!refreshToken,
+                                hasExpiration: !!accessTokenExpiresAt,
+                                scopesCount: scopes.length,
+                            });
+                        }
+                        else {
+                            this.logger.debug('No OAuth token data found in map (may be non-OAuth bearer token)', {
+                                tokenPrefix: authInfo.token.substring(0, 10),
+                            });
+                        }
+                    }
+                    newSessionId = this.createSession(authInfo.token, refreshToken, accessTokenExpiresAt, scopes, oauthClientId);
                 }
+                this.logger.debug('Calling messageHandler', { body, sessionId: isInitialization ? newSessionId : sessionId });
                 const response = await this.messageHandler(body, isInitialization ? newSessionId : sessionId);
-                // Check if client prefers SSE stream
-                if (accept.includes('text/event-stream')) {
-                    // Return SSE stream
+                this.logger.debug('MessageHandler response', { response });
+                // Debug: Check OAuth conditions
+                this.logger.debug('Checking OAuth conditions', {
+                    responseError: response.error,
+                    hasOAuthProvider: !!this.oauthProvider,
+                    oauthProviderType: typeof this.oauthProvider
+                });
+                // Check if response contains OAuth error and add WWW-Authenticate header
+                const responseObj = response;
+                if (responseObj.error && responseObj.error.data && responseObj.error.data.oauth_required) {
+                    const resourceMetadataUrl = new URL(OAUTH_PATHS.WELL_KNOWN_PROTECTED_RESOURCE, this.getServerUrl()).href;
+                    res.setHeader('WWW-Authenticate', `Bearer resource_metadata="${resourceMetadataUrl}", scope="api"`);
+                    res.status(HTTP_STATUS.UNAUTHORIZED); // Set 401 status for OAuth errors
+                }
+                // Decide response format based on Accept header
+                const accept = req.headers.accept || '';
+                const wantsOnlySSE = accept.trim() === MIME_TYPES.EVENT_STREAM;
+                if (wantsOnlySSE) {
+                    // Return SSE response only when client explicitly wants text/event-stream only
+                    this.logger.debug('Sending SSE response', { response, newSessionId });
                     this.startSSEResponse(res, response, newSessionId, sessionId);
                 }
                 else {
-                    // Return JSON
+                    // Return JSON response (default for requests)
                     if (newSessionId) {
                         res.setHeader('Mcp-Session-Id', newSessionId);
                     }
+                    this.logger.debug('Sending JSON response', { response, newSessionId });
                     res.json(response);
                 }
                 return;
             }
-            res.status(400).json({ error: 'Bad Request', message: 'Invalid message type' });
+            res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'Bad Request', message: 'Invalid message type' });
         }
         catch (error) {
             this.logger.error('POST request error', error);
@@ -466,18 +1077,18 @@ export class HttpTransport {
             const lastEventId = req.headers['last-event-id'];
             // Validate Accept header
             const accept = req.headers.accept || '';
-            if (!accept.includes('text/event-stream')) {
-                res.status(405).json({ error: 'Method Not Allowed', message: 'Must accept text/event-stream' });
+            if (!accept.includes(MIME_TYPES.EVENT_STREAM)) {
+                res.status(HTTP_STATUS.METHOD_NOT_ALLOWED).json({ error: 'Method Not Allowed', message: `Must accept ${MIME_TYPES.EVENT_STREAM}` });
                 return;
             }
             // Validate session
             if (!sessionId) {
-                res.status(400).json({ error: 'Bad Request', message: 'Mcp-Session-Id header required' });
+                res.status(HTTP_STATUS.BAD_REQUEST).json({ error: 'Bad Request', message: 'Mcp-Session-Id header required' });
                 return;
             }
             const session = this.sessions.get(sessionId);
             if (!session) {
-                res.status(404).json({ error: 'Not Found', message: 'Session not found or expired' });
+                res.status(HTTP_STATUS.NOT_FOUND).json({ error: 'Not Found', message: 'Session not found or expired' });
                 return;
             }
             this.updateSessionActivity(sessionId);
@@ -543,7 +1154,7 @@ export class HttpTransport {
      * Why: Returns response via SSE stream, allows server-initiated messages
      */
     startSSEResponse(res, response, newSessionId, sessionId) {
-        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Content-Type', MIME_TYPES.EVENT_STREAM);
         res.setHeader('Cache-Control', 'no-cache');
         res.setHeader('Connection', 'keep-alive');
         if (newSessionId) {
@@ -562,7 +1173,7 @@ export class HttpTransport {
      * Why: Allows server to send requests/notifications to client
      */
     startSSEStream(res, sessionId, lastEventId) {
-        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Content-Type', MIME_TYPES.EVENT_STREAM);
         res.setHeader('Cache-Control', 'no-cache');
         res.setHeader('Connection', 'keep-alive');
         const streamId = crypto.randomBytes(16).toString('hex');
@@ -673,7 +1284,7 @@ export class HttpTransport {
      *
      * Why: Stateful sessions for MCP protocol
      */
-    createSession(authToken) {
+    createSession(authToken, refreshToken, accessTokenExpiresAt, scopes, oauthClientId) {
         // Validate token if provided (defense in depth)
         if (authToken) {
             this.validateToken(authToken, 'Session auth token');
@@ -685,9 +1296,18 @@ export class HttpTransport {
             lastActivityAt: Date.now(),
             sseStreams: new Map(),
             authToken,
+            refreshToken,
+            accessTokenExpiresAt,
+            scopes,
+            oauthClientId,
         };
         this.sessions.set(sessionId, session);
-        this.logger.info('Session created', { sessionId, hasAuthToken: !!authToken });
+        this.logger.info('Session created', {
+            sessionId,
+            hasAuthToken: !!authToken,
+            hasRefreshToken: !!refreshToken,
+            hasExpiration: !!accessTokenExpiresAt,
+        });
         // Record metrics
         if (this.metrics) {
             this.metrics.recordSessionCreated();
@@ -726,6 +1346,10 @@ export class HttpTransport {
                 }
             }
             session.sseStreams.clear();
+            // Clean up OAuth token from map if present
+            if (session.authToken) {
+                this.oauthTokensByAccessToken.delete(session.authToken);
+            }
             this.sessions.delete(sessionId);
             this.logger.info('Session destroyed', { sessionId });
             // Notify session destruction listeners (for cleanup in MCPServer)
@@ -761,18 +1385,62 @@ export class HttpTransport {
             }
         }
     }
+    /**
+     * 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)
+     */
+    storeOAuthTokens(tokens, clientId, scopes) {
+        if (!tokens.access_token) {
+            this.logger.warn('OAuth tokens missing access_token, skipping storage');
+            return;
+        }
+        const expiresAt = tokens.expires_in
+            ? Date.now() + tokens.expires_in * 1000
+            : undefined;
+        this.oauthTokensByAccessToken.set(tokens.access_token, {
+            refreshToken: tokens.refresh_token,
+            expiresAt,
+            clientId,
+            scopes,
+        });
+        this.logger.debug('Stored OAuth tokens', {
+            hasRefreshToken: !!tokens.refresh_token,
+            expiresAt,
+            clientId,
+            scopesCount: scopes.length,
+        });
+    }
     /**
      * 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
      */
     cleanupExpiredSessions() {
         const now = Date.now();
         const expiredSessions = [];
+        // Default OAuth session timeout: 24 hours (or configurable)
+        const oauthSessionTimeoutMs = this.config.oauthSessionTimeoutMs
+            ?? (24 * 60 * 60 * 1000); // 24 hours default
         for (const [sessionId, session] of this.sessions) {
             const age = now - session.lastActivityAt;
-            if (age > this.config.sessionTimeoutMs) {
-                expiredSessions.push(sessionId);
+            // OAuth sessions with refresh tokens: use extended timeout or never expire
+            if (session.refreshToken) {
+                // If oauthSessionTimeoutMs is 0 or negative, never expire OAuth sessions
+                if (oauthSessionTimeoutMs > 0 && age > oauthSessionTimeoutMs) {
+                    expiredSessions.push(sessionId);
+                }
+                // Otherwise, keep the session alive (unlimited timeout)
+            }
+            else {
+                // Non-OAuth sessions: use standard timeout
+                if (age > this.config.sessionTimeoutMs) {
+                    expiredSessions.push(sessionId);
+                }
             }
         }
         for (const sessionId of expiredSessions) {
@@ -791,30 +1459,206 @@ export class HttpTransport {
         const session = this.sessions.get(sessionId);
         return session?.authToken;
     }
+    /**
+     * 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
+     */
+    async ensureValidSessionToken(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        // If no expiration info, assume token is valid (non-OAuth scenarios)
+        if (!session.accessTokenExpiresAt) {
+            return true;
+        }
+        const now = Date.now();
+        const refreshThresholdMs = this.config.oauthRefreshThresholdMs ?? (60 * 1000); // Default: 60 seconds before expiration
+        const timeUntilExpiration = session.accessTokenExpiresAt - now;
+        // If token is expired or about to expire, refresh it
+        if (timeUntilExpiration <= refreshThresholdMs) {
+            this.logger.debug('Access token expired or expiring soon, refreshing', {
+                sessionId,
+                expiresAt: new Date(session.accessTokenExpiresAt).toISOString(),
+                timeUntilExpiration,
+            });
+            return await this.refreshAccessToken(sessionId);
+        }
+        return true;
+    }
+    /**
+     * Refresh access token using refresh token
+     *
+     * Why: Automatically renew expired OAuth access tokens without user intervention
+     * Returns true on success, false on failure
+     */
+    async refreshAccessToken(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || !session.refreshToken || !this.oauthProvider) {
+            this.logger.warn('Cannot refresh token: missing session, refreshToken, or OAuth provider', {
+                sessionId,
+                hasSession: !!session,
+                hasRefreshToken: !!session?.refreshToken,
+                hasOAuthProvider: !!this.oauthProvider,
+            });
+            return false;
+        }
+        try {
+            // Get client from OAuth provider
+            // Try to find client by clientId stored in session, or use default client
+            let client;
+            if (session.oauthClientId) {
+                await this.oauthProvider.ensureEndpointsInitialized();
+                client = await this.oauthProvider.clientsStore.getClient(session.oauthClientId);
+            }
+            // Fallback to default client from config if session client not found
+            if (!client && this.oauthProvider) {
+                await this.oauthProvider.ensureEndpointsInitialized();
+                // Try common client IDs
+                const defaultClientIds = ['mcp-proxy-client'];
+                if (this.config.oauthConfig?.client_id) {
+                    defaultClientIds.unshift(this.config.oauthConfig.client_id);
+                }
+                for (const clientId of defaultClientIds) {
+                    client = await this.oauthProvider.clientsStore.getClient(clientId);
+                    if (client)
+                        break;
+                }
+            }
+            if (!client) {
+                this.logger.error('Cannot refresh token: OAuth client not found', undefined, {
+                    sessionId,
+                    oauthClientId: session.oauthClientId,
+                });
+                return false;
+            }
+            // Exchange refresh token for new tokens
+            const tokens = await this.oauthProvider.exchangeRefreshToken(client, session.refreshToken, session.scopes);
+            // Update session with new tokens
+            const oldAccessToken = session.authToken;
+            session.authToken = tokens.access_token;
+            session.refreshToken = tokens.refresh_token || session.refreshToken; // Keep old refresh token if new one not provided
+            session.accessTokenExpiresAt = tokens.expires_in
+                ? Date.now() + tokens.expires_in * 1000
+                : undefined;
+            // Update token map: remove old token, add new one
+            if (oldAccessToken) {
+                this.oauthTokensByAccessToken.delete(oldAccessToken);
+            }
+            this.storeOAuthTokens(tokens, client.client_id, session.scopes || []);
+            this.logger.info('Access token refreshed successfully', {
+                sessionId,
+                newExpiresAt: session.accessTokenExpiresAt ? new Date(session.accessTokenExpiresAt).toISOString() : undefined,
+            });
+            return true;
+        }
+        catch (error) {
+            this.logger.error('Token refresh failed', error instanceof Error ? error : new Error(String(error)), {
+                sessionId,
+            });
+            return false;
+        }
+    }
     /**
      * Set message handler for processing incoming JSON-RPC messages
      */
     setMessageHandler(handler) {
         this.messageHandler = handler;
     }
+    /**
+     * Check if OAuth provider is configured
+     */
+    hasOAuthProvider() {
+        return this.oauthProvider !== null;
+    }
+    /**
+     * Get server URL
+     */
+    getServerUrl() {
+        // Prefer base URL derived from OAuth redirect URI if available
+        // This ensures consistency with the public address used for OAuth callbacks
+        if (this.oauthProvider?.redirectUri) {
+            try {
+                return new URL(this.oauthProvider.redirectUri).origin;
+            }
+            catch (e) {
+                // Ignore invalid URL format
+            }
+        }
+        // Fallback to configured host/port
+        // If configured with 0.0.0.0, this will return http://0.0.0.0:port
+        // which is usually fine for internal communication but not for external clients
+        const protocol = this.config.host.includes('://') ? '' : 'http://';
+        const host = this.config.host.includes('://') ? this.config.host : this.config.host;
+        return `${protocol}${host}:${this.config.port}`;
+    }
+    /**
+     * Get OAuth authorization URL
+     */
+    getOAuthAuthorizationUrl() {
+        return this.oauthProvider?.authorizationEndpoint || '';
+    }
+    /**
+     * Get OAuth scopes
+     */
+    getOAuthScopes() {
+        return this.oauthProvider?.scopes || [];
+    }
     /**
      * Start HTTP server
      */
     async start() {
         return new Promise((resolve, reject) => {
             try {
-                this.server = this.app.listen(this.config.port, this.config.host, () => {
-                    this.logger.info('HTTP transport started', {
-                        host: this.config.host,
-                        port: this.config.port,
-                        heartbeat: this.config.heartbeatEnabled,
-                        metrics: this.config.metricsEnabled,
+                // Check for SSL configuration from environment variables
+                const sslCertFile = process.env.MCP4_SSL_CERT_FILE;
+                const sslKeyFile = process.env.MCP4_SSL_KEY_FILE;
+                if (sslCertFile && sslKeyFile) {
+                    // Start HTTPS server
+                    this.logger.info('SSL configuration detected, starting HTTPS server', {
+                        certFile: sslCertFile,
+                        keyFile: sslKeyFile,
                     });
-                    // Start session cleanup interval
-                    this.cleanupInterval = setInterval(() => this.cleanupExpiredSessions(), 60000 // Check every minute
-                    );
-                    resolve();
-                });
+                    try {
+                        const httpsOptions = {
+                            cert: fs.readFileSync(sslCertFile),
+                            key: fs.readFileSync(sslKeyFile),
+                        };
+                        this.server = https.createServer(httpsOptions, this.app);
+                        this.server.listen(this.config.port, this.config.host, () => {
+                            this.logger.info('HTTPS transport started', {
+                                host: this.config.host,
+                                port: this.config.port,
+                                heartbeat: this.config.heartbeatEnabled,
+                                metrics: this.config.metricsEnabled,
+                            });
+                            // Start session cleanup interval
+                            this.cleanupInterval = setInterval(() => this.cleanupExpiredSessions(), TIMEOUTS.CLEANUP_INTERVAL_MS);
+                            resolve();
+                        });
+                    }
+                    catch (sslError) {
+                        this.logger.error('Failed to start HTTPS server', sslError instanceof Error ? sslError : new Error(String(sslError)));
+                        reject(sslError);
+                        return;
+                    }
+                }
+                else {
+                    // Start HTTP server
+                    this.server = this.app.listen(this.config.port, this.config.host, () => {
+                        this.logger.info('HTTP transport started', {
+                            host: this.config.host,
+                            port: this.config.port,
+                            heartbeat: this.config.heartbeatEnabled,
+                            metrics: this.config.metricsEnabled,
+                        });
+                        // Start session cleanup interval
+                        this.cleanupInterval = setInterval(() => this.cleanupExpiredSessions(), TIMEOUTS.CLEANUP_INTERVAL_MS);
+                        resolve();
+                    });
+                }
                 this.server.on('error', reject);
             }
             catch (error) {