feat(errors): self censoring stack frames (#2928)

Closes: #XXXX
Refs: #XXXX

## Description

Introduces `hideAndHardenFunction` for functions to opt out of having
their frames be visible in abbreviated stacks. See changes to
`lockdown.md` for more.

```js
import { hideAndHardenFunction } from '@endo/errors';

export const foo() = {...stuff...};
hideAndHardenFunction(foo);

console.log(foo.name); // '__HIDE_foo'
```

If a function `foo` is first frozen with `hideAndHardenFunction(foo)`
rather than `freeze(foo)` or `harden(foo)`, then `foo.name` is changed
from `'foo'` to `'__HIDE_foo'`.

When `stackFiltering: 'concise'` or `stackFiltering: 'omit-frames'`,
then (currently only on v8), the stack frames for function whose `name`
begins with `'__HIDE_'` are omitted from the stacks reported by our
causal console. See

### Security Considerations

By allowing functions to opt into this themselves, a sneaky programmer
could use this to hide their attack functions from appearing in frames
of abbreviated stacks. However, more security conscious scenarios should
consider `stackFiltering: 'verbose'` or `stackFiltering:
'shorten-paths'` anyway, which do not drop frames. Nevertheless, this
security hazard is real.

### Scaling Considerations

none
### Documentation Considerations

`hideAndHardenFunction` has a good doc-comment, so presumably that will
appear in docs generated from doc-comments.

### Testing Considerations

As always, test that are about what should appear in stacks are hard to
write regression tests for, since their details depend on, for example,
platform and precise line and column numbers. This would make for
goldens that are *far* to fragile. Instead, I manually tested these, and
I captured the results of manual tests of `deep-send.test.js` in
`lockdown.md`.

### Compatibility Considerations

Production code should never depend on the contents of error messages or
error stacks. However, tests can. We know of goldens for error messages,
but none of error stacks. This PR only affects error stacks, so we do
not expect any compat problems even with golden tests.

### Upgrade Considerations

none

Author: erights

packages/common/apply-labeling-error.js

@@ -1,3 +1,4 @@
+import { hideAndHardenFunction } from '@endo/errors';
 import { E } from '@endo/eventual-send';
 import { isPromise } from '@endo/promise-kit';
 import { throwLabeled } from './throw-labeled.js';
@@ -57,4 +58,4 @@ export const applyLabelingError = (func, args, label = undefined) => {
     return result;
   }
 };
-harden(applyLabelingError);
+hideAndHardenFunction(applyLabelingError);

packages/common/throw-labeled.js

@@ -1,4 +1,9 @@
-import { X, makeError, annotateError } from '@endo/errors';
+import {
+  X,
+  makeError,
+  annotateError,
+  hideAndHardenFunction,
+} from '@endo/errors';
 
 /**
  * Given an error `innerErr` and a `label`, throws a similar
@@ -28,4 +33,4 @@ export const throwLabeled = (
   annotateError(outerErr, X`Caused by ${innerErr}`);
   throw outerErr;
 };
-harden(throwLabeled);
+hideAndHardenFunction(throwLabeled);

packages/errors/NEWS.md

@@ -1,5 +1,9 @@
 User-visible changes in `@endo/errors`:
 
+# Next release
+
+- `hideAndHardenFunction` - If a function `foo` is first frozen with `hideAndHardenFunction(foo)` rather than `freeze(foo)` or `harden(foo)`, then `foo.name` is changed from `'foo'` to `'__HIDE_foo'`. When `stackFiltering: 'concise'` or `stackFiltering: 'omit-frames'`, then (currently only on v8), the stack frames for that function are omitted from the stacks reported by our causal console.
+
 # v1.1.0 (2024-02-22)
 
 - `AggegateError` support

packages/errors/index.js

@@ -11,6 +11,8 @@
 // The assertions re-exported here are defined in
 // https://github.com/endojs/endo/blob/HEAD/packages/ses/src/error/assert.js
 
+const { defineProperty } = Object;
+
 const globalAssert = globalThis.assert;
 
 if (globalAssert === undefined) {
@@ -87,3 +89,30 @@ export {
   throwRedacted as Fail,
   note as annotateError,
 };
+
+/**
+ * `stackFiltering: 'omit-frames'` and `stackFiltering: 'concise'` omit frames
+ * not only of "obvious" infrastructure functions, but also of functions
+ * whose `name` property begins with `'__HIDE_'`. (Note: currently
+ * these options only work on v8.)
+ *
+ * Given that `func` is not yet frozen, then `hideAndHardenFunction(func)`
+ * will prifix `func.name` with an additional `'__HIDE_'`, so that under
+ * those stack filtering options, frames for calls to such functions are
+ * not reported.
+ *
+ * Then the function is hardened and returned. Thus, you can say
+ * `hideAndHardenFunction(func)` where you would normally first say
+ * `harden(func)`.
+ *
+ * @param {Function} func
+ */
+export const hideAndHardenFunction = func => {
+  typeof func === 'function' || throwRedacted`${func} must be a function`;
+  const { name } = func;
+  defineProperty(func, 'name', {
+    // Use `String` in case `name` is a symbol.
+    value: `__HIDE_${String(name)}`,
+  });
+  return harden(func);
+};

