@cloudflare/sandbox 0.0.9 → 0.1.0

package/container_src/types.ts

@@ -0,0 +1,103 @@
+import type { ChildProcess } from "node:child_process";
+
+// Process management types
+export type ProcessStatus =
+  | 'starting'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'killed'
+  | 'error';
+
+export interface ProcessRecord {
+  id: string;
+  pid?: number;
+  command: string;
+  status: ProcessStatus;
+  startTime: Date;
+  endTime?: Date;
+  exitCode?: number;
+  sessionId?: string;
+  childProcess?: ChildProcess;
+  stdout: string;
+  stderr: string;
+  outputListeners: Set<(stream: 'stdout' | 'stderr', data: string) => void>;
+  statusListeners: Set<(status: ProcessStatus) => void>;
+}
+
+export interface StartProcessRequest {
+  command: string;
+  options?: {
+    processId?: string;
+    sessionId?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+    cwd?: string;
+    encoding?: string;
+    autoCleanup?: boolean;
+  };
+}
+
+export interface ExecuteRequest {
+  command: string;
+  sessionId?: string;
+  background?: boolean;
+}
+
+export interface GitCheckoutRequest {
+  repoUrl: string;
+  branch?: string;
+  targetDir?: string;
+  sessionId?: string;
+}
+
+export interface MkdirRequest {
+  path: string;
+  recursive?: boolean;
+  sessionId?: string;
+}
+
+export interface WriteFileRequest {
+  path: string;
+  content: string;
+  encoding?: string;
+  sessionId?: string;
+}
+
+export interface ReadFileRequest {
+  path: string;
+  encoding?: string;
+  sessionId?: string;
+}
+
+export interface DeleteFileRequest {
+  path: string;
+  sessionId?: string;
+}
+
+export interface RenameFileRequest {
+  oldPath: string;
+  newPath: string;
+  sessionId?: string;
+}
+
+export interface MoveFileRequest {
+  sourcePath: string;
+  destinationPath: string;
+  sessionId?: string;
+}
+
+export interface ExposePortRequest {
+  port: number;
+  name?: string;
+}
+
+export interface UnexposePortRequest {
+  port: number;
+}
+
+export interface SessionData {
+  sessionId: string;
+  activeProcess: ChildProcess | null;
+  createdAt: Date;
+}

package/dist/chunk-6THNBO4S.js

@@ -0,0 +1,46 @@
+// src/types.ts
+var SandboxError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "SandboxError";
+  }
+};
+var ProcessNotFoundError = class extends SandboxError {
+  constructor(processId) {
+    super(`Process not found: ${processId}`, "PROCESS_NOT_FOUND");
+    this.name = "ProcessNotFoundError";
+  }
+};
+var ProcessAlreadyExistsError = class extends SandboxError {
+  constructor(processId) {
+    super(`Process already exists: ${processId}`, "PROCESS_EXISTS");
+    this.name = "ProcessAlreadyExistsError";
+  }
+};
+var ExecutionTimeoutError = class extends SandboxError {
+  constructor(timeout) {
+    super(`Execution timed out after ${timeout}ms`, "EXECUTION_TIMEOUT");
+    this.name = "ExecutionTimeoutError";
+  }
+};
+function isExecResult(value) {
+  return value && typeof value.success === "boolean" && typeof value.exitCode === "number" && typeof value.stdout === "string" && typeof value.stderr === "string";
+}
+function isProcess(value) {
+  return value && typeof value.id === "string" && typeof value.command === "string" && typeof value.status === "string";
+}
+function isProcessStatus(value) {
+  return ["starting", "running", "completed", "failed", "killed", "error"].includes(value);
+}
+
+export {
+  SandboxError,
+  ProcessNotFoundError,
+  ProcessAlreadyExistsError,
+  ExecutionTimeoutError,
+  isExecResult,
+  isProcess,
+  isProcessStatus
+};
+//# sourceMappingURL=chunk-6THNBO4S.js.map

