SandboxedShell class final

Implemented types

• Shell

Constructors

SandboxedShell(Shell _inner, CubeSpec? spec, {FileSystem? fs, String? os, String? homeDir, void onDegrade(String message)?, CubeFsProbe? pathProbe})

Creates a sandbox over inner, enforcing spec's policies; a null spec is passthrough — every command forwards untouched until updateSpec.

Properties

effectiveBackend → CubeBackendMode?

The backend this shell actually executes with: CubeBackendMode.kernel when commands are OS-wrapped, CubeBackendMode.policy when only the Dart policy layers run (a plain policy spec, or a kernel spec allowed to degrade), null in passthrough mode or while a kernel spec is refused (nothing executes at all). Hosts query this to display/audit what actually ran.

no setter

hashCode → int

The hash code for this object.

no setter, inherited

kernelStagingError → String?

The staging failure note from the last kernel staging attempt, or null (set when prepare returns null).

no setter

onDegrade → void Function(String message)?

Called when a backend: kernel spec degrades to policy mode because no enforcing backend exists for the host — only when the spec opted in via allowDegrade.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

clearSpec() → void

Leaves sandbox mode: every command is forwarded untouched.

exec(String command, {ShellExecOptions? options}) → Future<Result<ShellExecResult, ExecutionError>>

Executes a shell command. Must never throw: all failures are encoded in the returned Result.

override

kernelError(String note) → String

The single error shape every kernel failure surfaces — foreground execs, the background startup probe and background-job refusals (kernelStagingError consumers) all render their note through this, so callers and tests match exactly one prefix.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

prepare(String command, {Map<String, String>? env}) → Future<String?>

The command a background job should start for command: unchanged in policy mode, wrapped in the kernel backend in kernel mode (verifying and if necessary restaging the profile first — null when staging failed, see kernelStagingError; the caller must refuse to start the job). env is the caller's per-exec environment — threaded into the clean child env so jobs keep session vars and secrets. The policy check stays with the caller.

startupFailure() → Future<String?>

One-shot capability probe for backend: kernel background jobs: a job started through prepare only reports a wrapper failure inside its job log, so startupFailure runs a wrapped no-op command once per spec first and yields the clean failure note up front (null = the wrapper works). Foreground execs skip this — exec maps the failure from the result directly.

toString() → String

A string representation of this object.

inherited

updateSpec(CubeSpec spec) → void

Swaps the enforced spec live; the next exec uses the new policies. A backend: kernel spec with no enforcing backend for the host refuses (every command denied, nothing runs) unless the spec opts in via allowDegrade, in which case it degrades to policy mode and fires onDegrade.

Operators

operator ==(Object other) → bool

The equality operator.

inherited