typescript-virtual-container 1.0.1 → 1.0.3

package/.github/workflows/test-battery.yml

@@ -8,9 +8,8 @@ permissions:
   contents: read
 
 jobs:
-  typecheck:
+  setup:
     runs-on: ubuntu-latest
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -23,12 +22,36 @@ jobs:
       - name: Install dependencies
         run: bun install
 
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
+
+  typecheck:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Restore dependencies
+        uses: actions/cache@v3
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
+
       - name: Run typecheck
         run: bun check
 
   lint:
+    needs: setup
     runs-on: ubuntu-latest
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -38,8 +61,11 @@ jobs:
         with:
           bun-version: latest
 
-      - name: Install dependencies
-        run: bun install
+      - name: Restore dependencies
+        uses: actions/cache@v3
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
 
       - name: Run lint
         run: bun lint
@@ -49,7 +75,6 @@ jobs:
       - typecheck
       - lint
     runs-on: ubuntu-latest
-
     steps:
       - name: Test battery passed
         run: echo "Typecheck, lint and tests succeeded."

package/CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on Keep a Changelog.
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-04-14
+
 ### Added
 
 - Governance and community files:
@@ -14,6 +16,13 @@ The format is based on Keep a Changelog.
   - SECURITY.md
   - CODE_OF_CONDUCT.md
   - GitHub issue and PR templates
+- Security hardening for virtual auth storage and shell access:
+  - Non-root commands now block access to `/virtual-env-js/.auth/**`.
+  - Auth files are persisted with restrictive modes (`0700` for `.auth`, `0600` for `htpasswd` and `sudoers`).
+  - Root password no longer falls back to a fixed default when `SSH_MIMIC_ROOT_PASSWORD` is unset; startup generates an ephemeral password instead.
+- New environment toggle `SSH_MIMIC_AUTO_SUDO_NEW_USERS` to control whether newly created users are added to sudoers by default.
+- README and security docs now describe the new auth hardening and configuration flags.
+- Added tests covering `.auth` path protection and auto-sudo behavior.
 
 ## [1.0.1] - 2026-04-14
 

package/README.md

@@ -1040,13 +1040,15 @@ The following commands are available in both SSH shell mode and via `SshClient.e
 ### Environment Variables
 
 - **`SSH_MIMIC_HOSTNAME`**: Override server hostname at startup (default: "typescript-vm")
-- **`SSH_MIMIC_ROOT_PASSWORD`**: Set root password (default: "root")
+- **`SSH_MIMIC_ROOT_PASSWORD`**: Set root password. If unset, a random ephemeral password is generated at startup and logged once.
+- **`SSH_MIMIC_AUTO_SUDO_NEW_USERS`**: Control whether new users are added to sudoers automatically (default: enabled). Set to `0`, `false`, `no`, or `off` to disable.
 
 **Example:**
 
 ```bash
 export SSH_MIMIC_HOSTNAME=production-lab
 export SSH_MIMIC_ROOT_PASSWORD=SecurePass123
