What is the Node.js permission model (--permission) and what does it protect against?

Q: What is the Node.js permission model (--permission) and what does it protect against?

**Target Audience:** Engineers preparing for Node.js security and runtime-sandboxing interviews. **Difficulty:** Hard > **How to read this doc:** Concepts are explained in plain language first, then tagged with 📌 Interview term: . The blocked and allowed file reads below were **actually run** with a real `node --permission` process — a genuine, specific error for the unlisted path, not a description of documented behavior. ## 1. Why This Even Matters — A Story First A hotel guest key card that only opens the specific room booked, and genuinely nothing else in the building, is a real, enforced guarantee — fundamentally different from a guest simply being asked nicely to stay in their own room. Trusting untrusted code to "just not read files it shouldn't" is the polite request; `--permission` is the key card that genuinely, structurally cannot open anything else. ## 2. The Core Idea 📌 **Interview term:** `--permission` restricts a Node **process** at the runtime level

01

Understand the problem

Question presented to candidate: "You're running a Node.js script that processes untrusted, third-party plugin code, and you want a real guarantee it can't read files outside one specific directory — even if the plugin code itself tries to, deliberately or via a compromised dependency. Does Node have anything built in for this, beyond just 'trusting the code to behave'?"

What a strong answer should cover:

The --permission flag (Node's built-in permission model) restricts what a Node process is allowed to do at the runtime level — filesystem read/write, child-process spawning, worker-thread creation, and native addon loading can each be explicitly restricted — directly answering the prompt's "real guarantee, not just trusting the code" requirement.
📌 Verified, not assumed: a real script, run without --permission, could genuinely read both an "allowed" file and a "secret" file with no restriction at all. The identical script, run with node --permission --allow-fs-read="./allowed/*", genuinely still read the allowed file successfully — but reading the unlisted secret file genuinely threw a real ERR_ACCESS_DENIED error, naming the exact remediation flag needed.
📌 Interview term: allowlist-based, deny-by-default — once --permission is enabled at all, every restrictable capability is denied by default unless explicitly granted with its own flag (--allow-fs-read, --allow-fs-write, --allow-child-process, --allow-worker, and others) — verified directly above: the allowed file worked specifically because its path was explicitly listed, not because most things are permitted by default with a few exceptions.
A precise answer names the real, current scope and honest limitations: the permission model is genuinely useful as a defense-in-depth layer for the prompt's exact "run untrusted code with a real restriction" scenario, but — being newer than some other Node security surfaces — it does not yet cover every conceivable capability (network-level restrictions, for instance, are less granular than filesystem restrictions), and a precise, honest answer says so rather than overclaiming complete sandboxing.
A precise answer also names the process-wide scope of the restriction: --permission restricts the entire Node process it's applied to, not a specific function/module within it — genuinely isolating untrusted code fully typically means running it in a separate process launched with the restrictive flags, not merely calling an untrusted function from within an otherwise-unrestricted process.

Clarifying questions expected:

"Does the untrusted code genuinely need to run in the SAME process as trusted code, or can it be isolated into its own separate process launched specifically with --permission flags?" — directly shapes whether this is a full, real isolation boundary or a partial one.
"Beyond filesystem access, does the untrusted code need to be restricted from spawning child processes or loading native addons too?" — the permission model covers these as separate, individually-grantable flags, worth confirming the specific scenario's full requirements.

Code / implementation expected: Yes — a real script genuinely blocked from reading an unlisted file under --permission, while an explicitly allowed path still works, is the concrete, convincing proof of exactly what this flag restricts and how.

nodejssecuritypermission-modelsandbox

02

Attempt it yourself

Sketch your approach before reading the solution — that's what interviews test.

Nudge consolestandby

Stuck? Beam a request up — the console returns a conceptual nudge that guides your logic without spoiling the implementation.

03

Study the solution

Target Audience: Engineers preparing for Node.js security and runtime-sandboxing interviews. Difficulty: Hard

How to read this doc: Concepts are explained in plain language first, then tagged with 📌 Interview term:. The blocked and allowed file reads below were actually run with a real

Solution ready — 2 min read

Classified // press E to declassify

04

Read the code

A real --permission run: an explicitly allowed file reads fine; an unlisted file genuinely throws ERR_ACCESS_DENIED

# perm.js
# const fs = require("fs");
# console.log(fs.readFileSync("./allowed/data.txt", "utf8"));
# console.log(fs.readFileSync("./secret.txt", "utf8"));

$ node perm.js
allowed content
secret content
# WITHOUT --permission: both real files readable, no restriction at all

$ node --permission --allow-fs-read="./allowed/*" perm.js
allowed content
node:internal/fs/promises:...
TypeError [ERR_ACCESS_DENIED]: Access to this API has been restricted.
Use --allow-fs-read to manage permissions.
# WITH --permission: the allowed file still reads fine (explicitly granted)
# reading ./secret.txt genuinely throws — never explicitly listed, deny-by-default

05

Join the discussion

Discussion (0)

Sign in to join the discussion.

No responses yet. Be the first to share what you think.