@endo/compartment-mapper 1.6.3 → 2.1.0

package/src/capture-lite.js

@@ -30,45 +30,68 @@
  */
 
 /* eslint no-shadow: 0 */
+/* global globalThis */
 
 /**
  * @import {
  *   CaptureLiteOptions,
  *   CaptureResult,
- *   CompartmentMapDescriptor,
+ *   PackageCompartmentMapDescriptor,
+ *   PreloadOption,
+ *   MakeLoadCompartmentsOptions,
  *   ReadFn,
  *   ReadPowers,
  *   Sources,
+ *   CaptureCompartmentMapOptions,
  * } from './types.js'
  */
 
+import { digestCompartmentMap } from './digest.js';
 import {
   exitModuleImportHookMaker,
   makeImportHookMaker,
 } from './import-hook.js';
 import { link } from './link.js';
 import { resolve } from './node-module-specifier.js';
+import { ATTENUATORS_COMPARTMENT, ENTRY_COMPARTMENT } from './policy-format.js';
 import { detectAttenuators } from './policy.js';
 import { unpackReadPowers } from './powers.js';
-import { digestCompartmentMap } from './digest.js';
 
-const { freeze, assign, create } = Object;
+const { freeze, assign, create, keys, entries } = Object;
+const { quote: q } = assert;
+const noop = () => {};
+
+/**
+ * The name of the module to preload if no entry is provided in a {@link PreloadOption} array
+ */
+const DEFAULT_PRELOAD_ENTRY = '.';
 
-const defaultCompartment = Compartment;
+const DefaultCompartment = /** @type {typeof Compartment} */ (
+  // @ts-expect-error globalThis.Compartment is definitely on globalThis.
+  globalThis.Compartment
+);
 
 /**
- * @param {CompartmentMapDescriptor} compartmentMap
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
  * @param {Sources} sources
+ * @param {CaptureCompartmentMapOptions} options
  * @returns {CaptureResult}
  */
