feat(ses): hostEvaluators lockdown option

Author: leotm

packages/ses/docs/lockdown.md

@@ -30,6 +30,7 @@ Each option is explained in its own section below.
 | `reporting`                      | `'platform'`     | `'console'` `'none'`                   | where to report warnings ([details](#reporting-options))
 | `unhandledRejectionTrapping`     | `'report'`       | `'none'`                               | handling of finalized unhandled rejections ([details](#unhandledrejectiontrapping-options)) |
 | `evalTaming`                     | `'safeEval'`     | `'unsafeEval'` `'noEval'`              | `eval` and `Function` of the start compartment ([details](#evaltaming-options)) |
+| `hostEvaluators`                 | `'all'`          | `'none'` `'no-direct'`                 | handling of sloppy and indirect eval ([details](#hostevaluators-options)) |
 | `stackFiltering`                 | `'concise'`      | `'verbose'`                            | deep stacks signal/noise   ([details](#stackfiltering-options)) |
 | `overrideTaming`                 | `'moderate'`     | `'min'` or `'severe'`                  | override mistake antidote  ([details](#overridetaming-options)) |
 | `overrideDebug`                  | `[]`             | array of property names                | detect override mistake    ([details](#overridedebug-options)) |
@@ -51,6 +52,7 @@ for threading environment variables into a JavaScript program.
 | `reporting`                      | `LOCKDOWN_REPORTING`                         |                       |
 | `unhandledRejectionTrapping`     | `LOCKDOWN_UNHANDLED_REJECTION_TRAPPING`      |                       |
 | `evalTaming`                     | `LOCKDOWN_EVAL_TAMING`                       |                       |
+| `hostEvaluators`                 | `LOCKDOWN_HOST_EVALUATORS`                   |                       |
 | `stackFiltering`                 | `LOCKDOWN_STACK_FILTERING`                   |                       |
 | `overrideTaming`                 | `LOCKDOWN_OVERRIDE_TAMING`                   |                       |
 | `overrideDebug`                  | `LOCKDOWN_OVERRIDE_DEBUG`                    | comma separated names |
@@ -463,7 +465,7 @@ the container to exit explicitly, and we highly recommend setting
 
 ## `reporting` Options
 
-**Background**: Lockdown and `repairIntrinsics` report warnings if they
+**Background**: `lockdown` and `repairIntrinsics` report warnings if they
 encounter unexpected but repairable variations on the shared intrinsics, which
 regularly occurs if the version of `ses` predates the introduction of new
 language features.
@@ -617,6 +619,58 @@ LOCKDOWN_EVAL_TAMING=noEval
 LOCKDOWN_EVAL_TAMING=unsafeEval
 ```
 
+## `hostEvaluators` Options
+
+**Background**: Hermes is a JavaScript engine that does not yet support direct `eval()` nor the `with` statement. The SES `evalTaming` default option `"safeEval"` uses multiple nested `with` statements to create a restricted scope chain, so on Hermes we must run under the `"unsafeEval"` option. However SES cannot initialize unless 'eval' is the original intrinsic 'eval', suitable for direct-eval (dynamically scoped eval), which is where we introduce the `hostEvaluators` option `"no-direct"`.
+
+```js
+lockdown(); // Warn user to set `hostEvaluators`, which will soon default to 'all' (breaking change with a strict Content Security Policy)
+// or
+lockdown({ hostEvaluators: 'all' }); // SES fails to initialize if direct-eval is not the original intrinsic 'eval'
+// vs
+lockdown({ hostEvaluators: 'none' }); // SES initializes when evaluators are not allowed to execute (e.g. a strict CSP)
+// vs
+lockdown({ hostEvaluators: 'no-direct' }); // SES initializes without direct-eval (e.g. on Hermes)
+```
+
+Further
+
+* `'all'`: asserts evaluators are allowed to execute
+* `'none'`: asserts evaluators are _not_ allowed to execute
+* `'no-direct'`: asserts direct-eval is available
+
+Hermes example
+
+```js
+lockdown({ evalTaming: 'unsafeEval', hostEvaluators: 'no-direct' }); // Both options required on Hermes to initialize SES
+```
+
+If `lockdown` does not receive a `hostEvaluators` option, it will respect
+`process.env.LOCKDOWN_HOST_EVALUATORS`.
+
+```console
+LOCKDOWN_HOST_EVALUATORS=all
+LOCKDOWN_HOST_EVALUATORS=none
+LOCKDOWN_HOST_EVALUATORS=no-direct
+```
+
+Once Hermes engine supports direct-eval, `'no-direct'` will no longer be required. Currently there is an open feature request and open pull request targetting Static Hermes.
+
+* https://github.com/facebook/hermes/issues/957
+  * https://github.com/facebook/hermes/pull/1515
+
+You can also test and verify `lockdown` completing on this change by building and running Hermes on the following fork for example:
+https://github.com/leotm/hermes/tree/ses-lockdown-test-static-hermes-compiler-vm
+
+Once Hermes engine the the `with` statement, `evalTaming: 'safeEval'` will be possible.
+
+* https://github.com/facebook/hermes/issues/1056
+  * https://github.com/facebook/hermes/pull/1571
+
+There is also an open alternate idea to sandbox Compartment _without_ the `with` statement.
+
+* https://github.com/endojs/endo/discussions/1944
+
 ## `stackFiltering` Options
 
 **Background**: The error stacks shown by many JavaScript engines are

packages/ses/error-codes/SES_DIRECT_EVAL.md

@@ -3,7 +3,19 @@
 The SES Hardened JavaScript shim captures the `eval` function when it is
 initialized.
 The `eval` function it finds must be the original `eval` because SES uses its
-dynamic scope to implement its isolated eval. 
+dynamic scope to implement its isolated eval.
 
 If you see this error, something running before `ses` initialized, most likely
 another instance of `ses`, has replaced `eval` with something else.
+
+If you're running under an environment that doesn't support direct eval (Hermes), try setting `hostEvaluators` to `no-direct`.
+
+If you're running under CSP, try setting `hostEvaluators` to `none`.
+
+# _hostEvaluators_ was set to _none_, but evaluators are not blocked (`SES_DIRECT_EVAL`)
+
+It seems your CSP allows execution of `eval()`, try setting `hostEvaluators` to `all` or `no-direct`.
+
+# `"hostEvaluators" was set to "no-direct", but direct eval is functional
+
+If evaluators are working, if seems you've upgraded host to a version that now supports them (future Hermes).

packages/ses/src/compartment.js

@@ -213,6 +213,7 @@ defineProperties(InertCompartment, {
  * @param {object} [options]
  * @param {Compartment} [options.parentCompartment]
  * @param {boolean} [options.enforceNew]
+ * @param {string} [options.hostEvaluators]
  * @returns {Compartment['constructor']}
  */
 
@@ -270,7 +271,12 @@ export const makeCompartmentConstructor = (
   targetMakeCompartmentConstructor,
   intrinsics,
   markVirtualizedNativeFunction,
-  { parentCompartment = undefined, enforceNew = false } = {},
+  // eslint-disable-next-line default-param-last
+  {
+    parentCompartment = undefined,
+    enforceNew = false,
+    hostEvaluators = undefined,
+  } = {},
 ) => {
   function Compartment(...args) {
     if (enforceNew && new.target === undefined) {
@@ -326,6 +332,18 @@ export const makeCompartmentConstructor = (
       sloppyGlobalsMode: false,
     });
 
+    let evaluator;
+
+    if (hostEvaluators === 'no-direct') {
+      evaluator = () => {
+        throw TypeError(
+          'Compartment evaluation not supported without direct eval.',
+        );
+      };
+    } else {
+      evaluator = safeEvaluate;
+    }
+
     setGlobalObjectMutableProperties(globalObject, {
       intrinsics,
       newGlobalPropertyNames: sharedGlobalPropertyNames,
@@ -337,7 +355,7 @@ export const makeCompartmentConstructor = (
     // TODO: maybe add evalTaming to the Compartment constructor 3rd options?
     setGlobalObjectEvaluators(
       globalObject,
-      safeEvaluate,
+      evaluator,
       markVirtualizedNativeFunction,
     );
 

packages/ses/src/global-object.js

@@ -19,7 +19,7 @@ import { constantProperties, universalPropertyNames } from './permits.js';
  * guest programs, we cannot emulate the proper behavior.
  * With this shim, assigning Symbol.unscopables causes the given lexical
  * names to fall through to the terminal scope proxy.
- * But, we can install this setter to prevent a program from proceding on
+ * But, we can install this setter to prevent a program from proceeding on
  * this false assumption.
  *
  * @param {object} globalObject
@@ -75,6 +75,7 @@ export const setGlobalObjectConstantProperties = globalObject => {
  * @param {Function} args.makeCompartmentConstructor
  * @param {(object) => void} args.markVirtualizedNativeFunction
  * @param {Compartment} [args.parentCompartment]
+ * @param {string} [args.hostEvaluators]
  */
 export const setGlobalObjectMutableProperties = (
   globalObject,
@@ -84,6 +85,7 @@ export const setGlobalObjectMutableProperties = (
     makeCompartmentConstructor,
     markVirtualizedNativeFunction,
     parentCompartment,
+    hostEvaluators,
   },
 ) => {
   for (const [name, intrinsicName] of entries(universalPropertyNames)) {
@@ -121,6 +123,7 @@ export const setGlobalObjectMutableProperties = (
         parentCompartment,
         enforceNew: true,
       },
+      hostEvaluators,
     ),
   );
 

packages/ses/src/lockdown.js

@@ -100,10 +100,30 @@ const safeHarden = makeHardener();
 // only ever need to be called once and that simplifying lockdown will improve
 // the quality of audits.
 
-const assertDirectEvalAvailable = () => {
-  let allowed = false;
+const probeHostEvaluators = () => {
+  let functionAllowed;
   try {
-    allowed = FERAL_FUNCTION(
+    functionAllowed = FERAL_FUNCTION('return true')();
+  } catch (_error) {
+    // We reach here if the Function() constructor has not been implemented by the
+    // host, or is outright forbidden by a Content Security Policy.
+    functionAllowed = false;
+  }
+
+  let evalAllowed;
+  try {
+    evalAllowed = FERAL_EVAL('true');
+  } catch (_error) {
+    // We reach here if eval() has not been implemented by the host, or is outright
+    // forbidden by a Content Security Policy.
+    // We allow this for SES usage that delegates the responsibility to isolate
+    // guest code to production code generation.
+    evalAllowed = false;
+  }
+
+  let directEvalAllowed;
+  if (functionAllowed && evalAllowed) {
+    directEvalAllowed = FERAL_FUNCTION(
       'eval',
       'SES_changed',
       `\
@@ -115,21 +135,12 @@ const assertDirectEvalAvailable = () => {
     // and indirect, which generally creates a new global.
     // We are going to throw an exception for failing to initialize SES, but
     // good neighbors clean up.
-    if (!allowed) {
+    if (!directEvalAllowed) {
       delete globalThis.SES_changed;
     }
-  } catch (_error) {
-    // We reach here if eval is outright forbidden by a Content Security Policy.
-    // We allow this for SES usage that delegates the responsibility to isolate
-    // guest code to production code generation.
-    allowed = true;
-  }
-  if (!allowed) {
-    // See https://github.com/endojs/endo/blob/master/packages/ses/error-codes/SES_DIRECT_EVAL.md
-    throw TypeError(
-      `SES cannot initialize unless 'eval' is the original intrinsic 'eval', suitable for direct-eval (dynamically scoped eval) (SES_DIRECT_EVAL)`,
-    );
   }
+
+  return { functionAllowed, evalAllowed, directEvalAllowed };
 };
 
 /**
@@ -152,11 +163,11 @@ export const repairIntrinsics = (options = {}) => {
   // The `stackFiltering` is not a safety issue. Rather it is a tradeoff
   // between relevance and completeness of the stack frames shown on the
   // console. Setting`stackFiltering` to `'verbose'` applies no filters, providing
-  // the raw stack frames that can be quite versbose. Setting
+  // the raw stack frames that can be quite verbose. Setting
   // `stackFrameFiltering` to`'concise'` limits the display to the stack frame
   // information most likely to be relevant, eliminating distracting frames
   // such as those from the infrastructure. However, the bug you're trying to
-  // track down might be in the infrastrure, in which case the `'verbose'` setting
+  // track down might be in the infrastructure, in which case the `'verbose'` setting
   // is useful. See
   // [`stackFiltering` options](https://github.com/Agoric/SES-shim/blob/master/packages/ses/docs/lockdown.md#stackfiltering-options)
   // for an explanation.
@@ -189,6 +200,10 @@ export const repairIntrinsics = (options = {}) => {
       /** @param {string} debugName */
       debugName => debugName !== '',
     ),
+    // TODO: Remove '_legacy' when breaking change introduced (hostEvaluators: 'all' as default), where strict CSPs will require 'none'.
+    hostEvaluators = /** @type { '_legacy' | 'all' | 'none' | 'no-direct'  } */ (
+      getenv('LOCKDOWN_HOST_EVALUATORS', '_legacy')
+    ),
     legacyRegeneratorRuntimeTaming = getenv(
       'LOCKDOWN_LEGACY_REGENERATOR_RUNTIME_TAMING',
       'safe',
@@ -208,6 +223,17 @@ export const repairIntrinsics = (options = {}) => {
     evalTaming === 'noEval' ||
     Fail`lockdown(): non supported option evalTaming: ${q(evalTaming)}`;
 
+  // TODO: Remove '_legacy' when breaking change introduced (hostEvaluators: 'all' as default), where strict CSPs will require 'none'.
+  hostEvaluators === '_legacy' ||
+    hostEvaluators === 'all' ||
+    hostEvaluators === 'none' ||
+    hostEvaluators === 'no-direct' ||
+    Fail`lockdown(): non supported option hostEvaluators: ${q(hostEvaluators)}`;
+
+  evalTaming === 'safeEval' &&
+    hostEvaluators === 'no-direct' &&
+    Fail`lockdown(): option evalTaming: ${q(evalTaming)} is incompatible with hostEvaluators: ${q(hostEvaluators)}`;
+
   // Assert that only supported options were passed.
   // Use Reflect.ownKeys to reject symbol-named properties as well.
   const extraOptionsNames = ownKeys(extraOptions);
@@ -218,17 +244,21 @@ export const repairIntrinsics = (options = {}) => {
   const { warn } = reporter;
 
   if (dateTaming !== undefined) {
-    // eslint-disable-next-line no-console
     warn(
       `SES The 'dateTaming' option is deprecated and does nothing. In the future specifying it will be an error.`,
     );
   }
   if (mathTaming !== undefined) {
-    // eslint-disable-next-line no-console
     warn(
       `SES The 'mathTaming' option is deprecated and does nothing. In the future specifying it will be an error.`,
     );
   }
+  if (hostEvaluators === '_legacy') {
+    // TODO: Remove when 'all' introduced as the new default option (breaking change).
+    warn(
+      `SES Please now use the 'hostEvaluators' option. In the future not specifying 'none' will error under strict CSP.`,
+    );
+  }
 
   priorRepairIntrinsics === undefined ||
     // eslint-disable-next-line @endo/no-polymorphic-call
@@ -242,7 +272,35 @@ export const repairIntrinsics = (options = {}) => {
   // trace retained:
   priorRepairIntrinsics.stack;
 
-  assertDirectEvalAvailable();
+  const { functionAllowed, evalAllowed, directEvalAllowed } =
+    probeHostEvaluators();
+
+  // This could be a strict Content Security Policy containing either a `default-src` or a `script-src` directive, or an ES host with broken APIs.
+  const noEvaluators = !evalAllowed && !functionAllowed; // eval() itself and the Function() constructor are not allowed to execute.
+
+  hostEvaluators === 'all' &&
+    noEvaluators &&
+    Fail`'hostEvaluators' was set to 'all', but the Function() constructor and eval() are not allowed to execute (SES_DIRECT_EVAL)`;
+
+  hostEvaluators === 'none' &&
+    !noEvaluators &&
+    Fail`'hostEvaluators' was set to 'none', but the Function() constructor and eval() are allowed to execute (SES_DIRECT_EVAL)`;
+
+  hostEvaluators === 'no-direct' &&
+    directEvalAllowed &&
+    Fail`'hostEvaluators' was set to 'no-direct', but ${directEvalAllowed === true ? 'direct eval is functional' : 'the Function() constructor and eval() are not allowed to execute'} (SES_DIRECT_EVAL)`;
+
+  // TODO: Remove '_legacy' when 'all' introduced as the new default option (breaking change).
+  // For backwards compatibility under '_legacy', we do not error with a strict CSP, since directEvalAllowed remains undefined.
+  if (
+    (hostEvaluators === '_legacy' || hostEvaluators === 'all') &&
+    directEvalAllowed === false
+  ) {
+    // See https://github.com/endojs/endo/blob/master/packages/ses/error-codes/SES_DIRECT_EVAL.md
+    throw TypeError(
+      "SES cannot initialize unless 'eval' is the original intrinsic 'eval', suitable for direct-eval (dynamically scoped eval) (SES_DIRECT_EVAL)",
+    );
+  }
 
   /**
    * Because of packagers and bundlers, etc, multiple invocations of lockdown
@@ -406,6 +464,7 @@ export const repairIntrinsics = (options = {}) => {
     newGlobalPropertyNames: initialGlobalPropertyNames,
     makeCompartmentConstructor,
     markVirtualizedNativeFunction,
+    hostEvaluators,
   });
 
   if (evalTaming === 'noEval') {

packages/ses/src/make-eval-function.js

@@ -1,11 +1,13 @@
 /**
  * makeEvalFunction()
  * A safe version of the native eval function which relies on
- * the safety of safeEvaluate for confinement.
+ * the safety of safeEvaluate for confinement, unless noEval
+ * is specified (then a TypeError is thrown).
  *
- * @param {Function} safeEvaluate
+ * @param {Function} evaluator
+ * @param legacyHermesTaming
  */
-export const makeEvalFunction = safeEvaluate => {
+export const makeEvalFunction = evaluator => {
   // We use the concise method syntax to create an eval without a
   // [[Construct]] behavior (such that the invocation "new eval()" throws
   // TypeError: eval is not a constructor"), but which still accepts a
@@ -19,7 +21,7 @@ export const makeEvalFunction = safeEvaluate => {
         // rule. Track.
         return source;
       }
-      return safeEvaluate(source);
+      return evaluator(source);
     },
   }.eval;