AK-21/Graphite-Industrial-Intelligence

1/**2 * **The `node:wasi` module does not currently provide the**3 * **comprehensive file system security properties provided by some WASI runtimes.**4 * **Full support for secure file system sandboxing may or may not be implemented in**5 * **future. In the mean time, do not rely on it to run untrusted code.**6 *7 * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives WebAssembly applications access to the underlying8 * operating system via a collection of POSIX-like functions.9 *10 * ```js11 * import { readFile } from 'node:fs/promises';12 * import { WASI } from 'node:wasi';13 * import { argv, env } from 'node:process';14 *15 * const wasi = new WASI({16 *   version: 'preview1',17 *   args: argv,18 *   env,19 *   preopens: {20 *     '/local': '/some/real/path/that/wasm/can/access',21 *   },22 * });23 *24 * const wasm = await WebAssembly.compile(25 *   await readFile(new URL('./demo.wasm', import.meta.url)),26 * );27 * const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());28 *29 * wasi.start(instance);30 * ```31 *32 * To run the above example, create a new WebAssembly text format file named `demo.wat`:33 *34 * ```text35 * (module36 *     ;; Import the required fd_write WASI function which will write the given io vectors to stdout37 *     ;; The function signature for fd_write is:38 *     ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written39 *     (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32)))40 *41 *     (memory 1)42 *     (export "memory" (memory 0))43 *44 *     ;; Write 'hello world\n' to memory at an offset of 8 bytes45 *     ;; Note the trailing newline which is required for the text to appear46 *     (data (i32.const 8) "hello world\n")47 *48 *     (func $main (export "_start")49 *         ;; Creating a new io vector within linear memory50 *         (i32.store (i32.const 0) (i32.const 8))  ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string51 *         (i32.store (i32.const 4) (i32.const 12))  ;; iov.iov_len - The length of the 'hello world\n' string52 *53 *         (call $fd_write54 *             (i32.const 1) ;; file_descriptor - 1 for stdout55 *             (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 056 *             (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.57 *             (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written58 *         )59 *         drop ;; Discard the number of bytes written from the top of the stack60 *     )61 * )62 * ```63 *64 * Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm`65 *66 * ```bash67 * wat2wasm demo.wat68 * ```69 * @experimental70 * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/wasi.js)71 */72declare module "wasi" {73    interface WASIOptions {74        /**75         * An array of strings that the WebAssembly application will76         * see as command line arguments. The first argument is the virtual path to the77         * WASI command itself.78         * @default []79         */80        args?: readonly string[] | undefined;81        /**82         * An object similar to `process.env` that the WebAssembly83         * application will see as its environment.84         * @default {}85         */86        env?: object | undefined;87        /**88         * This object represents the WebAssembly application's89         * sandbox directory structure. The string keys of `preopens` are treated as90         * directories within the sandbox. The corresponding values in `preopens` are91         * the real paths to those directories on the host machine.92         */93        preopens?: NodeJS.Dict<string> | undefined;94        /**95         * By default, when WASI applications call `__wasi_proc_exit()`96         * `wasi.start()` will return with the exit code specified rather than terminatng the process.97         * Setting this option to `false` will cause the Node.js process to exit with98         * the specified exit code instead.99         * @default true100         */101        returnOnExit?: boolean | undefined;102        /**103         * The file descriptor used as standard input in the WebAssembly application.104         * @default 0105         */106        stdin?: number | undefined;107        /**108         * The file descriptor used as standard output in the WebAssembly application.109         * @default 1110         */111        stdout?: number | undefined;112        /**113         * The file descriptor used as standard error in the WebAssembly application.114         * @default 2115         */116        stderr?: number | undefined;117        /**118         * The version of WASI requested.119         * Currently the only supported versions are `'unstable'` and `'preview1'`. This option is mandatory.120         * @since v19.8.0121         */122        version: "unstable" | "preview1";123    }124    interface FinalizeBindingsOptions {125        /**126         * @default instance.exports.memory127         */128        memory?: object | undefined;129    }130    /**131     * The `WASI` class provides the WASI system call API and additional convenience132     * methods for working with WASI-based applications. Each `WASI` instance133     * represents a distinct environment.134     * @since v13.3.0, v12.16.0135     */136    class WASI {137        constructor(options?: WASIOptions);138        /**139         * Return an import object that can be passed to `WebAssembly.instantiate()` if no other WASM imports are needed beyond those provided by WASI.140         *141         * If version `unstable` was passed into the constructor it will return:142         *143         * ```js144         * { wasi_unstable: wasi.wasiImport }145         * ```146         *147         * If version `preview1` was passed into the constructor or no version was specified it will return:148         *149         * ```js150         * { wasi_snapshot_preview1: wasi.wasiImport }151         * ```152         * @since v19.8.0153         */154        getImportObject(): object;155        /**156         * Attempt to begin execution of `instance` as a WASI command by invoking its `_start()` export. If `instance` does not contain a `_start()` export, or if `instance` contains an `_initialize()`157         * export, then an exception is thrown.158         *159         * `start()` requires that `instance` exports a [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) named `memory`. If160         * `instance` does not have a `memory` export an exception is thrown.161         *162         * If `start()` is called more than once, an exception is thrown.163         * @since v13.3.0, v12.16.0164         */165        start(instance: object): number; // TODO: avoid DOM dependency until WASM moved to own lib.166        /**167         * Attempt to initialize `instance` as a WASI reactor by invoking its `_initialize()` export, if it is present. If `instance` contains a `_start()` export, then an exception is thrown.168         *169         * `initialize()` requires that `instance` exports a [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) named `memory`.170         * If `instance` does not have a `memory` export an exception is thrown.171         *172         * If `initialize()` is called more than once, an exception is thrown.173         * @since v14.6.0, v12.19.0174         */175        initialize(instance: object): void; // TODO: avoid DOM dependency until WASM moved to own lib.176        /**177         * Set up WASI host bindings to `instance` without calling `initialize()`178         * or `start()`. This method is useful when the WASI module is instantiated in179         * child threads for sharing the memory across threads.180         *181         * `finalizeBindings()` requires that either `instance` exports a182         * [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) named `memory` or user specify a183         * [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) object in `options.memory`. If the `memory` is invalid184         * an exception is thrown.185         *186         * `start()` and `initialize()` will call `finalizeBindings()` internally.187         * If `finalizeBindings()` is called more than once, an exception is thrown.188         * @since v24.4.0189         */190        finalizeBindings(instance: object, options?: FinalizeBindingsOptions): void;191        /**192         * `wasiImport` is an object that implements the WASI system call API. This object193         * should be passed as the `wasi_snapshot_preview1` import during the instantiation194         * of a [`WebAssembly.Instance`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance).195         * @since v13.3.0, v12.16.0196         */197        readonly wasiImport: NodeJS.Dict<any>; // TODO: Narrow to DOM types198    }199}200declare module "node:wasi" {201    export * from "wasi";202}203