@zackbart/connecta 0.28.0 → 0.29.0

package/dist/providers/github/index.js

@@ -0,0 +1,140 @@
+import { remoteMcp } from "../../connectors/remote-mcp.js";
+import { array, keys, optionsOf } from "../../config-schema.js";
+import { ConnectorCallError } from "../../errors.js";
+import { redactSentSecrets } from "../../sent-secrets.js";
+import { defineProvider, PROVIDER_COMMON } from "../../provider.js";
+import { AppAuth } from "./auth.js";
+import { HOSTED_CLASSIFICATION, HOSTED_ROUTES, hostedTarget } from "./hosted.js";
+import { restConnector } from "./rest.js";
+import { parseScopes, ScopePolicy } from "./scope.js";
+import { skill } from "./skill.generated.js";
+export const GITHUB_MCP_ENDPOINT = "https://api.githubcopilot.com/mcp/";
+const CLASSIFICATION = {
+    unlisted: "hide",
+    tools: {
+        ...HOSTED_CLASSIFICATION.tools,
+        list_scopes: "read",
+        search_scoped: "read",
+        create_release: "write",
+        update_release: "destructive",
+        delete_release: "destructive",
+        merge_pull_request: "destructive",
+    },
+};
+/** One GitHub App, multiple owner installations, explicit org/repo grants. */
+export const github = defineProvider({
+    name: "github",
+    title: "GitHub",
+    kind: "composed",
+    skill,
+    classify: CLASSIFICATION,
+    bundle: {
+        baselineGzip: 164063,
+        maxGzip: 224063,
+        note: "./providers/github initial measured baseline includes the hosted MCP SDK plus portable GitHub App signing, exact routing and REST complements; cap retains the existing 60,000-byte provider headroom policy.",
+    },
+    options: optionsOf()({
+        ...PROVIDER_COMMON,
+        app: optionsOf()(keys("appId", "privateKey")),
+        scopes: array(optionsOf()(keys("org", "repo", "access", "workflows"))),
+    }),
+    create(id, options, provider) {
+        if (options.authScope === "personal")
+            throw new Error("shared GitHub App identity; per-user OAuth attribution is planned separately for 0.29.");
+        const policy = new ScopePolicy(parseScopes(options.scopes));
+        const auth = new AppAuth(options.app, policy);
+        const rest = restConnector(id, auth, policy);
+        const usageGuide = provider.usageGuide({
+            context: [`Act as the GitHub App. Reachable configuration: ${policy.summary()}.`, `Purpose: ${options.purpose}`],
+            summary: "GitHub App scopes, installation routing, confined search and workflow-file limits.",
+            required: true,
+        });
+        // Each operation owns its token-bound client, transport and callback.
+        // It closes them before returning; no shared header or client mutation.
+        const hosted = (token, classify = HOSTED_CLASSIFICATION) => remoteMcp(id, {
+            url: GITHUB_MCP_ENDPOINT,
+            requireHttps: true,
+            redirects: "none",
+            classify,
+            auth: {
+                type: "request",
+                token: async () => token,
+                headers: {
+                    "X-MCP-Toolsets": "repos,git,issues,pull_requests,actions,labels",
+                    "X-MCP-Tools": Object.keys(HOSTED_ROUTES).join(","),
+                },
+            },
+        });
+        const withHosted = async (token, ctx, run) => {
+            const client = hosted(token);
+            try {
+                return await run(client);
+            }
+            catch (error) {
+                if (error instanceof ConnectorCallError && error.code === "auth_required")
+                    await auth.rejectToken(token);
+                throw redactSentSecrets(ctx, error);
+            }
+            finally {
+                await client.closeScope?.(ctx);
+            }
+        };
+        const credential = options.app.privateKey === undefined
+            ? {
+                label: "GitHub App private key",
+                description: "RSA PEM for the deployment's GitHub App. Stored encrypted in the configured credential vault.",
+                fields: [{ name: "privateKey", label: "Private key PEM", inputType: "password" }],
+            }
+            : undefined;
+        return {
+            id,
+            title: options.title ?? "GitHub",
+            kind: "mcp",
+            authScope: "shared",
+            ...provider.connectorOptions,
+            ...(credential ? { credential } : {}),
+            classification: provider.classify,
+            description: `GitHub App access to ${policy.summary()}.`,
+            usageGuide,
+            describe: () => ({
+                source: { kind: "custom" },
+                endpoint: { origin: "https://api.githubcopilot.com", path: "/mcp/" },
+                auth: { mode: "request", header: "Authorization", scheme: "Bearer" },
+            }),
+            async listTools(ctx) {
+                // Catalog discovery authenticates only a configured scope, with read
+                // permissions. Fetch one complete vendor catalog and preserve schemas.
+                const first = policy.scopes[0];
+                const owner = first.org ?? first.repo.split("/")[0];
+                const repos = first.repo ? [first.repo.split("/")[1]] : undefined;
+                const token = await auth.token(owner, repos, {
+                    contents: "read",
+                    issues: "read",
+                    pull_requests: "read",
+                    actions: "read",
+                    checks: "read",
+                    statuses: "read",
+                }, ctx);
+                const facts = await withHosted(token, ctx, (client) => client.listTools(ctx));
+                const complement = await rest.listTools(ctx);
+                // Names not reviewed never leave this boundary, including collisions
+                // with the REST complement. The registry alone applies verdicts.
+                return [...facts.filter((tool) => Object.hasOwn(HOSTED_ROUTES, tool.name)), ...complement];
+            },
+            async callTool(name, args, ctx, callOptions) {
+                if (Object.hasOwn(HOSTED_ROUTES, name)) {
+                    const route = hostedTarget(name, args, policy);
+                    const token = await auth.repo(route.target, route.permissions, ctx);
+                    return withHosted(token, ctx, (client) => client.callTool(name, args, ctx, callOptions));
+                }
+                if (!Object.hasOwn(CLASSIFICATION.tools, name))
+                    throw new ConnectorCallError("invalid_args", "This GitHub tool is not in the reviewed allowlist.");
+                const result = await rest.callTool(name, args, ctx, callOptions);
+                return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
+            },
+            async status() {
+                return { state: "ok", message: "GitHub App configured; installation access is resolved lazily on use." };
+            },
+        };
+    },
+});

