src,lib: add --allow-env permission

Necessarily semver-major.

When `--permission` is on, every env var not matched by
`--allow-env` is removed at startup. It takes names,
patterns (`PREFI_*`), or `*`, repeatable or comma-sep'd.

There are a range of env vars that Node.js itself uses,
and a default range that are generally known to be safe
in common usage. These are never scrubbed. These include
things like `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `PATH`,
`HOME`, etc.

Env vars can be dropped at runtime after reading using
`permission.drop()`. This is a stronger protection than
using `process.env.FOO = undefined` because it will
scrub the env var also from the environment block.

On Linux, the removed entries are overwritten in the
initial environment block and fs reads of /proc/*/environ
are denied.

On Windows, removal also clears the C runtime's copy
of the environ using _wputenv_s

Reading a removed name returns undefined, warns once per
name, and publishes to a diagnostics channel.

Env file keys are allowed. If the user had reason to pass
in an env file the assumption is they meant to allow them.

File-source config (node.config.json and NODE_OPTIONS
from a .env file can only narrow the allow list.

Embedders must call ScrubProcessEnvironment() themselves
on startup. This is left up to the embedder to determine
the exact timing but needs to be called before startup
actually happens.

Child processes are started with `--allow-env=*`. Those
either receive the explicit env they were started with
or only the env they inherit from the parent. Since the
parent process is scrubbed, it should never be more than
what the parent can see.

Main part of the impl was done by hand. Docs, tests,
verification pass, and cleanup nits were automated.

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode

Author: jasnell

doc/api/cli.md

@@ -191,6 +191,50 @@ This behavior also applies to `child_process.spawn()`, but in that case, the
 flags are propagated via the `NODE_OPTIONS` environment variable rather than
 directly through the process arguments.
 
+### `--allow-env`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active development
+
+When using the [Permission Model][], the process starts without the environment
+variables it has not been granted access to. At startup, every variable that
+`--allow-env` does not match is removed from the process environment. Removed
+variables are absent from `process.env`, from diagnostic reports, from native
+code calling `getenv()`, and from the environment of child processes and worker
+threads.
+
+The valid values are:
+
+* `*` - Grants access to every environment variable.
+* A variable name, for example `--allow-env=DATABASE_URL`.
+* A variable name prefix followed by `*`, for example `--allow-env=APP_*`.
+
+Multiple values can be passed by repeating the flag, or by separating them with
+commas: `--allow-env=PORT,APP_*`. Variable names are case-insensitive on
+Windows.
+
+Example:
+
+```js
+console.log(process.env.DATABASE_URL);
+console.log(process.env.AWS_SECRET_ACCESS_KEY);
+```
+
+```console
+$ node --permission --allow-fs-read=* --allow-env=DATABASE_URL index.js
+postgres://localhost/app
+undefined
+(node:1234) Warning: The permission model removed the environment variable "AWS_SECRET_ACCESS_KEY" at startup. Use --allow-env to manage permissions.
+```
+
+The variables that Node.js and its bundled dependencies read, such as
+`NODE_OPTIONS`, `PATH`, `HOME`, `TZ`, and `SSL_CERT_FILE`, are always kept, as
+are the variables defined in [`--env-file`][] files. See
+[Environment variable permissions][] for details.
+
 ### `--allow-ffi`
 
 <!-- YAML
@@ -2538,6 +2582,7 @@ following permissions are restricted:
 * File System - manageable through
   [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Network - manageable through [`--allow-net`][] flag
+* Environment variables - manageable through [`--allow-env`][] flag
 * Child Process - manageable through [`--allow-child-process`][] flag
 * Worker Threads - manageable through [`--allow-worker`][] flag
 * WASI - manageable through [`--allow-wasi`][] flag
@@ -4128,6 +4173,7 @@ one is included in the list below.
 
 * `--allow-addons`
 * `--allow-child-process`
+* `--allow-env`
 * `--allow-ffi`
 * `--allow-fs-read`
 * `--allow-fs-vfs`
@@ -4776,6 +4822,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [CommonJS module]: modules.md
 [DEP0025 warning]: deprecations.md#dep0025-requirenodesys
 [ECMAScript module]: esm.md#modules-ecmascript-modules
+[Environment variable permissions]: permissions.md#environment-variable-permissions
 [EventSource Web API]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events
 [ExperimentalWarning: `vm.measureMemory` is an experimental feature]: vm.md#vmmeasurememoryoptions
 [FIPS mode]: crypto.md#fips-mode
@@ -4799,6 +4846,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`'crypto.fips.indicator'`]: diagnostics_channel.md#event-cryptofipsindicator
 [`--allow-addons`]: #--allow-addons
 [`--allow-child-process`]: #--allow-child-process
+[`--allow-env`]: #--allow-env
 [`--allow-fs-read`]: #--allow-fs-read
 [`--allow-fs-write`]: #--allow-fs-write
 [`--allow-net`]: #--allow-net

doc/api/embedding.md

@@ -72,6 +72,51 @@ int main(int argc, char** argv) {
 }
 ```
 
