LogoفارسیFA

Permissions in Node.js

The Node.js Permission Model provides a mechanism to restrict process access to system resources. It acts as a "seat belt," preventing trusted code from unintentionally modifying files or using resources without explicit permission. However, it does not guarantee protection against malicious code, which can bypass restrictions. Developers can configure permissions at startup or check them at runtime.

--permission flagprocess.permission.has()--allow-fs-read / --allow-fs-write--allow-net / --allow-worker / --allow-addons / --allow-wasi

~2 min read • Updated Dec 30, 2025

1. Introduction


By starting Node.js with the --permission flag, access to resources such as the file system, network, child processes, worker threads, native addons, WASI, and the inspector is restricted.


$ node --permission index.js
Error: Access to this API has been restricted

2. Runtime API


When the Permission Model is enabled, the process.permission property is available with the has() method to check permissions:


process.permission.has('fs.write'); // true
process.permission.has('fs.read', '/home/protected'); // false

3. File System Permissions


By default, file system access is restricted. To allow read or write operations, use:


  • --allow-fs-read=*: Allow all read operations.
  • --allow-fs-write=/tmp/: Allow write access to /tmp.
  • Supports wildcards: --allow-fs-read=/home/test*.

4. Using with npx


Enable the Permission Model when running scripts via npx using --node-options:


npx --node-options="--permission" package-name

To avoid FileSystemRead errors, grant read access to global node_modules or npm cache directories.


5. Permission Model Constraints


  • Permissions do not inherit to worker threads.
  • Restricted features include native modules, network, child processes, file system, WASI, and inspector.
  • Certain flags like --env-file or --openssl-config bypass the model since they run before initialization.
  • Existing file descriptors can bypass restrictions.

6. Limitations and Known Issues


  • Symbolic links are followed even outside allowed paths.
  • Relative symlinks may grant access to arbitrary files and directories.

Conclusion


The Node.js Permission Model is a useful tool for controlling resource access at runtime. While it prevents unintended actions, it does not fully protect against malicious code. Developers must carefully configure allowed paths and be aware of constraints and known issues.


Written & researched by Dr. Shahin Siami

Next Article