typescript-virtual-container 1.2.3 → 1.2.5

package/benchmark-results.txt

@@ -1,40 +1,40 @@
 Benchmarking VirtualShell concurrency:
 
 Running 1 shells...
-  Initialized 1 shells in 86ms, RSS 82 MB
-  Executed shell commands in 2ms, RSS now 82 MB (+0 MB)
+  Initialized 1 shells in 50ms, RSS 82 MB
+  Executed shell commands in 4ms, RSS now 83 MB (+0 MB)
 
 Running 2 shells...
-  Initialized 2 shells in 2ms, RSS 82 MB
-  Executed shell commands in 1ms, RSS now 82 MB (+0 MB)
+  Initialized 2 shells in 2ms, RSS 83 MB
+  Executed shell commands in 0ms, RSS now 83 MB (+0 MB)
 
 Running 5 shells...
-  Initialized 5 shells in 5ms, RSS 82 MB
-  Executed shell commands in 2ms, RSS now 82 MB (+0 MB)
+  Initialized 5 shells in 3ms, RSS 83 MB
+  Executed shell commands in 1ms, RSS now 83 MB (+0 MB)
 
 Running 10 shells...
-  Initialized 10 shells in 5ms, RSS 84 MB
-  Executed shell commands in 3ms, RSS now 84 MB (+1 MB)
+  Initialized 10 shells in 4ms, RSS 83 MB
+  Executed shell commands in 4ms, RSS now 84 MB (+1 MB)
 
 Running 20 shells...
-  Initialized 20 shells in 12ms, RSS 84 MB
-  Executed shell commands in 6ms, RSS now 85 MB (+1 MB)
+  Initialized 20 shells in 7ms, RSS 84 MB
+  Executed shell commands in 5ms, RSS now 85 MB (+0 MB)
 
 Running 50 shells...
-  Initialized 50 shells in 30ms, RSS 87 MB
-  Executed shell commands in 12ms, RSS now 88 MB (+2 MB)
+  Initialized 50 shells in 23ms, RSS 85 MB
+  Executed shell commands in 12ms, RSS now 87 MB (+2 MB)
 
 Running 100 shells...
-  Initialized 100 shells in 52ms, RSS 91 MB
-  Executed shell commands in 28ms, RSS now 92 MB (+2 MB)
+  Initialized 100 shells in 36ms, RSS 89 MB
+  Executed shell commands in 33ms, RSS now 91 MB (+2 MB)
 
 Summary:
 
 count   init_ms cmd_ms  init_rss        final_rss
-1       86      2       82 MB   82 MB   0 MB
-2       2       1       82 MB   82 MB   0 MB
-5       5       2       82 MB   82 MB   0 MB
-10      5       3       84 MB   84 MB   1 MB
-20      12      6       84 MB   85 MB   1 MB
-50      30      12      87 MB   88 MB   2 MB
-100     52      28      91 MB   92 MB   2 MB
+1       50      4       82 MB           83 MB           0 MB
+2       2       0       83 MB           83 MB           0 MB
+5       3       1       83 MB           83 MB           0 MB
+10      4       4       83 MB           84 MB           1 MB
+20      7       5       84 MB           85 MB           0 MB
+50      23      12      85 MB           87 MB           2 MB
+100     36      33      89 MB           91 MB           2 MB

package/biome.json

@@ -17,5 +17,14 @@
                 "noNonNullAssertion": "off"
             }
         }
+    },
+    "formatter": {
+        "enabled": true,
+        "formatWithErrors": false,
+        "attributePosition": "auto",
+        "indentStyle": "tab",
+        "indentWidth": 2,
+        "lineWidth": 80,
+        "lineEnding": "lf"
     }
 }

package/dist/SSHMimic/index.d.ts

