policy: canonicalize before resolving specifiers

PR-URL: nodejs#37863
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

doc/api/errors.md

@@ -1774,6 +1774,14 @@ 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_INVALID_SPECIFIER"></a>
+### `ERR_MANIFEST_INVALID_SPECIFIER`
+
+A policy manifest resource had an invalid value for one of its dependency
+mappings. 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

@@ -57,7 +57,7 @@ by defining an "onerror" field in a policy manifest. The following values are
 available to change the behavior:
 
 * `"exit"`: will exit the process immediately.
-    No cleanup code will be allowed to run.
+  No cleanup code will be allowed to run.
 * `"log"`: will log the error at the site of the failure.
 * `"throw"`: will throw a JS error at the site of the failure. This is the
   default.
@@ -80,9 +80,9 @@ compatible with the browser
 [integrity attribute](https://www.w3.org/TR/SRI/#the-integrity-attribute)
 associated with absolute URLs.
 
-When using `require()` all resources involved in loading are checked for
-integrity if a policy manifest has been specified. If a resource does not match
-the integrity listed in the manifest, an error will be thrown.
+When using `require()` or `import` all resources involved in loading are checked
+for integrity if a policy manifest has been specified. If a resource does not
+match the integrity listed in the manifest, an error will be thrown.
 
 An example policy file that would allow loading a file `checked.js`:
 
@@ -107,7 +107,7 @@ and hash fragment. `./a.js?b` will not be used when attempting to load
 `./a.js` and vice versa.
 
 To generate integrity strings, a script such as
-`printf "sha384-$(cat checked.js | openssl dgst -sha384 -binary | base64)"`
+`node -e 'process.stdout.write("sha256-");process.stdin.pipe(crypto.createHash("sha256").setEncoding("base64")).pipe(process.stdout)' < FILE`
 can be used.
 
 Integrity can be specified as the boolean value `true` to accept any
@@ -140,13 +140,37 @@ The dependencies are keyed by the requested specifier string and have values
 of either `true`, `null`, a string pointing to a module to be resolved,
 or a conditions object.
 
-The specifier string does not perform any searching and must match exactly
-what is provided to the `require()` or `import`. Therefore, multiple specifiers
-may be needed in the policy if it uses multiple different strings to point
-to the same module (such as excluding the extension).
+The specifier string does not perform any searching and must match exactly what
+is provided to the `require()` or `import` except for a canonicalization step.
+Therefore, multiple specifiers may be needed in the policy if it 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 are
-used to find the module.
+Specifier strings are canonicalized but not resolved prior to be used for
+matching in order to have some compatibility with import maps, for example if a
+resource `file:///C:/app/server.js` was given the following redirection from a
+policy located at `file:///C:/app/policy.json`:
+
+```json
+{
+  "resources": {
+    "file:///C:/app/utils.js": {
+      "dependencies": {
+        "./utils.js": "./utils-v2.js"
+      }
+    }
+  }
+}
+```
+
+Any specifier used to load `file:///C:/app/utils.js` would then be intercepted
+and redirected to `file:///C:/app/utils-v2.js` instead regardless of using an
+absolute or relative specifier. However, if a specifier that is not an absolute
+or relative URL string is used, it would not be intercepted. So, if an import
+such as `import('#utils')` was used, it would not be intercepted.
+
+If the value of the redirection is `true`, a "dependencies" field at the top of
+the policy file will be used. If that field at the top of the policy file is
+`true` the default node searching algorithms are used to find the module.
 
 If the value of the redirection is a string, it is resolved relative to
 the manifest and then immediately used without searching.
@@ -207,7 +231,8 @@ is found by recursively reducing the resource URL by removing segments for
 hash fragment. This leads to the eventual reduction of the URL to its origin.
 If the URL is non-special the scope will be located by the URL's origin. If no
 scope is found for the origin or in the case of opaque origins, a protocol
-string can be used as a scope.
+string can be used as a scope. If no scope is found for the URL's protocol, a
+final empty string `""` scope will be used.
 
 Note, `blob:` URLs adopt their origin from the path they contain, and so a scope
 of `"blob:https://nodejs.org"` will have no effect since no URL can have an
@@ -216,6 +241,61 @@ origin of `blob:https://nodejs.org`; URLs starting with
 thus `https:` for its protocol scope. For opaque origin `blob:` URLs they will
 have `blob:` for their protocol scope since they do not adopt origins.
 
+#### Example
+
+```json
+{
+  "scopes": {
+    "file:///C:/app/": {},
+    "file:": {},
+    "": {}
+  }
+}
+```
+
+Given a file located at `file:///C:/app/bin/main.js`, the following scopes would
+be checked in order:
+
+1. `"file:///C:/app/bin/"`
+
+This determines the policy for all file based resources within
+`"file:///C:/app/bin/"`. This is not in the `"scopes"` field of the policy and
+would be skipped. Adding this scope to the policy would cause it to be used
+prior to the `"file:///C:/app/"` scope.
+
+2. `"file:///C:/app/"`
+
+This determines the policy for all file based resources within
+`"file:///C:/app/"`. This is in the `"scopes"` field of the policy and it would
+determine the policy for the resource at `file:///C:/app/bin/main.js`. If the
+scope has `"cascade": true`, any unsatisfied queries about the resource would
+delegate to the next relevant scope for `file:///C:/app/bin/main.js`, `"file:"`.
+
+3. `"file:///C:/"`
+
+This determines the policy for all file based resources within `"file:///C:/"`.
+This is not in the `"scopes"` field of the policy and would be skipped. It would
+not be used for `file:///C:/app/bin/main.js` unless `"file:///"` is set to
+cascade or is not in the `"scopes"` of the policy.
+
+4. `"file:///"`
+
+This determines the policy for all file based resources on the `localhost`. This
+is not in the `"scopes"` field of the policy and would be skipped. It would not
+be used for `file:///C:/app/bin/main.js` unless `"file:///"` is set to cascade
+or is not in the `"scopes"` of the policy.
+
+5. `"file:"`
+
+This determines the policy for all file based resources. It would not be used
+for `file:///C:/app/bin/main.js` unless `"file:///"` is set to cascade or is not
+in the `"scopes"` of the policy.
+
+6. `""`
+
+This determines the policy for all resources. It would not be used for
+`file:///C:/app/bin/main.js` unless `"file:"` is set to cascade.
+
 #### Integrity using scopes
 
 Setting an integrity to `true` on a scope will set the integrity for any
@@ -284,5 +364,64 @@ The following example, would allow access to `fs` for all `data:` resources:
 }
 ```
 
-[relative-URL string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
+#### Example: [import maps][] emulation
+
+Given an import map:
+
+```json
+{
+  "imports": {
+    "react": "./app/node_modules/react/index.js"
+  },
+  "scopes": {
+    "./ssr/": {
+      "react": "./app/node_modules/server-side-react/index.js"
+    }
+  }
+}
+```
+
+```json
+{
+  "dependencies": true,
+  "scopes": {
+    "": {
+      "cascade": true,
+      "dependencies": {
+        "react": "./app/node_modules/react/index.js"
+      }
+    },
+    "./ssr/": {
+      "cascade": true,
+      "dependencies": {
+        "react": "./app/node_modules/server-side-react/index.js"
+      }
+    }
+  }
+}
+```
+
+Import maps assume you can get any resource by default. This means
+`"dependencies"` at the top level of the policy should be set to `true`.
+Policies require this to be opt-in since it enables all resources of the
+application cross linkage which doesn't make sense for many scenarios. They also
+assume any given scope has access to any scope above its allowed dependencies;
+all scopes emulating import maps must set `"cascade": true`.
+
+Import maps only have a single top level scope for their "imports". So for
+emulating `"imports"` use the `""` scope. For emulating `"scopes"` use the
+`"scopes"` in a similar manner to how `"scopes"` works in import maps.
+
+Caveats: Policies do not use string matching for various finding of scope. They
+do URL traversals. This means things like `blob:` and `data:` URLs might not be
+entirely interoperable between the two systems. For example import maps can
+partially match a `data:` or `blob:` URL by partitioning the URL on a `/`
+character, policies intentionally cannot. For `blob:` URLs import map scopes do
+not adopt the origin of the `blob:` URL.
+
+Additionally, import maps only work on `import` so it may be desirable to add a
+`"import"` condition to all dependency mappings.
+
+[import maps]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
+[relative-url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
 [special schemes]: https://url.spec.whatwg.org/#special-scheme

lib/internal/errors.js

@@ -1349,6 +1349,9 @@ E('ERR_MANIFEST_INTEGRITY_MISMATCH',
 E('ERR_MANIFEST_INVALID_RESOURCE_FIELD',
   'Manifest resource %s has invalid property value for %s',
   TypeError);
+E('ERR_MANIFEST_INVALID_SPECIFIER',
+  'Manifest resource %s has invalid dependency mapping %s',
+  TypeError);
 E('ERR_MANIFEST_TDZ', 'Manifest initialization has not yet run', Error);
 E('ERR_MANIFEST_UNKNOWN_ONERROR',
   'Manifest specified unknown error behavior "%s".',