doc: add documentation for --allow-env flag in CLI and permissions

Signed-off-by: nabeel378 <[email protected]>

Author: nabeel378

doc/api/cli.md

@@ -191,6 +191,45 @@ 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`
+
+> Stability: 1.1 - Active development
+
+When using the [Permission Model][], access to environment variables is
+restricted by default unless the user explicitly passes the `--allow-env`
+flag when starting Node.js.
+
+* Reading a restricted variable (`process.env.HOME`) silently returns
+  `undefined`.
+* Writing (`process.env.FOO = 'bar'`) or deleting (`delete process.env.FOO`)
+  a restricted variable throws `ERR_ACCESS_DENIED`.
+
+The valid arguments for the `--allow-env` flag are:
+
+* `*` - To allow access to all environment variables.
+* Specific environment variable names can be allowed using a comma-separated
+  list. Example: `--allow-env=HOME,PATH,NODE_ENV`
+
+Example:
+
+```js
+console.log(process.env.HOME); // undefined (silently denied)
+process.env.FOO = 'bar';       // ERR_ACCESS_DENIED (throws)
+```
+
+```console
+$ node --permission --allow-fs-read=* index.js
+node:internal/process/per_thread:12
+  throw new ERR_ACCESS_DENIED('EnvVar', name);
+  ^
+
+Error: Access to this API has been restricted
+    at node:internal/main/run_main_module:17:47 {
+  code: 'ERR_ACCESS_DENIED',
+  permission: 'EnvVar'
+}
+```
+
 ### `--allow-ffi`
 
 <!-- YAML
@@ -2224,6 +2263,7 @@ following permissions are restricted:
 * Worker Threads - manageable through [`--allow-worker`][] flag
 * WASI - manageable through [`--allow-wasi`][] flag
 * Addons - manageable through [`--allow-addons`][] flag
+* Environment Variables - manageable through [`--allow-env`][] flag
 * FFI - manageable through [`--allow-ffi`](#--allow-ffi) flag
 
 ### `--permission-audit`
@@ -3671,6 +3711,7 @@ one is included in the list below.
 
 * `--allow-addons`
 * `--allow-child-process`
+* `--allow-env`
 * `--allow-ffi`
 * `--allow-fs-read`
 * `--allow-fs-write`
@@ -4309,6 +4350,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`"type"`]: packages.md#type
 [`--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/permissions.md

@@ -71,7 +71,8 @@ using the [`--allow-child-process`][] and [`--allow-worker`][] respectively.
 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
-[`--allow-ffi`][] flag. The [`node:ffi`](ffi.md) module also requires the
+[`--allow-ffi`][] flag. For environment variables, use the
+[`--allow-env`][] flag. The [`node:ffi`](ffi.md) module also requires the
 `--experimental-ffi` flag and is only available in builds with FFI support.
 
 #### Runtime API
@@ -283,6 +284,7 @@ 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

doc/api/process.md

@@ -1559,6 +1559,12 @@ changes:
 The `process.env` property returns an object containing the user environment.
 See environ(7).
 
+When the [Permission Model][] is enabled, access to environment variables is
+restricted. Reading a restricted variable silently returns `undefined`, while
+writing or deleting throws `ERR_ACCESS_DENIED`. Use `--allow-env` to grant
+access to all variables or `--allow-env=HOME,PATH` to grant access to specific
+ones. See the [`--allow-env`][] documentation for more details.
+
 An example of this object looks like:
 
 <!-- eslint-skip -->
@@ -4596,6 +4602,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--allow-env`]: cli.md#--allow-env
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md