@cyanheads/git-mcp-server 2.2.2 → 2.2.3

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

@@ -1,149 +0,0 @@
-/**
- * @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

@@ -1,127 +0,0 @@
-/**
- * @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/httpTransport.js

@@ -1,207 +0,0 @@
-/**
- * @fileoverview Configures and starts the Streamable HTTP MCP transport using Hono.
- * This module integrates the `@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport`
- * into a Hono web server. Its responsibilities include:
- * - Creating a Hono server instance.
- * - Applying and configuring middleware for CORS, rate limiting, and authentication (JWT/OAuth).
- * - Defining the routes (`/mcp` endpoint for POST, GET, DELETE) to handle the MCP lifecycle.
- * - Orchestrating session management by mapping session IDs to SDK transport instances.
- * - Implementing port-binding logic with automatic retry on conflicts.
- *
- * The underlying implementation of the MCP Streamable HTTP specification, including
- * Server-Sent Events (SSE) for streaming, is handled by the SDK's transport class.
- *
- * Specification Reference:
- * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#streamable-http
- * @module src/mcp-server/transports/httpTransport
- */
-import { serve } from "@hono/node-server";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { Hono } from "hono";
-import { cors } from "hono/cors";
-import http from "http";
-import { randomUUID } from "node:crypto";
-import { config } from "../../config/index.js";
-import { BaseErrorCode, McpError } from "../../types-global/errors.js";
-import { logger, rateLimiter, requestContextService, } from "../../utils/index.js";
-import { jwtAuthMiddleware, oauthMiddleware, } from "./auth/index.js";
-import { httpErrorHandler } from "./httpErrorHandler.js";
-const HTTP_PORT = config.mcpHttpPort;
-const HTTP_HOST = config.mcpHttpHost;
-const MCP_ENDPOINT_PATH = "/mcp";
-const MAX_PORT_RETRIES = 15;
-// The transports map will store active sessions, keyed by session ID.
-// NOTE: This is an in-memory session store, which is a known limitation for scalability.
-// It will not work in a multi-process (clustered) or serverless environment.
-// For a scalable deployment, this would need to be replaced with a distributed
-// store like Redis or Memcached.
-const transports = {};
-async function isPortInUse(port, host, parentContext) {
-    requestContextService.createRequestContext({
-        ...parentContext,
-        operation: "isPortInUse",
-        port,
-        host,
-    });
-    return new Promise((resolve) => {
-        const tempServer = http.createServer();
-        tempServer
-            .once("error", (err) => {
-            resolve(err.code === "EADDRINUSE");
-        })
-            .once("listening", () => {
-            tempServer.close(() => resolve(false));
-        })
-            .listen(port, host);
-    });
-}
-function startHttpServerWithRetry(app, initialPort, host, maxRetries, parentContext) {
-    const startContext = requestContextService.createRequestContext({
-        ...parentContext,
-        operation: "startHttpServerWithRetry",
-    });
-    return new Promise(async (resolve, reject) => {
-        for (let i = 0; i <= maxRetries; i++) {
-            const currentPort = initialPort + i;
-            const attemptContext = {
-                ...startContext,
-                port: currentPort,
-                attempt: i + 1,
-            };
-            if (await isPortInUse(currentPort, host, attemptContext)) {
-                logger.warning(`Port ${currentPort} is in use, retrying...`, attemptContext);
-                continue;
-            }
-            try {
-                const serverInstance = serve({ fetch: app.fetch, port: currentPort, hostname: host }, (info) => {
-                    const serverAddress = `http://${info.address}:${info.port}${MCP_ENDPOINT_PATH}`;
-                    logger.info(`HTTP transport listening at ${serverAddress}`, {
-                        ...attemptContext,
-                        address: serverAddress,
-                    });
-                    if (process.stdout.isTTY) {
-                        console.log(`\n🚀 MCP Server running at: ${serverAddress}\n`);
-                    }
-                });
-                resolve(serverInstance);
-                return;
-            }
-            catch (err) {
-                if (err.code !== "EADDRINUSE") {
-                    reject(err);
-                    return;
-                }
-            }
-        }
-        reject(new Error("Failed to bind to any port after multiple retries."));
-    });
-}
-export async function startHttpTransport(server, parentContext) {
-    const app = new Hono();
-    const transportContext = requestContextService.createRequestContext({
-        ...parentContext,
-        component: "HttpTransportSetup",
-    });
-    app.use("*", cors({
-        origin: config.mcpAllowedOrigins || [],
-        allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
-        allowHeaders: [
-            "Content-Type",
-            "Mcp-Session-Id",
-            "Last-Event-ID",
-            "Authorization",
-        ],
-        credentials: true,
-    }));
-    app.use("*", async (c, next) => {
-        c.res.headers.set("X-Content-Type-Options", "nosniff");
-        await next();
-    });
-    app.use(MCP_ENDPOINT_PATH, async (c, next) => {
-        // NOTE (Security): The 'x-forwarded-for' header is used for rate limiting.
-        // This is only secure if the server is run behind a trusted proxy that
-        // correctly sets or validates this header.
-        const clientIp = c.req.header("x-forwarded-for")?.split(",")[0].trim() || "unknown_ip";
-        const context = requestContextService.createRequestContext({
-            operation: "httpRateLimitCheck",
-            ipAddress: clientIp,
-        });
-        // Let the centralized error handler catch rate limit errors
-        rateLimiter.check(clientIp, context);
-        await next();
-    });
-    if (config.mcpAuthMode === "oauth") {
-        app.use(MCP_ENDPOINT_PATH, oauthMiddleware);
-    }
-    else {
-        app.use(MCP_ENDPOINT_PATH, jwtAuthMiddleware);
-    }
-    // Centralized Error Handling
-    app.onError(httpErrorHandler);
-    app.post(MCP_ENDPOINT_PATH, async (c) => {
-        const postContext = requestContextService.createRequestContext({
-            ...transportContext,
-            operation: "handlePost",
-        });
-        const body = await c.req.json();
-        const sessionId = c.req.header("mcp-session-id");
-        let transport = sessionId
-            ? transports[sessionId]
-            : undefined;
-        if (isInitializeRequest(body)) {
-            // If a transport already exists for a session, it's a re-initialization.
-            if (transport) {
-                logger.warning("Re-initializing existing session.", {
-                    ...postContext,
-                    sessionId,
-                });
-                await transport.close(); // This will trigger the onclose handler.
-            }
-            // Create a new transport for a new session.
-            const newTransport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => randomUUID(),
-                onsessioninitialized: (newId) => {
-                    transports[newId] = newTransport;
-                    logger.info(`HTTP Session created: ${newId}`, {
-                        ...postContext,
-                        newSessionId: newId,
-                    });
-                },
-            });
-            // Set up cleanup logic for when the transport is closed.
-            newTransport.onclose = () => {
-                const closedSessionId = newTransport.sessionId;
-                if (closedSessionId && transports[closedSessionId]) {
-                    delete transports[closedSessionId];
-                    logger.info(`HTTP Session closed: ${closedSessionId}`, {
-                        ...postContext,
-                        closedSessionId,
-                    });
-                }
-            };
-            // Connect the new transport to the existing server instance.
-            await server.connect(newTransport);
-            transport = newTransport;
-        }
-        else if (!transport) {
-            // If it's not an initialization request and no transport was found, it's an error.
-            throw new McpError(BaseErrorCode.NOT_FOUND, "Invalid or expired session ID.");
-        }
-        // Pass the request to the transport to handle.
-        return await transport.handleRequest(c.env.incoming, c.env.outgoing, body);
-    });
-    // A reusable handler for GET and DELETE requests which operate on existing sessions.
-    const handleSessionRequest = async (c) => {
-        const sessionId = c.req.header("mcp-session-id");
-        const transport = sessionId ? transports[sessionId] : undefined;
-        if (!transport) {
-            throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.");
-        }
-        // Let the transport handle the streaming (GET) or termination (DELETE) request.
-        return await transport.handleRequest(c.env.incoming, c.env.outgoing);
-    };
-    app.get(MCP_ENDPOINT_PATH, handleSessionRequest);
-    app.delete(MCP_ENDPOINT_PATH, handleSessionRequest);
-    return startHttpServerWithRetry(app, HTTP_PORT, HTTP_HOST, MAX_PORT_RETRIES, transportContext);
-}