mcp-macos 2.0.0

package/dist/server/transports/http/auth.js

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Cloudflare Access JWT verification for HTTP transport
+ * @module server/transports/http/auth
+ * @description Verifies JWTs from Cloudflare Access for defense-in-depth security
+ */
+import * as jose from 'jose';
+/** JWKS cache TTL in milliseconds (1 hour) */
+const JWKS_CACHE_TTL = 60 * 60 * 1000;
+/** JWKS cache keyed by team domain */
+const jwksCache = new Map();
+/**
+ * Gets the JWKS URL for a Cloudflare Access team domain
+ * @param teamDomain - Cloudflare Access team domain
+ * @returns JWKS URL
+ */
+function getJwksUrl(teamDomain) {
+    // Normalize domain - remove protocol if present and ensure .cloudflareaccess.com suffix
+    let domain = teamDomain.replace(/^https?:\/\//, '');
+    // If just the team name is provided, add the full domain
+    if (!domain.includes('.')) {
+        domain = `${domain}.cloudflareaccess.com`;
+    }
+    return `https://${domain}/cdn-cgi/access/certs`;
+}
+/**
+ * Gets or creates a cached JWKS getter for the team domain
+ * @param teamDomain - Cloudflare Access team domain
+ * @returns JWKS getter function
+ */
+async function getJwks(teamDomain) {
+    const cached = jwksCache.get(teamDomain);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.jwks;
+    }
+    const jwksUrl = getJwksUrl(teamDomain);
+    const jwks = jose.createRemoteJWKSet(new URL(jwksUrl));
+    jwksCache.set(teamDomain, {
+        jwks,
+        expiresAt: Date.now() + JWKS_CACHE_TTL,
+    });
+    return jwks;
+}
+/**
+ * Verifies a Cloudflare Access JWT
+ *
+ * @param token - JWT from Cf-Access-Jwt-Assertion header
+ * @param config - Cloudflare Access configuration
+ * @returns Verification result
+ */
+export async function verifyCloudflareAccessJwt(token, config) {
+    try {
+        const jwks = await getJwks(config.teamDomain);
+        // Normalize team domain for issuer validation
+        let normalizedDomain = config.teamDomain.replace(/^https?:\/\//, '');
+        if (!normalizedDomain.includes('.')) {
+            normalizedDomain = `${normalizedDomain}.cloudflareaccess.com`;
+        }
+        const expectedIssuer = `https://${normalizedDomain}`;
+        const { payload } = await jose.jwtVerify(token, jwks, {
+            audience: config.policyAUD,
+            issuer: expectedIssuer,
+        });
+        // Extract email from payload
+        const email = typeof payload.email === 'string' ? payload.email : undefined;
+        // Validate email against allowed list if configured
+        if (config.allowedEmails && config.allowedEmails.length > 0) {
+            if (!email) {
+                return {
+                    valid: false,
+                    error: 'JWT missing email claim',
+                };
+            }
+            if (!config.allowedEmails.includes(email)) {
+                return {
+                    valid: false,
+                    error: `Email ${email} not in allowed list`,
+                };
+            }
+        }
+        return {
+            valid: true,
+            email,
+        };
+    }
+    catch (error) {
+        if (error instanceof jose.errors.JWTExpired) {
+            return {
+                valid: false,
+                error: 'JWT has expired',
+            };
+        }
+        if (error instanceof jose.errors.JWTClaimValidationFailed) {
+            return {
+                valid: false,
+                error: `JWT claim validation failed: ${error.message}`,
+            };
+        }
+        if (error instanceof jose.errors.JWSSignatureVerificationFailed) {
+            return {
+                valid: false,
+                error: 'JWT signature verification failed',
+            };
+        }
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            valid: false,
+            error: `JWT verification failed: ${errorMessage}`,
+        };
+    }
+}
+/**
+ * Express middleware that verifies Cloudflare Access JWTs
+ * Returns 401 if no valid JWT is present
+ *
+ * @param config - Cloudflare Access configuration
+ * @returns Express middleware function
+ */
+export function createAuthMiddleware(config) {
+    return async (req, res, next) => {
+        // Get JWT from Cloudflare Access header
+        const token = req.headers['cf-access-jwt-assertion'];
+        if (!token || typeof token !== 'string') {
+            res.status(401).json({
+                error: 'Unauthorized',
+                message: 'Missing Cf-Access-Jwt-Assertion header',
+            });
+            return;
+        }
+        const result = await verifyCloudflareAccessJwt(token, config);
+        if (!result.valid) {
+            res.status(401).json({
+                error: 'Unauthorized',
+                message: result.error ?? 'JWT verification failed',
+            });
+            return;
+        }
+        // Attach verified email to request for logging
+        req.cfAccessEmail = result.email;
+        next();
+    };
+}
+/**
+ * Clears the JWKS cache (useful for testing)
+ */
+export function clearJwksCache() {
+    jwksCache.clear();
+}
+//# sourceMappingURL=auth.js.map

