gitx.do 0.0.1

package/dist/mcp/sandbox.d.ts

@@ -0,0 +1,261 @@
+/**
+ * MCP Sandbox Execution Environment
+ *
+ * Provides isolated execution environment for MCP tools with:
+ * - Resource limits (memory, CPU, time)
+ * - Capability restrictions (file, network, process)
+ * - Safe git operation execution
+ * - Audit logging
+ *
+ * SECURITY: Uses Node.js vm module for proper isolation instead of
+ * string analysis, which can be easily bypassed.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Sandbox error codes
+ */
+export declare enum SandboxErrorCode {
+    TIMEOUT = "TIMEOUT",
+    MEMORY_LIMIT_EXCEEDED = "MEMORY_LIMIT_EXCEEDED",
+    CPU_LIMIT_EXCEEDED = "CPU_LIMIT_EXCEEDED",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    EXECUTION_ERROR = "EXECUTION_ERROR",
+    FILE_DESCRIPTOR_LIMIT = "FILE_DESCRIPTOR_LIMIT",
+    PROCESS_LIMIT_EXCEEDED = "PROCESS_LIMIT_EXCEEDED",
+    BANDWIDTH_LIMIT_EXCEEDED = "BANDWIDTH_LIMIT_EXCEEDED",
+    DISK_LIMIT_EXCEEDED = "DISK_LIMIT_EXCEEDED",
+    SANDBOX_CRASHED = "SANDBOX_CRASHED",
+    SANDBOX_PAUSED = "SANDBOX_PAUSED"
+}
+/**
+ * Sandbox error class
+ */
+export declare class SandboxError extends Error {
+    code: SandboxErrorCode;
+    data?: Record<string, unknown>;
+    stack?: string;
+    constructor(code: SandboxErrorCode, message: string, data?: Record<string, unknown>);
+    toJSON(): {
+        code: SandboxErrorCode;
+        message: string;
+        data?: Record<string, unknown>;
+    };
+}
+/**
+ * Sandbox state enum
+ */
+export declare enum SandboxState {
+    IDLE = "IDLE",
+    RUNNING = "RUNNING",
+    PAUSED = "PAUSED",
+    DESTROYED = "DESTROYED"
+}
+/**
+ * Isolation level for sandbox
+ */
+export type IsolationLevel = 'strict' | 'normal' | 'lax';
+/**
+ * Resource limits configuration
+ */
+export interface ResourceLimits {
+    memoryLimit?: number;
+    cpuTimeLimit?: number;
+    maxOpenFiles?: number;
+    maxProcesses?: number;
+    networkBandwidthLimit?: number;
+    diskWriteLimit?: number;
+}
+/**
+ * Permission set for sandbox
+ */
+export interface PermissionSet {
+    fileRead?: boolean;
+    fileWrite?: boolean;
+    network?: boolean;
+    spawn?: boolean;
+    env?: boolean;
+    nativeModules?: boolean;
+    allowedPaths?: string[];
+    envWhitelist?: string[];
+}
+/**
+ * Permission preset types
+ */
+export type PermissionPreset = 'readonly' | 'full' | 'network-only';
+/**
+ * Sandbox configuration
+ */
+export interface SandboxConfig {
+    timeout?: number;
+    memoryLimit?: number;
+    cpuTimeLimit?: number;
+    maxOpenFiles?: number;
+    maxProcesses?: number;
+    networkBandwidthLimit?: number;
+    diskWriteLimit?: number;
+    isolationLevel?: IsolationLevel;
+    env?: Record<string, string>;
+    workingDirectory?: string;
+    permissions?: PermissionSet;
+    permissionPreset?: PermissionPreset;
+    resourceLimits?: ResourceLimits;
+    queueOnPause?: boolean;
+    maxConcurrentExecutions?: number;
+}
+/**
+ * Execution options
+ */
+export interface ExecutionOptions {
+    timeout?: number;
+    context?: Record<string, unknown>;
+}
+/**
+ * Resource usage statistics
+ */
+export interface ResourceStats {
+    memoryUsed: number;
+    cpuTimeUsed: number;
+    executionCount: number;
+    activeHandles: number;
+}
+/**
+ * Resource usage in result
+ */
+export interface ResourceUsage {
+    memoryUsed: number;
+    cpuTimeUsed?: number;
+}
+/**
+ * Result metadata
+ */
+export interface ResultMetadata {
+    startTime: number;
+    endTime: number;
+    elapsedMs: number;
+}
+/**
+ * Permission violation record
+ */
+export interface PermissionViolation {
+    permission: string;
+    timestamp: number;
+    details?: string;
+}
+/**
+ * Sandbox execution result
+ */
+export interface SandboxResult<T = unknown> {
+    value?: T;
+    error?: SandboxError;
+    sandboxId: string;
+    metadata?: ResultMetadata;
+    resourceUsage?: ResourceUsage;
+}
+/**
+ * MCP Sandbox class for isolated execution
+ *
+ * SECURITY: This implementation uses Node.js vm module with proper context
+ * isolation and runtime permission checks instead of string analysis.
+ */
+export declare class MCPSandbox extends EventEmitter {
+    private id;
+    private config;
+    private state;
+    private resourceStats;
+    private permissionViolations;
+    private permissions;
+    private executionQueue;
+    private activeExecutions;
+    private globalContext;
+    constructor(config?: SandboxConfig);
+    getId(): string;
+    getConfig(): SandboxConfig;
+    getState(): SandboxState;
+    getPermissions(): PermissionSet;
+    getResourceStats(): ResourceStats;
+    getResourceLimits(): ResourceLimits;
+    getPermissionViolations(): PermissionViolation[];
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cleanup(): Promise<void>;
+    destroy(): Promise<void>;
+    execute<T>(fn: (() => T) | (() => Promise<T>), options?: ExecutionOptions): Promise<SandboxResult<T>>;
+    private executeInSandbox;
+    /**
+     * Pre-check function for static analysis of potential violations
+     *
+     * SECURITY NOTE: This performs two types of checks:
+     * 1. Resource limit checks (memory, CPU, bandwidth) - defense-in-depth for obvious cases
+     * 2. Permission checks for module imports - enforced before execution starts
+     *
+     * The permission checks here are CRITICAL for security because we cannot intercept
+     * dynamic import() calls at runtime without experimental Node.js loader hooks.
+     * By analyzing the function source, we can detect which modules will be imported
+     * and block execution before it starts.
+     *
+     * This is combined with runtime fs proxy checks for additional security layers.
+     */
+    private preCheckResourceLimits;
+    /**
+     * Create a secure require/import function that enforces runtime permission checks
+     */
+    private createSecureImport;
+    /**
+     * Create a secure fs module proxy that checks permissions at runtime
+     */
+    private createSecureFs;
+    /**
+     * Run function with secure context using runtime permission checks
+     *
+     * SECURITY: This replaces the previous string-analysis approach with
+     * actual runtime interception of dangerous operations.
+     */
+    private runWithSecureContext;
+    /**
+     * Wrap the user function to intercept dynamic imports
+     */
+    private wrapFunctionWithSecureImports;
+    /**
+     * Create an isolated process object with permission checks
+     */
+    private createIsolatedProcess;
+    private createIsolatedEnv;
+    private createPermissionError;
+    private recordPermissionViolation;
+    private wrapError;
+}
+/**
+ * Create a new sandbox instance
+ */
+export declare function createSandbox(config?: SandboxConfig): MCPSandbox;
+/**
+ * Sandbox pool configuration
+ */
+export interface SandboxPoolConfig {
+    size: number;
+    acquireTimeout?: number;
+    sandboxConfig?: SandboxConfig;
+}
+/**
+ * Sandbox pool for managing multiple sandbox instances
+ */
+export declare class SandboxPool {
+    private sandboxes;
+    private availableSandboxes;
+    private acquireTimeout;
+    private waiters;
+    private isShutdown;
+    constructor(config: SandboxPoolConfig);
+    size(): number;
+    available(): number;
+    acquire(): Promise<MCPSandbox>;
+    release(sandbox: MCPSandbox): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a sandbox pool
+ */
+export declare function createSandboxPool(config: SandboxPoolConfig): SandboxPool;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/mcp/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/mcp/sandbox.ts"],"names":[],"mappings":"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"}