feat(security): #505 MVP — PERRY_SANDBOX_BUILDRS=1 wraps cargo in sandbox-exec on macOS

[proggeramlug]

Closes #505 (MVP — Linux landlock follow-up tracked).

Summary

perry.nativeLibrary resolution triggers cargo build on developer machines for any source-distributed crate. Crate build.rs scripts run with full developer privileges. Most TypeScript developers don't think of bun add as triggering arbitrary Rust code, so the implicit trust escalation is invisible.

This adds an opt-in sandbox: when PERRY_SANDBOX_BUILDRS=1 is set, the compile driver wraps cargo invocations for nativeLibrary crate builds in sandbox-exec on macOS. Build-time only — zero runtime cost in the produced binary.

Profile contents

• deny default + deny network* (build.rs can't phone home)
• allow file-read* everywhere (cargo / rustc read system libs, source, dep crates)
• allow file-write* to target/ + ~/.cargo + ~/.rustup + /tmp + TempDir
• allow process-fork + process-exec (rustc, cc, ld, build.rs binaries)
• allow sysctl-read / mach-lookup / iokit-open (system queries)

Opt-in

Off by default for backwards compat. Enable per build:

PERRY_SANDBOX_BUILDRS=1 perry compile main.ts -o myapp

CI sets the env var on every job. Local dev keeps the legacy flow until ready.

Pre-fetch workflow

The sandbox denies network, so cargo can't reach crates.io from inside it. Pre-fetch outside the sandbox once before the sandboxed build:

cargo fetch --manifest-path node_modules/@foo/native-bar/Cargo.toml
PERRY_SANDBOX_BUILDRS=1 perry compile main.ts -o myapp

CI typically caches ~/.cargo, so this pre-fetch is free on subsequent runs.

Per-package escape hatch

{
  "perry": {
    "allowUnsandboxedBuild": ["@some-vendor/builds-with-network"]
  }
}

Host-controlled — transitive deps can't opt themselves out. The exemption sits in the host repo's package.json and shows up in code review.

Cross-platform scope

Platform	Status
macOS	Real impl — sandbox-exec wrapper + per-package profile
Linux	One-line note; landlock/bubblewrap follow-up under #505
Windows	Same — Win32 sandbox profile follow-up

Test coverage

4 unit tests in commands::compile::sandbox_buildrs::tests:

• profile_denies_network_allows_build_dirs — pins the deny-network + allow-process-spawn + allow-file-read + target/ write semantics.
• profile_header_documents_usage_and_escape_hatch — pins PERRY_SANDBOX_BUILDRS=1, allowUnsandboxedBuild, security: sandbox cargo build.rs execution for native-archive crates #505 cite in the emitted header.
• wrap_cargo_falls_through_when_sandbox_disabled — opt-in invariant.
• wrap_cargo_falls_through_when_package_exempt — escape-hatch invariant.

Plumbing

• CompilationContext gains pub allow_unsandboxed_build: Vec<String>.
• Parsed from perry.allowUnsandboxedBuild in host package.json.
• New module commands::compile::sandbox_buildrs with wrap_cargo_command() / build_macos_buildrs_profile() / write_macos_buildrs_profile(). Sanitises the package name into a single path component when writing the profile so a hostile name: "../etc/passwd" can't escape the cache dir.
• link.rs swaps Command::new("cargo") for the wrapper.

Docs

docs/src/cli/sandbox-buildrs.md documents the workflow + the pre-fetch pattern + the escape hatch + the deferred Linux follow-up. Linked from SUMMARY.md under CLI Reference.

What's deferred for #505 follow-ups

• Linux landlock + bubblewrap profile, optionally unshare -n for network denial.
• Auto pre-fetch (cargo fetch outside the sandbox before the sandboxed build).
• HIR-driven profile refinement.

Notes

No Cargo.toml version bump, no CLAUDE.md touch, no CHANGELOG.md entry — maintainer folds those in at merge time.