Surface SES on globalThis

packages/ses-integration-test/package.json

@@ -11,9 +11,9 @@
     "depcheck": "depcheck",
     "lint": "eslint '**/*.js'",
     "lint-fix": "eslint --fix '**/*.js'",
-    "create-test-file-no-lib-cjs": "rollup --no-treeshake -c transform-tests/config/rollup.config.no-lib.js",
     "test:pre-release": "node -r esm puppeteer-test/pre-release.test.js",
     "test:post-release": "node -r esm puppeteer-test/post-release.test.js",
+    "create-test-file-no-lib-cjs": "rollup --no-treeshake -c transform-tests/config/rollup.config.no-lib.js",
     "create-test-file-esm": "rollup --no-treeshake -c transform-tests/config/rollup.config.esm.js",
     "create-test-file-cjs": "rollup --no-treeshake -c transform-tests/config/rollup.config.cjs.js",
     "create-test-file-browserified-tape": "browserify transform-tests/output/test.no-lib.cjs.js > transform-tests/output/test.tape-no-lib.js --exclude 'ses' --ignore-missing",

packages/ses-integration-test/scaffolding/rollup/rollup.config.test.js

@@ -7,8 +7,7 @@ export default [
     output: [
       {
         file: path.resolve(__dirname, "../../bundles/rollup.js"),
-        format: "iife",
-        name: "SES"
+        format: "iife"
       }
     ],
     plugins: [

packages/ses-integration-test/test/sanity.test.js

@@ -1,10 +1,10 @@
-/* global Compartment */
+/* global Compartment, lockdown */
 import test from "tape";
 
-import * as SES from "ses";
+import "ses";
 
 test("sanity", t => {
-  t.equal(SES.lockdown(), true, "lockdown runs successfully");
+  t.equal(lockdown(), true, "lockdown runs successfully");
   const c = new Compartment();
   t.equal(c.evaluate("123"), 123, "simple evaluate succeeds");
   t.equal(

packages/ses-integration-test/transform-tests/config/rollup.config.no-lib.js

@@ -15,7 +15,7 @@ export default [
     plugins: [
       replace({
         delimiters: ["", ""],
-        'import * as SES from "ses";': ""
+        'import "ses";': ""
       }),
       resolve({
         only: ["@agoric/nat"]

packages/ses/NEWS.md

@@ -2,11 +2,19 @@ User-visible changes in SES:
 
 ## Next release
 
+* Adds support for modules to Compartments.
+* SES no longer exports anything.
+  `Compartment`, `ModuleStaticRecord`, `lockdown`, and `harden` are all
+  introduced as properties of `globalThis`.
+* The `Compartment` `global` getter is now named `globalThis`, consistent with
+  the specification proposal.
 * Repair `Function.apply` and `TypeError.message` (as well as `.message` on
   all the other Error types), to tolerate what the npm `es-abstract` module
   does. This allows `tape` (version 4.x) to be loaded in a locked-down SES
   world, and also allows its `t.throws` assertion to work. `tape` (version
-  5.x) still has problems. (#293)
+  5.x) still has problems. [#293]
+
+  [#293]: https://github.com/Agoric/SES-shim/issues/293)
 
 ## Release 0.7.7 (27-Apr-2020)
 

packages/ses/README.md

@@ -27,69 +27,130 @@ npm install ses
 
 ## Usage
 
-### Module
+### Lockdown
 
-This example locks down the current realm, turning it into a starting
-compartment.
-Within a compartment, there is a `Compartment` constructor that conveys
-"endownments" into the new compartment's global scope, and a `harden` method
-that that object and any object reachable from its surface.
-The compartment can import modules and evaluate programs.
+SES introduces the `lockdown()` function.
+Calling `lockdown()` alters the surrounding execution enviornment, or
+**realm**, such that no two programs running in the same realm can observe or
+interfere with each other until they have been introduced.
+
+To this end, `lockdown()` freezes all objects accessible to any program in the
+realm.
+The set of accessible objects includes but is not limited to: `globalThis`,
+`[].__proto__`, `{}.__proto__`, `(() => {}).__proto__` `(async () =>
+{}).__proto__`, and the properties of any accessible object.
+
+The `lockdown()` function also **tames** some of those accessible objects
+that have powers that would otherwise allow programs to observe or interfere
+with one another like clocks, random number generators, and regular
+expressions.
+
+```js
+import 'ses';
+import 'my-vetted-shim';
+
+lockdown();
+
+console.log(Object.isFrozen([].__proto__));
+// true
+```
+
+### Harden
+
+SES introduces the `harden` function.
+*After* calling `lockdown`, the `harden` function ensures that every object in
+the transitive closure over property and prototype access starting with that
+object has been **frozen** by `Object.freeze`.
+This means that the object can be passed among programs and none of those
+programs will be able to tamper with the **surface** of that object graph.
+They can only read the surface data and call the surface functions.
 
 ```js
-import {lockdown} from "ses";
+import 'ses';
 
 lockdown();
 
+let counter = 0;
+const capability = harden({
+  inc() {
+    counter++;
+  },
+});
+
+console.log(Object.isFrozen(capability));
+// true
+console.log(Object.isFrozen(capability.inc));
+// true
+```
+
+Note that although the **surface** of the capability is frozen, the capability
+still closes over the mutable counter.
+Hardening an object graph makes the surface immutable, but does not make
+methods pure.
+
+
+### Compartment
+
+SES introduces the `Compartment` constructor.
+A compartment is an evaluation and execution environment with its own
+`globalThis` and wholly independent system of modules, but otherwise shares
+the same batch of intrinsics like `Array` with the surrounding compartment.
+The concept of a compartment implies the existence of a "start compartment",
+the initial execution environment of a **realm**.
+
+In the following example, we create a compartment endowed with a `print()`
+function on `globalThis`.
+
+```js
+import 'ses';
+
 const c = new Compartment({
-    print: harden(console.log),
+  print: harden(console.log),
 });
 
 c.evaluate(`
-    print("Hello! Hello?");
+  print('Hello! Hello?');
 `);
 ```
 
 The new compartment has a different global object than the start compartment.
 The global object is initially mutable.
-Locking down the start compartment hardened many of the intrinsics in global
-scope.
-After lockdown, no compartment can tamper with these intrinsics.
-Many of these intrinsics are identical in the new compartment.
+Locking down the realm hardened the objects in global scope.
+After `lockdown`, no compartment can tamper with these **intrinsics** and
+**undeniable** objects.
+Many of these are identical in the new compartment.
 
 ```js
 const c = new Compartment();
-c.global === global; // false
-c.global.JSON === JSON; // true
+c.globalThis === globalThis; // false
+c.globalThis.JSON === JSON; // true
 ```
 
-The property holds among any other compartments.
+Other pairs of compartments also share many identical intrinsics and undeniable
+objects of the realm.
 Each has a unique, initially mutable, global object.
-Many intrinsics are shared.
 
 ```js
 const c1 = new Compartment();
 const c2 = new Compartment();
-c1.global === c2.global; // false
-c1.global.JSON === c2.global.JSON; // true
+c1.globalThis === c2.globalThis; // false
+c1.globalThis.JSON === c2.globalThis.JSON; // true
 ```
 
-### Compartments
-
 Any code executed within a compartment shares a set of module instances.
 For modules to work within a compartment, the creator must provide
 a `resolveHook` and an `importHook`.
 The `resolveHook` determines how the compartment will infer the full module
-specifier for another module from a referrer module and the module specifier
-imported within that module.
-The `importHook` accepts a module specifier and asynchronously returns a
+specifier for another module from a referrer module and the import specifier.
+The `importHook` accepts a full specifier and asynchronously returns a
 `ModuleStaticRecord` for that module.
 
 ```js
-import { Compartment, ModuleStaticRecord } from 'ses';
+import 'ses';
+
 const c1 = new Compartment({}, {}, {
   resolveHook: (moduleSpecifier, moduleReferrer) => {
-    return new URL(moduleSpecifier, moduleReferrer).toString();
+    return resolve(moduleSpecifier, moduleReferrer);
   },
   importHook: async moduleSpecifier => {
     const moduleLocation = locate(moduleSpecifier);
@@ -101,14 +162,14 @@ const c1 = new Compartment({}, {}, {
 
 A compartment can also link a module in another compartment.
 Each compartment has a `module` function that accepts a module specifier
-and returns the ModuleNamespace for that module.
-The ModuleNamespace is not useful for inspecting the exports of the
+and returns the module exports namespace for that module.
+The module exports namespace is not useful for inspecting the exports of the
 module until that module has been imported, but it can be passed into the
 module map of another Compartment, creating a link.
 
 ```js
 const c2 = new Compartment({}, {
-  'https://example.com/packages/example/': c1.module('./main.js'),
+  'c1': c1.module('./main.js'),
 }, {
   resolveHook,
   importHook,

packages/ses/src/intrinsic-names.js

@@ -146,5 +146,7 @@ export const intrinsicNames = [
   'FunctionPrototypeConstructor',
   'Compartment',
   'CompartmentPrototype',
+  'ModuleStaticRecord',
+  'ModuleStaticRecordPrototype',
   'harden',
 ];

packages/ses/src/intrinsics-global.js

@@ -94,7 +94,9 @@ const globalIntrinsicNames = [
 
   'globalThis',
   'Compartment',
+  'CompartmentPrototype',
   'ModuleStaticRecord',
+  'ModuleStaticRecordPrototype',
   'harden',
 ];
 

packages/ses/src/lockdown-shim.js

@@ -14,6 +14,7 @@
 
 import makeHardener from '@agoric/make-hardener';
 
+import { assert } from './assert.js';
 import { getIntrinsics } from './intrinsics.js';
 import whitelistIntrinsics from './whitelist-intrinsics.js';
 import repairLegacyAccessors from './repair-legacy-accessors.js';
@@ -23,25 +24,29 @@ import tameGlobalDateObject from './tame-global-date-object.js';
 import tameGlobalErrorObject from './tame-global-error-object.js';
 import tameGlobalMathObject from './tame-global-math-object.js';
 import tameGlobalRegExpObject from './tame-global-reg-exp-object.js';
-
 import enablePropertyOverrides from './enable-property-overrides.js';
-import { Compartment } from './compartment-shim.js';
 
 let previousOptions;
 
-function assert(condition, message) {
-  if (!condition) {
-    throw new TypeError(message);
-  }
-}
+// A successful lockdown call indicates that `harden` can be called and
+// guarantee that the hardened object graph is frozen out to the fringe.
+let lockedDown = false;
+
+// Build a harden() with an empty fringe.
+// Gate it on lockdown.
+const lockdownHarden = makeHardener();
+
+export const harden = ref => {
+  assert(lockedDown, `Cannot harden before lockdown`);
+  return lockdownHarden(ref);
+};
 
 export function lockdown(options = {}) {
   const {
     noTameDate = false,
     noTameError = false,
     noTameMath = false,
     noTameRegExp = false,
-    registerOnly = false,
     ...extraOptions
   } = options;
 
@@ -60,7 +65,6 @@ export function lockdown(options = {}) {
     noTameError,
     noTameMath,
     noTameRegExp,
-    registerOnly,
   };
   if (previousOptions) {
     // Assert that multiple invocation have the same value
@@ -88,30 +92,7 @@ export function lockdown(options = {}) {
   tameGlobalRegExpObject(noTameRegExp);
 
   /**
-   * 2. SHIM to expose the proposed APIs.
-   */
-
-  // Build a harden() with an empty fringe.
-  const harden = makeHardener();
-
-  // Add the API to the global object.
-  Object.defineProperties(globalThis, {
-    harden: {
-      value: harden,
-      configurable: true,
-      writable: true,
-      enumerable: false,
-    },
-    Compartment: {
-      value: Compartment,
-      configurable: true,
-      writable: true,
-      enumerable: false,
-    },
-  });
-
-  /**
-   * 3. WHITELIST to standardize the environment.
+   * 2. WHITELIST to standardize the environment.
    */
 
   // Extract the intrinsics from the global.
@@ -124,16 +105,22 @@ export function lockdown(options = {}) {
   repairLegacyAccessors();
 
   /**
-   * 4. HARDEN to share the intrinsics.
+   * 3. HARDEN to share the intrinsics.
    */
 
   // Circumvent the override mistake.
   const detachedProperties = enablePropertyOverrides(intrinsics);
 
   // Finally register and optionally freeze all the intrinsics. This
   // must be the operation that modifies the intrinsics.
-  harden(intrinsics, registerOnly);
-  harden(detachedProperties, registerOnly);
+  lockdownHarden(intrinsics);
+  lockdownHarden(detachedProperties);
+
+  // Having completed lockdown without failing, the user may now
+  // call `harden` and expect the object's transitively accessible properties
+  // to be frozen out to the fringe.
+  // Raise the `harden` gate.
+  lockedDown = true;
 
   // Returning `true` indicates that this is a JS to SES transition.
   return true;

packages/ses/src/main.js

@@ -12,5 +12,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-export { lockdown } from './lockdown-shim.js';
-export { Compartment, ModuleStaticRecord } from './compartment-shim.js';
+import { lockdown, harden } from './lockdown-shim.js';
+import { Compartment, ModuleStaticRecord } from './compartment-shim.js';
+
+Object.assign(globalThis, {
+  lockdown,
+  harden,
+  Compartment,
+  ModuleStaticRecord,
+});

packages/ses/test/compartment.test.js

@@ -1,6 +1,6 @@
-/* global Compartment */
+/* global Compartment, lockdown */
 import test from 'tape';
-import { lockdown } from '../src/lockdown-shim.js';
+import '../src/main.js';
 
 lockdown();