endo

[Edit section]

[Copy link]

• • •

Endo is a distributed secure JavaScript sandbox based on Hardened JavaScript as implemented by its ses shim. It allows developers to create isolated execution environments for running untrusted JavaScript code safely. Endo provides compartmentalization, module mapping, and enables secure multi-tenant JavaScript applications.

The core of Endo is Hardened Javascript, implemented in …/ses. SES creates a hardened JavaScript environment by:

• Freezing built-in objects and prototypes to prevent tampering • Removing unsafe features like eval and with • Providing a Compartment class for creating isolated execution contexts

The Compartment class is central to Endo's security model. It allows creating separate realms with their own global objects and module maps. Code running in a compartment cannot access or modify objects outside its boundaries. The Compartment Management section provides more details on how compartments are implemented.

Endo uses a custom module system to load and link code securely across compartments. The Compartment Mapper in …/compartment-mapper handles:

• Parsing module source code • Creating module dependency graphs • Linking modules across compartment boundaries • Loading modules from archives

The Module Handling section explains the module system in depth.

Key design choices in Endo include:

• Using SES to create a hardened JavaScript environment • Leveraging compartments for isolation • Implementing a confined module system
• Supporting ECMAScript modules and CommonJS modules

By combining these technologies, Endo enables running untrusted JavaScript securely in a distributed environment while preserving key language features and compatibility with most existing JavaScript libraries.

Secure EcmaScript (SES)

[Edit section]

[Copy link]

References: packages/ses

The Secure EcmaScript (SES) environment provides a robust foundation for executing JavaScript code in a controlled and isolated manner. At its core, SES implements a set of security features that restrict access to potentially dangerous functionality while preserving the essential capabilities of the language.

Compartment Management

[Edit section]

[Copy link]

References: packages/ses/src/compartment-evaluate.js, packages/ses/src/compartment-shim.js, packages/ses/src/compartment.js

• • •

The Compartment class, created by makeCompartmentConstructor(), provides isolated execution environments within JavaScript. Each compartment has its own global object, initialized with constant and mutable properties. The private state of compartments is stored in the privateFields WeakMap.

Lockdown and Hardening

[Edit section]

[Copy link]

References: packages/ses/src/lockdown-shim.js, packages/ses/src/lockdown.js, packages/ses/src/tame-harden.js

• • •

The repairIntrinsics() function in …/lockdown.js is the core mechanism for securing the JavaScript environment. It performs the following key operations:

Module Handling

[Edit section]

[Copy link]

References: packages/ses/src/module-instance.js, packages/ses/src/module-link.js, packages/ses/src/module-load.js, packages/ses/src/module-proxy.js

• • •

Module handling in the SES environment is primarily managed through three key components:

Secure Evaluation

[Edit section]

[Copy link]

References: packages/ses/src/eval-scope.js, packages/ses/src/make-evaluate.js, packages/ses/src/make-safe-evaluator.js

• • •

The makeSafeEvaluator function in …/make-safe-evaluator.js creates a secure environment for code evaluation. It returns an object with a safeEvaluate method, which serves as the main entry point for executing code safely. Key features include:

Error Handling and Logging

[Edit section]

[Copy link]

References: packages/ses/src/error

Error handling and logging in the SES environment is implemented through several key components:

Configuration and Environment Variables

[Edit section]

[Copy link]

References: packages/ses/docs/lockdown.md

• • •

The SES environment provides a set of configuration options and environment variables that allow developers to fine-tune the security and compatibility of their JavaScript execution context. Among these, the LOCKDOWN_LEGACY_REGENERATOR_RUNTIME_TAMING and LOCKDOWN_HARDEN_TAMING environment variables stand out for their specific roles in adjusting the SES system's behavior.

Uint8Array Enhancements

[Edit section]

[Copy link]

References: packages/ses/src/permits.js

• • •

In …/permits.js, the TypedArray intrinsic object is configured to restrict the available properties and methods, ensuring a secure environment within the SES. This configuration includes enhancements to Uint8Array, a subtype of TypedArray, which is commonly used for binary data handling in JavaScript.

Array Prototype Transfer

[Edit section]

[Copy link]

References: packages/ses

• • •

The Array.prototype.transfer method is emulated on platforms that lack native support but have structuredClone available. This emulation allows for consistent behavior across different environments.

Console Shim

[Edit section]

[Copy link]

References: packages/ses

• • •

The console shim functionality is implemented in …/console-shim.js. This file imports the console shim from …/console-shim.js, providing a separate export for console-related features.

Compartment Mapper

[Edit section]

[Copy link]

References: packages/compartment-mapper

• • •

The compartment-mapper package provides functionality for creating and managing compartment maps, which describe how to construct isolated compartments for each dependency in a Node.js application. This allows granting minimal necessary authority to third-party packages and mitigating security vulnerabilities.

Compartment Map Structure

[Edit section]

[Copy link]

References: packages/compartment-mapper/src/compartment-map.js, packages/compartment-mapper/src/types.js

• • •

The compartment map structure defines the organization of compartments, modules, and their associated properties. The assertCompartmentMap function validates this structure, ensuring it conforms to expected patterns.

Archive Generation and Handling

[Edit section]

[Copy link]

References: packages/compartment-mapper/src/archive-lite.js, packages/compartment-mapper/src/import-archive-lite.js

• • •

Archive generation and handling in the compartment mapper is primarily managed through functions in …/archive-lite.js and …/import-archive-lite.js.

Bundle Creation and Management

[Edit section]

[Copy link]

References: packages/compartment-mapper/src/bundle.js

• • •

The makeBundle() function in …/bundle.js is responsible for creating bundles. It performs the following key steps:

Node Modules Integration

[Edit section]

[Copy link]

References: packages/compartment-mapper/src/node-modules.js

• • •

The compartment mapper integrates with Node.js modules through a set of functions that construct a compartment map capturing reachable packages from an entry module and their relationships. This process involves:

Linking and Compartment Creation

[Edit section]

[Copy link]

References: packages/compartment-mapper/src/link.js

• • •

The link function in …/link.js assembles a directed acyclic graph (DAG) of compartments based on a provided compartment map. It starts with the named entry compartment and builds all dependent compartments. Key aspects of the linking process include:

Capture and Source Management

[Edit section]

[Copy link]

References: packages/compartment-mapper/src/capture-lite.js

• • •

The captureFromMap function in …/capture-lite.js is responsible for capturing compartment map descriptors and sources without creating an archive. This process involves:

ECMAScript Internationalization API

[Edit section]

[Copy link]

References: packages/test262-runner/test262/test/intl402

• • •

The ECMAScript Internationalization API implementation covers various objects and methods for language-sensitive string comparison, number formatting, date and time formatting, and other internationalization features.

Language Features

[Edit section]

[Copy link]

References: packages/test262-runner/test262/test/language/arguments-object, packages/test262-runner/test262/test/language/asi, packages/test262-runner/test262/test/language/eval-code, packages/test262-runner/test262/test/language/expressions, packages/test262-runner/test262/test/language/identifiers, packages/test262-runner/test262/test/language/literals, packages/test262-runner/test262/test/language/module-code, packages/test262-runner/test262/test/language/statements, packages/test262-runner/test262/test/language/types

JavaScript language features are implemented and tested extensively in the …/expressions and …/statements directories. Key aspects include:

Built-in Objects

[Edit section]

[Copy link]

References: packages/test262-runner/test262/test/built-ins

The Promise object implements asynchronous programming functionality in JavaScript. Key features include: