@cloudflare/sandbox 0.0.8 → 0.1.0

package/src/security.ts

@@ -0,0 +1,113 @@
+/**
+ * Security utilities for URL construction and input validation
+ *
+ * This module contains critical security functions to prevent:
+ * - URL injection attacks
+ * - SSRF (Server-Side Request Forgery) attacks
+ * - DNS rebinding attacks
+ * - Host header injection
+ * - Open redirect vulnerabilities
+ */
+
+export class SecurityError extends Error {
+  constructor(message: string, public readonly code?: string) {
+    super(message);
+    this.name = 'SecurityError';
+  }
+}
+
+/**
+ * Validates port numbers for sandbox services
+ * Only allows non-system ports to prevent conflicts and security issues
+ */
+export function validatePort(port: number): boolean {
+  // Must be a valid integer
+  if (!Number.isInteger(port)) {
+    return false;
+  }
+
+  // Only allow non-system ports (1024-65535)
+  if (port < 1024 || port > 65535) {
+    return false;
+  }
+
+  // Exclude ports reserved by our system
+  const reservedPorts = [
+    3000, // Control plane port
+    8787, // Common wrangler dev port
+  ];
+
+  if (reservedPorts.includes(port)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Sanitizes and validates sandbox IDs for DNS compliance and security
+ * Only enforces critical requirements - allows maximum developer flexibility
+ */
+export function sanitizeSandboxId(id: string): string {
+  // Basic validation: not empty, reasonable length limit (DNS subdomain limit is 63 chars)
+  if (!id || id.length > 63) {
+    throw new SecurityError(
+      'Sandbox ID must be 1-63 characters long.',
+      'INVALID_SANDBOX_ID_LENGTH'
+    );
+  }
+
+  // DNS compliance: cannot start or end with hyphens (RFC requirement)
+  if (id.startsWith('-') || id.endsWith('-')) {
+    throw new SecurityError(
+      'Sandbox ID cannot start or end with hyphens (DNS requirement).',
+      'INVALID_SANDBOX_ID_HYPHENS'
+    );
+  }
+
+  // Prevent reserved names that cause technical conflicts
+  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;
+}
+
+
+/**
+ * Logs security events for monitoring
+ */
+export function logSecurityEvent(
+  event: string,
+  details: Record<string, any>,
+  severity: 'low' | 'medium' | 'high' | 'critical' = 'medium'
+): void {
+  const logEntry = {
+    timestamp: 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;
+  }
+}

package/src/sse-parser.ts

@@ -0,0 +1,147 @@
+/**
+ * Server-Sent Events (SSE) parser for streaming responses
+ * Converts ReadableStream<Uint8Array> to typed AsyncIterable<T>
+ */
+
+/**
+ * Parse a ReadableStream of SSE events into typed AsyncIterable
+ * @param stream - The ReadableStream from fetch response
+ * @param signal - Optional AbortSignal for cancellation
+ */
+export async function* parseSSEStream<T>(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal
+): AsyncIterable<T> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  try {
+    while (true) {
+      // Check for cancellation
+      if (signal?.aborted) {
+        throw new Error('Operation was aborted');
+      }
+
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      // Decode chunk and add to buffer
+      buffer += decoder.decode(value, { stream: true });
+
+      // Process complete SSE events in buffer
+      const lines = buffer.split('\n');
+
+      // Keep the last incomplete line in buffer
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        // Skip empty lines
+        if (line.trim() === '') continue;
+
+        // Process SSE data lines
+        if (line.startsWith('data: ')) {
+          const data = line.substring(6);
+
+          // Skip [DONE] markers or empty data
+          if (data === '[DONE]' || data.trim() === '') continue;
+
+          try {
+            const event = JSON.parse(data) as T;
+            yield event;
+          } catch (error) {
+            // Log parsing errors but continue processing
+            console.error('Failed to parse SSE event:', data, error);
+            // Optionally yield an error event
+            // yield { type: 'error', data: `Parse error: ${error.message}` } as T;
+          }
+        }
+        // Handle other SSE fields if needed (event:, id:, retry:)
+        // For now, we only care about data: lines
+      }
+    }
+
+    // Process any remaining data in buffer
+    if (buffer.trim() && buffer.startsWith('data: ')) {
+      const data = buffer.substring(6);
+      if (data !== '[DONE]' && data.trim()) {
+        try {
+          const event = JSON.parse(data) as T;
+          yield event;
+        } catch (error) {
+          console.error('Failed to parse final SSE event:', data, error);
+        }
+      }
+    }
+  } finally {
+    // Clean up resources
+    reader.releaseLock();
+  }
+}
+
+
+/**
+ * Helper to convert a Response with SSE stream directly to AsyncIterable
+ * @param response - Response object with SSE stream
+ * @param signal - Optional AbortSignal for cancellation
+ */
+export async function* responseToAsyncIterable<T>(
+  response: Response,
+  signal?: AbortSignal
+): AsyncIterable<T> {
+  if (!response.ok) {
+    throw new Error(`Response not ok: ${response.status} ${response.statusText}`);
+  }
+
+  if (!response.body) {
+    throw new Error('No response body');
+  }
+
+  yield* parseSSEStream<T>(response.body, signal);
+}
+
+/**
+ * Create an SSE-formatted ReadableStream from an AsyncIterable
+ * (Useful for Worker endpoints that need to forward AsyncIterable as SSE)
+ * @param events - AsyncIterable of events
+ * @param options - Stream options
+ */
+export function asyncIterableToSSEStream<T>(
+  events: AsyncIterable<T>,
+  options?: {
+    signal?: AbortSignal;
+    serialize?: (event: T) => string;
+  }
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const serialize = options?.serialize || JSON.stringify;
+
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const event of events) {
+          if (options?.signal?.aborted) {
+            controller.error(new Error('Operation was aborted'));
+            break;
+          }
+
+          const data = serialize(event);
+          const sseEvent = `data: ${data}\n\n`;
+          controller.enqueue(encoder.encode(sseEvent));
+        }
+
+        // Send completion marker
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+      } catch (error) {
+        controller.error(error);
+      } finally {
+        controller.close();
+      }
+    },
+
+    cancel() {
+      // Handle stream cancellation
+      console.log('SSE stream cancelled');
+    }
+  });
+}

