@sandblocks/sdk 0.1.0

package/dist/output.js

@@ -0,0 +1,54 @@
+// src/output.ts
+var Output = {
+  string(input) {
+    return { kind: "string", tag: validTag(input.tag) };
+  },
+  object(input) {
+    return { kind: "object", tag: validTag(input.tag), schema: input.schema };
+  }
+};
+async function extractOutput(spec, text) {
+  const pattern = new RegExp(`<${escapeRegex(spec.tag)}>([\\s\\S]*?)<\\/${escapeRegex(spec.tag)}>`);
+  const match = text.match(pattern);
+  if (!match)
+    throw new Error(`structured output tag <${spec.tag}> was not found`);
+  const content = match[1]?.trim();
+  if (content === undefined)
+    throw new Error(`structured output tag <${spec.tag}> is empty`);
+  if (spec.kind === "string")
+    return content;
+  let value;
+  try {
+    value = JSON.parse(content);
+  } catch {
+    throw new Error(`structured output <${spec.tag}> is not valid JSON`);
+  }
+  const schema = spec.schema;
+  if (schema["~standard"]) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues?.length)
+      throw new Error(`structured output validation failed: ${JSON.stringify(result.issues)}`);
+    return result.value;
+  }
+  if (schema.safeParse) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+      throw new Error(`structured output validation failed: ${String(result.error)}`);
+    return result.data;
+  }
+  if (schema.parse)
+    return schema.parse(value);
+  throw new Error("structured output schema is unsupported");
+}
+function validTag(tag) {
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(tag))
+    throw new Error("output tag is invalid");
+  return tag;
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export {
+  extractOutput,
+  Output
+};

package/dist/providers/custom.js

@@ -0,0 +1,49 @@
+// src/providers/custom.ts
+function createSandboxProvider(options) {
+  if (!/^[a-z][a-z0-9-]{0,62}$/.test(options.kind))
+    throw new Error("custom provider kind is invalid");
+  const reconnect = options.reconnect;
+  return {
+    kind: options.kind,
+    capabilities: Object.freeze({ ...options.capabilities }),
+    create: (input) => options.create(input),
+    ...reconnect ? { reconnect: (input) => reconnect(input) } : {}
+  };
+}
+function createBindMountSandboxProvider(options) {
+  return createSandboxProvider({
+    ...options,
+    capabilities: {
+      bindMounts: true,
+      isolatedFilesystem: true,
+      persistent: true,
+      networks: false,
+      devices: false,
+      snapshots: false,
+      reconnect: Boolean(options.reconnect),
+      remote: false,
+      ...options.capabilities
+    }
+  });
+}
+function createIsolatedSandboxProvider(options) {
+  return createSandboxProvider({
+    ...options,
+    capabilities: {
+      bindMounts: false,
+      isolatedFilesystem: true,
+      persistent: true,
+      networks: true,
+      devices: false,
+      snapshots: false,
+      reconnect: Boolean(options.reconnect),
+      remote: true,
+      ...options.capabilities
+    }
+  });
+}
+export {
+  createSandboxProvider,
+  createIsolatedSandboxProvider,
+  createBindMountSandboxProvider
+};

package/dist/providers/docker.js

