feat: Establish test extension and shims library

[rekmarks]

Establishes an extension that entrains SES with eventual send (E()) for the purpose of tests, experimentation, and prototyping. This is accomplished by the addition of two new monorepo packages:

• @ocap/extension
• @ocap/shims

These packages are private. The @ocap prefix is merely a convenience serving to identify monorepo packages from external packages. We are not going to claim this prefix in any public registry, and any packages that we want to publish in the future will be renamed @metamask.

Various changes are made to config files in the root workspace in service of the new packages. In particular, constraints.pro has been modified, and a number of exceptions have been added. However, reviewers are encouraged to ignore this file, since Prolog constraints are deprecated in Yarn 4, and we will eventually migrate to its JavaScript constraints system.

Added code follows existing MetaMask conventions to the greatest extent possible. Both packages are exceptional in that neither of them are TypeScript libraries, and the extension of course isn't a library at all. Therefore, neither package necessarily sets a precedent for a "conventional" package in this monorepo.

@ocap/shims

This package contains various shims that we want to import as-is, without applying any transforms. This includes ses and lockdown. Moreover, some of these shims, such as eventual-send, need to be applied in a particular order to be successfully applied. To this end, the package exports endoify.mjs, which is intended to be The One Shim to Rule Them All^TM for ocap programming purposes.

Note that, while the eventual send shim is applied, eventual send itself (E()) isn't actually used anywhere yet. We will definitively use it in the immediate future, however, so we may as well add it now.

@ocap/extension

This package consists of a headless MV3 Chrome extension. See its readme for installation and usage instructions.

The extension has three entry-points:

• background.js, for its background service worker
• offscreen.html, for its offscreen document
• iframe.html, for the iframes that we append to the offscreen document
  • These iframes are sandboxed pages, for whose CSP we are allowed to enable unsafe-eval, and thereby Compartment.evaluate() (from the SES shim).
  • This is the recommended way to access unsafe-eval in MV3 extensions.
  • This is also what we do for Snaps in the production extension, see feat: Use sandboxed pages for Snaps execution in MV3 metamask-extension#25171.

The extension is written in TypeScript where possible, and bundled using Vite. Shims and other files are statically imported (i.e. without bundling) using vite-plugin-static-copy. Easily testable modules are tested using Vitest, Vite's Jest-inspired and ESM-compatible test runner.

[rekmarks]

@SocketSecurity ignore npm/[email protected] npm/[email protected]

These are well-known build tools.

[rekmarks]

@SocketSecurity ignore npm/[email protected] npm/[email protected] npm/[email protected] npm/[email protected] npm/[email protected] npm/[email protected] npm/[email protected]

These are all due to widely used dev dependencies.

[rekmarks]

@SocketSecurity ignore npm/@metamask/[email protected] npm/@metamask/[email protected]

[SMotaal]

My thinking here is that the DX can be improved in a separate PR by defining externalModules in one place at the top and using it to populate the config:

// These are the external modules that must not be modified.
const externalModules = {
  // @ocap/shims dependencies
  './endoify.mjs': '../../shims/dist/endoify.mjs',
  './eventual-send.mjs': '../../shims/dist/eventual-send.mjs',

  // SES dependencies
  './ses.mjs': '../../../node_modules/ses/dist/ses.mjs',
  './lockdown.mjs': '../../../node_modules/ses/dist/lockdown.mjs',
};

This would make it possible to:

• Simplify config.build.rollupOptions.external using Object.keys(externalModules).
• Simplify config.plugins[viteStaticCopy({ targets })] using Object.values(externalModules).map(…).
• Introduce config.resolve.alias using Object.entries(externalModules).map(…) which is needed to experiment with yarn start.

This way we'd be using a single source of truth at the top of the file.

I tested locally before making this request, but want to make sure that including those changes aligns with the intent of the current PR.

---

Aside: For a later PR, we should discuss using bare specifiers (see Node.js's terminology) with importmap instead of ./ specifiers, at for least third-party dependencies.

[SMotaal]

There is a well-established and well-defined convention for capitalization, where:

• acronyms (e.g. HTML) are upper-cased (e.g. document.body.setHTMLUnsafe) unless they are at the beginning of a camel-cased name (e.g. html`<html>`).
• abbreviations (e.g. id) are title-cased (e.g. document.getElementById) unless they are at the beginning of a camel-cased name (e.g. this.id).

The convention was documented in the standards, which escapes me now, but an older reference can be found here.

I propose that we follow this convention moving forward as it is well-established and well-defined.

---

Aside: const URI on line 8 seems obscure and may be changed to IFRAME_URI for added clarity.

[rekmarks]

@SMotaal regarding your first suggestion, I tried storing the values in a map, but failed to find a satisfying key->value mapping. Instead, I moved the values to two separate arrays at the top of the file in e64d534, with some additional clarifying comments.

[SMotaal]

@rekmarks Can you confirm if the intent is to bundle those three modules at any point?

Given the current structure I am note sure if we want to include them in both arrays to eliminate the risk of accidental duplication down the road.

No need to make the change for this PR, I can do it in the following one, but it helps to clarify now while we are here.

Thanks 🙏

[rekmarks]

Hm. If we decide to touch these again (not unlikely), we should probably just bundle everything in @ocap/shims and just leave ./endoify.mjs as the only thing that needs to be copied from outside of @ocap/extension itself. When we do so, we'll remove everything under "dependencies of external modules". I'm tracking this here: #9

[SMotaal]

I wonder if we may hit duplications with separate references, nothing concrete, just something I want to keep in mind for down the road.

Let's revisit this discussion if we need to.