@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/text-encoder.ts

@@ -0,0 +1,102 @@
+/**
+ * TextEncoder bridge - Encodes strings to Uint8Array
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import { defineClass } from './utils.js';
+import { unwrapResult } from './shared/index.js';
+
+/**
+ * Install TextEncoder in the sandbox
+ * Bridges to runtime's native TextEncoder
+ */
+export function installTextEncoder(ctx: BridgeContext): void {
+  const { context, logger } = ctx;
+
+  // Create cached Uint8Array wrapper function once - avoids evalCode on every encode()
+  // Store in global so it persists and can be used by the host function
+  {
+    using _uint8ArrayWrapper = unwrapResult(
+      context.evalCode('(globalThis.__uint8ArrayWrapper = function(ab) { return new Uint8Array(ab); })'),
+      context
+    );
+    // wrapper persists in globalThis; our reference is disposed by `using`
+  }
+
+  // Create host function that does the actual encoding
+  // Reusable native encoder (stateless)
+  const nativeEncoder = new TextEncoder();
+  {
+    using hostEncodeFunction = context.newFunction('__hostEncode', strHandle => {
+      try {
+        const str = context.dump(strHandle);
+        if (typeof str !== 'string') {
+          return context.newError('encode() requires a string');
+        }
+
+        const uint8Array = nativeEncoder.encode(str);
+
+        // Create a Uint8Array in QuickJS from the ArrayBuffer
+        // Use slice to handle any Uint8Array views into larger ArrayBuffers
+        const buf =
+          uint8Array.byteOffset === 0 && uint8Array.byteLength === uint8Array.buffer.byteLength
+            ? uint8Array.buffer
+            : uint8Array.buffer.slice(
+                uint8Array.byteOffset,
+                uint8Array.byteOffset + uint8Array.byteLength
+              );
+        using arrayBufferHandle = context.newArrayBuffer(buf);
+
+        // Get the cached wrapper from global
+        using wrapperHandle = context.getProp(context.global, '__uint8ArrayWrapper');
+
+        // Use cached wrapper function instead of evalCode on every encode
+        return unwrapResult(
+          context.callFunction(wrapperHandle, context.undefined, arrayBufferHandle),
+          context
+        );
+      } catch (e) {
+        logger?.error?.('TextEncoder.encode error', { error: e });
+        return context.newError(e instanceof Error ? e.message : String(e));
+      }
+    });
+
+    context.setProp(context.global, '__hostEncode', hostEncodeFunction);
+  }
+
+  // Define TextEncoder class in QuickJS
+  const classCode = `
+		class TextEncoder {
+			constructor() {
+				this.encoding = 'utf-8';
+			}
+			
+			encode(str) {
+				return __hostEncode(str);
+			}
+		}
+	`;
+
+  const classHandle = defineClass(ctx, classCode, 'TextEncoder');
+  if (classHandle) {
+    using handle = classHandle;
+    context.setProp(context.global, 'TextEncoder', handle);
+
+    // Clean up internal globals — make non-enumerable/writable to hide from sandbox
+    // NOTE: The sandbox is not a hard security boundary. Internal helpers are hidden via
+    // enumerable: false but can still be called by name. This is acceptable because the bridges
+    // are the primary security boundary, not QuickJS containment. See Sandbox.ts for details.
+    const hideResult = context.evalCode(`(function() {
+      try { Object.defineProperty(globalThis, '__hostEncode', { enumerable: false, writable: false, configurable: false }); } catch(e) {}
+      try { Object.defineProperty(globalThis, '__uint8ArrayWrapper', { enumerable: false, writable: false, configurable: false }); } catch(e) {}
+    })()`);
+    if (hideResult.error) {
+      hideResult.error.dispose();
+    } else {
+      (hideResult as { value: QuickJSHandle }).value.dispose();
+    }
+
+    logger?.info?.('[Bridge] TextEncoder installed');
+  }
+}

package/src/sandbox/bridges/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Types for QuickJS bridge utilities
+ */
+
+import type { QuickJSContext, QuickJSRuntime, QuickJSDeferredPromise } from 'quickjs-emscripten-core';
+import type { Logger } from '../../types.js';
+
+/**
+ * Promise tracker for async operations
+ */
+export interface PromiseTracker {
+  pendingPromises: Set<Promise<void>>;
+  notifyNewPromise: () => void;
+  newPromiseSignal: Promise<void>;
+  deferredPromises: Set<QuickJSDeferredPromise>;
+}
+
+/**
+ * Bridge context containing QuickJS context and shared resources
+ */
+export interface BridgeContext {
+  context: QuickJSContext;
+  runtime: QuickJSRuntime;
+  tracker: PromiseTracker;
+  logger?: Logger;
+  cleanupHandlers: Array<() => void | Promise<void>>;
+}
+
+/**
+ * Options for bridge installation
+ */
+export interface BridgeOptions {
+  logger?: Logger;
+}
+
+/**
+ * A bridge installer function
+ */
+export type BridgeInstaller = (ctx: BridgeContext) => void | (() => void);

