doc: fix --allow-env docs to describe opt-in model

The documentation incorrectly described env var restriction as
deny-by-default when --permission is used. In reality, env vars
are unrestricted by default and only become restricted when
--allow-env is explicitly passed. Update cli.md and process.md
to accurately reflect this behavior.

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

Author: nabeel378

doc/api/cli.md

@@ -196,29 +196,37 @@ directly through the process arguments.
 > 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.
+unrestricted by default. To restrict access, the `--allow-env` flag must be
+explicitly passed when starting Node.js. Once `--allow-env` is specified,
+only the listed environment variables are accessible.
 
 * 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`.
+* Enumerating (`Object.keys(process.env)`) only returns allowed variables.
 
 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:
+Examples:
 
-```js
-console.log(process.env.HOME); // undefined (silently denied)
-process.env.FOO = 'bar';       // ERR_ACCESS_DENIED (throws)
+```console
+$ node --permission --allow-fs-read=* -p 'process.env.HOME'
+/Users/user
+$ node --permission --allow-env=PATH --allow-fs-read=* -p 'process.env.HOME'
+undefined
+$ node --permission --allow-env=HOME --allow-fs-read=* -p 'process.env.HOME'
+/Users/user
 ```
 
+Attempting to write a restricted variable throws:
+
 ```console
-$ node --permission index.js
+$ node --permission --allow-env=HOME --allow-fs-read=* -e "process.env.FOO = 'bar'"
 node:internal/process/per_thread:12
   throw new ERR_ACCESS_DENIED('EnvVar', name);
   ^

doc/api/process.md

@@ -1560,10 +1560,12 @@ 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.
+unrestricted by default. To restrict access, the `--allow-env` flag must be
+explicitly passed. Once `--allow-env` is specified, 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: