@agentforge-ai/sandbox 0.6.0

package/dist/docker-sandbox.d.ts

@@ -0,0 +1,92 @@
+import Dockerode from 'dockerode';
+import { SandboxProvider, DockerSandboxConfig, ExecOptions, ExecResult } from './types.js';
+
+/**
+ * @module docker-sandbox
+ *
+ * DockerSandbox — a container-backed {@link SandboxProvider} for AgentForge.
+ *
+ * Each instance manages exactly one Docker container. The container is
+ * created lazily on the first call to {@link DockerSandbox.start}, executed
+ * via the Docker exec API, and destroyed via {@link DockerSandbox.destroy}.
+ *
+ * @example
+ * ```ts
+ * const sandbox = new DockerSandbox({
+ *   scope: 'agent',
+ *   workspaceAccess: 'ro',
+ *   workspacePath: '/home/user/project',
+ *   resourceLimits: { memoryMb: 512, cpuShares: 512 },
+ * });
+ * await sandbox.start();
+ * const result = await sandbox.exec('echo hello');
+ * console.log(result.stdout); // "hello\n"
+ * await sandbox.destroy();
+ * ```
+ */
+
+/**
+ * Container-based sandbox using the Docker engine.
+ *
+ * Implements the {@link SandboxProvider} interface for full lifecycle
+ * management, command execution, and file I/O within an isolated container.
+ */
+declare class DockerSandbox implements SandboxProvider {
+    private readonly config;
+    private readonly docker;
+    private container;
+    private containerId;
+    private killTimer;
+    /**
+     * @param config - Sandbox configuration.
+     * @param docker - Optional pre-configured Dockerode instance (useful in tests).
+     */
+    constructor(config: DockerSandboxConfig, docker?: Dockerode);
+    /**
+     * Create and start the Docker container.
+     * Idempotent — calling start() on an already-running sandbox is a no-op.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the container gracefully (10 s grace period then SIGKILL).
+     * The container is kept for potential restart.
+     */
+    stop(): Promise<void>;
+    /**
+     * Destroy the container and release all resources.
+     * Safe to call multiple times.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Execute a shell command inside the running container.
+     *
+     * @param command - Shell command string passed to `/bin/sh -c`.
+     * @param options - Per-call options (timeout, cwd, env overrides).
+     */
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Read a file from the container filesystem by running `cat`.
+     *
+     * @param path - Absolute path inside the container.
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Write content to a file inside the container using base64 encoding
+     * to avoid shell quoting issues.
+     *
+     * @param path    - Absolute path inside the container.
+     * @param content - UTF-8 string content.
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Returns true if the underlying Docker container is running.
+     */
+    isRunning(): Promise<boolean>;
+    /**
+     * Returns the Docker container ID or null if not yet started.
+     */
+    getContainerId(): string | null;
+    private _clearKillTimer;
+}
+
+export { DockerSandbox };

package/dist/docker-sandbox.js

