{"_id":"@brainst0rm/sandbox-vz","name":"@brainst0rm/sandbox-vz","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@brainst0rm/sandbox-vz","version":"0.1.0","repository":{"type":"git","url":"git+https://github.com/justinjilg/brainstorm.git","directory":"packages/sandbox-vz"},"type":"module","description":"macOS Apple Virtualization.framework backend for the Brainstorm endpoint-agent sandbox abstraction (P3.1b). Wraps a small Swift helper binary (bsm-vz-helper) that drives Virtualization.framework from a code-signed app bundle. Linux guest, vsock-equivalent","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run"},"dependencies":{},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.3.0","typescript":"^5.6.0","vitest":"^2.1.0"},"_id":"@brainst0rm/sandbox-vz@0.1.0","gitHead":"10e9a5392bcf59b26446ef84a942d5b89cecc491","bugs":{"url":"https://github.com/justinjilg/brainstorm/issues"},"homepage":"https://github.com/justinjilg/brainstorm#readme","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-D7sCXQc8JlnbnSwO5iFohLtkLiToZuMfM7+Ypzr0LJDDzE02QZWDw6k6OLtEEa+9FIG6xxVDs8lCWCu/YlrOpw==","shasum":"22ce0c63e00f6a2066706dfaf737ea017fa381e2","tarball":"https://registry.npmjs.org/@brainst0rm/sandbox-vz/-/sandbox-vz-0.1.0.tgz","fileCount":18,"unpackedSize":128763,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@brainst0rm%2fsandbox-vz@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDqQu00yDHAzNGj5E84XtOhMNJ3k4icpga0/x93lkuUIwIgM9IYpkCUHxy/AlgSNtIuZ7rG7Wla1+ed1XqqSlqCNys="}]},"_npmUser":{"name":"justinjilg","email":"justin.jilg@gmail.com"},"directories":{},"maintainers":[{"name":"justinjilg","email":"justin.jilg@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sandbox-vz_0.1.0_1778932017597_0.23393990180198676"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-16T11:46:57.442Z","0.1.0":"2026-05-16T11:46:57.800Z","modified":"2026-05-16T11:46:58.265Z"},"maintainers":[{"name":"justinjilg","email":"justin.jilg@gmail.com"}],"description":"macOS Apple Virtualization.framework backend for the Brainstorm endpoint-agent sandbox abstraction (P3.1b). Wraps a small Swift helper binary (bsm-vz-helper) that drives Virtualization.framework from a code-signed app bundle. Linux guest, vsock-equivalent","homepage":"https://github.com/justinjilg/brainstorm#readme","repository":{"type":"git","url":"git+https://github.com/justinjilg/brainstorm.git","directory":"packages/sandbox-vz"},"bugs":{"url":"https://github.com/justinjilg/brainstorm/issues"},"readme":"# @brainst0rm/sandbox-vz\n\nmacOS Apple Virtualization.framework (VZ) backend for the Brainstorm\nendpoint-agent sandbox abstraction (P3.1b in `docs/endpoint-agent-plan.md`).\n\nThis is the **developer-laptop tier** of the sandbox. Production Linux\nendpoints use Cloud Hypervisor via `@brainst0rm/sandbox` (P3.1a). Both\nbackends run the **same Linux microVM image** behind a unified `Sandbox`\ninterface so guest-side tools, evidence-hashing, and reset semantics are\nbackend-agnostic.\n\n> **Status:** scaffolding only. Compiles. Unit-tested with an injected\n> fake helper. **Not booted against a real VM** — that requires the\n> Swift `bsm-vz-helper` binary, which is a separate deliverable\n> (see \"What needs to happen for first-boot\" below). Be honest with\n> downstream consumers: this package is a wire-spec + compile-clean\n> scaffold, not a working microVM yet.\n\n---\n\n## Architecture\n\n```\n   ┌────────────────────────┐\n   │  brainstorm-agent (TS) │\n   │                        │\n   │  VzSandbox             │   NDJSON over stdio (this package)\n   │   (this package)       │ ──────────────────────────────┐\n   └────────────────────────┘                               │\n                                                            ▼\n                                           ┌─────────────────────────────┐\n                                           │  bsm-vz-helper (Swift)      │\n                                           │   - VZVirtualMachine        │\n                                           │   - VZVirtioSocketDevice    │\n                                           │   - lives in code-signed    │\n                                           │     .app bundle             │\n                                           └──────────────┬──────────────┘\n                                                          │ Virtualization.framework\n                                                          ▼\n                                           ┌─────────────────────────────┐\n                                           │  Linux microVM (guest)      │\n                                           │   - same image as CHV       │\n                                           │   - vsock dispatcher        │\n                                           └─────────────────────────────┘\n```\n\nWhy a Swift helper at all (vs. a CGo bridge or a third-party Node binding)?\n\n1. Virtualization.framework is Obj-C / Swift only. A small first-party\n   Swift binary is the lowest-risk integration.\n2. The framework requires an entitlement that **must be embedded in a\n   code-signed app bundle**. Isolating that to one ~300-line Swift\n   binary keeps the entitlement scope minimal — the agent itself can\n   ship as a normal CLI, and only the helper goes through bundling +\n   signing.\n3. R13 in the plan: `Code-Hex/vz` Go bindings flagged as \"maturity\n   check needed\". A purpose-built Swift binary owned by us avoids that\n   risk vector entirely.\n\n---\n\n## Apple VZ requirements\n\n### Entitlements\n\nThe helper's `.app` bundle MUST carry the\n`com.apple.security.virtualization` entitlement:\n\n```xml\n<!-- bsm-vz-helper.entitlements -->\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\"\n  \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n<plist version=\"1.0\">\n  <dict>\n    <key>com.apple.security.virtualization</key>\n    <true/>\n  </dict>\n</plist>\n```\n\nWithout this entitlement, calling `VZVirtualMachine.start()` fails with\n`VZErrorVirtualMachineDeniedEntitlement`. **There is no way around this\nshort of running the helper from inside a properly-signed app bundle.**\nFor local dev on Justin's laptop, ad-hoc signing (`codesign --sign -`)\nis sufficient; production / customer endpoints need a Developer ID\nsignature + notarization, both of which are explicitly DEFERRED to v1.0\nper the plan (D24).\n\n### Code signing\n\nFor local dev (this is what the orchestrator can actually verify works\non a Mac):\n\n```bash\nswift build -c release\ncodesign --sign - \\\n  --entitlements bsm-vz-helper.entitlements \\\n  --force \\\n  .build/release/bsm-vz-helper\n```\n\nFor production: the helper will live at\n`brainstorm-agent.app/Contents/MacOS/bsm-vz-helper`, signed with the\nBrainstorm Apple Developer ID, hardened-runtime enabled, notarized via\n`notarytool`. The agent process resolves the helper path by looking\ninside its own bundle when packaged. **Notarization needs Apple\nDeveloper Program enrollment, which is not done yet** (post-MVP per\nD24).\n\n### macOS version matrix\n\n| macOS version | Reset path                                                   | Latency target |\n| ------------- | ------------------------------------------------------------ | -------------- |\n| 14 Sonoma+    | `VZVirtualMachine.saveMachineStateTo:` /\\* fast snapshot \\*/ | < 1s p50       |\n| 11–13         | Cold boot fallback (full kernel reboot)                      | < 5s p50       |\n| < 11          | UNSUPPORTED                                                  | —              |\n\nThis matches D23 in the plan. The helper auto-detects host version on\n`bsm-vz-helper preflight` and reports `fast_snapshot_supported: bool`.\n\n### Apple Silicon vs Intel\n\n- Apple Silicon (M-series) is the **target host arch**. Linux guest\n  must be ARM64; we ship a single ARM64 microVM image.\n- Intel Macs: Virtualization.framework on Intel is supported up to\n  macOS 13 only (Apple deprecated it for macOS 14+). Out of MVP scope.\n  The helper's `preflight` rejects `arm64=false && macos>=14`.\n\n### vsock-equivalent\n\nVZ does not expose vsock by that name — the equivalent is\n`VZVirtioSocketDevice` (a virtio-socket-over-VZ implementation). From\nthe guest's perspective it IS Linux vsock — same ioctls, same syscalls.\nFrom the host's perspective the helper attaches a\n`VZVirtioSocketDevice` to the VM config, then connects with\n`VZVirtioSocketConnection`s for each port the guest dispatcher listens\non.\n\nThe CID assignment is host-side: the helper picks a CID and reports it\nback in the boot result so the TS side can audit/log. Guest-side\nports follow the same convention as the CHV backend\n(`@brainst0rm/sandbox`) — coordinate with the Linux track when both\nland. Default ports per the threat-model integrity-monitor design:\n\n- `:1024` — `ToolDispatch` ↔ `ToolResult` channel\n- `:1025` — `EvidenceChunk` stream\n- `:1026` — `GuestQuery` ↔ `GuestResponse` (integrity verification —\n  open-fd count, mem usage, process list)\n- `:1027` — control / heartbeat\n\n### Kernel format\n\nVZ requires a **bootable Linux kernel image** for Linux guests; there\nis no firmware or BIOS path (you can't just point it at a disk image\nand expect a multiboot loader to figure it out). Concretely:\n\n- ARM64: `Image` (the unstripped kernel image, same one Linux uses for\n  EFI boot). NOT a `bzImage`.\n- An optional initrd/initramfs.\n- A kernel command line you supply (the helper doesn't synthesize one\n  — defaults are in `VzBootConfig.cmdline`).\n\nThe microVM image build pipeline (P3.4) produces the `Image` artifact\nalongside the rootfs. This package only consumes paths.\n\n---\n\n## What the helper does (Swift, NOT in this PR)\n\nDefined in `src/helper-protocol.ts` as a strict NDJSON contract.\nSubcommand surface:\n\n```\nbsm-vz-helper preflight\nbsm-vz-helper boot --kernel ... --rootfs ... [--initrd ...] [--cmdline ...]\n                   [--cpus N] [--memory-mib N] [--saved-state ...]\nbsm-vz-helper exec --command-id ... --tool ... --params ... --deadline-ms ...\nbsm-vz-helper save-state --out PATH      # macOS 14+ only\nbsm-vz-helper restore-state --from PATH  # macOS 14+ only\n```\n\nWhen invoked as `boot`, the helper daemonizes and switches into NDJSON\nmode on stdin/stdout. See `src/helper-protocol.ts` for the request /\nresponse shapes and exit codes.\n\n---\n\n## What needs to happen for first-boot on a real macOS dev laptop\n\n1. **Write `bsm-vz-helper` (Swift).** ~300 lines wrapping\n   `VZVirtualMachineConfiguration`,\n   `VZLinuxBootLoader`,\n   `VZVirtioBlockDeviceConfiguration`,\n   `VZVirtioSocketDeviceConfiguration`,\n   `VZVirtualMachine`, plus an NDJSON loop on stdin. Implements every\n   subcommand in `helper-protocol.ts`.\n2. **Build a code-signed `.app` bundle.** Minimal Info.plist + the\n   helper binary + the entitlements file above. `codesign --sign -`\n   for local dev; deferred to v1.0 for notarized distribution.\n3. **Build the Linux microVM image.** ARM64 `Image` kernel + rootfs\n   with the guest dispatcher baked in. Owned by P3.4 (orchestrator +\n   crd4sdom shared work) — coordinate to ensure the same image runs\n   under both VZ and CHV.\n4. **Wire VzSandbox into brainstorm-agent.** When the parallel\n   `@brainst0rm/sandbox` package merges, refactor `VzSandbox` to\n   `implements Sandbox` from that package and drop the local\n   `Sandbox` interface in `src/types.ts`.\n5. **Run `bsm-vz-helper preflight` from VzSandbox at agent startup.**\n   Surface failures with actionable error codes (entitlement missing\n   = HELPER_EXIT_PREFLIGHT_FAIL).\n6. **Validate end-to-end.** P3.5b validation gates: 1000-dispatch\n   red-team, sandbox escape probe, network egress audit, reset\n   verification injection. Owner: orchestrator, crd4sdom PR review.\n\nThe TypeScript side of this list is entirely items 4 and 5; everything\nelse is the Swift / image-build / packaging story that this package\ndeliberately does not own.\n\n---\n\n## Honesty about what's untested\n\n- **No real VM has booted via this package.** Unit tests inject a fake\n  ChildProcess and play canned NDJSON responses. The wire shape is\n  correct; the Swift binary is the missing piece.\n- **No entitlement / signing has been verified.** All of §\"Code\n  signing\" above is design-time documentation, not a tested workflow.\n- **No reset verification semantics have been exercised under attack.**\n  Per threat-model §3 (substrate-lying attacker class), the 3-source\n  cross-check is the load-bearing defense; we surface the data shape\n  the helper reports but do not adversarially probe it. P3.5b owns\n  that.\n- **The local `Sandbox` interface in `src/types.ts` will be replaced**\n  with the canonical one from `@brainst0rm/sandbox` after that\n  parallel package lands. The shapes are byte-equivalent on purpose\n  to make the swap mechanical.\n\n---\n\n## Tests\n\n```bash\nnpm test --workspace @brainst0rm/sandbox-vz\n```\n\nThe suite fakes the helper process and exercises:\n\n- Boot handshake (waits for `boot_result` line).\n- `executeTool` request/response correlation by `request_id`.\n- `reset` returns a `SandboxResetState` whose `verification_details`\n  matches the `@brainst0rm/relay` wire shape.\n\nCross-platform: tests are skipped on non-Darwin since `boot()` rejects\nearly — they are safe to run in CI on Linux without false failures.\n\n---\n\n## See also\n\n- `docs/endpoint-agent-plan.md` §5 — Phase 3 sandbox plan, P3.1b row\n- `docs/endpoint-agent-protocol-v1.md` §13 — wire schemas\n  (`SandboxResetState`, `VerificationDetails`, `VmmApiState`)\n- `docs/endpoint-agent-threat-model.md` §5 — 3-source reset\n  verification (substrate-lying attacker class)\n- `packages/sandbox/` — sibling Cloud Hypervisor backend (parallel\n  P3.1a track; this package will eventually consume its `Sandbox`\n  interface)\n- `packages/relay/src/types.ts` — canonical wire types\n","readmeFilename":"README.md","_rev":"1-4941f5632ec58ffad066f33c9a77e9d7"}