{ "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": "
Node.js contains experimental support for creating policies on loading code.
\nPolicies 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.
\nA 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.
", "miscs": [ { "textRaw": "Enabling", "name": "Enabling", "type": "misc", "desc": "The --experimental-policy
flag can be used to enable features for policies\nwhen loading modules.
Once this has been set, all modules must conform to a policy manifest file\npassed to the flag:
\nnode --experimental-policy=policy.json app.js\n
\nThe policy manifest will be used to enforce constraints on code loaded by\nNode.js.
" }, { "textRaw": "Features", "name": "features", "modules": [ { "textRaw": "Error Behavior", "name": "error_behavior", "desc": "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:
\n\"exit\"
- will exit the process immediately.\nNo cleanup code will be allowed to run.\"log\"
- will log the error at the site of the failure.\"throw\"
(default) - will throw a JS error at the site of the failure.{\n \"onerror\": \"log\",\n \"resources\": {\n \"./app/checked.js\": {\n \"integrity\": \"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0\"\n }\n }\n}\n
",
"type": "module",
"displayName": "Error Behavior"
},
{
"textRaw": "Integrity Checks",
"name": "integrity_checks",
"desc": "Policy files must use integrity checks with Subresource Integrity strings\ncompatible with the browser\nintegrity attribute\nassociated with absolute URLs.
\nWhen using require()
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.
An example policy file that would allow loading a file checked.js
:
{\n \"resources\": {\n \"./app/checked.js\": {\n \"integrity\": \"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0\"\n }\n }\n}\n
\nEach resource listed in the policy manifest can be of one the following\nformats to determine its location:
\n./resource.js
, ../resource.js
, or /resource.js
.file:///resource.js
.When loading resources the entire URL must match including search parameters\nand hash fragment. ./a.js?b
will not be used when attempting to load\n./a.js
and vice versa.
In order to generate integrity strings, a script such as\nprintf \"sha384-$(cat checked.js | openssl dgst -sha384 -binary | base64)\"
\ncan be used.