Node.js Permission Model

The Node.js Permission Model restricts which system resources a process can access. It is useful as a safety mechanism for trusted applications that should not accidentally read files, write files, spawn processes, or use other sensitive capabilities.

The permission model limits accidental resource access by trusted code. It is not a security sandbox for running malicious programs.

The permission model is stable in Node.js 22.13 and later. The examples below run from the project root.

Enable Permission Enforcement

Example:

node --permission app.js

Supported protected capabilities are denied unless granted. This does not imply that every possible resource, including network access in every release, is sandboxed.

Allow File Reads

Example:

node --permission --allow-fs-read=./config app.js

This permits reads from the specified path while other file reads remain restricted.

Allow File Writes

Example:

node --permission --allow-fs-write=./output app.js

Read and write permissions are separate, so you can allow one without automatically allowing the other.

Permission Errors

If code attempts an operation that is not allowed, Node.js throws an error such as ERR_ACCESS_DENIED.

Example:

const fs = require('node:fs');

try {
  const text = fs.readFileSync('/private/data.txt', 'utf8');
  console.log(text);
} catch (error) {
  console.error(error.code);
}

Check Permissions in Code

Applications can inspect permissions through the process permission API.

Example:

if (process.permission.has('fs.read', './config/settings.json')) {
  console.log('Read access is available');
}

This can help an application choose a fallback instead of waiting for an operation to fail.

Audit Mode

Audit mode was added in Node.js 24.20 and 25.8. It publishes permission-violation events through node:diagnostics_channel without denying operations. A diagnostics subscriber must collect those events; this flag alone is not a human-readable violation report. It is unavailable in older Node.js 22 runtimes.

Example:

node --permission-audit app.js

Common Resource Controls

Practical Use

A build script may only need read access to source files and write access to a build directory. A report generator may need read access to one data folder and no permission to launch subprocesses. Restricting the process to those capabilities reduces accidental damage.

Conclusion

The Node.js Permission Model lets you explicitly grant the resources an application needs. Start by enabling permissions in audit or enforcement mode, then allow only the file paths and capabilities required by the program.