SandboxJS

You can customize the sandbox security model by providing your own prototypeWhitelist and globals.

• Use Sandbox.SAFE_PROTOTYPES to get the default prototype whitelist (a Set).
• Use Sandbox.SAFE_GLOBALS to get the default safe globals object.

Example of adding alert to globals and Node to the prototype whitelist:

const prototypeWhitelist = Sandbox.SAFE_PROTOTYPES;
prototypeWhitelist.set(Node, new Set());

const globals = {...Sandbox.SAFE_GLOBALS, alert};

const sandbox = new Sandbox({globals, prototypeWhitelist});

Install the SandboxJS library using npm to begin sandboxing untrusted JavaScript code.

npm install @nyariv/sandboxjs

SandboxJS uses a Lisp-like structure to represent code internally. A Lisp object is a tuple consisting of a LispType (the operation), and two LispItems (the operands/arguments).

Key types include:

• LispItemSingle: Can be LispType.None, LispType.True, a string, or a Lisp object.
• LispItem: Either a LispItemSingle or an array of LispItemSingles.
• Lisp: A tuple [LispType, LispItem, LispItem].

This structure allows the parser to represent complex expressions like function calls, assignments, and control flow in a predictable, tree-like format.

To execute code in a sandbox, create a new Sandbox instance, compile your code string into an executable, and then call .run() with a scope object containing the variables available to the code.

const code = `return myTest;`;
const scope = { myTest: "hello world" };
const sandbox = new Sandbox();
const exec = sandbox.compile(code);
const result = exec(scope).run(); // result: "hello world"

SandboxJS allows you to pass multiple scope objects to an executable. This is useful for managing layered permissions or reusing scopes across different execution layers.

const sandbox = new Sandbox();

const scopeA = {a: 1};
const scopeB = {b: 2};
const scopeC = {c: 3};

const code = `a = 4; let d = 5; let b = 6`;
const exec = sandbox.compile(code);
exec(scopeA, scopeB, scopeC).run();

console.log(scopeA); // {a: 4}
console.log(scopeB); // {b: 2}
console.log(scopeC); // {c: 3, d: 5, b: 6}

If you are unsure which globals or prototypes a piece of code requires, use Sandbox.audit(code). This method permits all access but returns a JSON object detailing every global and prototype accessed during the execution. This is useful for determining the exact whitelist needed for a specific library.

const code = `console.log("test")`;
console.log(Sandbox.audit(code));

These are the default prototypes allowed within the sandbox.

- SandboxGlobal
- Function
- Boolean
- Object
- Number
- BigInt
- String
- Date
- RegExp
- Error
- Array
- Int8Array
- Uint8Array
- Uint8ClampedArray
- Int16Array
- Uint16Array
- Int32Array
- Uint32Array
- Float32Array
- Float64Array
- Map
- Set
- WeakMap
- WeakSet
- Promise

These are the default global properties available in the sandbox. Note that setTimeout, setInterval, clearTimeout, and clearInterval are excluded by default.

- globalThis
- Function
- eval
- setTimeout (excluded)
- setInterval (excluded)
- clearTimeout (excluded)
- clearInterval (excluded)
- console
- isFinite
- isNaN
- parseFloat
- parseInt
- decodeURI
- decodeURIComponent
- encodeURI
- encodeURIComponent
- escape
- unescape
- Boolean
- Number
- BigInt
- String
- Object
- Array
- Symbol
- Error
- EvalError
- RangeError
- ReferenceError
- SyntaxError
- TypeError
- URIError
- Int8Array
- Uint8Array
- Uint8ClampedArray
- Int16Array
- Uint16Array
- Int32Array
- Uint32Array
- Float32Array
- Float64Array
- Map
- Set
- WeakMap
- WeakSet
- Promise
- Intl
- JSON
- Math

The LispCallback<T> type is used to define callback functions that react to specific parts of the Lisp tree during parsing or execution. The callback receives a context object containing depth information, constants, and the current state of the parse.

type LispCallback<T> = (ctx: LispCallbackCtx & { type: T }) => any;

LispCallbackCtx includes:

• generatorDepth: Current generator depth.
• asyncDepth: Current async depth.
• lispDepth: Current Lisp tree depth.
• constants: The IConstants object.
• type: The specific type being processed.
• part: The CodeString being processed.
• res: An array of strings (results).
• expect: The expected value/token.
• lispTree: The current Lisp node.

You can extend the executor's capabilities by registering custom operation callbacks using the addOps function. This allows you to define how specific LispType values are handled during execution.

To register an operation, provide the LispType and a callback function. The callback receives an OpsCallbackParams object containing the execution context, the current Lisp item (tree), the scope, and control flow information.

import { addOps } from '@nyariv/sandboxjs';

// Example: Registering a custom operation for a specific LispType
addOps(myCustomType, ({ op, exec, a, b, obj, bobj, ticks, tree, scope, context, done, statementLabels, internal, generatorYield }) => {
  // Implement custom execution logic here
  // Use 'exec' to continue execution or 'done' to signal completion
});