typescript-virtual-container 1.2.8 → 1.3.0

package/src/VirtualShell/index.ts

@@ -1,16 +1,42 @@
 import { EventEmitter } from "node:events";
-import { createCustomCommand, registerCommand, runCommand } from "../commands";
+import { createCustomCommand, registerCommand } from "../commands/registry";
+import { runCommand } from "../commands/runtime";
+import {
+	bootstrapLinuxRootfs,
+	refreshProc,
+	syncEtcPasswd,
+} from "../modules/linuxRootfs";
 import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
 import type { PerfLogger } from "../utils/perfLogger";
 import { createPerfLogger } from "../utils/perfLogger";
 import VirtualFileSystem, { type VfsOptions } from "../VirtualFileSystem";
+import { VirtualPackageManager } from "../VirtualPackageManager";
 import { VirtualUserManager } from "../VirtualUserManager";
 import { startShell } from "./shell";
 
+/**
+ * Virtual machine identity strings surfaced by system-info commands
+ * (`uname`, `neofetch`, `lsb_release`, `/proc/version`, `/etc/os-release`).
+ *
+ * Pass this as the second argument to `new VirtualShell()` to customise the
+ * distro name, kernel version, and CPU architecture reported inside the shell.
+ *
+ * @example
+ * ```ts
+ * const shell = new VirtualShell("my-vm", {
+ *   kernel: "6.1.0+custom-amd64",
+ *   os:     "Acme GNU/Linux x64",
+ *   arch:   "x86_64",
+ * });
+ * ```
+ */
 export interface ShellProperties {
+	/** Kernel version string (e.g. `"1.0.0+itsrealfortune+1-amd64"`). */
 	kernel: string;
+	/** Full OS description (e.g. `"Fortune GNU/Linux x64"`). */
 	os: string;
+	/** CPU architecture label (e.g. `"x86_64"`, `"aarch64"`). */
 	arch: string;
 }
 
