typescript-virtual-container 1.1.1-b → 1.1.1-c

package/dist/VirtualUserManager/index.js

@@ -0,0 +1,375 @@
+import { randomBytes, randomUUID, scryptSync } from "node:crypto";
+import * as path from "node:path";
+/**
+ * Persistent user, sudoers, and active-session manager for the shell runtime.
+ *
+ * Passwords are hashed with scrypt and stored in the backing virtual filesystem.
+ */
+export class VirtualUserManager {
+    vfs;
+    defaultRootPassword;
+    autoSudoForNewUsers;
+    usersPath = "/virtual-env-js/.auth/htpasswd";
+    sudoersPath = "/virtual-env-js/.auth/sudoers";
+    quotasPath = "/virtual-env-js/.auth/quotas";
+    authDirPath = "/virtual-env-js/.auth";
+    users = new Map();
+    sudoers = new Set();
+    quotas = new Map();
+    activeSessions = new Map();
+    nextTty = 0;
+    /**
+     * Creates a user manager instance backed by a virtual filesystem.
+     *
+     * @param vfs Backing virtual filesystem used for persistence.
+     * @param defaultRootPassword Initial root password used when root is created.
+     * @param autoSudoForNewUsers Whether newly created users are added to sudoers.
+     */
+    constructor(vfs, defaultRootPassword = "root", autoSudoForNewUsers = true) {
+        this.vfs = vfs;
+        this.defaultRootPassword = defaultRootPassword;
+        this.autoSudoForNewUsers = autoSudoForNewUsers;
+    }
+    /**
+     * Loads users/sudoers from disk and ensures root account exists.
+     */
+    async initialize() {
+        this.loadFromVfs();
+        this.loadSudoersFromVfs();
+        this.loadQuotasFromVfs();
+        this.users.set("root", this.createRecord("root", this.defaultRootPassword));
+        this.sudoers.add("root");
+        await this.persist();
+    }
+    /**
+     * Sets max allowed bytes under /home/<username>.
+     *
+     * @param username Target username.
+     * @param maxBytes Quota ceiling in bytes.
+     */
+    async setQuotaBytes(username, maxBytes) {
+        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.
+     */
+    async clearQuota(username) {
+        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.
+     */
+    getQuotaBytes(username) {
+        return this.quotas.get(username) ?? null;
+    }
+    /**
+     * Computes current usage under /home/<username>.
+     *
+     * @param username Target username.
+     * @returns Current usage in bytes.
+     */
+    getUsageBytes(username) {
+        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.
+     */
+    assertWriteWithinQuota(username, targetPath, nextContent) {
+        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.
+     *
+     * @param username User login name.
+     * @param password Plaintext password candidate.
+     * @returns True when credentials are valid.
+     */
+    verifyPassword(username, password) {
+        const record = this.users.get(username);
+        if (!record) {
+            return false;
+        }
+        return this.hashPassword(password, record.salt) === record.passwordHash;
+    }
+    /**
+     * Creates user, home directory, and sudo access entry.
+     *
+     * @param username New username.
+     * @param password Initial plaintext password.
+     */
+    async addUser(username, password) {
+        this.validateUsername(username);
+        this.validatePassword(password);
+        if (this.users.has(username)) {
+            throw new Error(`adduser: user '${username}' already exists`);
+        }
+        this.users.set(username, this.createRecord(username, password));
+        if (this.autoSudoForNewUsers) {
+            this.sudoers.add(username);
+        }
+        const homePath = `/home/${username}`;
+        if (!this.vfs.exists(homePath)) {
+            this.vfs.mkdir(homePath, 0o755);
+            this.vfs.writeFile(`${homePath}/README.txt`, `Welcome to the virtual environment, ${username}`);
+        }
+        await this.persist();
+    }
+    /**
+     * Deletes existing non-root user account.
+     *
+     * @param username Username to remove.
+     */
+    async deleteUser(username) {
+        this.validateUsername(username);
+        if (username === "root") {
+            throw new Error("deluser: cannot delete root");
+        }
+        if (!this.users.delete(username)) {
+            throw new Error(`deluser: user '${username}' does not exist`);
+        }
+        this.sudoers.delete(username);
+        await this.persist();
+    }
+    /**
+     * Checks whether user is member of sudoers set.
+     *
+     * @param username Username to test.
+     * @returns True when user can run sudo.
+     */
+    isSudoer(username) {
+        return this.sudoers.has(username);
+    }
+    /**
+     * Grants sudo access to existing user.
+     *
+     * @param username Username to promote.
+     */
+    async addSudoer(username) {
+        this.validateUsername(username);
+        if (!this.users.has(username)) {
+            throw new Error(`sudoers: user '${username}' does not exist`);
+        }
+        this.sudoers.add(username);
+        await this.persist();
+    }
+    /**
+     * Revokes sudo access from user.
+     *
+     * @param username Username to demote.
+     */
+    async removeSudoer(username) {
+        this.validateUsername(username);
+        if (username === "root") {
+            throw new Error("sudoers: cannot remove root");
+        }
+        this.sudoers.delete(username);
+        await this.persist();
+    }
+    /**
+     * Registers active session and allocates tty id.
+     *
+     * @param username Session username.
+     * @param remoteAddress Session source address.
+     * @returns Registered session descriptor.
+     */
+    registerSession(username, remoteAddress) {
+        const session = {
+            id: randomUUID(),
+            username,
+            tty: `pts/${this.nextTty++}`,
+            remoteAddress,
+            startedAt: new Date().toISOString(),
+        };
+        this.activeSessions.set(session.id, session);
+        return session;
+    }
+    /**
+     * Unregisters active session when connection closes.
+     *
+     * @param sessionId Session identifier; ignored when nullish.
+     */
+    unregisterSession(sessionId) {
+        if (!sessionId) {
+            return;
+        }
+        this.activeSessions.delete(sessionId);
+    }
+    /**
+     * Updates username/address metadata for existing session.
+     *
+     * @param sessionId Session identifier; ignored when nullish.
+     * @param username New username value.
+     * @param remoteAddress New remote address value.
+     */
+    updateSession(sessionId, username, remoteAddress) {
+        if (!sessionId) {
+            return;
+        }
+        const session = this.activeSessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        this.activeSessions.set(sessionId, {
+            ...session,
+            username,
+            remoteAddress,
+        });
+    }
+    /**
+     * Lists active sessions sorted by start time.
+     *
+     * @returns Snapshot of active session descriptors.
+     */
+    listActiveSessions() {
+        return Array.from(this.activeSessions.values()).sort((left, right) => left.startedAt.localeCompare(right.startedAt));
+    }
+    loadFromVfs() {
+        this.users.clear();
+        if (!this.vfs.exists(this.usersPath)) {
+            return;
+        }
+        const raw = this.vfs.readFile(this.usersPath);
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0) {
+                continue;
+            }
+            const parts = trimmed.split(":");
+            if (parts.length < 3) {
+                continue;
+            }
+            const [username, salt, passwordHash] = parts;
+            if (!username || !salt || !passwordHash) {
+                continue;
+            }
+            this.users.set(username, { username, salt, passwordHash });
+        }
+    }
+    loadSudoersFromVfs() {
+        this.sudoers.clear();
+        if (!this.vfs.exists(this.sudoersPath)) {
+            return;
+        }
+        const raw = this.vfs.readFile(this.sudoersPath);
+        for (const line of raw.split("\n")) {
+            const username = line.trim();
+            if (username.length > 0) {
+                this.sudoers.add(username);
+            }
+        }
+    }
+    loadQuotasFromVfs() {
+        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);
+        }
+    }
+    async persist() {
+        if (!this.vfs.exists(this.authDirPath)) {
+            this.vfs.mkdir(this.authDirPath, 0o700);
+        }
+        const content = Array.from(this.users.values())
+            .sort((left, right) => left.username.localeCompare(right.username))
+            .map((record) => [record.username, record.salt, record.passwordHash].join(":"))
+            .join("\n");
+        this.vfs.writeFile(this.usersPath, content.length > 0 ? `${content}\n` : "", { mode: 0o600 });
+        const sudoersContent = Array.from(this.sudoers.values()).sort().join("\n");
+        this.vfs.writeFile(this.sudoersPath, 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();
+    }
+    createRecord(username, password) {
+        const salt = randomBytes(16).toString("hex");
+        return {
+            username,
+            salt,
+            passwordHash: this.hashPassword(password, salt),
+        };
+    }
+    hashPassword(password, salt) {
+        return scryptSync(password, salt, 64).toString("hex");
+    }
+    validateUsername(username) {
+        if (!username || username.trim() === "") {
+            throw new Error("invalid username");
+        }
+        if (!/^[a-z_][a-z0-9_-]{0,31}$/i.test(username)) {
+            throw new Error("invalid username");
+        }
+    }
+    validatePassword(password) {
+        if (!password || password.trim() === "") {
+            throw new Error("invalid password");
+        }
+    }
+}
+function normalizeVfsPath(targetPath) {
+    const normalized = path.posix.normalize(targetPath);
+    return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}

package/dist/commands/adduser.d.ts

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

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

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

package/dist/commands/adduser.js

@@ -0,0 +1,18 @@
+export const adduserCommand = {
+    name: "adduser",
+    params: ["<username> <password>"],
+    run: async ({ authUser, shell, args }) => {
+        if (authUser !== "root") {
+            return { stderr: "adduser: permission denied", exitCode: 1 };
+        }
+        const [username, password] = args;
+        if (!username || !password) {
+            return {
+                stderr: "adduser: usage: adduser <username> <password>",
+                exitCode: 1,
+            };
+        }
+        await shell.users.addUser(username, password);
+        return { stdout: `adduser: user '${username}' created`, exitCode: 0 };
+    },
+};

package/dist/commands/cat.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"cat.d.ts","sourceRoot":"","sources":["../../src/commands/cat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,eAAO,MAAM,UAAU,EAAE,WAaxB,CAAC"}

package/dist/commands/cat.js

@@ -0,0 +1,15 @@
+import { getArg } from "./command-helpers";
+import { assertPathAccess, resolveReadablePath } from "./helpers";
+export const catCommand = {
+    name: "cat",
+    params: ["<file>"],
+    run: ({ authUser, shell, cwd, args }) => {
+        const fileArg = getArg(args, 0);
+        if (!fileArg) {
+            return { stderr: "cat: missing file operand", exitCode: 1 };
+        }
+        const target = resolveReadablePath(shell.vfs, cwd, fileArg);
+        assertPathAccess(authUser, target, "cat");
+        return { stdout: shell.vfs.readFile(target), exitCode: 0 };
+    },
+};

package/dist/commands/cd.d.ts

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

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

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

package/dist/commands/cd.js

@@ -0,0 +1,17 @@
+import { assertPathAccess, resolvePath } from "./helpers";
+export const cdCommand = {
+    name: "cd",
+    params: ["[path]"],
+    run: ({ authUser, shell, cwd, args, mode }) => {
+        const target = resolvePath(cwd, args[0] ?? "/virtual-env-js");
+        assertPathAccess(authUser, target, "cd");
+        const stats = shell.vfs.stat(target);
+        if (stats.type !== "directory") {
+            return { stderr: `cd: not a directory: ${target}`, exitCode: 1 };
+        }
+        if (mode === "exec") {
+            return { exitCode: 0 };
+        }
+        return { nextCwd: target, exitCode: 0 };
+    },
+};

package/dist/commands/clear.d.ts

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

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

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

package/dist/commands/clear.js

@@ -0,0 +1,5 @@
+export const clearCommand = {
+    name: "clear",
+    params: [],
+    run: () => ({ clearScreen: true, exitCode: 0 }),
+};

package/dist/commands/command-helpers.d.ts

@@ -0,0 +1,23 @@
+type ArgParseOptions = {
+    flags?: string[];
+    flagsWithValue?: string[];
+};
+export declare function ifFlag(args: string[], flags: string | string[]): boolean;
+export declare function getFlag(args: string[], flags: string | string[]): string | true | undefined;
+export declare function getArg(args: string[], index: number, options?: ArgParseOptions): string | undefined;
+/**
+ * Parse arguments into flags, flags with values, and positionals.
+ * @param args - Array of arguments to parse.
+ * @param options - Parsing options for flags and flags with values.
+ * @returns Parsed arguments as { flags, flagsWithValues, positionals }.
+ */
+export declare function parseArgs(args: string[], options?: {
+    flags?: string[];
+    flagsWithValue?: string[];
+}): {
+    flags: Set<string>;
+    flagsWithValues: Map<string, string>;
+    positionals: string[];
+};
+export {};
+//# sourceMappingURL=command-helpers.d.ts.map

package/dist/commands/command-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/command-helpers.ts"],"names":[],"mappings":"AAAA,KAAK,eAAe,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA+EF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAYxE;AAED,wBAAgB,OAAO,CACtB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GACtB,MAAM,GAAG,IAAI,GAAG,SAAS,CA0B3B;AAED,wBAAgB,MAAM,CACrB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC3B,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC3D;IACF,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB,CAiDA"}

package/dist/commands/command-helpers.js

@@ -0,0 +1,139 @@
+function toFlagList(flags) {
+    return Array.isArray(flags) ? flags : [flags];
+}
+function matchFlagToken(token, flag) {
+    if (token === flag) {
+        return { matched: true, inlineValue: null };
+    }
+    const prefix = `${flag}=`;
+    if (token.startsWith(prefix)) {
+        return { matched: true, inlineValue: token.slice(prefix.length) };
+    }
+    return { matched: false, inlineValue: null };
+}
+function collectPositionals(args, options = {}) {
+    const boolFlags = new Set(options.flags ?? []);
+    const valueFlags = new Set(options.flagsWithValue ?? []);
+    const positionals = [];
+    let passthrough = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (passthrough) {
+            positionals.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            passthrough = true;
+            continue;
+        }
+        let consumed = false;
+        for (const flag of boolFlags) {
+            const { matched } = matchFlagToken(arg, flag);
+            if (matched) {
+                consumed = true;
+                break;
+            }
+        }
+        if (consumed) {
+            continue;
+        }
+        for (const flag of valueFlags) {
+            const match = matchFlagToken(arg, flag);
+            if (!match.matched) {
+                continue;
+            }
+            consumed = true;
+            if (match.inlineValue === null && index + 1 < args.length) {
+                index += 1;
+            }
+            break;
+        }
+        if (!consumed) {
+            positionals.push(arg);
+        }
+    }
+    return positionals;
+}
+export function ifFlag(args, flags) {
+    const allFlags = toFlagList(flags);
+    for (const arg of args) {
+        for (const flag of allFlags) {
+            if (matchFlagToken(arg, flag).matched) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+export function getFlag(args, flags) {
+    const allFlags = toFlagList(flags);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        for (const flag of allFlags) {
+            const match = matchFlagToken(arg, flag);
+            if (!match.matched) {
+                continue;
+            }
+            if (match.inlineValue !== null) {
+                return match.inlineValue;
+            }
+            const next = args[index + 1];
+            if (next !== undefined && next !== "--") {
+                return next;
+            }
+            return true;
+        }
+    }
+    return undefined;
+}
+export function getArg(args, index, options = {}) {
+    const positionals = collectPositionals(args, options);
+    return positionals[index];
+}
+/**
+ * Parse arguments into flags, flags with values, and positionals.
+ * @param args - Array of arguments to parse.
+ * @param options - Parsing options for flags and flags with values.
+ * @returns Parsed arguments as { flags, flagsWithValues, positionals }.
+ */
+export function parseArgs(args, options = {}) {
+    const flags = new Set();
+    const flagsWithValues = new Map();
+    const positionals = [];
+    const boolFlags = new Set(options.flags ?? []);
+    const valueFlags = new Set(options.flagsWithValue ?? []);
+    let passthrough = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (passthrough) {
+            positionals.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            passthrough = true;
+            continue;
+        }
+        if (boolFlags.has(arg)) {
+            flags.add(arg);
+            continue;
+        }
+        if (valueFlags.has(arg)) {
+            const next = args[index + 1];
+            if (next && !next.startsWith("-")) {
+                flagsWithValues.set(arg, next);
+                index += 1;
+            }
+            else {
+                flagsWithValues.set(arg, "");
+            }
+            continue;
+        }
+        const inlineFlag = Array.from(valueFlags).find((flag) => arg.startsWith(`${flag}=`));
+        if (inlineFlag) {
+            flagsWithValues.set(inlineFlag, arg.slice(inlineFlag.length + 1));
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return { flags, flagsWithValues, positionals };
+}

package/dist/commands/curl.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"curl.d.ts","sourceRoot":"","sources":["../../src/commands/curl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASrD,eAAO,MAAM,WAAW,EAAE,WAiDzB,CAAC"}