@cloudflare/sandbox 0.0.0-db09b4d → 0.0.0-e1fa354

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');
+    }
+  });
+}