@bytecodealliance/preview2-shim 0.17.5 → 0.17.7

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/config.js

@@ -1,4 +1,3 @@
-// eslint-disable-next-line no-unused-vars
 let _cwd = '/';
 
 export function _setCwd(cwd) {

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,9 +341,159 @@ 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,
+    filesystemErrorCode(err) {
+        return convertFsError(err.payload);
+    },
 };
 
+function convertFsError(e) {
+    switch (e.code) {
+    case 'EACCES':
+        return 'access';
+    case 'EAGAIN':
+    case 'EWOULDBLOCK':
+        return 'would-block';
+    case 'EALREADY':
+        return 'already';
+    case 'EBADF':
+        return 'bad-descriptor';
+    case 'EBUSY':
+        return 'busy';
+    case 'EDEADLK':
+        return 'deadlock';
+    case 'EDQUOT':
+        return 'quota';
+    case 'EEXIST':
+        return 'exist';
+    case 'EFBIG':
+        return 'file-too-large';
+    case 'EILSEQ':
+        return 'illegal-byte-sequence';
+    case 'EINPROGRESS':
+        return 'in-progress';
+    case 'EINTR':
+        return 'interrupted';
+    case 'EINVAL':
+        return 'invalid';
+    case 'EIO':
+        return 'io';
+    case 'EISDIR':
+        return 'is-directory';
+    case 'ELOOP':
+        return 'loop';
+    case 'EMLINK':
+        return 'too-many-links';
+    case 'EMSGSIZE':
+        return 'message-size';
+    case 'ENAMETOOLONG':
+        return 'name-too-long';
+    case 'ENODEV':
+        return 'no-device';
+    case 'ENOENT':
+        return 'no-entry';
+    case 'ENOLCK':
+        return 'no-lock';
+    case 'ENOMEM':
+        return 'insufficient-memory';
+    case 'ENOSPC':
+        return 'insufficient-space';
+    case 'ENOTDIR':
+    case 'ERR_FS_EISDIR':
+        return 'not-directory';
+    case 'ENOTEMPTY':
+        return 'not-empty';
+    case 'ENOTRECOVERABLE':
+        return 'not-recoverable';
+    case 'ENOTSUP':
+        return 'unsupported';
+    case 'ENOTTY':
+        return 'no-tty';
+        // windows gives this error for badly structured `//` reads
+        // this seems like a slightly better error than unknown given
+        // that it's a common footgun
+    case -4094:
+    case 'ENXIO':
+        return 'no-such-device';
+    case 'EOVERFLOW':
+        return 'overflow';
+    case 'EPERM':
+        return 'not-permitted';
+    case 'EPIPE':
+        return 'pipe';
+    case 'EROFS':
+        return 'read-only';
+    case 'ESPIPE':
+        return 'invalid-seek';
+    case 'ETXTBSY':
+        return 'text-file-busy';
+    case 'EXDEV':
+        return 'cross-device';
+    case 'UNKNOWN':
+        switch (e.errno) {
+        case -4094:
+            return 'no-such-device';
+        default:
+            throw e;
+        }
+    default:
+        throw e;
+    }
+}
+
 export { types as filesystemTypes };

package/lib/browser/http.js

@@ -142,4 +142,14 @@ export const types = {
     listenToFutureIncomingResponse(_f) {
         console.log('[types] Listen to future incoming response');
     },
+    Fields: class Fields {},
+    FutureIncomingResponse: new class FutureIncomingResponse {},
+    IncomingBody: new class IncomingBody {},
+    IncomingRequest: new class IncomingRequest {},
+    IncomingResponse: new class IncomingResponse {},
+    OutgoingBody: new class OutgoingBody {},
+    OutgoingRequest: new class OutgoingRequest {},
+    OutgoingResponse: new class OutgoingResponse {},
+    RequestOptions: new class RequestOptions {},
+    ResponseOutparam: new class ResponseOutparam {},
 };

package/lib/browser/io.js

@@ -17,7 +17,7 @@ const IoError = class Error {
  *   blockingRead: (len: BigInt) => Uint8Array,
  *   skip?: (len: BigInt) => BigInt,
  *   blockingSkip?: (len: BigInt) => BigInt,
- *   subscribe: () => void,
+ *   subscribe: () => Pollable,
  *   drop?: () => void,
  * }} InputStreamHandler
  *
