@cloudflare/sandbox 0.0.0-02ee8fe

package/src/security.ts

@@ -0,0 +1,104 @@
+/**
+ * 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;
+}
+
+
+/**
+ * Validates language for code interpreter
+ * Only allows supported languages
+ */
+export function validateLanguage(language: string | undefined): void {
+  if (!language) {
+    return; // undefined is valid, will default to python
+  }
+
+  const supportedLanguages = ['python', 'python3', 'javascript', 'js', 'node', 'typescript', 'ts'];
+  const normalized = language.toLowerCase();
+
+  if (!supportedLanguages.includes(normalized)) {
+    throw new SecurityError(
+      `Unsupported language '${language}'. Supported languages: python, javascript, typescript`,
+      'INVALID_LANGUAGE'
+    );
+  }
+}

package/src/sse-parser.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 {
+            // Skip invalid JSON events and continue processing
+          }
+        }
+        // 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 {
+          // Skip invalid JSON in final event
+        }
+      }
+    }
+  } 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
+    }
+  });
+}

package/src/version.ts

@@ -0,0 +1,6 @@
+/**
+ * SDK version - automatically synchronized with package.json by Changesets
+ * This file is auto-updated by .github/changeset-version.ts during releases
+ * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
+ */
+export const SDK_VERSION = '0.4.12';

package/startup.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+exec bun dist/index.js

package/tests/base-client.test.ts