+### Restricting access to environment variables
+
+<!-- YAML
+added: REPLACEME
+-->
+
+When the arguments passed to `node::InitializeOncePerProcess()` enable the
+[Permission Model][] without `--allow-env=*`, the process environment must not
+contain any variable that [`--allow-env`][] does not grant access to.
+`node::InitializeOncePerProcess()` fails otherwise. Unlike the `node`
+executable, embedders own the process environment, so Node.js does not remove
+these variables itself.
+
+`node::ScrubProcessEnvironment()` removes them. Because it modifies the process
+environment without any locking that native code calling `getenv()`
+participates in, it must be called before starting any thread that may read the
+environment, and before `node::InitializeOncePerProcess()`:
+
+```cpp
+int main(int argc, char** argv) {
+  argv = uv_setup_args(argc, argv);
+  std::vector<std::string> args(argv, argv + argc);
+
+  // Keep the variables the embedder itself reads, in addition to the ones
+  // Node.js reads (see node::GetRuntimeEnvironmentDefaults()).
+  node::ProcessEnvironmentScrubOptions scrub_options;
+  scrub_options.allow = {"PORT", "APP_*"};
+  if (node::ScrubProcessEnvironment(scrub_options).IsNothing()) {
+    return 1;
+  }
+
+  // args contains, for example, --permission --allow-env=PORT
+  std::unique_ptr<node::InitializationResult> result =
+      node::InitializeOncePerProcess(args, {
+        node::ProcessInitializationFlags::kNoInitializeV8,
+        node::ProcessInitializationFlags::kNoInitializeNodeV8Platform
+      });
+  // ...
+}
+```
+
+`process.permission.drop('env', name)` removes a variable from the process
+environment, so it throws when called from a `node::Environment` created
+without `node::EnvironmentFlags::kOwnsProcessState`.
+
 ### Setting up a per-instance state
 
 <!-- YAML