package/src/types.ts

@@ -0,0 +1,386 @@
+// Core Types
+
+export interface BaseExecOptions {
+  /**
+   * Session ID for grouping related commands
+   */
+  sessionId?: string;
+
+  /**
+   * Maximum execution time in milliseconds
+   */
+  timeout?: number;
+
+  /**
+   * Environment variables for the command
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Working directory for command execution
+   */
+  cwd?: string;
+
+  /**
+   * Text encoding for output (default: 'utf8')
+   */
+  encoding?: string;
+}
+
+export interface ExecOptions extends BaseExecOptions {
+  /**
+   * Enable real-time output streaming via callbacks
+   */
+  stream?: boolean;
+
+  /**
+   * Callback for real-time output data
+   */
+  onOutput?: (stream: 'stdout' | 'stderr', data: string) => void;
+
+  /**
+   * Callback when command completes (only when stream: true)
+   */
+  onComplete?: (result: ExecResult) => void;
+
+  /**
+   * Callback for execution errors
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * AbortSignal for cancelling execution
+   */
+  signal?: AbortSignal;
+}
+
+export interface ExecResult {
+  /**
+   * Whether the command succeeded (exitCode === 0)
+   */
+  success: boolean;
+
+  /**
+   * Process exit code
+   */
+  exitCode: number;
+
+  /**
+   * Standard output content
+   */
+  stdout: string;
+
+  /**
+   * Standard error content
+   */
+  stderr: string;
+
+  /**
+   * Command that was executed
+   */
+  command: string;
+
+
+  /**
+   * Execution duration in milliseconds
+   */
+  duration: number;
+
+  /**
+   * ISO timestamp when command started
+   */
+  timestamp: string;
+
+  /**
+   * Session ID if provided
+   */
+  sessionId?: string;
+}
+
+// Background Process Types
+
+export interface ProcessOptions extends BaseExecOptions {
+  /**
+   * Custom process ID for later reference
+   * If not provided, a UUID will be generated
+   */
+  processId?: string;
+
+  /**
+   * Automatically cleanup process record after exit (default: true)
+   */
+  autoCleanup?: boolean;
+
+  /**
+   * Callback when process exits
+   */
+  onExit?: (code: number | null) => void;
+
+  /**
+   * Callback for real-time output (background processes)
+   */
+  onOutput?: (stream: 'stdout' | 'stderr', data: string) => void;
+
+  /**
+   * Callback when process starts successfully
+   */
+  onStart?: (process: Process) => void;
+
+  /**
+   * Callback for process errors
+   */
+  onError?: (error: Error) => void;
+}
+
+export type ProcessStatus =
+  | 'starting'    // Process is being initialized
+  | 'running'     // Process is actively running
+  | 'completed'   // Process exited successfully (code 0)
+  | 'failed'      // Process exited with non-zero code
+  | 'killed'      // Process was terminated by signal
+  | 'error';      // Process failed to start or encountered error
+
+export interface Process {
+  /**
+   * Unique process identifier
+   */
+  readonly id: string;
+
+  /**
+   * System process ID (if available and running)
+   */
+  readonly pid?: number;
+
+  /**
+   * Command that was executed
+   */
+  readonly command: string;
+
+
+  /**
+   * Current process status
+   */
+  readonly status: ProcessStatus;
+
+  /**
+   * When the process was started
+   */
+  readonly startTime: Date;
+
+  /**
+   * When the process ended (if completed)
+   */
+  readonly endTime?: Date;
+
+  /**
+   * Process exit code (if completed)
+   */
+  readonly exitCode?: number;
+
+  /**
+   * Session ID if provided
+   */
+  readonly sessionId?: string;
+
+  /**
+   * Kill the process
+   */
+  kill(signal?: string): Promise<void>;
+
+  /**
+   * Get current process status (refreshed)
+   */
+  getStatus(): Promise<ProcessStatus>;
+
+  /**
+   * Get accumulated logs
+   */
+  getLogs(): Promise<{ stdout: string; stderr: string }>;
+}
+
+// Streaming Types
+
+export interface ExecEvent {
+  type: 'start' | 'stdout' | 'stderr' | 'complete' | 'error';
+  timestamp: string;
+  data?: string;
+  command?: string;
+  exitCode?: number;
+  result?: ExecResult;
+  error?: string; // Changed to string for serialization
+  sessionId?: string;
+}
+
+export interface LogEvent {
+  type: 'stdout' | 'stderr' | 'exit' | 'error';
+  timestamp: string;
+  data: string;
+  processId: string;
+  sessionId?: string;
+  exitCode?: number; // For 'exit' events
+}
+
+export interface StreamOptions extends BaseExecOptions {
+  /**
+   * Buffer size for streaming output
+   */
+  bufferSize?: number;
+
+  /**
+   * AbortSignal for cancelling stream
+   */
+  signal?: AbortSignal;
+}
+
+// Error Types
+
+export class SandboxError extends Error {
+  constructor(message: string, public code?: string) {
+    super(message);
+    this.name = 'SandboxError';
+  }
+}
+
+export class ProcessNotFoundError extends SandboxError {
+  constructor(processId: string) {
+    super(`Process not found: ${processId}`, 'PROCESS_NOT_FOUND');
+    this.name = 'ProcessNotFoundError';
+  }
+}
+
+export class ProcessAlreadyExistsError extends SandboxError {
+  constructor(processId: string) {
+    super(`Process already exists: ${processId}`, 'PROCESS_EXISTS');
+    this.name = 'ProcessAlreadyExistsError';
+  }
+}
+
+export class ExecutionTimeoutError extends SandboxError {
+  constructor(timeout: number) {
+    super(`Execution timed out after ${timeout}ms`, 'EXECUTION_TIMEOUT');
+    this.name = 'ExecutionTimeoutError';
+  }
+}
+
+// Internal Container Types
+
+export interface ProcessRecord {
+  id: string;
+  pid?: number;
+  command: string;
+  status: ProcessStatus;
+  startTime: Date;
+  endTime?: Date;
+  exitCode?: number;
+  sessionId?: string;
+
+  // Internal fields
+  childProcess?: any;  // Node.js ChildProcess
+  stdout: string;      // Accumulated output (ephemeral)
+  stderr: string;      // Accumulated output (ephemeral)
+
+  // Streaming
+  outputListeners: Set<(stream: 'stdout' | 'stderr', data: string) => void>;
+  statusListeners: Set<(status: ProcessStatus) => void>;
+}
+
+// Container Request/Response Types
+
+export interface StartProcessRequest {
+  command: string;
+  options?: {
+    processId?: string;
+    sessionId?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+    cwd?: string;
+    encoding?: string;
+    autoCleanup?: boolean;
+  };
+}
+
+export interface StartProcessResponse {
+  process: {
+    id: string;
+    pid?: number;
+    command: string;
+      status: ProcessStatus;
+    startTime: string;
+    sessionId?: string;
+  };
+}
+
+export interface ListProcessesResponse {
+  processes: Array<{
+    id: string;
+    pid?: number;
+    command: string;
+      status: ProcessStatus;
+    startTime: string;
+    endTime?: string;
+    exitCode?: number;
+    sessionId?: string;
+  }>;
+}
+
+export interface GetProcessResponse {
+  process: {
+    id: string;
+    pid?: number;
+    command: string;
+      status: ProcessStatus;
+    startTime: string;
+    endTime?: string;
+    exitCode?: number;
+    sessionId?: string;
+  } | null;
+}
+
+export interface GetProcessLogsResponse {
+  stdout: string;
+  stderr: string;
+  processId: string;
+}
+
+// Main Sandbox Interface
+
+export interface ISandbox {
+  // Enhanced execution API
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+
+  // Background process management
+  startProcess(command: string, options?: ProcessOptions): Promise<Process>;
+  listProcesses(): Promise<Process[]>;
+  getProcess(id: string): Promise<Process | null>;
+  killProcess(id: string, signal?: string): Promise<void>;
+  killAllProcesses(): Promise<number>;
+
+  // Advanced streaming - returns ReadableStream that can be converted to AsyncIterable
+  execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
+  streamProcessLogs(processId: string, options?: { signal?: AbortSignal }): Promise<ReadableStream<Uint8Array>>;
+
+  // Utility methods
+  cleanupCompletedProcesses(): Promise<number>;
+  getProcessLogs(id: string): Promise<{ stdout: string; stderr: string }>;
+}
+
+// Type Guards
+
+export function isExecResult(value: any): value is ExecResult {
+  return value &&
+    typeof value.success === 'boolean' &&
+    typeof value.exitCode === 'number' &&
+    typeof value.stdout === 'string' &&
+    typeof value.stderr === 'string';
+}
+
+export function isProcess(value: any): value is Process {
+  return value &&
+    typeof value.id === 'string' &&
+    typeof value.command === 'string' &&
+    typeof value.status === 'string';
+}
+
+export function isProcessStatus(value: string): value is ProcessStatus {
+  return ['starting', 'running', 'completed', 'failed', 'killed', 'error'].includes(value);
+}