package/dist/chunk-6THNBO4S.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["// Core Types\n\nexport interface BaseExecOptions {\n  /**\n   * Session ID for grouping related commands\n   */\n  sessionId?: string;\n\n  /**\n   * Maximum execution time in milliseconds\n   */\n  timeout?: number;\n\n  /**\n   * Environment variables for the command\n   */\n  env?: Record<string, string>;\n\n  /**\n   * Working directory for command execution\n   */\n  cwd?: string;\n\n  /**\n   * Text encoding for output (default: 'utf8')\n   */\n  encoding?: string;\n}\n\nexport interface ExecOptions extends BaseExecOptions {\n  /**\n   * Enable real-time output streaming via callbacks\n   */\n  stream?: boolean;\n\n  /**\n   * Callback for real-time output data\n   */\n  onOutput?: (stream: 'stdout' | 'stderr', data: string) => void;\n\n  /**\n   * Callback when command completes (only when stream: true)\n   */\n  onComplete?: (result: ExecResult) => void;\n\n  /**\n   * Callback for execution errors\n   */\n  onError?: (error: Error) => void;\n\n  /**\n   * AbortSignal for cancelling execution\n   */\n  signal?: AbortSignal;\n}\n\nexport interface ExecResult {\n  /**\n   * Whether the command succeeded (exitCode === 0)\n   */\n  success: boolean;\n\n  /**\n   * Process exit code\n   */\n  exitCode: number;\n\n  /**\n   * Standard output content\n   */\n  stdout: string;\n\n  /**\n   * Standard error content\n   */\n  stderr: string;\n\n  /**\n   * Command that was executed\n   */\n  command: string;\n\n\n  /**\n   * Execution duration in milliseconds\n   */\n  duration: number;\n\n  /**\n   * ISO timestamp when command started\n   */\n  timestamp: string;\n\n  /**\n   * Session ID if provided\n   */\n  sessionId?: string;\n}\n\n// Background Process Types\n\nexport interface ProcessOptions extends BaseExecOptions {\n  /**\n   * Custom process ID for later reference\n   * If not provided, a UUID will be generated\n   */\n  processId?: string;\n\n  /**\n   * Automatically cleanup process record after exit (default: true)\n   */\n  autoCleanup?: boolean;\n\n  /**\n   * Callback when process exits\n   */\n  onExit?: (code: number | null) => void;\n\n  /**\n   * Callback for real-time output (background processes)\n   */\n  onOutput?: (stream: 'stdout' | 'stderr', data: string) => void;\n\n  /**\n   * Callback when process starts successfully\n   */\n  onStart?: (process: Process) => void;\n\n  /**\n   * Callback for process errors\n   */\n  onError?: (error: Error) => void;\n}\n\nexport type ProcessStatus =\n  | 'starting'    // Process is being initialized\n  | 'running'     // Process is actively running\n  | 'completed'   // Process exited successfully (code 0)\n  | 'failed'      // Process exited with non-zero code\n  | 'killed'      // Process was terminated by signal\n  | 'error';      // Process failed to start or encountered error\n\nexport interface Process {\n  /**\n   * Unique process identifier\n   */\n  readonly id: string;\n\n  /**\n   * System process ID (if available and running)\n   */\n  readonly pid?: number;\n\n  /**\n   * Command that was executed\n   */\n  readonly command: string;\n\n\n  /**\n   * Current process status\n   */\n  readonly status: ProcessStatus;\n\n  /**\n   * When the process was started\n   */\n  readonly startTime: Date;\n\n  /**\n   * When the process ended (if completed)\n   */\n  readonly endTime?: Date;\n\n  /**\n   * Process exit code (if completed)\n   */\n  readonly exitCode?: number;\n\n  /**\n   * Session ID if provided\n   */\n  readonly sessionId?: string;\n\n  /**\n   * Kill the process\n   */\n  kill(signal?: string): Promise<void>;\n\n  /**\n   * Get current process status (refreshed)\n   */\n  getStatus(): Promise<ProcessStatus>;\n\n  /**\n   * Get accumulated logs\n   */\n  getLogs(): Promise<{ stdout: string; stderr: string }>;\n}\n\n// Streaming Types\n\nexport interface ExecEvent {\n  type: 'start' | 'stdout' | 'stderr' | 'complete' | 'error';\n  timestamp: string;\n  data?: string;\n  command?: string;\n  exitCode?: number;\n  result?: ExecResult;\n  error?: string; // Changed to string for serialization\n  sessionId?: string;\n}\n\nexport interface LogEvent {\n  type: 'stdout' | 'stderr' | 'exit' | 'error';\n  timestamp: string;\n  data: string;\n  processId: string;\n  sessionId?: string;\n  exitCode?: number; // For 'exit' events\n}\n\nexport interface StreamOptions extends BaseExecOptions {\n  /**\n   * Buffer size for streaming output\n   */\n  bufferSize?: number;\n\n  /**\n   * AbortSignal for cancelling stream\n   */\n  signal?: AbortSignal;\n}\n\n// Error Types\n\nexport class SandboxError extends Error {\n  constructor(message: string, public code?: string) {\n    super(message);\n    this.name = 'SandboxError';\n  }\n}\n\nexport class ProcessNotFoundError extends SandboxError {\n  constructor(processId: string) {\n    super(`Process not found: ${processId}`, 'PROCESS_NOT_FOUND');\n    this.name = 'ProcessNotFoundError';\n  }\n}\n\nexport class ProcessAlreadyExistsError extends SandboxError {\n  constructor(processId: string) {\n    super(`Process already exists: ${processId}`, 'PROCESS_EXISTS');\n    this.name = 'ProcessAlreadyExistsError';\n  }\n}\n\nexport class ExecutionTimeoutError extends SandboxError {\n  constructor(timeout: number) {\n    super(`Execution timed out after ${timeout}ms`, 'EXECUTION_TIMEOUT');\n    this.name = 'ExecutionTimeoutError';\n  }\n}\n\n// Internal Container Types\n\nexport interface ProcessRecord {\n  id: string;\n  pid?: number;\n  command: string;\n  status: ProcessStatus;\n  startTime: Date;\n  endTime?: Date;\n  exitCode?: number;\n  sessionId?: string;\n\n  // Internal fields\n  childProcess?: any;  // Node.js ChildProcess\n  stdout: string;      // Accumulated output (ephemeral)\n  stderr: string;      // Accumulated output (ephemeral)\n\n  // Streaming\n  outputListeners: Set<(stream: 'stdout' | 'stderr', data: string) => void>;\n  statusListeners: Set<(status: ProcessStatus) => void>;\n}\n\n// Container Request/Response Types\n\nexport interface StartProcessRequest {\n  command: string;\n  options?: {\n    processId?: string;\n    sessionId?: string;\n    timeout?: number;\n    env?: Record<string, string>;\n    cwd?: string;\n    encoding?: string;\n    autoCleanup?: boolean;\n  };\n}\n\nexport interface StartProcessResponse {\n  process: {\n    id: string;\n    pid?: number;\n    command: string;\n      status: ProcessStatus;\n    startTime: string;\n    sessionId?: string;\n  };\n}\n\nexport interface ListProcessesResponse {\n  processes: Array<{\n    id: string;\n    pid?: number;\n    command: string;\n      status: ProcessStatus;\n    startTime: string;\n    endTime?: string;\n    exitCode?: number;\n    sessionId?: string;\n  }>;\n}\n\nexport interface GetProcessResponse {\n  process: {\n    id: string;\n    pid?: number;\n    command: string;\n      status: ProcessStatus;\n    startTime: string;\n    endTime?: string;\n    exitCode?: number;\n    sessionId?: string;\n  } | null;\n}\n\nexport interface GetProcessLogsResponse {\n  stdout: string;\n  stderr: string;\n  processId: string;\n}\n\n// Main Sandbox Interface\n\nexport interface ISandbox {\n  // Enhanced execution API\n  exec(command: string, options?: ExecOptions): Promise<ExecResult>;\n\n  // Background process management\n  startProcess(command: string, options?: ProcessOptions): Promise<Process>;\n  listProcesses(): Promise<Process[]>;\n  getProcess(id: string): Promise<Process | null>;\n  killProcess(id: string, signal?: string): Promise<void>;\n  killAllProcesses(): Promise<number>;\n\n  // Advanced streaming - returns ReadableStream that can be converted to AsyncIterable\n  execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;\n  streamProcessLogs(processId: string, options?: { signal?: AbortSignal }): Promise<ReadableStream<Uint8Array>>;\n\n  // Utility methods\n  cleanupCompletedProcesses(): Promise<number>;\n  getProcessLogs(id: string): Promise<{ stdout: string; stderr: string }>;\n}\n\n// Type Guards\n\nexport function isExecResult(value: any): value is ExecResult {\n  return value &&\n    typeof value.success === 'boolean' &&\n    typeof value.exitCode === 'number' &&\n    typeof value.stdout === 'string' &&\n    typeof value.stderr === 'string';\n}\n\nexport function isProcess(value: any): value is Process {\n  return value &&\n    typeof value.id === 'string' &&\n    typeof value.command === 'string' &&\n    typeof value.status === 'string';\n}\n\nexport function isProcessStatus(value: string): value is ProcessStatus {\n  return ['starting', 'running', 'completed', 'failed', 'killed', 'error'].includes(value);\n}"],"mappings":";AA4OO,IAAM,eAAN,cAA2B,MAAM;AAAA,EACtC,YAAY,SAAwB,MAAe;AACjD,UAAM,OAAO;AADqB;AAElC,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,uBAAN,cAAmC,aAAa;AAAA,EACrD,YAAY,WAAmB;AAC7B,UAAM,sBAAsB,SAAS,IAAI,mBAAmB;AAC5D,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,4BAAN,cAAwC,aAAa;AAAA,EAC1D,YAAY,WAAmB;AAC7B,UAAM,2BAA2B,SAAS,IAAI,gBAAgB;AAC9D,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,wBAAN,cAAoC,aAAa;AAAA,EACtD,YAAY,SAAiB;AAC3B,UAAM,6BAA6B,OAAO,MAAM,mBAAmB;AACnE,SAAK,OAAO;AAAA,EACd;AACF;AA0GO,SAAS,aAAa,OAAiC;AAC5D,SAAO,SACL,OAAO,MAAM,YAAY,aACzB,OAAO,MAAM,aAAa,YAC1B,OAAO,MAAM,WAAW,YACxB,OAAO,MAAM,WAAW;AAC5B;AAEO,SAAS,UAAU,OAA8B;AACtD,SAAO,SACL,OAAO,MAAM,OAAO,YACpB,OAAO,MAAM,YAAY,YACzB,OAAO,MAAM,WAAW;AAC5B;AAEO,SAAS,gBAAgB,OAAuC;AACrE,SAAO,CAAC,YAAY,WAAW,aAAa,UAAU,UAAU,OAAO,EAAE,SAAS,KAAK;AACzF;","names":[]}