@@ -178,6 +223,8 @@ int RunNodeInstance(MultiIsolatePlatform* platform,
 ```
 
 [CLI options]: cli.md
+[Permission Model]: permissions.md#permission-model
+[`--allow-env`]: cli.md#--allow-env
 [`process.memoryUsage()`]: process.md#processmemoryusage
 [deprecation policy]: deprecations.md
 [embedtest.cc]: https://github.com/nodejs/node/blob/HEAD/test/embedding/embedtest.cc

doc/api/permissions.md

@@ -61,9 +61,9 @@ The Permission Model has two operational modes:
 
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, access the network,
-spawn processes, use `node:worker_threads`, use native addons, use WASI, use
-FFI, and enable the runtime inspector will be restricted (the listener for
-SIGUSR1 won't be created).
+access environment variables, spawn processes, use `node:worker_threads`, use
+native addons, use WASI, use FFI, and enable the runtime inspector will be
+restricted (the listener for SIGUSR1 won't be created).
 
 ```console
 $ node --permission index.js
@@ -79,6 +79,8 @@ Error: Access to this API has been restricted
 Allowing access to spawning a process and creating worker threads can be done
 using the [`--allow-child-process`][] and [`--allow-worker`][] respectively.
 
+To grant access to environment variables, use [`--allow-env`][].
+
 To allow network access, use [`--allow-net`][] and for allowing native addons
 when using permission model, use the [`--allow-addons`][]
 flag. For WASI, use the [`--allow-wasi`][] flag. For FFI, use the
@@ -157,9 +159,9 @@ mode. Execution continues normally.
 Audit mode is useful for discovering what permissions your application
 requires before deploying with [`--permission`][]. It can also be combined
 with the [`--allow-fs-read`][], [`--allow-fs-write`][], [`--allow-net`][],
-[`--allow-child-process`][], [`--allow-worker`][], [`--allow-addons`][],
-[`--allow-wasi`][], and [`--allow-ffi`][] flags to audit a subset of
-permissions while granting others.
+[`--allow-env`][], [`--allow-child-process`][], [`--allow-worker`][],
+[`--allow-addons`][], [`--allow-wasi`][], and [`--allow-ffi`][] flags to audit
+a subset of permissions while granting others.
 
 When a permission check fails in audit mode, a message is published to the
 diagnostics channel corresponding to the denied scope. The channel names are:
@@ -172,6 +174,7 @@ diagnostics channel corresponding to the denied scope. The channel names are:
 * `node:permission-model:wasi` — WASI
 * `node:permission-model:addon` — Native Addons
 * `node:permission-model:ffi` — FFI
+* `node:permission-model:env` — Environment variables
 
 Each message is an object with the following properties:
 
@@ -266,6 +269,78 @@ both to the top-level `node:fs` functions and to the equivalent
 `FileHandle` methods, and currently includes `fsync`/`fdatasync`,
 `fchmod`, and `fchown` (and their synchronous variants).
 
+#### Environment variable permissions
+
+When the Permission Model is enforced, the process only has access to the
+environment variables that [`--allow-env`][] grants access to.
+
+Instead of checking each access, Node.js removes every other variable from the
+process environment at startup, before any JavaScript code runs and before
+Node.js starts any other thread. Removed variables are absent from everything
+that exposes the environment of the process: `process.env`, diagnostic reports,
+native code calling `getenv()`, worker threads, and the environment inherited by
+child processes.
+
+```console
+$ node --permission --allow-env=PORT --allow-env=APP_* index.js
+```
+
+The valid arguments for the flag are:
+
+* `*` - Grants access to every environment variable. Nothing is removed.
+* A variable name, such as `PORT`.
+* A variable name prefix followed by `*`, such as `APP_*`.
+
+Some variables are always kept:
+
+* The variables that Node.js and its bundled dependencies read after startup,
+  such as `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `PATH`, `HOME`, `TMPDIR`, `TZ`,
+  `LANG`, `SSL_CERT_FILE`, and the variables that terminal color detection
+  reads. Other variables whose names start with `NODE_`, such as
+  `NODE_AUTH_TOKEN`, are not kept.
+* The variables defined in the files passed to [`--env-file`][] and
+  [`--env-file-if-exists`][]. If a variable is defined in such a file and also
+  inherited from the parent process, and `--allow-env` does not grant access to
+  it, the inherited value is removed and the value from the file is used.
+
+Proxy URLs often contain credentials, so the `HTTP_PROXY`, `HTTPS_PROXY`, and
+`NO_PROXY` variables are not kept. Grant access to them explicitly when using
+[`--use-env-proxy`][].
+
+Reading a variable that was removed at startup returns `undefined`, emits a
+warning the first time, and publishes a message to the
+`node:permission-model:env` diagnostics channel.
+
+Variables set at runtime, for example with `process.env.KEY = 'value'` or
+[`process.loadEnvFile()`][], are not restricted, as they cannot reveal what was
+removed.
+
+Dropping a variable with [`permission.drop()`][] removes it from the
+environment. Dropping the whole `env` scope removes every variable except the
+ones Node.js reads itself. This makes it possible to read a secret during
+initialization, and then remove it:
+
+```js
+const databaseUrl = process.env.DATABASE_URL;
+process.permission.drop('env', 'DATABASE_URL');
+```
+
+When a process that enforces the Permission Model spawns a child process, the
+child is started with `--allow-env=*`: the environment it inherits only contains
+variables that the parent had access to.
+
+In audit mode, nothing is removed. Accesses to variables that `--allow-env`
+does not grant access to are published to the `node:permission-model:env`
+diagnostics channel instead.
+
+On Linux, `/proc/<pid>/environ` exposes the environment a process was started
+with. While access to environment variables is restricted, reading any
+`/proc/<pid>/environ` file is denied, regardless of [`--allow-fs-read`][], and
+the removed variables are overwritten in the initial environment block of the
+process. This does not affect the environment of other processes, such as the
+parent process. A process granted [`--allow-child-process`][] can read their
+environment through other programs.
+
 #### Configuration file support
 
 In addition to passing permission flags on the command line, they can also be
@@ -297,6 +372,20 @@ automatically enables the `--permission` flag. Run with:
 $ node --experimental-default-config-file app.js
 ```
 
+A configuration file, like the `NODE_OPTIONS` defined in an [`--env-file`][]
+file, may be controlled by the project being run rather than by whoever starts
+Node.js. When the command line or the `NODE_OPTIONS` environment variable
+enable the Permission Model, the `allow-env` values these files define can only
+narrow the access that [`--allow-env`][] grants, and never widen it:
+
+```console
+$ node --permission --allow-env=APP_* --experimental-config-file=node.config.json app.js
+```
+
+With `"allow-env": ["*"]` in `node.config.json`, only the variables starting with
+`APP_` are kept. With `"allow-env": ["APP_DATABASE_URL", "OTHER"]`, only
+`APP_DATABASE_URL` is.
+
 #### Using the Permission Model with `npx`
 
 If you're using [`npx`][] to execute a Node.js script, you can enable the
@@ -342,6 +431,7 @@ There are constraints you need to know before using this system:
 * When using the Permission Model the following features will be restricted:
   * Native modules
   * Network
+  * Environment variables
   * Child process
   * Worker Threads
   * Inspector protocol
@@ -404,15 +494,21 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md
 [`--allow-addons`]: cli.md#--allow-addons
 [`--allow-child-process`]: cli.md#--allow-child-process
+[`--allow-env`]: cli.md#--allow-env
 [`--allow-ffi`]: cli.md#--allow-ffi
 [`--allow-fs-read`]: cli.md#--allow-fs-read
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-net`]: cli.md#--allow-net
 [`--allow-openssl-store`]: cli.md#--allow-openssl-store
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--env-file-if-exists`]: cli.md#--env-file-if-existsfile
+[`--env-file`]: cli.md#--env-filefile
 [`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
+[`--use-env-proxy`]: cli.md#--use-env-proxy
 [`crypto.createPrivateKey()`]: crypto.md#cryptocreateprivatekeykey
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
+[`permission.drop()`]: process.md#processpermissiondropscope-reference
 [`permission.has()`]: process.md#processpermissionhasscope-reference
+[`process.loadEnvFile()`]: process.md#processloadenvfilepath

doc/api/process.md

@@ -3163,6 +3163,7 @@ The available scopes are:
 * `fs.read` - File System read operations
 * `fs.write` - File System write operations
 * `child` - Child process spawning operations
+* `env` - Environment variables
 * `openssl.store` - Loading keys through OpenSSL STORE loaders
 * `worker` - Worker thread spawning operation
 * `ffi` - Foreign function interface operations
@@ -3220,6 +3221,8 @@ The available scopes are the same as [`process.permission.has()`][]:
 * `fs.read` - File System read operations
 * `fs.write` - File System write operations
 * `child` - Child process spawning operations
+* `env` - Environment variables. Dropping a variable removes it from the
+  environment
 * `openssl.store` - Loading keys through OpenSSL STORE loaders
 * `worker` - Worker thread spawning operation
 * `net` - Network operations

doc/node.1

@@ -118,6 +118,41 @@ This behavior also applies to \fBchild_process.spawn()\fR, but in that case, the
 flags are propagated via the \fBNODE_OPTIONS\fR environment variable rather than
 directly through the process arguments.
 .
+.It Fl -allow-env
+When using the Permission Model, the process starts without the environment
+variables it has not been granted access to. At startup, every variable that
+\fB--allow-env\fR does not match is removed from the process environment. Removed
+variables are absent from \fBprocess.env\fR, from diagnostic reports, from native
+code calling \fBgetenv()\fR, and from the environment of child processes and worker
+threads.
+The valid values are:
+.Bl -bullet
+.It
+\fB*\fR - Grants access to every environment variable.
+.It
+A variable name, for example \fB--allow-env=DATABASE_URL\fR.
+.It
+A variable name prefix followed by \fB*\fR, for example \fB--allow-env=APP_*\fR.
+.El
+Multiple values can be passed by repeating the flag, or by separating them with
+commas: \fB--allow-env=PORT,APP_*\fR. Variable names are case-insensitive on
+Windows.
+Example:
+.Bd -literal
+console.log(process.env.DATABASE_URL);
+console.log(process.env.AWS_SECRET_ACCESS_KEY);
+.Ed
+.Bd -literal
+$ node --permission --allow-fs-read=* --allow-env=DATABASE_URL index.js
+postgres://localhost/app
+undefined
+(node:1234) Warning: The permission model removed the environment variable "AWS_SECRET_ACCESS_KEY" at startup. Use --allow-env to manage permissions.
+.Ed
+The variables that Node.js and its bundled dependencies read, such as
+\fBNODE_OPTIONS\fR, \fBPATH\fR, \fBHOME\fR, \fBTZ\fR, and \fBSSL_CERT_FILE\fR, are always kept, as
+are the variables defined in \fB--env-file\fR files. See
+Environment variable permissions for details.
+.
 .It Fl -allow-ffi
 When using the Permission Model, the process will not be able to use FFI
 APIs by default. Attempts to use FFI APIs will throw an \fBERR_ACCESS_DENIED\fR
@@ -1274,6 +1309,8 @@ File System - manageable through
 .It
 Network - manageable through \fB--allow-net\fR flag
 .It
+Environment variables - manageable through \fB--allow-env\fR flag
+.It
 Child Process - manageable through \fB--allow-child-process\fR flag
 .It
 Worker Threads - manageable through \fB--allow-worker\fR flag
@@ -2088,6 +2125,8 @@ one is included in the list below.
 .It
 \fB--allow-child-process\fR
 .It
+\fB--allow-env\fR
+.It
 \fB--allow-ffi\fR
 .It
 \fB--allow-fs-read\fR