-const captureCompartmentMap = (compartmentMap, sources) => {
+const captureCompartmentMap = (
+  compartmentMap,
+  sources,
+  { packageConnectionsHook, log = noop } = {},
+) => {
   const {
     compartmentMap: captureCompartmentMap,
     sources: captureSources,
     newToOldCompartmentNames,
     compartmentRenames,
     oldToNewCompartmentNames,
-  } = digestCompartmentMap(compartmentMap, sources);
+  } = digestCompartmentMap(compartmentMap, sources, {
+    packageConnectionsHook,
+    log,
+  });
   return {
     captureCompartmentMap,
     captureSources,
@@ -79,12 +102,190 @@ const captureCompartmentMap = (compartmentMap, sources) => {
 };
 
 /**
- * @param {ReadFn | ReadPowers} powers
- * @param {CompartmentMapDescriptor} compartmentMap
+ * Factory for a function that loads compartments.
+ *
+ * @param {PackageCompartmentMapDescriptor} compartmentMap Compartment map
+ * @param {Sources} sources Sources
+ * @param {MakeLoadCompartmentsOptions} [options]
+ * @returns {(linkedCompartments: Record<string, Compartment>, entryCompartment: Compartment, attenuatorsCompartment: Compartment) => Promise<void>}
+ */
+const makePreloader = (
+  compartmentMap,
+  sources,
+  {
+    log = noop,
+    policy,
+    _preload: preload = [],
+    _redundantPreloadHook: redundantPreloadHook = undefined,
+  } = {},
+) => {
+  const {
+    entry: { module: entryModuleSpecifier },
+  } = compartmentMap;
+
+  /**
+   * Iterates over canonical names in the {@link preload preload array}
+   * and loads those which have not yet been loaded.
+   *
+   * Will not load the "attenuators" `Compartment`, nor will it load any
+   * `Compartment` having a non-empty value in `sources` (since it is presumed
+   * it has already been loaded).
+   *
+   * @param {Record<string, Compartment>} compartments
+   * @returns {Promise<void>} Resolves when all appropriate compartments are
+   * loaded.
+   */
+  const preloader = async compartments => {
+    /** @type {[compartmentName: string, compartment: Compartment, moduleSpecifier: string][]} */
+    const compartmentsToLoad = [];
+
+    for (const preloadValue of preload) {
+      /** @type {string} */
+      let canonicalName;
+      /** @type {string} */
+      let entry;
+      if (typeof preloadValue === 'string') {
+        canonicalName = preloadValue;
+        entry = DEFAULT_PRELOAD_ENTRY;
+      } else {
+        canonicalName = preloadValue.compartment;
+        entry = preloadValue.entry;
+      }
+
+      // skip; should already be loaded
+      if (
+        canonicalName !== ATTENUATORS_COMPARTMENT &&
+        canonicalName !== ENTRY_COMPARTMENT
+      ) {
+        // TODO: A mapping of canonical name to compartment name is generated by
+        // mapNodeModules(), but it is not exposed. Expose it as an option on
+        // mapNodeModules() to be mutated and allow it as an option to
+        // captureFromMap() so we do not have to do this extra work. The data we
+        // need is _also_ generated by digestCompartmentMap() as the
+        // newToOldCompartmentNames property, but we cannot time-travel.
+        const [compartmentName, compartmentDescriptor] = entries(
+          compartmentMap.compartments,
+        ).find(([, compartment]) => compartment.label === canonicalName) ?? [
+          canonicalName,
+          compartmentMap.compartments[canonicalName],
+        ];
+
+        if (!compartmentDescriptor) {
+          throw new ReferenceError(
+            `Failed attempting to preload unknown compartment ${q(canonicalName)}`,
+          );
+        }
+
+        const compartmentSources = sources[compartmentName];
+
+        // The default preload entry is the entry module as defined by the
+        // package itself. This corresponds to the `ModuleConfiguration` of `.`
+        // in the `CompartmentDescriptor`'s `modules` object. Since the key in
+        // `compartmentSources` is presumably a resolved relative path, we don't
+        // actually know which key to look for! Thus, we are assuming that the
+        // `Compartment`'s entry module has been loaded if _any_ sources are
+        // present.
+        const entryIsLoaded =
+          entry === DEFAULT_PRELOAD_ENTRY
+            ? keys(compartmentSources).length > 0
+            : entry in compartmentSources;
+
+        if (entryIsLoaded) {
+          log(
+            `Refusing to preload Compartment ${q(canonicalName)} entry ${q(entry)}; already loaded`,
+          );
+          if (redundantPreloadHook) {
+            redundantPreloadHook({
+              canonicalName,
+              entry,
+              log,
+            });
+          }
+        } else {
+          const compartment = compartments[compartmentName];
+          if (!compartment) {
+            throw new ReferenceError(
+              `No compartment found for ${q(canonicalName)}`,
+            );
+          }
+
+          compartmentsToLoad.push([canonicalName, compartment, entry]);
+        }
+      }
+    }
+
+    const { length: compartmentsToLoadCount } = compartmentsToLoad;
+
+    /**
+     * This index increments in the order in which compartments finish
+     * loading—_not_ the order in which they began loading.
+     */
+    let loadedCompartmentIndex = 0;
+    await Promise.all(
+      compartmentsToLoad.map(
+        async ([compartmentName, compartment, moduleSpecifier]) => {
+          await compartment.load(moduleSpecifier);
+          loadedCompartmentIndex += 1;
+          log(
+            `Force-loaded Compartment: ${q(compartmentName)} (${loadedCompartmentIndex}/${compartmentsToLoadCount})`,
+          );
+        },
+      ),
+    );
+  };
+
+  /**
+   * Loads, in order:
+   *
+   * 1. The entry compartment
+   * 2. The attenuators compartment (_if and only if_ `policy` was provided)
+   * 3. All modules scheduled for preloading
+   *
+   * @param {Record<string, Compartment>} linkedCompartments
+   * @param {Compartment} entryCompartment
+   * @param {Compartment} attenuatorsCompartment
+   * @returns {Promise<void>} Resolves when all compartments are loaded.
+   */
+  const loadCompartments = async (
+    linkedCompartments,
+    entryCompartment,
+    attenuatorsCompartment,
+  ) => {
+    await entryCompartment.load(entryModuleSpecifier);
+
+    if (policy) {
+      // retain all attenuators.
+      await Promise.all(
+        detectAttenuators(policy).map(attenuatorSpecifier =>
+          attenuatorsCompartment.load(attenuatorSpecifier),
+        ),
+      );
+    }
+
+    await preloader(linkedCompartments);
+  };
+
+  return loadCompartments;
+};
+
+/**
+ * "Captures" the compartment map descriptors and sources from a partially
+ * completed compartment map—_without_ creating an archive.
+ *
+ * The resulting compartment map represents a well-formed dependency graph,
+ * laden with useful metadata. This, for example, could be used for automatic
+ * policy generation.
+ *
+ * @param {ReadFn | ReadPowers} readPowers Powers
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
  * @param {CaptureLiteOptions} [options]
  * @returns {Promise<CaptureResult>}
  */
-export const captureFromMap = async (powers, compartmentMap, options = {}) => {
+export const captureFromMap = async (
+  readPowers,
+  compartmentMap,
+  options = {},
+) => {
   const {
     moduleTransforms,
     syncModuleTransforms,
@@ -94,14 +295,18 @@ export const captureFromMap = async (powers, compartmentMap, options = {}) => {
     policy = undefined,
     sourceMapHook = undefined,
     parserForLanguage: parserForLanguageOption = {},
-    Compartment = defaultCompartment,
+    Compartment: CompartmentOption = DefaultCompartment,
+    log = noop,
+    _preload: preload = [],
+    _redundantPreloadHook: redundantPreloadHook = undefined,
+    packageConnectionsHook,
+    moduleSourceHook,
   } = options;
-
   const parserForLanguage = freeze(
     assign(create(null), parserForLanguageOption),
   );
 
-  const { read, computeSha512 } = unpackReadPowers(powers);
+  const { read, computeSha512 } = unpackReadPowers(readPowers);
 
   const {
     compartments,
@@ -111,6 +316,13 @@ export const captureFromMap = async (powers, compartmentMap, options = {}) => {
   /** @type {Sources} */
   const sources = Object.create(null);
 
+  const loadCompartments = makePreloader(compartmentMap, sources, {
+    log,
+    policy,
+    _preload: preload,
+    _redundantPreloadHook: redundantPreloadHook,
+  });
+
   const consolidatedExitModuleImportHook = exitModuleImportHookMaker({
     modules: exitModules,
     exitModuleImportHook,
@@ -127,26 +339,32 @@ export const captureFromMap = async (powers, compartmentMap, options = {}) => {
     entryModuleSpecifier,
     importHook: consolidatedExitModuleImportHook,
     sourceMapHook,
+    moduleSourceHook,
   });
+
   // Induce importHook to record all the necessary modules to import the given module specifier.
-  const { compartment, attenuatorsCompartment } = link(compartmentMap, {
+  const {
+    compartment: entryCompartment,
+    compartments: linkedCompartments,
+    attenuatorsCompartment,
+  } = link(compartmentMap, {
     resolve,
     makeImportHook,
     moduleTransforms,
     syncModuleTransforms,
     parserForLanguage,
     archiveOnly: true,
-    Compartment,
+    Compartment: CompartmentOption,
   });
-  await compartment.load(entryModuleSpecifier);
-  if (policy) {
-    // retain all attenuators.
-    await Promise.all(
-      detectAttenuators(policy).map(attenuatorSpecifier =>
-        attenuatorsCompartment.load(attenuatorSpecifier),
-      ),
-    );
-  }
 
-  return captureCompartmentMap(compartmentMap, sources);
+  await loadCompartments(
+    linkedCompartments,
+    entryCompartment,
+    attenuatorsCompartment,
+  );
+
+  return captureCompartmentMap(compartmentMap, sources, {
+    packageConnectionsHook,
+    log,
+  });
 };

package/src/compartment-map.d.ts

@@ -1,5 +1,12 @@
 /** @type {(a: string, b: string) => number} */
 export const stringCompare: (a: string, b: string) => number;
-export function assertCompartmentMap(allegedCompartmentMap: unknown, url?: string): asserts allegedCompartmentMap is CompartmentMapDescriptor;
-import type { CompartmentMapDescriptor } from './types.js';
+export function assertFileCompartmentMap(allegedCompartmentMap: unknown, url?: string): asserts allegedCompartmentMap is FileCompartmentMapDescriptor;
+export function assertDigestedCompartmentDescriptors(allegedCompartments: unknown, url?: string): asserts allegedCompartments is Record<string, DigestedCompartmentDescriptor>;
+export function assertDigestedCompartmentMap(allegedCompartmentMap: unknown, url?: string): asserts allegedCompartmentMap is DigestedCompartmentMapDescriptor;
+export function assertPackageCompartmentMap(allegedCompartmentMap: unknown, url?: string): asserts allegedCompartmentMap is PackageCompartmentMapDescriptor;
+export type AssertFn<T = string> = (value: unknown, keypath: string, url: string) => void;
+import type { FileCompartmentMapDescriptor } from './types.js';
+import type { DigestedCompartmentDescriptor } from './types.js';
+import type { DigestedCompartmentMapDescriptor } from './types.js';
+import type { PackageCompartmentMapDescriptor } from './types.js';
 //# sourceMappingURL=compartment-map.d.ts.map

package/src/compartment-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compartment-map.d.ts","sourceRoot":"","sources":["compartment-map.js"],"names":[],"mappings":"AAYA,+CAA+C;AAE/C,4BAFW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAE2B;AA8Z/D,4DALI,OAAO,QACP,MAAM,GACJ,QAAQ,qBAAqB,IAAI,wBAAwB,CA+BrE;8CApc2C,YAAY"}
+{"version":3,"file":"compartment-map.d.ts","sourceRoot":"","sources":["compartment-map.js"],"names":[],"mappings":"AAyCA,+CAA+C;AAE/C,4BAFW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAE2B;AA60B/D,gEAJI,OAAO,QACP,MAAM,GACJ,QAAQ,qBAAqB,IAAI,4BAA4B,CASzE;AAQM,0EAJI,OAAO,QACP,MAAM,GACJ,QAAQ,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAUxF;AAQM,oEAJI,OAAO,QACP,MAAM,GACJ,QAAQ,qBAAqB,IAAI,gCAAgC,CAS7E;AAOM,mEAJI,OAAO,QACP,MAAM,GACJ,QAAQ,qBAAqB,IAAI,+BAA+B,CAS5E;qBApca,CAAC,aACF,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI;kDA3c1B,YAAY;mDAAZ,YAAY;sDAAZ,YAAY;qDAAZ,YAAY"}