@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Implements the JWT authentication strategy.
+ * This module provides a concrete implementation of the AuthStrategy for validating
+ * JSON Web Tokens (JWTs). It encapsulates all logic related to JWT verification,
+ * including secret key management and payload validation.
+ * @module src/mcp-server/transports/auth/strategies/JwtStrategy
+ */
+import { jwtVerify } from 'jose';
+import { buildAuthInfoFromClaims, handleJoseVerifyError, } from '../../../../mcp-server/transports/auth/lib/claimParser.js';
+import { JsonRpcErrorCode, McpError } from '../../../../types-global/errors.js';
+import { requestContextService } from '../../../../utils/internal/requestContext.js';
+export class JwtStrategy {
+    config;
+    logger;
+    secretKey;
+    devMcpClientId;
+    devMcpScopes;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+        const context = requestContextService.createRequestContext({
+            operation: 'JwtStrategy.constructor',
+        });
+        this.logger.debug('Initializing JwtStrategy...', context);
+        this.devMcpClientId = this.config.devMcpClientId || 'dev-client-id';
+        this.devMcpScopes = this.config.devMcpScopes || ['dev-scope'];
+        const secretKey = this.config.mcpAuthSecretKey;
+        if (!secretKey && !this.config.devMcpAuthBypass) {
+            this.logger.fatal('CRITICAL: MCP_AUTH_SECRET_KEY is not set for JWT auth. Set the key or enable DEV_MCP_AUTH_BYPASS=true for development.', context);
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'MCP_AUTH_SECRET_KEY must be set for JWT auth (or set DEV_MCP_AUTH_BYPASS=true).', context);
+        }
+        else if (!secretKey) {
+            // devMcpAuthBypass is explicitly true — opt-in dev bypass
+            this.logger.warning(`MCP_AUTH_SECRET_KEY is not set. JWT auth bypassed via DEV_MCP_AUTH_BYPASS=true (environment: ${this.config.environment}).`, context);
+            this.secretKey = null;
+        }
+        else {
+            this.logger.info('JWT secret key loaded successfully.', context);
+            this.secretKey = new TextEncoder().encode(secretKey);
+        }
+    }
+    async verify(token) {
+        const context = requestContextService.createRequestContext({
+            operation: 'JwtStrategy.verify',
+        });
+        this.logger.debug('Attempting to verify JWT.', context);
+        // Handle development mode bypass (constructor prevents null key in production)
+        if (!this.secretKey) {
+            this.logger.warning('Bypassing JWT verification: No secret key (DEV ONLY).', context);
+            return {
+                token: 'dev-mode-placeholder-token',
+                clientId: this.devMcpClientId,
+                scopes: this.devMcpScopes,
+            };
+        }
+        try {
+            const { payload: decoded } = await jwtVerify(token, this.secretKey);
+            this.logger.debug('JWT signature verified successfully.', {
+                ...context,
+                claims: {
+                    iss: decoded.iss,
+                    aud: decoded.aud,
+                    exp: decoded.exp,
+                    iat: decoded.iat,
+                    jti: decoded.jti,
+                },
+            });
+            const authInfo = buildAuthInfoFromClaims(token, decoded);
+            this.logger.info('JWT verification successful.', {
+                ...context,
+                clientId: authInfo.clientId,
+                scopes: authInfo.scopes,
+                ...(authInfo.tenantId ? { tenantId: authInfo.tenantId } : {}),
+            });
+            return authInfo;
+        }
+        catch (error) {
+            this.logger.warning('JWT verification failed.', {
+                ...context,
+                errorName: error instanceof Error ? error.name : 'Unknown',
+            });
+            handleJoseVerifyError(error, 'Token verification failed.');
+        }
+    }
+}
+//# sourceMappingURL=jwtStrategy.js.map

package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js.map

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

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts

