Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.ts
index 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.ts
index 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.ts
index 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 = remoteRepository
diff --git a/packages/eve-git/test/integration/github-shell.test.ts b/packages/eve-git/test/integration/github-shell.test.ts
index 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-capabl
assert.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",