@cyanheads/git-mcp-server 2.1.3 → 2.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-2.1.3-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-2.1.4-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/git-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/git-mcp-server?style=social)](https://github.com/cyanheads/git-mcp-server)
@@ -29,10 +29,9 @@ This server equips your AI with a comprehensive suite of tools to interact with
 
 ## Table of Contents
 
-| [Overview](#overview)           | [Features](#features)                   | [Installation](#installation) |
-| :------------------------------ | :-------------------------------------- | :---------------------------- | ------------------- |
+| [Overview](#overview) | [Features](#features) | [Installation](#installation) |
 | [Configuration](#configuration) | [Project Structure](#project-structure) |
-| [Tools](#tools)                 | [Resources](#resources)                 | [Development](#development)   | [License](#license) |
+| [Tools](#tools) | [Resources](#resources) | [Development](#development) | [License](#license) |
 
 ## Overview
 
@@ -61,7 +60,7 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 - **Input Validation/Sanitization**: Uses `zod` for schema validation and custom sanitization logic (crucial for paths).
 - **Request Context**: Tracking and correlation of operations via unique request IDs using `AsyncLocalStorage`.
 - **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.
-- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management with garbage collection, CORS, and IP-based rate limiting.
+- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management, CORS, and authentication support.
 - **Deployment**: Multi-stage `Dockerfile` for creating small, secure production images with native dependency support.
 
 ### Git Integration
@@ -100,7 +99,7 @@ Add the following to your MCP client's configuration file (e.g., `cline_mcp_sett
 }
 ```
 
-### If running manually (not via MCP client for development or testing)
+### If running manually (not via MCP client) for development or testing
 
 #### Install via npm
 
@@ -143,7 +142,10 @@ Configure the server using environment variables. These environmental variables
 | `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).                                                      | (none)      |
 | `MCP_LOG_LEVEL`       | Logging level (`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). Inherited from template.                     | `info`      |
 | `GIT_SIGN_COMMITS`    | Set to `"true"` to enable signing attempts for commits made by the `git_commit` tool. Requires server-side Git/key setup (see below). | `false`     |
-| `MCP_AUTH_SECRET_KEY` | Secret key for signing/verifying authentication tokens (required if auth is enabled in the future).                                   | `''`        |
+| `MCP_AUTH_MODE`       | Authentication mode: `jwt`, `oauth`, or `none`.                                                                                       | `none`      |
+| `MCP_AUTH_SECRET_KEY` | Secret key for JWT validation (if `MCP_AUTH_MODE=jwt`).                                                                               | `''`        |
+| `OAUTH_ISSUER_URL`    | OIDC issuer URL for OAuth validation (if `MCP_AUTH_MODE=oauth`).                                                                      | `''`        |
+| `OAUTH_AUDIENCE`      | Audience claim for OAuth validation (if `MCP_AUTH_MODE=oauth`).                                                                       | `''`        |
 
 ## Project Structure
 
@@ -201,7 +203,7 @@ _Note: The `path` parameter for most tools defaults to the session's working dir
 
 ## Resources
 
-**MCP Resources are not implemented in this version (v2.1.2).**
+**MCP Resources are not implemented in this version (v2.1.4).**
 
 This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.13.0. Resource capabilities, previously available, have been temporarily removed during this major update.
 

package/dist/config/index.js

@@ -40,14 +40,22 @@ export const config = {
     mcpAllowedOrigins: process.env.MCP_ALLOWED_ORIGINS?.split(",") || [],
     /** Flag to enable GPG signing for commits made by the git_commit tool. Requires server-side GPG setup. */
     gitSignCommits: process.env.GIT_SIGN_COMMITS === "true",
+    /** The authentication mode ('jwt', 'oauth', or 'none'). Defaults to 'none'. */
+    mcpAuthMode: process.env.MCP_AUTH_MODE || "none",
+    /** Secret key for signing/verifying JWTs. Required if mcpAuthMode is 'jwt'. */
+    mcpAuthSecretKey: process.env.MCP_AUTH_SECRET_KEY,
+    /** The OIDC issuer URL for OAuth token validation. Required if mcpAuthMode is 'oauth'. */
+    oauthIssuerUrl: process.env.OAUTH_ISSUER_URL,
+    /** The audience claim for OAuth token validation. Required if mcpAuthMode is 'oauth'. */
+    oauthAudience: process.env.OAUTH_AUDIENCE,
+    /** The JWKS URI for fetching public keys for OAuth. Optional, can be derived from issuer URL. */
+    oauthJwksUri: process.env.OAUTH_JWKS_URI,
     /** Security-related configurations. */
     security: {
         // Placeholder for security settings
         // Example: authRequired: process.env.AUTH_REQUIRED === 'true'
         /** Indicates if authentication is required for server operations. */
         authRequired: false,
-        /** Secret key for signing/verifying authentication tokens (required if authRequired is true). */
-        mcpAuthSecretKey: process.env.MCP_AUTH_SECRET_KEY || "", // Default to empty string, validation should happen elsewhere
     },
     // Note: mcpClient configuration is now loaded separately from mcp-config.json
 };

package/dist/mcp-server/server.js

@@ -43,9 +43,9 @@ import { initializeGitStatusStateAccessors, registerGitStatusTool, } from "./too
 import { initializeGitTagStateAccessors, registerGitTagTool, } from "./tools/gitTag/index.js";
 import { initializeGitWorktreeStateAccessors, registerGitWorktreeTool, } from "./tools/gitWorktree/index.js";
 import { initializeGitWrapupInstructionsStateAccessors, registerGitWrapupInstructionsTool, } from "./tools/gitWrapupInstructions/index.js";
-// Import transport setup functions AND state accessors
-import { getHttpSessionWorkingDirectory, setHttpSessionWorkingDirectory, startHttpTransport, } from "./transports/httpTransport.js";
-import { connectStdioTransport, getStdioWorkingDirectory, setStdioWorkingDirectory, } from "./transports/stdioTransport.js";
+// Import transport setup functions
+import { startHttpTransport } from "./transports/httpTransport.js";
+import { connectStdioTransport } from "./transports/stdioTransport.js";
 /**
  * Creates and configures a new instance of the McpServer.
  *
@@ -79,7 +79,9 @@ import { connectStdioTransport, getStdioWorkingDirectory, setStdioWorkingDirecto
  */
 // Removed sessionId parameter, it will be retrieved from context within tool handlers
 async function createMcpServerInstance() {
-    const context = { operation: "createMcpServerInstance" };
+    const context = requestContextService.createRequestContext({
+        operation: "createMcpServerInstance",
+    });
     logger.info("Initializing MCP server instance", context);
     // Configure the request context service (used for correlating logs/errors).
     requestContextService.configure({
@@ -110,6 +112,9 @@ async function createMcpServerInstance() {
             tools: { listChanged: true },
         },
     });
+    // Each server instance is isolated per session. This variable will hold the
+    // working directory for the duration of this session.
+    let sessionWorkingDirectory = undefined;
     // --- Define Unified State Accessor Functions ---
     // These functions abstract away the transport type to get/set session state.
     /** Gets the session ID from the tool's execution context. */
@@ -117,34 +122,21 @@ async function createMcpServerInstance() {
         // The RequestContext created by the tool registration wrapper should contain the sessionId.
         return toolContext?.sessionId;
     };
-    /** Gets the working directory based on transport type and session ID. */
+    /** Gets the working directory for the current session. */
     const getWorkingDirectory = (sessionId) => {
-        if (config.mcpTransportType === "http") {
-            if (!sessionId) {
-                logger.warning("Attempted to get HTTP working directory without session ID", { ...context, caller: "getWorkingDirectory" });
-                return undefined;
-            }
-            return getHttpSessionWorkingDirectory(sessionId);
-        }
-        else {
-            // For stdio, there's only one implicit session, ID is not needed.
-            return getStdioWorkingDirectory();
-        }
+        // The working directory is now stored in a variable scoped to this server instance.
+        // The sessionId is kept for potential logging or more complex future state management.
+        return sessionWorkingDirectory;
     };
-    /** Sets the working directory based on transport type and session ID. */
+    /** Sets the working directory for the current session. */
     const setWorkingDirectory = (sessionId, dir) => {
-        if (config.mcpTransportType === "http") {
-            if (!sessionId) {
-                logger.error("Attempted to set HTTP working directory without session ID", { ...context, caller: "setWorkingDirectory", dir });
-                // Optionally throw an error or just log
-                return;
-            }
-            setHttpSessionWorkingDirectory(sessionId, dir);
-        }
-        else {
-            // For stdio, set the single session's directory.
-            setStdioWorkingDirectory(dir);
-        }
+        // The working directory is now stored in a variable scoped to this server instance.
+        logger.debug("Setting session working directory", {
+            ...context,
+            sessionId,
+            newDirectory: dir,
+        });
+        sessionWorkingDirectory = dir;
     };
     // --- Initialize Tool State Accessors BEFORE Registration ---
     // Pass the defined unified accessor functions to the initializers.
@@ -254,7 +246,10 @@ async function createMcpServerInstance() {
 async function startTransport() {
     // Determine the transport type from the validated configuration.
     const transportType = config.mcpTransportType;
-    const context = { operation: "startTransport", transport: transportType };
+    const context = requestContextService.createRequestContext({
+        operation: "startTransport",
+        transport: transportType,
+    });
     logger.info(`Starting transport: ${transportType}`, context);
     // --- HTTP Transport Setup ---
     if (transportType === "http") {
@@ -294,7 +289,9 @@ async function startTransport() {
  * @returns {Promise<void | McpServer>} Resolves upon successful startup (void for http, McpServer for stdio). Rejects on critical failure.
  */
 export async function initializeAndStartServer() {
-    const context = { operation: "initializeAndStartServer" };
+    const context = requestContextService.createRequestContext({
+        operation: "initializeAndStartServer",
+    });
     logger.info("MCP Server initialization sequence started.", context);
     try {
         // Initiate the transport setup based on configuration.
@@ -310,7 +307,11 @@ export async function initializeAndStartServer() {
             stack: err instanceof Error ? err.stack : undefined,
         });
         // Use the centralized error handler for consistent critical error reporting.
-        ErrorHandler.handleError(err, { ...context, critical: true });
+        ErrorHandler.handleError(err, {
+            ...context,
+            operation: "initializeAndStartServer_Catch",
+            critical: true,
+        });
         // Exit the process with a non-zero code to indicate failure.
         logger.info("Exiting process due to critical initialization error.", context);
         process.exit(1);

package/dist/mcp-server/transports/auth/core/authContext.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Defines the AsyncLocalStorage context for authentication information.
+ * This module provides a mechanism to store and retrieve authentication details
+ * (like scopes and client ID) across asynchronous operations, making it available
+ * from the middleware layer down to the tool and resource handlers without
+ * drilling props.
+ *
+ * @module src/mcp-server/transports/auth/core/authContext
+ */
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * An instance of AsyncLocalStorage to hold the authentication context (`AuthStore`).
+ * This allows `authInfo` to be accessible throughout the async call chain of a request
+ * after being set in the authentication middleware.
+ *
+ * @example
+ * // In middleware:
+ * await authContext.run({ authInfo }, next);
+ *
+ * // In a deeper handler:
+ * const store = authContext.getStore();
+ * const scopes = store?.authInfo.scopes;
+ */
+export const authContext = new AsyncLocalStorage();

package/dist/mcp-server/transports/auth/core/authTypes.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Shared types for authentication middleware.
+ * @module src/mcp-server/transports/auth/core/auth.types
+ */
+export {};

package/dist/mcp-server/transports/auth/core/authUtils.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Provides utility functions for authorization, specifically for
+ * checking token scopes against required permissions for a given operation.
+ * @module src/mcp-server/transports/auth/core/authUtils
+ */
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { logger, requestContextService } from "../../../../utils/index.js";
+import { authContext } from "./authContext.js";
+/**
+ * Checks if the current authentication context contains all the specified scopes.
+ * This function is designed to be called within tool or resource handlers to
+ * enforce scope-based access control. It retrieves the authentication information
+ * from `authContext` (AsyncLocalStorage).
+ *
+ * @param requiredScopes - An array of scope strings that are mandatory for the operation.
+ * @throws {McpError} Throws an error with `BaseErrorCode.INTERNAL_ERROR` if the
+ *   authentication context is missing, which indicates a server configuration issue.
+ * @throws {McpError} Throws an error with `BaseErrorCode.FORBIDDEN` if one or
+ *   more required scopes are not present in the validated token.
+ */
+export function withRequiredScopes(requiredScopes) {
+    const store = authContext.getStore();
+    if (!store || !store.authInfo) {
+        // This is a server-side logic error; the auth middleware should always populate this.
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Authentication context is missing. This indicates a server configuration error.", requestContextService.createRequestContext({
+            operation: "withRequiredScopesCheck",
+            error: "AuthStore not found in AsyncLocalStorage.",
+        }));
+    }
+    const { scopes: grantedScopes, clientId } = store.authInfo;
+    const grantedScopeSet = new Set(grantedScopes);
+    const missingScopes = requiredScopes.filter((scope) => !grantedScopeSet.has(scope));
+    if (missingScopes.length > 0) {
+        const context = requestContextService.createRequestContext({
+            operation: "withRequiredScopesCheck",
+            required: requiredScopes,
+            granted: grantedScopes,
+            missing: missingScopes,
+            clientId: clientId,
+            subject: store.authInfo.subject,
+        });
+        logger.warning("Authorization failed: Missing required scopes.", context);
+        throw new McpError(BaseErrorCode.FORBIDDEN, `Insufficient permissions. Missing required scopes: ${missingScopes.join(", ")}`, { requiredScopes, missingScopes });
+    }
+}

package/dist/mcp-server/transports/auth/index.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel file for the auth module.
+ * Exports core utilities and middleware strategies for easier imports.
+ * @module src/mcp-server/transports/auth/index
+ */
+export { authContext } from "./core/authContext.js";
+export { withRequiredScopes } from "./core/authUtils.js";
+export { mcpAuthMiddleware as jwtAuthMiddleware } from "./strategies/jwt/jwtMiddleware.js";
+export { oauthMiddleware } from "./strategies/oauth/oauthMiddleware.js";

package/dist/mcp-server/transports/auth/strategies/jwt/jwtMiddleware.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview MCP Authentication Middleware for Bearer Token Validation (JWT) for Hono.
+ *
+ * This middleware validates JSON Web Tokens (JWT) passed via the 'Authorization' header
+ * using the 'Bearer' scheme (e.g., "Authorization: Bearer <your_token>").
+ * It verifies the token's signature and expiration using the secret key defined
+ * in the configuration (`config.mcpAuthSecretKey`).
+ *
+ * If the token is valid, an object conforming to the MCP SDK's `AuthInfo` type
+ * is attached to `c.env.incoming.auth`. This direct attachment to the raw Node.js
+ * request object is for compatibility with the underlying SDK transport, which is
+ * not Hono-context-aware.
+ * If the token is missing, invalid, or expired, it throws an `McpError`, which is
+ * then handled by the centralized `httpErrorHandler`.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ * @module src/mcp-server/transports/auth/strategies/jwt/jwtMiddleware
+ */
+import { jwtVerify } from "jose";
+import { config, environment } from "../../../../../config/index.js";
+import { logger, requestContextService } from "../../../../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../../../types-global/errors.js";
+import { authContext } from "../../core/authContext.js";
+// Startup Validation: Validate secret key presence on module load.
+if (config.mcpAuthMode === "jwt") {
+    if (environment === "production" && !config.mcpAuthSecretKey) {
+        logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment for JWT auth. Authentication cannot proceed securely.");
+        throw new Error("MCP_AUTH_SECRET_KEY must be set in production environment for JWT authentication.");
+    }
+    else if (!config.mcpAuthSecretKey) {
+        logger.warning("MCP_AUTH_SECRET_KEY is not set. JWT auth middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.");
+    }
+}
+/**
+ * Hono middleware for verifying JWT Bearer token authentication.
+ * It attaches authentication info to `c.env.incoming.auth` for SDK compatibility with the node server.
+ */
+export async function mcpAuthMiddleware(c, next) {
+    const context = requestContextService.createRequestContext({
+        operation: "mcpAuthMiddleware",
+        method: c.req.method,
+        path: c.req.path,
+    });
+    logger.debug("Running MCP Authentication Middleware (Bearer Token Validation)...", context);
+    const reqWithAuth = c.env.incoming;
+    // If JWT auth is not enabled, skip the middleware.
+    if (config.mcpAuthMode !== "jwt") {
+        return await next();
+    }
+    // Development Mode Bypass
+    if (!config.mcpAuthSecretKey) {
+        if (environment !== "production") {
+            logger.warning("Bypassing JWT authentication: MCP_AUTH_SECRET_KEY is not set (DEVELOPMENT ONLY).", context);
+            reqWithAuth.auth = {
+                token: "dev-mode-placeholder-token",
+                clientId: "dev-client-id",
+                scopes: ["dev-scope"],
+            };
+            const authInfo = reqWithAuth.auth;
+            logger.debug("Dev mode auth object created.", {
+                ...context,
+                authDetails: authInfo,
+            });
+            return await authContext.run({ authInfo }, next);
+        }
+        else {
+            logger.error("FATAL: MCP_AUTH_SECRET_KEY is missing in production. Cannot bypass auth.", context);
+            throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Server configuration error: Authentication key missing.");
+        }
+    }
+    const secretKey = new TextEncoder().encode(config.mcpAuthSecretKey);
+    const authHeader = c.req.header("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        logger.warning("Authentication failed: Missing or malformed Authorization header (Bearer scheme required).", context);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid authentication token format.");
+    }
+    const tokenParts = authHeader.split(" ");
+    if (tokenParts.length !== 2 || tokenParts[0] !== "Bearer" || !tokenParts[1]) {
+        logger.warning("Authentication failed: Malformed Bearer token.", context);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Malformed authentication token.");
+    }
+    const rawToken = tokenParts[1];
+    try {
+        const { payload: decoded } = await jwtVerify(rawToken, secretKey);
+        const clientIdFromToken = typeof decoded.cid === "string"
+            ? decoded.cid
+            : typeof decoded.client_id === "string"
+                ? decoded.client_id
+                : undefined;
+        if (!clientIdFromToken) {
+            logger.warning("Authentication failed: JWT 'cid' or 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token, missing client identifier.");
+        }
+        let scopesFromToken = [];
+        if (Array.isArray(decoded.scp) &&
+            decoded.scp.every((s) => typeof s === "string")) {
+            scopesFromToken = decoded.scp;
+        }
+        else if (typeof decoded.scope === "string" &&
+            decoded.scope.trim() !== "") {
+            scopesFromToken = decoded.scope.split(" ").filter((s) => s);
+            if (scopesFromToken.length === 0 && decoded.scope.trim() !== "") {
+                scopesFromToken = [decoded.scope.trim()];
+            }
+        }
+        if (scopesFromToken.length === 0) {
+            logger.warning("Authentication failed: Token resulted in an empty scope array, and scopes are required.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.");
+        }
+        reqWithAuth.auth = {
+            token: rawToken,
+            clientId: clientIdFromToken,
+            scopes: scopesFromToken,
+        };
+        const subClaimForLogging = typeof decoded.sub === "string" ? decoded.sub : undefined;
+        const authInfo = reqWithAuth.auth;
+        logger.debug("JWT verified successfully. AuthInfo attached to request.", {
+            ...context,
+            mcpSessionIdContext: subClaimForLogging,
+            clientId: authInfo.clientId,
+            scopes: authInfo.scopes,
+        });
+        await authContext.run({ authInfo }, next);
+    }
+    catch (error) {
+        let errorMessage = "Invalid token.";
+        let errorCode = BaseErrorCode.UNAUTHORIZED;
+        if (error instanceof Error && error.name === "JWTExpired") {
+            errorMessage = "Token expired.";
+            logger.warning("Authentication failed: Token expired.", {
+                ...context,
+                errorName: error.name,
+            });
+        }
+        else if (error instanceof Error) {
+            errorMessage = `Invalid token: ${error.message}`;
+            logger.warning(`Authentication failed: ${errorMessage}`, {
+                ...context,
+                errorName: error.name,
+            });
+        }
+        else {
+            errorMessage = "Unknown verification error.";
+            errorCode = BaseErrorCode.INTERNAL_ERROR;
+            logger.error("Authentication failed: Unexpected non-error exception during token verification.", { ...context, error });
+        }
+        throw new McpError(errorCode, errorMessage);
+    }
+}

package/dist/mcp-server/transports/auth/strategies/oauth/oauthMiddleware.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Hono middleware for OAuth 2.1 Bearer Token validation.
+ * This middleware extracts a JWT from the Authorization header, validates it against
+ * a remote JWKS (JSON Web Key Set), and checks its issuer and audience claims.
+ * On success, it populates an AuthInfo object and stores it in an AsyncLocalStorage
+ * context for use in downstream handlers.
+ *
+ * @module src/mcp-server/transports/auth/strategies/oauth/oauthMiddleware
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { config } from "../../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../../types-global/errors.js";
+import { ErrorHandler } from "../../../../../utils/internal/errorHandler.js";
+import { logger, requestContextService } from "../../../../../utils/index.js";
+import { authContext } from "../../core/authContext.js";
+// --- Startup Validation ---
+// Ensures that necessary OAuth configuration is present when the mode is 'oauth'.
+if (config.mcpAuthMode === "oauth") {
+    if (!config.oauthIssuerUrl) {
+        throw new Error("OAUTH_ISSUER_URL must be set when MCP_AUTH_MODE is 'oauth'");
+    }
+    if (!config.oauthAudience) {
+        throw new Error("OAUTH_AUDIENCE must be set when MCP_AUTH_MODE is 'oauth'");
+    }
+    logger.info("OAuth 2.1 mode enabled. Verifying tokens against issuer.", requestContextService.createRequestContext({
+        issuer: config.oauthIssuerUrl,
+        audience: config.oauthAudience,
+    }));
+}
+// --- JWKS Client Initialization ---
+// The remote JWK set is fetched and cached to avoid network calls on every request.
+let jwks;
+if (config.mcpAuthMode === "oauth" && config.oauthIssuerUrl) {
+    try {
+        const jwksUrl = new URL(config.oauthJwksUri ||
+            `${config.oauthIssuerUrl.replace(/\/$/, "")}/.well-known/jwks.json`);
+        jwks = createRemoteJWKSet(jwksUrl, {
+            cooldownDuration: 300000, // 5 minutes
+            timeoutDuration: 5000, // 5 seconds
+        });
+        logger.info(`JWKS client initialized for URL: ${jwksUrl.href}`, requestContextService.createRequestContext({
+            operation: "oauthMiddlewareSetup",
+        }));
+    }
+    catch (error) {
+        logger.fatal("Failed to initialize JWKS client.", {
+            error: error,
+            context: requestContextService.createRequestContext({
+                operation: "oauthMiddlewareSetup",
+            }),
+        });
+        // Prevent server from starting if JWKS setup fails in oauth mode
+        process.exit(1);
+    }
+}
+/**
+ * Hono middleware for verifying OAuth 2.1 JWT Bearer tokens.
+ * It validates the token and uses AsyncLocalStorage to pass auth info.
+ * @param c - The Hono context object.
+ * @param next - The function to call to proceed to the next middleware.
+ */
+export async function oauthMiddleware(c, next) {
+    // If OAuth is not the configured auth mode, skip this middleware.
+    if (config.mcpAuthMode !== "oauth") {
+        return await next();
+    }
+    const context = requestContextService.createRequestContext({
+        operation: "oauthMiddleware",
+        httpMethod: c.req.method,
+        httpPath: c.req.path,
+    });
+    if (!jwks) {
+        // This should not happen if startup validation is correct, but it's a safeguard.
+        // This should not happen if startup validation is correct, but it's a safeguard.
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAuth middleware is active, but JWKS client is not initialized.", context);
+    }
+    const authHeader = c.req.header("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid token format.");
+    }
+    const token = authHeader.substring(7);
+    try {
+        const { payload } = await jwtVerify(token, jwks, {
+            issuer: config.oauthIssuerUrl,
+            audience: config.oauthAudience,
+        });
+        // The 'scope' claim is typically a space-delimited string in OAuth 2.1.
+        const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+        if (scopes.length === 0) {
+            logger.warning("Authentication failed: Token contains no scopes, but scopes are required.", { ...context, jwtPayloadKeys: Object.keys(payload) });
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.");
+        }
+        const clientId = typeof payload.client_id === "string" ? payload.client_id : undefined;
+        if (!clientId) {
+            logger.warning("Authentication failed: OAuth token 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(payload) });
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token, missing client identifier.");
+        }
+        const authInfo = {
+            token,
+            clientId,
+            scopes,
+            subject: typeof payload.sub === "string" ? payload.sub : undefined,
+        };
+        // Attach to the raw request for potential legacy compatibility and
+        // store in AsyncLocalStorage for modern, safe access in handlers.
+        c.env.incoming.auth = authInfo;
+        await authContext.run({ authInfo }, next);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "JWTExpired") {
+            logger.warning("Authentication failed: OAuth token expired.", context);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token expired.");
+        }
+        const handledError = ErrorHandler.handleError(error, {
+            operation: "oauthMiddleware",
+            context,
+            rethrow: false, // We will throw a new McpError below
+        });
+        // Ensure we always throw an McpError for consistency
+        if (handledError instanceof McpError) {
+            throw handledError;
+        }
+        else {
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, `Unauthorized: ${handledError.message || "Invalid token"}`, { originalError: handledError.name });
+        }
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * @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/httpErrorHandler
+ */
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { ErrorHandler, requestContextService } from "../../utils/index.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.
+ *
+ * @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",
+        path: c.req.path,
+        method: c.req.method,
+    });
+    const handledError = ErrorHandler.handleError(err, {
+        operation: "httpTransport",
+        context,
+    });
+    let status = 500;
+    if (handledError instanceof McpError) {
+        switch (handledError.code) {
+            case BaseErrorCode.NOT_FOUND:
+                status = 404;
+                break;
+            case BaseErrorCode.UNAUTHORIZED:
+                status = 401;
+                break;
+            case BaseErrorCode.FORBIDDEN:
+                status = 403;
+                break;
+            case BaseErrorCode.VALIDATION_ERROR:
+                status = 400;
+                break;
+            case BaseErrorCode.CONFLICT:
+                status = 409;
+                break;
+            case BaseErrorCode.RATE_LIMITED:
+                status = 429;
+                break;
+            default:
+                status = 500;
+        }
+    }
+    // Attempt to get the request ID from the body, but don't fail if it's not there or unreadable.
+    let requestId = null;
+    try {
+        const body = await c.req.json();
+        requestId = body?.id || null;
+    }
+    catch {
+        // Ignore parsing errors, requestId will remain null
+    }
+    const errorCode = handledError instanceof McpError ? handledError.code : -32603;
+    c.status(status);
+    return c.json({
+        jsonrpc: "2.0",
+        error: {
+            code: errorCode,
+            message: handledError.message,
+        },
+        id: requestId,
+    });
+};