docs: refactor docs

Author: patriksimek

.claude/skills/hacker/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: hacker
+description: >
+  Red team agent for vm2 sandbox escape testing. Systematically attempts to break out of the
+  vm2 JavaScript sandbox by exploiting known and novel attack vectors. Use this skill whenever
+  the user makes changes to vm2's sandbox code (bridge.js, setup-sandbox.js, setup-node-sandbox.js,
+  vm.js, nodevm.js, transformer.js) and wants to verify the sandbox still holds. Also use when
+  the user asks to "hack", "attack", "test security", "try to escape", "red team", or "pentest"
+  the sandbox. Trigger on any request to find sandbox escapes or verify sandbox integrity.
+---
+
+# Hacker - vm2 Sandbox Red Team Agent
+
+## Purpose
+
+Act as a persistent adversary trying to escape the vm2 sandbox. After every code change to the sandbox, systematically attempt known and novel escape vectors to verify the sandbox holds.
+
+## Before Starting
+
+1. Read `docs/ATTACKS.md` -- the full catalog of attack patterns, fundamentals, and defense table.
+2. Read `lib/bridge.js` and `lib/setup-sandbox.js` to understand the current defenses.
+3. Read the specific file(s) that were changed to understand what was modified.
+
+## Attack Methodology
+
+### Phase 1: Understand the Change
+
+Analyze the diff or changed code to understand:
+- What new surface area is exposed?
+- What invariants were relaxed or tightened?
+- What assumptions does the change make?
+
+### Phase 2: Replay Known Attacks
+
+Run through all attack categories from `docs/ATTACKS.md` against the modified code. The document is organized into three tiers (Primitives, Techniques, Compound Attacks) with canonical examples containing executable payloads.
+
+### Phase 3: Synthesize Novel Attacks
+
+Combine attack primitives to create compound attacks targeting the specific change:
+- New property/method exposed: try constructor chain, prototype traversal, symbol extraction
+- Async code modified: try Promise species, TOCTOU, static method stealing, Reflect.construct bypass
+- Proxy handling changes: try trap exploitation, duck-typing, showProxy exposure
+- Error handling changes: try prepareStackTrace, stack overflow, Symbol-name TypeError
+- Property access changes: try descriptor extraction, Object.entries unwrapping, nested getOwnPropertyDescriptors
+
+### Phase 4: Write Attack Tests
+
+Write each escape attempt as a Mocha test in `test/vm.js`:
+
+```javascript
+it('attack name - description', () => {
+  const vm2 = new VM();
+  assert.doesNotThrow(() => vm2.run(`
+    // ... attack code ...
+  `), 'description of what should be prevented');
+
+  // Or for attacks that should throw:
+  assert.throws(() => vm2.run(`
+    // ... attack code ...
+  `), /expected error pattern/, 'description');
+});
+```
+
+For async attacks:
+```javascript
+it('async attack name', async () => {
+  const vm2 = new VM({allowAsync: true});
+  let escaped = false;
+  global.escapeMarker = () => { escaped = true; };
+  await new Promise((resolve) => {
+    vm2.run(`
+      // ... async attack code ...
+      // If escape works: escapeMarker()
+    `);
+    setTimeout(() => {
+      delete global.escapeMarker;
+      assert.strictEqual(escaped, false, 'Sandbox escape should be prevented');
+      resolve();
+    }, 200);
+  });
+});
+```
+
+Use `it.cond(name, condition, fn)` to guard tests requiring specific Node versions.
+
+## Thinking Like an Attacker
+
+When analyzing a code change, ask:
+1. Does this introduce a new way to get a reference to a host object?
+2. Can I make the bridge call my code with unsanitized arguments?
+3. Can I intercept an internal operation between check and use (TOCTOU)?
+4. Can I override something the bridge relies on before it caches it?
+5. Can I cause an error that leaks host realm objects?
+6. Can I make the bridge skip a security check via type confusion?
+7. Can I reach a code path where values cross the boundary unsanitized?
+8. Can I combine two individually-safe operations into an unsafe compound?
+
+## Output
+
+After each attack session, produce:
+1. Summary of which attack categories were tested
+2. Any new vulnerabilities discovered (with proof-of-concept code)
+3. Mocha tests for each attempted attack (both successful and prevented)
+4. Recommendations for fixes if escapes were found

CLAUDE.md

