@bytecodealliance/preview2-shim 0.17.6 → 0.17.8

package/README.md

@@ -51,6 +51,54 @@ const component = await instantiate(loader, new WASIShim().getImportObject());
 // TODO: Code that uses your component's exports goes here.
 ```
 
+## Sandboxing
+
+By default, the preview2-shim provides full access to the host filesystem, environment variables,
+and network - matching the default behavior of Node.js libraries. However, you can configure
+sandboxing to restrict what guests can access.
+
+### Using WASIShim for sandboxing
+
+The `WASIShim` class accepts a `sandbox` configuration option to control access:
+
+```js
+import { WASIShim } from '@bytecodealliance/preview2-shim/instantiation';
+
+// Fully sandboxed - no filesystem, network, or env access
+const sandboxedShim = new WASIShim({
+  sandbox: {
+    preopens: {},           // No filesystem access
+    env: {},                // No environment variables
+    args: ['arg1'],         // Custom arguments
+    enableNetwork: false,   // Disable network access
+  }
+});
+
+// Limited filesystem access - map virtual paths to host paths
+const limitedShim = new WASIShim({
+  sandbox: {
+    preopens: {
+      '/data': '/tmp/guest-data',  // Guest sees /data, maps to /tmp/guest-data
+      '/config': '/etc/app'        // Guest sees /config, maps to /etc/app
+    },
+    env: { 'ENV1': '42' },           // Only expose specific env vars
+  }
+});
+
+const component = await instantiate(loader, sandboxedShim.getImportObject());
+```
+
+### Notes on sandboxing
+
+- By default (when no options are passed), the shim is providing full access to match typical
+  Node.js library behavior.
+- Each `WASIShim` instance has its own isolated preopens, environment variables, and arguments.
+  Multiple instances with different configurations will not affect each other.
+- The direct preopen functions (`_setPreopens`, `_clearPreopens`, etc.) modify global state and
+  affect all components not using `WASIShim` with explicit configuration. For isolation, prefer
+  using `WASIShim` with the `sandbox` option containing `preopens` and `env`.
+- When `sandbox.enableNetwork: false`, all socket and HTTP operations will throw "access-denied" errors.
+
 [jco]: https://www.npmjs.com/package/@bytecodealliance/jco
 
 # License

package/lib/browser/clocks.js

@@ -1,3 +1,6 @@
+import { poll } from './io.js';
+const { Pollable } = poll;
+
 export const monotonicClock = {
     resolution() {
         // usually we dont get sub-millisecond accuracy in the browser
@@ -10,15 +13,16 @@ export const monotonicClock = {
     },
     subscribeInstant(instant) {
         instant = BigInt(instant);
-        const now = this.now();
+        const now = monotonicClock.now();
         if (instant <= now) {
-            return this.subscribeDuration(0);
+            return new Pollable(new Promise(resolve => setTimeout(resolve, 0)));
         }
-        return this.subscribeDuration(instant - now);
+        return monotonicClock.subscribeDuration(instant - now);
     },
-    subscribeDuration(_duration) {
-        _duration = BigInt(_duration);
-        console.log(`[monotonic-clock] subscribe`);
+    subscribeDuration(duration) {
+        duration = BigInt(duration);
+        const ms = duration <= 0n ? 0 : Number(duration / 1_000_000n);
+        return new Pollable(new Promise(resolve => setTimeout(resolve, ms)));
     },
 };
 

package/lib/browser/filesystem.js

@@ -6,6 +6,25 @@ export { _setCwd } from './config.js';
 
 const { InputStream, OutputStream } = streams;
 
+/**
+ * @typedef {Object} FileDataEntry
+ * @property {Record<string, FileDataEntry>} [dir] - Directory contents (present for directories)
+ * @property {Uint8Array|string} [source] - File contents (present for files)
+ */
+
+/**
+ * @typedef {FileDataEntry} FileData
+ * Root file data structure representing a filesystem tree.
+ * Each entry is either a directory (has `dir` property) or a file (has `source` property).
+ * @example
+ * // A simple filesystem with one directory containing one file:
+ * const fileData = {
+ *   dir: {
+ *     'myfile.txt': { source: new Uint8Array([72, 101, 108, 108, 111]) }
+ *   }
+ * };
+ */
+
 export function _setFileData(fileData) {
     _fileData = fileData;
     _rootPreopen[0] = new Descriptor(fileData);
@@ -322,6 +341,59 @@ export const preopens = {
     },
 };
 
+/**
+ * Replace all preopens with the given set.
+ * @param {Record<string, FileData>} preopensConfig - Map of virtual paths to file data entries
+ */
+export function _setPreopens(preopensConfig) {
+    _preopens = [];
+    for (const [virtualPath, fileData] of Object.entries(preopensConfig)) {
+        _addPreopen(virtualPath, fileData);
+    }
+}
+
+/**
+ * Add a single preopen mapping.
+ * @param {string} virtualPath - The virtual path visible to the guest
+ * @param {FileData} fileData - The file data object representing the directory
+ */
+export function _addPreopen(virtualPath, fileData) {
+    const descriptor = new Descriptor(fileData);
+    _preopens.push([descriptor, virtualPath]);
+    if (virtualPath === '/') {
+        _rootPreopen = [descriptor, virtualPath];
+    }
+}
+
+/**
+ * Clear all preopens, giving the guest no filesystem access.
+ * 
+ * This functionality exists mostly to maintain backwards compatibility. Prefer setting preopens
+ * via `WASIShim` rather than making top level changes to preopens using these functions.
+ */
+export function _clearPreopens() {
+    _preopens = [];
+    _rootPreopen = null;
+}
+
+/**
+ * Get current preopens configuration.
+ * @returns {Array<[Descriptor, string]>} Array of [descriptor, virtualPath] pairs
+ */
+export function _getPreopens() {
+    return [..._preopens];
+}
+
+/**
+ * Create a preopen descriptor for file data.
+ * This is used internally to create isolated preopen instances.
+ * @param {FileData} fileData - The file data object representing the directory
+ * @returns {Descriptor} A preopen descriptor
+ */
+export function _createPreopenDescriptor(fileData) {
+    return new Descriptor(fileData);
+}
+
 export const types = {
     Descriptor,
     DirectoryEntryStream,