@@ -38,7 +38,7 @@ node --experimental-policy=policy.json app.js
3838The policy manifest will be used to enforce constraints on code loaded by
3939Node.js.
4040
41- In order to mitigate tampering with policy files on disk, an integrity for
41+ To mitigate tampering with policy files on disk, an integrity for
4242the policy file itself may be provided via ` --policy-integrity ` .
4343This allows running ` node ` and asserting the policy file contents
4444even if the file is changed on disk.
@@ -105,9 +105,83 @@ When loading resources the entire URL must match including search parameters
105105and hash fragment. ` ./a.js?b ` will not be used when attempting to load
106106` ./a.js ` and vice versa.
107107
108- In order to generate integrity strings, a script such as
108+ To generate integrity strings, a script such as
109109` printf "sha384-$(cat checked.js | openssl dgst -sha384 -binary | base64)" `
110110can be used.
111111
112+ Integrity can be specified as the boolean value ` true ` to accept any
113+ body for the resource which can be useful for local development. It is not
114+ recommended in production since it would allow unexpected alteration of
115+ resources to be considered valid.
116+
117+ ### Dependency Redirection
118+
119+ An application may need to ship patched versions of modules or to prevent
120+ modules from allowing all modules access to all other modules. Redirection
121+ can be used by intercepting attempts to load the modules wishing to be
122+ replaced.
123+
124+ ``` json
125+ {
126+ "builtins" : [],
127+ "resources" : {
128+ "./app/checked.js" : {
129+ "dependencies" : {
130+ "fs" : true ,
131+ "os" : " ./app/node_modules/alt-os"
132+ }
133+ }
134+ }
135+ }
136+ ```
137+
138+ The dependencies are keyed by the requested string specifier and have values
139+ of either ` true ` or a string pointing to a module that will be resolved.
140+
141+ The specifier string does not perform any searching and must match exactly
142+ what is provided to the ` require() ` . Therefore, multiple specifiers may be
143+ needed in the policy if ` require() ` uses multiple different strings to point
144+ to the same module (such as excluding the extension).
145+
146+ If the value of the redirection is ` true ` the default searching algorithms will
147+ be used to find the module.
148+
149+ If the value of the redirection is a string, it will be resolved relative to
150+ the manifest and then immediately be used without searching.
151+
152+ Any specifier string that is ` require() ` ed and not listed in the dependencies
153+ will result in an error according to the policy.
154+
155+ Redirection will not prevent access to APIs through means such as direct access
156+ to ` require.cache ` and/or through ` module.constructor ` which allow access to
157+ loading modules. Policy redirection only affect specifiers to ` require() ` .
158+ Other means such as to prevent undesired access to APIs through variables are
159+ necessary to lock down that path of loading modules.
160+
161+ A boolean value of ` true ` for the dependencies map can be specified to allow a
162+ module to load any specifier without redirection. This can be useful for local
163+ development and may have some valid usage in production, but should be used
164+ only with care after auditing a module to ensure its behavior is valid.
165+
166+ #### Example: Patched Dependency
167+
168+ Since a dependency can be redirected, you can provide attenuated or modified
169+ forms of dependencies as fits your application. For example, you could log
170+ data about timing of function durations by wrapping the original:
171+
172+ ``` js
173+ const original = require (' fn'
174+ module .exports = function fn (... args ) {
175+ console .time ();
176+ try {
177+ return new .target ?
178+ Reflect .construct (original, args) :
179+ Reflect .apply (original, this , args);
180+ } finally {
181+ console .timeEnd ();
182+ }
183+ };
184+ ```
185+
112186
113187[ relative url string ] : https://url.spec.whatwg.org/#relative-url-with-fragment-string
0 commit comments