doc: add env permission

Signed-off-by: Daeyeon Jeong <daeyeon.dev@gmail.com>

doc/api/cli.md

@@ -141,6 +141,62 @@ Error: Access to this API has been restricted
 }
 ```
 
+### `--allow-env`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+When using the [Permission Model][], access to the environment variables via
+`process.env` is denied by default. Attempts to do so will throw an
+`ERR_ACCESS_DENIED`. Users can explicitly configure permissions by passing the
+`--allow-env` flag when starting Node.js.
+
+The valid arguments for the `--allow-env` flag are:
+
+* Strings delimited by comma (`,`).
+* `*` - Used as a wildcard.
+* `-` - Used to deny access. By prefixing environment variables with `-`, you
+  can restrict access to them. It's worth noting that denied permissions always
+  take precedence over allowed permissions, regardless of the input order.
+
+See the [Environment Permissions][] documentation for more details.
+
+Example:
+
+```js
+// Attempt to bypass the permission
+process.env.SECRET;
+```
+
+```console
+$ node --experimental-permission --allow-fs-read=* index.js
+node:internal/modules/cjs/loader:162
+  const result = internalModuleStat(filename);
+                 ^
+
+Error: Access to this API has been restricted
+    at Object.<anonymous> (/home/index.js.js:1:13)
+    at Module._compile (node:internal/modules/cjs/loader:1256:14)
+    at Module._extensions..js (node:internal/modules/cjs/loader:1310:10)
+    at Module.load (node:internal/modules/cjs/loader:1114:32)
+    at Module._load (node:internal/modules/cjs/loader:961:12)
+    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:83:12)
+    at node:internal/main/run_main_module:23:47 {
+  code: 'ERR_ACCESS_DENIED',
+  permission: 'Environment',
+  resource: 'SECRET'
+}
+```
+
+The process needs to have access to the `SECRET` in the environment variables:
+
+```console
+$ node --experimental-permission --allow-fs-read=* --allow-env=SECRET index.js
+```
+
 ### `--allow-fs-read`
 
 <!-- YAML
@@ -2562,6 +2618,7 @@ done
 [CustomEvent Web API]: https://dom.spec.whatwg.org/#customevent
 [ECMAScript module]: esm.md#modules-ecmascript-modules
 [ECMAScript module loader]: esm.md#loaders
+[Environment Permissions]: permissions.md#environment-permissions
 [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
 [File System Permissions]: permissions.md#file-system-permissions
 [Modules loaders]: packages.md#modules-loaders

doc/api/permissions.md

@@ -464,9 +464,10 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--experimental-permission`][]
 flag.
 
-When starting Node.js with `--experimental-permission`,
-the ability to access the file system through the `fs` module, spawn processes,
-and use `node:worker_threads` will be restricted.
+When starting Node.js with `--experimental-permission`, the ability to access
+the file system through the `fs` module, access environment variables through
+`process.env`, spawn processes, and use `node:worker_threads` will be
+restricted.
 
 ```console
 $ node --experimental-permission index.js
@@ -488,6 +489,9 @@ 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.
 
+Allowing access to environment variables through `process.env` can be done using
+the [`--allow-env`][].
+
 #### Runtime API
 
 When enabling the Permission Model through the [`--experimental-permission`][]
@@ -506,6 +510,45 @@ process.permission.has('fs.read'); // true
 process.permission.has('fs.read', '/home/rafaelgss/protected-folder'); // false
 ```
 
+#### Environment Permissions
+
+To configure permission to access the environment variables via `process.env`,
+use the [`--allow-env`][] flag:
+
+```console
+$ node --experimental-permission --allow-fs-read=* --allow-env=* index.js
+```
+
+The valid arguments for the flag are:
+
+* Strings delimited by comma (`,`).
+* `*` - Used as a wildcard. To allow access to all environment variables, simply
+  use `--allow-env=*`.
+  * Use a string ended with `*` to allow access to variables that match the
+    specified prefix. For example, `--allow-env=NODE_*` will allow access to all
+    variables that start with `NODE_`.
+  * If `*` is not used as the last character of a string, such as `N*DE`,`*ODE`,
+    or `*ODE*`, the string is ignored.
+* `-` - Used to deny access. By prefixing variables with `-`, you can restrict
+  access to them. For example, `--allow-env=*,-SECURE_KEY` allows access to all
+  environment variables except `SECURE_KEY`. It's worth noting that denied
+  permissions always take precedence over allowed permissions, regardless of the
+  input order.
+
+Example:
+
+* `--allow-env=DATABASE_HOST` - `DATABASE_HOST` is allowed.
+* `--allow-env=DATABASE_HOST,DATABASE_PORT` - `DATABASE_HOST` and
+  `DATABASE_PORT` are allowed.
+* `--allow-env=DATABASE_*` - Environment variables starting with `DATABASE_` are
+  allowed.
+* `--allow-env=DATABASE_*,-DATABASE_PASSWORD` - Environment variables starting
+  with `DATABASE_` except `DATABASE_PASSWORD` are allowed.
+* `--allow-env=*,-DATABASE_PASSWORD` - All environment variables except
+  `DATABASE_PASSWORD` are allowed.
+* `--allow-env=DATABASE_HOST,*_PORT` - `DATABASE_HOST` is allowed. (`*_PORT` is
+  ignored.)
+
 #### File System Permissions
 
 To allow access to the file system, use the [`--allow-fs-read`][] and
@@ -554,6 +597,7 @@ There are constraints you need to know before using this system:
 [Import maps]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
 [Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md
 [`--allow-child-process`]: cli.md#--allow-child-process
+[`--allow-env`]: cli.md#--allow-env
 [`--allow-fs-read`]: cli.md#--allow-fs-read
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-worker`]: cli.md#--allow-worker

doc/api/process.md

@@ -2659,12 +2659,18 @@ The available scopes are:
 * `fs.write` - File System write operations
 * `child` - Child process spawning operations
 * `worker` - Worker thread spawning operation
+* `env` - Environment variable access operations
 
 ```js
 // Check if the process has permission to read the README file
 process.permission.has('fs.read', './README.md');
 // Check if the process has read permission operations
 process.permission.has('fs.read');
+
+// Check if the process has permission to access SECRET in environment variables
+process.permission.has('env', 'SECRET');
+// Check if the process has permission to access all environment variables
+process.permission.has('env');
 ```
 
 ## `process.pid`