@zereight/mcp-gitlab 2.1.46 → 2.1.48

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/scripts/generate-server-card.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import { allTools } from "../tools/registry.js";
+async function main() {
+    const pkgPath = path.resolve(process.cwd(), "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const serverCard = {
+        serverInfo: {
+            name: pkg.mcpName || pkg.name,
+            version: pkg.version,
+        },
+        authentication: {
+            required: true,
+            schemes: ["bearer", "oauth2"],
+        },
+        tools: allTools.map(t => {
+            const tool = { ...t };
+            if (tool.inputSchema &&
+                typeof tool.inputSchema === "object" &&
+                "$schema" in tool.inputSchema) {
+                const schema = { ...tool.inputSchema };
+                delete schema["$schema"];
+                tool.inputSchema = schema;
+            }
+            return tool;
+        }),
+        resources: [],
+        prompts: [],
+    };
+    const outDir = path.resolve(process.cwd(), ".well-known", "mcp");
+    fs.mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, "server-card.json");
+    fs.writeFileSync(outFile, JSON.stringify(serverCard, null, 2), "utf8");
+    console.log(`Successfully generated ${outFile} (${allTools.length} tools)`);
+}
+main().catch(err => {
+    console.error("Failed to generate server card:", err);
+    process.exit(1);
+});

package/build/server/request-helpers.js

@@ -0,0 +1,75 @@
+/**
+ * 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;
+}
+/**
+ * Normalize an `Accept` header. Duplicate Accept values surface as `string[]`
+ * in Node; joining them preserves `text/event-stream` if any value listed it.
+ */
+export function readAcceptHeader(req) {
+    const raw = req.headers.accept;
+    if (typeof raw === "string")
+        return raw;
+    if (Array.isArray(raw))
+        return raw.filter(value => typeof value === "string").join(", ");
+    return "";
+}

package/build/stateless/consumed-proxy-code-cache.js

@@ -0,0 +1,82 @@
+/**
+ * Per-pod replay-prevention cache for sealed proxy authorization codes.
+ *
+ * Unlike an LRU map, entries are retained until their TTL expires — never
+ * evicted early. Inserts fail closed when the cache is full of still-valid
+ * entries, so a burst of traffic cannot reopen a capture-replay window by
+ * pushing a consumed hash out before `storedTtlSeconds` elapses.
+ */
+import { randomBytes } from "node:crypto";
+export const PROXY_CODE_CACHE_FULL = "PROXY_CODE_CACHE_FULL";
+/** Largest TTL (seconds) that keeps `now + ttl * 1000` finite. */
+const MAX_TTL_SECONDS = Math.floor(Number.MAX_SAFE_INTEGER / 1000);
+function ttlToExpiryMs(now, ttlSeconds) {
+    // Non-finite / non-positive TTLs must still create a usable expiry so a
+    // reservation blocks concurrent replay instead of leaving expiresAt as NaN.
+    let safeSeconds = Number.isFinite(ttlSeconds) && ttlSeconds > 0 ? ttlSeconds : 1;
+    if (safeSeconds > MAX_TTL_SECONDS) {
+        safeSeconds = MAX_TTL_SECONDS;
+    }
+    const expiresAt = now + safeSeconds * 1000;
+    return Number.isFinite(expiresAt) ? expiresAt : Number.MAX_SAFE_INTEGER;
+}
+export class ConsumedProxyCodeCache {
+    _map = new Map();
+    _maxSize;
+    _now;
+    constructor(maxSize, now = Date.now) {
+        this._maxSize = maxSize;
+        this._now = now;
+    }
+    purgeExpired(now) {
+        for (const [key, entry] of this._map) {
+            if (entry.expiresAt <= now)
+                this._map.delete(key);
+        }
+    }
+    /**
+     * Atomically reserve a code hash for an in-flight exchange.
+     * @returns `{ ok: true }` if reserved, or `{ ok: false, reason }` when an
+     *   in-TTL pending/consumed entry already exists.
+     * @throws Error with message {@link PROXY_CODE_CACHE_FULL} when the cache
+     *   is full of non-expired entries (fail closed).
+     */
+    tryReserve(key, ttlSeconds) {
+        const now = this._now();
+        this.purgeExpired(now);
+        const existing = this._map.get(key);
+        if (existing && existing.expiresAt > now) {
+            return { ok: false, reason: existing.state };
+        }
+        if (this._map.size >= this._maxSize) {
+            throw new Error(PROXY_CODE_CACHE_FULL);
+        }
+        this._map.set(key, {
+            expiresAt: ttlToExpiryMs(now, ttlSeconds),
+            state: "pending",
+            reservationId: randomBytes(16).toString("hex"),
+        });
+        const entry = this._map.get(key);
+        return { ok: true, reservationId: entry.reservationId };
+    }
+    /** Mark a reserved code as fully consumed (replay rejected until TTL). */
+    commit(key, reservationId) {
+        const entry = this._map.get(key);
+        if (entry && entry.reservationId === reservationId) {
+            entry.state = "consumed";
+        }
+    }
+    /** Drop an in-flight reservation so a later legitimate exchange can proceed. */
+    release(key, reservationId) {
+        const entry = this._map.get(key);
+        if (entry?.state === "pending" && entry.reservationId === reservationId) {
+            this._map.delete(key);
+        }
+    }
+    get size() {
+        return this._map.size;
+    }
+    get maxSize() {
+        return this._maxSize;
+    }
+}

