@cloudflare/sandbox 0.0.0-46eb4e6 → 0.0.0-485cf61

package/src/file-stream.ts

@@ -1,162 +1,164 @@
+import type { FileChunk, FileMetadata, FileStreamEvent } from '@repo/shared';
+
 /**
- * File streaming utilities for reading binary and text files
- * Provides simple AsyncIterable API over SSE stream with automatic base64 decoding
+ * Parse SSE (Server-Sent Events) lines from a stream
  */
+async function* parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<FileStreamEvent> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) {
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
 
-import { parseSSEStream } from './sse-parser';
-import type { FileChunk, FileMetadata, FileStreamEvent } from './types';
+      // Keep the last incomplete line in the buffer
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6); // Remove 'data: ' prefix
+          try {
+            const event = JSON.parse(data) as FileStreamEvent;
+            yield event;
+          } catch (error) {
+            console.error('Failed to parse SSE event:', error);
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
 
 /**
- * Convert ReadableStream of SSE file events to AsyncIterable of file chunks
- * Automatically decodes base64 for binary files and provides metadata
+ * Stream a file from the sandbox with automatic base64 decoding for binary files
  *
- * @param stream - The SSE ReadableStream from readFileStream()
- * @param signal - Optional AbortSignal for cancellation
- * @returns AsyncIterable that yields file chunks (string for text, Uint8Array for binary)
+ * @param stream - The ReadableStream from readFileStream()
+ * @returns AsyncGenerator that yields FileChunk (string for text, Uint8Array for binary)
  *
  * @example
- * ```typescript
+ * ```ts
  * const stream = await sandbox.readFileStream('/path/to/file.png');
- *
  * for await (const chunk of streamFile(stream)) {
  *   if (chunk instanceof Uint8Array) {
- *     // Binary chunk - already decoded from base64
- *     console.log('Binary chunk:', chunk.byteLength, 'bytes');
+ *     // Binary chunk
+ *     console.log('Binary chunk:', chunk.length, 'bytes');
  *   } else {
  *     // Text chunk
  *     console.log('Text chunk:', chunk);
  *   }
  * }
- *
- * // Access metadata
- * const iter = streamFile(stream);
- * for await (const chunk of iter) {
- *   console.log('MIME type:', iter.metadata?.mimeType);
- *   // process chunk...
- * }
  * ```
  */
-export async function* streamFile(
-  stream: ReadableStream<Uint8Array>,
-  signal?: AbortSignal
-): AsyncGenerator<FileChunk, void, undefined> {
-  let metadata: FileMetadata | undefined;
+export async function* streamFile(stream: ReadableStream<Uint8Array>): AsyncGenerator<FileChunk, FileMetadata> {
+  let metadata: FileMetadata | null = null;
 
-  try {
-    for await (const event of parseSSEStream<FileStreamEvent>(stream, signal)) {
-      switch (event.type) {
-        case 'metadata':
-          // Store metadata for access via iterator
-          metadata = {
-            mimeType: event.mimeType,
-            size: event.size,
-            isBinary: event.isBinary,
-            encoding: event.encoding,
-          };
-          // Store on generator function for external access
-          (streamFile as any).metadata = metadata;
-          break;
-
-        case 'chunk':
-          // Auto-decode base64 for binary files
-          if (metadata?.isBinary && metadata?.encoding === 'base64') {
-            // Decode base64 to Uint8Array
-            const binaryString = atob(event.data);
-            const bytes = new Uint8Array(binaryString.length);
-            for (let i = 0; i < binaryString.length; i++) {
-              bytes[i] = binaryString.charCodeAt(i);
-            }
-            yield bytes;
-          } else {
-            // Text file - yield as-is
-            yield event.data;
+  for await (const event of parseSSE(stream)) {
+    switch (event.type) {
+      case 'metadata':
+        metadata = {
+          mimeType: event.mimeType,
+          size: event.size,
+          isBinary: event.isBinary,
+          encoding: event.encoding,
+        };
+        break;
+
+      case 'chunk':
+        if (!metadata) {
+          throw new Error('Received chunk before metadata');
+        }
+
+        if (metadata.isBinary && metadata.encoding === 'base64') {
+          // Decode base64 to Uint8Array for binary files
+          const binaryString = atob(event.data);
+          const bytes = new Uint8Array(binaryString.length);
+          for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
           }
-          break;
+          yield bytes;
+        } else {
+          // Text files - yield as-is
+          yield event.data;
+        }
+        break;
 
-        case 'complete':
-          // Stream completed successfully
-          console.log(`[streamFile] File streaming complete: ${event.bytesRead} bytes read`);
-          return;
+      case 'complete':
+        if (!metadata) {
+          throw new Error('Stream completed without metadata');
+        }
+        return metadata;
 
-        case 'error':
-          // Stream error
-          throw new Error(`File streaming error: ${event.error}`);
-      }
+      case 'error':
+        throw new Error(`File streaming error: ${event.error}`);
     }
-  } catch (error) {
-    console.error('[streamFile] Error streaming file:', error);
-    throw error;
   }
+
+  throw new Error('Stream ended unexpectedly');
 }
 
 /**
- * Helper to collect entire file from stream into memory
- * Useful for smaller files where you want the complete content at once
+ * Collect an entire file into memory from a stream
  *
- * @param stream - The SSE ReadableStream from readFileStream()
- * @param signal - Optional AbortSignal for cancellation
- * @returns Object with content (string or Uint8Array) and metadata
+ * @param stream - The ReadableStream from readFileStream()
+ * @returns Object containing the file content and metadata
  *
  * @example
- * ```typescript
- * const stream = await sandbox.readFileStream('/path/to/image.png');
+ * ```ts
+ * const stream = await sandbox.readFileStream('/path/to/file.txt');
  * const { content, metadata } = await collectFile(stream);
- *
- * if (content instanceof Uint8Array) {
- *   console.log('Binary file:', metadata.mimeType, content.byteLength, 'bytes');
- * } else {
- *   console.log('Text file:', metadata.mimeType, content.length, 'chars');
- * }
+ * console.log('Content:', content);
+ * console.log('MIME type:', metadata.mimeType);
  * ```
  */
-export async function collectFile(
-  stream: ReadableStream<Uint8Array>,
-  signal?: AbortSignal
-): Promise<{ content: string | Uint8Array; metadata: FileMetadata }> {
-  let metadata: FileMetadata | undefined;
-  const chunks: FileChunk[] = [];
-
-  for await (const chunk of streamFile(stream, signal)) {
-    chunks.push(chunk);
-    // Capture metadata from first iteration
-    if (!metadata && (streamFile as any).metadata) {
-      metadata = (streamFile as any).metadata;
-    }
+export async function collectFile(stream: ReadableStream<Uint8Array>): Promise<{
+  content: string | Uint8Array;
+  metadata: FileMetadata;
+}> {
+  const chunks: Array<string | Uint8Array> = [];
+
+  // Iterate through the generator and get the return value (metadata)
+  const generator = streamFile(stream);
+  let result = await generator.next();
+
+  while (!result.done) {
+    chunks.push(result.value);
+    result = await generator.next();
   }
 
+  const metadata = result.value;
+
   if (!metadata) {
-    throw new Error('No metadata received from file stream');
+    throw new Error('Failed to get file metadata');
   }
 
   // Combine chunks based on type
-  if (chunks.length === 0) {
-    // Empty file
-    return {
-      content: metadata.isBinary ? new Uint8Array(0) : '',
-      metadata,
-    };
-  }
-
-  // Check if binary or text based on first chunk
-  if (chunks[0] instanceof Uint8Array) {
-    // Binary file - concatenate Uint8Arrays
-    const totalLength = chunks.reduce((sum, chunk) => {
-      return sum + (chunk as Uint8Array).byteLength;
-    }, 0);
-
-    const result = new Uint8Array(totalLength);
+  if (metadata.isBinary) {
+    // Binary file - combine Uint8Arrays
+    const totalLength = chunks.reduce((sum, chunk) =>
+      sum + (chunk instanceof Uint8Array ? chunk.length : 0), 0
+    );
+    const combined = new Uint8Array(totalLength);
     let offset = 0;
     for (const chunk of chunks) {
-      result.set(chunk as Uint8Array, offset);
-      offset += (chunk as Uint8Array).byteLength;
+      if (chunk instanceof Uint8Array) {
+        combined.set(chunk, offset);
+        offset += chunk.length;
+      }
     }
-
-    return { content: result, metadata };
+    return { content: combined, metadata };
   } else {
-    // Text file - concatenate strings
-    return {
-      content: chunks.join(''),
-      metadata,
-    };
+    // Text file - combine strings
+    const combined = chunks.filter(c => typeof c === 'string').join('');
+    return { content: combined, metadata };
   }
 }

package/src/index.ts

@@ -1,81 +1,93 @@
-// biome-ignore-start assist/source/organizeImports: Need separate exports for deprecation warnings to work properly
-/**
- * @deprecated Use `InterpreterNotReadyError` instead. Will be removed in a future version.
- */
-export { InterpreterNotReadyError as JupyterNotReadyError } from "./errors";
+// Export the main Sandbox class and utilities
 
-/**
- * @deprecated Use `isInterpreterNotReadyError` instead. Will be removed in a future version.
- */
-export { isInterpreterNotReadyError as isJupyterNotReadyError } from "./errors";
-// biome-ignore-end assist/source/organizeImports: Need separate exports for deprecation warnings to work properly
 
-// Export API response types
+// Export the new client architecture
 export {
-  CodeExecutionError,
-  ContainerNotReadyError,
-  ContextNotFoundError,
-  InterpreterNotReadyError,
-  isInterpreterNotReadyError,
-  isRetryableError,
-  isSandboxError,
-  parseErrorResponse,
-  SandboxError,
-  type SandboxErrorResponse,
-  SandboxNetworkError,
-  ServiceUnavailableError,
-} from "./errors";
-
-// Export code interpreter types
-export type {
-  ChartData,
-  CodeContext,
-  CreateContextOptions,
-  Execution,
-  ExecutionError,
-  OutputMessage,
-  Result,
-  RunCodeOptions,
-} from "./interpreter-types";
-// Export the implementations
-export { ResultImpl } from "./interpreter-types";
-// Re-export request handler utilities
-export {
-  proxyToSandbox,
-  type RouteInfo,
-  type SandboxEnv,
-} from "./request-handler";
+  CommandClient,
+  FileClient,
+  GitClient,
+  PortClient,
+  ProcessClient,
+  SandboxClient,
+  UtilityClient
+} from "./clients";
 export { getSandbox, Sandbox } from "./sandbox";
-// Export SSE parser for converting ReadableStream to AsyncIterable
-export {
-  asyncIterableToSSEStream,
-  parseSSEStream,
-  responseToAsyncIterable,
-} from "./sse-parser";
-// Export file streaming utilities
-export { streamFile, collectFile } from "./file-stream";
+
+// Legacy types are now imported from the new client architecture
+
+// Export core SDK types for consumers
 export type {
-  DeleteFileResponse,
+  BaseExecOptions,
   ExecEvent,
   ExecOptions,
-  ExecResult,
-  ExecuteResponse,
-  ExecutionSession,
-  FileChunk,
-  FileMetadata,
-  FileStream,
-  FileStreamEvent,
-  GitCheckoutResponse,
+  ExecResult,FileChunk, FileMetadata, FileStreamEvent, 
   ISandbox,
-  ListFilesResponse,
   LogEvent,
-  MkdirResponse,
-  MoveFileResponse,
   Process,
   ProcessOptions,
   ProcessStatus,
-  ReadFileResponse,
-  RenameFileResponse,
-  StreamOptions,
-  WriteFileResponse,
-} from "./types";
+  StreamOptions 
+} from "@repo/shared";
+export * from '@repo/shared';
+// Export type guards for runtime validation
+export {
+  isExecResult,
+  isProcess,
+  isProcessStatus
+} from "@repo/shared";
+// Export all client types from new architecture
+export type {
+  BaseApiResponse,
+  CommandsResponse,
+  ContainerStub,
+  ErrorResponse,
+
+  // Command client types
+  ExecuteRequest,
+  ExecuteResponse as CommandExecuteResponse,
+
+  // Port client types
+  ExposePortRequest,
+  FileOperationRequest,
+
+  // Git client types
+  GitCheckoutRequest,
+  GitCheckoutResult,
+  // Base client types
+  HttpClientOptions as SandboxClientOptions,
+
+  // File client types
+  MkdirRequest,
+
+  // Utility client types
+  PingResponse,
+  PortCloseResult,
+  PortExposeResult,
+  PortListResult,
+  ProcessCleanupResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessListResult,
+  ProcessLogsResult,
+  ProcessStartResult,
+  ReadFileRequest,
+  RequestConfig,
+  ResponseHandler,
+  SessionRequest,
+
+  // Process client types
+  StartProcessRequest,
+  UnexposePortRequest,
+  WriteFileRequest
+} from "./clients";
+export type { ExecutionCallbacks, InterpreterClient } from './clients/interpreter-client.js';
+// Export file streaming utilities for binary file support
+export { collectFile, streamFile } from './file-stream';
+// Export interpreter functionality
+export { CodeInterpreter } from './interpreter.js';
+// Re-export request handler utilities
+export {
+  proxyToSandbox, type RouteInfo, type SandboxEnv
+} from './request-handler';
+// Export SSE parser for converting ReadableStream to AsyncIterable
+export { asyncIterableToSSEStream, parseSSEStream, responseToAsyncIterable } from "./sse-parser";

package/src/interpreter.ts

@@ -1,19 +1,24 @@
-import type { InterpreterClient } from "./interpreter-client.js";
 import {
   type CodeContext,
   type CreateContextOptions,
   Execution,
+  type ExecutionError,
+  type OutputMessage,
+  type Result,
   ResultImpl,
   type RunCodeOptions,
-} from "./interpreter-types.js";
+} from "@repo/shared";
+import type { InterpreterClient } from "./clients/interpreter-client.js";
 import type { Sandbox } from "./sandbox.js";
+import { validateLanguage } from "./security.js";
 
 export class CodeInterpreter {
   private interpreterClient: InterpreterClient;
   private contexts = new Map<string, CodeContext>();
 
   constructor(sandbox: Sandbox) {
-    this.interpreterClient = sandbox.client as InterpreterClient;
+    // In init-testing architecture, client is a SandboxClient with an interpreter property
+    this.interpreterClient = (sandbox.client as any).interpreter as InterpreterClient;
   }
 
   /**
@@ -22,6 +27,9 @@ export class CodeInterpreter {
   async createCodeContext(
     options: CreateContextOptions = {}
   ): Promise<CodeContext> {
+    // Validate language before sending to container
+    validateLanguage(options.language);
+
     const context = await this.interpreterClient.createCodeContext(options);
     this.contexts.set(context.id, context);
     return context;
@@ -47,19 +55,19 @@ export class CodeInterpreter {
 
     // Stream execution
     await this.interpreterClient.runCodeStream(context.id, code, options.language, {
-      onStdout: (output) => {
+      onStdout: (output: OutputMessage) => {
         execution.logs.stdout.push(output.text);
         if (options.onStdout) return options.onStdout(output);
       },
-      onStderr: (output) => {
+      onStderr: (output: OutputMessage) => {
         execution.logs.stderr.push(output.text);
         if (options.onStderr) return options.onStderr(output);
       },
-      onResult: async (result) => {
+      onResult: async (result: Result) => {
         execution.results.push(new ResultImpl(result) as any);
         if (options.onResult) return options.onResult(result);
       },
-      onError: (error) => {
+      onError: (error: ExecutionError) => {
         execution.error = error;
         if (options.onError) return options.onError(error);
       },
@@ -83,7 +91,8 @@ export class CodeInterpreter {
     }
 
     // Create streaming response
-    const response = await this.interpreterClient.doFetch("/api/execute/code", {
+    // Note: doFetch is protected but we need direct access for raw stream response
+    const response = await (this.interpreterClient as any).doFetch("/api/execute/code", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",

package/src/request-handler.ts

@@ -13,6 +13,7 @@ export interface RouteInfo {
   port: number;
   sandboxId: string;
   path: string;
+  token: string;
 }
 
 export async function proxyToSandbox<E extends SandboxEnv>(
@@ -27,9 +28,40 @@ export async function proxyToSandbox<E extends SandboxEnv>(
       return null; // Not a request to an exposed container port
     }
 
-    const { sandboxId, port, path } = routeInfo;
+    const { sandboxId, port, path, token } = routeInfo;
     const sandbox = getSandbox(env.Sandbox, sandboxId);
 
+    // Critical security check: Validate token (mandatory for all user ports)
+    // Skip check for control plane port 3000
+    if (port !== 3000) {
+      // Validate the token matches the port
+      const isValidToken = await sandbox.validatePortToken(port, token);
+      if (!isValidToken) {
+        logSecurityEvent('INVALID_TOKEN_ACCESS_BLOCKED', {
+          port,
+          sandboxId,
+          path,
+          hostname: url.hostname,
+          url: request.url,
+          method: request.method,
+          userAgent: request.headers.get('User-Agent') || 'unknown'
+        }, 'high');
+
+        return new Response(
+          JSON.stringify({
+            error: `Access denied: Invalid token or port not exposed`,
+            code: 'INVALID_TOKEN'
+          }),
+          {
+            status: 404,
+            headers: {
+              'Content-Type': 'application/json'
+            }
+          }
+        );
+      }
+    }
+
     // Build proxy request with proper headers
     let proxyUrl: string;
 
@@ -52,6 +84,8 @@ export async function proxyToSandbox<E extends SandboxEnv>(
         'X-Sandbox-Name': sandboxId, // Pass the friendly name
       },
       body: request.body,
+      // @ts-expect-error - duplex required for body streaming in modern runtimes
+      duplex: 'half',
     });
 
     return sandbox.containerFetch(proxyRequest, port);
@@ -62,8 +96,8 @@ export async function proxyToSandbox<E extends SandboxEnv>(
 }
 
 function extractSandboxRoute(url: URL): RouteInfo | null {
-  // Parse subdomain pattern: port-sandboxId.domain
-  const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*[^.-]|[^.-])\.(.+)$/);
+  // Parse subdomain pattern: port-sandboxId-token.domain (tokens mandatory)
+  const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*[^.-]|[^.-])-([a-zA-Z0-9_-]{12,20})\.(.+)$/);
 
   if (!subdomainMatch) {
     // Log malformed subdomain attempts
@@ -78,7 +112,8 @@ function extractSandboxRoute(url: URL): RouteInfo | null {
 
   const portStr = subdomainMatch[1];
   const sandboxId = subdomainMatch[2];
-  const domain = subdomainMatch[3];
+  const token = subdomainMatch[3]; // Mandatory token
+  const domain = subdomainMatch[4];
 
   const port = parseInt(portStr, 10);
   if (!validatePort(port)) {
@@ -122,23 +157,42 @@ function extractSandboxRoute(url: URL): RouteInfo | null {
     sandboxId: sanitizedSandboxId,
     domain,
     path: url.pathname || "/",
-    hostname: url.hostname
+    hostname: url.hostname,
+    hasToken: !!token
   }, 'low');
 
   return {
     port,
     sandboxId: sanitizedSandboxId,
     path: url.pathname || "/",
+    token,
   };
 }
 
 export function isLocalhostPattern(hostname: string): boolean {
+  // Handle IPv6 addresses in brackets (with or without port)
+  if (hostname.startsWith('[')) {
+    if (hostname.includes(']:')) {
+      // [::1]:port format
+      const ipv6Part = hostname.substring(0, hostname.indexOf(']:') + 1);
+      return ipv6Part === '[::1]';
+    } else {
+      // [::1] format without port
+      return hostname === '[::1]';
+    }
+  }
+  
+  // Handle bare IPv6 without brackets
+  if (hostname === '::1') {
+    return true;
+  }
+  
+  // For IPv4 and regular hostnames, split on colon to remove port
   const hostPart = hostname.split(":")[0];
+  
   return (
     hostPart === "localhost" ||
     hostPart === "127.0.0.1" ||
-    hostPart === "::1" ||
-    hostPart === "[::1]" ||
     hostPart === "0.0.0.0"
   );
 }