@novasamatech/host-worker-sandbox 0.6.8

package/README.md

@@ -0,0 +1,33 @@
+# @novasamatech/host-worker-sandbox
+
+QuickJS-based sandbox for running product "worker" code in an isolated VM, wired to Triangle Host API via a byte-oriented `Provider`.
+
+## Usage
+
+`createSandbox()` returns a `Sandbox` with `container` (a [`Container`](https://github.com/paritytech/triangle-js-sdks/tree/main/packages/host-container) from `@novasamatech/host-container`) and `provider`. Register `handle*` callbacks on `sandbox.container` so worker code that talks to the Host API receives real responses.
+
+```ts
+import { createSandbox } from '@novasamatech/host-worker-sandbox';
+
+const hostStorage = new Map<string, Uint8Array>();
+
+const sandbox = await createSandbox('worker.example-product.dot');
+
+// Container bindings: implement the host side of the Host API (storage, features, chain, …).
+const unbindStorageRead = sandbox.container.handleLocalStorageRead((key, { ok }) =>
+  ok(hostStorage.get(key) ?? new Uint8Array()),
+);
+const unbindFeatureSupported = sandbox.container.handleFeatureSupported((_params, { ok }) => ok(false));
+
+const workerSource = `
+  // Worker module: __HOST_API_PORT__, TextEncoder, etc. are available in the VM.
+`;
+
+await sandbox.run(workerSource);
+
+// Later on...
+
+unbindStorageRead();
+unbindFeatureSupported();
+sandbox.dispose();
+```

package/dist/globals/AbortController.d.ts

@@ -0,0 +1,2 @@
+import type { QuickJSContext } from 'quickjs-emscripten';
+export declare function injectAbortController(vm: QuickJSContext): void;

package/dist/globals/AbortController.js

@@ -0,0 +1,17 @@
+export function injectAbortController(vm) {
+    const abortControllerCtor = vm.newConstructorFunction('AbortController', () => {
+        const signal = vm.newObject();
+        const addEventListener = vm.newFunction('addEventListener', () => vm.undefined);
+        const removeEventListener = vm.newFunction('removeEventListener', () => vm.undefined);
+        vm.setProp(signal, 'addEventListener', addEventListener);
+        vm.setProp(signal, 'removeEventListener', removeEventListener);
+        const instance = vm.newObject();
+        vm.setProp(instance, 'signal', signal);
+        signal.dispose();
+        addEventListener.dispose();
+        removeEventListener.dispose();
+        return instance;
+    });
+    vm.setProp(vm.global, 'AbortController', abortControllerCtor);
+    abortControllerCtor.dispose();
+}

package/dist/globals/TextDecoder.d.ts

@@ -0,0 +1,2 @@
+import type { QuickJSContext } from 'quickjs-emscripten';
+export declare function injectTextDecoder(vm: QuickJSContext): void;

package/dist/globals/TextDecoder.js

@@ -0,0 +1,50 @@
+export function injectTextDecoder(vm) {
+    const textDecoderCtor = vm.newConstructorFunction('TextDecoder', (...args) => {
+        const proto = vm.newObject();
+        const decodeFn = vm.newFunction('decode', function (...args) {
+            const dataHandle = args[0];
+            if (dataHandle === undefined || vm.typeof(dataHandle) === 'undefined') {
+                return vm.newString('');
+            }
+            const encodingHandle = vm.getProp(this, 'encoding');
+            const rawEncoding = vm.dump(encodingHandle);
+            encodingHandle.dispose();
+            const encoding = typeof rawEncoding === 'string' ? rawEncoding : 'utf-8';
+            // Support TypedArray (has .buffer + .byteOffset) and raw ArrayBuffer
+            const bufferPropHandle = vm.getProp(dataHandle, 'buffer');
+            let bytes;
+            if (vm.typeof(bufferPropHandle) !== 'undefined') {
+                // TypedArray path: extract slice from underlying buffer
+                const byteOffsetHandle = vm.getProp(dataHandle, 'byteOffset');
+                const byteLengthHandle = vm.getProp(dataHandle, 'byteLength');
+                const byteOffset = Number(vm.dump(byteOffsetHandle));
+                const byteLength = Number(vm.dump(byteLengthHandle));
+                byteOffsetHandle.dispose();
+                byteLengthHandle.dispose();
+                const lifetime = vm.getArrayBuffer(bufferPropHandle);
+                bytes = lifetime.value.slice(byteOffset, byteOffset + byteLength);
+                lifetime.dispose();
+            }
+            else {
+                // Raw ArrayBuffer path
+                const lifetime = vm.getArrayBuffer(dataHandle);
+                bytes = lifetime.value.slice(0);
+                lifetime.dispose();
+            }
+            bufferPropHandle.dispose();
+            return vm.newString(new TextDecoder(encoding).decode(bytes));
+        });
+        vm.setProp(proto, 'decode', decodeFn);
+        const instance = vm.newObject(proto);
+        const raw = args[0] !== undefined ? vm.dump(args[0]) : undefined;
+        const encoding = typeof raw === 'string' ? raw : 'utf-8';
+        const encHandle = vm.newString(encoding);
+        vm.setProp(instance, 'encoding', encHandle);
+        encHandle.dispose();
+        proto.dispose();
+        decodeFn.dispose();
+        return instance;
+    });
+    vm.setProp(vm.global, 'TextDecoder', textDecoderCtor);
+    textDecoderCtor.dispose();
+}

package/dist/globals/TextEncoder.d.ts

@@ -0,0 +1,2 @@
+import type { QuickJSContext, QuickJSHandle } from 'quickjs-emscripten';
+export declare function injectTextEncoder(vm: QuickJSContext, toUint8ArrayFn: QuickJSHandle): void;

package/dist/globals/TextEncoder.js

@@ -0,0 +1,28 @@
+export function injectTextEncoder(vm, toUint8ArrayFn) {
+    const textEncoderCtor = vm.newConstructorFunction('TextEncoder', () => {
+        const proto = vm.newObject();
+        const encodeFn = vm.newFunction('encode', strHandle => {
+            const raw = vm.dump(strHandle);
+            const str = typeof raw === 'string' ? raw : '';
+            const hostBytes = new TextEncoder().encode(str);
+            const buf = hostBytes.byteOffset === 0 && hostBytes.byteLength === hostBytes.buffer.byteLength
+                ? hostBytes.buffer
+                : hostBytes.buffer.slice(hostBytes.byteOffset, hostBytes.byteOffset + hostBytes.byteLength);
+            const bufHandle = vm.newArrayBuffer(buf);
+            const uint8Result = vm.callFunction(toUint8ArrayFn, vm.undefined, bufHandle);
+            bufHandle.dispose();
+            if (uint8Result.error) {
+                uint8Result.error.dispose();
+                return vm.undefined;
+            }
+            return uint8Result.value;
+        });
+        vm.setProp(proto, 'encode', encodeFn);
+        const instance = vm.newObject(proto);
+        proto.dispose();
+        encodeFn.dispose();
+        return instance;
+    });
+    vm.setProp(vm.global, 'TextEncoder', textEncoderCtor);
+    textEncoderCtor.dispose();
+}

package/dist/globals/console.d.ts

@@ -0,0 +1,3 @@
+import type { Logger } from '@novasamatech/host-api';
+import type { QuickJSContext } from 'quickjs-emscripten';
+export declare function injectConsole(vm: QuickJSContext, logger: Logger): void;

package/dist/globals/console.js

@@ -0,0 +1,13 @@
+export function injectConsole(vm, logger) {
+    const consoleObj = vm.newObject();
+    for (const method of ['log', 'info', 'warn', 'error']) {
+        const fn = vm.newFunction(method, (...args) => {
+            logger[method](...args.map(h => vm.dump(h)));
+            return vm.undefined;
+        });
+        vm.setProp(consoleObj, method, fn);
+        fn.dispose();
+    }
+    vm.setProp(vm.global, 'console', consoleObj);
+    consoleObj.dispose();
+}

package/dist/globals/crypto.d.ts

@@ -0,0 +1,2 @@
+import type { QuickJSContext, QuickJSHandle } from 'quickjs-emscripten';
+export declare function injectCrypto(vm: QuickJSContext, toUint8ArrayFn: QuickJSHandle): void;

package/dist/globals/crypto.js

@@ -0,0 +1,25 @@
+export function injectCrypto(vm, toUint8ArrayFn) {
+    const cryptoInstance = vm.newObject();
+    const getRandomValues = vm.newFunction('getRandomValues', arg => {
+        const bufferPropHandle = vm.getProp(arg, 'buffer');
+        const buffer = vm.getArrayBuffer(bufferPropHandle);
+        bufferPropHandle.dispose();
+        const bytes = crypto.getRandomValues(buffer.value);
+        buffer.dispose();
+        const buf = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+            ? bytes.buffer
+            : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const bufHandle = vm.newArrayBuffer(buf);
+        const uint8Result = vm.callFunction(toUint8ArrayFn, vm.undefined, bufHandle);
+        bufHandle.dispose();
+        if (uint8Result.error) {
+            uint8Result.error.dispose();
+            return vm.undefined;
+        }
+        return uint8Result.value;
+    });
+    vm.setProp(cryptoInstance, 'getRandomValues', getRandomValues);
+    vm.setProp(vm.global, 'crypto', cryptoInstance);
+    cryptoInstance.dispose();
+    getRandomValues.dispose();
+}

package/dist/globals/timers.d.ts

@@ -0,0 +1,4 @@
+import type { QuickJSContext } from 'quickjs-emscripten';
+export declare function injectTimeouts(vm: QuickJSContext): VoidFunction;
+export declare function injectIntervals(vm: QuickJSContext): VoidFunction;
+export declare function injectQueueMicrotask(vm: QuickJSContext): VoidFunction;

package/dist/globals/timers.js

@@ -0,0 +1,125 @@
+export function injectTimeouts(vm) {
+    const refs = new Map();
+    let disposed = false;
+    const setTimeoutHandler = vm.newFunction('setTimeout', (funcHandle, timeoutHandle) => {
+        const ttl = vm.getNumber(timeoutHandle);
+        const ref = funcHandle.dup();
+        const timeout = setTimeout(() => {
+            if (disposed)
+                return;
+            refs.delete(key);
+            const result = vm.callFunction(ref, vm.global);
+            if (result.error) {
+                result.error.dispose();
+            }
+            else {
+                result.value.dispose();
+            }
+            ref.dispose();
+            vm.runtime.executePendingJobs(-1);
+        }, ttl);
+        const key = typeof timeout === 'number' ? timeout : Math.round(Math.random() * 10000);
+        refs.set(key, ref);
+        return vm.newNumber(key);
+    });
+    vm.setProp(vm.global, 'setTimeout', setTimeoutHandler);
+    setTimeoutHandler.dispose();
+    const clearTimeoutHandler = vm.newFunction('clearTimeout', timeoutHandle => {
+        const key = vm.getNumber(timeoutHandle);
+        const ref = refs.get(key);
+        if (ref) {
+            clearTimeout(key);
+            ref.dispose();
+            refs.delete(key);
+            vm.runtime.executePendingJobs(-1);
+        }
+    });
+    vm.setProp(vm.global, 'clearTimeout', clearTimeoutHandler);
+    clearTimeoutHandler.dispose();
+    return () => {
+        disposed = true;
+        for (const [key, ref] of refs) {
+            clearTimeout(key);
+            ref.dispose();
+        }
+        refs.clear();
+    };
+}
+export function injectIntervals(vm) {
+    const refs = new Map();
+    let disposed = false;
+    const setIntervalHandler = vm.newFunction('setInterval', (funcHandle, timeoutHandle) => {
+        const ttl = vm.getNumber(timeoutHandle);
+        const ref = funcHandle.dup();
+        const interval = setInterval(() => {
+            if (disposed)
+                return;
+            const result = vm.callFunction(ref, vm.global);
+            if (result.error) {
+                result.error.dispose();
+            }
+            else {
+                result.value.dispose();
+            }
+            vm.runtime.executePendingJobs(-1);
+        }, ttl);
+        const key = typeof interval === 'number' ? interval : Math.round(Math.random() * 10000);
+        refs.set(key, ref);
+        return vm.newNumber(key);
+    });
+    vm.setProp(vm.global, 'setInterval', setIntervalHandler);
+    setIntervalHandler.dispose();
+    const clearIntervalHandler = vm.newFunction('clearInterval', timeoutHandle => {
+        const key = vm.getNumber(timeoutHandle);
+        const ref = refs.get(key);
+        if (ref) {
+            clearInterval(key);
+            ref.dispose();
+            refs.delete(key);
+            vm.runtime.executePendingJobs(-1);
+        }
+    });
+    vm.setProp(vm.global, 'clearInterval', clearIntervalHandler);
+    clearIntervalHandler.dispose();
+    return () => {
+        disposed = true;
+        for (const [key, ref] of refs) {
+            clearInterval(key);
+            ref.dispose();
+        }
+        refs.clear();
+    };
+}
+export function injectQueueMicrotask(vm) {
+    const pendingRefs = new Set();
+    let disposed = false;
+    const queueMicrotaskHandler = vm.newFunction('queueMicrotask', funcHandle => {
+        const ref = funcHandle.dup();
+        pendingRefs.add(ref);
+        queueMicrotask(() => {
+            pendingRefs.delete(ref);
+            if (disposed) {
+                ref.dispose();
+                return;
+            }
+            const result = vm.callFunction(ref, vm.global);
+            ref.dispose();
+            if (result.error) {
+                result.error.dispose();
+            }
+            else {
+                result.value.dispose();
+            }
+            vm.runtime.executePendingJobs(-1);
+        });
+        return vm.undefined;
+    });
+    vm.setProp(vm.global, 'queueMicrotask', queueMicrotaskHandler);
+    queueMicrotaskHandler.dispose();
+    return () => {
+        disposed = true;
+        for (const ref of pendingRefs)
+            ref.dispose();
+        pendingRefs.clear();
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { Sandbox } from './sandbox.js';
+export { createSandbox } from './sandbox.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createSandbox } from './sandbox.js';

package/dist/sandbox.d.ts

@@ -0,0 +1,9 @@
+import type { Provider } from '@novasamatech/host-api';
+import type { Container } from '@novasamatech/host-container';
+export type Sandbox = {
+    container: Container;
+    provider: Provider;
+    run: (code: string | Uint8Array, product?: string) => Promise<void>;
+    dispose: VoidFunction;
+};
+export declare function createSandbox(productId: string): Promise<Sandbox>;

package/dist/sandbox.js

@@ -0,0 +1,286 @@
+import { createDefaultLogger } from '@novasamatech/host-api';
+import { createContainer } from '@novasamatech/host-container';
+import { getQuickJS } from 'quickjs-emscripten';
+import { injectAbortController } from './globals/AbortController.js';
+import { injectTextDecoder } from './globals/TextDecoder.js';
+import { injectTextEncoder } from './globals/TextEncoder.js';
+import { injectConsole } from './globals/console.js';
+import { injectCrypto } from './globals/crypto.js';
+import { injectIntervals, injectQueueMicrotask, injectTimeouts } from './globals/timers.js';
+function makeOnMessageDescriptor(state, vm) {
+    // Regular function expressions have implicit `this: any`, which satisfies
+    // `(this: QuickJSHandle) => QuickJSHandle` without needing an `as` cast.
+    return {
+        configurable: false,
+        enumerable: true,
+        get() {
+            return state.handle?.dup() ?? vm.null;
+        },
+        set(handlerHandle) {
+            state.handle?.dispose();
+            const value = vm.dump(handlerHandle);
+            state.handle = value == null ? null : handlerHandle.dup();
+        },
+    };
+}
+class SandboxPort {
+    vm;
+    onMessageState = { handle: null };
+    messageListeners = [];
+    subscribers = new Set();
+    toUint8ArrayFn;
+    disposed = false;
+    provider;
+    constructor(productId, vm, toUint8ArrayFn) {
+        this.vm = vm;
+        this.toUint8ArrayFn = toUint8ArrayFn;
+        this.provider = this.makeProvider(productId);
+    }
+    buildHandle() {
+        const { vm } = this;
+        const port = vm.newObject();
+        // sandbox → host: extract Uint8Array bytes from the QuickJS handle and notify subscribers
+        const postMessageFn = vm.newFunction('postMessage', dataHandle => {
+            try {
+                const bufferHandle = vm.getProp(dataHandle, 'buffer');
+                const byteOffsetHandle = vm.getProp(dataHandle, 'byteOffset');
+                const byteLengthHandle = vm.getProp(dataHandle, 'byteLength');
+                const lifetime = vm.getArrayBuffer(bufferHandle);
+                // Number() converts `unknown` to number without an `as` cast
+                const byteOffset = Number(vm.dump(byteOffsetHandle));
+                const byteLength = Number(vm.dump(byteLengthHandle));
+                bufferHandle.dispose();
+                byteOffsetHandle.dispose();
+                byteLengthHandle.dispose();
+                // .slice() copies out of WASM memory before the lifetime is freed
+                const bytes = lifetime.value.slice(byteOffset, byteOffset + byteLength);
+                lifetime.dispose();
+                for (const subscriber of this.subscribers) {
+                    subscriber(bytes);
+                }
+            }
+            catch (e) {
+                console.error('[Sandbox] port.postMessage: failed to extract bytes', e);
+            }
+        });
+        vm.setProp(port, 'postMessage', postMessageFn);
+        postMessageFn.dispose();
+        // host → sandbox via addEventListener('message', handler)
+        const addEventListenerFn = vm.newFunction('addEventListener', (typeHandle, handlerHandle) => {
+            if (vm.getString(typeHandle) === 'message') {
+                this.messageListeners.push(handlerHandle.dup());
+            }
+        });
+        vm.setProp(port, 'addEventListener', addEventListenerFn);
+        addEventListenerFn.dispose();
+        // start() — no-op, exists for API compatibility
+        const startFn = vm.newFunction('start', () => vm.undefined);
+        vm.setProp(port, 'start', startFn);
+        startFn.dispose();
+        // close() — frees all stored handles
+        const closeFn = vm.newFunction('close', () => {
+            this.disposeHandles();
+        });
+        vm.setProp(port, 'close', closeFn);
+        closeFn.dispose();
+        // onmessage getter/setter via defineProp.
+        // State is accessed through a plain object ref captured in function expressions.
+        const { onMessageState } = this;
+        vm.defineProp(port, 'onmessage', makeOnMessageDescriptor(onMessageState, vm));
+        return port;
+    }
+    // Returns a Provider implementation backed by this port's QuickJS transport
+    makeProvider(productId) {
+        return {
+            logger: createDefaultLogger(productId),
+            isCorrectEnvironment: () => true,
+            postMessage: message => {
+                this.deliver(message);
+            },
+            subscribe: callback => {
+                this.subscribers.add(callback);
+                return () => {
+                    this.subscribers.delete(callback);
+                };
+            },
+            dispose: () => undefined,
+        };
+    }
+    // Delivers raw bytes from the host into the sandbox as a MessageEvent with Uint8Array data
+    deliver(bytes) {
+        if (this.disposed)
+            return;
+        const { vm } = this;
+        // Ensure the ArrayBuffer exactly covers the bytes (handle slice views)
+        const buffer = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+            ? bytes.buffer
+            : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const bufferHandle = vm.newArrayBuffer(buffer);
+        const uint8Result = vm.callFunction(this.toUint8ArrayFn, vm.undefined, bufferHandle);
+        bufferHandle.dispose();
+        if (uint8Result.error) {
+            console.error('[Sandbox] port: failed to create Uint8Array', vm.dump(uint8Result.error));
+            uint8Result.error.dispose();
+            return;
+        }
+        const event = vm.newObject();
+        vm.setProp(event, 'data', uint8Result.value);
+        uint8Result.value.dispose();
+        const handlers = [];
+        if (this.onMessageState.handle)
+            handlers.push(this.onMessageState.handle);
+        handlers.push(...this.messageListeners);
+        for (const handler of handlers) {
+            const result = vm.callFunction(handler, vm.undefined, event);
+            if (result.error) {
+                console.error('[Sandbox] port.onmessage error:', vm.dump(result.error));
+                result.error.dispose();
+            }
+            else {
+                result.value.dispose();
+            }
+        }
+        event.dispose();
+        const jobResult = vm.runtime.executePendingJobs(-1);
+        if (jobResult.error) {
+            console.error('[Sandbox] job error after port message:', vm.dump(jobResult.error));
+            jobResult.error.dispose();
+        }
+    }
+    disposeHandles() {
+        this.onMessageState.handle?.dispose();
+        this.onMessageState.handle = null;
+        for (const h of this.messageListeners)
+            h.dispose();
+        this.messageListeners.length = 0;
+    }
+    dispose() {
+        this.disposed = true;
+        this.disposeHandles();
+        this.subscribers.clear();
+    }
+}
+class QuickJsSandbox {
+    vm;
+    port;
+    toUint8ArrayFn;
+    disposeTimers;
+    disposed = false;
+    productId;
+    container;
+    provider;
+    constructor(productId, vm) {
+        this.productId = productId;
+        this.vm = vm;
+        const helperResult = vm.evalCode('(buf) => new Uint8Array(buf)');
+        if (helperResult.error) {
+            const msg = vm.dump(helperResult.error);
+            helperResult.error.dispose();
+            throw new Error(`Sandbox setup error: ${JSON.stringify(msg)}`);
+        }
+        this.toUint8ArrayFn = helperResult.value;
+        this.port = new SandboxPort(productId, vm, this.toUint8ArrayFn);
+        this.provider = this.port.provider;
+        this.container = createContainer(this.provider);
+        this.disposeTimers = this.injectGlobals();
+    }
+    injectGlobals() {
+        const { vm } = this;
+        const portHandle = this.port.buildHandle();
+        vm.setProp(vm.global, '__HOST_WEBVIEW_MARK__', vm.true);
+        vm.setProp(vm.global, '__HOST_API_PORT__', portHandle);
+        portHandle.dispose();
+        vm.setProp(vm.global, 'top', vm.global);
+        vm.setProp(vm.global, 'window', vm.global);
+        injectConsole(vm, this.provider.logger);
+        injectTextEncoder(vm, this.toUint8ArrayFn);
+        injectTextDecoder(vm);
+        injectCrypto(vm, this.toUint8ArrayFn);
+        injectAbortController(vm);
+        const disposeQueueMicrotask = injectQueueMicrotask(vm);
+        const disposeIntervals = injectIntervals(vm);
+        const disposeTimeouts = injectTimeouts(vm);
+        return () => {
+            disposeTimeouts();
+            disposeIntervals();
+            disposeQueueMicrotask();
+        };
+    }
+    async run(code) {
+        const { vm } = this;
+        const str = typeof code === 'string' ? code : new TextDecoder().decode(code);
+        const result = vm.evalCode(str, `${this.productId ?? 'unknown_product'}/worker.js`, {
+            type: 'module',
+            strict: true,
+        });
+        if (result.error) {
+            const message = vm.dump(result.error);
+            result.error.dispose();
+            throw new Error(`Sandbox error: ${JSON.stringify(message)}`);
+        }
+        // If the evaluated code returned a Promise (e.g. an async IIFE), attach a
+        // .then and .catch handler before flushing microtasks so that rejections are surfaced
+        // as thrown errors rather than silently swallowed.
+        let response = undefined;
+        const thenHandle = vm.getProp(result.value, 'then');
+        if (vm.typeof(thenHandle) === 'function') {
+            response = new Promise((resolve, reject) => {
+                const thenFn = vm.newFunction('__then', () => {
+                    resolve();
+                });
+                const thenMethod = vm.getProp(result.value, 'then');
+                const thenChained = vm.callFunction(thenMethod, result.value, thenFn);
+                thenMethod.dispose();
+                thenFn.dispose();
+                if (thenChained.error) {
+                    thenChained.error.dispose();
+                }
+                else {
+                    thenChained.value.dispose();
+                }
+                const catchFn = vm.newFunction('__catch', errorHandle => {
+                    reject(new Error(`Sandbox error: ${JSON.stringify(vm.dump(errorHandle))}`));
+                });
+                const catchMethod = vm.getProp(result.value, 'catch');
+                const cacheChained = vm.callFunction(catchMethod, result.value, catchFn);
+                catchMethod.dispose();
+                catchFn.dispose();
+                if (cacheChained.error) {
+                    cacheChained.error.dispose();
+                }
+                else {
+                    cacheChained.value.dispose();
+                }
+            });
+        }
+        thenHandle.dispose();
+        result.value.dispose();
+        this.flushJobs();
+        if (response) {
+            await response;
+        }
+    }
+    flushJobs() {
+        const result = this.vm.runtime.executePendingJobs(-1);
+        if (result.error) {
+            console.error('[Sandbox] job error:', this.vm.dump(result.error));
+            result.error.dispose();
+        }
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const { vm } = this;
+        this.disposeTimers();
+        this.port.dispose();
+        this.toUint8ArrayFn.dispose();
+        vm.runtime.executePendingJobs(-1);
+        vm.dispose();
+    }
+}
+export async function createSandbox(productId) {
+    const QuickJS = await getQuickJS();
+    const vm = QuickJS.newContext();
+    return new QuickJsSandbox(productId, vm);
+}

package/dist/sandbox.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sandbox.spec.js

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest';
+import { createSandbox } from './sandbox.js';
+describe('createSandbox', () => {
+    describe('initialization', () => {
+        it('should resolve to a sandbox with a container', async () => {
+            const sandbox = await createSandbox('test');
+            expect(sandbox.container).toBeDefined();
+            sandbox.dispose();
+        });
+        it('should inject window global with __HOST_WEBVIEW_MARK__', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('if (!window.__HOST_WEBVIEW_MARK__) throw new Error("missing")')).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should inject port global', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('if (typeof __HOST_API_PORT__ === "undefined") throw new Error("missing")')).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should inject TextEncoder', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('new TextEncoder()')).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should inject TextDecoder', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('new TextDecoder()')).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should inject intervals', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run(`
+          const interval = setInterval(() => {}, 1000);
+          clearInterval(interval);
+        `)).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should inject timeouts', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run(`
+          const timeout = setTimeout(() => {}, 1000);
+          clearTimeout(timeout);
+        `)).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should inject queueMicrotask', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run(`
+          queueMicrotask(() => {});
+        `)).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+    });
+    describe('run', () => {
+        it('should evaluate code without throwing', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('const x = 1 + 2')).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should throw on runtime error', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('throw new Error("boom")')).rejects.toThrow('Sandbox error');
+            sandbox.dispose();
+        });
+        it('should throw on syntax error', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('const = invalid;;')).rejects.toThrow('Sandbox error');
+            sandbox.dispose();
+        });
+        it('should run async IIFE without throwing', async () => {
+            const sandbox = await createSandbox('test');
+            await expect(sandbox.run('(async () => { await Promise.resolve(); })()')).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+        it('should deliver data posted inside an async IIFE', async () => {
+            const received = [];
+            const sandbox = await createSandbox('test');
+            sandbox.provider.subscribe(bytes => received.push(...bytes.subarray(0, 1)));
+            await sandbox.run('(async () => { await Promise.resolve(); __HOST_API_PORT__.postMessage(new Uint8Array([7])); })()');
+            expect(received).toEqual([7]);
+            sandbox.dispose();
+        });
+    });
+    describe('port messaging', () => {
+        it('should call provider subscriber when sandbox calls port.postMessage', async () => {
+            const sandbox = await createSandbox('test');
+            const received = [];
+            sandbox.provider.subscribe(bytes => received.push(bytes));
+            await sandbox.run('__HOST_API_PORT__.postMessage(new Uint8Array([1, 2, 3]))');
+            expect(received).toHaveLength(1);
+            expect(received[0]).toEqual(new Uint8Array([1, 2, 3]));
+            sandbox.dispose();
+        });
+        it('should deliver bytes to port.onmessage when provider.postMessage is called', async () => {
+            const received = [];
+            const sandbox = await createSandbox('test');
+            sandbox.provider.subscribe(bytes => received.push(...bytes.subarray(0, 1)));
+            await sandbox.run('__HOST_API_PORT__.onmessage = event => { __HOST_API_PORT__.postMessage(new Uint8Array([event.data[0]])); }');
+            sandbox.provider.postMessage(new Uint8Array([42]));
+            expect(received).toEqual([42]);
+            sandbox.dispose();
+        });
+        it('should deliver bytes to port.addEventListener message handlers', async () => {
+            const received = [];
+            const sandbox = await createSandbox('test');
+            sandbox.provider.subscribe(bytes => received.push(...bytes.subarray(0, 1)));
+            await sandbox.run(`__HOST_API_PORT__.addEventListener('message', event => { __HOST_API_PORT__.postMessage(new Uint8Array([event.data[0]])); })`);
+            sandbox.provider.postMessage(new Uint8Array([99]));
+            expect(received).toEqual([99]);
+            sandbox.dispose();
+        });
+        it('should deliver to both onmessage and addEventListener handlers', async () => {
+            const received = [];
+            const sandbox = await createSandbox('test');
+            sandbox.provider.subscribe(bytes => received.push(...bytes.subarray(0, 1)));
+            await sandbox.run(`
+        __HOST_API_PORT__.onmessage = event => { __HOST_API_PORT__.postMessage(new Uint8Array([event.data[0]])); };
+        __HOST_API_PORT__.addEventListener('message', event => { __HOST_API_PORT__.postMessage(new Uint8Array([event.data[0] + 10])); });
+      `);
+            sandbox.provider.postMessage(new Uint8Array([5]));
+            // onmessage fires first, then addEventListener handlers
+            expect(received).toEqual([5, 15]);
+            sandbox.dispose();
+        });
+        it('should clear the subscriber when the returned unsubscribe is called', async () => {
+            const sandbox = await createSandbox('test');
+            const received = [];
+            const unsubscribe = sandbox.provider.subscribe(bytes => received.push(bytes));
+            unsubscribe();
+            await sandbox.run('__HOST_API_PORT__.postMessage(new Uint8Array([1]))');
+            expect(received).toHaveLength(0);
+            sandbox.dispose();
+        });
+        it('should read and set port.onmessage via the getter', async () => {
+            const sandbox = await createSandbox('test');
+            await sandbox.run(`
+        if (__HOST_API_PORT__.onmessage !== null) throw new Error('expected null');
+        __HOST_API_PORT__.onmessage = () => {};
+        if (typeof __HOST_API_PORT__.onmessage !== 'function') throw new Error('expected function');
+      `);
+            await expect(sandbox.run('')).resolves.toBeUndefined();
+            sandbox.dispose();
+        });
+    });
+    describe('dispose', () => {
+        it('should not throw when disposing with active subscriptions and handlers', async () => {
+            const sandbox = await createSandbox('test');
+            await sandbox.run(`
+        __HOST_API_PORT__.onmessage = () => {};
+        __HOST_API_PORT__.addEventListener('message', () => {});
+      `);
+            expect(() => sandbox.dispose()).not.toThrow();
+        });
+        it('should stop delivering messages after dispose', async () => {
+            const received = [];
+            const sandbox = await createSandbox('test');
+            sandbox.provider.subscribe(bytes => received.push(...bytes.subarray(0, 1)));
+            await sandbox.run('__HOST_API_PORT__.onmessage = event => { __HOST_API_PORT__.postMessage(new Uint8Array([event.data[0]])); }');
+            sandbox.dispose();
+            // provider.postMessage after dispose must not throw even though the vm is gone
+            expect(() => sandbox.provider.postMessage(new Uint8Array([1]))).not.toThrow();
+            expect(received).toHaveLength(0);
+        });
+    });
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@novasamatech/host-worker-sandbox",
+  "type": "module",
+  "version": "0.6.8",
+  "description": "QuickJS-based sandbox for running product worker code with Triangle Host API.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paritytech/triangle-js-sdks.git"
+  },
+  "keywords": [
+    "polkadot"
+  ],
+  "main": "dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "#/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@novasamatech/host-api": "0.6.8",
+    "@novasamatech/host-container": "0.6.8",
+    "quickjs-emscripten": "0.32.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}