package/dist/chunk-6UAWTJ5S.js

@@ -0,0 +1,85 @@
+// src/security.ts
+var SecurityError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "SecurityError";
+  }
+};
+function validatePort(port) {
+  if (!Number.isInteger(port)) {
+    return false;
+  }
+  if (port < 1024 || port > 65535) {
+    return false;
+  }
+  const reservedPorts = [
+    3e3,
+    // Control plane port
+    8787
+    // Common wrangler dev port
+  ];
+  if (reservedPorts.includes(port)) {
+    return false;
+  }
+  return true;
+}
+function sanitizeSandboxId(id) {
+  if (!id || id.length > 63) {
+    throw new SecurityError(
+      "Sandbox ID must be 1-63 characters long.",
+      "INVALID_SANDBOX_ID_LENGTH"
+    );
+  }
+  if (id.startsWith("-") || id.endsWith("-")) {
+    throw new SecurityError(
+      "Sandbox ID cannot start or end with hyphens (DNS requirement).",
+      "INVALID_SANDBOX_ID_HYPHENS"
+    );
+  }
+  const reservedNames = [
+    "www",
+    "api",
+    "admin",
+    "root",
+    "system",
+    "cloudflare",
+    "workers"
+  ];
+  const lowerCaseId = id.toLowerCase();
+  if (reservedNames.includes(lowerCaseId)) {
+    throw new SecurityError(
+      `Reserved sandbox ID '${id}' is not allowed.`,
+      "RESERVED_SANDBOX_ID"
+    );
+  }
+  return id;
+}
+function logSecurityEvent(event, details, severity = "medium") {
+  const logEntry = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    event,
+    severity,
+    ...details
+  };
+  switch (severity) {
+    case "critical":
+    case "high":
+      console.error(`[SECURITY:${severity.toUpperCase()}] ${event}:`, JSON.stringify(logEntry));
+      break;
+    case "medium":
+      console.warn(`[SECURITY:${severity.toUpperCase()}] ${event}:`, JSON.stringify(logEntry));
+      break;
+    case "low":
+      console.info(`[SECURITY:${severity.toUpperCase()}] ${event}:`, JSON.stringify(logEntry));
+      break;
+  }
+}
+
+export {
+  SecurityError,
+  validatePort,
+  sanitizeSandboxId,
+  logSecurityEvent
+};
+//# sourceMappingURL=chunk-6UAWTJ5S.js.map

