@endo/compartment-mapper 1.1.5 → 1.2.0

package/src/import-archive.js

@@ -1,406 +1,87 @@
-// @ts-check
-/* eslint no-shadow: "off" */
-
-import { ZipReader } from '@endo/zip';
-import { link } from './link.js';
-import parserPreCjs from './parse-pre-cjs.js';
-import parserJson from './parse-json.js';
-import parserText from './parse-text.js';
-import parserBytes from './parse-bytes.js';
-import parserPreMjs from './parse-pre-mjs.js';
-import { parseLocatedJson } from './json.js';
-import { unpackReadPowers } from './powers.js';
-import { join } from './node-module-specifier.js';
-import { assertCompartmentMap } from './compartment-map.js';
-import { exitModuleImportHookMaker } from './import-hook.js';
-import { attenuateModuleHook, enforceModulePolicy } from './policy.js';
-
-/** @import {StaticModuleType} from 'ses' */
-/** @import {Application, CompartmentDescriptor, ComputeSourceLocationHook, ComputeSourceMapLocationHook, ExecuteFn, ExecuteOptions, ExitModuleImportHook, HashFn, ImportHookMaker, LoadArchiveOptions, ParserImplementation, ReadPowers} from './types.js' */
-
-const DefaultCompartment = Compartment;
-
-const { Fail, quote: q } = assert;
-
-const textDecoder = new TextDecoder();
-
-const { freeze } = Object;
-
-/** @type {Record<string, ParserImplementation>} */
-const parserForLanguage = {
-  'pre-cjs-json': parserPreCjs,
-  'pre-mjs-json': parserPreMjs,
-  json: parserJson,
-  text: parserText,
-  bytes: parserBytes,
-};
-
-/**
- * @param {string} errorMessage - error to throw on execute
- * @returns {StaticModuleType}
+/* Provides functions for evaluating modules in an archive (a zip file
+ * with a `compartment-map.json` and a file for a module and each of its
+ * transitive dependencies.)
+ *
+ * These functions accept the URL of an entry module and find its transitive
+ * dependencies through the Node.js `node_modules` conventions.
+ *
+ * These functions use the default parsers in `import-archive-parsers.js`,
+ * which support only pre-compiled ESM and CommonJS.
+ *
+ * See `import-archive-lite.js` for functions that are not coupled to these
+ * parsers or the `node_modules` conventions without necessarily entraining a
+ * dependency on Babel.
  */
-const postponeErrorToExecute = errorMessage => {
-  // Return a place-holder that'd throw an error if executed
-  // This allows cjs parser to more eagerly find calls to require
-  // - if parser identified a require call that's a local function, execute will never be called
-  // - if actual required module is missing, the error will happen anyway - at execution time
 
-  const record = freeze({
-    imports: [],
-    exports: [],
-    execute: () => {
-      throw Error(errorMessage);
-    },
-  });
+// @ts-check
 
-  return record;
-};
+import { defaultParserForLanguage } from './import-archive-parsers.js';
+import {
+  parseArchive as parseArchiveLite,
+  loadArchive as loadArchiveLite,
+  importArchive as importArchiveLite,
+} from './import-archive-lite.js';
+
+const { assign, create, freeze } = Object;
+
+/** @import {Application} from './types.js' */
+/** @import {ComputeSourceLocationHook} from './types.js' */
+/** @import {ComputeSourceMapLocationHook} from './types.js' */
+/** @import {ExecuteOptions} from './types.js' */
+/** @import {ExitModuleImportHook} from './types.js' */
+/** @import {HashFn} from './types.js' */
+/** @import {LoadArchiveOptions} from './types.js' */
+/** @import {ReadPowers} from './types.js' */
+/** @import {ParserForLanguage} from './types.js' */
+
+// Must give the type of Compartment a name to capture the external meaning of
+// Compartment Otherwise @param {typeof Compartment} takes the Compartment to
+// mean the const variable defined within the function.
+//
+/** @typedef {typeof Compartment} CompartmentConstructor */
 
 /**
- * @param {(path: string) => Uint8Array} get
- * @param {Record<string, CompartmentDescriptor>} compartments
- * @param {string} archiveLocation
- * @param {HashFn} [computeSha512]
- * @param {ComputeSourceLocationHook} [computeSourceLocation]
- * @param {ExitModuleImportHook} [exitModuleImportHook]
- * @param {ComputeSourceMapLocationHook} [computeSourceMapLocation]
- * @returns {ImportHookMaker}
+ * @typedef {object} Options
+ * @property {string} [expectedSha512]
+ * @property {HashFn} [computeSha512]
+ * @property {Record<string, unknown>} [modules]
+ * @property {ExitModuleImportHook} [importHook]
+ * @property {CompartmentConstructor} [Compartment]
+ * @property {ComputeSourceLocationHook} [computeSourceLocation]
+ * @property {ComputeSourceMapLocationHook} [computeSourceMapLocation]
+ * @property {ParserForLanguage} [parserForLanguage]
  */