package/README.md

@@ -1,65 +0,0 @@
-## @cloudflare/sandbox
-
-> **⚠️ Experimental** - This library is currently experimental and we're actively seeking feedback. Please try it out and let us know what you think!
-
-A library to spin up a sandboxed environment.
-
-First, setup your wrangler.json to use the sandbox:
-
-```jsonc
-{
-  // ...
-  "containers": [
-    {
-      "class_name": "Sandbox",
-      "image": "./node_modules/@cloudflare/sandbox/Dockerfile",
-      "name": "sandbox"
-    }
-  ],
-  "durable_objects": {
-    "bindings": [
-      {
-        "class_name": "Sandbox",
-        "name": "Sandbox"
-      }
-    ]
-  },
-  "migrations": [
-    {
-      "new_sqlite_classes": ["Sandbox"],
-      "tag": "v1"
-    }
-  ]
-}
-```
-
-Then, export the Sandbox class in your worker:
-
-```ts
-export { Sandbox } from "@cloudflare/sandbox";
-```
-
-You can then use the Sandbox class in your worker:
-
-```ts
-import { getSandbox } from "@cloudflare/sandbox";
-
-export default {
-  async fetch(request: Request, env: Env) {
-    const sandbox = getSandbox(env.Sandbox, "my-sandbox");
-    return sandbox.exec("ls", ["-la"]);
-  },
-};
-```
-
-### Methods:
-
-- `exec(command: string, args: string[], options?: { stream?: boolean })`: Execute a command in the sandbox.
-- `gitCheckout(repoUrl: string, options: { branch?: string; targetDir?: string; stream?: boolean })`: Checkout a git repository in the sandbox.
-- `mkdir(path: string, options: { recursive?: boolean; stream?: boolean })`: Create a directory in the sandbox.
-- `writeFile(path: string, content: string, options: { encoding?: string; stream?: boolean })`: Write content to a file in the sandbox.
-- `readFile(path: string, options: { encoding?: string; stream?: boolean })`: Read content from a file in the sandbox.
-- `deleteFile(path: string, options?: { stream?: boolean })`: Delete a file from the sandbox.
-- `renameFile(oldPath: string, newPath: string, options?: { stream?: boolean })`: Rename a file in the sandbox.
-- `moveFile(sourcePath: string, destinationPath: string, options?: { stream?: boolean })`: Move a file from one location to another in the sandbox.
-- `ping()`: Ping the sandbox.