typescript-virtual-container 1.1.0 → 1.1.1-b

package/.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+    "files.exclude": {
+        "**/.git": true,
+        "**/.hg": true,
+        "**/.svn": true,
+        "**/.DS_Store": true,
+        "**/Thumbs.db": true,
+        "**/node_modules": true,
+
+        ".ssh-mimic": true,
+        ".vfs": true,
+        
+        "LICENSE": true,
+        // "*.md": true,
+        "biome.json": true,
+        "tsconfig.tsbuildinfo": true
+    }
+}

package/README.md

@@ -83,7 +83,7 @@ bun add typescript-virtual-container
 ### From source (development)
 
 ```bash
-git clone <repo-url>
+git clone https://github.com/itsrealfortune/typescript-virtual-container/
 cd virtual-env-js
 bun install
 bun format  # Format code per Biome
@@ -745,6 +745,46 @@ Revokes sudo privileges. Cannot remove root.
 await users.removeSudoer("charlie");
 ```
 
+##### `async setQuotaBytes(username: string, maxBytes: number): Promise<void>`
+
+Sets an optional per-user quota (bytes) for writes under `/home/<username>`.
+
+```typescript
+await users.setQuotaBytes("alice", 5 * 1024 * 1024); // 5 MB
+```
+
+##### `async clearQuota(username: string): Promise<void>`
+
+Removes quota limit for a user.
+
+```typescript
+await users.clearQuota("alice");
+```
+
+##### `getQuotaBytes(username: string): number | null`
+
+Returns configured quota in bytes, or `null` if unlimited.
+
+```typescript
+console.log(users.getQuotaBytes("alice"));
+```
+
+##### `getUsageBytes(username: string): number`
+
+Returns current stored usage in bytes under `/home/<username>`.
+
+```typescript
+console.log(users.getUsageBytes("alice"));
+```
+
+##### `assertWriteWithinQuota(username: string, targetPath: string, nextContent: string | Buffer): void`
+
+Validates a write operation against quota rules; throws when projected usage exceeds quota.
+
+```typescript
+users.assertWriteWithinQuota("alice", "/home/alice/data.txt", "payload");
+```
+
 ##### `registerSession(username: string, remoteAddress: string): VirtualActiveSession`
 
 Creates active session (called on SSH auth). Returns session descriptor with UUID, tty, start time.
@@ -1358,9 +1398,9 @@ MIT License. See LICENSE file for details.
 
 ## Roadmap
 
-- [ ] Custom command plugin API
-- [ ] Optional per-user quotas for virtual filesystem usage
-- [ ] Improved shell compatibility for complex piping and redirection
+- [x] Custom command plugin API
+- [x] Optional per-user quotas for virtual filesystem usage
+- [x] Improved shell compatibility for complex piping and redirection
 - [ ] Snapshot diff tooling for test assertions
-- [ ] Structured event hooks (session open/close, file write, sudo challenge)
+- [x] Structured event hooks (session open/close, file write, sudo challenge)
 - [ ] WebSocket-based remote shell client (experimental)

package/modules/shellInteractive.ts

@@ -0,0 +1,45 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import type { ShellStream } from "../src/types/streams";
+import { shellQuote, type TerminalSize, withTerminalSize } from "./shellRuntime";
+
+function spawnScriptProcess(
+	command: string,
+	terminalSize: TerminalSize,
+	stream: ShellStream,
+): ChildProcessWithoutNullStreams {
+	const formatted = withTerminalSize(command, terminalSize);
+	const proc = spawn("script", ["-qfec", formatted, "/dev/null"], {
+		stdio: ["pipe", "pipe", "pipe"],
+		env: {
+			...process.env,
+			// biome-ignore lint/style/useNamingConvention: env variable should be uppercase
+			TERM: process.env.TERM ?? "xterm-256color",
+		},
+	});
+
+	proc.stdout.on("data", (data: Buffer) => {
+		stream.write(data.toString("utf8"));
+	});
+
+	proc.stderr.on("data", (data: Buffer) => {
+		stream.write(data.toString("utf8"));
+	});
+
+	return proc;
+}
+
+export function spawnNanoEditorProcess(
+	tempPath: string,
+	terminalSize: TerminalSize,
+	stream: ShellStream,
+): ChildProcessWithoutNullStreams {
+	return spawnScriptProcess(`nano -- ${shellQuote(tempPath)}`, terminalSize, stream);
+}
+
+export function spawnHtopProcess(
+	pidList: string,
+	terminalSize: TerminalSize,
+	stream: ShellStream,
+): ChildProcessWithoutNullStreams {
+	return spawnScriptProcess(`htop -p ${shellQuote(pidList)}`, terminalSize, stream);
+}

