{"id":13517019,"url":"https://github.com/Agoric/realms-shim","last_synced_at":"2025-03-31T07:30:44.785Z","repository":{"id":45074965,"uuid":"176340639","full_name":"Agoric/realms-shim","owner":"Agoric","description":"Spec-compliant shim for Realms TC39 Proposal","archived":false,"fork":false,"pushed_at":"2023-07-07T11:13:33.000Z","size":1316,"stargazers_count":350,"open_issues_count":26,"forks_count":19,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-03-21T11:09:10.053Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Agoric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-03-18T17:52:53.000Z","updated_at":"2025-03-13T04:22:45.000Z","dependencies_parsed_at":"2024-01-10T10:12:04.819Z","dependency_job_id":null,"html_url":"https://github.com/Agoric/realms-shim","commit_stats":{"total_commits":350,"total_committers":22,"mean_commits":"15.909090909090908","dds":0.6542857142857144,"last_synced_commit":"e3e43e54f1c89cd671d2f826c05a6eff199c5444"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agoric%2Frealms-shim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agoric%2Frealms-shim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agoric%2Frealms-shim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agoric%2Frealms-shim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Agoric","download_url":"https://codeload.github.com/Agoric/realms-shim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246026111,"owners_count":20711580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T05:01:28.613Z","updated_at":"2025-03-31T07:30:44.756Z","avatar_url":"https://github.com/Agoric.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Realms Shim : OBSOLETE, INSECURE, NOT RECOMMENDED FOR USE\n\n[![License][license-image]][license-url]\n\nThis repository contains a legacy shim implementation of an outdated [Realm API Proposal](https://github.com/tc39/proposal-realms/tree/ff7583930ed67dda603b59e343b3ed85ac741d35#ecmascript-spec-proposal-for-realms-api). \n\nThe Realms proposal has been superceded by the [ShadowRealm Proposal](https://github.com/tc39/proposal-shadowrealm/). This shim does not implement ShadowRealm, which (as of this writing) is a proposal at Stage 3 of the TC39 standardization process, so common JS engines should have support soon.\n\nWe do not recommend the use of this shim or the original Realms approach. While the Realm API allows the user to create a new set of independent built-ins (intrinsics), this cannot be used for isolation or security properties without either freezing those intrinsics or hiding them behind a Membrane. The shim provides no mechanism to do either, and both are non-trivial to implement. Without those, when two mutually-suspicious Realms are communicating, both must be extremely careful to prevent any object leakage, otherwise one Realm can pollute the globals or intrinsics of the other.\n\nShadowRealms defines a \"callable boundary\" which prevents objects from passing through, mitigating this danger.\n\nIn general, we recommend the use of alternate isolation tools like [Endo](https://github.com/endojs/endo/) and the related/embedded SES/HardenedJS environment. This provides `lockdown()` to tame the environment at startup, and the `Compartment` constructor to create evaluation compartments with independent (and potentially frozen) globals. In our experience with the [Agoric SDK](https://github.com/Agoric/agoric-sdk), we find Endo to be much safer and easier to use securely.\n\n\n## Limitations\n\nThe current implementation has 3 main limitations:\n\n* All code evaluated inside a Realm runs in strict mode.\n* Direct eval is not supported.\n* `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.\n\n## Building the Shim\n\n```bash\ngit clone https://github.com/Agoric/realms-shim.git\ncd realms-shim\nnpm install\nnpm run shim:build\n```\n\nThis will install the necessary dependencies and build the shim locally.\n\n## Playground\n\nTo open the playground example in your default browser:\n\n```bash\nnpm run shim:build\nopen examples/simple.html\n```\n\n## Usage\n\nTo use the shim in a webpage, build the shim, then:\n\n```html\n  \u003cscript src=\"../dist/realm-shim.min.js\"\u003e\u003c/script\u003e\n  \u003cscript\u003e\n    const r = new Realm();\n    [...]\n  \u003c/script\u003e\n```\n\nTo use the shim with node:\n```js\n  const Realm = require('./realm-shim.min.js');\n  const r = new Realm();\n  [...]\n```\n\nYou 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:\n\n```bash\nnpm install esm\nnode -r esm main.js\n```\n\nAnd import the realm module in your code:\n\n```js\n  import Realm from './src/realm';\n  const r = new Realm();\n  [...]\n```\n\n## Examples\n\n### Example 1: Root Realm\n\nTo create a root realm with a new global and a fresh set of intrinsics:\n\n```js\nconst r = new Realm(); // root realm\nr.global === this; // false\nr.global.JSON === JSON; // false\n```\n\n### Example 2: Realm Compartment\n\nTo create a realm compartment with a new global and inherit the intrinsics from another realm:\n\n```js\nconst r1 = new Realm(); // root realm\nconst r2 = new r1.global.Realm({ intrinsics: 'inherit' }); // realm compartment\nr1.global === r2.global; // false\nr1.global.JSON === r2.global.JSON; // true\n```\n\n### Example 3: Realm Compartment from current Realm\n\nTo create a realm compartment with a new global and inherit the intrinsics from the current execution context:\n\n```js\nconst r = new Realm({ intrinsics: 'inherit' }); // realm compartment\nr.global === this; // false\nr.global.JSON === JSON; // true\n```\n\n\n[license-image]: https://img.shields.io/badge/License-Apache%202.0-blue.svg\n[license-url]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAgoric%2Frealms-shim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAgoric%2Frealms-shim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAgoric%2Frealms-shim/lists"}