sandboxedjs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1958 @@
+import { MemoryVolume, Nodepod } from '@scelar/nodepod/headless';
+
+type FileKind = "file" | "directory" | "symlink" | "chardev" | "blockdev" | "fifo" | "socket";
+/** Render as `drwxr-xr-x`, honouring setuid/setgid/sticky. */
+declare function formatMode(mode: number): string;
+/** Zero-padded octal permissions, as `stat -c %a`/`%04a` would show. */
+declare function octalMode(mode: number, width?: number): string;
+/**
+ * Apply a `chmod` spec to an existing mode. Accepts octal (`755`, `0644`) and
+ * the symbolic grammar (`u+rwx,go-w`, `a=r`, `+X`, `u+s`, `o+t`).
+ *
+ * @param isDir whether the target is a directory — needed for the `X` flag.
+ */
+declare function applyChmod(spec: string, current: number, isDir: boolean, umask?: number): number;
+/** Parse the `umask` builtin's argument. */
+declare function parseUmask(spec: string): number;
+
+/**
+ * The `Stats` object handed back by `Vfs.stat`. Shaped like `fs.Stats` so it
+ * feels familiar, but with a real `st_mode` that carries the file-type bits
+ * (which the underlying volume stores separately).
+ */
+
+interface StatInit {
+    mode: number;
+    size: number;
+    uid: number;
+    gid: number;
+    ino: number;
+    nlink: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs?: number;
+    dev?: number;
+    rdev?: number;
+    blksize?: number;
+}
+declare class Stats {
+    readonly mode: number;
+    readonly size: number;
+    readonly uid: number;
+    readonly gid: number;
+    readonly ino: number;
+    readonly nlink: number;
+    readonly dev: number;
+    readonly rdev: number;
+    readonly blksize: number;
+    readonly atimeMs: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs: number;
+    constructor(init: StatInit);
+    get blocks(): number;
+    get atime(): Date;
+    get mtime(): Date;
+    get ctime(): Date;
+    get birthtime(): Date;
+    get kind(): FileKind;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    isCharacterDevice(): boolean;
+    isBlockDevice(): boolean;
+    isFIFO(): boolean;
+    isSocket(): boolean;
+    /** Permission bits only, with the type bits masked off. */
+    get perms(): number;
+}
+interface DirEntry {
+    name: string;
+    kind: FileKind;
+}
+
+/**
+ * The container's virtual filesystem.
+ *
+ * Real file content lives in a Nodepod `MemoryVolume`, which is deliberately the
+ * *same* volume the Node.js worker processes see — so a file written by `echo`
+ * is readable by `require('fs')` inside a spawned script, and vice versa.
+ *
+ * On top of that volume this layer adds the parts a Linux userland expects and
+ * the raw volume does not have: file-type bits in `st_mode`, permission and
+ * ownership checks, an `O_*` open/fd table, and pluggable *virtual providers*
+ * that synthesise `/proc`, `/sys` and `/dev` on demand.
+ */
+
+/** The identity a filesystem operation runs as. */
+interface Cred {
+    uid: number;
+    gid: number;
+    groups: number[];
+    umask: number;
+}
+declare const ROOT_CRED: Cred;
+declare function makeCred(uid: number, gid: number, groups?: number[], umask?: number): Cred;
+/** A file that does not live in the volume — `/proc/uptime`, `/dev/null`, … */
+interface VirtualNode {
+    kind: FileKind;
+    /** Permission bits only; the type bits are added from `kind`. */
+    mode: number;
+    uid?: number;
+    gid?: number;
+    size?: number;
+    mtimeMs?: number;
+    /** Symlink target, when `kind === "symlink"`. */
+    target?: string;
+    read?(): Uint8Array | string;
+    write?(data: Uint8Array, append: boolean): void;
+    /** Directory listing, when `kind === "directory"`. */
+    list?(): string[];
+}
+/**
+ * Supplies a subtree of synthetic files. `resolve` receives the path *relative*
+ * to `root` ("" means the mount point itself) and returns null for misses.
+ */
+interface VirtualProvider {
+    root: string;
+    resolve(rel: string): VirtualNode | null;
+    /**
+     * When true (the default) the provider owns its whole subtree and a miss is
+     * `ENOENT` — that is what `/proc` wants, so a dead pid does not resolve to a
+     * stale on-disk file. `/dev` and `/sys` set this to false so that synthetic
+     * nodes overlay a real directory users can still write into.
+     */
+    exclusive?: boolean;
+}
+interface WriteOptions {
+    mode?: number;
+    append?: boolean;
+    cred?: Cred;
+    /** Skip the permission check — used by kernel-internal writes. */
+    privileged?: boolean;
+}
+interface ResolveOptions {
+    cred?: Cred;
+    /** Follow a symlink in the final position. Off for `lstat`, `rm`, `chmod -h`. */
+    followFinal?: boolean;
+}
+declare class Vfs {
+    readonly volume: MemoryVolume;
+    private readonly providers;
+    private nextVirtualIno;
+    private readonly virtualInos;
+    constructor(volume: MemoryVolume);
+    addProvider(provider: VirtualProvider): void;
+    removeProvider(root: string): void;
+    /** The mount points currently served synthetically. */
+    get virtualRoots(): string[];
+    private lookupVirtual;
+    /** True when a miss at `abs` must be ENOENT rather than a volume lookup. */
+    private isUnderProvider;
+    /** Synthetic children a non-exclusive provider contributes to a directory. */
+    private virtualChildren;
+    private virtualIno;
+    /** True when `cred` may perform `mode` (R_OK/W_OK/X_OK) on a stat result. */
+    permitted(st: Stats, mode: number, cred: Cred): boolean;
+    private require;
+    /**
+     * Walk `abs` component by component, following symlinks and checking search
+     * (`+x`) permission on every directory along the way, exactly like `namei`.
+     *
+     * Returns the fully resolved absolute path. Does *not* require the final
+     * component to exist — callers decide whether a miss is fatal.
+     */
+    resolvePath(abs: string, opts?: ResolveOptions): string;
+    /** lstat that returns null instead of throwing, for internal probing. */
+    private tryLstat;
+    private readlinkRaw;
+    /** stat(2) — follows symlinks. */
+    stat(abs: string, opts?: {
+        cred?: Cred;
+    }): Stats;
+    /** lstat(2) — does not follow a symlink in the final position. */
+    lstat(abs: string): Stats;
+    private statFromVirtual;
+    exists(abs: string, cred?: Cred): boolean;
+    lexists(abs: string): boolean;
+    access(abs: string, mode?: number, cred?: Cred): void;
+    realpath(abs: string, cred?: Cred): string;
+    readFile(abs: string, cred?: Cred): Uint8Array;
+    readText(abs: string, cred?: Cred): string;
+    readdir(abs: string, cred?: Cred): string[];
+    /** True when the volume itself has a real directory at `abs`. */
+    private volumeHasDir;
+    readdirWithTypes(abs: string, cred?: Cred): DirEntry[];
+    readlink(abs: string, cred?: Cred): string;
+    writeFile(abs: string, data: Uint8Array | string, opts?: WriteOptions): void;
+    appendFile(abs: string, data: Uint8Array | string, opts?: WriteOptions): void;
+    truncate(abs: string, len?: number, cred?: Cred): void;
+    mkdir(abs: string, opts?: {
+        mode?: number;
+        recursive?: boolean;
+        cred?: Cred;
+    }): void;
+    private mkdirOne;
+    rmdir(abs: string, cred?: Cred): void;
+    unlink(abs: string, cred?: Cred): void;
+    /** Recursive delete, the engine behind `rm -r`. */
+    rmrf(abs: string, cred?: Cred): void;
+    private requireParentWrite;
+    rename(from: string, to: string, cred?: Cred): void;
+    copyFile(from: string, to: string, cred?: Cred): void;
+    symlink(target: string, linkPath: string, cred?: Cred): void;
+    link(existing: string, newPath: string, cred?: Cred): void;
+    chmod(abs: string, mode: number, cred?: Cred, follow?: boolean): void;
+    chown(abs: string, uid: number, gid: number, cred?: Cred, follow?: boolean): void;
+    utimes(abs: string, atimeMs: number, mtimeMs: number, cred?: Cred): void;
+    /** `touch` semantics: create when missing, otherwise bump the timestamps. */
+    touch(abs: string, cred?: Cred, timeMs?: number): void;
+    /** Depth-first walk yielding absolute paths. Symlinks are not followed. */
+    walk(abs: string, opts?: {
+        includeSelf?: boolean;
+        cred?: Cred;
+        maxDepth?: number;
+    }): Generator<string>;
+    /** Recursive copy used by `cp -r` and the container's `copyIn` helper. */
+    copyTree(from: string, to: string, cred?: Cred): void;
+    /** Free/used byte accounting for `df` and `du`. */
+    usage(abs?: string): {
+        files: number;
+        dirs: number;
+        bytes: number;
+    };
+}
+
+/**
+ * Byte streams for stdin/stdout/stderr, pipelines and redirections.
+ *
+ * Everything here is promise-based rather than Node-stream based: commands are
+ * plain async functions, a pipeline is just a chain of `Pipe` objects, and a
+ * closed reader turns further writes into `EPIPE` the way a real pipe does.
+ */
+
+interface OutputStream {
+    write(data: Uint8Array | string): void;
+    end(): void;
+    /** True once the far end went away — producers should stop. */
+    readonly closed: boolean;
+    isTTY: boolean;
+    /** Terminal width, when this is a TTY. */
+    columns?: number;
+    rows?: number;
+}
+interface InputStream {
+    /** Resolves to null at EOF. `size` is a maximum, not a guarantee. */
+    read(size?: number): Promise<Uint8Array | null>;
+    readAll(): Promise<Uint8Array>;
+    /** One line without its terminator; null at EOF. */
+    readLine(): Promise<string | null>;
+    /** Bytes already buffered, for non-blocking peeks. */
+    readonly available: number;
+    close(): void;
+    isTTY: boolean;
+    /**
+     * True when the far end is a live caller who may never signal EOF — a
+     * terminal, or the `stdin` pipe of `Container.spawn`. Programs that would
+     * otherwise slurp stdin before starting must not block on these.
+     */
+    readonly interactive?: boolean;
+}
+interface Stdio {
+    stdin: InputStream;
+    stdout: OutputStream;
+    stderr: OutputStream;
+}
+/** An in-memory pipe: writable on one end, readable on the other. */
+declare class Pipe implements InputStream, OutputStream {
+    private chunks;
+    private buffered;
+    private writerClosed;
+    private readerClosed;
+    private wakers;
+    isTTY: boolean;
+    /** Set on pipes owned by an outside caller, who may never call `end()`. */
+    interactive: boolean;
+    columns: number | undefined;
+    rows: number | undefined;
+    get closed(): boolean;
+    get ended(): boolean;
+    get available(): number;
+    write(data: Uint8Array | string): void;
+    end(): void;
+    close(): void;
+    private wake;
+    private waitForData;
+    read(size?: number): Promise<Uint8Array | null>;
+    readAll(): Promise<Uint8Array>;
+    private lineRemainder;
+    readLine(): Promise<string | null>;
+    /** Seed the pipe with content then close it — handy for here-docs. */
+    static from(data: Uint8Array | string): Pipe;
+    static empty(): Pipe;
+}
+/** Discards everything; `/dev/null` as an output stream. */
+declare class NullOutput implements OutputStream {
+    readonly closed = false;
+    isTTY: boolean;
+    write(): void;
+    end(): void;
+}
+/** Always at EOF; `/dev/null` as an input stream. */
+declare class NullInput implements InputStream {
+    readonly available = 0;
+    isTTY: boolean;
+    read(): Promise<null>;
+    readAll(): Promise<Uint8Array>;
+    readLine(): Promise<null>;
+    close(): void;
+}
+/** Collects everything written, for `exec()` and command substitution. */
+declare class BufferSink implements OutputStream {
+    private readonly onWrite?;
+    private chunks;
+    private total;
+    private _closed;
+    isTTY: boolean;
+    columns: number | undefined;
+    rows: number | undefined;
+    constructor(onWrite?: ((chunk: Uint8Array) => void) | undefined);
+    get closed(): boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+    bytes(): Uint8Array;
+    text(): string;
+    get length(): number;
+    reset(): void;
+}
+/** Forwards each write to a callback — used to stream into a terminal. */
+declare class CallbackSink implements OutputStream {
+    private readonly sink;
+    private _closed;
+    isTTY: boolean;
+    columns: number | undefined;
+    rows: number | undefined;
+    constructor(sink: (text: string) => void, opts?: {
+        isTTY?: boolean;
+        columns?: number;
+        rows?: number;
+    });
+    get closed(): boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+}
+/** Fan-out, for `tee` and for `2>&1`-style duplication. */
+declare class TeeOutput implements OutputStream {
+    private readonly targets;
+    constructor(targets: OutputStream[]);
+    get closed(): boolean;
+    isTTY: boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+}
+/**
+ * Writes into a VFS file. Buffers in memory and flushes on every write so a
+ * long-running redirect (`cmd > log &`) is observable while it runs.
+ */
+declare class FileOutput implements OutputStream {
+    private readonly vfs;
+    private readonly path;
+    private readonly opts;
+    private _closed;
+    isTTY: boolean;
+    constructor(vfs: Vfs, path: string, opts?: {
+        append?: boolean;
+        cred?: Cred;
+        mode?: number;
+    });
+    get closed(): boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+}
+/** Reads a VFS file as an input stream, for `cmd < file`. */
+declare class FileInput implements InputStream {
+    private pipe;
+    isTTY: boolean;
+    constructor(vfs: Vfs, path: string, cred?: Cred);
+    get available(): number;
+    read(size?: number): Promise<Uint8Array | null>;
+    readAll(): Promise<Uint8Array>;
+    readLine(): Promise<string | null>;
+    close(): void;
+}
+/** Convenience factory for a fully buffered stdio triple. */
+declare function captureStdio(stdin?: Uint8Array | string): {
+    stdio: Stdio;
+    out: BufferSink;
+    err: BufferSink;
+};
+
+/**
+ * The process table.
+ *
+ * Processes here are cooperative JavaScript tasks, not OS processes, but they
+ * carry the state Linux tooling expects to see: pid/ppid/pgid/sid, a state
+ * letter, credentials, a cwd, an environment, and an exit status that encodes
+ * the killing signal. `ps`, `kill`, `jobs` and `/proc` all read from here.
+ */
+
+type ProcessState = "R" | "S" | "D" | "T" | "Z" | "X";
+type Env = Record<string, string>;
+interface ProcessOptions {
+    argv: string[];
+    cwd: string;
+    env: Env;
+    cred: Cred;
+    ppid?: number;
+    pgid?: number;
+    sid?: number;
+    stdio?: Partial<Stdio>;
+    tty?: string | null;
+    /** Marks the process as a shell builtin frame rather than a real command. */
+    kind?: ProcessKind;
+}
+type ProcessKind = "init" | "shell" | "builtin" | "command" | "node" | "python" | "script";
+declare class Process {
+    readonly pid: number;
+    ppid: number;
+    pgid: number;
+    sid: number;
+    argv: string[];
+    cwd: string;
+    env: Env;
+    cred: Cred;
+    kind: ProcessKind;
+    tty: string | null;
+    state: ProcessState;
+    exitCode: number | null;
+    /** Signal that terminated the process, if any. */
+    termSignal: string | null;
+    readonly startTime: number;
+    cpuMs: number;
+    stdin: InputStream;
+    stdout: OutputStream;
+    stderr: OutputStream;
+    readonly children: Set<Process>;
+    private readonly aborter;
+    private readonly exitWaiters;
+    private readonly signalHandlers;
+    constructor(opts: ProcessOptions);
+    /** Basename of argv[0], the `comm` field in `ps`. */
+    get comm(): string;
+    get cmdline(): string;
+    get running(): boolean;
+    get signal(): AbortSignal;
+    /** Seconds since the process started, for `ps etime`. */
+    get elapsedMs(): number;
+    setStdio(stdio: Partial<Stdio>): void;
+    onSignal(sig: string, handler: "default" | "ignore" | ((sig: string) => void)): void;
+    /**
+     * Deliver a signal. Returns true when the process handled or died from it.
+     * Catchable signals run the installed handler; uncatchable ones always kill.
+     */
+    deliver(sigSpec: string | number): boolean;
+    exit(code: number): void;
+    /** Remove from the table entirely — the parent has reaped us. */
+    reap(): void;
+    wait(): Promise<number>;
+}
+interface ProcessFilter {
+    pid?: number;
+    pgid?: number;
+    uid?: number;
+    comm?: string;
+    includeDead?: boolean;
+}
+declare class ProcessTable {
+    private readonly map;
+    create(opts: ProcessOptions): Process;
+    get(pid: number): Process | undefined;
+    has(pid: number): boolean;
+    remove(pid: number): void;
+    list(filter?: ProcessFilter): Process[];
+    get size(): number;
+    /** Send a signal to a pid, a process group (negative pid), or everything (-1). */
+    signal(target: number, sig: string | number): number;
+    /** Drop finished processes so the table does not grow without bound. */
+    gc(keepMs?: number): void;
+    clear(): void;
+}
+/** Reset the pid counter — used by tests and by `Container.reset()`. */
+declare function resetPidCounter(start?: number): void;
+
+/**
+ * The user and group database, backed by real `/etc/passwd`, `/etc/group` and
+ * `/etc/shadow` files so `cat /etc/passwd` and `id` agree with each other and
+ * `useradd` is just a file edit.
+ */
+
+interface PasswdEntry {
+    name: string;
+    passwd: string;
+    uid: number;
+    gid: number;
+    gecos: string;
+    home: string;
+    shell: string;
+}
+interface GroupEntry {
+    name: string;
+    passwd: string;
+    gid: number;
+    members: string[];
+}
+declare class UserDatabase {
+    private readonly vfs;
+    constructor(vfs: Vfs);
+    private readLines;
+    users(): PasswdEntry[];
+    groups(): GroupEntry[];
+    userByName(name: string): PasswdEntry | undefined;
+    userByUid(uid: number): PasswdEntry | undefined;
+    groupByName(name: string): GroupEntry | undefined;
+    groupByGid(gid: number): GroupEntry | undefined;
+    /** Accepts a name or a numeric id, the way `chown` arguments do. */
+    resolveUid(spec: string): number | undefined;
+    resolveGid(spec: string): number | undefined;
+    nameForUid(uid: number): string;
+    nameForGid(gid: number): string;
+    /** Every group id a user belongs to, primary first. */
+    groupsFor(name: string): number[];
+    credFor(nameOrUid: string | number, umask?: number): Cred;
+    nextFreeUid(min?: number, max?: number): number;
+    nextFreeGid(min?: number, max?: number): number;
+    addUser(entry: PasswdEntry, opts?: {
+        createHome?: boolean;
+        password?: string;
+    }): void;
+    addGroup(entry: GroupEntry): void;
+    removeUser(name: string): boolean;
+    removeGroup(name: string): boolean;
+    /** Add `user` to the supplementary members of `group`. */
+    addUserToGroup(user: string, group: string): boolean;
+}
+
+/**
+ * The contract every in-container program implements.
+ *
+ * A "binary" is an async function over an `ExecContext`, returning an exit
+ * code. The shell, the coreutils and the language runtimes all speak this one
+ * interface, which is what lets `node`, `python3` and `grep` sit side by side
+ * in `$PATH` and be pipelined together.
+ */
+
+interface ExecContext {
+    /** argv[0] is the command name as invoked. */
+    readonly argv: string[];
+    readonly stdin: InputStream;
+    readonly stdout: OutputStream;
+    readonly stderr: OutputStream;
+    readonly env: Env;
+    readonly cwd: string;
+    readonly vfs: Vfs;
+    readonly kernel: Kernel;
+    readonly proc: Process;
+    readonly cred: Cred;
+    readonly signal: AbortSignal;
+    /** Command name, for error prefixes. */
+    readonly name: string;
+    /** argv without argv[0]. */
+    readonly args: string[];
+    /** Resolve a possibly relative path against the process cwd. */
+    path(p: string): string;
+    /** Write to stdout verbatim. */
+    write(text: string | Uint8Array): void;
+    /** Write a line to stdout. */
+    line(text?: string): void;
+    /** Write `name: message` to stderr, followed by a newline. */
+    warn(message: string): void;
+    /** Report an error and produce an exit code in one expression. */
+    fail(message: string, code?: number): number;
+    /** Turn a caught filesystem error into the message coreutils would print. */
+    reportError(e: unknown, subject?: string): number;
+    /** Change the calling process's directory (used by `cd`, `chroot`). */
+    chdir(dir: string): void;
+}
+interface Command {
+    readonly name: string;
+    /** One-line summary shown by `help` and `whatis`. */
+    readonly summary?: string;
+    /** Usage string shown on `--help` and on a `UsageError`. */
+    readonly usage?: string;
+    /** Longer text shown by `man`. */
+    readonly manual?: string;
+    /** Aliases registered into the same PATH entry, e.g. `egrep` → `grep`. */
+    readonly aliases?: string[];
+    /** Where the binary claims to live, for `which` and `type`. */
+    readonly path?: string;
+    run(ctx: ExecContext): Promise<number> | number;
+}
+declare function defineCommand(cmd: Command): Command;
+declare class CommandRegistry {
+    private readonly commands;
+    register(cmd: Command): void;
+    registerAll(cmds: Command[]): void;
+    get(name: string): Command | undefined;
+    has(name: string): boolean;
+    names(): string[];
+    all(): Command[];
+    /** Default install location, used when populating `/bin` and `/usr/bin`. */
+    binPath(name: string): string;
+}
+interface ContextInit {
+    argv: string[];
+    proc: Process;
+    kernel: Kernel;
+    stdin?: InputStream;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    env?: Env;
+    cwd?: string;
+    cred?: Cred;
+}
+declare function createContext(init: ContextInit): ExecContext;
+
+/**
+ * The container's network stack.
+ *
+ * There is no real socket layer: HTTP servers started inside the container are
+ * registered with Nodepod's request proxy, and this module is the routing and
+ * name-resolution layer on top — interfaces for `ip`/`ifconfig`, a hosts file
+ * resolver, a listening-port table for `ss`/`netstat`, and an outbound policy
+ * that decides whether `curl https://example.com` is allowed to touch the real
+ * network.
+ */
+
+interface NetInterface {
+    name: string;
+    mac: string;
+    ipv4: string;
+    netmask: string;
+    broadcast?: string;
+    ipv6?: string;
+    mtu: number;
+    up: boolean;
+    loopback: boolean;
+    rxBytes: number;
+    txBytes: number;
+    rxPackets: number;
+    txPackets: number;
+}
+interface ListeningPort {
+    port: number;
+    proto: "tcp" | "udp";
+    address: string;
+    pid: number;
+    program: string;
+    since: number;
+}
+interface NetworkOptions {
+    /**
+     * Allow outbound requests to the real internet. When false (the default),
+     * `curl`/`wget`/`fetch` only reach servers running inside the container.
+     */
+    allowOutbound?: boolean;
+    /** Host allowlist applied when `allowOutbound` is on. `null` means any host. */
+    allowedHosts?: string[] | null;
+    /** Address handed to eth0. */
+    ipv4?: string;
+    gateway?: string;
+}
+declare class NetworkStack {
+    private readonly pod;
+    private readonly vfs;
+    private readonly ifaces;
+    private readonly listeners;
+    readonly options: Required<Pick<NetworkOptions, "allowOutbound">> & NetworkOptions;
+    constructor(pod: Nodepod, vfs: Vfs, options?: NetworkOptions);
+    interfaces(): NetInterface[];
+    interface(name: string): NetInterface | undefined;
+    setInterfaceUp(name: string, up: boolean): boolean;
+    get gateway(): string;
+    /** Resolve through `/etc/hosts`; returns null when the name is not local. */
+    resolve(host: string): string | null;
+    isLocal(host: string): boolean;
+    registerListener(port: number, info: Omit<ListeningPort, "port" | "since">): void;
+    unregisterListener(port: number): void;
+    listening(): ListeningPort[];
+    /** Ports Nodepod's proxy has registered for this instance. */
+    private knownPodPorts;
+    /** True when something inside the container answers on `port`. */
+    isPortOpen(port: number, timeoutMs?: number): Promise<boolean>;
+    /** Wait for an in-container server to start answering on `port`. */
+    waitForPort(port: number, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<boolean>;
+    outboundAllowed(url: string): boolean;
+    procNetDev(): string;
+    procNetRoute(): string;
+    countTx(bytes: number, iface?: string): void;
+    countRx(bytes: number, iface?: string): void;
+}
+
+/**
+ * The kernel: the object that owns the filesystem, the process table, the user
+ * database and the executable namespace, and knows how to turn an `argv` into
+ * a running process.
+ *
+ * Executables in `$PATH` are real files. Built-in programs are installed as
+ * tiny stub files whose shebang points at the in-kernel implementation, so
+ * `ls -l /usr/bin/grep`, `which grep` and `file /usr/bin/grep` all behave, and
+ * a user-written script in `/usr/local/bin` is dispatched by exactly the same
+ * lookup path.
+ */
+
+interface KernelOptions {
+    pod: Nodepod;
+    hostname?: string;
+    /** Login user for interactive sessions. Defaults to `root`. */
+    user?: string;
+    env?: Env;
+    /** Total "RAM" reported by `free`, `/proc/meminfo` and `top`. */
+    memoryBytes?: number;
+    /** Simulated CPU count for `nproc` and `/proc/cpuinfo`. */
+    cpus?: number;
+    now?: () => number;
+}
+interface RunOptions {
+    cwd?: string;
+    env?: Env;
+    cred?: Cred;
+    stdin?: InputStream | string | Uint8Array;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    ppid?: number;
+    pgid?: number;
+    kind?: ProcessKind;
+    tty?: string | null;
+    /** Wall-clock budget; the process is sent SIGKILL when it expires. */
+    timeoutMs?: number;
+}
+interface RunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    pid: number;
+    signal: string | null;
+    timedOut: boolean;
+}
+type ExecutableKind = "builtin" | "script" | "unknown";
+interface ResolvedExecutable {
+    kind: ExecutableKind;
+    /** Absolute path of the file that was found. */
+    path: string;
+    /** Present when `kind === "builtin"`. */
+    command?: Command;
+    /** Interpreter argv from a `#!` line, when `kind === "script"`. */
+    interpreter?: string[];
+}
+interface MountEntry {
+    device: string;
+    mountpoint: string;
+    fstype: string;
+    options: string;
+    totalBytes: number;
+}
+declare class Kernel {
+    readonly vfs: Vfs;
+    readonly procs: ProcessTable;
+    readonly commands: CommandRegistry;
+    readonly users: UserDatabase;
+    readonly pod: Nodepod;
+    readonly bootTime: number;
+    readonly memoryBytes: number;
+    readonly cpus: number;
+    readonly now: () => number;
+    /** Populated by the network module once it is attached. */
+    net: NetworkStack;
+    /** init — pid 1, the ancestor of everything. */
+    readonly init: Process;
+    private readonly builtinByPath;
+    private readonly mounts;
+    private disposed;
+    private _current;
+    /**
+     * The process whose builtin is currently on the stack. `/proc/self` resolves
+     * through this. It is set around each dispatch, so a command that reads
+     * `/proc/self/...` synchronously always sees itself.
+     */
+    get currentProcess(): Process | null;
+    constructor(opts: KernelOptions);
+    get hostname(): string;
+    set hostname(value: string);
+    get uptimeMs(): number;
+    addMount(entry: MountEntry): void;
+    removeMount(mountpoint: string): boolean;
+    mountTable(): MountEntry[];
+    /**
+     * Install a command as a real file in `$PATH`. The file holds a shebang that
+     * points at the in-kernel dispatcher, which is what `resolve` looks for.
+     */
+    installCommand(cmd: Command, dir?: string): void;
+    installCommands(cmds: Command[], dir?: string): void;
+    /** Directories from `$PATH`, with a sane fallback. */
+    pathDirs(env: Env): string[];
+    /**
+     * Find `name` the way `execvp` does. Returns null when nothing matches.
+     */
+    resolveExecutable(name: string, cwd: string, env: Env, cred?: Cred): ResolvedExecutable | null;
+    /** `which`-style lookup that only reports the path. */
+    which(name: string, cwd: string, env: Env, cred?: Cred): string | null;
+    /** Every executable name reachable through `$PATH`, for tab completion. */
+    executableNames(env: Env, cred?: Cred): string[];
+    private toInputStream;
+    /**
+     * Create a process for `argv` and start it. Returns the process immediately;
+     * `proc.wait()` resolves with the exit code.
+     */
+    spawn(argv: string[], opts?: RunOptions): Process;
+    /** Run to completion and collect stdout/stderr. */
+    run(argv: string[], opts?: RunOptions): Promise<RunResult>;
+    /**
+     * Resolve `proc.argv` and execute it in-process. Interpreted scripts are
+     * dispatched by re-entering with the interpreter's argv, up to a small depth
+     * so a self-referential shebang cannot loop forever.
+     */
+    private dispatch;
+    /** Convenience for internal callers that just want the text output. */
+    capture(argv: string[], opts?: RunOptions): Promise<string>;
+    dispose(): void;
+    get isDisposed(): boolean;
+    assertActive(): void;
+}
+
+/** Shell syntax tree. Words stay raw; `expand.ts` interprets them. */
+type RedirectOp = ">" | ">>" | "<" | "<>" | ">|" | ">&" | "<&" | "&>" | "&>>" | "<<" | "<<<";
+interface Redirect {
+    op: RedirectOp;
+    /** Source fd, e.g. `2` in `2>file`. Defaults per operator. */
+    fd?: number;
+    /** Target word (a filename, an fd number, or here-doc/string content). */
+    target: string;
+    /** Populated for `<<`. */
+    heredoc?: {
+        body: string;
+        expand: boolean;
+    };
+}
+interface Assignment {
+    name: string;
+    /** Raw value word; undefined for `name=` with nothing after it. */
+    value: string;
+    /** `name+=value`. */
+    append: boolean;
+    /** `name=(a b c)` array literal. */
+    arrayWords?: string[];
+}
+type Node = ListNode | PipelineNode | SimpleCommandNode | SubshellNode | GroupNode | IfNode | ForNode | ForArithNode | WhileNode | CaseNode | FunctionNode | ArithCommandNode | CondNode;
+type ListOperator = ";" | "&" | "&&" | "||";
+interface ListItem {
+    node: Node;
+    /** Operator that *follows* this item. */
+    op: ListOperator;
+}
+interface ListNode {
+    type: "list";
+    items: ListItem[];
+}
+interface PipelineNode {
+    type: "pipeline";
+    commands: Node[];
+    /** `! cmd` inverts the exit status. */
+    negated: boolean;
+    /** `cmd |& next` pipes stderr too. */
+    stderrToo: boolean[];
+    /** `time cmd` */
+    timed?: boolean;
+}
+interface SimpleCommandNode {
+    type: "command";
+    assignments: Assignment[];
+    words: string[];
+    redirects: Redirect[];
+}
+interface SubshellNode {
+    type: "subshell";
+    body: Node;
+    redirects: Redirect[];
+}
+interface GroupNode {
+    type: "group";
+    body: Node;
+    redirects: Redirect[];
+}
+interface IfClause {
+    condition: Node;
+    body: Node;
+}
+interface IfNode {
+    type: "if";
+    clauses: IfClause[];
+    elseBody?: Node;
+    redirects: Redirect[];
+}
+interface ForNode {
+    type: "for";
+    name: string;
+    /** Absent means `for x; do` which iterates `"$@"`. */
+    words?: string[];
+    body: Node;
+    redirects: Redirect[];
+    /** `select` shares the same shape. */
+    select?: boolean;
+}
+interface ForArithNode {
+    type: "for-arith";
+    init: string;
+    condition: string;
+    step: string;
+    body: Node;
+    redirects: Redirect[];
+}
+interface WhileNode {
+    type: "while";
+    condition: Node;
+    body: Node;
+    until: boolean;
+    redirects: Redirect[];
+}
+interface CaseItem {
+    patterns: string[];
+    body: Node | null;
+    /** `;;` stops, `;&` falls through, `;;&` retests. */
+    terminator: ";;" | ";&" | ";;&";
+}
+interface CaseNode {
+    type: "case";
+    word: string;
+    items: CaseItem[];
+    redirects: Redirect[];
+}
+interface FunctionNode {
+    type: "function";
+    name: string;
+    body: Node;
+    redirects: Redirect[];
+}
+interface ArithCommandNode {
+    type: "arith";
+    expression: string;
+    redirects: Redirect[];
+}
+/** `[[ ... ]]` — parsed as a small expression tree of its own. */
+type CondExpr = {
+    type: "unary";
+    op: string;
+    operand: string;
+} | {
+    type: "binary";
+    op: string;
+    left: string;
+    right: string;
+} | {
+    type: "not";
+    operand: CondExpr;
+} | {
+    type: "and";
+    left: CondExpr;
+    right: CondExpr;
+} | {
+    type: "or";
+    left: CondExpr;
+    right: CondExpr;
+} | {
+    type: "word";
+    value: string;
+};
+interface CondNode {
+    type: "cond";
+    expression: CondExpr;
+    redirects: Redirect[];
+}
+
+/**
+ * Shell variable table: scalars, indexed arrays, export/readonly attributes,
+ * and the function-local scoping that `local` introduces.
+ */
+interface VarAttributes {
+    exported?: boolean;
+    readonly?: boolean;
+    integer?: boolean;
+    /** `declare -l` / `-u` case folding. */
+    lower?: boolean;
+    upper?: boolean;
+}
+interface VarEntry extends VarAttributes {
+    value: string;
+    array?: string[];
+    assoc?: Map<string, string>;
+}
+declare class Variables {
+    /** Innermost scope last; index 0 is the global scope. */
+    private readonly scopes;
+    constructor(initial?: Record<string, string>);
+    pushScope(): void;
+    popScope(): void;
+    get depth(): number;
+    private find;
+    has(name: string): boolean;
+    get(name: string): string | undefined;
+    entry(name: string): VarEntry | undefined;
+    getArray(name: string): string[] | undefined;
+    isArray(name: string): boolean;
+    set(name: string, value: string, attrs?: VarAttributes): void;
+    /** Declare in the innermost scope, shadowing outer definitions (`local`). */
+    setLocal(name: string, value: string, attrs?: VarAttributes): void;
+    setArray(name: string, values: string[], attrs?: VarAttributes): void;
+    setIndex(name: string, index: number, value: string): void;
+    append(name: string, value: string): void;
+    unset(name: string): boolean;
+    export(name: string, exported?: boolean): void;
+    markReadonly(name: string): void;
+    names(): string[];
+    /** The environment handed to a child process. */
+    environment(): Record<string, string>;
+    /** Every variable with its attributes, for `declare -p` / `set`. */
+    all(): Array<{
+        name: string;
+        entry: VarEntry;
+    }>;
+}
+
+/**
+ * POSIX path helpers. Deliberately independent of `node:path` so container
+ * paths behave identically no matter what platform the host runs on.
+ */
+declare const SEP = "/";
+declare function isAbsolute(p: string): boolean;
+/** Split into non-empty segments, dropping the leading/trailing slashes. */
+declare function segments(p: string): string[];
+/**
+ * Lexical normalisation: collapse `//`, resolve `.` and `..` without touching
+ * the filesystem. Symlinks are *not* followed — that is `Vfs.realpath`'s job.
+ */
+declare function normalize(p: string): string;
+/** Join fragments then normalise, like `path.posix.join`. */
+declare function join(...parts: string[]): string;
+/** Resolve `p` against `base` (usually a process cwd) to an absolute path. */
+declare function resolve(base: string, ...parts: string[]): string;
+declare function dirname(p: string): string;
+declare function basename(p: string, ext?: string): string;
+declare function extname(p: string): string;
+/** Relative path from `from` to `to`, both assumed absolute + normalised. */
+declare function relative(from: string, to: string): string;
+/** True when `child` is `parent` or lives beneath it. */
+declare function contains(parent: string, child: string): boolean;
+/** Drop a trailing slash except on the root, for display and map keys. */
+declare function clean(p: string): string;
+
+declare const path_SEP: typeof SEP;
+declare const path_basename: typeof basename;
+declare const path_clean: typeof clean;
+declare const path_contains: typeof contains;
+declare const path_dirname: typeof dirname;
+declare const path_extname: typeof extname;
+declare const path_isAbsolute: typeof isAbsolute;
+declare const path_join: typeof join;
+declare const path_normalize: typeof normalize;
+declare const path_relative: typeof relative;
+declare const path_resolve: typeof resolve;
+declare const path_segments: typeof segments;
+declare namespace path {
+  export { path_SEP as SEP, path_basename as basename, path_clean as clean, path_contains as contains, path_dirname as dirname, path_extname as extname, path_isAbsolute as isAbsolute, path_join as join, path_normalize as normalize, path_relative as relative, path_resolve as resolve, path_segments as segments };
+}
+
+/**
+ * Word expansion, in the order POSIX specifies:
+ *
+ *   brace → tilde → parameter/command/arithmetic → field splitting →
+ *   pathname → quote removal
+ *
+ * The tricky part is that only text produced by *unquoted* expansions may be
+ * field-split, and only unquoted text may be globbed. Each fragment therefore
+ * carries `split` and `glob` flags through the pipeline, and quote removal is
+ * the last thing that happens.
+ */
+
+interface ExpandContext {
+    vars: Variables;
+    /** `$1`, `$2`, … */
+    positional: string[];
+    /** `$0` */
+    scriptName: string;
+    /** `$?` */
+    lastStatus: number;
+    /** `$$` */
+    shellPid: number;
+    /** `$!` */
+    lastBackgroundPid: number;
+    /** `$-` */
+    optionFlags: string;
+    cwd: string;
+    vfs: Vfs;
+    cred: Cred;
+    /** Home directory lookup for `~user`. */
+    homeFor(user: string): string | undefined;
+    /** Runs a command substitution and returns its stdout. */
+    runSubstitution(command: string): Promise<string>;
+    /** Materialises `<(cmd)` / `>(cmd)` as a path. Optional. */
+    processSubstitution?(command: string, direction: "in" | "out"): Promise<string>;
+    /** `set -u` */
+    nounset?: boolean;
+    /** `set -f` */
+    noglob?: boolean;
+    /** Extended globbing (`shopt -s extglob`). */
+    extglob?: boolean;
+    /** Include dotfiles in globs (`shopt -s dotglob`). */
+    dotglob?: boolean;
+    /** Leave an unmatched glob as-is (bash default) or drop it (`nullglob`). */
+    nullglob?: boolean;
+    /** Error out on an unmatched glob (`failglob`). */
+    failglob?: boolean;
+}
+/** Full expansion of a list of words, as used for command arguments. */
+declare function expandWords(words: string[], ctx: ExpandContext): Promise<string[]>;
+/** Expand one word into zero or more fields. */
+declare function expandWord(word: string, ctx: ExpandContext): Promise<string[]>;
+/** `a{b,c}d` → `abd acd`; `{1..5}` and `{a..e}` sequences too. */
+declare function braceExpand(word: string): string[];
+declare function shellQuote(value: string): string;
+
+/** Registry of shell builtins. Lookup order in the interpreter is: function, builtin, then `$PATH`. */
+
+interface BuiltinContext {
+    shell: Shell;
+    /** Full argv, including argv[0]. */
+    argv: string[];
+    io: ShellIO;
+}
+type Builtin = (ctx: BuiltinContext) => Promise<number> | number;
+declare function getBuiltin(name: string): Builtin | undefined;
+declare function isBuiltinName(name: string): boolean;
+declare function builtinNames(): string[];
+
+/**
+ * The shell interpreter.
+ *
+ * Walks the syntax tree, applies redirections, wires pipelines together, and
+ * dispatches each simple command to a function, a builtin, or the kernel's
+ * executable lookup — in that order, which is the order bash uses.
+ */
+
+interface ShellIO {
+    stdin: InputStream;
+    stdout: OutputStream;
+    stderr: OutputStream;
+}
+interface ShellOptions {
+    /** `set -e` */
+    errexit: boolean;
+    /** `set -u` */
+    nounset: boolean;
+    /** `set -x` */
+    xtrace: boolean;
+    /** `set -v` */
+    verbose: boolean;
+    /** `set -f` */
+    noglob: boolean;
+    /** `set -o pipefail` */
+    pipefail: boolean;
+    /** `set -n` */
+    noexec: boolean;
+    /** `set -m` */
+    monitor: boolean;
+    /** `set -C` */
+    noclobber: boolean;
+    /** `set -a` */
+    allexport: boolean;
+    /** Interactive shells print prompts and keep history. */
+    interactive: boolean;
+    /** Login shells source `/etc/profile`. */
+    login: boolean;
+}
+interface Job {
+    id: number;
+    pgid: number;
+    command: string;
+    state: "running" | "done" | "stopped";
+    exitCode: number | null;
+    promise: Promise<number>;
+    pids: number[];
+}
+declare class ShellExit {
+    readonly code: number;
+    constructor(code: number);
+}
+interface ShellInit {
+    kernel: Kernel;
+    proc: Process;
+    cwd?: string;
+    env?: Record<string, string>;
+    cred?: Cred;
+    options?: Partial<ShellOptions>;
+    positional?: string[];
+    scriptName?: string;
+}
+declare class Shell {
+    readonly kernel: Kernel;
+    readonly proc: Process;
+    readonly vars: Variables;
+    readonly functions: Map<string, Node>;
+    readonly aliases: Map<string, string>;
+    readonly traps: Map<string, string>;
+    readonly dirStack: string[];
+    readonly jobs: Job[];
+    readonly history: string[];
+    options: ShellOptions;
+    shopts: Set<string>;
+    positional: string[];
+    scriptName: string;
+    lastStatus: number;
+    lastBackgroundPid: number;
+    cwd: string;
+    cred: Cred;
+    /** Pipeline exit statuses, exposed as `PIPESTATUS`. */
+    pipeStatus: number[];
+    private nextJobId;
+    private functionDepth;
+    private tempFileCounter;
+    private exiting;
+    constructor(init: ShellInit);
+    /** Parse and run a script fragment. Returns the last exit status. */
+    execute(source: string, io: ShellIO): Promise<number>;
+    get isExiting(): boolean;
+    /** True when `source` is not yet a complete command (for REPL continuation). */
+    static isIncomplete(source: string): boolean;
+    expandContext(): ExpandContext;
+    optionFlagString(): string;
+    /** Run `command` in a subshell and return its stdout. */
+    captureSubshell(command: string): Promise<string>;
+    /** `<(cmd)` — run the command now and hand back a path holding its output. */
+    private makeProcessSubstitution;
+    /** A copy that shares nothing mutable with this shell. */
+    fork(): Shell;
+    private currentIO;
+    run(node: Node, io: ShellIO): Promise<number>;
+    private runList;
+    /** Skip past short-circuited members of an `&&`/`||` chain. */
+    private skipChain;
+    private runPipeline;
+    /**
+     * Every stage of a pipeline runs in its own subshell in bash. Sharing the
+     * variable table would let `echo x | read v` leak `v` into the parent.
+     */
+    private forkForPipeline;
+    private reportTime;
+    private startBackgroundJob;
+    private runSubshell;
+    private runGroup;
+    private runIf;
+    /** Conditions are exempt from `set -e`. */
+    private runCondition;
+    private runFor;
+    private runSelect;
+    private runForArith;
+    private runWhile;
+    private runCase;
+    private runFunctionDefinition;
+    private runArithCommand;
+    private runCond;
+    private evalCond;
+    private runSimpleCommand;
+    private reportCommandError;
+    /** One level of alias substitution on the command word. */
+    private substituteAlias;
+    private invoke;
+    private callFunction;
+    private runExternal;
+    /** `VAR=x cmd` — set for the duration, then restore. */
+    private applyTemporaryAssignments;
+    applyAssignment(assignment: SimpleCommandNode["assignments"][number], exported: boolean): Promise<void>;
+    applyRedirects(redirects: Redirect[], io: ShellIO): Promise<{
+        io: ShellIO;
+        cleanup: () => void;
+    }>;
+    private openInput;
+    private openOutput;
+    private expandHeredoc;
+    setTrap(signal: string, action: string): void;
+    runTrap(signal: string, io: ShellIO): Promise<void>;
+    changeDirectory(target: string): void;
+    throwBreak(levels: number): never;
+    throwContinue(levels: number): never;
+    throwReturn(code: number): never;
+    throwExit(code: number): never;
+    addJob(job: Job): void;
+    reapJobs(): Job[];
+}
+
+/**
+ * A promise-based filesystem façade for host code, shaped like `fs/promises`
+ * so it reads naturally from the outside.
+ */
+
+declare class ContainerFs {
+    private readonly kernel;
+    constructor(kernel: Kernel);
+    private get vfs();
+    readFile(path: string): Promise<Uint8Array>;
+    readFile(path: string, encoding: "utf8" | "utf-8"): Promise<string>;
+    writeFile(path: string, data: string | Uint8Array, opts?: {
+        mode?: number;
+    }): Promise<void>;
+    appendFile(path: string, data: string | Uint8Array): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdir(path: string, opts: {
+        withFileTypes: true;
+    }): Promise<DirEntry[]>;
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    rm(path: string, opts?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    copyFile(from: string, to: string): Promise<void>;
+    stat(path: string): Promise<Stats>;
+    lstat(path: string): Promise<Stats>;
+    exists(path: string): Promise<boolean>;
+    symlink(target: string, link: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    /** Every path beneath `root`, depth-first. */
+    walk(root?: string): Promise<string[]>;
+    /** Total bytes and file counts, as `df` reports them. */
+    usage(root?: string): Promise<{
+        files: number;
+        dirs: number;
+        bytes: number;
+    }>;
+    /** Read many files at once, keyed by path. */
+    readAll(paths: string[]): Promise<Record<string, string>>;
+    /** Write a whole map of files, creating parents. */
+    writeAll(files: Record<string, string | Uint8Array>, opts?: {
+        cwd?: string;
+    }): Promise<void>;
+}
+
+/**
+ * A stateful shell session — `cd`, variables, functions and history persist
+ * across calls, the way a terminal does. `Container.exec` is deliberately
+ * stateless; this is the other half.
+ */
+
+interface SessionInit {
+    cwd: string;
+    env: Record<string, string>;
+    cred: Cred;
+    hooks?: {
+        onStdout?: (chunk: string) => void;
+        onStderr?: (chunk: string) => void;
+    };
+}
+interface SessionRunOptions {
+    stdin?: string | Uint8Array | InputStream;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    timeoutMs?: number;
+    /** Present the session as attached to a terminal. */
+    tty?: boolean;
+    columns?: number;
+    rows?: number;
+}
+interface SessionResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    output: string;
+}
+declare class Session {
+    private readonly kernel;
+    readonly shell: Shell;
+    readonly proc: Process;
+    private closed;
+    constructor(kernel: Kernel, init: SessionInit);
+    private readonly hooks;
+    get cwd(): string;
+    get env(): Record<string, string>;
+    get history(): string[];
+    /** Run a command line, keeping every side effect for the next call. */
+    run(command: string, opts?: SessionRunOptions): Promise<SessionResult>;
+    /** Stream a long-running command; resolves when it exits. */
+    stream(command: string, handlers?: {
+        onStdout?: (chunk: string) => void;
+        onStderr?: (chunk: string) => void;
+    }): Promise<number>;
+    /** Feed the session an arbitrary output stream, for terminal integration. */
+    pipeTo(command: string, stdout: OutputStream, stderr: OutputStream, stdin?: InputStream): Promise<number>;
+    /** True when the last command asked the shell to exit. */
+    get isExiting(): boolean;
+    close(): void;
+}
+
+/**
+ * The public surface: a Linux-like container you can boot inside any Node
+ * process, run commands in, and throw away.
+ *
+ * ```ts
+ * const box = await createContainer({ files: { "/app/index.js": "console.log(1)" } });
+ * await box.exec("node /app/index.js");
+ * ```
+ */
+
+interface ContainerOptions {
+    /**
+     * Files to seed the filesystem with, keyed by absolute (or `cwd`-relative)
+     * path. Parent directories are created automatically — this is the fast way
+     * to drop a whole project in and run it.
+     */
+    files?: Record<string, string | Uint8Array>;
+    /** Directory `files` keys are resolved against, and the default cwd. Default `/`. */
+    cwd?: string;
+    hostname?: string;
+    /**
+     * Login user. `"root"` (default) runs privileged; any other name is created
+     * with uid 1000 and sudo rights. Pass `null` for a root-only image.
+     */
+    user?: string | null;
+    env?: Record<string, string>;
+    /** RAM reported by `free`, `top` and `/proc/meminfo`. Default 2 GiB. */
+    memory?: number;
+    /** CPU count reported by `nproc` and `/proc/cpuinfo`. Default 4. */
+    cpus?: number;
+    network?: NetworkOptions;
+    timezone?: string;
+    /** Default wall-clock limit for `exec`. Omit for no limit. */
+    timeoutMs?: number;
+    /** Called for every byte any command writes to stdout, across the container. */
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    /** Invoked when an in-container HTTP server starts listening. */
+    onServerReady?: (port: number, url: string) => void;
+}
+interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Run as this user instead of the container default. */
+    user?: string;
+    stdin?: string | Uint8Array;
+    /** Stream output as it is produced, in addition to buffering it. */
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    timeoutMs?: number;
+    /** Report the command as running on a terminal (affects `ls` colour, `-t`). */
+    tty?: boolean;
+    columns?: number;
+    rows?: number;
+}
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** stdout and stderr interleaved in write order. */
+    output: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+interface SpawnHandle {
+    pid: number;
+    stdin: Pipe;
+    stdout: Pipe;
+    stderr: Pipe;
+    /** Resolves with the exit code. */
+    wait(): Promise<number>;
+    kill(signal?: string): void;
+    readonly exitCode: number | null;
+}
+interface HttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    bytes: Uint8Array;
+    json<T = unknown>(): T;
+}
+declare class Container {
+    readonly kernel: Kernel;
+    readonly pod: Nodepod;
+    readonly fs: ContainerFs;
+    readonly net: NetworkStack;
+    private readonly defaults;
+    private readonly hooks;
+    private disposed;
+    private defaultSession;
+    private constructor();
+    static create(opts?: ContainerOptions): Promise<Container>;
+    /**
+     * Drop a map of files into the container. Keys may be absolute or relative
+     * to `opts.cwd`; parent directories are created as needed.
+     */
+    mount(files: Record<string, string | Uint8Array>, opts?: {
+        cwd?: string;
+        mode?: number;
+    }): this;
+    private mountSync;
+    /** Copy a directory tree from the host filesystem into the container. */
+    copyIn(hostPath: string, containerPath: string): Promise<void>;
+    /** Copy a file or directory out of the container onto the host. */
+    copyOut(containerPath: string, hostPath: string): Promise<void>;
+    /** Run a shell command line and collect its output. */
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /** Run a program directly, without a shell parsing the arguments. */
+    run(argv: string[], opts?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Start a command and get streams back, for long-running processes such as a
+     * dev server that you want to watch and later kill.
+     */
+    spawn(command: string, opts?: ExecOptions): SpawnHandle;
+    /**
+     * A stateful shell session: `cd`, variables and functions persist between
+     * calls, the way a terminal behaves.
+     */
+    session(opts?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        user?: string;
+    }): Session;
+    /** The container-wide session used by `shell()` shorthand helpers. */
+    get shell(): Session;
+    private makeStdio;
+    /** Send an HTTP request to a server running inside the container. */
+    request(port: number, init?: {
+        method?: string;
+        path?: string;
+        headers?: Record<string, string>;
+        body?: string | Uint8Array;
+    }): Promise<HttpResponse>;
+    /** Wait until something inside the container answers on `port`. */
+    waitForPort(port: number, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<boolean>;
+    /**
+     * Bridge a container port onto a real host port, so a browser (or anything
+     * else on your machine) can reach a dev server running inside the sandbox.
+     */
+    expose(port: number, opts?: {
+        hostPort?: number;
+        hostname?: string;
+    }): Promise<{
+        url: string;
+        port: number;
+        close(): Promise<void>;
+    }>;
+    /** A serialisable snapshot of the whole filesystem. */
+    snapshot(opts?: {
+        shallow?: boolean;
+    }): unknown;
+    restore(snapshot: unknown): Promise<void>;
+    get hostname(): string;
+    get user(): string;
+    get cwd(): string;
+    get env(): Record<string, string>;
+    private assertActive;
+    /** Tear down every process and release the Nodepod instance. */
+    dispose(): void;
+    get isDisposed(): boolean;
+}
+/** Boot a container. The one function most callers need. */
+declare function createContainer(opts?: ContainerOptions): Promise<Container>;
+
+/**
+ * An interactive terminal on top of a `Session`.
+ *
+ * Deliberately transport-agnostic: feed it keystrokes with `input()` and it
+ * calls `write()` with what should appear on screen. That works equally well
+ * for a real TTY (the `sandboxedjs` CLI) and for xterm.js in a browser app.
+ *
+ * Provides line editing, history, tab completion over commands and paths,
+ * multi-line continuation for unfinished commands, and the usual control keys.
+ */
+
+interface TerminalOptions {
+    /** Called with text to display. */
+    write(data: string): void;
+    columns?: number;
+    rows?: number;
+    /** Overrides `$PS1` when provided. */
+    prompt?: (session: Session) => string;
+    /** Print `/etc/motd` when the terminal starts. Default true. */
+    motd?: boolean;
+    /** Invoked after the shell exits. */
+    onExit?: (code: number) => void;
+}
+declare class Terminal {
+    private readonly session;
+    private readonly opts;
+    private buffer;
+    private cursor;
+    private pending;
+    private historyIndex;
+    private savedLine;
+    private running;
+    private closed;
+    private escapeBuffer;
+    private currentStdin;
+    private exitCode;
+    columns: number;
+    rows: number;
+    constructor(session: Session, opts: TerminalOptions);
+    /** Print the banner and the first prompt. */
+    start(): void;
+    resize(columns: number, rows: number): void;
+    /** Feed raw keystrokes. */
+    input(data: string): void;
+    close(): void;
+    get isClosed(): boolean;
+    private write;
+    private promptText;
+    private writePrompt;
+    /** Repaint the current line after an edit. */
+    private redraw;
+    private key;
+    private handleEscape;
+    private recallHistory;
+    private complete;
+    private completeCommand;
+    private completePath;
+    private submit;
+    private execute;
+}
+/** Expand a `PS1`-style prompt string. */
+declare function expandPrompt(format: string, session: Session): string;
+
+/** POSIX signal numbers, names and default dispositions. */
+declare const SIGNALS: Record<string, number>;
+declare const SIGNAL_NAMES: Record<number, string>;
+/**
+ * Normalise anything `kill` might be handed — `9`, `TERM`, `SIGTERM`, `-9` —
+ * into a canonical `SIGxxx` name. Returns null when unrecognised.
+ */
+declare function normalizeSignal(spec: string | number): string | null;
+/** The `$?` value a shell reports for a process killed by `sig`. */
+declare function exitCodeForSignal(sig: string): number;
+
+/**
+ * The identity the container reports for itself.
+ *
+ * The release string deliberately matches what Nodepod's `os.release()` returns
+ * inside a spawned Node process, so `uname -r` and
+ * `node -p "os.release()"` agree.
+ */
+declare const KERNEL_NAME = "Linux";
+declare const KERNEL_RELEASE = "5.10.0";
+declare const OS_RELEASE = "PRETTY_NAME=\"SandboxedJS 1.0 (nodepod)\"\nNAME=\"SandboxedJS\"\nVERSION_ID=\"1.0\"\nVERSION=\"1.0 (nodepod)\"\nVERSION_CODENAME=nodepod\nID=sandboxedjs\nID_LIKE=debian\nHOME_URL=\"https://github.com/R1ck404/Nodepod\"\nSUPPORT_URL=\"https://www.npmjs.com/package/sandboxedjs\"\n";
+interface UnameInfo {
+    sysname: string;
+    nodename: string;
+    release: string;
+    version: string;
+    machine: string;
+    processor: string;
+    hardwarePlatform: string;
+    operatingSystem: string;
+}
+declare function unameInfo(hostname: string): UnameInfo;
+
+/**
+ * Linux errno numbers and the `SysError` type every syscall-ish helper throws.
+ *
+ * The numbers match Linux x86-64 so that programs which print `err.errno`
+ * (or read `$?` after a failed syscall) see the values they would on a real box.
+ */
+declare const ERRNO: {
+    readonly EPERM: 1;
+    readonly ENOENT: 2;
+    readonly ESRCH: 3;
+    readonly EINTR: 4;
+    readonly EIO: 5;
+    readonly ENXIO: 6;
+    readonly E2BIG: 7;
+    readonly ENOEXEC: 8;
+    readonly EBADF: 9;
+    readonly ECHILD: 10;
+    readonly EAGAIN: 11;
+    readonly ENOMEM: 12;
+    readonly EACCES: 13;
+    readonly EFAULT: 14;
+    readonly ENOTBLK: 15;
+    readonly EBUSY: 16;
+    readonly EEXIST: 17;
+    readonly EXDEV: 18;
+    readonly ENODEV: 19;
+    readonly ENOTDIR: 20;
+    readonly EISDIR: 21;
+    readonly EINVAL: 22;
+    readonly ENFILE: 23;
+    readonly EMFILE: 24;
+    readonly ENOTTY: 25;
+    readonly ETXTBSY: 26;
+    readonly EFBIG: 27;
+    readonly ENOSPC: 28;
+    readonly ESPIPE: 29;
+    readonly EROFS: 30;
+    readonly EMLINK: 31;
+    readonly EPIPE: 32;
+    readonly EDOM: 33;
+    readonly ERANGE: 34;
+    readonly EDEADLK: 35;
+    readonly ENAMETOOLONG: 36;
+    readonly ENOLCK: 37;
+    readonly ENOSYS: 38;
+    readonly ENOTEMPTY: 39;
+    readonly ELOOP: 40;
+    readonly ENOMSG: 42;
+    readonly ENOTSOCK: 88;
+    readonly EADDRINUSE: 98;
+    readonly EADDRNOTAVAIL: 99;
+    readonly ENETDOWN: 100;
+    readonly ECONNRESET: 104;
+    readonly ENOTCONN: 107;
+    readonly ETIMEDOUT: 110;
+    readonly ECONNREFUSED: 111;
+    readonly EHOSTUNREACH: 113;
+    readonly ENOTSUP: 95;
+};
+type ErrnoCode = keyof typeof ERRNO;
+/** An error carrying the same shape Node uses for `fs` failures. */
+declare class SysError extends Error {
+    readonly code: ErrnoCode;
+    readonly errno: number;
+    readonly syscall: string;
+    readonly path?: string;
+    readonly dest?: string;
+    constructor(code: ErrnoCode, syscall: string, path?: string, dest?: string);
+    /** The message a coreutil prints: `ls: /nope: No such file or directory`. */
+    toUserMessage(program: string, subject?: string | undefined): string;
+}
+declare function isSysError(e: unknown): e is SysError;
+declare function strerror(code: ErrnoCode): string;
+
+/**
+ * Pattern matching: `fnmatch(3)` semantics for `case`/`find -name`, plus the
+ * pathname expansion the shell performs on unquoted words.
+ */
+
+interface MatchOptions {
+    /** `*` and `?` stop at `/` (shell pathname expansion). */
+    pathname?: boolean;
+    /** Match leading dots with wildcards (shell `dotglob`). */
+    dot?: boolean;
+    /** Case-insensitive comparison. */
+    nocase?: boolean;
+    /** Enable ksh-style `?(a|b)`, `*(a|b)`, `+(...)`, `@(...)`, `!(...)`. */
+    extglob?: boolean;
+}
+declare function globToRegex(pattern: string, opts?: MatchOptions): RegExp;
+/** `fnmatch(3)`. */
+declare function fnmatch(pattern: string, str: string, opts?: MatchOptions): boolean;
+/** True when the word contains an unescaped glob metacharacter. */
+declare function hasMagic(word: string, extglob?: boolean): boolean;
+interface GlobOptions extends MatchOptions {
+    cwd?: string;
+    cred?: Cred;
+    /** Only return paths that are directories (trailing `/` in the pattern). */
+    onlyDirs?: boolean;
+    /** Cap on results, to keep a runaway `/**` from exhausting memory. */
+    limit?: number;
+}
+/**
+ * Pathname expansion against the container filesystem. Returns absolute paths
+ * when the pattern is absolute, otherwise paths relative to `cwd` — matching
+ * how the shell substitutes the results back into the command line.
+ */
+declare function glob(vfs: Vfs, pattern: string, opts?: GlobOptions): string[];
+
+/**
+ * Shell tokenizer.
+ *
+ * Words are kept as *raw* text with their quotes intact — expansion happens
+ * later, in `expand.ts`, which is the only stage that needs to distinguish
+ * `"$x"` from `$x`. The lexer's job is to find word boundaries correctly in the
+ * presence of quoting, `$(...)`, backticks and `${...}`, and to pull here-doc
+ * bodies out of the stream at the right moment.
+ */
+type TokenType = "word" | "op" | "newline" | "eof" | "io_number";
+interface HeredocInfo {
+    tag: string;
+    /** `<<-` strips leading tabs from the body and the delimiter line. */
+    stripTabs: boolean;
+    /** A quoted tag disables expansion inside the body. */
+    quoted: boolean;
+    body: string;
+}
+interface Token {
+    type: TokenType;
+    value: string;
+    pos: number;
+    /** Attached to the `<<` operator token once the body has been collected. */
+    heredoc?: HeredocInfo;
+}
+declare class ShellSyntaxError extends Error {
+    readonly pos: number;
+    constructor(message: string, pos: number);
+}
+/** Thrown when input ends mid-construct, so a REPL can ask for another line. */
+declare class IncompleteInputError extends ShellSyntaxError {
+    constructor(message: string, pos: number);
+}
+declare class Lexer {
+    private readonly src;
+    private pos;
+    private readonly tokens;
+    /** Here-docs whose bodies are collected when the current line ends. */
+    private pendingHeredocs;
+    constructor(src: string);
+    static tokenize(src: string): Token[];
+    run(): Token[];
+    private push;
+    /** True when `prev` ends exactly where the current operator begins. */
+    private adjacent;
+    private skipBlanks;
+    private matchOperator;
+    private readWord;
+    private readDoubleQuoted;
+    /**
+     * Consume a balanced `$( ... )` or `${ ... }`, honouring nesting and quotes
+     * inside. `prefix` is emitted before the opening delimiter.
+     */
+    private readBalanced;
+    private skipDoubleQuoted;
+    private findBacktickEnd;
+    /**
+     * Called right after a newline: read the bodies of every here-doc whose
+     * operator appeared on the line just finished.
+     */
+    private collectHeredocs;
+}
+
+/**
+ * Recursive-descent parser for the shell grammar.
+ *
+ * Covers the POSIX command language plus the bash extensions that scripts in
+ * the wild actually depend on: `[[ ]]`, `(( ))`, `function name { }`,
+ * `for ((;;))`, `select`, `|&`, `&>`, `<<<`, and `;&`/`;;&` in `case`.
+ */
+
+declare function parse(source: string): Node;
+
+/**
+ * Arithmetic expansion — the `$(( ... ))` and `(( ... ))` evaluator.
+ *
+ * Implements the C-like operator set bash supports, including assignment,
+ * pre/post increment, the ternary, comma, and `base#digits` literals. Values
+ * are integers; division by zero is an error, as it is in bash.
+ */
+interface ArithScope {
+    get(name: string): string | undefined;
+    set(name: string, value: string): void;
+}
+declare class ArithError extends Error {
+    constructor(message: string);
+}
+declare function evalArith(expression: string, scope: ArithScope): number;
+
+/**
+ * The userland: every program installed into `$PATH` at boot.
+ *
+ * Each command is a real file under `/bin`, `/sbin` or `/usr/bin`, so `which`,
+ * `ls -l /usr/bin` and shebang dispatch all behave the way they do on a real
+ * system.
+ */
+
+/** Every command, in installation order. */
+declare function allCommands(): Command[];
+/**
+ * Install the userland into a kernel. Commands declaring their own `path` land
+ * there; everything else goes to `/usr/bin`, with `/bin` and `/sbin` symlinked
+ * the way merged-`/usr` distributions do.
+ */
+declare function installUserland(kernel: Kernel): void;
+
+/**
+ * The root filesystem image.
+ *
+ * Everything here is a real file in the volume, not a special case in code —
+ * `/etc/passwd` is what `id` reads, `/etc/profile` is what a login shell
+ * sources, and `/etc/os-release` is what `lsb_release` parses. Editing them
+ * inside the container changes behaviour, exactly as it would on a real box.
+ */
+
+interface RootfsOptions {
+    hostname?: string;
+    /** Non-root login user created at boot. Pass null for a root-only image. */
+    user?: {
+        name: string;
+        uid?: number;
+        gid?: number;
+        home?: string;
+        shell?: string;
+    } | null;
+    timezone?: string;
+}
+declare function buildRootfs(vfs: Vfs, opts?: RootfsOptions): void;
+
+/**
+ * The Node.js runtime, backed by Nodepod.
+ *
+ * Nodepod runs the script in an isolated worker over the *same* memory volume
+ * the container's filesystem uses, so `require('fs')` inside a script sees the
+ * files `echo` and `tar` created, and anything the script writes is visible to
+ * the shell afterwards.
+ *
+ * Two gaps in the underlying `spawn` are papered over here:
+ *  - only `node` resolves as a command, so everything else is dispatched by our
+ *    own kernel rather than being handed to Nodepod's shell (which hangs on an
+ *    unknown command);
+ *  - the worker's stdin has no end-of-stream signal, so when a pipeline feeds
+ *    a script we materialise stdin as a file and install a real stdin stream
+ *    over it before the script loads.
+ */
+
+declare const NODE_VERSION = "v22.12.0";
+
+/**
+ * The Python runtime: MicroPython compiled to WebAssembly, wired to the
+ * container's filesystem, argv, environment and standard streams.
+ *
+ * A fresh interpreter is created per process, which is both correct (no state
+ * leaks between runs) and cheap — the WASM module is compiled once and reused,
+ * so subsequent instantiations take single-digit milliseconds.
+ */
+
+declare const PYTHON_VERSION = "3.4.0";
+/** True when a Python interpreter can be started in this process. */
+declare function isPythonAvailable(): Promise<boolean>;
+
+/**
+ * Package managers: `npm`/`npx`/`yarn`/`pnpm` on top of Nodepod's installer,
+ * and an `apt`-shaped front end for the things a container image would ship.
+ */
+
+declare const NPM_VERSION = "10.9.0";
+
+/**
+ * sandboxedjs — a Linux-like container that runs entirely inside Node.js.
+ *
+ * ```ts
+ * import { createContainer } from "sandboxedjs";
+ *
+ * const box = await createContainer({
+ *   files: { "/app/server.js": "require('http').createServer(...).listen(3000)" },
+ * });
+ *
+ * await box.exec("ls -la /app");
+ * await box.exec("python3 -c 'print(sum(range(101)))'");
+ * box.spawn("node /app/server.js");
+ * await box.waitForPort(3000);
+ * const res = await box.request(3000, { path: "/" });
+ * ```
+ */
+
+export { ArithError, BufferSink, CallbackSink, type Command, CommandRegistry, Container, ContainerFs, type ContainerOptions, type ContextInit, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type ExecContext, type ExecOptions, type ExecResult, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, type MountEntry, NODE_VERSION, NPM_VERSION, type NetInterface, type NetworkOptions, NetworkStack, NullInput, NullOutput, OS_RELEASE, type OutputStream, PYTHON_VERSION, type PasswdEntry, Pipe, Process, type ProcessKind, type ProcessOptions, type ProcessState, ProcessTable, ROOT_CRED, type ResolvedExecutable, type RootfsOptions, type RunOptions, type RunResult, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, type VirtualNode, type VirtualProvider, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, createContainer, createContext, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isPythonAvailable, isSysError, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, resetPidCounter, shellQuote, strerror, unameInfo };