typescript-virtual-container 1.5.5 → 1.5.7

package/dist/SSHMimic/scp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SCP (Secure Copy Protocol) server-side implementation over SSH exec.
+ *
+ * Supports:
+ *   scp -t [-r] <dest>   — sink mode  (client → server, uploading)
+ *   scp -f [-r] <src>    — source mode (server → client, downloading)
+ *
+ * The SCP wire protocol is a line-oriented binary protocol sent over the
+ * SSH exec channel. Control messages are ASCII lines terminated with \n.
+ * File data immediately follows the ready acknowledgement (\0).
+ *
+ * Sink control messages (client → server):
+ *   C<mode> <size> <name>\n   — regular file
+ *   D<mode> 0 <name>\n        — enter directory
+ *   E\n                        — leave directory
+ *   T<mtime_s> 0 <atime_s> 0\n — timestamps (ignored)
+ *
+ * Acknowledgement byte: \0 = ok, \1 = warning, \2 = error.
+ */
+import type { VirtualShell } from "../VirtualShell";
+interface ScpStream {
+    write(data: Buffer | string): boolean;
+    on(event: "data", listener: (chunk: Buffer) => void): this;
+    on(event: "end" | "close", listener: () => void): this;
+    stderr: {
+        write(data: string | Buffer): void;
+    };
+    exit(code: number): void;
+    end(): void;
+}
+export declare function runScpSink(stream: ScpStream, destArg: string, authUser: string, shell: VirtualShell, recursive: boolean): void;
+export declare function runScpSource(stream: ScpStream, srcArg: string, _authUser: string, shell: VirtualShell, recursive: boolean): void;
+export declare function handleScp(stream: ScpStream, rawArgs: string[], authUser: string, shell: VirtualShell): void;
+export {};

package/dist/SSHMimic/scp.js

