typescript-virtual-container 1.0.1 → 1.0.4

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,18 +61,42 @@ 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
 
+  tests:
+    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 tests
+        run: bun test
+
   test-battery:
     needs:
       - typecheck
       - lint
+      - tests
     runs-on: ubuntu-latest
-
     steps:
       - name: Test battery passed
         run: echo "Typecheck, lint and tests succeeded."

package/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on Keep a Changelog.
 
 ## [Unreleased]
 
+## [1.0.4] - 2026-04-15
+
+### Added
+
+- Shell pipeline parser and executor with support for:
+  - Pipes (`|`)
+  - Input redirection (`<`)
+  - Output redirection (`>`)
+  - Append redirection (`>>`)
+- New built-in commands:
+  - `echo`
+  - `grep`
+  - `set`
+  - `env`
+  - `export`
+  - `unset`
+  - `sh` (with `bash` alias)
+- Command stdin support in runtime context so commands can consume piped input.
+
+### Changed
+
+- Argument parsing now respects quoted strings, including for commands like `sh -c "echo hi"`.
+- `echo` now expands environment variables (`$VAR`) and can read from stdin when no explicit text argument is provided.
+- `grep` now supports stdin input (e.g. `ls | grep ".txt"`) in addition to file operands.
+
+### Fixed
+
+- Relative file paths in redirections are now resolved from current working directory during pipeline execution.
+  - Example fixed behavior: `echo hi > cat.txt` writes to `./cat.txt` in current virtual directory.
+- Pipeline chaining now correctly passes command stdout as stdin to next command.
+
+## [1.0.2] - 2026-04-14
+
 ### Added
 
 - Governance and community files:
@@ -14,6 +47,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

@@ -39,7 +39,7 @@
 - **Virtual Filesystem**: In-memory filesystem with optional compression, persistence to disk via tar.gz snapshots, and programmatic access.
 - **User Management**: Create, authenticate, and manage virtual users with strict password hashing (scrypt) and sudo-like privilege elevation.
 - **Programmatic Shell API**: Execute shell commands and query filesystem state directly from TypeScript without SSH overhead.
-- **Built-in Commands**: `ls`, `cd`, `pwd`, `cat`, `mkdir`, `touch`, `rm`, `tree`, `whoami`, `hostname`, `who`, `sudo`, `su`, `adduser`, `deluser`, `nano` (text editor), `curl`, `wget`, and more.
+- **Built-in Commands**: `ls`, `cd`, `pwd`, `cat`, `mkdir`, `touch`, `rm`, `tree`, `whoami`, `hostname`, `who`, `sudo`, `su`, `adduser`, `deluser`, `nano` (text editor), `curl`, `wget`, and a growing set of additional commands. Not everything is implemented yet, and shell compatibility is still being expanded.
 - **Full TypeScript Support**: Complete JSDoc coverage, exported types, and first-class async/await for all operations.
 
 ## Why This Package
@@ -140,7 +140,7 @@ ssh.stop();
 
 ## Architecture Overview
 
-### Core Components
+<!-- ### Core Components
 
 ```
 ┌─────────────────────────────────────────────┐
@@ -158,7 +158,7 @@ ssh.stop();
 │              Backed by disk
 │              .vfs/mirror.tar.gz
 └──────────────────────────────────┘
-```
+``` -->
 
 ### Execution Modes
 
@@ -1006,7 +1006,7 @@ ssh.stop();
 
 ## Built-in Commands
 
-The following commands are available in both SSH shell mode and via `SshClient.exec()`:
+The following commands are available in both SSH shell mode and via `SshClient.exec()`. This list is intentionally incomplete: some commands, flags, and edge cases are still missing or only partially compatible with real shells, and that will continue to be worked on.
 
 | Command | Purpose | Notes |
 |---------|---------|-------|
@@ -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
 ```
 
@@ -1123,7 +1125,7 @@ No. It emulates SSH sessions, users, and filesystem behavior in memory. It is id
 
 ### Can I use this in production?
 
-You can use it in production-like automation contexts (sandboxed command runners, test harnesses, training environments), but it is not a security boundary like a real container/VM.
+You can use it in production-like automation contexts (sandboxed command runners, test harnesses, training environments), but it is not a security boundary like a real container/VM. And at the moment, all commands are not implemented with full fidelity, so it may not be suitable for all production use cases.
 
 ### Does data persist between restarts?
 
@@ -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.
@@ -1258,26 +1262,4 @@ MIT License. See LICENSE file for details.
 - [ ] Improved shell compatibility for complex piping and redirection
 - [ ] Snapshot diff tooling for test assertions
 - [ ] Structured event hooks (session open/close, file write, sudo challenge)
-
----
-
-## Changelog
-
-### v1.0.0 (2026-04-14)
-
-**Initial Release**
-
-- ✨ SSH server with password auth
-- ✨ Virtual filesystem with persistence
-- ✨ User management & sudoers
-- ✨ Programmatic `SshClient` API
-- ✨ 20+ built-in shell commands
-- ✨ Full TypeScript support & JSDoc coverage
-- ✨ tar.gz snapshot persistence
-- ✨ Session & TTY management
-- ✨ Interactive `nano` editor
-- ✨ Sudo/su privilege escalation
-
----
-
-**Made with ❤️ for testing, automation, and interactive TypeScript development.**
+- [ ] WebSocket-based remote shell client (experimental)

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.4",
   "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/echo.ts