package/src/sandbox/bridges/utils.ts

@@ -0,0 +1,123 @@
+/**
+ * Utility functions for creating QuickJS bridges
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import { convertToHandle } from './shared/convert.js';
+
+// Re-export convertToHandle from the shared module (single source of truth)
+export { convertToHandle } from './shared/convert.js';
+
+/**
+ * Create a synchronous function that bridges to a sync host function
+ */
+export function createSyncBridge(
+  ctx: BridgeContext,
+  name: string,
+  hostFn: (...args: any[]) => any
+): QuickJSHandle {
+  const { context, logger } = ctx;
+
+  return context.newFunction(name, (...args: QuickJSHandle[]) => {
+    const jsArgs = args.map(arg => context.dump(arg));
+    const result = hostFn(...jsArgs);
+
+    logger?.debug?.(`[Bridge] Sync bridge called: ${name}`);
+
+    return convertToHandle(context, result);
+  });
+}
+
+/**
+ * Create a promise-returning function that bridges to an async host function
+ */
+export function createAsyncBridge(
+  ctx: BridgeContext,
+  name: string,
+  hostFn: (...args: any[]) => Promise<any>
+): QuickJSHandle {
+  const { context, runtime, tracker, logger } = ctx;
+
+  return context.newFunction(name, (...args: QuickJSHandle[]) => {
+    const jsArgs = args.map(arg => context.dump(arg));
+    const deferred = context.newPromise();
+    tracker.deferredPromises.add(deferred);
+
+    const hostPromise = hostFn(...jsArgs)
+      .then((result: any) => {
+        try {
+          const handle = convertToHandle(context, result);
+          deferred.resolve(handle);
+          handle.dispose();
+          runtime.executePendingJobs();
+        } catch (e) {
+          try {
+            const errHandle = context.newString(String(e));
+            deferred.reject(errHandle);
+            errHandle.dispose();
+            runtime.executePendingJobs();
+          } catch {
+            // Context truly disposed — deferred will be cleaned up by sandbox cleanup
+          }
+          logger?.warn?.(`[Bridge] ${name}: error after async completion: ${e}`);
+        }
+      })
+      .catch((err: Error) => {
+        try {
+          const errHandle = context.newString(err.message || String(err));
+          deferred.reject(errHandle);
+          errHandle.dispose();
+          runtime.executePendingJobs();
+        } catch (e2) {
+          // Second-level catch: context disposed or string creation failed
+          // Try one more time with a minimal error before giving up
+          try {
+            const fallbackHandle = context.newString('Async bridge error');
+            deferred.reject(fallbackHandle);
+            fallbackHandle.dispose();
+            runtime.executePendingJobs();
+          } catch {
+            // Context truly disposed
+          }
+          logger?.warn?.(`[Bridge] ${name}: error handling failed: ${err.message}, fallback error: ${e2}`);
+        }
+      })
+      .finally(() => {
+        tracker.pendingPromises.delete(hostPromise);
+        tracker.deferredPromises.delete(deferred);
+      });
+
+    tracker.pendingPromises.add(hostPromise);
+    tracker.notifyNewPromise();
+
+    logger?.debug?.(`[Bridge] Created async bridge for ${name}`);
+
+    return deferred.handle;
+  });
+}
+
+/**
+ * Define an ES6 class in the sandbox using evalCode
+ * Returns the class handle or null if there was an error
+ */
+export function defineClass(
+  ctx: BridgeContext,
+  classCode: string,
+  className: string
+): QuickJSHandle | null {
+  const { context, logger } = ctx;
+
+  const classDef = context.evalCode(`(${classCode})`);
+
+  if (classDef.error) {
+    const error = context.dump(classDef.error);
+    classDef.error.dispose();
+    logger?.error?.(`Failed to define ${className} class`, { error });
+    return null;
+  }
+
+  return (classDef as any).value;
+}
+
+

package/src/sandbox/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Sandbox exports
+ */
+
+export { Sandbox } from './sandbox.js';
+export type { BridgeInstaller } from './bridges/types.js';

package/src/sandbox/quickjs-wasm.d.ts

@@ -0,0 +1,9 @@
+declare module '*.wasm' {
+  const content: WebAssembly.Module;
+  export default content;
+}
+
+declare module '@jitl/quickjs-ng-wasmfile-release-sync/dist/emscripten-module.wasm' {
+  const content: WebAssembly.Module;
+  export default content;
+}

