suaveplan/openspec/archive/2026-05-25-enterprise-sandbox/proposal.md

# Proposal — Migrate @suaveplan/sandbox to genesis

- **Design**: ./design.md
- **Spec delta**: ./specs/sandbox/spec.md

## Why

Upstream `@suaveplan/sandbox` (`/mnt/s/web/suaveplan/packages/server/sandbox/`) ships a
working server-tier sandboxed execution environment built around `Bun.spawn` for
process-isolated execution, an `IsolateEngine` contract for isolated-vm, a
pre-warmed `SandboxPool`, an async `ResultStreamer`, a pattern-based
`CodeTransformer`, an allowlist-based `ModuleResolver`, a sliding-window
`ResourceLimiter`, and a SHA-256 `AuditLogger`. The genesis `enterprise/sandbox.md`
audit calls out two cross-cutting gaps shared with every other migration: (a) no
error-code registry — every failure path raises plain `Error` instances so
consumers cannot discriminate programmatically, and (b) no OpenTelemetry surface
even though sandbox execution is a load-bearing primitive in any agent or
plugin host. The upstream also hard-codes a single transport (Bun.spawn pinned
to `process.argv[0]`) with no seam for testing without an actual child process,
and it lacks Zod-validated configuration on the public boundary.

Genesis cleans up the contract: every failure raises a typed `SandboxError`
with a stable `SANDBOX.*` code, the engine surface gains a runner-tier abstraction
that defaults to real `node:vm` (universally available, no Bun dependency) and
real `node:worker_threads` for true isolation when requested, `Bun.spawn` is
retained behind the same `SandboxEngine` contract for environments that prefer
process boundaries, Zod schemas guard the public surface, and OTel counters +
histograms tag every execution by engine, outcome, and phase.

## What

Land `@suaveplan/sandbox@0.1.0` at `packages/devtools/tooling/sandbox/` with these
feature modules (one folder per feature, sibling `.md` per implementation file):

- `types/` — shared `SandboxConfig`, `SandboxResult`, `SandboxOptions`,
  `SandboxModule`, `ExecutionContext`, `AuditLogEntry`, `AuditStatistics`,
  `Clock`, `ProcessSpawner`, `CommandResult` types.
- `error-codes/` — `SANDBOX_CODES` via `defineCodes("SANDBOX", [...])` +
  `SandboxError` class.
- `schemas/` — Zod schemas for `SandboxConfig`, `SandboxOptions`,
  `SandboxModule` boundaries.
- `telemetry/` — OTel counters (`sandbox_executions_total`,
  `sandbox_rule_blocks_total`, `sandbox_pool_acquisitions_total`) and a
  histogram (`sandbox_execution_duration_ms`) tagged by engine + outcome.
- `audit-logger/` — `AuditLogger` with SHA-256 code hashing, search filters,
  statistics aggregation, and `onAuditLog` callback hook.
- `resource-limiter/` — `ResourceLimiter` with sliding-window rate limiting,
  output-size truncation, injectable `Clock` for deterministic tests.
- `module-resolver/` — `ModuleResolver` with `BLOCKED_MODULES` denylist,
  `BUILTIN_SAFE_MODULES` (`Math`/`JSON`/`Date`), custom module registry.
- `code-transformer/` — `CodeTransformer` with the eleven `BUILTIN_RULES`
  (block-process, block-require, block-import-dynamic, block-eval,
  block-function-constructor, block-global-this, block-proto-access,
  block-constructor-access, warn-while-true, warn-infinite-for,
  max-code-length) plus an injectable custom-rule slot.
- `vm-engine/` — Real-`node:vm`-backed `SandboxEngine` (default). Frozen-Realm
  pattern via `vm.createContext(...)`, `vm.Script` compile +
  `runInContext({ timeout })`, captured console with output-size limit,
  module + context injection, heap snapshotting via `v8.getHeapStatistics()`.
- `worker-engine/` — Real-`node:worker_threads`-backed `SandboxEngine`. Spawns
  an inline `Worker` (`eval: true`) with code + context + modules sent via
  `postMessage`, captures result via the message channel, enforces timeout by
  terminating the worker.
