policy: add dependencies map for redirect and whitelisting

doc/api/errors.md

@@ -1432,6 +1432,13 @@ An attempt was made to load a resource, but the resource did not match the
 integrity defined by the policy manifest. See the documentation for [policy]
 manifests for more information.
 
+<a id="ERR_MANIFEST_DEPENDENCY_MISSING"></a>
+### ERR_MANIFEST_DEPENDENCY_MISSING
+
+An attempt was made to load a resource, but the resource was not listed as a
+dependency from the location that attempted to load it. See the documentation
+for [policy] manifests for more information.
+
 <a id="ERR_MANIFEST_INTEGRITY_MISMATCH"></a>
 ### ERR_MANIFEST_INTEGRITY_MISMATCH
 
@@ -1440,6 +1447,13 @@ entries for a resource which did not match each other. Update the manifest
 entries to match in order to resolve this error. See the documentation for
 [policy] manifests for more information.
 
+<a id="ERR_MANIFEST_INVALID_RESOURCE_FIELD"></a>
+### ERR_MANIFEST_INVALID_RESOURCE_FIELD
+
+A policy manifest resource had an invalid value for one of its fields. Update
+the manifest entry to match in order to resolve this error. See the
+documentation for [policy] manifests for more information.
+
 <a id="ERR_MANIFEST_PARSE_POLICY"></a>
 ### ERR_MANIFEST_PARSE_POLICY
 

doc/api/policy.md

@@ -38,7 +38,7 @@ node --experimental-policy=policy.json app.js
 The policy manifest will be used to enforce constraints on code loaded by
 Node.js.
 
-In order to mitigate tampering with policy files on disk, an integrity for
+To mitigate tampering with policy files on disk, an integrity for
 the policy file itself may be provided via `--policy-integrity`.
 This allows running `node` and asserting the policy file contents
 even if the file is changed on disk.
@@ -105,9 +105,83 @@ When loading resources the entire URL must match including search parameters
 and hash fragment. `./a.js?b` will not be used when attempting to load
 `./a.js` and vice versa.
 
-In order to generate integrity strings, a script such as
+To generate integrity strings, a script such as
 `printf "sha384-$(cat checked.js | openssl dgst -sha384 -binary | base64)"`
 can be used.
 
+Integrity can be specified as the boolean value `true` to accept any
+body for the resource which can be useful for local development. It is not
+recommended in production since it would allow unexpected alteration of
+resources to be considered valid.
+
+### Dependency Redirection
+
+An application may need to ship patched versions of modules or to prevent
+modules from allowing all modules access to all other modules. Redirection
+can be used by intercepting attempts to load the modules wishing to be
+replaced.
+
+```json
+{
+ "builtins": [],
+ "resources": {
+ "./app/checked.js": {
+ "dependencies": {
+ "fs": true,
+ "os": "./app/node_modules/alt-os"
+ }
+ }
+ }
+}
+```
+
+The dependencies are keyed by the requested string specifier and have values
+of either `true` or a string pointing to a module that will be resolved.
+
+The specifier string does not perform any searching and must match exactly
+what is provided to the `require()`. Therefore, multiple specifiers may be
+needed in the policy if `require()` uses multiple different strings to point
+to the same module (such as excluding the extension).
+
+If the value of the redirection is `true` the default searching algorithms will
+be used to find the module.
+
+If the value of the redirection is a string, it will be resolved relative to
+the manifest and then immediately be used without searching.
+
+Any specifier string that is `require()`ed and not listed in the dependencies
+will result in an error according to the policy.
+
+Redirection will not prevent access to APIs through means such as direct access
+to `require.cache` and/or through `module.constructor` which allow access to
+loading modules. Policy redirection only affect specifiers to `require()`.
+Other means such as to prevent undesired access to APIs through variables are
+necessary to lock down that path of loading modules.
+
+A boolean value of `true` for the dependencies map can be specified to allow a
+module to load any specifier without redirection. This can be useful for local
+development and may have some valid usage in production, but should be used
+only with care after auditing a module to ensure its behavior is valid.
+
+#### Example: Patched Dependency
+
+Since a dependency can be redirected, you can provide attenuated or modified
+forms of dependencies as fits your application. For example, you could log
+data about timing of function durations by wrapping the original:
+
+```js
+const original = require('fn');
+module.exports = function fn(...args) {
+ console.time();
+ try {
+ return new.target ?
+ Reflect.construct(original, args) :
+ Reflect.apply(original, this, args);
+ } finally {
+ console.timeEnd();
+ }
+};
+```
+
 
 [relative url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string

lib/internal/errors.js

@@ -1033,9 +1033,15 @@ E('ERR_MANIFEST_ASSERT_INTEGRITY',
  }
  return msg;
  }, Error);
+E('ERR_MANIFEST_DEPENDENCY_MISSING',
+ 'Manifest resource %s does not list %s as a dependency specifier',
+ Error);
 E('ERR_MANIFEST_INTEGRITY_MISMATCH',
  'Manifest resource %s has multiple entries but integrity lists do not match',
  SyntaxError);
