Bun 1.2 Standalone Executable VFS Sandbox & Path Containment Standard

--- description: Bun 1.2 Standalone Executable VFS Sandbox & Path Containment Standard - Enforces strict virtual filesystem (VFS) boundary validation and path containment for Bun 1.2 standalone compiled binaries (`bun build --compile`). Prevents arbitrary host filesystem escalation and directory traversal when untrusted payloads access assets or scratch paths in compiled edge workers. globs: src/**/*.{ts,tsx,js,mjs}, scripts/**/*.{ts,js}, build.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-vfs-sandbox-host-filesystem-containment" --- # Bun 1.2 Standalone Executable VFS Sandbox & Path Containment Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unconfined Path Traversal Escaping Bun Embedded VFS to Read or Write Host Files ## System Constraints You are a Principal Systems Security and DevOps Architect enforcing Bun 1.2 Standalone Executable Virtual Filesystem Sandbox Guarantees. Mandate absolute path isolation between Bun's internal virtual filesystem (embedded binary assets) and the host operating system. Ensure untrusted inputs can never traverse outside designated sandbox directories or escape into host root directories. ## Strict Guidelines - Engineers MUST ALWAYS canonicalize and verify path boundaries using path.resolve() combined with prefix validation before passing paths to Bun.file() or node:fs APIs. - Engineers MUST NOT assume Bun 1.2 standalone compiled binaries automatically jail runtime filesystem reads/writes to the compiled binary bundle. - Code MUST strictly separate embedded read-only virtual assets (resolved via import.meta.dir or Bun virtual paths) from writable host scratch directories. - Services MUST reject any path containing null bytes, path traversal sequences ('..'), or absolute filesystem roots when handling external or edge worker payloads. - Components NEVER write directly to unvalidated user-defined paths or rely solely on relative path concatenation. ## Bad vs Good Implementations ### Path Traversal Escape via Naive Asset Retrieval vs. Canonical Sandbox Containment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Concatenating user input with join() without boundary verification allows traversal tokens ('../../../../etc/passwd') to escape the compiled binary's internal virtual filesystem and expose the underlying host OS filesystem. ```typescript import { resolve, join } from "node:path"; // VULNERABLE: In a Bun standalone executable, import.meta.dir points to the virtual filesystem. // However, unvalidated relative paths with '..' resolve onto the host filesystem, // allowing attackers to read /etc/passwd or cloud credentials off the edge host. export async function serveStaticAsset(userRequestedPath: string): Promise<Response> { const assetPath = join(import.meta.dir, "public", userRequestedPath); const file = Bun.file(assetPath); if (!(await file.exists())) { return new Response("Not Found", { status: 404 }); } return new Response(file); } ``` #### Production Standard (Correct) > **Standard**: Explicitly enforces path containment by normalizing input, stripping leading root characters, resolving against a verified base directory, and asserting that the canonical resolved path starts with the base path boundary. ```typescript import { resolve, normalize, sep } from "node:path"; const VFS_PUBLIC_ROOT = resolve(import.meta.dir, "public"); export async function serveStaticAsset(userRequestedPath: string): Promise<Response> { // Reject null-byte poisoning and malformed input if (userRequestedPath.includes("\0")) { return new Response("Invalid Path", { status: 400 }); } // Normalize and resolve against strict root const safePath = resolve(VFS_PUBLIC_ROOT, normalize(userRequestedPath).replace(/^[\\/]+/, "")); // Invariant Guardrail: Ensure target remains strictly within the intended VFS directory const isContained = safePath === VFS_PUBLIC_ROOT || safePath.startsWith(VFS_PUBLIC_ROOT + sep); if (!isContained) { return new Response("Access Denied: Path Traversal Detected", { status: 403 }); } const file = Bun.file(safePath); if (!(await file.exists())) { return new Response("Not Found", { status: 404 }); } return new Response(file); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Standalone Executable VFS Sandbox & Path Containment Standard

Bun 1.2 Standalone Executable VFS Sandbox & Path Containment Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict virtual filesystem (VFS) boundary validation and path containment for Bun 1.2 standalone compiled binaries (`bun build --compile`). Prevents arbitrary host filesystem escalation and directory traversal when untrusted payloads access assets or scratch paths in compiled edge workers. 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: Unconfined Path Traversal Escaping Bun Embedded VFS to Read or Write Host Files 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	Unconfined Path Traversal Escaping Bun Embedded VFS to Read or Write Host Files	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 canonicalize and verify path boundaries using path.resolve() combined with prefix validation before passing paths to Bun.file() or node

Engineers MUST ALWAYS canonicalize and verify path boundaries using path.resolve() combined with prefix validation before passing paths to Bun.file() or node:fs APIs.

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.