@@ -32,16 +58,40 @@ function resolveAutoSudoForNewUsers(): boolean {
 }
 
 /**
- * Coordinates the virtual filesystem, user manager, and command runtime.
+ * Coordinates the virtual filesystem, user manager, package manager, and
+ * command runtime for a single isolated shell environment.
  *
- * Instances are used both by the SSH server facade and by the programmatic
- * client API.
+ * Each instance owns its own VFS tree, user database, package registry, and
+ * session state — multiple instances are fully independent.
+ *
+ * Instances are consumed both by the SSH/SFTP server facades and directly via
+ * the programmatic `SshClient` API.
+ *
+ * @example
+ * ```ts
+ * const shell = new VirtualShell("my-vm");
+ * await shell.ensureInitialized();
+ * const client = new SshClient(shell, "root");
+ * const result = await client.exec("uname -a");
+ * ```
+ *
+ * @fires VirtualShell#initialized  Emitted once the VFS and users are ready.
+ * @fires VirtualShell#command       Emitted after every command execution.
+ * @fires VirtualShell#session:start Emitted when an interactive session opens.
  */
 class VirtualShell extends EventEmitter {
+	/** Backing virtual filesystem — use for direct path operations. */
 	vfs: VirtualFileSystem;
+	/** Virtual user database — use for auth, quotas, and session tracking. */
 	users: VirtualUserManager;
+	/** APT/dpkg package manager backed by the built-in package registry. */
+	packageManager: VirtualPackageManager;
+	/** Hostname shown in the shell prompt and SSH ident string. */
 	hostname: string;
+	/** Distro identity strings surfaced by `uname`, `neofetch`, etc. */
 	properties: ShellProperties;
+	/** Unix ms timestamp of shell creation — used by `uptime` and `/proc/uptime`. */
+	startTime: number;
 	private initialized: Promise<void>;
 
 	/**
@@ -60,17 +110,27 @@ class VirtualShell extends EventEmitter {
 		perf.mark("constructor");
 		this.hostname = hostname;
 		this.properties = properties || defaultShellProperties;
+		this.startTime = Date.now();
 		this.vfs = new VirtualFileSystem(vfsOptions ?? {});
 		this.users = new VirtualUserManager(this.vfs, resolveAutoSudoForNewUsers());
+		this.packageManager = new VirtualPackageManager(this.vfs, this.users);
 
 		// Store references to avoid TypeScript "used before assigned" errors
 		const vfs = this.vfs;
 		const users = this.users;
+		const pm = this.packageManager;
+		const shellProps = this.properties;
+		const shellHostname = this.hostname;
+		const startTime = this.startTime;
 
 		// Initialize both VFS mirror and users, ensuring all is ready before auth
 		this.initialized = (async () => {
 			await vfs.restoreMirror();
 			await users.initialize();
+			// Bootstrap Linux rootfs (idempotent)
+			bootstrapLinuxRootfs(vfs, users, shellHostname, shellProps, startTime);
+			// Load installed packages from dpkg status
+			pm.load();
 			this.emit("initialized");
 		})();
 	}
@@ -105,11 +165,16 @@ class VirtualShell extends EventEmitter {
 	}
 
 	/**
-	 * Executes a command line string in the context of this shell instance.
+	 * Executes a raw command line string programmatically.
+	 *
+	 * Supports the full shell operator set (`&&`, `||`, `;`, `|`, `>`, `<`,
+	 * `$(cmd)`) and alias expansion. The result is emitted via the
+	 * `"command"` event but not returned — use `SshClient.exec()` for a
+	 * result-returning wrapper.
 	 *
-	 * @param rawInput
-	 * @param authUser
-	 * @param cwd
+	 * @param rawInput Unparsed command line (e.g. `"ls -la /tmp"`).
+	 * @param authUser Username to run the command as.
+	 * @param cwd      Current working directory for path resolution.
 	 */
 	executeCommand(rawInput: string, authUser: string, cwd: string): void {
 		perf.mark("executeCommand");
@@ -118,14 +183,19 @@ class VirtualShell extends EventEmitter {
 	}
 
 	/**
-	 * Starts an interactive session with the shell.
+	 * Attaches an interactive PTY session to this shell instance.
 	 *
-	 * @param stream The stream for the interactive session.
-	 * @param authUser The authenticated user for the session.
-	 * @param sessionId The ID of the session.
-	 * @param remoteAddress The address of the remote client.
+	 * Called internally by `SshMimic` when a client opens a shell channel.
+	 * The session reads from `stream` (user keystrokes) and writes back ANSI
+	 * output. History, `.bashrc` sourcing, and Ctrl+W/Ctrl+U line editing are
+	 * handled automatically.
+	 *
+	 * @param stream        Bidirectional SSH channel stream.
+	 * @param authUser      Authenticated username bound to this session.
+	 * @param sessionId     Stable session UUID (used for `who` output), or `null`.
+	 * @param remoteAddress IP or hostname of the connecting client.
+	 * @param terminalSize  Initial terminal dimensions in columns and rows.
 	 */
-
 	startInteractiveSession(
 		stream: ShellStream,
 		authUser: string,
@@ -146,6 +216,55 @@ class VirtualShell extends EventEmitter {
 			terminalSize,
 			this,
 		);
+		// Refresh /proc/<pid> and /proc/self after session is registered
+		this.refreshProcSessions();
+	}
+
+	/**
+	 * Refreshes the `/proc` virtual filesystem with current system state.
+	 *
+	 * Updates `/proc/uptime`, `/proc/meminfo`, `/proc/cpuinfo`,
+	 * `/proc/version`, `/proc/loadavg`, `/proc/self`, and per-session
+	 * `/proc/<pid>` entries from live session and host data.
+	 *
+	 * Called automatically during `bootstrapLinuxRootfs`. Call again before
+	 * reading `/proc` files for up-to-date values.
+	 */
+	public refreshProcFs(): void {
+		refreshProc(
+			this.vfs,
+			this.properties,
+			this.hostname,
+			this.startTime,
+			this.users.listActiveSessions(),
+		);
+	}
+
+	/**
+	 * Updates only the session-dependent `/proc` entries (`/proc/<pid>`,
+	 * `/proc/self`). Cheaper than a full `refreshProcFs()` — call this
+	 * whenever a session is registered or unregistered.
+	 */
+	public refreshProcSessions(): void {
+		refreshProc(
+			this.vfs,
+			this.properties,
+			this.hostname,
+			this.startTime,
+			this.users.listActiveSessions(),
+		);
+	}
+
+	/**
+	 * Syncs `/etc/passwd`, `/etc/group`, and `/etc/shadow` from the current
+	 * `VirtualUserManager` state.
+	 *
+	 * Called automatically during `bootstrapLinuxRootfs`. Call again after
+	 * `users.addUser()`, `users.deleteUser()`, or `users.addSudoer()` to keep
+	 * the classic Unix credential files in sync with the user manager.
+	 */
+	public syncPasswd(): void {
+		syncEtcPasswd(this.vfs, this.users);
 	}
 
 	/**

package/src/VirtualShell/shell.ts

@@ -73,9 +73,20 @@ export function startShell(
 				for (const line of bashrc.split("\n")) {
 					const l = line.trim();
 					if (!l || l.startsWith("#")) continue;
-					await runCommand(l, authUser, hostname, "shell", cwd, shell, undefined, shellEnv);
+					await runCommand(
+						l,
+						authUser,
+						hostname,
+						"shell",
+						cwd,
+						shell,
+						undefined,
+						shellEnv,
+					);
 				}
-			} catch { /* ignore bashrc errors */ }
+			} catch {
+				/* ignore bashrc errors */
+			}
 		}
 	})();
 
