@endo/compartment-mapper 1.6.2 → 2.0.0

package/src/node-modules.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-underscore-dangle */
 /**
  * Provides functions for constructing a compartment map that has a
  * compartment descriptor corresponding to every reachable package from an
@@ -13,22 +14,45 @@
 
 /* eslint no-shadow: 0 */
 
+import { inferExportsAndAliases } from './infer-exports.js';
+import { parseLocatedJson } from './json.js';
+import { join } from './node-module-specifier.js';
+import {
+  assertPolicy,
+  ATTENUATORS_COMPARTMENT,
+  ENTRY_COMPARTMENT,
+  generateCanonicalName,
+} from './policy-format.js';
+import { dependencyAllowedByPolicy, makePackagePolicy } from './policy.js';
+import { unpackReadPowers } from './powers.js';
+import { search, searchDescriptor } from './search.js';
+import { GenericGraph, makeShortestPath } from './generic-graph.js';
+
 /**
  * @import {
  *   CanonicalFn,
  *   CompartmentDescriptor,
  *   CompartmentMapDescriptor,
  *   CompartmentMapForNodeModulesOptions,
+ *   FileUrlString,
  *   LanguageForExtension,
  *   MapNodeModulesOptions,
+ *   MaybeReadDescriptorFn,
  *   MaybeReadFn,
  *   MaybeReadPowers,
  *   PackageDescriptor,
- *   ReadDescriptorFn,
  *   ReadFn,
  *   ReadPowers,
- *   SomePackagePolicy,
  *   SomePolicy,
+ *   LogFn,
+ *   CompartmentModuleConfiguration,
+ *   PackageCompartmentDescriptor,
+ *   PackageCompartmentMapDescriptor,
+ *   ScopeDescriptor,
+ *   CanonicalName,
+ *   SomePackagePolicy,
+ *   PackageCompartmentDescriptorName,
+ *   PackageData,
  * } from './types.js'
  * @import {
  *   Graph,
@@ -38,29 +62,21 @@
  *   GatherDependencyOptions,
  *   GraphPackageOptions,
  *   GraphPackagesOptions,
+ *   LogicalPathGraph,
  *   PackageDetails,
+ *   FinalGraph,
+ *   CanonicalNameMap,
+ *   FinalNode,
+ TranslateGraphOptions,
  * } from './types/node-modules.js'
  */
 
-import { pathCompare } from '@endo/path-compare';
-import { inferExportsAndAliases } from './infer-exports.js';
-import { parseLocatedJson } from './json.js';
-import { join } from './node-module-specifier.js';
-import { assertPolicy } from './policy-format.js';
-import {
-  ATTENUATORS_COMPARTMENT,
-  dependencyAllowedByPolicy,
-  getPolicyForPackage,
-} from './policy.js';
-import { unpackReadPowers } from './powers.js';
-import { search, searchDescriptor } from './search.js';
-
-const { assign, create, keys, values, entries } = Object;
+const { assign, create, keys, values, entries, freeze } = Object;
 
 const decoder = new TextDecoder();
 
 // q, as in quote, for enquoting strings in error messages.
-const q = JSON.stringify;
+const { quote: q } = assert;
 
 /**
  * Default logger that does nothing.
@@ -68,14 +84,103 @@ const q = JSON.stringify;
 const noop = () => {};
 
 /**
+ * Default handler for unknown canonical names found in policy.
+ * Logs a warning when a canonical name from policy is not found in the compartment map.
+ *
+ * @param {object} params
+ * @param {CanonicalName} params.canonicalName
+ * @param {string} params.message
+ * @param {LogFn} params.log
+ */
+const defaultUnknownCanonicalNameHandler = ({
+  canonicalName,
+  message,
+  log,
+}) => {
+  log(`WARN: Invalid resource ${q(canonicalName)} in policy: ${message}`);
+};
+
+/**
+ * Default filter for package dependencies based on policy.
+ * Filters out dependencies not allowed by the package policy.
+ *
+ * **Note:** This filter is _only_ applied if a policy is provided.
+ *
+ * @param {object} params - The parameters object
+ * @param {CanonicalName} params.canonicalName - The canonical name of the package
+ * @param {Readonly<Set<CanonicalName>>} params.dependencies - The set of dependencies
+ * @param {LogFn} params.log - The logging function
+ * @param {SomePolicy} policy - The policy to check against
+ * @returns {Partial<{ dependencies: Set<CanonicalName> }> | void}
+ */
+const prePackageDependenciesFilter = (
+  { canonicalName, dependencies, log },
+  policy,
+) => {
+  const packagePolicy = makePackagePolicy(canonicalName, { policy });
+  if (!packagePolicy) {
+    return { dependencies };
+  }
+  const filteredDependencies = new Set(
+    [...dependencies].filter(dependency => {
+      const allowed = dependencyAllowedByPolicy(dependency, packagePolicy);
+      if (!allowed) {
+        log(
+          `Excluding dependency ${q(dependency)} of package ${q(canonicalName)} per policy`,
+        );
+      }
+      return allowed;
+    }),
+  );
+
+  return { dependencies: filteredDependencies };
+};
+
+/**
+ * Given a relative path andd URL, return a fully qualified URL string.
+ *
+ * @overload
  * @param {string} rel - a relative URL
- * @param {string} abs - a fully qualified URL
- * @returns {string}
+ * @param {URL} abs - a fully qualified URL
+ * @returns {string} Fully qualified URL string
+ */
+
+/**
+ * Given a relative path and fully qualified stringlike URL, return a fully
+ * qualified stringlike URL.
+ *
+ * @template {string} [T=string] Type of fully qualified URL string
+ * @overload
+ * @param {string} rel - a relative URL
+ * @param {T} abs - a fully qualified URL
+ * @returns {T} Fully qualified stringlike URL
+ */
+
+/**
+ * @param {string} rel - a relative URL
+ * @param {string|URL} abs - a fully qualified URL
  */
 const resolveLocation = (rel, abs) => {
   return new URL(rel, abs).toString();
 };
 
