diff options
author | Bradley Farias <bradley.meck@gmail.com> | 2020-07-17 20:39:02 +0300 |
---|---|---|
committer | Bradley Farias <bradley.meck@gmail.com> | 2020-08-13 21:17:40 +0300 |
commit | e155d9601429057a34adbcdcb790a1c12bd2a163 (patch) | |
tree | 330623d1c4116c229e3b47c05c627522a4c1f27e /doc/api/policy.md | |
parent | f8976a76bbb49d678056d6d2ddd57064cf9e63c2 (diff) |
policy: support conditions for redirects
PR-URL: https://github.com/nodejs/node/pull/34414
Reviewed-By: Jan Krems <jan.krems@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Diffstat (limited to 'doc/api/policy.md')
-rw-r--r-- | doc/api/policy.md | 34 |
1 files changed, 23 insertions, 11 deletions
diff --git a/doc/api/policy.md b/doc/api/policy.md index 05918500fca..e5387f49c03 100644 --- a/doc/api/policy.md +++ b/doc/api/policy.md @@ -124,24 +124,25 @@ replaced. ```json { - "builtins": [], "resources": { "./app/checked.js": { "dependencies": { "fs": true, - "os": "./app/node_modules/alt-os" + "os": "./app/node_modules/alt-os", + "http": { "import": true } } } } } ``` -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 dependencies are keyed by the requested specifier string and have values +of either `true`, `null`, a string pointing to a module that will be resolved, +or a conditions object. 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 +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). If the value of the redirection is `true` the default searching algorithms will @@ -150,20 +151,31 @@ 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. +Any specifier string that is attempted to resolved 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. +loading modules. Policy redirection only affect specifiers to `require()` and +`import`. 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. +Similar to `"exports"` in `package.json` dependencies can also be specified to +be objects containing conditions which branch how dependencies are loaded. In +the above example `"http"` will be allowed when the `"import"` condition is +part of loading it. + +A value of `null` for the resolved value will cause the resolution to fail. +This can be used to ensure some kinds dynamic access are explicitly prevented. + +Unknown values for the resolved module location will cause failure, but are +not guaranteed to be forwards compatible. + #### Example: Patched dependency Redirected dependencies can provide attenuated or modified functionality as fits |