@zereight/mcp-gitlab 2.1.62 → 2.1.63

package/build/masking/engine.js

@@ -0,0 +1,404 @@
+import fs from "node:fs";
+import path from "node:path";
+const BUILTIN_RULES = [
+    {
+        id: "gitlab-token",
+        type: "regex",
+        // GitLab token prefixes documented at
+        // https://docs.gitlab.com/security/token_overview/#token-prefixes
+        pattern: "\\bgl(?:pat|rt|ptt|dt|cbt|soat|oas|agent|ft|imt)-[A-Za-z0-9_-]{20,}\\b",
+        flags: "g",
+        replacement: "[Token masked]",
+    },
+    {
+        id: "ipv4",
+        type: "regex",
+        pattern: "\\b(?:25[0-5]|2[0-4]\\d|1?\\d?\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1?\\d?\\d)){3}\\b",
+        flags: "g",
+        replacement: "[IP address]",
+    },
+    {
+        id: "ipv6",
+        type: "regex",
+        pattern: "(?<![0-9A-Fa-f:])(?:(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,7}:|(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,5}(?::[0-9A-Fa-f]{1,4}){1,2}|(?:[0-9A-Fa-f]{1,4}:){1,4}(?::[0-9A-Fa-f]{1,4}){1,3}|(?:[0-9A-Fa-f]{1,4}:){1,3}(?::[0-9A-Fa-f]{1,4}){1,4}|(?:[0-9A-Fa-f]{1,4}:){1,2}(?::[0-9A-Fa-f]{1,4}){1,5}|[0-9A-Fa-f]{1,4}:(?:(?::[0-9A-Fa-f]{1,4}){1,6})|:(?:(?::[0-9A-Fa-f]{1,4}){1,7}|:))(?![0-9A-Fa-f:])",
+        flags: "g",
+        replacement: "[IP address]",
+    },
+];
+const ALLOWED_REGEX_FLAGS = new Set(["g", "i", "m", "s", "u"]);
+function assertString(value, field) {
+    if (typeof value !== "string")
+        throw new Error(`${field} must be a string`);
+    return value;
+}
+function compileRule(rule, order) {
+    if (!rule || typeof rule !== "object")
+        throw new Error(`Invalid mask rule at index ${order}`);
+    const id = assertString(rule.id, `mask rule ${order}.id`);
+    if (!id)
+        throw new Error(`mask rule ${order}.id must not be empty`);
+    const replacement = assertString(rule.replacement, `mask rule ${id}.replacement`);
+    let source;
+    let flags;
+    if (rule.type === "keyword") {
+        const match = assertString(rule.match, `mask rule ${id}.match`);
+        if (!match)
+            throw new Error(`mask rule ${id}.match must not be empty`);
+        source = escapeRegExp(match);
+        flags = rule.caseSensitive === false ? "gi" : "g";
+    }
+    else if (rule.type === "regex") {
+        source = assertString(rule.pattern, `mask rule ${id}.pattern`);
+        flags = rule.flags ?? "g";
+        if (!flags.includes("g"))
+            flags += "g";
+        if ([...flags].some(flag => !ALLOWED_REGEX_FLAGS.has(flag))) {
+            throw new Error(`mask rule ${id}.flags contains an unsupported flag`);
+        }
+        if (source.length === 0)
+            throw new Error(`mask rule ${id}.pattern must not be empty`);
+    }
+    else {
+        throw new Error(`mask rule ${id}.type must be "keyword" or "regex"`);
+    }
+    let expression;
+    try {
+        expression = new RegExp(source, flags);
+    }
+    catch (error) {
+        throw new Error(`Invalid regular expression in mask rule ${id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Empty matches can make a rule unexpectedly rewrite every character and are
+    // particularly easy to create accidentally with a configurable expression.
+    if (expression.test(""))
+        throw new Error(`mask rule ${id} must not match an empty string`);
+    return { id, replacement, expression, order };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function mergeBuiltinRules(file) {
+    const overrides = file?.builtins ?? {};
+    return BUILTIN_RULES.flatMap(rule => {
+        const override = overrides[rule.id];
+        if (override?.enabled === false)
+            return [];
+        return [
+            {
+                ...rule,
+                ...(override?.replacement !== undefined ? { replacement: override.replacement } : {}),
+            },
+        ];
+    });
+}
+function loadFile(configPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Unable to load masking config ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Masking config ${configPath} must contain a JSON object`);
+    }
+    if (isManagedReference(parsed)) {
+        const value = parsed;
+        if (value.version !== 2 || typeof value.policyGroup !== "string" || !value.policyGroup.trim()) {
+            throw new Error(`Managed masking config ${configPath} requires version 2 and a non-empty policyGroup`);
+        }
+        return value;
+    }
+    validateMaskingFile(parsed, `Masking config ${configPath}`);
+    return parsed;
+}
+function loadJsonFile(configPath) {
+    try {
+        return JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Unable to load masking config ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function normalizeGitLabInstance(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid managed masking GitLab instance: ${value}`);
+    }
+    return `${url.protocol}//${url.host}${url.pathname.replace(/\/api\/v4\/?$/, "").replace(/\/+$/, "")}`;
+}
+function isManagedReference(value) {
+    return Boolean(value && typeof value === "object" && value.mode === "managed");
+}
+function loadManagedPolicyFile(configPath) {
+    const parsed = loadJsonFile(configPath);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Managed masking policy file ${configPath} must contain a JSON object`);
+    }
+    const file = parsed;
+    if (file.version !== 1)
+        throw new Error("Unsupported managed masking policy version");
+    if (!file.policyGroups ||
+        typeof file.policyGroups !== "object" ||
+        Array.isArray(file.policyGroups)) {
+        throw new Error("Managed masking policy file policyGroups must be an object");
+    }
+    if (!Array.isArray(file.bindings))
+        throw new Error("Managed masking policy file bindings must be an array");
+    if (file.unboundProjectBehavior !== undefined &&
+        file.unboundProjectBehavior !== "deny" &&
+        file.unboundProjectBehavior !== "builtin") {
+        throw new Error('Managed masking policy file unboundProjectBehavior must be "deny" or "builtin"');
+    }
+    for (const [name, policy] of Object.entries(file.policyGroups)) {
+        if (!name.trim())
+            throw new Error("Managed masking policy group names must not be empty");
+        validateMaskingFile(policy, `managed masking policy group ${name}`);
+    }
+    for (const binding of file.bindings) {
+        if (!binding ||
+            typeof binding !== "object" ||
+            typeof binding.gitlabInstance !== "string" ||
+            typeof binding.policyGroup !== "string" ||
+            !Array.isArray(binding.projectIds)) {
+            throw new Error("Invalid managed masking policy binding");
+        }
+        normalizeGitLabInstance(binding.gitlabInstance);
+        if (!file.policyGroups[binding.policyGroup]) {
+            throw new Error(`Managed masking policy binding references unknown group: ${binding.policyGroup}`);
+        }
+        if (binding.projectIds.some(id => !Number.isSafeInteger(id) || id <= 0)) {
+            throw new Error("Managed masking policy binding projectIds must be positive integers");
+        }
+    }
+    return file;
+}
+function validateMaskingFile(value, description) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${description} must contain a JSON object`);
+    }
+    const file = value;
+    if (file.version !== undefined && file.version !== 1) {
+        throw new Error(`Unsupported masking config version: ${String(file.version)}`);
+    }
+    if (file.rules !== undefined && !Array.isArray(file.rules)) {
+        throw new Error(`${description}.rules must be an array`);
+    }
+}
+function maskStrings(value, mask, parentKey) {
+    if (typeof value === "string") {
+        const masked = mask(value);
+        return masked !== value && parentKey === "download_url" ? "[Download URL masked]" : masked;
+    }
+    if (Array.isArray(value))
+        return value.map(item => maskStrings(item, mask, parentKey));
+    if (value && typeof value === "object") {
+        const output = {};
+        for (const [key, item] of Object.entries(value))
+            output[key] = maskStrings(item, mask, key);
+        return output;
+    }
+    return value;
+}
+function maskJsonText(text, mask) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object")
+            return mask(text);
+    }
+    catch {
+        return mask(text);
+    }
+    // Rewrite only JSON string values. Re-serializing the parsed object would
+    // change whitespace and lose precision in numeric values from GitLab.
+    let propertyKey;
+    return text.replace(/"(?:\\.|[^"\\])*"/g, (literal, offset) => {
+        const value = JSON.parse(literal);
+        if (/^\s*:/.test(text.slice(offset + literal.length))) {
+            propertyKey = value;
+            return literal;
+        }
+        const masked = mask(value);
+        if (masked === value)
+            return literal;
+        const isDownloadUrl = propertyKey === "download_url" && /:\s*$/.test(text.slice(0, offset));
+        return JSON.stringify(isDownloadUrl ? "[Download URL masked]" : masked);
+    });
+}
+function createMaskingEngineFromFile(file, configPath) {
+    const rules = [...(file.rules ?? []), ...mergeBuiltinRules(file)].map(compileRule);
+    const maskedErrors = new WeakSet();
+    const maskText = (text) => {
+        const matches = [];
+        for (const rule of rules) {
+            rule.expression.lastIndex = 0;
+            let match;
+            while ((match = rule.expression.exec(text)) !== null) {
+                const start = match.index;
+                const end = start + match[0].length;
+                if (end === start)
+                    throw new Error(`mask rule ${rule.id} produced an empty match`);
+                matches.push({ start, end, replacement: rule.replacement, order: rule.order });
+                if (!rule.expression.global)
+                    break;
+            }
+        }
+        if (matches.length === 0)
+            return text;
+        matches.sort((a, b) => a.start - b.start || b.end - b.start - (a.end - a.start) || a.order - b.order);
+        const coveredMatches = [];
+        for (const match of matches) {
+            const previous = coveredMatches[coveredMatches.length - 1];
+            if (previous && match.start < previous.end) {
+                // Preserve the selected replacement, but cover the entire overlapping
+                // interval so a longer secret cannot survive behind a shorter match.
+                previous.end = Math.max(previous.end, match.end);
+            }
+            else {
+                coveredMatches.push({ ...match });
+            }
+        }
+        let output = "";
+        let cursor = 0;
+        for (const match of coveredMatches) {
+            output += text.slice(cursor, match.start) + match.replacement;
+            cursor = match.end;
+        }
+        return output + text.slice(cursor);
+    };
+    return {
+        configPath,
+        maskText,
+        maskValue: (value) => maskStrings(value, maskText),
+        maskToolResult: (result, options) => {
+            const output = { ...result };
+            if (Array.isArray(output.content))
+                output.content = output.content.map(item => {
+                    if (!item || typeof item !== "object")
+                        return item;
+                    const block = { ...item };
+                    if (typeof block.text === "string") {
+                        block.text =
+                            options?.textFormat === "plain"
+                                ? maskText(block.text)
+                                : maskJsonText(block.text, maskText);
+                    }
+                    return block;
+                });
+            if (output.structuredContent !== undefined)
+                output.structuredContent = maskStrings(output.structuredContent, maskText);
+            return output;
+        },
+        maskError: (error) => {
+            if (error instanceof Error && !maskedErrors.has(error)) {
+                error.message = maskText(error.message);
+                maskedErrors.add(error);
+            }
+            return error;
+        },
+    };
+}
+export function createMaskingEngine(options) {
+    if (!options.enabled)
+        return undefined;
+    const workspaceDir = path.resolve(options.workspaceDir ?? process.cwd());
+    const configPath = options.configPath
+        ? path.resolve(workspaceDir, options.configPath)
+        : path.join(workspaceDir, ".gitlab-mcp-mask.json");
+    if (options.configPath && !fs.existsSync(configPath)) {
+        throw new Error(`Configured masking config does not exist: ${configPath}`);
+    }
+    const file = fs.existsSync(configPath) ? loadFile(configPath) : undefined;
+    if (isManagedReference(file))
+        throw new Error("Managed masking references require a managed policy resolver");
+    return createMaskingEngineFromFile(file ?? {}, fs.existsSync(configPath) ? configPath : undefined);
+}
+/**
+ * Selects a compiled policy for each tool request. In managed mode this keeps
+ * the secret rules on the server while the workspace carries only a group name.
+ */
+export function createMaskingPolicyResolver(options) {
+    if (!options.enabled)
+        return undefined;
+    const workspaceDir = path.resolve(options.workspaceDir ?? process.cwd());
+    const localConfigPath = options.configPath
+        ? path.resolve(workspaceDir, options.configPath)
+        : path.join(workspaceDir, ".gitlab-mcp-mask.json");
+    if (options.configPath && !fs.existsSync(localConfigPath)) {
+        throw new Error(`Configured masking config does not exist: ${localConfigPath}`);
+    }
+    const localConfig = fs.existsSync(localConfigPath) ? loadFile(localConfigPath) : undefined;
+    const localGroup = isManagedReference(localConfig) ? localConfig.policyGroup : undefined;
+    if (!options.policyFilePath) {
+        if (localGroup)
+            throw new Error("Managed masking config requires GITLAB_MASKING_POLICY_FILE");
+        const localEngine = createMaskingEngineFromFile(localConfig ?? {}, localConfigPath);
+        return { managed: false, select: () => localEngine };
+    }
+    const policyPath = path.resolve(workspaceDir, options.policyFilePath);
+    const policyFile = loadManagedPolicyFile(policyPath);
+    if (localGroup && !policyFile.policyGroups[localGroup]) {
+        throw new Error(`Managed masking config references unknown policy group: ${localGroup}`);
+    }
+    const engines = new Map();
+    for (const [name, policy] of Object.entries(policyFile.policyGroups)) {
+        engines.set(name, createMaskingEngineFromFile(policy, policyPath));
+    }
+    const builtinEngine = createMaskingEngineFromFile({}, policyPath);
+    const bindings = new Map();
+    for (const binding of policyFile.bindings) {
+        const instance = normalizeGitLabInstance(binding.gitlabInstance);
+        for (const projectId of binding.projectIds) {
+            const key = `${instance}#${projectId}`;
+            const existing = bindings.get(key);
+            if (existing && existing !== binding.policyGroup) {
+                throw new Error(`Managed masking policy has conflicting bindings for ${key}`);
+            }
+            bindings.set(key, binding.policyGroup);
+        }
+    }
+    return {
+        managed: true,
+        select: ({ gitlabInstance, projectIds = [], hasProjectScope = projectIds.length > 0, allowBuiltinForUnscoped = false, }) => {
+            const numericProjectIds = projectIds.map(projectId => {
+                if (typeof projectId === "number" && Number.isSafeInteger(projectId) && projectId > 0) {
+                    return projectId;
+                }
+                if (typeof projectId === "string" && /^\d+$/.test(projectId)) {
+                    const numericProjectId = Number(projectId);
+                    if (Number.isSafeInteger(numericProjectId) && numericProjectId > 0)
+                        return numericProjectId;
+                }
+                throw new Error("Managed masking requires numeric project IDs");
+            });
+            if (numericProjectIds.length === 0) {
+                if (hasProjectScope)
+                    throw new Error("Managed masking requires a project ID");
+                if (allowBuiltinForUnscoped || policyFile.unboundProjectBehavior === "builtin")
+                    return builtinEngine;
+                throw new Error("Managed masking policy does not cover this project-less tool");
+            }
+            const groups = new Set();
+            for (const projectId of numericProjectIds) {
+                const group = bindings.get(`${normalizeGitLabInstance(gitlabInstance)}#${projectId}`);
+                if (!group)
+                    throw new Error("No managed masking policy is bound to this GitLab project");
+                groups.add(group);
+            }
+            if (groups.size !== 1) {
+                throw new Error("Managed masking does not allow a tool call to span policy groups");
+            }
+            const [group] = groups;
+            if (localGroup && group !== localGroup) {
+                throw new Error("Managed masking policy group does not match the server project binding");
+            }
+            const engine = engines.get(group);
+            if (!engine)
+                throw new Error(`Managed masking policy group is unavailable: ${group}`);
+            return engine;
+        },
+    };
+}

