@bytecodealliance/preview2-shim 0.17.6 → 0.17.8

package/lib/browser/io.js

@@ -77,7 +77,9 @@ class InputStream {
         return BigInt(bytes.byteLength);
     }
     subscribe() {
-        console.log(`[streams] Subscribe to input stream ${this.id}`);
+        if (this.handler.subscribe) {
+            return this.handler.subscribe();
+        }
         return new Pollable();
     }
     [symbolDispose]() {
@@ -168,7 +170,9 @@ class OutputStream {
         console.log(`[streams] Forward ${this.id}`);
     }
     subscribe() {
-        console.log(`[streams] Subscribe to output stream ${this.id}`);
+        if (this.handler.subscribe) {
+            return this.handler.subscribe();
+        }
         return new Pollable();
     }
     [symbolDispose]() {}
@@ -178,19 +182,75 @@ export const error = { Error: IoError };
 
 export const streams = { InputStream, OutputStream };
 
-class Pollable {}
+class Pollable {
+    #ready = false;
+    #promise = null;
+
+    constructor(promise) {
+        if (!promise) {
+            this.#ready = true;
+        } else {
+            this.#promise = promise.then(
+                () => { this.#ready = true; },
+                () => { this.#ready = true; }
+            );
+        }
+    }
+
+    ready() {
+        return this.#ready;
+    }
+
+    block() {
+        if (this.#ready) {
+            return Promise.resolve();
+        }
+        return this.#promise;
+    }
 
-function pollList(_list) {
-    // TODO
+    [symbolDispose]() {
+        this.#promise = null;
+    }
+}
+
+function pollList(list) {
+    if (list.length === 0) {
+        throw new Error('poll list must not be empty');
+    }
+    if (list.length > 0xFFFFFFFF) {
+        throw new Error('poll list length exceeds u32 index range');
+    }
+    const ready = [];
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].ready()) {
+            ready.push(i);
+        }
+    }
+    if (ready.length > 0) {
+        return new Uint32Array(ready);
+    }
+    // None ready synchronously. Wait for the first to resolve via Promise.race,
+    // then sweep for any others that became ready concurrently.
+    return Promise.race(
+        list.map((p, i) => p.block().then(() => {
+            const result = [i];
+            for (let j = 0; j < list.length; j++) {
+                if (j !== i && list[j].ready()) {
+                    result.push(j);
+                }
+            }
+            return new Uint32Array(result);
+        }))
+    );
 }
 
-function pollOne(_poll) {
-    // TODO
+function pollOne(poll) {
+    return poll.block();
 }
 
 export const poll = {
     Pollable,
     pollList,
     pollOne,
-    poll: pollOne,
+    poll: pollList,
 };

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.6",
+  "version": "0.17.8",
   "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