Function: srtBinarySandbox()
function srtBinarySandbox(
enforcer: SandboxPolicyEnforcer,
opts?: SrtBinarySandboxOptions,
): BinarySandbox;Defined in: src/batteries/sandbox/node/srt_enforcer.ts:864
Expose an existing SandboxPolicyEnforcer as a BinarySandbox for the media pipeline — the bridge between the sandbox battery and sandboxedExecutor.
Parameters
| Parameter | Type | Description |
|---|---|---|
enforcer | SandboxPolicyEnforcer | The live enforcer whose session, shell, policy mapping and env allow-list this wrapper reuses. Construct it with srtEnforcer and dispose it when the executor goes away. |
opts | SrtBinarySandboxOptions | The per-invocation policy and the DEFAULT working directory (the invocation's own cwd wins); the same directory is used for the SRT profile and for the returned invocation. |
Returns
A BinarySandbox whose wrap returns the sandboxed argv the inner executor runs.
Remarks
DELIBERATELY DERIVED FROM srtEnforcer, NOT A SECOND SRT ADAPTER. It holds no state of its own: the wrapper closes over the enforcer's single live SandboxManager session, its validated binShell, its mapPolicy translation, its network-divergence admission gate and its host-env allow-list. One process-global session, one translation point, one admission policy — the two execution routes (run() for streaming tools, this for settled media invocations) share the internal admission+wrapping step so they cannot drift.
The wrapped invocation is what the inner executor spawns: cmd is the wrapper binary (bwrap/sandbox-exec), args are the rest of the generated argv, and the caller's own argv is already inside that generated command. The adapter therefore must not re-append the original args.
THE ENVIRONMENT SPLITS IN TWO, AND ONLY ONE HALF INHERITS FROM THE HOST. The host-env allow-list is what decides which HOST variables a child may inherit from process.env; it is the adapter's decision, taken at construction. The caller's env is its own EXPLICIT values, applied last, and may add names or override allow-listed ones. The wrap composes the two into { ...hostEnv, ...(invocation.env ?? {}) } and sets extendEnv: false, so the executor hands the child EXACTLY those variables. This is load-bearing: execa's default extendEnv: true would merge the full process.env back in, which would silently hand the model every host secret whenever it ran env — the exact leak the allow-list exists to prevent. So the invariant this adapter enforces is the contract's: env may add or override, but NOTHING from the host beyond the allow-list reaches the child, and env is never a reason to inherit more from the host.
REFUSES rather than degrades in the same places run() does: the network gate throws E_SANDBOX_NETWORK_GRANT_UNSUPPORTED before anything runs, and an unavailable platform throws E_SANDBOX_UNSUPPORTED_ENV (surfaced by srtEnforcer's construction). After the enforcer is disposed the process-global session is gone, so a wrap still generates argv but the child is refused by the OS — the same honest failure mode run() presents. Prefer disposing the executor alongside the enforcer.
POSIX-only, like the session it wraps: there is no process.kill(-pid, signal) equivalent on Windows, which is why srtEnforcer never constructs there.