Class ReadWriteFs

packages/just-bash/src/fs/read-write-fs/read-write-fs.ts:69–901

}

export class ReadWriteFs implements IFileSystem {
  private readonly root: string;
  private readonly canonicalRoot: string;
  private readonly maxFileReadSize: number;
  private readonly allowSymlinks: boolean;

  constructor(options: ReadWriteFsOptions) {
    this.root = nodePath.resolve(options.root);
    this.maxFileReadSize = options.maxFileReadSize ?? 10485760;
    this.allowSymlinks = options.allowSymlinks ?? false;

    // Verify root exists and is a directory
    validateRootDirectory(this.root, "ReadWriteFs");

    // Compute canonical root (resolves symlinks like /var -> /private/var on macOS)
    this.canonicalRoot = fs.realpathSync(this.root);
  }

  /**
   * Validate that a resolved real path stays within the sandbox root and
   * return the canonical (symlink-resolved) path for use in subsequent I/O.
   * This closes the TOCTOU gap where the original path could be swapped
   * between validation and use.
   * Throws EACCES if the path escapes the root.
   */
  private resolveAndValidate(realPath: string, virtualPath: string): string {
    const canonical = this.allowSymlinks
      ? resolveCanonicalPath(realPath, this.canonicalRoot)
      : resolveCanonicalPathNoSymlinks(realPath, this.root, this.canonicalRoot);
    if (canonical === null) {
      throw new Error(
        `EACCES: permission denied, '${virtualPath}' resolves outside sandbox`,
      );
    }
    return canonical;
  }

  /**
   * Validate the parent directory of a path (for operations like lstat/readlink
   * that should not follow the final component's symlink).
   * Returns the canonical parent joined with the original basename.
   */
  private validateParent(realPath: string, virtualPath: string): string {
    const parent = nodePath.dirname(realPath);
    const canonicalParent = this.resolveAndValidate(parent, virtualPath);
    return nodePath.join(canonicalParent, nodePath.basename(realPath));
  }

  /**
   * Convert a virtual path to a real filesystem path.
   */
  private toRealPath(virtualPath: string): string {
    const normalized = normalizePath(virtualPath);
    const realPath = nodePath.join(this.root, normalized);
    return nodePath.resolve(realPath);
  }

  async readFile(