package/dist/chunk-6UAWTJ5S.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/security.ts"],"sourcesContent":["/**\n * Security utilities for URL construction and input validation\n *\n * This module contains critical security functions to prevent:\n * - URL injection attacks\n * - SSRF (Server-Side Request Forgery) attacks\n * - DNS rebinding attacks\n * - Host header injection\n * - Open redirect vulnerabilities\n */\n\nexport class SecurityError extends Error {\n  constructor(message: string, public readonly code?: string) {\n    super(message);\n    this.name = 'SecurityError';\n  }\n}\n\n/**\n * Validates port numbers for sandbox services\n * Only allows non-system ports to prevent conflicts and security issues\n */\nexport function validatePort(port: number): boolean {\n  // Must be a valid integer\n  if (!Number.isInteger(port)) {\n    return false;\n  }\n\n  // Only allow non-system ports (1024-65535)\n  if (port < 1024 || port > 65535) {\n    return false;\n  }\n\n  // Exclude ports reserved by our system\n  const reservedPorts = [\n    3000, // Control plane port\n    8787, // Common wrangler dev port\n  ];\n\n  if (reservedPorts.includes(port)) {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Sanitizes and validates sandbox IDs for DNS compliance and security\n * Only enforces critical requirements - allows maximum developer flexibility\n */\nexport function sanitizeSandboxId(id: string): string {\n  // Basic validation: not empty, reasonable length limit (DNS subdomain limit is 63 chars)\n  if (!id || id.length > 63) {\n    throw new SecurityError(\n      'Sandbox ID must be 1-63 characters long.',\n      'INVALID_SANDBOX_ID_LENGTH'\n    );\n  }\n\n  // DNS compliance: cannot start or end with hyphens (RFC requirement)\n  if (id.startsWith('-') || id.endsWith('-')) {\n    throw new SecurityError(\n      'Sandbox ID cannot start or end with hyphens (DNS requirement).',\n      'INVALID_SANDBOX_ID_HYPHENS'\n    );\n  }\n\n  // Prevent reserved names that cause technical conflicts\n  const reservedNames = [\n    'www', 'api', 'admin', 'root', 'system',\n    'cloudflare', 'workers'\n  ];\n\n  const lowerCaseId = id.toLowerCase();\n  if (reservedNames.includes(lowerCaseId)) {\n    throw new SecurityError(\n      `Reserved sandbox ID '${id}' is not allowed.`,\n      'RESERVED_SANDBOX_ID'\n    );\n  }\n\n  return id;\n}\n\n\n/**\n * Logs security events for monitoring\n */\nexport function logSecurityEvent(\n  event: string,\n  details: Record<string, any>,\n  severity: 'low' | 'medium' | 'high' | 'critical' = 'medium'\n): void {\n  const logEntry = {\n    timestamp: new Date().toISOString(),\n    event,\n    severity,\n    ...details\n  };\n\n  switch (severity) {\n    case 'critical':\n    case 'high':\n      console.error(`[SECURITY:${severity.toUpperCase()}] ${event}:`, JSON.stringify(logEntry));\n      break;\n    case 'medium':\n      console.warn(`[SECURITY:${severity.toUpperCase()}] ${event}:`, JSON.stringify(logEntry));\n      break;\n    case 'low':\n      console.info(`[SECURITY:${severity.toUpperCase()}] ${event}:`, JSON.stringify(logEntry));\n      break;\n  }\n}\n"],"mappings":";AAWO,IAAM,gBAAN,cAA4B,MAAM;AAAA,EACvC,YAAY,SAAiC,MAAe;AAC1D,UAAM,OAAO;AAD8B;AAE3C,SAAK,OAAO;AAAA,EACd;AACF;AAMO,SAAS,aAAa,MAAuB;AAElD,MAAI,CAAC,OAAO,UAAU,IAAI,GAAG;AAC3B,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,QAAQ,OAAO,OAAO;AAC/B,WAAO;AAAA,EACT;AAGA,QAAM,gBAAgB;AAAA,IACpB;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,MAAI,cAAc,SAAS,IAAI,GAAG;AAChC,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAMO,SAAS,kBAAkB,IAAoB;AAEpD,MAAI,CAAC,MAAM,GAAG,SAAS,IAAI;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAGA,MAAI,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,GAAG;AAC1C,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAGA,QAAM,gBAAgB;AAAA,IACpB;AAAA,IAAO;AAAA,IAAO;AAAA,IAAS;AAAA,IAAQ;AAAA,IAC/B;AAAA,IAAc;AAAA,EAChB;AAEA,QAAM,cAAc,GAAG,YAAY;AACnC,MAAI,cAAc,SAAS,WAAW,GAAG;AACvC,UAAM,IAAI;AAAA,MACR,wBAAwB,EAAE;AAAA,MAC1B;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAMO,SAAS,iBACd,OACA,SACA,WAAmD,UAC7C;AACN,QAAM,WAAW;AAAA,IACf,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,IAClC;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL;AAEA,UAAQ,UAAU;AAAA,IAChB,KAAK;AAAA,IACL,KAAK;AACH,cAAQ,MAAM,aAAa,SAAS,YAAY,CAAC,KAAK,KAAK,KAAK,KAAK,UAAU,QAAQ,CAAC;AACxF;AAAA,IACF,KAAK;AACH,cAAQ,KAAK,aAAa,SAAS,YAAY,CAAC,KAAK,KAAK,KAAK,KAAK,UAAU,QAAQ,CAAC;AACvF;AAAA,IACF,KAAK;AACH,cAAQ,KAAK,aAAa,SAAS,YAAY,CAAC,KAAK,KAAK,KAAK,KAAK,UAAU,QAAQ,CAAC;AACvF;AAAA,EACJ;AACF;","names":[]}