fix(ses): lockdown options should be kebob-case

packages/ses/NEWS.md

@@ -1,5 +1,15 @@
 User-visible changes in `ses`:
 
+# Next release
+
+The `evalTaming:` option values are renamed
+- from `'safeEval'`, `'unsafeEval'`, and `'noEval'`
+- to `'safe-eval'`, `'unsafe-eval'`, and `'no-eval'`
+
+in order to follow the convention that lockdown option values use kebob-case
+rather than camelCase. To avoid breaking old programs during the transition,
+the old names are deprecated, but continue to work for now.
+
 # v1.11.0 (2025-01-23)
 
 - Adds support for dynamic `import` in conjunction with an update to

packages/ses/docs/lockdown.md

@@ -29,7 +29,7 @@ Each option is explained in its own section below.
 | `errorTrapping`                  | `'platform'`     | `'exit'` `'abort'` `'report'` `'none'` | handling of uncaught exceptions ([details](#errortrapping-options)) |
 | `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)) |
+| `evalTaming`                     | `'safe-eval'`    | `'unsafe-eval'` `'no-eval'`            | `eval` and `Function` of the start compartment ([details](#evaltaming-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)) |
@@ -574,15 +574,15 @@ The default lockdown behavior isolates all of these evaluators.
 
 Replacing the realm's initial evaluators is not necessary to ensure the
 isolation of guest code because guest code must not run in the start compartment.
-Although the code run in the start compartment is normally referred to as "trusted", we mean only that we assume it was not written maliciously. It may still be buggy, and it may be buggy in a way that is exploitable by malicious guest code. To limit the harm that such vulnerabilities can cause, the default (`"safeEval"`) setting replaces the evaluators of the start compartment with their safe alternatives.
+Although the code run in the start compartment is normally referred to as "trusted", we mean only that we assume it was not written maliciously. It may still be buggy, and it may be buggy in a way that is exploitable by malicious guest code. To limit the harm that such vulnerabilities can cause, the default (`"safe-eval"`) setting replaces the evaluators of the start compartment with their safe alternatives.
 
 However, in the shim, only the exact `eval` function from the start compartment can be used to
-perform direct-eval, which runs in the lexical scope in which the direct-eval syntax appears (direct-eval is a special form rather than a function call).
+perform direct-eval, which runs in the lexical scope in which the direct-eval syntax appears (the direct-eval syntax is a special form rather than a function call).
 The SES shim itself uses direct-eval internally to construct an isolated
 evaluator, so replacing the initial `eval` prevents any subsequent program
 from using the same mechanism to isolate a guest program.
 
-The `"unsafeEval"` option for `evalTaming` leaves the original `eval` in place
+The `"unsafe-eval"` option for `evalTaming` leaves the original `eval` in place
 for other isolation mechanisms like isolation code generators that work in
 tandem with SES.
 This option may be useful for web pages with an environment that allows `unsafe-eval`,
@@ -593,28 +593,28 @@ In these cases, SES cannot be responsible for maintaining the isolation of
 guest code. If you're going to use `eval`, [Trusted
 Types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types) may help maintain security.
 
-The `"noEval"` option emulates a Content Security Policy that disallows
+The `"no-eval"` option emulates a Content Security Policy that disallows
 `unsafe-eval` by replacing all evaluators with functions that throw an
 exception.
 
 ```js
-lockdown(); // evalTaming defaults to 'safeEval'
+lockdown(); // evalTaming defaults to 'safe-eval'
 // or
-lockdown({ evalTaming: 'noEval' }); // disallowing calling eval like there is a CSP limitation.
+lockdown({ evalTaming: 'no-eval' }); // disallowing calling eval like there is a CSP limitation.
 // vs
 
 // Please use this option with caution.
 // You may want to use Trusted Types or Content Security Policy with this option.
-lockdown({ evalTaming: 'unsafeEval' });
+lockdown({ evalTaming: 'unsafe-eval' });
 ```
 
 If `lockdown` does not receive an `evalTaming` option, it will respect
 `process.env.LOCKDOWN_EVAL_TAMING`.
 
 ```console
-LOCKDOWN_EVAL_TAMING=safeEval
-LOCKDOWN_EVAL_TAMING=noEval
-LOCKDOWN_EVAL_TAMING=unsafeEval
+LOCKDOWN_EVAL_TAMING=safe-eval
+LOCKDOWN_EVAL_TAMING=no-eval
+LOCKDOWN_EVAL_TAMING=unsafe-eval
 ```
 
 ## `stackFiltering` Options

packages/ses/error-codes/SES_NO_EVAL.md

@@ -1,3 +1,3 @@
 # SES is disallowing eval in the current compartment (`SES_NO_EVAL`)
 
-The SES Hardened JavaScript shim is configured to reject any source evaluation in the current compartment. This is configured in the `lockdown` option. To mitigate this error, change the [lockdown option `"evalTaming"`](../docs/lockdown.md) from `"noEval"` to either `"safeEval"` (default) or `"unsafeEval"`.
+The SES Hardened JavaScript shim is configured to reject any source evaluation in the current compartment. This is configured in the `lockdown` option. To mitigate this error, change the [lockdown option `"evalTaming"`](../docs/lockdown.md) from `"no-eval"` to either `"safe-eval"` (default) or `"unsafe-eval"`.

packages/ses/src/commons.js

@@ -320,7 +320,7 @@ export const FERAL_FUNCTION = Function;
 
 export const noEvalEvaluate = () => {
   // See https://github.com/endojs/endo/blob/master/packages/ses/error-codes/SES_NO_EVAL.md
-  throw TypeError('Cannot eval with evalTaming set to "noEval" (SES_NO_EVAL)');
+  throw TypeError('Cannot eval with evalTaming set to "no-eval" (SES_NO_EVAL)');
 };
 
 // ////////////////// FERAL_STACK_GETTER FERAL_STACK_SETTER ////////////////////

packages/ses/src/eval-scope.js

@@ -27,9 +27,9 @@ const { Fail } = assert;
 //   prepareStack(depth, () => {
 //     (eval)('');
 //   });
-//   const unsafeEval = (eval);
-//   const safeEval = (eval);
-//   const realGlobal = unsafeEval('globalThis');
+//   const unsafe-eval = (eval);
+//   const safe-eval = (eval);
+//   const realGlobal = unsafe-eval('globalThis');
 //
 // To protect against that case, we also delete `eval` from the `evalScope` in
 // a `finally` block surrounding the call to the safe evaluator.

packages/ses/src/lockdown.js

@@ -183,7 +183,7 @@ export const repairIntrinsics = (options = {}) => {
     ),
     stackFiltering = getenv('LOCKDOWN_STACK_FILTERING', 'concise'),
     domainTaming = getenv('LOCKDOWN_DOMAIN_TAMING', 'safe'),
-    evalTaming = getenv('LOCKDOWN_EVAL_TAMING', 'safeEval'),
+    evalTaming = getenv('LOCKDOWN_EVAL_TAMING', 'safe-eval'),
     overrideDebug = arrayFilter(
       stringSplit(getenv('LOCKDOWN_OVERRIDE_DEBUG', ''), ','),
       /** @param {string} debugName */
@@ -203,9 +203,12 @@ export const repairIntrinsics = (options = {}) => {
     legacyRegeneratorRuntimeTaming === 'unsafe-ignore' ||
     Fail`lockdown(): non supported option legacyRegeneratorRuntimeTaming: ${q(legacyRegeneratorRuntimeTaming)}`;
 
-  evalTaming === 'unsafeEval' ||
-    evalTaming === 'safeEval' ||
-    evalTaming === 'noEval' ||
+  evalTaming === 'unsafe-eval' ||
+    evalTaming === 'unsafeEval' || // deprecated
+    evalTaming === 'safe-eval' ||
+    evalTaming === 'safeEval' || // deprecated
+    evalTaming === 'no-eval' ||
+    evalTaming === 'noEval' || // deprecated
     Fail`lockdown(): non supported option evalTaming: ${q(evalTaming)}`;
 
   // Assert that only supported options were passed.
@@ -408,23 +411,36 @@ export const repairIntrinsics = (options = {}) => {
     markVirtualizedNativeFunction,
   });
 
-  if (evalTaming === 'noEval') {
+  if (
+    evalTaming === 'no-eval' ||
+    // deprecated
+    evalTaming === 'noEval'
+  ) {
     setGlobalObjectEvaluators(
       globalThis,
       noEvalEvaluate,
       markVirtualizedNativeFunction,
     );
-  } else if (evalTaming === 'safeEval') {
+  } else if (
+    evalTaming === 'safe-eval' ||
+    // deprecated
+    evalTaming === 'safeEval'
+  ) {
     const { safeEvaluate } = makeSafeEvaluator({ globalObject: globalThis });
     setGlobalObjectEvaluators(
       globalThis,
       safeEvaluate,
       markVirtualizedNativeFunction,
     );
-  } else if (evalTaming === 'unsafeEval') {
-    // Leave eval function and Function constructor of the initial compartment in-tact.
-    // Other compartments will not have access to these evaluators unless a guest program
-    // escapes containment.
+  } else if (
+    evalTaming === 'unsafe-eval' ||
+    // deprecated
+    evalTaming === 'unsafeEval'
+  ) {
+    // Leave eval function and Function constructor of the initial
+    // compartment intact.
+    // Other compartments will not have access to these evaluators unless a
+    // guest program escapes containment.
   }
 
   /**

packages/ses/test/evalTaming-no-eval.test.js

@@ -0,0 +1,15 @@
+import test from 'ava';
+import '../index.js';
+
+lockdown({ evalTaming: 'no-eval' });
+
+test('no eval when evalTaming is no-eval.', t => {
+  // eslint-disable-next-line no-eval
+  t.throws(() => eval('1+1'));
+
+  const compartment = new Compartment();
+  // should not throw
+  compartment.evaluate('(1, eval)("1 + 1")');
+  // eslint-disable-next-line no-eval
+  t.is(eval.toString(), 'function eval() { [native code] }');
+});

packages/ses/test/evalTaming-noEval.test.js

@@ -3,6 +3,7 @@ import '../index.js';
 
 lockdown({ evalTaming: 'noEval' });
 
+// 'noEval' is deprecated, but testing that it still works
 test('no eval when evalTaming is noEval.', t => {
   // eslint-disable-next-line no-eval
   t.throws(() => eval('1+1'));

packages/ses/test/evalTaming-safe-eval.test.js

@@ -0,0 +1,15 @@
+import test from 'ava';
+import '../index.js';
+
+lockdown({ evalTaming: 'safe-eval' });
+
+test('safe eval when evalTaming is safe-eval.', t => {
+  // eslint-disable-next-line no-unused-vars
+  const a = 0;
+  // eslint-disable-next-line no-eval
+  t.throws(() => eval('a'));
+  // eslint-disable-next-line no-eval
+  t.is(eval('1 + 1'), 2);
+  // eslint-disable-next-line no-eval
+  t.is(eval.toString(), 'function eval() { [native code] }');
+});

packages/ses/test/evalTaming-safeEval.test.js

@@ -3,6 +3,7 @@ import '../index.js';
 
 lockdown({ evalTaming: 'safeEval' });
 
+// 'safeEval' is deprecated, but testing that it still works
 test('safe eval when evalTaming is safeEval.', t => {
   // eslint-disable-next-line no-unused-vars
   const a = 0;

packages/ses/test/evalTaming-unsafe.test.js → packages/ses/test/evalTaming-unsafe-eval.test.js

@@ -1,9 +1,9 @@
 import test from 'ava';
 import '../index.js';
 
-lockdown({ evalTaming: 'unsafeEval' });
+lockdown({ evalTaming: 'unsafe-eval' });
 
-test('direct eval is possible when evalTaming is unsafe.', t => {
+test('direct eval is possible when evalTaming is unsafe-eval.', t => {
   // eslint-disable-next-line no-unused-vars
   const a = 0;
   // eslint-disable-next-line no-eval

packages/ses/test/evalTaming-unsafeEval.test.js

@@ -0,0 +1,18 @@
+import test from 'ava';
+import '../index.js';
+
+lockdown({ evalTaming: 'unsafeEval' });
+
+// 'unsafeEval' is deprecated, but testing that it still works
+test('direct eval is possible when evalTaming is unsafeEval.', t => {
+  // eslint-disable-next-line no-unused-vars
+  const a = 0;
+  // eslint-disable-next-line no-eval
+  t.is(eval('a'), 0);
+
+  // should not throw
+  const compartment = new Compartment();
+  compartment.evaluate('(1, eval)("1 + 1")');
+  // eslint-disable-next-line no-eval
+  t.is(eval.toString(), 'function eval() { [native code] }');
+});

packages/ses/types.d.ts

@@ -35,7 +35,14 @@ export interface RepairOptions {
    * @deprecated Deprecated and does nothing. In the future specifying it will be an error.
    */
   mathTaming?: 'safe' | 'unsafe';
-  evalTaming?: 'safeEval' | 'unsafeEval' | 'noEval';
+  evalTaming?:
+    | 'safe-eval'
+    | 'unsafe-eval'
+    | 'no-eval'
+    // deprecated
+    | 'safeEval'
+    | 'unsafeEval'
+    | 'noEval';
   stackFiltering?: 'concise' | 'verbose';
   overrideTaming?: 'moderate' | 'min' | 'severe';
   overrideDebug?: Array<string>;