package/dist/server/transports/http/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../../src/server/transports/http/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAgB7B,8CAA8C;AAC9C,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtC,sCAAsC;AACtC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEpD;;;;GAIG;AACH,SAAS,UAAU,CAAC,UAAkB;IACpC,wFAAwF;IACxF,IAAI,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAEpD,yDAAyD;IACzD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,MAAM,uBAAuB,CAAC;IAC5C,CAAC;IAED,OAAO,WAAW,MAAM,uBAAuB,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,OAAO,CAAC,UAAkB;IACvC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAEzC,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAC5C,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,kBAAkB,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAEvD,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE;QACxB,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc;KACvC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAa,EACb,MAA8B;IAE9B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAE9C,8CAA8C;QAC9C,IAAI,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,gBAAgB,GAAG,GAAG,gBAAgB,uBAAuB,CAAC;QAChE,CAAC;QACD,MAAM,cAAc,GAAG,WAAW,gBAAgB,EAAE,CAAC;QAErD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;YACpD,QAAQ,EAAE,MAAM,CAAC,SAAS;YAC1B,MAAM,EAAE,cAAc;SACvB,CAAC,CAAC;QAEH,6BAA6B;QAC7B,MAAM,KAAK,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAE5E,oDAAoD;QACpD,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5D,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,KAAK,EAAE,yBAAyB;iBACjC,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1C,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,KAAK,EAAE,SAAS,KAAK,sBAAsB;iBAC5C,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO;YACL,KAAK,EAAE,IAAI;YACX,KAAK;SACN,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAC5C,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,iBAAiB;aACzB,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,YAAY,IAAI,CAAC,MAAM,CAAC,wBAAwB,EAAE,CAAC;YAC1D,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,gCAAgC,KAAK,CAAC,OAAO,EAAE;aACvD,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,YAAY,IAAI,CAAC,MAAM,CAAC,8BAA8B,EAAE,CAAC;YAChE,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,mCAAmC;aAC3C,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QAC3D,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,4BAA4B,YAAY,EAAE;SAClD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAA8B;IAE9B,OAAO,KAAK,EACV,GAAY,EACZ,GAAa,EACb,IAAkB,EACH,EAAE;QACjB,wCAAwC;QACxC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;QAErD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACxC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,cAAc;gBACrB,OAAO,EAAE,wCAAwC;aAClD,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAE9D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,cAAc;gBACrB,OAAO,EAAE,MAAM,CAAC,KAAK,IAAI,yBAAyB;aACnD,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,+CAA+C;QAC9C,GAA4C,CAAC,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC;QAE3E,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}

package/dist/server/transports/http/health.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Health check endpoints for HTTP transport
+ * @module server/transports/http/health
+ * @description Provides /health and /health/ready endpoints for monitoring
+ */
+import type { Request, Response, Router } from 'express';
+import type { FullServerConfig } from '../../../config/index.js';
+/**
+ * Marks the server as started (call when HTTP server begins listening)
+ */
+export declare function markServerStarted(): void;
+/**
+ * Basic health check handler
+ * Returns 200 if server is running
+ *
+ * @param config - Server configuration
+ * @returns Express request handler
+ */
+export declare function createHealthHandler(config: FullServerConfig): (req: Request, res: Response) => void;
+/**
+ * Readiness check handler
+ * Returns 200 with subsystem status if server is ready to accept requests
+ *
+ * @param config - Server configuration
+ * @returns Express request handler
+ */
+export declare function createReadinessHandler(config: FullServerConfig): (req: Request, res: Response) => void;
+/**
+ * Registers health check routes on the provided router
+ * These endpoints do NOT require authentication
+ *
+ * @param router - Express router to register routes on
+ * @param config - Server configuration
+ */
+export declare function registerHealthRoutes(router: Router, config: FullServerConfig): void;