@@ -0,0 +1,257 @@
+// src/providers/oci.ts
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+// src/process.ts
+import { spawn } from "node:child_process";
+async function executeProcess(command, options = {}) {
+  if (!command.length || command.some((part) => !part || part.includes("\x00"))) {
+    throw new Error("command must contain safe non-empty arguments");
+  }
+  const startedAt = new Date().toISOString();
+  const [executable, ...args] = command;
+  if (!executable)
+    throw new Error("command executable is required");
+  const child = spawn(executable, args, {
+    cwd: options.cwd ?? options.hostCwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"]
+  });
+  if (options.stdin !== undefined)
+    child.stdin?.end(options.stdin);
+  let timedOut = false;
+  let stdout = "";
+  let stderr = "";
+  let callbackQueue = Promise.resolve();
+  child.stdout?.on("data", (chunk) => {
+    const text = chunk.toString();
+    stdout = `${stdout}${text}`.slice(-4 * 1024 * 1024);
+    callbackQueue = callbackQueue.then(() => options.onStdout?.(text)).then(() => {
+      return;
+    });
+  });
+  child.stderr?.on("data", (chunk) => {
+    const text = chunk.toString();
+    stderr = `${stderr}${text}`.slice(-4 * 1024 * 1024);
+    callbackQueue = callbackQueue.then(() => options.onStderr?.(text)).then(() => {
+      return;
+    });
+  });
+  const stop = () => child.kill("SIGTERM");
+  options.signal?.addEventListener("abort", stop, { once: true });
+  const timer = options.timeoutMs ? setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGKILL");
+  }, options.timeoutMs) : undefined;
+  try {
+    const exitCode = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+    await callbackQueue;
+    if (options.signal?.aborted)
+      throw options.signal.reason ?? new Error("operation aborted");
+    return {
+      exitCode: timedOut ? 124 : exitCode,
+      stdout,
+      stderr,
+      timedOut,
+      startedAt,
+      finishedAt: new Date().toISOString()
+    };
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    options.signal?.removeEventListener("abort", stop);
+  }
+}
+function expandHome(path) {
+  if (path === "~")
+    return process.env.HOME ?? path;
+  if (path.startsWith("~/"))
+    return `${process.env.HOME ?? "~"}/${path.slice(2)}`;
+  return path;
+}
+
+// src/providers/oci.ts
+var capabilities = {
+  bindMounts: true,
+  isolatedFilesystem: true,
+  persistent: true,
+  networks: true,
+  devices: true,
+  snapshots: false,
+  reconnect: true,
+  remote: false
+};
+
+class OciProvider {
+  capabilities = capabilities;
+  kind;
+  options;
+  binary;
+  constructor(kind, options = {}) {
+    this.kind = kind;
+    this.options = options;
+    this.binary = options.binary ?? kind;
+  }
+  async create(input) {
+    await this.preflight();
+    const cwd = await realpath(input.cwd);
+    const image = input.image ?? this.options.image;
+    if (!image)
+      throw new Error(`${this.kind} provider requires an image`);
+    if (!(this.options.allowUnpinnedImages ?? true) && !image.includes("@sha256:")) {
+      throw new Error("OCI image must be digest-pinned unless allowUnpinnedImages is enabled");
+    }
+    const id = safeName(input.id);
+    const existing = await this.inspect(id);
+    if (existing) {
+      await this.command(["start", id], { signal: input.signal, timeoutMs: 30000 }, true);
+      return this.runtime(id, cwd);
+    }
+    const uid = this.options.containerUid ?? (typeof process.getuid === "function" ? process.getuid() : 1000);
+    const gid = this.options.containerGid ?? (typeof process.getgid === "function" ? process.getgid() : 1000);
+    const networks = array(input.network ?? this.options.network ?? "none");
+    const args = [
+      "create",
+      "--name",
+      id,
+      "--label",
+      "sandblocks.sdk.managed=true",
+      "--label",
+      `sandblocks.sdk.id=${id}`,
+      "--user",
+      `${uid}:${gid}`,
+      "--cap-drop",
+      "ALL",
+      "--security-opt",
+      "no-new-privileges",
+      "--pids-limit",
+      String(input.pids ?? this.options.pids ?? 256),
+      "--memory",
+      `${input.memoryMb ?? this.options.memoryMb ?? 4096}m`,
+      "--cpus",
+      String(input.cpus ?? this.options.cpus ?? 2),
+      "--network",
+      networks[0] ?? "none",
+      "--tmpfs",
+      `/tmp:rw,nosuid,nodev,exec,size=${input.tmpfsMb ?? this.options.tmpfsMb ?? 512}m`,
+      "--workdir",
+      "/workspace"
+    ];
+    if (this.options.readOnlyRoot !== false)
+      args.push("--read-only");
+    const rootMount = { source: cwd, target: "/workspace" };
+    for (const mount of [rootMount, ...this.options.mounts ?? [], ...input.mounts ?? []]) {
+      if (!mount.source)
+        throw new Error("local OCI mounts require source");
+      const source = resolve(cwd, expandHome(mount.source));
+      const target = mount.target.startsWith("/") ? mount.target : resolve("/workspace", mount.target);
+      const label = this.options.selinuxLabel === false ? "" : `,${this.options.selinuxLabel ?? "z"}`;
+      args.push("--volume", `${source}:${target}:${mount.readonly ? "ro" : "rw"}${label}`);
+    }
+    for (const [key, value] of Object.entries({ ...this.options.env, ...input.env })) {
+      assertEnv(key, value);
+      args.push("--env", `${key}=${value}`);
+    }
+    for (const group of [...this.options.groups ?? [], ...input.groups ?? []])
+      args.push("--group-add", String(group));
+    for (const device of [...this.options.devices ?? [], ...input.devices ?? []])
+      args.push("--device", device);
+    for (const [key, value] of Object.entries(input.metadata ?? {}))
+      args.push("--label", `sandblocks.sdk.${safeLabel(key)}=${safeLabel(value)}`);
+    args.push(image, ...this.options.idleCommand ?? ["sh", "-lc", "trap : TERM INT; sleep infinity & wait"]);
+    await this.command(args, { signal: input.signal, timeoutMs: 60000 });
+    await this.command(["start", id], { signal: input.signal, timeoutMs: 30000 });
+    for (const network of networks.slice(1))
+      await this.command(["network", "connect", network, id], { signal: input.signal });
+    return this.runtime(id, cwd);
+  }
+  async reconnect(input) {
+    const id = safeName(input.id);
+    if (!await this.inspect(id))
+      throw new Error(`sandbox '${id}' was not found`);
+    await this.command(["start", id], { signal: input.signal, timeoutMs: 30000 }, true);
+    return this.runtime(id, resolve(input.cwd ?? process.cwd()));
+  }
+  runtime(id, cwd) {
+    return {
+      id,
+      provider: this.kind,
+      cwd,
+      exec: async (command, options = {}) => {
+        const args = ["exec"];
+        if (options.stdin !== undefined)
+          args.push("-i");
+        args.push("--workdir", options.cwd ?? "/workspace");
+        for (const [key, value] of Object.entries(options.env ?? {})) {
+          assertEnv(key, value);
+          args.push("--env", `${key}=${value}`);
+        }
+        args.push(id, ...command);
+        return this.command(args, options);
+      },
+      upload: async (source, destination) => {
+        await this.command(["cp", resolve(cwd, source), `${id}:${destination}`]);
+      },
+      download: async (source, destination) => {
+        await this.command(["cp", `${id}:${source}`, resolve(cwd, destination)]);
+      },
+      stop: async () => {
+        await this.command(["kill", id], {}, true);
+      },
+      destroy: async () => {
+        await this.command(["rm", "-f", "-v", id], {}, true);
+      }
+    };
+  }
+  async command(args, options = {}, allowFailure = false) {
+    const result = this.options.commandRunner ? await this.options.commandRunner([this.binary, ...args], options) : await executeProcess([this.binary, ...args], options);
+    if (result.exitCode !== 0 && !allowFailure) {
+      throw new Error(`${this.kind} ${args[0]} failed (${result.exitCode}): ${(result.stderr || result.stdout).slice(-2000)}`);
+    }
+    return result;
+  }
+  async inspect(id) {
+    return (await this.command(["inspect", id], { timeoutMs: 15000 }, true)).exitCode === 0;
+  }
+  async preflight() {
+    const result = this.kind === "docker" ? await this.command(["info", "--format", "{{json .SecurityOptions}}"], { timeoutMs: 15000 }, true) : await this.command(["info", "--format", "{{.Host.Security.Rootless}}"], { timeoutMs: 15000 }, true);
+    if (result.exitCode !== 0)
+      throw new Error(`${this.kind} runtime is unavailable`);
+    if (this.options.rootless !== false && !/rootless|true/i.test(result.stdout)) {
+      throw new Error(`${this.kind} provider requires a rootless runtime`);
+    }
+  }
+}
+function array(value) {
+  return Array.isArray(value) ? value : [value];
+}
+function safeName(value) {
+  const name = `sandblocks-sdk-${value}`.toLowerCase().replace(/[^a-z0-9_.-]/g, "-").slice(0, 120);
+  if (name.length < 3)
+    throw new Error("sandbox id is invalid");
+  return name;
+}
+function safeLabel(value) {
+  return value.replace(/[^A-Za-z0-9_.:/@+-]/g, "_").slice(0, 200);
+}
+function assertEnv(key, value) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || value.includes("\x00"))
+    throw new Error("sandbox environment is invalid");
+}
+
+// src/providers/docker.ts
+class DockerProvider extends OciProvider {
+  constructor(options = {}) {
+    super("docker", options);
+  }
+}
+function docker(options = {}) {
+  return new DockerProvider(options);
+}
+export {
+  docker,
+  DockerProvider
+};

