Node.js 57 🟢 Native Permission Model (–permission) for File, Process, and Worker Access
Node.js has always trusted the code it runs. Any npm package, any postinstall script, any dependency in the tree executes with the full privileges of the Node.js process: it can read the filesystem, spawn subprocesses, open network connections, and load native addons. The permission model changes that default. When Node.js is started with the --permission flag, the process starts with no permissions at all. Every capability must be explicitly granted on the command line, and any attempt to use an ungranted capability throws ERR_ACCESS_DENIED . The model went stable in Node.js 23.5.0 and is available in current LTS releases .
Key point: The permission model is a “seat belt,” not a sandbox. Node.js’s own documentation states explicitly that it “does not provide security guarantees in the presence of malicious code” . It prevents trusted code from accidentally touching files it should not touch, and it raises the cost of a supply-chain attack, but a determined attacker with code execution can bypass it.
Why the permission model exists
The ambient-authority problem. A Node.js process runs with the full privileges of the user who started it. A build script that only needs to read a package.json and write to dist/ can also read ~/.aws/credentials, spawn a shell, and exfiltrate the result over the network. The permission model closes the gap between what a script needs and what it can do.
The supply-chain problem. The most common npm attack pattern is a malicious postinstall script that reads sensitive files or connects to an external server. With --permission, the script starts with no filesystem or child-process access. It cannot read the credentials file, and it cannot spawn a shell to exfiltrate anything .
The transitive-dependency problem. A dependency of a dependency can execute arbitrary code in an install script, and no one reviewed the package. The permission model limits what any code in the process can do, regardless of which package introduced it.
The least-privilege principle. The default in most runtimes is maximum privilege. The permission model inverts the default: the process starts with nothing, and the operator grants only what the application demonstrably needs. This is the principle of least privilege applied at the process level.
The stability milestone. The model started as --experimental-permission in Node.js 20 and moved to stable in Node.js 23.5.0 . The stability means the API is documented and supported, and the flags are not expected to change between minor releases.
The comparison with Deno. Deno has had a granular permission model since 1.0, with network host scoping and environment variable scoping. Node.js’s model is coarser: it covers filesystem reads and writes, child processes, workers, native addons, WASI, and the inspector, but network scoping is still being developed .
a. Enabling the permission model
The --permission flag activates the model. When it is enabled, all six capability classes are restricted by default.
The basic invocation
node --permission index.js
The process starts with no filesystem access, no child-process spawning, no worker threads, no native addons, no WASI, and no inspector. Any attempt to use one of them throws an error.
The default error
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'
}
The error includes the permission that was denied and the resource that triggered the denial . The code is always ERR_ACCESS_DENIED.
The entry-point exception
The entry point of the application is automatically added to the filesystem read list. A script run as node --permission index.js can read index.js without an explicit grant . Preloaded modules passed with -r are also included.
The process.permission API
When the model is enabled, the process.permission object is added with a has method for runtime checks .
process.permission.has('fs.write'); // true or false
process.permission.has('fs.write', '/home/user/protected-folder');
The has method returns a boolean. It is used by libraries that want to degrade gracefully when a capability is denied.
The stability status
The model is stable as of Node.js 23.5.0. The --permission flag is documented in the CLI reference, and the API is part of the stable surface .
b. Granting file system access
Filesystem access is the most commonly granted capability. The --allow-fs-read and --allow-fs-write flags control it.
The allow-fs-read flag
node --permission --allow-fs-read=/app/src app.js
The flag accepts absolute paths, relative paths, and wildcards. The * argument allows all reads .
The allow-fs-write flag
node --permission --allow-fs-write=/tmp/ --allow-fs-write=/app/uploads app.js
The write flag follows the same syntax. It can be repeated to grant multiple paths, and the paths must not be comma-separated .
The wildcard behavior
A wildcard after a path allows everything matching the prefix.
node --permission --allow-fs-read="/home/test*" app.js
The pattern matches /home/test/file1 and /home/test2. Everything after the * is ignored .
The directory expansion
When a directory path is granted, Node.js automatically appends a wildcard if the directory exists.
node --permission --allow-fs-read=/app/data app.js
If /app/data exists, the grant becomes /app/data/*. If the directory does not exist, the wildcard is not added, and access is limited to the exact path .
The comma-separated paths
The comma-separated syntax is no longer allowed. Passing a single flag with commas produces a warning, and the paths are not treated as separate grants .
# Deprecated
node --permission --allow-fs-read=/folder1/,/folder2/ app.js
# Correct
node --permission --allow-fs-read=/folder1/ --allow-fs-read=/folder2/ app.js
c. Granting process and worker access
Child processes and worker threads are restricted by default. The --allow-child-process and --allow-worker flags open them.
The allow-child-process flag
node --permission --allow-child-process app.js
Without the flag, child_process.spawn throws ERR_ACCESS_DENIED with the permission ChildProcess .
The fork inheritance
A child process created with child_process.fork() inherits the permission model flags from the parent. If the parent has --allow-child-process, the forked child receives the same flags .
The spawn propagation
child_process.spawn() propagates the flags through the NODE_OPTIONS environment variable. The child receives the same permission model configuration .
The allow-worker flag
node --permission --allow-worker app.js
Without the flag, new Worker() throws ERR_ACCESS_DENIED with the permission Worker .
The worker inheritance limitation
The permission model does not inherit to worker threads. A worker created with --allow-worker operates with full permissions, and the model’s restrictions do not apply inside the worker .
The native addon flag
node --permission --allow-addons app.js
Without the flag, loading a native addon throws an error. The flag is required for any package that ships a .node binary .
The WASI flag
node --permission --allow-wasi app.js
WASI modules are restricted by default. The --allow-wasi flag opens them .
Complete Example Session
# ============================================
# PART 1: THE DEFAULT DENY
# ============================================
node --permission index.js
# Error: Access to this API has been restricted
# code: 'ERR_ACCESS_DENIED'
# permission: 'FileSystemRead'
# ============================================
# PART 2: GRANTING READ ACCESS
# ============================================
node --permission --allow-fs-read=/app/src index.js
# ============================================
# PART 3: GRANTING WRITE ACCESS
# ============================================
node --permission \
--allow-fs-read=/app/src \
--allow-fs-write=/app/uploads \
--allow-fs-write=/tmp/ \
index.js
# ============================================
# PART 4: THE WILDCARD
# ============================================
node --permission --allow-fs-read="/app/data/*" index.js
# ============================================
# PART 5: THE CHILD PROCESS
# ============================================
node --permission --allow-child-process index.js
# ============================================
# PART 6: THE WORKER THREAD
# ============================================
node --permission --allow-worker index.js
# ============================================
# PART 7: THE NATIVE ADDON
# ============================================
node --permission --allow-addons index.js
# ============================================
# PART 8: THE RUNTIME CHECK
# ============================================
# index.js
console.log(process.permission.has('fs.read')); // true
console.log(process.permission.has('fs.write')); // false
console.log(process.permission.has('fs.write', '/tmp/')); // true
# ============================================
# PART 9: THE COMBINED FLAGS
# ============================================
node --permission \
--allow-fs-read=/app \
--allow-fs-write=/app/uploads \
--allow-child-process \
--allow-worker \
--allow-addons \
app.js
# ============================================
# PART 10: THE INSTALL SCRIPT PROTECTION
# ============================================
# Run npm install with restricted permissions
node --permission \
--allow-fs-read=/project/node_modules \
--allow-fs-write=/project/node_modules \
$(which npm) install
The ten parts showed the default deny, read access, write access, the wildcard, the child process, the worker thread, the native addon, the runtime check, the combined flags, and the install script protection.
Quick Reference
The Permission Flags
| Flag | Grants |
|---|---|
--permission | Enables the model (default deny) |
--allow-fs-read | Filesystem read access |
--allow-fs-write | Filesystem write access |
--allow-child-process | Child process spawning |
--allow-worker | Worker thread creation |
--allow-addons | Native addon loading |
--allow-wasi | WASI module execution |
The Default-Restricted Capabilities
| Capability | Default | Flag to Allow |
|---|---|---|
| File system read | Denied | --allow-fs-read |
| File system write | Denied | --allow-fs-write |
| Child processes | Denied | --allow-child-process |
| Worker threads | Denied | --allow-worker |
| Native addons | Denied | --allow-addons |
| WASI | Denied | --allow-wasi |
| Inspector | Denied | No flag |
| Network | Restricted | --allow-net |
The Runtime API
| Call | Returns |
|---|---|
process.permission.has('fs.read') | boolean |
process.permission.has('fs.write') | boolean |
process.permission.has('fs.read', path) | boolean |
process.permission.has('fs.write', path) | boolean |
The Constraints
| Constraint | Detail |
|---|---|
| Not a sandbox | Does not protect against malicious code |
| No worker inheritance | Workers run with full permissions |
| No network scoping | Network access is not yet granular |
| Symbolic links | Followed even outside granted paths |
| OpenSSL engines | Cannot be requested at runtime |
| File descriptors | Existing FDs bypass the model |
Best Practices
✅ Do This:
# Start with no permissions and add only what is needed.
node --permission --allow-fs-read=/app/src app.js # ✅
# Use absolute paths for the grants.
--allow-fs-read=/app/src # ✅
# Use multiple flags for multiple paths.
--allow-fs-read=/folder1/ --allow-fs-read=/folder2/ # ✅
# Scope write access tightly.
--allow-fs-write=/app/uploads # ✅
# Check permissions at runtime.
process.permission.has('fs.read', path) # ✅
# Use it for install scripts and untrusted code.
node --permission --allow-fs-read=/node_modules --allow-fs-write=/node_modules npm install # ✅
❌ Don’t Do This:
# Don't treat it as a sandbox.
# It does not protect against malicious code. # ❌
# Don't grant all permissions by default.
--allow-fs-read=* --allow-fs-write=* # ❌ Defeats the purpose
# Don't use comma-separated paths.
--allow-fs-read=/folder1/,/folder2/ # ❌ Deprecated
# Don't assume workers inherit permissions.
# Workers run with full permissions. # ❌
# Don't rely on it for network isolation.
# Network scoping is not yet granular. # ❌
# Don't forget the native addon flag.
# Native packages fail without --allow-addons. # ❌
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Entry point denied | No read access | The entry point is auto-granted |
| Directory not granted | Wildcard not added | Add /* explicitly |
| Native addon fails | No --allow-addons | Add the flag |
| Worker runs unrestricted | No inheritance | Accept the limitation |
| Symbolic link bypass | Followed outside path | Audit granted paths |
| File descriptor bypass | Existing FDs | Do not use pre-opened FDs |
| Comma paths ignored | Deprecated syntax | Use multiple flags |
| Network not restricted | No granular scoping | Use OS-level controls |
Real-World Examples
1. Basic Permission Model
node --permission index.js
2. Read Access
node --permission --allow-fs-read=/app/src index.js
3. Write Access
node --permission --allow-fs-write=/tmp/ index.js
4. Child Process
node --permission --allow-child-process index.js
5. Worker Thread
node --permission --allow-worker index.js
6. Native Addon
node --permission --allow-addons index.js
7. Runtime Check
process.permission.has('fs.read', '/app/data')
8. Combined Flags
node --permission --allow-fs-read=/app --allow-fs-write=/app/uploads --allow-child-process app.js
9. Install Script Protection
node --permission --allow-fs-read=/node_modules --allow-fs-write=/node_modules npm install
10. The Wildcard
node --permission --allow-fs-read="/app/data/*" index.js
Visual
The Default-Deny Model
┌────────────────────────────────────────────────────────────┐
│ THE DEFAULT-DENY MODEL │
│ │
│ node --permission index.js │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ PROCESS STARTS WITH: │ │
│ │ File system read: DENIED │ │
│ │ File system write: DENIED │ │
│ │ Child processes: DENIED │ │
│ │ Worker threads: DENIED │ │
│ │ Native addons: DENIED │ │
│ │ WASI: DENIED │ │
│ │ Inspector: DENIED │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ │ Explicit grants │
│ v │
│ ┌──────────────────────────────────────────────────┐ │
│ │ --allow-fs-read=/app/src │ │
│ │ --allow-fs-write=/tmp/ │ │
│ │ │ │
│ │ Each grant opens one capability. │ │
│ └──────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
The Supply-Chain Protection
┌────────────────────────────────────────────────────────────┐
│ SUPPLY-CHAIN PROTECTION │
│ │
│ WITHOUT --permission │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Malicious postinstall script: │ │
│ │ 1. Reads ~/.aws/credentials │ │
│ │ 2. Reads .env │ │
│ │ 3. Spawns curl to exfiltrate │ │
│ │ │ │
│ │ All three succeed. │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ WITH --permission │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Malicious postinstall script: │ │
│ │ 1. Reads ~/.aws/credentials │ │
│ │ → ERR_ACCESS_DENIED (FileSystemRead) │ │
│ │ 2. Reads .env │ │
│ │ → ERR_ACCESS_DENIED (FileSystemRead) │ │
│ │ 3. Spawns curl │ │
│ │ → ERR_ACCESS_DENIED (ChildProcess) │ │
│ │ │ │
│ │ All three fail. │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ The blast radius is reduced. │
└────────────────────────────────────────────────────────────┘
The Worker Inheritance
┌────────────────────────────────────────────────────────────┐
│ WORKER INHERITANCE │
│ │
│ MAIN THREAD │
│ ┌──────────────────────────────────────────────────┐ │
│ │ node --permission --allow-worker app.js │ │
│ │ │ │
│ │ File system read: DENIED │ │
│ │ File system write: DENIED │ │
│ │ Child processes: DENIED │ │
│ │ Worker threads: ALLOWED │ │
│ └────────────────────────┬─────────────────────────┘ │
│ │ │
│ │ new Worker() │
│ v │
│ WORKER THREAD │
│ ┌──────────────────────────────────────────────────┐ │
│ │ File system read: ALLOWED (no inheritance) │ │
│ │ File system write: ALLOWED │ │
│ │ Child processes: ALLOWED │ │
│ │ Worker threads: ALLOWED │ │
│ │ │ │
│ │ The model does not inherit to the worker. │ │
│ └──────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
The Comparison
┌────────────────────────────────────────────────────────────┐
│ NODE.JS vs DENO │
│ │
│ NODE.JS --permission │
│ ┌──────────────────────────────────────────────────┐ │
│ │ File system read: Granular (paths) │ │
│ │ File system write: Granular (paths) │ │
│ │ Child processes: Yes/No │ │
│ │ Worker threads: Yes/No │ │
│ │ Network: Restricted (not granular) │ │
│ │ Environment: Not restricted │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ DENO │
│ ┌──────────────────────────────────────────────────┐ │
│ │ File system read: Granular (paths) │ │
│ │ File system write: Granular (paths) │ │
│ │ Child processes: Yes/No │ │
│ │ Worker threads: Yes/No │ │
│ │ Network: Granular (hosts, ports) │ │
│ │ Environment: Granular (variables) │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ Deno is more granular. Node is catching up. │
└────────────────────────────────────────────────────────────┘
Summary
| Item | Value |
|---|---|
--permission | Enables the permission model |
--allow-fs-read | Grants filesystem read |
--allow-fs-write | Grants filesystem write |
--allow-child-process | Grants child process spawning |
--allow-worker | Grants worker thread creation |
--allow-addons | Grants native addon loading |
--allow-wasi | Grants WASI module execution |
process.permission.has | Runtime permission check |
ERR_ACCESS_DENIED | The error thrown on denial |
| Stability | Stable in Node.js 23.5.0 |
Key takeaways:
- The permission model inverts the default to deny. When
--permissionis enabled, the process starts with no filesystem access, no child processes, no workers, no native addons, no WASI, and no inspector. Every capability must be granted explicitly . - It is a seat belt, not a sandbox. Node.js documentation states explicitly that the model does not protect against malicious code. It prevents trusted code from accidentally touching resources it should not touch, and it raises the cost of a supply-chain attack, but it is not an isolation mechanism .
- Filesystem access is scoped by path. The
--allow-fs-readand--allow-fs-writeflags accept absolute paths, relative paths, and wildcards. The model checks the path of every filesystem operation against the granted list . - Child processes and workers are separate capabilities. A script that needs to run a subprocess must be started with
--allow-child-process. A script that needs to create a worker must be started with--allow-worker. Without the flag, the operation throwsERR_ACCESS_DENIED. - The model does not inherit to worker threads. A worker created under
--permissionruns with full permissions. This is a documented limitation, and it means the model’s protection does not extend inside workers . - The entry point is auto-granted read access. The script that Node.js is asked to run is automatically added to the read list. Preloaded modules are also included .
- The
process.permissionAPI enables runtime checks. Thehasmethod returns a boolean and is used by libraries that want to degrade gracefully when a capability is denied . - The model is most valuable for install scripts and untrusted code. Running
npm installunder--permissionwith restricted filesystem access limits what a malicious postinstall script can do. It is a defense-in-depth layer, not a replacement for OS-level controls like containers or a non-root user .
Remember: The Node.js permission model is the runtime’s answer to the ambient-authority problem. It starts the process with nothing and requires the operator to grant only what the application needs. It covers filesystem reads and writes, child processes, workers, native addons, WASI, and the inspector. It is stable as of Node.js 23.5.0. It is a seat belt, not a sandbox: it prevents accidents and raises the cost of an attack, but it does not stop malicious code that has found a way to run. The result is a runtime where a compromised dependency cannot silently read your credentials or spawn a shell, and a deployment where the blast radius of a supply-chain attack is smaller than it was before.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!