Permissions can be used to control what system resources the\nNode.js process has access to or what actions the process can take\nwith those resources. Permissions can also control what modules can\nbe accessed by other modules.
\nModule-based permissions control which files\nor URLs are available to other modules during application execution.\nThis can be used to control what modules can be accessed by third-party\ndependencies, for example.
\nProcess-based permissions control the Node.js\nprocess's access to resources.\nThe resource can be entirely allowed or denied, or actions related to it can\nbe controlled. For example, file system reads can be allowed while denying\nwrites.\nThis feature does not protect against malicious code. According to the Node.js\nSecurity Policy, Node.js trusts any code it is asked to run.
\nThe permission model implements a \"seat belt\" approach, which prevents trusted\ncode from unintentionally changing files or using resources that access has\nnot explicitly been granted to. It does not provide security guarantees in the\npresence of malicious code. Malicious code can bypass the permission model and\nexecute arbitrary code without the restrictions imposed by the permission\nmodel.
\nIf you find a potential security vulnerability, please refer to our\nSecurity Policy.
", "modules": [ { "textRaw": "Module-based permissions", "name": "module-based_permissions", "introduced_in": "v11.8.0", "stability": 0, "stabilityText": "Deprecated: Will be removed shortly", "miscs": [ { "textRaw": "Policies", "name": "policy", "introduced_in": "v11.8.0", "type": "misc", "stability": 0, "stabilityText": "Deprecated: Will be removed shortly", "desc": "Node.js contains experimental support for creating policies on loading code.
\nPolicies are a security feature intended to ensure the integrity\nof the loaded code.
\nWhile it does not function as a provenance mechanism to trace the origin of\ncode, it serves as a robust defense against the execution of malicious code.\nUnlike runtime-based models that may restrict capabilities once the code is\nloaded, Node.js policies focus on preventing malicious code from ever being\nfully loaded into the application in the first place.
\nThe use of policies assumes safe practices for the policy\nfiles such as ensuring that policy files cannot be overwritten by the Node.js\napplication by using file 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\nThe policy manifest will be used to enforce constraints on code loaded by\nNode.js.
\nTo mitigate tampering with policy files on disk, an integrity for\nthe policy file itself may be provided via --policy-integrity.\nThis allows running node and asserting the policy file contents\neven if the file is changed on disk.
node --experimental-policy=policy.json --policy-integrity=\"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0\" app.js\nWhen 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\": will throw a JS error at the site of the failure. This is the\ndefault.{\n \"onerror\": \"log\",\n \"resources\": {\n \"./app/checked.js\": {\n \"integrity\": \"sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0\"\n }\n }\n}\nPolicy files must use integrity checks with Subresource Integrity strings\ncompatible with the browser\nintegrity attribute\nassociated with absolute URLs.
\nWhen using require() or import all resources involved in loading are checked\nfor integrity if a policy manifest has been specified. If a resource does not\nmatch the 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}\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.
To generate integrity strings, a script such as\nnode -e 'process.stdout.write(\"sha256-\");process.stdin.pipe(crypto.createHash(\"sha256\").setEncoding(\"base64\")).pipe(process.stdout)' < FILE\ncan be used.
Integrity can be specified as the boolean value true 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.
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.
\n{\n \"resources\": {\n \"./app/checked.js\": {\n \"dependencies\": {\n \"fs\": true,\n \"os\": \"./app/node_modules/alt-os\",\n \"http\": { \"import\": true }\n }\n }\n }\n}\nThe dependencies are keyed by the requested specifier string and have values\nof either true, null, a string pointing to a module to be resolved,\nor a conditions object.
The specifier string does not perform any searching and must match exactly what\nis provided to the require() or import except for a canonicalization step.\nTherefore, multiple specifiers may be needed in the policy if it uses multiple\ndifferent strings to point to the same module (such as excluding the extension).
Specifier strings are canonicalized but not resolved prior to be used for\nmatching in order to have some compatibility with import maps, for example if a\nresource file:///C:/app/utils.js was given the following redirection from a\npolicy located at file:///C:/app/policy.json:
{\n \"resources\": {\n \"file:///C:/app/utils.js\": {\n \"dependencies\": {\n \"./utils.js\": \"./utils-v2.js\"\n }\n }\n }\n}\nAny specifier used to load file:///C:/app/utils.js would then be intercepted\nand redirected to file:///C:/app/utils-v2.js instead regardless of using an\nabsolute or relative specifier. However, if a specifier that is not an absolute\nor relative URL string is used, it would not be intercepted. So, if an import\nsuch as import('#utils') was used, it would not be intercepted.
If the value of the redirection is true, a \"dependencies\" field at the top of\nthe policy file will be used. If that field at the top of the policy file is\ntrue the default node searching algorithms are used to find the module.
If the value of the redirection is a string, it is resolved relative to\nthe manifest and then immediately used without searching.
\nAny specifier string for which resolution is attempted and that is not listed in\nthe dependencies results in an error according to the policy.
\nA boolean value of true 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.
Similar to \"exports\" in package.json, dependencies can also be specified to\nbe objects containing conditions which branch how dependencies are loaded. In\nthe preceding example, \"http\" is allowed when the \"import\" condition is\npart of loading it.
A value of null for the resolved value causes the resolution to fail. This\ncan be used to ensure some kinds of dynamic access are explicitly prevented.
Unknown values for the resolved module location cause failures but are\nnot guaranteed to be forward compatible.
\nAll the guarantees for policy redirection are specified in the\nGuarantees section.
\nRedirected dependencies can provide attenuated or modified functionality as fits\nthe application. For example, log data about timing of function durations by\nwrapping the original:
\nconst 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};\nUse the \"scopes\" field of a manifest to set configuration for many resources\nat once. The \"scopes\" field works by matching resources by their segments.\nIf a scope or resource includes \"cascade\": true, unknown specifiers will\nbe searched for in their containing scope. The containing scope for cascading\nis found by recursively reducing the resource URL by removing segments for\nspecial schemes, keeping trailing \"/\" suffixes, and removing the query and\nhash fragment. This leads to the eventual reduction of the URL to its origin.\nIf the URL is non-special the scope will be located by the URL's origin. If no\nscope is found for the origin or in the case of opaque origins, a protocol\nstring can be used as a scope. If no scope is found for the URL's protocol, a\nfinal empty string \"\" scope will be used.
Note, blob: URLs adopt their origin from the path they contain, and so a scope\nof \"blob:https://nodejs.org\" will have no effect since no URL can have an\norigin of blob:https://nodejs.org; URLs starting with\nblob:https://nodejs.org/ will use https://nodejs.org for its origin and\nthus https: for its protocol scope. For opaque origin blob: URLs they will\nhave blob: for their protocol scope since they do not adopt origins.
{\n \"scopes\": {\n \"file:///C:/app/\": {},\n \"file:\": {},\n \"\": {}\n }\n}\nGiven a file located at file:///C:/app/bin/main.js, the following scopes would\nbe checked in order:
\"file:///C:/app/bin/\"This determines the policy for all file based resources within\n\"file:///C:/app/bin/\". This is not in the \"scopes\" field of the policy and\nwould be skipped. Adding this scope to the policy would cause it to be used\nprior to the \"file:///C:/app/\" scope.
\"file:///C:/app/\"This determines the policy for all file based resources within\n\"file:///C:/app/\". This is in the \"scopes\" field of the policy and it would\ndetermine the policy for the resource at file:///C:/app/bin/main.js. If the\nscope has \"cascade\": true, any unsatisfied queries about the resource would\ndelegate to the next relevant scope for file:///C:/app/bin/main.js, \"file:\".
\"file:///C:/\"This determines the policy for all file based resources within \"file:///C:/\".\nThis is not in the \"scopes\" field of the policy and would be skipped. It would\nnot be used for file:///C:/app/bin/main.js unless \"file:///C:/app/\" is set\nto cascade or is not in the \"scopes\" of the policy.
\"file:///\"This determines the policy for all file based resources on the localhost. This\nis not in the \"scopes\" field of the policy and would be skipped. It would not\nbe used for file:///C:/app/bin/main.js unless \"file:///C:/\" is set to\ncascade or is not in the \"scopes\" of the policy.
\"file:\"This determines the policy for all file based resources. It would not be used\nfor file:///C:/app/bin/main.js unless \"file:///\" is set to cascade or is not\nin the \"scopes\" of the policy.
\"\"This determines the policy for all resources. It would not be used for\nfile:///C:/app/bin/main.js unless \"file:\" is set to cascade.
Setting an integrity to true on a scope will set the integrity for any\nresource not found in the manifest to true.
Setting an integrity to null on a scope will set the integrity for any\nresource not found in the manifest to fail matching.
Not including an integrity is the same as setting the integrity to null.
\"cascade\" for integrity checks will be ignored if \"integrity\" is explicitly\nset.
The following example allows loading any file:
\n{\n \"scopes\": {\n \"file:\": {\n \"integrity\": true\n }\n }\n}\nThe following example, would allow access to fs for all resources within\n./app/:
{\n \"resources\": {\n \"./app/checked.js\": {\n \"cascade\": true,\n \"integrity\": true\n }\n },\n \"scopes\": {\n \"./app/\": {\n \"dependencies\": {\n \"fs\": true\n }\n }\n }\n}\nThe following example, would allow access to fs for all data: resources:
{\n \"resources\": {\n \"data:text/javascript,import('node:fs');\": {\n \"cascade\": true,\n \"integrity\": true\n }\n },\n \"scopes\": {\n \"data:\": {\n \"dependencies\": {\n \"fs\": true\n }\n }\n }\n}\nGiven an import map:
\n{\n \"imports\": {\n \"react\": \"./app/node_modules/react/index.js\"\n },\n \"scopes\": {\n \"./ssr/\": {\n \"react\": \"./app/node_modules/server-side-react/index.js\"\n }\n }\n}\n{\n \"dependencies\": true,\n \"scopes\": {\n \"\": {\n \"cascade\": true,\n \"dependencies\": {\n \"react\": \"./app/node_modules/react/index.js\"\n }\n },\n \"./ssr/\": {\n \"cascade\": true,\n \"dependencies\": {\n \"react\": \"./app/node_modules/server-side-react/index.js\"\n }\n }\n }\n}\nImport maps assume you can get any resource by default. This means\n\"dependencies\" at the top level of the policy should be set to true.\nPolicies require this to be opt-in since it enables all resources of the\napplication cross linkage which doesn't make sense for many scenarios. They also\nassume any given scope has access to any scope above its allowed dependencies;\nall scopes emulating import maps must set \"cascade\": true.
Import maps only have a single top level scope for their \"imports\". So for\nemulating \"imports\" use the \"\" scope. For emulating \"scopes\" use the\n\"scopes\" in a similar manner to how \"scopes\" works in import maps.
Caveats: Policies do not use string matching for various finding of scope. They\ndo URL traversals. This means things like blob: and data: URLs might not be\nentirely interoperable between the two systems. For example import maps can\npartially match a data: or blob: URL by partitioning the URL on a /\ncharacter, policies intentionally cannot. For blob: URLs import map scopes do\nnot adopt the origin of the blob: URL.
Additionally, import maps only work on import so it may be desirable to add a\n\"import\" condition to all dependency mappings.
require(), import() or new Module().require.cache which allow access to loaded modules.\nPolicy redirection only affects specifiers to require() and\nimport.The Node.js Permission Model is a mechanism for restricting access to specific\nresources during execution.\nThe API exists behind a flag --experimental-permission which when enabled,\nwill restrict access to all available permissions.
The available permissions are documented by the --experimental-permission\nflag.
When starting Node.js with --experimental-permission,\nthe ability to access the file system through the fs module, spawn processes,\nuse node:worker_threads, use native addons, use WASI, and enable the runtime inspector\nwill be restricted.
$ node --experimental-permission index.js\nnode:internal/modules/cjs/loader:171\n const result = internalModuleStat(filename);\n ^\n\nError: Access to this API has been restricted\n at stat (node:internal/modules/cjs/loader:171:18)\n at Module._findPath (node:internal/modules/cjs/loader:627:16)\n at resolveMainPath (node:internal/modules/run_main:19:25)\n at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:76:24)\n at node:internal/main/run_main_module:23:47 {\n code: 'ERR_ACCESS_DENIED',\n permission: 'FileSystemRead',\n resource: '/home/user/index.js'\n}\nAllowing access to spawning a process and creating worker threads can be done\nusing the --allow-child-process and --allow-worker respectively.
To allow native addons when using permission model, use the --allow-addons\nflag. For WASI, use the --allow-wasi flag.
When enabling the Permission Model through the --experimental-permission\nflag a new property permission is added to the process object.\nThis property contains one function:
API call to check permissions at runtime (permission.has())
process.permission.has('fs.write'); // true\nprocess.permission.has('fs.write', '/home/rafaelgss/protected-folder'); // true\n\nprocess.permission.has('fs.read'); // true\nprocess.permission.has('fs.read', '/home/rafaelgss/protected-folder'); // false\nThe Permission Model, by default, restricts access to the file system through the node:fs module.\nIt does not guarantee that users will not be able to access the file system through other means,\nsuch as through the node:sqlite module.
To allow access to the file system, use the --allow-fs-read and\n--allow-fs-write flags:
$ node --experimental-permission --allow-fs-read=* --allow-fs-write=* index.js\nHello world!\n(node:19836) ExperimentalWarning: Permission is an experimental feature\n(Use `node --trace-warnings ...` to show where the warning was created)\nThe valid arguments for both flags are:
\n* - To allow all FileSystemRead or FileSystemWrite operations,\nrespectively.,) to allow only matching FileSystemRead or\nFileSystemWrite operations, respectively.Example:
\n--allow-fs-read=* - It will allow all FileSystemRead operations.--allow-fs-write=* - It will allow all FileSystemWrite operations.--allow-fs-write=/tmp/ - It will allow FileSystemWrite access to the /tmp/\nfolder.--allow-fs-read=/tmp/ --allow-fs-read=/home/.gitignore - It allows FileSystemRead access\nto the /tmp/ folder and the /home/.gitignore path.Wildcards are supported too:
\n--allow-fs-read=/home/test* will allow read access to everything\nthat matches the wildcard. e.g: /home/test/file1 or /home/test2After passing a wildcard character (*) all subsequent characters will\nbe ignored. For example: /home/*.js will work similar to /home/*.
When the permission model is initialized, it will automatically add a wildcard\n(*) if the specified directory exists. For example, if /home/test/files\nexists, it will be treated as /home/test/files/*. However, if the directory\ndoes not exist, the wildcard will not be added, and access will be limited to\n/home/test/files. If you want to allow access to a folder that does not exist\nyet, make sure to explicitly include the wildcard:\n/my-path/folder-do-not-exist/*.
There are constraints you need to know before using this system:
\n--env-file or --openssl-config are designed\nto read files before environment initialization. As a result, such flags are\nnot subject to the rules of the Permission Model. The same applies for V8\nflags that can be set via runtime through v8.setFlagsFromString.node:fs module bypasses the\nPermission Model.