@zackbart/connecta 0.28.1 → 0.29.0

package/dist/providers/forms/skill.generated.js

@@ -0,0 +1,11 @@
+// Generated by scripts/generate-providers.mjs; do not edit.
+export const skill = {
+    "content": "# Google Forms usage\n\nActs as the signed-in person in Google Forms through Workspace delegation: read and edit their forms, read responses, never submit or delete.\n\nConnection purpose: \n\n## Whose forms\n\nEvery call reaches only the forms the Workspace user deployment config maps\nthe caller to can open. No argument names a user. A call with none mapped\nfails `auth_required`; only an operator can change the mapping. A form id\nthat does not exist and one not shared with that user fail alike, as\n`connector_call_failed`: Google does not say which.\n\n## Finding forms\n\nThere is no list or search here: the Forms API has none. Find a form in\nDrive, or take its id from an edit URL (`/forms/d/<formId>/edit`). The\n`/forms/d/e/…` responder link is not the form id.\n\n## Reading\n\n- Every result stays inside  KiB, so it crosses into\n  `execute_code` whole. A page that would outgrow that ends early with\n  `page.hasMore`; follow `page.nextCursor` rather than raising `limit`.\n- `get_form` lists items with their `questions`: one for a question,\n  one per row for a grid, none for sections and media. Answers are keyed by\n  those `questionId`s. A large form pages its items (`itemCount` is the\n  total), and a grid too large for one page continues on the next: the item\n  repeats with `questionsFrom`, the index of its first row there, and\n  `moreQuestions` counts rows still to come. A cursor from a form that has\n  since changed fails `conflict`.\n  Long text is cut with a marker; `raw: true` returns Google's whole Form\n  resource, or refuses one too large for a result.\n- `list_responses` labels each answer with its question's title, in form\n  order; an answer to a since-deleted question has no title. Answers longer\n  than  characters end with a truncation marker; `get_response`\n  reads one whole. Page with `page.nextCursor` and the same\n  `submittedAfter`. To read only new responses, pass the newest\n  `lastSubmittedTime` already seen as `submittedAfter`. A cursor\n  continues after the last response it returned; if Google's page has\n  changed since (new, deleted, or reordered responses), it fails\n  `conflict` — start again, or use `submittedAfter`.\n- A response too large for one result comes back cut, with the answers left\n  out named in `omittedQuestionIds`; pass them to `get_response` as\n  `questionIds`.\n\n## Editing\n\n- `create_form` makes an empty form: Google takes only its title and Drive\n  file name at creation. Add a description and questions afterwards.\n- `update_form_info` replaces the title or description.\n- `batch_update_form` is the escape hatch for everything else, and always\n  needs approval. It takes Google's own Request objects, applied all or none,\n  with the form's current `revisionId` as `requiredRevisionId`: a form\n  someone changed since you read it is refused as `conflict`, so re-read it\n  and rebuild the edit. Its reply carries the new `revisionId` and each created item's id.\n  A reply too large to return whole comes back with `truncated: true`: the\n  batch still applied; read the rest with `get_form`. An `updateItem` needs an `updateMask`; read `raw: true` first so the\n  item it replaces keeps its grading, images, and navigation.\n- Publishing, sharing, deleting, and watches are not in this connection; the\n  owner does those in Forms or Drive. Responses are read-only.\n",
+    "instructionsHeading": "Connection instructions",
+    "fragments": {
+        "guide_0": "# Google Forms usage\n\nActs as the signed-in person in Google Forms through Workspace delegation: read and edit their forms, read responses, never submit or delete.\n\nConnection purpose: ",
+        "guide_1": "\n\n## Whose forms\n\nEvery call reaches only the forms the Workspace user deployment config maps\nthe caller to can open. No argument names a user. A call with none mapped\nfails `auth_required`; only an operator can change the mapping. A form id\nthat does not exist and one not shared with that user fail alike, as\n`connector_call_failed`: Google does not say which.\n\n## Finding forms\n\nThere is no list or search here: the Forms API has none. Find a form in\nDrive, or take its id from an edit URL (`/forms/d/<formId>/edit`). The\n`/forms/d/e/…` responder link is not the form id.\n\n## Reading\n\n- Every result stays inside ",
+        "guide_2": " KiB, so it crosses into\n  `execute_code` whole. A page that would outgrow that ends early with\n  `page.hasMore`; follow `page.nextCursor` rather than raising `limit`.\n- `get_form` lists items with their `questions`: one for a question,\n  one per row for a grid, none for sections and media. Answers are keyed by\n  those `questionId`s. A large form pages its items (`itemCount` is the\n  total), and a grid too large for one page continues on the next: the item\n  repeats with `questionsFrom`, the index of its first row there, and\n  `moreQuestions` counts rows still to come. A cursor from a form that has\n  since changed fails `conflict`.\n  Long text is cut with a marker; `raw: true` returns Google's whole Form\n  resource, or refuses one too large for a result.\n- `list_responses` labels each answer with its question's title, in form\n  order; an answer to a since-deleted question has no title. Answers longer\n  than ",
+        "guide_3": " characters end with a truncation marker; `get_response`\n  reads one whole. Page with `page.nextCursor` and the same\n  `submittedAfter`. To read only new responses, pass the newest\n  `lastSubmittedTime` already seen as `submittedAfter`. A cursor\n  continues after the last response it returned; if Google's page has\n  changed since (new, deleted, or reordered responses), it fails\n  `conflict` — start again, or use `submittedAfter`.\n- A response too large for one result comes back cut, with the answers left\n  out named in `omittedQuestionIds`; pass them to `get_response` as\n  `questionIds`.\n\n## Editing\n\n- `create_form` makes an empty form: Google takes only its title and Drive\n  file name at creation. Add a description and questions afterwards.\n- `update_form_info` replaces the title or description.\n- `batch_update_form` is the escape hatch for everything else, and always\n  needs approval. It takes Google's own Request objects, applied all or none,\n  with the form's current `revisionId` as `requiredRevisionId`: a form\n  someone changed since you read it is refused as `conflict`, so re-read it\n  and rebuild the edit. Its reply carries the new `revisionId` and each created item's id.\n  A reply too large to return whole comes back with `truncated: true`: the\n  batch still applied; read the rest with `get_form`. An `updateItem` needs an `updateMask`; read `raw: true` first so the\n  item it replaces keeps its grading, images, and navigation.\n- Publishing, sharing, deleting, and watches are not in this connection; the\n  owner does those in Forms or Drive. Responses are read-only.\n"
+    }
+};

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

@@ -0,0 +1,32 @@
+import { type GuardedRequest } from "../../connectors/guarded-fetch.js";
+import type { ConnectorContext } from "../../types.js";
+import { ScopePolicy, type Target } from "./scope.js";
+export interface GitHubApp {
+    appId: string | number;
+    /** Deployment secret. Omit to read the connector's privateKey vault field. */
+    privateKey?: string;
+}
+export type Permissions = Readonly<Record<string, "read" | "write">>;
+export declare class AppAuth {
+    readonly app: GitHubApp;
+    readonly policy: ScopePolicy;
+    private readonly installations;
+    private readonly tokens;
+    private readonly repositories;
+    private readonly grants;
+    private readonly orgInstallations;
+    private readonly configuredDer?;
+    private readonly appId;
+    constructor(app: GitHubApp, policy: ScopePolicy);
+    private key;
+    json(request: GuardedRequest, bearer: string, ctx: ConnectorContext): Promise<unknown>;
+    private invalidate;
+    rejectToken(bearer: string): Promise<void>;
+    private installation;
+    private repository;
+    private authorizeId;
+    token(owner: string, repos: readonly string[] | undefined, permissions: Permissions, ctx: ConnectorContext): Promise<string>;
+    private mint;
+    checkResult(t: Target, id: unknown, token: string, ctx: ConnectorContext): Promise<void>;
+    repo(t: Target, permissions: Permissions, ctx: ConnectorContext): Promise<string>;
+}

package/dist/providers/github/auth.js

