sandboxedjs 0.1.48 → 0.1.49

package/dist/vfs-DzEcPbMY.d.ts

@@ -0,0 +1,427 @@
+/** The handle a pod's process manager returns. */
+interface ChildHandle {
+    pid: number;
+    state: "starting" | "running" | "exited";
+    exitCode: number | undefined;
+    on(event: "stdout" | "stderr" | "exit" | "rawmode", listener: (...args: any[]) => void): unknown;
+    exec(): void;
+    sendStdin(data: string): void;
+    /**
+     * Close the child's input.
+     *
+     * Without this a child that reads stdin to EOF — every filter, and every
+     * tool a library pipes into, `xsel` and `base64` alike — waits forever for
+     * an end that never comes, and the parent waits on its exit.
+     */
+    endStdin?(): void;
+    kill(signal?: string): void;
+}
+interface ChildSpawnConfig {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    parentPid?: number;
+    /**
+     * The child was given the parent's streams (`stdio: "inherit"`).
+     *
+     * Its input is then the parent's terminal rather than a pipe that will end,
+     * which is the difference between a program that waits for what the user
+     * types and one that reads to end-of-input and stops.
+     */
+    inheritStdio?: boolean;
+    /**
+     * The child was told to ignore its input (`stdio: "ignore"`).
+     *
+     * It then has no input at all, so its stdin is closed at once rather than
+     * left open on a parent that will never write to it.
+     */
+    stdinIgnored?: boolean;
+}
+type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
+/**
+ * Run a child to completion without returning to the event loop.
+ *
+ * Supplied only by a pod that can actually block — one whose guest runs on its
+ * own thread. Where it is absent the synchronous entry points keep reporting
+ * that they are unavailable, which is the honest answer for an in-realm pod.
+ */
+type SyncSpawn = (request: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    input?: string;
+    inheritStdio?: boolean;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    signal: string | null;
+    error?: {
+        code?: string;
+        message: string;
+    };
+};
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn, defaultEnv?: () => Record<string, string>): Record<string, unknown>;
+
+/**
+ * Clean-room contracts between SandboxedJS and its JavaScript runtime.
+ *
+ * These deliberately describe only behavior SandboxedJS consumes. Runtime
+ * implementations may use Web Workers in browsers or worker_threads on Node.
+ */
+
+interface VolumeStats {
+    totalBytes: number;
+    fileCount: number;
+    /** New runtime spelling. */
+    directoryCount?: number;
+    /** Compatibility spelling used by existing volume implementations. */
+    dirCount?: number;
+}
+interface VolumeStat {
+    mode: number;
+    size: number;
+    uid: number;
+    gid: number;
+    ino: number;
+    nlink: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+interface RuntimeVolume {
+    readFileSync(path: string): Uint8Array;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    appendFileSync(path: string, data: string | Uint8Array): void;
+    readdirSync(path: string): string[];
+    lstatSync(path: string): VolumeStat;
+    readlinkSync(path: string): string;
+    mkdirSync(path: string, options?: {
+        mode?: number;
+    }): void;
+    rmdirSync(path: string): void;
+    unlinkSync(path: string): void;
+    renameSync(from: string, to: string): void;
+    symlinkSync(target: string, path: string): void;
+    linkSync(existing: string, path: string): void;
+    truncateSync(path: string, length?: number): void;
+    chmodSync(path: string, mode: number): void;
+    lchmodSync(path: string, mode: number): void;
+    chownSync(path: string, uid: number, gid: number): void;
+    lchownSync(path: string, uid: number, gid: number): void;
+    utimesSync(path: string, atime: Date, mtime: Date): void;
+    getStats(): VolumeStats;
+}
+interface RuntimeProcessResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface RuntimeProcess {
+    readonly completion: Promise<RuntimeProcessResult>;
+    /**
+     * `output` and `error` carry stdout and stderr; `exit` the code. `rawmode`
+     * reports the program turning terminal raw mode on or off, which a terminal
+     * needs so that it stops echoing input the program is drawing itself.
+     */
+    on(event: "output" | "error" | "exit" | "rawmode", listener: (...args: any[]) => void): this;
+    write(data: string): void;
+    kill(signal?: string): void;
+}
+interface RuntimeHttpResponse {
+    statusCode?: number;
+    statusMessage?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array | ArrayBuffer;
+}
+interface RuntimePackageInstaller {
+    install(name: string, version?: string, options?: Record<string, unknown>): Promise<unknown>;
+    installFromManifest(path: string, options?: Record<string, unknown>): Promise<unknown>;
+    /** Create a view that installs into another project root. */
+    forCwd?(cwd: string): RuntimePackageInstaller;
+}
+/** Where bytes written by an upgraded server inside the container come out. */
+interface RuntimeSocketPeer {
+    data(bytes: Uint8Array): void;
+    close(): void;
+}
+/** The caller's end of a connection opened with {@link RuntimePod.connect}. */
+interface RuntimeConnection {
+    send(bytes: Uint8Array): void;
+    close(): void;
+}
+/** The process-manager protocol a container's kernel bridge substitutes for. */
+interface RuntimeProcessManager {
+    spawn(config: ChildSpawnConfig): ChildHandle;
+}
+interface RuntimePod {
+    readonly volume: RuntimeVolume;
+    readonly packages: RuntimePackageInstaller;
+    readonly instanceId: string;
+    readonly processManager: RuntimeProcessManager;
+    readonly proxy: {
+        activePorts(instanceId?: string): number[];
+    };
+    spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    request(port: number, init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    /**
+     * Open a connection that upgrades out of HTTP, or null if nothing takes one.
+     *
+     * Optional because a pod that only ever answers requests is still a usable
+     * pod — a caller treats the absence as "no WebSocket here" rather than as a
+     * broken implementation.
+     */
+    connect?(port: number, init: Record<string, unknown>, peer: RuntimeSocketPeer): RuntimeConnection | null;
+    /**
+     * Bind a port to a server implemented outside the JavaScript runtime.
+     *
+     * The pod owns the port table, and a Python process cannot register with it
+     * the way a Node server does — it has no `http.createServer`. This is the
+     * seam that lets one exist without a second, divergent port table, so
+     * `box.request()`, the preview router and `ss` all see the same listeners.
+     *
+     * Returns the function that unbinds it. Optional: a pod that cannot host
+     * foreign servers simply does not offer one.
+     */
+    serveExternal?(port: number, owner: string, handler: (request: {
+        method: string;
+        path: string;
+        headers: Record<string, string>;
+        body: Uint8Array;
+    }) => Promise<RuntimeHttpResponse>): () => void;
+    snapshot(options?: Record<string, unknown>): unknown;
+    restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
+    teardown(): void;
+}
+
+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 the RuntimePod's `MemoryVolume`, 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: RuntimeVolume;
+    private readonly providers;
+    private nextVirtualIno;
+    private readonly virtualInos;
+    constructor(volume: RuntimeVolume);
+    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;
+    };
+}
+
+export { type Cred as C, type DirEntry as D, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, type RuntimeHttpResponse as a, type SyncSpawn as b, type VolumeStat as c, type VolumeStats as d, type RuntimePod as e, type RuntimePackageInstaller as f, type ChildSpawnConfig as g, type ChildHandle as h, type RuntimeProcess as i, type RuntimeSocketPeer as j, type RuntimeConnection as k, ROOT_CRED as l, type RuntimeProcessManager as m, type RuntimeProcessResult as n, Stats as o, type VirtualNode as p, type VirtualProvider as q, applyChmod as r, createChildProcessModule as s, formatMode as t, makeCred as u, octalMode as v, parseUmask as w };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sandboxedjs",
-  "version": "0.1.48",
-  "description": "A Linux-like container that runs entirely inside Node.js — POSIX shell, ~140 coreutils, Node.js and Python runtimes, virtual filesystem and networking. No Docker, no VM, no native modules.",
+  "version": "0.1.49",
+  "description": "A Linux-like container that runs entirely inside Node.js \u2014 POSIX shell, ~140 coreutils, Node.js and Python runtimes, virtual filesystem and networking. No Docker, no VM, no native modules.",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -32,6 +32,11 @@
       "types": "./dist/browser-host.d.ts",
       "import": "./dist/browser-host.js",
       "require": "./dist/browser-host.cjs"
+    },
+    "./python-abi": {
+      "types": "./dist/python-abi.d.ts",
+      "import": "./dist/python-abi.js",
+      "require": "./dist/python-abi.cjs"
     }
   },
   "files": [
@@ -41,7 +46,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node python-runtime/scripts/copy_runtime.mjs",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",