@@ -0,0 +1,14 @@
+import type { config as ConfigType } from '../../../../config/index.js';
+import type { AuthInfo } from '../../../../mcp-server/transports/auth/lib/authTypes.js';
+import type { AuthStrategy } from '../../../../mcp-server/transports/auth/strategies/authStrategy.js';
+import type { logger as LoggerType } from '../../../../utils/internal/logger.js';
+export declare class OauthStrategy implements AuthStrategy {
+    private config;
+    private logger;
+    private readonly jwks;
+    private readonly issuerUrl;
+    private readonly audience;
+    constructor(config: typeof ConfigType, logger: typeof LoggerType);
+    verify(token: string): Promise<AuthInfo>;
+}
+//# sourceMappingURL=oauthStrategy.d.ts.map

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthStrategy.d.ts","sourceRoot":"","sources":["../../../../../src/mcp-server/transports/auth/strategies/oauthStrategy.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AAK9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yDAAyD,CAAC;AAE5F,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGvE,qBAAa,aAAc,YAAW,YAAY;IAM9C,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IANhB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwC;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAGxB,MAAM,EAAE,OAAO,UAAU,EACzB,MAAM,EAAE,OAAO,UAAU;IAmD7B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAyE/C"}

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Implements the OAuth 2.1 authentication strategy.
+ * This module provides a concrete implementation of the AuthStrategy for validating
+ * JWTs against a remote JSON Web Key Set (JWKS), as is common in OAuth 2.1 flows.
+ * @module src/mcp-server/transports/auth/strategies/OauthStrategy
+ */
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { buildAuthInfoFromClaims, handleJoseVerifyError, } from '../../../../mcp-server/transports/auth/lib/claimParser.js';
+import { JsonRpcErrorCode, McpError } from '../../../../types-global/errors.js';
+import { requestContextService } from '../../../../utils/internal/requestContext.js';
+export class OauthStrategy {
+    config;
+    logger;
+    jwks;
+    issuerUrl;
+    audience;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+        const context = requestContextService.createRequestContext({
+            operation: 'OauthStrategy.constructor',
+        });
+        this.logger.debug('Initializing OauthStrategy...', context);
+        if (this.config.mcpAuthMode !== 'oauth') {
+            throw new Error('OauthStrategy instantiated for non-oauth auth mode.');
+        }
+        if (!this.config.oauthIssuerUrl || !this.config.oauthAudience) {
+            this.logger.fatal('CRITICAL: OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.', context);
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.', context);
+        }
+        // Store validated config — no casts needed after the guard above
+        this.issuerUrl = this.config.oauthIssuerUrl;
+        this.audience = this.config.oauthAudience;
+        try {
+            const jwksUrl = new URL(this.config.oauthJwksUri || `${this.issuerUrl.replace(/\/$/, '')}/.well-known/jwks.json`);
+            this.jwks = createRemoteJWKSet(jwksUrl, {
+                cooldownDuration: this.config.oauthJwksCooldownMs,
+                timeoutDuration: this.config.oauthJwksTimeoutMs,
+            });
+            this.logger.info(`JWKS client initialized for URL: ${jwksUrl.href}`, context);
+        }
+        catch (error) {
+            this.logger.fatal('Failed to initialize JWKS client.', {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw new McpError(JsonRpcErrorCode.ServiceUnavailable, 'Could not initialize JWKS client for OAuth strategy.', {
+                ...context,
+                originalError: error instanceof Error ? error.message : 'Unknown',
+            });
+        }
+    }
+    async verify(token) {
+        const context = requestContextService.createRequestContext({
+            operation: 'OauthStrategy.verify',
+        });
+        this.logger.debug('Attempting to verify OAuth token via JWKS.', context);
+        try {
+            const { payload } = await jwtVerify(token, this.jwks, {
+                issuer: this.issuerUrl,
+                audience: this.audience,
+            });
+            this.logger.debug('OAuth token signature verified successfully.', {
+                ...context,
+                claims: {
+                    iss: payload.iss,
+                    aud: payload.aud,
+                    exp: payload.exp,
+                    iat: payload.iat,
+                    jti: payload.jti,
+                },
+            });
+            // RFC 8707 Resource Indicators validation (MCP 2025-06-18 requirement)
+            if (this.config.mcpServerResourceIdentifier) {
+                const resourceClaim = payload.resource || payload.aud;
+                const expectedResource = this.config.mcpServerResourceIdentifier;
+                const isResourceValid = (Array.isArray(resourceClaim) && resourceClaim.includes(expectedResource)) ||
+                    resourceClaim === expectedResource;
+                if (!isResourceValid) {
+                    this.logger.warning('Token resource indicator mismatch. Token was not issued for this MCP server.', {
+                        ...context,
+                        expected: expectedResource,
+                        received: resourceClaim,
+                    });
+                    throw new McpError(JsonRpcErrorCode.Forbidden, 'Token was not issued for this MCP server. Resource indicator mismatch.', {
+                        expected: expectedResource,
+                        received: resourceClaim,
+                    });
+                }
+                this.logger.debug('RFC 8707 resource indicator validated successfully.', {
+                    ...context,
+                    resource: expectedResource,
+                });
+            }
+            const authInfo = buildAuthInfoFromClaims(token, payload);
+            this.logger.info('OAuth token verification successful.', {
+                ...context,
+                clientId: authInfo.clientId,
+                scopes: authInfo.scopes,
+                ...(authInfo.tenantId ? { tenantId: authInfo.tenantId } : {}),
+            });
+            return authInfo;
+        }
+        catch (error) {
+            this.logger.warning('OAuth token verification failed.', {
+                ...context,
+                errorName: error instanceof Error ? error.name : 'Unknown',
+            });
+            handleJoseVerifyError(error, 'OAuth token verification failed.');
+        }
+    }
+}
+//# sourceMappingURL=oauthStrategy.js.map

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthStrategy.js","sourceRoot":"","sources":["../../../../../src/mcp-server/transports/auth/strategies/oauthStrategy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAwB,SAAS,EAAE,MAAM,MAAM,CAAC;AAI3E,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAE3E,MAAM,OAAO,aAAa;IAMd;IACA;IANO,IAAI,CAAwC;IAC5C,SAAS,CAAS;IAClB,QAAQ,CAAS;IAElC,YACU,MAAyB,EACzB,MAAyB;QADzB,WAAM,GAAN,MAAM,CAAmB;QACzB,WAAM,GAAN,MAAM,CAAmB;QAEjC,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,2BAA2B;SACvC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE,OAAO,CAAC,CAAC;QAE5D,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK,OAAO,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAC9D,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,2EAA2E,EAC3E,OAAO,CACR,CAAC;YACF,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,iEAAiE,EACjE,OAAO,CACR,CAAC;QACJ,CAAC;QAED,iEAAiE;QACjE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;QAE1C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,wBAAwB,CACzF,CAAC;YACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,OAAO,EAAE;gBACtC,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,mBAAmB;gBACjD,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,kBAAkB;aAChD,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oCAAoC,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QAChF,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE;gBACrD,GAAG,OAAO;gBACV,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;YACH,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,sDAAsD,EACtD;gBACE,GAAG,OAAO;gBACV,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;aAClE,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa;QACxB,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,sBAAsB;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,4CAA4C,EAAE,OAAO,CAAC,CAAC;QAEzE,IAAI,CAAC;YACH,MAAM,EAAE,OAAO,EAAE,GAAoB,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE;gBACrE,MAAM,EAAE,IAAI,CAAC,SAAS;gBACtB,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,EAAE;gBAChE,GAAG,OAAO;gBACV,MAAM,EAAE;oBACN,GAAG,EAAE,OAAO,CAAC,GAAG;oBAChB,GAAG,EAAE,OAAO,CAAC,GAAG;oBAChB,GAAG,EAAE,OAAO,CAAC,GAAG;oBAChB,GAAG,EAAE,OAAO,CAAC,GAAG;oBAChB,GAAG,EAAE,OAAO,CAAC,GAAG;iBACjB;aACF,CAAC,CAAC;YAEH,uEAAuE;YACvE,IAAI,IAAI,CAAC,MAAM,CAAC,2BAA2B,EAAE,CAAC;gBAC5C,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC;gBACtD,MAAM,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC,2BAA2B,CAAC;gBAEjE,MAAM,eAAe,GACnB,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;oBAC1E,aAAa,KAAK,gBAAgB,CAAC;gBAErC,IAAI,CAAC,eAAe,EAAE,CAAC;oBACrB,IAAI,CAAC,MAAM,CAAC,OAAO,CACjB,8EAA8E,EAC9E;wBACE,GAAG,OAAO;wBACV,QAAQ,EAAE,gBAAgB;wBAC1B,QAAQ,EAAE,aAAa;qBACxB,CACF,CAAC;oBACF,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,SAAS,EAC1B,wEAAwE,EACxE;wBACE,QAAQ,EAAE,gBAAgB;wBAC1B,QAAQ,EAAE,aAAa;qBACxB,CACF,CAAC;gBACJ,CAAC;gBAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qDAAqD,EAAE;oBACvE,GAAG,OAAO;oBACV,QAAQ,EAAE,gBAAgB;iBAC3B,CAAC,CAAC;YACL,CAAC;YAED,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAEzD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,EAAE;gBACvD,GAAG,OAAO;gBACV,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9D,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,kCAAkC,EAAE;gBACtD,GAAG,OAAO;gBACV,SAAS,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;aAC3D,CAAC,CAAC;YACH,qBAAqB,CAAC,KAAK,EAAE,kCAAkC,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;CACF"}

package/dist/mcp-server/transports/http/httpErrorHandler.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Centralized error handler for the Hono HTTP transport.
+ * This middleware intercepts errors that occur during request processing,
+ * standardizes them using the application's ErrorHandler utility, and
+ * formats them into a consistent JSON-RPC error response.
+ * @module src/mcp-server/transports/http/httpErrorHandler
+ */
+import type { Context } from 'hono';
+import type { HonoNodeBindings } from '../../../mcp-server/transports/http/httpTypes.js';
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * Generic to support different binding types (Node.js, Cloudflare Workers, etc).
+ *
+ * @template TBindings - The Hono binding type (defaults to HonoNodeBindings)
+ * @param err - The error that was thrown.
+ * @param c - The Hono context object for the request.
+ * @returns A Response object containing the formatted JSON-RPC error.
+ */
+export declare const httpErrorHandler: <TBindings extends object = HonoNodeBindings>(err: Error, c: Context<{
+    Bindings: TBindings;
+}>) => Promise<Response>;
+//# sourceMappingURL=httpErrorHandler.d.ts.map

package/dist/mcp-server/transports/http/httpErrorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpErrorHandler.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/http/httpErrorHandler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAIpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAOlF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAAU,SAAS,SAAS,MAAM,GAAG,gBAAgB,EAChF,KAAK,KAAK,EACV,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,KAClC,OAAO,CAAC,QAAQ,CAiGlB,CAAC"}

package/dist/mcp-server/transports/http/httpErrorHandler.js

@@ -0,0 +1,112 @@
+import { config } from '../../../config/index.js';
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { getProperty } from '../../../utils/types/guards.js';
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * Generic to support different binding types (Node.js, Cloudflare Workers, etc).
+ *
+ * @template TBindings - The Hono binding type (defaults to HonoNodeBindings)
+ * @param err - The error that was thrown.
+ * @param c - The Hono context object for the request.
+ * @returns A Response object containing the formatted JSON-RPC error.
+ */
+export const httpErrorHandler = async (err, c) => {
+    const context = requestContextService.createRequestContext({
+        operation: 'httpErrorHandler',
+        additionalContext: {
+            path: c.req.path,
+            method: c.req.method,
+        },
+    });
+    logger.debug('HTTP error handler invoked.', context);
+    const handledError = ErrorHandler.handleError(err, {
+        operation: 'httpTransport',
+        context,
+    });
+    const errorCode = handledError instanceof McpError ? handledError.code : -32603;
+    let status = 500;
+    switch (errorCode) {
+        case JsonRpcErrorCode.NotFound:
+            status = 404;
+            break;
+        case JsonRpcErrorCode.Unauthorized:
+            status = 401;
+            // RFC 9728 §7: 401 responses MUST include WWW-Authenticate with resource_metadata URL.
+            // /.well-known/oauth-protected-resource is always mounted regardless of auth mode.
+            // https://datatracker.ietf.org/doc/html/rfc9728#section-7
+            {
+                const origin = new URL(c.req.url).origin;
+                const resourceMetadataUrl = `${origin}/.well-known/oauth-protected-resource`;
+                c.header('WWW-Authenticate', `Bearer realm="${config.mcpServerName}", resource_metadata="${resourceMetadataUrl}"`);
+                logger.debug('Added WWW-Authenticate header for 401 response.', {
+                    ...context,
+                    resourceMetadataUrl,
+                });
+            }
+            break;
+        case JsonRpcErrorCode.Forbidden:
+            status = 403;
+            break;
+        case JsonRpcErrorCode.ValidationError:
+        case JsonRpcErrorCode.InvalidRequest:
+            status = 400;
+            break;
+        case JsonRpcErrorCode.Conflict:
+            status = 409;
+            break;
+        case JsonRpcErrorCode.RateLimited:
+            status = 429;
+            break;
+        default:
+            status = 500;
+    }
+    logger.debug(`Mapping error to HTTP status ${status}.`, {
+        ...context,
+        status,
+        errorCode,
+    });
+    // Attempt to get the request ID from the body, but don't fail if it's not there or unreadable.
+    let requestId = null;
+    // Only attempt to read the body if it hasn't been consumed already.
+    if (c.req.raw.bodyUsed === false) {
+        try {
+            const body = await c.req.json();
+            const id = getProperty(body, 'id');
+            requestId = typeof id === 'string' || typeof id === 'number' ? id : null;
+            logger.debug('Extracted JSON-RPC request ID from body.', {
+                ...context,
+                jsonRpcId: requestId,
+            });
+        }
+        catch {
+            logger.warning('Could not parse request body to extract JSON-RPC ID.', context);
+            // Ignore parsing errors, requestId will remain null
+        }
+    }
+    else {
+        logger.debug('Request body already consumed, cannot extract JSON-RPC ID.', context);
+    }
+    c.status(status);
+    const errorResponse = {
+        jsonrpc: '2.0',
+        error: {
+            code: errorCode,
+            message: handledError.message,
+        },
+        id: requestId,
+    };
+    logger.info(`Sending formatted error response for request.`, {
+        ...context,
+        status,
+        errorCode,
+        jsonRpcId: requestId,
+    });
+    return c.json(errorResponse);
+};
+//# sourceMappingURL=httpErrorHandler.js.map

package/dist/mcp-server/transports/http/httpErrorHandler.js.map

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

package/dist/mcp-server/transports/http/httpTransport.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Configures and starts the HTTP MCP transport using Hono.
+ * This implementation uses the official @hono/mcp package for a fully
+ * web-standard, platform-agnostic transport layer.
+ *
+ * Implements MCP Specification 2025-06-18 Streamable HTTP Transport.
+ * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http | MCP Streamable HTTP Transport}
+ * @module src/mcp-server/transports/http/httpTransport
+ */
+import { type ServerType } from '@hono/node-server';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Hono } from 'hono';
+import type { HonoNodeBindings } from '../../../mcp-server/transports/http/httpTypes.js';
+import { SessionStore } from '../../../mcp-server/transports/http/sessionStore.js';
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+/**
+ * Creates a Hono HTTP application for the MCP server.
+ *
+ * This function is generic and can create apps with different binding types:
+ * - Node.js environments use HonoNodeBindings (default)
+ * - Cloudflare Workers use CloudflareBindings
+ *
+ * The function itself doesn't access bindings; they're only used at runtime
+ * when the app processes requests in its specific environment.
+ *
+ * @template TBindings - The Hono binding type (must extend object, defaults to HonoNodeBindings for Node.js)
+ * @param mcpServer - The MCP server instance
+ * @param parentContext - Parent request context for logging
+ * @returns Configured Hono application with the specified binding type
+ */
+export declare function createHttpApp<TBindings extends object = HonoNodeBindings>(serverFactory: () => Promise<McpServer>, parentContext: RequestContext): Promise<{
+    app: Hono<{
+        Bindings: TBindings;
+    }>;
+    sessionStore: SessionStore | null;
+}>;
+/**
+ * Handle returned by {@link startHttpTransport} bundling the HTTP server
+ * and a shutdown function that cleans up all associated resources
+ * (session store intervals, etc.).
+ */
+export interface HttpTransportHandle {
+    server: ServerType;
+    stop: (parentContext: RequestContext) => Promise<void>;
+}
+export declare function startHttpTransport(serverFactory: () => Promise<McpServer>, parentContext: RequestContext): Promise<HttpTransportHandle>;
+//# sourceMappingURL=httpTransport.d.ts.map

package/dist/mcp-server/transports/http/httpTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpTransport.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/http/httpTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAS,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAQ5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAGlF,OAAO,EAAwB,YAAY,EAAE,MAAM,8CAA8C,CAAC;AAGlG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAgBzE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CAAC,SAAS,SAAS,MAAM,GAAG,gBAAgB,EAC7E,aAAa,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EACvC,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC;IAAE,GAAG,EAAE,IAAI,CAAC;QAAE,QAAQ,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,CAAC,CAqTpF;AA+ED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,CAAC,aAAa,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EACvC,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAuB9B"}