lts/doc/api/policy.json
{
"type": "module",
"source": "doc/api/policy.md",
"introduced_in": "v11.8.0",
"stability": 1,
"stabilityText": "Experimental",
"miscs": [
{
"textRaw": "Policies",
"name": "policy",
"introduced_in": "v11.8.0",
"type": "misc",
"stability": 1,
"stabilityText": "Experimental",
"desc": "<p>Node.js contains experimental support for creating policies on loading code.</p>\n<p>Policies are a security feature intended to allow guarantees\nabout what code Node.js is able to load. The use of policies assumes\nsafe practices for the policy files such as ensuring that policy\nfiles cannot be overwritten by the Node.js application by using\nfile permissions.</p>\n<p>A best practice would be to ensure that the policy manifest is read only for\nthe running Node.js application, and that the file cannot be changed\nby the running Node.js application in any way. A typical setup would be to\ncreate the policy file as a different user id than the one running Node.js\nand granting read permissions to the user id running Node.js.</p>",
"miscs": [
{
"textRaw": "Enabling",
"name": "Enabling",
"type": "misc",
"desc": "<p>The <code>--experimental-policy</code> flag can be used to enable features for policies\nwhen loading modules.</p>\n<p>Once this has been set, all modules must conform to a policy manifest file\npassed to the flag:</p>\n<pre><code class=\"language-bash\">node --experimental-policy=policy.json app.js\n</code></pre>\n<p>The policy manifest will be used to enforce constraints on code loaded by\nNode.js.</p>\n<p>To mitigate tampering with policy files on disk, an integrity for\nthe policy file itself may be provided via <code>--policy-integrity</code>.\nThis allows running <code>node</code> and asserting the policy file contents\neven if the file is changed on disk.</p>\n<pre><code class=\"language-bash\">node --experimental-policy=policy.json --policy-integrity=\"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0\" app.js\n</code></pre>"
},
{
"textRaw": "Features",
"name": "features",
"modules": [
{
"textRaw": "Error behavior",
"name": "error_behavior",
"desc": "<p>When a policy check fails, Node.js by default will throw an error.\nIt is possible to change the error behavior to one of a few possibilities\nby defining an \"onerror\" field in a policy manifest. The following values are\navailable to change the behavior:</p>\n<ul>\n<li><code>\"exit\"</code>: will exit the process immediately.\nNo cleanup code will be allowed to run.</li>\n<li><code>\"log\"</code>: will log the error at the site of the failure.</li>\n<li><code>\"throw\"</code>: will throw a JS error at the site of the failure. This is the\ndefault.</li>\n</ul>\n<pre><code class=\"language-json\">{\n \"onerror\": \"log\",\n \"resources\": {\n \"./app/checked.js\": {\n \"integrity\": \"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0\"\n }\n }\n}\n</code></pre>",
"type": "module",
"displayName": "Error behavior"
},
{
"textRaw": "Integrity checks",
"name": "integrity_checks",
"desc": "<p>Policy files must use integrity checks with Subresource Integrity strings\ncompatible with the browser\n<a href=\"https://www.w3.org/TR/SRI/#the-integrity-attribute\">integrity attribute</a>\nassociated with absolute URLs.</p>\n<p>When using <code>require()</code> all resources involved in loading are checked for\nintegrity if a policy manifest has been specified. If a resource does not match\nthe integrity listed in the manifest, an error will be thrown.</p>\n<p>An example policy file that would allow loading a file <code>checked.js</code>:</p>\n<pre><code class=\"language-json\">{\n \"resources\": {\n \"./app/checked.js\": {\n \"integrity\": \"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0\"\n }\n }\n}\n</code></pre>\n<p>Each resource listed in the policy manifest can be of one the following\nformats to determine its location:</p>\n<ol>\n<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>\n<li>A complete url string to a resource such as <code>file:///resource.js</code>.</li>\n</ol>\n<p>When loading resources the entire URL must match including search parameters\nand hash fragment. <code>./a.js?b</code> will not be used when attempting to load\n<code>./a.js</code> and vice versa.</p>\n<p>To generate integrity strings, a script such as\n<code>printf \"sha384-$(cat checked.js | openssl dgst -sha384 -binary | base64)\"</code>\ncan be used.</p>\n<p>Integrity can be specified as the boolean value <code>true</code> to accept any\nbody for the resource which can be useful for local development. It is not\nrecommended in production since it would allow unexpected alteration of\nresources to be considered valid.</p>",
"type": "module",
"displayName": "Integrity checks"
},
{
"textRaw": "Dependency redirection",
"name": "dependency_redirection",
"desc": "<p>An application may need to ship patched versions of modules or to prevent\nmodules from allowing all modules access to all other modules. Redirection\ncan be used by intercepting attempts to load the modules wishing to be\nreplaced.</p>\n<pre><code class=\"language-json\">{\n \"builtins\": [],\n \"resources\": {\n \"./app/checked.js\": {\n \"dependencies\": {\n \"fs\": true,\n \"os\": \"./app/node_modules/alt-os\"\n }\n }\n }\n}\n</code></pre>\n<p>The dependencies are keyed by the requested string specifier and have values\nof either <code>true</code> or a string pointing to a module that will be resolved.</p>\n<p>The specifier string does not perform any searching and must match exactly\nwhat is provided to the <code>require()</code>. Therefore, multiple specifiers may be\nneeded in the policy if <code>require()</code> uses multiple different strings to point\nto the same module (such as excluding the extension).</p>\n<p>If the value of the redirection is <code>true</code> the default searching algorithms will\nbe used to find the module.</p>\n<p>If the value of the redirection is a string, it will be resolved relative to\nthe manifest and then immediately be used without searching.</p>\n<p>Any specifier string that is <code>require()</code>ed and not listed in the dependencies\nwill result in an error according to the policy.</p>\n<p>Redirection will not prevent access to APIs through means such as direct access\nto <code>require.cache</code> and/or through <code>module.constructor</code> which allow access to\nloading modules. Policy redirection only affect specifiers to <code>require()</code>.\nOther means such as to prevent undesired access to APIs through variables are\nnecessary to lock down that path of loading modules.</p>\n<p>A boolean value of <code>true</code> for the dependencies map can be specified to allow a\nmodule to load any specifier without redirection. This can be useful for local\ndevelopment and may have some valid usage in production, but should be used\nonly with care after auditing a module to ensure its behavior is valid.</p>\n<h4>Example: Patched dependency</h4>\n<p>Redirected dependencies can provide attenuated or modified functionality as fits\nthe application. For example, log data about timing of function durations by\nwrapping the original:</p>\n<pre><code class=\"language-js\">const original = require('fn');\nmodule.exports = function fn(...args) {\n console.time();\n try {\n return new.target ?\n Reflect.construct(original, args) :\n Reflect.apply(original, this, args);\n } finally {\n console.timeEnd();\n }\n};\n</code></pre>",
"type": "module",
"displayName": "Dependency redirection"
}
],
"type": "misc",
"displayName": "Features"
}
]
}
]
}