realms-shim

Realm Shim

This folder contains a shim implementation of the Realm API Proposal.

Limitations

The current implementation has 3 main limitations:

• All code evaluated inside a Realm runs in strict mode.
• Direct eval is not supported.
• let, global function declarations and any other feature that relies on new bindings in global contour are not preserved between difference invocations of eval, instead we create a new contour everytime.

Building the Shim

git clone https://github.com/Agoric/realms-shim.git
cd realms-shim
npm install
npm run shim:build

This will install the necessary dependencies and build the shim locally.

Playground

To open the playground example in your default browser:

npm run shim:build
open examples/simple.html

Usage

To use the shim in a webpage, build the shim, then:

  <script src="../dist/realm-shim.min.js"></script>
  <script>
    const r = new Realm();
    [...]
  </script>

To use the shim with node:

  const Realm = require('./realm-shim.min.js');
  const r = new Realm();
  [...]

You can also use the ES6 module version of the Realms shim in Node.js via the package esm. To do that, launch node with esm via the "require" option:

npm install esm
node -r esm main.js

And import the realm module in your code:

  import Realm from './src/realm';
  const r = new Realm();
  [...]

Examples

Example 1: Root Realm

To create a root realm with a new global and a fresh set of intrinsics:

const r = new Realm(); // root realm
r.global === this; // false
r.global.JSON === JSON; // false

Example 2: Realm Compartment

To create a realm compartment with a new global and inherit the intrinsics from another realm:

const r1 = new Realm(); // root realm
const r2 = new r1.global.Realm({ intrinsics: 'inherit' }); // realm compartment
r1.global === r2.global; // false
r1.global.JSON === r2.global.JSON; // true

Example 3: Realm Compartment from current Realm

To create a realm compartment with a new global and inherit the intrinsics from the current execution context:

const r = new Realm({ intrinsics: 'inherit' }); // realm compartment
r.global === this; // false
r.global.JSON === JSON; // true

Bug Disclosure

Please help us practice coordinated security bug disclosure, by using the instructions in SECURITY.md to report security-sensitive bugs privately.

For non-security bugs, please use the regular Issues page.