typescript-virtual-container 1.2.7 → 1.2.9

package/dist/VirtualShell/index.d.ts

@@ -3,22 +3,66 @@ import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
 import VirtualFileSystem, { type VfsOptions } from "../VirtualFileSystem";
 import { VirtualUserManager } from "../VirtualUserManager";
+import { VirtualPackageManager } from "../VirtualPackageManager";
+/**
+ * Virtual machine identity strings surfaced by system-info commands
+ * (`uname`, `neofetch`, `lsb_release`, `/proc/version`, `/etc/os-release`).
+ *
+ * Pass this as the second argument to `new VirtualShell()` to customise the
+ * distro name, kernel version, and CPU architecture reported inside the shell.
+ *
+ * @example
+ * ```ts
+ * const shell = new VirtualShell("my-vm", {
+ *   kernel: "6.1.0+custom-amd64",
+ *   os:     "Acme GNU/Linux x64",
+ *   arch:   "x86_64",
+ * });
+ * ```
+ */
 export interface ShellProperties {
+    /** Kernel version string (e.g. `"1.0.0+itsrealfortune+1-amd64"`). */
     kernel: string;
+    /** Full OS description (e.g. `"Fortune GNU/Linux x64"`). */
     os: string;
+    /** CPU architecture label (e.g. `"x86_64"`, `"aarch64"`). */
     arch: string;
 }
 /**
- * Coordinates the virtual filesystem, user manager, and command runtime.
+ * Coordinates the virtual filesystem, user manager, package manager, and
+ * command runtime for a single isolated shell environment.
  *
- * Instances are used both by the SSH server facade and by the programmatic
- * client API.
+ * Each instance owns its own VFS tree, user database, package registry, and
+ * session state — multiple instances are fully independent.
+ *
+ * Instances are consumed both by the SSH/SFTP server facades and directly via
+ * the programmatic `SshClient` API.
+ *
+ * @example
+ * ```ts
+ * const shell = new VirtualShell("my-vm");
+ * await shell.ensureInitialized();
+ * const client = new SshClient(shell, "root");
+ * const result = await client.exec("uname -a");
+ * ```
+ *
+ * @fires VirtualShell#initialized  Emitted once the VFS and users are ready.
+ * @fires VirtualShell#command       Emitted after every command execution.
+ * @fires VirtualShell#session:start Emitted when an interactive session opens.
  */
 declare class VirtualShell extends EventEmitter {
+    /** Backing virtual filesystem — use for direct path operations. */
     vfs: VirtualFileSystem;
+    /** Virtual user database — use for auth, quotas, and session tracking. */
     users: VirtualUserManager;
+    /** APT/dpkg package manager backed by the built-in package registry. */
+    packageManager: VirtualPackageManager;
+    /** Hostname shown in the shell prompt and SSH ident string. */
     hostname: string;
+    /** Distro identity strings surfaced by `uname`, `neofetch`, etc. */
     properties: ShellProperties;
+    /** Unix ms timestamp of shell creation — used by `uptime` and `/proc/uptime`. */
+    startTime: number;
     private initialized;
     /**
      * Creates a new virtual shell instance.
@@ -42,25 +86,56 @@ declare class VirtualShell extends EventEmitter {
      */
     addCommand(name: string, params: string[], callback: (ctx: CommandContext) => CommandResult | Promise<CommandResult>): void;
     /**
-     * Executes a command line string in the context of this shell instance.
+     * Executes a raw command line string programmatically.
+     *
+     * Supports the full shell operator set (`&&`, `||`, `;`, `|`, `>`, `<`,
+     * `$(cmd)`) and alias expansion. The result is emitted via the
+     * `"command"` event but not returned — use `SshClient.exec()` for a
+     * result-returning wrapper.
      *
-     * @param rawInput
-     * @param authUser
-     * @param cwd
+     * @param rawInput Unparsed command line (e.g. `"ls -la /tmp"`).
+     * @param authUser Username to run the command as.
+     * @param cwd      Current working directory for path resolution.
      */
     executeCommand(rawInput: string, authUser: string, cwd: string): void;
     /**
-     * Starts an interactive session with the shell.
+     * Attaches an interactive PTY session to this shell instance.
      *
-     * @param stream The stream for the interactive session.
-     * @param authUser The authenticated user for the session.
-     * @param sessionId The ID of the session.
-     * @param remoteAddress The address of the remote client.
+     * Called internally by `SshMimic` when a client opens a shell channel.
+     * The session reads from `stream` (user keystrokes) and writes back ANSI
+     * output. History, `.bashrc` sourcing, and Ctrl+W/Ctrl+U line editing are
+     * handled automatically.
+     *
+     * @param stream        Bidirectional SSH channel stream.
+     * @param authUser      Authenticated username bound to this session.
+     * @param sessionId     Stable session UUID (used for `who` output), or `null`.
+     * @param remoteAddress IP or hostname of the connecting client.
+     * @param terminalSize  Initial terminal dimensions in columns and rows.
      */
     startInteractiveSession(stream: ShellStream, authUser: string, sessionId: string | null, remoteAddress: string, terminalSize: {
         cols: number;
         rows: number;
     }): void;
+    /**
+     * Refreshes the `/proc` virtual filesystem with current system state.
+     *
+     * Updates `/proc/uptime`, `/proc/meminfo`, `/proc/cpuinfo`,
+     * `/proc/version`, and `/proc/loadavg` from live host data.
+     *
+     * Called automatically during `bootstrapLinuxRootfs`. Call again before
+     * reading `/proc` files for up-to-date values (e.g. before `neofetch`
+     * or `free` in long-running processes).
+     */
+    refreshProcFs(): void;
+    /**
+     * Syncs `/etc/passwd`, `/etc/group`, and `/etc/shadow` from the current
+     * `VirtualUserManager` state.
+     *
+     * Called automatically during `bootstrapLinuxRootfs`. Call again after
+     * `users.addUser()`, `users.deleteUser()`, or `users.addSudoer()` to keep
+     * the classic Unix credential files in sync with the user manager.
+     */
+    syncPasswd(): void;
     /**
      * Returns virtual filesystem instance after server started.
      *

package/dist/VirtualShell/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualShell/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,iBAAiB,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACb;AAmBD;;;;;GAKG;AACH,cAAM,YAAa,SAAQ,YAAY;IACtC,GAAG,EAAE,iBAAiB,CAAC;IACvB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,CAAC,WAAW,CAAgB;IAEnC;;;;;;OAMG;gBAEF,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,eAAe,EAC5B,UAAU,CAAC,EAAE,UAAU;IAqBxB;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/C;;;;;;OAMG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GACvE,IAAI;IASP;;;;;;OAMG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAMrE;;;;;;;OAOG;IAEH,uBAAuB,CACtB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC1C,IAAI;IAgBP;;;;OAIG;IACI,MAAM,IAAI,iBAAiB,GAAG,IAAI;IAIzC;;;;OAIG;IACI,QAAQ,IAAI,kBAAkB,GAAG,IAAI;IAI5C;;;;OAIG;IACI,WAAW,IAAI,MAAM;IAI5B;;;;;;OAMG;IACI,eAAe,CACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,GACtB,IAAI;CAKP;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualShell/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,iBAAiB,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAIjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACb;AAmBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAM,YAAa,SAAQ,YAAY;IACtC,mEAAmE;IACnE,GAAG,EAAE,iBAAiB,CAAC;IACvB,0EAA0E;IAC1E,KAAK,EAAE,kBAAkB,CAAC;IAC1B,wEAAwE;IACxE,cAAc,EAAE,qBAAqB,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,UAAU,EAAE,eAAe,CAAC;IAC5B,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,WAAW,CAAgB;IAEnC;;;;;;OAMG;gBAEF,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,eAAe,EAC5B,UAAU,CAAC,EAAE,UAAU;IA+BxB;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/C;;;;;;OAMG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GACvE,IAAI;IASP;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAMrE;;;;;;;;;;;;;OAaG;IACH,uBAAuB,CACtB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC1C,IAAI;IAgBP;;;;;;;;;OASG;IACI,aAAa,IAAI,IAAI;IAI5B;;;;;;;OAOG;IACI,UAAU,IAAI,IAAI;IAIzB;;;;OAIG;IACI,MAAM,IAAI,iBAAiB,GAAG,IAAI;IAIzC;;;;OAIG;IACI,QAAQ,IAAI,kBAAkB,GAAG,IAAI;IAI5C;;;;OAIG;IACI,WAAW,IAAI,MAAM;IAI5B;;;;;;OAMG;IACI,eAAe,CACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,GACtB,IAAI;CAKP;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/VirtualShell/index.js

@@ -3,6 +3,8 @@ import { createCustomCommand, registerCommand, runCommand } from "../commands";
 import { createPerfLogger } from "../utils/perfLogger";
 import VirtualFileSystem, {} from "../VirtualFileSystem";
 import { VirtualUserManager } from "../VirtualUserManager";
+import { VirtualPackageManager } from "../VirtualPackageManager";
+import { bootstrapLinuxRootfs, refreshProc, syncEtcPasswd } from "../modules/linuxRootfs";
 import { startShell } from "./shell";
 const defaultShellProperties = {
     kernel: "1.0.0+itsrealfortune+1-amd64",
@@ -18,16 +20,40 @@ function resolveAutoSudoForNewUsers() {
     return !["0", "false", "no", "off"].includes(configured.toLowerCase());
 }
 /**
- * Coordinates the virtual filesystem, user manager, and command runtime.
+ * Coordinates the virtual filesystem, user manager, package manager, and
+ * command runtime for a single isolated shell environment.
  *
- * Instances are used both by the SSH server facade and by the programmatic
- * client API.
+ * Each instance owns its own VFS tree, user database, package registry, and
+ * session state — multiple instances are fully independent.
+ *
+ * Instances are consumed both by the SSH/SFTP server facades and directly via
+ * the programmatic `SshClient` API.
+ *
+ * @example
+ * ```ts
+ * const shell = new VirtualShell("my-vm");
+ * await shell.ensureInitialized();
+ * const client = new SshClient(shell, "root");
+ * const result = await client.exec("uname -a");
+ * ```
+ *
+ * @fires VirtualShell#initialized  Emitted once the VFS and users are ready.
+ * @fires VirtualShell#command       Emitted after every command execution.
+ * @fires VirtualShell#session:start Emitted when an interactive session opens.
  */
 class VirtualShell extends EventEmitter {
+    /** Backing virtual filesystem — use for direct path operations. */
     vfs;
+    /** Virtual user database — use for auth, quotas, and session tracking. */
     users;
+    /** APT/dpkg package manager backed by the built-in package registry. */
+    packageManager;
+    /** Hostname shown in the shell prompt and SSH ident string. */
     hostname;
+    /** Distro identity strings surfaced by `uname`, `neofetch`, etc. */
     properties;
+    /** Unix ms timestamp of shell creation — used by `uptime` and `/proc/uptime`. */
+    startTime;
     initialized;
     /**
      * Creates a new virtual shell instance.
@@ -41,15 +67,25 @@ class VirtualShell extends EventEmitter {
         perf.mark("constructor");
         this.hostname = hostname;
         this.properties = properties || defaultShellProperties;
+        this.startTime = Date.now();
         this.vfs = new VirtualFileSystem(vfsOptions ?? {});
         this.users = new VirtualUserManager(this.vfs, resolveAutoSudoForNewUsers());
+        this.packageManager = new VirtualPackageManager(this.vfs, this.users);
         // Store references to avoid TypeScript "used before assigned" errors
         const vfs = this.vfs;
         const users = this.users;
+        const pm = this.packageManager;
+        const shellProps = this.properties;
+        const shellHostname = this.hostname;
+        const startTime = this.startTime;
         // Initialize both VFS mirror and users, ensuring all is ready before auth
         this.initialized = (async () => {
             await vfs.restoreMirror();
             await users.initialize();
+            // Bootstrap Linux rootfs (idempotent)
+            bootstrapLinuxRootfs(vfs, users, shellHostname, shellProps, startTime);
+            // Load installed packages from dpkg status
+            pm.load();
             this.emit("initialized");
         })();
     }
@@ -76,11 +112,16 @@ class VirtualShell extends EventEmitter {
         registerCommand(createCustomCommand(normalized, params, callback));
     }
     /**
-     * Executes a command line string in the context of this shell instance.
+     * Executes a raw command line string programmatically.
+     *
+     * Supports the full shell operator set (`&&`, `||`, `;`, `|`, `>`, `<`,
+     * `$(cmd)`) and alias expansion. The result is emitted via the
+     * `"command"` event but not returned — use `SshClient.exec()` for a
+     * result-returning wrapper.
      *
-     * @param rawInput
-     * @param authUser
-     * @param cwd
+     * @param rawInput Unparsed command line (e.g. `"ls -la /tmp"`).
+     * @param authUser Username to run the command as.
+     * @param cwd      Current working directory for path resolution.
      */
     executeCommand(rawInput, authUser, cwd) {
         perf.mark("executeCommand");
@@ -88,12 +129,18 @@ class VirtualShell extends EventEmitter {
         this.emit("command", { command: rawInput, user: authUser, cwd });
     }
     /**
-     * Starts an interactive session with the shell.
+     * Attaches an interactive PTY session to this shell instance.
      *
-     * @param stream The stream for the interactive session.
-     * @param authUser The authenticated user for the session.
-     * @param sessionId The ID of the session.
-     * @param remoteAddress The address of the remote client.
+     * Called internally by `SshMimic` when a client opens a shell channel.
+     * The session reads from `stream` (user keystrokes) and writes back ANSI
+     * output. History, `.bashrc` sourcing, and Ctrl+W/Ctrl+U line editing are
+     * handled automatically.
+     *
+     * @param stream        Bidirectional SSH channel stream.
+     * @param authUser      Authenticated username bound to this session.
+     * @param sessionId     Stable session UUID (used for `who` output), or `null`.
+     * @param remoteAddress IP or hostname of the connecting client.
+     * @param terminalSize  Initial terminal dimensions in columns and rows.
      */
     startInteractiveSession(stream, authUser, sessionId, remoteAddress, terminalSize) {
         perf.mark("startInteractiveSession");
@@ -101,6 +148,30 @@ class VirtualShell extends EventEmitter {
         this.emit("session:start", { user: authUser, sessionId, remoteAddress });
         startShell(this.properties, stream, authUser, this.hostname, sessionId, remoteAddress, terminalSize, this);
     }
+    /**
+     * Refreshes the `/proc` virtual filesystem with current system state.
+     *
+     * Updates `/proc/uptime`, `/proc/meminfo`, `/proc/cpuinfo`,
+     * `/proc/version`, and `/proc/loadavg` from live host data.
+     *
+     * Called automatically during `bootstrapLinuxRootfs`. Call again before
+     * reading `/proc` files for up-to-date values (e.g. before `neofetch`
+     * or `free` in long-running processes).
+     */
+    refreshProcFs() {
+        refreshProc(this.vfs, this.properties, this.hostname, this.startTime);
+    }
+    /**
+     * Syncs `/etc/passwd`, `/etc/group`, and `/etc/shadow` from the current
+     * `VirtualUserManager` state.
+     *
+     * Called automatically during `bootstrapLinuxRootfs`. Call again after
+     * `users.addUser()`, `users.deleteUser()`, or `users.addSudoer()` to keep
+     * the classic Unix credential files in sync with the user manager.
+     */
+    syncPasswd() {
+        syncEtcPasswd(this.vfs, this.users);
+    }
     /**
      * Returns virtual filesystem instance after server started.
      *

package/dist/VirtualUserManager/index.d.ts

@@ -114,16 +114,18 @@ export declare class VirtualUserManager extends EventEmitter {
      */
     getPasswordHash(username: string): string | null;
     /**
-     * Updates password for an existing user account.
+     * Updates the password for an existing user account.
      *
      * @param username Username to update.
-     * @param password New plaintext password.
+     * @param password New plaintext password (must be non-empty).
+     * @throws When the user does not exist or the password is empty.
      */
     setPassword(username: string, password: string): Promise<void>;
     /**
-     * Deletes existing non-root user account.
+     * Deletes an existing non-root user account and revokes sudo access.
      *
      * @param username Username to remove.
+     * @throws When `username` is `"root"` or the user does not exist.
      */
     deleteUser(username: string): Promise<void>;
     /**
@@ -134,57 +136,87 @@ export declare class VirtualUserManager extends EventEmitter {
      */
     isSudoer(username: string): boolean;
     /**
-     * Grants sudo access to existing user.
+     * Grants sudo privileges to an existing user.
      *
      * @param username Username to promote.
+     * @throws When the user does not exist.
      */
     addSudoer(username: string): Promise<void>;
     /**
-     * Revokes sudo access from user.
+     * Revokes sudo privileges from a user. Root cannot be demoted.
      *
      * @param username Username to demote.
+     * @throws When `username` is `"root"`.
      */
     removeSudoer(username: string): Promise<void>;
     /**
-     * Registers active session and allocates tty id.
+     * Registers a new active session and allocates a virtual TTY identifier.
      *
-     * @param username Session username.
-     * @param remoteAddress Session source address.
-     * @returns Registered session descriptor.
+     * Called by the SSH server when a client is authenticated. The returned
+     * descriptor is visible in `who` output and `listActiveSessions()`.
+     *
+     * @param username      Authenticated username bound to the session.
+     * @param remoteAddress IP address or hostname of the connecting client.
+     * @returns The newly created `VirtualActiveSession` descriptor.
      */
     registerSession(username: string, remoteAddress: string): VirtualActiveSession;
     /**
-     * Unregisters active session when connection closes.
+     * Removes an active session record when the connection closes.
+     *
+     * Safe to call with a `null` or `undefined` session ID — it will be a no-op.
      *
-     * @param sessionId Session identifier; ignored when nullish.
+     * @param sessionId Session UUID returned by `registerSession()`, or nullish.
      */
     unregisterSession(sessionId: string | null | undefined): void;
     /**
-     * Updates username/address metadata for existing session.
+     * Updates the username and remote address metadata for an active session.
      *
-     * @param sessionId Session identifier; ignored when nullish.
-     * @param username New username value.
-     * @param remoteAddress New remote address value.
+     * Called internally by `su` and `sudo` when the effective user changes
+     * within a session. Silently ignored when the session ID is nullish or
+     * unknown.
+     *
+     * @param sessionId     Session UUID to update, or nullish for no-op.
+     * @param username      New effective username.
+     * @param remoteAddress New remote address (usually unchanged).
      */
     updateSession(sessionId: string | null | undefined, username: string, remoteAddress: string): void;
     /**
-     * Lists active sessions sorted by start time.
+     * Returns a snapshot of all currently active sessions, sorted by start time.
+     *
+     * Used by `who`, `ps`, `uptime`, and the `HoneyPot` auditor.
      *
-     * @returns Snapshot of active session descriptors.
+     * @returns Array of `VirtualActiveSession` descriptors.
      */
     listActiveSessions(): VirtualActiveSession[];
+    /**
+     * Returns a sorted list of all registered usernames.
+     *
+     * @returns Array of username strings sorted alphabetically.
+     */
+    listUsers(): string[];
     private loadFromVfs;
     private loadSudoersFromVfs;
     private loadQuotasFromVfs;
     private persist;
     private writeIfChanged;
     private createRecord;
+    /**
+     * Returns `true` when the user has a non-empty password set.
+     *
+     * A user with no password (or whose password hash matches the empty-string
+     * hash) is allowed to authenticate without a credential check.
+     *
+     * @param username Target username.
+     */
     hasPassword(username: string): boolean;
     /**
-     * Hashes plaintext password with per-user salt using scrypt.
+     * Hashes a plaintext password using scrypt (or SHA-256 in fast-hash mode).
+     *
+     * Set `SSH_MIMIC_FAST_PASSWORD_HASH=1` to switch to SHA-256 for test
+     * environments where scrypt latency is undesirable.
      *
-     * @param password Plaintext password.
-     * @returns Hex-encoded password hash.
+     * @param password Plaintext password string.
+     * @returns Hex-encoded hash string.
      */
     hashPassword(password: string): string;
     private validateUsername;

package/dist/VirtualUserManager/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualUserManager/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualUserManager/index.ts"],"names":[],"mappings":"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"}

package/dist/VirtualUserManager/index.js

@@ -222,10 +222,11 @@ export class VirtualUserManager extends EventEmitter {
         return record ? record.passwordHash : null;
     }
     /**
-     * Updates password for an existing user account.
+     * Updates the password for an existing user account.
      *
      * @param username Username to update.
-     * @param password New plaintext password.
+     * @param password New plaintext password (must be non-empty).
+     * @throws When the user does not exist or the password is empty.
      */
     async setPassword(username, password) {
         perf.mark("setPassword");
@@ -238,9 +239,10 @@ export class VirtualUserManager extends EventEmitter {
         await this.persist();
     }
     /**
-     * Deletes existing non-root user account.
+     * Deletes an existing non-root user account and revokes sudo access.
      *
      * @param username Username to remove.
+     * @throws When `username` is `"root"` or the user does not exist.
      */
     async deleteUser(username) {
         perf.mark("deleteUser");
@@ -266,9 +268,10 @@ export class VirtualUserManager extends EventEmitter {
         return this.sudoers.has(username);
     }
     /**
-     * Grants sudo access to existing user.
+     * Grants sudo privileges to an existing user.
      *
      * @param username Username to promote.
+     * @throws When the user does not exist.
      */
     async addSudoer(username) {
         perf.mark("addSudoer");
@@ -280,9 +283,10 @@ export class VirtualUserManager extends EventEmitter {
         await this.persist();
     }
     /**
-     * Revokes sudo access from user.
+     * Revokes sudo privileges from a user. Root cannot be demoted.
      *
      * @param username Username to demote.
+     * @throws When `username` is `"root"`.
      */
     async removeSudoer(username) {
         perf.mark("removeSudoer");
@@ -294,11 +298,14 @@ export class VirtualUserManager extends EventEmitter {
         await this.persist();
     }
     /**
-     * Registers active session and allocates tty id.
+     * Registers a new active session and allocates a virtual TTY identifier.
      *
-     * @param username Session username.
-     * @param remoteAddress Session source address.
-     * @returns Registered session descriptor.
+     * Called by the SSH server when a client is authenticated. The returned
+     * descriptor is visible in `who` output and `listActiveSessions()`.
+     *
+     * @param username      Authenticated username bound to the session.
+     * @param remoteAddress IP address or hostname of the connecting client.
+     * @returns The newly created `VirtualActiveSession` descriptor.
      */
     registerSession(username, remoteAddress) {
         perf.mark("registerSession");
@@ -318,9 +325,11 @@ export class VirtualUserManager extends EventEmitter {
         return session;
     }
     /**
-     * Unregisters active session when connection closes.
+     * Removes an active session record when the connection closes.
+     *
+     * Safe to call with a `null` or `undefined` session ID — it will be a no-op.
      *
-     * @param sessionId Session identifier; ignored when nullish.
+     * @param sessionId Session UUID returned by `registerSession()`, or nullish.
      */
     unregisterSession(sessionId) {
         perf.mark("unregisterSession");
@@ -338,11 +347,15 @@ export class VirtualUserManager extends EventEmitter {
         this.activeSessions.delete(sessionId);
     }
     /**
-     * Updates username/address metadata for existing session.
+     * Updates the username and remote address metadata for an active session.
      *
-     * @param sessionId Session identifier; ignored when nullish.
-     * @param username New username value.
-     * @param remoteAddress New remote address value.
+     * Called internally by `su` and `sudo` when the effective user changes
+     * within a session. Silently ignored when the session ID is nullish or
+     * unknown.
+     *
+     * @param sessionId     Session UUID to update, or nullish for no-op.
+     * @param username      New effective username.
+     * @param remoteAddress New remote address (usually unchanged).
      */
     updateSession(sessionId, username, remoteAddress) {
         perf.mark("updateSession");
@@ -360,14 +373,24 @@ export class VirtualUserManager extends EventEmitter {
         });
     }
     /**
-     * Lists active sessions sorted by start time.
+     * Returns a snapshot of all currently active sessions, sorted by start time.
+     *
+     * Used by `who`, `ps`, `uptime`, and the `HoneyPot` auditor.
      *
-     * @returns Snapshot of active session descriptors.
+     * @returns Array of `VirtualActiveSession` descriptors.
      */
     listActiveSessions() {
         perf.mark("listActiveSessions");
         return Array.from(this.activeSessions.values()).sort((left, right) => left.startedAt.localeCompare(right.startedAt));
     }
+    /**
+     * Returns a sorted list of all registered usernames.
+     *
+     * @returns Array of username strings sorted alphabetically.
+     */
+    listUsers() {
+        return Array.from(this.users.keys()).sort();
+    }
     loadFromVfs() {
         this.users.clear();
         if (!this.vfs.exists(this.usersPath)) {
@@ -472,6 +495,14 @@ export class VirtualUserManager extends EventEmitter {
         VirtualUserManager.recordCache.set(cacheKey, record);
         return record;
     }
+    /**
+     * Returns `true` when the user has a non-empty password set.
+     *
+     * A user with no password (or whose password hash matches the empty-string
+     * hash) is allowed to authenticate without a credential check.
+     *
+     * @param username Target username.
+     */
     hasPassword(username) {
         perf.mark("hasPassword");
         if (this.getPasswordHash(username) === this.hashPassword("")) {
@@ -481,10 +512,13 @@ export class VirtualUserManager extends EventEmitter {
         return !!record && !!record.passwordHash;
     }
     /**
-     * Hashes plaintext password with per-user salt using scrypt.
+     * Hashes a plaintext password using scrypt (or SHA-256 in fast-hash mode).
+     *
+     * Set `SSH_MIMIC_FAST_PASSWORD_HASH=1` to switch to SHA-256 for test
+     * environments where scrypt latency is undesirable.
      *
-     * @param password Plaintext password.
-     * @returns Hex-encoded password hash.
+     * @param password Plaintext password string.
+     * @returns Hex-encoded hash string.
      */
     hashPassword(password) {
         if (VirtualUserManager.fastPasswordHash) {

package/dist/commands/alias.d.ts

@@ -0,0 +1,4 @@
+import type { ShellModule } from "../types/commands";
+export declare const aliasCommand: ShellModule;
+export declare const unaliasCommand: ShellModule;
+//# sourceMappingURL=alias.d.ts.map

package/dist/commands/alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias.d.ts","sourceRoot":"","sources":["../../src/commands/alias.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,eAAO,MAAM,YAAY,EAAE,WAkC1B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAoB5B,CAAC"}