@@ -0,0 +1,285 @@
+/**
+ * SCP (Secure Copy Protocol) server-side implementation over SSH exec.
+ *
+ * Supports:
+ *   scp -t [-r] <dest>   — sink mode  (client → server, uploading)
+ *   scp -f [-r] <src>    — source mode (server → client, downloading)
+ *
+ * The SCP wire protocol is a line-oriented binary protocol sent over the
+ * SSH exec channel. Control messages are ASCII lines terminated with \n.
+ * File data immediately follows the ready acknowledgement (\0).
+ *
+ * Sink control messages (client → server):
+ *   C<mode> <size> <name>\n   — regular file
+ *   D<mode> 0 <name>\n        — enter directory
+ *   E\n                        — leave directory
+ *   T<mtime_s> 0 <atime_s> 0\n — timestamps (ignored)
+ *
+ * Acknowledgement byte: \0 = ok, \1 = warning, \2 = error.
+ */
+import { basename } from "node:path";
+import { resolvePath } from "../modules/shellRuntime";
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const ACK = Buffer.from([0x00]);
+const ERR = (msg) => Buffer.from(`\x02${msg}\n`);
+function scpError(stream, msg, code = 1) {
+    stream.stderr.write(`scp: ${msg}\n`);
+    stream.write(ERR(`scp: ${msg}`));
+    stream.exit(code);
+    stream.end();
+}
+function parseArgs(args) {
+    const flags = args.filter((a) => a.startsWith("-")).join("");
+    return {
+        sink: flags.includes("t"),
+        source: flags.includes("f"),
+        recursive: flags.includes("r"),
+        preserve: flags.includes("p"),
+        target: args.find((a) => !a.startsWith("-")),
+    };
+}
+// ── Sink mode (upload: client → server) ──────────────────────────────────────
+export function runScpSink(stream, destArg, authUser, shell, recursive) {
+    // Buffered reader that handles arbitrary chunk boundaries
+    let buf = Buffer.alloc(0);
+    const dirStack = [resolvePath("/", destArg)];
+    let state = "cmd";
+    let pendingFile = null;
+    let bytesRead = 0;
+    const fileChunks = [];
+    let finished = false;
+    function currentDir() {
+        return dirStack.at(-1) ?? "/";
+    }
+    function send(data) {
+        stream.write(typeof data === "string" ? Buffer.from(data) : data);
+    }
+    function processCmd(line) {
+        const type = line[0];
+        // Timestamps — ignored, just ack
+        if (type === "T") {
+            send(ACK);
+            return;
+        }
+        // End directory
+        if (type === "E") {
+            dirStack.pop();
+            send(ACK);
+            return;
+        }
+        // File or directory header: C<mode> <size> <name>  /  D<mode> 0 <name>
+        if (type === "C" || type === "D") {
+            const parts = line.slice(1).split(" ");
+            const name = parts.slice(2).join(" "); // name may contain spaces
+            const size = Number(parts[1] ?? "0");
+            if (!name || name === "." || name === "..") {
+                send(ERR("invalid filename"));
+                return;
+            }
+            if (type === "D") {
+                if (!recursive) {
+                    send(ERR("not a regular file"));
+                    return;
+                }
+                const dir = `${currentDir()}/${name}`;
+                if (!shell.vfs.exists(dir)) {
+                    try {
+                        shell.vfs.mkdir(dir, 0o755);
+                    }
+                    catch { /* already exists */ }
+                }
+                dirStack.push(dir);
+                send(ACK);
+                return;
+            }
+            // type === "C"
+            const destPath = `${currentDir()}/${name}`;
+            pendingFile = { name, size, dest: destPath };
+            bytesRead = 0;
+            fileChunks.length = 0;
+            state = "data";
+            send(ACK);
+            return;
+        }
+        send(ERR(`unknown control message: ${line[0]}`));
+    }
+    function processBuffer() {
+        while (buf.length > 0) {
+            if (state === "cmd") {
+                const nl = buf.indexOf(0x0a); // \n
+                if (nl === -1)
+                    break; // wait for more
+                const line = buf.subarray(0, nl).toString("utf8").replace(/\r$/, "");
+                buf = buf.subarray(nl + 1);
+                processCmd(line);
+            }
+            else if (state === "data" && pendingFile) {
+                const remaining = pendingFile.size - bytesRead;
+                if (remaining > 0) {
+                    const take = Math.min(buf.length, remaining);
+                    fileChunks.push(buf.subarray(0, take));
+                    buf = buf.subarray(take);
+                    bytesRead += take;
+                }
+                if (bytesRead >= pendingFile.size) {
+                    // Next byte must be \0 (end-of-file marker from client)
+                    if (buf.length === 0)
+                        break;
+                    const marker = buf[0];
+                    buf = buf.subarray(1);
+                    if (marker !== 0x00) {
+                        scpError(stream, "protocol error: expected \\0 after file data");
+                        finished = true;
+                        return;
+                    }
+                    // Write file to VFS
+                    const content = Buffer.concat(fileChunks);
+                    try {
+                        shell.writeFileAsUser(authUser, pendingFile.dest, content);
+                    }
+                    catch (e) {
+                        send(ERR(`cannot write ${pendingFile.dest}: ${String(e)}`));
+                        finished = true;
+                        return;
+                    }
+                    pendingFile = null;
+                    state = "cmd";
+                    send(ACK);
+                }
+            }
+            else {
+                break;
+            }
+        }
+    }
+    // Send initial ready signal
+    send(ACK);
+    stream.on("data", (chunk) => {
+        if (finished)
+            return;
+        buf = Buffer.concat([buf, chunk]);
+        processBuffer();
+    });
+    stream.on("end", () => {
+        stream.exit(0);
+        stream.end();
+    });
+}
+// ── Source mode (download: server → client) ───────────────────────────────────
+export function runScpSource(stream, srcArg, _authUser, shell, recursive) {
+    const srcPath = resolvePath("/", srcArg);
+    if (!shell.vfs.exists(srcPath)) {
+        scpError(stream, `${srcArg}: No such file or directory`);
+        return;
+    }
+    const entries = [];
+    function collect(p, name) {
+        const st = shell.vfs.stat(p);
+        if (st.type === "directory") {
+            if (!recursive) {
+                // skip directories silently like real scp
+                return;
+            }
+            entries.push({ kind: "dir-open", name });
+            for (const child of shell.vfs.list(p)) {
+                collect(`${p}/${child}`, child);
+            }
+            entries.push({ kind: "dir-close" });
+        }
+        else {
+            entries.push({ kind: "file", path: p, name });
+        }
+    }
+    collect(srcPath, basename(srcPath));
+    if (entries.length === 0) {
+        stream.exit(0);
+        stream.end();
+        return;
+    }
+    // State machine driven by \0 acks from client
+    let idx = 0;
+    let sendingData = false;
+    let pendingData = null;
+    function sendNext() {
+        if (idx >= entries.length) {
+            stream.exit(0);
+            stream.end();
+            return;
+        }
+        const entry = entries[idx];
+        idx++;
+        if (entry.kind === "dir-open") {
+            stream.write(`D0755 0 ${entry.name}\n`);
+            // wait for ack, then recurse
+        }
+        else if (entry.kind === "dir-close") {
+            stream.write("E\n");
+            // wait for ack
+        }
+        else {
+            const content = shell.vfs.readFileRaw(entry.path);
+            stream.write(`C0644 ${content.length} ${entry.name}\n`);
+            pendingData = content;
+            sendingData = true;
+        }
+    }
+    let buf = Buffer.alloc(0);
+    let waitingForDataAck = false;
+    function processAcks() {
+        while (buf.length > 0) {
+            const byte = buf[0];
+            buf = buf.subarray(1);
+            if (byte === 0x01 || byte === 0x02) {
+                // Error from client
+                stream.exit(1);
+                stream.end();
+                return;
+            }
+            // byte === 0x00: ack
+            if (waitingForDataAck) {
+                waitingForDataAck = false;
+                sendNext();
+                return;
+            }
+            if (sendingData && pendingData !== null) {
+                // Client acked the header — send data then \0
+                stream.write(pendingData);
+                stream.write(ACK);
+                pendingData = null;
+                sendingData = false;
+                waitingForDataAck = true;
+            }
+            else {
+                sendNext();
+            }
+        }
+    }
+    stream.on("data", (chunk) => {
+        buf = Buffer.concat([buf, chunk]);
+        processAcks();
+    });
+    stream.on("end", () => {
+        stream.exit(0);
+        stream.end();
+    });
+    // Wait for initial \0 from client before sending anything
+    // (processAcks will call sendNext on first ack)
+}
+// ── Entry point ───────────────────────────────────────────────────────────────
+export function handleScp(stream, rawArgs, authUser, shell) {
+    const { sink, source, recursive, target } = parseArgs(rawArgs);
+    if (!sink && !source) {
+        scpError(stream, "missing -t or -f flag");
+        return;
+    }
+    if (!target) {
+        scpError(stream, "missing target path");
+        return;
+    }
+    if (sink) {
+        runScpSink(stream, target, authUser, shell, recursive);
+    }
+    else {
+        runScpSource(stream, target, authUser, shell, recursive);
+    }
+}

