@zereight/mcp-gitlab 2.1.50 → 2.1.52

package/build/oauth-device-flow.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const SLOW_DOWN_INCREMENT_SECONDS = 5;
+const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+const DeviceAuthorizationSchema = z.object({
+    device_code: z.string().min(1),
+    user_code: z.string().min(1),
+    verification_uri: z.string().min(1),
+    verification_uri_complete: z.string().min(1).optional(),
+    expires_in: z.number().positive(),
+    interval: z.number().nonnegative().optional(),
+});
+const DeviceTokenErrorSchema = z.object({
+    error: z.string().min(1),
+    error_description: z.string().optional(),
+});
+const TokenResponseSchema = z.object({
+    access_token: z.string().min(1),
+    refresh_token: z.string().min(1).optional(),
+    expires_in: z.number().positive().optional(),
+    token_type: z.string().min(1).optional(),
+});
+function delayAsync(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+async function readJsonBodyAsync(response) {
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function gitlabOrigin(gitlabUrl) {
+    return gitlabUrl.replace(/\/$/, "");
+}
+function formatOauthError(errorCode, description) {
+    if (description) {
+        return `${errorCode}: ${description}`;
+    }
+    return errorCode;
+}
+function unsupportedDeviceFlowMessage(status) {
+    return (`Device authorization is not available on this GitLab instance (HTTP ${status}). ` +
+        "GitLab 17.9+ is required for `zereight-mcp-gitlab auth` " +
+        "(17.2–17.8 need oauth2_device_grant_flow). " +
+        "Use a Personal Access Token (GITLAB_PERSONAL_ACCESS_TOKEN) instead.");
+}
+/**
+ * RFC 8628 Device Authorization Grant against GitLab (17.9+; 17.2–17.8 with
+ * oauth2_device_grant_flow).
+ * Does not open a browser. Never logs device_code or tokens.
+ */
+export async function runDeviceAuthorizationGrantAsync(input) {
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const sleepAsync = input.sleepAsync ?? delayAsync;
+    const now = input.now ?? Date.now;
+    const origin = gitlabOrigin(input.gitlabUrl);
+    const authorizeParams = new URLSearchParams({
+        client_id: input.clientId,
+        scope: input.scopes.join(" "),
+    });
+    const authorizeResponse = await fetchImpl(`${origin}/oauth/authorize_device`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: authorizeParams.toString(),
+    });
+    if (authorizeResponse.status === 404) {
+        throw new Error(unsupportedDeviceFlowMessage(404));
+    }
+    const authorizeBody = await readJsonBodyAsync(authorizeResponse);
+    if (!authorizeResponse.ok) {
+        const parsedError = DeviceTokenErrorSchema.safeParse(authorizeBody);
+        if (parsedError.success) {
+            throw new Error(`Device authorization request failed: ${formatOauthError(parsedError.data.error, parsedError.data.error_description)}`);
+        }
+        if (authorizeResponse.status >= 400 && authorizeResponse.status < 500) {
+            throw new Error(unsupportedDeviceFlowMessage(authorizeResponse.status));
+        }
+        throw new Error(`Device authorization request failed (HTTP ${authorizeResponse.status}).`);
+    }
+    const authorization = DeviceAuthorizationSchema.safeParse(authorizeBody);
+    if (!authorization.success) {
+        throw new Error("Device authorization endpoint returned an invalid response.");
+    }
+    const { device_code: deviceCode, user_code: userCode, verification_uri: verificationUri, verification_uri_complete: verificationUriComplete, expires_in: expiresIn, interval: rawInterval, } = authorization.data;
+    input.onUserCode?.({
+        userCode,
+        verificationUri,
+        verificationUriComplete,
+    });
+    let intervalSeconds = rawInterval === undefined || rawInterval <= 0
+        ? DEFAULT_POLL_INTERVAL_SECONDS
+        : rawInterval;
+    const deadline = now() + expiresIn * 1000;
+    const tokenUrl = `${origin}/oauth/token`;
+    while (now() < deadline) {
+        const tokenParams = new URLSearchParams({
+            grant_type: DEVICE_GRANT_TYPE,
+            device_code: deviceCode,
+            client_id: input.clientId,
+        });
+        if (input.clientSecret) {
+            tokenParams.set("client_secret", input.clientSecret);
+        }
+        const tokenResponse = await fetchImpl(tokenUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: tokenParams.toString(),
+        });
+        const tokenBody = await readJsonBodyAsync(tokenResponse);
+        if (tokenResponse.ok) {
+            const token = TokenResponseSchema.safeParse(tokenBody);
+            if (!token.success) {
+                throw new Error("Token endpoint returned an invalid response.");
+            }
+            return {
+                access_token: token.data.access_token,
+                refresh_token: token.data.refresh_token,
+                expires_in: token.data.expires_in,
+                created_at: now(),
+                token_type: token.data.token_type ?? "Bearer",
+            };
+        }
+        const tokenError = DeviceTokenErrorSchema.safeParse(tokenBody);
+        const errorCode = tokenError.success ? tokenError.data.error : undefined;
+        if (errorCode === "authorization_pending") {
+            await sleepAsync(intervalSeconds * 1000);
+            continue;
+        }
+        if (errorCode === "slow_down") {
+            intervalSeconds += SLOW_DOWN_INCREMENT_SECONDS;
+            await sleepAsync(intervalSeconds * 1000);
+            continue;
+        }
+        if (errorCode === "expired_token") {
+            throw new Error("Device code expired before authorization completed. Run `auth` again.");
+        }
+        if (errorCode === "access_denied") {
+            throw new Error("Authorization was denied in the browser.");
+        }
+        if (tokenError.success) {
+            throw new Error(`Device token request failed: ${formatOauthError(tokenError.data.error, tokenError.data.error_description)}`);
+        }
+        throw new Error(`Device token request failed (HTTP ${tokenResponse.status}).`);
+    }
+    throw new Error("Device code expired before authorization completed. Run `auth` again.");
+}

