feat(bundle-source,import-bundle): Thread importHook option to endoZipBase64 moduleFormat. (#2753)

## Description

This PR allows `bundleSource` and `importBundle` to bundle files and
import bundled files respectively in the case that
1. the source file depends on external dependencies (such as 'fs' and
'path') and
2. the bundle is created using the endoZipBase64 moduleFormat option

This functionality already existed in `@endo/compartment-mapper`, and
this PR simply plumbs the importHook option to the bundleSource and
importBundle APIs.

### Security Considerations

Any designs which depend upon code bundled with the endoZipBase64
moduleFormat to have no external dependencies will be broken. To my
knowledge none exist.

### Scaling Considerations

None

### Documentation Considerations

The bundleSource documentation does not have a use case showing the
importHook option.

### Testing Considerations

See included tests.

### Compatibility Considerations

None

### Upgrade Considerations

Bundling with endoZipBase64 is now more permissive, so existing
importBundle calls may fail in a way they couldn't before.

Author: grypez

packages/bundle-source/NEWS.md

@@ -1,5 +1,10 @@
 User-visible changes to `@endo/bundle-source`:
 
+# Next release
+
+- The `'endoZipBase64'` moduleFormat now utilizes the `importHook` option to
+  exit dependencies whose specifiers return a truthy value.
+
 # v4.0.0 (2025-03-19)
 
 - Replaces the implementation for the `nestedEvaluate` and `getExport`

packages/bundle-source/demo/external-fs-transitive.js

@@ -0,0 +1,3 @@
+import { readFileSync } from './external-fs.js';
+
+assert(typeof readFileSync === 'function');

packages/bundle-source/demo/external-fs.js

@@ -3,3 +3,5 @@ import { readFileSync } from 'fs';
 
 assert(fs[Symbol.toStringTag] === 'Module');
 assert(typeof readFileSync === 'function');
+
+export { readFileSync };

packages/bundle-source/src/zip-base64.js

@@ -25,6 +25,8 @@ const readPowers = makeReadPowers({ fs, url, crypto });
  * @param {boolean} [options.elideComments]
  * @param {string[]} [options.conditions]
  * @param {Record<string, string>} [options.commonDependencies]
+ * @param {(specifier: string, packageLocation: string) => Promise<import('@endo/compartment-mapper/src/types').ThirdPartyStaticModuleInterface | undefined>} [options.importHook]
+ *
  * @param {object} [grantedPowers]
  * @param {(bytes: string | Uint8Array) => string} [grantedPowers.computeSha512]
  * @param {typeof import('path)['resolve']} [grantedPowers.pathResolve]
@@ -44,6 +46,7 @@ export async function bundleZipBase64(
     elideComments = false,
     conditions = [],
     commonDependencies,
+    importHook,
   } = options;
   const powers = { ...readPowers, ...grantedPowers };
   const {
@@ -96,6 +99,7 @@ export async function bundleZipBase64(
       parserForLanguage,
       moduleTransforms,
       sourceMapHook,
+      importHook,
     },
   );
   assert(sha512);

packages/bundle-source/test/external-fs.test.js

@@ -29,3 +29,29 @@ test(`external require('fs')`, async t => {
   const srcMap1 = `(${src1})`;
   nestedEvaluate(srcMap1)();
 });
+
+const testFsImportHookEndoZipBase64 = (name, file) => {
+  test(`bundle ${name} with endoZipBase64`, async t => {
+    // We expect the provided importHook is called with 'fs' exactly once
+    t.plan(1);
+
+    const testFile = url.fileURLToPath(new URL(file, import.meta.url));
+
+    await bundleSource(testFile, {
+      format: 'endoZipBase64',
+      importHook: async specifier => {
+        if (specifier === 'fs') {
+          t.is(specifier, 'fs', 'imported fs module');
+          return true;
+        }
+        return undefined;
+      },
+    });
+  });
+};
+
+testFsImportHookEndoZipBase64('import fs', '../demo/external-fs.js');
+testFsImportHookEndoZipBase64(
+  'transitive import fs',
+  '../demo/external-fs-transitive.js',
+);

packages/import-bundle/NEWS.md

@@ -1,5 +1,9 @@
 User-visible changes to `@endo/import-bundle`:
 
+# Next release
+
+- The `'endoZipBase64'` moduleFormat now utilizes the `importHook` option.
+
 # v1.4.0 (2025-03-11)
 
 - Adds support for `test` format bundles, which simply return a promise for an

packages/import-bundle/src/index.js

@@ -32,6 +32,7 @@ export async function importBundle(bundle, options = {}, powers = {}) {
     inescapableTransforms = [],
     inescapableGlobalProperties = {},
     expectedSha512 = undefined,
+    importHook = undefined,
   } = options;
   const {
     computeSha512 = undefined,
@@ -74,13 +75,15 @@ export async function importBundle(bundle, options = {}, powers = {}) {
       expectedSha512,
       computeSourceLocation,
       computeSourceMapLocation,
+      importHook,
     });
     // Call import by property to bypass SES censoring for dynamic import.
     // eslint-disable-next-line dot-notation
     const { namespace } = await archive['import']({
       globals: endowments,
       __shimTransforms__: transforms,
       Compartment: CompartmentToUse,
+      importHook,
     });
     // namespace.default has the default export
     return namespace;

packages/import-bundle/test/bundle3.js

@@ -0,0 +1,5 @@
+import { readFileSync } from 'fs';
+
+const fileContents = readFileSync('self.js', 'utf8');
+
+export default fileContents;

packages/import-bundle/test/import-bundle.test.js

@@ -35,7 +35,10 @@ async function testBundle1(t, b1, mode, ew) {
     `ns2.f5 ${mode} ok`,
   );
 
-  const ns3 = await importBundle(b1, { endowments, transforms: [transform1] });
+  const ns3 = await importBundle(b1, {
+    endowments,
+    transforms: [transform1],
+  });
   t.is(ns3.f4('is ok'), 'substitution is ok', `ns3.f4 ${mode} ok`);
   t.is(
     ns3.f5('the bed'),
@@ -92,6 +95,46 @@ test('test import archive', async t => {
   await testBundle1(t, b1EndoZipBase64Bundle, 'endoZipBase64', endowments);
 });
 
+test('test fs import with importHook', async t => {
+  t.plan(3);
+  const testFilePath = url.fileURLToPath(
+    new URL('bundle3.js', import.meta.url),
+  );
+  const fileContents = await fs.promises.readFile(testFilePath, 'utf8');
+
+  const options = {
+    moduleFormat: 'endoZipBase64',
+    importHook: async specifier => {
+      console.log(`importHook(${specifier})`);
+      if (specifier === 'fs') {
+        t.is(specifier, 'fs');
+        return {
+          imports: [],
+          exports: ['readFileSync'],
+          execute: moduleExports => {
+            moduleExports.readFileSync = path => {
+              if (path === 'self.js') {
+                return fileContents;
+              }
+              throw new Error(`Unknown path: ${path}`);
+            };
+          },
+        };
+      }
+      return undefined; // Let the archive handle other modules
+    },
+  };
+
+  const bundle = await bundleSource(testFilePath, options);
+  const ns = await importBundle(bundle, options);
+
+  t.is(
+    ns.default.toString(),
+    fileContents,
+    'should read the file contents correctly',
+  );
+});
+
 test('test import script', async t => {
   const endowments = { console };
   const b1EndoScriptBundle = await bundleSource(