Jailed Function

Jailed Function is a Node.js library that safely runs untrusted code. It can be used in cloud services or low-code platforms that need to execute user-provided JavaScript.

Table of Contents

• Features
• How it works
• Architecture
• Usage
• Security
• High-Risk Method Protection
• Globals
• Performance
• Util
• Development
• License

Features

• Secure by default: Protects against common attacks using code constraints, sandboxing, and injected runtime checks.
• Run untrusted JavaScript securely: The jailed code runs in the same event loop but can't access your data or resources.
• Set execution time limits: Prevents DoS attacks and runaway scripts.
• Set memory allocation limits: Prevents memory leaks and excessive memory usage.
• ReDoS protection: Dangerous regex patterns are detected and executed in isolated worker threads with timeout protection.

How it works

1. Compile-time restrictions: The source code is validated against a secure subset of JavaScript, then transpiled to inject runtime checks and limit global variable access.
2. Sandboxing: The secured code runs in an isolated vm context.
3. Immutability: Globals, arguments, and return values are made read-only using Proxies to prevent mutations.
4. Worker thread isolation: Dangerous regex operations that can block the event loop are executed in worker threads with timeout protection.

Architecture

The library has three main components:

• Compiler: Validates the source code against a strict feature whitelist and then transpiles it. During transpilation, it injects runtime checks for memory, execution time, and property access.
• Runtime: Executes the compiled code in an isolated vm context, providing the functions that the injected checks call into to manage resources and security.
• Worker: Executes dangerous regex operations in worker threads with Atomics.wait for synchronous timeout protection.

Usage

createJailedFunction(options)

Creates a jailed function that can be executed safely.

Options

Option	Type	Default	Description
source	string	''	The async function source code
availableGlobals	string[]	[]	Allowed global variable names inside the jailed function
timeout	number	60000	Max execution time in ms (1 minute)
syncTimeout	number	100	Max synchronous execution time between awaits in ms
enableNativeProtection	boolean	true	Enable worker thread protection for dangerous regex patterns. Set to false to disable
memoryLimit	number	524288000	Max memory allocation in bytes (500 MB)
filename	string	'jailed-function:file'	Filename for stack traces
readOnlyResult	boolean	true	Make the return value read-only
readOnlyGlobals	boolean	true	Make globals read-only
readOnlyArguments	boolean	true	Make arguments read-only

Basic usage

const jailedFunc = createJailedFunction({
  source: `async (num1, num2) => {
    return num1 + num2
  }`
})

await jailedFunc([2, 3]) // returns 5

Injecting global variables

const findUserById = createJailedFunction({
  availableGlobals: ['userService'],
  source: `async (id) => {
    return userService.byId(id)
  }`
})

// provide global variables during execution
await findUserById([1], { userService })

Disabling high-risk protection for performance

// When you control all inputs and need maximum performance
const trustedFunc = createJailedFunction({
  source: `async (str) => str.match(/pattern/)`,
  enableNativeProtection: false  // Disable worker thread protection
})

Security

Jailed Function provides a secure environment for untrusted JavaScript.

• Code restrictions: The compiler enforces a strict whitelist of language features and globals. This prevents the use of potentially malicious features, such as dynamic code execution (eval, Function) or module loading (require).
• Sandboxing: Node.js vm creates an isolated context, preventing access to the file system, network, and other sensitive resources.
• Runtime checks: Injected code monitors execution time and memory usage, terminating the function to prevent DoS attacks or memory leaks.
• Immutability: Globals, arguments, and return values are made read-only to protect your data.
• ReDoS protection: Dangerous regex patterns are detected and run in worker threads with timeout protection.

High-Risk Method Protection

Regex operations can block the event loop with catastrophic backtracking (ReDoS attacks). When dangerous patterns are detected, these operations are automatically executed in worker threads with Atomics.wait for true synchronous timeout protection.

Worker-Protected Methods (Regex)

Category	Methods
String (regex)	match, replace, search, split
RegExp	exec, test

Worker protection triggers when:

• A regex pattern is detected as potentially dangerous (nested quantifiers, backreferences, etc.)
• The input string exceeds the size threshold (default: 1000 chars)

Safe Wrappers (Timeout Checks)

Other operations use chunked processing with periodic timeout checks:

Category	Methods
Object	keys, values, assign, fromEntries
Array	from, fill, sort, reverse, flat, flatMap, join, concat, indexOf, find, filter, map, reduce, etc.
String	repeat, normalize, padStart, padEnd, toLowerCase, toUpperCase, trim, includes, etc.
Encoding	encodeURIComponent, encodeURI
JSON	parse, stringify

Example: ReDoS Protection

const fn = createJailedFunction({
  source: `async (input, regex) => input.match(regex)`,
  syncTimeout: 100  // 100ms timeout for synchronous operations
})

// This evil regex would normally hang for hours
const evilRegex = /^(a+)+$/
const evilInput = 'a'.repeat(25) + 'X'

await fn([evilInput, evilRegex])
// Throws: "Timeout error" after 100ms instead of hanging

Performance Considerations

Worker thread isolation uses a persistent worker pool, adding minimal overhead (~0.006ms) per protected method call after the initial cold start:

Protection	Latency	Throughput
Enabled (enableNativeProtection: true)	~0.006ms	~160,000+ ops/s
Disabled (enableNativeProtection: false)	~0.003ms	~300,000+ ops/s

When to disable protection (enableNativeProtection: false):

• You control all regex patterns (no user input)
• Performance is critical (extreme throughput needed)
• Security risk is acceptable for your use case

Globals

Built-in globals available in jailed functions:

Global	Methods/Properties
console	log, error, warn (muted in production)
Object	keys, values, hasOwnProperty, fromEntries, assign, create
Promise	all, race, resolve, reject, allSettled
Date	now, parse, UTC
Array	isArray, from, of
Number	isFinite, isInteger, isNaN, isSafeInteger, parseFloat, parseInt, MAX_VALUE, MIN_VALUE, NaN, NEGATIVE_INFINITY, POSITIVE_INFINITY, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, EPSILON
String	fromCharCode, fromCodePoint, raw
encodeURIComponent	(function)
encodeURI	(function)
Error	(constructor)
TypeError	(constructor)
RangeError	(constructor)
ReferenceError	(constructor)
SyntaxError	(constructor)
EvalError	(constructor)
URIError	(constructor)

Performance

Jailed Function vs Worker Threads

Scenario	Jailed Function	Worker Threads
Cold start	~1.5ms	~15ms
Warm execution	~0.004ms	~15ms (must spawn each time)
Memory overhead	Low (shared V8)	High (~5-10MB per worker)

Recommendation

• Use jailed-function for: Frequent, short executions (<100ms)
• Use worker threads for: Infrequent, long-running tasks or when true process isolation is critical

Performance tests are in spec/worker-comparison.ts.

Util

readOnly(target, traps)

Prevents object modification by wrapping in a Proxy.

createGetTrap(propNames)

Creates a Proxy get trap to allow access only to specified properties.

Example: Restrict Math to only max

const max = createJailedFunction({
  availableGlobals: ['Math'],
  source: `async (a, b) => Math.max(a, b)`
})

await max([1, 2], { Math: readOnly(Math, createGetTrap(['max'])) })

Development

Requirements

• Node.js 16+ (for SharedArrayBuffer and worker_threads support)

Build

npm run build

Test

npm run test

Benchmark

npx ts-node spec/worker-comparison.ts

License

(c) 2023-present Yosbel Marín, MIT License