@treesap/sandbox 0.2.0

package/src/file-service.ts

@@ -0,0 +1,273 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { Readable } from 'stream';
+import { createReadStream, createWriteStream } from 'fs';
+
+export interface FileInfo {
+  name: string;
+  path: string;
+  type: 'file' | 'directory';
+  size?: number;
+  mtime?: number;
+}
+
+export interface ListFilesOptions {
+  recursive?: boolean;
+  pattern?: string;
+  includeHidden?: boolean;
+}
+
+export interface ReadFileOptions {
+  encoding?: BufferEncoding;
+  raw?: boolean;
+}
+
+export interface WriteFileOptions {
+  encoding?: BufferEncoding;
+  mode?: number;
+  createDirs?: boolean;
+}
+
+/**
+ * Service for managing file operations within a sandbox
+ * Includes path validation to prevent directory traversal attacks
+ */
+export class FileService {
+  private basePath: string;
+
+  constructor(basePath: string) {
+    this.basePath = path.resolve(basePath);
+  }
+
+  /**
+   * Validate and resolve a path within the sandbox
+   * Prevents directory traversal attacks
+   */
+  private resolvePath(filePath: string): string {
+    const resolved = path.resolve(this.basePath, filePath);
+
+    // Ensure the resolved path is within basePath
+    if (!resolved.startsWith(this.basePath)) {
+      throw new Error('Path traversal detected - access denied');
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Read a file's contents
+   */
+  async readFile(filePath: string, options: ReadFileOptions = {}): Promise<string | Buffer> {
+    const resolved = this.resolvePath(filePath);
+
+    if (options.raw) {
+      return await fs.readFile(resolved);
+    }
+
+    const encoding = options.encoding || 'utf-8';
+    return await fs.readFile(resolved, encoding);
+  }
+
+  /**
+   * Write content to a file
+   */
+  async writeFile(
+    filePath: string,
+    content: string | Buffer,
+    options: WriteFileOptions = {}
+  ): Promise<void> {
+    const resolved = this.resolvePath(filePath);
+
+    // Create parent directories if requested
+    if (options.createDirs) {
+      const dir = path.dirname(resolved);
+      await fs.mkdir(dir, { recursive: true });
+    }
+
+    const encoding = options.encoding || 'utf-8';
+    const writeOptions: any = { encoding };
+
+    if (options.mode) {
+      writeOptions.mode = options.mode;
+    }
+
+    await fs.writeFile(resolved, content, writeOptions);
+  }
+
+  /**
+   * List files in a directory
+   */
+  async listFiles(dirPath: string = '.', options: ListFilesOptions = {}): Promise<FileInfo[]> {
+    const resolved = this.resolvePath(dirPath);
+
+    const files: FileInfo[] = [];
+
+    const entries = await fs.readdir(resolved, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // Skip hidden files unless requested
+      if (!options.includeHidden && entry.name.startsWith('.')) {
+        continue;
+      }
+
+      // Apply pattern filter if provided
+      if (options.pattern && !this.matchPattern(entry.name, options.pattern)) {
+        continue;
+      }
+
+      const fullPath = path.join(resolved, entry.name);
+      const relativePath = path.relative(this.basePath, fullPath);
+
+      const fileInfo: FileInfo = {
+        name: entry.name,
+        path: relativePath,
+        type: entry.isDirectory() ? 'directory' : 'file',
+      };
+
+      // Get file stats for size and mtime
+      try {
+        const stats = await fs.stat(fullPath);
+        fileInfo.size = stats.size;
+        fileInfo.mtime = stats.mtimeMs;
+      } catch {
+        // Ignore stat errors
+      }
+
+      files.push(fileInfo);
+
+      // Recursively list subdirectories if requested
+      if (options.recursive && entry.isDirectory()) {
+        const subFiles = await this.listFiles(relativePath, options);
+        files.push(...subFiles);
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Delete a file or directory
+   */
+  async deleteFile(filePath: string, options: { recursive?: boolean } = {}): Promise<void> {
+    const resolved = this.resolvePath(filePath);
+
+    const stats = await fs.stat(resolved);
+
+    if (stats.isDirectory()) {
+      await fs.rm(resolved, { recursive: options.recursive, force: true });
+    } else {
+      await fs.unlink(resolved);
+    }
+  }
+
+  /**
+   * Check if a file or directory exists
+   */
+  async exists(filePath: string): Promise<boolean> {
+    try {
+      const resolved = this.resolvePath(filePath);
+      await fs.access(resolved);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get file stats
+   */
+  async stat(filePath: string): Promise<FileInfo> {
+    const resolved = this.resolvePath(filePath);
+    const stats = await fs.stat(resolved);
+    const relativePath = path.relative(this.basePath, resolved);
+
+    return {
+      name: path.basename(resolved),
+      path: relativePath,
+      type: stats.isDirectory() ? 'directory' : 'file',
+      size: stats.size,
+      mtime: stats.mtimeMs,
+    };
+  }
+
+  /**
+   * Create a directory
+   */
+  async mkdir(dirPath: string, options: { recursive?: boolean } = {}): Promise<void> {
+    const resolved = this.resolvePath(dirPath);
+    await fs.mkdir(resolved, { recursive: options.recursive });
+  }
+
+  /**
+   * Copy a file or directory
+   */
+  async copy(
+    sourcePath: string,
+    destPath: string,
+    options: { overwrite?: boolean } = {}
+  ): Promise<void> {
+    const resolvedSource = this.resolvePath(sourcePath);
+    const resolvedDest = this.resolvePath(destPath);
+
+    // Check if destination exists
+    if (!options.overwrite) {
+      try {
+        await fs.access(resolvedDest);
+        throw new Error('Destination already exists');
+      } catch (err: any) {
+        if (err.code !== 'ENOENT') {
+          throw err;
+        }
+      }
+    }
+
+    await fs.cp(resolvedSource, resolvedDest, { recursive: true });
+  }
+
+  /**
+   * Move/rename a file or directory
+   */
+  async move(sourcePath: string, destPath: string): Promise<void> {
+    const resolvedSource = this.resolvePath(sourcePath);
+    const resolvedDest = this.resolvePath(destPath);
+
+    await fs.rename(resolvedSource, resolvedDest);
+  }
+
+  /**
+   * Create a readable stream for a file
+   */
+  createReadStream(filePath: string): Readable {
+    const resolved = this.resolvePath(filePath);
+    return createReadStream(resolved);
+  }
+
+  /**
+   * Create a writable stream for a file
+   */
+  createWriteStream(filePath: string): NodeJS.WritableStream {
+    const resolved = this.resolvePath(filePath);
+    return createWriteStream(resolved);
+  }
+
+  /**
+   * Simple glob pattern matching
+   */
+  private matchPattern(filename: string, pattern: string): boolean {
+    // Convert glob pattern to regex
+    const regexPattern = pattern
+      .replace(/\./g, '\\.')
+      .replace(/\*/g, '.*')
+      .replace(/\?/g, '.');
+
+    const regex = new RegExp(`^${regexPattern}$`, 'i');
+    return regex.test(filename);
+  }
+
+  /**
+   * Get the base path of this file service
+   */
+  getBasePath(): string {
+    return this.basePath;
+  }
+}

package/src/http-exposure-service.ts

@@ -0,0 +1,232 @@
+/**
+ * HTTP Exposure Service
+ * Integrates with Caddy Admin API to dynamically expose sandbox ports
+ */
+
+export interface HttpExposureConfig {
+  /**
+   * Caddy Admin API URL (default: http://localhost:2019)
+   */
+  caddyAdminUrl: string;
+
+  /**
+   * Base domain for sandbox subdomains (e.g., sandbox.yourdomain.com)
+   */
+  baseDomain: string;
+
+  /**
+   * Protocol to use for generated URLs (default: https)
+   */
+  protocol: 'http' | 'https';
+
+  /**
+   * Host where sandbox ports are accessible (default: localhost)
+   * This is the internal address Caddy will proxy to
+   */
+  upstreamHost: string;
+}
+
+export interface ExposedEndpoint {
+  sandboxId: string;
+  port: number;
+  publicUrl: string;
+  routeId: string;
+  createdAt: number;
+}
+
+const DEFAULT_CONFIG: HttpExposureConfig = {
+  caddyAdminUrl: 'http://localhost:2019',
+  baseDomain: 'sandbox.localhost',
+  protocol: 'https',
+  upstreamHost: 'localhost',
+};
+
+/**
+ * Service for managing HTTP exposure of sandbox ports via Caddy
+ */
+export class HttpExposureService {
+  private config: HttpExposureConfig;
+  private exposures: Map<string, ExposedEndpoint[]> = new Map();
+
+  constructor(config: Partial<HttpExposureConfig> = {}) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      // Allow env vars to override
+      caddyAdminUrl: config.caddyAdminUrl || process.env.CADDY_ADMIN_URL || DEFAULT_CONFIG.caddyAdminUrl,
+      baseDomain: config.baseDomain || process.env.SANDBOX_DOMAIN || DEFAULT_CONFIG.baseDomain,
+      protocol: (config.protocol || process.env.SANDBOX_PROTOCOL || DEFAULT_CONFIG.protocol) as 'http' | 'https',
+      upstreamHost: config.upstreamHost || process.env.SANDBOX_UPSTREAM_HOST || DEFAULT_CONFIG.upstreamHost,
+    };
+  }
+
+  /**
+   * Generate a unique subdomain for a sandbox port
+   */
+  private generateSubdomain(sandboxId: string, port: number): string {
+    // Use first 8 chars of sandbox ID + port for a shorter, readable subdomain
+    const shortId = sandboxId.substring(0, 8);
+    return `${shortId}-${port}`;
+  }
+
+  /**
+   * Generate a unique route ID for Caddy
+   */
+  private generateRouteId(sandboxId: string, port: number): string {
+    return `sandbox-${sandboxId}-${port}`;
+  }
+
+  /**
+   * Expose a sandbox port and return the public URL
+   */
+  async expose(sandboxId: string, port: number): Promise<string> {
+    const subdomain = this.generateSubdomain(sandboxId, port);
+    const routeId = this.generateRouteId(sandboxId, port);
+    const hostname = `${subdomain}.${this.config.baseDomain}`;
+    const publicUrl = `${this.config.protocol}://${hostname}`;
+
+    // Check if already exposed
+    const existing = this.getExposure(sandboxId, port);
+    if (existing) {
+      return existing.publicUrl;
+    }
+
+    // Create Caddy route configuration
+    const route = {
+      '@id': routeId,
+      match: [{ host: [hostname] }],
+      handle: [
+        {
+          handler: 'reverse_proxy',
+          upstreams: [{ dial: `${this.config.upstreamHost}:${port}` }],
+        },
+      ],
+    };
+
+    try {
+      // Add route to Caddy via Admin API
+      const response = await fetch(
+        `${this.config.caddyAdminUrl}/config/apps/http/servers/srv0/routes`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(route),
+        }
+      );
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Failed to add Caddy route: ${errorText}`);
+      }
+
+      // Track the exposure
+      const endpoint: ExposedEndpoint = {
+        sandboxId,
+        port,
+        publicUrl,
+        routeId,
+        createdAt: Date.now(),
+      };
+
+      const sandboxExposures = this.exposures.get(sandboxId) || [];
+      sandboxExposures.push(endpoint);
+      this.exposures.set(sandboxId, sandboxExposures);
+
+      return publicUrl;
+    } catch (error: any) {
+      // If Caddy is not available, return a placeholder URL for development
+      if (error.cause?.code === 'ECONNREFUSED') {
+        console.warn(`Caddy not available at ${this.config.caddyAdminUrl}. Using placeholder URL.`);
+
+        // Still track the exposure locally
+        const endpoint: ExposedEndpoint = {
+          sandboxId,
+          port,
+          publicUrl: `http://${this.config.upstreamHost}:${port}`,
+          routeId,
+          createdAt: Date.now(),
+        };
+
+        const sandboxExposures = this.exposures.get(sandboxId) || [];
+        sandboxExposures.push(endpoint);
+        this.exposures.set(sandboxId, sandboxExposures);
+
+        return endpoint.publicUrl;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Remove HTTP exposure for a sandbox port (or all ports if port is undefined)
+   */
+  async unexpose(sandboxId: string, port?: number): Promise<void> {
+    const endpoints = this.exposures.get(sandboxId) || [];
+    const toRemove = port
+      ? endpoints.filter((e) => e.port === port)
+      : endpoints;
+
+    for (const endpoint of toRemove) {
+      try {
+        // Remove route from Caddy via Admin API
+        const response = await fetch(
+          `${this.config.caddyAdminUrl}/id/${endpoint.routeId}`,
+          { method: 'DELETE' }
+        );
+
+        // Ignore 404 errors (route doesn't exist)
+        if (!response.ok && response.status !== 404) {
+          console.warn(`Failed to remove Caddy route ${endpoint.routeId}: ${response.status}`);
+        }
+      } catch (error: any) {
+        // Ignore connection errors (Caddy not available)
+        if (error.cause?.code !== 'ECONNREFUSED') {
+          console.warn(`Error removing Caddy route: ${error.message}`);
+        }
+      }
+    }
+
+    // Update local tracking
+    if (port) {
+      this.exposures.set(
+        sandboxId,
+        endpoints.filter((e) => e.port !== port)
+      );
+    } else {
+      this.exposures.delete(sandboxId);
+    }
+  }
+
+  /**
+   * Get all exposures for a sandbox
+   */
+  getExposures(sandboxId: string): ExposedEndpoint[] {
+    return this.exposures.get(sandboxId) || [];
+  }
+
+  /**
+   * Get a specific exposure
+   */
+  getExposure(sandboxId: string, port: number): ExposedEndpoint | undefined {
+    const endpoints = this.exposures.get(sandboxId) || [];
+    return endpoints.find((e) => e.port === port);
+  }
+
+  /**
+   * Get all exposures across all sandboxes
+   */
+  getAllExposures(): ExposedEndpoint[] {
+    const all: ExposedEndpoint[] = [];
+    for (const endpoints of this.exposures.values()) {
+      all.push(...endpoints);
+    }
+    return all;
+  }
+
+  /**
+   * Clean up all exposures for a sandbox (called when sandbox is destroyed)
+   */
+  async cleanup(sandboxId: string): Promise<void> {
+    await this.unexpose(sandboxId);
+  }
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+/**
+ * TreeSap Sandbox v1.0
+ *
+ * A self-hosted sandbox API for isolated code execution and file management.
+ * Provides a Cloudflare-style API for managing sandboxed environments.
+ *
+ * @example Server usage
+ * ```typescript
+ * import { startServer } from '@treesap/sandbox';
+ *
+ * // Start the sandbox server
+ * const { server, manager } = await startServer({
+ *   port: 3000,
+ *   basePath: './.sandboxes'
+ * });
+ * ```
+ *
+ * @example Client SDK usage
+ * ```typescript
+ * import { SandboxClient } from '@treesap/sandbox';
+ *
+ * // Create a new sandbox
+ * const sandbox = await SandboxClient.create('http://localhost:3000');
+ *
+ * // Execute commands
+ * const result = await sandbox.exec('npm install');
+ * console.log(result.stdout);
+ *
+ * // File operations
+ * await sandbox.writeFile('package.json', JSON.stringify(pkg, null, 2));
+ * const files = await sandbox.listFiles();
+ *
+ * // Process management
+ * const server = await sandbox.startProcess('node server.js');
+ * const logs = await sandbox.streamProcessLogs(server.id);
+ *
+ * // Cleanup
+ * await sandbox.destroy({ cleanup: true });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Server API
+// ============================================================================
+
+export { startServer, createServer } from './api-server';
+export type { ServerConfig } from './api-server';
+
+// ============================================================================
+// Client SDK
+// ============================================================================
+
+export { SandboxClient, parseSSEStream } from './client';
+export type { SandboxClientConfig, CreateSandboxResponse } from './client';
+
+// ============================================================================
+// Core Components
+// ============================================================================
+
+export { Sandbox } from './sandbox';
+export { SandboxManager } from './sandbox-manager';
+export { FileService } from './file-service';
+export { StreamService } from './stream-service';
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type {
+  SandboxConfig,
+  ProcessInfo,
+  ExecOptions,
+  ExecuteResponse,
+} from './sandbox';
+
+export type { SandboxManagerConfig } from './sandbox-manager';
+
+export type {
+  FileInfo,
+  ListFilesOptions,
+  ReadFileOptions,
+  WriteFileOptions,
+} from './file-service';
+
+export type { ExecEvent, ExecEventType, LogEvent } from './stream-service';
+
+// ============================================================================
+// Auth & Middleware
+// ============================================================================
+
+export { createAuthMiddleware, parseApiKeysFromEnv } from './auth-middleware';
+export type { AuthConfig } from './auth-middleware';
+
+// ============================================================================
+// HTTP Exposure
+// ============================================================================
+
+export { HttpExposureService } from './http-exposure-service';
+export type { HttpExposureConfig, ExposedEndpoint } from './http-exposure-service';