Implement ShadowRealm Built-in Object (TC39 Stage 2.7)

[ParthMozarkar]

This issue proposes implementing the ShadowRealm built-in object as described in the ECMAScript proposal maintained by TC39.

ShadowRealm introduces a mechanism to execute JavaScript code in a separate, fully isolated global environment while still running synchronously within the same engine instance. This enables secure code evaluation without the overhead of creating workers or separate processes.

This feature is useful for several use cases including:

• Secure plugin systems
• Sandboxed execution of untrusted code
• Library isolation
• Testing environments
• Dynamic code evaluation

Implementing ShadowRealm in Boa would improve ECMAScript feature coverage and provide a lightweight isolation mechanism that fits well with Boa’s architecture.

Proposed Implementation

The implementation would include the following components:

1. ShadowRealm Constructor

Implement the ShadowRealm constructor and attach it to the global object.

Example usage:

const realm = new ShadowRealm();

2. ShadowRealm.prototype.evaluate(sourceText)

This method evaluates JavaScript source code inside the isolated realm and returns the result of the evaluation.

Example:

const realm = new ShadowRealm();
const result = realm.evaluate("1 + 2");
console.log(result); // 3

3. ShadowRealm.prototype.importValue(specifier, name)

This method loads a module inside the realm and returns a Promise that resolves to the exported value.

Example:

const value = await realm.importValue("./module.js", "myExport");

4. Realm Integration

Boa already has Realm and Context abstractions that can be leveraged to implement ShadowRealm.

The new realm should:

• Create a separate global object
• Have isolated intrinsics
• Prevent sharing of objects between realms
• Share the same underlying engine instance

5. Callable Masking (Wrapped Function Objects)

Functions crossing the boundary between realms must be wrapped according to the ShadowRealm specification.

This ensures:

• Calls are safely forwarded across realms
• Internal objects are not exposed
• Realm isolation is preserved

This would require implementing the ShadowRealm Wrapped Function Object algorithm.

6. Value Marshalling

Only certain values should be allowed to cross the realm boundary.

Allowed:

• Primitive values
• Wrapped functions

Disallowed:

• Objects
• Arrays
• Host objects

This prevents state leakage between realms and maintains strict isolation.

Specification

ShadowRealm proposal:
https://github.com/tc39/proposal shadowrealm

Motivation

Implementing ShadowRealm would improve Boa’s compliance with evolving ECMAScript features and provide an important mechanism for secure and isolated code execution. This capability is particularly valuable for embedding scenarios where sandboxing is required.

Possible Implementation Steps

1. Implement ShadowRealm constructor
2. Create isolated realm instances using existing Boa infrastructure
3. Implement evaluate() method
4. Implement importValue() method
5. Implement wrapped function objects
6. Implement value marshalling rules
7. Add tests and documentation

[ParthMozarkar]

Hi! I’m interested in working on implementing this feature. I’ve been studying Boa’s Realm and Context infrastructure and the ShadowRealm proposal specification.

If the maintainers think this would be a suitable contribution, I would love to work on it and start drafting a detailed implementation plan. Any guidance or suggestions on the approach would be greatly appreciated.

[ParthMozarkar]

Hi! I’ve opened a Draft PR with an initial implementation of the ShadowRealm built-in.

The current implementation includes the constructor and basic realm isolation through ShadowRealm.prototype.evaluate, along with unit tests verifying the behavior.

The PR is still a work in progress. I plan to continue implementing the remaining parts of the proposal, including callable masking and importValue.

I would really appreciate any early feedback on the current approach and integration.

Draft PR: #5077