@@ -0,0 +1,328 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { BaseApiResponse, HttpClientOptions } from '../src/clients';
+import { BaseHttpClient } from '../src/clients/base-client';
+import type { ErrorResponse } from '../src/errors';
+import {
+  CommandError,
+  FileNotFoundError,
+  FileSystemError,
+  PermissionDeniedError,
+  SandboxError
+} from '../src/errors';
+
+interface TestDataResponse extends BaseApiResponse {
+  data: string;
+}
+
+interface TestResourceResponse extends BaseApiResponse {
+  id: string;
+}
+
+interface TestSourceResponse extends BaseApiResponse {
+  source: string;
+}
+
+interface TestStatusResponse extends BaseApiResponse {
+  status: string;
+}
+
+class TestHttpClient extends BaseHttpClient {
+  constructor(options: HttpClientOptions = {}) {
+    super({
+      baseUrl: 'http://test.com',
+      port: 3000,
+      ...options,
+    });
+  }
+
+  public async testRequest<T = BaseApiResponse>(endpoint: string, data?: Record<string, unknown>): Promise<T> {
+    if (data) {
+      return this.post<T>(endpoint, data);
+    }
+    return this.get<T>(endpoint);
+  }
+
+  public async testStreamRequest(endpoint: string): Promise<ReadableStream> {
+    const response = await this.doFetch(endpoint);
+    return this.handleStreamResponse(response);
+  }
+
+  public async testErrorHandling(errorResponse: ErrorResponse) {
+    const response = new Response(
+      JSON.stringify(errorResponse),
+      { status: errorResponse.httpStatus || 400 }
+    );
+    return this.handleErrorResponse(response);
+  }
+}
+
+describe('BaseHttpClient', () => {
+  let client: TestHttpClient;
+  let mockFetch: ReturnType<typeof vi.fn>;
+  let onError: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+    onError = vi.fn();
+    
+    client = new TestHttpClient({
+      baseUrl: 'http://test.com',
+      port: 3000,
+      onError,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('core request functionality', () => {
+    it('should handle successful API requests', async () => {
+      mockFetch.mockResolvedValue(new Response(
+        JSON.stringify({ success: true, data: 'operation completed' }),
+        { status: 200 }
+      ));
+
+      const result = await client.testRequest<TestDataResponse>('/api/test');
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe('operation completed');
+    });
+
+    it('should handle POST requests with data', async () => {
+      const requestData = { action: 'create', name: 'test-resource' };
+      mockFetch.mockResolvedValue(new Response(
+        JSON.stringify({ success: true, id: 'resource-123' }),
+        { status: 201 }
+      ));
+
+      const result = await client.testRequest<TestResourceResponse>('/api/create', requestData);
+
+      expect(result.success).toBe(true);
+      expect(result.id).toBe('resource-123');
+
+      const [url, options] = mockFetch.mock.calls[0];
+      expect(url).toBe('http://test.com/api/create');
+      expect(options.method).toBe('POST');
+      expect(options.headers['Content-Type']).toBe('application/json');
+      expect(JSON.parse(options.body)).toEqual(requestData);
+    });
+  });
+
+  describe('error handling and mapping', () => {
+    it('should map container errors to client errors', async () => {
+      const errorMappingTests = [
+        {
+          containerError: {
+            code: 'FILE_NOT_FOUND',
+            message: 'File not found: /test.txt',
+            context: { path: '/test.txt' },
+            httpStatus: 404,
+            timestamp: new Date().toISOString()
+          },
+          expectedError: FileNotFoundError,
+        },
+        {
+          containerError: {
+            code: 'PERMISSION_DENIED',
+            message: 'Permission denied',
+            context: { path: '/secure.txt' },
+            httpStatus: 403,
+            timestamp: new Date().toISOString()
+          },
+          expectedError: PermissionDeniedError,
+        },
+        {
+          containerError: {
+            code: 'COMMAND_EXECUTION_ERROR',
+            message: 'Command failed: badcmd',
+            context: { command: 'badcmd' },
+            httpStatus: 400,
+            timestamp: new Date().toISOString()
+          },
+          expectedError: CommandError,
+        },
+        {
+          containerError: {
+            code: 'FILESYSTEM_ERROR',
+            message: 'Filesystem error',
+            context: { path: '/test' },
+            httpStatus: 500,
+            timestamp: new Date().toISOString()
+          },
+          expectedError: FileSystemError,
+        },
+        {
+          containerError: {
+            code: 'UNKNOWN_ERROR',
+            message: 'Unknown error',
+            context: {},
+            httpStatus: 500,
+            timestamp: new Date().toISOString()
+          },
+          expectedError: SandboxError,
+        }
+      ];
+
+      for (const test of errorMappingTests) {
+        await expect(client.testErrorHandling(test.containerError as ErrorResponse))
+          .rejects.toThrow(test.expectedError);
+
+        expect(onError).toHaveBeenCalledWith(test.containerError.message, undefined);
+      }
+    });
+
+    it('should handle malformed error responses', async () => {
+      mockFetch.mockResolvedValue(new Response(
+        'invalid json {',
+        { status: 500 }
+      ));
+
+      await expect(client.testRequest('/api/test'))
+        .rejects.toThrow(SandboxError);
+    });
+
+    it('should handle network failures', async () => {
+      mockFetch.mockRejectedValue(new Error('Network connection timeout'));
+
+      await expect(client.testRequest('/api/test'))
+        .rejects.toThrow('Network connection timeout');
+    });
+
+    it('should handle server unavailable scenarios', async () => {
+      mockFetch.mockResolvedValue(new Response(
+        'Service Unavailable',
+        { status: 503 }
+      ));
+
+      await expect(client.testRequest('/api/test'))
+        .rejects.toThrow(SandboxError);
+
+      expect(onError).toHaveBeenCalledWith('HTTP error! status: 503', undefined);
+    });
+  });
+
+
+  describe('streaming functionality', () => {
+    it('should handle streaming responses', async () => {
+      const streamData = 'data: {"type":"output","content":"stream data"}\n\n';
+      const mockStream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(streamData));
+          controller.close();
+        }
+      });
+
+      mockFetch.mockResolvedValue(new Response(mockStream, {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' }
+      }));
+
+      const stream = await client.testStreamRequest('/api/stream');
+
+      expect(stream).toBeInstanceOf(ReadableStream);
+
+      const reader = stream.getReader();
+      const { done, value } = await reader.read();
+      const content = new TextDecoder().decode(value);
+
+      expect(done).toBe(false);
+      expect(content).toContain('stream data');
+
+      reader.releaseLock();
+    });
+
+    it('should handle streaming errors', async () => {
+      mockFetch.mockResolvedValue(new Response(
+        JSON.stringify({ error: 'Stream initialization failed', code: 'STREAM_ERROR' }),
+        { status: 400 }
+      ));
+
+      await expect(client.testStreamRequest('/api/bad-stream'))
+        .rejects.toThrow(SandboxError);
+    });
+
+    it('should handle missing stream body', async () => {
+      mockFetch.mockResolvedValue(new Response(null, {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' }
+      }));
+
+      await expect(client.testStreamRequest('/api/empty-stream'))
+        .rejects.toThrow('No response body for streaming');
+    });
+  });
+
+  describe('stub integration', () => {
+    it('should use stub when provided instead of fetch', async () => {
+      const stubFetch = vi.fn().mockResolvedValue(new Response(
+        JSON.stringify({ success: true, source: 'stub' }),
+        { status: 200 }
+      ));
+
+      const stub = { containerFetch: stubFetch };
+      const stubClient = new TestHttpClient({
+        baseUrl: 'http://test.com',
+        port: 3000,
+        stub,
+      });
+
+      const result = await stubClient.testRequest<TestSourceResponse>('/api/stub-test');
+
+      expect(result.success).toBe(true);
+      expect(result.source).toBe('stub');
+      expect(stubFetch).toHaveBeenCalledWith(
+        'http://localhost:3000/api/stub-test',
+        { method: 'GET' },
+        3000
+      );
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('should handle stub errors', async () => {
+      const stubFetch = vi.fn().mockRejectedValue(new Error('Stub connection failed'));
+      const stub = { containerFetch: stubFetch };
+      const stubClient = new TestHttpClient({
+        baseUrl: 'http://test.com',
+        port: 3000,
+        stub,
+      });
+
+      await expect(stubClient.testRequest('/api/stub-error'))
+        .rejects.toThrow('Stub connection failed');
+    });
+  });
+
+  describe('edge cases and resilience', () => {
+    it('should handle responses with unusual status codes', async () => {
+      const unusualStatusTests = [
+        { status: 201, shouldSucceed: true },
+        { status: 202, shouldSucceed: true },
+        { status: 409, shouldSucceed: false },
+        { status: 422, shouldSucceed: false },
+        { status: 429, shouldSucceed: false },
+      ];
+
+      for (const test of unusualStatusTests) {
+        mockFetch.mockResolvedValueOnce(new Response(
+          test.shouldSucceed
+            ? JSON.stringify({ success: true, status: test.status })
+            : JSON.stringify({ error: `Status ${test.status}` }),
+          { status: test.status }
+        ));
+
+        if (test.shouldSucceed) {
+          const result = await client.testRequest<TestStatusResponse>('/api/unusual-status');
+          expect(result.success).toBe(true);
+          expect(result.status).toBe(test.status);
+        } else {
+          await expect(client.testRequest('/api/unusual-status'))
+            .rejects.toThrow();
+        }
+      }
+    });
+  });
+});