@@ -5,19 +5,31 @@ declare class SshMimic extends EventEmitter {
     port: number;
     server: SshServer | null;
     private shell;
-    private shellHostname;
+    /** Max failed auth attempts before an IP is temporarily locked. */
+    private readonly maxAuthAttempts;
+    /** How long (ms) a locked IP must wait before retrying. */
+    private readonly lockoutDurationMs;
+    private readonly authAttempts;
     /**
      * Creates a new SSH mimic server instance.
      *
      * @param port TCP port to bind on localhost.
      * @param hostname Virtual hostname used for the SSH ident and default shell label.
      * @param shell Optional preconfigured virtual shell instance to reuse.
+     * @param maxAuthAttempts Max failed attempts per IP before lockout (default: 5).
+     * @param lockoutDurationMs Lockout window in ms after exceeding attempts (default: 60 000).
      */
-    constructor({ port, hostname, shell, }: {
+    constructor({ port, hostname, shell, maxAuthAttempts, lockoutDurationMs, }: {
         port: number;
         hostname?: string;
         shell?: VirtualShell;
+        maxAuthAttempts?: number;
+        lockoutDurationMs?: number;
     });
+    private isLockedOut;
+    private recordFailure;
+    private recordSuccess;
+    private ensureHomeDir;
     /**
      * Starts server and initializes virtual filesystem, users, and handlers.
      *
@@ -28,6 +40,11 @@ declare class SshMimic extends EventEmitter {
      * Stops server if running.
      */
     stop(): void;
+    /**
+     * Manually clears the rate-limit record for an IP address.
+     * Useful in tests or admin tooling.
+     */
+    clearLockout(ip: string): void;
 }
 export { SftpMimic } from "./sftp";
 export { SshMimic };

package/dist/SSHMimic/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/SSHMimic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAc/C,cAAM,QAAS,SAAQ,YAAY;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;;OAMG;gBACS,EACX,IAAI,EACJ,QAA0B,EAC1B,KAAkC,GAClC,EAAE;QACF,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,YAAY,CAAC;KACrB;IASD;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAyHrC;;OAEG;IACI,IAAI,IAAI,IAAI;CASnB;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/SSHMimic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA0B/C,cAAM,QAAS,SAAQ,YAAY;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,KAAK,CAAe;IAE5B,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqC;IAElE;;;;;;;;OAQG;gBACS,EACX,IAAI,EACJ,QAA0B,EAC1B,KAAkC,EAClC,eAAmB,EACnB,iBAA0B,GAC1B,EAAE;QACF,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC3B;IAYD,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,aAAa;IAcrB;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IA6LrC;;OAEG;IACI,IAAI,IAAI,IAAI;IAUnB;;;OAGG;IACI,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAGrC;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/SSHMimic/index.js

@@ -10,28 +10,76 @@ import { loadOrCreateHostKey } from "./hostKey";
  * This class is exported as `VirtualSshServer` for public API compatibility.
  * Create an instance, call {@link SshMimic.start}, and stop it with
  * {@link SshMimic.stop} when your process exits.
+ *
+ * Features:
+ * - Password authentication
+ * - Public-key authentication
+ * - Per-IP rate limiting / lockout for brute-force protection
+ * - Interactive shell sessions
+ * - Non-interactive exec sessions
  */
 const perf = createPerfLogger("SshMimic");
 class SshMimic extends EventEmitter {
     port;
     server;
     shell;
-    shellHostname;
+    /** Max failed auth attempts before an IP is temporarily locked. */
+    maxAuthAttempts;
+    /** How long (ms) a locked IP must wait before retrying. */
+    lockoutDurationMs;
+    authAttempts = new Map();
     /**
      * Creates a new SSH mimic server instance.
      *
      * @param port TCP port to bind on localhost.
      * @param hostname Virtual hostname used for the SSH ident and default shell label.
      * @param shell Optional preconfigured virtual shell instance to reuse.
+     * @param maxAuthAttempts Max failed attempts per IP before lockout (default: 5).
+     * @param lockoutDurationMs Lockout window in ms after exceeding attempts (default: 60 000).
      */
-    constructor({ port, hostname = "typescript-vm", shell = new VirtualShell(hostname), }) {
+    constructor({ port, hostname = "typescript-vm", shell = new VirtualShell(hostname), maxAuthAttempts = 5, lockoutDurationMs = 60_000, }) {
         super();
         perf.mark("constructor");
         this.port = port;
-        this.shellHostname = hostname;
         this.server = null;
         this.shell = shell;
+        this.maxAuthAttempts = maxAuthAttempts;
+        this.lockoutDurationMs = lockoutDurationMs;
+    }
+    // ── Rate limiting ────────────────────────────────────────────────────────
+    isLockedOut(ip) {
+        const entry = this.authAttempts.get(ip);
+        if (!entry)
+            return false;
+        if (Date.now() < entry.lockedUntil)
+            return true;
+        if (entry.lockedUntil > 0) {
+            this.authAttempts.delete(ip);
+        }
+        return false;
+    }
+    recordFailure(ip) {
+        const entry = this.authAttempts.get(ip) ?? { attempts: 0, lockedUntil: 0 };
+        entry.attempts += 1;
+        if (entry.attempts >= this.maxAuthAttempts) {
+            entry.lockedUntil = Date.now() + this.lockoutDurationMs;
+            this.emit("auth:lockout", { ip, until: new Date(entry.lockedUntil) });
+        }
+        this.authAttempts.set(ip, entry);
     }
+    recordSuccess(ip) {
+        this.authAttempts.delete(ip);
+    }
+    // ── Home directory bootstrap ─────────────────────────────────────────────
+    ensureHomeDir(authUser) {
+        const homePath = `/home/${authUser}`;
+        if (!this.shell.vfs.exists(homePath)) {
+            this.shell.vfs.mkdir(homePath, 0o755);
+            this.shell.vfs.writeFile(`${homePath}/README.txt`, `Welcome to ${this.shell.hostname}\n`);
+            void this.shell.vfs.flushMirror();
+        }
+    }
+    // ── Server lifecycle ─────────────────────────────────────────────────────
     /**
      * Starts server and initializes virtual filesystem, users, and handlers.
      *
@@ -41,7 +89,6 @@ class SshMimic extends EventEmitter {
         perf.mark("start");
         const shell = this.shell;
         const privateKey = loadOrCreateHostKey();
-        // Ensure VirtualShell is fully initialized before accepting connections
         await shell.ensureInitialized();
         this.server = new SshServer({
             hostKeys: [privateKey],
@@ -52,11 +99,34 @@ class SshMimic extends EventEmitter {
             let sessionId = null;
             this.emit("client:connect");
             client.on("authentication", (ctx) => {
-                shell;
+                const candidateUser = ctx.username || "root";
+                remoteAddress = ctx.ip ?? remoteAddress;
+                // Rate-limit check
+                if (this.isLockedOut(remoteAddress)) {
+                    this.emit("auth:failure", {
+                        username: candidateUser,
+                        remoteAddress,
+                        reason: "lockout",
+                    });
+                    ctx.reject();
+                    return;
+                }
+                // ── Password auth ──────────────────────────────────────
                 if (ctx.method === "password") {
-                    const candidateUser = ctx.username || "root";
-                    remoteAddress = ctx.ip ?? remoteAddress;
-                    if (!shell.users.verifyPassword(candidateUser, ctx.password ?? "")) {
+                    if (!shell.users.hasPassword(candidateUser)) {
+                        console.log(`User ${candidateUser} has no password set, allowing login without verification`);
+                        authUser = candidateUser;
+                        sessionId = shell.users.registerSession(authUser, remoteAddress).id;
+                        this.recordSuccess(remoteAddress);
+                        this.emit("auth:success", { username: authUser, remoteAddress });
+                        this.ensureHomeDir(authUser);
+                        ctx.accept();
+                        return;
+                    }
+                    if (!ctx.password ||
+                        ctx.password === "" ||
+                        !shell.users.verifyPassword(candidateUser, ctx.password)) {
+                        this.recordFailure(remoteAddress);
                         this.emit("auth:failure", {
                             username: candidateUser,
                             remoteAddress,
@@ -66,17 +136,52 @@ class SshMimic extends EventEmitter {
                     }
                     authUser = candidateUser;
                     sessionId = shell.users.registerSession(authUser, remoteAddress).id;
+                    this.recordSuccess(remoteAddress);
                     this.emit("auth:success", { username: authUser, remoteAddress });
-                    const homePath = `/home/${authUser}`;
-                    if (!shell.vfs.exists(homePath)) {
-                        shell.vfs.mkdir(homePath, 0o755);
-                        shell.vfs.writeFile(`${homePath}/README.txt`, `Welcome to ${shell?.hostname ?? this.shellHostname}`);
-                        void shell.vfs.flushMirror();
-                    }
+                    this.ensureHomeDir(authUser);
                     ctx.accept();
                     return;
                 }
-                ctx.reject();
+                // ── Public-key auth ────────────────────────────────────
+                if (ctx.method === "publickey") {
+                    const authorizedKeys = shell.users.getAuthorizedKeys(candidateUser);
+                    if (authorizedKeys.length === 0) {
+                        // No keys configured — reject cleanly
+                        ctx.reject();
+                        return;
+                    }
+                    const incomingKey = ctx.key;
+                    const keyMatches = authorizedKeys.some((k) => k.algo === incomingKey.algo && k.data.equals(incomingKey.data));
+                    if (!keyMatches) {
+                        this.recordFailure(remoteAddress);
+                        this.emit("auth:failure", {
+                            username: candidateUser,
+                            remoteAddress,
+                            method: "publickey",
+                        });
+                        ctx.reject();
+                        return;
+                    }
+                    // Key matched — if this is a signature check step, accept
+                    if (ctx.signature) {
+                        authUser = candidateUser;
+                        sessionId = shell.users.registerSession(authUser, remoteAddress).id;
+                        this.recordSuccess(remoteAddress);
+                        this.emit("auth:success", {
+                            username: authUser,
+                            remoteAddress,
+                            method: "publickey",
+                        });
+                        this.ensureHomeDir(authUser);
+                        ctx.accept();
+                    }
+                    else {
+                        // Key exists but no signature yet — ssh2 will call again with signature
+                        ctx.accept();
+                    }
+                    return;
+                }
+                ctx.reject(["password", "publickey"]);
             });
             client.on("close", () => {
                 shell.users.unregisterSession(sessionId);
@@ -130,6 +235,13 @@ class SshMimic extends EventEmitter {
             });
         }
     }
+    /**
+     * Manually clears the rate-limit record for an IP address.
+     * Useful in tests or admin tooling.
+     */
+    clearLockout(ip) {
+        this.authAttempts.delete(ip);
+    }
 }
 export { SftpMimic } from "./sftp";
 export { SshMimic };

package/dist/VirtualFileSystem/index.d.ts

@@ -1,127 +1,154 @@
 import { EventEmitter } from "node:events";
-import type { RemoveOptions, VfsNodeStats, WriteFileOptions } from "../types/vfs";
+import type { RemoveOptions, VfsNodeStats, VfsSnapshot, WriteFileOptions } from "../types/vfs";
+/**
+ * "memory" — pure in-memory, no disk I/O (default).
+ *
+ * "fs"     — mirrors the VFS tree to a directory on the host filesystem.
+ *             `snapshotPath` must be set to the directory where the JSON
+ *             snapshot file will be read/written.
+ */
+export type VfsPersistenceMode = "memory" | "fs";
+export interface VfsOptions {
+    /**
+     * Persistence mode.
+     * - `"memory"` (default): no disk access, snapshot via `toSnapshot()`.
+     * - `"fs"`: auto-save JSON snapshot to `snapshotPath` on every
+     *   `flushMirror()` call, and restore from it on `restoreMirror()`.
+     */
+    mode?: VfsPersistenceMode;
+    /**
+     * Directory used by `"fs"` mode.
+     * The snapshot file will be written to `<snapshotPath>/vfs-snapshot.json`.
+     * Required when `mode` is `"fs"`.
+     */
+    snapshotPath?: string;
+}
+/**
+ * In-memory virtual filesystem with optional JSON-snapshot persistence.
+ *
+ * **Memory mode** (default) — all state lives in a fast recursive tree.
+ * Use `toSnapshot()` / `fromSnapshot()` / `importSnapshot()` for serialisation.
+ *
+ * **FS mode** — same in-memory tree, but `restoreMirror()` loads a JSON
+ * snapshot from disk and `flushMirror()` writes it back.  This gives you
+ * persistent VFS state across process restarts without any real POSIX filesystem
+ * semantics leaking through.
+ *
+ * @example
+ * ```ts
+ * // Pure in-memory (default)
+ * const vfs = new VirtualFileSystem();
+ *
+ * // With disk persistence
+ * const vfs = new VirtualFileSystem({ mode: "fs", snapshotPath: "./data" });
+ * await vfs.restoreMirror(); // load from disk (no-op if no snapshot yet)
+ * // ... use vfs ...
+ * await vfs.flushMirror();  // persist to disk
+ * ```
+ */
 declare class VirtualFileSystem extends EventEmitter {
-    private readonly mirrorRoot;
-    private ensureMirrorRoot;
-    private resolveFsPath;
-    private detectGzipFile;
-    private computeDiskUsageBytes;
-    private renderTreeLines;
-    /**
-     * Creates a virtual filesystem instance.
-     *
-     * @param baseDir Base directory used to resolve mirror archive location.
-     */
-    constructor(baseDir?: string);
+    private root;
+    private readonly mode;
+    private readonly snapshotFile;
+    constructor(options?: VfsOptions);
+    private makeDir;
+    private makeFile;
+    private mkdirRecursive;
     /**
-     * Restores filesystem state from mirror archive.
+     * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+     * Silently succeeds when the snapshot file does not exist yet.
      *
-     * If archive does not exist or cannot be read, creates fresh mirror file.
+     * In `"memory"` mode: no-op (kept for API compatibility).
      */
     restoreMirror(): Promise<void>;
     /**
-     * Persists current filesystem state to mirror archive.
+     * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+     * The directory is created if it does not exist.
      *
-     * No-op when nothing changed and archive already exists.
+     * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).
      */
     flushMirror(): Promise<void>;
-    /**
-     * Creates directory and any missing parent directories.
-     *
-     * @param targetPath Absolute or relative path to directory.
-     * @param mode POSIX-like mode bits for new directories.
-     */
+    /** Returns the current persistence mode. */
+    getMode(): VfsPersistenceMode;
+    /** Returns the snapshot file path used in `"fs"` mode, or `null`. */
+    getSnapshotPath(): string | null;
+    /** Creates a directory (and any missing parents). */
     mkdir(targetPath: string, mode?: number): void;
     /**
-     * Writes UTF-8 text or binary content into file.
-     *
+     * Writes UTF-8 text or binary content into a file.
      * Parent directories are created when missing.
-     *
-     * @param targetPath Destination file path.
-     * @param content File content as string or Buffer.
-     * @param options Optional write behavior (mode, compression).
      */
     writeFile(targetPath: string, content: string | Buffer, options?: WriteFileOptions): void;
     /**
-     * Reads file content as UTF-8 text.
-     *
-     * Compressed files are transparently decompressed.
-     *
-     * @param targetPath Path to file.
-     * @returns UTF-8 string content.
+     * Reads file content as a UTF-8 string.
+     * Gzip-compressed files are transparently decompressed.
      */
     readFile(targetPath: string): string;
-    /**
-     * Checks whether node exists at path.
-     *
-     * @param targetPath Node path.
-     * @returns True when file or directory exists.
-     */
+    /** Reads file content as a Buffer (decompresses if needed). */
+    readFileRaw(targetPath: string): Buffer;
+    /** Returns true when a file or directory exists at path. */
     exists(targetPath: string): boolean;
-    /**
-     * Updates mode bits for file or directory.
-     *
-     * @param targetPath Node path.
-     * @param mode New POSIX-like mode.
-     */
+    /** Updates mode bits on a node. */
     chmod(targetPath: string, mode: number): void;
-    /**
-     * Returns metadata for file or directory.
-     *
-     * @param targetPath Node path.
-     * @returns Typed stat object based on node type.
-     */
+    /** Returns metadata for a file or directory. */
     stat(targetPath: string): VfsNodeStats;
-    /**
-     * Lists direct children names of directory.
-     *
-     * @param dirPath Directory path, defaults to root.
-     * @returns Sorted child names.
-     */
+    /** Lists direct children names of a directory (sorted). */
     list(dirPath?: string): string[];
-    /**
-     * Renders ASCII tree view of directory hierarchy.
-     *
-     * @param dirPath Directory path, defaults to root.
-     * @returns Multi-line tree string.
-     */
+    /** Renders ASCII tree view of a directory hierarchy. */
     tree(dirPath?: string): string;
+    private renderTreeLines;
+    /** Computes total stored bytes under a path. */
+    getUsageBytes(targetPath?: string): number;
+    private computeUsage;
+    /** Compresses a file's content with gzip in place. */
+    compressFile(targetPath: string): void;
+    /** Decompresses a gzip-compressed file in place. */
+    decompressFile(targetPath: string): void;
     /**
-     * Computes total stored file bytes under a path.
-     *
-     * File usage is based on in-memory stored bytes, including compressed
-     * payload size when files are marked as compressed.
-     *
-     * @param targetPath File or directory path to measure, defaults to root.
-     * @returns Total byte usage for file content under target path.
+     * Creates a symbolic link.
+     * The link node is stored with mode `0o120777` (POSIX symlink convention).
      */
-    getUsageBytes(targetPath?: string): number;
+    symlink(targetPath: string, linkPath: string): void;
+    /** Returns true when the path is a symbolic link node. */
+    isSymlink(targetPath: string): boolean;
     /**
-     * Compresses file content with gzip and flags node as compressed.
-     *
-     * @param targetPath Path to file.
+     * Resolves a symlink chain up to `maxDepth` hops.
+     * Throws when the chain is too long (circular links).
      */
-    compressFile(targetPath: string): void;
+    resolveSymlink(linkPath: string, maxDepth?: number): string;
+    /** Removes a file or directory node. */
+    remove(targetPath: string, options?: RemoveOptions): void;
+    /** Moves or renames a node. */
+    move(fromPath: string, toPath: string): void;
     /**
-     * Decompresses gzip-compressed file content.
+     * Exports the entire filesystem as a JSON-serialisable snapshot.
      *
-     * @param targetPath Path to file.
+     * Works regardless of the persistence mode. Useful for test fixtures,
+     * manual backups, or passing VFS state between processes.
      */
-    decompressFile(targetPath: string): void;
+    toSnapshot(): VfsSnapshot;
+    private serializeDir;
+    private serializeFile;
     /**
-     * Removes file or directory node.
+     * Creates a new `VirtualFileSystem` instance (memory mode) from a snapshot.
      *
-     * @param targetPath Path to remove.
-     * @param options Removal options, including recursive delete.
+     * @example
+     * ```ts
+     * const vfs = VirtualFileSystem.fromSnapshot(savedSnapshot);
+     * ```
      */
-    remove(targetPath: string, options?: RemoveOptions): void;
+    static fromSnapshot(snapshot: VfsSnapshot): VirtualFileSystem;
     /**
-     * Moves or renames node to destination path.
+     * Replaces the current filesystem state with the content of a snapshot.
+     * The persistence mode is preserved.
      *
-     * @param fromPath Existing source path.
-     * @param toPath Destination path.
+     * @example
+     * ```ts
+     * vfs.importSnapshot(savedSnapshot);
+     * ```
      */
-    move(fromPath: string, toPath: string): void;
+    importSnapshot(snapshot: VfsSnapshot): void;
+    private deserializeDir;
 }
 export default VirtualFileSystem;
 //# sourceMappingURL=index.d.ts.map

package/dist/VirtualFileSystem/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualFileSystem/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,KAAK,EACX,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,MAAM,cAAc,CAAC;AActB,cAAM,iBAAkB,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,eAAe;IA4BvB;;;;OAIG;gBACS,OAAO,GAAE,MAAsB;IAM3C;;;;OAIG;IACU,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3C;;;;OAIG;IACU,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzC;;;;;OAKG;IACI,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAc,GAAG,IAAI;IAa5D;;;;;;;;OAQG;IACI,SAAS,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,gBAAqB,GAC5B,IAAI;IAyBP;;;;;;;OAOG;IACI,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAe3C;;;;;OAKG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAU1C;;;;;OAKG;IACI,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IASpD;;;;;OAKG;IACI,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY;IAsC7C;;;;;OAKG;IACI,IAAI,CAAC,OAAO,GAAE,MAAY,GAAG,MAAM,EAAE;IAU5C;;;;;OAKG;IACI,IAAI,CAAC,OAAO,GAAE,MAAY,GAAG,MAAM;IAY1C;;;;;;;;OAQG;IACI,aAAa,CAAC,UAAU,GAAE,MAAY,GAAG,MAAM;IAStD;;;;OAIG;IACI,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAa7C;;;;OAIG;IACI,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAa/C;;;;;OAKG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI;IA6BpE;;;;;OAKG;IACI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAuBnD;AAED,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualFileSystem/index.ts"],"names":[],"mappings":"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"}