From 058c73972d3173840eff620896feda888de2f965 Mon Sep 17 00:00:00 2001
From: Trivikram Kamat <16024985+trivikr@users.noreply.github.com>
Date: Mon, 9 Nov 2026 19:01:23 -0800
Subject: [PATCH] doc: add temp dir write permission for VFS libraries

Loading an FFI library or native addon from a mounted VFS writes a
temporary copy of it. Under the permission model, this requires
--allow-fs-write on the temporary directory.

Signed-off-by: Trivikram Kamat <16024985+trivikr@users.noreply.github.com>
---
 doc/api/ffi.md         | 8 ++++++++
 doc/api/permissions.md | 6 +++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/doc/api/ffi.md b/doc/api/ffi.md
index 3a8adb9378fc..0d53f8b75251 100644
--- a/doc/api/ffi.md
+++ b/doc/api/ffi.md
@@ -240,6 +240,13 @@ self-cleaning temporary image instead, while `lib.path` keeps reporting
 the virtual path. Libraries on the real file system are unaffected and
 load directly.
 
+When using the [Permission Model][], loading a library from a virtual file
+system also requires [`--allow-fs-write`][] access to the temporary
+directory: the `TMPDIR` environment variable, or `/tmp` if it is unset, on
+POSIX, and the directory returned by `GetTempPathW()` on Windows. The path is
+matched as given, without resolving symbolic links. This applies even on
+platforms where the image is held in memory.
+
 When `definitions` is omitted, `functions` is returned as an empty object until
 symbols are resolved explicitly.
 
@@ -1052,6 +1059,7 @@ and keep callback and pointer lifetimes explicit on the native side.
 [Fast API call path]: #fast-api-call-path
 [Permission Model]: permissions.md#permission-model
 [`--allow-ffi`]: cli.md#--allow-ffi
+[`--allow-fs-write`]: cli.md#--allow-fs-write
 [`ffi.dlopen()`]: #ffidlopenpath-definitions
 [`ffi.toBuffer(pointer, length, copy)`]: #ffitobufferpointer-length-copy
 [`library.functions`]: #libraryfunctions
diff --git a/doc/api/permissions.md b/doc/api/permissions.md
index 2cf99bd167ab..7bbd3878b202 100644
--- a/doc/api/permissions.md
+++ b/doc/api/permissions.md
@@ -97,7 +97,11 @@ 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`][].
+gated by [`--allow-fs-read`][] or [`--allow-fs-write`][]. Loading a native
+addon or an [FFI library](ffi.md#ffidlopenpath-definitions) from a mounted VFS
+is the exception: the library is copied to a temporary image before it is
+loaded, so it also needs [`--allow-fs-write`][] access to the temporary
+directory.
 
 #### Runtime API