- `spawn-engine/` — Real-`node:child_process`-backed runner equivalent to
  upstream's `bun-spawn-runner` but using `node:child_process.spawn` so it
  works under both Bun and Node. Pinned to current `process.execPath`,
  sanitised env (`SECRET`/`KEY`/`TOKEN`/`PASSWORD`/`CREDENTIAL`/`AUTH`
  patterns + `HOME`/`USER`/`SHELL`/`LOGNAME` stripped), structured JSON IPC
  via stdin/stdout, timeout via `Promise.race`.
- `runner/` — Child-process entry point invoked by `spawn-engine`. Reads JSON
  from stdin, evaluates code via a strict-mode dynamic wrapper, writes JSON
  result to stdout. Ships as its own subpath export.
- `isolate-engine/` — Pluggable `IsolateEngine` over the upstream's
  isolated-vm contract (kept as a structural interface so the optional peer
  dep stays optional).
- `pool/` — `SandboxPool` of pre-warmed engines, idle reclamation,
  recycle-on-N-executions, statistics surface.
- `result-streamer/` — `ResultStreamer` with subscribe/unsubscribe, push
  chunks (`log`/`result`/`error`/`complete`), buffered + interval-flushed
  delivery, completion gating.
- `sandbox/` — `createSandbox(config?)` facade composing module resolver,
  resource limiter, audit logger, code transformer, and an engine selection.
  `Sandbox.execute` / `executeFunction` returns the structured `SandboxResult`.

## Parity Checklist

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| `createSandbox(config)` facade | ✅ | ✅ | Same surface, Zod-validated config. |
| `Sandbox.execute(code, context, opts)` | ✅ | ✅ | |
| `Sandbox.executeFunction(fn, args, opts)` | ✅ | ✅ | |
| `Sandbox.registerModule` / `unregisterModule` | ✅ | ✅ | |
| `Sandbox.getAuditLog` / `getStatistics` / `reset` | ✅ | ✅ | |
| `Bun.spawn` process engine | ✅ | ⬆️ | Replaced with portable `node:child_process` `spawn` (works under Bun + Node). Same isolation guarantees. |
| Frozen-Realm VM engine | 🚫 | ⬆️ | New default — `node:vm` `createContext` + `runInContext({ timeout })`. |
| `node:worker_threads` engine | 🚫 | ⬆️ | New — true OS-thread isolation for stronger CPU caps. |
| `IsolateEngine` (isolated-vm contract) | ✅ | ✅ | Preserved as structural interface; tests use a real fake factory. |
| `SandboxPool` (warm + idle reclaim + recycle) | ✅ | ✅ | |
| `ResultStreamer` (subscribe/buffer/flush) | ✅ | ✅ | |
| `CodeTransformer` (10 built-in rules + max-code-length) | ✅ | ✅ | |
| `ModuleResolver` (blocked/allowed + builtins) | ✅ | ✅ | |
| `ResourceLimiter` (sliding-window rate limit + output trunc) | ✅ | ⬆️ | Injectable `Clock` for deterministic tests. |
| `AuditLogger` (SHA-256 hash + filter + stats) | ✅ | ✅ | |
| `BUILTIN_RULES` export | ✅ | ✅ | |
| `DEFAULT_CONFIG` export | ✅ | ✅ | |
| Error-code registry | 🚫 | ⬆️ | Added — `SANDBOX.*` codes via `defineCodes`. |
| OTel self-telemetry | 🚫 | ⬆️ | Added — counters + histograms. |
| Zod-validated config | 🚫 | ⬆️ | Added — `SandboxConfigSchema`, etc. |
| Subpath exports per feature | 🚫 | ⬆️ | Added — every feature module is its own subpath. |

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/sandbox` to enumerate. Net-new on
genesis — no current dependents.

- No dependents (verified by `bunx turbo ls --filter=...@suaveplan/sandbox`).

## Risks

- **`node:vm` is not a security boundary.** `vm.runInContext` shares the host
  realm; a determined attacker with code-injection can escape via prototype
  chain tricks. The package documents this explicitly: `vm-engine` is for
  *isolation against accidents*, `worker-engine` and `spawn-engine` are for
  isolation against adversaries.
- **Timeouts under `vm.runInContext` only cover synchronous code.** A microtask
  scheduled inside the context outlives the timeout. The package documents
  this and recommends `worker-engine` for code that awaits.
- **`node:worker_threads` `eval: true` accepts a string.** This is the
  worker's documented contract for running ad-hoc code. The boundary is the
  worker thread, not the string parser.