Merge pull request #1718 from endojs/markm-910-align-w-xs-prop-censor

fix(ses): align with XS property censorship agreement

Author: erights

packages/ses/NEWS.md

@@ -1,5 +1,23 @@
 User-visible changes in SES:
 
+# Next release
+
+- In the SES-shim implementation of HardenedJS, all constructed compartments
+get the same safe `Date`
+constructor, that does not provide the ability to measure duration. It used
+to do this by having `Date.now()` return `NaN`, and to have calls on the
+constructor that would normally have returned an indication of the current date,
+instead return the corresponding invalid date indication. Now, all of these
+throw a `TypeError` whose message begins with `'secure mode'`. This aligns with
+the XS implementation of HardenedJS.
+- Similarly, In the SES-shim implementation of HardenedJS,
+all constructed compartments get the same safe `Math` namespace
+object that does not provide a working `random()` function. It used to do that
+by omitting the `random` property from the safe `Math` namespace object. Now,
+the safe shared `Math` namespace object has a `Math.random()` function that
+throws a `TypeError whose message begins with `'secure mode'`. This again
+aligns with the XS implementation of HardenedJS.
+
 # v0.18.6 (2023-08-07)
 
 - Censors the pattern `{...import(specifier)`}.
@@ -44,7 +62,7 @@ User-visible changes in SES:
 - Fixes a bug for SES initialization in a no-unsafe-eval
   Content-Security-Policy.
 - Fixes a bug where reexport of multiple named exports of the same name was
-  causing them to be overridden by the last value. Now named exports are 
+  causing them to be overridden by the last value. Now named exports are
   handled in the same manner as `export *`.
 - Allows Compatment `importHook` implementations to return aliases: module
   descriptors that refer to a module by its specifier in the same or a

packages/ses/README.md

@@ -194,7 +194,8 @@ c1.globalThis.JSON === c2.globalThis.JSON; // true
 ```
 
 The global scope of every compartment includes a shallow, specialized copy of
-the JavaScript intrinsics, omitting `Date.now` and `Math.random`.
+the JavaScript intrinsics, disabling `Math.random`, `Date.now` and the
+behaviors of the `Date` constructor which would reveal the current time.
 Comaprtments leave these out since they can be used as covert communication
 channels between programs.
 However, a compartment may be expressly given access to these objects
@@ -722,7 +723,7 @@ have found the object capability model that `ses` provides to be sound.
 Hardened JavaScript is also within the scope of the [Agoric bug bounty
 program](https://hackerone.com/agoric), which rewards researchers for surfacing valid
 bugs in our code. We welcome the opportunity to cooperate with researchers,
-whose efforts will undoubtedly yield stronger, more resilient code. 
+whose efforts will undoubtedly yield stronger, more resilient code.
 
 ## Bug Disclosure
 
@@ -768,7 +769,7 @@ provide some place to include text like
 > option.
 > Specifically, [link to source in the project] does not work correctly in such
 > an environment.
-> 
+>
 > Please consider increasing support by replacing assignments to object
 > properties inherited from intrinsics with use of `Object.defineProperties`
 > (thereby working around the JavaScript "override mistake"), and if applicable
@@ -791,4 +792,3 @@ intrinsics, including `ses`.
 [SES proposal]: https://github.com/tc39/proposal-ses
 [SES Strategy Group]: https://groups.google.com/g/ses-strategy
 [SES Strategy Recordings]: https://www.youtube.com/playlist?list=PLzDw4TTug5O1jzKodRDp3qec8zl88oxGd
-

packages/ses/demos/challenge/README.md

@@ -7,12 +7,12 @@ https://ses-demo.agoric.app/demos/challenge/ to run it.
 To avoid relying upon a third party for security, your production applications
 should publish and reference their own copy of `ses.umd.js`.
 
-For local testing, after making a change, run ``yarn build`` to build the
+For local testing, after making a change, run `yarn build` to build the
 generated files. Then, ensure that the demo is pointing towards your generated
-file (i.e.``<script src="../../dist/ses.umd.js"></script> ``). Next, run a web
+file (i.e.`<script src="../../dist/ses.umd.js"></script> `). Next, run a web
 server and serve the entire git tree.  (the demo accesses the generated
-``ROOT/dist/ses.umd.js`` file, so serving just this ``demos/challenge/``
-directory is not enough). 
+`ROOT/dist/ses.umd.js` file, so serving just this `demos/challenge/`
+directory is not enough).
 
 ## Would You Like To Play A Game?
 
@@ -25,13 +25,13 @@ the computer.
 You provide the attacker's program by pasting its source code into the box
 and pressing the Execute button. The attack program is confined in an SES
 environment (shared with the defender), which means it is limited to
-``strict`` mode and has access to the usual ECMAScript intrinsics (Object,
+`strict` mode and has access to the usual ECMAScript intrinsics (Object,
 String, Array, Math, Map, Date (but see below), and so on). But it does not
-have access to platform objects (``window``, ``document``, or ``XHR`` on a
-web browser, or ``require`` on Node.js).
+have access to platform objects (`window`, `document`, or `XHR` on a
+web browser, or `require` on Node.js).
 
 In addition to the intrinsics, the attacker's program gets access to two
-endowments: ``guess(code)`` and ``log(message)``. These are provided by the
+endowments: `guess(code)` and `log(message)`. These are provided by the
 defender.
 
 This source code must evaluate to a generator function (starting with
@@ -45,12 +45,12 @@ function* guessZeros() {
 }
 ```
 
-The attacker uses ``guess()`` to try and guess the launch code. This guess is
+The attacker uses `guess()` to try and guess the launch code. This guess is
 displayed on the bottom panel. When the guess matches the code on the top
 panel, the attacker wins and the game is over. The codes are ten characters
 long, and each character is a capital letter from A to Z, or a digit from 0
-to 9. There are ``36**10`` possibilities (about three quadrillion, or about
-``2**51``, which also happens to be roughly how many ants are alive on Earth
+to 9. There are `36**10` possibilities (about three quadrillion, or about
+`2**51`, which also happens to be roughly how many ants are alive on Earth
 at any given moment). It takes at least a few milliseconds to check each one,
 so brute-force guessing would take thousands of years to try all possible
 combinations.
@@ -76,7 +76,7 @@ script is taking too long" dialog box after maybe 15 seconds of constant
 execution, since it is effectively stuck in an infinite loop.
 
 By using a generator, we can update the UI once per iteration. Thus the
-attack function should call ``guess()`` once, then yield from the generator,
+attack function should call `guess()` once, then yield from the generator,
 then loop back around if it wants to make more guesses. The above program
 should be rewritten like this:
 
@@ -94,39 +94,39 @@ function* counter() {
 
 Despite this quirk, the attacker's program is still essentially being
 evaluated as purely transformational code: the way we load the attacker isn't
-quite as important as the way we allow it to call ``guess()``.
+quite as important as the way we allow it to call `guess()`.
 
 ## Defender
 
 The defender in this game has slightly more power than the attacker: it is
 SES-confined as well, but it gets additional endowments from the setup code.
-One of these is a form of ``getRandomValues`` so it can select a random
+One of these is a form of `getRandomValues` so it can select a random
 target code: SES programs are normally denied access to non-determinism, so
 it would have no way of choosing a different code on each pageload. A few
-more endowments provide control over the DOM: ``setMacguffinText`` sets the
-target code in the top box, ``setAttackerGuess`` sets the guessed code in the
-bottom box, ``setLaunch`` changes the CSS class of the bottom box to change
+more endowments provide control over the DOM: `setMacguffinText` sets the
+target code in the top box, `setAttackerGuess` sets the guessed code in the
+bottom box, `setLaunch` changes the CSS class of the bottom box to change
 the text color when the guess is correct. Note that, for this demo, none of
 these endowments are particularly defensive: the defender code could use them
 to break out of the SES sandbox.
 
-``refreshUI`` returns a Promise that resolves after a ``setTimeout(0)``. This
+`refreshUI` returns a Promise that resolves after a `setTimeout(0)`. This
 yields control back to the browser's UI event queue, giving it a chance to
-repaint the screen with the updated codes. ``log`` simply delivers its
-arguments to the browser's usual ``console.log``.
+repaint the screen with the updated codes. `log` simply delivers its
+arguments to the browser's usual `console.log`.
 
-``delayMS`` performs a busy-wait for the given number of milliseconds by
-polling ``Date.now`` until it reaches some target value.
+`delayMS` performs a busy-wait for the given number of milliseconds by
+polling `Date.now` until it reaches some target value.
 
-We use ``delayMS()`` to introduce an egregious timing-channel vulnerability
-into the defender's ``guess()`` function: it checks the attacker's guess one
+We use `delayMS()` to introduce an egregious timing-channel vulnerability
+into the defender's `guess()` function: it checks the attacker's guess one
 character at a time, waiting a full 10ms between each test, and returns
 immediately upon the first incorrect failure. If the attacker can measure how
-long ``guess()`` takes to run, they can mount a classic timing-oracle attack
+long `guess()` takes to run, they can mount a classic timing-oracle attack
 which runs in linear (rather than exponential) time. A safer form of
-``guess()`` would do a constant-time comparison (for which the most practical
+`guess()` would do a constant-time comparison (for which the most practical
 approach is to just hash both sides and compare the hashes). Our vulnerable
-``guess()`` looks like this:
+`guess()` looks like this:
 
 ```js
 function guess(guessedCode) {
@@ -145,8 +145,8 @@ function guess(guessedCode) {
 }
 ```
 
-The defender creates the ``guess()`` function, then provides it (and ``log``)
-as endowments to the attacker. It invokes ``SES.confine`` to evaluate the
+The defender creates the `guess()` function, then provides it (and `log`)
+as endowments to the attacker. It invokes `SES.confine` to evaluate the
 attacker's code with the endowments as the second argument:
 
 ```js
@@ -156,7 +156,7 @@ function attackerLog(...args) {
 const attacker = SES.confine(program, { guess: guess, log: attackerLog });
 ```
 
-The defender then invokes the attacker in a loop, using ``refreshUI()`` to
+The defender then invokes the attacker in a loop, using `refreshUI()` to
 delay each pass until the UI had a chance to be updated, with something like
 this:
 
@@ -179,20 +179,29 @@ this:
 code right).
 
 
-## Taming Date.now
+## Taming Date and Date.now
 
-The SES environment normally replaces ``Date.now()`` with a function that
-only returns ``NaN``. But ``Date.now()`` can be re-enabled by setting a
-configuration option named ``dateNowMode`` to ``allow``.
+The original standard `Date` constructor provides three ways to obtain the
+current time:
+   * `new Date()` -- calling it as a constructor (with `new`) but
+     with no arguments, returns a date instance representing the current time.
+   * `Date(...)` -- calling it as a function (without `new`) no matter what
+     the arguments may be, returns a string representing the current time.
+   * `Date.now()` -- returns the number of milliseconds since the Unix Epoch
 
-(Note that this API is still in flux, and we might change it in the future.
-One interesting option might be to set ``Date.now`` to return a constant,
-pre-selected value, enabling more code to run mostly-correctly, while still
-limiting its use as an attack vector)
+Because this original `Date` constructor provides the magical I/O power,
+let's call it the "powerful" `Date` constructor. SES leaves this powerful `Date`
+constructor on the original global object, i.e., the global object of the
+start compartment. All compartments other than the start compartment must be
+explicitly created, so those are the "constructed" compartments.
 
-SES replaces the ``new Date()`` constructor with a tamed version that acts as
-if you wrote ``new Date(NaN)``. It does not currently have an option to
-change this behavior, but that will probably change too.
+The challenge code runs in an SES constructed Compartment.
+Within a constructed Compartment, SES normally replaces
+the powerful `Date` constructor with the safe that one that throws a
+`TypeError` in response to the three cases above. But the code in the start
+compartment can explicitly provide the powerful `Date` as an endowment to
+a compartment it constructs, enabling code run in that compartment to sense
+the current time.
 
 By prohibiting access to a clock, we can prevent the attacker code from
 sensing timing-based covert channel. Fully-deterministic execution cannot
@@ -207,14 +216,14 @@ Gruss, and Mangard) enumerates a variety of surprising clocks that might be
 available to Javascript code. They all depend upon forms of non-determinism,
 such as:
 
-* shared-state mutability: a ``WebWorker`` writes sequential integers to a
-  shared ``ArrayBuffer`` as fast as it can, while a second thread simply
+* shared-state mutability: a `WebWorker` writes sequential integers to a
+  shared `ArrayBuffer` as fast as it can, while a second thread simply
   reads from that location when desired
 * platform-provided UI features: initiate a CSS animation and monitor its
   progress
-* message-passing: two separate frames exchange ``postMessage`` calls and
+* message-passing: two separate frames exchange `postMessage` calls and
   compare their arrival order with ones sent to themselves
-* explicit platform features: the ``performance.now()`` call offers
+* explicit platform features: the `performance.now()` call offers
   microsecond-level timing
 
 SES omits all platform features, which removes all the timers listed in this
@@ -226,17 +235,18 @@ interleaved in some nondeterminisic fashion that depends upon the arrival
 times: that ordering can also be used as a clock.
 
 The demo page has two flavors: by changing the URL slightly, the attacker can
-be allowed or denied access to ``Date.now()``. This makes it easy to
+be allowed or denied access to the powerful `Date` constructor.
+This makes it easy to
 demonstrate the success or failure of a timing-based attack.
 
-The first version of this demo implemented ``delayMS()`` with a Promise that
-resolved at some point in the future (via a ``setTimeout()`` callback). In
-that version, ``guess()`` returned a Promise. Richard Gibson exploited this
+The first version of this demo implemented `delayMS()` with a Promise that
+resolved at some point in the future (via a `setTimeout()` callback). In
+that version, `guess()` returned a Promise. Richard Gibson exploited this
 in a [clever attack](https://github.com/endojs/endo/issues/191) that submitted
 multiple guesses in parallel and sensed the order of their resolution: it
-didn't reveal exactly how long ``guess()`` took, but knowing which guess took
+didn't reveal exactly how long `guess()` took, but knowing which guess took
 the longest was enough to mount the attack. We thought we were only using
-``setTimeout()`` for internal purposes, but by exposing a function that used
+`setTimeout()` for internal purposes, but by exposing a function that used
 it, we accidentally gave the attacker code enough tools to build a clock of
 their own.
 

packages/ses/demos/challenge/index.html

@@ -38,8 +38,8 @@ <h1>Hardened JavaScript Escape Room</h1>
     Compartment (the one that ran <code>lockdown()</code>), so this attacker
       doesn’t get a clock, and cannot read from the covert channel. Load this page
       <a href="?dateNow=enabled">with ?dateNow=enabled</a> to demonstrate the
-      attack with <code>Date.now</code> enabled, or <a href="?dateNow=NaN">with
-      ?dateNow=NaN</a> to properly confine the attacker.</p>
+      attack with <code>Date.now</code> enabled, or <a href="?dateNow=disabled">with
+      ?dateNow=disabled</a> to properly confine the attacker.</p>
       <p>The defender running in the start Compartment gets access to powerful JS
       globals.  This includes sources of non-determinism like
       <code>window.setTimeout</code> and

packages/ses/docs/draft-standalone-spec.md

@@ -26,10 +26,18 @@ the default configuration of SES are
  * Omit annex B (except those our whitelist allows)
  * In particular, omit the `RegExp` static properties that provide a global
    communications channel.
- * Omit `Math.random()`
- * Omit ambient access to current date/time:
-   * `Date.now()` returns `NaN`
-   * `new Date()` return equivalent of `new Date(NaN)`
+ * On the `Math` namespace object shared by constructed compartments:
+   - `Math.random()` throws a `TypeError` rather than provide a random number,
+     which would be a source of non-determinism.
+ * On the `Date` constructor shared by constructed compartments:
+   - `Date.now()` throws a `TypeError` rather than returning the millisecods
+     representing the current time.
+   - `new Date()`, calling it as a constructor (with `new`) with no arguments,
+     throws a `TypeError` rather than returning a date instance
+     representing the current time.
+   - `Date(...)`, calling it as a function (without `new`) no matter what
+     the arguments, throws a `TypeError` rather than a string presenting
+     the current time.
  * By default, omit `Intl`, the internationalization APIs
  * If some of `Intl` is included, it must suppress ambient authority and
    non-determinism.

packages/ses/docs/guide.md

@@ -160,11 +160,16 @@ defines a subset of the globals defined by the baseline JavaScript language spec
 - `BigInt`
 - `Intl`
 - `Math` all features except
-  - `Math.random()` is disabled (calling it throws an error) as an obvious source of
-     non-determinism.
+  - `Math.random()` throws a `TypeError` rather than provide a random number, which would be a source of non-determinism.
 - `Date` all features except
-  - `Date.now()` returns `NaN`
-  - `new Date(nonNumber)` or `Date(anything)` return a `Date` that stringifies to `"Invalid Date"`
+  - `Date.now()` throws a `TypeError` rather than returning the millisecods
+    representing the current time.
+  - `new Date()`, calling it as a constructor (with `new`) with no arguments,
+    throws a `TypeError` rather than returning a date instance
+    representing the current time.
+  - `Date(...)`, calling it as a function (without `new`) no matter what
+    the arguments, throws a `TypeError` rather than a string presenting
+    the current time.
 
 Much of the `Intl` package, and some other objects' locale-specific aspects (e.g. `Number.prototype.toLocaleString`)
 have results that depend upon which locale is configured. This varies from one process to another.
@@ -327,8 +332,10 @@ c1.globalThis === c2.globalThis; // false
 c1.globalThis.JSON === c2.globalThis.JSON; // true
 ```
 Every compartment's global scope includes a shallow, specialized copy of the JavaScript
-intrinsics. These omit `Date.now()` and `Math.random()`
-since they can be covert inter-program communication channels.
+intrinsics. These disable `Math.random()`, `Date.now()`, and the behaviors of
+the `Date` constructor which would provide the current time,
+since all these sources of non-determinism can enable covert inter-program
+communication channels.
 
 However, a compartment may be expressly given access to these objects through
 the compartment constructor's first argument or by assigning them to the