+/**
+ * Ensures a string is a file URL (a {@link FileUrlString})
+ *
+ * @param {unknown} allegedPackageLocation - a package location to assert
+ * @returns {asserts allegedPackageLocation is FileUrlString}
+ */
+const assertFileUrlString = allegedPackageLocation => {
+  assert(
+    typeof allegedPackageLocation === 'string',
+    `Package location must be a string, got ${q(allegedPackageLocation)}`,
+  );
+  assert(
+    allegedPackageLocation.startsWith('file://'),
+    `Package location must be a file URL, got ${q(allegedPackageLocation)}`,
+  );
+};
+
 // Exported for testing:
 /**
  * @param {string} location
@@ -93,10 +198,28 @@ export const basename = location => {
   return pathname.slice(index + 1);
 };
 
+/**
+ * Asserts that the given value is a `PackageDescriptor`.
+ *
+ * TODO: This only validates that the value is a plain object. As mentioned in
+ * {@link PackageDescriptor}, `name` is currently a required field, but in the
+ * real world this is not so. We _do_ make assumptions about the shape of a
+ * `PackageDescriptor`, but it may not be worth eagerly validating further.
+ * @param {unknown} allegedPackageDescriptor
+ * @returns {asserts allegedPackageDescriptor is PackageDescriptor}
+ */
+const assertPackageDescriptor = allegedPackageDescriptor => {
+  assert(
+    typeof allegedPackageDescriptor !== 'function' &&
+      Object(allegedPackageDescriptor) === allegedPackageDescriptor,
+    `Package descriptor must be a plain object, got ${q(allegedPackageDescriptor)}`,
+  );
+};
+
 /**
  * @param {MaybeReadFn} maybeRead
  * @param {string} packageLocation
- * @returns {Promise<object>}
+ * @returns {Promise<PackageDescriptor|undefined>}
  */
 const readDescriptor = async (maybeRead, packageLocation) => {
   const descriptorLocation = resolveLocation('package.json', packageLocation);
@@ -106,16 +229,20 @@ const readDescriptor = async (maybeRead, packageLocation) => {
   }
   const descriptorText = decoder.decode(descriptorBytes);
   const descriptor = parseLocatedJson(descriptorText, descriptorLocation);
+  assertPackageDescriptor(descriptor);
   return descriptor;
 };
 
 /**
- * @param {Record<string, object>} memo
+ * Memoized {@link readDescriptor}
+ *
+ * @param {Record<string, Promise<PackageDescriptor|undefined>>} memo
  * @param {MaybeReadFn} maybeRead
  * @param {string} packageLocation
- * @returns {Promise<object>}
+ * @returns {Promise<PackageDescriptor|undefined>}
  */
 const readDescriptorWithMemo = async (memo, maybeRead, packageLocation) => {
+  /** @type {Promise<PackageDescriptor|undefined>} */
   let promise = memo[packageLocation];
   if (promise !== undefined) {
     return promise;
@@ -125,90 +252,6 @@ const readDescriptorWithMemo = async (memo, maybeRead, packageLocation) => {
   return promise;
 };
 
-/**
- * Compares `logicalPath` to the current best logical path in `preferredPackageLogicalPathMap` for `packageLocation`.
- *
- * If no current best path exists, it returns `logicalPath`.
- *
- * @template {string[]} T
- * @template {string[]} U
- * @param {T} logicalPath
- * @param {string} packageLocation
- * @param {Map<string, U>} preferredPackageLogicalPathMap
- * @returns {T|U}
- */
-const currentBestLogicalPath = (
-  logicalPath,
-  packageLocation,
-  preferredPackageLogicalPathMap,
-) => {
-  const theCurrentBest = preferredPackageLogicalPathMap.get(packageLocation);
-  if (theCurrentBest === undefined) {
-    return logicalPath;
-  }
-  return pathCompare(logicalPath, theCurrentBest) < 0
-    ? logicalPath
-    : theCurrentBest;
-};
-
-/**
- * Updates the shortest paths in a subgraph of `graph` starting with `packageLocation`.
- *
- * This should be called upon the second (and each subsequent) visit to a graph node.
- *
- * @param {Graph} graph Graph
- * @param {string} packageLocation Location of the package to start with
- * @param {string[]} logicalPath Current path parts of the same package
- * @param {Map<string, string[]>} [preferredPackageLogicalPathMap] Mapping of shortest known paths for each package location
- * @returns {void}
- */
-const updateShortestPaths = (
-  graph,
-  packageLocation,
-  logicalPath,
-  preferredPackageLogicalPathMap = new Map(),
-) => {
-  const node = graph[packageLocation];
-  if (!node) {
-    throw new ReferenceError(
-      `Cannot find package at ${packageLocation} in graph`,
-    );
-  }
-
-  const bestLogicalPath = currentBestLogicalPath(
-    logicalPath,
-    packageLocation,
-    preferredPackageLogicalPathMap,
-  );
-
-  if (bestLogicalPath === logicalPath) {
-    preferredPackageLogicalPathMap.set(packageLocation, bestLogicalPath);
-
-    for (const name of keys(node.dependencyLocations).sort()) {
-      const packageLocation = node.dependencyLocations[name];
-      if (!packageLocation) {
-        // "should never happen"
-        throw new ReferenceError(
-          `Expected graph node ${q(node.name)} to contain a dependency location for ${q(name)}`,
-        );
-      }
-      updateShortestPaths(
-        graph,
-        packageLocation,
-        [...logicalPath, name],
-        preferredPackageLogicalPathMap,
-      );
-    }
-  }
-
-  // a path length of 0 means the node represents the eventual entry compartment.
-  // we do not want to mess with that path.
-  if (node.path.length && node.path !== bestLogicalPath) {
-    node.path = bestLogicalPath;
-  }
-
-  return undefined;
-};
 /**
  * `findPackage` behaves as Node.js to find third-party modules by searching
  * parent to ancestor directories for a `node_modules` directory that contains
@@ -218,9 +261,9 @@ const updateShortestPaths = (
  * these are the locations that package managers drop a package so Node.js can
  * find it efficiently.
  *
- * @param {ReadDescriptorFn} readDescriptor
+ * @param {MaybeReadDescriptorFn} readDescriptor
  * @param {CanonicalFn} canonical
- * @param {string} directory
+ * @param {FileUrlString} directory
  * @param {string} name
  * @returns {Promise<PackageDetails|undefined>}
  */
@@ -232,6 +275,10 @@ const findPackage = async (readDescriptor, canonical, directory, name) => {
       resolveLocation(`node_modules/${name}/`, directory),
     );
 
+    // We have no guarantee that `canonical` will return a file URL; it spits
+    // back whatever we give it if `fs.promises.realpath()` rejects.
+    assertFileUrlString(packageLocation);
+
     // eslint-disable-next-line no-await-in-loop
     const packageDescriptor = await readDescriptor(packageLocation);
     if (packageDescriptor !== undefined) {
@@ -339,6 +386,37 @@ const inferParsers = (descriptor, location, languageOptions) => {
   return { ...commonjsLanguageForExtension, ...packageLanguageForExtension };
 };
 
+/**
+ * This returns the "weight" of a package name, which is used when determining
+ * the shortest path.
+ *
+ * It is an analogue of the `pathCompare` function.
+ *
+ * The weight is calculated as follows:
+ *
+ * 1. The {@link String.length length} of the package name contributes a fixed
+ *    value of `0x10000` per character. This is because the `pathCompare`
+ *    algorithm first compares strings by length and only evaluates code unit
+ *    values if the lengths of two strings are equal. `0x10000` is one (1)
+ *    greater than the maximum value that {@link String.charCodeAt charCodeAt}
+ *    can return (`0xFFFF`), which guarantees longer strings will have higher
+ *    weights.
+ * 2. Each character in the package name contributes its UTF-16 code unit value
+ *    (`0x0` thru `0xFFFF`) to the total. This is the same operation used when
+ *    comparing two strings using comparison operators.
+ * 3. The total weight is the sum of 1. and 2.
+ *
+ * @param {string} packageName - Name of package to calculate weight for.
+ * @returns {number} Numeric weight
+ */
+const calculatePackageWeight = packageName => {
+  let totalCodeValue = packageName.length * 65536; // each character contributes 65536
+  for (let i = 0; i < packageName.length; i += 1) {
+    totalCodeValue += packageName.charCodeAt(i);
+  }
+  return totalCodeValue;
+};
+
 /**
  * `graphPackage` and {@link gatherDependency} are mutually recursive functions that
  * gather the metadata for a package and its transitive dependencies.
@@ -348,7 +426,7 @@ const inferParsers = (descriptor, location, languageOptions) => {
  * that the package exports.
  *
  * @param {string} name
- * @param {ReadDescriptorFn} readDescriptor
+ * @param {MaybeReadDescriptorFn} readDescriptor
  * @param {CanonicalFn} canonical
  * @param {Graph} graph
  * @param {PackageDetails} packageDetails
@@ -356,6 +434,7 @@ const inferParsers = (descriptor, location, languageOptions) => {
  * @param {boolean | undefined} dev
  * @param {LanguageOptions} languageOptions
  * @param {boolean} strict
+ * @param {LogicalPathGraph} logicalPathGraph
  * @param {GraphPackageOptions} options
  * @returns {Promise<undefined>}
  */
@@ -369,21 +448,15 @@ const graphPackage = async (
   dev,
   languageOptions,
   strict,
+  logicalPathGraph,
   {
     commonDependencyDescriptors = {},
-    preferredPackageLogicalPathMap = new Map(),
-    logicalPath = [],
     log = noop,
+    packageDependenciesHook,
+    policy,
   } = {},
 ) => {
   if (graph[packageLocation] !== undefined) {
-    updateShortestPaths(
-      graph,
-      packageLocation,
-      logicalPath,
-      preferredPackageLogicalPathMap,
-    );
-
     // Returning the promise here would create a causal cycle and stall recursion.
     return undefined;
   }
@@ -396,7 +469,7 @@ const graphPackage = async (
     });
   }
 
-  const result = /** @type {Node} */ ({});
+  const result = /** @type {Node} */ ({ location: packageLocation });
   graph[packageLocation] = result;
 
   /** @type {Node['dependencyLocations']} */
@@ -447,20 +520,19 @@ const graphPackage = async (
   // use the peerDependenciesMeta field (because there was no way to define
   // an "optional" peerDependency prior to npm v7). this is plainly wrong,
   // but not exactly rare, either
-  for (const [name, meta] of entries(peerDependenciesMeta)) {
+  for (const [dependencyName, meta] of entries(peerDependenciesMeta)) {
     if (Object(meta) === meta && meta.optional) {
-      optionals.add(name);
-      allDependencies.add(name);
+      optionals.add(dependencyName);
+      allDependencies.add(dependencyName);
     }
   }
 
-  for (const name of keys(optionalDependencies)) {
-    optionals.add(name);
+  for (const dependencyName of keys(optionalDependencies)) {
+    optionals.add(dependencyName);
   }
 
-  for (const name of [...allDependencies].sort()) {
-    const optional = optionals.has(name);
-    const childLogicalPath = [...logicalPath, name];
+  for (const dependencyName of [...allDependencies].sort()) {
+    const optional = optionals.has(dependencyName);
     children.push(
       // Mutual recursion ahead:
       // eslint-disable-next-line no-use-before-define
@@ -470,16 +542,17 @@ const graphPackage = async (
         graph,
         dependencyLocations,
         packageLocation,
-        name,
+        dependencyName,
         conditions,
-        preferredPackageLogicalPathMap,
         languageOptions,
         strict,
+        logicalPathGraph,
         {
-          childLogicalPath,
           optional,
           commonDependencyDescriptors,
           log,
+          packageDependenciesHook,
+          policy,
         },
       ),
     );
@@ -521,9 +594,9 @@ const graphPackage = async (
 
   const sourceDirname = basename(packageLocation);
 
-  assign(result, {
+  /** @type {Partial<Node>} */
+  const partialNode = {
     name,
-    path: logicalPath,
     label: `${name}${version ? `-v${version}` : ''}`,
     sourceDirname,
     explicitExports: exportsDescriptor !== undefined,
@@ -532,7 +605,9 @@ const graphPackage = async (
     dependencyLocations,
     types,
     parsers,
-  });
+    packageDescriptor,
+  };
+  assign(result, partialNode);
 
   await Promise.all(
     values(result.externalAliases).map(async item => {
@@ -579,17 +654,17 @@ const graphPackage = async (
 /**
  * Adds information for the dependency of the package at `packageLocation` to the `graph` object.
  *
- * @param {ReadDescriptorFn} readDescriptor
+ * @param {MaybeReadDescriptorFn} readDescriptor
  * @param {CanonicalFn} canonical
  * @param {Graph} graph - the partially build graph.
  * @param {Record<string, string>} dependencyLocations
- * @param {string} packageLocation - location of the package of interest.
+ * @param {FileUrlString} packageLocation - location of the package of interest.
  * @param {string} name - name of the package of interest.
  * @param {Set<string>} conditions
- * @param {Map<string, Array<string>>} preferredPackageLogicalPathMap
  * @param {LanguageOptions} languageOptions
  * @param {boolean} strict - If `true`, a missing dependency will throw an exception
- * @param {GatherDependencyOptions} options
+ * @param {LogicalPathGraph} logicalPathGraph
+ * @param {GatherDependencyOptions} [options]
  * @returns {Promise<void>}
  */
 const gatherDependency = async (
@@ -600,14 +675,15 @@ const gatherDependency = async (
   packageLocation,
   name,
   conditions,
-  preferredPackageLogicalPathMap,
   languageOptions,
   strict,
+  logicalPathGraph,
   {
-    childLogicalPath = [],
     optional = false,
     commonDependencyDescriptors = {},
     log = noop,
+    packageDependenciesHook,
+    policy,
   } = {},
 ) => {
   const dependency = await findPackage(
@@ -616,6 +692,7 @@ const gatherDependency = async (
     packageLocation,
     name,
   );
+
   if (dependency === undefined) {
     // allow the dependency to be missing if optional
     if (optional || !strict) {
@@ -623,21 +700,15 @@ const gatherDependency = async (
     }
     throw Error(`Cannot find dependency ${name} for ${packageLocation}`);
   }
+
   dependencyLocations[name] = dependency.packageLocation;
 
-  const bestLogicalPath = currentBestLogicalPath(
-    childLogicalPath,
+  logicalPathGraph.addEdge(
+    packageLocation,
     dependency.packageLocation,
-    preferredPackageLogicalPathMap,
+    calculatePackageWeight(name),
   );
 
-  if (bestLogicalPath === childLogicalPath) {
-    preferredPackageLogicalPathMap.set(
-      dependency.packageLocation,
-      bestLogicalPath,
-    );
-  }
-
   await graphPackage(
     name,
     readDescriptor,
@@ -648,11 +719,12 @@ const gatherDependency = async (
     false,
     languageOptions,
     strict,
+    logicalPathGraph,
     {
       commonDependencyDescriptors,
-      preferredPackageLogicalPathMap,
-      logicalPath: childLogicalPath,
       log,
+      packageDependenciesHook,
+      policy,
     },
   );
 };
@@ -663,7 +735,7 @@ const gatherDependency = async (
  *
  * @param {MaybeReadFn} maybeRead
  * @param {CanonicalFn} canonical
- * @param {string} packageLocation - location of the main package.
+ * @param {FileUrlString} packageLocation - location of the main package.
  * @param {Set<string>} conditions
  * @param {PackageDescriptor} mainPackageDescriptor - the parsed contents of the
  * main `package.json`, which was already read when searching for the
@@ -674,7 +746,9 @@ const gatherDependency = async (
  * to all packages
  * @param {LanguageOptions} languageOptions
  * @param {boolean} strict
+ * @param {LogicalPathGraph} logicalPathGraph
  * @param {GraphPackagesOptions} options
+ * @returns {Promise<Graph>}
  */
 const graphPackages = async (
   maybeRead,
@@ -686,12 +760,12 @@ const graphPackages = async (
   commonDependencies,
   languageOptions,
   strict,
-  { log = noop } = {},
+  logicalPathGraph,
+  { log = noop, packageDependenciesHook, policy } = {},
 ) => {
   const memo = create(null);
   /**
-   * @param {string} packageLocation
-   * @returns {Promise<PackageDescriptor>}
+   * @type {MaybeReadDescriptorFn}
    */
   const readDescriptor = packageLocation =>
     readDescriptorWithMemo(memo, maybeRead, packageLocation);
@@ -700,19 +774,22 @@ const graphPackages = async (
     memo[packageLocation] = Promise.resolve(mainPackageDescriptor);
   }
 
-  const packageDescriptor = await readDescriptor(packageLocation);
+  const allegedPackageDescriptor = await readDescriptor(packageLocation);
+
+  if (allegedPackageDescriptor === undefined) {
+    throw TypeError(
+      `Cannot find package.json for application at ${packageLocation}`,
+    );
+  }
+
+  assertPackageDescriptor(allegedPackageDescriptor);
+  const packageDescriptor = allegedPackageDescriptor;
 
   conditions = new Set(conditions || []);
   conditions.add('import');
   conditions.add('default');
   conditions.add('endo');
 
-  if (packageDescriptor === undefined) {
-    throw Error(
-      `Cannot find package.json for application at ${packageLocation}`,
-    );
-  }
-
   // Resolve common dependencies.
   /** @type {CommonDependencyDescriptors} */
   const commonDependencyDescriptors = {};
@@ -730,6 +807,8 @@ const graphPackages = async (
     };
   }
 
+  logicalPathGraph.addNode(packageLocation);
+
   const graph = create(null);
   await graphPackage(
     packageDescriptor.name,
@@ -744,9 +823,12 @@ const graphPackages = async (
     dev,
     languageOptions,
     strict,
+    logicalPathGraph,
     {
       commonDependencyDescriptors,
       log,
+      packageDependenciesHook,
+      policy,
     },
   );
   return graph;
@@ -761,19 +843,101 @@ const graphPackages = async (
  * @param {Graph} graph
  * @param {Set<string>} conditions - build conditions about the target environment
  * for selecting relevant exports, e.g., "browser" or "node".
- * @param {SomePolicy} [policy]
- * @returns {CompartmentMapDescriptor}
+ * @param {TranslateGraphOptions} [options]
+ * @returns {PackageCompartmentMapDescriptor}
  */
 const translateGraph = (
   entryPackageLocation,
   entryModuleSpecifier,
   graph,
   conditions,
-  policy,
+  { policy, log = noop, packageDependenciesHook } = {},
 ) => {
-  /** @type {CompartmentMapDescriptor['compartments']} */
+  /** @type {Record<PackageCompartmentDescriptorName, PackageCompartmentDescriptor>} */
   const compartments = create(null);
 
+  /**
+   * Execute package dependencies hooks: default first (if policy exists), then user-provided.
+   *
+   * @param {CanonicalName} label
+   * @param {Record<string, FileUrlString>} dependencyLocations
+   * @returns {Record<string, FileUrlString>}
+   */
+  const executePackageDependenciesHook = (label, dependencyLocations) => {
+    const dependencies = new Set(
+      values(dependencyLocations).map(
+        dependencyLocation => graph[dependencyLocation].label,
+      ),
+    );
+
+    const packageDependenciesHookInput = {
+      canonicalName: label,
+      dependencies: new Set(dependencies),
+      log,
+    };
+
+    // Call default filter first if policy exists
+    let packageDependenciesHookResult;
+    if (policy) {
+      packageDependenciesHookResult = prePackageDependenciesFilter(
+        packageDependenciesHookInput,
+        policy,
+      );
+    }
+
+    // Then call user-provided hook if it exists
+    if (packageDependenciesHook) {
+      const userResult = packageDependenciesHook(packageDependenciesHookInput);
+      // If user hook also returned a result, use it (overrides default)
+      if (userResult?.dependencies) {
+        packageDependenciesHookResult = userResult;
+      }
+    }
+
+    // if "dependencies" are in here, then something changed the list.
+    if (packageDependenciesHookResult?.dependencies) {
+      const size = packageDependenciesHookResult.dependencies.size;
+      if (typeof size === 'number' && size > 0) {
+        // because the list of dependencies contains canonical names, we need to lookup any new ones.
+        const nodesByCanonicalName = new Map(
+          entries(graph).map(([location, node]) => [
+            node.label,
+            {
+              ...node,
+              packageLocation: /** @type {FileUrlString} */ (location),
+            },
+          ]),
+        );
+
+        /** @type {typeof dependencyLocations} */
+        const newDependencyLocations = {};
+        try {
+          for (const label of packageDependenciesHookResult.dependencies) {
+            const { name, packageLocation } =
+              nodesByCanonicalName.get(label) ?? create(null);
+            if (name && packageLocation) {
+              newDependencyLocations[name] = packageLocation;
+            } else {
+              log(
+                `WARNING: packageDependencies hook returned unknown package with label ${q(label)}`,
+              );
+            }
+          }
+          return newDependencyLocations;
+        } catch {
+          log(
+            `WARNING: packageDependencies hook returned invalid value ${q(
+              packageDependenciesHookResult,
+            )}; using original dependencies`,
+          );
+        }
+      } else {
+        dependencyLocations = create(null);
+      }
+    }
+    return dependencyLocations;
+  };
+
   // For each package, build a map of all the external modules the package can
   // import from other packages.
   // The keys of this map are the full specifiers of those modules from the
@@ -783,36 +947,24 @@ const translateGraph = (
   // The full map includes every exported module from every dependencey
   // package and is a complete list of every external module that the
   // corresponding compartment can import.
-  for (const dependeeLocation of keys(graph).sort()) {
+  for (const dependeeLocation of /** @type {PackageCompartmentDescriptorName[]} */ (
+    keys(graph).sort()
+  )) {
     const {
       name,
-      path,
       label,
       sourceDirname,
-      dependencyLocations,
       internalAliases,
       parsers,
       types,
+      packageDescriptor,
     } = graph[dependeeLocation];
-    /** @type {CompartmentDescriptor['modules']} */
+    /** @type {Record<string, CompartmentModuleConfiguration>} */
     const moduleDescriptors = create(null);
-    /** @type {CompartmentDescriptor['scopes']} */
+    /** @type {Record<string, ScopeDescriptor<PackageCompartmentDescriptorName>>} */
     const scopes = create(null);
 
-    /**
-     * List of all the compartments (by name) that this compartment can import from.
-     *
-     * @type {Set<string>}
-     */
-    const compartmentNames = new Set();
-    const packagePolicy = getPolicyForPackage(
-      {
-        isEntry: dependeeLocation === entryPackageLocation,
-        name,
-        path,
-      },
-      policy,
-    );
+    const packagePolicy = makePackagePolicy(label, { policy });
 
     /* c8 ignore next */
     if (policy && !packagePolicy) {
@@ -820,34 +972,29 @@ const translateGraph = (
       throw new TypeError('Unexpectedly falsy package policy');
     }
 
+    let dependencyLocations = graph[dependeeLocation].dependencyLocations;
+    dependencyLocations = executePackageDependenciesHook(
+      label,
+      dependencyLocations,
+    );
+
     /**
      * @param {string} dependencyName
-     * @param {string} packageLocation
+     * @param {PackageCompartmentDescriptorName} packageLocation
      */
     const digestExternalAliases = (dependencyName, packageLocation) => {
-      const { externalAliases, explicitExports, name, path } =
-        graph[packageLocation];
+      const { externalAliases, explicitExports } = graph[packageLocation];
       for (const exportPath of keys(externalAliases).sort()) {
         const targetPath = externalAliases[exportPath];
         // dependency name may be different from package's name,
-        // as in the case of browser field dependency replacements
+        // as in the case of browser field dependency replacements.
+        // note that policy still applies
         const localPath = join(dependencyName, exportPath);
-        if (
-          !policy ||
-          (packagePolicy &&
-            dependencyAllowedByPolicy(
-              {
-                name,
-                path,
-              },
-              packagePolicy,
-            ))
-        ) {
-          moduleDescriptors[localPath] = {
-            compartment: packageLocation,
-            module: targetPath,
-          };
-        }
+        // if we have policy, this has already been vetted
+        moduleDescriptors[localPath] = {
+          compartment: packageLocation,
+          module: targetPath,
+        };
       }
       // if the exports field is not present, then all modules must be accessible
       if (!explicitExports) {
@@ -862,7 +1009,6 @@ const translateGraph = (
     for (const dependencyName of keys(dependencyLocations).sort()) {
       const dependencyLocation = dependencyLocations[dependencyName];
       digestExternalAliases(dependencyName, dependencyLocation);
-      compartmentNames.add(dependencyLocation);
     }
     // digest own internal aliases
     for (const modulePath of keys(internalAliases).sort()) {
@@ -879,9 +1025,9 @@ const translateGraph = (
     }
 
     compartments[dependeeLocation] = {
+      version: packageDescriptor.version ? packageDescriptor.version : '',
       label,
       name,
-      path,
       location: dependeeLocation,
       sourceDirname,
       modules: moduleDescriptors,
@@ -889,7 +1035,6 @@ const translateGraph = (
       parsers,
       types,
       policy: /** @type {SomePackagePolicy} */ (packagePolicy),
-      compartments: compartmentNames,
     };
   }
 
@@ -898,7 +1043,7 @@ const translateGraph = (
     // https://github.com/endojs/endo/issues/2388
     tags: [...conditions],
     entry: {
-      compartment: entryPackageLocation,
+      compartment: /** @type {FileUrlString} */ (entryPackageLocation),
       module: entryModuleSpecifier,
     },
     compartments,
@@ -972,23 +1117,200 @@ const makeLanguageOptions = ({
     workspaceModuleLanguageForExtension,
   };
 };
+/**
+ * Creates a `Node` in `graph` corresponding to the "attenuators" Compartment.
+ *
+ * Only does so if `policy` is provided.
+ *
+ * @param {Graph} graph Graph
+ * @param {Node} entryNode Entry node of the grpah
+ * @param {SomePolicy} [policy]
+ * @throws If there's already a `Node` in `graph` for the "attenuators"
+ * Compartment
+ * @returns {void}
+ */
+const makeAttenuatorsNode = (graph, entryNode, policy) => {
+  if (policy) {
+    assertPolicy(policy);
+
+    assert(
+      graph[ATTENUATORS_COMPARTMENT] === undefined,
+      `${q(ATTENUATORS_COMPARTMENT)} is a reserved compartment name`,
+    );
+
+    graph[ATTENUATORS_COMPARTMENT] = {
+      ...entryNode,
+      internalAliases: {},
+      externalAliases: {},
+      packageDescriptor: { name: ATTENUATORS_COMPARTMENT },
+      name: ATTENUATORS_COMPARTMENT,
+    };
+  }
+};
 
 /**
- * @param {ReadFn | ReadPowers | MaybeReadPowers} readPowers
- * @param {string} packageLocation
+ * Transforms a `Graph` into a readonly `FinalGraph`, in preparation for
+ * conversion to a `CompartmentDescriptor`.
+ *
+ * @param {Graph} graph Graph
+ * @param {LogicalPathGraph} logicalPathGraph Logical path graph
+ * @param {FileUrlString} entryPackageLocation Entry package location
+ * @param {CanonicalNameMap} canonicalNameMap Mapping of canonical names to `Node` names (keys in `graph`)
+ * @returns {Readonly<FinalGraph>}
+ */
+const finalizeGraph = (
+  graph,
+  logicalPathGraph,
+  entryPackageLocation,
+  canonicalNameMap,
+) => {
+  const shortestPath = makeShortestPath(logicalPathGraph);
+
+  // neither the entry package nor the attenuators compartment have a path; omit
+  const {
+    [ATTENUATORS_COMPARTMENT]: attenuatorsNode,
+    [entryPackageLocation]: entryNode,
+    ...subgraph
+  } = graph;
+
+  /** @type {FinalGraph} */
+  const finalGraph = create(null);
+
+  /** @type {Readonly<FinalNode>} */
+  finalGraph[entryPackageLocation] = freeze({
+    ...entryNode,
+    label: generateCanonicalName({
+      isEntry: true,
+      path: [],
+    }),
+  });
+
+  canonicalNameMap.set(ENTRY_COMPARTMENT, entryPackageLocation);
+
+  if (attenuatorsNode) {
+    /** @type {Readonly<FinalNode>} */
+    finalGraph[ATTENUATORS_COMPARTMENT] = freeze({
+      ...attenuatorsNode,
+      label: generateCanonicalName({
+        name: ATTENUATORS_COMPARTMENT,
+        path: [],
+      }),
+    });
+  }
+
+  const subgraphEntries = /** @type {[FileUrlString, Node][]} */ (
+    entries(subgraph)
+  );
+
+  for (const [location, node] of subgraphEntries) {
+    const shortestLogicalPath = shortestPath(entryPackageLocation, location);
+
+    // the first element will always be the root package location; this is omitted from the path.
+    shortestLogicalPath.shift();
+
+    const path = shortestLogicalPath.map(location => graph[location].name);
+    const canonicalName = generateCanonicalName({ path });
+
+    /** @type {Readonly<FinalNode>} */
+    const finalNode = freeze({
+      ...node,
+      label: canonicalName,
+    });
+
+    canonicalNameMap.set(canonicalName, location);
+
+    finalGraph[location] = finalNode;
+  }
+
+  for (const node of values(finalGraph)) {
+    Object.freeze(node);
+  }
+
+  return freeze(finalGraph);
+};
+
+/**
+ * Returns an array of "issue" objects if any resources referenced in `policy`
+ * are unknown.
+ *
+ * @param {Set<CanonicalName>} canonicalNames Set of all known canonical names
+ * @param {SomePolicy} policy Policy to validate
+ * @returns {Array<{canonicalName: CanonicalName, message: string, path:
+ * string[], suggestion?: CanonicalName}>} Array of issue objects, or `undefined` if no issues were
+ * found
+ */
+const validatePolicyResources = (canonicalNames, policy) => {
+  /**
+   * Finds a suggestion for `badName` if it is a suffix of any
+   * canonical name in `canonicalNames`.
+   *
+   * @param {string} badName Unknown canonical name
+   * @returns {CanonicalName | undefined}
+   */
+  const findSuggestion = badName => {
+    for (const canonicalName of canonicalNames) {
+      if (canonicalName.endsWith(`>${badName}`)) {
+        return canonicalName;
+      }
+    }
+    return undefined;
+  };
+
+  /** @type {Array<{canonicalName: CanonicalName, message: string, path: string[], suggestion?: CanonicalName}>} */
+  const issues = [];
+  for (const [resourceName, resourcePolicy] of entries(
+    policy.resources ?? {},
+  )) {
+    if (!canonicalNames.has(resourceName)) {
+      const issueMessage = `Resource ${q(resourceName)} was not found`;
+      const suggestion = findSuggestion(resourceName);
+      const issue = {
+        canonicalName: resourceName,
+        message: issueMessage,
+        path: ['resources', resourceName],
+      };
+      if (suggestion) {
+        issue.suggestion = suggestion;
+      }
+      issues.push(issue);
+    }
+    if (typeof resourcePolicy?.packages === 'object') {
+      for (const packageName of keys(resourcePolicy.packages)) {
+        if (!canonicalNames.has(packageName)) {
+          const issueMessage = `Resource ${q(packageName)} from resource ${q(resourceName)} was not found`;
+          const suggestion = findSuggestion(packageName);
+          const issue = {
+            canonicalName: packageName,
+            message: issueMessage,
+            path: ['resources', resourceName, 'packages', packageName],
+          };
+          if (suggestion) {
+            issue.suggestion = suggestion;
+          }
+          issues.push(issue);
+        }
+      }
+    }
+  }
+
+  return issues;
+};
+
+/**
+ * @param {ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>} readPowers
+ * @param {FileUrlString} entryPackageLocation
  * @param {Set<string>} conditionsOption
  * @param {PackageDescriptor} packageDescriptor
- * @param {string} moduleSpecifier
+ * @param {string} entryModuleSpecifier
  * @param {CompartmentMapForNodeModulesOptions} [options]
- * @returns {Promise<CompartmentMapDescriptor>}
- * @deprecated Use {@link mapNodeModules} instead.
+ * @returns {Promise<PackageCompartmentMapDescriptor>}
  */
-export const compartmentMapForNodeModules = async (
+export const compartmentMapForNodeModules_ = async (
   readPowers,
-  packageLocation,
+  entryPackageLocation,
   conditionsOption,
   packageDescriptor,
-  moduleSpecifier,
+  entryModuleSpecifier,
   options = {},
 ) => {
   const {
@@ -997,52 +1319,109 @@ export const compartmentMapForNodeModules = async (
     policy,
     strict = false,
     log = noop,
+    unknownCanonicalNameHook,
+    packageDataHook,
+    packageDependenciesHook,
   } = options;
   const { maybeRead, canonical } = unpackReadPowers(readPowers);
   const languageOptions = makeLanguageOptions(options);
 
   const conditions = new Set(conditionsOption || []);
 
+  /**
+   * This graph will contain nodes for each package location (a
+   * {@link FileUrlString}) and edges representing dependencies between packages.
+   *
+   * The edges are weighted by {@link calculatePackageWeight}.
+   *
+   * @type {LogicalPathGraph}
+   */
+  const logicalPathGraph = new GenericGraph();
+
   // dev is only set for the entry package, and implied by the development
   // condition.
-  // The dev option is deprecated in favor of using conditions, since that
-  // covers more intentional behaviors of the development mode.
 
   const graph = await graphPackages(
     maybeRead,
     canonical,
-    packageLocation,
+    entryPackageLocation,
     conditions,
     packageDescriptor,
     dev || (conditions && conditions.has('development')),
     commonDependencies,
     languageOptions,
     strict,
-    { log },
+    logicalPathGraph,
+    { log, policy, packageDependenciesHook },
   );
 
-  if (policy) {
-    assertPolicy(policy);
+  makeAttenuatorsNode(graph, graph[entryPackageLocation], policy);
 
-    assert(
-      graph[ATTENUATORS_COMPARTMENT] === undefined,
-      `${q(ATTENUATORS_COMPARTMENT)} is a reserved compartment name`,
-    );
+  /**
+   * @type {CanonicalNameMap}
+   */
+  const canonicalNameMap = new Map();
 
-    graph[ATTENUATORS_COMPARTMENT] = {
-      ...graph[packageLocation],
-      externalAliases: {},
-      label: ATTENUATORS_COMPARTMENT,
-      name: ATTENUATORS_COMPARTMENT,
-    };
+  const finalGraph = finalizeGraph(
+    graph,
+    logicalPathGraph,
+    entryPackageLocation,
+    canonicalNameMap,
+  );
+
+  // if policy exists, cross-reference the policy "resources" against the list
+  // of known canonical names and fire the `unknownCanonicalName` hook for each
+  // unknown resource, if found
+  if (policy) {
+    const canonicalNames = new Set(canonicalNameMap.keys());
+    const issues = validatePolicyResources(canonicalNames, policy) ?? [];
+    // Call default handler first if policy exists
+    for (const { message, canonicalName, path, suggestion } of issues) {
+      const hookInput = {
+        canonicalName,
+        message,
+        path,
+        log,
+      };
+      if (suggestion) {
+        hookInput.suggestion = suggestion;
+      }
+      defaultUnknownCanonicalNameHandler(hookInput);
+      // Then call user-provided hook if it exists
+      if (unknownCanonicalNameHook) {
+        unknownCanonicalNameHook(hookInput);
+      }
+    }
+  }
+
+  // Fire packageData hook with all package data before translateGraph
+  if (packageDataHook) {
+    const packageData =
+      /** @type {Map<PackageCompartmentDescriptorName, PackageData>} */ (
+        new Map(
+          values(finalGraph).map(node => [
+            node.label,
+            {
+              name: node.name,
+              packageDescriptor: node.packageDescriptor,
+              location: node.location,
+              canonicalName: node.label,
+            },
+          ]),
+        )
+      );
+    packageDataHook({
+      packageData,
+      log,
+    });
   }
 
   const compartmentMap = translateGraph(
-    packageLocation,
-    moduleSpecifier,
-    graph,
+    entryPackageLocation,
+    entryModuleSpecifier,
+    finalGraph,
     conditions,
-    policy,
+    { policy, log, packageDependenciesHook },
   );
 
   return compartmentMap;
@@ -1054,15 +1433,24 @@ export const compartmentMapForNodeModules = async (
  *
  * Locates the {@link PackageDescriptor} for the module at `moduleLocation`
  *
- * @param {ReadFn | ReadPowers | MaybeReadPowers} readPowers
+ * @param {ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>} readPowers
  * @param {string} moduleLocation
  * @param {MapNodeModulesOptions} [options]
- * @returns {Promise<CompartmentMapDescriptor>}
+ * @returns {Promise<PackageCompartmentMapDescriptor>}
  */
 export const mapNodeModules = async (
   readPowers,
   moduleLocation,
-  { tags = new Set(), conditions = tags, log = noop, ...otherOptions } = {},
+  {
+    tags = new Set(),
+    conditions = tags,
+    log = noop,
+    unknownCanonicalNameHook,
+    packageDataHook,
+    packageDependenciesHook,
+    policy,
+    ...otherOptions
+  } = {},
 ) => {
   const {
     packageLocation,
@@ -1071,16 +1459,31 @@ export const mapNodeModules = async (
     moduleSpecifier,
   } = await search(readPowers, moduleLocation, { log });
 
-  const packageDescriptor = /** @type {PackageDescriptor} */ (
-    parseLocatedJson(packageDescriptorText, packageDescriptorLocation)
-  );
+  const packageDescriptor = /** @type {typeof parseLocatedJson<unknown>} */ (
+    parseLocatedJson
+  )(packageDescriptorText, packageDescriptorLocation);
 
-  return compartmentMapForNodeModules(
+  assertPackageDescriptor(packageDescriptor);
+  assertFileUrlString(packageLocation);
+
+  return compartmentMapForNodeModules_(
     readPowers,
     packageLocation,
     conditions,
     packageDescriptor,
     moduleSpecifier,
-    { log, ...otherOptions },
+    {
+      log,
+      policy,
+      unknownCanonicalNameHook,
+      packageDependenciesHook,
+      packageDataHook,
+      ...otherOptions,
+    },
   );
 };
+
+/**
+ * @deprecated Use {@link mapNodeModules} instead.
+ */
+export const compartmentMapForNodeModules = compartmentMapForNodeModules_;