typescript-virtual-container 1.6.1 → 1.6.3

package/README.md

@@ -13,7 +13,7 @@
 ## Table of Contents
 
 - [Three ways to run](#three-ways-to-run) · [Get Started](#get-started)
-- [How It Works](#how-it-works) · [Built-in Commands](#built-in-commands-149)
+- [How It Works](#how-it-works) · [Built-in Commands](#built-in-commands-152)
 - [Shell Scripting](#shell-scripting) · [Linux Rootfs](#linux-rootfs--vfs-path-resolution)
 - [Configuration](#configuration) · [Troubleshooting](#troubleshooting)
 - [FAQ](#faq) · [Contributing](#contributing)
@@ -27,8 +27,8 @@
 | Mode | Entry point | Use case |
 |------|-------------|----------|
 | **SSH/SFTP server** | `VirtualSshServer` / `VirtualSftpServer` | Honeypots, remote testing, training environments |
-| **Web shell** | `builds/fortune-nyx-v1.6.1-web.min.js` (ESM) | Embedded terminals, interactive tutorials, browser demos |
-| **Standalone CLI** | `builds/fortune-nyx-v1.6.1-directbash-k6.1.0.mjs` (single file) | Local shell, one-liner demos, no install required |
+| **Web shell** | `builds/fortune-nyx-v1.6.3-web.min.js` (ESM) | Embedded terminals, interactive tutorials, browser demos — run `startxfce4` for a full XFCE desktop |
+| **Standalone CLI** | `builds/fortune-nyx-v1.6.3-directbash-k6.1.0.mjs` (single file) | Local shell, one-liner demos, no install required |
 <!-- /BUILD:mode-table -->
 
 All three modes share the same core: a pure in-memory VFS, a real shell interpreter, a virtual package manager, and a typed programmatic API.
@@ -49,22 +49,22 @@ npm install typescript-virtual-container
 <!-- BUILD:curl-start -->
 #### Interactive local shell — persists VFS in .vfs/ in the current directory
 ```bash
-curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.6.1-directbash-k6.1.0.mjs -o fortune-nyx-v1.6.1-directbash-k6.1.0.mjs && node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.6.3-directbash-k6.1.0.mjs -o fortune-nyx-v1.6.3-directbash-k6.1.0.mjs && node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs
 ```
 
 #### SSH server with built-in SFTP subsystem (scp / sftp on port 2222)
 ```bash
-curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.6.1-ssh.cjs -o fortune-nyx-v1.6.1-ssh.cjs && node fortune-nyx-v1.6.1-ssh.cjs
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.6.3-ssh.cjs -o fortune-nyx-v1.6.3-ssh.cjs && node fortune-nyx-v1.6.3-ssh.cjs
 ```
 
 #### Custom SSH port
 ```bash
-node fortune-nyx-v1.6.1-ssh.cjs --ssh-port=2022
+node fortune-nyx-v1.6.3-ssh.cjs --ssh-port=2022
 ```
 
 #### SSH disabled (handler only, no server started)
 ```bash
-node fortune-nyx-v1.6.1-ssh.cjs --no-ssh
+node fortune-nyx-v1.6.3-ssh.cjs --no-ssh
 ```
 <!-- /BUILD:curl-start -->
 
@@ -72,16 +72,16 @@ node fortune-nyx-v1.6.1-ssh.cjs --no-ssh
 > The standalone builds are intended for quick demos and testing. For production use, it's recommended to install the package and import the relevant classes directly in your codebase for better performance, stability, and security.
 
 <!-- BUILD:selfStandalone-options -->
-**`fortune-nyx-v1.6.1-directbash-k6.1.0.mjs` options:**
+**`fortune-nyx-v1.6.3-directbash-k6.1.0.mjs` options:**
 
 ```bash
-node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs                          # boot as root
-node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs --user alice             # boot as alice (prompts for password if set)
-node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs --user=alice             # same, inline form
-node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs --hostname=my-box        # custom hostname
-node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs --snapshot=/data/.vfs    # custom VFS snapshot path
-node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs --help                   # show all options
-node fortune-nyx-v1.6.1-directbash-k6.1.0.mjs --version                # print version
+node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs                          # boot as root
+node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs --user alice             # boot as alice (prompts for password if set)
+node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs --user=alice             # same, inline form
+node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs --hostname=my-box        # custom hostname
+node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs --snapshot=/data/.vfs    # custom VFS snapshot path
+node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs --help                   # show all options
+node fortune-nyx-v1.6.3-directbash-k6.1.0.mjs --version                # print version
 ```
 <!-- /BUILD:selfStandalone-options -->
 
@@ -108,7 +108,7 @@ Two browser bundles are available:
 <!-- BUILD:web-table -->
 | Bundle | Format | Entry point | Use case |
 |--------|--------|-------------|----------|
-| `builds/fortune-nyx-v1.6.1-web.min.js` | ESM | `createWebShell()` | Embedded terminals, modern bundlers |
+| `builds/fortune-nyx-v1.6.3-web.min.js` | ESM | `createWebShell()` | Embedded terminals, modern bundlers |
 <!-- /BUILD:web-table -->
 
 Both bundles persist the VFS in **IndexedDB** — state survives page reloads.
@@ -120,11 +120,11 @@ bun run build-all       # rebuild everything
 ```
 
 <!-- BUILD:web-options -->
-**`fortune-nyx-v1.6.1-web.min.js`** — lightweight shell with IndexedDB VFS:
+**`fortune-nyx-v1.6.3-web.min.js`** — lightweight shell with IndexedDB VFS:
 
 ```html
 <script type="module">
-  import { createWebShell } from "./builds/fortune-nyx-v1.6.1-web.min.js";
+  import { createWebShell } from "./builds/fortune-nyx-v1.6.3-web.min.js";
 
   const shell = createWebShell("web-vm", {
     vfs: { databaseName: "virtual-env-js", storeName: "vfs" },
@@ -136,11 +136,11 @@ bun run build-all       # rebuild everything
 </script>
 ```
 
-**`fortune-nyx-v1.6.1-web.min.js`** — mirrors the `VirtualShell` programmatic API:
+**`fortune-nyx-v1.6.3-web.min.js`** — mirrors the `VirtualShell` programmatic API:
 
 ```html
 <script type="module">
-  import { createVirtualShellShim } from "./builds/fortune-nyx-v1.6.1-web.min.js";
+  import { createVirtualShellShim } from "./builds/fortune-nyx-v1.6.3-web.min.js";
 
   const shell = createVirtualShellShim("web-vm");
   await shell.ensureInitialized();
@@ -186,13 +186,13 @@ console.log(r.stdout);
 │  per-IP rate limiting / lockout          home-dir confinement            │
 └─────────────────────────┬────────────────────────────────────────────────┘
                           │
-               ┌──────────▼──────────┐
-               │    VirtualShell     │
-               │  script parser      │  ← &&/||/; · if/for/while/case
-               │  command executor   │  ← per-session ShellEnv
-               │  .bashrc loader     │  ← /home/<user>/.bashrc
-               │  session manager    │
-               └──┬──────────────┬───┘
+               ┌──────────▼──────────┐         ┌──────────────────────────┐
+               │    VirtualShell     │────────▶ │    DesktopManager        │
+               │  script parser      │          │  XFCE panel · windows    │
+               │  command executor   │          │  Thunar · Mousepad       │
+               │  .bashrc loader     │          │  Trash · terminal windows│
+               │  session manager    │          │  (browser only)          │
+               └──┬──────────────┬───┘          └──────────────────────────┘
                   │              │
      ┌────────────▼───┐    ┌─────▼───────────────┐
      │VirtualFileSystem│   │ VirtualUserManager   │
@@ -211,7 +211,7 @@ console.log(r.stdout);
 
 **What it is:** a shell emulator and virtual Linux environment for developer workflows.
 
-**What it is not:** a kernel-level security boundary. `curl`/`wget` use the native `fetch()` API — no host binary spawned. `node`/`python3`/`npm` are virtual REPL stubs, not real runtimes. `execvp` is never called. Do not expose to the public internet without additional isolation.
+**What it is not:** a fully isolated sandbox. The shell commands are contained — no host binary is ever spawned, `execvp` is never called, `node`/`python3`/`npm` are virtual stubs. But `curl`/`wget` use the real `fetch()` API (live network access), all instances share the same JS heap as the host application, and CPU/memory are not capped. Do not expose to untrusted input without additional infrastructure-level isolation.
 
 ---
 
@@ -440,9 +440,9 @@ const [r1, r2] = await Promise.all([
 ---
 
 <details>
-<summary><strong>Built-in Commands (149)</strong></summary>
+<summary><strong>Built-in Commands (152)</strong></summary>
 
-Type `help` in the shell for a grouped, colorized listing. Type `help <command>` for detailed usage. Type `man <command>` for full manual pages — all 149 commands are documented.
+Type `help` in the shell for a grouped, colorized listing. Type `help <command>` for detailed usage. Type `man <command>` for full manual pages — all commands are documented.
 
 ### Navigation
 
@@ -598,6 +598,16 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `history [n]` | Command history |
 | `help` | Full list: type `help` in the shell |
 
+### Desktop (browser only)
+
+| Command | Description |
+|---------|-------------|
+| `startxfce4` | Launch the XFCE desktop — blocks the shell until logout |
+| `thunar [path]` | Open the file manager window |
+| `mousepad [file]` | Open the text editor (`gedit` and `xed` are aliases) |
+
+> Desktop commands are no-ops outside the browser environment.
+
 ### Fun
 
 | Command | Description |
@@ -613,7 +623,7 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `pacman` | Pacman game (mock) |
 | `help` | Full list: type `help` in the shell |
 
-**ℹ️ All 149 built-in commands include complete JSDoc documentation** with `@category` and `@params` tags. See [src/commands/](https://github.com/itsrealfortune/typescript-virtual-container/tree/main/src/commands) for source code and inline documentation.
+**ℹ️ All 152 built-in commands include complete JSDoc documentation** with `@category` and `@params` tags. See [src/commands/](https://github.com/itsrealfortune/typescript-virtual-container/tree/main/src/commands) for source code and inline documentation.
 
 Custom commands: `shell.addCommand(name, params, callback)`.
 
@@ -954,27 +964,46 @@ import type {
 
 ## FAQ
 
-**Is this a real container runtime?**
-No — it emulates SSH sessions, users, and filesystem behavior in a virtual runtime. Ideal for testing, simulations, and automation where full OS isolation is not required.
+**What exactly is this project?**
+A self-contained Linux environment implemented entirely in TypeScript. It is not a mock, a stub, or a thin SSH wrapper — it is a full virtual container with its own filesystem (`VirtualFileSystem`), user and permission system (`VirtualUserManager`), shell interpreter, package manager, network layer, process table, and desktop environment. Each `VirtualShell` instance is an independent container that runs anywhere TypeScript runs: Node.js, Bun, or the browser.
+
+**How is this different from a Docker container or a real VM?**
+Docker and VMs enforce kernel-level isolation and run real binaries. This project runs entirely in the JavaScript runtime — no subprocess is ever spawned, no host binary is called. The trade-off is intentional: you get zero-dependency portability (including the browser), a fully inspectable and programmable environment, and no host OS requirements. It is not a security boundary.
+
+**Is the environment fully isolated?**
+No — and this is important to understand before exposing it to untrusted input:
+
+- **Network is real.** `curl` and `wget` use the host's `fetch()` — requests reach the actual internet.
+- **The JS heap is shared.** All `VirtualShell` instances run in the same JavaScript runtime as your application. There is no memory boundary between them or between the shell and the host.
+- **No resource enforcement.** CPU usage and memory consumption are not capped by the container itself — a runaway loop consumes real host resources.
+- **Filesystem isolation holds** in `"memory"` mode (the VFS never touches the host FS) and is limited to one `.vfsb` file in `"fs"` mode.
+
+In short: the shell commands are sandboxed, the runtime is not.
 
 **Can I use this in production?**
-Yes for automation contexts (sandboxed command runners, test harnesses, training environments, honeypots). It is not a security boundary like a real container/VM.
+Yes, for the right use cases: automated test harnesses, interactive tutorials, training environments, honeypots, and browser-based shell experiences. Do not expose it to arbitrary untrusted input without additional isolation at the infrastructure level — it is not a security boundary.
 
 **Does the VFS touch the host filesystem?**
-In `"memory"` mode: no. In `"fs"` mode: one binary file (`vfs-snapshot.vfsb`) inside `snapshotPath` only.
+In `"memory"` mode: never. In `"fs"` mode: exactly one binary file (`vfs-snapshot.vfsb`) inside `snapshotPath`. In the browser: IndexedDB only.
 
-**Can I run multiple isolated shells?**
-Yes. Each `new VirtualShell(...)` is completely independent (separate VFS, users, env state).
+**Can I run multiple isolated environments in parallel?**
+Yes. Each `new VirtualShell(...)` is fully independent — separate VFS, user database, environment state, and session manager. They share no global state.
 
 **Does the shell support `&&`, `||`, `;`, and `&`?**
-Yes — plus pipes, redirections, `if`/`for`/`while`/`case`, function definitions, and background jobs (`cmd &`).
+Yes — plus pipes, redirections, `if`/`for`/`while`/`until`/`case`, function definitions, arrays, brace expansion, glob expansion, heredocs, `set -e`/`set -x`, and background jobs (`cmd &`).
 
 **Can I use this for honeypot deployments?**
-Yes — use `HoneyPot.attach()` to capture all activity, configure `maxAuthAttempts` to throttle scanners, export on shutdown.
+Yes — `HoneyPot.attach()` captures every command, file write, auth attempt, and session event with timestamps. Configure `maxAuthAttempts` to throttle scanners. Export the audit log on shutdown.
 
 **Is SFTP fully supported?**
 Core operations are implemented. Extended attributes and symlinks return `OP_UNSUPPORTED`.
 
+**Does the desktop work outside the browser?**
+No — `startxfce4`, `thunar`, and `mousepad` require a DOM. In Node.js/Bun they return an error immediately. The `DesktopManager` is only instantiated in the web shell example (`examples/app.ts`).
+
+**What does the desktop simulate?**
+A single-user XFCE session: a panel with Applications menu and clock, draggable windows, a file manager (Thunar) with navigation, right-click context menu, rename, and trash, a text editor (Mousepad) with Ctrl+S save, and terminal windows each backed by a real interactive shell session against the same VFS.
+
 ---
 
 ## Contributing
@@ -993,8 +1022,9 @@ Core operations are implemented. Extended attributes and symlinks return `OP_UNS
 - Passwords hashed with scrypt (N=32768, r=8, p=1) with random per-user salt.
 - Root account always exists and cannot be deleted.
 - Per-IP rate limiting prevents automated brute-force on the SSH server.
-- This project does **not** provide kernel-level or process-level isolation.
-- Do **not** expose to the public internet without understanding the risks.
+- This project does **not** provide kernel-level or process-level isolation. All `VirtualShell` instances share the same JS heap as the host application.
+- `curl` and `wget` issue real network requests via `fetch()` — they are not sandboxed.
+- Do **not** expose to untrusted input without additional infrastructure-level isolation.
 
 Vulnerability reports: contact maintainers privately before public disclosure — see `SECURITY.md`.
 
@@ -1018,6 +1048,8 @@ MIT — see [LICENSE](./LICENSE).
 Open:
 
 - [ ] WebSocket-based remote shell client (experimental)
+- [ ] XFCE desktop: resize windows, multi-monitor layout
+- [ ] Thunar: drag-and-drop between folders
 
 <details>
 <summary>Completed</summary>
@@ -1033,9 +1065,10 @@ Open:
 - [x] Snapshot diff tooling — `diffSnapshots`, `formatDiff`, `assertDiff`
 - [x] `node`/`python3`/`npm`/`npx` — package-gated virtual REPL stubs
 <!-- BUILD:changelog -->
-- [x] Web shell bundles (`fortune-nyx-v1.6.1-web.min.js`) — fully browser-native with IndexedDB VFS
-- [x] Self-standalone CLI (`fortune-nyx-v1.6.1-directbash-k6.1.0.mjs`) — single-file interactive shell, per-user history, tab completion
+- [x] Web shell bundles (`fortune-nyx-v1.6.3-web.min.js`) — fully browser-native with IndexedDB VFS
+- [x] Self-standalone CLI (`fortune-nyx-v1.6.3-directbash-k6.1.0.mjs`) — single-file interactive shell, per-user history, tab completion
 <!-- /BUILD:changelog -->
+- [x] XFCE desktop simulation — `startxfce4` launches a full in-browser desktop with draggable windows, XFCE panel (Applications menu, clock, tray), Thunar file manager (navigate, right-click, trash, rename), Mousepad text editor (Ctrl+S, dirty indicator), terminal windows with live shell sessions, Font Awesome icons
 - [x] 127+ `man` pages — all built-in commands documented via `man <cmd>`
 - [x] Background job support — trailing `&` fires commands async; `:(){ :|:& };:` fork-bomb safely blocked by `MAX_CALL_DEPTH` guard; shell function names now accept any non-whitespace identifier (POSIX-compliant)
 - [x] Shared `tokenize.ts` — unified tokenizer for shell parser and runtime (eliminates duplication)