-const makeArchiveImportHookMaker = (
-  get,
-  compartments,
-  archiveLocation,
-  computeSha512 = undefined,
-  computeSourceLocation = undefined,
-  exitModuleImportHook = undefined,
-  computeSourceMapLocation = undefined,
-) => {
-  // per-assembly:
-  /** @type {ImportHookMaker} */
-  const makeImportHook = ({
-    packageLocation,
-    packageName,
-    attenuators,
-    // note `compartments` are not passed to makeImportHook because
-    // the reference was passed to makeArchiveImportHookMaker.
-  }) => {
-    // per-compartment:
-    const compartmentDescriptor = compartments[packageLocation];
-    const { modules } = compartmentDescriptor;
-    /** @type {import('ses').ImportHook} */
-    const importHook = async moduleSpecifier => {
-      // per-module:
-      const module = modules[moduleSpecifier];
-      if (module === undefined) {
-        if (exitModuleImportHook) {
-          // At this point in archive importing, if a module is not found and
-          // exitModuleImportHook exists, the only possibility is that the
-          // module is a "builtin" module and the policy needs to be enforced.
-          enforceModulePolicy(moduleSpecifier, compartmentDescriptor, {
-            exit: true,
-            errorHint: `Blocked in loading. ${q(
-              moduleSpecifier,
-            )} was not in the archive and an attempt was made to load it as a builtin`,
-          });
-          const record = await exitModuleImportHook(moduleSpecifier);
-          if (record) {
-            // note it's not being marked as exit in sources
-            // it could get marked and the second pass, when the archive is being executed, would have the data
-            // to enforce which exits can be dynamically imported
-            return {
-              record: await attenuateModuleHook(
-                moduleSpecifier,
-                record,
-                compartmentDescriptor.policy,
-                attenuators,
-              ),
-              specifier: moduleSpecifier,
-            };
-          } else {
-            // if exitModuleImportHook is allowed, the mechanism to defer
-            // errors in archive creation is never used. We don't want to
-            // throw until the module execution is attempted. This is because
-            // the cjs parser eagerly looks for require calls, and if it finds
-            // one, it will try to import the module even if the require is
-            // never reached.
-            return postponeErrorToExecute(
-              `Cannot find external module ${q(moduleSpecifier)} in package ${q(
-                packageLocation,
-              )} in archive ${q(archiveLocation)}`,
-            );
-          }
-        }
-        throw Error(
-          `Cannot find module ${q(moduleSpecifier)} in package ${q(
-            packageLocation,
-          )} in archive ${q(archiveLocation)}`,
-        );
-      }
-      if (module.deferredError !== undefined) {
-        return postponeErrorToExecute(module.deferredError);
-      }
-      if (module.parser === undefined) {
-        throw Error(
-          `Cannot parse module ${q(moduleSpecifier)} in package ${q(
-            packageLocation,
-          )} in archive ${q(archiveLocation)}`,
-        );
-      }
-      if (parserForLanguage[module.parser] === undefined) {
-        throw Error(
-          `Cannot parse ${q(module.parser)} module ${q(
-            moduleSpecifier,
-          )} in package ${q(packageLocation)} in archive ${q(archiveLocation)}`,
-        );
-      }
-      const { parse } = parserForLanguage[module.parser];
-      const moduleLocation = `${packageLocation}/${module.location}`;
-      const moduleBytes = get(moduleLocation);
-
-      if (computeSha512 !== undefined && module.sha512 !== undefined) {
-        const sha512 = computeSha512(moduleBytes);
-        if (sha512 !== module.sha512) {
-          throw Error(
-            `Module ${q(module.location)} of package ${q(
-              packageLocation,
-            )} in archive ${q(
-              archiveLocation,
-            )} failed a SHA-512 integrity check`,
-          );
-        }
-      }
-
-      let sourceLocation = `file:///${moduleLocation}`;
-      if (packageName !== undefined) {
-        const base = packageName.split('/').slice(-1).join('/');
-        sourceLocation = `.../${join(base, moduleSpecifier)}`;
-      }
-      if (computeSourceLocation !== undefined) {
-        sourceLocation =
-          computeSourceLocation(packageLocation, moduleSpecifier) ||
-          sourceLocation;
-      }
-
-      let sourceMapUrl;
-      if (
-        computeSourceMapLocation !== undefined &&
-        module.sha512 !== undefined
-      ) {
-        sourceMapUrl = computeSourceMapLocation({
-          compartment: packageLocation,
-          module: moduleSpecifier,
-          location: sourceLocation,
-          sha512: module.sha512,
-        });
-      }
-
-      // eslint-disable-next-line no-await-in-loop
-      const { record } = await parse(
-        moduleBytes,
-        moduleSpecifier,
-        sourceLocation,
-        packageLocation,
-        {
-          sourceMapUrl,
-        },
-      );
-      return { record, specifier: moduleSpecifier };
-    };
-    return importHook;
-  };
-  return makeImportHook;
-};
 
 /**
- * Creates a fake module namespace object that passes a brand check.
- *
- * @param {typeof Compartment} Compartment
- * @returns {import('ses').ModuleExportsNamespace}
+ * Add the default parserForLanguage option.
+ * @param {Options} [options]
+ * @returns {Options}
  */
