sandbox-fs 1.0.0

package/src/FSModule.ts

@@ -0,0 +1,546 @@
+import * as fs from 'fs';
+import type { PathMapper } from './PathMapper';
+import type { ResourceTracker } from './ResourceTracker';
+import { callbackify, callbackifyVoid } from './utils/callbackify';
+
+// Import operations
+import * as readOps from './operations/read';
+import * as writeOps from './operations/write';
+import * as symlinkOps from './operations/symlink';
+import * as newerOps from './operations/newer';
+
+/**
+ * Create a Node.js fs-compatible module
+ */
+export function createFSModule(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
+  // Create promise-based operations
+  const promiseOps = {
+    // Read operations
+    readFile: readOps.createReadFileOperation(pathMapper, resourceTracker),
+    readdir: readOps.createReaddirOperation(pathMapper, resourceTracker),
+    stat: readOps.createStatOperation(pathMapper, resourceTracker),
+    lstat: readOps.createLstatOperation(pathMapper, resourceTracker),
+    access: readOps.createAccessOperation(pathMapper, resourceTracker),
+    realpath: readOps.createRealpathOperation(pathMapper, resourceTracker),
+    open: readOps.createOpenOperation(pathMapper, resourceTracker),
+    read: readOps.createReadOperation(pathMapper, resourceTracker),
+    close: readOps.createCloseOperation(pathMapper, resourceTracker),
+    fstat: readOps.createFstatOperation(pathMapper, resourceTracker),
+    opendir: readOps.createOpendirOperation(pathMapper, resourceTracker),
+    exists: readOps.createExistsOperation(pathMapper, resourceTracker),
+
+    // Write operations (all denied)
+    writeFile: writeOps.createWriteFileOperation(),
+    appendFile: writeOps.createAppendFileOperation(),
+    mkdir: writeOps.createMkdirOperation(),
+    rmdir: writeOps.createRmdirOperation(),
+    rm: writeOps.createRmOperation(),
+    unlink: writeOps.createUnlinkOperation(),
+    rename: writeOps.createRenameOperation(),
+    copyFile: writeOps.createCopyFileOperation(),
+    truncate: writeOps.createTruncateOperation(),
+    ftruncate: writeOps.createFtruncateOperation(),
+    chmod: writeOps.createChmodOperation(),
+    fchmod: writeOps.createFchmodOperation(),
+    lchmod: writeOps.createLchmodOperation(),
+    chown: writeOps.createChownOperation(),
+    fchown: writeOps.createFchownOperation(),
+    lchown: writeOps.createLchownOperation(),
+    utimes: writeOps.createUtimesOperation(),
+    futimes: writeOps.createFutimesOperation(),
+    lutimes: writeOps.createLutimesOperation(),
+    write: writeOps.createWriteOperation(),
+    writev: writeOps.createWritevOperation(),
+    fsync: writeOps.createFsyncOperation(),
+    fdatasync: writeOps.createFdatasyncOperation(),
+
+    // Symlink operations (all denied)
+    symlink: symlinkOps.createSymlinkOperation(),
+    link: symlinkOps.createLinkOperation(),
+    readlink: symlinkOps.createReadlinkOperation(),
+
+    // Newer operations
+    glob: newerOps.createGlobOperation(pathMapper, resourceTracker),
+    statfs: newerOps.createStatfsOperation(pathMapper, resourceTracker),
+    cp: newerOps.createCpOperation(pathMapper, resourceTracker),
+    openAsBlob: newerOps.createOpenAsBlobOperation(pathMapper, resourceTracker),
+    readv: newerOps.createReadvOperation(pathMapper, resourceTracker),
+  };
+
+  // Create callback-based operations
+  const callbackOps = {
+    // Read operations
+    readFile: callbackify(promiseOps.readFile),
+    readdir: callbackify(promiseOps.readdir),
+    stat: callbackify(promiseOps.stat),
+    lstat: callbackify(promiseOps.lstat),
+    access: callbackifyVoid(promiseOps.access),
+    realpath: callbackify(promiseOps.realpath),
+    open: callbackify(promiseOps.open),
+    read: callbackify(promiseOps.read),
+    close: callbackifyVoid(promiseOps.close),
+    fstat: callbackify(promiseOps.fstat),
+    opendir: callbackify(promiseOps.opendir),
+    exists: (path: string, callback: (exists: boolean) => void) => {
+      promiseOps.exists(path).then(callback).catch(() => callback(false));
+    },
+
+    // Write operations (all denied)
+    writeFile: callbackifyVoid(promiseOps.writeFile),
+    appendFile: callbackifyVoid(promiseOps.appendFile),
+    mkdir: callbackify(promiseOps.mkdir),
+    rmdir: callbackifyVoid(promiseOps.rmdir),
+    rm: callbackifyVoid(promiseOps.rm),
+    unlink: callbackifyVoid(promiseOps.unlink),
+    rename: callbackifyVoid(promiseOps.rename),
+    copyFile: callbackifyVoid(promiseOps.copyFile),
+    truncate: callbackifyVoid(promiseOps.truncate),
+    ftruncate: callbackifyVoid(promiseOps.ftruncate),
+    chmod: callbackifyVoid(promiseOps.chmod),
+    fchmod: callbackifyVoid(promiseOps.fchmod),
+    lchmod: callbackifyVoid(promiseOps.lchmod),
+    chown: callbackifyVoid(promiseOps.chown),
+    fchown: callbackifyVoid(promiseOps.fchown),
+    lchown: callbackifyVoid(promiseOps.lchown),
+    utimes: callbackifyVoid(promiseOps.utimes),
+    futimes: callbackifyVoid(promiseOps.futimes),
+    lutimes: callbackifyVoid(promiseOps.lutimes),
+    write: callbackify(promiseOps.write),
+    writev: callbackify(promiseOps.writev),
+    fsync: callbackifyVoid(promiseOps.fsync),
+    fdatasync: callbackifyVoid(promiseOps.fdatasync),
+
+    // Symlink operations (all denied)
+    symlink: callbackifyVoid(promiseOps.symlink),
+    link: callbackifyVoid(promiseOps.link),
+    readlink: callbackify(promiseOps.readlink),
+
+    // Newer operations
+    statfs: callbackify(promiseOps.statfs),
+    cp: callbackifyVoid(promiseOps.cp),
+    openAsBlob: callbackify(promiseOps.openAsBlob),
+    readv: callbackify(promiseOps.readv),
+  };
+
+  // Sync operations - all throw EACCES or operate on the real filesystem
+  const syncOps = {
+    readFileSync: (path: string, options?: any) => {
+      resourceTracker.assertNotClosed();
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        return fs.readFileSync(realPath, options);
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+    
+    readdirSync: (path: string, options?: any) => {
+      resourceTracker.assertNotClosed();
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        return fs.readdirSync(realPath, options);
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    statSync: (path: string, options?: any) => {
+      resourceTracker.assertNotClosed();
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        const stats = fs.statSync(realPath, options);
+        if (stats.isSymbolicLink()) {
+          const err = new Error('stat: operation not permitted') as NodeJS.ErrnoException;
+          err.code = 'EACCES';
+          err.errno = -13;
+          err.syscall = 'stat';
+          err.path = path;
+          throw err;
+        }
+        return stats;
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    lstatSync: (path: string, options?: any) => {
+      resourceTracker.assertNotClosed();
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        const stats = fs.lstatSync(realPath, options);
+        if (stats.isSymbolicLink()) {
+          const err = new Error('lstat: operation not permitted') as NodeJS.ErrnoException;
+          err.code = 'EACCES';
+          err.errno = -13;
+          err.syscall = 'lstat';
+          err.path = path;
+          throw err;
+        }
+        return stats;
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    accessSync: (path: string, mode?: number) => {
+      resourceTracker.assertNotClosed();
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        return fs.accessSync(realPath, mode);
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    realpathSync: (path: string, options?: any) => {
+      resourceTracker.assertNotClosed();
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        const resolved = fs.realpathSync(realPath, options);
+        const resolvedStr = Buffer.isBuffer(resolved) ? resolved.toString() : resolved;
+        return pathMapper.toVirtualPath(resolvedStr);
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    openSync: (path: string, flags?: string | number, mode?: number) => {
+      resourceTracker.assertNotClosed();
+      const flagsStr = typeof flags === 'number' ? flags.toString() : (flags || 'r');
+      const isWriteMode = /w|a|\+/.test(flagsStr.toString());
+      
+      if (isWriteMode) {
+        const err = new Error('open: operation not permitted') as NodeJS.ErrnoException;
+        err.code = 'EACCES';
+        err.errno = -13;
+        err.syscall = 'open';
+        err.path = path;
+        throw err;
+      }
+      
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        const fd = fs.openSync(realPath, (flags || 'r') as any, mode);
+        resourceTracker.trackFD(fd, {
+          virtualPath: path,
+          realPath,
+          flags: flags || 'r',
+          mode,
+          isStream: false,
+        });
+        return fd;
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    readSync: (fd: number, buffer: NodeJS.ArrayBufferView, offset: number, length: number, position: number | null) => {
+      resourceTracker.assertNotClosed();
+      if (!resourceTracker.isTracked(fd)) {
+        const err = new Error('bad file descriptor') as NodeJS.ErrnoException;
+        err.code = 'EBADF';
+        err.errno = -9;
+        err.syscall = 'read';
+        throw err;
+      }
+      return fs.readSync(fd, buffer, offset, length, position);
+    },
+
+    closeSync: (fd: number) => {
+      resourceTracker.assertNotClosed();
+      resourceTracker.untrackFD(fd);
+      return fs.closeSync(fd);
+    },
+
+    fstatSync: (fd: number, options?: any) => {
+      resourceTracker.assertNotClosed();
+      if (!resourceTracker.isTracked(fd)) {
+        const err = new Error('bad file descriptor') as NodeJS.ErrnoException;
+        err.code = 'EBADF';
+        err.errno = -9;
+        err.syscall = 'fstat';
+        throw err;
+      }
+      return fs.fstatSync(fd, options);
+    },
+
+    opendirSync: (path: string, options?: any) => {
+      resourceTracker.assertNotClosed();
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        const realDir = fs.opendirSync(realPath, options);
+        return new (require('./wrappers/VirtualDir').VirtualDir)(realDir, path, pathMapper);
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    existsSync: (path: string) => {
+      if (resourceTracker.closed) return false;
+      try {
+        const realPath = pathMapper.toRealPath(path);
+        return fs.existsSync(realPath);
+      } catch {
+        return false;
+      }
+    },
+
+    // Write operations - all throw EACCES
+    writeFileSync: (path: string) => {
+      const err = new Error('open: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'open';
+      err.path = path;
+      throw err;
+    },
+    appendFileSync: (path: string) => {
+      const err = new Error('open: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'open';
+      err.path = path;
+      throw err;
+    },
+    mkdirSync: (path: string) => {
+      const err = new Error('mkdir: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'mkdir';
+      err.path = path;
+      throw err;
+    },
+    rmdirSync: (path: string) => {
+      const err = new Error('rmdir: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'rmdir';
+      err.path = path;
+      throw err;
+    },
+    rmSync: (path: string) => {
+      const err = new Error('rm: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'rm';
+      err.path = path;
+      throw err;
+    },
+    unlinkSync: (path: string) => {
+      const err = new Error('unlink: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'unlink';
+      err.path = path;
+      throw err;
+    },
+    renameSync: (oldPath: string) => {
+      const err = new Error('rename: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'rename';
+      err.path = oldPath;
+      throw err;
+    },
+    copyFileSync: (src: string, dest: string) => {
+      const err = new Error('copyfile: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'copyfile';
+      err.path = dest;
+      throw err;
+    },
+    truncateSync: (path: string) => {
+      const err = new Error('open: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'open';
+      err.path = path;
+      throw err;
+    },
+    ftruncateSync: (fd: number) => {
+      const err = new Error('ftruncate: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'ftruncate';
+      throw err;
+    },
+    chmodSync: (path: string) => {
+      const err = new Error('chmod: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'chmod';
+      err.path = path;
+      throw err;
+    },
+    fchmodSync: (fd: number) => {
+      const err = new Error('fchmod: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'fchmod';
+      throw err;
+    },
+    lchmodSync: (path: string) => {
+      const err = new Error('lchmod: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'lchmod';
+      err.path = path;
+      throw err;
+    },
+    chownSync: (path: string) => {
+      const err = new Error('chown: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'chown';
+      err.path = path;
+      throw err;
+    },
+    fchownSync: (fd: number) => {
+      const err = new Error('fchown: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'fchown';
+      throw err;
+    },
+    lchownSync: (path: string) => {
+      const err = new Error('lchown: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'lchown';
+      err.path = path;
+      throw err;
+    },
+    utimesSync: (path: string) => {
+      const err = new Error('utime: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'utime';
+      err.path = path;
+      throw err;
+    },
+    futimesSync: (fd: number) => {
+      const err = new Error('futime: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'futime';
+      throw err;
+    },
+    lutimesSync: (path: string) => {
+      const err = new Error('lutime: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'lutime';
+      err.path = path;
+      throw err;
+    },
+    writeSync: (fd: number) => {
+      const err = new Error('write: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'write';
+      throw err;
+    },
+    writevSync: (fd: number) => {
+      const err = new Error('writev: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'writev';
+      throw err;
+    },
+    fsyncSync: (fd: number) => {
+      const err = new Error('fsync: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'fsync';
+      throw err;
+    },
+    fdatasyncSync: (fd: number) => {
+      const err = new Error('fdatasync: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'fdatasync';
+      throw err;
+    },
+
+    // Symlink operations - all throw EACCES
+    symlinkSync: (target: string, path: string) => {
+      const err = new Error('symlink: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'symlink';
+      err.path = path;
+      throw err;
+    },
+    linkSync: (existingPath: string, newPath: string) => {
+      const err = new Error('link: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'link';
+      err.path = newPath;
+      throw err;
+    },
+    readlinkSync: (path: string) => {
+      const err = new Error('readlink: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'readlink';
+      err.path = path;
+      throw err;
+    },
+
+    // Newer operations
+    cpSync: (source: string, destination: string) => {
+      const err = new Error('cp: operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      err.syscall = 'cp';
+      err.path = destination;
+      throw err;
+    },
+
+    statfsSync: (path: string, options?: any) => {
+      resourceTracker.assertNotClosed();
+      if (typeof fs.statfsSync !== 'function') {
+        throw new Error('statfsSync is not supported in this Node.js version');
+      }
+      const realPath = pathMapper.toRealPath(path);
+      try {
+        return fs.statfsSync(realPath, options);
+      } catch (error) {
+        throw require('./utils/ErrorFilter').filterError(error, pathMapper);
+      }
+    },
+
+    readvSync: (fd: number, buffers: NodeJS.ArrayBufferView[], position?: number) => {
+      resourceTracker.assertNotClosed();
+      if (!resourceTracker.isTracked(fd)) {
+        const err = new Error('bad file descriptor') as NodeJS.ErrnoException;
+        err.code = 'EBADF';
+        err.errno = -9;
+        err.syscall = 'readv';
+        throw err;
+      }
+      if (typeof (fs as any).readvSync !== 'function') {
+        throw new Error('readvSync is not supported in this Node.js version');
+      }
+      return (fs as any).readvSync(fd, buffers, position);
+    },
+  };
+
+  // Stream operations
+  const streamOps = {
+    createReadStream: readOps.createCreateReadStreamOperation(pathMapper, resourceTracker),
+    createWriteStream: writeOps.createCreateWriteStreamOperation(),
+  };
+
+  // Watch operations
+  const watchOps = {
+    watch: newerOps.createWatchOperation(pathMapper, resourceTracker),
+    watchFile: newerOps.createWatchFileOperation(pathMapper, resourceTracker),
+    unwatchFile: newerOps.createUnwatchFileOperation(pathMapper, resourceTracker),
+  };
+
+  // Combine all operations
+  return {
+    // Callback-based operations
+    ...callbackOps,
+    
+    // Sync operations
+    ...syncOps,
+    
+    // Stream operations
+    ...streamOps,
+    
+    // Watch operations
+    ...watchOps,
+    
+    // Promise-based API
+    promises: {
+      ...promiseOps,
+      // Note: glob is already an async generator, so it's included as-is
+    },
+    
+    // Constants
+    constants: fs.constants,
+    
+    // Classes
+    Stats: fs.Stats,
+    Dirent: fs.Dirent,
+    ReadStream: fs.ReadStream,
+    WriteStream: fs.WriteStream,
+  };
+}

package/src/PathMapper.ts

@@ -0,0 +1,102 @@
+import * as path from 'path';
+import * as fs from 'fs';
+
+/**
+ * Handles conversion between virtual Unix-style paths and real platform-native paths
+ */
+export class PathMapper {
+  private readonly normalizedRoot: string;
+
+  constructor(rootPath: string) {
+    // 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(): string {
+    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: string): string {
+    // 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: string): string {
+    // 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: string): boolean {
+    try {
+      const normalized = path.resolve(realPath);
+      const rel = path.relative(this.normalizedRoot, normalized);
+      return !rel.startsWith('..') && !path.isAbsolute(rel);
+    } catch {
+      return false;
+    }
+  }
+}