doc: document --permission-audit audit mode behavior

Expand the documentation for the --permission-audit flag, which was
fixed in 51c09ea to no longer throw ERR_ACCESS_DENIED on denied
operations. The previous docs only had a two-sentence description in
cli.md and no mention in the permissions guide or process.permission
API docs.
- permissions.md: add enforce vs audit mode overview, a new
"Audit Mode" subsection listing the diagnostics channel names
(node:permission-model:*) and the { permission, resource } message
shape, and a usage example. Update the Runtime API section to
mention both --permission and --permission-audit.
- cli.md: expand the --permission-audit section to clarify that
--permission is not required, --allow-* flags are not needed,
errors are not thrown, and --permission takes precedence when both
are set. Add a cross-reference from --permission to
--permission-audit.
- process.md: note that process.permission is available under both
flags, and clarify permission.has() and permission.drop() behavior
in audit mode.
- node.1: regenerated via `make node.1`.
Refs: #64426
Signed-off-by: Adrian Estrada <edsadr@gmail.com>
PR-URL: #64791
Backport-PR-URL: #65354
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: edsadr

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.

doc/api/cli.md

@@ -2130,6 +2130,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
 [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Child Process - manageable through [`--allow-child-process`][] flag
@@ -2143,9 +2146,22 @@ following permissions are restricted:
 added: REPLACEME
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+***Enforce mode** (default when using [`--permission`][]): Access is denied and
+ an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+ been granted permission to perform.
+***Audit mode** (when using [`--permission-audit`][]): Permission checks are
+ performed and violations are published through the diagnostics channel, but
+ access is **not** denied. Execution continues normally. This mode is useful
+ for discovering what permissions your application requires before deploying
+ with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, spawn processes,
 use `node:worker_threads`, use native addons, use WASI, and enable the runtime inspector
@@ -73,8 +84,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag.
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the`process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -122,6 +133,53 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');
 ```
 
+#### Audit Mode
+
+The [`--permission-audit`][] flag enables audit mode for the Permission Model.
+In audit mode, permission checks are performed but access is **not** denied —
+no `ERR_ACCESS_DENIED` error is thrown. Instead, each permission violation is
+published through the `node:diagnostics_channel` module, allowing the
+application to observe and log which operations would be denied under enforce
+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-child-process`][], [`--allow-worker`][], [`--allow-addons`][], and
+[`--allow-wasi`][] 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:
+
+*`node:permission-model:fs` — File System (read and write)
+*`node:permission-model:child` — Child Process
+*`node:permission-model:worker` — Worker Threads
+*`node:permission-model:inspector` — Inspector
+*`node:permission-model:wasi` — WASI
+*`node:permission-model:addon` — Native Addons
+
+Each message is an object with the following properties:
+
+*`permission` {string} The name of the denied permission scope.
+*`resource` {string} The resource that access was denied to (e.g. a file path).
+
+```js
+constdiagnostics_channel=require('node:diagnostics_channel');
+
+diagnostics_channel.channel('node:permission-model:fs').subscribe((msg) => {
+console.log(`Permission denied: ${msg.permission} on ${msg.resource}`);
+});
+
+// Running with --permission-audit, this publishes a diagnostics channel
+// message but does not throw
+constfs=require('node:fs');
+fs.readFileSync('/etc/passwd');
+```
+
+If both [`--permission`][] and [`--permission-audit`][] are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
+
 #### File System Permissions
 
 The Permission Model, by default, restricts access to the file system through the `node:fs` module.
@@ -312,6 +370,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-wasi`]: cli.md#--allow-wasi
 [`--allow-worker`]: cli.md#--allow-worker
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`npx`]: https://docs.npmjs.com/cli/commands/npx
 [`permission.has()`]: process.md#processpermissionhasscope-reference

doc/api/process.md

@@ -3150,7 +3150,8 @@ added: v20.0.0
 
 * Type: {Object}
 
-This API is available through the [`--permission`][] flag.
+This API is available through the [`--permission`][] or
+[`--permission-audit`][] flags.
 
 `process.permission` is an object whose methods are used to manage permissions
 for the current process. Additional documentation is available in the
@@ -3171,6 +3172,9 @@ If no reference is provided, a global scope is assumed, for instance,
 `process.permission.has('fs.read')` will check if the process has ALL
 file system read permissions.
 
+In audit mode ([`--permission-audit`][]), this method still returns the actual
+permission status, but denied operations will not throw `ERR_ACCESS_DENIED`.
+
 The reference has a meaning based on the provided scope. For example,
 the reference when the scope is File System means files and folders.
 
@@ -3204,6 +3208,10 @@ Drops the specified permission from the current process. This operation is
 **irreversible** — once a permission is dropped, it cannot be restored through
 any Node.js API.
 
+In audit mode ([`--permission-audit`][]), dropping a permission takes effect,
+but since denied operations do not throw, the impact is limited to changing the
+return value of `permission.has()`.
+
 If no reference is provided, the entire scope is dropped. For example,
 `process.permission.drop('fs.read')` will revoke ALL file system read
 permissions.
@@ -4626,6 +4634,7 @@ cases:
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
 [`--no-deprecation`]: cli.md#--no-deprecation
+[`--permission-audit`]: cli.md#--permission-audit
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
 [`Buffer`]: buffer.md

doc/node.1

@@ -469,9 +469,19 @@ Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is
 Emit pending deprecation warnings.
 .
 .ItFl-permission-audit
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is \fBnot\fR denied — no \fBERR_ACCESS_DENIED\fR error is
+thrown. Instead, each permission violation is published through the
+\fBnode:diagnostics_channel\fR module, and execution continues normally.
+This flag does not require \fB--permission\fR to be specified. The
+\fB--allow-*\fR flags are not needed in audit mode, since no
+access is denied.
+Audit mode is useful for discovering what permissions your application
+requires before deploying with \fB--permission\fR. See the
+Permission Model documentation for the list of diagnostics channel names
+and the message format.
+If both \fB--permission\fR and \fB--permission-audit\fR are specified,
+\fB--permission\fR takes precedence and the Permission Model runs in enforce mode.
 .
 .ItFl-preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module.