@@ -0,0 +1,361 @@
+import { guardedFetch, retryAfterMs } from "../../connectors/guarded-fetch.js";
+import { ConnectorCallError } from "../../errors.js";
+import { attachFailureFacts } from "../../operator-record.js";
+import { appJwt, privateKeyDer } from "./key.js";
+import { target } from "./scope.js";
+const MAX_ENTRIES = 256;
+const REFRESH_MARGIN = 60_000;
+const INSTALLATION_TTL = 300_000;
+const REPOSITORY_TTL = 300_000;
+function boundedSet(map, key, value) {
+    if (!map.has(key) && map.size >= MAX_ENTRIES)
+        map.delete(map.keys().next().value);
+    map.set(key, value);
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export class AppAuth {
+    app;
+    policy;
+    // These maps retain completed scalar values, never a request promise,
+    // signal, transport, response, or crypto import promise. No disk tokens.
+    installations = new Map();
+    tokens = new Map();
+    repositories = new Map();
+    // Configured grants bind once for this provider's lifetime, independent of
+    // expiring name lookups and key rotation. Never evict or silently rebind a
+    // grant to a new repository that reuses its name. At most 100 config entries.
+    grants = new Map();
+    orgInstallations = new Map();
+    configuredDer;
+    appId;
+    constructor(app, policy) {
+        this.app = app;
+        this.policy = policy;
+        if (!app ||
+            !/^[1-9][0-9]*$/.test(String(app.appId)) ||
+            (typeof app.appId !== "string" && typeof app.appId !== "number") ||
+            (typeof app.appId === "number" && !Number.isSafeInteger(app.appId))) {
+            throw new Error("app.appId to be a positive GitHub App ID.");
+        }
+        this.appId = String(app.appId);
+        if (app.privateKey !== undefined) {
+            if (typeof app.privateKey !== "string")
+                throw new Error("app.privateKey to be an RSA PEM or omitted for the vault slot.");
+            this.configuredDer = privateKeyDer(app.privateKey);
+        }
+    }
+    async key(ctx) {
+        ctx.signal?.throwIfAborted();
+        let der = this.configuredDer;
+        if (!der) {
+            const pem = await ctx.credential?.get("privateKey");
+            if (!pem)
+                throw new ConnectorCallError("auth_required", "Configure the GitHub App private key in this connector's vault slot.");
+            try {
+                der = privateKeyDer(pem);
+            }
+            catch {
+                throw new ConnectorCallError("auth_required", "Replace the GitHub App private key with a complete RSA PEM.");
+            }
+        }
+        const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", der));
+        ctx.signal?.throwIfAborted();
+        return {
+            der,
+            fingerprint: `${this.appId}:${Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("")}`,
+        };
+    }
+    async json(request, bearer, ctx) {
+        ctx.signal?.throwIfAborted();
+        const transport = guardedFetch({
+            provider: "GitHub",
+            baseUrl: "https://api.github.com",
+            maxResponseBytes: 4 * 1024 * 1024,
+            headers: {
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": "connecta",
+            },
+            authenticate: () => ({ Authorization: `Bearer ${bearer}` }),
+        });
+        return transport(request, ctx, async (response) => {
+            if (!response.ok) {
+                // Dispose of the body without interpreting error text or Content-Type.
+                await response.prefix(0);
+                const status = response.status;
+                const reset = Number(response.headers.get("x-ratelimit-reset"));
+                const retry = retryAfterMs(response.headers);
+                const wait = retry ?? (Number.isFinite(reset) && reset > 0 ? Math.max(0, reset * 1000 - Date.now()) : undefined);
+                const rate = status === 429 ||
+                    (status === 403 && (retry !== undefined || response.headers.get("x-ratelimit-remaining") === "0"));
+                if (status === 401 || (status === 403 && !rate))
+                    this.invalidate(bearer);
+                const code = rate
+                    ? "rate_limited"
+                    : status === 401 || status === 403
+                        ? "auth_required"
+                        : status === 409
+                            ? "conflict"
+                            : status >= 500
+                                ? "unavailable"
+                                : "connector_call_failed";
+                throw attachFailureFacts(new ConnectorCallError(code, rate
+                    ? "GitHub rate limit reached. Honor the retry timing before trying again."
+                    : code === "auth_required"
+                        ? "Verify the GitHub App key, installation, repository selection and required permissions."
+                        : code === "conflict"
+                            ? "GitHub rejected a stale version. Read the current state before resubmitting."
+                            : status === 404
+                                ? "GitHub returned 404; the resource may be absent or inaccessible to this installation."
+                                : "The GitHub API request failed; downstream error text is withheld.", { retryable: rate || status >= 500, ...(rate && wait !== undefined ? { retryAfterMs: wait } : {}) }), { httpStatus: status });
+            }
+            const parsed = await response.jsonResult();
+            ctx.signal?.throwIfAborted();
+            if ("parseError" in parsed)
+                throw new ConnectorCallError("connector_call_failed", "GitHub returned malformed JSON; response text is withheld.");
+            return parsed.value;
+        });
+    }
+    invalidate(bearer) {
+        for (const [key, token] of this.tokens) {
+            if (token.value !== bearer)
+                continue;
+            this.tokens.delete(key);
+            for (const [owner, installation] of this.installations) {
+                if (installation.id === token.installation)
+                    this.installations.delete(owner);
+            }
+        }
+    }
+    async rejectToken(bearer) {
+        this.invalidate(bearer);
+    }
+    async installation(owner, ctx, key) {
+        this.policy.owner(owner);
+        const cacheKey = `${key.fingerprint}:${owner}`;
+        const previous = this.installations.get(cacheKey);
+        if (previous && previous.expires > Date.now())
+            return previous;
+        let jwt;
+        try {
+            jwt = await appJwt(this.appId, key.der, Date.now());
+        }
+        catch {
+            throw new ConnectorCallError("auth_required", "The GitHub App key could not sign an RS256 JWT. Replace the key.");
+        }
+        let found;
+        for (let page = 1; page <= 20; page++) {
+            const data = await this.json({ method: "GET", path: "/app/installations", query: { per_page: 100, page } }, jwt, ctx);
+            if (!Array.isArray(data))
+                throw new ConnectorCallError("connector_call_failed", "GitHub returned an invalid installation list.");
+            for (const item of data) {
+                const row = record(item);
+                const account = record(row.account);
+                if (typeof account.login !== "string" || account.login.toLowerCase() !== owner)
+                    continue;
+                if (!Number.isSafeInteger(row.id) || Number(row.id) <= 0 || row.suspended_at != null) {
+                    throw new ConnectorCallError("auth_required", "Install or unsuspend the GitHub App on the configured owner.");
+                }
+                found = {
+                    id: Number(row.id),
+                    owner,
+                    all: row.repository_selection === "all",
+                    organization: account.type === "Organization",
+                    expires: Date.now() + INSTALLATION_TTL,
+                };
+            }
+            if (data.length < 100)
+                break;
+            if (page === 20)
+                throw new ConnectorCallError("connector_call_failed", "The GitHub installation list exceeded its paging bound; no partial mapping was cached.");
+        }
+        if (!found)
+            throw new ConnectorCallError("auth_required", "Install the GitHub App on the configured owner and grant the configured repositories.");
+        if (this.policy.repositories(owner) === undefined && (!found.all || !found.organization)) {
+            throw new ConnectorCallError("auth_required", "Org scopes require an organization installation with All repositories selected, including future repositories.");
+        }
+        ctx.signal?.throwIfAborted();
+        // Compare-and-set by entry identity. A slower request cannot overwrite a
+        // completed mapping installed by another request while it was paging.
+        const current = this.installations.get(cacheKey);
+        const resolved = current !== previous ? (current ?? found) : found;
+        if (this.policy.repositories(owner) === undefined) {
+            const bound = this.orgInstallations.get(owner);
+            if (bound !== undefined && bound !== resolved.id)
+                throw new ConnectorCallError("auth_required", "The organization grant is bound to a different installation. Reconfigure after reviewing the replacement installation.");
+            this.orgInstallations.set(owner, resolved.id);
+        }
+        if (this.installations.get(cacheKey) === previous)
+            boundedSet(this.installations, cacheKey, resolved);
+        return resolved;
+    }
+    async repository(owner, name, installation, key, ctx) {
+        const prefix = `${key.fingerprint}:${installation.id}:`;
+        const cacheKey = `${prefix}${owner}/${name}`;
+        const previous = this.repositories.get(cacheKey);
+        if (previous && previous.expires > Date.now())
+            return previous;
+        // GitHub requires an installation token for /installation/repositories.
+        // Mint with the App JWT, metadata only, and never give this resolver token
+        // to the hosted server or a caller-selected REST operation.
+        const resolver = await this.mint(owner, installation, key, undefined, { metadata: "read" }, ctx, "resolver");
+        const found = new Map();
+        const configured = this.policy.scopes.filter((scope) => scope.repo?.startsWith(`${owner}/`));
+        for (let page = 1; page <= 100; page++) {
+            const data = record(await this.json({ method: "GET", path: "/installation/repositories", query: { per_page: 100, page } }, resolver, ctx));
+            if (!Array.isArray(data.repositories))
+                throw new ConnectorCallError("connector_call_failed", "GitHub returned an invalid repository list.");
+            for (const item of data.repositories) {
+                const row = record(item);
+                const parts = typeof row.full_name === "string" ? row.full_name.split("/") : [];
+                const t = target(parts[0], parts.length === 2 ? parts[1] : undefined);
+                if (t.owner !== owner || !Number.isSafeInteger(row.id) || Number(row.id) <= 0)
+                    throw new ConnectorCallError("connector_call_failed", "GitHub returned an invalid installation repository binding.");
+                const fullName = `${t.owner}/${t.repo}`;
+                if (t.repo === name ||
+                    configured.some((scope) => scope.repo === fullName || this.grants.get(scope.repo) === row.id)) {
+                    found.set(fullName, { ...t, id: Number(row.id), expires: Date.now() + REPOSITORY_TTL });
+                }
+            }
+            if (data.repositories.length < 100)
+                break;
+            if (page === 100)
+                throw new ConnectorCallError("connector_call_failed", "The installation repository list exceeded its paging bound; no partial mapping was cached.");
+        }
+        ctx.signal?.throwIfAborted();
+        // Commit only complete, uncancelled reads. An earlier completed binding
+        // wins even if a slower read observed the old name before a rename.
+        for (const grant of configured) {
+            const repo = found.get(grant.repo);
+            if (!this.grants.has(grant.repo) && repo)
+                this.grants.set(grant.repo, repo.id);
+            if (!this.grants.has(grant.repo))
+                throw new ConnectorCallError("auth_required", "A configured repository grant could not be bound in this installation.");
+            if (!repo) {
+                const renamed = [...found.values()].find((candidate) => candidate.id === this.grants.get(grant.repo));
+                if (renamed)
+                    found.set(grant.repo, renamed);
+            }
+        }
+        for (const [fullName, repo] of found) {
+            const current = this.repositories.get(`${prefix}${fullName}`);
+            if (!current || current === previous || current.expires <= Date.now())
+                boundedSet(this.repositories, `${prefix}${fullName}`, repo);
+            for (const grant of configured)
+                if (this.grants.get(grant.repo) === repo.id)
+                    this.policy.bindAlias(repo, grant);
+        }
+        const resolved = this.repositories.get(cacheKey);
+        if (!resolved || resolved.expires <= Date.now())
+            throw new ConnectorCallError("auth_required", "The repository is not reachable in the configured installation. Verify its selection or current name.");
+        return resolved;
+    }
+    authorizeId(repo, permissions) {
+        const grant = this.policy.scope(repo, Object.values(permissions).includes("write"), permissions.workflows === "write");
+        if (grant.repo && this.grants.get(grant.repo) !== repo.id)
+            throw new ConnectorCallError("invalid_args", "This repository name now identifies a different repository outside its bound grant.");
+        // An exact grant's restrictions survive a rename beneath an org grant.
+        for (const scope of this.policy.scopes) {
+            if (scope.repo && this.grants.get(scope.repo) === repo.id) {
+                if ((Object.values(permissions).includes("write") && scope.access !== "read-write") ||
+                    (permissions.workflows === "write" && scope.workflows !== "write")) {
+                    throw new ConnectorCallError("invalid_args", "The bound repository grant does not permit this operation.");
+                }
+            }
+        }
+    }
+    async token(owner, repos, permissions, ctx) {
+        // All routes, including discovery, validate scope before touching a key.
+        owner = this.policy.owner(owner);
+        if (repos)
+            for (const repo of repos)
+                this.policy.scope({ owner, repo }, Object.values(permissions).includes("write"), permissions.workflows === "write");
+        else if (Object.values(permissions).includes("write"))
+            throw new ConnectorCallError("invalid_args", "GitHub writes require exact repository targets.");
+        const key = await this.key(ctx);
+        const installation = await this.installation(owner, ctx, key);
+        const names = repos ?? this.policy.repositories(owner);
+        const ids = [];
+        if (names)
+            for (const name of names) {
+                const repo = await this.repository(owner, name, installation, key, ctx);
+                this.authorizeId(repo, permissions);
+                ids.push(repo.id);
+            }
+        const repositorySet = names ? [...new Set(ids)].sort((a, b) => a - b) : undefined;
+        return this.mint(owner, installation, key, repositorySet, permissions, ctx);
+    }
+    async mint(owner, installation, key, repositorySet, permissions, ctx, purpose = "operation") {
+        const permissionSet = Object.fromEntries(Object.entries(permissions).sort(([a], [b]) => a.localeCompare(b)));
+        const cacheKey = JSON.stringify([key.fingerprint, installation.id, repositorySet ?? "all", permissionSet, purpose]);
+        const previous = this.tokens.get(cacheKey);
+        if (previous && previous.expires > Date.now() + REFRESH_MARGIN)
+            return previous.value;
+        let jwt;
+        try {
+            jwt = await appJwt(this.appId, key.der, Date.now());
+        }
+        catch {
+            throw new ConnectorCallError("auth_required", "The GitHub App key could not sign an RS256 JWT. Replace the key.");
+        }
+        let response;
+        try {
+            response = record(await this.json({
+                method: "POST",
+                path: `/app/installations/${installation.id}/access_tokens`,
+                body: { permissions: permissionSet, ...(repositorySet ? { repository_ids: repositorySet } : {}) },
+            }, jwt, ctx));
+        }
+        catch (error) {
+            // Re-resolve on the next call, never replay this call. Fence a slow
+            // failure so it cannot erase another request's newer installation.
+            const ownerKey = `${key.fingerprint}:${owner}`;
+            if (this.installations.get(ownerKey) === installation)
+                this.installations.delete(ownerKey);
+            throw error;
+        }
+        const expiry = typeof response.expires_at === "string" ? Date.parse(response.expires_at) : NaN;
+        if (typeof response.token !== "string" ||
+            !response.token ||
+            /[^\x21-\x7e]/.test(response.token) ||
+            !Number.isFinite(expiry) ||
+            expiry <= Date.now() + REFRESH_MARGIN) {
+            throw new ConnectorCallError("auth_required", "GitHub returned an invalid or already expiring installation token.");
+        }
+        ctx.signal?.throwIfAborted();
+        const completed = {
+            value: response.token,
+            expires: Math.min(expiry, Date.now() + 3_600_000),
+            installation: installation.id,
+            ...(repositorySet ? { repositoryIds: repositorySet } : {}),
+        };
+        if (this.tokens.get(cacheKey) === previous)
+            boundedSet(this.tokens, cacheKey, completed);
+        return this.tokens.get(cacheKey)?.value ?? completed.value;
+    }
+    async checkResult(t, id, token, ctx) {
+        this.policy.owner(t.owner);
+        if (id === undefined) {
+            const repo = record(await this.json({ method: "GET", path: `/repos/${encodeURIComponent(t.owner)}/${encodeURIComponent(t.repo)}` }, token, ctx));
+            id = repo.id;
+        }
+        const key = await this.key(ctx);
+        const installation = await this.installation(t.owner, ctx, key);
+        const repo = await this.repository(t.owner, t.repo, installation, key, ctx);
+        this.authorizeId(repo, {});
+        const issued = [...this.tokens.values()].find((entry) => entry.value === token);
+        if (!Number.isSafeInteger(id) ||
+            id !== repo.id ||
+            !issued ||
+            issued.installation !== installation.id ||
+            (issued.repositoryIds && !issued.repositoryIds.includes(repo.id))) {
+            throw new ConnectorCallError("connector_call_failed", "GitHub returned a repository outside the bound scope; results were withheld.");
+        }
+    }
+    async repo(t, permissions, ctx) {
+        this.policy.scope(t, Object.values(permissions).includes("write"), permissions.workflows === "write");
+        return this.token(t.owner, [t.repo], permissions, ctx);
+    }
+}

package/dist/providers/github/hosted.js

@@ -0,0 +1,218 @@
+import { ConnectorCallError } from "../../errors.js";
+import { target, workflowPath } from "./scope.js";
+// Exact reviewed ownership map. New upstream names, arguments and methods
+// require review before they can authenticate or dispatch.
+export const HOSTED_ROUTES = {
+    get_file_contents: {
+        verdict: "read",
+        permissions: { "contents": "read" },
+        keys: ["fields", "owner", "path", "ref", "repo", "sha"],
+    },
+    get_commit: {
+        verdict: "read",
+        permissions: { "contents": "read" },
+        keys: ["detail", "owner", "page", "perPage", "repo", "sha"],
+    },
+    list_commits: {
+        verdict: "read",
+        permissions: { "contents": "read" },
+        keys: ["author", "fields", "owner", "page", "path", "perPage", "repo", "sha", "since", "until"],
+    },
+    list_branches: { verdict: "read", permissions: { "contents": "read" }, keys: ["owner", "page", "perPage", "repo"] },
+    get_tag: { verdict: "read", permissions: { "contents": "read" }, keys: ["owner", "repo", "tag"] },
+    list_tags: { verdict: "read", permissions: { "contents": "read" }, keys: ["owner", "page", "perPage", "repo"] },
+    get_latest_release: { verdict: "read", permissions: { "contents": "read" }, keys: ["owner", "repo"] },
+    get_release_by_tag: { verdict: "read", permissions: { "contents": "read" }, keys: ["owner", "repo", "tag"] },
+    list_releases: {
+        verdict: "read",
+        permissions: { "contents": "read" },
+        keys: ["fields", "owner", "page", "perPage", "repo"],
+    },
+    list_issues: {
+        verdict: "read",
+        permissions: { "issues": "read", "pull_requests": "read" },
+        keys: [
+            "after",
+            "direction",
+            "field_filters",
+            "fields",
+            "labels",
+            "orderBy",
+            "owner",
+            "perPage",
+            "repo",
+            "since",
+            "state",
+        ],
+    },
+    issue_read: {
+        verdict: "read",
+        permissions: { "issues": "read" },
+        keys: ["issue_number", "method", "owner", "page", "perPage", "repo"],
+        methods: ["get", "get_comments", "get_labels"],
+    },
+    get_label: { verdict: "read", permissions: { "issues": "read" }, keys: ["name", "owner", "repo"] },
+    list_pull_requests: {
+        verdict: "read",
+        permissions: { "pull_requests": "read" },
+        keys: ["base", "direction", "fields", "head", "owner", "page", "perPage", "repo", "sort", "state"],
+    },
+    pull_request_read: {
+        verdict: "read",
+        permissions: { "pull_requests": "read", "contents": "read", "checks": "read", "statuses": "read" },
+        keys: ["after", "method", "owner", "page", "perPage", "pullNumber", "repo"],
+        methods: [
+            "get",
+            "get_diff",
+            "get_status",
+            "get_files",
+            "get_commits",
+            "get_review_comments",
+            "get_reviews",
+            "get_comments",
+            "get_check_runs",
+        ],
+    },
+    actions_list: {
+        verdict: "read",
+        permissions: { "actions": "read" },
+        keys: ["method", "owner", "page", "perPage", "repo", "resource_id", "workflow_jobs_filter", "workflow_runs_filter"],
+        methods: ["list_workflows", "list_workflow_runs", "list_workflow_jobs", "list_workflow_run_artifacts"],
+    },
+    actions_get: {
+        verdict: "read",
+        permissions: { "actions": "read" },
+        keys: ["method", "owner", "repo", "resource_id"],
+        methods: ["get_workflow", "get_workflow_run", "get_workflow_run_usage", "get_workflow_job"],
+    },
+    issue_write: {
+        verdict: "destructive",
+        permissions: { "issues": "write", "pull_requests": "write" },
+        keys: [
+            "assignees",
+            "body",
+            "duplicate_of",
+            "issue_fields",
+            "issue_number",
+            "labels",
+            "method",
+            "milestone",
+            "owner",
+            "parent_issue_number",
+            "parent_owner",
+            "parent_repo",
+            "repo",
+            "state",
+            "state_reason",
+            "title",
+            "type",
+        ],
+        methods: ["create", "update"],
+    },
+    add_issue_comment: {
+        verdict: "write",
+        permissions: { "issues": "write", "pull_requests": "write" },
+        keys: ["body", "comment_id", "issue_number", "owner", "reaction", "repo"],
+    },
+    create_pull_request: {
+        verdict: "write",
+        permissions: { "pull_requests": "write" },
+        keys: ["base", "body", "draft", "head", "maintainer_can_modify", "owner", "repo", "reviewers", "title"],
+    },
+    update_pull_request: {
+        verdict: "destructive",
+        permissions: { "pull_requests": "write" },
+        keys: [
+            "base",
+            "body",
+            "draft",
+            "maintainer_can_modify",
+            "owner",
+            "pullNumber",
+            "repo",
+            "reviewers",
+            "state",
+            "title",
+        ],
+    },
+    pull_request_review_write: {
+        verdict: "destructive",
+        permissions: { "pull_requests": "write" },
+        keys: ["body", "commitID", "event", "method", "owner", "pullNumber", "repo", "threadId"],
+        methods: ["create", "submit_pending", "delete_pending"],
+    },
+    create_branch: {
+        verdict: "write",
+        permissions: { "contents": "write" },
+        keys: ["branch", "from_branch", "owner", "repo"],
+    },
+    create_or_update_file: {
+        verdict: "destructive",
+        permissions: { "contents": "write" },
+        keys: ["allow_symlink_write", "branch", "content", "message", "owner", "path", "repo", "sha"],
+    },
+    delete_file: {
+        verdict: "destructive",
+        permissions: { "contents": "write" },
+        keys: ["branch", "message", "owner", "path", "repo"],
+    },
+    push_files: {
+        verdict: "destructive",
+        permissions: { "contents": "write" },
+        keys: ["branch", "files", "message", "owner", "repo"],
+    },
+    actions_run_trigger: {
+        verdict: "destructive",
+        permissions: { "actions": "write" },
+        keys: ["inputs", "method", "owner", "ref", "repo", "run_id", "workflow_id"],
+        methods: ["run_workflow", "rerun_workflow_run", "rerun_failed_jobs", "cancel_workflow_run"],
+    },
+};
+export const HOSTED_CLASSIFICATION = {
+    unlisted: "hide",
+    tools: Object.fromEntries(Object.entries(HOSTED_ROUTES).map(([name, route]) => [name, route.verdict])),
+};
+export function hostedTarget(name, input, policy) {
+    const route = Object.hasOwn(HOSTED_ROUTES, name) ? HOSTED_ROUTES[name] : undefined;
+    if (!route)
+        throw new ConnectorCallError("invalid_args", "This GitHub tool is not in the reviewed allowlist.");
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new ConnectorCallError("invalid_args", "Supply GitHub arguments as an object.");
+    const args = input;
+    const t = target(args.owner, args.repo);
+    policy.scope(t, route.verdict !== "read");
+    if (Object.keys(args).some((key) => !route.keys.includes(key)))
+        throw new ConnectorCallError("invalid_args", "Unreviewed GitHub arguments are refused; use the reviewed tool schema.");
+    if (route.methods && !route.methods.includes(String(args.method)))
+        throw new ConnectorCallError("invalid_args", "This GitHub method is not in the reviewed allowlist.");
+    // Secondary repositories and opaque review-thread IDs cannot choose a grant.
+    if (args.parent_owner !== undefined ||
+        args.parent_repo !== undefined ||
+        args.threadId !== undefined ||
+        args.comment_id !== undefined) {
+        throw new ConnectorCallError("invalid_args", "Cross-repository parent references and opaque comment/thread IDs are not supported. Use the scoped repository operation.");
+    }
+    if (args.allow_symlink_write === true)
+        throw new ConnectorCallError("invalid_args", "Symlink writes cannot establish a workflow-file boundary.");
+    if (name === "create_pull_request" && (typeof args.head !== "string" || args.head.includes(":")))
+        throw new ConnectorCallError("invalid_args", "Create pull requests from a branch in the target repository; cross-owner heads are not supported.");
+    let workflows = false;
+    if (["create_or_update_file", "delete_file"].includes(name))
+        workflows = workflowPath(args.path);
+    if (name === "push_files") {
+        if (!Array.isArray(args.files) || args.files.length === 0 || args.files.length > 100)
+            throw new ConnectorCallError("invalid_args", "Supply between 1 and 100 file changes.");
+        for (const file of args.files) {
+            if (!file ||
+                typeof file !== "object" ||
+                Array.isArray(file) ||
+                Object.keys(file).some((key) => !["path", "content"].includes(key)))
+                throw new ConnectorCallError("invalid_args", "Each file has only path and content fields.");
+            workflows = workflowPath(file.path) || workflows;
+        }
+    }
+    if (name === "get_file_contents" && args.path !== undefined && args.path !== "")
+        workflowPath(args.path);
+    policy.scope(t, route.verdict !== "read", workflows);
+    return { target: t, permissions: { ...route.permissions, ...(workflows ? { workflows: "write" } : {}) } };
+}

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

@@ -0,0 +1,13 @@
+import { type ProviderOptions } from "../../provider.js";
+import { type GitHubApp } from "./auth.js";
+import { type GitHubScope } from "./scope.js";
+export type { GitHubApp } from "./auth.js";
+export type { GitHubScope } from "./scope.js";
+export declare const GITHUB_MCP_ENDPOINT = "https://api.githubcopilot.com/mcp/";
+export interface GitHubOptions extends ProviderOptions {
+    app: GitHubApp;
+    /** Mixed org and exact repository grants, with explicit access. */
+    scopes: readonly GitHubScope[];
+}
+/** One GitHub App, multiple owner installations, explicit org/repo grants. */
+export declare const github: import("../../provider.js").ProviderFactory<GitHubOptions>;