mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
<!-- Written in ASD-STE100 style: short sentences, active voice. --> ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Paperclip Runner and the Codex adapters run agent shell commands inside a sandboxed Codex session with a strict environment allowlist > - The controller builds `shell_environment_policy.include_only` before the sandbox injects certificate-trust variables such as `SSL_CERT_FILE` and `GIT_SSL_CAINFO` > - The allowlist drops the injected variables, so managed `git` and `gh` commands cannot verify HTTPS against a runtime-provided CA > - This pull request allows the certificate-trust variable names through every environment policy stage, from the Rust process supervisor to the shell allowlist > - The benefit is that managed `git` and `gh` work again in sandboxes that require a runtime CA, while provider-credential isolation and the bounded allowlist stay in place ## Linked Issues or Issue Description - Fixes: #20019 - Refs #20038 — community pull request for the same defect. This change reviews the approach independently. The commit credits the community author as co-author. ## What Changed - Add `CERTIFICATE_ENVIRONMENT_KEYS` (`SSL_CERT_FILE`, `SSL_CERT_DIR`, `GIT_SSL_CAINFO`, `NODE_EXTRA_CA_CERTS`, `DENO_CERT`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`) to `packages/paperclip-runner/src/configured-environment.ts` - Native Codex shell policy (`codex-security-config.ts`): always put the certificate names in `include_only`; set inheritance to `"all"` with `ignore_default_excludes=true`, bounded by the explicit allowlist - Pass the certificate names through the app-server environment filter, the ACPX spawn environment filter, the ACPX runtime sandbox `include_only`, the runner platform environment keys, and the Rust process supervisor base key list - Legacy and ACPX-engine Codex shell allowlists (`packages/adapter-utils/src/codex-shell-environment.ts`): always include the certificate names - Add a synthetic private-CA HTTPS journey test: a real `git ls-remote` fails TLS verification without the injected CA and succeeds with it, through the policy-filtered child environment - Document the contract in `doc/sandbox-shell-environment.md` and link it from `doc/DEVELOPING.md` ## Verification - `pnpm --filter @paperclipai/paperclip-runner exec vitest run src/drivers/codex/codex-security-config.test.ts src/configured-environment.test.ts src/drivers/codex/codex-shell-certificate-trust.test.ts src/drivers/codex/codex-app-server-driver.context-control.test.ts src/drivers/acpx/runtime-sandbox.test.ts` — 104 tests pass - `pnpm --filter @paperclipai/adapter-utils exec vitest run src/codex-shell-environment.test.ts src/acpx-engine/execute.test.ts` — 270 tests pass - `pnpm --filter @paperclipai/adapter-codex-local exec vitest run src/server/execute.test.ts` — 10 tests pass - Codex driver lifecycle, conformance, recovery, and boundaries suites pass (103 tests); environment-builder suites pass (307 tests) - Red proof: with only the source fix reverted, the new regressions fail. The journey test shows `GIT_SSL_CAINFO` is undefined in the shell environment, and `git` fails TLS verification against the private-CA fixture - `cargo check` passes for `paperclip-runner-core`; `rustfmt --check` passes for the edited Rust file - The journey test needs `git` and `openssl`; it skips when either tool is absent ## Risks - The native shell policy now always sets `shell_environment_policy.inherit="all"` with `ignore_default_excludes=true`. Before, it set `"none"` when no credentials or task keys were projected. The explicit `include_only` allowlist still bounds every inherited name, so no new secret names can cross - The allowlist grows by seven non-secret certificate-trust names. Their values point at CA files. The sandbox filesystem policy still controls access to those files; this change grants no filesystem access - No persisted run, session, or launch identity changes shape. Sessions saved by the previous release resume unchanged; the new policy applies when the next launch builds its arguments - Provider credentials keep their existing exclusions at every stage ## Model Used - Claude Fable 5 (Anthropic, model ID `claude-fable-5`), extended thinking, agentic tool use, run through Claude Code. The implementation was written and reviewed independently against the community design in #20038; the community author is credited as co-author in the commit. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green (pending: checks run after this PR opens) - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending review) - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: everlastingcrown <everlastingcrown@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
344 lines
14 KiB
TypeScript
344 lines
14 KiB
TypeScript
import { lstat, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
|
import os from "node:os";
|
|
import path from "node:path";
|
|
import { afterEach, describe, expect, it, vi } from "vitest";
|
|
|
|
import type { SandboxManagedRuntimeAsset } from "@paperclipai/adapter-utils/sandbox-managed-runtime";
|
|
|
|
// Captured Codex `home` asset descriptor + the sandbox `auth.json` fixture the
|
|
// mocked runtime hands back during teardown. Mutated per-test so a single
|
|
// harness drives every round-trip case through the REAL `execute()` wiring.
|
|
const captured: { assets: SandboxManagedRuntimeAsset[] } = { assets: [] };
|
|
const sandboxAuthFixture: { bytes: Buffer } = { bytes: Buffer.from("{}") };
|
|
const REMOTE_RUNTIME_ROOT = "/remote/workspace/.paperclip-runtime/codex";
|
|
|
|
const {
|
|
runChildProcess,
|
|
ensureCommandResolvable,
|
|
resolveCommandForLogs,
|
|
prepareAdapterExecutionTargetRuntime,
|
|
startAdapterExecutionTargetPaperclipBridge,
|
|
} = vi.hoisted(() => ({
|
|
runChildProcess: vi.fn(async () => ({
|
|
exitCode: 0,
|
|
signal: null,
|
|
timedOut: false,
|
|
stdout: "",
|
|
stderr: "",
|
|
pid: 321,
|
|
startedAt: new Date().toISOString(),
|
|
})),
|
|
ensureCommandResolvable: vi.fn(async () => undefined),
|
|
resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"),
|
|
prepareAdapterExecutionTargetRuntime: vi.fn(),
|
|
startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => null),
|
|
}));
|
|
|
|
vi.mock("@paperclipai/adapter-utils/server-utils", async () => {
|
|
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(
|
|
"@paperclipai/adapter-utils/server-utils",
|
|
);
|
|
return {
|
|
...actual,
|
|
ensureCommandResolvable,
|
|
resolveCommandForLogs,
|
|
runChildProcess,
|
|
};
|
|
});
|
|
|
|
vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
|
|
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/execution-target")>(
|
|
"@paperclipai/adapter-utils/execution-target",
|
|
);
|
|
return {
|
|
...actual,
|
|
prepareAdapterExecutionTargetRuntime,
|
|
startAdapterExecutionTargetPaperclipBridge,
|
|
};
|
|
});
|
|
|
|
import { execute } from "./execute.js";
|
|
|
|
// Mirror the sandbox core's restore closure: capture the assets `execute()`
|
|
// declares, then during teardown invoke each asset's `restore` with an injected
|
|
// `readFile` (returns the sandbox fixture) and the remote asset dir. This drives
|
|
// the exact `restore` contribution the Codex adapter wires in production without
|
|
// needing a live sandbox.
|
|
prepareAdapterExecutionTargetRuntime.mockImplementation(async (input: { assets?: SandboxManagedRuntimeAsset[] }) => {
|
|
captured.assets = input.assets ?? [];
|
|
return {
|
|
target: { kind: "remote", transport: "ssh" },
|
|
workspaceRemoteDir: "/remote/workspace",
|
|
runtimeRootDir: REMOTE_RUNTIME_ROOT,
|
|
assetDirs: { home: `${REMOTE_RUNTIME_ROOT}/home` },
|
|
restoreWorkspace: async () => {
|
|
for (const asset of captured.assets) {
|
|
if (!asset.restore) continue;
|
|
await asset.restore({
|
|
assetDir: `${REMOTE_RUNTIME_ROOT}/home`,
|
|
readFile: async () => sandboxAuthFixture.bytes,
|
|
});
|
|
}
|
|
},
|
|
};
|
|
});
|
|
|
|
describe("codex execute — outbound auth copy-back restore contribution", () => {
|
|
const cleanupDirs: string[] = [];
|
|
let savedCodexHomeEnv: string | undefined;
|
|
|
|
afterEach(async () => {
|
|
vi.clearAllMocks();
|
|
vi.unstubAllEnvs();
|
|
if (savedCodexHomeEnv === undefined) {
|
|
delete process.env.CODEX_HOME;
|
|
} else {
|
|
process.env.CODEX_HOME = savedCodexHomeEnv;
|
|
}
|
|
while (cleanupDirs.length > 0) {
|
|
const dir = cleanupDirs.pop();
|
|
if (!dir) continue;
|
|
await rm(dir, { recursive: true, force: true }).catch(() => undefined);
|
|
}
|
|
});
|
|
|
|
function subscriptionAuth(input: { accountId: string; lastRefresh?: string; marker: string }): string {
|
|
return JSON.stringify(
|
|
{
|
|
tokens: {
|
|
id_token: `id-token-${input.marker}`,
|
|
access_token: `access-token-${input.marker}`,
|
|
refresh_token: `refresh-token-${input.marker}`,
|
|
account_id: input.accountId,
|
|
},
|
|
...(input.lastRefresh ? { last_refresh: input.lastRefresh } : {}),
|
|
},
|
|
null,
|
|
2,
|
|
);
|
|
}
|
|
|
|
async function runTeardown(input: { sandboxAuth: string; hostAuth: string; onProviderStopped?: () => Promise<void>; withIdentity?: boolean; env?: Record<string, string> }) {
|
|
const rootDir = await mkdtemp(
|
|
path.join(os.tmpdir(), "paperclip-codex-copyback-e2e-"),
|
|
);
|
|
cleanupDirs.push(rootDir);
|
|
const workspaceDir = path.join(rootDir, "workspace");
|
|
// The shared host home is what `resolveSharedCodexHomeDir` returns
|
|
// (process.env.CODEX_HOME) — the copy-back target. Point it at a tmp dir so
|
|
// the round-trip never touches the real host credential.
|
|
const sharedHostHome = path.join(rootDir, "shared-codex-home");
|
|
await mkdir(workspaceDir, { recursive: true });
|
|
await mkdir(sharedHostHome, { recursive: true });
|
|
const hostAuthPath = path.join(sharedHostHome, "auth.json");
|
|
await writeFile(hostAuthPath, input.hostAuth, { mode: 0o600 });
|
|
|
|
savedCodexHomeEnv = process.env.CODEX_HOME;
|
|
process.env.CODEX_HOME = sharedHostHome;
|
|
sandboxAuthFixture.bytes = Buffer.from(input.sandboxAuth, "utf8");
|
|
|
|
const commandArgs: string[] = [];
|
|
const executionResult = await execute({
|
|
runId: "run-copyback-e2e",
|
|
...(input.withIdentity ? {
|
|
authToken: "assigned-run-token",
|
|
agentIdentity: { keyId: "sha256:test", publicKeyPem: "public", privateKeyPem: "private" },
|
|
} : {}),
|
|
onMeta: async meta => { commandArgs.push(...(meta.commandArgs ?? [])); },
|
|
onProviderStopped: input.onProviderStopped,
|
|
agent: {
|
|
id: "agent-1",
|
|
companyId: "company-1",
|
|
name: "CodexCoder",
|
|
adapterType: "codex_local",
|
|
adapterConfig: {},
|
|
},
|
|
runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
|
|
config: {
|
|
command: "codex",
|
|
engine: "cli",
|
|
// External CODEX_HOME (outside the managed company tree) so no managed
|
|
// seeding rewrites auth.json before teardown; equals the shared host home.
|
|
env: { CODEX_HOME: sharedHostHome, ...input.env },
|
|
},
|
|
context: {
|
|
paperclipWorkspace: {
|
|
cwd: workspaceDir,
|
|
source: "project_primary",
|
|
},
|
|
},
|
|
executionTransport: {
|
|
remoteExecution: {
|
|
host: "127.0.0.1",
|
|
port: 2222,
|
|
username: "fixture",
|
|
remoteWorkspacePath: "/remote/workspace",
|
|
remoteCwd: "/remote/workspace",
|
|
privateKey: "PRIVATE KEY",
|
|
knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",
|
|
strictHostKeyChecking: true,
|
|
},
|
|
},
|
|
onLog: async () => {},
|
|
});
|
|
|
|
return {
|
|
commandArgs,
|
|
finalHostAuth: await readFile(hostAuthPath, "utf8"),
|
|
finalHostMode: (await lstat(hostAuthPath)).mode & 0o777,
|
|
executionResult,
|
|
};
|
|
}
|
|
|
|
it.each([true, false])("delivers configured service tokens to CLI shells while isolating host and provider credentials (identity: %s)", async (withIdentity) => {
|
|
vi.stubEnv("DATABASE_URL", "postgres://operator:host-password@host/private");
|
|
vi.stubEnv("HOST_DATABASE_PASSWORD", "host-password");
|
|
const { commandArgs } = await runTeardown({ sandboxAuth: "{}", hostAuth: "{}", withIdentity,
|
|
env: { SLACK_BOT_TOKEN: "assigned-tool-token", OPENAI_API_KEY: "provider-key-canary" },
|
|
});
|
|
const policy = commandArgs.find(arg => arg.startsWith("shell_environment_policy.include_only="));
|
|
const keys = policy ? JSON.parse(policy.slice(policy.indexOf("=") + 1)) : [];
|
|
expect(keys).toEqual(expect.arrayContaining(["SLACK_BOT_TOKEN", "SSL_CERT_FILE", "SSL_CERT_DIR", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS", "DENO_CERT", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE"]));
|
|
if (withIdentity) expect(keys).toEqual(expect.arrayContaining([
|
|
"PAPERCLIP_API_KEY", "PAPERCLIP_AGENT_PRIVATE_KEY",
|
|
]));
|
|
expect(keys).not.toContain("OPENAI_API_KEY");
|
|
expect(keys).not.toContain("DATABASE_URL");
|
|
expect(keys).not.toContain("HOST_DATABASE_PASSWORD");
|
|
expect(commandArgs.join(" ")).not.toContain("assigned-run-token");
|
|
expect(commandArgs.join(" ")).not.toContain("assigned-tool-token");
|
|
});
|
|
|
|
it("collects stopped-provider instruction edits before a throwing remote restore", async () => {
|
|
const order: string[] = [];
|
|
prepareAdapterExecutionTargetRuntime.mockImplementationOnce(async () => ({
|
|
target: { kind: "remote", transport: "ssh" }, workspaceRemoteDir: "/remote/workspace",
|
|
runtimeRootDir: REMOTE_RUNTIME_ROOT, assetDirs: { home: `${REMOTE_RUNTIME_ROOT}/home` },
|
|
restoreWorkspace: async () => { order.push("restore"); throw new Error("restore failed"); },
|
|
}));
|
|
await expect(runTeardown({ sandboxAuth: "{}", hostAuth: "{}", onProviderStopped: async () => { order.push("collect"); } })).rejects.toThrow("restore failed");
|
|
expect(order).toEqual(["collect", "restore"]);
|
|
});
|
|
|
|
it("collects after a failed provider exit before restoring its workspace", async () => {
|
|
runChildProcess.mockResolvedValueOnce({ exitCode: 1, signal: null, timedOut: false, stdout: "", stderr: "provider failed", pid: 321, startedAt: new Date().toISOString() });
|
|
const collected = vi.fn(async () => {});
|
|
await runTeardown({ sandboxAuth: "{}", hostAuth: "{}", onProviderStopped: collected });
|
|
expect(collected).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("stops the bridge and restores the workspace when instruction collection rejects", async () => {
|
|
const order: string[] = [];
|
|
startAdapterExecutionTargetPaperclipBridge.mockResolvedValueOnce({
|
|
env: {}, stop: async () => { order.push("bridge-stop"); },
|
|
} as never);
|
|
prepareAdapterExecutionTargetRuntime.mockImplementationOnce(async () => ({
|
|
target: { kind: "remote", transport: "ssh" }, workspaceRemoteDir: "/remote/workspace",
|
|
runtimeRootDir: REMOTE_RUNTIME_ROOT, assetDirs: { home: `${REMOTE_RUNTIME_ROOT}/home` },
|
|
restoreWorkspace: async () => { order.push("restore"); },
|
|
}));
|
|
await expect(runTeardown({ sandboxAuth: "{}", hostAuth: "{}", onProviderStopped: async () => {
|
|
order.push("collect");
|
|
throw new Error("instruction collection failed");
|
|
} })).rejects.toThrow("instruction collection failed");
|
|
expect(order).toEqual(["collect", "bridge-stop", "restore"]);
|
|
});
|
|
|
|
it("declares a Codex `home` asset carrying both inbound provision and outbound restore contributions", async () => {
|
|
await runTeardown({
|
|
sandboxAuth: subscriptionAuth({ accountId: "acct", lastRefresh: "2026-07-09T01:00:00Z", marker: "s" }),
|
|
hostAuth: subscriptionAuth({ accountId: "acct", lastRefresh: "2026-07-09T02:00:00Z", marker: "h" }),
|
|
});
|
|
|
|
const homeAsset = captured.assets.find((asset) => asset.key === "home");
|
|
expect(homeAsset).toBeDefined();
|
|
expect(homeAsset?.provision).toBeTruthy();
|
|
expect(typeof homeAsset?.restore).toBe("function");
|
|
});
|
|
|
|
it("round-trips a strictly-newer same-identity sandbox auth.json to the shared host at 0600 on teardown", async () => {
|
|
const sandboxAuth = subscriptionAuth({
|
|
accountId: "acct-same",
|
|
lastRefresh: "2026-07-09T02:00:00Z",
|
|
marker: "sandbox-newer",
|
|
});
|
|
const hostAuth = subscriptionAuth({
|
|
accountId: "acct-same",
|
|
lastRefresh: "2026-07-09T01:00:00Z",
|
|
marker: "host-older",
|
|
});
|
|
|
|
const result = await runTeardown({ sandboxAuth, hostAuth });
|
|
|
|
expect(result.finalHostAuth).toBe(sandboxAuth);
|
|
expect(result.finalHostMode).toBe(0o600);
|
|
});
|
|
|
|
it("keeps the host auth.json when the sandbox copy is a tie or older on teardown", async () => {
|
|
const cases = [
|
|
{
|
|
name: "tie",
|
|
sandboxAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: "2026-07-09T02:00:00Z", marker: "s-tie" }),
|
|
hostAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: "2026-07-09T02:00:00Z", marker: "h-tie" }),
|
|
},
|
|
{
|
|
name: "older",
|
|
sandboxAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: "2026-07-09T01:00:00Z", marker: "s-old" }),
|
|
hostAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: "2026-07-09T02:00:00Z", marker: "h-new" }),
|
|
},
|
|
];
|
|
|
|
for (const entry of cases) {
|
|
const result = await runTeardown({ sandboxAuth: entry.sandboxAuth, hostAuth: entry.hostAuth });
|
|
expect(result.finalHostAuth, entry.name).toBe(entry.hostAuth);
|
|
expect(result.finalHostMode, entry.name).toBe(0o600);
|
|
}
|
|
});
|
|
|
|
it("surfaces workspace restore failure after successful provider execution", async () => {
|
|
prepareAdapterExecutionTargetRuntime.mockResolvedValueOnce({
|
|
target: { kind: "remote", transport: "ssh" },
|
|
workspaceRemoteDir: "/remote/workspace",
|
|
runtimeRootDir: REMOTE_RUNTIME_ROOT,
|
|
assetDirs: { home: `${REMOTE_RUNTIME_ROOT}/home` },
|
|
restoreWorkspace: async () => {
|
|
throw new Error("workspace copy-back failed");
|
|
},
|
|
});
|
|
|
|
await expect(
|
|
runTeardown({
|
|
sandboxAuth: subscriptionAuth({ accountId: "acct", marker: "sandbox" }),
|
|
hostAuth: subscriptionAuth({ accountId: "acct", marker: "host" }),
|
|
}),
|
|
).rejects.toThrow("workspace copy-back failed");
|
|
});
|
|
|
|
it("preserves a provider failure when workspace restore also fails", async () => {
|
|
runChildProcess.mockResolvedValueOnce({
|
|
exitCode: 1,
|
|
signal: null,
|
|
timedOut: false,
|
|
stdout: "",
|
|
stderr: "provider failed first",
|
|
pid: 321,
|
|
startedAt: new Date().toISOString(),
|
|
});
|
|
prepareAdapterExecutionTargetRuntime.mockResolvedValueOnce({
|
|
target: { kind: "remote", transport: "ssh" },
|
|
workspaceRemoteDir: "/remote/workspace",
|
|
runtimeRootDir: REMOTE_RUNTIME_ROOT,
|
|
assetDirs: { home: `${REMOTE_RUNTIME_ROOT}/home` },
|
|
restoreWorkspace: async () => {
|
|
throw new Error("workspace copy-back failed second");
|
|
},
|
|
});
|
|
|
|
const result = await runTeardown({
|
|
sandboxAuth: subscriptionAuth({ accountId: "acct", marker: "sandbox" }),
|
|
hostAuth: subscriptionAuth({ accountId: "acct", marker: "host" }),
|
|
});
|
|
expect(result.executionResult.errorMessage).toBe("provider failed first");
|
|
});
|
|
});
|