@@ -0,0 +1,26 @@
+import type { ShellModule } from "../../types/commands";
+import { getAllEnvVars } from "./set";
+
+function expandEnvVars(input: string, env: Record<string, string>): string {
+	return input.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name: string) => {
+		return env[name] ?? "";
+	});
+}
+
+export const echoCommand: ShellModule = {
+	name: "echo",
+	params: ["[options] [text...]"],
+	run: ({ args, authUser, stdin }) => {
+		const newline = !args.includes("-n");
+		const filteredArgs = args.filter((arg) => arg !== "-n");
+		const env = getAllEnvVars(authUser);
+		const rawText =
+			filteredArgs.length > 0 ? filteredArgs.join(" ") : (stdin ?? "");
+		const text = expandEnvVars(rawText, env);
+
+		return {
+			stdout: newline ? text : text.trimEnd(),
+			exitCode: 0,
+		};
+	},
+};

package/src/SSHMimic/commands/env.ts

@@ -0,0 +1,22 @@
+import type { ShellModule } from "../../types/commands";
+import { getAllEnvVars } from "./set";
+
+export const envCommand: ShellModule = {
+	name: "env",
+	params: ["[VAR=value...] [command]"],
+	run: ({ authUser }) => {
+		// For now, just display all environment variables
+		// In a full implementation, this would also handle running commands with modified env
+
+		const allVars = getAllEnvVars(authUser);
+		const envVarsOutput = Object.entries(allVars)
+			.map(([key, value]) => `${key}=${value}`)
+			.sort()
+			.join("\n");
+
+		return {
+			stdout: envVarsOutput,
+			exitCode: 0,
+		};
+	},
+};

package/src/SSHMimic/commands/export.ts

@@ -0,0 +1,32 @@
+import type { ShellModule } from "../../types/commands";
+import { getEnvVar, setEnvVar } from "./set";
+
+export const exportCommand: ShellModule = {
+	name: "export",
+	params: ["[VAR=value]"],
+	run: ({ args }) => {
+		// export VAR=value or export VAR (to make it available to child processes)
+		if (args.length === 0) {
+			// List all exported variables
+			return {
+				stdout: "# export command - sets variables for child processes",
+				exitCode: 0,
+			};
+		}
+
+		// Parse VAR=value format
+		for (const arg of args) {
+			if (arg.includes("=")) {
+				const [varName, varValue] = arg.split("=", 2);
+				if (varName && varValue !== undefined) {
+					setEnvVar(varName, varValue);
+				}
+			} else {
+				// export VAR_NAME makes it available but we just set it
+				setEnvVar(arg, getEnvVar(arg) || "");
+			}
+		}
+
+		return { exitCode: 0 };
+	},
+};

package/src/SSHMimic/commands/grep.ts

@@ -0,0 +1,81 @@
+import type { ShellModule } from "../../types/commands";
+import { assertPathAccess, resolvePath } from "./helpers";
+
+export const grepCommand: ShellModule = {
+	name: "grep",
+	params: ["[-i] [-v] <pattern> [file...]"],
+	run: ({ authUser, vfs, cwd, args, stdin }) => {
+		const caseInsensitive = args.includes("-i");
+		const invertMatch = args.includes("-v");
+		const filteredArgs = args.filter((arg) => arg !== "-i" && arg !== "-v");
+
+		if (filteredArgs.length === 0) {
+			return { stderr: "grep: no pattern specified", exitCode: 1 };
+		}
+
+		const pattern = filteredArgs[0];
+		const files = filteredArgs.slice(1);
+
+		let regex: RegExp;
+		try {
+			const flags = caseInsensitive ? "gmi" : "gm";
+			regex = new RegExp(pattern as string, flags);
+		} catch {
+			return { stderr: `grep: invalid regex: ${pattern}`, exitCode: 1 };
+		}
+
+		const results: string[] = [];
+
+		// If no files specified, read from stdin (pipe/input redirection).
+		if (files.length === 0) {
+			if (!stdin) {
+				return { stdout: "", exitCode: 1 };
+			}
+
+			const lines = stdin.split("\n");
+			for (const line of lines) {
+				regex.lastIndex = 0;
+				const matches = regex.test(line);
+				const shouldInclude = invertMatch ? !matches : matches;
+
+				if (shouldInclude) {
+					results.push(line);
+				}
+			}
+
+			return {
+				stdout: results.length > 0 ? results.join("\n") : "",
+				exitCode: results.length > 0 ? 0 : 1,
+			};
+		}
+
+		for (const file of files) {
+			const target = resolvePath(cwd, file);
+			try {
+				assertPathAccess(authUser, target, "grep");
+				const content = vfs.readFile(target);
+				const lines = content.split("\n");
+
+				for (const line of lines) {
+					regex.lastIndex = 0;
+					const matches = regex.test(line);
+					const shouldInclude = invertMatch ? !matches : matches;
+
+					if (shouldInclude) {
+						results.push(line);
+					}
+				}
+			} catch {
+				return {
+					stderr: `grep: ${file}: No such file or directory`,
+					exitCode: 1,
+				};
+			}
+		}
+
+		return {
+			stdout: results.length > 0 ? results.join("\n") : "",
+			exitCode: results.length > 0 ? 0 : 1,
+		};
+	},
+};

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[];