Bun 1.2 Standalone Binary Embedded VFS Sandbox Enforcement

--- description: Bun 1.2 Standalone Binary Embedded VFS Sandbox Enforcement - Enforces strict boundary isolation between Bun 1.2's read-only embedded Virtual File System ($bunfs) and the host operating system during standalone compiled binary execution. Prevents host filesystem breakout vulnerabilities and runtime panics caused by directory traversal out of embedded virtual roots or illegal write operations on bundled assets. globs: src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-standalone-vfs-sandbox-enforcement" --- # Bun 1.2 Standalone Binary Embedded VFS Sandbox Enforcement > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Path Resolution and Mutative Operations Against Bun Embedded VFS Roots ## System Constraints You are a Principal Software Architect enforcing runtime sandboxing invariants for Bun 1.2 standalone compiled executables (`bun build --compile`). You must ensure that all code treats embedded virtual filesystem resources as strictly immutable, guarantees that user-controlled path parameters cannot break out of designated storage roots via relative traversal (`../`), and completely decouples host filesystem write targets from virtual `$bunfs` directories. ## Strict Guidelines - Engineers MUST ALWAYS treat `import.meta.dir` and paths prefixed with `/$bunfs/` as strictly read-only virtual mounts. - Engineers MUST NOT invoke mutative filesystem APIs (`Bun.write`, `node:fs/promises.writeFile`, `chmod`, `unlink`) against paths resolved within `import.meta.dir` in compiled standalone targets. - Code MUST strictly validate and canonicalize any input-derived path using `path.resolve()` combined with `path.relative()` prefix boundaries before passing to `Bun.file()` or host filesystem APIs. - Services MUST explicitly redirect dynamic runtime writes to isolated, verified host operating system directories (such as validated subdirectories of `os.tmpdir()` or specific application data paths), never falling back to execution binary roots. - Components NEVER trust relative path traversals (`../`) originating from embedded asset roots to access the host operating system. ## Bad vs Good Implementations ### VFS Traversal and Illegal VFS Write in Standalone Binary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In a Bun 1.2 compiled binary, `import.meta.dir` resolves inside the embedded VFS (`/$bunfs/root/...`). Writing to this path causes unhandled runtime IO panics because the embedded filesystem is read-only. Furthermore, evaluating relative paths without boundary validation allows path traversal to escape the VFS and access arbitrary host files. ```typescript import { resolve } from "node:path"; // ANTI-PATTERN: In Bun standalone binaries, import.meta.dir points to the virtual embedded filesystem ($bunfs/root). // Attempting to resolve untrusted paths from it allows breakout to host root, or writing to VFS crashes at runtime. export async function handleFileRequest(userRelativePath: string, payload?: string) { const targetPath = resolve(import.meta.dir, "public", userRelativePath); if (payload) { // Throws EROFS / EPERM: Bun's standalone VFS is immutable await Bun.write(targetPath, payload); return { success: true }; } // Potential path breakout: userRelativePath of "../../../../etc/passwd" leaves VFS to host const file = Bun.file(targetPath); return await file.text(); } ``` #### Production Standard (Correct) > **Standard**: Separates the read-only embedded VFS assets from mutable host filesystem state. Employs a strict containment assertion (`assertPathContained`) using `relative()` checks to prevent directory traversal breakout vectors, guaranteeing that writes only touch designated host directories and embedded reads cannot escape the virtual mount. ```typescript import { resolve, relative, normalize } from "node:path"; import { tmpdir } from "node:os"; import { realpathSync } from "node:fs"; const VFS_ASSET_ROOT = resolve(import.meta.dir, "public"); const HOST_WRITABLE_ROOT = resolve(process.env.APP_DATA_DIR ?? tmpdir(), "app-sandbox"); function assertPathContained(basePath: string, targetPath: string): string { const canonicalBase = normalize(basePath); const resolvedTarget = resolve(canonicalBase, targetPath); const rel = relative(canonicalBase, resolvedTarget); if (rel.startsWith("..") || resolve(canonicalBase, rel) !== resolvedTarget) { throw new Error("Security Exception: Path traversal out of sandbox boundary."); } return resolvedTarget; } export async function handleFileRequest(userRelativePath: string, payload?: string) { if (payload) { // Host writes are strictly isolated to validated host storage directories const safeWritePath = assertPathContained(HOST_WRITABLE_ROOT, userRelativePath); await Bun.write(safeWritePath, payload); return { success: true }; } // Embedded VFS reads are strictly contained within read-only asset boundaries const safeReadPath = assertPathContained(VFS_ASSET_ROOT, userRelativePath); const asset = Bun.file(safeReadPath); if (!(await asset.exists())) { throw new Error("File not found"); } return await asset.text(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Standalone Binary Embedded VFS Sandbox Enforcement

Bun 1.2 Standalone Binary Embedded VFS Sandbox Enforcement defines an industrial-grade behavioral standard for backend engineering. Enforces strict boundary isolation between Bun 1.2's read-only embedded Virtual File System ($bunfs) and the host operating system during standalone compiled binary execution. Prevents host filesystem breakout vulnerabilities and runtime panics caused by directory traversal out of embedded virtual roots or illegal write operations on bundled assets. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unchecked Path Resolution and Mutative Operations Against Bun Embedded VFS Roots Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unchecked Path Resolution and Mutative Operations Against Bun Embedded VFS Roots	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS treat `import.meta.dir` and paths prefixed with `/$bunfs/` as strictly read-only virtual mounts.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.