mirror of
https://github.com/dtzp555-max/olp.git
synced 2026-07-19 09:45:07 +00:00
feat(sandbox): Phase 7 Solution 1 implementation + opus 4.8 (#68)
Implements ADR 0014 Amendment 1 (4-layer Solution 1) + ADR 0002 Amendment 9 (Provider ISOLATION contract) + opus 4.8 model. Fresh-context opus reviewer APPROVE_WITH_MINOR; 2 nit fold-ins applied. 813 unit tests pass. Known deferred coverage: Suite 44 PI231 E2E tests are placeholders under describe.skip pending Task #9 (PI231 prod-target validation). The load-bearing negative test ('in-sandbox cat ~/.olp/keys.json MUST fail') will be validated when Task #9 runs against the merged code. PR-B outer-bwrap superseded; archive at phase-7-pr-b-outer-bwrap-snapshot branch.
This commit is contained in:
dtzp555-max
+164
-40
@@ -77,11 +77,12 @@ import { homedir } from 'node:os';
|
||||
import * as https from 'node:https';
|
||||
import * as http from 'node:http';
|
||||
import { ProviderError } from './base.mjs';
|
||||
// Phase 7 PR-B (ADR 0014 § PR-B): sandbox spawn wrap.
|
||||
// wrapSpawn() is transparent (returns inputs unchanged) when sandbox is inactive.
|
||||
// Authority: @anthropic-ai/sandbox-runtime v0.0.52, ADR 0014 § PR-B,
|
||||
// ADR 0009 Amendment 1 § unchanged spawn args — only the spawn execution is wrapped.
|
||||
import { wrapSpawn } from '../sandbox/manager.mjs';
|
||||
// Phase 7 Solution 1 (ADR 0014 Amendment 1): wrapSpawn() removed from manager.mjs.
|
||||
// Isolation is composed by server.mjs via prepareIsolatedEnvironment() before
|
||||
// provider.spawn() is called (Task #8). The anthropic ISOLATION block (Task #6)
|
||||
// declares per-provider primitives; _spawnAndStream() applies isolationCtx
|
||||
// (envOverrides, hardenedArgs, wrapForLayer3) on top of its own env-cleanup + args.
|
||||
// No sandbox/manager.mjs import needed in this plugin.
|
||||
|
||||
// ── Binary resolution ─────────────────────────────────────────────────────
|
||||
// OLP_CLAUDE_BIN env takes priority, then falls back to 'claude' from PATH.
|
||||
@@ -868,7 +869,7 @@ function buildSpawnEnv() {
|
||||
// stop chunk; proc.on('close') is the safety net if `result` is never emitted.
|
||||
//
|
||||
// OCP server.mjs:542: const proc = spawn(CLAUDE, cliArgs, { env, stdio: [...] });
|
||||
async function* _spawnAndStream(irRequest, authContext, spawnImpl) {
|
||||
async function* _spawnAndStream(irRequest, authContext, spawnImpl, isolationCtx) {
|
||||
const auth = authContext ?? readAuthArtifact();
|
||||
if (!auth?.accessToken) {
|
||||
throw new ProviderError(
|
||||
@@ -915,44 +916,54 @@ async function* _spawnAndStream(irRequest, authContext, spawnImpl) {
|
||||
// ADR 0009 Amendment 1: system prompt extracted from IR messages,
|
||||
// prepended with OLP_SYSTEM_PROMPT_WRAPPER, passed via --system-prompt.
|
||||
const systemPrompt = extractSystemPrompt(irRequest);
|
||||
const args = buildCliArgs(irRequest.model, systemPrompt);
|
||||
const baseArgs = buildCliArgs(irRequest.model, systemPrompt);
|
||||
|
||||
// stdin: serialized user/assistant/tool messages (system skipped — goes via --system-prompt)
|
||||
const prompt = irToAnthropic(irRequest);
|
||||
|
||||
// Phase 7 PR-B (ADR 0014 § PR-B): wrap spawn in sandbox-runtime if active.
|
||||
// wrapSpawn() is transparent when sandbox is inactive (returns inputs unchanged).
|
||||
// Per-spawn ephemeral cwd (UUID) is created inside wrapSpawn to prevent cross-
|
||||
// request contamination. Allowed domains are the Anthropic API domains only.
|
||||
//
|
||||
// ADR 0009 Amendment 1 § unchanged spawn args: only the spawn execution is
|
||||
// wrapped — bin/args/env/NDJSON parsing are all unchanged from pre-PR-B.
|
||||
//
|
||||
// 2026-05-28 PR-B fold-in: skip sandbox wrap when a custom spawnImpl is in
|
||||
// use (test mode — __setSpawnImpl was called). Test mocks do not actually
|
||||
// exec a binary, so sandbox isolation provides no protection there; the
|
||||
// wrap only obscures the original bin/args from the mock's assertions and
|
||||
// breaks every HTTP integration test that uses __setSpawnImpl + asserts
|
||||
// on spawn args. wrapSpawn is for real-CLI spawns; Suite 44 exercises that
|
||||
// path directly without going through this provider.
|
||||
//
|
||||
// Authority: @anthropic-ai/sandbox-runtime v0.0.52 wrapWithSandbox() API,
|
||||
// ADR 0014 § PR-B, spike-anthropic.mjs (PI231 2026-05-28).
|
||||
const usingMockSpawn = spawnImpl !== defaultSpawn;
|
||||
const wrapped = usingMockSpawn
|
||||
? { bin, args, env, cwd: undefined, sandboxed: false }
|
||||
: await wrapSpawn({
|
||||
bin,
|
||||
args,
|
||||
env,
|
||||
cwd: undefined, // let manager assign ephemeral cwd
|
||||
allowedDomains: ['api.anthropic.com', 'statsig.anthropic.com'],
|
||||
});
|
||||
// Task #8 — Phase 7 Solution 1: apply isolation context from orchestrator.
|
||||
// isolationCtx is provided by server.mjs (prepareIsolatedEnvironment) when
|
||||
// present. Three layers compose here:
|
||||
// Layer 1 (env): envOverrides have final precedence over buildSpawnEnv output.
|
||||
// Layer 4 (args): hardenedArgs transforms the final args array.
|
||||
// Layer 3 (wrap): wrapForLayer3 optionally wraps the command string via
|
||||
// sandbox-runtime (identity when inactive or hasInnerSandbox=true).
|
||||
// When isolationCtx is absent (legacy callers / tests), behavior is unchanged.
|
||||
// Authority: ADR 0014 Amendment 1 § A1.2 + ADR 0002 Amendment 9 § Backward compat.
|
||||
const envOverrides = isolationCtx?.envOverrides ?? {};
|
||||
const finalEnv = Object.keys(envOverrides).length > 0 ? { ...env, ...envOverrides } : env;
|
||||
|
||||
const hardenedArgs = isolationCtx?.hardenedArgs ?? ((a) => a);
|
||||
const args = hardenedArgs(baseArgs);
|
||||
|
||||
// Layer 3: wrapForLayer3 is async; returns the command string to spawn.
|
||||
// When sandbox-runtime is active and hasInnerSandbox=false for this provider,
|
||||
// the result is a wrapped shell invocation (/bin/sh -c <bwrap-args...> <cmd>).
|
||||
// When inactive (or hasInnerSandbox=true), it is an identity: returns bin unchanged.
|
||||
const wrapForLayer3 = isolationCtx?.wrapForLayer3 ?? (async (c) => c);
|
||||
const wrappedBin = await wrapForLayer3(bin);
|
||||
// If Layer 3 wrapping changed the bin (returns a '/bin/sh -c ...' style string),
|
||||
// pass the entire wrapped command as a shell-execute string; otherwise use bin/args
|
||||
// directly to avoid an unnecessary shell layer.
|
||||
let finalBin, finalArgs;
|
||||
if (wrappedBin !== bin) {
|
||||
// Layer 3 active: wrappedBin is the full shell command string. Invoke via sh -c.
|
||||
finalBin = '/bin/sh';
|
||||
finalArgs = ['-c', wrappedBin];
|
||||
} else {
|
||||
// Layer 3 inactive (identity): use bin + args directly.
|
||||
finalBin = bin;
|
||||
finalArgs = args;
|
||||
}
|
||||
|
||||
// ADR 0009 Amendment 1 § unchanged spawn args: NDJSON parsing unchanged.
|
||||
// Authority: ADR 0014 Amendment 1 § A1.2.3 (Layer 3 is orchestrator responsibility,
|
||||
// not provider responsibility); ADR 0002 Amendment 9 § Backward compatibility
|
||||
// (spawn() method is not changed; orchestrator composes above it).
|
||||
|
||||
// OCP server.mjs:542: spawn(CLAUDE, cliArgs, { env, stdio: ["pipe", "pipe", "pipe"] })
|
||||
const proc = spawnImpl(wrapped.bin, wrapped.args, {
|
||||
env: wrapped.env,
|
||||
...(wrapped.cwd ? { cwd: wrapped.cwd } : {}),
|
||||
const proc = spawnImpl(finalBin, finalArgs, {
|
||||
env: finalEnv,
|
||||
stdio: ['pipe', 'pipe', 'pipe'],
|
||||
});
|
||||
|
||||
@@ -1144,8 +1155,14 @@ async function* _spawnAndStream(irRequest, authContext, spawnImpl) {
|
||||
// Tests set `anthropic._spawnImpl = mockSpawn` before calling `anthropic.spawn()`.
|
||||
let _spawnImpl = defaultSpawn;
|
||||
|
||||
export async function* spawn(irRequest, authContext) {
|
||||
yield* _spawnAndStream(irRequest, authContext, _spawnImpl);
|
||||
// Task #8 — Phase 7 Solution 1: isolationCtx is an optional third argument.
|
||||
// When present (from server.mjs prepareIsolatedEnvironment call), it carries
|
||||
// { envOverrides, hardenedArgs, wrapForLayer3, cleanup } — the orchestrator
|
||||
// composes these on top of the provider's own env-cleanup + args composition.
|
||||
// When absent (legacy callers, tests that don't pass it), behavior is identical
|
||||
// to the pre-Task-#8 path. Authority: ADR 0014 Amendment 1 § A1.2.
|
||||
export async function* spawn(irRequest, authContext, isolationCtx) {
|
||||
yield* _spawnAndStream(irRequest, authContext, _spawnImpl, isolationCtx);
|
||||
}
|
||||
|
||||
// Test hook: allows tests to inject a mock spawn without importing child_process.
|
||||
@@ -1603,3 +1620,110 @@ const anthropic = {
|
||||
};
|
||||
|
||||
export default anthropic;
|
||||
|
||||
// ── Provider ISOLATION contract ───────────────────────────────────────────
|
||||
// ADR 0002 Amendment 9 (2026-05-29) — Provider ISOLATION Contract for
|
||||
// Multi-Tenant Spawn Isolation. Specifies the isolation primitives the
|
||||
// lib/sandbox/manager.mjs orchestrator composes on every uncached spawn
|
||||
// of this provider.
|
||||
//
|
||||
// Authority citations (ALIGNMENT.md Rule 1 — Cite First):
|
||||
// @anthropic-ai/claude-code v2.1.152
|
||||
// § --system-prompt — full system-prompt replacement suppresses env-block
|
||||
// injection, tool descriptions (Bash, Read, Write, Edit), and all other
|
||||
// tool surfaces that Claude Code injects by default. Verified live on
|
||||
// PI231 (arm64 Debian Bookworm) at docs/spikes/2026-05-29-ephemeral-home.md.
|
||||
// § HOME env override — claude CLI v2.1.152 honours HOME completely; all
|
||||
// state writes ($HOME/.claude.json, $HOME/.claude/*) redirect to the
|
||||
// ephemeral root. Auth reads from $HOME/.claude/.credentials.json.
|
||||
// Verified at docs/spikes/2026-05-29-ephemeral-home.md (✅ PASS).
|
||||
// ADR 0009 Amendment 1 (Phase 6c) — the --system-prompt flag that achieves
|
||||
// tool suppression is injected by the spawn() method; it is the enforcement
|
||||
// mechanism crossTenantReadProtection='tool-suppression' cites.
|
||||
// ADR 0014 Amendment 1 (2026-05-29) — supersedes outer-bwrap PR-B with the
|
||||
// per-spawn ephemeral-home + per-provider ISOLATION architecture that this
|
||||
// block participates in. §A1.2 defines the four-layer model; §A1.3 names
|
||||
// this contract surface.
|
||||
// ADR 0002 Amendment 9 (2026-05-29) — specifies the ISOLATION contract shape,
|
||||
// field-level semantics, validation rules, and the anthropic concrete
|
||||
// instance this block implements.
|
||||
// cc-mem incident memory:
|
||||
// ~/.cc-rules/memory/projects/olp/incident_2026_05_27_spawn_cli_security.md
|
||||
// § 6.1 — empirical evidence that --system-prompt suppression is effective:
|
||||
// the model in a stream-json spawn without --tools cannot emit tool_use
|
||||
// blocks because the default Claude Code tool descriptions are absent.
|
||||
// This is the primary empirical basis for crossTenantReadProtection:
|
||||
// 'tool-suppression' in the absence of OS-level bwrap isolation.
|
||||
//
|
||||
// isolation rationale: Anthropic Claude reaches OLP via stream-json transport
|
||||
// without a tool surface (ADR 0009 Amendment 1's --system-prompt injection
|
||||
// suppresses env-block, file tools, Bash, and Read/Write/Edit). The model has
|
||||
// no documented mechanism to read files during the spawn. Cross-tenant read
|
||||
// protection is achieved at the prompt-engineering / CLI-flag layer. The OS-
|
||||
// level isolation primitives (HOME redirect + ephemeral credential mount) add
|
||||
// defense in depth against future CLI changes that might re-introduce a tool
|
||||
// surface. (cf. ADR 0014 Amendment 1 § A1.2.4 — Layer 4 tool hardening)
|
||||
|
||||
export const ISOLATION = {
|
||||
// Returns the env-var overrides that steer claude CLI to use the per-spawn
|
||||
// ephemeral home rather than the server process's real $HOME.
|
||||
// HOME is the POSIX-conventional lookup root; claude v2.1.152 reads
|
||||
// $HOME/.claude/.credentials.json for OAuth and writes session state to
|
||||
// $HOME/.claude.json and $HOME/.claude/*. Redirecting HOME is the
|
||||
// documented and verified mechanism (docs/spikes/2026-05-29-ephemeral-home.md).
|
||||
// CLAUDE_CONFIG_DIR is NOT honored as of v2.1.152 — do not use it.
|
||||
// keyId / reqId are received for signature consistency but unused here.
|
||||
ephemeralEnvOverrides: ({ ephemeralRoot, keyId: _keyId, reqId: _reqId }) => ({
|
||||
HOME: ephemeralRoot,
|
||||
}),
|
||||
|
||||
// Credential files to symlink from the operator's real home into the
|
||||
// ephemeral home so that claude CLI can authenticate without being given
|
||||
// access to the full ~/.claude/ directory.
|
||||
// srcAbsPath MUST be absolute (ADR 0002 Amendment 9 § 2 validation rule).
|
||||
// Authority: anthropic.auth.path above — ~/.claude/.credentials.json is
|
||||
// the documented OAuth artifact for @anthropic-ai/claude-code v2.1.152.
|
||||
credentialMounts: [
|
||||
[join(homedir(), '.claude', '.credentials.json'), '.claude/.credentials.json'],
|
||||
],
|
||||
|
||||
// Directories that must be pre-created (mkdir -p) under ephemeralRoot before
|
||||
// credentialMounts are processed. The CLI expects $HOME/.claude/ to exist;
|
||||
// absent the directory the auth-file symlink's parent would be missing.
|
||||
requiredHomePaths: [
|
||||
'.claude',
|
||||
// No additional mandatory pre-existing subdirs observed as of v2.1.152.
|
||||
// If future CLI versions add a mandatory subdir (e.g. .claude/logs),
|
||||
// add it here with an observed-behavior comment per ADR 0002 Amendment 9
|
||||
// § 3 ("speculative directories are a Rule 2 violation").
|
||||
],
|
||||
|
||||
// claude CLI (stream-json transport) does NOT spawn its own bwrap or
|
||||
// sandbox-exec boundary during normal OLP use. The Layer 3 outer
|
||||
// sandbox-runtime wrap (ADR 0014 Amendment 1 § A1.2.3) is therefore
|
||||
// applicable for this provider and must NOT be skipped.
|
||||
// Authority: @anthropic-ai/claude-code v2.1.152 stream-json path verified
|
||||
// at docs/spikes/2026-05-29-ephemeral-home.md — no nested sandbox observed.
|
||||
hasInnerSandbox: false,
|
||||
|
||||
// ADR 0009 Amendment 1's --system-prompt injection (Phase 6c) replaces the
|
||||
// entire system prompt and eliminates the default tool surface (Bash, Read,
|
||||
// Write, Edit, computer-use blocks) that claude would otherwise expose.
|
||||
// Empirical evidence: incident memory § 6.1 confirms suppression is effective
|
||||
// in stream-json mode. OS-level isolation (Layers 1-3) adds defense in depth.
|
||||
crossTenantReadProtection: 'tool-suppression',
|
||||
|
||||
// With tool-suppression active and no inner sandbox, the model cannot read
|
||||
// arbitrary files; the ephemeral-home + credential-mount isolation (Layers
|
||||
// 1-2) provides per-request HOME isolation. This combination is rated
|
||||
// suitable for a shared-OS-user deployment (all OLP keys on one OS user).
|
||||
// Authority: ADR 0014 Amendment 1 § A1.2 four-layer model + ADR 0006
|
||||
// risk-tier framework.
|
||||
recommendedDeploymentTier: 'shared-os-user',
|
||||
|
||||
// toolHardeningArgs omitted — the existing spawn() method's args already
|
||||
// encode the --system-prompt tool-suppression mechanism (ADR 0009 Amendment
|
||||
// 1). No additional CLI flags are needed at the orchestrator level.
|
||||
// Per ADR 0002 Amendment 9 § 7: absence means the orchestrator passes args
|
||||
// through unchanged from spawn().
|
||||
};
|
||||
|
||||
+166
-5
@@ -458,7 +458,7 @@ function buildSpawnEnv() {
|
||||
//
|
||||
// Authority: Codex CLI reference § "codex exec [flags] PROMPT"
|
||||
// § "--json": NDJSON event stream on stdout
|
||||
async function* _spawnAndStream(irRequest, authContext, spawnImpl) {
|
||||
async function* _spawnAndStream(irRequest, authContext, spawnImpl, isolationCtx) {
|
||||
const auth = authContext ?? readAuthArtifact();
|
||||
if (!auth?.accessToken) {
|
||||
throw new ProviderError(
|
||||
@@ -468,7 +468,7 @@ async function* _spawnAndStream(irRequest, authContext, spawnImpl) {
|
||||
}
|
||||
|
||||
const bin = resolveCodexBin();
|
||||
const { args, prompt, useStdin } = irToCodex(irRequest);
|
||||
const { args: baseArgs, prompt, useStdin } = irToCodex(irRequest);
|
||||
const env = buildSpawnEnv();
|
||||
|
||||
// Authority: Codex CLI reference § "Authentication"
|
||||
@@ -476,7 +476,34 @@ async function* _spawnAndStream(irRequest, authContext, spawnImpl) {
|
||||
// No explicit token injection: Codex CLI reads its own auth.json
|
||||
// (contrast with Anthropic plugin which injects CLAUDE_CODE_OAUTH_TOKEN).
|
||||
|
||||
const proc = spawnImpl(bin, args, { env, stdio: ['pipe', 'pipe', 'pipe'] });
|
||||
// Task #8 — Phase 7 Solution 1: apply isolation context from orchestrator.
|
||||
// isolationCtx is provided by server.mjs (prepareIsolatedEnvironment) when
|
||||
// present. Three layers compose here:
|
||||
// Layer 1 (env): envOverrides (HOME, CODEX_HOME) have final precedence.
|
||||
// Layer 4 (args): hardenedArgs injects --sandbox read-only + -c approval_policy.
|
||||
// Layer 3 (wrap): wrapForLayer3 is identity for codex (hasInnerSandbox=true).
|
||||
// When isolationCtx is absent (legacy callers / tests), behavior is unchanged.
|
||||
// Authority: ADR 0014 Amendment 1 § A1.2 + ADR 0002 Amendment 9 § Backward compat.
|
||||
const envOverrides = isolationCtx?.envOverrides ?? {};
|
||||
const finalEnv = Object.keys(envOverrides).length > 0 ? { ...env, ...envOverrides } : env;
|
||||
|
||||
const hardenedArgs = isolationCtx?.hardenedArgs ?? ((a) => a);
|
||||
const args = hardenedArgs(baseArgs);
|
||||
|
||||
// Layer 3: wrapForLayer3 for codex is always identity (hasInnerSandbox=true);
|
||||
// included here for API symmetry with the anthropic path and future-proofing.
|
||||
const wrapForLayer3 = isolationCtx?.wrapForLayer3 ?? (async (c) => c);
|
||||
const wrappedBin = await wrapForLayer3(bin);
|
||||
let finalBin, finalArgs;
|
||||
if (wrappedBin !== bin) {
|
||||
finalBin = '/bin/sh';
|
||||
finalArgs = ['-c', wrappedBin];
|
||||
} else {
|
||||
finalBin = bin;
|
||||
finalArgs = args;
|
||||
}
|
||||
|
||||
const proc = spawnImpl(finalBin, finalArgs, { env: finalEnv, stdio: ['pipe', 'pipe', 'pipe'] });
|
||||
|
||||
// Write prompt via stdin for multi-line prompts (D6 assumption A1)
|
||||
if (useStdin) {
|
||||
@@ -659,8 +686,14 @@ async function* _spawnAndStream(irRequest, authContext, spawnImpl) {
|
||||
// spawn: async (irRequest, authContext) => AsyncIterator<ResponseChunk>
|
||||
let _spawnImpl = defaultSpawn;
|
||||
|
||||
export async function* spawn(irRequest, authContext) {
|
||||
yield* _spawnAndStream(irRequest, authContext, _spawnImpl);
|
||||
// Task #8 — Phase 7 Solution 1: isolationCtx is an optional third argument.
|
||||
// When present (from server.mjs prepareIsolatedEnvironment call), it carries
|
||||
// { envOverrides, hardenedArgs, wrapForLayer3, cleanup } — the orchestrator
|
||||
// composes these on top of the provider's own env-cleanup + args composition.
|
||||
// When absent (legacy callers, tests that don't pass it), behavior is unchanged.
|
||||
// Authority: ADR 0014 Amendment 1 § A1.2.
|
||||
export async function* spawn(irRequest, authContext, isolationCtx) {
|
||||
yield* _spawnAndStream(irRequest, authContext, _spawnImpl, isolationCtx);
|
||||
}
|
||||
|
||||
// Test hook: inject mock spawn without importing child_process.
|
||||
@@ -795,6 +828,134 @@ export function doctorChecks({ _binaryExistsFn, _authReadFn } = {}) {
|
||||
];
|
||||
}
|
||||
|
||||
// ── ISOLATION export ─────────────────────────────────────────────────────
|
||||
// Declares per-provider isolation primitives consumed by lib/sandbox/manager.mjs
|
||||
// (per ADR 0014 Amendment 1 + ADR 0002 Amendment 9).
|
||||
//
|
||||
// Authority citations (all required per ALIGNMENT.md Rule 1):
|
||||
// codex CLI v0.133.0 — current PI231 prod version (verified 2026-05-29 spike)
|
||||
// https://developers.openai.com/codex/config-reference — CODEX_HOME env var
|
||||
// (2 occurrences verified: "$CODEX_HOME/profile-name.config.toml" and
|
||||
// "$CODEX_HOME/log" path templates)
|
||||
// https://developers.openai.com/codex/auth/ — ~/.codex/auth.json path
|
||||
// (2 occurrences verified: "auth.json under CODEX_HOME" credential-storage
|
||||
// section)
|
||||
// https://developers.openai.com/codex/concepts/sandboxing — --sandbox flag +
|
||||
// read-only default (codex inner bubblewrap sandbox)
|
||||
// openai/codex#16018 — inner bwrap behavior documented (failure under
|
||||
// restricted env, establishing hasInnerSandbox: true)
|
||||
// ADR 0014 Amendment 1 — orchestrator composition architecture
|
||||
// ADR 0002 Amendment 9 — ISOLATION contract spec (field semantics)
|
||||
// docs/spikes/2026-05-29-ephemeral-home.md § 5.3 — flag-drift caveat
|
||||
// (--ask-for-approval removed in codex v0.133.0; use -c approval_policy=)
|
||||
//
|
||||
// isolation rationale: OpenAI Codex's `codex exec` exposes a shell tool that
|
||||
// actually executes commands during the spawn (cc-mem incident memory § 3.2).
|
||||
// The CLI provides its own inner bubblewrap sandbox (`--sandbox read-only` by
|
||||
// default per https://developers.openai.com/codex/concepts/sandboxing) that
|
||||
// confines shell tool reads/writes. The orchestrator's outer isolation composes
|
||||
// with the inner sandbox: credential-dir redirect via CODEX_HOME
|
||||
// (https://developers.openai.com/codex/config-reference) + HOME redirect for
|
||||
// the inner bwrap's HOME lookup + per-spawn ephemeral credential mount.
|
||||
// hasInnerSandbox: true so the outer profile is relaxed to permit the inner
|
||||
// bwrap's user-namespace clone (openai/codex#16018).
|
||||
|
||||
export const ISOLATION = {
|
||||
// ephemeralEnvOverrides: pure function, no side effects, no fs access.
|
||||
// CODEX_HOME redirects the entire codex config/credential base directory.
|
||||
// HOME is also redirected because the codex inner sandbox inherits the parent
|
||||
// process's HOME for its own home lookup unless overridden.
|
||||
// Authority: CODEX_HOME → https://developers.openai.com/codex/config-reference
|
||||
// HOME → POSIX convention (both verified by PI231 spike § 4.3-4.4).
|
||||
ephemeralEnvOverrides: ({ ephemeralRoot, keyId: _keyId, reqId: _reqId }) => ({
|
||||
HOME: ephemeralRoot,
|
||||
CODEX_HOME: `${ephemeralRoot}/.codex`,
|
||||
}),
|
||||
|
||||
// credentialMounts: static list of [srcAbsPath, dstRelativeToEphemeralRoot].
|
||||
// srcAbsPath uses os.homedir() (imported as `homedir` at top of file) per
|
||||
// ADR 0002 Amendment 9 § Field 2 validation rules: absolute paths only, no
|
||||
// `~/` prefixes (shell-expansion semantics differ from Node.js behavior).
|
||||
// Authority: ~/.codex/auth.json → https://developers.openai.com/codex/auth/
|
||||
// "Codex caches login details locally in a plaintext file at ~/.codex/auth.json"
|
||||
// (matches existing codex.mjs `auth.path` field declaration above).
|
||||
credentialMounts: [
|
||||
[join(homedir(), '.codex', 'auth.json'), '.codex/auth.json'],
|
||||
],
|
||||
|
||||
// requiredHomePaths: directories to mkdir-p under ephemeralRoot before mounts.
|
||||
// .codex is required because CODEX_HOME points there and codex startup may
|
||||
// attempt to read from it before any auto-create logic runs (observed in
|
||||
// PI231 spike § 4.3 post-state: .codex/ created at spawn time).
|
||||
requiredHomePaths: [
|
||||
'.codex',
|
||||
],
|
||||
|
||||
// hasInnerSandbox: true — codex exec spawns its own bubblewrap sandbox
|
||||
// internally. Declaring true tells the outer isolation orchestrator to relax
|
||||
// the outer profile to permit clone(CLONE_NEWUSER) so the inner bwrap can
|
||||
// create user namespaces. Without this flag the inner bwrap fails with
|
||||
// EPERM. Authority: openai/codex#16018 + https://developers.openai.com/codex/concepts/sandboxing
|
||||
hasInnerSandbox: true,
|
||||
|
||||
// crossTenantReadProtection: 'inner-sandbox' — codex's shell tool runs real
|
||||
// commands but the inner bubblewrap sandbox (read-only by default) confines
|
||||
// reads/writes to the inner namespace. The toolHardeningArgs below makes this
|
||||
// default explicit at the spawn-args level. Authority: openai/codex#16018 +
|
||||
// https://developers.openai.com/codex/concepts/sandboxing.
|
||||
crossTenantReadProtection: 'inner-sandbox',
|
||||
|
||||
// recommendedDeploymentTier: 'per-os-user' — the inner bwrap sandbox protects
|
||||
// against accidental cross-tenant leakage from the model's shell tool, but a
|
||||
// sandbox-escape CVE (e.g. in bubblewrap) would expose the OS-user filesystem.
|
||||
// Per-OS-user isolation adds defense in depth. See ADR 0002 Amendment 9
|
||||
// § Field 6 for the full rationale per recommendedDeploymentTier semantics.
|
||||
recommendedDeploymentTier: 'per-os-user',
|
||||
|
||||
// toolHardeningArgs: injects --sandbox read-only if not already present, and
|
||||
// -c approval_policy="never" to suppress interactive approval prompts.
|
||||
//
|
||||
// Flag-drift caveat (docs/spikes/2026-05-29-ephemeral-home.md § 5.3):
|
||||
// ADR 0002 Amendment 9 § codex example uses `--ask-for-approval never`.
|
||||
// PI231 spike (2026-05-29) confirmed this flag was REMOVED in codex
|
||||
// v0.133.0. The codex v0.133.0 `--help` output shows the replacement is
|
||||
// the generic config-override flag: `-c approval_policy="never"`.
|
||||
// We use `-c approval_policy="never"` here. This deviates from the ADR
|
||||
// 0002 Amendment 9 code example (not the field spec — the spec only
|
||||
// requires an injected flag corresponding to a documented CLI flag).
|
||||
// The config-override form is documented at https://developers.openai.com/codex/config-reference
|
||||
// as the mechanism for overriding any config key at spawn time, including
|
||||
// approval_policy. The deviation is intentional, flag-drift-driven, and
|
||||
// takes precedence over the (now-incorrect) Amendment 9 code example per
|
||||
// ALIGNMENT.md Rule 2 (provider CLI is the authority, not the ADR text).
|
||||
//
|
||||
// --sandbox read-only: Authority: https://developers.openai.com/codex/concepts/sandboxing
|
||||
// § "Sandboxing modes" — the default posture is `read-only`; injecting it
|
||||
// explicitly prevents a future codex default change from silently weakening
|
||||
// isolation (same rationale as the existing irToCodex --skip-git-repo-check).
|
||||
toolHardeningArgs: (existingArgs) => {
|
||||
let result = [...existingArgs];
|
||||
|
||||
// Inject --sandbox read-only if the caller has not already specified --sandbox.
|
||||
if (!result.some(arg => arg === '--sandbox' || arg.startsWith('--sandbox='))) {
|
||||
result = [...result, '--sandbox', 'read-only'];
|
||||
}
|
||||
|
||||
// Inject -c approval_policy="never" if not already present.
|
||||
// Checks for the exact -c flag form used by codex v0.133.0 config overrides.
|
||||
// Flag-drift note: --ask-for-approval (pre-v0.133.0) is NOT injected — it
|
||||
// was removed; see header comment above.
|
||||
const approvalAlreadySet = result.some(
|
||||
(arg, i) => arg === '-c' && typeof result[i + 1] === 'string' && result[i + 1].startsWith('approval_policy'),
|
||||
);
|
||||
if (!approvalAlreadySet) {
|
||||
result = [...result, '-c', 'approval_policy="never"'];
|
||||
}
|
||||
|
||||
return result;
|
||||
},
|
||||
};
|
||||
|
||||
// ── Provider export ───────────────────────────────────────────────────────
|
||||
// Conforms to ADR 0002 § "Provider contract (v1.0 interface)" + contractVersion.
|
||||
|
||||
|
||||
+325
-280
@@ -1,291 +1,178 @@
|
||||
/**
|
||||
* lib/sandbox/manager.mjs — Sandbox manager bootstrap + spawn-wrap (Phase 7 PR-B)
|
||||
* lib/sandbox/manager.mjs — Sandbox manager + ephemeral-home orchestrator (Phase 7 PR-B')
|
||||
*
|
||||
* Authority:
|
||||
* OLP ADR 0014 Amendment 1 — Solution 1 four-layer architecture
|
||||
* § A1.2.1 — Layer 1: per-spawn ephemeral home directory
|
||||
* § A1.2.2 — Layer 2: symlinked credential files into ephemeral home
|
||||
* § A1.2.3 — Layer 3: optional sandbox-runtime per-call customConfig
|
||||
* § A1.6.1 — OLP_SANDBOX_DISABLED gate (preserved 1-2 releases)
|
||||
* OLP ADR 0002 Amendment 9 — Provider ISOLATION contract specification
|
||||
* § Field specification (ephemeralEnvOverrides, credentialMounts,
|
||||
* requiredHomePaths, hasInnerSandbox, toolHardeningArgs)
|
||||
* @anthropic-ai/sandbox-runtime v0.0.52
|
||||
* https://github.com/anthropic-experimental/sandbox-runtime
|
||||
* dist/sandbox/sandbox-manager.js — SandboxManager.initialize(), wrapWithSandbox()
|
||||
* dist/sandbox/sandbox-utils.js — getDefaultWritePaths() (used internally)
|
||||
* dist/sandbox/sandbox-manager.js — SandboxManager.wrapWithSandbox()
|
||||
* The third argument `customConfig` is the per-call override mechanism.
|
||||
* 2026-05-29 PI231 spike (docs/spikes/2026-05-29-ephemeral-home.md):
|
||||
* Verified HOME (claude) + CODEX_HOME (codex) redirect 100% of CLI state
|
||||
* writes into ephemeral location. Credentials via symlink work end-to-end.
|
||||
*
|
||||
* 2026-05-28 PR-A spike report on PI231 (arm64 Debian Bookworm):
|
||||
* /tmp/sandbox-spike/spike-anthropic.mjs — wrapWithSandbox call signature,
|
||||
* CLAUDE_CODE_OAUTH_TOKEN env passthrough, shell-mode spawn pattern.
|
||||
* OLP ADR 0014 § Decision (singleton at boot) + § PR-B specific scope
|
||||
* OLP ADR 0009 Amendment 1 § Caveats #3 (sandbox is cloud prerequisite)
|
||||
* cc-mem incident 2026-05-27 § 3 (multi-tenant security gap motivation)
|
||||
* ALIGNMENT.md Rule 1 — provider plugin authority citation
|
||||
* Design (Amendment 1 architecture):
|
||||
*
|
||||
* Design:
|
||||
* One-shot bootstrap at server startup (idempotent). If sandbox not available
|
||||
* (doctor.available=false or SandboxManager.initialize throws), bootstrap is a
|
||||
* no-op and isSandboxActive() returns false → provider falls back to direct spawn
|
||||
* (transparent pass-through).
|
||||
* Boot-time:
|
||||
* bootstrapSandbox() — checks sandbox-runtime library + OS deps availability
|
||||
* via doctor.mjs. Does NOT call SandboxManager.initialize() (per A1.2.3:
|
||||
* Layer 3 is per-call, not boot-singleton). The singleton pattern from PR-B
|
||||
* is removed entirely — per-spawn config eliminates its reason to exist.
|
||||
*
|
||||
* Singleton pattern: SandboxManager is a process-wide singleton per library
|
||||
* design (reset() clears ALL state). PR-B initializes once at boot with union
|
||||
* config (Anthropic domains only; codex config follows in PR-C). Per-request
|
||||
* wrapSpawn() calls SandboxManager.wrapWithSandbox() which reads from the
|
||||
* already-initialized config state — no per-request initialize().
|
||||
* Per-spawn (uncached /v1/chat/completions request):
|
||||
* prepareIsolatedEnvironment({ provider, keyId, reqId }) — the main
|
||||
* orchestrator entry point. Reads provider.ISOLATION, composes Layers 1–3:
|
||||
* Layer 1: mkdir /tmp/olp-spawn/<keyId>/<reqId>/home
|
||||
* Layer 2: symlink credentialMounts into ephemeralRoot
|
||||
* Layer 3: wrapForLayer3 — when isSandboxActive() && !hasInnerSandbox,
|
||||
* calls SandboxManager.wrapWithSandbox() per-call with
|
||||
* per-spawn customConfig
|
||||
* Returns { ephemeralRoot, envOverrides, hardenedArgs, wrapForLayer3, cleanup }.
|
||||
*
|
||||
* ADR 0014 § Pitfalls #4: SandboxManager.reset() in test teardown must happen
|
||||
* in finally blocks; concurrent in-flight spawns may break if reset fires while
|
||||
* a wrapWithSandbox call is in-flight. OLP's current single-server model (one
|
||||
* process) makes this safe: tests call __resetSandboxManagerForTests() which
|
||||
* also calls SandboxManager.reset() — only safe in test context where no real
|
||||
* spawns are in-flight.
|
||||
* OLP_SANDBOX_DISABLED=1 (A1.6.1 belt-and-suspenders gate):
|
||||
* When set, Layers 1+2 still operate (ephemeral home + credential mounts).
|
||||
* Layer 3 (wrapForLayer3) becomes identity. Preserved for 1-2 releases.
|
||||
*
|
||||
* Exports:
|
||||
* bootstrapSandbox(opts?) — one-shot bootstrap; returns { active, reason?, summary? }
|
||||
* isSandboxActive() — synchronous query
|
||||
* wrapSpawn({ bin, args, env, cwd, allowedDomains })
|
||||
* — wraps spawn args; transparent pass-through when inactive
|
||||
* __resetSandboxManagerForTests() — test seam: reset internal state + SandboxManager
|
||||
* bootstrapSandbox(opts?) — preflight check; returns { available, reason?, summary? }
|
||||
* isSandboxActive() — synchronous; true when Layer 3 is operational
|
||||
* prepareIsolatedEnvironment({ provider, keyId, reqId })
|
||||
* — compose Layers 1+2+3; returns env + hooks + cleanup
|
||||
* __resetSandboxManagerForTests() — test seam: reset module state
|
||||
*/
|
||||
|
||||
import { createHash } from 'node:crypto';
|
||||
import { mkdirSync } from 'node:fs';
|
||||
import { existsSync, mkdirSync, symlinkSync } from 'node:fs';
|
||||
import { rm } from 'node:fs/promises';
|
||||
import { homedir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { dirname, join } from 'node:path';
|
||||
import { checkSandboxAvailability } from './doctor.mjs';
|
||||
|
||||
// ── Internal state ────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Whether bootstrapSandbox() has been called (initialized = true means we
|
||||
* ran through bootstrap, not necessarily that sandbox is active).
|
||||
* Whether bootstrapSandbox() has completed (initialized = true means bootstrap
|
||||
* ran; does NOT mean sandbox is active).
|
||||
* @type {boolean}
|
||||
*/
|
||||
let _initialized = false;
|
||||
|
||||
/**
|
||||
* Whether the SandboxManager was successfully initialized and is ready to wrap.
|
||||
* Whether the sandbox-runtime library is loaded and OS deps are present.
|
||||
* When true, Layer 3 (per-call wrapWithSandbox) is available.
|
||||
* @type {boolean}
|
||||
*/
|
||||
let _active = false;
|
||||
|
||||
/**
|
||||
* The config-at-boot snapshot passed to SandboxManager.initialize().
|
||||
* Null if never initialized or bootstrap failed.
|
||||
* Cached failure reason string (when _active=false after bootstrap).
|
||||
* @type {string|null}
|
||||
*/
|
||||
let _failReason = null;
|
||||
|
||||
/**
|
||||
* Memoized sandbox-runtime module (loaded lazily on first prepareIsolatedEnvironment
|
||||
* call that needs Layer 3). Import caching is native ESM semantics; this variable
|
||||
* holds the resolved SandboxManager class after first load.
|
||||
* @type {object|null}
|
||||
*/
|
||||
let _initConfig = null;
|
||||
let _SandboxManager = null;
|
||||
|
||||
// ── Ephemeral workspace root ─────────────────────────────────────────────
|
||||
// Per-request cwd: /tmp/olp-spawn/<uuid>/ — unique per request to prevent
|
||||
// cross-request contamination. Caller (provider) owns cleanup (or trusts tmpfs
|
||||
// lifetime). Created by mkdirSync(recursive:true) inside wrapSpawn().
|
||||
// /tmp/olp-spawn/<keyId>/<reqId>/home — unique per (key, request).
|
||||
const SPAWN_BASE_DIR = '/tmp/olp-spawn';
|
||||
|
||||
// ── Custom error types ───────────────────────────────────────────────────
|
||||
|
||||
export class SandboxBootstrapError extends Error {
|
||||
constructor(message) {
|
||||
super(message);
|
||||
this.name = 'SandboxBootstrapError';
|
||||
}
|
||||
}
|
||||
|
||||
export class SandboxWrapError extends Error {
|
||||
constructor(message) {
|
||||
super(message);
|
||||
this.name = 'SandboxWrapError';
|
||||
}
|
||||
}
|
||||
|
||||
// ── bootstrapSandbox ──────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* One-shot bootstrap of the sandbox. Idempotent — safe to call multiple times.
|
||||
* If already bootstrapped, returns cached result immediately.
|
||||
* Preflight check for Layer 3 capability (sandbox-runtime library + OS deps).
|
||||
* Idempotent — safe to call multiple times; returns cached result after first call.
|
||||
*
|
||||
* Steps:
|
||||
* 1. Call checkSandboxAvailability() from doctor module.
|
||||
* 2. If !available → set _active=false, return { active:false, reason }.
|
||||
* 3. If available → build config-at-boot, call SandboxManager.initialize(config).
|
||||
* 4. On init success → _active=true, return { active:true, summary }.
|
||||
* 5. On init failure → log + _active=false + return error (server still starts).
|
||||
* This function NO LONGER calls SandboxManager.initialize() at boot.
|
||||
* Per ADR 0014 Amendment 1 § A1.2.3, Layer 3 uses per-call wrapWithSandbox()
|
||||
* with a per-spawn customConfig; the singleton boot-init pattern is removed.
|
||||
*
|
||||
* The network allowedDomains covers the Anthropic provider only (PR-B scope).
|
||||
* Codex domains will be added in PR-C alongside the enableWeakerNestedSandbox flag.
|
||||
*
|
||||
* ADR 0014 § PR-B: denyRead covers ~/.olp, ~/.claude, ~/.ssh, ~/.config, ~/.codex
|
||||
* using absolute literal Linux paths (no globs — see ADR 0014 § Pitfalls #2).
|
||||
* ~/.olp contains keys.json (OLP API keys). ~/.claude contains OAuth credentials.
|
||||
* ~/.ssh and ~/.config contain identity material. ~/.codex contains codex config.
|
||||
* The OLP_SANDBOX_DISABLED=1 env-var gate (A1.6.1): when set, Layer 3 is
|
||||
* disabled. Layers 1+2 (ephemeral home + credential mounts) still operate.
|
||||
*
|
||||
* @param {object} [opts]
|
||||
* @param {boolean} [opts.force=false] — if true, re-run bootstrap even if already initialized
|
||||
* @param {boolean} [opts.force=false] — re-run even if already bootstrapped
|
||||
* @returns {Promise<{ active: boolean, reason?: string, summary?: string }>}
|
||||
*/
|
||||
export async function bootstrapSandbox(opts = {}) {
|
||||
// Return cached result if already initialized (unless forced)
|
||||
if (_initialized && !opts.force) {
|
||||
return _active
|
||||
? { active: true, summary: _buildSummary() }
|
||||
: { active: false, reason: _initConfig?.failReason ?? 'sandbox not available' };
|
||||
: { active: false, reason: _failReason ?? 'sandbox not available' };
|
||||
}
|
||||
|
||||
// OLP_SANDBOX_DISABLED env-var gate (2026-05-28 PR-B emergency disable):
|
||||
// Live PI231 evidence showed that even with the exit-null guard, HTTP-path
|
||||
// anthropic spawns produced no claude stdout when wrapped (manual exec of
|
||||
// the SAME wrap script in the same process did produce output — root cause
|
||||
// not yet isolated; likely interaction between SandboxManager in-process
|
||||
// proxy sockets and OLP's request-handler event loop). Until the root cause
|
||||
// is debugged + Suite 44-equivalent E2E tests cover the HTTP path, the
|
||||
// sandbox bootstrap is opt-out via OLP_SANDBOX_DISABLED=1 in the server env.
|
||||
//
|
||||
// Default is sandbox-enabled (no env var = try-and-bootstrap). Sandbox is
|
||||
// skipped only when the operator explicitly disables.
|
||||
//
|
||||
// Future PR-B follow-up: investigate the in-process proxy lifecycle
|
||||
// interaction with OLP's HTTP server event loop; capture diagnostic
|
||||
// transcript; ship Suite 44-equivalent that exercises the full HTTP
|
||||
// request → sandbox spawn → response pipeline.
|
||||
// OLP_SANDBOX_DISABLED gate (A1.6.1): operator emergency disable.
|
||||
// Layer 3 skipped; Layers 1+2 unaffected (ephemeral home + credential mounts).
|
||||
if (process.env.OLP_SANDBOX_DISABLED === '1') {
|
||||
_initialized = true;
|
||||
_active = false;
|
||||
_initConfig = { failReason: 'OLP_SANDBOX_DISABLED=1 — sandbox bootstrap skipped by operator' };
|
||||
return {
|
||||
active: false,
|
||||
reason: 'OLP_SANDBOX_DISABLED=1 — sandbox bootstrap skipped by operator',
|
||||
};
|
||||
_failReason = 'OLP_SANDBOX_DISABLED=1 — Layer 3 (sandbox-runtime wrap) disabled by operator; Layers 1+2 still active';
|
||||
return { active: false, reason: _failReason };
|
||||
}
|
||||
|
||||
// Reset state for re-bootstrap
|
||||
// Reset for re-bootstrap
|
||||
_initialized = false;
|
||||
_active = false;
|
||||
_initConfig = null;
|
||||
_failReason = null;
|
||||
|
||||
// Step 1: Check OS + library availability
|
||||
// Check OS + library availability via doctor
|
||||
let availability;
|
||||
try {
|
||||
availability = await checkSandboxAvailability();
|
||||
} catch (e) {
|
||||
_initialized = true;
|
||||
_active = false;
|
||||
_initConfig = { failReason: `doctor check threw: ${e?.message ?? e}` };
|
||||
return { active: false, reason: _initConfig.failReason };
|
||||
_failReason = `doctor check threw: ${e?.message ?? e}`;
|
||||
return { active: false, reason: _failReason };
|
||||
}
|
||||
|
||||
if (!availability.available) {
|
||||
_initialized = true;
|
||||
_active = false;
|
||||
const reason = availability.missing.length > 0
|
||||
_failReason = availability.missing?.length > 0
|
||||
? `sandbox deps missing: ${availability.missing.join(', ')}`
|
||||
: `sandbox not available on platform: ${availability.details?.platform}`;
|
||||
_initConfig = { failReason: reason };
|
||||
return { active: false, reason };
|
||||
return { active: false, reason: _failReason };
|
||||
}
|
||||
|
||||
// Step 2: Build config-at-boot
|
||||
// Network allowedDomains: Anthropic provider API domains (PR-B scope).
|
||||
// - api.anthropic.com: primary Anthropic API endpoint
|
||||
// - statsig.anthropic.com: claude CLI telemetry (verified empirically in spike;
|
||||
// required by claude CLI OAuth token refresh path — removing it causes auth failure)
|
||||
// TODO(PR-C): union in codex/openai provider domains when codex wrap lands.
|
||||
const allowedDomains = [
|
||||
'api.anthropic.com',
|
||||
'statsig.anthropic.com',
|
||||
];
|
||||
|
||||
const home = homedir();
|
||||
|
||||
// denyRead: Absolute literal Linux paths per ADR 0014 § Pitfalls #2.
|
||||
// No ~ or glob — ripgrep glob expansion is not used here to stay safe on
|
||||
// both Linux (bwrap) and macOS (sandbox-exec profile).
|
||||
//
|
||||
// 2026-05-28 PR-B fold-in: ~/.claude is NOT in denyRead. It contains the
|
||||
// spawn's own OAuth credentials — claude CLI must read its own auth file
|
||||
// to function. Denying read here causes "Not logged in" failures even
|
||||
// though the operator has valid credentials present.
|
||||
//
|
||||
// The cross-tenant risk for ~/.claude is mitigated by Phase 6c's
|
||||
// --system-prompt flag (ADR 0009 Amendment 1): the system prompt is
|
||||
// fully replaced, suppressing the default tool descriptions that would
|
||||
// otherwise tell the model it has Read/Bash. Without tool descriptions,
|
||||
// the model is highly unlikely to emit tool_use even under prompt
|
||||
// injection. Sandbox's contribution here is protecting OTHER auth
|
||||
// material (other clients' OLP keys, SSH identity, other providers'
|
||||
// tokens) — files claude CLI does NOT legitimately need.
|
||||
//
|
||||
// If we ever switch to a CLI that requires reading credentials.json
|
||||
// AND also legitimately offers tool execution that surfaces those files
|
||||
// (no known case today), this trade-off needs revisiting.
|
||||
const denyRead = [
|
||||
join(home, '.olp'), // OLP API keys + config — cross-tenant
|
||||
join(home, '.ssh'), // SSH identity material — lateral movement
|
||||
join(home, '.config'), // Generic config dir (may contain tokens)
|
||||
join(home, '.codex'), // Codex config — other-provider auth (PR-C will wrap codex)
|
||||
// NOT denied: ~/.claude — this spawn's own auth, breaks claude CLI if denied
|
||||
];
|
||||
|
||||
// allowWrite: ephemeral spawn workspace only. mkdirSync at bootstrap.
|
||||
// getDefaultWritePaths() adds /dev/stdout, /dev/null etc. internally.
|
||||
try {
|
||||
mkdirSync(SPAWN_BASE_DIR, { recursive: true });
|
||||
} catch (e) {
|
||||
// Non-fatal: if this dir can't be created, wrapSpawn will fail per-request.
|
||||
console.warn(`[sandbox/manager] Warning: could not create ${SPAWN_BASE_DIR}: ${e?.message}`);
|
||||
}
|
||||
|
||||
const config = {
|
||||
network: {
|
||||
allowedDomains,
|
||||
deniedDomains: [],
|
||||
},
|
||||
filesystem: {
|
||||
denyRead,
|
||||
allowWrite: [SPAWN_BASE_DIR, '/tmp'],
|
||||
denyWrite: [],
|
||||
},
|
||||
};
|
||||
|
||||
// Step 3: Initialize SandboxManager
|
||||
let SandboxManager;
|
||||
// Verify sandbox-runtime import is available (lazy-load check only;
|
||||
// no SandboxManager.initialize() — per ADR 0014 Amendment 1 A1.2.3).
|
||||
try {
|
||||
const mod = await import('@anthropic-ai/sandbox-runtime');
|
||||
SandboxManager = mod.SandboxManager;
|
||||
_SandboxManager = mod.SandboxManager;
|
||||
} catch (e) {
|
||||
_initialized = true;
|
||||
_active = false;
|
||||
_initConfig = { failReason: `sandbox-runtime import failed: ${e?.message ?? e}` };
|
||||
return { active: false, reason: _initConfig.failReason };
|
||||
_failReason = `sandbox-runtime import failed: ${e?.message ?? e}`;
|
||||
return { active: false, reason: _failReason };
|
||||
}
|
||||
|
||||
try {
|
||||
// ADR 0014 § Pitfalls #5: initialize() generates MITM CA cert (~100-500ms).
|
||||
// Must happen at boot, not per-request.
|
||||
await SandboxManager.initialize(config);
|
||||
_initialized = true;
|
||||
_active = true;
|
||||
_initConfig = { config, SandboxManager };
|
||||
return { active: true, summary: _buildSummary() };
|
||||
} catch (e) {
|
||||
_initialized = true;
|
||||
_active = false;
|
||||
const reason = `SandboxManager.initialize failed: ${e?.message ?? e}`;
|
||||
_initConfig = { failReason: reason };
|
||||
// Log but DO NOT throw — server still starts in unsandboxed mode.
|
||||
// PR-D will add hard-fail mode via config flag.
|
||||
console.warn(`[sandbox/manager] WARNING: ${reason} — provider spawns will run UNSANDBOXED`);
|
||||
return { active: false, reason };
|
||||
}
|
||||
_initialized = true;
|
||||
_active = true;
|
||||
return { active: true, summary: _buildSummary() };
|
||||
}
|
||||
|
||||
/** @internal — returns summary string for logging */
|
||||
/** @internal */
|
||||
function _buildSummary() {
|
||||
const cfg = _initConfig?.config;
|
||||
if (!cfg) return 'active (no config)';
|
||||
const domains = (cfg.network?.allowedDomains ?? []).join(', ');
|
||||
return `network allowlist=[${domains}], denyRead=[${(cfg.filesystem?.denyRead ?? []).length} paths], allowWrite=[${SPAWN_BASE_DIR}, /tmp]`;
|
||||
return `Layer 3 available (sandbox-runtime loaded, OS deps present); per-spawn wrapWithSandbox enabled`;
|
||||
}
|
||||
|
||||
// ── isSandboxActive ───────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Synchronous query of bootstrap state.
|
||||
* Returns true only if bootstrapSandbox() completed successfully.
|
||||
* Used by provider plugins to decide spawn path.
|
||||
* Synchronous query: is Layer 3 (per-call sandbox-runtime wrap) operational?
|
||||
* Returns true only if bootstrapSandbox() completed successfully AND
|
||||
* OLP_SANDBOX_DISABLED is not set.
|
||||
*
|
||||
* @returns {boolean}
|
||||
*/
|
||||
@@ -293,117 +180,275 @@ export function isSandboxActive() {
|
||||
return _active;
|
||||
}
|
||||
|
||||
// ── wrapSpawn ─────────────────────────────────────────────────────────────
|
||||
// ── prepareIsolatedEnvironment ────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Wrap a spawn command + args for sandbox execution.
|
||||
* Compose per-spawn isolation primitives (Layers 1+2+3) for a single request.
|
||||
*
|
||||
* Returns { bin, args, env, cwd, sandboxed: boolean }.
|
||||
* - If sandbox inactive: returns inputs unchanged with sandboxed:false.
|
||||
* - If sandbox active: returns the wrapped shell string as
|
||||
* { bin: '/bin/sh', args: ['-c', wrappedShellString], env, cwd, sandboxed:true }.
|
||||
*
|
||||
* The wrapped command is a shell string from SandboxManager.wrapWithSandbox().
|
||||
* It must be spawned with shell:true OR by invoking /bin/sh -c <string> directly
|
||||
* (the latter is what we do here — avoids relying on the shell that Node picks).
|
||||
*
|
||||
* Per-spawn ephemeral cwd uses a UUID to prevent cross-request contamination.
|
||||
* The caller is responsible for cleanup (or trusts tmpfs lifetime).
|
||||
*
|
||||
* ADR 0014 § PR-B: env vars passed through unchanged so CLAUDE_CODE_OAUTH_TOKEN
|
||||
* (if operator set at OLP boot time) still works inside the sandbox.
|
||||
* Reads provider.ISOLATION per ADR 0002 Amendment 9. If ISOLATION is absent,
|
||||
* returns the legacy unsandboxed shape (identity env, identity hooks, no cleanup).
|
||||
*
|
||||
* @param {object} params
|
||||
* @param {string} params.bin — original binary (e.g. 'claude')
|
||||
* @param {string[]} params.args — original args
|
||||
* @param {object} params.env — spawn environment (from buildSpawnEnv())
|
||||
* @param {string} [params.cwd] — original cwd (ignored; replaced by ephemeral dir)
|
||||
* @param {string[]} [params.allowedDomains] — per-spawn domain override (passed as customConfig)
|
||||
* @returns {Promise<{ bin: string, args: string[], env: object, cwd: string, sandboxed: boolean }>}
|
||||
* @param {object} params.provider — provider plugin object (may have .ISOLATION)
|
||||
* @param {string} params.keyId — OLP key identity driving this request
|
||||
* @param {string} params.reqId — per-request UUID
|
||||
* @returns {Promise<{
|
||||
* ephemeralRoot: string|null,
|
||||
* envOverrides: Record<string, string>,
|
||||
* hardenedArgs: (args: string[]) => string[],
|
||||
* wrapForLayer3: (command: string) => Promise<string>,
|
||||
* cleanup: () => Promise<void>,
|
||||
* }>}
|
||||
*/
|
||||
export async function wrapSpawn({ bin, args, env, cwd: _cwd, allowedDomains }) {
|
||||
// Transparent pass-through when sandbox inactive
|
||||
if (!_active || !_initConfig?.SandboxManager) {
|
||||
return {
|
||||
bin,
|
||||
args: args ?? [],
|
||||
env: env ?? {},
|
||||
cwd: _cwd,
|
||||
sandboxed: false,
|
||||
};
|
||||
export async function prepareIsolatedEnvironment({ provider, keyId, reqId }) {
|
||||
const isolation = provider?.ISOLATION;
|
||||
|
||||
// ── Legacy unsandboxed path (no ISOLATION declared) ──────────────────────
|
||||
if (!isolation) {
|
||||
if (provider?.name) {
|
||||
console.warn(
|
||||
`[sandbox/manager] [WARN] provider "${provider.name}" does not declare ISOLATION; ` +
|
||||
`spawns will run under legacy unsandboxed shape. Recommended in multi-tenant ` +
|
||||
`deployments: declare ISOLATION per ADR 0002 Amendment 9.`,
|
||||
);
|
||||
}
|
||||
return _legacyShape();
|
||||
}
|
||||
|
||||
const SandboxManager = _initConfig.SandboxManager;
|
||||
// ── Layer 1: Create per-spawn ephemeral home ──────────────────────────────
|
||||
// /tmp/olp-spawn/<keyId>/<reqId>/home
|
||||
// keyId is sanitized to filesystem-safe characters (alphanumeric + hyphens).
|
||||
const safeKeyId = String(keyId ?? 'anon').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
|
||||
const safeReqId = String(reqId ?? 'req').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
|
||||
const ephemeralRoot = join(SPAWN_BASE_DIR, safeKeyId, safeReqId, 'home');
|
||||
|
||||
// Build the shell command string from bin + args.
|
||||
// Each arg is shell-quoted to handle spaces and special characters.
|
||||
// Authority: spike-anthropic.mjs line 29-31 — same quoting pattern.
|
||||
const quotedArgs = (args ?? []).map(a =>
|
||||
/[\s"'`$\\;&|<>()\[\]{}!#~*?]/.test(a)
|
||||
? `"${a.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`')}"`
|
||||
: a
|
||||
);
|
||||
const commandString = [bin, ...quotedArgs].join(' ');
|
||||
|
||||
// Per-spawn ephemeral cwd (UUID) — prevents cross-request contamination.
|
||||
// ADR 0014 § PR-B: unique per request.
|
||||
const reqId = createHash('sha256').update(`${Date.now()}-${Math.random()}`).digest('hex').slice(0, 16);
|
||||
const spawnCwd = join(SPAWN_BASE_DIR, reqId);
|
||||
try {
|
||||
mkdirSync(spawnCwd, { recursive: true });
|
||||
mkdirSync(ephemeralRoot, { recursive: true });
|
||||
} catch (e) {
|
||||
throw new SandboxWrapError(`Failed to create ephemeral spawn dir ${spawnCwd}: ${e?.message ?? e}`);
|
||||
throw new Error(
|
||||
`[sandbox/manager] Failed to create ephemeral root ${ephemeralRoot}: ${e?.message ?? e}`,
|
||||
);
|
||||
}
|
||||
|
||||
// Per-spawn customConfig: allow caller to override domains (e.g. different provider).
|
||||
// Default: use the config-at-boot allowedDomains.
|
||||
let customConfig;
|
||||
if (allowedDomains && allowedDomains.length > 0) {
|
||||
customConfig = {
|
||||
// ── Layer 1 cont.: mkdir requiredHomePaths ────────────────────────────────
|
||||
const requiredPaths = isolation.requiredHomePaths ?? [];
|
||||
for (const relPath of requiredPaths) {
|
||||
if (typeof relPath !== 'string' || relPath.startsWith('..') || relPath.startsWith('/')) {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.requiredHomePaths contains ` +
|
||||
`invalid entry "${relPath}" — must be a relative path with no leading .. or /`,
|
||||
);
|
||||
}
|
||||
const absPath = join(ephemeralRoot, relPath);
|
||||
mkdirSync(absPath, { recursive: true });
|
||||
}
|
||||
|
||||
// ── Layer 2: Symlink credentialMounts ─────────────────────────────────────
|
||||
const mounts = isolation.credentialMounts ?? [];
|
||||
for (const mount of mounts) {
|
||||
if (!Array.isArray(mount) || mount.length !== 2) {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.credentialMounts entry ` +
|
||||
`is not a 2-tuple: ${JSON.stringify(mount)}`,
|
||||
);
|
||||
}
|
||||
const [srcAbsPath, dstRel] = mount;
|
||||
|
||||
// Validate src
|
||||
if (typeof srcAbsPath !== 'string' || !srcAbsPath.startsWith('/')) {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.credentialMounts src ` +
|
||||
`"${srcAbsPath}" must be an absolute path (call os.homedir() in the plugin)`,
|
||||
);
|
||||
}
|
||||
// Validate dst
|
||||
if (typeof dstRel !== 'string' || dstRel.startsWith('..') || dstRel.startsWith('/')) {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.credentialMounts dst ` +
|
||||
`"${dstRel}" must be a relative path with no leading .. or /`,
|
||||
);
|
||||
}
|
||||
|
||||
if (!existsSync(srcAbsPath)) {
|
||||
console.warn(
|
||||
`[sandbox/manager] [WARN] provider "${provider.name}" credentialMount src ` +
|
||||
`"${srcAbsPath}" does not exist — spawn may fail auth`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
const dstAbs = join(ephemeralRoot, dstRel);
|
||||
// Ensure parent dir exists
|
||||
mkdirSync(dirname(dstAbs), { recursive: true });
|
||||
|
||||
// Create symlink (skip if already exists — idempotent)
|
||||
if (!existsSync(dstAbs)) {
|
||||
try {
|
||||
symlinkSync(srcAbsPath, dstAbs);
|
||||
} catch (e) {
|
||||
throw new Error(
|
||||
`[sandbox/manager] Failed to symlink ${srcAbsPath} → ${dstAbs}: ${e?.message ?? e}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── Compose envOverrides (Layer 1 output) ────────────────────────────────
|
||||
let envOverrides = {};
|
||||
if (typeof isolation.ephemeralEnvOverrides === 'function') {
|
||||
const raw = isolation.ephemeralEnvOverrides({ ephemeralRoot, keyId, reqId });
|
||||
if (raw === null || typeof raw !== 'object') {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.ephemeralEnvOverrides ` +
|
||||
`must return a plain object; got ${typeof raw}`,
|
||||
);
|
||||
}
|
||||
// Validate all values are strings
|
||||
for (const [k, v] of Object.entries(raw)) {
|
||||
if (typeof v !== 'string') {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.ephemeralEnvOverrides ` +
|
||||
`returned non-string value for key "${k}": ${typeof v}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
envOverrides = raw;
|
||||
}
|
||||
|
||||
// ── Compose hardenedArgs (Layer 4 hook) ──────────────────────────────────
|
||||
const hardenedArgs = typeof isolation.toolHardeningArgs === 'function'
|
||||
? (args) => {
|
||||
const copy = [...args];
|
||||
const result = isolation.toolHardeningArgs(copy);
|
||||
if (!Array.isArray(result)) {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.toolHardeningArgs ` +
|
||||
`must return an array; got ${typeof result}`,
|
||||
);
|
||||
}
|
||||
for (const arg of result) {
|
||||
if (typeof arg !== 'string') {
|
||||
throw new Error(
|
||||
`[sandbox/manager] provider "${provider.name}" ISOLATION.toolHardeningArgs ` +
|
||||
`returned non-string element in args array: ${typeof arg}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
: (args) => args; // identity — provider encodes hardening in its own spawn()
|
||||
|
||||
// ── Compose wrapForLayer3 ─────────────────────────────────────────────────
|
||||
// Layer 3: per-call sandbox-runtime wrap.
|
||||
// Skipped when:
|
||||
// (a) hasInnerSandbox === true (codex — outer wrap would conflict with inner bwrap)
|
||||
// (b) sandbox is not active (!_active — deps missing or OLP_SANDBOX_DISABLED=1)
|
||||
// When active + no inner sandbox: calls SandboxManager.wrapWithSandbox() per-spawn
|
||||
// with a per-spawn customConfig scoped to the ephemeralRoot.
|
||||
const hasInnerSandbox = isolation.hasInnerSandbox === true;
|
||||
const layer3Active = _active && !hasInnerSandbox;
|
||||
|
||||
let wrapForLayer3;
|
||||
if (layer3Active && _SandboxManager) {
|
||||
const operatorHome = homedir();
|
||||
// Per-spawn customConfig: deny reads on real operator home; allow the
|
||||
// ephemeral home and /tmp. Cross-tenant deny list will be tightened in a
|
||||
// follow-up task once the base Layer 3 integration is validated (Task #9).
|
||||
// ADR 0002 Amendment 9 does NOT declare an allowedDomains field on the
|
||||
// ISOLATION contract. Network policy at Layer 3 is therefore the
|
||||
// orchestrator's responsibility, not the provider's. v1 defaults to empty
|
||||
// allowlist (kernel-level deny-all on outbound to non-trusted domains
|
||||
// would be added here in a follow-up ADR amendment once the contract
|
||||
// surface for "trusted-domains per provider" is ratified). For now: open
|
||||
// network (legacy behaviour, matches pre-Solution-1 spawn shape).
|
||||
const customConfig = {
|
||||
network: {
|
||||
allowedDomains,
|
||||
allowedDomains: [],
|
||||
deniedDomains: [],
|
||||
},
|
||||
filesystem: {
|
||||
denyRead: [
|
||||
operatorHome,
|
||||
join(operatorHome, '.ssh'),
|
||||
join(operatorHome, '.gnupg'),
|
||||
join(operatorHome, '.olp'),
|
||||
],
|
||||
allowRead: [ephemeralRoot],
|
||||
allowWrite: [ephemeralRoot, '/tmp'],
|
||||
denyWrite: [],
|
||||
},
|
||||
};
|
||||
|
||||
const SM = _SandboxManager;
|
||||
wrapForLayer3 = async (commandString) => {
|
||||
try {
|
||||
return await SM.wrapWithSandbox(commandString, undefined, customConfig);
|
||||
} catch (e) {
|
||||
throw new Error(
|
||||
`[sandbox/manager] SandboxManager.wrapWithSandbox failed: ${e?.message ?? e}`,
|
||||
);
|
||||
}
|
||||
};
|
||||
} else {
|
||||
// Identity — no Layer 3 wrap (either hasInnerSandbox=true or sandbox inactive)
|
||||
wrapForLayer3 = async (commandString) => commandString;
|
||||
}
|
||||
|
||||
let wrappedCommand;
|
||||
try {
|
||||
wrappedCommand = await SandboxManager.wrapWithSandbox(commandString, undefined, customConfig);
|
||||
} catch (e) {
|
||||
throw new SandboxWrapError(`SandboxManager.wrapWithSandbox failed: ${e?.message ?? e}`);
|
||||
}
|
||||
// ── Cleanup (called by server after spawn completes) ─────────────────────
|
||||
const cleanup = async () => {
|
||||
// Walk up to /tmp/olp-spawn/<safeKeyId>/<safeReqId> and remove.
|
||||
// Best-effort: log + swallow errors (don't fail the response pipeline).
|
||||
const spawnDir = join(SPAWN_BASE_DIR, safeKeyId, safeReqId);
|
||||
try {
|
||||
await rm(spawnDir, { recursive: true, force: true });
|
||||
} catch (e) {
|
||||
console.warn(
|
||||
`[sandbox/manager] Warning: cleanup of ${spawnDir} failed: ${e?.message ?? e}`,
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
// Invoke via /bin/sh -c to avoid spawning a second shell layer.
|
||||
// The wrapped command is already a complete shell invocation (bwrap args or
|
||||
// sandbox-exec profile + the original command inside).
|
||||
return {
|
||||
bin: '/bin/sh',
|
||||
args: ['-c', wrappedCommand],
|
||||
env: env ?? {},
|
||||
cwd: spawnCwd,
|
||||
sandboxed: true,
|
||||
ephemeralRoot,
|
||||
envOverrides,
|
||||
hardenedArgs,
|
||||
wrapForLayer3,
|
||||
cleanup,
|
||||
};
|
||||
}
|
||||
|
||||
// ── Legacy unsandboxed shape ──────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Returns the identity shape used for providers without ISOLATION declared.
|
||||
* Per ADR 0002 Amendment 9 § Backward compatibility.
|
||||
*/
|
||||
function _legacyShape() {
|
||||
return {
|
||||
ephemeralRoot: null,
|
||||
envOverrides: {},
|
||||
hardenedArgs: (args) => args,
|
||||
wrapForLayer3: async (cmd) => cmd,
|
||||
cleanup: async () => { /* nothing to clean up — no ephemeral root was created */ },
|
||||
};
|
||||
}
|
||||
|
||||
// ── Test seam ─────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Reset internal state so test suite can simulate fresh process.
|
||||
* Also calls SandboxManager.reset() if it was initialized (to clear singleton).
|
||||
* Reset module-level state so the test suite can simulate a fresh process.
|
||||
* Per ADR 0014 § Pitfalls #4: only safe in sequential test contexts with no
|
||||
* in-flight spawns.
|
||||
*
|
||||
* ADR 0014 § Pitfalls #4: must only be called when no in-flight wrapSpawn calls
|
||||
* are active. Safe in sequential test contexts.
|
||||
* Note: Under Amendment 1, there is no SandboxManager singleton to reset
|
||||
* (no SandboxManager.reset() call) — the per-call pattern means the library's
|
||||
* internal state is transient per wrapWithSandbox() invocation.
|
||||
*
|
||||
* @returns {Promise<void>}
|
||||
*/
|
||||
export async function __resetSandboxManagerForTests() {
|
||||
if (_active && _initConfig?.SandboxManager) {
|
||||
try {
|
||||
await _initConfig.SandboxManager.reset();
|
||||
} catch { /* ignore — test teardown, best-effort */ }
|
||||
}
|
||||
_initialized = false;
|
||||
_active = false;
|
||||
_initConfig = null;
|
||||
_failReason = null;
|
||||
_SandboxManager = null;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user