@@ -0,0 +1,343 @@
+// src/docker-sandbox.ts
+import Dockerode from "dockerode";
+import { randomUUID } from "crypto";
+
+// src/security.ts
+var BLOCKED_BIND_PREFIXES = [
+  "/var/run/docker.sock",
+  "/etc",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/boot",
+  "/root"
+];
+var DEFAULT_CAP_DROP = ["ALL"];
+var BASE_ALLOWED_IMAGE_PREFIXES = [
+  "node:",
+  "python:",
+  "ubuntu:",
+  "debian:",
+  "alpine:",
+  "agentforge/"
+];
+function validateBind(bind) {
+  const hostPath = bind.split(":")[0];
+  if (!hostPath) {
+    throw new SecurityError(`Invalid bind mount spec: "${bind}"`);
+  }
+  for (const blocked of BLOCKED_BIND_PREFIXES) {
+    if (hostPath === blocked || hostPath.startsWith(blocked + "/") || hostPath.startsWith(blocked)) {
+      throw new SecurityError(
+        `Bind mount "${bind}" is blocked. Host path "${hostPath}" matches blocked prefix "${blocked}".`
+      );
+    }
+  }
+}
+function validateBinds(binds) {
+  for (const bind of binds) {
+    validateBind(bind);
+  }
+}
+function validateImageName(image) {
+  if (!image || typeof image !== "string") {
+    throw new SecurityError("Image name must be a non-empty string.");
+  }
+  if (/[;&|`$(){}[\]<>]/.test(image)) {
+    throw new SecurityError(`Image name "${image}" contains forbidden characters.`);
+  }
+  if (process.env["NODE_ENV"] !== "production") {
+    return;
+  }
+  const extraPrefixes = (process.env["AGENTFORGE_ALLOWED_IMAGES"] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const allowedPrefixes = [...BASE_ALLOWED_IMAGE_PREFIXES, ...extraPrefixes];
+  const allowed = allowedPrefixes.some((prefix) => image.startsWith(prefix));
+  if (!allowed) {
+    throw new SecurityError(
+      `Image "${image}" is not on the allow-list. Allowed prefixes: ${allowedPrefixes.join(", ")}. Add custom prefixes via AGENTFORGE_ALLOWED_IMAGES env var.`
+    );
+  }
+}
+function validateCommand(command) {
+  if (!command || typeof command !== "string") {
+    throw new SecurityError("Command must be a non-empty string.");
+  }
+  const dangerousPatterns = [
+    /docker\.sock/i,
+    /nsenter\s/i,
+    /mount\s+-t\s+proc/i
+  ];
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(command)) {
+      throw new SecurityError(
+        `Command contains a potentially dangerous pattern: ${pattern.source}`
+      );
+    }
+  }
+}
+var SecurityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SecurityError";
+  }
+};
+
+// src/docker-sandbox.ts
+var DEFAULT_IMAGE = "node:22-slim";
+var DEFAULT_EXEC_TIMEOUT_MS = 3e4;
+var DEFAULT_CONTAINER_WORKSPACE = "/workspace";
+function demuxDockerStream(buffer) {
+  let stdout = "";
+  let stderr = "";
+  let offset = 0;
+  while (offset + 8 <= buffer.length) {
+    const streamType = buffer[offset];
+    const frameSize = buffer.readUInt32BE(offset + 4);
+    offset += 8;
+    if (offset + frameSize > buffer.length) break;
+    const chunk = buffer.slice(offset, offset + frameSize).toString("utf8");
+    offset += frameSize;
+    if (streamType === 1) {
+      stdout += chunk;
+    } else if (streamType === 2) {
+      stderr += chunk;
+    }
+  }
+  return { stdout, stderr };
+}
+var DockerSandbox = class {
+  config;
+  docker;
+  container = null;
+  containerId = null;
+  killTimer = null;
+  /**
+   * @param config - Sandbox configuration.
+   * @param docker - Optional pre-configured Dockerode instance (useful in tests).
+   */
+  constructor(config, docker) {
+    const image = config.image ?? DEFAULT_IMAGE;
+    validateImageName(image);
+    if (config.binds && config.binds.length > 0) {
+      validateBinds(config.binds);
+    }
+    this.config = {
+      ...config,
+      image,
+      containerWorkspacePath: config.containerWorkspacePath ?? DEFAULT_CONTAINER_WORKSPACE
+    };
+    this.docker = docker ?? new Dockerode(
+      process.env["DOCKER_HOST"] ? { host: process.env["DOCKER_HOST"] } : { socketPath: "/var/run/docker.sock" }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  /**
+   * Create and start the Docker container.
+   * Idempotent — calling start() on an already-running sandbox is a no-op.
+   */
+  async start() {
+    if (this.container) return;
+    const { image, scope, resourceLimits, binds, env, timeout, workspaceAccess, workspacePath, containerWorkspacePath } = this.config;
+    const name = `agentforge-${scope}-${randomUUID().slice(0, 8)}`;
+    const envArray = Object.entries(env ?? {}).map(([k, v]) => `${k}=${v}`);
+    const allBinds = [...binds ?? []];
+    if (workspaceAccess !== "none" && workspacePath) {
+      const mode = workspaceAccess === "ro" ? "ro" : "rw";
+      allBinds.push(`${workspacePath}:${containerWorkspacePath}:${mode}`);
+    }
+    const hostConfig = {
+      // Resource limits
+      CpuShares: resourceLimits?.cpuShares,
+      Memory: resourceLimits?.memoryMb ? resourceLimits.memoryMb * 1024 * 1024 : void 0,
+      PidsLimit: resourceLimits?.pidsLimit ?? 256,
+      // Security hardening
+      CapDrop: [...DEFAULT_CAP_DROP],
+      SecurityOpt: ["no-new-privileges:true"],
+      ReadonlyRootfs: false,
+      // Bind mounts
+      Binds: allBinds.length > 0 ? allBinds : void 0
+    };
+    this.container = await this.docker.createContainer({
+      name,
+      Image: image,
+      // Keep container alive — we run commands via exec
+      Cmd: ["/bin/sh", "-c", "while true; do sleep 3600; done"],
+      Env: envArray,
+      AttachStdin: false,
+      AttachStdout: false,
+      AttachStderr: false,
+      Tty: false,
+      NetworkDisabled: resourceLimits?.networkDisabled ?? false,
+      WorkingDir: containerWorkspacePath,
+      Labels: {
+        "agentforge.scope": scope,
+        "agentforge.managed": "true"
+      },
+      HostConfig: hostConfig
+    });
+    await this.container.start();
+    this.containerId = this.container.id;
+    if (timeout && timeout > 0) {
+      this.killTimer = setTimeout(() => {
+        void this.destroy();
+      }, timeout * 1e3);
+    }
+  }
+  /**
+   * Stop the container gracefully (10 s grace period then SIGKILL).
+   * The container is kept for potential restart.
+   */
+  async stop() {
+    this._clearKillTimer();
+    if (!this.container) return;
+    try {
+      const info = await this.container.inspect();
+      if (info.State.Running) {
+        await this.container.stop({ t: 10 });
+      }
+    } catch {
+    }
+  }
+  /**
+   * Destroy the container and release all resources.
+   * Safe to call multiple times.
+   */
+  async destroy() {
+    this._clearKillTimer();
+    const container = this.container;
+    this.container = null;
+    this.containerId = null;
+    if (!container) return;
+    try {
+      await container.remove({ force: true });
+    } catch {
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Execute a shell command inside the running container.
+   *
+   * @param command - Shell command string passed to `/bin/sh -c`.
+   * @param options - Per-call options (timeout, cwd, env overrides).
+   */
+  async exec(command, options = {}) {
+    if (!this.container) {
+      throw new Error("DockerSandbox: container is not running. Call start() first.");
+    }
+    validateCommand(command);
+    const timeoutMs = options.timeout ?? DEFAULT_EXEC_TIMEOUT_MS;
+    const envOverride = Object.entries(options.env ?? {}).map(([k, v]) => `${k}=${v}`);
+    const execInstance = await this.container.exec({
+      Cmd: ["/bin/sh", "-c", command],
+      AttachStdout: true,
+      AttachStderr: true,
+      Tty: false,
+      WorkingDir: options.cwd,
+      Env: envOverride.length > 0 ? envOverride : void 0
+    });
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`DockerSandbox: exec timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      execInstance.start({ hijack: true, stdin: false }, (err, stream) => {
+        if (err) {
+          clearTimeout(timer);
+          reject(err);
+          return;
+        }
+        if (!stream) {
+          clearTimeout(timer);
+          reject(new Error("DockerSandbox: no stream returned from exec"));
+          return;
+        }
+        const chunks = [];
+        stream.on("data", (chunk) => chunks.push(chunk));
+        stream.on("end", async () => {
+          clearTimeout(timer);
+          try {
+            const raw = Buffer.concat(chunks);
+            const { stdout, stderr } = demuxDockerStream(raw);
+            const inspectResult = await execInstance.inspect();
+            const exitCode = inspectResult.ExitCode ?? 0;
+            resolve({ stdout, stderr, exitCode });
+          } catch (inspectErr) {
+            reject(inspectErr);
+          }
+        });
+        stream.on("error", (streamErr) => {
+          clearTimeout(timer);
+          reject(streamErr);
+        });
+      });
+    });
+  }
+  /**
+   * Read a file from the container filesystem by running `cat`.
+   *
+   * @param path - Absolute path inside the container.
+   */
+  async readFile(path) {
+    const result = await this.exec(`cat "${path.replace(/"/g, '\\"')}"`);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `DockerSandbox.readFile: failed to read "${path}" (exit ${result.exitCode}): ${result.stderr}`
+      );
+    }
+    return result.stdout;
+  }
+  /**
+   * Write content to a file inside the container using base64 encoding
+   * to avoid shell quoting issues.
+   *
+   * @param path    - Absolute path inside the container.
+   * @param content - UTF-8 string content.
+   */
+  async writeFile(path, content) {
+    const b64 = Buffer.from(content, "utf8").toString("base64");
+    const cmd = `printf '%s' "${b64}" | base64 -d > "${path.replace(/"/g, '\\"')}"`;
+    const result = await this.exec(cmd);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `DockerSandbox.writeFile: failed to write "${path}" (exit ${result.exitCode}): ${result.stderr}`
+      );
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Health
+  // ---------------------------------------------------------------------------
+  /**
+   * Returns true if the underlying Docker container is running.
+   */
+  async isRunning() {
+    if (!this.container) return false;
+    try {
+      const info = await this.container.inspect();
+      return info.State.Running === true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Returns the Docker container ID or null if not yet started.
+   */
+  getContainerId() {
+    return this.containerId;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  _clearKillTimer() {
+    if (this.killTimer !== null) {
+      clearTimeout(this.killTimer);
+      this.killTimer = null;
+    }
+  }
+};
+export {
+  DockerSandbox
+};
+//# sourceMappingURL=docker-sandbox.js.map

package/dist/docker-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/docker-sandbox.ts","../src/security.ts"],"sourcesContent":["/**\n * @module docker-sandbox\n *\n * DockerSandbox — a container-backed {@link SandboxProvider} for AgentForge.\n *\n * Each instance manages exactly one Docker container. The container is\n * created lazily on the first call to {@link DockerSandbox.start}, executed\n * via the Docker exec API, and destroyed via {@link DockerSandbox.destroy}.\n *\n * @example\n * ```ts\n * const sandbox = new DockerSandbox({\n *   scope: 'agent',\n *   workspaceAccess: 'ro',\n *   workspacePath: '/home/user/project',\n *   resourceLimits: { memoryMb: 512, cpuShares: 512 },\n * });\n * await sandbox.start();\n * const result = await sandbox.exec('echo hello');\n * console.log(result.stdout); // \"hello\\n\"\n * await sandbox.destroy();\n * ```\n */\n\nimport Dockerode from 'dockerode';\nimport { randomUUID } from 'node:crypto';\nimport type { DockerSandboxConfig, ExecOptions, ExecResult, SandboxProvider } from './types.js';\nimport { DEFAULT_CAP_DROP, SecurityError, validateBinds, validateCommand, validateImageName } from './security.js';\n\n/** Default Docker image used when none is specified. */\nconst DEFAULT_IMAGE = 'node:22-slim';\n\n/** Default per-exec timeout in milliseconds. */\nconst DEFAULT_EXEC_TIMEOUT_MS = 30_000;\n\n/** Default container workspace mount point. */\nconst DEFAULT_CONTAINER_WORKSPACE = '/workspace';\n\n// ---------------------------------------------------------------------------\n// Stream demuxing\n// ---------------------------------------------------------------------------\n\n/**\n * Decodes the multiplexed stream that Docker returns for exec output.\n *\n * Docker prefixes every chunk with an 8-byte header:\n *   [stream_type(1)] [0(3)] [size(4 BE)]\n * where stream_type is 1 = stdout, 2 = stderr.\n */\nfunction demuxDockerStream(buffer: Buffer): { stdout: string; stderr: string } {\n  let stdout = '';\n  let stderr = '';\n  let offset = 0;\n\n  while (offset + 8 <= buffer.length) {\n    const streamType = buffer[offset];\n    const frameSize = buffer.readUInt32BE(offset + 4);\n    offset += 8;\n\n    if (offset + frameSize > buffer.length) break;\n\n    const chunk = buffer.slice(offset, offset + frameSize).toString('utf8');\n    offset += frameSize;\n\n    if (streamType === 1) {\n      stdout += chunk;\n    } else if (streamType === 2) {\n      stderr += chunk;\n    }\n  }\n\n  return { stdout, stderr };\n}\n\n// ---------------------------------------------------------------------------\n// DockerSandbox\n// ---------------------------------------------------------------------------\n\n/**\n * Container-based sandbox using the Docker engine.\n *\n * Implements the {@link SandboxProvider} interface for full lifecycle\n * management, command execution, and file I/O within an isolated container.\n */\nexport class DockerSandbox implements SandboxProvider {\n  private readonly config: Required<\n    Pick<DockerSandboxConfig, 'scope' | 'workspaceAccess' | 'image' | 'containerWorkspacePath'>\n  > &\n    DockerSandboxConfig;\n\n  private readonly docker: Dockerode;\n  private container: Dockerode.Container | null = null;\n  private containerId: string | null = null;\n  private killTimer: ReturnType<typeof setTimeout> | null = null;\n\n  /**\n   * @param config - Sandbox configuration.\n   * @param docker - Optional pre-configured Dockerode instance (useful in tests).\n   */\n  constructor(config: DockerSandboxConfig, docker?: Dockerode) {\n    // Validate security constraints eagerly\n    const image = config.image ?? DEFAULT_IMAGE;\n    validateImageName(image);\n\n    if (config.binds && config.binds.length > 0) {\n      validateBinds(config.binds);\n    }\n\n    this.config = {\n      ...config,\n      image,\n      containerWorkspacePath: config.containerWorkspacePath ?? DEFAULT_CONTAINER_WORKSPACE,\n    };\n\n    this.docker =\n      docker ??\n      new Dockerode(\n        process.env['DOCKER_HOST']\n          ? { host: process.env['DOCKER_HOST'] }\n          : { socketPath: '/var/run/docker.sock' },\n      );\n  }\n\n  // ---------------------------------------------------------------------------\n  // Lifecycle\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Create and start the Docker container.\n   * Idempotent — calling start() on an already-running sandbox is a no-op.\n   */\n  async start(): Promise<void> {\n    if (this.container) return;\n\n    const { image, scope, resourceLimits, binds, env, timeout, workspaceAccess, workspacePath, containerWorkspacePath } = this.config;\n\n    const name = `agentforge-${scope}-${randomUUID().slice(0, 8)}`;\n\n    const envArray = Object.entries(env ?? {}).map(([k, v]) => `${k}=${v}`);\n\n    // Build bind mounts\n    const allBinds: string[] = [...(binds ?? [])];\n\n    // Mount workspace if configured\n    if (workspaceAccess !== 'none' && workspacePath) {\n      const mode = workspaceAccess === 'ro' ? 'ro' : 'rw';\n      allBinds.push(`${workspacePath}:${containerWorkspacePath}:${mode}`);\n    }\n\n    const hostConfig: Dockerode.HostConfig = {\n      // Resource limits\n      CpuShares: resourceLimits?.cpuShares,\n      Memory: resourceLimits?.memoryMb ? resourceLimits.memoryMb * 1024 * 1024 : undefined,\n      PidsLimit: resourceLimits?.pidsLimit ?? 256,\n\n      // Security hardening\n      CapDrop: [...DEFAULT_CAP_DROP],\n      SecurityOpt: ['no-new-privileges:true'],\n      ReadonlyRootfs: false,\n\n      // Bind mounts\n      Binds: allBinds.length > 0 ? allBinds : undefined,\n    };\n\n    this.container = await this.docker.createContainer({\n      name,\n      Image: image,\n      // Keep container alive — we run commands via exec\n      Cmd: ['/bin/sh', '-c', 'while true; do sleep 3600; done'],\n      Env: envArray,\n      AttachStdin: false,\n      AttachStdout: false,\n      AttachStderr: false,\n      Tty: false,\n      NetworkDisabled: resourceLimits?.networkDisabled ?? false,\n      WorkingDir: containerWorkspacePath,\n      Labels: {\n        'agentforge.scope': scope,\n        'agentforge.managed': 'true',\n      },\n      HostConfig: hostConfig,\n    });\n\n    await this.container.start();\n    this.containerId = this.container.id;\n\n    // Auto-kill after configured timeout\n    if (timeout && timeout > 0) {\n      this.killTimer = setTimeout(() => {\n        void this.destroy();\n      }, timeout * 1000);\n    }\n  }\n\n  /**\n   * Stop the container gracefully (10 s grace period then SIGKILL).\n   * The container is kept for potential restart.\n   */\n  async stop(): Promise<void> {\n    this._clearKillTimer();\n    if (!this.container) return;\n\n    try {\n      const info = await this.container.inspect();\n      if (info.State.Running) {\n        await this.container.stop({ t: 10 });\n      }\n    } catch {\n      // Container may already be stopped — ignore\n    }\n  }\n\n  /**\n   * Destroy the container and release all resources.\n   * Safe to call multiple times.\n   */\n  async destroy(): Promise<void> {\n    this._clearKillTimer();\n    const container = this.container;\n    this.container = null;\n    this.containerId = null;\n\n    if (!container) return;\n\n    try {\n      await container.remove({ force: true });\n    } catch {\n      // Already gone — ignore\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // Execution\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Execute a shell command inside the running container.\n   *\n   * @param command - Shell command string passed to `/bin/sh -c`.\n   * @param options - Per-call options (timeout, cwd, env overrides).\n   */\n  async exec(command: string, options: ExecOptions = {}): Promise<ExecResult> {\n    if (!this.container) {\n      throw new Error('DockerSandbox: container is not running. Call start() first.');\n    }\n\n    // Defense-in-depth command validation\n    validateCommand(command);\n\n    const timeoutMs = options.timeout ?? DEFAULT_EXEC_TIMEOUT_MS;\n    const envOverride = Object.entries(options.env ?? {}).map(([k, v]) => `${k}=${v}`);\n\n    const execInstance = await this.container.exec({\n      Cmd: ['/bin/sh', '-c', command],\n      AttachStdout: true,\n      AttachStderr: true,\n      Tty: false,\n      WorkingDir: options.cwd,\n      Env: envOverride.length > 0 ? envOverride : undefined,\n    });\n\n    return new Promise<ExecResult>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        reject(new Error(`DockerSandbox: exec timed out after ${timeoutMs}ms`));\n      }, timeoutMs);\n\n      execInstance.start({ hijack: true, stdin: false }, (err, stream) => {\n        if (err) {\n          clearTimeout(timer);\n          reject(err);\n          return;\n        }\n\n        if (!stream) {\n          clearTimeout(timer);\n          reject(new Error('DockerSandbox: no stream returned from exec'));\n          return;\n        }\n\n        const chunks: Buffer[] = [];\n\n        stream.on('data', (chunk: Buffer) => chunks.push(chunk));\n\n        stream.on('end', async () => {\n          clearTimeout(timer);\n          try {\n            const raw = Buffer.concat(chunks);\n            const { stdout, stderr } = demuxDockerStream(raw);\n\n            // Inspect exec to get exit code\n            const inspectResult = await execInstance.inspect();\n            const exitCode = inspectResult.ExitCode ?? 0;\n\n            resolve({ stdout, stderr, exitCode });\n          } catch (inspectErr) {\n            reject(inspectErr);\n          }\n        });\n\n        stream.on('error', (streamErr: Error) => {\n          clearTimeout(timer);\n          reject(streamErr);\n        });\n      });\n    });\n  }\n\n  /**\n   * Read a file from the container filesystem by running `cat`.\n   *\n   * @param path - Absolute path inside the container.\n   */\n  async readFile(path: string): Promise<string> {\n    const result = await this.exec(`cat \"${path.replace(/\"/g, '\\\\\"')}\"`);\n    if (result.exitCode !== 0) {\n      throw new Error(\n        `DockerSandbox.readFile: failed to read \"${path}\" (exit ${result.exitCode}): ${result.stderr}`,\n      );\n    }\n    return result.stdout;\n  }\n\n  /**\n   * Write content to a file inside the container using base64 encoding\n   * to avoid shell quoting issues.\n   *\n   * @param path    - Absolute path inside the container.\n   * @param content - UTF-8 string content.\n   */\n  async writeFile(path: string, content: string): Promise<void> {\n    const b64 = Buffer.from(content, 'utf8').toString('base64');\n    const cmd = `printf '%s' \"${b64}\" | base64 -d > \"${path.replace(/\"/g, '\\\\\"')}\"`;\n    const result = await this.exec(cmd);\n    if (result.exitCode !== 0) {\n      throw new Error(\n        `DockerSandbox.writeFile: failed to write \"${path}\" (exit ${result.exitCode}): ${result.stderr}`,\n      );\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // Health\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Returns true if the underlying Docker container is running.\n   */\n  async isRunning(): Promise<boolean> {\n    if (!this.container) return false;\n    try {\n      const info = await this.container.inspect();\n      return info.State.Running === true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Returns the Docker container ID or null if not yet started.\n   */\n  getContainerId(): string | null {\n    return this.containerId;\n  }\n\n  // ---------------------------------------------------------------------------\n  // Private helpers\n  // ---------------------------------------------------------------------------\n\n  private _clearKillTimer(): void {\n    if (this.killTimer !== null) {\n      clearTimeout(this.killTimer);\n      this.killTimer = null;\n    }\n  }\n}\n","/**\n * @module security\n *\n * Security helpers for the Docker sandbox implementation.\n *\n * Centralised in one module so policy changes propagate everywhere.\n * All validation functions throw {@link SecurityError} on violations.\n */\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/**\n * Host-side paths that must never be bind-mounted into a sandbox container.\n * Mounting these paths would allow container-escape or privilege escalation.\n */\nexport const BLOCKED_BIND_PREFIXES: readonly string[] = [\n  '/var/run/docker.sock',\n  '/etc',\n  '/proc',\n  '/sys',\n  '/dev',\n  '/boot',\n  '/root',\n];\n\n/**\n * Linux capabilities dropped by default for every sandbox container.\n * We start with no capabilities at all (drop \"ALL\") then add nothing back.\n */\nexport const DEFAULT_CAP_DROP: readonly string[] = ['ALL'];\n\n/**\n * Allowed image name patterns (non-arbitrary image names in production).\n * Only images that match one of these prefixes are permitted.\n * In test / dev the list can be extended via AGENTFORGE_ALLOWED_IMAGES env var.\n */\nconst BASE_ALLOWED_IMAGE_PREFIXES: readonly string[] = [\n  'node:',\n  'python:',\n  'ubuntu:',\n  'debian:',\n  'alpine:',\n  'agentforge/',\n];\n\n// ---------------------------------------------------------------------------\n// Validation functions\n// ---------------------------------------------------------------------------\n\n/**\n * Throws if the provided bind-mount spec contains a blocked host path.\n *\n * @param bind - A bind-mount spec in `host:container[:mode]` format.\n * @throws {SecurityError} when the host path is on the block-list.\n */\nexport function validateBind(bind: string): void {\n  const hostPath = bind.split(':')[0];\n  if (!hostPath) {\n    throw new SecurityError(`Invalid bind mount spec: \"${bind}\"`);\n  }\n\n  for (const blocked of BLOCKED_BIND_PREFIXES) {\n    if (hostPath === blocked || hostPath.startsWith(blocked + '/') || hostPath.startsWith(blocked)) {\n      throw new SecurityError(\n        `Bind mount \"${bind}\" is blocked. Host path \"${hostPath}\" matches blocked prefix \"${blocked}\".`,\n      );\n    }\n  }\n}\n\n/**\n * Validate all bind mounts in the provided array.\n * @throws {SecurityError} on the first violation found.\n */\nexport function validateBinds(binds: string[]): void {\n  for (const bind of binds) {\n    validateBind(bind);\n  }\n}\n\n/**\n * Validate that an image name is on the allow-list.\n *\n * In production (NODE_ENV === 'production') only known safe images are allowed.\n * In development/test any image name that passes format validation is accepted.\n *\n * Additional allowed prefixes can be injected via the\n * `AGENTFORGE_ALLOWED_IMAGES` env var (comma-separated prefixes).\n *\n * @param image - Docker image name, e.g. `node:22-slim`.\n * @throws {SecurityError} if the image is not permitted.\n */\nexport function validateImageName(image: string): void {\n  if (!image || typeof image !== 'string') {\n    throw new SecurityError('Image name must be a non-empty string.');\n  }\n\n  // Reject obviously dangerous patterns (shell metacharacters)\n  if (/[;&|`$(){}[\\]<>]/.test(image)) {\n    throw new SecurityError(`Image name \"${image}\" contains forbidden characters.`);\n  }\n\n  if (process.env['NODE_ENV'] !== 'production') {\n    // In dev/test, just ensure the name is a plausible Docker image reference\n    return;\n  }\n\n  // Build the full allow-list (base + env-configured extras)\n  const extraPrefixes = (process.env['AGENTFORGE_ALLOWED_IMAGES'] ?? '')\n    .split(',')\n    .map((s) => s.trim())\n    .filter(Boolean);\n\n  const allowedPrefixes = [...BASE_ALLOWED_IMAGE_PREFIXES, ...extraPrefixes];\n\n  const allowed = allowedPrefixes.some((prefix) => image.startsWith(prefix));\n  if (!allowed) {\n    throw new SecurityError(\n      `Image \"${image}\" is not on the allow-list. ` +\n        `Allowed prefixes: ${allowedPrefixes.join(', ')}. ` +\n        `Add custom prefixes via AGENTFORGE_ALLOWED_IMAGES env var.`,\n    );\n  }\n}\n\n/**\n * Validate that a command does not contain obvious escape attempts.\n * This is a defense-in-depth measure — the container itself is the primary boundary.\n *\n * @param command - The shell command to validate.\n * @throws {SecurityError} if the command contains dangerous patterns.\n */\nexport function validateCommand(command: string): void {\n  if (!command || typeof command !== 'string') {\n    throw new SecurityError('Command must be a non-empty string.');\n  }\n\n  // Block attempts to access the Docker socket from within the container\n  const dangerousPatterns = [\n    /docker\\.sock/i,\n    /nsenter\\s/i,\n    /mount\\s+-t\\s+proc/i,\n  ];\n\n  for (const pattern of dangerousPatterns) {\n    if (pattern.test(command)) {\n      throw new SecurityError(\n        `Command contains a potentially dangerous pattern: ${pattern.source}`,\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Error class\n// ---------------------------------------------------------------------------\n\n/**\n * A structured error type for sandbox security violations.\n */\nexport class SecurityError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SecurityError';\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { DockerSandbox } from './docker-sandbox.js';
+export { ContainerPool } from './container-pool.js';
+export { SandboxManager, isDockerAvailable } from './sandbox-manager.js';
+export { BLOCKED_BIND_PREFIXES, DEFAULT_CAP_DROP, SecurityError, validateBind, validateBinds, validateCommand, validateImageName } from './security.js';
+export { DockerSandboxConfig, ExecOptions, ExecResult, PoolConfig, PoolEntry, ResourceLimits, SandboxManagerConfig, SandboxProvider } from './types.js';
+import 'dockerode';