package/src/sandbox/sandbox.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Sandbox tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Sandbox } from './index.js';
+
+describe('Sandbox', () => {
+  beforeEach(async () => {
+    await Sandbox.reset();
+  });
+
+  afterEach(async () => {
+    await Sandbox.reset();
+  });
+
+  it('should create singleton instance', async () => {
+    const sandbox1 = await Sandbox.configure();
+    const sandbox2 = await Sandbox.getInstance();
+
+    expect(sandbox1).toBe(sandbox2);
+  });
+
+  it('should return existing instance when configure is called twice', async () => {
+    const sandbox1 = await Sandbox.configure();
+    const sandbox2 = await Sandbox.configure();
+    expect(sandbox2).toBe(sandbox1);
+  });
+
+  it('should reject getInstance when not configured', async () => {
+    await expect(Sandbox.getInstance()).rejects.toThrow('not been configured');
+  });
+
+  it('should execute simple code', async () => {
+    const sandbox = await Sandbox.configure();
+    const result = await sandbox.execute('const x = 1 + 2; return x;', {}, { logger: console });
+
+    if (!result.success) {
+      console.error('Execution failed:', result.error);
+      console.error('Full result:', JSON.stringify(result, null, 2));
+    }
+    expect(result.success).toBe(true);
+    expect(result.result).toBe(3);
+  });
+
+  it('should handle async operations', async () => {
+    const sandbox = await Sandbox.configure();
+    const result = await sandbox.execute(
+      `
+      const p = Promise.resolve('done');
+      return await p;
+    `,
+      {},
+      { logger: console }
+    );
+
+    if (!result.success) {
+      console.error('Execution failed:', result.error);
+      console.error('Full result:', JSON.stringify(result, null, 2));
+    }
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('done');
+  });
+
+  it('should queue concurrent executions', async () => {
+    const sandbox = await Sandbox.configure();
+    const order: number[] = [];
+
+    // Each execution records its completion order via .then() callback.
+    // The queue serializes them, so they complete in submission order.
+    // Use computation (not setTimeout) to create varying execution times.
+    const promise1 = sandbox
+      .execute(
+        `
+      // Heavier computation to take longer
+      let sum = 0;
+      for (let i = 0; i < 10000; i++) sum += i;
+      return 1;
+    `
+      )
+      .then((result) => {
+        if (!result.success) console.error('Execution 1 failed:', result.error);
+        expect(result.success).toBe(true);
+        order.push(result.result as number);
+      });
+
+    const promise2 = sandbox
+      .execute(
+        `
+      let sum = 0;
+      for (let i = 0; i < 100; i++) sum += i;
+      return 2;
+    `
+      )
+      .then((result) => {
+        expect(result.success).toBe(true);
+        order.push(result.result as number);
+      });
+
+    const promise3 = sandbox
+      .execute(
+        `
+      return 3;
+    `
+      )
+      .then((result) => {
+        expect(result.success).toBe(true);
+        order.push(result.result as number);
+      });
+
+    await Promise.all([promise1, promise2, promise3]);
+
+    // Executions are serialized by the queue — they must complete in submission order
+    // even though execution 2 and 3 are faster computations than execution 1
+    expect(order).toEqual([1, 2, 3]);
+  });
+
+  it('should inject globals', async () => {
+    const sandbox = await Sandbox.configure();
+    const result = await sandbox.execute('return myGlobal;', {
+      myGlobal: 'hello world'
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('hello world');
+  });
+
+  it('should handle errors', async () => {
+    const sandbox = await Sandbox.configure();
+    const result = await sandbox.execute('throw new Error("test error");', {}, { logger: console });
+
+    if (!result.success) {
+      console.error('Error result:', result.error);
+    }
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('test error');
+  });
+
+  it('should enforce timeout', async () => {
+    const sandbox = await Sandbox.configure();
+    const result = await sandbox.execute(
+      'await new Promise(() => {});',
+      {},
+      {
+        timeoutMs: 100
+      }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('timeout');
+  });
+
+  it('should capture console output', async () => {
+    const sandbox = await Sandbox.configure();
+    const result = await sandbox.execute('console.log("hello"); return "done";');
+
+    expect(result.success).toBe(true);
+    expect(result.consoleOutput).toContain('hello');
+  });
+
+  it('should dispose correctly', async () => {
+    const sandbox = await Sandbox.configure();
+    await sandbox.dispose();
+
+    // After dispose, configure should create a new instance
+    const sandbox2 = await Sandbox.configure();
+    expect(sandbox2).not.toBe(sandbox);
+  });
+
+  it('should reject queued executions after dispose', async () => {
+    const sandbox = await Sandbox.configure();
+
+    // Start a long execution
+    const longPromise = sandbox.execute(`
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return 'done';
+    `);
+
+    // Queue another execution
+    const queuedPromise = sandbox.execute('return "queued";');
+
+    // Dispose while first is still running
+    await sandbox.dispose();
+
+    // Queued execution should be rejected
+    await expect(queuedPromise).rejects.toThrow('disposed');
+
+    // Clean up long promise
+    await longPromise.catch(() => {});
+  });
+});