package/build/masking/index.js

@@ -0,0 +1,2 @@
+export * from "./engine.js";
+export * from "./project-scope.js";

package/build/masking/project-scope.js

@@ -0,0 +1,53 @@
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function collectDeclaredProjectIds(schema, value, projectIds) {
+    if (!isRecord(value))
+        return;
+    for (const [field, fieldSchema] of Object.entries(schema.properties ?? {})) {
+        const fieldValue = value[field];
+        if (field === "project_id" || field.endsWith("_project_id")) {
+            if (fieldValue !== undefined && fieldValue !== null && fieldValue !== "")
+                projectIds.push(fieldValue);
+            continue;
+        }
+        if (Array.isArray(fieldValue) && fieldSchema.items) {
+            for (const item of fieldValue)
+                collectDeclaredProjectIds(fieldSchema.items, item, projectIds);
+        }
+        else if (fieldSchema.properties) {
+            collectDeclaredProjectIds(fieldSchema, fieldValue, projectIds);
+        }
+    }
+}
+/**
+ * Return project identifiers declared by the tool schema, including nested
+ * request objects that the tool can use to access another project. This avoids
+ * both accepting undeclared arguments and overlooking a cross-project action.
+ */
+export function getManagedMaskingProjectIds(inputSchema, argumentsValue, getDefaultProjectId) {
+    const properties = inputSchema?.properties;
+    if (!properties)
+        return { hasProjectScope: false, projectIds: [] };
+    const args = isRecord(argumentsValue) ? argumentsValue : {};
+    const projectIds = [];
+    collectDeclaredProjectIds({ properties }, args, projectIds);
+    const hasPrimaryProjectField = Object.hasOwn(properties, "project_id");
+    const primaryProjectIsMissing = args.project_id === undefined || args.project_id === null || args.project_id === "";
+    // A group-scoped tool may declare project_id as an alternative. Do not turn
+    // that absent optional field into the server default when group_id was chosen.
+    const hasAlternativeScope = primaryProjectIsMissing &&
+        Object.keys(properties).some(field => (field === "group_id" || field.endsWith("_group_id")) && args[field] !== undefined);
+    // A project filter on a group query does not establish the scope of all
+    // projects contributing to its response.
+    if (hasAlternativeScope)
+        return { hasProjectScope: false, projectIds: [] };
+    if (hasPrimaryProjectField && primaryProjectIsMissing && getDefaultProjectId) {
+        projectIds.unshift(getDefaultProjectId());
+    }
+    return {
+        hasProjectScope: projectIds.length > 0 ||
+            (inputSchema?.required ?? []).some(field => field === "project_id" || field.endsWith("_project_id")),
+        projectIds,
+    };
+}

