@hara-lang/hta 0.1.9

package/sandbox.js

@@ -0,0 +1,371 @@
+import { HtaContext, HtaHandle, HtaKeyword, HtaMapEntry, HtaStruct } from "./index.js";
+
+export const BROWSER_WASM_SANDBOX_PROTOCOL = "hara.browser-wasm-sandbox/0-alpha";
+export const MCP_PURE_PROFILE = "hara.mcp-pure/0-alpha";
+export const SANDBOX_EVAL_TARGET = "sandbox/eval";
+
+export const DEFAULT_BROWSER_SANDBOX_LIMITS = Object.freeze({
+  sourceBytes: 65_536,
+  outputBytes: 1_048_576,
+  wallMs: 5_000,
+});
+
+export const MAX_BROWSER_SANDBOX_LIMITS = Object.freeze({
+  sourceBytes: 1_048_576,
+  outputBytes: 4_194_304,
+  wallMs: 30_000,
+});
+
+const REQUEST_KEYS = new Set(["operation", "source", "limits"]);
+const LIMIT_KEYS = new Set(["sourceBytes", "outputBytes", "wallMs"]);
+const TEXT_ENCODER = new TextEncoder();
+const MAX_TRANSFER_DEPTH = 32;
+const MAX_TRANSFER_ITEMS = 65_536;
+
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function exactObject(value, keys, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw fail("sandbox/request-invalid", `${label} must be an object`);
+  }
+  for (const key of Object.keys(value)) {
+    if (!keys.has(key)) {
+      throw fail("sandbox/request-invalid", `${label} contains unknown field ${key}`);
+    }
+  }
+  return value;
+}
+
+function positiveInteger(value, label, maximum) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) {
+    throw fail(
+      "sandbox/limit-invalid",
+      `${label} must be a positive integer no greater than ${maximum}`,
+    );
+  }
+  return value;
+}
+
+function byteLength(value) {
+  return TEXT_ENCODER.encode(value).byteLength;
+}
+
+function validateSource(source, maximum) {
+  if (typeof source !== "string" || source.length === 0) {
+    throw fail("sandbox/request-invalid", "sandbox.eval requires non-empty source");
+  }
+  const bytes = byteLength(source);
+  if (bytes > maximum) {
+    throw fail(
+      "sandbox/source-limit",
+      `source is ${bytes} bytes, above the sandbox maximum ${maximum}`,
+    );
+  }
+  return source;
+}
+
+function validateLimits(value) {
+  if (value === undefined) return { ...DEFAULT_BROWSER_SANDBOX_LIMITS };
+  const limits = exactObject(value, LIMIT_KEYS, "sandbox limits");
+  return {
+    sourceBytes:
+      limits.sourceBytes === undefined
+        ? DEFAULT_BROWSER_SANDBOX_LIMITS.sourceBytes
+        : positiveInteger(
+            limits.sourceBytes,
+            "limits.sourceBytes",
+            MAX_BROWSER_SANDBOX_LIMITS.sourceBytes,
+          ),
+    outputBytes:
+      limits.outputBytes === undefined
+        ? DEFAULT_BROWSER_SANDBOX_LIMITS.outputBytes
+        : positiveInteger(
+            limits.outputBytes,
+            "limits.outputBytes",
+            MAX_BROWSER_SANDBOX_LIMITS.outputBytes,
+          ),
+    wallMs:
+      limits.wallMs === undefined
+        ? DEFAULT_BROWSER_SANDBOX_LIMITS.wallMs
+        : positiveInteger(limits.wallMs, "limits.wallMs", MAX_BROWSER_SANDBOX_LIMITS.wallMs),
+  };
+}
+
+export function validateBrowserSandboxRequest(value) {
+  const request = exactObject(value, REQUEST_KEYS, "sandbox request");
+  if (request.operation !== "sandbox.eval") {
+    throw fail(
+      "sandbox/capability-unsupported",
+      `browser sandbox operation is not available: ${String(request.operation)}`,
+    );
+  }
+  const limits = validateLimits(request.limits);
+  return Object.freeze({
+    operation: request.operation,
+    source: validateSource(request.source, limits.sourceBytes),
+    limits: Object.freeze(limits),
+  });
+}
+
+function projectMap(value, state, depth) {
+  const projected = {};
+  const entries = [...value.entries()];
+  state.items += entries.length;
+  if (state.items > MAX_TRANSFER_ITEMS) {
+    throw fail("sandbox/result-limit", "sandbox result contains too many values");
+  }
+  for (const [key, item] of entries) {
+    let name;
+    if (typeof key === "string") name = key;
+    else if (key instanceof HtaKeyword) name = `:${key.name}`;
+    else {
+      throw fail(
+        "sandbox/result-non-transferable",
+        "sandbox map keys must be strings or keywords",
+      );
+    }
+    if (Object.prototype.hasOwnProperty.call(projected, name)) {
+      throw fail("sandbox/result-non-transferable", `sandbox map key collision: ${name}`);
+    }
+    Object.defineProperty(projected, name, {
+      value: projectValue(item, state, depth + 1),
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return projected;
+}
+
+function projectValue(value, state, depth) {
+  if (depth > MAX_TRANSFER_DEPTH) {
+    throw fail("sandbox/result-limit", "sandbox result exceeds maximum nesting depth");
+  }
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw fail("sandbox/result-non-transferable", "sandbox result contains a non-finite number");
+    }
+    return value;
+  }
+  if (typeof value === "bigint") {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number)) {
+      throw fail("sandbox/result-non-transferable", "sandbox integer exceeds transfer-safe range");
+    }
+    return number;
+  }
+  if (value instanceof HtaKeyword) return `:${value.name}`;
+  if (value instanceof HtaMapEntry) {
+    return [
+      projectValue(value.key, state, depth + 1),
+      projectValue(value.value, state, depth + 1),
+    ];
+  }
+  if (value instanceof HtaHandle || value instanceof HtaStruct) {
+    throw fail(
+      "sandbox/result-non-transferable",
+      "sandbox result contains a live runtime value",
+    );
+  }
+  if (Array.isArray(value)) {
+    state.items += value.length;
+    if (state.items > MAX_TRANSFER_ITEMS) {
+      throw fail("sandbox/result-limit", "sandbox result contains too many values");
+    }
+    return value.map((item) => projectValue(item, state, depth + 1));
+  }
+  if (value instanceof Map) return projectMap(value, state, depth);
+  throw fail(
+    "sandbox/result-non-transferable",
+    `sandbox result type is not transfer-safe: ${Object.prototype.toString.call(value)}`,
+  );
+}
+
+export function projectBrowserSandboxValue(value, outputBytes) {
+  const json = projectValue(value, { items: 1 }, 0);
+  const text = typeof json === "string" ? json : JSON.stringify(json);
+  const bytes = byteLength(text);
+  if (bytes > outputBytes) {
+    throw fail(
+      "sandbox/output-limit",
+      `sandbox result is ${bytes} bytes, above the requested maximum ${outputBytes}`,
+    );
+  }
+  return Object.freeze({ text, json });
+}
+
+function defaultWorkerFactory(workerUrl) {
+  if (typeof Worker !== "function") {
+    throw fail("sandbox/worker-unavailable", "Worker is unavailable in this environment");
+  }
+  return new Worker(workerUrl, { type: "module", name: "hara-browser-sandbox" });
+}
+
+function defaultContextFactory(options) {
+  return new HtaContext(options);
+}
+
+export class BrowserWasmSandbox {
+  constructor(options = {}) {
+    const allowed = new Set([
+      "workerUrl",
+      "moduleUrl",
+      "moduleBytes",
+      "workerFactory",
+      "contextFactory",
+      "setTimer",
+      "clearTimer",
+    ]);
+    exactObject(options, allowed, "BrowserWasmSandbox options");
+    if (
+      !(typeof options.workerUrl === "string" || options.workerUrl instanceof URL) ||
+      String(options.workerUrl).length === 0
+    ) {
+      throw fail("sandbox/config-invalid", "workerUrl must be a non-empty URL or string");
+    }
+    if ((options.moduleUrl === undefined) === (options.moduleBytes === undefined)) {
+      throw fail(
+        "sandbox/config-invalid",
+        "exactly one of moduleUrl or moduleBytes must be supplied",
+      );
+    }
+    if (
+      options.moduleUrl !== undefined &&
+      !(typeof options.moduleUrl === "string" || options.moduleUrl instanceof URL)
+    ) {
+      throw fail("sandbox/config-invalid", "moduleUrl must be a URL or string");
+    }
+    if (
+      options.moduleBytes !== undefined &&
+      !(options.moduleBytes instanceof Uint8Array || options.moduleBytes instanceof ArrayBuffer)
+    ) {
+      throw fail("sandbox/config-invalid", "moduleBytes must be an ArrayBuffer or Uint8Array");
+    }
+    this.workerUrl = options.workerUrl;
+    this.moduleUrl = options.moduleUrl;
+    this.moduleBytes = options.moduleBytes;
+    this.workerFactory = options.workerFactory ?? defaultWorkerFactory;
+    this.contextFactory = options.contextFactory ?? defaultContextFactory;
+    this.setTimer = options.setTimer ?? ((callback, milliseconds) => setTimeout(callback, milliseconds));
+    this.clearTimer = options.clearTimer ?? ((timer) => clearTimeout(timer));
+    this.state = "new";
+    this.worker = null;
+    this.context = null;
+    this.activePromise = null;
+  }
+
+  snapshot() {
+    return Object.freeze({
+      protocol: BROWSER_WASM_SANDBOX_PROTOCOL,
+      profile: MCP_PURE_PROFILE,
+      state: this.state,
+      reusable: false,
+      hostCalls: false,
+      filesystem: false,
+    });
+  }
+
+  cancel() {
+    if (this.state !== "running" || !this.activePromise) return false;
+    const active = this.activePromise;
+    this.activePromise = null;
+    const cancelled = active.cancel?.() === true;
+    this.state = "cancelling";
+    if (!cancelled) this.close();
+    return cancelled;
+  }
+
+  close() {
+    if (this.state === "closed") return;
+    this.activePromise?.cancel?.();
+    this.activePromise = null;
+    const context = this.context;
+    const worker = this.worker;
+    this.context = null;
+    this.worker = null;
+    try {
+      context?.close?.();
+    } finally {
+      worker?.terminate?.();
+      this.state = "closed";
+    }
+  }
+
+  async run(value, options = {}) {
+    exactObject(options, new Set(["signal"]), "sandbox run options");
+    if (this.state !== "new") {
+      throw fail("sandbox/not-reusable", "a browser sandbox instance can execute exactly once");
+    }
+    const request = validateBrowserSandboxRequest(value);
+    const signal = options.signal;
+    if (
+      signal !== undefined &&
+      !(
+        typeof signal === "object" &&
+        typeof signal.aborted === "boolean" &&
+        typeof signal.addEventListener === "function" &&
+        typeof signal.removeEventListener === "function"
+      )
+    ) {
+      throw fail("sandbox/request-invalid", "signal must be an AbortSignal-compatible object");
+    }
+    if (signal?.aborted) {
+      this.state = "closed";
+      throw fail("sandbox/cancelled", "sandbox request was cancelled before start");
+    }
+
+    let timer;
+    let timedOut = false;
+    const onAbort = () => this.cancel();
+    this.state = "starting";
+    try {
+      this.worker = this.workerFactory(this.workerUrl);
+      this.context = this.contextFactory({
+        worker: this.worker,
+        moduleUrl: this.moduleUrl,
+        moduleBytes: this.moduleBytes,
+        hostCalls: Object.freeze({}),
+        filesystemHost: null,
+        kernelId: null,
+      });
+      signal?.addEventListener("abort", onAbort, { once: true });
+      timer = this.setTimer(() => {
+        timedOut = true;
+        if (!this.cancel()) this.close();
+      }, request.limits.wallMs);
+      if (signal?.aborted) throw fail("sandbox/cancelled", "sandbox request was cancelled");
+      await this.context.ready;
+      if (timedOut) throw fail("sandbox/timed-out", "sandbox wall-time limit expired");
+      this.state = "running";
+      const call = this.context.call(SANDBOX_EVAL_TARGET, [request.source]);
+      this.activePromise = call;
+      const result = await call;
+      if (timedOut) throw fail("sandbox/timed-out", "sandbox wall-time limit expired");
+      if (signal?.aborted) throw fail("sandbox/cancelled", "sandbox request was cancelled");
+      const projection = projectBrowserSandboxValue(result, request.limits.outputBytes);
+      this.state = "completed";
+      return Object.freeze({
+        protocol: BROWSER_WASM_SANDBOX_PROTOCOL,
+        profile: MCP_PURE_PROFILE,
+        status: "completed",
+        value: projection,
+        cleanup: "completed",
+      });
+    } catch (error) {
+      if (timedOut) throw fail("sandbox/timed-out", "sandbox wall-time limit expired");
+      if (signal?.aborted || error?.message === "cancelled") {
+        throw fail("sandbox/cancelled", "sandbox request was cancelled");
+      }
+      throw error;
+    } finally {
+      if (timer !== undefined) this.clearTimer(timer);
+      signal?.removeEventListener("abort", onAbort);
+      this.close();
+    }
+  }
+}

