The Node.js Permission Model

The release of Node.js 20 includes a new Permission Model. Why is this important? It allows developers to restrict Node.js scripts from accessing the filesystem, child processes, and worker threads.

Table of Contents

• Getting Started
• Permissions
  • --allow-fs-read
  • --allow-fs-write
  • --allow-child-process
  • --allow-worker
  • --allow-addons
• Checking for Filesystem Permissions
• Checking Permissions for Child Processes and Worker Threads
• Conclusion
• Further Reading

Getting Started

To use the new Permission model you will need to download version 20 from nodejs.org or your favorite Node.js version manager. (Check out Volta!)

Enable the experimental Permission Model by passing the --experimental-permission flag to the node command. For example: node --experimental-permission some-script.js.

Permissions

By itself, --experimental-permission will lock down the process and prevent access to the filesystem, child processes, and worker threads. Use this flag in conjunction with the following flags to granularly enable permissions on a per-process basis.

--allow-fs-read

This flag allows access to read from the filesystem (not write). To allow full read access, use: --allow-fs-read=*. Or pass a comma-separated list of paths to limit access: --allow-fs-read=/some/path,/some/other/file.json.

--allow-fs-write

This flag allows access to write to the filesystem (not read). To allow full write access, use: --allow-fs-write=*. Or pass a comma-separated list of paths to limit access: --allow-fs-write=/some/path,/some/other/file.json.

--allow-child-process

This flag allows access to running child processes. Currently, there is no way to restrict while child processes can be spawned. This means that a script could use a child process to gain write access to the system without specifically allowing it via --allow-fs-write.

--allow-worker

This flag allows worker threads to be spawned. The worker thread will retain the same permissions as the process that spawned it.

--allow-addons

This flag allows native addons to be used. This is available in Node.js version 21.6.0.

Checking for Filesystem Permissions

Now that you can restrict permissions to a given script. How does the script see if it has the necessary permissions to proceed?

To check permissions, a script can use process.permission.has(). This new function returns true or false if the given process has permission to the provided scope. The scope can be either fs, fs.read, or fs.write for filesystem access, read access, and write access respectively.

The second, optional, argument to process.permission.has() is a path to test for access. For example, to check for write access to a certain path, use: process.permission.has('fs.write', '/some/path').

Checking Permissions for Child Processes and Worker Threads

The process.permission.has() function will only tell you if the script has file system access. The only way to check for child process and worker thread access is to handle the ERR_ACCESS_DENIED error that gets thrown if permission is denied.

Conclusion

It is important to note that the permission model is experimental in Node.js version 20. And also, at this time Node.js 20 is not the supported LTS. So the Permission Model may be subject to change in the future. That being said, it is exciting to see where Node.js will be in the coming releases!

Further Reading

• Permission Model docs
• Node.js version 20 release announcement
• process.permission.has() docs