@@ -0,0 +1,99 @@
+# vm2
+
+vm2 safely sandboxes untrusted JavaScript code running in Node.js. This is a security-critical project -- every change must be evaluated for sandbox escape potential.
+
+## Public API
+
+Exported from `lib/main.js` via `index.js`:
+
+- **`VM`** -- isolated context for synchronous execution without `require`.
+- **`NodeVM`** -- sandbox emulating Node's module loader with fine-grained `require` controls.
+- **`VMScript`** -- compilation, caching, and compiler selection wrapper.
+- **`VMFileSystem`** -- controls sandbox filesystem access.
+- **`VMError`** -- raised when sandbox policy is violated.
+
+## Architecture
+
+### The Boundary (Security-Critical)
+
+| File | Role |
+|------|------|
+| `lib/bridge.js` | Core proxy layer. Paired proxies for every value crossing host/sandbox. WeakMap caches for identity. Proxy trap handlers (`BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`). |
+| `lib/setup-sandbox.js` | Sandbox bootstrap for `VM`. `handleException`, Promise wrapping, `Symbol.for` override, symbol filtering, `Error.prepareStackTrace` safe default, `WebAssembly.JSTag` deletion. |
+| `lib/setup-node-sandbox.js` | Sandbox bootstrap for `NodeVM`. `require`, module resolution, console redirection. |
+| `lib/transformer.js` | Acorn parser instrumenting `catch` blocks and `with` statements. **Limitation**: `ecmaVersion: 2022` -- post-ES2022 syntax (e.g., `using`) is invisible. |
+
+### Other Files
+
+| File | Role |
+|------|------|
+| `lib/vm.js` | `VM` class. Compiles via `vm.Script`, applies transformer, enforces timeout/async. |
+| `lib/nodevm.js` | `NodeVM` class. Module loader, external module access, console redirection. |
+| `lib/script.js` | `VMScript`. Options, compilers, caching, async detection. |
+| `lib/compiler.js` | Compiler resolution (JS passthrough, optional CoffeeScript/TypeScript). |
+| `lib/filesystem.js` | `VMFileSystem` implementation. |
+| `lib/resolver.js` | Module resolution for `NodeVM`. |
+| `lib/events.js` | Sandbox-safe copy of Node's `events`. |
+
+### CLI
+
+```sh
+npx vm2 path/to/script.js  # NodeVM with external modules, verbose logging
+```
+
+## Security
+
+See [`docs/ATTACKS.md`](docs/ATTACKS.md) for the full catalog of attack patterns, fundamentals of realm separation and V8 internals, and the defense table.
+
+**Key insight**: V8 internal algorithms (ArraySpeciesCreate, FormatStackTrace, PromiseResolveThenableJob) operate on raw objects, bypassing proxy traps. Defenses must neutralize raw objects directly, not just intercept via proxies.
+
+### Principles
+
+1. Never expose host constructors or prototypes.
+2. Rebound every function crossing the bridge to the destination realm.
+3. Freeze or proxy shared mutable state.
+4. Filter property access via `Object.getOwnPropertyDescriptor`. Never `for...in` or spread on host objects.
+5. Treat new symbols and language features as suspect until vetted.
+6. Cache `Reflect.*` and other critical references at init time.
+
+### Checklist for Boundary Changes
+
+1. Does this expose any new return path for host objects?
+2. Can sandbox code call this method directly (not through a proxy)?
+3. Does this accept attacker-controlled parameters?
+4. Are all `Reflect.*` calls using cached references?
+5. Could V8 internal algorithms trigger this path (bypassing traps)?
+6. Does this handle host-realm errors that could be thrown?
+7. Are there new well-known symbols that need filtering?
+
+## Tests
+
+```sh
+npm test                # Main suite (Mocha)
+npm run test:compilers  # Optional (needs typescript, coffee-script)
+npm run lint            # ESLint
+```
+
+- `test/vm.js` -- Main sandbox tests. Uses `makeHelpers()` for proxy boundary checks, `it.cond(name, condition, fn)` for version-gated tests.
+- `test/nodevm.js` -- NodeVM module loading tests.
+- `test/escape-scanner.js` -- Automated escape scanner. Serializable, runs inside `vm.run()`.
+
+Every security fix must include tests that reproduce the attack, verify the defense, and test bypass variants. Use `it.cond()` for Node version requirements.
+
+Use the `/hacker` skill after making security-related changes to systematically red-team the sandbox and verify it still holds.
+
+## Updating ATTACKS.md
+
+**Every time the library is patched**, update [`docs/ATTACKS.md`](docs/ATTACKS.md):
+
+- Add the attack to the appropriate tier/category (or create a new one).
+- Document: attack flow, canonical example, why it works, mitigation, detection rules.
+- Update the Compound Attack Patterns and "How The Bridge Defends" table.
+- Add new APIs/features to "Considered Attack Surfaces" or "Future Risks".
+
+## Workflow
+
+- Keep changes small and focused. Security-sensitive code discourages large refactors.
+- Include threat model reasoning and escape-prevention tests for boundary changes.
+- Follow existing ESLint code style.
+- Vulnerabilities: follow `SECURITY.md`, not public issues.