packages/errors/package.json

@@ -38,6 +38,7 @@
     "ses": "workspace:^"
   },
   "devDependencies": {
+    "@endo/eventual-send": "workspace:^",
     "@endo/lockdown": "workspace:^",
     "@endo/ses-ava": "workspace:^",
     "ava": "^6.4.1",

packages/errors/test/deep-send.test.js

@@ -0,0 +1,45 @@
+// This file is not really useful as an
+// automated test. Rather, its purpose is just to run it to see what a
+// deep stack looks like.
+// [lockdown.md](https://github.com/endojs/endo/blob/master/packages/ses/docs/lockdown.md)
+// shows the output for `errorTaming: 'safe'` and all variations of
+// `stackFiltering.
+
+// Note: importing `commit.js` rather than `commit-debug.js` so that
+// `errorTaming` is subject to variation by environment variables. If no
+// LOCKDOWN_ERROR_TAMING is set, then it defaults to `'safe'`, whereas
+// `commit.js` sets it to `'unsafe'`.
+import '@endo/lockdown/commit.js';
+import '@endo/eventual-send/shim.js';
+import test from 'ava';
+
+import { E } from '@endo/eventual-send';
+import { Fail, hideAndHardenFunction, q } from '../index.js';
+
+const { freeze } = Object;
+
+const carol = freeze({
+  // Throw an error with unredacted and redacted contents.
+  bar: () => Fail`${q('blue')} is not ${42}`,
+});
+
+const bob = freeze({
+  foo: carolP => E(carolP).bar(),
+});
+
+const alice = freeze({
+  test: () => E(bob).foo(carol),
+});
+
+const goAskAlice = () => alice.test();
+hideAndHardenFunction(goAskAlice);
+
+test('deep-send demo test', t => {
+  const p = goAskAlice();
+  return p.catch(reason => {
+    t.true(reason instanceof Error);
+    t.log('possibly redacted message:', reason.message);
+    t.log('possibly redacted stack:', JSON.stringify(reason.stack));
+    t.log('expected failure:', reason);
+  });
+});

packages/errors/test/deep-stacks.test.js

@@ -0,0 +1,21 @@
+// This file is not really useful as an
+// automated test. Rather, its purpose is just to run it to see what a
+// deep stack looks like.
+
+import '@endo/lockdown/commit-debug.js';
+import '@endo/eventual-send/shim.js';
+import test from 'ava';
+
+import { E } from '@endo/eventual-send';
+
+test('deep-stacks demo test', t => {
+  /** @type {any} */
+  let r;
+  const p = new Promise(res => (r = res));
+  const q = E.when(p, v1 => E.when(v1 + 1, v2 => assert.equal(v2, 22)));
+  r(33);
+  return q.catch(reason => {
+    t.assert(reason instanceof Error);
+    t.log('expected failure', reason);
+  });
+});

packages/eventual-send/test/deep-send.test.js

@@ -4,7 +4,7 @@ import test from '@endo/ses-ava/prepare-endo.js';
 import { E } from '@endo/eventual-send';
 import { Far } from '../src/make-far.js';
 
-// Example from test-deep-send.js in @endo/eventual-send
+// Example from test-deep-send.js in @endo/errors
 
 const carol = Far('Carol', {
   bar: () => console.log('Wut?'),