package/modules/shellRuntime.ts

@@ -0,0 +1,76 @@
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+
+export interface TerminalSize {
+	cols: number;
+	rows: number;
+}
+
+export function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export function toTtyLines(text: string): string {
+	return text
+		.replace(/\r\n/g, "\n")
+		.replace(/\r/g, "\n")
+		.replace(/\n/g, "\r\n");
+}
+
+export function withTerminalSize(
+	command: string,
+	terminalSize: TerminalSize,
+): 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}`;
+}
+
+export 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));
+}
+
+export 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 [];
+	}
+}
+
+export async function getVisibleHtopPidList(
+	rootPid = process.pid,
+): Promise<string | null> {
+	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(",");
+}

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.1.0",
+  "version": "1.1.1b",
   "license": "MIT",
   "keywords": [
     "ssh",

package/src/{SSHMimic/client.ts → SSHClient/index.ts}

@@ -1,6 +1,6 @@
+import { runCommand } from "../commands";
 import type { CommandResult } from "../types/commands";
 import type { VirtualShell } from "../VirtualShell";
-import { runCommand } from "../VirtualShell/commands";
 
 /**
  * Programmatic client for executing shell commands against a virtual shell.
@@ -154,7 +154,7 @@ export class SshClient {
 		}
 
 		try {
-			vfs.writeFile(path, content);
+			this.shell.writeFileAsUser(this.username, path, content);
 			return { stdout: `File '${path}' written`, exitCode: 0 };
 		} catch (error) {
 			return {

package/src/SSHMimic/exec.ts

@@ -1,6 +1,6 @@
+import { runCommand } from "../commands";
 import type { ExecStream } from "../types/streams";
 import type { VirtualShell } from "../VirtualShell";
-import { runCommand } from "../VirtualShell/commands";
 
 function toTtyLines(text: string): string {
 	return text

package/src/SSHMimic/executor.ts

@@ -1,8 +1,8 @@
+import { runCommand as runSingleCommand } from "../commands";
+import { resolvePath } from "../commands/helpers";
 import type { CommandMode, CommandResult } from "../types/commands";
 import type { Pipeline, PipelineCommand } from "../types/pipeline";
 import type { VirtualShell } from "../VirtualShell";
-import { runCommand as runSingleCommand } from "../VirtualShell/commands";
-import { resolvePath } from "../VirtualShell/commands/helpers";
 
 /**
  * Execute a parsed pipeline, chaining commands and handling redirections.
@@ -90,12 +90,12 @@ async function executeSingleCommandWithRedirections(
 			if (cmd.appendOutput) {
 				try {
 					const existing = shell.vfs.readFile(outputPath);
-					shell.vfs.writeFile(outputPath, existing + output);
+					shell.writeFileAsUser(authUser, outputPath, existing + output);
 				} catch {
-					shell.vfs.writeFile(outputPath, output);
+					shell.writeFileAsUser(authUser, outputPath, output);
 				}
 			} else {
-				shell.vfs.writeFile(outputPath, output);
+				shell.writeFileAsUser(authUser, outputPath, output);
 			}
 			return { ...result, stdout: "" };
 		} catch {
@@ -165,12 +165,12 @@ async function executePipelineChain(
 				if (cmd.appendOutput) {
 					try {
 						const existing = shell.vfs.readFile(outputPath);
-						shell.vfs.writeFile(outputPath, existing + output);
+						shell.writeFileAsUser(authUser, outputPath, existing + output);
 					} catch {
-						shell.vfs.writeFile(outputPath, output);
+						shell.writeFileAsUser(authUser, outputPath, output);
 					}
 				} else {
-					shell.vfs.writeFile(outputPath, output);
+					shell.writeFileAsUser(authUser, outputPath, output);
 				}
 				currentOutput = "";
 			} catch {

package/src/VirtualFileSystem/index.ts

@@ -24,6 +24,18 @@ class VirtualFileSystem {
 	private readonly archivePath: string;
 	private dirty = false;
 
+	private computeNodeUsageBytes(node: InternalNode): number {
+		if (node.type === "file") {
+			return node.content.length;
+		}
+
+		let total = 0;
+		for (const child of node.children.values()) {
+			total += this.computeNodeUsageBytes(child);
+		}
+		return total;
+	}
+
 	/**
 	 * Creates a virtual filesystem instance.
 	 *
@@ -287,6 +299,20 @@ class VirtualFileSystem {
 		return renderTree(node, rootLabel);
 	}
 
+	/**
+	 * Computes total stored file bytes under a path.
+	 *
+	 * File usage is based on in-memory stored bytes, including compressed
+	 * payload size when files are marked as compressed.
+	 *
+	 * @param targetPath File or directory path to measure, defaults to root.
+	 * @returns Total byte usage for file content under target path.
+	 */
+	public getUsageBytes(targetPath: string = "/"): number {
+		const node = getNode(this.root, targetPath);
+		return this.computeNodeUsageBytes(node);
+	}
+
 	/**
 	 * Compresses file content with gzip and flags node as compressed.
 	 *

package/src/VirtualShell/index.ts

@@ -1,9 +1,9 @@
 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 VirtualFileSystem from "../VirtualFileSystem";
 import { VirtualUserManager } from "../VirtualUserManager";
-import { createCustomCommand, registerCommand, runCommand } from "./commands";
 import { startShell } from "./shell";
 
 export interface ShellProperties {
@@ -170,6 +170,22 @@ class VirtualShell {
 	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,12 +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 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 { ShellStream } from "../types/streams";
 import type VirtualFileSystem from "../VirtualFileSystem";
-import { getCommandNames, runCommand } from "./commands";
 
 interface NanoSession {
 	kind: "nano" | "htop";
@@ -24,22 +34,6 @@ 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,
@@ -68,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`);
@@ -236,7 +176,11 @@ export function startShell(
 		if (activeSession.kind === "nano") {
 			try {
 				const updatedContent = await readFile(activeSession.tempPath, "utf8");
-				shell.vfs.writeFile(activeSession.targetPath, updatedContent);
+				shell.writeFileAsUser(
+					authUser,
+					activeSession.targetPath,
+					updatedContent,
+				);
 				await shell.vfs.flushMirror();
 			} catch {
 				// If temp file does not exist, nano exited without writing.
@@ -261,23 +205,7 @@ export function startShell(
 			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`);
@@ -303,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`);

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 {

package/src/VirtualUserManager/index.ts

@@ -1,4 +1,5 @@
 import { randomBytes, randomUUID, scryptSync } from "node:crypto";
+import * as path from "node:path";
 import type VirtualFileSystem from "../VirtualFileSystem";
 
 /** Persisted virtual user credential record. */
@@ -33,9 +34,11 @@ export interface VirtualActiveSession {
 export class VirtualUserManager {
 	private readonly usersPath = "/virtual-env-js/.auth/htpasswd";
 	private readonly sudoersPath = "/virtual-env-js/.auth/sudoers";
+	private readonly quotasPath = "/virtual-env-js/.auth/quotas";
 	private readonly authDirPath = "/virtual-env-js/.auth";
 	private readonly users = new Map<string, VirtualUserRecord>();
 	private readonly sudoers = new Set<string>();
+	private readonly quotas = new Map<string, number>();
 	private readonly activeSessions = new Map<string, VirtualActiveSession>();
 	private nextTty = 0;
 
@@ -58,6 +61,7 @@ export class VirtualUserManager {
 	public async initialize(): Promise<void> {
 		this.loadFromVfs();
 		this.loadSudoersFromVfs();
+		this.loadQuotasFromVfs();
 
 		this.users.set("root", this.createRecord("root", this.defaultRootPassword));
 
@@ -66,6 +70,113 @@ export class VirtualUserManager {
 		await this.persist();
 	}
 
+	/**
+	 * Sets max allowed bytes under /home/<username>.
+	 *
+	 * @param username Target username.
+	 * @param maxBytes Quota ceiling in bytes.
+	 */
+	public async setQuotaBytes(
+		username: string,
+		maxBytes: number,
+	): Promise<void> {
+		this.validateUsername(username);
+		if (!this.users.has(username)) {
+			throw new Error(`quota: user '${username}' does not exist`);
+		}
+
+		if (!Number.isFinite(maxBytes) || maxBytes < 0) {
+			throw new Error("quota: maxBytes must be a non-negative number");
+		}
+
+		this.quotas.set(username, Math.floor(maxBytes));
+		await this.persist();
+	}
+
+	/**
+	 * Removes quota for a user.
+	 *
+	 * @param username Target username.
+	 */
+	public async clearQuota(username: string): Promise<void> {
+		this.validateUsername(username);
+		this.quotas.delete(username);
+		await this.persist();
+	}
+
+	/**
+	 * Gets configured quota in bytes for a user.
+	 *
+	 * @param username Target username.
+	 * @returns Quota in bytes, or null when unlimited.
+	 */
+	public getQuotaBytes(username: string): number | null {
+		return this.quotas.get(username) ?? null;
+	}
+
+	/**
+	 * Computes current usage under /home/<username>.
+	 *
+	 * @param username Target username.
+	 * @returns Current usage in bytes.
+	 */
+	public getUsageBytes(username: string): number {
+		const homePath = `/home/${username}`;
+		if (!this.vfs.exists(homePath)) {
+			return 0;
+		}
+
+		return this.vfs.getUsageBytes(homePath);
+	}
+
+	/**
+	 * Validates that writing file content would not exceed user quota.
+	 *
+	 * Quotas are enforced only for writes inside /home/<username>.
+	 *
+	 * @param username Authenticated user.
+	 * @param targetPath Target file path.
+	 * @param nextContent New file content.
+	 */
+	public assertWriteWithinQuota(
+		username: string,
+		targetPath: string,
+		nextContent: string | Buffer,
+	): void {
+		const quota = this.quotas.get(username);
+		if (quota === undefined) {
+			return;
+		}
+
+		const normalizedPath = normalizeVfsPath(targetPath);
+		const homePath = normalizeVfsPath(`/home/${username}`);
+		const inUserHome =
+			normalizedPath === homePath || normalizedPath.startsWith(`${homePath}/`);
+		if (!inUserHome) {
+			return;
+		}
+
+		const currentUsage = this.getUsageBytes(username);
+		let existingSize = 0;
+		if (this.vfs.exists(normalizedPath)) {
+			const existing = this.vfs.stat(normalizedPath);
+			if (existing.type === "file") {
+				existingSize = existing.size;
+			}
+		}
+
+		const incomingSize = Buffer.isBuffer(nextContent)
+			? nextContent.length
+			: Buffer.byteLength(nextContent, "utf8");
+		const projectedUsage = currentUsage - existingSize + incomingSize;
+
+		if (projectedUsage > quota) {
+			throw new Error(
+				`quota exceeded for '${username}': ${projectedUsage}/${quota} bytes`,
+			);
+		}
+	}
+
 	/**
 	 * Verifies plaintext password against stored record.
 	 *
@@ -291,6 +402,30 @@ export class VirtualUserManager {
 		}
 	}
 
+	private loadQuotasFromVfs(): void {
+		this.quotas.clear();
+
+		if (!this.vfs.exists(this.quotasPath)) {
+			return;
+		}
+
+		const raw = this.vfs.readFile(this.quotasPath);
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (trimmed.length === 0) {
+				continue;
+			}
+
+			const [username, value] = trimmed.split(":");
+			const bytes = Number.parseInt(value ?? "", 10);
+			if (!username || !Number.isFinite(bytes) || bytes < 0) {
+				continue;
+			}
+
+			this.quotas.set(username, bytes);
+		}
+	}
+
 	private async persist(): Promise<void> {
 		if (!this.vfs.exists(this.authDirPath)) {
 			this.vfs.mkdir(this.authDirPath, 0o700);
@@ -314,6 +449,15 @@ export class VirtualUserManager {
 			sudoersContent.length > 0 ? `${sudoersContent}\n` : "",
 			{ mode: 0o600 },
 		);
+		const quotasContent = Array.from(this.quotas.entries())
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([username, maxBytes]) => `${username}:${maxBytes}`)
+			.join("\n");
+		this.vfs.writeFile(
+			this.quotasPath,
+			quotasContent.length > 0 ? `${quotasContent}\n` : "",
+			{ mode: 0o600 },
+		);
 		await this.vfs.flushMirror();
 	}
 
@@ -346,3 +490,8 @@ export class VirtualUserManager {
 		}
 	}
 }
+
+function normalizeVfsPath(targetPath: string): string {
+	const normalized = path.posix.normalize(targetPath);
+	return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}

package/src/{VirtualShell/commands → commands}/adduser.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const adduserCommand: ShellModule = {
 	name: "adduser",

package/src/{VirtualShell/commands → commands}/cat.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 import { assertPathAccess, resolveReadablePath } from "./helpers";
 

package/src/{VirtualShell/commands → commands}/cd.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
 export const cdCommand: ShellModule = {

package/src/{VirtualShell/commands → commands}/clear.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const clearCommand: ShellModule = {
 	name: "clear",

package/src/{VirtualShell/commands → commands}/curl.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
 import {
 	assertPathAccess,
@@ -39,7 +39,7 @@ export const curlCommand: ShellModule = {
 		if (outputPath) {
 			const target = resolvePath(cwd, outputPath);
 			assertPathAccess(authUser, target, "curl");
-			shell.vfs.writeFile(target, result.stdout);
+			shell.writeFileAsUser(authUser, target, result.stdout);
 			return {
 				stderr: result.stderr
 					? normalizeTerminalOutput(result.stderr)

package/src/{VirtualShell/commands → commands}/deluser.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const deluserCommand: ShellModule = {
 	name: "deluser",

package/src/{VirtualShell/commands → commands}/echo.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
 import { getAllEnvVars } from "./set";
 

package/src/{VirtualShell/commands → commands}/env.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getAllEnvVars } from "./set";
 
 export const envCommand: ShellModule = {

package/src/{VirtualShell/commands → commands}/exit.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const exitCommand: ShellModule = {
 	name: "exit",

package/src/{VirtualShell/commands → commands}/export.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 import { getEnvVar, setEnvVar } from "./set";
 

package/src/{VirtualShell/commands → commands}/grep.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 

package/src/{VirtualShell/commands → commands}/help.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export function createHelpCommand(getNames: () => string[]): ShellModule {
 	return {

package/src/{VirtualShell/commands → commands}/helpers.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import * as path from "node:path";
-import type VirtualFileSystem from "../../VirtualFileSystem";
+import type VirtualFileSystem from "../VirtualFileSystem";
 
 const PROTECTED_PREFIXES = ["/virtual-env-js/.auth"] as const;
 

package/src/{VirtualShell/commands → commands}/hostname.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const hostnameCommand: ShellModule = {
 	name: "hostname",

package/src/{VirtualShell/commands → commands}/htop.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const htopCommand: ShellModule = {
 	name: "htop",

package/src/{VirtualShell/commands → commands}/index.ts

@@ -1,10 +1,10 @@
-import type { VirtualShell } from "..";
+import type { VirtualShell } from "../VirtualShell";
 import type {
 	CommandContext,
 	CommandMode,
 	CommandResult,
 	ShellModule,
-} from "../../types/commands";
+} from "../types/commands";
 import { adduserCommand } from "./adduser";
 import { catCommand } from "./cat";
 import { cdCommand } from "./cd";
@@ -142,6 +142,9 @@ export function getCommandNames(): string[] {
 }
 
 export function resolveModule(name: string): ShellModule | undefined {
+	if (!cachedCommandNames) {
+		buildCache();
+	}
 	return commandRegistry.get(name.toLowerCase());
 }
 
@@ -213,8 +216,8 @@ export async function runCommand(
 	}
 
 	if (trimmed.includes("|") || trimmed.includes(">") || trimmed.includes("<")) {
-		const { parseShellPipeline } = await import("../shellParser");
-		const { executePipeline } = await import("../../SSHMimic/executor");
+		const { parseShellPipeline } = await import("../VirtualShell/shellParser");
+		const { executePipeline } = await import("../SSHMimic/executor");
 
 		const pipeline = parseShellPipeline(trimmed);
 		if (!pipeline.isValid) {

package/src/{VirtualShell/commands → commands}/ls.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg, ifFlag } from "./command-helpers";
 import { assertPathAccess, joinListWithType, resolvePath } from "./helpers";
 

package/src/{VirtualShell/commands → commands}/mkdir.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 

package/src/{VirtualShell/commands → commands}/nano.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
 export const nanoCommand: ShellModule = {

package/src/{VirtualShell/commands → commands}/neofetch.ts

@@ -1,5 +1,5 @@
-import { buildNeofetchOutput } from "../../../modules/neofetch";
-import type { ShellModule } from "../../types/commands";
+import { buildNeofetchOutput } from "../../modules/neofetch";
+import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 import { getAllEnvVars } from "./set";
 

package/src/{VirtualShell/commands → commands}/pwd.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const pwdCommand: ShellModule = {
 	name: "pwd",

package/src/{VirtualShell/commands → commands}/rm.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg, ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 

package/src/{VirtualShell/commands → commands}/set.ts

@@ -1,5 +1,5 @@
 /** biome-ignore-all lint/style/useNamingConvention: env variables */
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 
 // Simple in-memory environment variables store

package/src/{VirtualShell/commands → commands}/sh.ts

@@ -1,4 +1,4 @@
-import type { CommandContext, ShellModule } from "../../types/commands";
+import type { CommandContext, ShellModule } from "../types/commands";
 import { getArg, getFlag } from "./command-helpers";
 import { runCommand } from "./index";
 

package/src/{VirtualShell/commands → commands}/su.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 
 export const suCommand: ShellModule = {

package/src/{VirtualShell/commands → commands}/sudo.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
 import { runCommand } from "./index";
 

package/src/{VirtualShell/commands → commands}/touch.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
 export const touchCommand: ShellModule = {
@@ -13,7 +13,7 @@ export const touchCommand: ShellModule = {
 			const target = resolvePath(cwd, file);
 			assertPathAccess(authUser, target, "touch");
 			if (!shell.vfs.exists(target)) {
-				shell.vfs.writeFile(target, "");
+				shell.writeFileAsUser(authUser, target, "");
 			}
 		}
 		return { exitCode: 0 };

package/src/{VirtualShell/commands → commands}/tree.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 

package/src/{VirtualShell/commands → commands}/unset.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 import { setEnvVar } from "./set";
 
 export const unsetCommand: ShellModule = {

package/src/{VirtualShell/commands → commands}/wget.ts

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 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 type { ShellModule } from "../types/commands";
 import { ifFlag, parseArgs } from "./command-helpers";
 import {
 	assertPathAccess,
@@ -131,7 +131,7 @@ export const wgetCommand: ShellModule = {
 			const content = await readFile(tempFile, "utf8");
 			const target = resolvePath(cwd, outputPath || stripUrlFilename(url));
 			assertPathAccess(authUser, target, "wget");
-			shell.vfs.writeFile(target, content);
+			shell.writeFileAsUser(authUser, target, content);
 
 			return {
 				stdout: `saved ${target}`,

package/src/{VirtualShell/commands → commands}/who.ts

@@ -1,5 +1,5 @@
-import { formatLoginDate } from "../../SSHMimic/loginFormat";
-import type { ShellModule } from "../../types/commands";
+import { formatLoginDate } from "../SSHMimic/loginFormat";
+import type { ShellModule } from "../types/commands";
 
 export const whoCommand: ShellModule = {
 	name: "who",

package/src/{VirtualShell/commands → commands}/whoami.ts

@@ -1,4 +1,4 @@
-import type { ShellModule } from "../../types/commands";
+import type { ShellModule } from "../types/commands";
 
 export const whoamiCommand: ShellModule = {
 	name: "whoami",

package/src/index.ts

@@ -1,4 +1,4 @@
-import { SshClient } from "./SSHMimic/client";
+import { SshClient } from "./SSHClient";
 import { SshMimic } from "./SSHMimic/index";
 import VirtualFileSystem from "./VirtualFileSystem";
 import { VirtualShell } from "./VirtualShell";
@@ -41,4 +41,4 @@ export {
 	getArg,
 	getFlag,
 	ifFlag,
-} from "./VirtualShell/commands/command-helpers";
+} from "./commands/command-helpers";

package/tests/command-helpers.test.ts

@@ -3,7 +3,7 @@ import {
     getArg,
     getFlag,
     ifFlag,
-} from "../src/VirtualShell/commands/command-helpers";
+} from "../src/commands/command-helpers";
 
 describe("command-helpers", () => {
 	test("ifFlag detects plain and inline flag forms", () => {

package/tests/helpers.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { assertPathAccess } from "../src/VirtualShell/commands/helpers";
+import { assertPathAccess } from "../src/commands/helpers";
 
 describe("assertPathAccess", () => {
 	test("blocks non-root access to auth store", () => {

package/tests/users.test.ts

@@ -39,3 +39,63 @@ describe("VirtualUserManager auto sudo", () => {
 		});
 	});
 });
+
+describe("VirtualUserManager quotas", () => {
+	test("enforces quota for writes inside user home", async () => {
+		await withTempVfs(async (vfs) => {
+			const users = new VirtualUserManager(vfs, "root-pass");
+			await users.initialize();
+			await users.addUser("alice", "alice-pass");
+			const startingUsage = users.getUsageBytes("alice");
+			await users.setQuotaBytes("alice", startingUsage + 5);
+
+			expect(() => {
+				users.assertWriteWithinQuota("alice", "/home/alice/note.txt", "hello");
+			}).not.toThrow();
+
+			vfs.writeFile("/home/alice/note.txt", "hello");
+
+			expect(() => {
+				users.assertWriteWithinQuota(
+					"alice",
+					"/home/alice/note.txt",
+					"this exceeds the configured quota",
+				);
+			}).toThrow("quota exceeded for 'alice'");
+		});
+	});
+
+	test("does not enforce home quota outside user home", async () => {
+		await withTempVfs(async (vfs) => {
+			const users = new VirtualUserManager(vfs, "root-pass");
+			await users.initialize();
+			await users.addUser("bob", "bob-pass");
+			await users.setQuotaBytes("bob", 1);
+
+			expect(() => {
+				users.assertWriteWithinQuota("bob", "/tmp/shared.txt", "large-content");
+			}).not.toThrow();
+		});
+	});
+
+	test("clearQuota removes enforced limit", async () => {
+		await withTempVfs(async (vfs) => {
+			const users = new VirtualUserManager(vfs, "root-pass");
+			await users.initialize();
+			await users.addUser("charlie", "charlie-pass");
+			await users.setQuotaBytes("charlie", 2);
+
+			expect(users.getQuotaBytes("charlie")).toBe(2);
+			await users.clearQuota("charlie");
+			expect(users.getQuotaBytes("charlie")).toBeNull();
+
+			expect(() => {
+				users.assertWriteWithinQuota(
+					"charlie",
+					"/home/charlie/file.txt",
+					"long-content",
+				);
+			}).not.toThrow();
+		});
+	});
+});