package/build/stateless/index.js

@@ -11,4 +11,5 @@ export { open, seal, sign, verify, } from "./codec.js";
 export { looksLikeStatelessClientId, mintClientId, openClientId, } from "./client-id.js";
 export { looksLikeStatelessState, mintPendingAuthState, openPendingAuthState, } from "./pending-auth.js";
 export { looksLikeStatelessStoredTokensCode, mintStoredTokensCode, openStoredTokensCode, } from "./stored-tokens.js";
+export { ConsumedProxyCodeCache, PROXY_CODE_CACHE_FULL, } from "./consumed-proxy-code-cache.js";
 export { looksLikeStatelessSessionId, mintSessionId, openSessionId, } from "./session-id.js";

package/build/stateless/stored-tokens.js

@@ -15,9 +15,11 @@
  * Uses AEAD (AES-256-GCM) because the payload contains the GitLab access
  * token and refresh token.
  *
- * Replay: proxyCode replay is defeated by two mitigations:
- *   - short TTL (OAUTH_STATELESS_STORED_TTL_SECONDS, default 600s)
+ * Replay: proxyCode replay is defeated by three mitigations:
+ *   - short TTL (OAUTH_STATELESS_STORED_TTL_SECONDS, default 120s)
  *   - PKCE binding (the client must still present a matching code_verifier)
+ *   - per-pod TTL-bound replay cache (pending reservation → commit on success;
+ *     failed binding/PKCE releases the reservation; never LRU-evicts early)
  */
 import { open, seal } from "./codec.js";
 import { StatelessCodecError } from "./errors.js";

package/build/test/mcp-oauth-tests.js

@@ -400,6 +400,102 @@ describe("MCP OAuth — createGitLabOAuthProvider", () => {
             stub.close();
         }
     });