package/dist/providers/github/key.js

@@ -0,0 +1,100 @@
+// GitHub downloads PKCS#1 PEMs. WebCrypto imports PKCS#8, so wrap the RSA
+// sequence without interpreting or reserializing its private integers.
+function sequence(tag, content) {
+    let length = content.length;
+    const octets = [];
+    if (length < 128)
+        octets.push(length);
+    else {
+        while (length) {
+            octets.unshift(length & 255);
+            length >>>= 8;
+        }
+        octets.unshift(128 | octets.length);
+    }
+    return new Uint8Array([tag, ...octets, ...content]);
+}
+function element(bytes, offset) {
+    const tag = bytes[offset++];
+    let length = bytes[offset++];
+    if (tag === undefined || length === undefined)
+        throw new Error("invalid DER");
+    if (length & 128) {
+        const count = length & 127;
+        if (!count || count > 4 || offset + count > bytes.length)
+            throw new Error("invalid DER");
+        length = 0;
+        for (let i = 0; i < count; i++)
+            length = length * 256 + bytes[offset++];
+    }
+    if (offset + length > bytes.length)
+        throw new Error("invalid DER");
+    return { tag, start: offset, end: offset + length };
+}
+const ALGORITHM = new Uint8Array([
+    0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00,
+]);
+export function privateKeyDer(pem) {
+    try {
+        const match = /^-----BEGIN (RSA PRIVATE KEY|PRIVATE KEY)-----\s*([A-Za-z0-9+/=\s]+)\s*-----END \1-----$/.exec(pem.replace(/\\n/g, "\n").trim());
+        if (!match)
+            throw new Error("invalid PEM");
+        const binary = atob(match[2].replace(/\s/g, ""));
+        const der = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+        const outer = element(der, 0);
+        if (outer.tag !== 0x30 || outer.end !== der.length)
+            throw new Error("invalid DER");
+        const version = element(der, outer.start);
+        if (version.tag !== 2 || version.end - version.start !== 1 || der[version.start] !== 0)
+            throw new Error("invalid version");
+        let rsa = der;
+        if (match[1] === "PRIVATE KEY") {
+            const algorithm = element(der, version.end);
+            if (algorithm.end - version.end !== ALGORITHM.length ||
+                !ALGORITHM.every((byte, i) => byte === der[version.end + i]))
+                throw new Error("not RSA");
+            const octet = element(der, algorithm.end);
+            if (octet.tag !== 4 || octet.end !== outer.end)
+                throw new Error("invalid PKCS8");
+            rsa = der.slice(octet.start, octet.end);
+        }
+        const root = element(rsa, 0);
+        let offset = root.start;
+        const integers = [];
+        while (offset < root.end) {
+            const integer = element(rsa, offset);
+            if (integer.tag !== 2 || integer.end <= integer.start || integer.end > root.end)
+                throw new Error("invalid RSA");
+            integers.push(integer);
+            offset = integer.end;
+        }
+        if (root.tag !== 0x30 || root.end !== rsa.length || integers.length !== 9 || rsa[integers[0].start] !== 0)
+            throw new Error("invalid RSA");
+        const modulus = integers[1];
+        const first = modulus.start + (rsa[modulus.start] === 0 ? 1 : 0);
+        const bits = (modulus.end - first - 1) * 8 + 32 - Math.clz32(rsa[first]);
+        if (bits < 2048)
+            throw new Error("weak RSA");
+        if (match[1] === "PRIVATE KEY")
+            return der;
+        return sequence(0x30, new Uint8Array([2, 1, 0, ...ALGORITHM, ...sequence(4, rsa)]));
+    }
+    catch {
+        throw new Error("app.privateKey to be a complete PKCS#1 or PKCS#8 RSA PEM with at least 2048 bits.");
+    }
+}
+function base64url(bytes) {
+    let text = "";
+    for (const byte of bytes)
+        text += String.fromCharCode(byte);
+    return btoa(text).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+export async function appJwt(appId, der, now) {
+    const encoder = new TextEncoder();
+    const seconds = Math.floor(now / 1000);
+    const data = `${base64url(encoder.encode(JSON.stringify({ alg: "RS256", typ: "JWT" })))}.${base64url(encoder.encode(JSON.stringify({ iat: seconds - 60, exp: seconds + 540, iss: appId })))}`;
+    const key = await crypto.subtle.importKey("pkcs8", der, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, [
+        "sign",
+    ]);
+    return `${data}.${base64url(new Uint8Array(await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, encoder.encode(data))))}`;
+}

package/dist/providers/github/rest.js

@@ -0,0 +1,321 @@
+import { api } from "../../connectors/api.js";
+import { ConnectorCallError } from "../../errors.js";
+import { target } from "./scope.js";
+const text = (description) => ({ type: "string", minLength: 1, description });
+const ownerRepo = { owner: text("Configured repository owner."), repo: text("Repository name under that owner.") };
+const object = (properties, required = []) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const integer = (description) => ({ type: "integer", minimum: 1, description });
+const bool = (description) => ({ type: "boolean", description });
+const jsonObject = { type: "object", additionalProperties: true };
+const scopeRecord = object({
+    org: { type: "string" },
+    repo: { type: "string" },
+    access: { type: "string", enum: ["read", "read-write"] },
+    workflows: { type: "string", enum: ["write"] },
+}, ["access"]);
+const selector = object({
+    org: text("Configured org scope."),
+    repo: text("Exact owner/repo within configured scope."),
+});
+const repoPath = (t) => `/repos/${encodeURIComponent(t.owner)}/${encodeURIComponent(t.repo)}`;
+const row = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+function selectors(input, policy) {
+    if (!Array.isArray(input) || input.length === 0 || input.length > 100)
+        throw new ConnectorCallError("invalid_args", "Select between 1 and 100 configured scopes.");
+    return input.map((item) => {
+        const value = row(item);
+        if ((value.org === undefined) === (value.repo === undefined))
+            throw new ConnectorCallError("invalid_args", "Each selector names either org or repo.");
+        if (value.org !== undefined) {
+            const owner = policy.owner(value.org);
+            const grant = policy.scopes.find((scope) => scope.org === owner);
+            if (!grant)
+                throw new ConnectorCallError("invalid_args", "This org is not configured for org-wide access.");
+            return grant;
+        }
+        const parts = typeof value.repo === "string" ? value.repo.split("/") : [];
+        const t = target(parts[0], parts.length === 2 ? parts[1] : undefined);
+        const grant = policy.scope(t);
+        return { repo: `${t.owner}/${t.repo}`, access: grant.access };
+    });
+}
+function searchPartitions(scopes) {
+    const orgs = new Set(scopes.flatMap((scope) => (scope.org ? [scope.org] : [])));
+    const repos = new Map();
+    for (const scope of scopes) {
+        if (!scope.repo)
+            continue;
+        const [owner, repo] = scope.repo.split("/");
+        if (orgs.has(owner))
+            continue;
+        if (!repos.has(owner))
+            repos.set(owner, new Set());
+        repos.get(owner).add(repo);
+    }
+    const partitions = [...orgs].sort().map((owner) => ({ id: `org:${owner}`, owner, qualifier: `org:${owner}` }));
+    const result = [...partitions];
+    for (const [owner, names] of [...repos].sort(([a], [b]) => a.localeCompare(b))) {
+        const sorted = [...names].sort();
+        for (let offset = 0; offset < sorted.length; offset += 5) {
+            const chunk = sorted.slice(offset, offset + 5);
+            result.push({
+                id: chunk.map((repo) => `${owner}/${repo}`).join(","),
+                owner,
+                repos: chunk,
+                qualifier: chunk.map((repo) => `repo:${owner}/${repo}`).join(" "),
+            });
+        }
+    }
+    if (result.length > 20)
+        throw new ConnectorCallError("invalid_args", "Search fan-out exceeds 20 partitions. Select fewer scopes.");
+    return result;
+}
+function resultTarget(item, kind) {
+    if (kind === "repositories" || kind === "code") {
+        const name = kind === "code" ? row(item.repository).full_name : item.full_name;
+        const parts = typeof name === "string" ? name.split("/") : [];
+        return target(parts[0], parts.length === 2 ? parts[1] : undefined);
+    }
+    let url;
+    try {
+        url = new URL(item.repository_url);
+    }
+    catch {
+        throw new ConnectorCallError("connector_call_failed", "GitHub search omitted the repository binding.");
+    }
+    const match = /^\/repos\/([^/]+)\/([^/]+)$/.exec(url.pathname);
+    if (url.origin !== "https://api.github.com" || !match || url.search || url.hash)
+        throw new ConnectorCallError("connector_call_failed", "GitHub search returned an invalid repository binding.");
+    return target(match[1], match[2]);
+}
+export function restConnector(id, auth, policy) {
+    const scopedRequest = async (args, permissions, method, suffix, body, ctx) => {
+        const t = target(args.owner, args.repo);
+        policy.scope(t, true);
+        const token = await auth.repo(t, permissions, ctx);
+        const data = await auth.json({ method, path: `${repoPath(t)}${suffix}`, ...(body !== undefined ? { body } : {}) }, token, ctx);
+        return data ?? { deleted: true };
+    };
+    const tools = [
+        {
+            name: "list_scopes",
+            description: "List configured GitHub scopes and reachable repositories for one owner.",
+            annotations: { readOnlyHint: true },
+            inputSchema: object({
+                owner: text("Configured owner; omit to return configuration without network access."),
+                page: integer("Repository page, default 1, at most 1000."),
+                per_page: { ...integer("Repositories per page, default 100."), maximum: 100 },
+            }),
+            outputSchema: object({
+                acting_as: { type: "string" },
+                scopes: { type: "array", items: scopeRecord },
+                repositories: { type: "array", items: { type: "string" } },
+                next_page: { type: ["integer", "null"] },
+            }, ["acting_as", "scopes"]),
+            async handler(args, ctx) {
+                if (args.owner === undefined)
+                    return { acting_as: "GitHub App", scopes: policy.scopes };
+                const owner = policy.owner(args.owner);
+                const page = args.page ?? 1;
+                const count = args.per_page ?? 100;
+                if (page > 1000)
+                    throw new ConnectorCallError("invalid_args", "Repository page must be at most 1000.");
+                const token = await auth.token(owner, undefined, { metadata: "read" }, ctx);
+                const data = row(await auth.json({ method: "GET", path: "/installation/repositories", query: { page, per_page: count } }, token, ctx));
+                if (!Array.isArray(data.repositories))
+                    throw new ConnectorCallError("connector_call_failed", "GitHub returned an invalid repository list.");
+                const repositories = [];
+                for (const item of data.repositories) {
+                    const repository = row(item);
+                    const t = resultTarget(repository, "repositories");
+                    if (t.owner !== owner)
+                        throw new ConnectorCallError("connector_call_failed", "GitHub returned a repository from another installation owner.");
+                    await auth.checkResult(t, repository.id, token, ctx);
+                    repositories.push(`${t.owner}/${t.repo}`);
+                }
+                return {
+                    acting_as: "GitHub App",
+                    scopes: policy.scopes.filter((scope) => scope.org === owner || scope.repo?.startsWith(`${owner}/`)),
+                    repositories,
+                    next_page: repositories.length === count ? page + 1 : null,
+                };
+            },
+        },
+        {
+            name: "search_scoped",
+            description: "Search GitHub repositories, issues, pull requests or code within configured scopes.",
+            annotations: { readOnlyHint: true },
+            inputSchema: object({
+                terms: text("Literal words only; scope qualifiers and Boolean operators are refused."),
+                kind: {
+                    type: "string",
+                    enum: ["repositories", "issues", "pull-requests", "code"],
+                    description: "Resource to search.",
+                },
+                scopes: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 100,
+                    items: selector,
+                    description: "Optional subset; defaults to all configured scopes.",
+                },
+                pages: {
+                    type: "object",
+                    additionalProperties: { type: "integer", minimum: 1, maximum: 10 },
+                    description: "Page per returned partition ID, at most 10.",
+                },
+                per_page: { ...integer("Results per partition, default 30."), maximum: 100 },
+            }, ["terms", "kind"]),
+            outputSchema: object({ partitions: { type: "array", items: jsonObject }, incomplete_results: { type: "boolean" } }, ["partitions", "incomplete_results"]),
+            async handler(args, ctx) {
+                if (!/^[a-z0-9_. -]{1,128}$/i.test(args.terms) || /\b(?:OR|NOT|AND)\b/i.test(args.terms))
+                    throw new ConnectorCallError("invalid_args", "Search terms must be literal words, without qualifiers or Boolean operators.");
+                const selected = args.scopes === undefined ? policy.scopes : selectors(args.scopes, policy);
+                const partitions = searchPartitions(selected);
+                if (Object.keys(args.pages ?? {}).some((key) => !partitions.some((partition) => partition.id === key)))
+                    throw new ConnectorCallError("invalid_args", "Pagination keys must match the selected search partitions.");
+                const type = args.kind === "issues" ? " is:issue" : args.kind === "pull-requests" ? " is:pr" : "";
+                const queries = partitions.map((partition) => `${partition.qualifier} ${args.terms.trim()}${type}`);
+                if (queries.some((query) => query.length > 256))
+                    throw new ConnectorCallError("invalid_args", "The scoped search query exceeds GitHub's 256-character bound. Select fewer repositories.");
+                const seen = new Set();
+                const output = [];
+                let incomplete = false;
+                for (const partition of partitions) {
+                    const page = args.pages?.[partition.id] ?? 1;
+                    const count = args.per_page ?? 30;
+                    const permissions = args.kind === "repositories"
+                        ? { metadata: "read" }
+                        : args.kind === "code"
+                            ? { contents: "read" }
+                            : { issues: "read", pull_requests: "read" };
+                    const token = await auth.token(partition.owner, partition.repos, permissions, ctx);
+                    const kind = args.kind === "pull-requests" ? "issues" : args.kind;
+                    const query = `${partition.qualifier} ${args.terms.trim()}${type}`;
+                    const data = row(await auth.json({ method: "GET", path: `/search/${kind}`, query: { q: query, page, per_page: count } }, token, ctx));
+                    if (!Array.isArray(data.items))
+                        throw new ConnectorCallError("connector_call_failed", "GitHub returned an invalid search result.");
+                    const items = [];
+                    for (const value of data.items) {
+                        const item = row(value);
+                        const t = resultTarget(item, args.kind);
+                        policy.owner(t.owner);
+                        if (t.owner !== partition.owner)
+                            throw new ConnectorCallError("connector_call_failed", "GitHub search escaped its selected partition; results were withheld.");
+                        await auth.checkResult(t, args.kind === "repositories" ? item.id : args.kind === "code" ? row(item.repository).id : undefined, token, ctx);
+                        const key = `${args.kind}:${t.owner}/${t.repo}:${args.kind === "code" ? item.path : item.id}`;
+                        if (!seen.has(key)) {
+                            seen.add(key);
+                            items.push(value);
+                        }
+                    }
+                    const more = data.items.length === count || data.total_count > page * count;
+                    const limited = data.incomplete_results === true || (more && page === 10);
+                    incomplete ||= limited;
+                    output.push({
+                        scope: partition.id,
+                        items,
+                        total_count: data.total_count,
+                        incomplete_results: limited,
+                        next_page: more && page < 10 ? page + 1 : null,
+                    });
+                }
+                return { partitions: output, incomplete_results: incomplete };
+            },
+        },
+        {
+            name: "create_release",
+            description: "Create a GitHub release, optionally as a draft.",
+            annotations: { readOnlyHint: false },
+            inputSchema: object({
+                ...ownerRepo,
+                tag_name: text("Release tag."),
+                target_commitish: text("Branch or commit for a new tag."),
+                name: text("Release title."),
+                body: { type: "string", description: "Release notes." },
+                draft: bool("Create a draft release."),
+                prerelease: bool("Mark as a prerelease."),
+            }, ["owner", "repo", "tag_name"]),
+            outputSchema: jsonObject,
+            handler: (args, ctx) => {
+                const { owner: _owner, repo: _repo, ...body } = args;
+                return scopedRequest(args, { contents: "write" }, "POST", "/releases", body, ctx);
+            },
+        },
+        {
+            name: "update_release",
+            description: "Update or publish an existing GitHub release.",
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            inputSchema: object({
+                ...ownerRepo,
+                release_id: integer("Release ID in this repository."),
+                tag_name: text("Release tag."),
+                name: text("Release title."),
+                body: { type: "string", description: "Release notes." },
+                draft: bool("Set false to publish a draft."),
+                prerelease: bool("Mark as a prerelease."),
+            }, ["owner", "repo", "release_id"]),
+            outputSchema: jsonObject,
+            handler: (args, ctx) => {
+                const { owner: _owner, repo: _repo, release_id, ...body } = args;
+                return scopedRequest(args, { contents: "write" }, "PATCH", `/releases/${release_id}`, body, ctx);
+            },
+        },
+        {
+            name: "delete_release",
+            description: "Delete a GitHub release from the scoped repository.",
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            inputSchema: object({ ...ownerRepo, release_id: integer("Release ID in this repository.") }, [
+                "owner",
+                "repo",
+                "release_id",
+            ]),
+            outputSchema: jsonObject,
+            handler: (args, ctx) => scopedRequest(args, { contents: "write" }, "DELETE", `/releases/${args.release_id}`, undefined, ctx),
+        },
+        {
+            name: "merge_pull_request",
+            description: "Merge a same-repository GitHub pull request with explicit workflow-write scope.",
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            inputSchema: object({
+                ...ownerRepo,
+                pull_number: integer("Pull request number."),
+                sha: text("Expected head commit SHA; reread after a conflict."),
+                merge_method: {
+                    type: "string",
+                    enum: ["merge", "squash", "rebase"],
+                    description: "Merge strategy, default merge.",
+                },
+            }, ["owner", "repo", "pull_number", "sha"]),
+            outputSchema: jsonObject,
+            async handler(args, ctx) {
+                const t = target(args.owner, args.repo);
+                // GitHub's atomic sha guard binds only the head, not the base/ref.
+                // Retargeting can turn a file-safe diff into workflow changes. Require
+                // explicit workflow permission before any authentication for merges.
+                policy.scope(t, true, true);
+                const reader = await auth.repo(t, { pull_requests: "read", contents: "read" }, ctx);
+                const pr = row(await auth.json({ method: "GET", path: `${repoPath(t)}/pulls/${args.pull_number}` }, reader, ctx));
+                const head = row(pr.head);
+                const base = row(pr.base);
+                if (head.sha !== args.sha ||
+                    row(head.repo).full_name?.toLowerCase() !== `${t.owner}/${t.repo}` ||
+                    row(base.repo).full_name?.toLowerCase() !== `${t.owner}/${t.repo}`)
+                    throw new ConnectorCallError("conflict", "Merge requires the expected head SHA and a same-repository head and base. Reread the pull request.");
+                const token = await auth.repo(t, { contents: "write", pull_requests: "write", workflows: "write" }, ctx);
+                // GitHub verifies sha atomically. No automatic write retry.
+                return auth.json({
+                    method: "PUT",
+                    path: `${repoPath(t)}/pulls/${args.pull_number}/merge`,
+                    body: { sha: args.sha, merge_method: args.merge_method ?? "merge" },
+                }, token, ctx);
+            },
+        },
+    ];
+    return api(id, { tools });
+}

package/dist/providers/github/scope.d.ts

@@ -0,0 +1,29 @@
+export type GitHubScope = ({
+    org: string;
+    repo?: never;
+} | {
+    repo: string;
+    org?: never;
+}) & {
+    access: "read" | "read-write";
+    /** Allow edits under .github/workflows. Omitted by default. */
+    workflows?: "write";
+};
+export interface Target {
+    owner: string;
+    repo: string;
+}
+export declare function target(owner: unknown, repo: unknown): Target;
+export declare function parseScopes(input: readonly GitHubScope[]): readonly GitHubScope[];
+export declare class ScopePolicy {
+    readonly scopes: readonly GitHubScope[];
+    private readonly aliases;
+    constructor(scopes: readonly GitHubScope[]);
+    scope(t: Target, write?: boolean, workflows?: boolean): GitHubScope;
+    bindAlias(t: Target, grant: GitHubScope): void;
+    summary(): string;
+    owner(owner: unknown): string;
+    repositories(owner: string): string[] | undefined;
+}
+/** Git paths are literal, canonical paths. Reject aliases before authentication. */
+export declare function workflowPath(path: unknown): boolean;