@namzu/sdk 30.2.0 → 31.1.0

package/src/sandbox/provider/local.ts

@@ -1,5 +1,5 @@
-import { execSync, spawn } from 'node:child_process'
-import { realpathSync } from 'node:fs'
+import { spawn, spawnSync } from 'node:child_process'
+import { constants, accessSync, existsSync, realpathSync } from 'node:fs'
 import {
 	readFile as fsReadFile,
 	writeFile as fsWriteFile,
@@ -29,6 +29,7 @@ import type { SandboxId } from '../../types/ids/index.js'
 import type {
 	Sandbox,
 	SandboxCreateConfig,
+	SandboxDestroyOptions,
 	SandboxEnvironment,
 	SandboxExecOptions,
 	SandboxExecResult,
@@ -39,14 +40,13 @@ import type {
 } from '../../types/sandbox/index.js'
 import { generateSandboxId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
-import { assertIsolation, describeIsolation } from '../isolation.js'
 import {
-	type OpenTerminalOptions,
-	type PtyLoader,
-	type TerminalSession,
-	loadPty,
-	openTerminalWith,
-} from '../terminal.js'
+	WINDOWS_CORE_ENV_KEYS,
+	applyEnvironmentOverrides,
+	pickEnvironmentEntries,
+} from '../../utils/process-environment.js'
+import { assertIsolation, describeIsolation } from '../isolation.js'
+import type { PtyLoader } from '../terminal.js'
 
 // ---------------------------------------------------------------------------
 // Path safety
@@ -71,6 +71,71 @@ function assertInsideSandbox(sandboxRoot: string, targetPath: string): string {
  */
 const LINUX_UNSHARE_FLAGS = ['--mount', '--pid', '--fork', '--map-root-user', '--net']
 
+const SPAWN_PROBE_SENTINEL = 'namzu-sandbox-spawn-probe'
+
+interface SpawnProbeObservation {
+	readonly error?: unknown
+	readonly status: number | null
+	readonly signal: NodeJS.Signals | null
+	readonly stdout: string | null
+}
+
+/**
+ * A wrapper is usable only when the same direct-spawn shape as a real command
+ * can execute and carry its output back through a pipe.
+ *
+ * Checking only the exit status is insufficient: a host policy can let a
+ * shell launch a namespace helper while refusing or partially virtualising a
+ * direct `spawn()` of that helper. In that state the old shell-string probe
+ * selected the tier, but production commands returned exit zero with empty
+ * output. Treat a spawn error, signal, or damaged pipe as an unavailable tier.
+ */
+export function acceptsSandboxSpawnProbe(observation: SpawnProbeObservation): boolean {
+	return (
+		observation.error === undefined &&
+		observation.status === 0 &&
+		observation.signal === null &&
+		observation.stdout === SPAWN_PROBE_SENTINEL
+	)
+}
+
+function probeSandboxSpawn(command: string, wrapperArgs: readonly string[]): boolean {
+	const observation = spawnSync(
+		command,
+		[
+			...wrapperArgs,
+			'--',
+			process.execPath,
+			'-e',
+			`process.stdout.write(${JSON.stringify(SPAWN_PROBE_SENTINEL)})`,
+		],
+		{
+			encoding: 'utf8',
+			timeout: 5_000,
+		},
+	)
+	return acceptsSandboxSpawnProbe(observation)
+}
+
+const TRUSTED_WRAPPER_CANDIDATES = {
+	bwrap: ['/usr/bin/bwrap', '/bin/bwrap', '/usr/sbin/bwrap'],
+	unshare: ['/usr/bin/unshare', '/bin/unshare', '/usr/sbin/unshare'],
+	'sandbox-exec': ['/usr/bin/sandbox-exec'],
+} as const
+
+function resolveTrustedWrapper(name: keyof typeof TRUSTED_WRAPPER_CANDIDATES): string | undefined {
+	for (const candidate of TRUSTED_WRAPPER_CANDIDATES[name]) {
+		try {
+			accessSync(candidate, constants.X_OK)
+			return realpathSync(candidate)
+		} catch {
+			// Try the next fixed system location. Caller-controlled PATH is not
+			// part of wrapper discovery because it is also configurable per run.
+		}
+	}
+	return undefined
+}
+
 /**
  * One output stream, accumulated under a byte cap that it reports hitting.
  *
@@ -105,6 +170,8 @@ export class CappedStream {
 
 export interface LimitedSpawnRequest {
 	readonly environment: SandboxEnvironment
+	/** Canonical outer wrapper selected and probed by the provider. */
+	readonly wrapperCommand?: string
 	readonly command: string
 	readonly args: readonly string[]
 	readonly rootDir: string
@@ -112,6 +179,15 @@ export interface LimitedSpawnRequest {
 	readonly maxProcesses?: number
 }
 
+function requiredWrapper(request: LimitedSpawnRequest): string {
+	if (request.wrapperCommand === undefined || !isAbsolute(request.wrapperCommand)) {
+		throw new Error(
+			`Sandbox environment ${request.environment} requires the absolute wrapper path that was probed`,
+		)
+	}
+	return request.wrapperCommand
+}
+
 /** Single-quote for a shell, escaping any quote already inside. */
 function shellQuote(value: string): string {
 	return `'${value.replace(/'/g, "'\\''")}'`
@@ -153,15 +229,21 @@ export function buildLimitedSpawn(request: LimitedSpawnRequest): {
 			: [command, ...args]
 
 	switch (environment) {
+		case 'linux-bwrap':
+			return {
+				spawnCommand: requiredWrapper(request),
+				spawnArgs: [...buildBwrapArgs(rootDir), '--', ...inner],
+			}
+
 		case 'linux-namespace':
 			return {
-				spawnCommand: 'unshare',
+				spawnCommand: requiredWrapper(request),
 				spawnArgs: [...LINUX_UNSHARE_FLAGS, '--', ...inner],
 			}
 
 		case 'macos-seatbelt':
 			return {
-				spawnCommand: 'sandbox-exec',
+				spawnCommand: requiredWrapper(request),
 				spawnArgs: ['-p', buildSeatbeltProfile(rootDir), '--', ...inner],
 			}
 
@@ -177,35 +259,43 @@ export function buildLimitedSpawn(request: LimitedSpawnRequest): {
 	}
 }
 
-function detectEnvironment(): SandboxEnvironment {
+type DetectedEnvironment =
+	| { readonly environment: 'basic' }
+	| {
+			readonly environment: Exclude<SandboxEnvironment, 'basic'>
+			readonly wrapperCommand: string
+	  }
+
+function detectEnvironment(): DetectedEnvironment {
 	const { platform } = process
 
 	if (platform === 'linux') {
-		try {
-			// Probe the real flags, not just the binary. `unshare --version`
-			// succeeds on a host where unprivileged user namespaces are
-			// disabled by sysctl and every actual spawn would fail — the tier
-			// would be claimed and never delivered. The other platform's probe
-			// already runs its sandbox for real; this one now does too.
-			execSync(`unshare ${LINUX_UNSHARE_FLAGS.join(' ')} -- /bin/true`, {
-				stdio: 'ignore',
-			})
-			return 'linux-namespace'
-		} catch {
-			// unshare missing, or the host refuses the namespaces we need
+		// Probe the direct child-process boundary used in production, including
+		// its stdout pipe. A shell-string probe is a different capability on
+		// hosts that mediate namespace helpers and can claim a tier production
+		// cannot actually drive.
+		const bwrap = resolveTrustedWrapper('bwrap')
+		if (bwrap !== undefined && probeSandboxSpawn(bwrap, buildBwrapArgs(tmpdir()))) {
+			return { environment: 'linux-bwrap', wrapperCommand: bwrap }
+		}
+
+		const unshare = resolveTrustedWrapper('unshare')
+		if (unshare !== undefined && probeSandboxSpawn(unshare, LINUX_UNSHARE_FLAGS)) {
+			return { environment: 'linux-namespace', wrapperCommand: unshare }
 		}
 	}
 
 	if (platform === 'darwin') {
-		try {
-			execSync('sandbox-exec -n no-network /usr/bin/true', { stdio: 'ignore' })
-			return 'macos-seatbelt'
-		} catch {
-			// sandbox-exec not available
+		const seatbelt = resolveTrustedWrapper('sandbox-exec')
+		if (
+			seatbelt !== undefined &&
+			probeSandboxSpawn(seatbelt, ['-p', buildSeatbeltProfile(tmpdir())])
+		) {
+			return { environment: 'macos-seatbelt', wrapperCommand: seatbelt }
 		}
 	}
 
-	return 'basic'
+	return { environment: 'basic' }
 }
 
 // ---------------------------------------------------------------------------
@@ -233,6 +323,103 @@ function canonicalizePath(p: string): string {
  *
  * Key principle: (deny default) + explicit allows. Network always denied.
  */
+/**
+ * A mount table containing the sandbox and the system paths a binary needs,
+ * and nothing else.
+ *
+ * The difference from the namespace tier is the whole point: that one unshares
+ * a mount table and keeps the host's contents in it, so the child sees
+ * everything and this file reports `filesystem: false` for it. Here each path
+ * is bound in deliberately, so a path nobody listed is not unreadable — it is
+ * absent. `ls /home` fails with ENOENT rather than EACCES, which is the
+ * behaviour a caller relying on `filesystem` isolation is entitled to.
+ *
+ * `--unshare-all` covers the network and process controls in the same call, so
+ * all three rows of this tier's isolation report come from one spawn rather
+ * than from three mechanisms that could drift apart.
+ *
+ * The system paths are bound READ-ONLY and only when present: a distribution
+ * with a merged `/usr` has no real `/lib`, and binding a path that does not
+ * exist is a hard failure rather than a no-op. `/proc` and `/dev` get their
+ * own fresh instances instead of a bind, so the child cannot read the host's
+ * process table through them — a bound `/proc` would hand back the process
+ * isolation the same flag just removed.
+ */
+export function buildBwrapArgs(sandboxRoot: string): string[] {
+	const root = canonicalizePath(sandboxRoot)
+
+	const args = [
+		'--unshare-all',
+		// The child dies with the parent rather than outliving a killed run.
+		// Without it an escaped grandchild keeps the mount namespace alive and
+		// the sandbox's temporary root cannot be removed.
+		'--die-with-parent',
+		'--new-session',
+	]
+
+	for (const path of BWRAP_SYSTEM_PATHS) {
+		if (existsSync(path)) args.push('--ro-bind', path, path)
+	}
+
+	// The runtime this process is running under, when it lives outside those.
+	//
+	// Found by the tier breaking four existing tests the moment it worked: they
+	// spawn `node` inside the sandbox, and a Node installed under a home
+	// directory — a tarball, a version manager, anything but the distribution's
+	// package — is simply not there once the host filesystem is gone. The
+	// failure reads as `execvp: No such file or directory`, which sounds like a
+	// broken test rather than a sandbox doing its job.
+	//
+	// The PREFIX rather than the `bin` directory: `bin` alone is enough to run
+	// `node`, but `npm` and `npx` resolve their own code through `../lib`, and a
+	// model that runs one of those is not doing anything unusual.
+	//
+	// Read-only, and skipped when a system path already covers it, so a
+	// distribution-packaged runtime adds no second bind.
+	const interpreterPrefix = dirname(dirname(canonicalizePath(process.execPath)))
+	const alreadyCovered = BWRAP_SYSTEM_PATHS.some(
+		(path) => interpreterPrefix === path || interpreterPrefix.startsWith(`${path}/`),
+	)
+	if (!alreadyCovered && existsSync(interpreterPrefix)) {
+		args.push('--ro-bind', interpreterPrefix, interpreterPrefix)
+	}
+
+	args.push(
+		'--proc',
+		'/proc',
+		'--dev',
+		'/dev',
+		// A private /tmp, because the sandbox root is where writes belong and a
+		// shared /tmp is a channel between runs.
+		'--tmpfs',
+		'/tmp',
+		'--bind',
+		root,
+		root,
+		'--chdir',
+		root,
+	)
+
+	return args
+}
+
+/**
+ * Read-only host paths a spawned binary needs to run at all.
+ *
+ * Bound rather than assumed: `/etc` carries the resolver and user database a
+ * shell reads on startup, and omitting it produces failures that look like the
+ * command is broken rather than like the sandbox is doing its job.
+ */
+const BWRAP_SYSTEM_PATHS: readonly string[] = [
+	'/usr',
+	'/bin',
+	'/sbin',
+	'/lib',
+	'/lib64',
+	'/etc',
+	'/opt',
+]
+
 function buildSeatbeltProfile(sandboxRoot: string): string {
 	const root = canonicalizePath(sandboxRoot)
 
@@ -323,21 +510,14 @@ function buildSafeEnv(
 	configEnv?: Record<string, string>,
 	optsEnv?: Record<string, string>,
 ): Record<string, string> {
-	const env: Record<string, string> = {}
+	const allowed =
+		process.platform === 'win32'
+			? [...SANDBOX_SAFE_ENV_KEYS, ...WINDOWS_CORE_ENV_KEYS]
+			: SANDBOX_SAFE_ENV_KEYS
+	const env = pickEnvironmentEntries(allowed)
 
-	for (const key of SANDBOX_SAFE_ENV_KEYS) {
-		const value = process.env[key]
-		if (value !== undefined) {
-			env[key] = value
-		}
-	}
-
-	if (configEnv) {
-		Object.assign(env, configEnv)
-	}
-	if (optsEnv) {
-		Object.assign(env, optsEnv)
-	}
+	applyEnvironmentOverrides(env, configEnv)
+	applyEnvironmentOverrides(env, optsEnv)
 
 	return env
 }
@@ -359,22 +539,14 @@ class LocalSandbox implements Sandbox {
 		return this._status
 	}
 
-	/**
-	 * How the pty binding is loaded. Injectable so a test needs no native
-	 * build — the refusal path and the session wiring are both worth
-	 * covering, and neither should require compiling C++ on CI.
-	 */
-	private readonly ptyLoader: PtyLoader | undefined
-
 	constructor(
 		id: SandboxId,
 		rootDir: string,
 		environment: SandboxEnvironment,
+		private readonly wrapperCommand: string | undefined,
 		config: SandboxCreateConfig,
 		log: Logger,
-		ptyLoader?: PtyLoader,
 	) {
-		this.ptyLoader = ptyLoader
 		this.id = id
 		this.rootDir = rootDir
 		this.environment = environment
@@ -440,33 +612,6 @@ class LocalSandbox implements Sandbox {
 		}
 	}
 
-	/**
-	 * A real pseudo-terminal, or a refusal that says what to install.
-	 *
-	 * Deliberately NOT confined the way `exec` is. `exec` wraps every
-	 * command in this class's isolation tiers (`unshare …`,
-	 * `sandbox-exec …`); a terminal is an interactive session a human is
-	 * driving, and wrapping it would put the tier's own shell between the
-	 * operator's keystrokes and the program. So this runs inside the
-	 * sandbox's ROOT DIRECTORY and nothing more — which is stated here
-	 * because a caller reading "sandbox" would otherwise assume the tier
-	 * applies, and it is exactly the assumption that makes a boundary
-	 * imaginary.
-	 *
-	 * A host that needs the tier runs its interactive program through
-	 * `exec` and accepts that it is not a terminal, or supplies a backend
-	 * whose terminals are confined by construction — a container's `exec`,
-	 * for instance, where the confinement is the container and not a
-	 * wrapper.
-	 */
-	async openTerminal(options: OpenTerminalOptions): Promise<TerminalSession> {
-		if (this._status === 'destroyed') {
-			throw new Error(`Sandbox ${this.id} is destroyed`)
-		}
-		const pty = await loadPty(this.ptyLoader)
-		return openTerminalWith(pty, options, { shell: '/bin/sh', cwd: this.rootDir })
-	}
-
 	async writeFile(path: string, content: string | Buffer): Promise<void> {
 		if (this._status === 'destroyed') {
 			throw new Error(`Sandbox ${this.id} is destroyed`)
@@ -522,7 +667,7 @@ class LocalSandbox implements Sandbox {
 		return entries
 	}
 
-	async destroy(): Promise<void> {
+	async destroy(_options?: SandboxDestroyOptions): Promise<void> {
 		if (this._status === 'destroyed') {
 			return
 		}
@@ -543,6 +688,7 @@ class LocalSandbox implements Sandbox {
 	): { spawnCommand: string; spawnArgs: string[] } {
 		return buildLimitedSpawn({
 			environment: this.environment,
+			...(this.wrapperCommand !== undefined ? { wrapperCommand: this.wrapperCommand } : {}),
 			command,
 			args,
 			rootDir: this.rootDir,
@@ -646,11 +792,13 @@ export interface LocalSandboxProviderOptions {
 	 */
 	readonly requireIsolation?: readonly SandboxIsolationControl[]
 	/**
-	 * How a sandbox loads the pty binding for {@link Sandbox.openTerminal}.
+	 * Legacy test injection for the local backend's former terminal method.
 	 *
-	 * Injectable so a test needs no native build. Absent means the real
-	 * `import`, which is what a host gets — and what refuses, by name, when
-	 * the binding is not installed.
+	 * @deprecated The local backend cannot preserve its selected isolation
+	 * tier or own the complete terminal process tree, so it no longer exposes
+	 * `Sandbox.openTerminal`. Supplying this option now throws. Use the
+	 * host-scoped terminal helpers directly only when unconfined execution is
+	 * intentional, or provide a backend that owns confinement and teardown.
 	 */
 	readonly ptyLoader?: PtyLoader
 }
@@ -661,12 +809,17 @@ export class LocalSandboxProvider implements SandboxProvider {
 	readonly environment: SandboxEnvironment
 
 	private readonly log: Logger
-
-	private readonly ptyLoader: PtyLoader | undefined
+	private readonly wrapperCommand: string | undefined
 
 	constructor(log: Logger, options: LocalSandboxProviderOptions = {}) {
-		this.ptyLoader = options.ptyLoader
-		this.environment = detectEnvironment()
+		if (options.ptyLoader !== undefined) {
+			throw new Error(
+				'LocalSandboxProvider no longer accepts ptyLoader because its terminal could not preserve the selected isolation tier or sandbox teardown ownership. Use the host-scoped terminal helpers only for intentional host execution, or provide a confined terminal backend.',
+			)
+		}
+		const detected = detectEnvironment()
+		this.environment = detected.environment
+		this.wrapperCommand = 'wrapperCommand' in detected ? detected.wrapperCommand : undefined
 		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'sandbox/provider/local' })
 
 		assertIsolation(this.environment, options.requireIsolation ?? [])
@@ -693,17 +846,29 @@ export class LocalSandboxProvider implements SandboxProvider {
 	}
 
 	async create(config?: SandboxCreateConfig): Promise<Sandbox> {
+		config?.signal?.throwIfAborted()
 		const id = generateSandboxId()
 
 		// mkdtemp is in node:fs/promises but requires an async import-style usage.
 		// We use the same pattern: create a unique dir under os.tmpdir().
 		const { mkdtemp } = await import('node:fs/promises')
 		const rawDir = await mkdtemp(join(tmpdir(), SANDBOX_TEMP_DIR_PREFIX))
+		if (config?.signal?.aborted) {
+			await rm(rawDir, { recursive: true, force: true })
+			throw config.signal.reason
+		}
 		// Canonicalize — macOS symlinks like /var → /private/var must be resolved
 		const rootDir = canonicalizePath(rawDir)
 
 		this.log.info('Creating sandbox', { 'namzu.sandbox.id': id, 'namzu.sandbox.root_dir': rootDir })
 
-		return new LocalSandbox(id, rootDir, this.environment, config ?? {}, this.log, this.ptyLoader)
+		return new LocalSandbox(
+			id,
+			rootDir,
+			this.environment,
+			this.wrapperCommand,
+			config ?? {},
+			this.log,
+		)
 	}
 }

package/src/sandbox/terminal.ts

@@ -1,5 +1,5 @@
 /**
- * A real terminal inside the sandbox, or nothing.
+ * A real host pseudo-terminal, or nothing.
  *
  * `exec` runs a command and hands back what it printed. That is the whole
  * shape of it, and a large class of work does not fit: an interactive
@@ -18,6 +18,12 @@
  * why. That is the same rule `Sandbox.setNetworkPolicy` states for itself:
  * a capability accepted and not applied is worse than one never offered,
  * because the caller stops looking.
+ *
+ * Nothing in this module creates a sandbox or owns a complete descendant
+ * process tree. `openTerminalWith` starts exactly the program, arguments and
+ * working directory it is handed through the supplied binding. A sandbox or
+ * durable terminal backend must wrap that argv under its own confinement and
+ * make teardown await every process it owns before using this primitive.
  */
 
 export interface TerminalSize {
@@ -26,7 +32,7 @@ export interface TerminalSize {
 }
 
 export interface OpenTerminalOptions {
-	/** The program to run. Defaults to the sandbox's own shell. */
+	/** The program to run. Defaults to the caller-supplied shell. */
 	readonly command?: string
 	readonly args?: readonly string[]
 	readonly cwd?: string
@@ -57,7 +63,7 @@ export interface TerminalSession {
 	onData(listener: (chunk: string) => void): () => void
 	/** Resolves when the program exits. */
 	readonly exited: Promise<{ exitCode: number; signal?: number }>
-	/** Stop it. */
+	/** Ask the backing binding to stop its top-level terminal process. */
 	kill(signal?: string): void
 }
 
@@ -142,11 +148,13 @@ export async function loadPty(loader?: PtyLoader): Promise<PtyModule> {
 }
 
 /**
- * Open a terminal, given a loaded binding.
+ * Open a host terminal, given a loaded binding.
  *
  * Separated from `loadPty` so the refusal and the session are testable
  * apart: one is about a missing dependency, the other about wiring a
- * process that exists.
+ * process that exists. This helper does not add confinement or descendant
+ * cleanup; those belong to the backend that supplies its argv and owns the
+ * returned session.
  */
 export function openTerminalWith(
 	pty: PtyModule,