+    test("verifyAccessToken falls back to access_token query param when Bearer gets 401", async () => {
+        // Simulates a GitLab behind an edge cache that strips the Authorization
+        // header on /oauth/* (e.g. git.drupalcode.org behind Varnish): the
+        // Bearer-header request 401s, the RFC 6750 query-param retry succeeds.
+        const TOKEN = "tok+en/with?special=chars&more"; // exercises URL encoding
+        const requests = [];
+        const { createServer } = await import("node:http");
+        const stub = createServer((req, res) => {
+            requests.push({ url: req.url, authHeader: req.headers["authorization"] });
+            const url = new URL(req.url, "http://localhost");
+            if (url.searchParams.get("access_token") === TOKEN) {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    resource_owner_id: 7,
+                    scopes: ["api"],
+                    expires_in_seconds: 3600,
+                    application: { uid: "app-uid-abc" },
+                    created_at: Math.floor(Date.now() / 1000),
+                }));
+            }
+            else {
+                // Header-stripping edge: reject anything not using the query param
+                res.writeHead(401, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "invalid_token" }));
+            }
+        });
+        await new Promise(resolve => stub.listen(0, "127.0.0.1", resolve));
+        const addr = stub.address();
+        const baseUrl = `http://127.0.0.1:${addr.port}`;
+        try {
+            const { createGitLabOAuthProvider } = await import("../oauth-proxy.js");
+            const provider = createGitLabOAuthProvider(baseUrl, "test-app-id");
+            const authInfo = await provider.verifyAccessToken(TOKEN);
+            assert.strictEqual(requests.length, 2, "exactly one retry after the 401");
+            assert.strictEqual(requests[0].authHeader, `Bearer ${TOKEN}`, "first attempt sends the token as a Bearer Authorization header");
+            assert.ok(!requests[0].url.includes("access_token="), "first attempt does not use the query param");
+            assert.strictEqual(requests[1].authHeader, undefined, "retry omits the Authorization header");
+            assert.ok(requests[1].url.includes(`access_token=${encodeURIComponent(TOKEN)}`), "retry carries the URL-encoded access_token query param");
+            assert.strictEqual(authInfo.token, TOKEN, "token preserved through the fallback path");
+            assert.strictEqual(authInfo.clientId, "app-uid-abc", "AuthInfo built from retry response");
+            console.log("  ✓ verifyAccessToken falls back to query param after Bearer 401");
+        }
+        finally {
+            stub.close();
+        }
+    });
+    test("verifyAccessToken does not retry when the Bearer request succeeds", async () => {
+        let requestCount = 0;
+        const { createServer } = await import("node:http");
+        const stub = createServer((_req, res) => {
+            requestCount++;
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                resource_owner_id: 7,
+                scopes: ["api"],
+                expires_in_seconds: 3600,
+                application: { uid: "app-uid-abc" },
+                created_at: Math.floor(Date.now() / 1000),
+            }));
+        });
+        await new Promise(resolve => stub.listen(0, "127.0.0.1", resolve));
+        const addr = stub.address();
+        const baseUrl = `http://127.0.0.1:${addr.port}`;
+        try {
+            const { createGitLabOAuthProvider } = await import("../oauth-proxy.js");
+            const provider = createGitLabOAuthProvider(baseUrl, "test-app-id");
+            await provider.verifyAccessToken("good-token");
+            assert.strictEqual(requestCount, 1, "no retry on a 200 response");
+            console.log("  ✓ verifyAccessToken makes a single request on success");
+        }
+        finally {
+            stub.close();
+        }
+    });
+    test("verifyAccessToken does not retry on non-401 errors", async () => {
+        let requestCount = 0;
+        const { createServer } = await import("node:http");
+        const stub = createServer((_req, res) => {
+            requestCount++;
+            res.writeHead(503, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "service_unavailable" }));
+        });
+        await new Promise(resolve => stub.listen(0, "127.0.0.1", resolve));
+        const addr = stub.address();
+        const baseUrl = `http://127.0.0.1:${addr.port}`;
+        try {
+            const { createGitLabOAuthProvider } = await import("../oauth-proxy.js");
+            const provider = createGitLabOAuthProvider(baseUrl, "test-app-id");
+            await assert.rejects(() => provider.verifyAccessToken("tok"), /invalid or expired/i, "non-401 errors still reject");
+            assert.strictEqual(requestCount, 1, "the query-param fallback is 401-only");
+            console.log("  ✓ verifyAccessToken does not retry on non-401 errors");
+        }
+        finally {
+            stub.close();
+        }
+    });
     test("verifyAccessToken maps GitLab token info to AuthInfo", async () => {
         const createdAt = Math.floor(Date.now() / 1000);
         const { createServer } = await import("node:http");

package/build/test/nullable-gitlab-response-fields.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { GitLabCompareResultSchema, GitLabProtectedBranchAccessLevelSchema, } from "../schemas.js";
+import { GitLabCiLintResultSchema, GitLabCompareResultSchema, GitLabProtectedBranchAccessLevelSchema, } from "../schemas.js";
 test("role-based protected-branch access levels accept null user_id/group_id", () => {
     // #575: GitLab returns null for role-based levels, not omitted fields
     const parsed = GitLabProtectedBranchAccessLevelSchema.parse({
@@ -20,3 +20,18 @@ test("branch compare accepts null commit", () => {
     });
     assert.equal(parsed.commit, null);
 });
+test("ci lint result accepts null merged_yaml/includes on an invalid config", () => {
+    // #638: GitLab nulls both fields whenever the config is invalid — i.e. in
+    // exactly the case validate_ci_lint exists to report on.
+    const parsed = GitLabCiLintResultSchema.parse({
+        valid: false,
+        errors: ["image is defined in top-level and `default:` entry"],
+        warnings: [],
+        merged_yaml: null,
+        includes: null,
+    });
+    assert.equal(parsed.valid, false);
+    assert.equal(parsed.merged_yaml, null);
+    assert.equal(parsed.includes, null);
+    assert.deepEqual(parsed.errors, ["image is defined in top-level and `default:` entry"]);
+});