|
4 | 4 |
|
5 | 5 | > Stability: 1 - Experimental |
6 | 6 |
|
| 7 | +<strong class="critical">The `node:wasi` module does not currently provide the |
| 8 | +comprehensive file system security properties provided by some WASI runtimes. |
| 9 | +Full support for secure file system sandboxing may or may not be implemented in |
| 10 | +future. In the mean time, do not rely on it to run untrusted code. </strong> |
| 11 | + |
7 | 12 | <!-- source_link=lib/wasi.js --> |
8 | 13 |
|
9 | 14 | The WASI API provides an implementation of the [WebAssembly System Interface][] |
10 | | -specification. WASI gives sandboxed WebAssembly applications access to the |
11 | | -underlying operating system via a collection of POSIX-like functions. |
| 15 | +specification. WASI gives WebAssembly applications access to the underlying |
| 16 | +operating system via a collection of POSIX-like functions. |
12 | 17 |
|
13 | 18 | ```mjs |
14 | 19 | import { readFile } from 'node:fs/promises'; |
@@ -20,7 +25,7 @@ const wasi = new WASI({ |
20 | 25 | args: argv, |
21 | 26 | env, |
22 | 27 | preopens: { |
23 | | - '/sandbox': '/some/real/path/that/wasm/can/access', |
| 28 | + '/local': '/some/real/path/that/wasm/can/access', |
24 | 29 | }, |
25 | 30 | }); |
26 | 31 |
|
@@ -44,7 +49,7 @@ const wasi = new WASI({ |
44 | 49 | args: argv, |
45 | 50 | env, |
46 | 51 | preopens: { |
47 | | - '/sandbox': '/some/real/path/that/wasm/can/access', |
| 52 | + '/local': '/some/real/path/that/wasm/can/access', |
48 | 53 | }, |
49 | 54 | }); |
50 | 55 |
|
@@ -97,6 +102,28 @@ Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` |
97 | 102 | wat2wasm demo.wat |
98 | 103 | ``` |
99 | 104 |
|
| 105 | +## Security |
| 106 | + |
| 107 | +<!-- YAML |
| 108 | +added: REPLACEME |
| 109 | +changes: |
| 110 | + - version: REPLACEME |
| 111 | + pr-url: https://github.com/nodejs/node/pull/50396 |
| 112 | + description: Clarify WASI security properties. |
| 113 | +--> |
| 114 | + |
| 115 | +WASI provides a capabilities-based model through which applications are provided |
| 116 | +their own custom `env`, `preopens`, `stdin`, `stdout`, `stderr`, and `exit` |
| 117 | +capabilities. |
| 118 | + |
| 119 | +**The current Node.js threat model does not provide secure sandboxing as is |
| 120 | +present in some WASI runtimes.** |
| 121 | + |
| 122 | +While the capability features are supported, they do not form a security model |
| 123 | +in Node.js. For example, the file system sandboxing can be escaped with various |
| 124 | +techniques. The project is exploring whether these security guarantees could be |
| 125 | +added in future. |
| 126 | + |
100 | 127 | ## Class: `WASI` |
101 | 128 |
|
102 | 129 | <!-- YAML |
@@ -107,9 +134,7 @@ added: |
107 | 134 |
|
108 | 135 | The `WASI` class provides the WASI system call API and additional convenience |
109 | 136 | methods for working with WASI-based applications. Each `WASI` instance |
110 | | -represents a distinct sandbox environment. For security purposes, each `WASI` |
111 | | -instance must have its command-line arguments, environment variables, and |
112 | | -sandbox directory structure configured explicitly. |
| 137 | +represents a distinct environment. |
113 | 138 |
|
114 | 139 | ### `new WASI([options])` |
115 | 140 |
|
@@ -136,9 +161,9 @@ changes: |
136 | 161 | * `env` {Object} An object similar to `process.env` that the WebAssembly |
137 | 162 | application will see as its environment. **Default:** `{}`. |
138 | 163 | * `preopens` {Object} This object represents the WebAssembly application's |
139 | | - sandbox directory structure. The string keys of `preopens` are treated as |
140 | | - directories within the sandbox. The corresponding values in `preopens` are |
141 | | - the real paths to those directories on the host machine. |
| 164 | + local directory structure. The string keys of `preopens` are treated as |
| 165 | + directories within the file system. The corresponding values in `preopens` |
| 166 | + are the real paths to those directories on the host machine. |
142 | 167 | * `returnOnExit` {boolean} By default, when WASI applications call |
143 | 168 | `__wasi_proc_exit()` `wasi.start()` will return with the exit code |
144 | 169 | specified rather than terminating the process. Setting this option to |
|