The Open Framework for Building Agents
feat(git): add authorize callback to github config (#4869)
roboeve[bot]4210766b5c54
diff --git a/.changeset/git-github-authorize.md b/.changeset/git-github-authorize.mdnew file mode 100644index 000000000..32f7b3950--- /dev/null+++ b/.changeset/git-github-authorize.md@@ -0,0 +1,5 @@+---+"eve": minor+---++`git({ github })` accepts an optional `authorize` callback that runs once per `gh` tool invocation with the caller, declared repository, and repository-scoped token; returning `false` blocks the command. It gates caller/repository access, not individual API requests or operations, and allowed commands use the app token's permissions rather than the caller's GitHub permissions.diff --git a/docs/code-extension.mdx b/docs/code-extension.mdxindex 1a5a2c138..e8508a108 100644--- a/docs/code-extension.mdx+++ b/docs/code-extension.mdx@@ -97,9 +97,37 @@ Configure `github` to broker GitHub access through Connect instead. The extensio| `github.connector` | With `github` | Connector that mints a GitHub token || `github.org` | With `github` | Organization whose repositories the `gh` tool can access || `github.broker` | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |+| `github.authorize` | No | `authorize({ auth, repository, token })` callback that allows or denies each `gh` tool invocation |The `gh` tool requests a token scoped to exactly one repository in `github.org` for each invocation. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.+`github.authorize` runs during each `gh` tool execution, not when the session starts. The order is: validate the command and repository, mint the repository-scoped app token, await `authorize({ auth, repository, token })`, install the credential lease, then run the command. `auth` is the session's current caller at tool invocation, or `null`. Returning `false` stops execution before the lease is installed or the command runs. The decision applies to that invocation only; it is neither cached for the session nor repeated for each GitHub API request.++For example, use the token to check collaborator status (allowed commands still use the app token's permissions, not the collaborator's):++```ts title="agent/extensions/git.ts"+import git from "eve/extensions/git";++import { brokerGitHubLease } from "../lib/github";++export default git({+ github: {+ connector: "github/my-agent",+ org: "acme",+ broker: brokerGitHubLease,+ // GitHub channel sessions carry the commenter's login as `auth.subject`.+ async authorize({ auth, repository, token }) {+ if (auth?.authenticator !== "github-webhook" || !auth.subject) return false;+ const response = await fetch(+ `https://api.github.com/repos/${repository}/collaborators/${auth.subject}`,+ { headers: { authorization: `Bearer ${token}` } },+ );+ return response.status === 204;+ },+ },+});+```+### Migrate from `code({ github })``code({ github })` is deprecated. While it is set, the code extension still contributes `code__gh`, its GitHub instructions, and the signed-commit `code__pr` skill. Without it, the code extension contributes no GitHub tool, instructions, or pull request skill. Move the `github` option to `git({ github })`, and import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`.diff --git a/packages/eve-git/extension/extension.ts b/packages/eve-git/extension/extension.tsindex 691a92ac3..f34d19082 100644--- a/packages/eve-git/extension/extension.ts+++ b/packages/eve-git/extension/extension.ts@@ -1,9 +1,10 @@import { defineExtension } from "eve/extension";import { z } from "zod";-import type { GitHubConfig } from "./lib/github-shell.ts";+import type { GitHubAuthorize, GitHubConfig } from "./lib/github-shell.ts";export type { GitHubLeaseRule } from "./lib/github-shell.ts";+export type { GitHubAuthorize, GitHubAuthorizeRequest } from "./lib/github-shell.ts";export type GitHubLeaseBroker = GitHubConfig["broker"];const fn = <T>() => z.custom<T>((value) => typeof value === "function");@@ -20,6 +21,12 @@ export default defineExtension({connector: z.string().min(1),org: z.string().min(1),broker: fn<GitHubLeaseBroker>(),+ /**+ * Called before each `gh` command with the session's caller, the+ * declared repository, and its scoped token. Return `false` to deny.+ * Without it, the GitHub App installation is the only boundary.+ */+ authorize: fn<GitHubAuthorize>().optional(),}).optional(),}),diff --git a/packages/eve-git/extension/lib/gh-tool.ts b/packages/eve-git/extension/lib/gh-tool.tsindex 25fc4dcb9..cfbe97bf1 100644--- a/packages/eve-git/extension/lib/gh-tool.ts+++ b/packages/eve-git/extension/lib/gh-tool.ts@@ -29,6 +29,7 @@ export function defineGhTool(}),execute(input, ctx) {return executeGitHubShell(input, github(), {+ auth: ctx.session.auth.current,getSandbox: () => ctx.getSandbox(),sessionId: ctx.session.id,});diff --git a/packages/eve-git/extension/lib/github-shell.ts b/packages/eve-git/extension/lib/github-shell.tsindex e972a2258..8a344aa8e 100644--- a/packages/eve-git/extension/lib/github-shell.ts+++ b/packages/eve-git/extension/lib/github-shell.ts@@ -1,5 +1,6 @@import { posix } from "node:path";import { getToken, type ConnectTokenParams } from "@vercel/connect";+import type { SessionAuthContext } from "eve/context";import type { SandboxSession } from "eve/sandbox";import { validateRepositoryRoot } from "./repository-root.ts";@@ -27,6 +28,7 @@ export interface GitHubShellOutput {}export interface GitHubConfig {+ readonly authorize?: GitHubAuthorize;readonly broker: (sandbox: SandboxSession,rules: Readonly<Record<string, readonly GitHubLeaseRule[]>> | null,@@ -35,6 +37,19 @@ export interface GitHubConfig {readonly org: string;}+/** What an `authorize` callback sees before a `gh` command runs. */+export interface GitHubAuthorizeRequest {+ /** The session's current caller, or `null` when the session has none. */+ readonly auth: SessionAuthContext | null;+ /** The `owner/name` repository the command declared. */+ readonly repository: string;+ /** The repository-scoped GitHub App token minted for this command, for API lookups. */+ readonly token: string;+}++/** Decides whether the session's caller may run a `gh` command against one repository. */+export type GitHubAuthorize = (request: GitHubAuthorizeRequest) => boolean | Promise<boolean>;+export interface GitHubLeaseRule {readonly match?: {readonly headers?: readonly {@@ -46,6 +61,7 @@ export interface GitHubLeaseRule {}interface GitHubShellDependencies {+ readonly auth?: SessionAuthContext | null;readonly getConnectToken?: typeof getToken;readonly getSandbox: () => Promise<SandboxSession>;/** Serializes credential leases per eve session; every `ctx.getSandbox()` call returns a new handle. */@@ -96,6 +112,13 @@ export async function executeGitHubShell(const token = await (dependencies.getConnectToken ?? getToken)(config.connector, tokenParams);if (!token)throw new Error(`Connect returned an empty token for ${JSON.stringify(config.connector)}.`);+ const repository = declaredRepositories[0]!;+ if (+ config.authorize &&+ !(await config.authorize({ auth: dependencies.auth ?? null, repository, token }))+ ) {+ throw new Error(`The current caller is not authorized to access ${repository}.`);+ }const executable = executablePath(argv[0]!);const executionArguments = remoteRepositorydiff --git a/packages/eve-git/test/integration/github-shell.test.ts b/packages/eve-git/test/integration/github-shell.test.tsindex 6cce98319..1376f350f 100644--- a/packages/eve-git/test/integration/github-shell.test.ts+++ b/packages/eve-git/test/integration/github-shell.test.ts@@ -112,6 +112,50 @@ test("runs clone without approval while retaining repository-scoped write-capablassert.equal(runs.length, 1);});+test("asks authorize with the caller, repository, and token before running", async () => {+ const auth = {+ attributes: {},+ authenticator: "github-webhook",+ principalId: "github:octocat",+ principalType: "user",+ subject: "octocat",+ };+ const requests: unknown[] = [];+ const runs: Parameters<SandboxSession["run"]>[0][] = [];+ const dependencies = {+ auth,+ sessionId: "session-authorize",+ async getConnectToken() {+ return "secret-token";+ },+ async getSandbox() {+ return fakeSandbox(runs, { exitCode: 0, stdout: "", stderr: "" });+ },+ };++ await assert.rejects(+ executeGitHubShell(+ READ,+ {+ ...CONFIG,+ authorize: (request) => {+ requests.push(request);+ return false;+ },+ },+ dependencies,+ ),+ /not authorized to access vercel\/internal-agents/u,+ );+ assert.deepEqual(requests, [+ { auth, repository: "vercel/internal-agents", token: "secret-token" },+ ]);+ assert.equal(runs.length, 0);++ await executeGitHubShell(READ, { ...CONFIG, authorize: async () => true }, dependencies);+ assert.equal(runs.length, 1);+});+test("approves the full syntactically valid gh surface", () => {for (const command of ["gh api repos/vercel/internal-agents",