package/dist/server/transports/http/health.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Health check endpoints for HTTP transport
+ * @module server/transports/http/health
+ * @description Provides /health and /health/ready endpoints for monitoring
+ */
+/** Server start time for uptime calculation */
+let serverStartTime = null;
+/**
+ * Marks the server as started (call when HTTP server begins listening)
+ */
+export function markServerStarted() {
+    serverStartTime = Date.now();
+}
+/**
+ * Gets the server uptime in seconds
+ * @returns Uptime in seconds, or 0 if not started
+ */
+function getUptime() {
+    if (serverStartTime === null) {
+        return 0;
+    }
+    return Math.floor((Date.now() - serverStartTime) / 1000);
+}
+/**
+ * Basic health check handler
+ * Returns 200 if server is running
+ *
+ * @param config - Server configuration
+ * @returns Express request handler
+ */
+export function createHealthHandler(config) {
+    return (_req, res) => {
+        const response = {
+            status: 'healthy',
+            service: config.name,
+            version: config.version,
+            timestamp: new Date().toISOString(),
+            uptime: getUptime(),
+        };
+        res.status(200).json(response);
+    };
+}
+/**
+ * Readiness check handler
+ * Returns 200 with subsystem status if server is ready to accept requests
+ *
+ * @param config - Server configuration
+ * @returns Express request handler
+ */
+export function createReadinessHandler(config) {
+    return (_req, res) => {
+        const subsystems = [
+            {
+                name: 'mcp-server',
+                status: 'healthy',
+                message: 'MCP server is accepting connections',
+            },
+            {
+                name: 'http-transport',
+                status: 'healthy',
+                message: 'HTTP transport is operational',
+            },
+        ];
+        // Determine overall status based on subsystems
+        const overallStatus = subsystems.every((s) => s.status === 'healthy')
+            ? 'healthy'
+            : subsystems.some((s) => s.status === 'unhealthy')
+                ? 'unhealthy'
+                : 'degraded';
+        const response = {
+            status: overallStatus,
+            service: config.name,
+            version: config.version,
+            timestamp: new Date().toISOString(),
+            uptime: getUptime(),
+            subsystems,
+        };
+        const statusCode = overallStatus === 'healthy' ? 200 : 503;
+        res.status(statusCode).json(response);
+    };
+}
+/**
+ * Registers health check routes on the provided router
+ * These endpoints do NOT require authentication
+ *
+ * @param router - Express router to register routes on
+ * @param config - Server configuration
+ */
+export function registerHealthRoutes(router, config) {
+    router.get('/health', createHealthHandler(config));
+    router.get('/health/ready', createReadinessHandler(config));
+}
+//# sourceMappingURL=health.js.map

