@cyanheads/git-mcp-server 2.2.2 → 2.2.3

package/dist/mcp-server/tools/gitCherryPick/logic.js

@@ -7,6 +7,7 @@ import { promisify } from "util";
 import { z } from "zod";
 import { logger, sanitization } from "../../../utils/index.js";
 import { McpError, BaseErrorCode } from "../../../types-global/errors.js";
+import { config } from "../../../config/index.js";
 const execFileAsync = promisify(execFile);
 // 1. DEFINE the Zod input schema.
 export const GitCherryPickInputSchema = z.object({
@@ -36,21 +37,46 @@ export async function gitCherryPickLogic(params, context) {
         throw new McpError(BaseErrorCode.VALIDATION_ERROR, "No session working directory set. Please specify a 'path' or use 'git_set_working_dir' first.");
     }
     const targetPath = sanitization.sanitizePath(params.path === "." ? workingDir : params.path, { allowAbsolute: true }).sanitizedPath;
-    const args = ["-C", targetPath, "cherry-pick"];
-    if (params.mainline)
-        args.push("-m", String(params.mainline));
-    if (params.strategy)
-        args.push(`-X${params.strategy}`);
-    if (params.noCommit)
-        args.push("--no-commit");
-    if (params.signoff)
-        args.push("--signoff");
-    args.push(params.commitRef);
-    logger.debug(`Executing command: git ${args.join(" ")}`, { ...context, operation });
-    const { stdout, stderr } = await execFileAsync("git", args);
+    const attemptCherryPick = async (withSigning) => {
+        const args = ["-C", targetPath, "cherry-pick"];
+        if (withSigning)
+            args.push("-S");
+        if (params.mainline)
+            args.push("-m", String(params.mainline));
+        if (params.strategy)
+            args.push(`-X${params.strategy}`);
+        if (params.noCommit)
+            args.push("--no-commit");
+        if (params.signoff)
+            args.push("--signoff");
+        args.push(params.commitRef);
+        logger.debug(`Executing command: git ${args.join(" ")}`, { ...context, operation });
+        return await execFileAsync("git", args);
+    };
+    const createsCommit = !params.noCommit;
+    const shouldSign = !!config.gitSignCommits && createsCommit;
+    let stdout;
+    let stderr;
+    try {
+        const result = await attemptCherryPick(shouldSign);
+        stdout = result.stdout;
+        stderr = result.stderr;
+    }
+    catch (error) {
+        const isSigningError = (error.stderr || "").includes("gpg failed to sign");
+        if (shouldSign && isSigningError) {
+            logger.warning("Cherry-pick with signing failed. Retrying automatically without signature.", { ...context, operation });
+            const result = await attemptCherryPick(false);
+            stdout = result.stdout;
+            stderr = result.stderr;
+        }
+        else {
+            throw error;
+        }
+    }
     const output = stdout + stderr;
     const conflicts = /conflict/i.test(output);
-    const commitCreated = !params.noCommit && !conflicts;
+    const commitCreated = createsCommit && !conflicts;
     const message = conflicts
         ? `Cherry-pick resulted in conflicts for commit(s) '${params.commitRef}'. Manual resolution required.`
         : `Successfully cherry-picked commit(s) '${params.commitRef}'.`;

package/dist/mcp-server/tools/gitCommit/logic.js

@@ -70,7 +70,7 @@ export async function commitGitChanges(params, context) {
     let result;
     const shouldSign = config.gitSignCommits;
     try {
-        result = await attemptCommit(shouldSign);
+        result = await attemptCommit(shouldSign || false);
     }
     catch (error) {
         const isSigningError = (error.stderr || "").includes("gpg failed to sign");

package/dist/mcp-server/tools/gitMerge/logic.js

@@ -7,6 +7,7 @@ import { promisify } from "util";
 import { z } from "zod";
 import { logger, sanitization } from "../../../utils/index.js";
 import { McpError, BaseErrorCode } from "../../../types-global/errors.js";
+import { config } from "../../../config/index.js";
 const execFileAsync = promisify(execFile);
 // 1. DEFINE the Zod input schema.
 export const GitMergeInputSchema = z.object({
@@ -38,21 +39,45 @@ export async function gitMergeLogic(params, context) {
         throw new McpError(BaseErrorCode.VALIDATION_ERROR, "No session working directory set. Please specify a 'path' or use 'git_set_working_dir' first.");
     }
     const targetPath = sanitization.sanitizePath(params.path === "." ? workingDir : params.path, { allowAbsolute: true }).sanitizedPath;
-    const args = ["-C", targetPath, "merge"];
-    if (params.abort) {
-        args.push("--abort");
+    const attemptMerge = async (withSigning) => {
+        const args = ["-C", targetPath, "merge"];
+        if (params.abort) {
+            args.push("--abort");
+        }
+        else {
+            if (withSigning)
+                args.push("-S");
+            if (params.noFf)
+                args.push("--no-ff");
+            if (params.squash)
+                args.push("--squash");
+            if (params.commitMessage && !params.squash)
+                args.push("-m", params.commitMessage);
+            args.push(params.branch);
+        }
+        logger.debug(`Executing command: git ${args.join(" ")}`, { ...context, operation });
+        return await execFileAsync("git", args);
+    };
+    // A merge commit is only created if it's not a fast-forward (or --no-ff is used)
+    // and we are not squashing or aborting.
+    const createsMergeCommit = !params.squash && !params.abort;
+    const shouldSign = !!config.gitSignCommits && createsMergeCommit;
+    let stdout;
+    try {
+        const result = await attemptMerge(shouldSign);
+        stdout = result.stdout;
     }
-    else {
-        if (params.noFf)
-            args.push("--no-ff");
-        if (params.squash)
-            args.push("--squash");
-        if (params.commitMessage && !params.squash)
-            args.push("-m", params.commitMessage);
-        args.push(params.branch);
+    catch (error) {
+        const isSigningError = (error.stderr || "").includes("gpg failed to sign");
+        if (shouldSign && isSigningError) {
+            logger.warning("Merge with signing failed. Retrying automatically without signature.", { ...context, operation });
+            const result = await attemptMerge(false);
+            stdout = result.stdout;
+        }
+        else {
+            throw error;
+        }
     }
-    logger.debug(`Executing command: git ${args.join(" ")}`, { ...context, operation });
-    const { stdout } = await execFileAsync("git", args);
     return {
         success: true,
         message: stdout.trim() || "Merge command executed successfully.",

package/dist/mcp-server/tools/gitTag/logic.js

@@ -5,8 +5,9 @@
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { z } from "zod";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { logger, sanitization } from "../../../utils/index.js";
-import { McpError, BaseErrorCode } from "../../../types-global/errors.js";
+import { config } from "../../../config/index.js";
 const execFileAsync = promisify(execFile);
 // 1. DEFINE the Zod input schema.
 export const GitTagBaseSchema = z.object({
@@ -47,27 +48,45 @@ export async function gitTagLogic(params, context) {
         throw new McpError(BaseErrorCode.VALIDATION_ERROR, "No session working directory set. Please specify a 'path' or use 'git_set_working_dir' first.");
     }
     const targetPath = sanitization.sanitizePath(params.path === "." ? workingDir : params.path, { allowAbsolute: true }).sanitizedPath;
-    const args = ["-C", targetPath, "tag"];
-    switch (params.mode) {
-        case "list":
-            args.push("--list");
-            break;
-        case "create":
-            if (params.annotate)
-                args.push("-a", "-m", params.message);
-            args.push(params.tagName);
-            if (params.commitRef)
-                args.push(params.commitRef);
-            break;
-        case "delete":
-            args.push("-d", params.tagName);
-            break;
-    }
-    logger.debug(`Executing command: git ${args.join(" ")}`, { ...context, operation });
-    const { stdout } = await execFileAsync("git", args);
     if (params.mode === 'list') {
+        const { stdout } = await execFileAsync("git", ["-C", targetPath, "tag", "--list"]);
         const tags = stdout.trim().split("\n").filter(Boolean);
         return { success: true, mode: params.mode, tags };
     }
+    if (params.mode === 'delete') {
+        await execFileAsync("git", ["-C", targetPath, "tag", "-d", params.tagName]);
+        return { success: true, mode: params.mode, message: `Tag '${params.tagName}' deleted successfully.`, tagName: params.tagName };
+    }
+    // Handle create mode with signing logic
+    if (params.mode === 'create') {
+        const attemptTag = async (withSigning) => {
+            const args = ["-C", targetPath, "tag"];
+            if (params.annotate) {
+                // Use -s for signed annotated tag, -a for unsigned
+                args.push(withSigning ? "-s" : "-a");
+                args.push("-m", params.message);
+            }
+            args.push(params.tagName);
+            if (params.commitRef) {
+                args.push(params.commitRef);
+            }
+            logger.debug(`Executing command: git ${args.join(" ")}`, { ...context, operation });
+            return await execFileAsync("git", args);
+        };
+        const shouldSign = !!config.gitSignCommits && params.annotate;
+        try {
+            await attemptTag(shouldSign);
+        }
+        catch (error) {
+            const isSigningError = (error.stderr || "").includes("gpg failed to sign");
+            if (shouldSign && isSigningError) {
+                logger.warning("Tag with signing failed. Retrying automatically without signature.", { ...context, operation });
+                await attemptTag(false); // Fallback to unsigned annotated tag
+            }
+            else {
+                throw error;
+            }
+        }
+    }
     return { success: true, mode: params.mode, message: `Tag '${params.tagName}' ${params.mode}d successfully.`, tagName: params.tagName };
 }

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

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Factory for creating an authentication strategy based on configuration.
+ * This module centralizes the logic for selecting and instantiating the correct
+ * authentication strategy, promoting loose coupling and easy extensibility.
+ * @module src/mcp-server/transports/auth/authFactory
+ */
+import { config } from "../../../config/index.js";
+import { logger, requestContextService } from "../../../utils/index.js";
+import { JwtStrategy } from "./strategies/jwtStrategy.js";
+import { OauthStrategy } from "./strategies/oauthStrategy.js";
+/**
+ * Creates and returns an authentication strategy instance based on the
+ * application's configuration (`config.mcpAuthMode`).
+ *
+ * @returns An instance of a class that implements the `AuthStrategy` interface,
+ *          or `null` if authentication is disabled (`none`).
+ * @throws {Error} If the auth mode is unknown or misconfigured.
+ */
+export function createAuthStrategy() {
+    const context = requestContextService.createRequestContext({
+        operation: "createAuthStrategy",
+        authMode: config.mcpAuthMode,
+    });
+    logger.info("Creating authentication strategy...", context);
+    switch (config.mcpAuthMode) {
+        case "jwt":
+            logger.debug("Instantiating JWT authentication strategy.", context);
+            return new JwtStrategy();
+        case "oauth":
+            logger.debug("Instantiating OAuth authentication strategy.", context);
+            return new OauthStrategy();
+        case "none":
+            logger.info("Authentication is disabled ('none' mode).", context);
+            return null; // No authentication
+        default:
+            // This ensures that if a new auth mode is added to the config type
+            // but not to this factory, we get a compile-time or runtime error.
+            logger.error(`Unknown authentication mode: ${config.mcpAuthMode}`, context);
+            throw new Error(`Unknown authentication mode: ${config.mcpAuthMode}`);
+    }
+}

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

@@ -0,0 +1,57 @@
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { authContext } from "./lib/authContext.js";
+/**
+ * Creates a Hono middleware function that enforces authentication using a given strategy.
+ *
+ * @param strategy - An instance of a class that implements the `AuthStrategy` interface.
+ * @returns A Hono middleware function.
+ */
+export function createAuthMiddleware(strategy) {
+    return async function authMiddleware(c, next) {
+        const context = requestContextService.createRequestContext({
+            operation: "authMiddleware",
+            method: c.req.method,
+            path: c.req.path,
+        });
+        logger.debug("Initiating authentication check.", context);
+        const authHeader = c.req.header("Authorization");
+        if (!authHeader || !authHeader.startsWith("Bearer ")) {
+            logger.warning("Authorization header missing or invalid.", context);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid Authorization header. Bearer scheme required.", context);
+        }
+        const token = authHeader.substring(7);
+        if (!token) {
+            logger.warning("Bearer token is missing from Authorization header.", context);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Authentication token is missing.", context);
+        }
+        logger.debug("Extracted Bearer token, proceeding to verification.", context);
+        try {
+            const authInfo = await strategy.verify(token);
+            const authLogContext = {
+                ...context,
+                clientId: authInfo.clientId,
+                subject: authInfo.subject,
+                scopes: authInfo.scopes,
+            };
+            logger.info("Authentication successful. Auth context populated.", authLogContext);
+            // Run the next middleware in the chain within the populated auth context.
+            await authContext.run({ authInfo }, next);
+        }
+        catch (error) {
+            // The strategy is expected to throw an McpError.
+            // We re-throw it here to be caught by the global httpErrorHandler.
+            logger.warning("Authentication verification failed.", {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Ensure consistent error handling
+            throw ErrorHandler.handleError(error, {
+                operation: "authMiddlewareVerification",
+                context,
+                rethrow: true, // Rethrow to be caught by Hono's global error handler
+                errorCode: BaseErrorCode.UNAUTHORIZED, // Default to unauthorized if not more specific
+            });
+        }
+    };
+}

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

@@ -3,7 +3,9 @@
  * 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";
+export { authContext } from "./lib/authContext.js";
+export { withRequiredScopes } from "./lib/authUtils.js";
+export { createAuthStrategy } from "./authFactory.js";
+export { createAuthMiddleware } from "./authMiddleware.js";
+export { JwtStrategy } from "./strategies/jwtStrategy.js";
+export { OauthStrategy } from "./strategies/oauthStrategy.js";

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

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Shared types for authentication middleware.
+ * @module src/mcp-server/transports/auth/core/auth.types
+ */
+export {};
+// The declaration for `http.IncomingMessage` is no longer needed here,
+// as the new architecture avoids direct mutation where possible and handles
+// the attachment within the Hono context.

package/dist/mcp-server/transports/auth/{core → lib}/authUtils.js

@@ -19,27 +19,34 @@ import { authContext } from "./authContext.js";
  *   more required scopes are not present in the validated token.
  */
 export function withRequiredScopes(requiredScopes) {
+    const operationName = "withRequiredScopesCheck";
+    const initialContext = requestContextService.createRequestContext({
+        operation: operationName,
+        requiredScopes,
+    });
+    logger.debug("Performing scope authorization check.", initialContext);
     const store = authContext.getStore();
     if (!store || !store.authInfo) {
+        logger.crit("Authentication context is missing in withRequiredScopes. This is a server configuration error.", initialContext);
         // 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",
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Authentication context is missing. This indicates a server configuration error.", {
+            ...initialContext,
             error: "AuthStore not found in AsyncLocalStorage.",
-        }));
+        });
     }
-    const { scopes: grantedScopes, clientId } = store.authInfo;
+    const { scopes: grantedScopes, clientId, subject } = store.authInfo;
     const grantedScopeSet = new Set(grantedScopes);
     const missingScopes = requiredScopes.filter((scope) => !grantedScopeSet.has(scope));
+    const finalContext = {
+        ...initialContext,
+        grantedScopes,
+        clientId,
+        subject,
+    };
     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 });
+        const errorContext = { ...finalContext, missingScopes };
+        logger.warning("Authorization failed: Missing required scopes.", errorContext);
+        throw new McpError(BaseErrorCode.FORBIDDEN, `Insufficient permissions. Missing required scopes: ${missingScopes.join(", ")}`, errorContext);
     }
+    logger.debug("Scope authorization successful.", finalContext);
 }

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,113 @@
+/**
+ * @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 { config, environment } from "../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../../utils/index.js";
+export class JwtStrategy {
+    secretKey;
+    constructor() {
+        const context = requestContextService.createRequestContext({
+            operation: "JwtStrategy.constructor",
+        });
+        logger.debug("Initializing JwtStrategy...", context);
+        if (config.mcpAuthMode === "jwt") {
+            if (environment === "production" && !config.mcpAuthSecretKey) {
+                logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production for JWT auth.", context);
+                throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "MCP_AUTH_SECRET_KEY must be set for JWT auth in production.", context);
+            }
+            else if (!config.mcpAuthSecretKey) {
+                logger.warning("MCP_AUTH_SECRET_KEY is not set. JWT auth will be bypassed (DEV ONLY).", context);
+                this.secretKey = null;
+            }
+            else {
+                logger.info("JWT secret key loaded successfully.", context);
+                this.secretKey = new TextEncoder().encode(config.mcpAuthSecretKey);
+            }
+        }
+        else {
+            this.secretKey = null;
+        }
+    }
+    async verify(token) {
+        const context = requestContextService.createRequestContext({
+            operation: "JwtStrategy.verify",
+        });
+        logger.debug("Attempting to verify JWT.", context);
+        // Handle development mode bypass
+        if (!this.secretKey) {
+            if (environment !== "production") {
+                logger.warning("Bypassing JWT verification: No secret key (DEV ONLY).", context);
+                return {
+                    token: "dev-mode-placeholder-token",
+                    clientId: config.devMcpClientId || "dev-client-id",
+                    scopes: config.devMcpScopes || ["dev-scope"],
+                };
+            }
+            // This path is defensive. The constructor should prevent this state in production.
+            logger.crit("Auth secret key is missing in production.", context);
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "Auth secret key is missing in production. This indicates a server configuration error.", context);
+        }
+        try {
+            const { payload: decoded } = await jwtVerify(token, this.secretKey);
+            logger.debug("JWT signature verified successfully.", {
+                ...context,
+                claims: decoded,
+            });
+            const clientId = typeof decoded.cid === "string"
+                ? decoded.cid
+                : typeof decoded.client_id === "string"
+                    ? decoded.client_id
+                    : undefined;
+            if (!clientId) {
+                logger.warning("Invalid token: missing 'cid' or 'client_id' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token: missing 'cid' or 'client_id' claim.", context);
+            }
+            let scopes = [];
+            if (Array.isArray(decoded.scp) &&
+                decoded.scp.every((s) => typeof s === "string")) {
+                scopes = decoded.scp;
+            }
+            else if (typeof decoded.scope === "string" && decoded.scope.trim()) {
+                scopes = decoded.scope.split(" ").filter(Boolean);
+            }
+            if (scopes.length === 0) {
+                logger.warning("Invalid token: missing or empty 'scp' or 'scope' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.", context);
+            }
+            const authInfo = {
+                token,
+                clientId,
+                scopes,
+                subject: decoded.sub,
+            };
+            logger.info("JWT verification successful.", {
+                ...context,
+                clientId,
+                scopes,
+            });
+            return authInfo;
+        }
+        catch (error) {
+            const message = error instanceof Error && error.name === "JWTExpired"
+                ? "Token has expired."
+                : "Token verification failed.";
+            logger.warning(`JWT verification failed: ${message}`, {
+                ...context,
+                errorName: error instanceof Error ? error.name : "Unknown",
+            });
+            throw ErrorHandler.handleError(error, {
+                operation: "JwtStrategy.verify",
+                context,
+                rethrow: true,
+                errorCode: BaseErrorCode.UNAUTHORIZED,
+                errorMapper: () => new McpError(BaseErrorCode.UNAUTHORIZED, message, context),
+            });
+        }
+    }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * @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 { config } from "../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../../utils/index.js";
+export class OauthStrategy {
+    jwks;
+    constructor() {
+        const context = requestContextService.createRequestContext({
+            operation: "OauthStrategy.constructor",
+        });
+        logger.debug("Initializing OauthStrategy...", context);
+        if (config.mcpAuthMode !== "oauth") {
+            // This check is for internal consistency, so a standard Error is acceptable here.
+            throw new Error("OauthStrategy instantiated for non-oauth auth mode.");
+        }
+        if (!config.oauthIssuerUrl || !config.oauthAudience) {
+            logger.fatal("CRITICAL: OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.", context);
+            // This is a user-facing configuration error, so McpError is appropriate.
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.", context);
+        }
+        try {
+            const jwksUrl = new URL(config.oauthJwksUri ||
+                `${config.oauthIssuerUrl.replace(/\/$/, "")}/.well-known/jwks.json`);
+            this.jwks = createRemoteJWKSet(jwksUrl, {
+                cooldownDuration: 300000, // 5 minutes
+                timeoutDuration: 5000, // 5 seconds
+            });
+            logger.info(`JWKS client initialized for URL: ${jwksUrl.href}`, context);
+        }
+        catch (error) {
+            logger.fatal("Failed to initialize JWKS client.", {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // This is a critical startup failure, so a specific McpError is warranted.
+            throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, "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",
+        });
+        logger.debug("Attempting to verify OAuth token via JWKS.", context);
+        try {
+            const { payload } = await jwtVerify(token, this.jwks, {
+                issuer: config.oauthIssuerUrl,
+                audience: config.oauthAudience,
+            });
+            logger.debug("OAuth token signature verified successfully.", {
+                ...context,
+                claims: payload,
+            });
+            const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+            if (scopes.length === 0) {
+                logger.warning("Invalid token: missing or empty 'scope' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.", context);
+            }
+            const clientId = typeof payload.client_id === "string" ? payload.client_id : undefined;
+            if (!clientId) {
+                logger.warning("Invalid token: missing 'client_id' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain a 'client_id' claim.", context);
+            }
+            const authInfo = {
+                token,
+                clientId,
+                scopes,
+                subject: typeof payload.sub === "string" ? payload.sub : undefined,
+            };
+            logger.info("OAuth token verification successful.", {
+                ...context,
+                clientId,
+                scopes,
+            });
+            return authInfo;
+        }
+        catch (error) {
+            const message = error instanceof Error && error.name === "JWTExpired"
+                ? "Token has expired."
+                : "OAuth token verification failed.";
+            logger.warning(`OAuth token verification failed: ${message}`, {
+                ...context,
+                errorName: error instanceof Error ? error.name : "Unknown",
+            });
+            throw ErrorHandler.handleError(error, {
+                operation: "OauthStrategy.verify",
+                context,
+                rethrow: true,
+                errorCode: BaseErrorCode.UNAUTHORIZED,
+                errorMapper: () => new McpError(BaseErrorCode.UNAUTHORIZED, message, context),
+            });
+        }
+    }
+}

package/dist/mcp-server/transports/core/baseTransportManager.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Abstract base class for transport managers.
+ * @module src/mcp-server/transports/core/baseTransportManager
+ */
+import { logger, requestContextService, } from "../../../utils/index.js";
+/**
+ * Abstract base class for transport managers, providing common functionality.
+ */
+export class BaseTransportManager {
+    createServerInstanceFn;
+    constructor(createServerInstanceFn) {
+        const context = requestContextService.createRequestContext({
+            operation: "BaseTransportManager.constructor",
+            managerType: this.constructor.name,
+        });
+        logger.debug("Initializing transport manager.", context);
+        this.createServerInstanceFn = createServerInstanceFn;
+    }
+}