Skip to content
3 min read · 581 words

Interface: SandboxPolicyEnforcer ​

Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:6

Policy boundary. run resolves on spawn and exposes live streams plus a later completion promise.

Properties ​

PropertyModifierTypeDescriptionDefined in
adopted?readonlybooleanWhether this adapter adopted an already-enabled process-global sandbox rather than initializing it.src/batteries/sandbox/contracts/policy_enforcer.ts:10

Methods ​

checkDependencies() ​

ts
checkDependencies(): Promise<{
  errors: string[];
  warnings: string[];
}>;

Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:12

Probe external prerequisites. A non-empty errors throws E_SANDBOX_DEPENDENCY_MISSING; warnings are surfaced through observability and are NOT fatal.

Returns ​

Promise<{ errors: string[]; warnings: string[]; }>


diagnosticsFor() ​

ts
diagnosticsFor(correlationId: string): string[];

Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:64

Retrieve diagnostics by correlation id, never by command text.

Parameters ​

ParameterType
correlationIdstring

Returns ​

string[]


dispose() ​

ts
dispose(): Promise<void>;

Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:66

Release what this enforcer OWNS. A no-op when it adopted a foreign sandbox — tearing down a manager we did not initialize would strip ACEs a host app depends on.

Returns ​

Promise<void>


effectivePolicy() ​

ts
effectivePolicy(): DerivedRules | undefined;

Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:62

Return the opaque derived snapshot used for drift validation.

Returns ​

DerivedRules | undefined


isSupported() ​

ts
isSupported(): boolean;

Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:8

Whether this enforcer can enforce on the current platform. false (a browser tab, where SRT does not exist) raises E_SANDBOX_UNSUPPORTED_ENV at construction rather than degrading — a shim that enforces nothing reads as sandboxed.

Returns ​

boolean


run() ​

ts
run(op: {
  argv: string[];
  correlationId: string;
  cwd: string;
  env?: Record<string, string>;
  policy: SandboxPolicy;
  signal?: AbortSignal;
}): Promise<{
  completed: Promise<{
     exitCode: number;
     failed: boolean;
     signalCode?: string;
  }>;
  stderr: ReadableStream<Uint8Array<ArrayBufferLike>>;
  stdout: ReadableStream<Uint8Array<ArrayBufferLike>>;
}>;

Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:22

Spawn under a narrowing policy; a non-zero exit is data, not a rejected promise.

Parameters ​

ParameterTypeDescription
op{ argv: string[]; correlationId: string; cwd: string; env?: Record<string, string>; policy: SandboxPolicy; signal?: AbortSignal; }-
op.argvstring[]-
op.correlationIdstring-
op.cwdstring-
op.env?Record<string, string>The caller's own EXPLICIT environment values, applied LAST. Remarks NOT the host-inheritance control. What a child inherits from the host is the ADAPTER's decision, expressed as an allow-list the adapter owns (the Node/SRT one denies by default and takes that allow-list at construction). This field is the other half of the picture: the values the caller names itself. They may add names, or override inherited ones, and because they are applied last they also win a collision with an allow-listed name. An adapter MUST NOT let env — or anything else — cause host variables BEYOND its allow-list to reach the child. Concretely, it must not merge the rest of process.env back in on top, and it must not treat the presence of env as a trigger to inherit more widely. Leaving these semantics unstated is how the Node adapter came to spread the entire process.env into every child while this field sat unused.
op.policySandboxPolicy-
op.signal?AbortSignalLifecycle cancellation for this child. Implementations must kill the spawned child and settle completed when this signal aborts.

Returns ​

Promise<{ completed: Promise<{ exitCode: number; failed: boolean; signalCode?: string; }>; stderr: ReadableStream<Uint8Array<ArrayBufferLike>>; stdout: ReadableStream<Uint8Array<ArrayBufferLike>>; }>

Remarks ​

When op.signal aborts, an implementation MUST terminate the spawned child (including a child hidden behind a sandbox wrapper) and settle completed; it MUST NOT leave the child running after the lifecycle owner has cancelled the invocation. The returned streams may end as a consequence of termination, but completed remains the authoritative settlement signal.