Nefariously Programmed Mecha

    This version has been deprecated

    Author message:

    TC39 has taken Realms in a new direction (ShadowRealm) and the security properties of the realms-shim have not been maintained.

    realms-shim

    1.2.1 • Public • Published

    Realm Shim

    Build Status Coverage Status dependency status dev dependency status License

    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.

    Install

    npm i realms-shim@1.2.1

    Version

    1.2.1

    License

    Apache-2.0

    Unpacked Size

    639 kB

    Total Files

    18

    Last publish

    Collaborators

    • erights
    • katesills
    • kriskowal
    • michaelfig
    • warner