package/dist/providers/podman.js

@@ -0,0 +1,257 @@
+// src/providers/oci.ts
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+// src/process.ts
+import { spawn } from "node:child_process";
+async function executeProcess(command, options = {}) {
+  if (!command.length || command.some((part) => !part || part.includes("\x00"))) {
+    throw new Error("command must contain safe non-empty arguments");
+  }
+  const startedAt = new Date().toISOString();
+  const [executable, ...args] = command;
+  if (!executable)
+    throw new Error("command executable is required");
+  const child = spawn(executable, args, {
+    cwd: options.cwd ?? options.hostCwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"]
+  });
+  if (options.stdin !== undefined)
+    child.stdin?.end(options.stdin);
+  let timedOut = false;
+  let stdout = "";
+  let stderr = "";
+  let callbackQueue = Promise.resolve();
+  child.stdout?.on("data", (chunk) => {
+    const text = chunk.toString();
+    stdout = `${stdout}${text}`.slice(-4 * 1024 * 1024);
+    callbackQueue = callbackQueue.then(() => options.onStdout?.(text)).then(() => {
+      return;
+    });
+  });
+  child.stderr?.on("data", (chunk) => {
+    const text = chunk.toString();
+    stderr = `${stderr}${text}`.slice(-4 * 1024 * 1024);
+    callbackQueue = callbackQueue.then(() => options.onStderr?.(text)).then(() => {
+      return;
+    });
+  });
+  const stop = () => child.kill("SIGTERM");
+  options.signal?.addEventListener("abort", stop, { once: true });
+  const timer = options.timeoutMs ? setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGKILL");
+  }, options.timeoutMs) : undefined;
+  try {
+    const exitCode = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+    await callbackQueue;
+    if (options.signal?.aborted)
+      throw options.signal.reason ?? new Error("operation aborted");
+    return {
+      exitCode: timedOut ? 124 : exitCode,
+      stdout,
+      stderr,
+      timedOut,
+      startedAt,
+      finishedAt: new Date().toISOString()
+    };
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    options.signal?.removeEventListener("abort", stop);
+  }
+}
+function expandHome(path) {
+  if (path === "~")
+    return process.env.HOME ?? path;
+  if (path.startsWith("~/"))
+    return `${process.env.HOME ?? "~"}/${path.slice(2)}`;
+  return path;
+}
+
+// src/providers/oci.ts
+var capabilities = {
+  bindMounts: true,
+  isolatedFilesystem: true,
+  persistent: true,
+  networks: true,
+  devices: true,
+  snapshots: false,
+  reconnect: true,
+  remote: false
+};
+
+class OciProvider {
+  capabilities = capabilities;
+  kind;
+  options;
+  binary;
+  constructor(kind, options = {}) {
+    this.kind = kind;
+    this.options = options;
+    this.binary = options.binary ?? kind;
+  }
+  async create(input) {
+    await this.preflight();
+    const cwd = await realpath(input.cwd);
+    const image = input.image ?? this.options.image;
+    if (!image)
+      throw new Error(`${this.kind} provider requires an image`);
+    if (!(this.options.allowUnpinnedImages ?? true) && !image.includes("@sha256:")) {
+      throw new Error("OCI image must be digest-pinned unless allowUnpinnedImages is enabled");
+    }
+    const id = safeName(input.id);
+    const existing = await this.inspect(id);
+    if (existing) {
+      await this.command(["start", id], { signal: input.signal, timeoutMs: 30000 }, true);
+      return this.runtime(id, cwd);
+    }
+    const uid = this.options.containerUid ?? (typeof process.getuid === "function" ? process.getuid() : 1000);
+    const gid = this.options.containerGid ?? (typeof process.getgid === "function" ? process.getgid() : 1000);
+    const networks = array(input.network ?? this.options.network ?? "none");
+    const args = [
+      "create",
+      "--name",
+      id,
+      "--label",
+      "sandblocks.sdk.managed=true",
+      "--label",
+      `sandblocks.sdk.id=${id}`,
+      "--user",
+      `${uid}:${gid}`,
+      "--cap-drop",
+      "ALL",
+      "--security-opt",
+      "no-new-privileges",
+      "--pids-limit",
+      String(input.pids ?? this.options.pids ?? 256),
+      "--memory",
+      `${input.memoryMb ?? this.options.memoryMb ?? 4096}m`,
+      "--cpus",
+      String(input.cpus ?? this.options.cpus ?? 2),
+      "--network",
+      networks[0] ?? "none",
+      "--tmpfs",
+      `/tmp:rw,nosuid,nodev,exec,size=${input.tmpfsMb ?? this.options.tmpfsMb ?? 512}m`,
+      "--workdir",
+      "/workspace"
+    ];
+    if (this.options.readOnlyRoot !== false)
+      args.push("--read-only");
+    const rootMount = { source: cwd, target: "/workspace" };
+    for (const mount of [rootMount, ...this.options.mounts ?? [], ...input.mounts ?? []]) {
+      if (!mount.source)
+        throw new Error("local OCI mounts require source");
+      const source = resolve(cwd, expandHome(mount.source));
+      const target = mount.target.startsWith("/") ? mount.target : resolve("/workspace", mount.target);
+      const label = this.options.selinuxLabel === false ? "" : `,${this.options.selinuxLabel ?? "z"}`;
+      args.push("--volume", `${source}:${target}:${mount.readonly ? "ro" : "rw"}${label}`);
+    }
+    for (const [key, value] of Object.entries({ ...this.options.env, ...input.env })) {
+      assertEnv(key, value);
+      args.push("--env", `${key}=${value}`);
+    }
+    for (const group of [...this.options.groups ?? [], ...input.groups ?? []])
+      args.push("--group-add", String(group));
+    for (const device of [...this.options.devices ?? [], ...input.devices ?? []])
+      args.push("--device", device);
+    for (const [key, value] of Object.entries(input.metadata ?? {}))
+      args.push("--label", `sandblocks.sdk.${safeLabel(key)}=${safeLabel(value)}`);
+    args.push(image, ...this.options.idleCommand ?? ["sh", "-lc", "trap : TERM INT; sleep infinity & wait"]);
+    await this.command(args, { signal: input.signal, timeoutMs: 60000 });
+    await this.command(["start", id], { signal: input.signal, timeoutMs: 30000 });
+    for (const network of networks.slice(1))
+      await this.command(["network", "connect", network, id], { signal: input.signal });
+    return this.runtime(id, cwd);
+  }
+  async reconnect(input) {
+    const id = safeName(input.id);
+    if (!await this.inspect(id))
+      throw new Error(`sandbox '${id}' was not found`);
+    await this.command(["start", id], { signal: input.signal, timeoutMs: 30000 }, true);
+    return this.runtime(id, resolve(input.cwd ?? process.cwd()));
+  }
+  runtime(id, cwd) {
+    return {
+      id,
+      provider: this.kind,
+      cwd,
+      exec: async (command, options = {}) => {
+        const args = ["exec"];
+        if (options.stdin !== undefined)
+          args.push("-i");
+        args.push("--workdir", options.cwd ?? "/workspace");
+        for (const [key, value] of Object.entries(options.env ?? {})) {
+          assertEnv(key, value);
+          args.push("--env", `${key}=${value}`);
+        }
+        args.push(id, ...command);
+        return this.command(args, options);
+      },
+      upload: async (source, destination) => {
+        await this.command(["cp", resolve(cwd, source), `${id}:${destination}`]);
+      },
+      download: async (source, destination) => {
+        await this.command(["cp", `${id}:${source}`, resolve(cwd, destination)]);
+      },
+      stop: async () => {
+        await this.command(["kill", id], {}, true);
+      },
+      destroy: async () => {
+        await this.command(["rm", "-f", "-v", id], {}, true);
+      }
+    };
+  }
+  async command(args, options = {}, allowFailure = false) {
+    const result = this.options.commandRunner ? await this.options.commandRunner([this.binary, ...args], options) : await executeProcess([this.binary, ...args], options);
+    if (result.exitCode !== 0 && !allowFailure) {
+      throw new Error(`${this.kind} ${args[0]} failed (${result.exitCode}): ${(result.stderr || result.stdout).slice(-2000)}`);
+    }
+    return result;
+  }
+  async inspect(id) {
+    return (await this.command(["inspect", id], { timeoutMs: 15000 }, true)).exitCode === 0;
+  }
+  async preflight() {
+    const result = this.kind === "docker" ? await this.command(["info", "--format", "{{json .SecurityOptions}}"], { timeoutMs: 15000 }, true) : await this.command(["info", "--format", "{{.Host.Security.Rootless}}"], { timeoutMs: 15000 }, true);
+    if (result.exitCode !== 0)
+      throw new Error(`${this.kind} runtime is unavailable`);
+    if (this.options.rootless !== false && !/rootless|true/i.test(result.stdout)) {
+      throw new Error(`${this.kind} provider requires a rootless runtime`);
+    }
+  }
+}
+function array(value) {
+  return Array.isArray(value) ? value : [value];
+}
+function safeName(value) {
+  const name = `sandblocks-sdk-${value}`.toLowerCase().replace(/[^a-z0-9_.-]/g, "-").slice(0, 120);
+  if (name.length < 3)
+    throw new Error("sandbox id is invalid");
+  return name;
+}
+function safeLabel(value) {
+  return value.replace(/[^A-Za-z0-9_.:/@+-]/g, "_").slice(0, 200);
+}
+function assertEnv(key, value) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || value.includes("\x00"))
+    throw new Error("sandbox environment is invalid");
+}
+
+// src/providers/podman.ts
+class PodmanProvider extends OciProvider {
+  constructor(options = {}) {
+    super("podman", options);
+  }
+}
+function podman(options = {}) {
+  return new PodmanProvider(options);
+}
+export {
+  podman,
+  PodmanProvider
+};