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

Closes: #XXXX
Refs: #961 #2690 #2723

## Description

#961 deviated from our general convention that lockdown option values be
kebob-case, instead adding `evalTaming:` option values `safeEval`,
`unsafeEval`, `noEval`. (I approved #961 at the time, apparently without
noticing this discrepancy.) This PR fixes those to be `safe-eval`,
`unsafe-eval`, and `no-eval`. But to avoid breaking any old usage, this
PR ensure the only names continue to work for now, but always commented
in the code as "deprecated".

This PR does only that. Other changes to the relevant lockdown option or
relevant lockdown options machinery are left to #2723 or #2690
respectively. I request that this PR go first, with those others
adjusting to this one.

### Security Considerations

none
### Scaling Considerations

non
### Documentation Considerations

This PR simply changes the documentation to use the new names without
ever mentioning the deprecated old names. That seems like an appropriate
simplification for the docs.

### Testing Considerations

With a bit of duplication and renaming, we now test the new names and
the old deprecated names.

### Compatibility Considerations

To avoid breaking any old usage, this PR ensure the only names continue
to work for now, but always commented in the code as "deprecated". It
would be very nice to eventually be able to retire the deprecated names,
but I find it hard to imagine how we'd test that it is safe to do so.

### Upgrade Considerations

Nothing BREAKING, since the old deprecated names continue to work.

- [x] Update `NEWS.md` for user-facing changes.

Author: erights

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/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 renamed to 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