1<!DOCTYPE html> 2<html lang="en"> 3<head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width"> 6 <meta name="nodejs.org:node-version" content="v18.20.1"> 7 <title>Permissions | Node.js v18.20.1 Documentation</title> 8 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 9 <link rel="stylesheet" href="assets/style.css"> 10 <link rel="stylesheet" href="assets/hljs.css"> 11 <link rel="canonical" href="https://nodejs.org/api/permissions.html"> 12 <script async defer src="assets/api.js" type="text/javascript"></script> 13 14</head> 15<body class="alt apidoc" id="api-section-permissions"> 16 <div id="content" class="clearfix"> 17 <div id="column2" class="interior"> 18 <div id="intro" class="interior"> 19 <a href="/" title="Go back to the home page"> 20 Node.js 21 </a> 22 </div> 23 <ul> 24<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 25<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 26</ul> 27<hr class="line"> 28<ul> 29<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 30<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 31<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 32<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 33<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 34<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 35<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 36<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 37<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 38<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 39<li><a href="console.html" class="nav-console">Console</a></li> 40<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 41<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 42<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 43<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 44<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 45<li><a href="dns.html" class="nav-dns">DNS</a></li> 46<li><a href="domain.html" class="nav-domain">Domain</a></li> 47<li><a href="errors.html" class="nav-errors">Errors</a></li> 48<li><a href="events.html" class="nav-events">Events</a></li> 49<li><a href="fs.html" class="nav-fs">File system</a></li> 50<li><a href="globals.html" class="nav-globals">Globals</a></li> 51<li><a href="http.html" class="nav-http">HTTP</a></li> 52<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 53<li><a href="https.html" class="nav-https">HTTPS</a></li> 54<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 55<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 56<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 57<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 58<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 59<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 60<li><a href="net.html" class="nav-net">Net</a></li> 61<li><a href="os.html" class="nav-os">OS</a></li> 62<li><a href="path.html" class="nav-path">Path</a></li> 63<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 64<li><a href="permissions.html" class="nav-permissions active">Permissions</a></li> 65<li><a href="process.html" class="nav-process">Process</a></li> 66<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 67<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 68<li><a href="readline.html" class="nav-readline">Readline</a></li> 69<li><a href="repl.html" class="nav-repl">REPL</a></li> 70<li><a href="report.html" class="nav-report">Report</a></li> 71<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 72<li><a href="stream.html" class="nav-stream">Stream</a></li> 73<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 74<li><a href="test.html" class="nav-test">Test runner</a></li> 75<li><a href="timers.html" class="nav-timers">Timers</a></li> 76<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 77<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 78<li><a href="tty.html" class="nav-tty">TTY</a></li> 79<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 80<li><a href="url.html" class="nav-url">URL</a></li> 81<li><a href="util.html" class="nav-util">Utilities</a></li> 82<li><a href="v8.html" class="nav-v8">V8</a></li> 83<li><a href="vm.html" class="nav-vm">VM</a></li> 84<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 85<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 86<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 87<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 88<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 89</ul> 90<hr class="line"> 91<ul> 92<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 93</ul> 94 </div> 95 96 <div id="column1" data-id="permissions" class="interior"> 97 <header class="header"> 98 <div class="header-container"> 99 <h1>Node.js v18.20.1 documentation</h1> 100 <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 101 <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 102 <path fill="none" d="M0 0h24v24H0z" /> 103 <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 104 <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 105 </svg> 106 <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 107 <path d="M0 0h24v24H0z" fill="none" /> 108 <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 109 </svg> 110 </button> 111 </div> 112 <div id="gtoc"> 113 <ul> 114 <li class="pinned-header">Node.js v18.20.1</li> 115 116 <li class="picker-header"> 117 <a href="#"> 118 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 119 Table of contents 120 </a> 121 122 <div class="picker"><div class="toc"><ul> 123<li><a href="#permissions">Permissions</a> 124<ul> 125<li><a href="#module-based-permissions">Module-based permissions</a> 126<ul> 127<li><span class="stability_1"><a href="#policies">Policies</a></span> 128<ul> 129<li><a href="#enabling">Enabling</a></li> 130<li><a href="#features">Features</a> 131<ul> 132<li><a href="#error-behavior">Error behavior</a></li> 133<li><a href="#integrity-checks">Integrity checks</a></li> 134<li><a href="#dependency-redirection">Dependency redirection</a></li> 135<li><a href="#example-patched-dependency">Example: Patched dependency</a></li> 136</ul> 137</li> 138<li><a href="#scopes">Scopes</a> 139<ul> 140<li><a href="#example">Example</a></li> 141<li><a href="#integrity-using-scopes">Integrity using scopes</a></li> 142<li><a href="#dependency-redirection-using-scopes">Dependency redirection using scopes</a></li> 143<li><a href="#example-import-maps-emulation">Example: import maps emulation</a></li> 144</ul> 145</li> 146</ul> 147</li> 148</ul> 149</li> 150</ul> 151</li> 152</ul></div></div> 153 </li> 154 155 156 <li class="picker-header"> 157 <a href="#"> 158 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 159 Index 160 </a> 161 162 <div class="picker"><ul> 163<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 164<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 165 166 <li> 167 <a href="index.html">Index</a> 168 </li> 169 </ul> 170 171<hr class="line"> 172<ul> 173<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 174<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 175<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 176<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 177<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 178<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 179<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 180<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 181<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 182<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 183<li><a href="console.html" class="nav-console">Console</a></li> 184<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 185<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 186<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 187<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 188<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 189<li><a href="dns.html" class="nav-dns">DNS</a></li> 190<li><a href="domain.html" class="nav-domain">Domain</a></li> 191<li><a href="errors.html" class="nav-errors">Errors</a></li> 192<li><a href="events.html" class="nav-events">Events</a></li> 193<li><a href="fs.html" class="nav-fs">File system</a></li> 194<li><a href="globals.html" class="nav-globals">Globals</a></li> 195<li><a href="http.html" class="nav-http">HTTP</a></li> 196<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 197<li><a href="https.html" class="nav-https">HTTPS</a></li> 198<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 199<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 200<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 201<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 202<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 203<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 204<li><a href="net.html" class="nav-net">Net</a></li> 205<li><a href="os.html" class="nav-os">OS</a></li> 206<li><a href="path.html" class="nav-path">Path</a></li> 207<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 208<li><a href="permissions.html" class="nav-permissions active">Permissions</a></li> 209<li><a href="process.html" class="nav-process">Process</a></li> 210<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 211<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 212<li><a href="readline.html" class="nav-readline">Readline</a></li> 213<li><a href="repl.html" class="nav-repl">REPL</a></li> 214<li><a href="report.html" class="nav-report">Report</a></li> 215<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 216<li><a href="stream.html" class="nav-stream">Stream</a></li> 217<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 218<li><a href="test.html" class="nav-test">Test runner</a></li> 219<li><a href="timers.html" class="nav-timers">Timers</a></li> 220<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 221<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 222<li><a href="tty.html" class="nav-tty">TTY</a></li> 223<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 224<li><a href="url.html" class="nav-url">URL</a></li> 225<li><a href="util.html" class="nav-util">Utilities</a></li> 226<li><a href="v8.html" class="nav-v8">V8</a></li> 227<li><a href="vm.html" class="nav-vm">VM</a></li> 228<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 229<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 230<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 231<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 232<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 233</ul> 234<hr class="line"> 235<ul> 236<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 237</ul></div> 238 </li> 239 240 241 <li class="picker-header"> 242 <a href="#"> 243 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 244 Other versions 245 </a> 246 <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/permissions.html">21.x</a></li> 247<li><a href="https://nodejs.org/docs/latest-v20.x/api/permissions.html">20.x <b>LTS</b></a></li> 248<li><a href="https://nodejs.org/docs/latest-v19.x/api/permissions.html">19.x</a></li> 249<li><a href="https://nodejs.org/docs/latest-v18.x/api/permissions.html">18.x <b>LTS</b></a></li> 250<li><a href="https://nodejs.org/docs/latest-v17.x/api/permissions.html">17.x</a></li> 251<li><a href="https://nodejs.org/docs/latest-v16.x/api/permissions.html">16.x</a></li> 252<li><a href="https://nodejs.org/docs/latest-v15.x/api/permissions.html">15.x</a></li> 253<li><a href="https://nodejs.org/docs/latest-v14.x/api/permissions.html">14.x</a></li> 254<li><a href="https://nodejs.org/docs/latest-v13.x/api/permissions.html">13.x</a></li> 255<li><a href="https://nodejs.org/docs/latest-v12.x/api/permissions.html">12.x</a></li> 256<li><a href="https://nodejs.org/docs/latest-v11.x/api/permissions.html">11.x</a></li></ol></div> 257 </li> 258 259 <li class="picker-header"> 260 <a href="#"> 261 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 262 Options 263 </a> 264 265 <div class="picker"> 266 <ul> 267 <li> 268 <a href="all.html">View on single page</a> 269 </li> 270 <li> 271 <a href="permissions.json">View as JSON</a> 272 </li> 273 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/permissions.md">Edit on GitHub</a></li> 274 </ul> 275 </div> 276 </li> 277 </ul> 278 </div> 279 <hr> 280 </header> 281 282 <details id="toc" open><summary>Table of contents</summary><ul> 283<li><a href="#permissions">Permissions</a> 284<ul> 285<li><a href="#module-based-permissions">Module-based permissions</a> 286<ul> 287<li><span class="stability_1"><a href="#policies">Policies</a></span> 288<ul> 289<li><a href="#enabling">Enabling</a></li> 290<li><a href="#features">Features</a> 291<ul> 292<li><a href="#error-behavior">Error behavior</a></li> 293<li><a href="#integrity-checks">Integrity checks</a></li> 294<li><a href="#dependency-redirection">Dependency redirection</a></li> 295<li><a href="#example-patched-dependency">Example: Patched dependency</a></li> 296</ul> 297</li> 298<li><a href="#scopes">Scopes</a> 299<ul> 300<li><a href="#example">Example</a></li> 301<li><a href="#integrity-using-scopes">Integrity using scopes</a></li> 302<li><a href="#dependency-redirection-using-scopes">Dependency redirection using scopes</a></li> 303<li><a href="#example-import-maps-emulation">Example: import maps emulation</a></li> 304</ul> 305</li> 306</ul> 307</li> 308</ul> 309</li> 310</ul> 311</li> 312</ul></details> 313 314 <div id="apicontent"> 315 <h2>Permissions<span><a class="mark" href="#permissions" id="permissions">#</a></span><a aria-hidden="true" class="legacy" id="permissions_permissions"></a></h2> 316<p>Permissions can be used to control what system resources the 317Node.js process has access to or what actions the process can take 318with those resources. Permissions can also control what modules can 319be accessed by other modules.</p> 320<ul> 321<li><a href="#module-based-permissions">Module-based permissions</a> control which files 322or URLs are available to other modules during application execution. 323This can be used to control what modules can be accessed by third-party 324dependencies, for example.</li> 325</ul> 326<p>If you find a potential security vulnerability, please refer to our 327<a href="https://github.com/nodejs/node/blob/main/SECURITY.md">Security Policy</a>.</p> 328<section><h3>Module-based permissions<span><a class="mark" href="#module-based-permissions" id="module-based-permissions">#</a></span><a aria-hidden="true" class="legacy" id="permissions_module_based_permissions"></a></h3> 329<h4>Policies<span><a class="mark" href="#policies" id="policies">#</a></span><a aria-hidden="true" class="legacy" id="permissions_policies"></a></h4> 330 331 332<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 333 334<p>Node.js contains experimental support for creating policies on loading code.</p> 335<p>Policies are a security feature intended to allow guarantees 336about what code Node.js is able to load. The use of policies assumes 337safe practices for the policy files such as ensuring that policy 338files cannot be overwritten by the Node.js application by using 339file permissions.</p> 340<p>A best practice would be to ensure that the policy manifest is read-only for 341the running Node.js application and that the file cannot be changed 342by the running Node.js application in any way. A typical setup would be to 343create the policy file as a different user id than the one running Node.js 344and granting read permissions to the user id running Node.js.</p> 345<h5>Enabling<span><a class="mark" href="#enabling" id="enabling">#</a></span><a aria-hidden="true" class="legacy" id="permissions_enabling"></a></h5> 346 347<p>The <code>--experimental-policy</code> flag can be used to enable features for policies 348when loading modules.</p> 349<p>Once this has been set, all modules must conform to a policy manifest file 350passed to the flag:</p> 351<pre><code class="language-bash">node --experimental-policy=policy.json app.js</code> <button class="copy-button">copy</button></pre> 352<p>The policy manifest will be used to enforce constraints on code loaded by 353Node.js.</p> 354<p>To mitigate tampering with policy files on disk, an integrity for 355the policy file itself may be provided via <code>--policy-integrity</code>. 356This allows running <code>node</code> and asserting the policy file contents 357even if the file is changed on disk.</p> 358<pre><code class="language-bash">node --experimental-policy=policy.json --policy-integrity=<span class="hljs-string">"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0"</span> app.js</code> <button class="copy-button">copy</button></pre> 359<h5>Features<span><a class="mark" href="#features" id="features">#</a></span><a aria-hidden="true" class="legacy" id="permissions_features"></a></h5> 360<h6>Error behavior<span><a class="mark" href="#error-behavior" id="error-behavior">#</a></span><a aria-hidden="true" class="legacy" id="permissions_error_behavior"></a></h6> 361<p>When a policy check fails, Node.js by default will throw an error. 362It is possible to change the error behavior to one of a few possibilities 363by defining an "onerror" field in a policy manifest. The following values are 364available to change the behavior:</p> 365<ul> 366<li><code>"exit"</code>: will exit the process immediately. 367No cleanup code will be allowed to run.</li> 368<li><code>"log"</code>: will log the error at the site of the failure.</li> 369<li><code>"throw"</code>: will throw a JS error at the site of the failure. This is the 370default.</li> 371</ul> 372<pre><code class="language-json"><span class="hljs-punctuation">{</span> 373 <span class="hljs-attr">"onerror"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"log"</span><span class="hljs-punctuation">,</span> 374 <span class="hljs-attr">"resources"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 375 <span class="hljs-attr">"./app/checked.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 376 <span class="hljs-attr">"integrity"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0"</span> 377 <span class="hljs-punctuation">}</span> 378 <span class="hljs-punctuation">}</span> 379<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 380<h6>Integrity checks<span><a class="mark" href="#integrity-checks" id="integrity-checks">#</a></span><a aria-hidden="true" class="legacy" id="permissions_integrity_checks"></a></h6> 381<p>Policy files must use integrity checks with Subresource Integrity strings 382compatible with the browser 383<a href="https://www.w3.org/TR/SRI/#the-integrity-attribute">integrity attribute</a> 384associated with absolute URLs.</p> 385<p>When using <code>require()</code> or <code>import</code> all resources involved in loading are checked 386for integrity if a policy manifest has been specified. If a resource does not 387match the integrity listed in the manifest, an error will be thrown.</p> 388<p>An example policy file that would allow loading a file <code>checked.js</code>:</p> 389<pre><code class="language-json"><span class="hljs-punctuation">{</span> 390 <span class="hljs-attr">"resources"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 391 <span class="hljs-attr">"./app/checked.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 392 <span class="hljs-attr">"integrity"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0"</span> 393 <span class="hljs-punctuation">}</span> 394 <span class="hljs-punctuation">}</span> 395<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 396<p>Each resource listed in the policy manifest can be of one the following 397formats to determine its location:</p> 398<ol> 399<li>A <a href="https://url.spec.whatwg.org/#relative-url-with-fragment-string">relative-URL string</a> to a resource from the manifest such as <code>./resource.js</code>, <code>../resource.js</code>, or <code>/resource.js</code>.</li> 400<li>A complete URL string to a resource such as <code>file:///resource.js</code>.</li> 401</ol> 402<p>When loading resources the entire URL must match including search parameters 403and hash fragment. <code>./a.js?b</code> will not be used when attempting to load 404<code>./a.js</code> and vice versa.</p> 405<p>To generate integrity strings, a script such as 406<code>node -e 'process.stdout.write("sha256-");process.stdin.pipe(crypto.createHash("sha256").setEncoding("base64")).pipe(process.stdout)' < FILE</code> 407can be used.</p> 408<p>Integrity can be specified as the boolean value <code>true</code> to accept any 409body for the resource which can be useful for local development. It is not 410recommended in production since it would allow unexpected alteration of 411resources to be considered valid.</p> 412<h6>Dependency redirection<span><a class="mark" href="#dependency-redirection" id="dependency-redirection">#</a></span><a aria-hidden="true" class="legacy" id="permissions_dependency_redirection"></a></h6> 413<p>An application may need to ship patched versions of modules or to prevent 414modules from allowing all modules access to all other modules. Redirection 415can be used by intercepting attempts to load the modules wishing to be 416replaced.</p> 417<pre><code class="language-json"><span class="hljs-punctuation">{</span> 418 <span class="hljs-attr">"resources"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 419 <span class="hljs-attr">"./app/checked.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 420 <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 421 <span class="hljs-attr">"fs"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span> 422 <span class="hljs-attr">"os"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./app/node_modules/alt-os"</span><span class="hljs-punctuation">,</span> 423 <span class="hljs-attr">"http"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"import"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> <span class="hljs-punctuation">}</span> 424 <span class="hljs-punctuation">}</span> 425 <span class="hljs-punctuation">}</span> 426 <span class="hljs-punctuation">}</span> 427<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 428<p>The dependencies are keyed by the requested specifier string and have values 429of either <code>true</code>, <code>null</code>, a string pointing to a module to be resolved, 430or a conditions object.</p> 431<p>The specifier string does not perform any searching and must match exactly what 432is provided to the <code>require()</code> or <code>import</code> except for a canonicalization step. 433Therefore, multiple specifiers may be needed in the policy if it uses multiple 434different strings to point to the same module (such as excluding the extension).</p> 435<p>Specifier strings are canonicalized but not resolved prior to be used for 436matching in order to have some compatibility with import maps, for example if a 437resource <code>file:///C:/app/server.js</code> was given the following redirection from a 438policy located at <code>file:///C:/app/policy.json</code>:</p> 439<pre><code class="language-json"><span class="hljs-punctuation">{</span> 440 <span class="hljs-attr">"resources"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 441 <span class="hljs-attr">"file:///C:/app/utils.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 442 <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 443 <span class="hljs-attr">"./utils.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./utils-v2.js"</span> 444 <span class="hljs-punctuation">}</span> 445 <span class="hljs-punctuation">}</span> 446 <span class="hljs-punctuation">}</span> 447<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 448<p>Any specifier used to load <code>file:///C:/app/utils.js</code> would then be intercepted 449and redirected to <code>file:///C:/app/utils-v2.js</code> instead regardless of using an 450absolute or relative specifier. However, if a specifier that is not an absolute 451or relative URL string is used, it would not be intercepted. So, if an import 452such as <code>import('#utils')</code> was used, it would not be intercepted.</p> 453<p>If the value of the redirection is <code>true</code>, a "dependencies" field at the top of 454the policy file will be used. If that field at the top of the policy file is 455<code>true</code> the default node searching algorithms are used to find the module.</p> 456<p>If the value of the redirection is a string, it is resolved relative to 457the manifest and then immediately used without searching.</p> 458<p>Any specifier string for which resolution is attempted and that is not listed in 459the dependencies results in an error according to the policy.</p> 460<p>Redirection does not prevent access to APIs through means such as direct access 461to <code>require.cache</code> or through <code>module.constructor</code> which allow access to 462loading modules. Policy redirection only affects specifiers to <code>require()</code> and 463<code>import</code>. Other means, such as to prevent undesired access to APIs through 464variables, are necessary to lock down that path of loading modules.</p> 465<p>A boolean value of <code>true</code> for the dependencies map can be specified to allow a 466module to load any specifier without redirection. This can be useful for local 467development and may have some valid usage in production, but should be used 468only with care after auditing a module to ensure its behavior is valid.</p> 469<p>Similar to <code>"exports"</code> in <code>package.json</code>, dependencies can also be specified to 470be objects containing conditions which branch how dependencies are loaded. In 471the preceding example, <code>"http"</code> is allowed when the <code>"import"</code> condition is 472part of loading it.</p> 473<p>A value of <code>null</code> for the resolved value causes the resolution to fail. This 474can be used to ensure some kinds of dynamic access are explicitly prevented.</p> 475<p>Unknown values for the resolved module location cause failures but are 476not guaranteed to be forward compatible.</p> 477<h6>Example: Patched dependency<span><a class="mark" href="#example-patched-dependency" id="example-patched-dependency">#</a></span><a aria-hidden="true" class="legacy" id="permissions_example_patched_dependency"></a></h6> 478<p>Redirected dependencies can provide attenuated or modified functionality as fits 479the application. For example, log data about timing of function durations by 480wrapping the original:</p> 481<pre><code class="language-js"><span class="hljs-keyword">const</span> original = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fn'</span>); 482<span class="hljs-variable language_">module</span>.<span class="hljs-property">exports</span> = <span class="hljs-keyword">function</span> <span class="hljs-title function_">fn</span>(<span class="hljs-params">...args</span>) { 483 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">time</span>(); 484 <span class="hljs-keyword">try</span> { 485 <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span>.<span class="hljs-property">target</span> ? 486 <span class="hljs-title class_">Reflect</span>.<span class="hljs-title function_">construct</span>(original, args) : 487 <span class="hljs-title class_">Reflect</span>.<span class="hljs-title function_">apply</span>(original, <span class="hljs-variable language_">this</span>, args); 488 } <span class="hljs-keyword">finally</span> { 489 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">timeEnd</span>(); 490 } 491};</code> <button class="copy-button">copy</button></pre> 492<h5>Scopes<span><a class="mark" href="#scopes" id="scopes">#</a></span><a aria-hidden="true" class="legacy" id="permissions_scopes"></a></h5> 493<p>Use the <code>"scopes"</code> field of a manifest to set configuration for many resources 494at once. The <code>"scopes"</code> field works by matching resources by their segments. 495If a scope or resource includes <code>"cascade": true</code>, unknown specifiers will 496be searched for in their containing scope. The containing scope for cascading 497is found by recursively reducing the resource URL by removing segments for 498<a href="https://url.spec.whatwg.org/#special-scheme">special schemes</a>, keeping trailing <code>"/"</code> suffixes, and removing the query and 499hash fragment. This leads to the eventual reduction of the URL to its origin. 500If the URL is non-special the scope will be located by the URL's origin. If no 501scope is found for the origin or in the case of opaque origins, a protocol 502string can be used as a scope. If no scope is found for the URL's protocol, a 503final empty string <code>""</code> scope will be used.</p> 504<p>Note, <code>blob:</code> URLs adopt their origin from the path they contain, and so a scope 505of <code>"blob:https://nodejs.org"</code> will have no effect since no URL can have an 506origin of <code>blob:https://nodejs.org</code>; URLs starting with 507<code>blob:https://nodejs.org/</code> will use <code>https://nodejs.org</code> for its origin and 508thus <code>https:</code> for its protocol scope. For opaque origin <code>blob:</code> URLs they will 509have <code>blob:</code> for their protocol scope since they do not adopt origins.</p> 510<h6>Example<span><a class="mark" href="#example" id="example">#</a></span><a aria-hidden="true" class="legacy" id="permissions_example"></a></h6> 511<pre><code class="language-json"><span class="hljs-punctuation">{</span> 512 <span class="hljs-attr">"scopes"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 513 <span class="hljs-attr">"file:///C:/app/"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span><span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 514 <span class="hljs-attr">"file:"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span><span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 515 <span class="hljs-attr">""</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span><span class="hljs-punctuation">}</span> 516 <span class="hljs-punctuation">}</span> 517<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 518<p>Given a file located at <code>file:///C:/app/bin/main.js</code>, the following scopes would 519be checked in order:</p> 520<ol> 521<li><code>"file:///C:/app/bin/"</code></li> 522</ol> 523<p>This determines the policy for all file based resources within 524<code>"file:///C:/app/bin/"</code>. This is not in the <code>"scopes"</code> field of the policy and 525would be skipped. Adding this scope to the policy would cause it to be used 526prior to the <code>"file:///C:/app/"</code> scope.</p> 527<ol start="2"> 528<li><code>"file:///C:/app/"</code></li> 529</ol> 530<p>This determines the policy for all file based resources within 531<code>"file:///C:/app/"</code>. This is in the <code>"scopes"</code> field of the policy and it would 532determine the policy for the resource at <code>file:///C:/app/bin/main.js</code>. If the 533scope has <code>"cascade": true</code>, any unsatisfied queries about the resource would 534delegate to the next relevant scope for <code>file:///C:/app/bin/main.js</code>, <code>"file:"</code>.</p> 535<ol start="3"> 536<li><code>"file:///C:/"</code></li> 537</ol> 538<p>This determines the policy for all file based resources within <code>"file:///C:/"</code>. 539This is not in the <code>"scopes"</code> field of the policy and would be skipped. It would 540not be used for <code>file:///C:/app/bin/main.js</code> unless <code>"file:///"</code> is set to 541cascade or is not in the <code>"scopes"</code> of the policy.</p> 542<ol start="4"> 543<li><code>"file:///"</code></li> 544</ol> 545<p>This determines the policy for all file based resources on the <code>localhost</code>. This 546is not in the <code>"scopes"</code> field of the policy and would be skipped. It would not 547be used for <code>file:///C:/app/bin/main.js</code> unless <code>"file:///"</code> is set to cascade 548or is not in the <code>"scopes"</code> of the policy.</p> 549<ol start="5"> 550<li><code>"file:"</code></li> 551</ol> 552<p>This determines the policy for all file based resources. It would not be used 553for <code>file:///C:/app/bin/main.js</code> unless <code>"file:///"</code> is set to cascade or is not 554in the <code>"scopes"</code> of the policy.</p> 555<ol start="6"> 556<li><code>""</code></li> 557</ol> 558<p>This determines the policy for all resources. It would not be used for 559<code>file:///C:/app/bin/main.js</code> unless <code>"file:"</code> is set to cascade.</p> 560<h6>Integrity using scopes<span><a class="mark" href="#integrity-using-scopes" id="integrity-using-scopes">#</a></span><a aria-hidden="true" class="legacy" id="permissions_integrity_using_scopes"></a></h6> 561<p>Setting an integrity to <code>true</code> on a scope will set the integrity for any 562resource not found in the manifest to <code>true</code>.</p> 563<p>Setting an integrity to <code>null</code> on a scope will set the integrity for any 564resource not found in the manifest to fail matching.</p> 565<p>Not including an integrity is the same as setting the integrity to <code>null</code>.</p> 566<p><code>"cascade"</code> for integrity checks will be ignored if <code>"integrity"</code> is explicitly 567set.</p> 568<p>The following example allows loading any file:</p> 569<pre><code class="language-json"><span class="hljs-punctuation">{</span> 570 <span class="hljs-attr">"scopes"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 571 <span class="hljs-attr">"file:"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 572 <span class="hljs-attr">"integrity"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> 573 <span class="hljs-punctuation">}</span> 574 <span class="hljs-punctuation">}</span> 575<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 576<h6>Dependency redirection using scopes<span><a class="mark" href="#dependency-redirection-using-scopes" id="dependency-redirection-using-scopes">#</a></span><a aria-hidden="true" class="legacy" id="permissions_dependency_redirection_using_scopes"></a></h6> 577<p>The following example, would allow access to <code>fs</code> for all resources within 578<code>./app/</code>:</p> 579<pre><code class="language-json"><span class="hljs-punctuation">{</span> 580 <span class="hljs-attr">"resources"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 581 <span class="hljs-attr">"./app/checked.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 582 <span class="hljs-attr">"cascade"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span> 583 <span class="hljs-attr">"integrity"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> 584 <span class="hljs-punctuation">}</span> 585 <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 586 <span class="hljs-attr">"scopes"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 587 <span class="hljs-attr">"./app/"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 588 <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 589 <span class="hljs-attr">"fs"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> 590 <span class="hljs-punctuation">}</span> 591 <span class="hljs-punctuation">}</span> 592 <span class="hljs-punctuation">}</span> 593<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 594<p>The following example, would allow access to <code>fs</code> for all <code>data:</code> resources:</p> 595<pre><code class="language-json"><span class="hljs-punctuation">{</span> 596 <span class="hljs-attr">"resources"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 597 <span class="hljs-attr">"data:text/javascript,import('node:fs');"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 598 <span class="hljs-attr">"cascade"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span> 599 <span class="hljs-attr">"integrity"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> 600 <span class="hljs-punctuation">}</span> 601 <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 602 <span class="hljs-attr">"scopes"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 603 <span class="hljs-attr">"data:"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 604 <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 605 <span class="hljs-attr">"fs"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> 606 <span class="hljs-punctuation">}</span> 607 <span class="hljs-punctuation">}</span> 608 <span class="hljs-punctuation">}</span> 609<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 610<h6>Example: import maps emulation<span><a class="mark" href="#example-import-maps-emulation" id="example-import-maps-emulation">#</a></span><a aria-hidden="true" class="legacy" id="permissions_example_import_maps_emulation"></a></h6> 611<p>Given an import map:</p> 612<pre><code class="language-json"><span class="hljs-punctuation">{</span> 613 <span class="hljs-attr">"imports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 614 <span class="hljs-attr">"react"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./app/node_modules/react/index.js"</span> 615 <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 616 <span class="hljs-attr">"scopes"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 617 <span class="hljs-attr">"./ssr/"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 618 <span class="hljs-attr">"react"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./app/node_modules/server-side-react/index.js"</span> 619 <span class="hljs-punctuation">}</span> 620 <span class="hljs-punctuation">}</span> 621<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 622<pre><code class="language-json"><span class="hljs-punctuation">{</span> 623 <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span> 624 <span class="hljs-attr">"scopes"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 625 <span class="hljs-attr">""</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 626 <span class="hljs-attr">"cascade"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span> 627 <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 628 <span class="hljs-attr">"react"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./app/node_modules/react/index.js"</span> 629 <span class="hljs-punctuation">}</span> 630 <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 631 <span class="hljs-attr">"./ssr/"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 632 <span class="hljs-attr">"cascade"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span> 633 <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 634 <span class="hljs-attr">"react"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./app/node_modules/server-side-react/index.js"</span> 635 <span class="hljs-punctuation">}</span> 636 <span class="hljs-punctuation">}</span> 637 <span class="hljs-punctuation">}</span> 638<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 639<p><a href="https://url.spec.whatwg.org/#relative-url-with-fragment-string">Import maps</a> assume you can get any resource by default. This means 640<code>"dependencies"</code> at the top level of the policy should be set to <code>true</code>. 641Policies require this to be opt-in since it enables all resources of the 642application cross linkage which doesn't make sense for many scenarios. They also 643assume any given scope has access to any scope above its allowed dependencies; 644all scopes emulating import maps must set <code>"cascade": true</code>.</p> 645<p>Import maps only have a single top level scope for their "imports". So for 646emulating <code>"imports"</code> use the <code>""</code> scope. For emulating <code>"scopes"</code> use the 647<code>"scopes"</code> in a similar manner to how <code>"scopes"</code> works in import maps.</p> 648<p>Caveats: Policies do not use string matching for various finding of scope. They 649do URL traversals. This means things like <code>blob:</code> and <code>data:</code> URLs might not be 650entirely interoperable between the two systems. For example import maps can 651partially match a <code>data:</code> or <code>blob:</code> URL by partitioning the URL on a <code>/</code> 652character, policies intentionally cannot. For <code>blob:</code> URLs import map scopes do 653not adopt the origin of the <code>blob:</code> URL.</p> 654<p>Additionally, import maps only work on <code>import</code> so it may be desirable to add a 655<code>"import"</code> condition to all dependency mappings.</p></section> 656 <!-- API END --> 657 </div> 658 </div> 659 </div> 660</body> 661</html> 662