package/build/schemas.js

@@ -1720,6 +1720,10 @@ export const GetMergeRequestNoteSchema = ProjectParamsSchema.extend({
     merge_request_iid: z.coerce.string().describe("The IID of a merge request"),
     note_id: z.coerce.string().describe("The ID of a thread note"),
 });
+export const GetMergeRequestDiscussionSchema = ProjectParamsSchema.extend({
+    merge_request_iid: z.coerce.string().describe("The IID of a merge request"),
+    discussion_id: z.coerce.string().describe("The ID of a thread"),
+});
 // Input schema for updating merge request notes
 export const UpdateMergeRequestNoteSchema = ProjectParamsSchema.extend({
     merge_request_iid: z.coerce.string().describe("The IID of a merge request"),

package/build/test/get-merge-request-discussion-schema.test.js

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { GetMergeRequestDiscussionSchema, GitLabDiscussionSchema } from "../schemas.js";
+test("get discussion input coerces numeric ids and keeps discussion id", () => {
+    const parsed = GetMergeRequestDiscussionSchema.parse({
+        project_id: 42,
+        merge_request_iid: 7,
+        discussion_id: "abc123",
+    });
+    assert.equal(parsed.project_id, "42");
+    assert.equal(parsed.merge_request_iid, "7");
+    assert.equal(parsed.discussion_id, "abc123");
+});
+test("get discussion input rejects a missing discussion id", () => {
+    assert.throws(() => GetMergeRequestDiscussionSchema.parse({
+        project_id: "42",
+        merge_request_iid: "7",
+    }));
+});
+test("single discussion response parses the GitLab discussion item shape", () => {
+    const parsed = GitLabDiscussionSchema.parse({
+        id: "abc123",
+        individual_note: false,
+        notes: [{ id: 1, body: "please fix", resolvable: true, resolved: false }],
+    });
+    assert.equal(parsed.id, "abc123");
+    assert.equal(parsed.individual_note, false);
+    assert.equal(parsed.notes.length, 1);
+    assert.equal(parsed.notes[0].body, "please fix");
+});