faraday-cage

Faraday Cage

A JavaScript sandboxing library with a focus on extensibility.

Features

• Secure JavaScript code execution in an isolated environment
• Extensible module system for customizing sandbox capabilities
• Built on QuickJS via WebAssembly
• TypeScript support
• ESM module loading capabilities

Installation

npm install faraday-cage
# or
yarn add faraday-cage
# or
pnpm add faraday-cage

Usage

Basic Example

import asyncWasmLocation from "@jitl/quickjs-wasmfile-release-asyncify/wasm?url"
import { FaradayCage } from 'faraday-cage';
import { console as consoleModule } from 'faraday-cage/modules';

async function runSandboxedCode() {
  // Create a new sandbox instance using Vite's ?url import feature to get the WASM module URL
  const cage = await FaradayCage.createFromQJSWasmLocation(asyncWasmLocation);
  
  // Define the code to run
  const code = `
    console.log('Hello from the sandbox!');
    const result = 40 + 2;
    console.log('Result:', result);
  `;
  
  // Run the code with console module
  const result = await cage.runCode(code, [
    consoleModule({
      onLog(...args) {
        console.log(...args)
      }
    })
  ]);
  
  if (result.type === "error") {
    console.error('Error executing code:', result.err);
  }
}

runSandboxedCode();

ESM Module Loading Example

import asyncWasmLocation from "@jitl/quickjs-wasmfile-release-asyncify/wasm?url"
import { FaradayCage } from 'faraday-cage';
import { 
  console as consoleModule,
  esmModuleLoader,
  blobPolyfill
} from 'faraday-cage/modules';

async function loadExternalModule() {
  const cage = await FaradayCage.createFromQJSWasmLocation(asyncWasmLocation);
  
  const code = `
    // Import an ESM module directly from a CDN
    import isEven from "https://esm.sh/is-even"
    
    console.log(isEven(1))  // false
    console.log(isEven(2))  // true
  `;
  
  await cage.runCode(code, [
    blobPolyfill,
    esmModuleLoader,
    consoleModule({
      onLog(...args) {
        console.log(...args)
      }
    })
  ]);
}

Custom Module Example

import asyncWasmLocation from "@jitl/quickjs-wasmfile-release-asyncify/wasm?url"
import { FaradayCage } from 'faraday-cage';
import { defineCageModule, defineSandboxFn } from 'faraday-cage/modules';

// Create a custom module to expose functionality to the sandbox
const mathModule = defineCageModule((ctx) => {
  // Create a function available in the sandbox
  const randomFn = defineSandboxFn(ctx, 'random', () => {
    return Math.random();
  });
  
  // Add function to global object
  const global = ctx.vm.global;
  ctx.vm.setProp(global, 'getRandomNumber', randomFn);
});

async function runWithCustomModule() {
  const cage = await FaradayCage.createFromQJSWasmLocation(asyncWasmLocation);
  
  const code = `
    // Use our custom function
    const value = getRandomNumber();
    console.log('Random value:', value);
  `;
  
  await cage.runCode(code, [mathModule]);
}

WASM Module Requirements

Important: Faraday Cage does not include the QuickJS WASM module. You must install and provide it separately:

npm install @jitl/quickjs-wasmfile-release-asyncify
# or
yarn add @jitl/quickjs-wasmfile-release-asyncify
# or
pnpm add @jitl/quickjs-wasmfile-release-asyncify

This design decision was made to support different build pipelines and bundlers properly, allowing you to handle WASM loading in the way that best fits your project setup.

Async WASM Requirement

Faraday Cage specifically requires an async-enabled QuickJS WASM module (such as @jitl/quickjs-wasmfile-release-asyncify). The Asyncify transform enables synchronous calls from QuickJS to async host functions, which is essential for Faraday Cage's functionality.

WASM Module Import

The example below uses Vite's ?url import suffix to get the URL of the QuickJS WASM module, but you can obtain the URL through any method appropriate for your build system:

// Using Vite's import feature to get the URL of the WASM file
import asyncWasmLocation from "@jitl/quickjs-wasmfile-release-asyncify/wasm?url"

// Then pass that URL to the sandbox
const cage = await FaradayCage.createFromQJSWasmLocation(asyncWasmLocation);

API Reference

FaradayCage

The main class for creating and managing sandboxes.

static async createFromQJSWasmLocation(wasmLocation: string): Promise<FaradayCage>

Creates a new sandbox instance from a QuickJS WebAssembly file.

FaradayCage.prototype.runCode(code: string, modules: CageModule[]): Promise<RunCodeResult>

Runs the provided code with the specified modules.

RunCodeResult

The result of running code in the sandbox, which is one of:

// Success case
{ type: "ok" }

// Error case
{ type: "error"; err: Error }

Example of handling the result:

const result = await cage.runCode(code, modules);
if (result.type === "error") {
  console.error('Error executing code:', result.err);
}

Modules

Modules add functionality to the sandbox:

• console: Provides console.log and other console methods
• blobPolyfill: Adds support for the Blob API
• esmModuleLoader: Enables ESM imports from external sources

License

MIT