From d0a4591573ec30de618558d79fe0bba9b8c7a607 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Fri, 16 Oct 2026 11:37:05 -0300 Subject: [PATCH] doc: document --allow-fs-vfs in the permission model page Signed-off-by: RafaelGSS --- doc/api/permissions.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/api/permissions.md b/doc/api/permissions.md index 386671b339d..7912864099e 100644 --- a/doc/api/permissions.md +++ b/doc/api/permissions.md @@ -94,6 +94,11 @@ This flag grants broad authority to configured OpenSSL STORE loaders, which may access files, devices, tokens, or the network. Access performed by a loader is not constrained by the `fs.read`, `fs.write`, or `net` permission scopes. +Mounting a [virtual file system][] with [`vfs.mount()`][] throws +`ERR_INVALID_STATE` unless the [`--allow-fs-vfs`][] flag is passed. A mounted +VFS serves paths that the file system permissions do not describe, so it is not +gated by [`--allow-fs-read`][] or [`--allow-fs-write`][]. + #### Runtime API When enabling the Permission Model through the [`--permission`][] @@ -158,11 +163,11 @@ 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-env`][], [`--allow-child-process`][], [`--allow-worker`][], -[`--allow-addons`][], [`--allow-wasi`][], [`--allow-ffi`][], -[`--allow-inspector`][], and [`--allow-openssl-store`][] flags to audit a subset -of permissions while granting others. +with the [`--allow-fs-read`][], [`--allow-fs-write`][], [`--allow-fs-vfs`][], +[`--allow-net`][], [`--allow-env`][], [`--allow-child-process`][], +[`--allow-worker`][], [`--allow-addons`][], [`--allow-wasi`][], +[`--allow-ffi`][], [`--allow-inspector`][], and [`--allow-openssl-store`][] +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: @@ -480,6 +485,7 @@ There are constraints you need to know before using this system: * WASI * FFI * OpenSSL STORE loaders + * Virtual file system mounting * The Permission Model is initialized after the Node.js environment is set up. However, certain flags such as `--env-file` or `--openssl-config` are designed to read files before environment initialization. As a result, such flags are @@ -538,6 +544,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha [`--allow-env`]: cli.md#--allow-env [`--allow-ffi`]: cli.md#--allow-ffi [`--allow-fs-read`]: cli.md#--allow-fs-read +[`--allow-fs-vfs`]: cli.md#--allow-fs-vfs [`--allow-fs-write`]: cli.md#--allow-fs-write [`--allow-inspector`]: cli.md#--allow-inspector [`--allow-net`]: cli.md#--allow-net @@ -555,3 +562,5 @@ Developers relying on --permission to sandbox untrusted code should be aware tha [`permission.drop()`]: process.md#processpermissiondropscope-reference [`permission.has()`]: process.md#processpermissionhasscope-reference [`process.loadEnvFile()`]: process.md#processloadenvfilepath +[`vfs.mount()`]: vfs.md#vfsmount +[virtual file system]: vfs.md