@zereight/mcp-gitlab 2.1.46 → 2.1.47

package/README.ko.md

@@ -80,7 +80,7 @@ npm install -g @zereight/mcp-gitlab
 
 예시는 기존 `mcp-gitlab`보다 충돌 가능성이 낮은 `zereight-mcp-gitlab` 별칭을 사용합니다. MCP 클라이언트가 찾지 못하면 `which zereight-mcp-gitlab`의 절대 경로를 사용하세요.
 
-전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.45`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.46`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
 
 #### CLI 인자 사용하기(환경 변수 문제가 있는 클라이언트용)
 

package/README.md

@@ -82,7 +82,7 @@ npm install -g @zereight/mcp-gitlab
 
 The examples use `zereight-mcp-gitlab`, a less collision-prone alias for the legacy `mcp-gitlab` binary. If your MCP client cannot find it, use the absolute path from `which zereight-mcp-gitlab`.
 
-No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.45`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
+No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.46`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
 
 #### Using CLI Arguments (for clients with env var issues)
 

package/README.zh-CN.md

@@ -80,7 +80,7 @@ npm install -g @zereight/mcp-gitlab
 
 示例使用 `zereight-mcp-gitlab`，这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它，请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
 
-如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.45`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.46`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 

package/build/config.js

@@ -127,7 +127,7 @@ function _intEnv(name, cliKey, fallback, safeFallback = fallback) {
 }
 export const OAUTH_STATELESS_CLIENT_TTL_SECONDS = _intEnv("OAUTH_STATELESS_CLIENT_TTL_SECONDS", "oauth-stateless-client-ttl", 86_400);
 export const OAUTH_STATELESS_PENDING_TTL_SECONDS = _intEnv("OAUTH_STATELESS_PENDING_TTL_SECONDS", "oauth-stateless-pending-ttl", 600);
-export const OAUTH_STATELESS_STORED_TTL_SECONDS = _intEnv("OAUTH_STATELESS_STORED_TTL_SECONDS", "oauth-stateless-stored-ttl", 600);
+export const OAUTH_STATELESS_STORED_TTL_SECONDS = _intEnv("OAUTH_STATELESS_STORED_TTL_SECONDS", "oauth-stateless-stored-ttl", 120);
 // ---------------------------------------------------------------------------
 // Session / server settings
 // ---------------------------------------------------------------------------

package/build/index.js

@@ -85,8 +85,10 @@ import { createDownloadToken } from "./utils/download-token.js";
 import { determineTransportMode, TransportMode } from "./server/transport-mode.js";
 import { formatPrometheusMetrics } from "./server/metrics.js";
 import { SERVER_VERSION } from "./server/version.js";
+import { isInitializationRequestBody, isUnauthenticatedDiscoveryRequestBody, readMcpSessionIdHeader, redactSessionIdForLog, } from "./server/request-helpers.js";
+export { readMcpSessionIdHeader } from "./server/request-helpers.js";
 import { normalizeGitLabApiUrl } from "./utils/url.js";
-import { estimateMergeCommitCount, filterDiffsByPatterns, summarizeWebhookEvents, } from "./utils/helpers.js";
+import { estimateMergeCommitCount, filterDiffsByPatterns, openSafeOutputWriteStream, readSafeExistingFile, summarizeWebhookEvents, } from "./utils/helpers.js";
 import { graphqlQueryContainsWriteOperation, graphqlQueryContainsDeleteOperation, } from "./utils/graphql-query.js";
 import { resolveNestedWikiUpdateTitle } from "./utils/wiki-title.js";
 import { redactSensitiveGitLabFields } from "./utils/redact-sensitive.js";
@@ -635,71 +637,6 @@ function validateConfiguration() {
 }
 let OAUTH_ACCESS_TOKEN = null;
 let oauthClient = null;
