doc/api/permissions.md
Permissions can be used to control what system resources the Node.js process has access to or what actions the process can take with those resources.
The permission model implements a "seat belt" approach, which prevents trusted code from unintentionally changing files or using resources that access has not explicitly been granted to. It does not provide security guarantees in the presence of malicious code. Malicious code can bypass the permission model and execute arbitrary code without the restrictions imposed by the permission model.
If you find a potential security vulnerability, please refer to our Security Policy.
Stability: 2 - Stable
The Node.js Permission Model is a mechanism for restricting access to specific
resources during execution.
The API exists behind a flag --permission which when enabled,
will restrict access to all available permissions.
The available permissions are documented by the --permission
flag.
The Permission Model has two operational modes:
--permission): Access is denied and
an ERR_ACCESS_DENIED error is thrown for any operation the process has not
been granted permission to perform.--permission-audit): Permission checks are
performed and violations are published through the diagnostics channel, but
access is not denied. Execution continues normally. This mode is useful
for discovering what permissions your application requires before deploying
with enforce mode.When starting Node.js with --permission,
the ability to access the file system through the fs module, access the network,
spawn processes, use node:worker_threads, use native addons, use WASI, use
FFI, and enable the runtime inspector will be restricted (the listener for
SIGUSR1 won't be created).
$ node --permission index.js
Error: Access to this API has been restricted
at node:internal/main/run_main_module:23:47 {
code: 'ERR_ACCESS_DENIED',
permission: 'FileSystemRead',
resource: '/home/user/index.js'
}
Allowing access to spawning a process and creating worker threads can be done
using the --allow-child-process and --allow-worker respectively.
To allow network access, use --allow-net and for allowing native addons
when using permission model, use the --allow-addons
flag. For WASI, use the --allow-wasi flag. For FFI, use the
--allow-ffi flag. The node:ffi module also requires the
--experimental-ffi flag and is only available in builds with FFI support.
To allow use of OpenSSL STORE loaders, for example to load a private key
from a {URL} passed to crypto.createPrivateKey(), use the
--allow-openssl-store flag.
This flag grants broad authority to configured OpenSSL STORE loaders, which may
access files, devices, tokens, or the network. Access performed by a loader is
not constrained by the fs.read, fs.write, or net permission scopes.
When enabling the Permission Model through the --permission
or --permission-audit flags, a new property permission is added to the
process object. This property contains the following functions:
permission.has(scope[, reference])API call to check permissions at runtime (permission.has())
process.permission.has('fs.write'); // true
process.permission.has('fs.write', '/home/rafaelgss/protected-folder'); // true
process.permission.has('fs.read'); // true
process.permission.has('fs.read', '/home/rafaelgss/protected-folder'); // false
permission.drop(scope[, reference])API call to drop permissions at runtime. This operation is irreversible.
When called without a reference, the entire scope is dropped. When called with a reference, only the permission for that specific resource is revoked. Dropping a permission only affects future access checks. It does not close or revoke access to resources that are already open, such as file descriptors, network sockets, child processes, or worker threads. Applications are responsible for closing or terminating those resources when they are no longer needed.
You can only drop the exact resource that was explicitly granted. The
reference passed to drop() must match the original grant. If a permission
was granted using a wildcard (*), only the entire scope can be dropped
(by calling drop() without a reference). If a directory was granted
(e.g. --allow-fs-read=/my/folder), you cannot drop individual files
inside it - you must drop the same directory that was originally granted.
const fs = require('node:fs');
// Read config at startup while we still have permission
const config = fs.readFileSync('/etc/myapp/config.json', 'utf8');
// Drop read access to /etc/myapp after initialization
process.permission.drop('fs.read', '/etc/myapp');
// This will now throw ERR_ACCESS_DENIED
process.permission.has('fs.read', '/etc/myapp/config.json'); // false
// Drop child process permission entirely
process.permission.drop('child');
The --permission-audit flag enables audit mode for the Permission Model.
In audit mode, permission checks are performed but access is not denied —
no ERR_ACCESS_DENIED error is thrown. Instead, each permission violation is
published through the node:diagnostics_channel module, allowing the
application to observe and log which operations would be denied under enforce
mode. Execution continues normally.
Audit mode is useful for discovering what permissions your application
requires before deploying with --permission. It can also be combined
with the --allow-fs-read, --allow-fs-write, --allow-net,
--allow-child-process, --allow-worker, --allow-addons,
--allow-wasi, and --allow-ffi flags to audit a subset of
permissions while granting others.
When a permission check fails in audit mode, a message is published to the diagnostics channel corresponding to the denied scope. The channel names are:
node:permission-model:fs — File System (read and write)node:permission-model:net — Networknode:permission-model:child — Child Processnode:permission-model:worker — Worker Threadsnode:permission-model:inspector — Inspectornode:permission-model:wasi — WASInode:permission-model:addon — Native Addonsnode:permission-model:ffi — FFIEach message is an object with the following properties:
permission {string} The name of the denied permission scope.resource {string} The resource that access was denied to (e.g. a file path
or host).const diagnostics_channel = require('node:diagnostics_channel');
diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
});
// Running with --permission-audit, this publishes a diagnostics channel
// message but does not throw
const fs = require('node:fs');
fs.readFileSync('/etc/passwd');
If both --permission and --permission-audit are specified,
--permission takes precedence and the Permission Model runs in enforce mode.
The Permission Model, by default, restricts access to the file system through the node:fs module.
It does not guarantee that users will not be able to access the file system through other means,
such as through the node:sqlite module.
To allow access to the file system, use the --allow-fs-read and
--allow-fs-write flags:
$ node --permission --allow-fs-read=* --allow-fs-write=* index.js
Hello world!
By default the entrypoints of your application are included in the allowed file system read list. For example:
$ node --permission index.js
index.js will be included in the allowed file system read list$ node -r /path/to/custom-require.js --permission index.js.
/path/to/custom-require.js will be included in the allowed file system read
list.index.js will be included in the allowed file system read list.The valid arguments for both flags are:
* - To allow all FileSystemRead or FileSystemWrite operations,
respectively.Example:
--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/
folder.--allow-fs-read=/tmp/ --allow-fs-read=/home/.gitignore - It allows FileSystemRead access
to the /tmp/ folder and the /home/.gitignore path.Wildcards are supported too:
--allow-fs-read=/home/test* will allow read access to everything
that matches the wildcard. e.g: /home/test/file1 or /home/test2After passing a wildcard character (*) all subsequent characters will
be ignored. For example: /home/*.js will work similar to /home/*.
When the permission model is initialized, it will automatically add a wildcard
(*) if the specified directory exists. For example, if /home/test/files
exists, it will be treated as /home/test/files/*. However, if the directory
does not exist, the wildcard will not be added, and access will be limited to
/home/test/files. If you want to allow access to a folder that does not exist
yet, make sure to explicitly include the wildcard:
/my-path/folder-do-not-exist/*.
In addition to passing permission flags on the command line, they can also be
declared in a Node.js configuration file when using the experimental
[--experimental-config-file][] flag. Permission options must be placed inside
the permission top-level object.
Example node.config.json:
{
"permission": {
"allow-fs-read": ["./foo"],
"allow-fs-write": ["./bar"],
"allow-child-process": true,
"allow-worker": true,
"allow-net": true,
"allow-addons": false,
"allow-ffi": false,
"allow-openssl-store": false
}
}
When the permission namespace is present in the configuration file, Node.js
automatically enables the --permission flag. Run with:
$ node --experimental-default-config-file app.js
npxIf you're using npx to execute a Node.js script, you can enable the
Permission Model by passing the --node-options flag. For example:
npx --node-options="--permission" package-name
This sets the NODE_OPTIONS environment variable for all Node.js processes
spawned by npx, without affecting the npx process itself.
FileSystemRead Error with npx
The above command will likely throw a FileSystemRead invalid access error
because Node.js requires file system read access to locate and execute the
package. To avoid this:
Using a Globally Installed Package
Grant read access to the global node_modules directory by running:
npx --node-options="--permission --allow-fs-read=$(npm prefix -g)" package-name
Using the npx Cache
If you are installing the package temporarily or relying on the npx cache,
grant read access to the npm cache directory:
npx --node-options="--permission --allow-fs-read=$(npm config get cache)" package-name
Any arguments you would normally pass to node (e.g., --allow-* flags) can
also be passed through the --node-options flag. This flexibility makes it
easy to configure permissions as needed when using npx.
There are constraints you need to know before using this system:
--env-file or --openssl-config are designed
to read files before environment initialization. As a result, such flags are
not subject to the rules of the Permission Model. The same applies for V8
flags that can be set via runtime through v8.setFlagsFromString.node:fs module bypasses the
Permission Model.The kInspector permission scope restricts the current process from opening its own V8 Inspector. However,
process._debugProcess(pid) — which sends an OS-level signal (SIGUSR1 on POSIX, a remote thread on Windows)
to an external process — is not gated by the kInspector scope or any other Permission Model scope.
A sandboxed process running under --permission with no additional grants can call process._debugProcess(pid) to force another Node.js process to open its V8 Inspector. The target process does not need to be running under --permission for this to work — any Node.js process running on the same host under the same OS user can be signaled.
This is consistent with the Node.js threat model: Node.js trusts the OS environment in which it runs. Cross-process signaling is an operating-system-level capability; restricting it is the responsibility of the operator (for example, using OS-level process isolation, separate OS users per process, or seccomp/AppArmor profiles on Linux).
Developers relying on --permission to sandbox untrusted code should be aware that: