@zereight/mcp-gitlab 2.1.29 → 2.1.38

package/README.zh-CN.md

@@ -2,9 +2,9 @@
 
 [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md)
 
-> **新功能**：支持带连接池的动态 GitLab API URL。详情请参阅 [Dynamic API URL 文档](docs/configuration/dynamic-api-url.md)。
+📖 **[文档 →](https://zereight.github.io/gitlab-mcp/)** 设置指南、环境变量和完整工具参考请查看托管文档站点。
 
-[![Star History Chart](https://api.star-history.com/svg?repos=zereight/gitlab-mcp&type=Date)](https://www.star-history.com/#zereight/gitlab-mcp&Date)
+[![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
 
 ## @zereight/mcp-gitlab
 
@@ -32,6 +32,8 @@
 - [基于 JSON 的 MCP 客户端设置指南](./docs/clients/json-clients.md) - 适用于 Factory AI Droid、OpenClaw 和 OpenCode 风格客户端
 - [OAuth2 认证设置指南](./docs/auth/oauth-setup.md)
 - [环境变量参考](./docs/configuration/environment-variables.md)
+- [Stateless Mode — 多 Pod HPA](./docs/configuration/stateless-mode.md)
+- [自定义 Agent 与多 PAT 设置](./docs/auth/custom-agent-multiple-pat.md)
 
 ## 使用方法
 
@@ -63,7 +65,13 @@
 
 最简单的本地设置可以从 Personal Access Token 开始。基于浏览器的本地认证使用 OAuth2。远程或多用户部署请继续查看下面的 MCP OAuth 和远程授权部分。
 
-先全局安装一次服务器：
+安装服务器：
+
+```shell
+brew install zereight/gitlab-mcp/zereight-mcp-gitlab
+```
+
+也可以使用 npm 安装：
 
 ```shell
 npm install -g @zereight/mcp-gitlab
@@ -71,7 +79,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.29`。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.37`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -93,14 +101,17 @@ npm install -g @zereight/mcp-gitlab
 
 - `--token` - GitLab Personal Access Token（替代 `GITLAB_PERSONAL_ACCESS_TOKEN`）
 - `--api-url` - GitLab API URL（替代 `GITLAB_API_URL`）
-- `--read-only=true` - 启用只读模式（替代 `GITLAB_READ_ONLY_MODE`）
+- `--read-only=true` - 启用只读模式（替代 `GITLAB_READ_ONLY_MODE`，已弃用 — 推荐 `--permission-mode=readonly`）
+- `--permission-mode` - 权限级别：`readonly`、`modify`（禁用删除工具）或 `full`（替代 `GITLAB_PERMISSION_MODE`，默认 `full`）
 - `--use-wiki=true` - 启用 Wiki API（替代 `USE_GITLAB_WIKI`，旧版 — 推荐 `GITLAB_TOOLSETS=wiki`）
 - `--use-milestone=true` - 启用里程碑 API（替代 `USE_MILESTONE`，旧版 — 推荐 `GITLAB_TOOLSETS=milestones`）
 - `--use-pipeline=true` - 启用流水线 API（替代 `USE_PIPELINE`，旧版 — 推荐 `GITLAB_TOOLSETS=pipelines`）
+- `--disable-version-check=true` - 关闭启动时的新版本提示（替代 `GITLAB_DISABLE_VERSION_CHECK`）
 
 CLI 参数优先于环境变量。
 
-> **细粒度工具过滤：**除了全开/全关的 `GITLAB_READ_ONLY_MODE`，还可以用
+> **细粒度工具过滤：**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新并阻止所有删除工具，
+> 或使用 `GITLAB_PERMISSION_MODE=readonly` 只读运行。还可以用
 > `GITLAB_TOOLSETS=<group,…>` 启用工具分组，用 `GITLAB_TOOLS=<tool,…>` 白名单启用单个工具
 > （例如：只读分组 + 少数几个写工具），用 `GITLAB_DENIED_TOOLS_REGEX` 按正则屏蔽工具。
 > 旧版 `USE_GITLAB_WIKI` / `USE_MILESTONE` / `USE_PIPELINE` 标志仅为向后兼容保留。
@@ -114,9 +125,10 @@ docker run -i --rm \
   -e HOST=0.0.0.0 \
   -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
-  -e GITLAB_READ_ONLY_MODE=true \
+  -e GITLAB_PERMISSION_MODE=readonly \
   -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
   -e SSE=true \
+  -e SSE_AUTH_TOKEN=your_mcp_sse_token \
   -p 3333:3002 \
   zereight050/gitlab-mcp
 ```
@@ -126,7 +138,10 @@ docker run -i --rm \
   "mcpServers": {
     "gitlab": {
       "type": "sse",
-      "url": "http://localhost:3333/sse"
+      "url": "http://localhost:3333/sse",
+      "headers": {
+        "Authorization": "Bearer your_mcp_sse_token"
+      }
     }
   }
 }
@@ -137,9 +152,9 @@ docker run -i --rm \
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \
-  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
+  -e REMOTE_AUTHORIZATION=true \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
-  -e GITLAB_READ_ONLY_MODE=true \
+  -e GITLAB_PERMISSION_MODE=readonly \
   -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
   -e STREAMABLE_HTTP=true \
   -p 3333:3002 \
@@ -151,7 +166,10 @@ docker run -i --rm \
   "mcpServers": {
     "gitlab": {
       "type": "streamable-http",
-      "url": "http://localhost:3333/mcp"
+      "url": "http://localhost:3333/mcp",
+      "headers": {
+        "Authorization": "Bearer glpat-..."
+      }
     }
   }
 }
@@ -197,6 +215,8 @@ OpenCode、MCPJam、Claude.ai 等远程 MCP 客户端可能会在授权时发送
 | `GITLAB_OAUTH_SCOPES`         | 可选 | 逗号分隔的 scope（默认：`api,read_api,read_user`）                                                          |
 | `GITLAB_OAUTH_ALLOWED_GROUPS` | 可选 | 逗号分隔的 GitLab 群组完整路径 — 仅该群组及其子群组的成员可获取令牌（替代已废弃的 `GITLAB_ALLOWED_GROUPS`） |
 
+当 `STREAMABLE_HTTP=true` 时，服务端 GitLab 凭据（`GITLAB_PERSONAL_ACCESS_TOKEN`、`GITLAB_JOB_TOKEN`、`GITLAB_AUTH_COOKIE_PATH` 或 `GITLAB_USE_OAUTH`）需要 `REMOTE_AUTHORIZATION=true`、`GITLAB_MCP_OAUTH=true` 或 `STREAMABLE_HTTP_AUTH_TOKEN`。
+
 > **排查 `Unregistered redirect_uri`**
 >
 > 检查浏览器 URL 中的 `redirect_uri`。如果它指向客户端 callback，例如 `http://127.0.0.1:xxxxx/.../callback`，请启用：
@@ -241,12 +261,19 @@ MCP 客户端配置：
 
 **请求头优先级**：`Private-Token` > `JOB-TOKEN` > `Authorization: Bearer`
 
-| 环境变量                 | 必需 | 说明                                                    |
-| ------------------------ | ---- | ------------------------------------------------------- |
-| `REMOTE_AUTHORIZATION`   | 是   | 设置为 `true` 以启用                                    |
-| `STREAMABLE_HTTP`        | 是   | 必须为 `true`                                           |
-| `ENABLE_DYNAMIC_API_URL` | 可选 | 允许按请求通过 `X-GitLab-API-URL` 请求头指定 GitLab URL |
-| `GITLAB_ALLOWED_HOSTS`   | 可选 | 逗号分隔的允许主机；`GITLAB_API_URL` 中的主机始终允许   |
+| 环境变量                                                         | 必需 | 说明                                                                                                                    |
+| ---------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------- |
+| `REMOTE_AUTHORIZATION`                                           | 是   | 设置为 `true` 以启用                                                                                                    |
+| `STREAMABLE_HTTP`                                                | 是   | 必须为 `true`                                                                                                           |
+| `ENABLE_DYNAMIC_API_URL`                                         | 可选 | 允许按请求通过 `X-GitLab-API-URL` 请求头指定 GitLab URL                                                                 |
+| `GITLAB_ALLOWED_HOSTS`                                           | 可选 | 允许的 `X-GitLab-API-URL` 主机逗号分隔列表；`GITLAB_API_URL` 中的主机始终允许                                          |
+| `GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY`                    | 可选 | 仅允许未认证的 `initialize`、`notifications/initialized`、`tools/list`（工具调用仍需认证）                                |
+| `MCP_SERVER_URL` / `MCP_ALLOWED_HOSTS` / `MCP_ALLOWED_ORIGINS` | 可选 | 用于 DNS rebinding 防护的允许 `/mcp` 主机/来源值                                                                        |
+| `MCP_TRUST_PROXY`                                                | 可选 | 在反向代理后信任 `Forwarded` / `X-Forwarded-*` 请求头（下载 URL、Express `req.ip`、`/mcp` IP 速率限制、OAuth 速率限制） |
+
+`GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY=true` 适用于在用户提供 GitLab token 之前需要检查工具元数据的 MCP 网关或管理 UI。除非你的部署可以安全地暴露工具列表，否则请保持禁用。
+
+当未设置 `MCP_SERVER_URL` 时，远程下载 URL 会回退到本地服务器地址。仅当服务器通过受信任的反向代理可达且已阻止客户端直接访问 MCP 服务器时，才设置 `MCP_TRUST_PROXY=true`。这会为 Streamable HTTP 和 SSE 启用 Express `trust proxy`，从 `Forwarded` / `X-Forwarded-Proto` / `X-Forwarded-Host` / `X-Forwarded-Prefix` 派生公共下载 URL，并在代理通过 `X-Forwarded-For` 发送带客户端端口的地址（例如 `1.2.3.4:5678`）时保持 OAuth 端点速率限制可用。引入此标志后，现有 OAuth+代理部署必须显式设置。
 
 **示例请求头：**
 
@@ -272,7 +299,9 @@ Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx
 
 - **本地 PAT**：`GITLAB_PERSONAL_ACCESS_TOKEN`, `GITLAB_API_URL`
 - **本地 OAuth**：`GITLAB_USE_OAUTH=true`, `GITLAB_OAUTH_CLIENT_ID`, `GITLAB_OAUTH_REDIRECT_URI`, `GITLAB_API_URL`
-- **远程多用户 HTTP**：`STREAMABLE_HTTP=true`, `REMOTE_AUTHORIZATION=true`, `HOST`, `PORT`
+- **远程多用户 HTTP**：`STREAMABLE_HTTP=true`, `REMOTE_AUTHORIZATION=true`（或 `GITLAB_MCP_OAUTH=true`）, `MCP_TRUST_PROXY=true`（反向代理后）, `MAX_REQUESTS_PER_MINUTE=300`, `MCP_SERVER_URL` 或 `MCP_ALLOWED_HOSTS`, `HOST`, `PORT`
+- **并行运行多个部署**：为每个实例设置不同的 `MCP_SERVER_NAME`（例如 `gitlab-selfhosted-readonly`），以便在客户端、日志和遥测数据中区分它们
+- **多 Pod HPA（stateless）**：上述配置 + `OAUTH_STATELESS_MODE=true`, `OAUTH_STATELESS_SECRET`（所有 Pod 相同）。参见 [Stateless Mode](./docs/configuration/stateless-mode.md)。
 
 常用变量：
 
@@ -280,8 +309,15 @@ Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx
 - `GITLAB_PERSONAL_ACCESS_TOKEN`
 - `GITLAB_USE_OAUTH`
 - `REMOTE_AUTHORIZATION`
+- `MCP_TRUST_PROXY`
+- `MAX_REQUESTS_PER_MINUTE`
+- `MAX_SESSIONS`
+- `MCP_ALLOWED_HOSTS`
+- `MCP_ALLOWED_ORIGINS`
 - `GITLAB_MCP_OAUTH`
 - `GITLAB_OAUTH_CALLBACK_PROXY`
+- `OAUTH_STATELESS_MODE`
+- `OAUTH_STATELESS_SECRET`
 
 参考文档还包含：
 
@@ -309,7 +345,7 @@ docker run -d \
   -e STREAMABLE_HTTP=true \
   -e REMOTE_AUTHORIZATION=true \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
-  -e GITLAB_READ_ONLY_MODE=true \
+  -e GITLAB_PERMISSION_MODE=readonly \
   -e SESSION_TIMEOUT_SECONDS=3600 \
   -p 3333:3002 \
   zereight050/gitlab-mcp
@@ -352,7 +388,7 @@ token 按会话存储（由 `mcp-session-id` 请求头标识），并在同一
 - 每个会话相互隔离。一个会话的 token 不能访问另一个会话的数据。会话关闭后 token 会自动清理。
 - **会话超时：** 认证 token 在 `SESSION_TIMEOUT_SECONDS`（默认 1 小时）无活动后过期。超时后，客户端必须再次发送认证请求头。传输会话仍保持活动。
 - 每个请求都会重置该会话的超时计时器。
-- **Rate limiting：** 每个会话限制为每分钟 `MAX_REQUESTS_PER_MINUTE` 次请求（默认 60）。
+- **Rate limiting：** `/mcp` 请求按客户端 IP 限制为每分钟 `MAX_REQUESTS_PER_MINUTE` 次；使用 OAuth 或远程授权时还按 MCP 会话限制（默认 60）。详见 [environment-variables.md](docs/configuration/environment-variables.md#max_requests_per_minute)。
 - **Capacity limit：** 服务器最多接受 `MAX_SESSIONS` 个并发会话（默认 1000）。
 
 ### MCP OAuth 设置（Claude.ai Native OAuth）
@@ -456,6 +492,22 @@ npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
 
 完整工具列表请参考英文 README 的 [Tools 部分](./README.md#tools-%EF%B8%8F)。当前服务器提供合并请求、议题、流水线、部署、环境、制品、里程碑、Wiki、仓库、发布、用户、事件、work item、webhook、代码搜索和 GraphQL 执行相关工具。
 
+### Wiki 页面标题与 slug
+
+GitLab 会根据 wiki 页面标题推导其 **slug**（即 URL，`/-/wikis/<slug>`）。因此向 `update_wiki_page` / `update_group_wiki_page` 传入 `title` 会**重命名页面并改变其 URL**——对于嵌套页面，还可能把页面移动到不同的路径——从而导致已有链接失效。
+
+若只想修改**显示标题**而保持 URL 不变，请**不要**传入 `title`，而是把显示标题写入页面内容的 YAML front matter 并更新内容：
+
+```markdown
+---
+title: 我的自定义显示标题
+---
+
+页面正文…
+```
+
+GitLab 会保持 slug/URL 不变，并在界面中显示 front matter 中的标题。读取时对 `get_wiki_page` 传入 `render_html: true`，即可填充 `front_matter` 字段——而普通的 `title` 字段始终反映由 slug 推导的值。
+
 ## 测试 🧪
 
 项目包含完整测试覆盖，包括远程授权：

package/build/config.js

@@ -28,9 +28,22 @@ export const IS_OLD = getConfig("is-old", "GITLAB_IS_OLD") === "true";
 // Behavior flags
 // ---------------------------------------------------------------------------
 export const GITLAB_READ_ONLY_MODE = getConfig("read-only", "GITLAB_READ_ONLY_MODE") === "true";
+const PERMISSION_MODES = ["readonly", "modify", "full"];
+export const GITLAB_PERMISSION_MODE = (() => {
+    const raw = getConfig("permission-mode", "GITLAB_PERMISSION_MODE");
+    if (raw !== undefined && !PERMISSION_MODES.includes(raw)) {
+        throw new Error(`Invalid GITLAB_PERMISSION_MODE: "${raw}". Expected one of: ${PERMISSION_MODES.join(", ")}`);
+    }
+    // Legacy GITLAB_READ_ONLY_MODE=true always wins (most restrictive)
+    if (GITLAB_READ_ONLY_MODE) {
+        return "readonly";
+    }
+    return raw ?? "full";
+})();
 export const USE_GITLAB_WIKI = getConfig("use-wiki", "USE_GITLAB_WIKI") === "true";
 export const USE_MILESTONE = getConfig("use-milestone", "USE_MILESTONE") === "true";
 export const USE_PIPELINE = getConfig("use-pipeline", "USE_PIPELINE") === "true";
+export const GITLAB_DISABLE_VERSION_CHECK = getConfig("disable-version-check", "GITLAB_DISABLE_VERSION_CHECK") === "true";
 // ---------------------------------------------------------------------------
 // Tool filtering
 // ---------------------------------------------------------------------------

package/build/downloads/proxy.js

@@ -0,0 +1,199 @@
+import { decryptDownloadToken } from "../utils/download-token.js";
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 120_000;
+function canonicalizeQueryParams(params) {
+    const sortedKeys = Object.keys(params).sort();
+    const normalized = {};
+    for (const key of sortedKeys) {
+        normalized[key] = params[key];
+    }
+    return JSON.stringify(normalized);
+}
+/**
+ * Register the /downloads/:type proxy endpoint on an Express app.
+ * Streams GitLab API responses directly to the client. Auth is read from
+ * an encrypted `_token` query param (self-contained URL) or from request headers.
+ */
+export function registerDownloadProxy(app, deps) {
+    const downloadRateLimits = {};
+    let lastEviction = Date.now();
+    const downloadTimeoutMs = deps.downloadTimeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;
+    const checkDownloadRateLimit = (token) => {
+        const now = Date.now();
+        // Evict expired entries every 60s to prevent unbounded growth
+        if (now - lastEviction > 60000) {
+            for (const key of Object.keys(downloadRateLimits)) {
+                if (now > downloadRateLimits[key].resetAt)
+                    delete downloadRateLimits[key];
+            }
+            lastEviction = now;
+        }
+        const entry = downloadRateLimits[token];
+        if (!entry || now > entry.resetAt) {
+            downloadRateLimits[token] = { count: 1, resetAt: now + 60000 };
+            return true;
+        }
+        if (entry.count >= deps.maxRequestsPerMinute)
+            return false;
+        entry.count++;
+        return true;
+    };
+    app.get("/downloads/:type", async (req, res) => {
+        const headers = { Accept: "application/octet-stream" };
+        let rateLimitKey;
+        // Try embedded encrypted token first (self-contained URL), then headers
+        const encryptedToken = req.query._token;
+        let tokenApiUrl;
+        if (encryptedToken) {
+            const decrypted = decryptDownloadToken(encryptedToken);
+            if (!decrypted) {
+                res.status(401).json({ error: "Invalid or expired download token" });
+                return;
+            }
+            // Verify resource binding — token must match the requested type and params
+            if (decrypted.resourceType || decrypted.resourceParams) {
+                const { type } = req.params;
+                const queryParams = {};
+                for (const [k, v] of Object.entries(req.query)) {
+                    if (k !== "_token" && typeof v === "string")
+                        queryParams[k] = v;
+                }
+                if (decrypted.resourceType !== type ||
+                    canonicalizeQueryParams(decrypted.resourceParams ?? {}) !==
+                        canonicalizeQueryParams(queryParams)) {
+                    res.status(403).json({ error: "Download token does not match the requested resource" });
+                    return;
+                }
+            }
+            headers[decrypted.header] = decrypted.token;
+            rateLimitKey = decrypted.token;
+            tokenApiUrl = decrypted.apiUrl;
+        }
+        else {
+            const privateToken = req.headers["private-token"];
+            const jobToken = req.headers["job-token"];
+            const authHeader = req.headers["authorization"];
+            if (privateToken) {
+                headers["Private-Token"] = privateToken;
+                rateLimitKey = privateToken;
+            }
+            else if (jobToken) {
+                headers["JOB-TOKEN"] = jobToken;
+                rateLimitKey = jobToken;
+            }
+            else if (authHeader) {
+                headers["Authorization"] = authHeader;
+                rateLimitKey = authHeader;
+            }
+            else {
+                res.status(401).json({ error: "Authentication required" });
+                return;
+            }
+        }
+        if (!checkDownloadRateLimit(rateLimitKey)) {
+            res.status(429).json({ error: "Rate limit exceeded" });
+            return;
+        }
+        // API URL: prefer token-embedded URL, then X-GitLab-API-URL header, then default
+        let apiUrl = deps.defaultApiUrl;
+        const requestedApiUrl = tokenApiUrl || req.headers["x-gitlab-api-url"]?.trim();
+        if (deps.enableDynamicApiUrl && requestedApiUrl) {
+            try {
+                apiUrl = deps.resolveTrustedGitLabApiUrl(requestedApiUrl);
+            }
+            catch {
+                res.status(400).json({ error: "Invalid X-GitLab-API-URL" });
+                return;
+            }
+        }
+        const { type } = req.params;
+        let gitlabUrl;
+        try {
+            switch (type) {
+                case "job-artifacts": {
+                    const { project_id, job_id } = req.query;
+                    if (!project_id || !job_id) {
+                        res.status(400).json({ error: "project_id and job_id are required" });
+                        return;
+                    }
+                    const effectiveProjectId = deps.getEffectiveProjectId(decodeURIComponent(project_id));
+                    gitlabUrl = `${apiUrl}/projects/${encodeURIComponent(effectiveProjectId)}/jobs/${deps.encodeGitLabPathSegment(job_id)}/artifacts`;
+                    break;
+                }
+                case "attachment": {
+                    const { project_id, secret, filename } = req.query;
+                    if (!project_id || !secret || !filename) {
+                        res.status(400).json({ error: "project_id, secret, and filename are required" });
+                        return;
+                    }
+                    const effectiveProjectId = deps.getEffectiveProjectId(decodeURIComponent(project_id));
+                    gitlabUrl = `${apiUrl}/projects/${encodeURIComponent(effectiveProjectId)}/uploads/${deps.encodeGitLabPathSegment(secret)}/${deps.encodeGitLabPath(filename)}`;
+                    break;
+                }
+                case "release-asset": {
+                    const { project_id, tag_name, direct_asset_path } = req.query;
+                    if (!project_id || !tag_name || !direct_asset_path) {
+                        res
+                            .status(400)
+                            .json({ error: "project_id, tag_name, and direct_asset_path are required" });
+                        return;
+                    }
+                    const effectiveProjectId = deps.getEffectiveProjectId(decodeURIComponent(project_id));
+                    gitlabUrl = `${apiUrl}/projects/${encodeURIComponent(effectiveProjectId)}/releases/${encodeURIComponent(tag_name)}/downloads/${deps.encodeGitLabPath(direct_asset_path)}`;
+                    break;
+                }
+                default:
+                    res.status(400).json({ error: `Unknown download type: ${type}` });
+                    return;
+            }
+        }
+        catch (e) {
+            // getEffectiveProjectId throws on access-denied
+            const message = e instanceof Error ? e.message : "Invalid parameters";
+            res.status(403).json({ error: message });
+            return;
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), downloadTimeoutMs);
+        try {
+            const agent = deps.getAgentFunctionForUrl(apiUrl);
+            const gitlabResponse = await deps.fetch(gitlabUrl, {
+                headers,
+                agent,
+                signal: controller.signal,
+            });
+            if (!gitlabResponse.ok) {
+                res.status(gitlabResponse.status).json({
+                    error: `GitLab API error: ${gitlabResponse.status} ${gitlabResponse.statusText}`,
+                });
+                return;
+            }
+            const contentType = gitlabResponse.headers.get("content-type");
+            const contentDisposition = gitlabResponse.headers.get("content-disposition");
+            const contentLength = gitlabResponse.headers.get("content-length");
+            if (contentType)
+                res.setHeader("Content-Type", contentType);
+            if (contentDisposition)
+                res.setHeader("Content-Disposition", contentDisposition);
+            if (contentLength)
+                res.setHeader("Content-Length", contentLength);
+            if (gitlabResponse.body) {
+                gitlabResponse.body.pipe(res);
+            }
+            else {
+                res.status(502).json({ error: "No response body from GitLab" });
+            }
+        }
+        catch (error) {
+            deps.logger.error({ err: error }, "Download proxy error");
+            if (!res.headersSent) {
+                const message = error instanceof Error && error.name === "AbortError"
+                    ? "GitLab download timed out"
+                    : "Failed to proxy download from GitLab";
+                res.status(502).json({ error: message });
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    });
+}