+E('ERR_MANIFEST_INVALID_RESOURCE_FIELD',
+ 'Manifest resource %s has invalid property value for %s',
+ TypeError);
 E('ERR_MANIFEST_TDZ', 'Manifest initialization has not yet run', Error);
 E('ERR_MANIFEST_UNKNOWN_ONERROR',
  'Manifest specified unknown error behavior "%s".',

lib/internal/modules/cjs/helpers.js

@@ -1,19 +1,72 @@
 'use strict';
 
 const { Object } = primordials;
+const {
+ ERR_MANIFEST_DEPENDENCY_MISSING,
+ ERR_UNKNOWN_BUILTIN_MODULE
+} = require('internal/errors').codes;
+const { NativeModule } = require('internal/bootstrap/loaders');
+const { getOptionValue } = require('internal/options');
+const experimentalModules = getOptionValue('--experimental-modules');
 
 const { validateString } = require('internal/validators');
 const path = require('path');
-const { pathToFileURL } = require('internal/url');
+const { pathToFileURL, fileURLToPath } = require('internal/url');
 const { URL } = require('url');
 
+const debug = require('internal/util/debuglog').debuglog('module');
+
+function loadNativeModule(filename, request, experimentalModules) {
+ const mod = NativeModule.map.get(filename);
+ if (mod) {
+ debug('load native module %s', request);
+ mod.compileForPublicLoader(experimentalModules);
+ return mod;
+ }
+}
+
 // Invoke with makeRequireFunction(module) where |module| is the Module object
 // to use as the context for the require() function.
-function makeRequireFunction(mod) {
+// Use redirects to set up a mapping from a policy and restrict dependencies
+function makeRequireFunction(mod, redirects) {
  const Module = mod.constructor;
 
- function require(path) {
- return mod.require(path);
+ let require;
+ if (redirects) {
+ const { map, reaction } = redirects;
+ const id = mod.filename || mod.id;
+ require = function require(path) {
+ let missing = true;
+ if (map === true) {
+ missing = false;
+ } else if (map.has(path)) {
+ const redirect = map.get(path);
+ if (redirect === true) {
+ missing = false;
+ } else if (typeof redirect === 'string') {
+ const parsed = new URL(redirect);
+ if (parsed.protocol === 'node:') {
+ const specifier = parsed.pathname;
+ const mod = loadNativeModule(
+ specifier,
+ redirect,
+ experimentalModules);
+ if (mod && mod.canBeRequiredByUsers) return mod.exports;
+ throw new ERR_UNKNOWN_BUILTIN_MODULE(specifier);
+ } else if (parsed.protocol === 'file:') {
+ return mod.require(fileURLToPath(parsed));
+ }
+ }
+ }
+ if (missing) {
+ reaction(new ERR_MANIFEST_DEPENDENCY_MISSING(id, path));
+ }
+ return mod.require(path);
+ };
+ } else {
+ require = function require(path) {
+ return mod.require(path);
+ };
  }
 
  function resolve(request, options) {
@@ -114,6 +167,7 @@ function normalizeReferrerURL(referrer) {
 module.exports = {
  addBuiltinLibsToObject,
  builtinLibs,
+ loadNativeModule,
  makeRequireFunction,
  normalizeReferrerURL,
  stripBOM,

lib/internal/modules/cjs/loader.js

@@ -40,6 +40,7 @@ const {
  makeRequireFunction,
  normalizeReferrerURL,
  stripBOM,
+ loadNativeModule
 } = require('internal/modules/cjs/helpers');
 const { getOptionValue } = require('internal/options');
 const preserveSymlinks = getOptionValue('--preserve-symlinks');
@@ -531,11 +532,8 @@ Module._load = function(request, parent, isMain) {
  return cachedModule.exports;
  }
 
- const mod = NativeModule.map.get(filename);
- if (mod && mod.canBeRequiredByUsers) {
- debug('load native module %s', request);
- return mod.compileForPublicLoader(experimentalModules);
- }
+ const mod = loadNativeModule(filename, request, experimentalModules);
+ if (mod && mod.canBeRequiredByUsers) return mod.exports;
 
  // Don't call updateChildren(), Module constructor already does.
  const module = new Module(filename, parent);
@@ -741,8 +739,11 @@ function wrapSafe(filename, content) {
 // the file.
 // Returns exception, if any.
 Module.prototype._compile = function(content, filename) {
+ let moduleURL;
+ let redirects;
  if (manifest) {
- const moduleURL = pathToFileURL(filename);
+ moduleURL = pathToFileURL(filename);
+ redirects = manifest.getRedirects(moduleURL);
  manifest.assertIntegrity(moduleURL, content);
  }
 
@@ -766,7 +767,7 @@ Module.prototype._compile = function(content, filename) {
  }
  }
  const dirname = path.dirname(filename);
- const require = makeRequireFunction(this);
+ const require = makeRequireFunction(this, redirects);
  var result;
  const exports = this.exports;
  const thisValue = exports;
@@ -855,7 +856,7 @@ function createRequireFromPath(filename) {
  m.filename = proxyPath;
 
  m.paths = Module._nodeModulePaths(m.path);
- return makeRequireFunction(m);
+ return makeRequireFunction(m, null);
 }
 
 Module.createRequireFromPath = deprecate(

lib/internal/modules/esm/translators.js

@@ -9,9 +9,9 @@ const {
  StringPrototype
 } = primordials;
 
-const { NativeModule } = require('internal/bootstrap/loaders');
 const {
- stripBOM
+ stripBOM,
+ loadNativeModule
 } = require('internal/modules/cjs/helpers');
 const CJSModule = require('internal/modules/cjs/loader').Module;
 const internalURLModule = require('internal/url');
@@ -93,11 +93,10 @@ translators.set('builtin', async function builtinStrategy(url) {
  debug(`Translating BuiltinModule ${url}`);
  // Slice 'node:' scheme
  const id = url.slice(5);
- const module = NativeModule.map.get(id);
+ const module = loadNativeModule(id, url, true);
  if (!module) {
  throw new ERR_UNKNOWN_BUILTIN_MODULE(id);
  }
- module.compileForPublicLoader(true);
  return createDynamicModule(
  [], [...module.exportKeys, 'default'], url, (reflect) => {
  debug(`Loading BuiltinModule ${url}`);