typescript-virtual-container 1.4.8 → 1.5.0

package/src/VirtualShell/index.ts

@@ -42,6 +42,10 @@ export interface ShellProperties {
 	arch: string;
 }
 
+/**
+ * Minimal VFS interface accepted by {@link VirtualShell} as a drop-in replacement
+ * for the built-in {@link VirtualFileSystem}.
+ */
 export interface VirtualShellVfsLike {
 	restoreMirror(): Promise<void>;
 	flushMirror(): Promise<void>;
@@ -57,6 +61,9 @@ export interface VirtualShellVfsLike {
 	getUsageBytes?(targetPath?: string): number;
 }
 
+/**
+ * Constructor options for {@link VirtualShell} when passing an existing VFS instance.
+ */
 export interface VirtualShellVfsOptions {
 	vfsInstance?: VirtualShellVfsLike;
 }
@@ -153,7 +160,7 @@ class VirtualShell extends EventEmitter {
 	 *
 	 * @param hostname Virtual hostname used for prompts and idents.
 	 * @param properties Customizable properties shown in `uname -a` and similar commands.
-	 * @param vfsOptions Optional VFS persistence options (mode, snapshotPath).
+	 * @param vfsOptionsOrInstance Optional VFS persistence options (mode, snapshotPath) or an existing VFS instance.
 	 */
 	constructor(
 		hostname: string,
@@ -239,7 +246,7 @@ class VirtualShell extends EventEmitter {
 	 */
 	executeCommand(rawInput: string, authUser: string, cwd: string): void {
 		perf.mark("executeCommand");
-		if (this._idle) void this._idle.ping();
+		this._idle?.ping();
 		runCommand(rawInput, authUser, this.hostname, "shell", cwd, this);
 		this.emit("command", { command: rawInput, user: authUser, cwd });
 	}
@@ -266,7 +273,7 @@ class VirtualShell extends EventEmitter {
 		terminalSize: { cols: number; rows: number },
 	): void {
 		perf.mark("startInteractiveSession");
-		if (this._idle) void this._idle.ping();
+		this._idle?.ping();
 		// Interactive shell logic
 		this.emit("session:start", { user: authUser, sessionId, remoteAddress });
 		startShell(
@@ -452,6 +459,14 @@ class VirtualShell extends EventEmitter {
 	public get idleMs(): number {
 		return this._idle?.idleMs ?? 0;
 	}
+
+	/**
+	 * Ping the idle manager to signal external activity (e.g. SFTP, direct VFS writes).
+	 * No-op when idle management is disabled.
+	 */
+	public pingIdle(): void {
+		this._idle?.ping();
+	}
 }
 
 export { VirtualShell };

package/src/VirtualShell/shell.ts

@@ -2,7 +2,7 @@ import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import * as path from "node:path";
 import type { ShellProperties, VirtualShell } from ".";
-import { getCommandNames, makeDefaultEnv, runCommand } from "../commands";
+import { getCommandNames, makeDefaultEnv, runCommand, userHome } from "../commands";
 import {
 	spawnHtopProcess,
 	spawnNanoEditorProcess,
@@ -55,12 +55,12 @@ export function startShell(
 	let history = loadHistory(shell.vfs, authUser);
 	let historyIndex: number | null = null;
 	let historyDraft = "";
-	let cwd = `/home/${authUser}`;
+	let cwd = userHome(authUser);
 	const shellEnv: ShellEnv = makeDefaultEnv(authUser, hostname);
 	let nanoSession: NanoSession | null = null;
 	let pendingSudo: PendingSudo | null = null;
 	const buildCurrentPrompt = (): string => {
-		const homePath = `/home/${authUser}`;
+		const homePath = userHome(authUser);
 		const cwdLabel = cwd === homePath ? "~" : path.posix.basename(cwd) || "/";
 		return buildPrompt(authUser, hostname, cwdLabel);
 	};
@@ -71,7 +71,7 @@ export function startShell(
 
 	// Load .bashrc if it exists
 	void (async () => {
-		const bashrcPath = `/home/${authUser}/.bashrc`;
+		const bashrcPath = `${userHome(authUser)}/.bashrc`;
 		if (shell.vfs.exists(bashrcPath)) {
 			try {
 				const bashrc = shell.vfs.readFile(bashrcPath);
@@ -146,7 +146,7 @@ export function startShell(
 		if (!challenge.commandLine) {
 			authUser = challenge.targetUser;
 			if (challenge.loginShell) {
-				cwd = `/home/${authUser}`;
+				cwd = userHome(authUser);
 			}
 			shell.users.updateSession(sessionId, authUser, remoteAddress);
 			stream.write("\r\n");
@@ -154,7 +154,7 @@ export function startShell(
 			return;
 		}
 
-		const runCwd = challenge.loginShell ? `/home/${challenge.targetUser}` : cwd;
+		const runCwd = challenge.loginShell ? userHome(challenge.targetUser) : cwd;
 		const result = await Promise.resolve(
 			runCommand(
 				challenge.commandLine,
@@ -196,7 +196,7 @@ export function startShell(
 
 		if (result.switchUser) {
 			authUser = result.switchUser;
-			cwd = result.nextCwd ?? `/home/${authUser}`;
+			cwd = result.nextCwd ?? userHome(authUser);
 			shell.users.updateSession(sessionId, authUser, remoteAddress);
 		} else if (result.nextCwd) {
 			cwd = result.nextCwd;
@@ -388,11 +388,11 @@ export function startShell(
 		}
 
 		const data = history.length > 0 ? `${history.join("\n")}\n` : "";
-		shell.vfs.writeFile(`/home/${authUser}/.bash_history`, data);
+		shell.vfs.writeFile(`${userHome(authUser)}/.bash_history`, data);
 	}
 
 	function readLastLogin(): { at: string; from: string } | null {
-		const lastlogPath = `/home/${authUser}/.lastlog.json`;
+		const lastlogPath = `${userHome(authUser)}/.lastlog.json`;
 		if (!shell.vfs.exists(lastlogPath)) {
 			return null;
 		}
@@ -408,7 +408,7 @@ export function startShell(
 	}
 
 	function writeLastLogin(nowIso: string): void {
-		const lastlogPath = `/home/${authUser}/.lastlog`;
+		const lastlogPath = `${userHome(authUser)}/.lastlog`;
 		shell.vfs.writeFile(
 			lastlogPath,
 			JSON.stringify({ at: nowIso, from: remoteAddress }),
@@ -651,7 +651,7 @@ export function startShell(
 
 					if (result.switchUser) {
 						authUser = result.switchUser;
-						cwd = result.nextCwd ?? `/home/${authUser}`;
+						cwd = result.nextCwd ?? userHome(authUser);
 						shell.users.updateSession(sessionId, authUser, remoteAddress);
 						lineBuffer = "";
 						cursorPos = 0;
@@ -686,7 +686,7 @@ export function startShell(
 }
 
 function loadHistory(vfs: VirtualFileSystem, authUser: string): string[] {
-	const historyPath = `/home/${authUser}/.bash_history`;
+	const historyPath = `${userHome(authUser)}/.bash_history`;
 	if (!vfs.exists(historyPath)) {
 		vfs.writeFile(historyPath, "");
 		return [];

package/src/VirtualUserManager/index.ts

@@ -5,7 +5,10 @@ import type { PerfLogger } from "../utils/perfLogger";
 import { createPerfLogger } from "../utils/perfLogger";
 import type VirtualFileSystem from "../VirtualFileSystem";
 
-/** Persisted virtual user credential record. */
+/** 
+ * Persisted virtual user credential record.
+ * @internal
+ */
 export interface VirtualUserRecord {
 	/** Unique login name. */
 	username: string;
@@ -61,7 +64,6 @@ export class VirtualUserManager extends EventEmitter {
 	 * 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 is created.
 	 * @param autoSudoForNewUsers Whether newly created users are added to sudoers.
 	 */
 	constructor(
@@ -101,14 +103,14 @@ export class VirtualUserManager extends EventEmitter {
 		// 	changed = true;
 		// }
 		
-		// const homePath = `/home/root`;
-		// if (!this.vfs.exists(homePath)) {
-		// 	this.vfs.mkdir(homePath, 0o755);
-		// 	this.vfs.writeFile(
-		// 		`${homePath}/README.txt`,
-		// 		`Welcome to the virtual environment, root`,
-		// 	);
-		// }
+		const homePath = "/root";
+		if (!this.vfs.exists(homePath)) {
+			this.vfs.mkdir(homePath, 0o755);
+			this.vfs.writeFile(
+				`${homePath}/README.txt`,
+				`Welcome to the virtual environment, root`,
+			);
+		}
 
 		if (changed) {
 			await this.persist();
@@ -171,7 +173,7 @@ export class VirtualUserManager extends EventEmitter {
 	 */
 	public getUsageBytes(username: string): number {
 		perf.mark("getUsageBytes");
-		const homePath = `/home/${username}`;
+		const homePath = username === "root" ? "/root" : `/home/${username}`;
 		if (!this.vfs.exists(homePath)) {
 			return 0;
 		}
@@ -200,7 +202,7 @@ export class VirtualUserManager extends EventEmitter {
 		}
 
 		const normalizedPath = normalizeVfsPath(targetPath);
-		const homePath = normalizeVfsPath(`/home/${username}`);
+		const homePath = normalizeVfsPath(username === "root" ? "/root" : `/home/${username}`);
 		const inUserHome =
 			normalizedPath === homePath || normalizedPath.startsWith(`${homePath}/`);
 		if (!inUserHome) {
@@ -277,7 +279,7 @@ export class VirtualUserManager extends EventEmitter {
 		if (this.autoSudoForNewUsers) {
 			this.sudoers.add(username);
 		}
-		const homePath = `/home/${username}`;
+		const homePath = username === "root" ? "/root" : `/home/${username}`;
 		if (!this.vfs.exists(homePath)) {
 			this.vfs.mkdir(homePath, 0o755);
 			this.vfs.writeFile(

package/src/commands/apt.ts

@@ -57,8 +57,8 @@ export const aptCommand: ShellModule = {
 			case "update": {
 				return {
 					stdout: [
-						"Hit:1 fortune://packages.fortune.local aurora InRelease",
-						"Hit:2 fortune://security.fortune.local aurora-security InRelease",
+						"Hit:1 fortune://packages.fortune.local nyx InRelease",
+						"Hit:2 fortune://security.fortune.local nyx-security InRelease",
 						"Reading package lists... Done",
 						"Building dependency tree... Done",
 						"Reading state information... Done",
@@ -218,7 +218,7 @@ export const aptCacheCommand: ShellModule = {
 						`  Candidate: ${def.version}`,
 						`  Version table:`,
 						`     ${def.version} 500`,
-						`        500 fortune://packages.fortune.local aurora/main amd64 Packages`,
+						`        500 fortune://packages.fortune.local nyx/main amd64 Packages`,
 					].join("\n"),
 					exitCode: 0,
 				};

package/src/commands/cd.ts

@@ -1,5 +1,6 @@
 import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
+import { userHome } from "./runtime";
 
 /**
  * Change current working directory.
@@ -12,7 +13,7 @@ export const cdCommand: ShellModule = {
 	category: "navigation",
 	params: ["[path]"],
 	run: ({ authUser, shell, cwd, args }) => {
-		const target = resolvePath(cwd, args[0] ?? `~`);
+		const target = resolvePath(cwd, args[0] ?? "~", userHome(authUser));
 		assertPathAccess(authUser, target, "cd");
 		const stats = shell.vfs.stat(target);
 		if (stats.type !== "directory") {

package/src/commands/command-helpers.ts

@@ -1,4 +1,8 @@
-type ArgParseOptions = {
+/**
+ * Options for argument parsing helpers.
+ * @public
+ */
+export type ArgParseOptions = {
 	flags?: string[];
 	flagsWithValue?: string[];
 };

package/src/commands/helpers.ts

@@ -28,12 +28,13 @@ export function normalizeTerminalOutput(text: string): string {
 		.trimEnd();
 }
 
-export function resolvePath(cwd: string, inputPath: string): string {
+export function resolvePath(cwd: string, inputPath: string, homeDir?: string): string {
 	if (!inputPath || inputPath.trim() === "") {
 		return cwd;
 	}
 	if (inputPath.startsWith("~")) {
-		return path.posix.normalize(`/home/${inputPath.slice(1)}`);
+		const home = homeDir ?? "/root";
+		return path.posix.normalize(`${home}${inputPath.slice(1)}`);
 	}
 	return inputPath.startsWith("/")
 		? path.posix.normalize(inputPath)

package/src/commands/index.ts

@@ -6,4 +6,4 @@ export {
 	resolveModule
 } from "./registry";
 
-export { makeDefaultEnv, runCommand, runCommandDirect } from "./runtime";
+export { makeDefaultEnv, runCommand, runCommandDirect, userHome } from "./runtime";

package/src/commands/lsb-release.ts

@@ -13,7 +13,7 @@ export const lsbReleaseCommand: ShellModule = {
 	params: ["[-a] [-i] [-d] [-r] [-c]"],
 	run: ({ args, shell }) => {
 		let osName = shell.properties?.os ?? "Fortune GNU/Linux x64";
-		let codename = "aurora";
+		let codename = "nyx";
 		let version = "1.0";
 
 		try {

package/src/commands/runtime.ts

@@ -11,11 +11,16 @@ import { expandAsync, expandBraces } from "../utils/expand";
 import { tokenizeCommand } from "../utils/tokenize";
 import { resolveModule } from "./registry";
 
+/** Returns the home directory path for a given user. Root lives at /root. */
+export function userHome(authUser: string): string {
+	return authUser === "root" ? "/root" : `/home/${authUser}`;
+}
+
 export function makeDefaultEnv(authUser: string, hostname: string): ShellEnv {
 	return {
 		vars: {
 			PATH: "/usr/local/bin:/usr/bin:/bin",
-			HOME: `/home/${authUser}`,
+			HOME: userHome(authUser),
 			USER: authUser,
 			LOGNAME: authUser,
 			SHELL: "/bin/sh",

package/src/index.ts

@@ -1,10 +1,12 @@
 export { HoneyPot } from "./Honeypot/index";
 export { SshClient } from "./SSHClient/index";
 export { SftpMimic as VirtualSftpServer, SshMimic as VirtualSshServer } from "./SSHMimic/index";
+export type { SftpMimicOptions as VirtualSftpServerOptions } from "./SSHMimic/sftp";
 export { default as VirtualFileSystem } from "./VirtualFileSystem/index";
 export { VirtualPackageManager } from "./VirtualPackageManager/index";
 export { VirtualShell } from "./VirtualShell/index";
 export { VirtualUserManager } from "./VirtualUserManager/index";
+export type { VirtualActiveSession } from "./VirtualUserManager/index";
 export { IdleManager } from "./VirtualShell/idleManager";
 export type { IdleManagerOptions, IdleState } from "./VirtualShell/idleManager";
 
@@ -18,6 +20,7 @@ export type {
 	CommandOutcome,
 	CommandResult,
 	NanoEditorSession,
+	PasswordChallenge,
 	ShellEnv,
 	ShellModule,
 	SudoChallenge
@@ -38,7 +41,7 @@ export type {
 	WriteFileOptions
 } from "./types/vfs";
 export type { VfsOptions, VfsPersistenceMode } from "./VirtualFileSystem/index";
-export type { ShellProperties } from "./VirtualShell/index";
+export type { ShellProperties, VirtualShellVfsLike, VirtualShellVfsOptions } from "./VirtualShell/index";
 
 export type {
 	InstalledPackage, PackageDefinition,
@@ -60,4 +63,5 @@ export {
 	getFlag,
 	ifFlag
 } from "./commands/command-helpers";
+export type { ArgParseOptions } from "./commands/command-helpers";