package/build/oauth.js

@@ -10,6 +10,7 @@ import { promisify } from "util";
 import open from "open";
 import pkceChallenge from "pkce-challenge";
 import { createLogger } from "./utils/logger.js";
+import { runDeviceAuthorizationGrantAsync } from "./oauth-device-flow.js";
 const logger = createLogger("gitlab-mcp-oauth");
 const execFileAsync = promisify(execFile);
 function escapeHtml(str) {
@@ -566,6 +567,25 @@ export class GitLabOAuth {
         }
         return !this.isTokenExpired(tokenData);
     }
+    /**
+     * Device Authorization Grant (GitLab 17.9+; 17.2–17.8 need oauth2_device_grant_flow).
+     * Does not open a browser.
+     * Stores the token with the same file format as the localhost callback flow.
+     */
+    async runDeviceFlowAsync(options) {
+        const tokenData = await runDeviceAuthorizationGrantAsync({
+            gitlabUrl: this.config.gitlabUrl,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            scopes: this.config.scopes,
+            fetchImpl: options?.fetchImpl,
+            sleepAsync: options?.sleepAsync,
+            onUserCode: options?.onUserCode,
+            now: options?.now,
+        });
+        this.saveToken(tokenData);
+        return tokenData;
+    }
 }
 /**
  * Create and initialize a GitLabOAuth client.

package/build/schemas.js

@@ -830,11 +830,33 @@ export const GitLabContentSchema = z.union([
     GitLabFileContentSchema,
     z.array(GitLabDirectoryContentSchema),
 ]);
+function refineCommitFileAction(data, ctx) {
+    const action = data.action ?? "create";
+    if ((action === "create" || action === "update") && data.content === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `content is required when action is '${action}'`,
+            path: ["content"],
+        });
+    }
+    if (action === "move" && (data.previous_path === undefined || data.previous_path.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "previous_path is required when action is 'move'",
+            path: ["previous_path"],
+        });
+    }
+}
 // Operation schemas
-export const FileOperationSchema = z.object({
+export const FileOperationSchema = z
+    .object({
     path: z.string(),
-    content: z.string(),
-});
+    content: z.string().optional(),
+    action: z.enum(["create", "update", "delete", "move"]).optional(),
+    encoding: z.enum(["text", "base64"]).optional(),
+    previous_path: z.string().optional(),
+})
+    .superRefine(refineCommitFileAction);
 // Tree and commit schemas
 export const GitLabTreeItemSchema = z.object({
     id: z.string(),
@@ -1415,6 +1437,10 @@ export const CreateOrUpdateFileSchema = ProjectParamsSchema.extend({
     previous_path: z.string().optional().describe("Path of the file to move/rename"),
     last_commit_id: z.string().optional().describe("Last known file commit ID"),
     commit_id: z.string().optional().describe("Current file commit ID (for update operations)"),
+    encoding: z
+        .enum(["text", "base64"])
+        .optional()
+        .describe("Content encoding. Use 'base64' for binary files (content must already be base64-encoded). When omitted, GITLAB_REPO_FILE_ENCODING applies."),
 });
 export const SearchRepositoriesSchema = z
     .object({
@@ -1481,11 +1507,28 @@ export const GetFileContentsSchema = z
 export const PushFilesSchema = ProjectParamsSchema.extend({
     branch: z.string().describe("Branch to push to"),
     files: z
-        .array(z.object({
-        file_path: z.string().describe("Path where to create the file"),
-        content: z.string().describe("Content of the file"),
-    }))
-        .describe("Array of files to push"),
+        .array(z
+        .object({
+        file_path: z.string().describe("Path of the file in the repo"),
+        content: z
+            .string()
+            .optional()
+            .describe("File content. Required for create and update. Omit for delete, or for a move that should keep the original content. Base64-encoded when encoding is 'base64'."),
+        action: z
+            .enum(["create", "update", "delete", "move"])
+            .optional()
+            .describe("Commit action for this file. Defaults to 'create'."),
+        encoding: z
+            .enum(["text", "base64"])
+            .optional()
+            .describe("Use 'base64' for binary files (content must already be base64-encoded). When omitted, GITLAB_REPO_FILE_ENCODING applies."),
+        previous_path: z
+            .string()
+            .optional()
+            .describe("Previous path of the file. Required when action is 'move'."),
+    })
+        .superRefine(refineCommitFileAction))
+        .describe("Array of files to push. Each entry defaults to action 'create'. Per-file fields: action (create/update/delete/move), encoding (text/base64; omitted uses GITLAB_REPO_FILE_ENCODING), previous_path (required for move). Content is required for create and update; omit content for delete, or for a move that should keep the original file. GITLAB_PERMISSION_MODE=modify rejects delete and move."),
     commit_message: z.string().describe("Commit message"),
 });
 export const CreateIssueSchema = ProjectParamsSchema.extend({
@@ -3339,8 +3382,8 @@ export const GitLabArtifactEntrySchema = z.object({
     name: z.string(),
     path: z.string(),
     type: z.enum(["file", "directory"]),
-    size: z.coerce.number().optional(),
-    mode: z.string().optional(),
+    size: z.coerce.number().nullish(),
+    mode: z.string().nullish(),
 });
 export const DownloadJobArtifactsSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),

package/build/scripts/generate-tool-docs.js

@@ -281,7 +281,7 @@ function buildIndexPage(groupedToolsList) {
         "Permission modes control which tools are exposed:",
         "",
         "- `GITLAB_PERMISSION_MODE=readonly` — hides every write tool regardless of toggles.",
-        "- `GITLAB_PERMISSION_MODE=modify` — allows create/update but blocks all `delete_*` tools.",
+        "- `GITLAB_PERMISSION_MODE=modify` — allows create/update but blocks all `delete_*` tools, plus `push_files` `delete`/`move` actions.",
         "- `GITLAB_READ_ONLY_MODE=true` (deprecated) — same as `readonly`; prefer `GITLAB_PERMISSION_MODE=readonly`.",
         "",
         "See [Environment Variables](../configuration/environment-variables.md)",

package/build/test/create-commit-actions.test.js

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FileOperationSchema } from "../schemas.js";
+import { fileOperationsIncludeDeleteOrMove, toGitLabCommitActions, } from "../utils/gitlab-commit-actions.js";
+function firstAction(actions) {
+    const entry = actions[0];
+    if (!entry) {
+        throw new Error("expected at least one commit action");
+    }
+    return entry;
+}
+describe("When mapping file operations to GitLab commit actions", () => {
+    describe("with a plain text file and no per-file encoding", () => {
+        it("should default the action to create", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", content: "hi" }], "text"));
+            assert.equal(entry.action, "create");
+        });
+        it("should keep the content unchanged when the global encoding is text", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", content: "hi" }], "text"));
+            assert.equal(entry.content, "hi");
+        });
+        it("should set encoding to the global text value", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", content: "hi" }], "text"));
+            assert.equal(entry.encoding, "text");
+        });
+    });
+    describe("with a plain text file and global base64 encoding", () => {
+        it("should base64-encode the content", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", content: "hi" }], "base64"));
+            assert.equal(entry.content, Buffer.from("hi").toString("base64"));
+        });
+        it("should set encoding to base64", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", content: "hi" }], "base64"));
+            assert.equal(entry.encoding, "base64");
+        });
+    });
+    describe("with an explicit per-file encoding", () => {
+        it("should pass text content through when encoding is text even if global is base64", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", content: "hi", encoding: "text" }], "base64"));
+            assert.equal(entry.content, "hi");
+        });
+        it("should keep the explicit text encoding on the payload", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", content: "hi", encoding: "text" }], "base64"));
+            assert.equal(entry.encoding, "text");
+        });
+        it("should pass base64 content through without encoding it again", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "logo.png", content: "aGk=", encoding: "base64" }], "text"));
+            assert.equal(entry.content, "aGk=");
+        });
+    });
+    describe("with action delete", () => {
+        it("should omit content from the payload", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", action: "delete" }], "text"));
+            assert.equal("content" in entry, false);
+        });
+        it("should omit encoding from the payload", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "a.txt", action: "delete" }], "text"));
+            assert.equal("encoding" in entry, false);
+        });
+    });
+    describe("with action move", () => {
+        it("should omit content when the move has no new content", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "b.txt", action: "move", previous_path: "a.txt" }], "text"));
+            assert.equal("content" in entry, false);
+        });
+        it("should include previous_path", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "b.txt", action: "move", previous_path: "a.txt" }], "text"));
+            assert.equal(entry.previous_path, "a.txt");
+        });
+        it("should include content when a move supplies replacement content", () => {
+            const entry = firstAction(toGitLabCommitActions([{ path: "b.txt", action: "move", previous_path: "a.txt", content: "new" }], "text"));
+            assert.equal(entry.content, "new");
+        });
+    });
+    describe("with create or update missing content", () => {
+        it("should reject a create without content before sending an empty file", () => {
+            assert.throws(() => toGitLabCommitActions([{ path: "a.txt" }], "text"), /content is required when action is 'create'/);
+        });
+        it("should reject the FileOperation schema for create without content", () => {
+            const parsed = FileOperationSchema.safeParse({ path: "a.txt" });
+            assert.equal(parsed.success, false);
+        });
+    });
+});
+describe("When checking push_files actions against modify mode", () => {
+    describe("with delete or move entries", () => {
+        it("should treat delete as blocked", () => {
+            assert.equal(fileOperationsIncludeDeleteOrMove([{ action: "delete" }]), true);
+        });
+        it("should treat move as blocked", () => {
+            assert.equal(fileOperationsIncludeDeleteOrMove([{ action: "move" }]), true);
+        });
+    });
+    describe("with create or update entries", () => {
+        it("should allow omitted action", () => {
+            assert.equal(fileOperationsIncludeDeleteOrMove([{}]), false);
+        });
+        it("should allow update", () => {
+            assert.equal(fileOperationsIncludeDeleteOrMove([{ action: "update" }]), false);
+        });
+    });
+});

package/build/test/gitlab-artifact-entry-schema.test.js

@@ -0,0 +1,44 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { GitLabArtifactEntrySchema } from "../schemas.js";
+function validEntry(overrides = {}) {
+    return {
+        name: "report.xml",
+        path: "report.xml",
+        type: "file",
+        ...overrides,
+    };
+}
+describe("When parsing an artifact tree entry", () => {
+    describe("with a string mode", () => {
+        it("should keep the mode", () => {
+            const parsed = GitLabArtifactEntrySchema.parse(validEntry({ mode: "100644", size: 1024 }));
+            assert.strictEqual(parsed.mode, "100644");
+            assert.strictEqual(parsed.size, 1024);
+        });
+    });
+    describe("with mode set to null", () => {
+        it("should accept null", () => {
+            const parsed = GitLabArtifactEntrySchema.parse(validEntry({ mode: null }));
+            assert.strictEqual(parsed.mode, null);
+        });
+    });
+    describe("with size set to null", () => {
+        it("should accept null", () => {
+            const parsed = GitLabArtifactEntrySchema.parse(validEntry({ size: null }));
+            assert.strictEqual(parsed.size, null);
+        });
+    });
+    describe("with mode and size omitted", () => {
+        it("should leave them undefined", () => {
+            const parsed = GitLabArtifactEntrySchema.parse(validEntry());
+            assert.strictEqual(parsed.mode, undefined);
+            assert.strictEqual(parsed.size, undefined);
+        });
+    });
+    describe("with an unknown type", () => {
+        it("should reject the entry", () => {
+            assert.throws(() => GitLabArtifactEntrySchema.parse(validEntry({ type: "symlink" })));
+        });
+    });
+});