-const makeFauxModuleExportsNamespace = Compartment => {
-  const compartment = new Compartment(
-    {},
-    {},
-    {
-      resolveHook() {
-        return '.';
-      },
-      async importHook() {
-        return {
-          imports: [],
-          execute() {},
-          exports: [],
-        };
-      },
-    },
+const assignParserForLanguage = (options = {}) => {
+  const { parserForLanguage: parserForLanguageOption, ...rest } = options;
+  /** @type {ParserForLanguage} */
+  const parserForLanguage = freeze(
+    assign(create(null), defaultParserForLanguage, parserForLanguageOption),
   );
-  return compartment.module('.');
+  return { ...rest, parserForLanguage };
 };
 
-// Have to give it a name to capture the external meaning of Compartment
-// Otherwise @param {typeof Compartment} takes the Compartment to mean
-// the const variable defined within the function.
-/** @typedef {typeof Compartment} CompartmentConstructor */
-
 /**
  * @param {Uint8Array} archiveBytes
  * @param {string} [archiveLocation]
- * @param {object} [options]
- * @param {string} [options.expectedSha512]
- * @param {HashFn} [options.computeSha512]
- * @param {Record<string, unknown>} [options.modules]
- * @param {ExitModuleImportHook} [options.importHook]
- * @param {CompartmentConstructor} [options.Compartment]
- * @param {ComputeSourceLocationHook} [options.computeSourceLocation]
- * @param {ComputeSourceMapLocationHook} [options.computeSourceMapLocation]
+ * @param {Options} [options]
  * @returns {Promise<Application>}
  */
 export const parseArchive = async (
   archiveBytes,
   archiveLocation = '<unknown>',
   options = {},
-) => {
-  const {
-    computeSha512 = undefined,
-    expectedSha512 = undefined,
-    computeSourceLocation = undefined,
-    computeSourceMapLocation = undefined,
-    Compartment = DefaultCompartment,
-    modules = undefined,
-    importHook: exitModuleImportHook = undefined,
-  } = options;
-
-  const compartmentExitModuleImportHook = exitModuleImportHookMaker({
-    modules,
-    exitModuleImportHook,
-  });
-
-  const archive = new ZipReader(archiveBytes, { name: archiveLocation });
-
-  // Track all modules that get loaded, all files that are used.
-  const unseen = new Set(archive.files.keys());
-  unseen.size >= 2 ||
-    Fail`Archive failed sanity check: should contain at least a compartment map file and one module file in ${q(
-      archiveLocation,
-    )}`;
-
-  /**
-   * @param {string} path
-   */
-  const get = path => {
-    unseen.delete(path);
-    return archive.read(path);
-  };
-
-  const compartmentMapBytes = get('compartment-map.json');
-
-  let sha512;
-  if (computeSha512 !== undefined) {
-    sha512 = computeSha512(compartmentMapBytes);
-  }
-  if (expectedSha512 !== undefined) {
-    if (sha512 === undefined) {
-      throw Error(
-        `Cannot verify expectedSha512 without also providing computeSha512, for archive ${archiveLocation}`,
-      );
-    }
-    if (sha512 !== expectedSha512) {
-      throw Error(
-        `Archive compartment map failed a SHA-512 integrity check, expected ${expectedSha512}, got ${sha512}, for archive ${archiveLocation}`,
-      );
-    }
-  }
-  const compartmentMapText = textDecoder.decode(compartmentMapBytes);
-  const compartmentMap = parseLocatedJson(
-    compartmentMapText,
-    'compartment-map.json',
+) =>
+  parseArchiveLite(
+    archiveBytes,
+    archiveLocation,
+    assignParserForLanguage(options),
   );
-  assertCompartmentMap(compartmentMap, archiveLocation);
-
-  const {
-    compartments,
-    entry: { module: moduleSpecifier },
-  } = compartmentMap;
-
-  // Archive integrity checks: ensure every module is pre-loaded so its hash
-  // gets checked, and ensure that every file in the archive is used, and
-  // therefore checked.
-  if (computeSha512 !== undefined) {
-    const makeImportHook = makeArchiveImportHookMaker(
-      get,
-      compartments,
-      archiveLocation,
-      computeSha512,
-      computeSourceLocation,
-      compartmentExitModuleImportHook,
-      computeSourceMapLocation,
-    );
-    // A weakness of the current Compartment design is that the `modules` map
-    // must be given a module namespace object that passes a brand check.
-    // We don't have module instances for the preload phase, so we supply fake
-    // namespaces.
-    const { compartment, pendingJobsPromise } = link(compartmentMap, {
-      makeImportHook,
-      parserForLanguage,
-      modules: Object.fromEntries(
-        Object.keys(modules || {}).map(specifier => {
-          return [specifier, makeFauxModuleExportsNamespace(Compartment)];
-        }),
-      ),
-      Compartment,
-    });
-
-    await pendingJobsPromise;
-
-    await compartment.load(moduleSpecifier);
-    unseen.size === 0 ||
-      Fail`Archive contains extraneous files: ${q([...unseen])} in ${q(
-        archiveLocation,
-      )}`;
-  }
-
-  /** @type {ExecuteFn} */
-  const execute = async options => {
-    const {
-      globals,
-      modules,
-      transforms,
-      __shimTransforms__,
-      Compartment,
-      importHook: exitModuleImportHook,
-    } = options || {};
-
-    const compartmentExitModuleImportHook = exitModuleImportHookMaker({
-      modules,
-      exitModuleImportHook,
-    });
-    const makeImportHook = makeArchiveImportHookMaker(
-      get,
-      compartments,
-      archiveLocation,
-      computeSha512,
-      computeSourceLocation,
-      compartmentExitModuleImportHook,
-      computeSourceMapLocation,
-    );
-    const { compartment, pendingJobsPromise } = link(compartmentMap, {
-      makeImportHook,
-      parserForLanguage,
-      globals,
-      modules,
-      transforms,
-      __shimTransforms__,
-      Compartment,
-    });
-
-    await pendingJobsPromise;
-
-    // eslint-disable-next-line dot-notation
-    return compartment['import'](moduleSpecifier);
-  };
-
-  return { import: execute, sha512 };
-};
 
 /**
  * @param {import('@endo/zip').ReadFn | ReadPowers} readPowers
@@ -408,27 +89,12 @@ export const parseArchive = async (
  * @param {LoadArchiveOptions} [options]
  * @returns {Promise<Application>}
  */
-export const loadArchive = async (
-  readPowers,
-  archiveLocation,
-  options = {},
-) => {
-  const { read, computeSha512 } = unpackReadPowers(readPowers);
-  const {
-    expectedSha512,
-    computeSourceLocation,
-    modules,
-    computeSourceMapLocation,
-  } = options;
-  const archiveBytes = await read(archiveLocation);
-  return parseArchive(archiveBytes, archiveLocation, {
-    computeSha512,
-    expectedSha512,
-    computeSourceLocation,
-    modules,
-    computeSourceMapLocation,
-  });
-};
+export const loadArchive = async (readPowers, archiveLocation, options) =>
+  loadArchiveLite(
+    readPowers,
+    archiveLocation,
+    assignParserForLanguage(options),
+  );
 
 /**
  * @param {import('@endo/zip').ReadFn | ReadPowers} readPowers
@@ -436,7 +102,9 @@ export const loadArchive = async (
  * @param {ExecuteOptions & LoadArchiveOptions} options
  * @returns {Promise<object>}
  */
-export const importArchive = async (readPowers, archiveLocation, options) => {
-  const archive = await loadArchive(readPowers, archiveLocation, options);
-  return archive.import(options);
-};
+export const importArchive = async (readPowers, archiveLocation, options) =>
+  importArchiveLite(
+    readPowers,
+    archiveLocation,
+    assignParserForLanguage(options),
+  );

package/src/import-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-hook.d.ts","sourceRoot":"","sources":["import-hook.js"],"names":[],"mappings":"AAuEO;cAJI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;qCA4B7B;AAuBM,mFAnBI,MAAM;IAEY,OAAO;IACuB,sBAAsB;IACpD,WAAW;IACZ,aAAa;IACN,cAAc;IAOtB,oBAAoB,EAApC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACyB,oBAAoB;IACN,aAAa;oBAsRpE;0CA3XuC,YAAY;4BAR1B,YAAY;gCACR,YAAY;6BAEf,YAAY;2CAEE,YAAY;4BAH3B,YAAY;qCAIH,YAAY"}
+{"version":3,"file":"import-hook.d.ts","sourceRoot":"","sources":["import-hook.js"],"names":[],"mappings":"AA4EO,8EAJJ;IAAqC,OAAO,GAApC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YAAC;IACU,oBAAoB,GAAlD,oBAAoB,YAAC;CAC7B,GAAU,oBAAoB,GAAC,SAAS,CA0B1C;AAuBM,gDApBI,MAAM,GAAC,UAAU,gBACjB,MAAM,qKAEd;IAA0B,OAAO;IACuB,sBAAsB;IACpD,WAAW;IACZ,aAAa;IACN,cAAc;IAOtB,oBAAoB,EAApC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACyB,oBAAoB;IACN,aAAa;CAClE,GAAU,eAAe,CAuR3B;0CA7XuC,YAAY;4BAN1B,YAAY;gCACR,YAAY;6BAEf,YAAY;2CACE,YAAY;4BAF3B,YAAY;qCAGH,YAAY"}

package/src/import-hook.js

@@ -1,17 +1,22 @@
+/* Provides the implementation of each compartment's `importHook` when using
+ * `import.js`, `import-lite.js`, `archive.js`, or `archive-lite.js`.
+ * However, `import-archive.js` and `import-archive-lite.js` use their own variant.
+ *
+ * For building archives, these import hooks create a table of all the modules
+ * in a "working set" of transitive dependencies.
+ */
+
 // @ts-check
 
 /** @import {ImportHook} from 'ses' */
 /** @import {StaticModuleType} from 'ses' */
 /** @import {RedirectStaticModuleInterface} from 'ses' */
-/** @import {ThirdPartyStaticModuleInterface} from 'ses' */
 /** @import {ReadFn} from './types.js' */
 /** @import {ReadPowers} from './types.js' */
 /** @import {HashFn} from './types.js' */
 /** @import {Sources} from './types.js' */
-/** @import {CompartmentSources} from './types.js' */
 /** @import {CompartmentDescriptor} from './types.js' */
 /** @import {ImportHookMaker} from './types.js' */
-/** @import {DeferredAttenuatorsProvider} from './types.js' */
 /** @import {ExitModuleImportHook} from './types.js' */
 
 import { attenuateModuleHook, enforceModulePolicy } from './policy.js';
@@ -204,6 +209,7 @@ export const makeImportHookMaker = (
 
     /** @type {ImportHook} */
     const importHook = async moduleSpecifier => {
+      await null;
       compartmentDescriptor.retained = true;
 
       // per-module:
@@ -316,6 +322,7 @@ export const makeImportHookMaker = (
                 (nextSourceMapObject => {
                   sourceMap = JSON.stringify(nextSourceMapObject);
                 }),
+              compartmentDescriptor,
             },
           );
           const {

package/src/import-lite.d.ts

@@ -0,0 +1,9 @@
+export function loadFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: import("./types.js").ArchiveOptions | undefined): Promise<Application>;
+export function importFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ImportLocationOptions | undefined): Promise<SomeObject>;
+import type { ReadFn } from './types.js';
+import type { ReadPowers } from './types.js';
+import type { CompartmentMapDescriptor } from './types.js';
+import type { Application } from './types.js';
+import type { ImportLocationOptions } from './types.js';
+import type { SomeObject } from './types.js';
+//# sourceMappingURL=import-lite.d.ts.map

package/src/import-lite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-lite.d.ts","sourceRoot":"","sources":["import-lite.js"],"names":[],"mappings":"AA0CO,wCALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,8DAEtB,OAAO,CAAC,WAAW,CAAC,CAgEhC;AASM,0CANI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,gDAEtB,OAAO,CAAC,UAAU,CAAC,CAU/B;4BAhGyB,YAAY;gCACR,YAAY;8CANE,YAAY;iCACzB,YAAY;2CACF,YAAY;gCAKvB,YAAY"}