Module sandbox 

Sandboxing primitives for shell commands run by flow-adapter-shell.

The module exposes a capability-declarative API: each shell node carries a Capabilities struct (network access, write paths, read paths, env policy). Given a Capabilities plus a cwd, resolve_layer picks the enforcement strategy the host OS supports, and wrap_command returns a tokio::process::Command already configured to run under that strategy.

Layers (in increasing order of enforcement):

• SandboxLayer::Lightweight - always applied. Pins cwd, scrubs env per EnvPolicy. Output cap and timeout are enforced by the calling adapter (they live closer to the spawn loop).
• SandboxLayer::MacosSandboxExec - on macOS only, when Capabilities carries non-empty write/read paths or net == false. Wraps the user command with sandbox-exec -p '<generated SBPL>'. Apple deprecated sandbox-exec but it still works on macOS 15; the comment block at the top of build_macos_sbpl covers the migration path.
• SandboxLayer::LinuxLandlock - on Linux when the kernel exposes landlock (5.13+). v1 returns the layer marker so the adapter records it in the audit log; the actual prctl/landlock_create_ruleset syscalls are wired in a follow-up so we don’t gate the whole build on a Linux-only crate.
• SandboxLayer::None - Windows, or when capability declarations are absent. The lightweight rails still apply; nothing OS-level enforces the declared capabilities.

See the project docs for the end-to-end story and the sandbox matrix.

Structs

Capabilities

Per-node capability declaration. Defaults match the most permissive “trust + log” baseline (network on, write to cwd, env scrubbed) so a node without an explicit capabilities field still works the same as a manual shell invocation.

PathEscape

Error returned by confine_path when a candidate path escapes the workspace root (traversal, absolute path outside the root, or a symlink pointing out). Carries human-readable detail for the adapter’s error.

Enums

EnvPolicy

Environment forwarding policy. Scrubbed is the default and matches the allow-list used by major sandboxing tools.

SandboxLayer

Strategy used to enforce a Capabilities declaration on the host.

Functions

audit_log_path

Audit-log directory: ~/.flow-studio/logs/audit/. Created lazily.

build_macos_sbpl

Build a macOS Seatbelt (SBPL) profile string from the declared capabilities. The profile starts from (deny default) and grants only what caps explicitly allows.

confine_path

Confine candidate to within root, returning the resolved absolute path or PathEscape if it lands outside.

resolve_layer

Pick the strongest enforcement layer the host supports for these capabilities. Always returns at least SandboxLayer::Lightweight.

scrub_env

Build the env map a child should inherit per the declared policy.

wrap_command

Wrap a user-provided command + argv into a tokio::process::Command that is ready to spawn under the resolved sandbox layer. Returns (Command, SandboxLayer) so the caller can record the actual layer in its audit log.