@@ -585,7 +596,16 @@ export function startShell(
 
 				if (line.length > 0) {
 					const result = await Promise.resolve(
-						runCommand(line, authUser, hostname, "shell", cwd, shell, undefined, shellEnv),
+						runCommand(
+							line,
+							authUser,
+							hostname,
+							"shell",
+							cwd,
+							shell,
+							undefined,
+							shellEnv,
+						),
 					);
 
 					pushHistory(line);

package/src/VirtualShell/shellParser.ts

@@ -1,4 +1,10 @@
-import type { Pipeline, PipelineCommand, Script, Statement, LogicalOp } from "../types/pipeline";
+import type {
+	Pipeline,
+	PipelineCommand,
+	Script,
+	Statement,
+	LogicalOp,
+} from "../types/pipeline";
 
 // ── Public API ───────────────────────────────────────────────────────────────
 
@@ -56,8 +62,9 @@ export function expandToken(
 	token = token.replace(/\$#/g, "0");
 
 	// ${VAR:-default} and ${VAR:+value}
-	token = token.replace(/\$\{([^}:]+):-([^}]*)\}/g, (_, name, def) =>
-		env[name] ?? def,
+	token = token.replace(
+		/\$\{([^}:]+):-([^}]*)\}/g,
+		(_, name, def) => env[name] ?? def,
 	);
 	token = token.replace(/\$\{([^}:]+):\+([^}]*)\}/g, (_, name, val) =>
 		env[name] ? val : "",
@@ -67,8 +74,9 @@ export function expandToken(
 	token = token.replace(/\$\{([^}]+)\}/g, (_, name) => env[name] ?? "");
 
 	// $VAR (greedy: match longest valid identifier)
-	token = token.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name) =>
-		env[name] ?? "",
+	token = token.replace(
+		/\$([A-Za-z_][A-Za-z0-9_]*)/g,
+		(_, name) => env[name] ?? "",
 	);
 
 	return token;
@@ -120,7 +128,10 @@ function parseStatements(input: string): Statement[] {
 	return statements;
 }
 
-interface Segment { text: string; op?: LogicalOp }
+interface Segment {
+	text: string;
+	op?: LogicalOp;
+}
 
 function splitByLogicalOps(input: string): Segment[] {
 	const segments: Segment[] = [];
@@ -139,19 +150,61 @@ function splitByLogicalOps(input: string): Segment[] {
 		const ch = input[i]!;
 		const ch2 = input.slice(i, i + 2);
 
-		if ((ch === '"' || ch === "'") && !inQ) { inQ = true; qChar = ch; current += ch; i++; continue; }
-		if (inQ && ch === qChar) { inQ = false; current += ch; i++; continue; }
-		if (inQ) { current += ch; i++; continue; }
+		if ((ch === '"' || ch === "'") && !inQ) {
+			inQ = true;
+			qChar = ch;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (inQ && ch === qChar) {
+			inQ = false;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (inQ) {
+			current += ch;
+			i++;
+			continue;
+		}
 
-		if (ch === "(") { depth++; current += ch; i++; continue; }
-		if (ch === ")") { depth--; current += ch; i++; continue; }
-		if (depth > 0) { current += ch; i++; continue; }
+		if (ch === "(") {
+			depth++;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (ch === ")") {
+			depth--;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (depth > 0) {
+			current += ch;
+			i++;
+			continue;
+		}
 
-		if (ch2 === "&&") { flush("&&"); i += 2; continue; }
-		if (ch2 === "||") { flush("||"); i += 2; continue; }
-		if (ch === ";") { flush(";"); i++; continue; }
+		if (ch2 === "&&") {
+			flush("&&");
+			i += 2;
+			continue;
+		}
+		if (ch2 === "||") {
+			flush("||");
+			i += 2;
+			continue;
+		}
+		if (ch === ";") {
+			flush(";");
+			i++;
+			continue;
+		}
 
-		current += ch; i++;
+		current += ch;
+		i++;
 	}
 	flush();
 	return segments;
@@ -170,13 +223,26 @@ function splitByPipe(input: string): string[] {
 
 	for (let i = 0; i < input.length; i++) {
 		const ch = input[i]!;
-		if ((ch === '"' || ch === "'") && !inQ) { inQ = true; qChar = ch; current += ch; continue; }
-		if (inQ && ch === qChar) { inQ = false; current += ch; continue; }
-		if (inQ) { current += ch; continue; }
+		if ((ch === '"' || ch === "'") && !inQ) {
+			inQ = true;
+			qChar = ch;
+			current += ch;
+			continue;
+		}
+		if (inQ && ch === qChar) {
+			inQ = false;
+			current += ch;
+			continue;
+		}
+		if (inQ) {
+			current += ch;
+			continue;
+		}
 
 		// || was already consumed at statement level, bare | is pipe
 		if (ch === "|" && input[i + 1] !== "|") {
-			if (!current.trim()) throw new Error("Syntax error near unexpected token '|'");
+			if (!current.trim())
+				throw new Error("Syntax error near unexpected token '|'");
 			tokens.push(current.trim());
 			current = "";
 		} else {
@@ -185,7 +251,8 @@ function splitByPipe(input: string): string[] {
 	}
 
 	const tail = current.trim();
-	if (!tail && tokens.length > 0) throw new Error("Syntax error near unexpected token '|'");
+	if (!tail && tokens.length > 0)
+		throw new Error("Syntax error near unexpected token '|'");
 	if (tail) tokens.push(tail);
 	return tokens;
 }
@@ -204,19 +271,27 @@ function parseCommandWithRedirections(token: string): PipelineCommand {
 		const part = parts[i]!;
 		if (part === "<") {
 			i++;
-			if (i >= parts.length) throw new Error("Syntax error: expected filename after <");
+			if (i >= parts.length)
+				throw new Error("Syntax error: expected filename after <");
 			inputFile = parts[i];
 			i++;
 		} else if (part === ">>") {
 			i++;
-			if (i >= parts.length) throw new Error("Syntax error: expected filename after >>");
-			outputFile = parts[i]; appendOutput = true; i++;
+			if (i >= parts.length)
+				throw new Error("Syntax error: expected filename after >>");
+			outputFile = parts[i];
+			appendOutput = true;
+			i++;
 		} else if (part === ">") {
 			i++;
-			if (i >= parts.length) throw new Error("Syntax error: expected filename after >");
-			outputFile = parts[i]; appendOutput = false; i++;
+			if (i >= parts.length)
+				throw new Error("Syntax error: expected filename after >");
+			outputFile = parts[i];
+			appendOutput = false;
+			i++;
 		} else {
-			cmdParts.push(part); i++;
+			cmdParts.push(part);
+			i++;
 		}
 	}
 
@@ -236,26 +311,49 @@ function tokenizeCommand(input: string): string[] {
 		const next = input[i + 1];
 
 		if ((ch === '"' || ch === "'") && !inQ) {
-			inQ = true; qChar = ch; i++; continue;
+			inQ = true;
+			qChar = ch;
+			i++;
+			continue;
 		}
 		if (inQ && ch === qChar) {
-			inQ = false; qChar = ""; i++; continue;
+			inQ = false;
+			qChar = "";
+			i++;
+			continue;
+		}
+		if (inQ) {
+			current += ch;
+			i++;
+			continue;
 		}
-		if (inQ) { current += ch; i++; continue; }
 
 		if (ch === " ") {
-			if (current) { tokens.push(current); current = ""; }
-			i++; continue;
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			i++;
+			continue;
 		}
 
 		if ((ch === ">" || ch === "<") && !inQ) {
-			if (current) { tokens.push(current); current = ""; }
-			if (ch === ">" && next === ">") { tokens.push(">>"); i += 2; }
-			else { tokens.push(ch); i++; }
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			if (ch === ">" && next === ">") {
+				tokens.push(">>");
+				i += 2;
+			} else {
+				tokens.push(ch);
+				i++;
+			}
 			continue;
 		}
 
-		current += ch; i++;
+		current += ch;
+		i++;
 	}
 	if (current) tokens.push(current);
 	return tokens;

package/src/VirtualUserManager/index.ts

@@ -290,10 +290,11 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Updates password for an existing user account.
+	 * Updates the password for an existing user account.
 	 *
 	 * @param username Username to update.
-	 * @param password New plaintext password.
+	 * @param password New plaintext password (must be non-empty).
+	 * @throws When the user does not exist or the password is empty.
 	 */
 	public async setPassword(username: string, password: string): Promise<void> {
 		perf.mark("setPassword");
@@ -309,9 +310,10 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Deletes existing non-root user account.
+	 * Deletes an existing non-root user account and revokes sudo access.
 	 *
 	 * @param username Username to remove.
+	 * @throws When `username` is `"root"` or the user does not exist.
 	 */
 	public async deleteUser(username: string): Promise<void> {
 		perf.mark("deleteUser");
@@ -343,9 +345,10 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Grants sudo access to existing user.
+	 * Grants sudo privileges to an existing user.
 	 *
 	 * @param username Username to promote.
+	 * @throws When the user does not exist.
 	 */
 	public async addSudoer(username: string): Promise<void> {
 		perf.mark("addSudoer");
@@ -359,9 +362,10 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Revokes sudo access from user.
+	 * Revokes sudo privileges from a user. Root cannot be demoted.
 	 *
 	 * @param username Username to demote.
+	 * @throws When `username` is `"root"`.
 	 */
 	public async removeSudoer(username: string): Promise<void> {
 		perf.mark("removeSudoer");
@@ -375,11 +379,14 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Registers active session and allocates tty id.
+	 * Registers a new active session and allocates a virtual TTY identifier.
 	 *
-	 * @param username Session username.
-	 * @param remoteAddress Session source address.
-	 * @returns Registered session descriptor.
+	 * Called by the SSH server when a client is authenticated. The returned
+	 * descriptor is visible in `who` output and `listActiveSessions()`.
+	 *
+	 * @param username      Authenticated username bound to the session.
+	 * @param remoteAddress IP address or hostname of the connecting client.
+	 * @returns The newly created `VirtualActiveSession` descriptor.
 	 */
 	public registerSession(
 		username: string,
@@ -403,9 +410,11 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Unregisters active session when connection closes.
+	 * Removes an active session record when the connection closes.
+	 *
+	 * Safe to call with a `null` or `undefined` session ID — it will be a no-op.
 	 *
-	 * @param sessionId Session identifier; ignored when nullish.
+	 * @param sessionId Session UUID returned by `registerSession()`, or nullish.
 	 */
 	public unregisterSession(sessionId: string | null | undefined): void {
 		perf.mark("unregisterSession");
@@ -425,11 +434,15 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Updates username/address metadata for existing session.
+	 * Updates the username and remote address metadata for an active session.
 	 *
-	 * @param sessionId Session identifier; ignored when nullish.
-	 * @param username New username value.
-	 * @param remoteAddress New remote address value.
+	 * Called internally by `su` and `sudo` when the effective user changes
+	 * within a session. Silently ignored when the session ID is nullish or
+	 * unknown.
+	 *
+	 * @param sessionId     Session UUID to update, or nullish for no-op.
+	 * @param username      New effective username.
+	 * @param remoteAddress New remote address (usually unchanged).
 	 */
 	public updateSession(
 		sessionId: string | null | undefined,
@@ -454,9 +467,11 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Lists active sessions sorted by start time.
+	 * Returns a snapshot of all currently active sessions, sorted by start time.
+	 *
+	 * Used by `who`, `ps`, `uptime`, and the `HoneyPot` auditor.
 	 *
-	 * @returns Snapshot of active session descriptors.
+	 * @returns Array of `VirtualActiveSession` descriptors.
 	 */
 	public listActiveSessions(): VirtualActiveSession[] {
 		perf.mark("listActiveSessions");
@@ -465,6 +480,15 @@ export class VirtualUserManager extends EventEmitter {
 		);
 	}
 
+	/**
+	 * Returns a sorted list of all registered usernames.
+	 *
+	 * @returns Array of username strings sorted alphabetically.
+	 */
+	public listUsers(): string[] {
+		return Array.from(this.users.keys()).sort();
+	}
+
 	private loadFromVfs(): void {
 		this.users.clear();
 
@@ -610,6 +634,14 @@ export class VirtualUserManager extends EventEmitter {
 		return record;
 	}
 
+	/**
+	 * Returns `true` when the user has a non-empty password set.
+	 *
+	 * A user with no password (or whose password hash matches the empty-string
+	 * hash) is allowed to authenticate without a credential check.
+	 *
+	 * @param username Target username.
+	 */
 	public hasPassword(username: string): boolean {
 		perf.mark("hasPassword");
 		if (this.getPasswordHash(username) === this.hashPassword("")) {
@@ -620,10 +652,13 @@ export class VirtualUserManager extends EventEmitter {
 	}
 
 	/**
-	 * Hashes plaintext password with per-user salt using scrypt.
+	 * Hashes a plaintext password using scrypt (or SHA-256 in fast-hash mode).
 	 *
-	 * @param password Plaintext password.
-	 * @returns Hex-encoded password hash.
+	 * Set `SSH_MIMIC_FAST_PASSWORD_HASH=1` to switch to SHA-256 for test
+	 * environments where scrypt latency is undesirable.
+	 *
+	 * @param password Plaintext password string.
+	 * @returns Hex-encoded hash string.
 	 */
 	public hashPassword(password: string): string {
 		if (VirtualUserManager.fastPasswordHash) {
@@ -648,7 +683,10 @@ export class VirtualUserManager extends EventEmitter {
 			throw new Error("invalid password");
 		}
 	}
-	private readonly authorizedKeys = new Map<string, Array<{ algo: string; data: Buffer }>>();
+	private readonly authorizedKeys = new Map<
+		string,
+		Array<{ algo: string; data: Buffer }>
+	>();
 
 	/**
 	 * Adds an SSH public key for a user, enabling public-key authentication.
@@ -681,7 +719,9 @@ export class VirtualUserManager extends EventEmitter {
 	 *
 	 * @param username Target user.
 	 */
-	public getAuthorizedKeys(username: string): Array<{ algo: string; data: Buffer }> {
+	public getAuthorizedKeys(
+		username: string,
+	): Array<{ algo: string; data: Buffer }> {
 		return this.authorizedKeys.get(username) ?? [];
 	}
 }