typescript-virtual-container 1.0.8 → 1.1.1

package/src/VirtualShell/index.ts

@@ -1,40 +1,96 @@
-import type { VirtualUserManager } from "../SSHMimic/users";
+import { randomBytes } from "node:crypto";
+import { createCustomCommand, registerCommand, runCommand } from "../commands";
 import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
-import type VirtualFileSystem from "../VirtualFileSystem";
-import { createCustomCommand, registerCommand, runCommand } from "./commands";
+import VirtualFileSystem from "../VirtualFileSystem";
+import { VirtualUserManager } from "../VirtualUserManager";
 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,56 @@ 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;
+	}
+
+	/**
+	 * Writes a file on behalf of a user with quota enforcement.
+	 *
+	 * @param authUser User performing the write.
+	 * @param targetPath Destination path.
+	 * @param content File content.
+	 */
+	public writeFileAsUser(
+		authUser: string,
+		targetPath: string,
+		content: string | Buffer,
+	): void {
+		this.users.assertWriteWithinQuota(authUser, targetPath, content);
+		this.vfs.writeFile(targetPath, content);
+	}
 }
 
 export { VirtualShell };

package/src/VirtualShell/shell.ts

@@ -1,13 +1,22 @@
-import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } 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 {
+	spawnHtopProcess,
+	spawnNanoEditorProcess,
+} from "../../modules/shellInteractive";
+import {
+	getVisibleHtopPidList,
+	resolvePath,
+	type TerminalSize,
+	toTtyLines,
+} from "../../modules/shellRuntime";
+import { getCommandNames, runCommand } from "../commands";
 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";
 
 interface NanoSession {
 	kind: "nano" | "htop";
@@ -25,36 +34,19 @@ interface PendingSudo {
 	buffer: string;
 }
 
-function shellQuote(value: string): string {
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
-interface TerminalSize {
-	cols: number;
-	rows: number;
-}
-
-function toTtyLines(text: string): string {
-	return text
-		.replace(/\r\n/g, "\n")
-		.replace(/\r/g, "\n")
-		.replace(/\n/g, "\r\n");
-}
-
 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}`;
@@ -70,60 +62,6 @@ export function startShell(
 		`[${sessionId}] Shell started for user '${authUser}' at ${remoteAddress}`,
 	);
 
-	async function collectChildPids(parentPid: number): Promise<number[]> {
-		try {
-			const childrenRaw = await readFile(
-				`/proc/${parentPid}/task/${parentPid}/children`,
-				"utf8",
-			);
-			const directChildren = childrenRaw
-				.trim()
-				.split(/\s+/)
-				.filter(Boolean)
-				.map((value) => Number.parseInt(value, 10))
-				.filter((pid) => Number.isInteger(pid) && pid > 0);
-
-			const nested = await Promise.all(
-				directChildren.map((pid) => collectChildPids(pid)),
-			);
-			return [...directChildren, ...nested.flat()];
-		} catch {
-			return [];
-		}
-	}
-
-	async function getVisibleHtopPidList(): Promise<string | null> {
-		const rootPid = process.pid;
-		const descendants = await collectChildPids(rootPid);
-		const unique = Array.from(new Set(descendants)).sort((a, b) => a - b);
-		if (unique.length === 0) {
-			return null;
-		}
-
-		return unique.join(",");
-	}
-
-	function withTerminalSize(command: string): string {
-		const cols =
-			Number.isFinite(terminalSize.cols) && terminalSize.cols > 0
-				? Math.floor(terminalSize.cols)
-				: 80;
-		const rows =
-			Number.isFinite(terminalSize.rows) && terminalSize.rows > 0
-				? Math.floor(terminalSize.rows)
-				: 24;
-		return `stty cols ${cols} rows ${rows} 2>/dev/null; ${command}`;
-	}
-
-	function resolvePath(base: string, inputPath: string): string {
-		if (!inputPath || inputPath.trim() === "" || inputPath === ".") {
-			return base;
-		}
-		return inputPath.startsWith("/")
-			? path.posix.normalize(inputPath)
-			: path.posix.normalize(path.posix.join(base, inputPath));
-	}
-
 	function renderLine(): void {
 		const prompt = buildCurrentPrompt();
 		stream.write(`\r${prompt}${lineBuffer}\u001b[K`);
@@ -170,7 +108,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;
@@ -182,11 +120,9 @@ export function startShell(
 				challenge.commandLine,
 				challenge.targetUser,
 				hostname,
-				users,
 				"shell",
 				runCwd,
-				defaultShellProperties,
-				vfs,
+				shell,
 			),
 		);
 
@@ -221,12 +157,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();
 	}
 
@@ -240,8 +176,12 @@ export function startShell(
 		if (activeSession.kind === "nano") {
 			try {
 				const updatedContent = await readFile(activeSession.tempPath, "utf8");
-				vfs.writeFile(activeSession.targetPath, updatedContent);
-				await vfs.flushMirror();
+				shell.writeFileAsUser(
+					authUser,
+					activeSession.targetPath,
+					updatedContent,
+				);
+				await shell.vfs.flushMirror();
 			} catch {
 				// If temp file does not exist, nano exited without writing.
 			}
@@ -261,27 +201,11 @@ export function startShell(
 		initialContent: string,
 		tempPath: string,
 	): Promise<void> {
-		if (vfs.exists(targetPath)) {
+		if (shell.vfs.exists(targetPath)) {
 			await writeFile(tempPath, initialContent, "utf8");
 		}
 
-		const command = withTerminalSize(`nano -- ${shellQuote(tempPath)}`);
-		const editor = spawn("script", ["-qfec", command, "/dev/null"], {
-			stdio: ["pipe", "pipe", "pipe"],
-			env: {
-				...process.env,
-				// biome-ignore lint/style/useNamingConvention: TERM is an environment variable conventionally in uppercase
-				TERM: process.env.TERM ?? "xterm-256color",
-			},
-		});
-
-		editor.stdout.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
-
-		editor.stderr.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
+		const editor = spawnNanoEditorProcess(tempPath, terminalSize, stream);
 
 		editor.on("error", (error: Error) => {
 			stream.write(`nano: ${error.message}\r\n`);
@@ -307,23 +231,7 @@ export function startShell(
 			return;
 		}
 
-		const command = withTerminalSize(`htop -p ${shellQuote(pidList)}`);
-		const monitor = spawn("script", ["-qfec", command, "/dev/null"], {
-			stdio: ["pipe", "pipe", "pipe"],
-			env: {
-				...process.env,
-				// biome-ignore lint/style/useNamingConvention: TERM is an environment variable conventionally in uppercase
-				TERM: process.env.TERM ?? "xterm-256color",
-			},
-		});
-
-		monitor.stdout.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
-
-		monitor.stderr.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
+		const monitor = spawnHtopProcess(pidList, terminalSize, stream);
 
 		monitor.on("error", (error: Error) => {
 			stream.write(`htop: ${error.message}\r\n`);
@@ -378,13 +286,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}`;
 				})