@@ -33,7 +33,7 @@ const IoError = class Error {
  *   splice?: (src: InputStream, len: BigInt) => BigInt,
  *   blockingSplice?: (src: InputStream, len: BigInt) => BigInt,
  *   forward?: (src: InputStream) => void,
- *   subscribe?: () => void,
+ *   subscribe?: () => Pollable,
  *   drop?: () => void,
  * }} OutputStreamHandler
  *
@@ -78,6 +78,7 @@ class InputStream {
     }
     subscribe() {
         console.log(`[streams] Subscribe to input stream ${this.id}`);
+        return new Pollable();
     }
     [symbolDispose]() {
         if (this.handler.drop) {
@@ -168,6 +169,7 @@ class OutputStream {
     }
     subscribe() {
         console.log(`[streams] Subscribe to output stream ${this.id}`);
+        return new Pollable();
     }
     [symbolDispose]() {}
 }
@@ -190,4 +192,5 @@ export const poll = {
     Pollable,
     pollList,
     pollOne,
+    poll: pollOne,
 };

package/lib/common/instantiation.js

@@ -44,6 +44,33 @@ import * as wasi from '@bytecodealliance/preview2-shim';
  * const component = await instantiate(null, customWASIShim.getImportObject())
  * ```
  *
+ * For sandboxing, you can configure preopens, environment variables, and other
+ * capabilities via the `sandbox` option:
+ *
+ * ```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: ['program'],      // Custom arguments
+ *     enableNetwork: false,   // Disable network (default: true for backward compat)
+ *   }
+ * });
+ *
+ * // Limited filesystem access
+ * 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
+ *     }
+ *   }
+ * });
+ * ```
+ *
  * Note that this object is similar but not identical to the Node `WASI` object --
  * it is solely concerned with shimming of preview2 when dealing with a WebAssembly
  * component transpiled by Jco. While this object *does* work with Node (and the browser)
@@ -66,8 +93,20 @@ export class WASIShim {
     #sockets;
     /** Object that confirms to the shim interface for `wasi:http` */
     #http;
+    /** Isolated preopens for this instance */
+    #preopens;
+    /** Isolated environment for this instance */
+    #environment;
+
+    /**
+     * Create a new WASIShim instance.
+     *
+     * @param {import('../types/instantiation.d.ts').WASIShimConfig} [config] - Configuration options
+     */
+    constructor(config) {
+        // Support both old 'shims' parameter name and new 'config' style
+        const shims = config;
 
-    constructor(shims) {
         this.#cli = shims?.cli ?? wasi.cli;
         this.#filesystem = shims?.filesystem ?? wasi.filesystem;
         this.#io = shims?.io ?? wasi.io;
@@ -75,6 +114,37 @@ export class WASIShim {
         this.#clocks = shims?.clocks ?? wasi.clocks;
         this.#sockets = shims?.sockets ?? wasi.sockets;
         this.#http = shims?.http ?? wasi.http;
+
+        // Extract sandbox options
+        const sandbox = shims?.sandbox;
+
+        // Create isolated preopens if configured
+        if (sandbox?.preopens !== undefined) {
+            this.#preopens = createIsolatedPreopens(sandbox.preopens);
+        }
+
+        // Create isolated environment if env or args are configured
+        if (sandbox?.env !== undefined || sandbox?.args !== undefined) {
+            this.#environment = createIsolatedEnvironment(
+                sandbox?.env,
+                sandbox?.args,
+                this.#cli
+            );
+        }
+
+        // Apply network restrictions if disabled
+        if (sandbox?.enableNetwork === false) {
+            // Use the sockets module's built-in deny functions
+            if (this.#sockets._denyTcp) {
+                this.#sockets._denyTcp();
+            }
+            if (this.#sockets._denyUdp) {
+                this.#sockets._denyUdp();
+            }
+            if (this.#sockets._denyDnsLookup) {
+                this.#sockets._denyDnsLookup();
+            }
+        }
     }
 
     /**
@@ -93,7 +163,8 @@ export class WASIShim {
         const versionSuffix = opts?.asVersion ? `@${opts.asVersion}` : '';
 
         const obj = {};
-        obj[`wasi:cli/environment${versionSuffix}`] = this.#cli.environment;
+
+        obj[`wasi:cli/environment${versionSuffix}`] = this.#environment ?? this.#cli.environment;
         obj[`wasi:cli/exit${versionSuffix}`] = this.#cli.exit;
         obj[`wasi:cli/stderr${versionSuffix}`] = this.#cli.stderr;
         obj[`wasi:cli/stdin${versionSuffix}`] = this.#cli.stdin;
@@ -112,7 +183,7 @@ export class WASIShim {
         obj[`wasi:sockets/udp${versionSuffix}`] = this.#sockets.udp;
         obj[`wasi:sockets/udp-create-socket${versionSuffix}`] = this.#sockets.udpCreateSocket;
 
-        obj[`wasi:filesystem/preopens${versionSuffix}`] = this.#filesystem.preopens;
+        obj[`wasi:filesystem/preopens${versionSuffix}`] = this.#preopens ?? this.#filesystem.preopens;
         obj[`wasi:filesystem/types${versionSuffix}`] = this.#filesystem.types;
 
         obj[`wasi:io/error${versionSuffix}`] = this.#io.error;
@@ -132,3 +203,55 @@ export class WASIShim {
         return obj;
     }
 }
+
+/**
+ * Create an isolated preopens object with its own preopen entries.
+ *
+ * @param {Record<string, string>} preopensConfig - Map of virtual paths to host paths
+ * @returns {object} A preopens object with Descriptor and getDirectories()
+ */
+function createIsolatedPreopens(preopensConfig) {
+    const { types, _createPreopenDescriptor } = wasi.filesystem;
+    const entries = [];
+
+    // Populate entries using the filesystem's descriptor creation
+    if (_createPreopenDescriptor) {
+        for (const [virtualPath, hostPath] of Object.entries(preopensConfig)) {
+            const descriptor = _createPreopenDescriptor(hostPath);
+            entries.push([descriptor, virtualPath]);
+        }
+    }
+
+    return {
+        Descriptor: types.Descriptor,
+        getDirectories() {
+            return entries;
+        },
+    };
+}
+
+/**
+ * Create an isolated CLI environment with its own env and args.
+ *
+ * @param {Record<string, string>} env - Environment variables
+ * @param {string[]} args - Command-line arguments
+ * @param {object} baseCli - The base CLI module to extend
+ * @returns {object} An isolated CLI environment object
+ */
+function createIsolatedEnvironment(env, args, baseCli) {
+    const envEntries = env ? Object.entries(env) : null;
+    const argsArray = args || null;
+
+    return {
+        ...baseCli.environment,
+        getEnvironment() {
+            return envEntries ?? baseCli.environment.getEnvironment();
+        },
+        getArguments() {
+            return argsArray ?? baseCli.environment.getArguments();
+        },
+        initialCwd() {
+            return baseCli.environment.initialCwd();
+        },
+    };
+}

package/lib/nodejs/filesystem.js

@@ -738,6 +738,10 @@ export const types = {
     },
 };
 
+/**
+ * Replace all preopens with the given set.
+ * @param {Record<string, string>} preopens - Map of virtual paths to host paths
+ */
 export function _setPreopens(preopens) {
     preopenEntries = [];
     for (const [virtualPath, hostPreopen] of Object.entries(preopens)) {
@@ -745,11 +749,46 @@ export function _setPreopens(preopens) {
     }
 }
 
+/**
+ * Add a single preopen mapping.
+ * @param {string} virtualPath - The virtual path visible to the guest
+ * @param {string} hostPreopen - The host filesystem path
+ */
 export function _addPreopen(virtualPath, hostPreopen) {
     const preopenEntry = [descriptorCreatePreopen(hostPreopen), virtualPath];
     preopenEntries.push(preopenEntry);
 }
 
+/**
+ * Clear all preopens, giving the guest no filesystem access.
+ * Call this immediately after import to disable default full filesystem access.
+ *
+ * @example
+ * import { _clearPreopens } from '@bytecodealliance/preview2-shim/filesystem';
+ * _clearPreopens(); // Now guest has no filesystem access by default
+ */
+export function _clearPreopens() {
+    preopenEntries = [];
+}
+
+/**
+ * Get current preopens configuration.
+ * @returns {Array<[Descriptor, string]>} Array of [descriptor, virtualPath] pairs
+ */
+export function _getPreopens() {
+    return [...preopenEntries];
+}
+
+/**
+ * Create a preopen descriptor for a host path.
+ * This is used internally to create isolated preopen instances.
+ * @param {string} hostPreopen - The host filesystem path
+ * @returns {Descriptor} A preopen descriptor
+ */
+export function _createPreopenDescriptor(hostPreopen) {
+    return descriptorCreatePreopen(hostPreopen);
+}
+
 function convertFsError(e) {
     switch (e.code) {
     case 'EACCES':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytecodealliance/preview2-shim",
-  "version": "0.17.5",
+  "version": "0.17.7",
   "description": "WASI Preview2 shim for JS environments",
   "author": "Guy Bedford, Eduardo Rodrigues<16357187+eduardomourar@users.noreply.github.com>",
   "contributors": [

package/types/filesystem.d.ts

@@ -1,2 +1,29 @@
 export type * as preopens from './interfaces/wasi-filesystem-preopens.d.ts';
 export type * as types from './interfaces/wasi-filesystem-types.d.ts';
+
+import type { Descriptor } from './interfaces/wasi-filesystem-types.d.ts';
+
+/**
+ * Replace all preopens with the given set.
+ * @param preopens - Map of virtual paths to host paths
+ */
+export function _setPreopens(preopens: Record<string, string>): void;
+
+/**
+ * Add a single preopen mapping.
+ * @param virtualPath - The virtual path visible to the guest
+ * @param hostPreopen - The host filesystem path
+ */
+export function _addPreopen(virtualPath: string, hostPreopen: string): void;
+
+/**
+ * Clear all preopens, giving the guest no filesystem access.
+ * Call this immediately after import to disable default full filesystem access.
+ */
+export function _clearPreopens(): void;
+
+/**
+ * Get current preopens configuration.
+ * @returns Array of [descriptor, virtualPath] pairs
+ */
+export function _getPreopens(): Array<[Descriptor, string]>;

package/types/instantiation.d.ts

@@ -64,6 +64,42 @@ type AppendVersion<
         : never
     : never;
 
+/**
+ * Sandbox configuration options for WASIShim
+ */
+interface SandboxConfig {
+    /** Filesystem preopens mapping (virtual path -> host path) */
+    preopens?: Record<string, string>;
+    /** Environment variables visible to the guest */
+    env?: Record<string, string>;
+    /** Command-line arguments */
+    args?: string[];
+    /** Whether to enable network access (sockets, HTTP). Default: true */
+    enableNetwork?: boolean;
+}
+
+/**
+ * Configuration options for WASIShim
+ */
+interface WASIShimConfig {
+    /** Custom CLI shim */
+    cli?: object;
+    /** Custom filesystem shim */
+    filesystem?: object;
+    /** Custom I/O shim */
+    io?: object;
+    /** Custom random shim */
+    random?: object;
+    /** Custom clocks shim */
+    clocks?: object;
+    /** Custom sockets shim */
+    sockets?: object;
+    /** Custom HTTP shim */
+    http?: object;
+    /** Sandbox configuration for restricting guest capabilities */
+    sandbox?: SandboxConfig;
+}
+
 /**
  * (EXPERIMENTAL) A class that holds WASI shims and can be used to configure
  * an instantiation of a WebAssembly component transpiled with jco
@@ -108,6 +144,33 @@ type AppendVersion<
  * const component = await instantiate(null, customWASIShim.getImportObject())
  * ```
  *
+ * For sandboxing, you can configure preopens, environment variables, and other
+ * capabilities via the `sandbox` option:
+ *
+ * ```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: ['program'],      // Custom arguments
+ *         enableNetwork: false,   // Disable network
+ *     }
+ * });
+ *
+ * // Limited filesystem access
+ * 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
+ *         }
+ *     }
+ * });
+ * ```
+ *
  * Note that this object is similar but not identical to the Node `WASI` object --
  * it is solely concerned with shimming of preview2 when dealing with a WebAssembly
  * component transpiled by Jco. While this object *does* work with Node (and the browser)
@@ -116,7 +179,7 @@ type AppendVersion<
  * @class WASIShim
  */
 export class WASIShim {
-    constructor(shims?: Partial<WASIImportObject>);
+    constructor(config?: WASIShimConfig);
 
     /**
      * Generate an import object for the shim that can be used with