package/dist/SSHMimic/sftp.d.ts

@@ -4,16 +4,60 @@ import { Server as SshServer } from "ssh2";
 import type VirtualFileSystem from "../VirtualFileSystem";
 import { VirtualShell } from "../VirtualShell";
 import type { VirtualUserManager } from "../VirtualUserManager";
+/** @internal */
+interface SftpAttributes {
+    mode: number;
+    uid: number;
+    gid: number;
+    size: number;
+    atime: number | Date;
+    mtime: number | Date;
+}
+/** @internal */
+interface SftpServerStream {
+    on(event: "OPEN", listener: (reqid: number, filename: string, flags: number) => void): this;
+    on(event: "READ", listener: (reqid: number, handle: Buffer, offset: number, length: number) => void): this;
+    on(event: "WRITE", listener: (reqid: number, handle: Buffer, offset: number, data: Buffer) => void): this;
+    on(event: "FSTAT", listener: (reqid: number, handle: Buffer) => void): this;
+    on(event: "CLOSE", listener: (reqid: number, handle: Buffer) => void): this;
+    on(event: "OPENDIR", listener: (reqid: number, path: string) => void): this;
+    on(event: "READDIR", listener: (reqid: number, handle: Buffer) => void): this;
+    on(event: "STAT", listener: (reqid: number, path: string) => void): this;
+    on(event: "LSTAT", listener: (reqid: number, path: string) => void): this;
+    on(event: "FSETSTAT", listener: (reqid: number, handle: Buffer, attrs: Partial<SftpAttributes>) => void): this;
+    on(event: "SETSTAT", listener: (reqid: number, path: string, attrs: Partial<SftpAttributes>) => void): this;
+    on(event: "REALPATH", listener: (reqid: number, path: string) => void): this;
+    on(event: "MKDIR", listener: (reqid: number, path: string) => void): this;
+    on(event: "RMDIR", listener: (reqid: number, path: string) => void): this;
+    on(event: "REMOVE", listener: (reqid: number, path: string) => void): this;
+    on(event: "RENAME", listener: (reqid: number, oldPath: string, newPath: string) => void): this;
+    on(event: "READLINK", listener: (reqid: number) => void): this;
+    on(event: "SYMLINK", listener: (reqid: number) => void): this;
+    on(event: "END", listener: () => void): this;
+    on(event: "end", listener: () => void): this;
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "close", listener: () => void): this;
+    status(reqid: number, code: number): void;
+    attrs(reqid: number, attrs: SftpAttributes): void;
+    handle(reqid: number, handle: Buffer): void;
+    data(reqid: number, data: Buffer): void;
+    name(reqid: number, entries: Array<{
+        filename: string;
+        longname: string;
+        attrs: SftpAttributes;
+    }>): void;
+}
 /** Options for {@link SftpMimic} constructor. */
 export interface SftpMimicOptions {
-    port: number;
+    /** TCP port to bind. Optional — omit if using as a subsystem handler only (no standalone server). */
+    port?: number;
     hostname?: string;
     shell?: VirtualShell;
     vfs?: VirtualFileSystem;
     users?: VirtualUserManager;
 }
 export declare class SftpMimic extends EventEmitter {
-    port: number;
+    port: number | undefined;
     server: SshServer | null;
     private readonly hostname;
     private readonly shell;
@@ -44,5 +88,11 @@ export declare class SftpMimic extends EventEmitter {
     private openHandle;
     private getHandle;
     private closeHandle;
-    private attachSftpHandlers;
+    /**
+     * Attach SFTP handlers to an already-accepted sftp stream.
+     * Used internally by {@link SshMimic} for the SFTP subsystem on the SSH port.
+     * @internal
+     */
+    attachSftpHandlers(sftp: SftpServerStream, authUser: string): void;
 }
+export {};

package/dist/SSHMimic/sftp.js

@@ -71,6 +71,9 @@ export class SftpMimic extends EventEmitter {
         return this.shell?.users ?? this.users;
     }
     async start() {
+        if (this.port === undefined) {
+            throw new Error("SftpMimic: cannot start — no port configured (this instance is a subsystem handler only)");
+        }
         perf.mark("start");
         const privateKey = loadOrCreateHostKey();
         // Ensure VirtualShell is fully initialized before accepting connections
@@ -271,6 +274,11 @@ export class SftpMimic extends EventEmitter {
     closeHandle(handle) {
         this.handles.delete(handle.toString("hex"));
     }
+    /**
+     * Attach SFTP handlers to an already-accepted sftp stream.
+     * Used internally by {@link SshMimic} for the SFTP subsystem on the SSH port.
+     * @internal
+     */
     attachSftpHandlers(sftp, authUser) {
         const getVfs = () => this.getVfs();
         const getUsers = () => this.getUsers();
@@ -283,8 +291,6 @@ export class SftpMimic extends EventEmitter {
                 return;
             }
             const openMode = flags;
-            const _canRead = Boolean(openMode & OPEN_MODE.READ);
-            const _canWrite = Boolean(openMode & OPEN_MODE.WRITE || openMode & OPEN_MODE.APPEND);
             const canCreate = Boolean(openMode & OPEN_MODE.CREAT);
             const shouldTruncate = Boolean(openMode & OPEN_MODE.TRUNC);
             try {
@@ -337,7 +343,7 @@ export class SftpMimic extends EventEmitter {
                 sftp.status(reqid, SFTP_STATUS_CODE.EOF);
                 return;
             }
-            const chunk = entry.buffer.slice(offset, offset + length);
+            const chunk = entry.buffer.subarray(offset, offset + length);
             sftp.data(reqid, chunk);
         });
         sftp.on("WRITE", async (reqid, handle, offset, data) => {

package/dist/VirtualFileSystem/binaryPack.d.ts

@@ -36,6 +36,13 @@ import type { InternalDirectoryNode } from "./internalTypes";
  * No base64, no JSON. ~27% smaller than the JSON+base64 format for typical VFS trees.
  */
 export declare function encodeVfs(root: InternalDirectoryNode): Buffer;
+/**
+ * Shallow-fork a decoded rootfs tree: creates new InternalDirectoryNode objects
+ * (necessary for per-shell write isolation) but shares all InternalFileNode and
+ * InternalStubNode references. Safe because file/stub nodes are never mutated in-place
+ * — writes replace the parent's children[name] reference with a new node.
+ */
+export declare function forkDirTree(base: InternalDirectoryNode): InternalDirectoryNode;
 /**
  * Deserialise a binary Buffer produced by {@link encodeVfs} back into an
  * InternalDirectoryNode tree. Throws on magic/version mismatch or truncation.

package/dist/VirtualFileSystem/binaryPack.js

@@ -162,7 +162,7 @@ class Decoder {
 }
 function decodeNode(dec) {
     const type = dec.readUint8();
-    const name = dec.readString();
+    const name = internName(dec.readString());
     const mode = dec.readUint32();
     const createdAt = dec.readFloat64();
     const updatedAt = dec.readFloat64();
@@ -194,10 +194,46 @@ function decodeNode(dec) {
             updatedAt,
             children,
             _childCount: count,
+            _sortedKeys: null,
         };
     }
     throw new Error(`[VFS binary] Unknown node type: 0x${type.toString(16)}`);
 }
+// String intern pool for node names — avoids duplicate string allocations per decode call.
+// Names like "bin", "etc", "usr", "passwd" appear in every shell's tree.
+const _namePool = new Map();
+function internName(s) {
+    const cached = _namePool.get(s);
+    if (cached !== undefined)
+        return cached;
+    _namePool.set(s, s);
+    return s;
+}
+/**
+ * Shallow-fork a decoded rootfs tree: creates new InternalDirectoryNode objects
+ * (necessary for per-shell write isolation) but shares all InternalFileNode and
+ * InternalStubNode references. Safe because file/stub nodes are never mutated in-place
+ * — writes replace the parent's children[name] reference with a new node.
+ */
+export function forkDirTree(base) {
+    const children = Object.create(null);
+    for (const name in base.children) {
+        const child = base.children[name];
+        children[name] = child.type === "directory"
+            ? forkDirTree(child)
+            : child; // shared — file/stub nodes are immutable until replaced
+    }
+    return {
+        type: "directory",
+        name: base.name,
+        mode: base.mode,
+        createdAt: base.createdAt,
+        updatedAt: base.updatedAt,
+        children,
+        _childCount: base._childCount,
+        _sortedKeys: base._sortedKeys, // safe to share — sorted list doesn't change for base
+    };
+}
 /**
  * Deserialise a binary Buffer produced by {@link encodeVfs} back into an
  * InternalDirectoryNode tree. Throws on magic/version mismatch or truncation.

package/dist/VirtualFileSystem/index.d.ts

@@ -86,6 +86,8 @@ declare class VirtualFileSystem extends EventEmitter {
     private _dirty;
     /** Active host-directory mounts: vPath → { hostPath, readOnly } */
     private readonly mounts;
+    /** Sorted mounts cache (longest-path-first). Rebuilt lazily on mount/unmount. */
+    private _sortedMounts;
     /** True when running in a browser environment (no host FS access). */
     private static readonly isBrowser;
     constructor(options?: VfsOptions);
@@ -248,6 +250,11 @@ declare class VirtualFileSystem extends EventEmitter {
     chmod(targetPath: string, mode: number): void;
     /** Returns metadata for a file or directory. */
     stat(targetPath: string): VfsNodeStats;
+    /**
+     * Fast type-only check — no Date/string allocation.
+     * Use instead of `stat().type` when that's all you need.
+     */
+    statType(targetPath: string): "file" | "directory" | null;
     /** Lists direct children names of a directory (sorted). */
     list(dirPath?: string): string[];
     /** Renders ASCII tree view of a directory hierarchy. */