-/**
- * Produce a safe short form of a session id for logs. Legacy UUIDs pass
- * through; stateless sealed sids are truncated to the "v1.sid." prefix
- * plus a handful of bytes of the ciphertext so operators can correlate
- * flows without the log line carrying the sealed bearer token.
- */
-function redactSessionIdForLog(sid) {
-    if (!sid)
-        return "<none>";
-    if (sid.startsWith("v1.sid."))
-        return "v1.sid.<redacted>";
-    // UUIDs / other formats are low-sensitivity; show first 8 chars.
-    return sid.length > 8 ? `${sid.slice(0, 8)}…` : sid;
-}
-/**
- * Detect whether an MCP JSON-RPC request body represents an "initialize"
- * request. Accepts both single-message and batch forms. Returns false on any
- * unexpected shape — callers treat an ambiguous body as non-init, which is
- * the safer default (it means the SDK will fail loudly rather than silently
- * spawning a new session).
- */
-function isInitializationRequestBody(body) {
-    if (!body)
-        return false;
-    const isInitObj = (m) => typeof m === "object" && m !== null && m.method === "initialize";
-    if (Array.isArray(body))
-        return body.some(isInitObj);
-    return isInitObj(body);
-}
-function isUnauthenticatedDiscoveryRequestBody(body) {
-    if (!body)
-        return false;
-    const isDiscoveryMethod = (m) => {
-        if (typeof m !== "object" || m === null)
-            return false;
-        const method = m.method;
-        return (method === "initialize" || method === "notifications/initialized" || method === "tools/list");
-    };
-    if (Array.isArray(body))
-        return body.every(isDiscoveryMethod);
-    return isDiscoveryMethod(body);
-}
-/**
- * Normalize an `Mcp-Session-Id` header value.
- *
- * Node's HTTP types allow any request header to surface as `string[]` when
- * the client sends it more than once. Casting to `string` and calling
- * `.startsWith()` on an array throws `TypeError: startsWith is not a
- * function`, which Express converts to a 500 — silently turning malformed
- * requests into server errors and breaking the 401/404 semantics we
- * carefully distinguish in stateless mode. A duplicated `Mcp-Session-Id` is
- * also ill-formed at the protocol level: there is no well-defined way to
- * pick between two values, so we reject arrays rather than guess.
- *
- * Empty-string is normalized to `undefined` so call sites can use truthy
- * checks and `?? undefined`-style fallbacks uniformly.
- *
- * Exported for unit tests; otherwise used only by the /mcp handlers below.
- */
-export function readMcpSessionIdHeader(req) {
-    const raw = req.headers["mcp-session-id"];
-    if (typeof raw !== "string")
-        return undefined;
-    return raw.length > 0 ? raw : undefined;
-}
 /**
  * Loaded once at startup. Null when OAUTH_STATELESS_MODE is disabled.
  * When set, the OAuth provider and (later phases) the Mcp-Session-Id path
@@ -983,7 +920,7 @@ const BASE_HEADERS = {
 function buildAuthHeaders() {
     if (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) {
         const ctx = sessionAuthStore.getStore();
-        logger.debug({ context: ctx }, "buildAuthHeaders: session context");
+        logger.debug({ sessionId: ctx?.sessionId, header: ctx?.header, apiUrl: ctx?.apiUrl }, "buildAuthHeaders: session context");
         if (ctx?.token) {
             return {
                 [ctx.header]: ctx.header === "Authorization" ? `Bearer ${ctx.token}` : ctx.token,
@@ -1028,7 +965,7 @@ function getEffectiveApiUrl() {
         if (ctx?.apiUrl) {
             return ctx.apiUrl;
         }
-        logger.warn({ ctx }, "getEffectiveApiUrl: No context or apiUrl found, falling back to default");
+        logger.warn({ sessionId: ctx?.sessionId, header: ctx?.header, apiUrl: ctx?.apiUrl }, "getEffectiveApiUrl: No context or apiUrl found, falling back to default");
     }
     return GITLAB_API_URL;
 }
@@ -1329,10 +1266,14 @@ async function getFileContents(projectId, filePath, ref) {
     await handleGitLabError(response);
     const data = await response.json();
     const parsedData = GitLabContentSchema.parse(data);
-    // Decode Base64-encoded file content to UTF-8
-    if (!Array.isArray(parsedData) && parsedData.content) {
-        parsedData.content = Buffer.from(parsedData.content, "base64").toString("utf8");
-        parsedData.encoding = "utf8";
+    // Decode Base64-encoded text files while preserving binary content losslessly.
+    if (!Array.isArray(parsedData) && typeof parsedData.content === "string") {
+        const decodedContent = Buffer.from(parsedData.content, "base64");
+        const utf8Content = decodedContent.toString("utf8");
+        if (Buffer.from(utf8Content, "utf8").equals(decodedContent)) {
+            parsedData.content = utf8Content;
+            parsedData.encoding = "utf8";
+        }
     }
     return parsedData;
 }
@@ -4108,13 +4049,33 @@ async function getMergeRequestApprovalState(projectId, mergeRequestIid) {
         ...getFetchConfig(),
         method: "GET",
     });
-    if (approvalStateResponse.status === 404) {
+    // 404 when the endpoint is unavailable; 402/403 when the instance or namespace is
+    // not licensed for approval rules, which are a paid-tier feature.
+    if (approvalStateResponse.status === 404 ||
+        approvalStateResponse.status === 402 ||
+        approvalStateResponse.status === 403) {
         return getMergeRequestApprovalsFallback(projectId, mergeRequestIid);
     }
     await handleGitLabError(approvalStateResponse);
     const parsedApprovalState = GitLabMergeRequestApprovalStateSchema.parse(await approvalStateResponse.json());
     const approvedByUsers = getUniqueApprovalUsers((parsedApprovalState.rules || []).flatMap(rule => rule.approved_by || []));
     const approvedByUsernames = approvedByUsers.map(user => user.username);
+    // approval_state only reports approvals attributed to rules, so a project with no
+    // approval rules answers 200 with `rules: []` and yields no approvers even when
+    // someone has approved. Read /approvals in that case. A non-empty rules array means
+    // rules are in use and approval_state is authoritative, so no extra request is made
+    // there - including while an MR is still waiting for its first approval.
+    if ((parsedApprovalState.rules || []).length === 0) {
+        try {
+            const viaApprovals = await getMergeRequestApprovalsFallback(projectId, mergeRequestIid);
+            if ((viaApprovals.approved_by ?? []).length > 0) {
+                return viaApprovals;
+            }
+        }
+        catch {
+            // /approvals unavailable as well - keep the approval_state answer below.
+        }
+    }
     return {
         ...parsedApprovalState,
         approved_by: approvedByUsers,
@@ -5319,12 +5280,11 @@ async function downloadJobArtifacts(projectId, jobId, localPath) {
     }
     await handleGitLabError(response);
     const filename = `artifacts_job_${encodeGitLabPathSegment(jobId)}.zip`;
-    const savePath = localPath ? path.join(localPath, filename) : filename;
-    fs.mkdirSync(path.dirname(savePath), { recursive: true });
     if (!response.body) {
         throw new Error("No response body from GitLab");
     }
-    await streamPipeline(response.body, fs.createWriteStream(savePath));
+    const { stream: saveStream, path: savePath } = openSafeOutputWriteStream(filename, localPath, "local_path");
+    await streamPipeline(response.body, saveStream);
     return savePath;
 }
 /**
@@ -6722,12 +6682,10 @@ async function markdownUpload(projectId, filePath, content, filename) {
         fileName = filename || "upload";
     }
     else if (filePath) {
-        // Local file mode
-        if (!fs.existsSync(filePath)) {
-            throw new Error(`File not found: ${filePath}`);
-        }
-        fileBuffer = fs.readFileSync(filePath);
-        fileName = path.basename(filePath);
+        // Local file mode — reject absolute/traversal/symlink escapes before reading
+        const { buffer, basename: safeBasename } = readSafeExistingFile(filePath, "file_path");
+        fileBuffer = buffer;
+        fileName = safeBasename;
     }
     else {
         throw new Error("Either file_path or content must be provided");
@@ -6792,29 +6750,12 @@ async function downloadAttachment(projectId, secret, filename, localPath) {
     // For non-image files, always save to disk.
     // For image files, only save to disk if local_path is explicitly provided.
     if (!mimeType || localPath) {
-        let savePath;
-        if (localPath) {
-            const normalizedLocalPath = path.normalize(localPath);
-            if (path.isAbsolute(normalizedLocalPath) ||
-                normalizedLocalPath === ".." ||
-                normalizedLocalPath.startsWith(".." + path.sep) ||
-                normalizedLocalPath.includes(path.sep + ".." + path.sep)) {
-                throw new Error("Invalid local_path: directory traversal is not allowed.");
-            }
-            savePath = path.join(normalizedLocalPath, safeFilename);
-        }
-        else {
-            savePath = safeFilename;
-        }
-        const dir = path.dirname(savePath);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        // Stream directly to disk instead of buffering in memory
         if (!response.body) {
             throw new Error("No response body from GitLab");
         }
-        await streamPipeline(response.body, fs.createWriteStream(savePath));
+        const { stream: saveStream, path: savePath } = openSafeOutputWriteStream(safeFilename, localPath, "local_path");
+        // Stream directly to disk instead of buffering in memory
+        await streamPipeline(response.body, saveStream);
         return { buffer: Buffer.alloc(0), filename: safeFilename, mimeType, savedPath: savePath };
     }
     // Images returned inline — buffer into memory for base64 encoding
@@ -9531,7 +9472,9 @@ async function handleToolCall(params) {
         }
     }
     catch (error) {
-        logger.debug(params);
+        // Log tool name only — never dump raw params (may contain approval_password).
+        // Sensitive fields are also covered by REDACT_PATHS if arguments are logged elsewhere.
+        logger.debug({ tool: params.name }, "Tool call failed");
         if (error instanceof z.ZodError) {
             throw new Error(`Invalid arguments: ${error.errors
                 .map(e => `${e.path.join(".")}: ${e.message}`)

package/build/oauth-proxy.js

@@ -49,7 +49,7 @@ import { OAuthTokensSchema } from "@modelcontextprotocol/sdk/shared/auth.js";
 import { randomUUID, randomBytes, createHash } from "node:crypto";
 import { looksLikeStatelessClientId, mintClientId, openClientId, } from "./stateless/client-id.js";
 import { looksLikeStatelessState, mintPendingAuthState, openPendingAuthState, } from "./stateless/pending-auth.js";
-import { looksLikeStatelessStoredTokensCode, mintStoredTokensCode, openStoredTokensCode, } from "./stateless/stored-tokens.js";
+import { looksLikeStatelessStoredTokensCode, mintStoredTokensCode, openStoredTokensCode, ConsumedProxyCodeCache, PROXY_CODE_CACHE_FULL, } from "./stateless/index.js";
 import { createLogger } from "./utils/logger.js";
 const logger = createLogger("gitlab-mcp-oauth-proxy");
 // ---------------------------------------------------------------------------
@@ -129,6 +129,13 @@ class GitLabOAuthServerProvider {
     _callbackUrl;
     _pendingAuth = new BoundedLRUMap(PENDING_AUTH_MAX_SIZE);
     _storedTokens = new BoundedLRUMap(PENDING_AUTH_MAX_SIZE);
+    /**
+     * Per-pod replay-prevention cache for sealed (stateless) proxy authorization
+     * codes. Keys are SHA-256 hashes of the code; entries are TTL-bound (never
+     * LRU-evicted early) and hold pending→consumed state. Cross-pod replay
+     * remains mitigated by the short stored-code TTL + PKCE.
+     */
+    _usedProxyCodes = new ConsumedProxyCodeCache(PENDING_AUTH_MAX_SIZE);
     // Stateless mode (optional). When set, DCR and callback-proxy state are
     // serialised into opaque OAuth values and the in-memory caches above are
     // bypassed. Enabled independently of callback-proxy mode.