package/dist/server/transports/http/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../../src/server/transports/http/health.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,+CAA+C;AAC/C,IAAI,eAAe,GAAkB,IAAI,CAAC;AAE1C;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS;IAChB,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC,GAAG,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAwB;IAExB,OAAO,CAAC,IAAa,EAAE,GAAa,EAAQ,EAAE;QAC5C,MAAM,QAAQ,GAAmB;YAC/B,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,MAAM,CAAC,IAAI;YACpB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM,EAAE,SAAS,EAAE;SACpB,CAAC;QAEF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAwB;IAExB,OAAO,CAAC,IAAa,EAAE,GAAa,EAAQ,EAAE;QAC5C,MAAM,UAAU,GAAsB;YACpC;gBACE,IAAI,EAAE,YAAY;gBAClB,MAAM,EAAE,SAAS;gBACjB,OAAO,EAAE,qCAAqC;aAC/C;YACD;gBACE,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,SAAS;gBACjB,OAAO,EAAE,+BAA+B;aACzC;SACF,CAAC;QAEF,+CAA+C;QAC/C,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC;YACnE,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;gBAChD,CAAC,CAAC,WAAW;gBACb,CAAC,CAAC,UAAU,CAAC;QAEjB,MAAM,QAAQ,GAAmB;YAC/B,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE,MAAM,CAAC,IAAI;YACpB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM,EAAE,SAAS,EAAE;YACnB,UAAU;SACX,CAAC;QAEF,MAAM,UAAU,GAAG,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAC3D,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAc,EACd,MAAwB;IAExB,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IACnD,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/server/transports/http/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview HTTP transport layer using MCP SDK's StreamableHTTPServerTransport
+ * @module server/transports/http
+ * @description Express server providing HTTP transport for MCP protocol messages
+ */
+import type { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import { type Express } from 'express';
+import type { FullServerConfig, HttpConfig } from '../../../config/index.js';
+/**
+ * HTTP transport instance
+ */
+export interface HttpTransportInstance {
+    /** Express application */
+    app: Express;
+    /** Start listening on configured host:port */
+    start: () => Promise<void>;
+    /** Stop the HTTP server */
+    stop: () => Promise<void>;
+}
+/**
+ * Creates an HTTP transport for the MCP server
+ *
+ * SDK 1.26.0 requires stateless transports to be created fresh per request.
+ * Each POST creates a new MCP Server + StreamableHTTPServerTransport pair,
+ * handles the request, then cleans up on response close.
+ *
+ * @param _mcpServer - Unused (kept for API compatibility). Per-request servers are created internally.
+ * @param config - Full server configuration
+ * @param httpConfig - HTTP-specific configuration
+ * @returns HTTP transport instance
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * const mcpServer = createServer(config);
+ * const httpTransport = createHttpTransport(mcpServer, config, config.http!);
+ * await httpTransport.start();
+ * ```
+ */
+export declare function createHttpTransport(_mcpServer: McpServer, config: FullServerConfig, httpConfig: HttpConfig): HttpTransportInstance;
+export { createAuthMiddleware, verifyCloudflareAccessJwt } from './auth.js';
+export { createHealthHandler, createReadinessHandler, registerHealthRoutes, } from './health.js';
+export { corsMiddleware, createRateLimiter, errorHandler, requestLogging, requestTiming, } from './middleware.js';

package/dist/server/transports/http/index.js

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview HTTP transport layer using MCP SDK's StreamableHTTPServerTransport
+ * @module server/transports/http
+ * @description Express server providing HTTP transport for MCP protocol messages
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express, { Router, } from 'express';
+import { createServer } from '../../server.js';
+import { createAuthMiddleware } from './auth.js';
+import { markServerStarted, registerHealthRoutes } from './health.js';
+import { corsMiddleware, createRateLimiter, errorHandler, requestLogging, requestTiming, } from './middleware.js';
+/**
+ * Creates an HTTP transport for the MCP server
+ *
+ * SDK 1.26.0 requires stateless transports to be created fresh per request.
+ * Each POST creates a new MCP Server + StreamableHTTPServerTransport pair,
+ * handles the request, then cleans up on response close.
+ *
+ * @param _mcpServer - Unused (kept for API compatibility). Per-request servers are created internally.
+ * @param config - Full server configuration
+ * @param httpConfig - HTTP-specific configuration
+ * @returns HTTP transport instance
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * const mcpServer = createServer(config);
+ * const httpTransport = createHttpTransport(mcpServer, config, config.http!);
+ * await httpTransport.start();
+ * ```
+ */
+export function createHttpTransport(_mcpServer, config, httpConfig) {
+    const app = express();
+    // Trust proxy for rate limiting behind Cloudflare Tunnel
+    app.set('trust proxy', true);
+    // Apply global middleware
+    // express.json() is required to pre-parse the body for the SDK's parsedBody parameter.
+    // SDK 1.26.0 explicitly supports this pattern: transport.handleRequest(req, res, req.body)
+    app.use(express.json());
+    app.use(corsMiddleware());
+    app.use(requestTiming());
+    app.use(requestLogging());
+    app.use(createRateLimiter());
+    // Register health endpoints (no auth required)
+    const healthRouter = Router();
+    registerHealthRoutes(healthRouter, config);
+    app.use(healthRouter);
+    // Apply auth middleware to MCP endpoint if Cloudflare Access is configured
+    if (httpConfig.cloudflareAccess) {
+        app.use('/mcp', createAuthMiddleware(httpConfig.cloudflareAccess));
+    }
+    // MCP endpoint handler — creates a fresh server + transport per request
+    // SDK 1.26.0 stateless mode throws "Stateless transport cannot be reused across requests"
+    // if a transport with sessionIdGenerator=undefined handles more than one request.
+    // The official SDK pattern (simpleStatelessStreamableHttp.ts) creates new instances per request.
+    const mcpHandler = async (req, res) => {
+        const perRequestServer = createServer(config);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        // Log transport-level errors to stderr for visibility
+        transport.onerror = (error) => {
+            process.stderr.write(`${JSON.stringify({ timestamp: new Date().toISOString(), error: 'MCP transport error', message: error.message, stack: error.stack })}\n`);
+        };
+        try {
+            await perRequestServer.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            // Clean up when the response closes
+            res.on('close', () => {
+                transport.close().catch(() => { });
+                perRequestServer.close().catch(() => { });
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            process.stderr.write(`${JSON.stringify({ timestamp: new Date().toISOString(), error: 'MCP request failed', message: errorMessage })}\n`);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    error: 'Internal Server Error',
+                    message: 'MCP request processing failed',
+                });
+            }
+        }
+    };
+    // Register MCP routes - handle all methods for session management
+    // Support both /mcp (explicit) and root / (Claude.ai expects this)
+    app.all('/mcp', mcpHandler);
+    app.all('/', mcpHandler);
+    // Error handler must be last
+    app.use(errorHandler());
+    // HTTP server reference for cleanup
+    let server = null;
+    return {
+        app,
+        async start() {
+            return new Promise((resolve, reject) => {
+                try {
+                    server = app.listen(httpConfig.port, httpConfig.host, () => {
+                        markServerStarted();
+                        process.stderr.write(`${JSON.stringify({
+                            timestamp: new Date().toISOString(),
+                            event: 'http_server_started',
+                            host: httpConfig.host,
+                            port: httpConfig.port,
+                            authEnabled: !!httpConfig.cloudflareAccess,
+                        })}\n`);
+                        resolve();
+                    });
+                    server.on('error', (error) => {
+                        process.stderr.write(`${JSON.stringify({ timestamp: new Date().toISOString(), error: 'HTTP server error', message: error.message })}\n`);
+                        reject(error);
+                    });
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        },
+        async stop() {
+            if (server) {
+                return new Promise((resolve, reject) => {
+                    server?.close((error) => {
+                        if (error) {
+                            reject(error);
+                        }
+                        else {
+                            process.stderr.write(`${JSON.stringify({ timestamp: new Date().toISOString(), event: 'http_server_stopped' })}\n`);
+                            resolve();
+                        }
+                    });
+                });
+            }
+        },
+    };
+}
+// Re-export components for testing and extensibility
+export { createAuthMiddleware, verifyCloudflareAccessJwt } from './auth.js';
+export { createHealthHandler, createReadinessHandler, registerHealthRoutes, } from './health.js';
+export { corsMiddleware, createRateLimiter, errorHandler, requestLogging, requestTiming, } from './middleware.js';
+//# sourceMappingURL=index.js.map

package/dist/server/transports/http/index.js.map

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

package/dist/server/transports/http/middleware.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview HTTP middleware for rate limiting, logging, and CORS
+ * @module server/transports/http/middleware
+ * @description Express middleware stack for the HTTP transport
+ */
+import type { NextFunction, Request, Response } from 'express';
+import rateLimit from 'express-rate-limit';
+/**
+ * Extended request type with timing and auth info
+ */
+export interface TimedRequest extends Request {
+    /** Request start time for duration calculation */
+    startTime?: number;
+    /** Verified Cloudflare Access email */
+    cfAccessEmail?: string;
+}
+/**
+ * Creates a rate limiter middleware
+ * Default: 100 requests per minute per IP
+ *
+ * @param maxRequests - Maximum requests per window (default: 100)
+ * @param windowMs - Window size in milliseconds (default: 60000 = 1 minute)
+ * @returns Express rate limiting middleware
+ */
+export declare function createRateLimiter(maxRequests?: number, windowMs?: number): ReturnType<typeof rateLimit>;
+/**
+ * Request timing middleware
+ * Adds startTime to request for duration calculation
+ *
+ * @returns Express middleware function
+ */
+export declare function requestTiming(): (req: TimedRequest, res: Response, next: NextFunction) => void;
+/**
+ * Request logging middleware
+ * Logs request details after response is sent
+ *
+ * @returns Express middleware function
+ */
+export declare function requestLogging(): (req: TimedRequest, res: Response, next: NextFunction) => void;
+/**
+ * CORS middleware for handling preflight requests
+ * Configured for Cloudflare Tunnel / Access
+ *
+ * @returns Express middleware function
+ */
+export declare function corsMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Error handling middleware
+ * Catches unhandled errors and returns appropriate response
+ *
+ * @returns Express error handling middleware
+ */
+export declare function errorHandler(): (err: Error, req: Request, res: Response, next: NextFunction) => void;

package/dist/server/transports/http/middleware.js

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview HTTP middleware for rate limiting, logging, and CORS
+ * @module server/transports/http/middleware
+ * @description Express middleware stack for the HTTP transport
+ */
+import rateLimit from 'express-rate-limit';
+/**
+ * Creates a rate limiter middleware
+ * Default: 100 requests per minute per IP
+ *
+ * @param maxRequests - Maximum requests per window (default: 100)
+ * @param windowMs - Window size in milliseconds (default: 60000 = 1 minute)
+ * @returns Express rate limiting middleware
+ */
+export function createRateLimiter(maxRequests = 100, windowMs = 60000) {
+    return rateLimit({
+        windowMs,
+        max: maxRequests,
+        // Suppress ERR_ERL_KEY_GEN_IPV6 ValidationError — we're behind Cloudflare
+        // Tunnel which always provides X-Forwarded-For, so IPv6 validation is irrelevant
+        validate: { keyGeneratorIpFallback: false },
+        message: {
+            error: 'Too Many Requests',
+            message: `Rate limit exceeded. Maximum ${maxRequests} requests per ${windowMs / 1000} seconds.`,
+        },
+        standardHeaders: true,
+        legacyHeaders: false,
+        // Use X-Forwarded-For header if behind proxy (Cloudflare Tunnel)
+        keyGenerator: (req) => {
+            const forwarded = req.headers['x-forwarded-for'];
+            if (typeof forwarded === 'string') {
+                // Take the first IP if there are multiple
+                return forwarded.split(',')[0].trim();
+            }
+            return req.ip ?? req.socket.remoteAddress ?? 'unknown';
+        },
+        // Skip rate limiting for health checks
+        skip: (req) => {
+            return req.path === '/health' || req.path === '/health/ready';
+        },
+    });
+}
+/**
+ * Request timing middleware
+ * Adds startTime to request for duration calculation
+ *
+ * @returns Express middleware function
+ */
+export function requestTiming() {
+    return (req, _res, next) => {
+        req.startTime = Date.now();
+        next();
+    };
+}
+/**
+ * Request logging middleware
+ * Logs request details after response is sent
+ *
+ * @returns Express middleware function
+ */
+export function requestLogging() {
+    return (req, res, next) => {
+        // Log after response is finished
+        res.on('finish', () => {
+            const duration = req.startTime ? Date.now() - req.startTime : 0;
+            const logEntry = {
+                timestamp: new Date().toISOString(),
+                method: req.method,
+                path: req.path,
+                status: res.statusCode,
+                duration,
+                ip: (typeof req.headers['x-forwarded-for'] === 'string'
+                    ? req.headers['x-forwarded-for'].split(',')[0].trim()
+                    : undefined) ??
+                    req.ip ??
+                    req.socket.remoteAddress ??
+                    'unknown',
+            };
+            // Add user if available from Cloudflare Access
+            if (req.cfAccessEmail) {
+                logEntry.user = req.cfAccessEmail;
+            }
+            // Log to stderr to avoid interfering with stdio transport
+            // Use structured JSON for easy parsing
+            process.stderr.write(`${JSON.stringify(logEntry)}\n`);
+        });
+        next();
+    };
+}
+/**
+ * CORS middleware for handling preflight requests
+ * Configured for Cloudflare Tunnel / Access
+ *
+ * @returns Express middleware function
+ */
+export function corsMiddleware() {
+    return (req, res, next) => {
+        // Allow requests from same origin or Cloudflare
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Cf-Access-Jwt-Assertion, Mcp-Session-Id, Last-Event-Id');
+        res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+        res.setHeader('Access-Control-Max-Age', '86400');
+        // Handle preflight requests
+        if (req.method === 'OPTIONS') {
+            res.status(204).end();
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Error handling middleware
+ * Catches unhandled errors and returns appropriate response
+ *
+ * @returns Express error handling middleware
+ */
+export function errorHandler() {
+    return (err, _req, res, _next) => {
+        // Log error to stderr
+        process.stderr.write(`${JSON.stringify({ timestamp: new Date().toISOString(), error: err.message, stack: err.stack })}\n`);
+        // Send error response if not already sent
+        if (!res.headersSent) {
+            res.status(500).json({
+                error: 'Internal Server Error',
+                message: process.env.NODE_ENV === 'production'
+                    ? 'An unexpected error occurred'
+                    : err.message,
+            });
+        }
+    };
+}
+//# sourceMappingURL=middleware.js.map