rules/propagation-and-config.md
GitHubInheritance, --allow-env, config files, npx
Child processes and workers
- With
--allow-child-process, a spawnednodechild runs under the same model. The flags arrive viaNODE_OPTIONSforspawn(v24.4.0, v22.18.0) or viaexecArgvforfork. ObservedNODE_OPTIONSin the child:--permission --allow-fs-read=* --allow-child-process. On main,--allow-env=*is appended, and the child inherits only the variables the parent kept. - Non-Node children (shell, other binaries) are not restricted at all. That is
why
--allow-child-process"could invalidate the permission model". - A
Workerwith noexecArgvinherits the parent flags. Any explicitexecArgv, including[], replaces them, and the worker runs without the model (process.permissionisundefined). This is intended. Repeat the flags inexecArgvif you set it. process._debugProcess(pid)is not gated: a sandboxed process can make another same-user Node.js process open its inspector. Isolate with OS users.
--allow-env (v27.0.0; not on v24/v26)
Variables are removed at startup instead of being checked on each access. They
are gone from process.env, getenv() in native code, reports, workers and
children.
- Values:
*,NAME,PREFIX*. Repeat the flag or separate with commas:--allow-env=PORT,APP_*. Names are case-insensitive on Windows. - Always kept: the variables Node and its deps read (
NODE_OPTIONS,PATH,HOME,TMPDIR,TZ,LANG,SSL_CERT_FILE,NODE_EXTRA_CA_CERTS, color detection vars), plus vars from--env-file. - Not kept:
NODE_ENV, otherNODE_*(such asNODE_AUTH_TOKEN),HTTP_PROXY/HTTPS_PROXY/NO_PROXY(grant them for--use-env-proxy), and vars that third-party OpenSSL modules need (such asSOFTHSM2_CONF). - A read of a removed var returns
undefinedand warns once:Warning: The permission model removed the environment variable "X" at startup. Use --allow-env to manage permissions.Variables set at runtime are not restricted. - On Linux, reading another process's
/proc/<pid>/environis denied regardless of--allow-fs-read. Reading your own needs--allow-env=*. - Any
--allow-*flag without--permission(or--permission-audit) is a startup error:TypeError [ERR_MISSING_OPTION]: --permission is required(verified with--allow-fs-readon all three binaries,--allow-envon main).
Config file (permission namespace)
{ "permission": { "allow-fs-read": ["./data"], "allow-net": true, "allow-child-process": false } }
| Binary | Flag name | Namespace alone enables --permission |
|---|---|---|
| v24.19.0 | --experimental-config-file=f (--config-file is a bad option) |
no: fails with ERR_MISSING_OPTION: --permission is required. Pass --permission too, or set "nodeOptions": { "permission": true } |
| v26.13.0, main | --config-file[=f] (v26.12.0+; the experimental names remain aliases) |
yes |
- Keys are flag names without
--. Path grants are arrays; boolean grants aretrue/false. - When the command line or
NODE_OPTIONSenables the model,allow-envin a config file or--env-filecan only narrow--allow-env. Example: with--permission --allow-env=APP_*plus"allow-env": ["*"], onlyAPP_*vars remain (verified on main). permissionis not valid inside thepermissionnamespace (Unknown or not allowed option).
npx
npx --node-options="--permission --allow-fs-read=$(npm config get cache)" pkg
npm needs read access to its cache, or to $(npm prefix -g) for global
installs. Without it, you get a FileSystemRead error. (Not exercised by the
examples.)