@@ -325,102 +332,150 @@ class GitLabOAuthServerProvider {
     // ---- Token exchange ----------------------------------------------------
     async exchangeAuthorizationCode(client, authorizationCode, codeVerifier, redirectUri, resource) {
         let tokens;
-        if (this._callbackProxyEnabled) {
-            // --- Callback proxy mode ---
-            // The authorizationCode is a proxy code we generated in handleCallback().
-            // It is either a sealed token (stateless mode) or a random UUID that
-            // keys into the _storedTokens LRU (legacy mode).
-            const stateless = this._stateless;
-            let entry = null;
-            if (stateless && looksLikeStatelessStoredTokensCode(authorizationCode)) {
-                const payload = openStoredTokensCode(stateless.material, authorizationCode, stateless.storedTtlSeconds);
-                if (!payload) {
-                    throw new ServerError("Invalid or expired authorization code");
+        /** Reserved sealed-code hash + id; released on failure, committed on success. */
+        let reservedProxyCode = null;
+        /**
+         * Legacy (non-stateless) proxy code taken from `_storedTokens` before
+         * binding checks. Restored on binding/PKCE failure so a wrong verifier
+         * cannot burn the code for the legitimate client.
+         */
+        let legacyRestorable = null;
+        try {
+            if (this._callbackProxyEnabled) {
+                // --- Callback proxy mode ---
+                // The authorizationCode is a proxy code we generated in handleCallback().
+                // It is either a sealed token (stateless mode) or a random UUID that
+                // keys into the _storedTokens LRU (legacy mode).
+                const stateless = this._stateless;
+                let entry = null;
+                if (stateless && looksLikeStatelessStoredTokensCode(authorizationCode)) {
+                    const codeHash = createHash("sha256").update(authorizationCode).digest("hex");
+                    let reserved;
+                    try {
+                        reserved = this._usedProxyCodes.tryReserve(codeHash, stateless.storedTtlSeconds);
+                        if (!reserved.ok) {
+                            if (reserved.reason === "pending") {
+                                throw new ServerError("Authorization code exchange in progress — please retry");
+                            }
+                            throw new ServerError("Authorization code already used");
+                        }
+                    }
+                    catch (err) {
+                        if (err instanceof Error && err.message === PROXY_CODE_CACHE_FULL) {
+                            logger.warn({
+                                cacheSize: this._usedProxyCodes.size,
+                                cacheMaxSize: this._usedProxyCodes.maxSize,
+                            }, "Proxy code replay cache at capacity");
+                            throw new ServerError("Authorization server busy — please retry the OAuth flow");
+                        }
+                        throw err;
+                    }
+                    reservedProxyCode = { hash: codeHash, id: reserved.reservationId };
+                    const payload = openStoredTokensCode(stateless.material, authorizationCode, stateless.storedTtlSeconds);
+                    if (!payload) {
+                        throw new ServerError("Invalid or expired authorization code");
+                    }
+                    entry = {
+                        tokens: payload.t,
+                        clientId: payload.cid,
+                        clientCodeChallenge: payload.ccc,
+                        clientRedirectUri: payload.cru,
+                    };
+                    // NOTE: Cross-pod one-time use still requires a shared store. Replay
+                    // across pods is mitigated by short TTL (default 120s) + client PKCE.
+                    // Documented in stateless/stored-tokens.ts.
                 }
-                entry = {
-                    tokens: payload.t,
-                    clientId: payload.cid,
-                    clientCodeChallenge: payload.ccc,
-                    clientRedirectUri: payload.cru,
-                };
-                // NOTE: Stateless mode cannot enforce one-time use without a shared
-                // store. Replay is mitigated by short TTL + client PKCE verification
-                // below (attacker needs the code_verifier). Documented in
-                // stateless/stored-tokens.ts.
-            }
-            else {
-                const lru = this._storedTokens.get(authorizationCode);
-                if (!lru) {
-                    throw new ServerError("Invalid or expired authorization code");
+                else {
+                    // Atomic take: serialize concurrent exchanges. Restored below if
+                    // client/redirect/PKCE binding checks fail (DoS prevention).
+                    const lru = this._storedTokens.getAndDelete(authorizationCode);
+                    if (!lru) {
+                        throw new ServerError("Invalid or expired authorization code");
+                    }
+                    if (Date.now() - lru.createdAt > PENDING_AUTH_TTL_MS) {
+                        throw new ServerError("Authorization code expired — please restart the OAuth flow");
+                    }
+                    legacyRestorable = { code: authorizationCode, entry: lru };
+                    entry = {
+                        tokens: lru.tokens,
+                        clientId: lru.clientId,
+                        clientCodeChallenge: lru.clientCodeChallenge,
+                        clientRedirectUri: lru.clientRedirectUri,
+                    };
                 }
-                if (Date.now() - lru.createdAt > PENDING_AUTH_TTL_MS) {
-                    this._storedTokens.delete(authorizationCode);
-                    throw new ServerError("Authorization code expired — please restart the OAuth flow");
+                // Bind the proxy code to the client and redirect_uri that initiated
+                // /authorize, preserving the normal OAuth authorization-code invariant.
+                // Binding + PKCE run while consumption is only *reserved* (pending /
+                // restorable); failed checks release so the legitimate client can retry.
+                if (client.client_id !== entry.clientId) {
+                    throw new ServerError("Invalid client for authorization code");
                 }
-                // One-time use: delete after validation
-                this._storedTokens.delete(authorizationCode);
-                entry = {
-                    tokens: lru.tokens,
-                    clientId: lru.clientId,
-                    clientCodeChallenge: lru.clientCodeChallenge,
-                    clientRedirectUri: lru.clientRedirectUri,
-                };
-            }
-            // Bind the proxy code to the client and redirect_uri that initiated
-            // /authorize, preserving the normal OAuth authorization-code invariant.
-            if (client.client_id !== entry.clientId) {
-                throw new ServerError("Invalid client for authorization code");
-            }
-            if (redirectUri !== entry.clientRedirectUri) {
-                throw new ServerError("Invalid redirect_uri for authorization code");
+                if (redirectUri !== entry.clientRedirectUri) {
+                    throw new ServerError("Invalid redirect_uri for authorization code");
+                }
+                // Verify client PKCE: the client's code_verifier must match the
+                // code_challenge stored during /authorize.
+                if (entry.clientCodeChallenge) {
+                    if (!codeVerifier) {
+                        throw new ServerError("PKCE code_verifier is required");
+                    }
+                    const computed = createHash("sha256").update(codeVerifier).digest("base64url");
+                    if (computed !== entry.clientCodeChallenge) {
+                        throw new ServerError("PKCE verification failed");
+                    }
+                }
+                tokens = entry.tokens;
             }
-            // Verify client PKCE: the client's code_verifier must match the
-            // code_challenge stored during /authorize.
-            if (entry.clientCodeChallenge) {
-                if (!codeVerifier) {
-                    throw new ServerError("PKCE code_verifier is required");
+            else {
+                // --- Passthrough mode (original behavior) ---
+                const params = new URLSearchParams({
+                    grant_type: "authorization_code",
+                    client_id: this._gitlabAppId,
+                    code: authorizationCode,
+                });
+                if (codeVerifier)
+                    params.append("code_verifier", codeVerifier);
+                if (redirectUri)
+                    params.append("redirect_uri", redirectUri);
+                if (resource)
+                    params.append("resource", resource.href);
+                const response = await fetch(`${this._gitlabBaseUrl}/oauth/token`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: params.toString(),
+                });
+                if (!response.ok) {
+                    const body = await response.text();
+                    logger.error(`Token exchange failed (${response.status}): ${body}`);
+                    throw new ServerError(`Token exchange failed: ${response.status}`);
                 }
-                const computed = createHash("sha256").update(codeVerifier).digest("base64url");
-                if (computed !== entry.clientCodeChallenge) {
-                    throw new ServerError("PKCE verification failed");
+                const data = await response.json();
+                tokens = OAuthTokensSchema.parse(data);
+            }
+            if (this._allowedGroups) {
+                const isMember = await this._checkGroupMembership(tokens.access_token);
+                if (!isMember) {
+                    logger.warn({ allowedGroups: this._allowedGroups }, "Token issuance denied: user is not a member of any allowed group");
+                    throw new ServerError("Access denied: user is not a member of an allowed group");
                 }
             }
-            tokens = entry.tokens;
-        }
-        else {
-            // --- Passthrough mode (original behavior) ---
-            const params = new URLSearchParams({
-                grant_type: "authorization_code",
-                client_id: this._gitlabAppId,
-                code: authorizationCode,
-            });
-            if (codeVerifier)
-                params.append("code_verifier", codeVerifier);
-            if (redirectUri)
-                params.append("redirect_uri", redirectUri);
-            if (resource)
-                params.append("resource", resource.href);
-            const response = await fetch(`${this._gitlabBaseUrl}/oauth/token`, {
-                method: "POST",
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: params.toString(),
-            });
-            if (!response.ok) {
-                const body = await response.text();
-                logger.error(`Token exchange failed (${response.status}): ${body}`);
-                throw new ServerError(`Token exchange failed: ${response.status}`);
+            // All checks passed — permanently consume the proxy code.
+            legacyRestorable = null;
+            if (reservedProxyCode) {
+                this._usedProxyCodes.commit(reservedProxyCode.hash, reservedProxyCode.id);
+                reservedProxyCode = null;
             }
-            const data = await response.json();
-            tokens = OAuthTokensSchema.parse(data);
+            return tokens;
         }
-        if (this._allowedGroups) {
-            const isMember = await this._checkGroupMembership(tokens.access_token);
-            if (!isMember) {
-                logger.warn({ allowedGroups: this._allowedGroups }, "Token issuance denied: user is not a member of any allowed group");
-                throw new ServerError("Access denied: user is not a member of an allowed group");
+        catch (err) {
+            if (legacyRestorable) {
+                this._storedTokens.set(legacyRestorable.code, legacyRestorable.entry);
             }
+            if (reservedProxyCode) {
+                this._usedProxyCodes.release(reservedProxyCode.hash, reservedProxyCode.id);
+            }
+            throw err;
         }
-        return tokens;
     }
     /**
      * Returns true if the token owner belongs to at least one group whose
@@ -480,9 +535,18 @@ class GitLabOAuthServerProvider {
     }
     // ---- Verify access token -----------------------------------------------
     async verifyAccessToken(token) {
-        const res = await fetch(`${this._gitlabBaseUrl}/oauth/token/info`, {
+        let res = await fetch(`${this._gitlabBaseUrl}/oauth/token/info`, {
             headers: { Authorization: `Bearer ${token}` },
         });
+        if (res.status === 401) {
+            // Some GitLab instances sit behind an edge cache that strips the
+            // Authorization header on /oauth/* paths (observed on
+            // git.drupalcode.org, fronted by Varnish), so a valid token 401s
+            // here while working fine against /api/v4. Doorkeeper also accepts
+            // the RFC 6750 access_token query parameter — retry with that form
+            // before rejecting the token.
+            res = await fetch(`${this._gitlabBaseUrl}/oauth/token/info?access_token=${encodeURIComponent(token)}`);
+        }
         if (!res.ok) {
             throw new InvalidTokenError("Invalid or expired GitLab OAuth token");
         }

package/build/schemas.js

@@ -309,8 +309,10 @@ export const GitLabCiLintResultSchema = z.object({
     valid: z.coerce.boolean(),
     errors: z.array(z.string()),
     warnings: z.array(z.string()).optional(),
-    merged_yaml: z.string().optional(),
-    includes: z.array(z.unknown()).optional(),
+    // GitLab sends null (not an omitted field) for both when the config is
+    // invalid, which is exactly when this tool is called. See #638.
+    merged_yaml: z.string().nullish(),
+    includes: z.array(z.unknown()).nullish(),
     jobs: z.array(z.unknown()).optional(),
 });
 export const ValidateCiLintSchema = z.object({

package/build/server/request-helpers.js

@@ -0,0 +1,63 @@
+/**
+ * Produce a safe short form of a session id for logs. Legacy UUIDs pass
+ * through; stateless sealed sids are truncated to the "v1.sid." prefix
+ * plus a handful of bytes of the ciphertext so operators can correlate
+ * flows without the log line carrying the sealed bearer token.
+ */
+export function redactSessionIdForLog(sid) {
+    if (!sid)
+        return "<none>";
+    if (sid.startsWith("v1.sid."))
+        return "v1.sid.<redacted>";
+    // UUIDs / other formats are low-sensitivity; show first 8 chars.
+    return sid.length > 8 ? `${sid.slice(0, 8)}…` : sid;
+}
+/**
+ * Detect whether an MCP JSON-RPC request body represents an "initialize"
+ * request. Accepts both single-message and batch forms. Returns false on any
+ * unexpected shape — callers treat an ambiguous body as non-init, which is
+ * the safer default (it means the SDK will fail loudly rather than silently
+ * spawning a new session).
+ */
+export function isInitializationRequestBody(body) {
+    if (!body)
+        return false;
+    const isInitObj = (m) => typeof m === "object" && m !== null && m.method === "initialize";
+    if (Array.isArray(body))
+        return body.some(isInitObj);
+    return isInitObj(body);
+}
+export function isUnauthenticatedDiscoveryRequestBody(body) {
+    if (!body)
+        return false;
+    const isDiscoveryMethod = (m) => {
+        if (typeof m !== "object" || m === null)
+            return false;
+        const method = m.method;
+        return (method === "initialize" || method === "notifications/initialized" || method === "tools/list");
+    };
+    if (Array.isArray(body))
+        return body.every(isDiscoveryMethod);
+    return isDiscoveryMethod(body);
+}
+/**
+ * Normalize an `Mcp-Session-Id` header value.
+ *
+ * Node's HTTP types allow any request header to surface as `string[]` when
+ * the client sends it more than once. Casting to `string` and calling
+ * `.startsWith()` on an array throws `TypeError: startsWith is not a
+ * function`, which Express converts to a 500 — silently turning malformed
+ * requests into server errors and breaking the 401/404 semantics we
+ * carefully distinguish in stateless mode. A duplicated `Mcp-Session-Id` is
+ * also ill-formed at the protocol level: there is no well-defined way to
+ * pick between two values, so we reject arrays rather than guess.
+ *
+ * Empty-string is normalized to `undefined` so call sites can use truthy
+ * checks and `?? undefined`-style fallbacks uniformly.
+ */
+export function readMcpSessionIdHeader(req) {
+    const raw = req.headers["mcp-session-id"];
+    if (typeof raw !== "string")
+        return undefined;
+    return raw.length > 0 ? raw : undefined;
+}