Skip to content

Commit

Permalink
policy: canonicalize before resolving specifiers
Browse files Browse the repository at this point in the history
PR-URL: #37863
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Co-authored-by: James M Snell <jasnell@gmail.com>
  • Loading branch information
3 people committed Aug 5, 2021
1 parent dd18795 commit 5ee3aa6
Show file tree
Hide file tree
Showing 12 changed files with 776 additions and 353 deletions.
7 changes: 7 additions & 0 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -1774,6 +1774,13 @@ 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 to resolve this error. See the
documentation for [policy][] manifests for more information.

<a id="ERR_MANIFEST_PARSE_POLICY"></a>
### `ERR_MANIFEST_PARSE_POLICY`

Expand Down
165 changes: 152 additions & 13 deletions doc/api/policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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`:

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
3 changes: 3 additions & 0 deletions lib/internal/errors.js
Original file line number Diff line number Diff line change
Expand Up @@ -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".',
Expand Down
Loading

0 comments on commit 5ee3aa6

Please sign in to comment.