src,lib: stabilize permission model

[RafaelGSS]

This PR upgrades the Permission Model from 1.1 (Active Development) to 2.0 (Stable).

I’ve been diving deep into the Permission Model since its release in Node.js 20.0.0, looking at its limitations and what’s been fixed so far. Most of the technical challenges have been addressed, except for how symlinks are handled. After a lot of research, it turns out this isn’t fixable due to how the Permission Model relies on file paths, making TOCTOU issues theoretically possible. This isn’t unique to Node.js though—even Deno’s permission system has similar behaviour (see this article).

Since the feature’s release, there’s been a shift in how we think about security in Node.js. We’ve leaned into a "Defense in Depth" approach—recognizing that no single feature will let you run untrusted code safely. Instead, these features are like seatbelts: they reduce risk significantly (let’s say 90% of cases, though that’s not a hard number) but won’t stop everything. This aligns with our threat model, and the Permission Model reflects that philosophy.

The only remaining "limitation" is symlink behaviour. Fixing this would require changing how the Permission Model works at a fundamental level. It’s not feasible because TOCTOU issues are always a possibility when operating on file paths. Importantly, this isn’t just a Node.js thing—other runtimes face the same challenge.

That said, symlinks aren’t a dealbreaker:

• The Permission Model blocks symlink creation by default.
• An attacker would need an exact map of existing symlinks in your system to do something harmful. That’s a very unlikely scenario.
• If you explicitly allow access to something like /proc/, you’re responsible for understanding what that includes. The docs already cover this.

I have been talking with @tniessen in private as he has been indirectly involved in this feature (by raising concerns or suggestions). Some questions that he raised, and that I expect some of you might raise here too, were:

• "Most importantly, is anyone actually using the permission model? What is the use case and what security expectations do these users have?"

As with any non-popular feature, it's hard to assess its usage in the ecosystem, but we have received some issues in the security-wg repository that could mean people are evaluating its usage:

• [Bug]：use pm2 and --experimental-permission, throw Error: Access to this API has been restricted security-wg#1330
• Is it possible to make a process.send cmd: "NODE_*" attack while under --experimental-pemission? security-wg#1156
• Can I use --experimental-permission in new worker_threads.Worder's execArgv? security-wg#1043 (same author of b)
• How to includes "," or "*" char self in --allow-fs-read? security-wg#1039 (same author of b)
• Permission Model - Roadmap security-wg#898 (comment)
• Segmentation fault when using inspector on experimental permission enabled process #53385
• Experimental permission wildcards seem to not be additive #50659
• Node should log denied path by permission restriction #49080
• There are more, but I don't think I should list all of them here.

I was also approached by many people on social media saying "thanks" for the feature and that they are looking forward to having it established. I also understand that testing a feature is different from using this feature in production.

• "Following up on that, what security guarantees does the permission model provide, if any? Do those security guarantees actually match the security expectations of the people that actively use the permission model today?"

The Permission Model is most useful in development environments or scenarios where you want extra guardrails, but it doesn’t replace the core rule: don’t run untrusted code in Node.js.

If you configure it correctly, it’ll block most unwanted filesystem access, but it’s not a magic bullet. It’s a tool that works well when used as intended, and it complements Node.js’ broader security posture.

---

cc: @nodejs/security-wg

[nodejs-github-bot]

Review requested:

• @nodejs/performance
• @nodejs/security-wg

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @RafaelGSS.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[codecov]

Codecov Report

Attention: Patch coverage is 90.00000% with 1 line in your changes missing coverage. Please review.

Project coverage is 88.53%. Comparing base (f184a0a) to head (ab96885).
Report is 20 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/process/pre_execution.js	66.66%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #56201   +/-   ##
=======================================
  Coverage   88.53%   88.53%           
=======================================
  Files         657      657           
  Lines      189858   189899   +41     
  Branches    36450    36464   +14     
=======================================
+ Hits       168089   168130   +41     
- Misses      14973    14977    +4     
+ Partials     6796     6792    -4     

Files with missing lines	Coverage Δ
lib/internal/process/permission.js	69.44% <100.00%> (ø)
src/env.cc	85.45% <100.00%> (ø)
src/node_options.cc	87.98% <100.00%> (+0.10%)	⬆️
src/node_options.h	98.29% <100.00%> (ø)
lib/internal/process/pre_execution.js	90.69% <66.66%> (+0.13%)	⬆️

... and 26 files with indirect coverage changes

[mertcanaltin]

lgtm

[targos]

You could add a flag alias so this is not semver-major.

[mcollina]

lgtm

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/63980/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/63988/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/64004/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/64016/

[nodejs-github-bot]

Landed in be04d06