package/shared-worker.js

@@ -0,0 +1,216 @@
+import { decodeHta, encodeHta, HTA_MAX_FRAME_BYTES } from "./index.js";
+import { createBrowserProvider } from "./provider-browser.mjs";
+
+// One raw HTA instance shared by every same-origin tab. Each MessagePort owns
+// its request IDs and host calls, while the task table associates kernel work
+// with the port that initiated it.
+let instance;
+let boot;
+const clients = new Map();
+const providers = new Map();
+const tasks = new Map();
+const hostCalls = new Map();
+
+self.onconnect = (event) => {
+  const port = event.ports[0];
+  clients.set(port, new Map());
+  port.addEventListener("message", (message) => receive(port, message.data));
+  port.start();
+};
+
+async function receive(port, message) {
+  try {
+    if (message.type === "init") {
+      if (message.backend === "provider") {
+        await initializeProvider(port, message);
+        port.postMessage({ type: "ready" });
+        return;
+      }
+      boot ??= instantiate(message);
+      await boot;
+      port.postMessage({ type: "ready" });
+    } else if (providers.has(port)) {
+      const provider = providers.get(port);
+      await provider.handle(message);
+      if (message.type === "close") {
+        providers.delete(port);
+        clients.delete(port);
+        port.postMessage({ type: "closed" });
+      }
+    } else if (message.type === "call") {
+      await boot;
+      const session = requestSession(message.frame);
+      const task = Number(callFrame(instance.exports.hta_start, message.frame));
+      clients.get(port)?.set(message.id, task);
+      tasks.set(task, { port, id: message.id, session });
+      pump();
+    } else if (message.type === "delivery") {
+      await boot;
+      if (hostCalls.get(message.call)?.port !== port) return;
+      hostCalls.delete(message.call);
+      callFrame(instance.exports.hta_deliver, encodeHta([message.call, message.ok ? 0 : 1, decodeHta(message.frame)]));
+      pump();
+    } else if (message.type === "cancel") {
+      const task = clients.get(port)?.get(message.id);
+      if (task !== undefined) {
+        const calls = [...hostCalls.entries()]
+          .filter(([, owner]) => owner.port === port && owner.task === task)
+          .map(([call, owner]) => ({ ...owner, call }));
+        if (calls.length) port.postMessage({ type: "host-cancel", calls });
+        clients.get(port).delete(message.id);
+        tasks.delete(task);
+        try { instance.exports.hta_cancel(BigInt(task)); }
+        finally { instance.exports.hta_drop_task(BigInt(task)); }
+        for (const [call, owner] of hostCalls) if (owner.port === port && owner.task === task) hostCalls.delete(call);
+        pump();
+      }
+    } else if (message.type === "release") {
+      await boot;
+      const status = callFrame(instance.exports.hta_release, message.frame);
+      if (Number(status) !== 0) throw new Error(`hta/handle-release-failed: ${status}`);
+      pump();
+    } else if (message.type === "close") {
+      dropClientTasks(port);
+      clients.delete(port);
+      // HtaContext terminates the client port after the acknowledgement. The
+      // acknowledgement must cross the port before the client closes it.
+      port.postMessage({ type: "closed" });
+    }
+  } catch (error) {
+    failPort(port, error);
+  }
+}
+
+async function initializeProvider(port, message) {
+  if (providers.has(port)) throw new Error("hta/worker-already-initialized");
+  if (typeof message.providerUrl !== "string") throw new Error("hta/provider-missing");
+  const providerModule = await import(message.providerUrl);
+  const call = providerModule.default ?? providerModule.call ?? providerModule.provider;
+  if (typeof call !== "function") throw new Error("hta/provider-invalid");
+  const close = providerModule.close ?? providerModule.closeAll;
+  if (close !== undefined && typeof close !== "function") {
+    throw new Error("hta/provider-close-invalid");
+  }
+  if (providerModule.release !== undefined && typeof providerModule.release !== "function") {
+    throw new Error("hta/provider-release-invalid");
+  }
+  providers.set(port, createBrowserProvider(call, {
+    scope: { postMessage: value => port.postMessage(value) },
+    origin: "shared-worker",
+    errorCode: message.errorCode,
+    close: close === undefined ? undefined : () => close(),
+    release: providerModule.release,
+    onEvent: message.instrumentation
+      ? event => port.postMessage({ type: "provider-event", event })
+      : undefined
+  }));
+}
+
+async function instantiate(message) {
+  const bytes = message.moduleBytes ?? await (await fetch(message.moduleUrl)).arrayBuffer();
+  instance = (await WebAssembly.instantiate(bytes, {
+    env: {
+      hara_random_fill(pointer, length) {
+      if (!validRange(pointer, length)) return 1;
+      crypto.getRandomValues(new Uint8Array(instance.exports.memory.buffer, pointer, length));
+      return 0;
+      },
+      hara_time_ms() { return BigInt(Math.trunc(Date.now())); },
+      hara_time_ns() { return BigInt(Math.trunc(performance.now() * 1_000_000)); }
+    }
+  })).instance;
+  for (const name of ["memory", "hta_abi_version", "hta_alloc", "hta_dealloc", "hta_start", "hta_next_event", "hta_deliver", "hta_cancel", "hta_drop_task", "hta_release"]) {
+    if (!(name in instance.exports)) throw new Error(`hta/export-missing: ${name}`);
+  }
+  if (![1, 2, 3, 4].includes(instance.exports.hta_abi_version())) throw new Error("hta/version-unsupported");
+}
+
+function callFrame(fn, frame) {
+  const bytes = frame instanceof Uint8Array ? frame : new Uint8Array(frame);
+  if (bytes.length > HTA_MAX_FRAME_BYTES) throw new Error("hta/value-too-large: frame exceeds 64 MiB");
+  const pointer = Number(instance.exports.hta_alloc(bytes.length));
+  if (!Number.isSafeInteger(pointer) || !validRange(pointer, bytes.length)) throw new Error("hta/memory-unavailable");
+  new Uint8Array(instance.exports.memory.buffer, pointer, bytes.length).set(bytes);
+  try { return fn(pointer, bytes.length); } finally { instance.exports.hta_dealloc(pointer, bytes.length); }
+}
+
+function next() {
+  const packed = instance.exports.hta_next_event();
+  if (packed === 0n) return null;
+  const pointer = Number(packed >> 32n);
+  const size = Number(packed & 0xffff_ffffn);
+  if (!Number.isSafeInteger(pointer) || !Number.isSafeInteger(size) || size === 0 ||
+      size > HTA_MAX_FRAME_BYTES || !validRange(pointer, size)) {
+    if (Number.isSafeInteger(pointer) && Number.isSafeInteger(size) && pointer >= 0 && size >= 0) {
+      instance.exports.hta_dealloc(pointer, size);
+    }
+    throw new Error("hta/event-memory-invalid");
+  }
+  const frame = new Uint8Array(instance.exports.memory.buffer, pointer, size).slice();
+  instance.exports.hta_dealloc(pointer, size);
+  return decodeHta(frame);
+}
+
+function requestSession(frame) {
+  const [target, args] = decodeHta(frame);
+  return typeof target === "string" &&
+    ["session/eval", "session/eval-vm", "session/prepare-vm", "session/invoke-vm",
+      "session/eval-bound", "session/trace-eval", "session/complete"].includes(target) &&
+    typeof args?.[0] === "string"
+    ? args[0]
+    : "ROOT";
+}
+
+function pump() {
+  for (let event; (event = next()) !== null;) {
+    const kind = Number(event[0]);
+    if (kind === 0 || kind === 1) {
+      const task = Number(event[1]);
+      const request = tasks.get(task);
+      if (!request) continue;
+      tasks.delete(task);
+      clients.get(request.port)?.delete(request.id);
+      instance.exports.hta_drop_task(BigInt(task));
+      request.port.postMessage({ type: "result", id: request.id, ok: kind === 0, frame: encodeHta(event[2]) });
+    } else if (kind === 2) {
+      const request = tasks.get(Number(event[2]));
+      if (request) {
+        const call = Number(event[1]);
+        hostCalls.set(call, {
+          port: request.port,
+          task: Number(event[2]),
+          session: event[3],
+          mount: event[4] ?? null,
+          service: event[5],
+          method: event[6]
+        });
+        request.port.postMessage({ type: "host-call", call, task: Number(event[2]), session: event[3], mount: event[4] ?? null, service: event[5], method: event[6], frame: encodeHta(event[7]) });
+      }
+    } else throw new Error("hta/event-unknown");
+  }
+}
+
+function validRange(pointer, size) {
+  return Number.isSafeInteger(pointer) && Number.isSafeInteger(size) &&
+    pointer >= 0 && size >= 0 && pointer + size <= instance.exports.memory.buffer.byteLength;
+}
+
+function dropClientTasks(port) {
+  const requests = clients.get(port);
+  if (!requests) return;
+  for (const [id, task] of requests) {
+    const calls = [...hostCalls.entries()]
+      .filter(([, owner]) => owner.port === port && owner.task === task)
+      .map(([call, owner]) => ({ ...owner, call }));
+    if (calls.length) port.postMessage({ type: "host-cancel", calls });
+    tasks.delete(task);
+    try { instance.exports.hta_cancel(BigInt(task)); } finally { instance.exports.hta_drop_task(BigInt(task)); }
+  }
+  requests.clear();
+  for (const [call, owner] of hostCalls) if (owner.port === port) hostCalls.delete(call);
+}
+
+function failPort(port, error) {
+  dropClientTasks(port);
+  port.postMessage({ type: "fatal", error: { message: String(error?.message ?? error) } });
+}