From ffb326c583c6a23bc94ff4989fe8a06edb92b011 Mon Sep 17 00:00:00 2001
From: Guy Bedford <gbedford@fastly.com>
Date: Wed, 25 Oct 2023 10:56:26 -0700
Subject: [PATCH] wasi: document security sandboxing status

PR-URL: https://github.com/nodejs/node/pull/50396
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/wasi.md | 45 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/doc/api/wasi.md b/doc/api/wasi.md
index f67187b7bcedb8..f590bd16fbbd2a 100644
--- a/doc/api/wasi.md
+++ b/doc/api/wasi.md
@@ -4,11 +4,16 @@
 
 > Stability: 1 - Experimental
 
+<strong class="critical">The `node:wasi` module does not currently provide the
+comprehensive file system security properties provided by some WASI runtimes.
+Full support for secure file system sandboxing may or may not be implemented in
+future. In the mean time, do not rely on it to run untrusted code. </strong>
+
 <!-- source_link=lib/wasi.js -->
 
 The WASI API provides an implementation of the [WebAssembly System Interface][]
-specification. WASI gives sandboxed WebAssembly applications access to the
-underlying operating system via a collection of POSIX-like functions.
+specification. WASI gives WebAssembly applications access to the underlying
+operating system via a collection of POSIX-like functions.
 
 ```mjs
 import { readFile } from 'node:fs/promises';
@@ -20,7 +25,7 @@ const wasi = new WASI({
   args: argv,
   env,
   preopens: {
-    '/sandbox': '/some/real/path/that/wasm/can/access',
+    '/local': '/some/real/path/that/wasm/can/access',
   },
 });
 
@@ -44,7 +49,7 @@ const wasi = new WASI({
   args: argv,
   env,
   preopens: {
-    '/sandbox': '/some/real/path/that/wasm/can/access',
+    '/local': '/some/real/path/that/wasm/can/access',
   },
 });
 
@@ -97,6 +102,28 @@ Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm`
 wat2wasm demo.wat
 ```
 
+## Security
+
+<!-- YAML
+added: REPLACEME
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/50396
+    description: Clarify WASI security properties.
+-->
+
+WASI provides a capabilities-based model through which applications are provided
+their own custom `env`, `preopens`, `stdin`, `stdout`, `stderr`, and `exit`
+capabilities.
+
+**The current Node.js threat model does not provide secure sandboxing as is
+present in some WASI runtimes.**
+
+While the capability features are supported, they do not form a security model
+in Node.js. For example, the file system sandboxing can be escaped with various
+techniques. The project is exploring whether these security guarantees could be
+added in future.
+
 ## Class: `WASI`
 
 <!-- YAML
@@ -107,9 +134,7 @@ added:
 
 The `WASI` class provides the WASI system call API and additional convenience
 methods for working with WASI-based applications. Each `WASI` instance
-represents a distinct sandbox environment. For security purposes, each `WASI`
-instance must have its command-line arguments, environment variables, and
-sandbox directory structure configured explicitly.
+represents a distinct environment.
 
 ### `new WASI([options])`
 
@@ -136,9 +161,9 @@ changes:
   * `env` {Object} An object similar to `process.env` that the WebAssembly
     application will see as its environment. **Default:** `{}`.
   * `preopens` {Object} This object represents the WebAssembly application's
-    sandbox directory structure. The string keys of `preopens` are treated as
-    directories within the sandbox. The corresponding values in `preopens` are
-    the real paths to those directories on the host machine.
+    local directory structure. The string keys of `preopens` are treated as
+    directories within the file system. The corresponding values in `preopens`
+    are the real paths to those directories on the host machine.
   * `returnOnExit` {boolean} By default, when WASI applications call
     `__wasi_proc_exit()`  `wasi.start()` will return with the exit code
     specified rather than terminating the process. Setting this option to