+export SSH_MIMIC_AUTO_SUDO_NEW_USERS=false
 npm run start
 ```
 
@@ -1231,6 +1233,8 @@ const ssh = new VirtualMachine({ port: 2222, hostname: "hostname" });
 - Passwords are hashed with `scrypt` in the virtual auth store.
 - Root account is always protected and cannot be deleted.
 - Sudo privileges are explicit and persisted in sudoers data.
+- Protect the root password in production by setting `SSH_MIMIC_ROOT_PASSWORD`; otherwise startup logs a generated ephemeral password.
+- Disable `SSH_MIMIC_AUTO_SUDO_NEW_USERS` when you want newly created users to stay unprivileged by default.
 - This project is not intended to provide kernel-level or process-level isolation.
 
 If you discover a vulnerability, avoid public disclosure in issues and contact maintainers privately first.

package/package.json

@@ -3,7 +3,7 @@
   "description": "In-memory SSH server with virtual filesystem and typed programmatic API",
   "module": "src/index.ts",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "license": "MIT",
   "keywords": [
     "ssh",

package/src/SSHMimic/commands/cat.ts

@@ -1,16 +1,17 @@
 import type { ShellModule } from "../../types/commands";
-import { resolveReadablePath } from "./helpers";
+import { assertPathAccess, resolveReadablePath } from "./helpers";
 
 export const catCommand: ShellModule = {
 	name: "cat",
 	params: ["<file>"],
-	run: ({ vfs, cwd, args }) => {
+	run: ({ authUser, vfs, cwd, args }) => {
 		const fileArg = args[0];
 		if (!fileArg) {
 			return { stderr: "cat: missing file operand", exitCode: 1 };
 		}
 
 		const target = resolveReadablePath(vfs, cwd, fileArg);
+		assertPathAccess(authUser, target, "cat");
 		return { stdout: vfs.readFile(target), exitCode: 0 };
 	},
 };

package/src/SSHMimic/commands/cd.ts

@@ -1,11 +1,12 @@
 import type { ShellModule } from "../../types/commands";
-import { resolvePath } from "./helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
 
 export const cdCommand: ShellModule = {
 	name: "cd",
 	params: ["[path]"],
-	run: ({ vfs, cwd, args, mode }) => {
+	run: ({ authUser, vfs, cwd, args, mode }) => {
 		const target = resolvePath(cwd, args[0] ?? "/virtual-env-js");
+		assertPathAccess(authUser, target, "cd");
 		const stats = vfs.stat(target);
 		if (stats.type !== "directory") {
 			return { stderr: `cd: not a directory: ${target}`, exitCode: 1 };

package/src/SSHMimic/commands/curl.ts

@@ -1,6 +1,10 @@
 import { spawn } from "node:child_process";
 import type { ShellModule } from "../../types/commands";
-import { normalizeTerminalOutput, resolvePath } from "./helpers";
+import {
+	assertPathAccess,
+	normalizeTerminalOutput,
+	resolvePath,
+} from "./helpers";
 
 function parseCurlOutputPath(args: string[]): {
 	outputPath: string | null;
@@ -105,7 +109,7 @@ function runHostCurl(args: string[]): Promise<{
 export const curlCommand: ShellModule = {
 	name: "curl",
 	params: ["[-o file] <url>"],
-	run: async ({ vfs, cwd, args }) => {
+	run: async ({ authUser, vfs, cwd, args }) => {
 		const { outputPath, inputArgs } = parseCurlOutputPath(args);
 		const url = inputArgs[0];
 		const isHelpLike = inputArgs.some(
@@ -130,7 +134,9 @@ export const curlCommand: ShellModule = {
 		}
 
 		if (outputPath) {
-			vfs.writeFile(resolvePath(cwd, outputPath), result.stdout);
+			const target = resolvePath(cwd, outputPath);
+			assertPathAccess(authUser, target, "curl");
+			vfs.writeFile(target, result.stdout);
 			return {
 				stderr: result.stderr
 					? normalizeTerminalOutput(result.stderr)

package/src/SSHMimic/commands/helpers.ts

@@ -1,6 +1,8 @@
 import * as path from "node:path";
 import type VirtualFileSystem from "../../VirtualFileSystem";
 
+const PROTECTED_PREFIXES = ["/virtual-env-js/.auth"] as const;
+
 function normalizeFetchUrl(input: string): string {
 	if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(input)) {
 		return input;
@@ -32,6 +34,30 @@ export function resolvePath(cwd: string, inputPath: string): string {
 		: path.posix.normalize(path.posix.join(cwd, inputPath));
 }
 
+function isProtectedPath(targetPath: string): boolean {
+	const normalized = targetPath.startsWith("/")
+		? path.posix.normalize(targetPath)
+		: path.posix.normalize(`/${targetPath}`);
+
+	return PROTECTED_PREFIXES.some(
+		(prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`),
+	);
+}
+
+export function assertPathAccess(
+	authUser: string,
+	targetPath: string,
+	operation: string,
+): void {
+	if (authUser === "root") {
+		return;
+	}
+
+	if (isProtectedPath(targetPath)) {
+		throw new Error(`${operation}: permission denied: ${targetPath}`);
+	}
+}
+
 export function parseOutputPath(args: string[]): {
 	outputPath: string | null;
 	inputArgs: string[];

package/src/SSHMimic/commands/ls.ts

@@ -1,5 +1,5 @@
 import type { ShellModule } from "../../types/commands";
-import { joinListWithType, resolvePath } from "./helpers";
+import { assertPathAccess, joinListWithType, resolvePath } from "./helpers";
 
 function formatPermissions(mode: number, isDirectory: boolean): string {
 	const fileType = isDirectory ? "d" : "-";
@@ -28,10 +28,11 @@ function formatDate(date: Date): string {
 export const lsCommand: ShellModule = {
 	name: "ls",
 	params: ["[path]"],
-	run: ({ vfs, cwd, args }) => {
+	run: ({ authUser, vfs, cwd, args }) => {
 		const longFormat = args.includes("-l") || args.includes("--long");
 		const targetArg = args.find((arg) => !arg.startsWith("-"));
 		const target = resolvePath(cwd, targetArg ?? cwd);
+		assertPathAccess(authUser, target, "ls");
 		const items = vfs.list(target).filter((name) => !name.startsWith("."));
 		const rendered = longFormat
 			? items

package/src/SSHMimic/commands/mkdir.ts

@@ -1,16 +1,18 @@
 import type { ShellModule } from "../../types/commands";
-import { resolvePath } from "./helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
 
 export const mkdirCommand: ShellModule = {
 	name: "mkdir",
 	params: ["<dir>"],
-	run: ({ vfs, cwd, args }) => {
+	run: ({ authUser, vfs, cwd, args }) => {
 		if (args.length === 0) {
 			return { stderr: "mkdir: missing operand", exitCode: 1 };
 		}
 
 		for (const dir of args) {
-			vfs.mkdir(resolvePath(cwd, dir));
+			const target = resolvePath(cwd, dir);
+			assertPathAccess(authUser, target, "mkdir");
+			vfs.mkdir(target);
 		}
 		return { exitCode: 0 };
 	},

package/src/SSHMimic/commands/nano.ts

@@ -1,17 +1,18 @@
 import * as path from "node:path";
 import type { ShellModule } from "../../types/commands";
-import { resolvePath } from "./helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
 
 export const nanoCommand: ShellModule = {
 	name: "nano",
 	params: ["<file>"],
-	run: ({ vfs, cwd, args }) => {
+	run: ({ authUser, vfs, cwd, args }) => {
 		const fileArg = args[0];
 		if (!fileArg) {
 			return { stderr: "nano: missing file operand", exitCode: 1 };
 		}
 
 		const targetPath = resolvePath(cwd, fileArg);
+		assertPathAccess(authUser, targetPath, "nano");
 		const initialContent = vfs.exists(targetPath)
 			? vfs.readFile(targetPath)
 			: "";

package/src/SSHMimic/commands/rm.ts

@@ -1,10 +1,10 @@
 import type { ShellModule } from "../../types/commands";
-import { resolvePath } from "./helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
 
 export const rmCommand: ShellModule = {
 	name: "rm",
 	params: ["[-r|-rf] <path>"],
-	run: ({ vfs, cwd, args }) => {
+	run: ({ authUser, vfs, cwd, args }) => {
 		if (args.length === 0) {
 			return { stderr: "rm: missing operand", exitCode: 1 };
 		}
@@ -18,7 +18,9 @@ export const rmCommand: ShellModule = {
 		}
 
 		for (const target of targets) {
-			vfs.remove(resolvePath(cwd, target), { recursive });
+			const resolvedTarget = resolvePath(cwd, target);
+			assertPathAccess(authUser, resolvedTarget, "rm");
+			vfs.remove(resolvedTarget, { recursive });
 		}
 
 		return { exitCode: 0 };

package/src/SSHMimic/commands/touch.ts

@@ -1,16 +1,17 @@
 import type { ShellModule } from "../../types/commands";
-import { resolvePath } from "./helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
 
 export const touchCommand: ShellModule = {
 	name: "touch",
 	params: ["<file>"],
-	run: ({ vfs, cwd, args }) => {
+	run: ({ authUser, vfs, cwd, args }) => {
 		if (args.length === 0) {
 			return { stderr: "touch: missing file operand", exitCode: 1 };
 		}
 
 		for (const file of args) {
 			const target = resolvePath(cwd, file);
+			assertPathAccess(authUser, target, "touch");
 			if (!vfs.exists(target)) {
 				vfs.writeFile(target, "");
 			}

package/src/SSHMimic/commands/tree.ts

@@ -1,11 +1,12 @@
 import type { ShellModule } from "../../types/commands";
-import { resolvePath } from "./helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
 
 export const treeCommand: ShellModule = {
 	name: "tree",
 	params: ["[path]"],
-	run: ({ vfs, cwd, args }) => {
+	run: ({ authUser, vfs, cwd, args }) => {
 		const target = resolvePath(cwd, args[0] ?? cwd);
+		assertPathAccess(authUser, target, "tree");
 		return { stdout: vfs.tree(target), exitCode: 0 };
 	},
 };

package/src/SSHMimic/commands/wget.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ShellModule } from "../../types/commands";
 import {
+	assertPathAccess,
 	normalizeTerminalOutput,
 	parseOutputPath,
 	resolvePath,
@@ -81,7 +82,7 @@ function runHostWget(args: string[]): Promise<{
 export const wgetCommand: ShellModule = {
 	name: "wget",
 	params: ["[url]"],
-	run: async ({ vfs, cwd, args }) => {
+	run: async ({ authUser, vfs, cwd, args }) => {
 		const { outputPath, inputArgs } = parseOutputPath(args);
 		const url = inputArgs[0];
 		const isHelpLike = inputArgs.some(
@@ -122,6 +123,7 @@ export const wgetCommand: ShellModule = {
 
 			const content = await readFile(tempFile, "utf8");
 			const target = resolvePath(cwd, outputPath ?? stripUrlFilename(url));
+			assertPathAccess(authUser, target, "wget");
 			vfs.writeFile(target, content);
 
 			return {

package/src/SSHMimic/index.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { Server as SshServer } from "ssh2";
 import VirtualFileSystem from "../VirtualFileSystem";
 import { runExec } from "./exec";
@@ -5,6 +6,28 @@ import { loadOrCreateHostKey } from "./hostKey";
 import { startShell } from "./shell";
 import { VirtualUserManager } from "./users";
 
+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());
+}
+
 /**
  * SSH server wrapper that exposes virtual shell and exec sessions.
  *
@@ -52,7 +75,8 @@ class SshMimic {
 		await this.vfs.restoreMirror();
 		this.users = new VirtualUserManager(
 			this.vfs,
-			process.env.SSH_MIMIC_ROOT_PASSWORD ?? "root",
+			resolveRootPassword(),
+			resolveAutoSudoForNewUsers(),
 		);
 		await this.users.initialize();
 

package/src/SSHMimic/users.ts

@@ -31,6 +31,7 @@ export interface VirtualActiveSession {
 export class VirtualUserManager {
 	private readonly usersPath = "/virtual-env-js/.auth/htpasswd";
 	private readonly sudoersPath = "/virtual-env-js/.auth/sudoers";
+	private readonly authDirPath = "/virtual-env-js/.auth";
 	private readonly users = new Map<string, VirtualUserRecord>();
 	private readonly sudoers = new Set<string>();
 	private readonly activeSessions = new Map<string, VirtualActiveSession>();
@@ -45,6 +46,7 @@ export class VirtualUserManager {
 	constructor(
 		private readonly vfs: VirtualFileSystem,
 		private readonly defaultRootPassword: string = "root",
+		private readonly autoSudoForNewUsers: boolean = true,
 	) {}
 
 	/**
@@ -54,12 +56,7 @@ export class VirtualUserManager {
 		this.loadFromVfs();
 		this.loadSudoersFromVfs();
 
-		if (!this.users.has("root")) {
-			this.users.set(
-				"root",
-				this.createRecord("root", this.defaultRootPassword),
-			);
-		}
+		this.users.set("root", this.createRecord("root", this.defaultRootPassword));
 
 		this.sudoers.add("root");
 
@@ -97,7 +94,9 @@ export class VirtualUserManager {
 		}
 
 		this.users.set(username, this.createRecord(username, password));
-		this.sudoers.add(username);
+		if (this.autoSudoForNewUsers) {
+			this.sudoers.add(username);
+		}
 		const homePath = `/home/${username}`;
 		if (!this.vfs.exists(homePath)) {
 			this.vfs.mkdir(homePath, 0o755);
@@ -290,6 +289,10 @@ export class VirtualUserManager {
 	}
 
 	private async persist(): Promise<void> {
+		if (!this.vfs.exists(this.authDirPath)) {
+			this.vfs.mkdir(this.authDirPath, 0o700);
+		}
+
 		const content = Array.from(this.users.values())
 			.sort((left, right) => left.username.localeCompare(right.username))
 			.map((record) =>
@@ -300,11 +303,13 @@ export class VirtualUserManager {
 		this.vfs.writeFile(
 			this.usersPath,
 			content.length > 0 ? `${content}\n` : "",
+			{ mode: 0o600 },
 		);
 		const sudoersContent = Array.from(this.sudoers.values()).sort().join("\n");
 		this.vfs.writeFile(
 			this.sudoersPath,
 			sudoersContent.length > 0 ? `${sudoersContent}\n` : "",
+			{ mode: 0o600 },
 		);
 		await this.vfs.flushMirror();
 	}
@@ -326,6 +331,10 @@ export class VirtualUserManager {
 		if (!username || username.trim() === "") {
 			throw new Error("invalid username");
 		}
+
+		if (!/^[a-z_][a-z0-9_-]{0,31}$/i.test(username)) {
+			throw new Error("invalid username");
+		}
 	}
 
 	private validatePassword(password: string): void {

package/tests/helpers.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { assertPathAccess } from "../src/SSHMimic/commands/helpers";
+
+describe("assertPathAccess", () => {
+	test("blocks non-root access to auth store", () => {
+		expect(() =>
+			assertPathAccess("alice", "/virtual-env-js/.auth/htpasswd", "cat"),
+		).toThrow("cat: permission denied: /virtual-env-js/.auth/htpasswd");
+	});
+
+	test("allows root access to auth store", () => {
+		expect(() =>
+			assertPathAccess("root", "/virtual-env-js/.auth/htpasswd", "cat"),
+		).not.toThrow();
+	});
+
+	test("allows non-root access outside protected paths", () => {
+		expect(() =>
+			assertPathAccess("alice", "/home/alice/README.txt", "cat"),
+		).not.toThrow();
+	});
+});

package/tests/users.test.ts

@@ -0,0 +1,41 @@
+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";
+
+async function withTempVfs(
+	run: (vfs: VirtualFileSystem) => Promise<void>,
+): Promise<void> {
+	const tempDir = await mkdtemp(join(tmpdir(), "virtual-env-js-test-"));
+	try {
+		const vfs = new VirtualFileSystem(tempDir);
+		await vfs.restoreMirror();
+		await run(vfs);
+	} finally {
+		await rm(tempDir, { recursive: true, force: true });
+	}
+}
+
+describe("VirtualUserManager auto sudo", () => {
+	test("adds new users to sudoers by default", async () => {
+		await withTempVfs(async (vfs) => {
+			const users = new VirtualUserManager(vfs, "root-pass");
+			await users.initialize();
+			await users.addUser("alice", "alice-pass");
+
+			expect(users.isSudoer("alice")).toBe(true);
+		});
+	});
+
+	test("does not auto-add sudoers when disabled", async () => {
+		await withTempVfs(async (vfs) => {
+			const users = new VirtualUserManager(vfs, "root-pass", false);
+			await users.initialize();
+			await users.addUser("bob", "bob-pass");
+
+			expect(users.isSudoer("bob")).toBe(false);
+		});
+	});
+});

package/tsconfig.json

@@ -26,6 +26,6 @@
     "noUnusedParameters": false,
     "noPropertyAccessFromIndexSignature": false,
 
-    "types": ["node"]
+    "types": ["node", "bun"]
   }
 }