Skip to content

doc: document --allow-fs-vfs in the permission model page #66793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RafaelGSS wants to merge 1 commit into
base: main
Choose a base branch
from
+14 −5
Open

doc: document --allow-fs-vfs in the permission model page #66793

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions doc/api/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`][]
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Loading