@eryx-org/eryx 0.0.0 → 0.15.1

package/shims/net.js

@@ -0,0 +1,260 @@
+/**
+ * Network shims for the eryx sandbox (eryx:net/tcp and eryx:net/tls).
+ *
+ * Networking is disabled until the host sets a policy, per sandbox or as the
+ * default with setNetConfig(). Host policy mirrors the Rust crate's NetConfig:
+ * blocked patterns are always enforced, then the host must match allowedHosts
+ * unless allowAllHosts is set. Hosts are
+ * matched in their WHATWG URL form too, so `2130706433` and `0x7f.1` read as
+ * `127.0.0.1`. IP addresses are checked against blockedNetworks (minus
+ * allowedNetworks); in Node, so are the addresses a name resolves to, unless
+ * the host matches internalHosts. Browsers don't expose DNS answers, so there
+ * only an allowlist keeps names that resolve to private addresses out.
+ *
+ * The transport depends on the environment:
+ * - Node.js: real TCP/TLS sockets (net-node.js)
+ * - Browsers: HTTP(S) only, replayed through fetch() (net-fetch.js)
+ *
+ * The guest calls these imports synchronously; they return Promises and are
+ * transpiled as JSPI async imports, which suspend the wasm stack until they
+ * settle. jco lowers `result<T, E>` imports as: return T, or throw
+ * `{ payload: E }`.
+ */
+
+const isNode =
+  typeof globalThis.process !== "undefined" &&
+  typeof globalThis.process.versions?.node !== "undefined";
+
+const transport = isNode ? await import("./net-node.js") : await import("./net-fetch.js");
+
+/** The Rust crate's `NetConfig::default().blocked_hosts`, plus `0.0.0.0` and `[::]`. */
+export const DEFAULT_BLOCKED_HOSTS = Object.freeze([
+  "localhost",
+  "*.localhost",
+  "127.*",
+  "10.*",
+  ...Array.from({ length: 16 }, (_, i) => `172.${16 + i}.*`),
+  "192.168.*",
+  "169.254.*",
+  "[::1]",
+  "0.0.0.0",
+  "[::]",
+]);
+
+/**
+ * The Rust crate's `DEFAULT_BLOCKED_NETWORKS`. IPv4-mapped, IPv4-compatible,
+ * NAT64 and Teredo addresses are also checked by the IPv4 address they embed.
+ */
+export const DEFAULT_BLOCKED_NETWORKS = Object.freeze([
+  "0.0.0.0/8",
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "127.0.0.0/8",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.0.0.0/24",
+  "192.168.0.0/16",
+  "198.18.0.0/15",
+  "224.0.0.0/4",
+  "240.0.0.0/4",
+  "::/96",
+  "2001::/32",
+  "2001:db8::/32",
+  "2002::/16",
+  "64:ff9b:1::/48",
+  "fc00::/7",
+  "fe80::/10",
+  "fec0::/10",
+  "ff00::/8",
+]);
+
+/** Same defaults as the Rust crate's `NetConfig::default()`. */
+const DEFAULT_MAX_CONNECTIONS = 10;
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+const DEFAULT_IO_TIMEOUT_MS = 60_000;
+
+/**
+ * A checked policy; `isAllowed` checks resolved addresses (null where the
+ * transport can't see them).
+ *
+ * @typedef {Required<import("./net.js").NetConfig> & { isAllowed: ((address: string, family: number) => boolean) | null }} Policy
+ */
+
+/**
+ * The policy new instances start with, set by setNetConfig().
+ * @type {Policy | null}
+ */
+let defaultPolicy = null;
+
+/** Strict CIDR syntax, so a typo can't parse as a wider network (`10.0.0.0/` as `/0`). */
+function checkCidrs(cidrs) {
+  for (const cidr of cidrs) {
+    const m = /^([0-9a-fA-F:.]+)\/(\d{1,3})$/.exec(cidr);
+    if (!m || Number(m[2]) > (m[1].includes(":") ? 128 : 32)) {
+      throw new TypeError(`invalid CIDR '${cidr}'`);
+    }
+  }
+  return cidrs;
+}
+
+/** A non-negative integer, or a TypeError. */
+function checkCount(name, value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative integer, got ${value}`);
+  }
+  return value;
+}
+
+/** A timeout above zero, or a TypeError: zero would time out every connection, as in Rust. */
+function checkTimeout(name, value) {
+  if (typeof value !== "number" || !(value > 0)) {
+    throw new TypeError(`${name} must be greater than zero, got ${value}`);
+  }
+  return value;
+}
+
+/**
+ * Check `netConfig` and fill in the defaults; null disables networking.
+ *
+ * Throws a TypeError if a network is not a valid CIDR, maxConnections is
+ * not a non-negative integer, a timeout is not greater than zero, or
+ * httpRules (the Rust crate's method and path rules) are given.
+ *
+ * @param {import("./net.js").NetConfig | null} netConfig
+ * @returns {Policy | null}
+ */
+function toPolicy(netConfig) {
+  if (!netConfig) return null;
+  // Requests aren't parsed here, so rules couldn't be enforced.
+  if (netConfig.httpRules?.length) {
+    throw new TypeError("httpRules are not supported by the JavaScript host");
+  }
+  // Copies, so changing the caller's arrays later can't change the policy.
+  const list = (xs, fallback) => Object.freeze([...(xs ?? fallback)]);
+  const next = {
+    allowAllHosts: netConfig.allowAllHosts ?? false,
+    allowedHosts: list(netConfig.allowedHosts, []),
+    blockedHosts: list(netConfig.blockedHosts, DEFAULT_BLOCKED_HOSTS),
+    blockedNetworks: checkCidrs(list(netConfig.blockedNetworks, DEFAULT_BLOCKED_NETWORKS)),
+    allowedNetworks: checkCidrs(list(netConfig.allowedNetworks, [])),
+    internalHosts: list(netConfig.internalHosts, []),
+    maxConnections: checkCount("maxConnections", netConfig.maxConnections ?? DEFAULT_MAX_CONNECTIONS),
+    connectTimeoutMs: checkTimeout("connectTimeoutMs", netConfig.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS),
+    ioTimeoutMs: checkTimeout("ioTimeoutMs", netConfig.ioTimeoutMs ?? DEFAULT_IO_TIMEOUT_MS),
+  };
+  return Object.freeze({ ...next, isAllowed: transport.networkFilter(next) });
+}
+
+/**
+ * Set the default policy (`null` disables networking), which each sandbox
+ * copies when it is created; sandboxes that already exist keep theirs.
+ *
+ * @param {import("./net.js").NetConfig | null} netConfig
+ */
+export function setNetConfig(netConfig) {
+  defaultPolicy = toPolicy(netConfig);
+  defaultNet.setNetConfig(netConfig);
+}
+
+/**
+ * The guest's timeout (`0` for none) clamped to the host's, so sandboxed code
+ * can shorten a timeout but never extend it.
+ */
+// setTimeout fires at once for delays past 2^31 - 1 ms.
+const clamp = (hostMs, guestMs) => Math.min(guestMs ? Math.min(guestMs, hostMs) : hostMs, 2 ** 31 - 1);
+
+/**
+ * `host` in WHATWG URL form (lower-cased, IPv4 in dotted decimal, IPv6
+ * bracketed and compressed) without a trailing dot, or null if it isn't a
+ * bare host name or address.
+ */
+function canonicalHost(host) {
+  // URL parsing would read these as userinfo, path or port delimiters.
+  if (!host || /[\s/?#@\\]/.test(host)) return null;
+  try {
+    return new URL(`http://${host.includes(":") ? `[${host}]` : host}`).hostname.replace(/\.$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/** Glob match with `*` wildcards, case-insensitive (like the Rust matcher). */
+function hostMatches(host, pattern) {
+  const re = pattern
+    .split("*")
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${re}$`, "i").test(host);
+}
+
+const notPermitted = (val) => ({ payload: { tag: "not-permitted", val } });
+
+/** Check `host` against `config` and return its canonical form. */
+function checkHost(config, host) {
+  if (!config) throw notPermitted("networking is disabled; enable it with setNetConfig()");
+  const canonical = canonicalHost(host);
+  if (canonical === null) throw notPermitted(`host '${host}' is not a valid host name`);
+  // Refusals match either spelling; allowances only the canonical one.
+  const matches = (patterns) => patterns.some((p) => hostMatches(canonical, p));
+  if (config.blockedHosts.some((p) => hostMatches(host, p)) || matches(config.blockedHosts)) {
+    throw notPermitted(`host '${host}' is blocked`);
+  }
+  if (!config.allowAllHosts && !matches(config.allowedHosts)) {
+    throw notPermitted(`host '${host}' not in allowed list`);
+  }
+  return { canonical, internal: matches(config.internalHosts) };
+}
+
+/**
+ * The eryx:net imports for one sandbox instance, with its own connection
+ * table and policy. The policy starts as the default set with setNetConfig();
+ * `setNetConfig()` on the result replaces it for this instance only, for
+ * connections opened after the call.
+ *
+ * `closeConnections()` closes every connection the instance's code left open;
+ * the sandbox calls it after each call into the instance.
+ */
+export function createNet() {
+  const t = transport.createTransport();
+  let config = defaultPolicy;
+  const connectTimeout = (ms) => clamp(config?.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS, ms);
+  const ioTimeout = (ms) => clamp(config?.ioTimeoutMs ?? DEFAULT_IO_TIMEOUT_MS, ms);
+  return {
+    tcp: {
+      async connect(host, port, timeoutMs) {
+        const { canonical, internal } = checkHost(config, host);
+        // 0 means no limit, as in the Rust crate.
+        if (config.maxConnections > 0 && t.openConnections() >= config.maxConnections) {
+          throw notPermitted(`connection limit reached (${config.maxConnections})`);
+        }
+        // The transport checks the address (Node: the resolved addresses)
+        // with this; internal hosts skip it.
+        const isAllowed = internal ? null : config.isAllowed;
+        // Connect to the form that was checked, unbracketed for the transport.
+        const target = canonical.replace(/^\[(.*)\]$/, "$1");
+        return t.tcp.connect(target, port, connectTimeout(timeoutMs), isAllowed);
+      },
+      read: (h, len, timeoutMs) => t.tcp.read(h, len, ioTimeout(timeoutMs)),
+      write: (h, timeoutMs, data) => t.tcp.write(h, ioTimeout(timeoutMs), data),
+      close: t.tcp.close,
+    },
+    tls: {
+      upgrade: (h, hostname, timeoutMs) => t.tls.upgrade(h, hostname, connectTimeout(timeoutMs)),
+      read: (h, len, timeoutMs) => t.tls.read(h, len, ioTimeout(timeoutMs)),
+      write: (h, timeoutMs, data) => t.tls.write(h, ioTimeout(timeoutMs), data),
+      close: t.tls.close,
+    },
+    closeConnections: t.closeAll,
+    /** @param {import("./net.js").NetConfig | null} netConfig */
+    setNetConfig(netConfig) {
+      config = toPolicy(netConfig);
+    },
+  };
+}
+
+/**
+ * The default instance, for code that imports the shims directly. It follows
+ * setNetConfig().
+ */
+const defaultNet = createNet();
+export const { tcp, tls, closeConnections } = defaultNet;

package/shims/preview2-node.js

@@ -0,0 +1,35 @@
+/**
+ * Node.js entry for the `#preview2/*` package imports.
+ *
+ * Under the "node" export condition, `@bytecodealliance/preview2-shim` resolves to
+ * its Node.js shims, which back WASI with the host filesystem and process and lack
+ * `_setFileData`. The sandbox needs the in-memory browser shims everywhere, so this
+ * loads them by file URL (bypassing the package's export conditions). Browsers and
+ * bundlers take the "default" branch in package.json and import them directly.
+ */
+
+async function load(name) {
+  const url = import.meta.resolve(`@bytecodealliance/preview2-shim/${name}`);
+  if (!url.includes("/dist/nodejs/")) {
+    throw new Error(`unexpected preview2-shim layout: ${url}`);
+  }
+  return import(url.replace("/dist/nodejs/", "/dist/browser/"));
+}
+
+export const {
+  environment,
+  exit,
+  stderr,
+  stdin,
+  stdout,
+  terminalInput,
+  terminalOutput,
+  terminalStderr,
+  terminalStdin,
+  terminalStdout,
+} = await load("cli");
+export const { monotonicClock, wallClock } = await load("clocks");
+export const { preopens, types, _setFileData, createFilesystem, InMemoryFilesystemAdapter } =
+  await load("filesystem");
+export const { error, poll, streams } = await load("io");
+export const { random } = await load("random");

package/shims/raw-json.js

@@ -0,0 +1,111 @@
+/**
+ * A JSON parser that keeps each value's source text.
+ *
+ * Callback replay needs this to store and replay callback results exactly as
+ * they were returned (`1.0` stays a float, large integers stay exact), which
+ * `JSON.parse` cannot do. Journal keys need no parsing: they are the guest's
+ * canonical argument text, used verbatim.
+ */
+
+const SPACE = /\s*/y;
+// Strings are scanned by hand in parseJson (linear by construction, and
+// guest-controlled input never meets a backtracking string pattern).
+const TOKEN =
+  /(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|([{}[\]:,])|(true|false|null)/y;
+
+/**
+ * A parsed JSON value that keeps its source text.
+ * @typedef {Object} JsonNode
+ * @property {"string"|"number"|"literal"|"array"|"object"} kind
+ * @property {*} value - Decoded string, number lexeme, literal text, array of
+ *   nodes, or Map of key to node (duplicate keys: last wins)
+ * @property {string} raw - The node's exact source text
+ */
+
+/**
+ * Parse JSON without losing number lexemes or source text.
+ *
+ * (Not `JSON.parse` with a reviver's `context.source`: besides being missing on
+ * older engines, it intermittently returned wrong keys and no source under
+ * Node 24 during differential testing.)
+ *
+ * @param {string} text - A JSON document
+ * @returns {JsonNode}
+ * @throws {SyntaxError} If `text` is not valid JSON
+ */
+export function parseJson(text) {
+  let pos = 0;
+  // Returns [text consumed, string, number, punctuation, literal].
+  const next = () => {
+    const from = pos;
+    SPACE.lastIndex = pos;
+    SPACE.exec(text);
+    const start = SPACE.lastIndex;
+    if (text[start] === '"') {
+      let end = start + 1;
+      while (end < text.length && text[end] !== '"') {
+        end += text[end] === "\\" ? 2 : 1;
+      }
+      if (end >= text.length) {
+        throw new SyntaxError(`Unterminated string at position ${start}`);
+      }
+      pos = end + 1;
+      return [text.slice(from, pos), text.slice(start, pos)];
+    }
+    TOKEN.lastIndex = start;
+    const m = TOKEN.exec(text);
+    if (!m) throw new SyntaxError(`Invalid JSON at position ${start}`);
+    pos = TOKEN.lastIndex;
+    return [text.slice(from, pos), undefined, m[1], m[2], m[3]];
+  };
+  const expect = (m, punct) => {
+    if (m[3] !== punct) {
+      throw new SyntaxError(`Expected '${punct}' at position ${pos}`);
+    }
+  };
+  const node = (m) => {
+    const start = pos - m[0].trimStart().length;
+    const done = (kind, value) => ({
+      kind,
+      value,
+      raw: text.slice(start, pos),
+    });
+    if (m[1]) return done("string", JSON.parse(m[1]));
+    if (m[2]) return done("number", m[2]);
+    if (m[4]) return done("literal", m[4]);
+    if (m[3] === "[") {
+      const items = [];
+      for (let t = next(); t[3] !== "]";) {
+        if (items.length) {
+          expect(t, ",");
+          t = next();
+        }
+        items.push(node(t));
+        t = next();
+      }
+      return done("array", items);
+    }
+    if (m[3] === "{") {
+      const entries = new Map();
+      let first = true;
+      for (let t = next(); t[3] !== "}"; first = false) {
+        if (!first) {
+          expect(t, ",");
+          t = next();
+        }
+        if (!t[1]) throw new SyntaxError(`Expected a key at position ${pos}`);
+        const key = JSON.parse(t[1]);
+        expect(next(), ":");
+        entries.set(key, node(next()));
+        t = next();
+      }
+      return done("object", entries);
+    }
+    throw new SyntaxError(`Unexpected token at position ${pos}`);
+  };
+  const root = node(next());
+  if (text.slice(pos).trim() !== "") {
+    throw new SyntaxError(`Unexpected data at position ${pos}`);
+  }
+  return root;
+}

package/shims/sockets.js

@@ -0,0 +1,53 @@
+/**
+ * Sockets shims for the eryx sandbox.
+ *
+ * The Python sandbox imports wasi:sockets/* but doesn't actually use them
+ * (networking goes through eryx:net/tcp and eryx:net/tls instead).
+ * These stubs satisfy the imports without providing real functionality.
+ */
+
+class ResolveAddressStream {}
+class TcpSocket {}
+class UdpSocket {}
+class IncomingDatagramStream {}
+class OutgoingDatagramStream {}
+class Network {}
+
+export const instanceNetwork = {
+  instanceNetwork() {
+    return new Network();
+  },
+};
+
+export const ipNameLookup = {
+  ResolveAddressStream,
+  resolveAddresses() {
+    throw new Error("networking not available in sandbox");
+  },
+};
+
+export const network = {
+  Network,
+};
+
+export const tcpCreateSocket = {
+  createTcpSocket() {
+    throw new Error("networking not available in sandbox");
+  },
+};
+
+export const tcp = {
+  TcpSocket,
+};
+
+export const udpCreateSocket = {
+  createUdpSocket() {
+    throw new Error("networking not available in sandbox");
+  },
+};
+
+export const udp = {
+  UdpSocket,
+  IncomingDatagramStream,
+  OutgoingDatagramStream,
+};

package/stdlib-loader.js

@@ -0,0 +1,174 @@
+/**
+ * Python stdlib loader for browser/Node.js environments.
+ *
+ * Fetches python-stdlib.tar.gz, decompresses it, parses the tar archive,
+ * and returns a file tree compatible with the @bytecodealliance/preview2-shim
+ * filesystem.
+ */
+
+/**
+ * Parse a tar archive from a Uint8Array into a preview2-shim file tree.
+ *
+ * @param {Uint8Array} tarData - Raw tar file bytes
+ * @returns {object} File tree with { dir: { ... } } structure
+ */
+function parseTar(tarData) {
+  const root = { dir: {} };
+  let offset = 0;
+
+  while (offset + 512 <= tarData.length) {
+    // Read 512-byte header
+    const header = tarData.subarray(offset, offset + 512);
+
+    // Check for end-of-archive (two consecutive zero blocks)
+    if (header.every((b) => b === 0)) break;
+
+    // Extract filename: prefix (bytes 345-499) + name (bytes 0-99)
+    const prefix = readString(header, 345, 155);
+    const name = readString(header, 0, 100);
+    const fullName = prefix ? `${prefix}/${name}` : name;
+
+    // File size in octal (bytes 124-135)
+    const sizeStr = readString(header, 124, 12);
+    const size = parseInt(sizeStr, 8) || 0;
+
+    // Type flag (byte 156): '0' or '\0' = file, '5' = directory
+    const typeFlag = header[156];
+
+    offset += 512; // Move past header
+
+    if (fullName && fullName !== "pax_global_header") {
+      // Normalize path: strip leading ./ and trailing /
+      const cleanPath = fullName.replace(/^\.\//, "").replace(/\/$/, "");
+
+      if (cleanPath) {
+        if (typeFlag === 53 /* '5' = directory */) {
+          ensureDir(root, cleanPath);
+        } else if (
+          typeFlag === 48 /* '0' = regular file */ ||
+          typeFlag === 0 /* '\0' = regular file (old format) */
+        ) {
+          const content = tarData.slice(offset, offset + size);
+          setFile(root, cleanPath, content);
+        }
+      }
+    }
+
+    // Advance past file data (padded to 512-byte boundary)
+    offset += Math.ceil(size / 512) * 512;
+  }
+
+  return root;
+}
+
+/** Read a null-terminated string from a buffer at the given offset. */
+function readString(buf, start, maxLen) {
+  let end = start;
+  while (end < start + maxLen && buf[end] !== 0) end++;
+  return new TextDecoder().decode(buf.subarray(start, end));
+}
+
+/** Ensure a directory path exists in the file tree. */
+function ensureDir(root, path) {
+  const parts = path.split("/");
+  let current = root;
+  for (const part of parts) {
+    if (!part) continue;
+    if (!current.dir) current.dir = {};
+    if (!current.dir[part]) current.dir[part] = { dir: {} };
+    current = current.dir[part];
+  }
+  return current;
+}
+
+/** Set a file at the given path in the file tree. */
+function setFile(root, path, content) {
+  const parts = path.split("/");
+  const fileName = parts.pop();
+  const dir = parts.length > 0 ? ensureDir(root, parts.join("/")) : root;
+  if (!dir.dir) dir.dir = {};
+  dir.dir[fileName] = { source: content };
+}
+
+/**
+ * Read and decompress the stdlib tar.gz in Node.js using fs and zlib.
+ * @param {string} filePath - Absolute path to the tar.gz file
+ * @returns {Promise<Uint8Array>} Decompressed tar data
+ */
+async function loadTarGzNode(filePath) {
+  const { readFileSync } = await import(/* webpackIgnore: true */ "node:fs");
+  const { gunzipSync } = await import(/* webpackIgnore: true */ "node:zlib");
+  const compressed = readFileSync(filePath);
+  return gunzipSync(compressed);
+}
+
+/**
+ * Read and decompress the stdlib tar.gz in the browser using fetch + DecompressionStream.
+ * @param {string} url - URL to the tar.gz file
+ * @returns {Promise<Uint8Array>} Decompressed tar data
+ */
+async function loadTarGzBrowser(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch Python stdlib: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  if (typeof DecompressionStream !== "undefined") {
+    const ds = new DecompressionStream("gzip");
+    const decompressed = response.body.pipeThrough(ds);
+    const reader = decompressed.getReader();
+    const chunks = [];
+    let totalLen = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      totalLen += value.length;
+    }
+    const tarData = new Uint8Array(totalLen);
+    let pos = 0;
+    for (const chunk of chunks) {
+      tarData.set(chunk, pos);
+      pos += chunk.length;
+    }
+    return tarData;
+  }
+
+  // Fallback: try node:zlib
+  const buf = new Uint8Array(await response.arrayBuffer());
+  const { gunzipSync } = await import(/* webpackIgnore: true */ "node:zlib");
+  return gunzipSync(buf);
+}
+
+/**
+ * Fetch and decompress python-stdlib.tar.gz, returning a file tree.
+ *
+ * @param {string|URL} [url] - URL to python-stdlib.tar.gz. Defaults to
+ *   './python-stdlib.tar.gz' relative to this module.
+ * @returns {Promise<object>} File tree with { dir: { ... } } structure
+ */
+export async function loadStdlib(url) {
+  const stdlibUrl =
+    url || new URL("./python-stdlib.tar.gz", import.meta.url).href;
+
+  let tarData;
+
+  // In Node.js, use fs + zlib for file:// URLs (fetch doesn't support file://)
+  const isNode =
+    typeof globalThis.process !== "undefined" &&
+    typeof globalThis.process.versions?.node !== "undefined";
+
+  if (isNode && stdlibUrl.startsWith("file://")) {
+    const { fileURLToPath } = await import(
+      /* webpackIgnore: true */ "node:url"
+    );
+    const filePath = fileURLToPath(stdlibUrl);
+    tarData = await loadTarGzNode(filePath);
+  } else {
+    tarData = await loadTarGzBrowser(stdlibUrl);
+  }
+
+  return parseTar(tarData);
+}