feat(harden): Introduce @endo/harden (#3008)

Closes: #2978 

## Description

This change introduces an `@endo/harden` package that allows packages to
be written for use in a JS or a HardenedJS environment without
modification. The `@endo/harden` module provides a behavior that depends
on the environment and packaging conditions.

Without any packaging conditions, in a HardenedJS environment,
`@endo/harden` provides the environment’s “volume freezing” `harden`,
meaning that it freezes the closure over both dimensions: transitive
properties and prototypes.

Also without any packaging conditions, if the environment does not
provide a `harden`, `@endo/harden` provides a “surface freezing”
`harden`, meaning that it freezes the closure over only the one
dimension: properties. This provides a modicum of immutability without
interfering with shims or other mutations to shared, intrinsic
prototypes.

With the `hardened` condition (`node -C hardened`, `bundle-source -C
hardened`), `@endo/harden` will not retain an implementation of `harden`
and will assert that `harden` existed as `Object[Symbol.for('harden')]`
or `globalThis.harden` in the environment and vend out that `harden`.
This is useful to minimize the size of bundles that can safely presume
that they will run in a HardenedJS environment.

With the `noop-harden` condition (`node -C noop-harden`), `@endo/harden`
will provide a version of `harden` that returns its argument unaltered.

With these new modes, we expect to deprecate the `lockdown` option for
`"unsafe"` `hardenTaming` which goes further and replaces
`isExtensible`, `isFrozen`, and `isSealed` with versions that misreport
`true` for extensible, unfrozen, or unsealed objects respectively. We
hope that the new default behavior of surface hardening will suffice,
but we leave the `noop-harden` condition as an option since that should
have performance parity with unsafe harden taming for environments that
need it.

As a side-effect, every kind of `harden` will install itself on first
use at `Object[Symbol.for('harden')]` as a non-configurable property
such that the first `@endo/harden` implementation used wins the race to
define the hardening behavior of the realm. SES will install the same
property at time of `lockdown`, but if it loses the race, will throw an
exception indicating that the realm cannot be locked down because of
unsafe usage of `harden` before `lockdown`, and render up the stack of
the first use for diagnostic purposes.

### Security Considerations

The `@endo/harden` provides a new mode of usage that is less safe than
`lockdown` for environments in which `lockdown` is not practical. We do
not expect safety to regress in lockdown environments as a consequence.

This change strengthens one safety guarantee: going forward, hardened
modules using `@endo/harden` will not be vulnerable to hosts that endow
a compartment with a weakened version of `harden`, because
`@endo/harden` always favors the `Object[Symbol.for('harden')]`
enshrined on a shared intrinsic hardened by `lockdown`.

### Scaling Considerations

Adopting `@endo/harden` will increase the size of bundles, and since
this change adopts `@endo/harden` throughout the Endo stack, this bundle
size increase may become problematic for systems close to their bundle
size limits. We provide the bundler condition `hardened` to mitigate
this problem.

### Documentation Considerations

- [ ] This change comes with documentation in README and NEWS for all
impacted packages, including advice to adopt the `hardened` bundle
condition to mitigate the bundle size increase.

### Testing Considerations

This change adds configurations to `sesAvaConfigs` where adopting
`@endo/harden` allows those packages to be used in more configurations.
The salient configuration Endo with shims installed only, without
calling Lockdown, in the cases where packages continue to rely on Assert
or Eventual Send. We hope in time to test in the Base configuration,
without any shims. Some packages are able to adopt the No-op mode of
harden and are accordingly tested in that mode.

### Compatibility Considerations

This change is additive apart from the expected increase in bundle size,
for which we provide a mitigation.

### Upgrade Considerations

None.

Author: kriskowal

.changeset/hardened-hounds-approve.md

@@ -0,0 +1,10 @@
+---
+'@endo/harden': minor
+---
+
+- Introduces `@endo/harden`, providing a `harden` implementation that works
+  both inside and outside HardenedJS.
+- Supports the `hardened` and `harden:unsafe` build conditions to select
+  hardened-environment and no-op behaviors.
+- Detects pre-lockdown use of `harden` so `lockdown()` fails with a helpful
+  error instead of leaving modules incorrectly hardened.

.changeset/hardened-lockdown-sense.md

@@ -0,0 +1,9 @@
+---
+'ses': minor
+---
+
+- `lockdown` and `repairIntrinsics` now detect when code has already called a
+  `harden` imported from `@endo/harden` before lockdown, and fail with a clear
+  error about hardened modules executing before lockdown.
+- Adds `Object[Symbol.for('harden')]` as a variant of `globalThis.harden` that
+  cannot be overridden by an endowment named `harden` in compartments.

.changeset/module-source-no-harden.md

@@ -0,0 +1,12 @@
+---
+'@endo/module-source': minor
+---
+
+- Transitively freezes the properties of `ModuleSource` constructors and
+  instances without requiring lockdown, for greater safety against
+  supply-chain-attack.
+  `ModuleSource`, particularly through the `@endo/module-source/shim.js`,
+  necessarily runs before `lockdown` is called (if ever) and cannot rely on
+  `harden`, so must preemptively transitively freeze its properties to be
+  a hardened module, regardless of whether `lockdown` is ever called.
+

.changeset/pre-lockdown-harden.md

@@ -0,0 +1,30 @@
+---
+'@endo/bundle-source': minor
+'@endo/captp': minor
+'@endo/check-bundle': minor
+'@endo/common': minor
+'@endo/eventual-send': minor
+'@endo/exo': minor
+'@endo/import-bundle': minor
+'@endo/lp32': minor
+'@endo/marshal': minor
+'@endo/memoize': minor
+'@endo/nat': minor
+'@endo/netstring': minor
+'@endo/pass-style': minor
+'@endo/patterns': minor
+'@endo/promise-kit': minor
+'@endo/stream-node': minor
+'@endo/stream': minor
+'@endo/zip': minor
+---
+
+- Relaxes dependence on a global, post-lockdown `harden` function by taking a
+  dependency on the new `@endo/harden` package.
+  Consequently, bundles will now entrain a `harden` implementation that is
+  superfluous if the bundled program is guaranteed to run in a post-lockdown
+  HardenedJS environment.
+  To compensate, use `bundle-source` with `-C hardened` or the analogous feature
+  for packaging conditions with your preferred bundler tool.
+  This will hollow out `@endo/harden` and defer exclusively to the global
+  `harden`.

CONTRIBUTING.md

@@ -26,7 +26,25 @@ If no version comment exists, it infers the latest tag for that action.
 CI enforces pinning with `node scripts/update-action-pins.mjs --check-pins`.
 If this check fails, run the updater and commit the resulting changes.
 
-### Creating a new package
+## Validation
+
+Continuous Integration is comprehensive.
+Many issues can be anticipated locally by running:
+
+- `yarn`
+- `yarn format` for Prettier code formatting
+- `yarn docs`, because Typedoc has a holistic view of TypeScript definitions
+  that lint in individual packages may not catch.
+- `yarn workspaces foreach --all --topological exec yarn pack`: Uncovers
+  issues with type definition generation that only occur during a release.
+- `yarn lerna run --reject-cycles --concurrency 1 prepack`: Prepack (without
+  cleanup per package) to ensure that type resolution in dependent packages
+  continues to work when the typedefs are generated by their upstream packages.
+  This helps avoid a situation in which the types only resolve because of the
+  state of the local filesystem, and fails when imported in an NPM
+  `node_modules` tree.
+
+## Creating a new package
 
 Run <code>[scripts/create-package.sh](./scripts/create-package.sh) $name</code>,
 then update the resulting README.md, package.json (specifically setting

ava-noop-harden.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  nodeArguments: ['-C', 'noop-harden'],
+  files: ['test/**/*.test.*'],
+  timeout: '2m',
+};

packages/bundle-source/cache.js

@@ -1,4 +1,5 @@
 // @ts-check
+import harden from '@endo/harden';
 import { makePromiseKit } from '@endo/promise-kit';
 import { makeReadPowers } from '@endo/compartment-mapper/node-powers.js';
 

packages/bundle-source/package.json

@@ -26,6 +26,7 @@
     "@endo/base64": "workspace:^",
     "@endo/compartment-mapper": "workspace:^",
     "@endo/evasive-transform": "workspace:^",
+    "@endo/harden": "workspace:^",
     "@endo/init": "workspace:^",
     "@endo/promise-kit": "workspace:^",
     "@endo/where": "workspace:^",

packages/bundle-source/src/endo.js

@@ -20,9 +20,10 @@ const textDecoder = new TextDecoder();
  * @returns {BundlingKit}
  */
 export const makeBundlingKit = (
-  { pathResolve, userInfo, computeSha512, platform, env },
+  io,
   { cacheSourceMaps, elideComments, noTransforms, commonDependencies },
 ) => {
+  const { pathResolve, userInfo, computeSha512, platform, env } = io;
   if (noTransforms && elideComments) {
     throw new Error(
       'bundleSource endoZipBase64 cannot elideComments with noTransforms',

packages/bundle-source/src/fs.js

@@ -1,4 +1,6 @@
 // @ts-check
+import harden from '@endo/harden';
+
 let mutex = Promise.resolve(undefined);
 
 /** @import {AtomicFileWriter, FileReader, FileWriter} from './types.js' */