diff --git a/doc/execution-github-identity.md b/doc/execution-github-identity.md index bf85604c1f..4779bbb56a 100644 --- a/doc/execution-github-identity.md +++ b/doc/execution-github-identity.md @@ -20,6 +20,16 @@ Server-side Git operations and GitHub gateway calls follow the same selection ru Managed commands disable ambient Git credential helpers, Git global/system configuration, host GitHub CLI configuration, and host SSH identity access. Per-operation GitHub CLI configuration is isolated in a writable configuration directory beneath the managed launcher directory. Missing credentials clear previous author and token values; no teammate, standing delegation, host token, or company-default user's account is substituted. Anonymous/local operations remain available where supported. +Remote launchers prepend their directory to the execution target's effective +`PATH`. An explicit remote `PATH` override is preserved; otherwise Paperclip +reads the provider's environment before staging the launcher shell files. +This keeps legacy NVM and user-local agent installations available alongside +newer images with system-wide CLIs. The generated shell files retain that +combined path with managed `git` and `gh` first. Sandbox command checks use +the same sanitized environment as execution, so a CLI visible only in the +provider's default environment cannot pass the launch check. Failed path +discovery stops startup instead of silently falling back to a minimal path. + Scripts that previously read a persistent `GH_TOKEN` must use managed `git`, `gh`, or GitHub gateway tools. Managed execution skips legacy GitHub token bindings in agent, environment, project, and routine configuration before secret preflight. Configure personal or dedicated access through the GitHub connection instead. Directly invoking an unmanaged executable or retaining a token obtained during an earlier invocation is outside the managed invocation contract. ## Dedicated accounts and diagnostics diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.ts index ebd5ae8d74..ccc4a9e2ab 100644 --- a/packages/adapter-utils/src/execution-target.ts +++ b/packages/adapter-utils/src/execution-target.ts @@ -678,6 +678,9 @@ export async function ensureAdapterExecutionTargetCommandResolvable( await ensureSandboxCommandResolvable( command, target, + sanitizeRemoteExecutionEnv(Object.fromEntries( + Object.entries(env).filter((entry): entry is [string, string] => typeof entry[1] === "string"), + )), options.installCommand?.trim() || null, options.timeoutSec, ); @@ -691,6 +694,7 @@ export async function ensureAdapterExecutionTargetCommandResolvable( async function probeSandboxCommandResolvable( command: string, target: AdapterSandboxExecutionTarget, + env: Record, ): Promise<{ resolved: boolean; timedOut: boolean; stderr: string }> { const runner = requireSandboxRunner(target); const probeScript = `command -v ${shellQuote(command)}`; @@ -698,6 +702,7 @@ async function probeSandboxCommandResolvable( command: "sh", args: ["-c", probeScript], cwd: target.remoteCwd, + env, timeoutMs: target.timeoutMs ?? 15_000, }); return { @@ -710,6 +715,7 @@ async function probeSandboxCommandResolvable( async function ensureSandboxCommandResolvable( command: string, target: AdapterSandboxExecutionTarget, + env: Record, installCommand: string | null, timeoutSec?: number | null, ): Promise { @@ -720,7 +726,7 @@ async function ensureSandboxCommandResolvable( // the first step honestly reflects whether the binary is on PATH. The // sandbox provider is responsible for sourcing login profiles (e2b mirrors // SSH's buildSshSpawnTarget) so this and the hello probe agree on PATH. - let probe = await probeSandboxCommandResolvable(command, target); + let probe = await probeSandboxCommandResolvable(command, target, env); if (probe.resolved) return; if (probe.timedOut) { throw new Error(`Timed out checking command "${command}" on sandbox target.`); @@ -742,6 +748,7 @@ async function ensureSandboxCommandResolvable( command: "sh", args: shellCommandArgs(installCommand), cwd: target.remoteCwd, + env, timeoutMs: installTimeoutMs, }); if (installResult.timedOut) { @@ -755,7 +762,7 @@ async function ensureSandboxCommandResolvable( } catch (err) { installFailureDetail = `install command threw: ${err instanceof Error ? err.message : String(err)}`; } - probe = await probeSandboxCommandResolvable(command, target); + probe = await probeSandboxCommandResolvable(command, target, env); if (probe.resolved) return; if (probe.timedOut) { throw new Error(`Timed out checking command "${command}" on sandbox target.`); @@ -1521,6 +1528,31 @@ export async function cleanupGitHubOperationLaunchers(input: GitHubLauncherLocat } } +async function githubOperationLauncherBasePath( + target: AdapterCommandCapableExecutionTarget | null, + env: Record, +): Promise { + if (!target) return env.PATH || process.env.PATH || "/usr/bin:/bin"; + const configuredPath = sanitizeRemoteExecutionEnv(env).PATH; + if (configuredPath !== undefined) return configuredPath; + + // The provider owns login/profile setup. Query its effective PATH before + // staging BASH_ENV, rather than substituting the controller's toolchain or + // a minimal PATH that hides legacy NVM/user-local agent installations. + const result = await adapterExecutionTargetCommandRunner(target).execute({ + command: "sh", + args: ["-c", "printf '\\000%s\\000' \"$PATH\""], + cwd: target.remoteCwd, + timeoutMs: 15_000, + }); + // Frame the value so login banners cannot become executable search paths. + const remotePath = result.stdout.match(/\0([^\0]+)\0/)?.[1]; + if (result.timedOut || result.exitCode !== 0 || !remotePath) { + throw new Error("Could not resolve remote PATH for managed GitHub launchers"); + } + return remotePath; +} + /** Stage token-free launchers next to the execution, not in shared global Git config. */ export async function prepareGitHubOperationLaunchers(input: { runId: string; target: AdapterExecutionTarget | null | undefined; cwd: string; env: Record; @@ -1528,8 +1560,8 @@ export async function prepareGitHubOperationLaunchers(input: { const remote = input.target?.kind === "remote" ? input.target : null; const directory = githubOperationLauncherDirectory(input); const configDirectory = path.posix.join(directory, "gh-config"); - const basePath = input.env.PATH || (remote ? "/usr/local/bin:/usr/bin:/bin" : process.env.PATH) || "/usr/bin:/bin"; - const managedPath = `${directory}:${basePath}`; + const basePath = await githubOperationLauncherBasePath(remote, input.env); + const managedPath = basePath ? `${directory}:${basePath}` : directory; // Login shells may reorder PATH through /etc/profile or path_helper. Restore // the managed launchers after startup without loading a host user's profile. const profile = `export PATH=${shellQuote(managedPath)}\n`; diff --git a/packages/adapter-utils/src/github-launcher-environment.test.ts b/packages/adapter-utils/src/github-launcher-environment.test.ts new file mode 100644 index 0000000000..2c3768fb15 --- /dev/null +++ b/packages/adapter-utils/src/github-launcher-environment.test.ts @@ -0,0 +1,180 @@ +import { execFile } from "node:child_process"; +import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { promisify } from "node:util"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import * as ssh from "./ssh.js"; +import type { CommandManagedRuntimeRunner } from "./command-managed-runtime.js"; +import { + ensureAdapterExecutionTargetCommandResolvable, + prepareGitHubOperationLaunchers, + runAdapterExecutionTargetProcess, +} from "./execution-target.js"; + +const exec = promisify(execFile); +const roots: string[] = []; +afterEach(async () => { + vi.restoreAllMocks(); + vi.unstubAllEnvs(); + await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); +}); + +async function sandbox(layout: string) { + const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-launcher-env-")); + roots.push(root); + const bin = path.join(root, layout); + await mkdir(bin, { recursive: true }); + for (const cli of ["claude", "codex", "git", "gh"]) { + await writeFile(path.join(bin, cli), `#!/bin/sh\nprintf '%s\\n' '${cli} started'\n`, { mode: 0o700 }); + } + const remotePath = `${bin}:${path.dirname(process.execPath)}:/usr/local/bin:/usr/bin:/bin`; + // Execute real shells and staged launchers, with a provider-owned environment. + // Do not inherit the controller's PATH, HOME, credentials, or shell hooks. + const execute: CommandManagedRuntimeRunner["execute"] = async (input) => { + const startedAt = new Date().toISOString(); + try { + const execution = exec(input.command, input.args ?? [], { + cwd: input.cwd ?? root, + env: { HOME: root, PATH: remotePath, ...input.env }, + timeout: input.timeoutMs ?? 15_000, + }); + const inputComplete = new Promise((resolve, reject) => { + const stdin = execution.child.stdin; + if (!stdin) return resolve(); + // Hash-skip staging can exit before reading the supplied file body. + // Its exit result still determines success; other input errors fail. + stdin.on("error", (error: NodeJS.ErrnoException) => { + if (error.code === "EPIPE") resolve(); + else reject(error); + }); + stdin.end(input.stdin ?? "", resolve); + }); + const [result] = await Promise.all([execution, inputComplete]); + return { ...result, exitCode: 0, signal: null, timedOut: false, pid: null, startedAt }; + } catch (error) { + const result = error as Error & { code?: number; killed?: boolean; stdout?: string; stderr?: string }; + return { exitCode: result.code ?? 1, signal: null, timedOut: result.killed ?? false, + stdout: result.stdout ?? "", stderr: result.stderr ?? "", pid: null, startedAt }; + } + }; + const runner = { execute: vi.fn(execute) }; + const target = { kind: "remote" as const, transport: "sandbox" as const, + providerKey: "fixture", remoteCwd: root, runner }; + return { root, bin, remotePath, runner, target }; +} + +describe("managed GitHub launcher environment", () => { + it.each(["nvm/current/bin", "usr/local/bin", "tools with 'quotes'/bin"])( + "preserves %s CLIs and keeps GitHub wrappers first in child shells", + async (layout) => { + const fixture = await sandbox(layout); + vi.stubEnv("PATH", "/controller-only/bin"); + const env = await prepareGitHubOperationLaunchers({ + runId: "run-layout", target: fixture.target, cwd: "/controller", env: {}, + }); + expect(env.PATH).toBe(`${env.PAPERCLIP_GITHUB_LAUNCHER_DIR}:${fixture.remotePath}`); + for (const cli of ["claude", "codex"]) { + await ensureAdapterExecutionTargetCommandResolvable(cli, fixture.target, fixture.root, env); + const result = await runAdapterExecutionTargetProcess("run-layout", fixture.target, "bash", [ + "--noprofile", "--norc", "-c", `command -v git; command -v gh; ${cli}`, + ], { cwd: fixture.root, env, timeoutSec: 5, graceSec: 1, onLog: async () => {} }); + expect(result.exitCode, result.stderr).toBe(0); + expect(result.stdout.trim().split("\n")).toEqual([ + `${env.PAPERCLIP_GITHUB_LAUNCHER_DIR}/git`, + `${env.PAPERCLIP_GITHUB_LAUNCHER_DIR}/gh`, + `${cli} started`, + ]); + } + for (const profile of [".profile", ".bash_profile", ".bashrc", ".zshenv", ".zprofile", ".zshrc"]) { + const script = await readFile(path.join(env.PAPERCLIP_GITHUB_LAUNCHER_DIR, profile), "utf8"); + const result = await fixture.runner.execute({ command: "sh", args: ["-c", `${script}\nprintf '%s' "$PATH"`] }); + expect(result.stdout).toBe(env.PATH); + } + // The wrappers' Node interpreter and underlying commands are still reachable. + const github = await fixture.runner.execute({ command: "bash", args: ["-c", "git; gh"], env }); + expect(github.exitCode, github.stderr).toBe(0); + expect(github.stdout).toBe("git started\ngh started\n"); + }, + ); + + it("preserves an explicit remote PATH without querying the remote environment", async () => { + const fixture = await sandbox("custom/bin"); + const env = await prepareGitHubOperationLaunchers({ + runId: "run-explicit", target: fixture.target, cwd: fixture.root, env: { PATH: fixture.remotePath }, + }); + expect(env.PATH).toBe(`${env.PAPERCLIP_GITHUB_LAUNCHER_DIR}:${fixture.remotePath}`); + expect(fixture.runner.execute.mock.calls.every(([input]) => !input.args?.join(" ").includes("$PATH"))).toBe(true); + }); + + it("does not copy an inherited controller PATH into a remote launcher", async () => { + const fixture = await sandbox("nvm/bin"); + vi.stubEnv("PATH", "/controller-only/bin"); + const env = await prepareGitHubOperationLaunchers({ + runId: "run-inherited", target: fixture.target, cwd: fixture.root, env: { PATH: process.env.PATH! }, + }); + expect(env.PATH).toBe(`${env.PAPERCLIP_GITHUB_LAUNCHER_DIR}:${fixture.remotePath}`); + }); + + it("keeps an explicit empty remote PATH empty apart from the managed wrappers", async () => { + const fixture = await sandbox("nvm/bin"); + const env = await prepareGitHubOperationLaunchers({ + runId: "run-empty", target: fixture.target, cwd: fixture.root, env: { PATH: "" }, + }); + expect(env.PATH).toBe(env.PAPERCLIP_GITHUB_LAUNCHER_DIR); + expect(fixture.runner.execute.mock.calls.every(([input]) => !input.args?.join(" ").includes("$PATH"))).toBe(true); + const result = await fixture.runner.execute({ command: "/bin/sh", args: ["-c", "command -v claude"], env }); + expect(result.exitCode).not.toBe(0); + }); + + it("reads the SSH target PATH and ignores login banners", async () => { + const fixture = await sandbox("ssh-toolchain/bin"); + fixture.runner.execute.mockResolvedValueOnce({ exitCode: 0, timedOut: false, signal: null, + stdout: `Welcome\n\0${fixture.remotePath}\0\n`, stderr: "", pid: null, startedAt: new Date().toISOString() }); + vi.spyOn(ssh, "createSshCommandManagedRuntimeRunner").mockReturnValue(fixture.runner); + const target = { kind: "remote" as const, transport: "ssh" as const, remoteCwd: fixture.root, + spec: { host: "sandbox.example.test", port: 22, username: "runner", remoteCwd: fixture.root, + remoteWorkspacePath: fixture.root, privateKey: null, knownHosts: null, strictHostKeyChecking: true } }; + const env = await prepareGitHubOperationLaunchers({ runId: "run-ssh", target, cwd: fixture.root, env: {} }); + expect(env.PATH).toBe(`${env.PAPERCLIP_GITHUB_LAUNCHER_DIR}:${fixture.remotePath}`); + expect(fixture.runner.execute.mock.calls[0]?.[0].env).toBeUndefined(); + }); + + it("uses the launch environment for install and re-probe after a missing command", async () => { + const fixture = await sandbox("custom/bin"); + const env = { PATH: fixture.remotePath, HOME: fixture.root }; + await ensureAdapterExecutionTargetCommandResolvable("fixture-cli", fixture.target, fixture.root, env, { + installCommand: `cp ${ssh.shellQuote(path.join(fixture.bin, "claude"))} ${ssh.shellQuote(path.join(fixture.bin, "fixture-cli"))}`, + }); + expect(fixture.runner.execute.mock.calls).toHaveLength(3); + for (const [input] of fixture.runner.execute.mock.calls) expect(input.env).toEqual(env); + }); + + it("checks command availability with the launch environment, not the provider default", async () => { + const fixture = await sandbox("nvm/bin"); + const env = { PATH: "/usr/bin:/bin" }; + // The binary exists on the provider PATH, but the requested launch excludes it. + await expect(ensureAdapterExecutionTargetCommandResolvable( + "claude", fixture.target, fixture.root, env, + )).rejects.toThrow('Command "claude" is not installed or not on PATH'); + const result = await runAdapterExecutionTargetProcess("run-missing", fixture.target, "sh", ["-c", "claude"], { + cwd: fixture.root, env, timeoutSec: 5, graceSec: 1, onLog: async () => {}, + }); + expect(result.exitCode).toBe(127); + }); + + it.each([ + { exitCode: 1, timedOut: false, stdout: "" }, + { exitCode: 0, timedOut: true, stdout: "" }, + { exitCode: 0, timedOut: false, stdout: "login banner only" }, + { exitCode: 0, timedOut: false, stdout: "\0\0" }, + ])("fails before staging when remote PATH discovery fails: %j", async (failure) => { + const fixture = await sandbox("nvm/bin"); + fixture.runner.execute.mockResolvedValueOnce({ ...failure, signal: null, stderr: "private diagnostic", + pid: null, startedAt: new Date().toISOString() }); + await expect(prepareGitHubOperationLaunchers({ + runId: "run-failure", target: fixture.target, cwd: fixture.root, env: {}, + })).rejects.toThrow("Could not resolve remote PATH for managed GitHub launchers"); + expect(fixture.runner.execute).toHaveBeenCalledTimes(1); + }); +});