The Open Framework for Building Agents
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 type { ToolContext } from "eve/tools";
import {
attributeCommand,
coAuthorTrailer,
isAttributable,
type GitHubCoAuthor,
} from "./attribution.ts";
import { validateRepositoryRoot } from "./repository-root.ts";
import { shellQuote } from "./shell.ts";
import { GITHUB_TOOLING_PATHS } from "./tooling.ts";
export type { GitHubCoAuthor } from "./attribution.ts";
export interface GitHubPermission {
readonly access: "write";
readonly provider: "github";
readonly repositories: readonly string[];
}
export interface GitHubShellInput {
readonly command: string;
readonly description: string;
readonly permissions: readonly GitHubPermission[];
readonly workingDirectory?: string;
}
export interface GitHubShellOutput {
readonly exitCode: number;
readonly stderr: string;
readonly stdout: string;
readonly truncated: boolean;
}
export interface GitHubConfig {
/**
* Resolves who the current turn publishes for. When it returns a person,
* `gh-signed-commit` messages and `gh pr create` bodies end with their
* `Co-authored-by` trailer. Return `null` to publish without one. It
* receives the `gh` tool's context, so `ctx.getToken` can resolve the
* requester's linked accounts.
*/
readonly attribution?: (
ctx: ToolContext,
) => GitHubCoAuthor | null | PromiseLike<GitHubCoAuthor | null>;
readonly authorize?: GitHubAuthorize;
readonly broker: (
sandbox: SandboxSession,
rules: Readonly<Record<string, readonly GitHubLeaseRule[]>> | null,
) => Promise<void>;
readonly connector: string;
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 {
readonly key?: { readonly exact: string };
readonly value?: { readonly exact?: string; readonly regex?: string };
}[];
};
readonly transform: readonly { readonly headers: Readonly<Record<string, string>> }[];
}
interface GitHubShellDependencies {
/** The calling tool's context, passed to `attribution`. */
readonly context?: ToolContext;
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. */
readonly sessionId: string;
}
const MAX_OUTPUT_BYTES = 100_000;
const leaseQueues = new Map<string, Promise<void>>();
const ALLOWED_GIT_REMOTE_COMMANDS = new Set(["fetch", "ls-remote", "pull", "push"]);
export function githubShellApproval(input: GitHubShellInput | undefined) {
if (!input) return "not-applicable" as const;
try {
validateGitHubShellInput(input);
return "not-applicable" as const;
} catch (error) {
return {
type: "denied" as const,
reason: error instanceof Error ? error.message : "Invalid GitHub command.",
};
}
}
export async function executeGitHubShell(
input: GitHubShellInput,
config: GitHubConfig | undefined,
dependencies: GitHubShellDependencies,
): Promise<GitHubShellOutput> {
if (!config) throw new Error("GitHub command access is not configured for this agent.");
const argv = validateGitHubShellInput(input);
const sandbox = await dependencies.getSandbox();
let workingDirectory = resolveWorkingDirectory(sandbox, input.workingDirectory);
if (argv[0] === "git" || argv[0] === "gh-signed-commit") {
workingDirectory = await validateRepositoryRoot(sandbox, workingDirectory);
}
const declaredRepositories = input.permissions[0]!.repositories;
const remoteRepository = await assertCommandTargets(
argv,
declaredRepositories,
workingDirectory,
sandbox,
);
const invocationId = crypto.randomUUID();
const bodyFile = `/tmp/eve-git-body-${invocationId}.md`;
const repositories = repositoryNames(declaredRepositories, config.org);
const tokenParams: ConnectTokenParams = {
authorizationDetails: [{ type: "github_app_installation", org: config.org, repositories }],
subject: { type: "app" },
};
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 coAuthor =
config.attribution && dependencies.context && isAttributable(argv)
? await config.attribution(dependencies.context)
: null;
const commandArgv = coAuthor
? await attributeCommand(argv, coAuthorTrailer(coAuthor), sandbox, workingDirectory, bodyFile)
: argv;
const executable = executablePath(commandArgv[0]!);
const executionArguments = remoteRepository
? [
"-c",
"protocol.allow=never",
"-c",
"protocol.https.allow=always",
commandArgv[1]!,
`https://github.com/${remoteRepository}.git`,
...commandArgv.slice(3),
]
: commandArgv.slice(1);
const command = `cd ${shellQuote(workingDirectory)} && exec ${shellQuote(executable)} ${executionArguments
.map(shellQuote)
.join(" ")}`;
const authorization = `Basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`;
const placeholder = `eve-github-${invocationId}`;
const githubConfig = `/tmp/eve-code-gh-${invocationId}`;
const placeholderAuthorization = `Basic ${Buffer.from(`x-access-token:${placeholder}`).toString("base64")}`;
let result: Awaited<ReturnType<SandboxSession["run"]>>;
try {
result = await withGitHubCredentialLease(
sandbox,
dependencies.sessionId,
{ authorization, placeholder, placeholderAuthorization, token },
() => {
const env: Record<string, string> = {
GH_CONFIG_DIR: githubConfig,
GH_PROMPT_DISABLED: "1",
};
if (argv[0] !== "git") env.GH_TOKEN = placeholder;
env.GIT_CONFIG_COUNT = "2";
env.GIT_CONFIG_KEY_0 = "http.https://github.com/.extraheader";
env.GIT_CONFIG_VALUE_0 = `Authorization: ${placeholderAuthorization}`;
env.GIT_CONFIG_KEY_1 = "core.hooksPath";
env.GIT_CONFIG_VALUE_1 = "/dev/null";
env.GIT_TERMINAL_PROMPT = "0";
env.PATH = "/usr/local/bin:/usr/bin:/bin";
return sandbox.run({ command, env });
},
config.broker,
);
} finally {
await sandbox.removePath({ path: githubConfig, recursive: true, force: true });
await sandbox.removePath({ path: bodyFile, force: true });
}
const stdout = sanitizeOutput(result.stdout, token, authorization);
const stderr = sanitizeOutput(result.stderr, token, authorization);
return {
exitCode: result.exitCode,
stdout: stdout.value,
stderr: stderr.value,
truncated: stdout.truncated || stderr.truncated,
};
}
async function withGitHubCredentialLease<T>(
sandbox: SandboxSession,
sessionId: string,
credential: {
readonly authorization: string;
readonly placeholder: string;
readonly placeholderAuthorization: string;
readonly token: string;
},
run: () => PromiseLike<T>,
broker: GitHubConfig["broker"],
): Promise<T> {
const previous = leaseQueues.get(sessionId) ?? Promise.resolve();
let release!: () => void;
const gate = new Promise<void>((resolve) => {
release = resolve;
});
const current = previous.then(() => gate);
leaseQueues.set(sessionId, current);
await previous;
try {
await broker(sandbox, {
"api.github.com": [
{
match: {
headers: [
{
key: { exact: "authorization" },
value: { regex: `^(?:token|Bearer) ${credential.placeholder}$` },
},
],
},
transform: [{ headers: { authorization: `Bearer ${credential.token}` } }],
},
],
"github.com": [
{
match: {
headers: [
{
key: { exact: "authorization" },
value: { exact: credential.placeholderAuthorization },
},
],
},
transform: [{ headers: { authorization: credential.authorization } }],
},
],
});
return await run();
} finally {
try {
await broker(sandbox, null);
} finally {
release();
if (leaseQueues.get(sessionId) === current) leaseQueues.delete(sessionId);
}
}
}
export function parseCommand(command: string): string[] {
const value = command.trim();
if (!value) throw new Error("GitHub command must not be empty.");
const argv: string[] = [];
let token = "";
let quote: "single" | "double" | null = null;
let escaped = false;
let started = false;
for (const character of value) {
if (escaped) {
token += character;
escaped = false;
started = true;
continue;
}
if (character === "\\" && quote !== "single") {
escaped = true;
started = true;
continue;
}
if (quote === "single") {
if (character === "'") quote = null;
else token += character;
continue;
}
if (quote === "double") {
if (character === '"') quote = null;
else if (character === "$" || character === "`") throw unsupportedSyntax();
else token += character;
continue;
}
if (character === "'") {
quote = "single";
started = true;
} else if (character === '"') {
quote = "double";
started = true;
} else if (/\s/u.test(character)) {
if (started) {
argv.push(token);
token = "";
started = false;
}
} else if (";&|<>$`(){}".includes(character)) {
throw unsupportedSyntax();
} else {
token += character;
started = true;
}
}
if (escaped || quote) throw new Error("GitHub command contains an unfinished quote or escape.");
if (started) argv.push(token);
if (argv.length === 0) throw new Error("GitHub command must not be empty.");
return argv;
}
function validateGitHubShellInput(input: GitHubShellInput): string[] {
const argv = parseCommand(input.command);
const permission = input.permissions[0];
if (input.permissions.length !== 1 || permission?.provider !== "github") {
throw new Error("Exactly one GitHub permission is required.");
}
if (permission.access !== "write") {
throw new Error("GitHub App commands require explicit write-capable access.");
}
if (!input.description.trim()) throw new Error("description must describe the intended result.");
const [executable, subcommand] = argv;
if (executable === "gh") {
if (!subcommand) throw new Error("A gh subcommand is required.");
} else if (executable === "git") {
if (!subcommand || !ALLOWED_GIT_REMOTE_COMMANDS.has(subcommand)) {
throw new Error(
"Authenticated git supports only fetch, ls-remote, pull, and push; clone with gh repo clone.",
);
}
} else if (executable !== "gh-signed-commit") {
throw new Error(
"GitHub commands must use gh, an authenticated git remote command, or gh-signed-commit.",
);
}
return argv;
}
async function assertCommandTargets(
argv: readonly string[],
declaredRepositories: readonly string[],
workingDirectory: string,
sandbox: Pick<SandboxSession, "run">,
): Promise<string | undefined> {
const declared = new Set(declaredRepositories.map((repository) => repository.toLowerCase()));
let remoteRepository: string | undefined;
let targets: string[];
if (argv[0] === "git") {
if (argv[2] !== "origin") {
throw new Error("Authenticated git commands must use the validated origin remote.");
}
const push = argv[1] === "push";
const remote = await sandbox.run({
command: `cd ${shellQuote(workingDirectory)} && git remote get-url ${push ? "--push " : ""}origin`,
env: { GIT_TERMINAL_PROMPT: "0", PATH: "/usr/bin:/bin" },
});
if (remote.exitCode !== 0) throw new Error("Could not resolve the origin GitHub repository.");
remoteRepository = repositoryFromRemote(remote.stdout.trim());
targets = [remoteRepository];
} else if (argv[0] === "gh-signed-commit") {
targets = repoFlagTargets(argv.slice(1));
if (targets.length === 0) {
throw new Error("gh-signed-commit requires an explicit --repo owner/repository target.");
}
} else {
targets = repoFlagTargets(argv.slice(1));
if (
argv[1] === "repo" &&
(argv[2] === "clone" || argv[2] === "view" || argv[2] === "fork") &&
argv[3] &&
!argv[3].startsWith("-")
) {
targets.push(canonicalRepository(argv[3]));
}
}
for (const target of targets) {
if (!declared.has(target.toLowerCase())) {
throw new Error(
`Command target ${JSON.stringify(target)} is not in the declared repositories.`,
);
}
}
return remoteRepository;
}
function repoFlagTargets(argv: readonly string[]): string[] {
const targets: string[] = [];
for (let index = 0; index < argv.length; index += 1) {
const value = argv[index];
if (value === "--repo" || value === "-R") {
const target = argv[index + 1];
if (!target) throw new Error(`${value} requires an owner/repository value.`);
targets.push(canonicalRepository(target));
index += 1;
} else if (value?.startsWith("--repo=")) {
targets.push(canonicalRepository(value.slice("--repo=".length)));
}
}
return targets;
}
function repositoryFromRemote(remote: string): string {
const https = /^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/iu.exec(remote);
if (https?.[1]) return canonicalRepository(https[1]);
const ssh = /^git@github\.com:([^/]+\/[^/]+?)(?:\.git)?$/iu.exec(remote);
if (ssh?.[1]) return canonicalRepository(ssh[1]);
throw new Error("The origin remote is not a canonical GitHub repository URL.");
}
function canonicalRepository(value: string): string {
const normalized = value.replace(/\.git$/iu, "");
if (!/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/u.test(normalized)) {
throw new Error(`Invalid GitHub repository ${JSON.stringify(value)}.`);
}
return normalized;
}
function repositoryNames(repositories: readonly string[], configuredOrg: string): string[] {
if (repositories.length !== 1) throw new Error("Exactly one GitHub repository is required.");
const names = new Set<string>();
for (const repository of repositories) {
const match = /^([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+)$/u.exec(repository);
if (!match) throw new Error(`Invalid GitHub repository ${JSON.stringify(repository)}.`);
if (match[1]?.toLowerCase() !== configuredOrg.toLowerCase()) {
throw new Error(`Repository ${JSON.stringify(repository)} is outside ${configuredOrg}.`);
}
names.add(match[2]!);
}
if (names.size !== 1) throw new Error("Exactly one GitHub repository is required.");
return [...names];
}
function executablePath(executable: string): string {
if (executable === "gh") return GITHUB_TOOLING_PATHS.ghReal;
if (executable === "gh-signed-commit") return GITHUB_TOOLING_PATHS.trustedSignedCommit;
return "git";
}
function resolveWorkingDirectory(
sandbox: Pick<SandboxSession, "resolvePath">,
workingDirectory: string | undefined,
): string {
const workspace = posix.resolve("/", sandbox.resolvePath(""));
const resolved = posix.resolve("/", sandbox.resolvePath(workingDirectory?.trim() || ""));
if (resolved !== workspace && !resolved.startsWith(`${workspace}/`)) {
throw new Error("GitHub command workingDirectory must stay inside the sandbox workspace.");
}
return resolved;
}
function sanitizeOutput(
value: string,
token: string,
authorization: string,
): { readonly truncated: boolean; readonly value: string } {
const redacted = value.replaceAll(token, "[redacted]").replaceAll(authorization, "[redacted]");
if (Buffer.byteLength(redacted) <= MAX_OUTPUT_BYTES) return { value: redacted, truncated: false };
return {
value: `[output truncated: showing final ${MAX_OUTPUT_BYTES} bytes]\n${Buffer.from(redacted).subarray(-MAX_OUTPUT_BYTES).toString()}`,
truncated: true,
};
}
function unsupportedSyntax(): Error {
return new Error(
"GitHub commands support argv syntax only, not pipes, redirects, substitutions, or shell operators.",
);
}