A Node.js application does not always need unrestricted access to the machine on which it runs. A typical API server may need to read its application files, load configuration, write temporary files, and communicate with a database. However, it usually does not need permission to modify every directory on the server, execute arbitrary system commands, or access unrelated files.
This distinction becomes important when an application runs in a production environment. If a vulnerability allows an attacker to execute unintended code within the Node.js process, the damage can depend on what resources that process can access. An application running with broad permissions may expose files, modify important data, or execute additional processes.
Node.js provides a built-in Permission Model that allows developers to restrict access to selected system resources. It can control file system operations, network access, environment variables, child processes, worker threads, native addons, and other capabilities.
However, enabling the Permission Model is not simply a matter of adding --permission to the startup command. Existing applications may depend on file access performed by dependencies, configuration loaders, logging libraries, build tools, and background jobs. If those requirements are not understood, the application may start failing with permission errors.
The practical approach is to understand the application's actual resource requirements, introduce restrictions gradually, and grant only the permissions needed for normal operation.
What Is the Node.js Permission Model?
The Node.js Permission Model provides a way to restrict what a Node.js process can access while it is running. When enabled, Node.js denies operations that have not been explicitly permitted.
For example, consider an application that processes uploaded documents. It needs to read application files and write processed documents to a specific upload directory. It does not necessarily need write access to the application's source directory or other locations on the server.
Without permission restrictions, the process generally operates with the file system privileges of its operating-system user. The application can access any location that user is allowed to access.
With the Permission Model, developers can explicitly grant file system access and other capabilities through command-line options.
The feature was introduced in Node.js 20 and became stable in Node.js 22.13.0 and 23.5.0. It is enabled through the --permission flag.
For example:
node --permission app.js
This command starts Node.js with the Permission Model enabled. Access to restricted resources is denied unless the necessary permissions have been granted.
When an operation is blocked, Node.js can throw an ERR_ACCESS_DENIED error. This makes missing permissions visible during development and testing.
An important distinction is that the Permission Model is designed as a safety mechanism for trusted application code. It is not a complete security sandbox for executing malicious JavaScript. Node.js explicitly documents that malicious code may bypass these restrictions. Production applications should still use operating-system isolation, containers, appropriate user permissions, and other security controls.
Understand the File System Permissions
File system access is one of the most important areas to understand before enabling the Permission Model.
Node.js provides two primary options for controlling file access:
These permissions are separate. An application can be allowed to read a directory without receiving permission to modify it.
For example, consider this application structure:
orders-api/
app.js
package.json
node_modules/
config/
app-config.json
uploads/
logs/
The application needs to read its source code, installed dependencies, and configuration. It also needs to write uploaded files and application logs.
A broad permission configuration might look like this:
node --permission \
--allow-fs-read=/srv/orders-api/ \
--allow-fs-write=/srv/orders-api/uploads/ \
--allow-fs-write=/srv/orders-api/logs/ \
app.js
Here, the application receives read access to its application directory and write access to two specific directories.
This is preferable to granting unrestricted file system access:
node --permission \
--allow-fs-read=* \
--allow-fs-write=* \
app.js
The second example effectively removes the intended file system restrictions. It may be useful temporarily while diagnosing an application, but it should not be the default production configuration.
There is also an important detail about paths. The Permission Model supports absolute paths, relative paths, and wildcards. Existing directories specified in the permission configuration are treated as directory grants. If a directory does not yet exist, the behavior is different, so explicitly include a wildcard when granting access to a directory that will be created later.
For example:
node --permission \
--allow-fs-write=/srv/orders-api/generated/* \
app.js
The application should be tested with the exact directory structure used in production. A permission configuration that works on a developer's machine may behave differently when deployment paths, symbolic links, or mounted directories change.
Why Applications Fail After Enabling --permission
A common mistake is assuming that the application only needs access to the files developers directly open in their own code.
In reality, an application may perform file operations through several layers.
A configuration library may read a JSON file during startup. A logging package may create a directory or rotate log files. An image-processing package may write temporary files. A dependency may load certificates, templates, or other resources from disk.
These operations are not always obvious when looking at the main application entry point.
Consider the following code:
const fs = require('node:fs');
const config = fs.readFileSync(
'./config/app-config.json',
'utf8'
);
console.log(config);
If the application starts with the Permission Model enabled but does not have permission to read the configuration file, Node.js rejects the operation.
The error may look similar to this:
Error: Access to this API has been restricted
code: 'ERR_ACCESS_DENIED'
permission: 'FileSystemRead'
The correct response is not to disable the Permission Model immediately. First, identify which file or directory the application is trying to access.
Then grant access to that specific resource.
node --permission \
--allow-fs-read=/srv/orders-api/config/ \
app.js
If the application also needs to read its dependencies and source files, include those paths in the read configuration.
This is why permission configuration should be based on actual application behavior rather than assumptions about which directories should be accessible.
Use Audit Mode Before Enforcing Restrictions
One of the most useful features of the Node.js Permission Model is audit mode.
Developers often struggle to determine every file or system resource an application accesses during normal execution. Enabling strict restrictions immediately can reveal many missing permissions, especially in applications with several dependencies.
Instead of discovering all these problems through repeated startup failures, developers can use --permission-audit to observe permission violations without blocking the operations.
For example:
node --permission-audit app.js
In audit mode, Node.js performs permission checks and publishes information about operations that would be denied under enforcement mode. The application continues running normally.
This provides an opportunity to exercise the application and identify its resource requirements before enabling strict enforcement.
Developers can also subscribe to the relevant diagnostics channel to capture these events.
const diagnosticsChannel =
require('node:diagnostics_channel');
diagnosticsChannel
.channel('node:permission-model:fs')
.subscribe((message) => {
console.log('File system permission event:', {
permission: message.permission,
resource: message.resource
});
});
The diagnostics channel reports information about the permission check, including the affected resource. Similar channels are available for network, child process, worker, environment, and other permission categories.
A useful testing strategy is to run the application through its normal workflows while audit mode is enabled. Do not limit testing to application startup. Exercise file uploads, downloads, report generation, logging, background processing, and any scheduled operations.
Once the required permissions are understood, move to enforcement mode and verify that the same workflows continue working.
Audit mode is a discovery mechanism, not a security enforcement mechanism. Operations that would otherwise be denied are still allowed while auditing.
Control Other Capabilities Beyond File Access
The Permission Model is not limited to the file system. It also restricts several other capabilities that can have significant security implications.
Capability | Permission option | Typical application requirement |
|---|
File system reading | --allow-fs-read
| Loading configuration and application files |
File system writing | --allow-fs-write
| Uploads, temporary files, and logs |
Network access | --allow-net
| Calling external APIs and databases |
Environment variables | --allow-env
| Reading application configuration |
Child processes | --allow-child-process
| Executing external commands |
Worker threads | --allow-worker
| Running background computation |
Native addons | --allow-addons
| Loading native Node.js extensions |
WASI | --allow-wasi
| Running WebAssembly System Interface modules |
FFI | --allow-ffi
| Accessing foreign functions through supported FFI functionality |
For example, an application that uses the node:child_process module to execute an external command will not automatically receive permission to create child processes.
The developer must explicitly grant that capability:
node --permission \
--allow-child-process \
app.js
Similarly, an application that uses worker threads needs the corresponding permission:
node --permission \
--allow-worker \
app.js
Do not grant these capabilities simply because a dependency might use them. First determine whether the application genuinely needs them and whether the requirement can be removed or handled through a safer design.
For network access, the --allow-net option enables the network capability. It should not be confused with a complete outbound network firewall or a host-level network security policy. Use infrastructure-level network controls when an application must be restricted to specific destinations.
Check Permissions From Application Code
The Permission Model also exposes a runtime API through process.permission.
The process.permission.has() method allows an application to check whether a particular permission has been granted.
For example:
if (process.permission.has('fs.write')) {
console.log('File system write access is available.');
} else {
console.log('File system write access is restricted.');
}
The method can also check access to a specific resource:
const canWriteUploads =
process.permission.has(
'fs.write',
'/srv/orders-api/uploads'
);
if (!canWriteUploads) {
throw new Error(
'Upload directory permission is missing.'
);
}
This can be useful when an application needs to validate its startup requirements and report configuration problems clearly.
The runtime API also provides process.permission.drop(), which allows an application to permanently remove a previously granted permission.
For example, an application may need to read a configuration file during startup but no longer need access to its containing directory afterward.
const fs = require('node:fs');
const config = fs.readFileSync(
'/srv/orders-api/config/app-config.json',
'utf8'
);
// Remove read permission after initialization.
process.permission.drop(
'fs.read',
'/srv/orders-api/config'
);
Dropping a permission is irreversible for the current process. It also affects future permission checks; it does not automatically close file descriptors, sockets, or other resources that are already open.
This feature should be used carefully. If a background task needs to reload configuration later, removing the required permission during startup may cause that task to fail.
Make the Permission Configuration Easier to Maintain
Long command-line arguments become difficult to maintain when an application has several directories and resource requirements.
Node.js supports configuration files for Permission Model settings through the --config-file option.
For example, create a node.config.json file:
{
"permission": {
"allow-fs-read": [
"./",
"/srv/orders-api/config"
],
"allow-fs-write": [
"/srv/orders-api/uploads",
"/srv/orders-api/logs"
],
"allow-child-process": false,
"allow-worker": false,
"allow-addons": false,
"allow-ffi": false
}
}
Start the application using:
node --config-file=node.config.json app.js
When the configuration file contains the permission namespace, Node.js automatically enables the Permission Model.
This approach makes permission requirements easier to review and maintain. It also gives developers a central place to understand which resources the application is expected to access.
Keep this file aligned with the application's deployment environment. Relative paths are resolved in relation to the current working directory, so production startup scripts should use a predictable working directory.
Common Mistakes When Enabling the Permission Model
One frequent mistake is granting unrestricted file system access simply to fix an ERR_ACCESS_DENIED error. Although this may make the application work again, it removes much of the benefit of enabling the Permission Model. Identify the actual resource that caused the failure and grant access only to the required directory or file.
Another mistake is testing only the main API endpoints. Production applications often perform file operations during scheduled jobs, background tasks, report generation, and application shutdown. These paths should also be tested before enabling enforcement in production.
Developers should also be careful with worker threads. The Permission Model's behavior depends on how worker arguments are configured. If execArgv is explicitly supplied, it replaces inherited command-line flags. A worker created with an empty execArgv array does not automatically retain the parent's permission configuration. Review worker startup code rather than assuming that every worker has identical permissions.
Finally, do not treat the Permission Model as a replacement for operating-system security. Node.js documents limitations involving APIs outside its permission checks, native functionality, existing file descriptors, and other execution paths. Symbolic links also require careful handling because they can lead outside the paths developers intended to grant.
For applications that process untrusted input or execute third-party code, use additional isolation such as containers, separate operating-system users, restricted file mounts, and network policies.
Best Practices for Production Applications
Start by identifying what the application actually needs. Separate read-only application resources from directories where the application must create or modify files. Keep temporary files, uploads, and logs in dedicated locations rather than allowing writes throughout the application directory.
Use audit mode to discover resource access during realistic testing. Once the requirements are understood, enable enforcement and test the same workflows again. This approach reduces the chance of discovering missing permissions only after deployment.
Review every capability grant. Child processes, worker threads, native addons, and network access should be enabled only when there is a genuine requirement. Keep permission configuration under source control so changes can be reviewed alongside application code.
Also make sure the application runs under a dedicated operating-system account with limited privileges. The Node.js Permission Model and operating-system permissions complement each other; neither should be treated as a complete substitute for the other.
Summary
The Node.js Permission Model gives developers a practical way to restrict the resources available to a running application. By using --permission, --allow-fs-read, --allow-fs-write, and the other permission options, teams can reduce unnecessary access to files, processes, network resources, and other system capabilities.
The main challenge is identifying the resources an existing application genuinely needs. Dependencies, configuration loaders, logging systems, and background jobs may perform operations that are not immediately visible in the application code.
Using audit mode before enforcement helps uncover these requirements without interrupting normal execution. Developers can then grant narrowly scoped permissions, validate application workflows, and maintain the configuration as part of the deployment process.
Most importantly, the Permission Model should be one layer of a broader security strategy. Combined with operating-system isolation, secure dependency management, restricted service accounts, and careful deployment practices, it helps reduce the impact of unintended operations without requiring developers to redesign their entire Node.js application.
Join the conversation! Your thoughts help the community grow.