typescript-virtual-container 1.0.7 → 1.1.0

package/src/VirtualShell/commands/wget.ts

@@ -3,11 +3,12 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ShellModule } from "../../types/commands";
-import { getArg, getFlag, ifFlag } from "./command-helpers";
+import { ifFlag, parseArgs } from "./command-helpers";
 import {
 	assertPathAccess,
 	normalizeTerminalOutput,
 	resolvePath,
+	runHostCommand,
 	stripUrlFilename,
 } from "./helpers";
 
@@ -82,37 +83,26 @@ function runHostWget(args: string[]): Promise<{
 export const wgetCommand: ShellModule = {
 	name: "wget",
 	params: ["[url]"],
-	run: async ({ authUser, vfs, cwd, args }) => {
-		const outputPathValue = getFlag(args, [
-			"-o",
-			"-O",
-			"--output",
-			"--output-document",
-		]);
-		const outputPath =
-			typeof outputPathValue === "string" && outputPathValue.length > 0
-				? outputPathValue
-				: null;
-		const parserOptions = {
+	run: async ({ authUser, cwd, args, shell }) => {
+		const { flagsWithValues, positionals } = parseArgs(args, {
 			flagsWithValue: ["-o", "-O", "--output", "--output-document"],
-		};
-		const inputArgs: string[] = [];
-		for (let index = 0; ; index += 1) {
-			const arg = getArg(args, index, parserOptions);
-			if (!arg) {
-				break;
-			}
-			inputArgs.push(arg);
-		}
-		const url = inputArgs[0];
-		const isHelpLike = ifFlag(args, ["-h", "--help", "-V", "--version"]);
+		});
+		const outputPath =
+			flagsWithValues.get("-o") ||
+			flagsWithValues.get("-O") ||
+			flagsWithValues.get("--output") ||
+			flagsWithValues.get("--output-document") ||
+			null;
+		const url = positionals[0];
 
 		if (!url) {
 			return { stderr: "wget: missing URL", exitCode: 1 };
 		}
 
+		const isHelpLike = ifFlag(args, ["-h", "--help", "-V", "--version"]);
+
 		if (isHelpLike) {
-			const result = await runHostWget(inputArgs);
+			const result = await runHostWget(args);
 			return {
 				stdout: normalizeTerminalOutput(result.stdout),
 				stderr: result.stderr
@@ -126,8 +116,8 @@ export const wgetCommand: ShellModule = {
 		const tempFile = join(tempDir, "download");
 
 		try {
-			const hostArgs = [...inputArgs, "-O", tempFile];
-			const result = await runHostWget(hostArgs);
+			const hostArgs = [...positionals, "-O", tempFile];
+			const result = await runHostCommand("wget", hostArgs);
 
 			if (result.exitCode !== 0) {
 				return {
@@ -139,9 +129,9 @@ export const wgetCommand: ShellModule = {
 			}
 
 			const content = await readFile(tempFile, "utf8");
-			const target = resolvePath(cwd, outputPath ?? stripUrlFilename(url));
+			const target = resolvePath(cwd, outputPath || stripUrlFilename(url));
 			assertPathAccess(authUser, target, "wget");
-			vfs.writeFile(target, content);
+			shell.vfs.writeFile(target, content);
 
 			return {
 				stdout: `saved ${target}`,

package/src/VirtualShell/commands/who.ts

@@ -4,8 +4,8 @@ import type { ShellModule } from "../../types/commands";
 export const whoCommand: ShellModule = {
 	name: "who",
 	params: [],
-	run: ({ users }) => {
-		const lines = users.listActiveSessions().map((session) => {
+	run: ({ shell }) => {
+		const lines = shell.users.listActiveSessions().map((session) => {
 			const loginAt = new Date(session.startedAt);
 			const displayDate = Number.isNaN(loginAt.getTime())
 				? session.startedAt

package/src/VirtualShell/index.ts

@@ -1,40 +1,96 @@
-import type { VirtualUserManager } from "../SSHMimic/users";
+import { randomBytes } from "node:crypto";
 import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
-import type VirtualFileSystem from "../VirtualFileSystem";
+import VirtualFileSystem from "../VirtualFileSystem";
+import { VirtualUserManager } from "../VirtualUserManager";
 import { createCustomCommand, registerCommand, runCommand } from "./commands";
 import { startShell } from "./shell";
 
 export interface ShellProperties {
 	kernel: string;
-	os: "Fortune GNU/Linux x64";
-	arch: "x86_64";
+	os: string;
+	arch: string;
 }
 
-export const defaultShellProperties: ShellProperties = {
+const defaultShellProperties: ShellProperties = {
 	kernel: "1.0.0+itsrealfortune+1-amd64",
 	os: "Fortune GNU/Linux x64",
 	arch: "x86_64",
 };
 
+function resolveRootPassword(): string {
+	const configured = process.env.SSH_MIMIC_ROOT_PASSWORD;
+	if (configured && configured.trim().length > 0) {
+		return configured;
+	}
+
+	const generated = randomBytes(18).toString("base64url");
+	console.warn(
+		`[ssh-mimic] SSH_MIMIC_ROOT_PASSWORD missing; generated ephemeral root password: ${generated}`,
+	);
+	return generated;
+}
+
+function resolveAutoSudoForNewUsers(): boolean {
+	const configured = process.env.SSH_MIMIC_AUTO_SUDO_NEW_USERS;
+	if (!configured) {
+		return true;
+	}
+
+	return !["0", "false", "no", "off"].includes(configured.toLowerCase());
+}
+
+/**
+ * Coordinates the virtual filesystem, user manager, and command runtime.
+ *
+ * Instances are used both by the SSH server facade and by the programmatic
+ * client API.
+ */
 class VirtualShell {
-	private vfs: VirtualFileSystem;
-	private users: VirtualUserManager;
-	private hostname: string;
-	public properties: ShellProperties;
+	basePath: string = ".";
+	vfs: VirtualFileSystem;
+	users: VirtualUserManager;
+	hostname: string;
+	properties: ShellProperties;
 
+	/**
+	 * Creates a new virtual shell instance.
+	 *
+	 * @param hostname Virtual hostname used for prompts and idents.
+	 * @param properties Customizable properties shown in `uname -a` and similar commands.
+	 * @param basePath Optional base path for the virtual filesystem (defaults to process.cwd()).
+	 */
 	constructor(
-		vfs: VirtualFileSystem,
-		users: VirtualUserManager,
 		hostname: string,
 		properties?: ShellProperties,
+		basePath?: string,
 	) {
-		this.vfs = vfs;
-		this.users = users;
 		this.hostname = hostname;
 		this.properties = properties || defaultShellProperties;
+		this.basePath = basePath || ".";
+		this.vfs = new VirtualFileSystem(this.basePath);
+		this.users = new VirtualUserManager(
+			this.vfs,
+			resolveRootPassword(),
+			resolveAutoSudoForNewUsers(),
+		);
+		this.vfs.restoreMirror().then(() => {
+			this.users = new VirtualUserManager(
+				this.vfs,
+				resolveRootPassword(),
+				resolveAutoSudoForNewUsers(),
+			);
+			this.users.initialize();
+		});
 	}
 
+	/**
+	 * Registers a new command in the shell runtime.
+	 *
+	 * @param name Case-insensitive command name (no spaces).
+	 * @param params List of parameter names for help text (no validation).
+	 * @param callback Function invoked with command context on execution.
+	 */
 	addCommand(
 		name: string,
 		params: string[],
@@ -48,19 +104,26 @@ class VirtualShell {
 		registerCommand(createCustomCommand(normalized, params, callback));
 	}
 
+	/**
+	 * Executes a command line string in the context of this shell instance.
+	 *
+	 * @param rawInput
+	 * @param authUser
+	 * @param cwd
+	 */
 	executeCommand(rawInput: string, authUser: string, cwd: string): void {
-		runCommand(
-			rawInput,
-			authUser,
-			this.hostname,
-			this.users,
-			"shell",
-			cwd,
-			this.properties,
-			this.vfs,
-		);
+		runCommand(rawInput, authUser, this.hostname, "shell", cwd, this);
 	}
 
+	/**
+	 * Starts an interactive session with the shell.
+	 *
+	 * @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.
+	 */
+
 	startInteractiveSession(
 		stream: ShellStream,
 		authUser: string,
@@ -73,14 +136,40 @@ class VirtualShell {
 			this.properties,
 			stream,
 			authUser,
-			this.vfs!,
 			this.hostname,
-			this.users!,
 			sessionId,
 			remoteAddress,
 			terminalSize,
+			this,
 		);
 	}
+
+	/**
+	 * Returns virtual filesystem instance after server started.
+	 *
+	 * @returns VirtualFileSystem or null when not started.
+	 */
+	public getVfs(): VirtualFileSystem | null {
+		return this?.vfs ?? null;
+	}
+
+	/**
+	 * Returns user manager instance after server started.
+	 *
+	 * @returns VirtualUserManager or null when not started.
+	 */
+	public getUsers(): VirtualUserManager | null {
+		return this?.users ?? null;
+	}
+
+	/**
+	 * Returns hostname shown in prompts and idents.
+	 *
+	 * @returns Configured hostname label.
+	 */
+	public getHostname(): string {
+		return this?.hostname;
+	}
 }
 
 export { VirtualShell };

package/src/VirtualShell/shell.ts

@@ -1,10 +1,9 @@
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import * as path from "node:path";
-import { defaultShellProperties, type ShellProperties } from ".";
+import type { ShellProperties, VirtualShell } from ".";
 import { formatLoginDate } from "../SSHMimic/loginFormat";
 import { buildPrompt } from "../SSHMimic/prompt";
-import type { VirtualUserManager } from "../SSHMimic/users";
 import type { ShellStream } from "../types/streams";
 import type VirtualFileSystem from "../VirtualFileSystem";
 import { getCommandNames, runCommand } from "./commands";
@@ -45,16 +44,15 @@ export function startShell(
 	properties: ShellProperties,
 	stream: ShellStream,
 	authUser: string,
-	vfs: VirtualFileSystem,
 	hostname: string,
-	users: VirtualUserManager,
 	sessionId: string | null,
 	remoteAddress = "unknown",
 	terminalSize: TerminalSize = { cols: 80, rows: 24 },
+	shell: VirtualShell,
 ): void {
 	let lineBuffer = "";
 	let cursorPos = 0;
-	let history = loadHistory(vfs);
+	let history = loadHistory(shell.vfs);
 	let historyIndex: number | null = null;
 	let historyDraft = "";
 	let cwd = `/home/${authUser}`;
@@ -66,6 +64,9 @@ export function startShell(
 		return buildPrompt(authUser, hostname, cwdLabel);
 	};
 	const commandNames = Array.from(new Set(getCommandNames())).sort();
+	console.log(
+		`[${sessionId}] Shell started for user '${authUser}' at ${remoteAddress}`,
+	);
 
 	async function collectChildPids(parentPid: number): Promise<number[]> {
 		try {
@@ -167,7 +168,7 @@ export function startShell(
 		if (!challenge.commandLine) {
 			authUser = challenge.targetUser;
 			cwd = `/home/${authUser}`;
-			users.updateSession(sessionId, authUser, remoteAddress);
+			shell.users.updateSession(sessionId, authUser, remoteAddress);
 			stream.write("\r\n");
 			renderLine();
 			return;
@@ -179,11 +180,9 @@ export function startShell(
 				challenge.commandLine,
 				challenge.targetUser,
 				hostname,
-				users,
 				"shell",
 				runCwd,
-				defaultShellProperties,
-				vfs,
+				shell,
 			),
 		);
 
@@ -218,12 +217,12 @@ export function startShell(
 		if (result.switchUser) {
 			authUser = result.switchUser;
 			cwd = result.nextCwd ?? `/home/${authUser}`;
-			users.updateSession(sessionId, authUser, remoteAddress);
+			shell.users.updateSession(sessionId, authUser, remoteAddress);
 		} else if (result.nextCwd) {
 			cwd = result.nextCwd;
 		}
 
-		await vfs.flushMirror();
+		await shell.vfs.flushMirror();
 		renderLine();
 	}
 
@@ -237,8 +236,8 @@ export function startShell(
 		if (activeSession.kind === "nano") {
 			try {
 				const updatedContent = await readFile(activeSession.tempPath, "utf8");
-				vfs.writeFile(activeSession.targetPath, updatedContent);
-				await vfs.flushMirror();
+				shell.vfs.writeFile(activeSession.targetPath, updatedContent);
+				await shell.vfs.flushMirror();
 			} catch {
 				// If temp file does not exist, nano exited without writing.
 			}
@@ -258,7 +257,7 @@ export function startShell(
 		initialContent: string,
 		tempPath: string,
 	): Promise<void> {
-		if (vfs.exists(targetPath)) {
+		if (shell.vfs.exists(targetPath)) {
 			await writeFile(tempPath, initialContent, "utf8");
 		}
 
@@ -375,13 +374,13 @@ export function startShell(
 		const basePath = resolvePath(cwd, dirPart || ".");
 
 		try {
-			return vfs
+			return shell.vfs
 				.list(basePath)
 				.filter((entry) => !entry.startsWith("."))
 				.filter((entry) => entry.startsWith(namePart))
 				.map((entry) => {
 					const fullPath = path.posix.join(basePath, entry);
-					const st = vfs.stat(fullPath);
+					const st = shell.vfs.stat(fullPath);
 					const suffix = st.type === "directory" ? "/" : "";
 					return `${dirPart}${entry}${suffix}`;
 				})
@@ -437,17 +436,17 @@ export function startShell(
 		}
 
 		const data = history.length > 0 ? `${history.join("\n")}\n` : "";
-		vfs.writeFile("/virtual-env-js/.bash_history", data);
+		shell.vfs.writeFile("/virtual-env-js/.bash_history", data);
 	}
 
 	function readLastLogin(): { at: string; from: string } | null {
 		const lastlogPath = `/virtual-env-js/.lastlog/${authUser}.json`;
-		if (!vfs.exists(lastlogPath)) {
+		if (!shell.vfs.exists(lastlogPath)) {
 			return null;
 		}
 
 		try {
-			return JSON.parse(vfs.readFile(lastlogPath)) as {
+			return JSON.parse(shell.vfs.readFile(lastlogPath)) as {
 				at: string;
 				from: string;
 			};
@@ -458,12 +457,12 @@ export function startShell(
 
 	function writeLastLogin(nowIso: string): void {
 		const dir = "/virtual-env-js/.lastlog";
-		if (!vfs.exists(dir)) {
-			vfs.mkdir(dir, 0o700);
+		if (!shell.vfs.exists(dir)) {
+			shell.vfs.mkdir(dir, 0o700);
 		}
 
 		const lastlogPath = `${dir}/${authUser}.json`;
-		vfs.writeFile(
+		shell.vfs.writeFile(
 			lastlogPath,
 			JSON.stringify({ at: nowIso, from: remoteAddress }),
 		);
@@ -534,7 +533,10 @@ export function startShell(
 				if (ch === "\r" || ch === "\n") {
 					const password = pendingSudo.buffer;
 					pendingSudo.buffer = "";
-					const valid = users.verifyPassword(pendingSudo.username, password);
+					const valid = shell.users.verifyPassword(
+						pendingSudo.username,
+						password,
+					);
 					await finishSudoPrompt(valid);
 					return;
 				}
@@ -647,16 +649,7 @@ export function startShell(
 
 				if (line.length > 0) {
 					const result = await Promise.resolve(
-						runCommand(
-							line,
-							authUser,
-							hostname,
-							users,
-							"shell",
-							cwd,
-							defaultShellProperties,
-							vfs,
-						),
+						runCommand(line, authUser, hostname, "shell", cwd, shell),
 					);
 
 					pushHistory(line);
@@ -706,12 +699,12 @@ export function startShell(
 					if (result.switchUser) {
 						authUser = result.switchUser;
 						cwd = result.nextCwd ?? `/home/${authUser}`;
-						users.updateSession(sessionId, authUser, remoteAddress);
+						shell.users.updateSession(sessionId, authUser, remoteAddress);
 						lineBuffer = "";
 						cursorPos = 0;
 					}
 
-					await vfs.flushMirror();
+					await shell.vfs.flushMirror();
 				}
 
 				renderLine();

package/src/{SSHMimic/users.ts → VirtualUserManager/index.ts}

@@ -26,7 +26,9 @@ export interface VirtualActiveSession {
 }
 
 /**
- * User, sudoers, and active session manager for SSH mimic runtime.
+ * Persistent user, sudoers, and active-session manager for the shell runtime.
+ *
+ * Passwords are hashed with scrypt and stored in the backing virtual filesystem.
  */
 export class VirtualUserManager {
 	private readonly usersPath = "/virtual-env-js/.auth/htpasswd";
@@ -38,10 +40,11 @@ export class VirtualUserManager {
 	private nextTty = 0;
 
 	/**
-	 * Creates user manager instance.
+	 * Creates a user manager instance backed by a virtual filesystem.
 	 *
 	 * @param vfs Backing virtual filesystem used for persistence.
-	 * @param defaultRootPassword Initial root password used when root missing.
+	 * @param defaultRootPassword Initial root password used when root is created.
+	 * @param autoSudoForNewUsers Whether newly created users are added to sudoers.
 	 */
 	constructor(
 		private readonly vfs: VirtualFileSystem,

package/src/index.ts

@@ -1,8 +1,8 @@
 import { SshClient } from "./SSHMimic/client";
 import { SshMimic } from "./SSHMimic/index";
-import { VirtualUserManager } from "./SSHMimic/users";
 import VirtualFileSystem from "./VirtualFileSystem";
-import type { VirtualShell } from "./VirtualShell";
+import { VirtualShell } from "./VirtualShell";
+import { VirtualUserManager } from "./VirtualUserManager";
 
 export type {
 	CommandContext,
@@ -32,9 +32,9 @@ export type {
 export {
 	SshClient,
 	VirtualFileSystem,
-	SshMimic as VirtualMachine,
+	VirtualShell,
+	SshMimic as VirtualSshServer,
 	VirtualUserManager,
-	type VirtualShell,
 };
 
 export {

package/src/standalone.ts

@@ -1,21 +1,26 @@
-import { VirtualMachine } from ".";
+import { VirtualShell, VirtualSshServer } from ".";
 
-const sshHostname = process.env.SSH_MIMIC_HOSTNAME ?? "typescript-vm";
-const sshMimic = new VirtualMachine({ port: 2222, hostname: sshHostname });
+const hostname = process.env.SSH_MIMIC_HOSTNAME ?? "typescript-vm";
+const virtualShell = new VirtualShell(hostname);
 
-sshMimic
+virtualShell.addCommand("demo", [], () => {
+	return {
+		stdout: "This is a demo command. It does nothing useful.",
+		exitCode: 0,
+	};
+});
+
+new VirtualSshServer({
+	port: 2222,
+	hostname,
+	shell: virtualShell,
+})
 	.start()
 	.then((port: number) => {
-		if (!sshMimic.shell) console.error("Failed to initialize SSH Mimic shell.");
-		else {
-			console.log(`SSH Mimic initialized. Listening on port ${port}.`);
-			sshMimic.shell.addCommand("demo", [], () => {
-				return {
-					stdout: "This is a demo command. It does nothing useful.",
-					exitCode: 0,
-				};
-			});
-		}
+		// if (!sshMimic) console.error("Failed to initialize SSH Mimic shell.");
+		// else {
+		console.log(`SSH Mimic initialized. Listening on port ${port}.`);
+		// }
 	})
 	.catch((error: unknown) => {
 		console.error("Failed to start SSH Mimic:", error);

package/src/types/commands.ts

@@ -1,12 +1,8 @@
 /** Command invocation mode used by shell runtime. */
 export type CommandMode = "shell" | "exec";
 
-import type {
-	VirtualActiveSession,
-	VirtualUserManager,
-} from "../SSHMimic/users";
-import type VirtualFileSystem from "../VirtualFileSystem";
-import type { ShellProperties } from "../VirtualShell";
+import type { VirtualShell } from "../VirtualShell";
+import type { VirtualActiveSession } from "../VirtualUserManager";
 
 /**
  * Normalized command execution output.
@@ -67,8 +63,6 @@ export interface CommandContext {
 	authUser: string;
 	/** Virtual hostname shown in prompt and banners. */
 	hostname: string;
-	/** User and session manager instance. */
-	users: VirtualUserManager;
 	/** Snapshot of currently active user sessions. */
 	activeSessions: VirtualActiveSession[];
 	/** Original unparsed command line input. */
@@ -78,13 +72,11 @@ export interface CommandContext {
 	/** Tokenized arguments excluding command name. */
 	args: string[];
 	/** Virtual shell instance. */
-	shellProps: ShellProperties;
+	shell: VirtualShell;
 	/** Optional stdin payload (used by pipes/redirections). */
 	stdin?: string;
 	/** Current working directory for command execution. */
 	cwd: string;
-	/** Virtual filesystem instance for IO operations. */
-	vfs: VirtualFileSystem;
 }
 
 /** Contract implemented by each shell command module. */

package/tests/parser-executor.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { VirtualShell } from "../src";
+import { executePipeline } from "../src/SSHMimic/executor";
+import { parseShellPipeline } from "../src/VirtualShell/shellParser";
+
+describe("Pipeline parser and executor", () => {
+  test("parses simple pipeline", () => {
+    const pipeline = parseShellPipeline("echo hello | grep h");
+    expect(pipeline.isValid).toBe(true);
+    expect(pipeline.commands).toHaveLength(2);
+    expect(pipeline.commands[0]?.name).toBe("echo");
+    expect(pipeline.commands[1]?.name).toBe("grep");
+  });
+
+  test("handles invalid syntax", () => {
+    const pipeline = parseShellPipeline("echo hello |");
+    expect(pipeline.isValid).toBe(false);
+    expect(pipeline.error).toBeDefined();
+  });
+
+  test("executes simple pipeline", async () => {
+    const shell = new VirtualShell("localhost");
+    const pipeline = parseShellPipeline("echo hello | grep h");
+
+    const result = await executePipeline(
+      pipeline,
+      "root",
+      "localhost",
+      "shell",
+      "/",
+      shell
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("hello");
+  });
+});

package/tests/users.test.ts

@@ -2,8 +2,8 @@ import { describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { VirtualUserManager } from "../src/SSHMimic/users";
 import VirtualFileSystem from "../src/VirtualFileSystem";
+import { VirtualUserManager } from "../src/VirtualUserManager";
 
 async function withTempVfs(
 	run: (vfs: VirtualFileSystem) => Promise<void>,