@@ -440,17 +348,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;
 			};
@@ -461,12 +369,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 }),
 		);
@@ -537,7 +445,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;
 				}
@@ -650,16 +561,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);
@@ -709,12 +611,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/VirtualShell/shellParser.ts

@@ -9,7 +9,16 @@ export function parseShellPipeline(rawInput: string): Pipeline {
 	}
 
 	const commands: PipelineCommand[] = [];
-	const pipeTokens = tokenizePipeline(trimmed);
+	const tokenized = tokenizePipeline(trimmed);
+	if (tokenized.error) {
+		return {
+			commands: [],
+			isValid: false,
+			error: tokenized.error,
+		};
+	}
+
+	const pipeTokens = tokenized.tokens;
 
 	for (const token of pipeTokens) {
 		const cmd = parseCommandWithRedirections(token);
@@ -29,7 +38,7 @@ export function parseShellPipeline(rawInput: string): Pipeline {
 }
 
 /** Tokenize input by pipes, respecting quoted strings */
-function tokenizePipeline(input: string): string[] {
+function tokenizePipeline(input: string): { tokens: string[]; error?: string } {
 	const tokens: string[] = [];
 	let current = "";
 	let inQuotes = false;
@@ -49,9 +58,13 @@ function tokenizePipeline(input: string): string[] {
 			current += ch;
 			i++;
 		} else if (ch === "|" && !inQuotes) {
-			if (current.trim()) {
-				tokens.push(current.trim());
+			if (!current.trim()) {
+				return {
+					tokens: [],
+					error: "Syntax error near unexpected token '|'",
+				};
 			}
+			tokens.push(current.trim());
 			current = "";
 			i++;
 		} else {
@@ -60,11 +73,23 @@ function tokenizePipeline(input: string): string[] {
 		}
 	}
 
-	if (current.trim()) {
-		tokens.push(current.trim());
+	if (inQuotes) {
+		return {
+			tokens: [],
+			error: "Syntax error: unterminated quote",
+		};
 	}
 
-	return tokens;
+	if (!current.trim()) {
+		return {
+			tokens: [],
+			error: "Syntax error near unexpected token '|'",
+		};
+	}
+
+	tokens.push(current.trim());
+
+	return { tokens };
 }
 
 interface ParseResult {