sandbox-fs 1.0.0

package/dist/PathMapper.js

@@ -0,0 +1,122 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PathMapper = void 0;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+/**
+ * Handles conversion between virtual Unix-style paths and real platform-native paths
+ */
+class PathMapper {
+    constructor(rootPath) {
+        // Normalize and resolve the root path to absolute platform-native format
+        this.normalizedRoot = path.resolve(rootPath);
+        // Validate that the root path exists
+        if (!fs.existsSync(this.normalizedRoot)) {
+            throw new Error(`VFS root path does not exist: ${rootPath}`);
+        }
+        // Validate that it's a directory
+        const stats = fs.statSync(this.normalizedRoot);
+        if (!stats.isDirectory()) {
+            throw new Error(`VFS root path is not a directory: ${rootPath}`);
+        }
+    }
+    /**
+     * Get the normalized root path
+     */
+    getRoot() {
+        return this.normalizedRoot;
+    }
+    /**
+     * Convert a virtual path (Unix-style with forward slashes) to a real platform-native path
+     * @param virtualPath - Virtual path starting with /
+     * @returns Real absolute path
+     * @throws Error if path traversal is detected
+     */
+    toRealPath(virtualPath) {
+        // Validate virtual path format
+        if (!virtualPath.startsWith('/')) {
+            throw new Error(`Virtual path must start with /: ${virtualPath}`);
+        }
+        // Remove leading slash and normalize
+        const relativePath = virtualPath.slice(1);
+        // Join with root to get real path
+        const realPath = path.join(this.normalizedRoot, relativePath);
+        // Resolve to get absolute path (handles .. and .)
+        const resolvedPath = path.resolve(realPath);
+        // Security check: ensure resolved path is within root
+        // Use path.relative to check if we've escaped the root
+        const rel = path.relative(this.normalizedRoot, resolvedPath);
+        // If relative path starts with .. or is an absolute path, we've escaped
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Path traversal detected: ${virtualPath}`);
+        }
+        return resolvedPath;
+    }
+    /**
+     * Convert a real platform-native path to a virtual Unix-style path
+     * @param realPath - Real absolute path
+     * @returns Virtual path starting with /
+     * @throws Error if real path is not within VFS root
+     */
+    toVirtualPath(realPath) {
+        // Normalize the real path
+        const normalized = path.resolve(realPath);
+        // Get relative path from root
+        const rel = path.relative(this.normalizedRoot, normalized);
+        // Check if path is outside root
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Real path is outside VFS root: ${realPath}`);
+        }
+        // Convert platform separators to forward slashes
+        const virtualPath = '/' + rel.split(path.sep).join('/');
+        return virtualPath;
+    }
+    /**
+     * Check if a real path is within the VFS root
+     */
+    isWithinRoot(realPath) {
+        try {
+            const normalized = path.resolve(realPath);
+            const rel = path.relative(this.normalizedRoot, normalized);
+            return !rel.startsWith('..') && !path.isAbsolute(rel);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.PathMapper = PathMapper;
+//# sourceMappingURL=PathMapper.js.map

package/dist/PathMapper.js.map

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

package/dist/PathModule.d.ts

@@ -0,0 +1,69 @@
+import * as path from 'path';
+/**
+ * Creates a path module that operates in virtual path space
+ * All paths use Unix-style forward slashes
+ * Fixed virtual CWD of '/'
+ */
+export declare function createPathModule(): {
+    /**
+     * Normalize a path, reducing '..' and '.' parts
+     */
+    normalize(p: string): string;
+    /**
+     * Join all path segments together and normalize the result
+     */
+    join(...paths: string[]): string;
+    /**
+     * Resolve a sequence of paths to an absolute path
+     */
+    resolve(...paths: string[]): string;
+    /**
+     * Return the relative path from 'from' to 'to'
+     */
+    relative(from: string, to: string): string;
+    /**
+     * Return the directory name of a path
+     */
+    dirname(p: string): string;
+    /**
+     * Return the last portion of a path
+     */
+    basename(p: string, ext?: string): string;
+    /**
+     * Return the extension of the path
+     */
+    extname(p: string): string;
+    /**
+     * Parse a path into an object
+     */
+    parse(p: string): path.ParsedPath;
+    /**
+     * Format a path object into a string
+     */
+    format(pathObject: path.FormatInputPathObject): string;
+    /**
+     * Check if a path is absolute
+     */
+    isAbsolute(p: string): boolean;
+    /**
+     * Convert path to namespaced path (Windows-only, no-op in virtual space)
+     */
+    toNamespacedPath(p: string): string;
+    /**
+     * Path segment separator (always / in virtual space)
+     */
+    sep: string;
+    /**
+     * Path delimiter (always : in virtual space)
+     */
+    delimiter: string;
+    /**
+     * POSIX-specific methods (same as main module in virtual space)
+     */
+    posix: any;
+    /**
+     * Windows-specific methods (same as main module in virtual space)
+     */
+    win32: any;
+};
+//# sourceMappingURL=PathModule.d.ts.map

package/dist/PathModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PathModule.d.ts","sourceRoot":"","sources":["../src/PathModule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;GAIG;AACH,wBAAgB,gBAAgB;IAI5B;;OAEG;iBACU,MAAM,GAAG,MAAM;IAM5B;;OAEG;mBACY,MAAM,EAAE,GAAG,MAAM;IAIhC;;OAEG;sBACe,MAAM,EAAE,GAAG,MAAM;IAkBnC;;OAEG;mBACY,MAAM,MAAM,MAAM,GAAG,MAAM;IAI1C;;OAEG;eACQ,MAAM,GAAG,MAAM;IAI1B;;OAEG;gBACS,MAAM,QAAQ,MAAM,GAAG,MAAM;IAIzC;;OAEG;eACQ,MAAM,GAAG,MAAM;IAI1B;;OAEG;aACM,MAAM,GAAG,IAAI,CAAC,UAAU;IASjC;;OAEG;uBACgB,IAAI,CAAC,qBAAqB,GAAG,MAAM;IAStD;;OAEG;kBACW,MAAM,GAAG,OAAO;IAI9B;;OAEG;wBACiB,MAAM,GAAG,MAAM;IAKnC;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;WACY,GAAG;IAElB;;OAEG;WACY,GAAG;EAQrB"}

package/dist/PathModule.js

@@ -0,0 +1,159 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPathModule = createPathModule;
+const path = __importStar(require("path"));
+/**
+ * Creates a path module that operates in virtual path space
+ * All paths use Unix-style forward slashes
+ * Fixed virtual CWD of '/'
+ */
+function createPathModule() {
+    const virtualCwd = '/';
+    const pathModule = {
+        /**
+         * Normalize a path, reducing '..' and '.' parts
+         */
+        normalize(p) {
+            const normalized = path.posix.normalize(p);
+            // Ensure it starts with / if it's absolute-like
+            return normalized.startsWith('/') ? normalized : normalized;
+        },
+        /**
+         * Join all path segments together and normalize the result
+         */
+        join(...paths) {
+            return path.posix.join(...paths);
+        },
+        /**
+         * Resolve a sequence of paths to an absolute path
+         */
+        resolve(...paths) {
+            if (paths.length === 0) {
+                return virtualCwd;
+            }
+            let resolved = virtualCwd;
+            for (const p of paths) {
+                if (path.posix.isAbsolute(p)) {
+                    resolved = p;
+                }
+                else {
+                    resolved = path.posix.join(resolved, p);
+                }
+            }
+            return path.posix.normalize(resolved);
+        },
+        /**
+         * Return the relative path from 'from' to 'to'
+         */
+        relative(from, to) {
+            return path.posix.relative(from, to);
+        },
+        /**
+         * Return the directory name of a path
+         */
+        dirname(p) {
+            return path.posix.dirname(p);
+        },
+        /**
+         * Return the last portion of a path
+         */
+        basename(p, ext) {
+            return path.posix.basename(p, ext);
+        },
+        /**
+         * Return the extension of the path
+         */
+        extname(p) {
+            return path.posix.extname(p);
+        },
+        /**
+         * Parse a path into an object
+         */
+        parse(p) {
+            const parsed = path.posix.parse(p);
+            // Ensure root is always '/' for virtual paths
+            if (parsed.root) {
+                parsed.root = '/';
+            }
+            return parsed;
+        },
+        /**
+         * Format a path object into a string
+         */
+        format(pathObject) {
+            // Ensure root is '/' for virtual paths
+            const virtualPathObject = { ...pathObject };
+            if (virtualPathObject.root) {
+                virtualPathObject.root = '/';
+            }
+            return path.posix.format(virtualPathObject);
+        },
+        /**
+         * Check if a path is absolute
+         */
+        isAbsolute(p) {
+            return p.startsWith('/');
+        },
+        /**
+         * Convert path to namespaced path (Windows-only, no-op in virtual space)
+         */
+        toNamespacedPath(p) {
+            // In virtual space, just return the path as-is
+            return p;
+        },
+        /**
+         * Path segment separator (always / in virtual space)
+         */
+        sep: '/',
+        /**
+         * Path delimiter (always : in virtual space)
+         */
+        delimiter: ':',
+        /**
+         * POSIX-specific methods (same as main module in virtual space)
+         */
+        posix: null,
+        /**
+         * Windows-specific methods (same as main module in virtual space)
+         */
+        win32: null,
+    };
+    // Both posix and win32 reference the same virtual implementation
+    pathModule.posix = pathModule;
+    pathModule.win32 = pathModule;
+    return pathModule;
+}
+//# sourceMappingURL=PathModule.js.map

package/dist/PathModule.js.map

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

package/dist/ResourceTracker.d.ts

@@ -0,0 +1,74 @@
+import { Readable, Writable } from 'stream';
+/**
+ * Information about a tracked file descriptor
+ */
+export interface FDInfo {
+    fd: number;
+    virtualPath: string;
+    realPath: string;
+    flags: string | number;
+    mode?: number;
+    isStream: boolean;
+}
+/**
+ * Manages lifecycle of file descriptors and streams to prevent resource leaks
+ * and ensure proper cleanup when VFS is closed
+ */
+export declare class ResourceTracker {
+    private fdMap;
+    private streams;
+    private abortControllers;
+    private _closed;
+    /**
+     * Check if the VFS has been closed
+     */
+    get closed(): boolean;
+    /**
+     * Assert that the VFS is not closed, throwing EBADF if it is
+     */
+    assertNotClosed(): void;
+    /**
+     * Track a file descriptor
+     */
+    trackFD(fd: number, info: Omit<FDInfo, 'fd'>): void;
+    /**
+     * Get information about a tracked file descriptor
+     */
+    getFD(fd: number): FDInfo | undefined;
+    /**
+     * Check if a file descriptor is tracked
+     */
+    isTracked(fd: number): boolean;
+    /**
+     * Untrack a file descriptor (when closed)
+     */
+    untrackFD(fd: number): FDInfo | undefined;
+    /**
+     * Track a stream
+     */
+    trackStream(stream: Readable | Writable): void;
+    /**
+     * Untrack a stream (when closed)
+     */
+    untrackStream(stream: Readable | Writable): void;
+    /**
+     * Register an AbortSignal listener for cleanup
+     */
+    registerAbortListener(signal: AbortSignal | undefined, cleanup: () => void): void;
+    /**
+     * Dispose all tracked resources and mark as closed
+     */
+    dispose(): void;
+    /**
+     * Get all tracked file descriptors (for debugging)
+     */
+    getAllFDs(): FDInfo[];
+    /**
+     * Get count of tracked resources
+     */
+    getResourceCount(): {
+        fds: number;
+        streams: number;
+    };
+}
+//# sourceMappingURL=ResourceTracker.d.ts.map

package/dist/ResourceTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceTracker.d.ts","sourceRoot":"","sources":["../src/ResourceTracker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,gBAAgB,CAAmC;IAC3D,OAAO,CAAC,OAAO,CAAkB;IAEjC;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;OAEG;IACH,eAAe,IAAI,IAAI;IAUvB;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI;IAInD;;OAEG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIrC;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMzC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAI9C;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAIhD;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAYjF;;OAEG;IACH,OAAO,IAAI,IAAI;IAsCf;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAIrB;;OAEG;IACH,gBAAgB,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAMrD"}

package/dist/ResourceTracker.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceTracker = void 0;
+const fs = __importStar(require("fs"));
+/**
+ * Manages lifecycle of file descriptors and streams to prevent resource leaks
+ * and ensure proper cleanup when VFS is closed
+ */
+class ResourceTracker {
+    constructor() {
+        this.fdMap = new Map();
+        this.streams = new Set();
+        this.abortControllers = new Set();
+        this._closed = false;
+    }
+    /**
+     * Check if the VFS has been closed
+     */
+    get closed() {
+        return this._closed;
+    }
+    /**
+     * Assert that the VFS is not closed, throwing EBADF if it is
+     */
+    assertNotClosed() {
+        if (this._closed) {
+            const error = new Error('bad file descriptor');
+            error.code = 'EBADF';
+            error.errno = -9;
+            error.syscall = 'read';
+            throw error;
+        }
+    }
+    /**
+     * Track a file descriptor
+     */
+    trackFD(fd, info) {
+        this.fdMap.set(fd, { fd, ...info });
+    }
+    /**
+     * Get information about a tracked file descriptor
+     */
+    getFD(fd) {
+        return this.fdMap.get(fd);
+    }
+    /**
+     * Check if a file descriptor is tracked
+     */
+    isTracked(fd) {
+        return this.fdMap.has(fd);
+    }
+    /**
+     * Untrack a file descriptor (when closed)
+     */
+    untrackFD(fd) {
+        const info = this.fdMap.get(fd);
+        this.fdMap.delete(fd);
+        return info;
+    }
+    /**
+     * Track a stream
+     */
+    trackStream(stream) {
+        this.streams.add(stream);
+    }
+    /**
+     * Untrack a stream (when closed)
+     */
+    untrackStream(stream) {
+        this.streams.delete(stream);
+    }
+    /**
+     * Register an AbortSignal listener for cleanup
+     */
+    registerAbortListener(signal, cleanup) {
+        if (!signal)
+            return;
+        const controller = new AbortController();
+        this.abortControllers.add(controller);
+        signal.addEventListener('abort', () => {
+            cleanup();
+            this.abortControllers.delete(controller);
+        }, { once: true });
+    }
+    /**
+     * Dispose all tracked resources and mark as closed
+     */
+    dispose() {
+        if (this._closed)
+            return;
+        // Close all tracked file descriptors
+        for (const [fd, info] of this.fdMap) {
+            try {
+                if (!info.isStream) {
+                    fs.closeSync(fd);
+                }
+            }
+            catch (err) {
+                // Ignore errors during cleanup
+            }
+        }
+        this.fdMap.clear();
+        // Destroy all tracked streams
+        for (const stream of this.streams) {
+            try {
+                stream.destroy();
+            }
+            catch (err) {
+                // Ignore errors during cleanup
+            }
+        }
+        this.streams.clear();
+        // Abort all pending operations
+        for (const controller of this.abortControllers) {
+            try {
+                controller.abort();
+            }
+            catch (err) {
+                // Ignore errors during cleanup
+            }
+        }
+        this.abortControllers.clear();
+        this._closed = true;
+    }
+    /**
+     * Get all tracked file descriptors (for debugging)
+     */
+    getAllFDs() {
+        return Array.from(this.fdMap.values());
+    }
+    /**
+     * Get count of tracked resources
+     */
+    getResourceCount() {
+        return {
+            fds: this.fdMap.size,
+            streams: this.streams.size,
+        };
+    }
+}
+exports.ResourceTracker = ResourceTracker;
+//# sourceMappingURL=ResourceTracker.js.map

package/dist/ResourceTracker.js.map

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