typescript-virtual-container 1.1.4 → 1.1.6

package/README.md

@@ -1,6 +1,6 @@
 # `typescript-virtual-container`
 
-> In-memory SSH server with a virtual filesystem and typed programmatic API for testing, automation, and interactive shell scripting in TypeScript/JavaScript.
+> In-memory SSH/SFTP server with a virtual filesystem and typed programmatic API for testing, automation, and interactive shell scripting in TypeScript/JavaScript.
 
 [![npm version](https://badge.fury.io/js/typescript-virtual-container.svg)](https://www.npmjs.com/package/typescript-virtual-container)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -34,12 +34,14 @@
 
 ## Overview
 
-`typescript-virtual-container` is a lightweight, fully-typed SSH server written in TypeScript that provides:
+`typescript-virtual-container` is a lightweight, fully-typed SSH/SFTP runtime written in TypeScript that provides:
 
-- **SSH Protocol Support**: Serve SSH connections on any port with password authentication and support for both shell and exec modes.
-- **Virtual Filesystem**: In-memory filesystem with optional compression, persistence to disk via tar.gz snapshots, and programmatic access.
+- **SSH + SFTP Protocol Support**: Serve SSH shell/exec sessions and SFTP file operations on configurable ports.
+- **Virtual Filesystem**: In-memory-like developer workflow backed by a mirror directory under `.vfs/mirror`, with optional gzip compression 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.
+- **Event-Driven Architecture**: All core classes extend `EventEmitter` for lifecycle and operation tracking. Listen to auth events, filesystem operations, session lifecycle, and command execution for auditing and integration.
+- **Security Auditing**: Built-in `HoneyPot` utility for comprehensive activity logging, event tracking, statistics collection, and anomaly detection across all components.
 - **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.
 
@@ -126,6 +128,31 @@ process.on("SIGTERM", () => {
 });
 ```
 
+### Running SSH + SFTP with Shared State
+
+```typescript
+import { VirtualSftpServer, VirtualShell, VirtualSshServer } from "typescript-virtual-container";
+
+const shell = new VirtualShell("my-container");
+
+const ssh = new VirtualSshServer({
+	port: 2222,
+	hostname: "my-container",
+	shell,
+});
+
+const sftp = new VirtualSftpServer({
+	port: 2223,
+	hostname: "my-container",
+	shell,
+});
+
+await ssh.start();
+await sftp.start();
+
+console.log("SSH on :2222, SFTP on :2223");
+```
+
 ### Using the Programmatic Client API
 
 ```typescript
@@ -174,7 +201,7 @@ ssh.stop();
 └──────────────┘  └──────────┘  └──────────┘
 			 ▲
 │              Backed by disk
-│              .vfs/mirror.tar.gz
+│              .vfs/mirror
 └──────────────────────────────────┘
 ``` -->
 
@@ -182,13 +209,14 @@ ssh.stop();
 
 1. **SSH Shell Mode**: Interactive terminal session over SSH with readline, prompt, TTY resizing.
 2. **SSH Exec Mode**: Non-interactive command execution (e.g., `ssh user@host "ls -la"`).
-3. **Programmatic Mode** (new): Direct TypeScript API via `SshClient`, no SSH protocol overhead.
+3. **SFTP Mode**: Remote file operations (`readdir`, `stat`, `readFile`, `writeFile`, `mkdir`, `rename`, etc.) with home-directory confinement.
+4. **Programmatic Mode**: Direct TypeScript API via `SshClient`, no SSH protocol overhead.
 
 ### Persistence
 
-- Filesystem state saved as gzip-compressed tar archive at `.vfs/mirror.tar.gz`
+- Filesystem state is stored under `.vfs/mirror` inside the configured `basePath`
 - Users/passwords stored in virtual paths `/virtual-env-js/.auth/htpasswd` and `/virtual-env-js/.auth/sudoers`
-- Manual flush via `VirtualFileSystem.flushMirror()` or automatic on command completion
+- `restoreMirror()` and `flushMirror()` are lightweight compatibility hooks for initialization boundaries
 
 ---
 
@@ -248,6 +276,31 @@ Cleanly closes server and all active connections.
 ssh.stop();
 ```
 
+#### Events
+
+`SshMimic` extends `EventEmitter` and emits the following events:
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `start` | `{ port: number }` | Server started and listening |
+| `stop` | — | Server stopped |
+| `auth:success` | `{ username: string; remoteAddress: string }` | User authenticated |
+| `auth:failure` | `{ username: string; remoteAddress: string }` | Auth failed for user |
+| `client:connect` | — | New SSH client connected |
+| `client:disconnect` | `{ user: string }` | SSH client disconnected |
+
+**Example:**
+
+```typescript
+ssh.on("auth:success", ({ username, remoteAddress }) => {
+	console.log(`[SSH] User ${username} authenticated from ${remoteAddress}`);
+});
+
+ssh.on("auth:failure", ({ username }) => {
+	console.log(`[SSH] Auth failed for user ${username}`);
+});
+```
+
 ##### `getVfs(): VirtualFileSystem | null`
 
 Returns the virtual filesystem instance. Null if server not started.
@@ -278,6 +331,75 @@ console.log(`Server name: ${ssh.getHostname()}`);
 
 ---
 
+### SftpMimic (SFTP Server)
+
+SFTP server class, exported as `VirtualSftpServer` in the package entrypoint. It can run with a shared `VirtualShell` (recommended) or with explicit `vfs + users` dependencies.
+
+#### Constructor
+
+```typescript
+new SftpMimic(options: {
+	port: number;
+	hostname?: string;
+	shell?: VirtualShell;
+	vfs?: VirtualFileSystem;
+	users?: VirtualUserManager;
+})
+```
+
+- If `shell` is provided, SFTP reuses the same users/filesystem state as SSH.
+- If `shell` is omitted, pass `vfs` and `users` explicitly.
+
+#### Methods
+
+##### `async start(): Promise<number>`
+
+Starts the SFTP server and returns the bound port (useful with `port: 0`).
+
+```typescript
+const sftp = new SftpMimic({ port: 0, shell });
+const boundPort = await sftp.start();
+console.log(`SFTP listening on ${boundPort}`);
+```
+
+##### `stop(): void`
+
+Stops the SFTP server.
+
+```typescript
+sftp.stop();
+```
+
+#### Behavior Notes
+
+- Supports `password` and `keyboard-interactive` authentication.
+- Resolves relative SFTP paths from `/home/<user>`.
+- Confines all SFTP operations to `/home/<user>` and blocks traversal attempts outside the user home.
+- Unsupported operations (`READLINK`, `SYMLINK`) return `OP_UNSUPPORTED`.
+
+#### Events
+
+`SftpMimic` extends `EventEmitter` and emits the following events:
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `start` | `{ port: number }` | SFTP server started and listening |
+| `stop` | — | SFTP server stopped |
+| `auth:success` | `{ username: string; remoteAddress: string }` | User authenticated for SFTP |
+| `auth:failure` | `{ username: string; remoteAddress: string }` | SFTP auth failed for user |
+| `client:connect` | — | New SFTP client connected |
+| `client:disconnect` | `{ user: string }` | SFTP client disconnected |
+
+**Example:**
+
+```typescript
+sftp.on("auth:success", ({ username }) => {
+	console.log(`[SFTP] User ${username} authenticated`);
+});
+```
+
+---
+
 ### SshClient (Programmatic Shell API)
 
 Execute shell commands against a `VirtualShell` instance without SSH overhead. Maintains connection state (current working directory) across calls.
@@ -475,7 +597,7 @@ new VirtualShell(
 
 - **hostname**: Hostname injected into command context and prompt behavior.
 - **properties**: Optional shell metadata. Defaults to `defaultShellProperties`.
-- **basePath**: Optional directory used to resolve `.vfs/mirror.tar.gz` (defaults to `.`).
+- **basePath**: Optional directory used to resolve `.vfs/mirror` and auth storage (defaults to `.`).
 
 **Example:**
 
@@ -519,11 +641,33 @@ shell.startInteractiveSession(
 );
 ```
 
+#### Events
+
+`VirtualShell` extends `EventEmitter` and emits the following events:
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `initialized` | — | Shell initialization complete |
+| `command` | `{ command: string; user: string; cwd: string }` | Command executed |
+| `session:start` | `{ user: string; sessionId: string \| null; remoteAddress: string }` | Interactive session started |
+
+**Example:**
+
+```typescript
+shell.on("command", ({ command, user, cwd }) => {
+	console.log(`[SHELL] User ${user} executed: ${command} (cwd: ${cwd})`);
+});
+
+shell.on("session:start", ({ user, remoteAddress }) => {
+	console.log(`[SHELL] Session started for ${user} from ${remoteAddress}`);
+});
+```
+
 ---
 
 ### VirtualFileSystem
 
-In-memory filesystem with optional gzip compression and tar.gz persistence.
+Virtual filesystem abstraction backed by a mirror directory on disk, with optional gzip compression per file.
 
 #### Constructor
 
@@ -531,18 +675,41 @@ In-memory filesystem with optional gzip compression and tar.gz persistence.
 new VirtualFileSystem(baseDir?: string)
 ```
 
-- **baseDir**: Directory to store `.vfs/mirror.tar.gz` snapshot (default: current working directory)
+- **baseDir**: Directory used for the `.vfs/mirror` root (default: current working directory)
 
 ```typescript
 const vfs = new VirtualFileSystem("./container-data");
-// Snapshot at ./container-data/.vfs/mirror.tar.gz
+// Mirror root at ./container-data/.vfs/mirror
 ```
 
 #### Methods
 
+#### Events
+
+`VirtualFileSystem` extends `EventEmitter` and emits the following events:
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `file:read` | `{ path: string; size: number }` | File read |
+| `file:write` | `{ path: string; size: number }` | File written |
+| `dir:create` | `{ path: string; mode: number }` | Directory created |
+| `mirror:flush` | — | Mirror persisted to disk |
+
+**Example:**
+
+```typescript
+vfs.on("file:write", ({ path, size }) => {
+	console.log(`[VFS] File written: ${path} (${size} bytes)`);
+});
+
+vfs.on("dir:create", ({ path, mode }) => {
+	console.log(`[VFS] Directory created: ${path} (mode: ${mode.toString(8)})`);
+});
+```
+
 ##### `async restoreMirror(): Promise<void>`
 
-Loads filesystem state from disk snapshot. If missing, creates fresh filesystem.
+Ensures mirror directory structure exists and is ready for operations.
 
 ```typescript
 await vfs.restoreMirror();
@@ -550,7 +717,7 @@ await vfs.restoreMirror();
 
 ##### `async flushMirror(): Promise<void>`
 
-Persists current filesystem state to disk. No-op if nothing changed.
+Compatibility hook to finalize mirror boundary operations.
 
 ```typescript
 // After file modifications...
@@ -662,6 +829,18 @@ Decompresses file content (inverse of `compressFile`).
 vfs.decompressFile("/var/log/app.log");
 ```
 
+**Example:**
+
+```typescript
+vfs.on("file:write", ({ path, size }) => {
+	console.log(`[VFS] File written: ${path} (${size} bytes)`);
+});
+
+vfs.on("dir:create", ({ path, mode }) => {
+	console.log(`[VFS] Directory created: ${path} (mode: ${mode.toString(8)})`);
+});
+```
+
 ---
 
 ### VirtualUserManager
@@ -723,6 +902,7 @@ await users.deleteUser("bob");
 
 Checks sudo access.
 
+
 ```typescript
 if (users.isSudoer("alice")) {
 	console.log("alice can use sudo");
@@ -821,6 +1001,154 @@ sessions.forEach(s => {
 });
 ```
 
+#### Events
+
+`VirtualUserManager` extends `EventEmitter` and emits the following events:
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `initialized` | — | User manager initialization complete, root user ready |
+| `user:add` | `{ username: string }` | New user created |
+| `user:delete` | `{ username: string }` | User deleted |
+| `session:register` | `{ sessionId: string; username: string; remoteAddress: string }` | Session registered (user logged in) |
+| `session:unregister` | `{ sessionId: string; username: string }` | Session unregistered (user logged out) |
+
+**Example:**
+
+```typescript
+users.on("user:add", ({ username }) => {
+	console.log(`[USERS] User created: ${username}`);
+});
+
+users.on("session:register", ({ sessionId, username, remoteAddress }) => {
+	console.log(`[USERS] Session ${sessionId}: ${username} from ${remoteAddress}`);
+});
+
+users.on("session:unregister", ({ sessionId, username }) => {
+	console.log(`[USERS] Session ${sessionId} (${username}) closed`);
+});
+```
+
+---
+
+### HoneyPot (Auditing & Event Tracking)
+
+Comprehensive security auditing and event tracking utility. Attaches to all core components (VirtualShell, VirtualFileSystem, VirtualUserManager, SshMimic, SftpMimic) to log activity, track statistics, and detect anomalies.
+
+#### Constructor
+
+```typescript
+new HoneyPot(maxLogSize?: number)
+```
+
+- **maxLogSize**: Maximum audit log entries to retain (default: 10000)
+
+```typescript
+const honeypot = new HoneyPot(5000);  // Keep last 5000 audit entries
+```
+
+#### Methods
+
+##### `attach(shell: VirtualShell, vfs: VirtualFileSystem, users: VirtualUserManager, ssh?: SshMimic, sftp?: SftpMimic): void`
+
+Attaches honeypot listeners to all provided event emitters. This wires up all audit tracking across the entire virtual environment.
+
+```typescript
+honeypot.attach(shell, vfs, users, ssh, sftp);
+// All components now emit events to honeypot
+```
+
+##### `getAuditLog(type?: string, source?: string): AuditLogEntry[]`
+
+Returns audit log entries with optional filtering by event type or source component.
+
+```typescript
+// All entries
+const allLogs = honeypot.getAuditLog();
+
+// Only auth events
+const authLogs = honeypot.getAuditLog("auth:failure");
+
+// Only SshMimic events
+const sshLogs = honeypot.getAuditLog(undefined, "SshMimic");
+
+// Combine filters
+const sshAuthLogs = honeypot.getAuditLog("auth:success", "SshMimic");
+```
+
+##### `getStats(): Readonly<HoneyPotStats>`
+
+Returns current activity statistics snapshot.
+
+```typescript
+const stats = honeypot.getStats();
+console.log(`Auth attempts: ${stats.authAttempts}`);
+console.log(`Auth successes: ${stats.authSuccesses}`);
+console.log(`Auth failures: ${stats.authFailures}`);
+console.log(`Commands executed: ${stats.commands}`);
+console.log(`File writes: ${stats.fileWrites}`);
+console.log(`File reads: ${stats.fileReads}`);
+console.log(`Sessions started: ${stats.sessionStarts}`);
+console.log(`Sessions ended: ${stats.sessionEnds}`);
+console.log(`Users created: ${stats.userCreated}`);
+console.log(`Users deleted: ${stats.userDeleted}`);
+console.log(`Client connects: ${stats.clientConnects}`);
+console.log(`Client disconnects: ${stats.clientDisconnects}`);
+```
+
+##### `getRecent(limit?: number): AuditLogEntry[]`
+
+Returns most recent audit entries in reverse chronological order.
+
+```typescript
+const last50 = honeypot.getRecent(50);
+last50.forEach(entry => {
+	console.log(`${entry.timestamp} | ${entry.source} | ${entry.type}`);
+	console.log(`Details:`, entry.details);
+});
+```
+
+##### `detectAnomalies(): Array<{ type: string; severity: "low" | "medium" | "high"; message: string }>`
+
+Analyzes activity patterns and detects potential security issues.
+
+```typescript
+const anomalies = honeypot.detectAnomalies();
+anomalies.forEach(anomaly => {
+	console.log(`[${anomaly.severity.toUpperCase()}] ${anomaly.type}`);
+	console.log(`  ${anomaly.message}`);
+});
+```
+
+Detects:
+- High authentication failure rates
+- Excessive authentication failures
+- Unusual command execution volume
+- Unusual file write volume
+
+##### `reset(): void`
+
+Clears audit log and resets all statistics counters.
+
+```typescript
+honeypot.reset();  // Fresh start
+```
+
+#### Audit Log Entry Structure
+
+```typescript
+interface AuditLogEntry {
+	timestamp: string;              // ISO-8601 timestamp
+	type: string;                   // Event type (e.g., "auth:success", "file:write")
+	source: string;                 // Event source component
+	details: Record<string, unknown>; // Event-specific data
+}
+```
+
+#### Example Usage
+
+See [Example 8: Security Auditing with HoneyPot](#example-8-security-auditing-with-honeypot) in Usage Examples.
+
 ---
 
 ### Key Types
@@ -1022,7 +1350,7 @@ vfs1.writeFile("/data/report.txt", "Baseline data");
 await vfs1.flushMirror();
 ssh1.stop();
 
-console.log("State saved to ./container/.vfs/mirror.tar.gz");
+console.log("State available under ./container/.vfs/mirror");
 
 // Later: Reload and continue
 const shell2 = new VirtualShell("typescript-vm", undefined, "./container");
@@ -1156,6 +1484,133 @@ ssh.stop();
 
 ---
 
+### Example 8: Security Auditing with HoneyPot
+
+Track all system activity, detect anomalies, and maintain security audit logs:
+
+```typescript
+import {
+	VirtualSshServer,
+	VirtualShell,
+	SshClient,
+	HoneyPot,
+} from "typescript-virtual-container";
+
+const shell = new VirtualShell("typescript-vm");
+const ssh = new VirtualSshServer({ port: 2222, shell });
+await ssh.start();
+
+const users = ssh.getUsers()!;
+const vfs = ssh.getVfs()!;
+
+// Initialize honeypot with 5000-entry log limit
+const honeypot = new HoneyPot(5000);
+honeypot.attach(shell, vfs, users, ssh);
+
+// Create users
+await users.addUser("alice", "alice123");
+await users.addUser("bob", "bob456");
+
+// Simulate activity
+const alice = new SshClient(shell, "alice");
+await alice.mkdir("/home/alice/projects", true);
+await alice.writeFile("/home/alice/projects/app.txt", "My application");
+await alice.ls("/home/alice/projects");
+
+const bob = new SshClient(shell, "bob");
+// Bob tries invalid operations
+await bob.readFile("/etc/shadow");  // Will fail
+await bob.writeFile("/etc/passwd", "hacked");  // Will fail
+
+// Collect stats
+const stats = honeypot.getStats();
+console.log("\n=== Activity Summary ===");
+console.log(`Auth attempts: ${stats.authAttempts}`);
+console.log(`Auth successes: ${stats.authSuccesses}`);
+console.log(`Auth failures: ${stats.authFailures}`);
+console.log(`Commands executed: ${stats.commands}`);
+console.log(`File writes: ${stats.fileWrites}`);
+console.log(`File reads: ${stats.fileReads}`);
+console.log(`Sessions active: ${stats.sessionStarts}`);
+console.log(`Users created: ${stats.userCreated}`);
+
+// Get recent events
+console.log("\n=== Last 5 Events ===");
+honeypot.getRecent(5).forEach((entry) => {
+	console.log(`[${entry.timestamp}] ${entry.source} -> ${entry.type}`);
+	console.log(`  Details: ${JSON.stringify(entry.details, null, 2)}`);
+});
+
+// Detect anomalies
+console.log("\n=== Security Analysis ===");
+const anomalies = honeypot.detectAnomalies();
+if (anomalies.length > 0) {
+	anomalies.forEach((anomaly) => {
+		console.log(
+			`[${anomaly.severity.toUpperCase()}] ${anomaly.type}: ${anomaly.message}`,
+		);
+	});
+} else {
+	console.log("No anomalies detected");
+}
+
+// Filter audit log by event type
+console.log("\n=== Auth Failures ===");
+const authFailures = honeypot.getAuditLog("auth:failure");
+authFailures.forEach((entry) => {
+	console.log(
+		`  ${entry.details.username} from ${entry.details.remoteAddress}`,
+	);
+});
+
+// Filter by source component
+console.log("\n=== All SSH Events ===");
+const sshEvents = honeypot.getAuditLog(undefined, "SshMimic");
+console.log(`  Total SSH events: ${sshEvents.length}`);
+
+// Export full audit log (for external storage/analysis)
+const fullAuditLog = honeypot.getAuditLog();
+console.log(`\nTotal audit entries: ${fullAuditLog.length}`);
+
+// Optional: Reset for next test phase
+// honeypot.reset();
+
+ssh.stop();
+```
+
+**Output example:**
+
+```
+[AUDIT] 2026-04-16T10:30:45.123Z | SshMimic | start { port: 2222 }
+[AUDIT] 2026-04-16T10:30:46.234Z | VirtualUserManager | user:add { username: 'alice' }
+[AUDIT] 2026-04-16T10:30:47.345Z | VirtualUserManager | user:add { username: 'bob' }
+[AUDIT] 2026-04-16T10:30:48.456Z | VirtualShell | command { command: 'mkdir /home/alice/projects', user: 'alice', cwd: '/home/alice' }
+[AUDIT] 2026-04-16T10:30:49.567Z | VirtualFileSystem | dir:create { path: '/home/alice/projects', mode: 16877 }
+[AUDIT] 2026-04-16T10:30:50.678Z | VirtualShell | command { command: 'writeFile /home/alice/projects/app.txt', user: 'alice', cwd: '/home/alice' }
+
+=== Activity Summary ===
+Auth attempts: 2
+Auth successes: 2
+Auth failures: 0
+Commands executed: 8
+File writes: 1
+File reads: 2
+Sessions active: 2
+Users created: 2
+
+=== Last 5 Events ===
+[2026-04-16T10:30:50.678Z] VirtualShell -> command
+  Details: { command: 'ls /home/alice/projects', user: 'alice', cwd: '/home/alice/projects' }
+
+=== Security Analysis ===
+No anomalies detected
+
+=== All SSH Events ===
+  Total SSH events: 4
+```
+
+---
+
 ## Built-in Commands
 
 The following commands are currently registered and available in both SSH shell mode and via `SshClient.exec()`. Some flags and edge-case behavior are still being expanded for shell compatibility.
@@ -1293,7 +1748,7 @@ You can use it in production-like automation contexts (sandboxed command runners
 
 ### Does data persist between restarts?
 
-Yes, if you call `flushMirror()` and use a stable `basePath`. State is restored from `.vfs/mirror.tar.gz`.
+Yes, when using a stable `basePath`. Files are stored under `.vfs/mirror`.
 
 ### Is networking fully implemented for curl/wget?