@secure-exec/core 0.1.0-rc.1

package/dist/shared/in-memory-fs.js

@@ -0,0 +1,341 @@
+const S_IFREG = 0o100000;
+const S_IFDIR = 0o040000;
+const S_IFLNK = 0o120000;
+function normalizePath(path) {
+    if (!path)
+        return "/";
+    let normalized = path.startsWith("/") ? path : `/${path}`;
+    normalized = normalized.replace(/\/+/g, "/");
+    if (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+function splitPath(path) {
+    const normalized = normalizePath(path);
+    return normalized === "/" ? [] : normalized.slice(1).split("/");
+}
+function dirname(path) {
+    const parts = splitPath(path);
+    if (parts.length <= 1)
+        return "/";
+    return `/${parts.slice(0, -1).join("/")}`;
+}
+/**
+ * A fully in-memory VirtualFileSystem backed by Maps.
+ * Used as the default filesystem for the browser sandbox and for tests.
+ * Paths are always POSIX-style (forward slashes, rooted at "/").
+ */
+export class InMemoryFileSystem {
+    files = new Map();
+    dirs = new Set(["/"]);
+    symlinks = new Map();
+    modes = new Map();
+    owners = new Map();
+    timestamps = new Map();
+    hardLinks = new Map(); // newPath → originalPath
+    listDirEntries(path) {
+        const normalized = normalizePath(path);
+        if (!this.dirs.has(normalized)) {
+            throw new Error(`ENOENT: no such file or directory, scandir '${normalized}'`);
+        }
+        const prefix = normalized === "/" ? "/" : `${normalized}/`;
+        const entries = new Map();
+        for (const filePath of this.files.keys()) {
+            if (filePath.startsWith(prefix)) {
+                const rest = filePath.slice(prefix.length);
+                if (rest && !rest.includes("/")) {
+                    entries.set(rest, false);
+                }
+            }
+        }
+        for (const dirPath of this.dirs.values()) {
+            if (dirPath.startsWith(prefix)) {
+                const rest = dirPath.slice(prefix.length);
+                if (rest && !rest.includes("/")) {
+                    entries.set(rest, true);
+                }
+            }
+        }
+        return Array.from(entries.entries()).map(([name, isDirectory]) => ({
+            name,
+            isDirectory,
+        }));
+    }
+    async readFile(path) {
+        const normalized = normalizePath(path);
+        const data = this.files.get(normalized);
+        if (!data) {
+            throw new Error(`ENOENT: no such file or directory, open '${normalized}'`);
+        }
+        return data;
+    }
+    async readTextFile(path) {
+        const data = await this.readFile(path);
+        return new TextDecoder().decode(data);
+    }
+    async readDir(path) {
+        return this.listDirEntries(path).map((entry) => entry.name);
+    }
+    async readDirWithTypes(path) {
+        return this.listDirEntries(path);
+    }
+    async writeFile(path, content) {
+        const normalized = normalizePath(path);
+        await this.mkdir(dirname(normalized));
+        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        this.files.set(normalized, data);
+    }
+    async createDir(path) {
+        const normalized = normalizePath(path);
+        const parent = dirname(normalized);
+        if (!this.dirs.has(parent)) {
+            throw new Error(`ENOENT: no such file or directory, mkdir '${normalized}'`);
+        }
+        this.dirs.add(normalized);
+    }
+    async mkdir(path) {
+        const parts = splitPath(path);
+        let current = "";
+        for (const part of parts) {
+            current += `/${part}`;
+            if (!this.dirs.has(current)) {
+                this.dirs.add(current);
+            }
+        }
+    }
+    resolveSymlink(normalized, maxDepth = 16) {
+        let current = normalized;
+        for (let i = 0; i < maxDepth; i++) {
+            const target = this.symlinks.get(current);
+            if (!target)
+                return current;
+            current = target.startsWith("/") ? normalizePath(target) : normalizePath(`${dirname(current)}/${target}`);
+        }
+        throw new Error(`ELOOP: too many levels of symbolic links, stat '${normalized}'`);
+    }
+    statEntry(normalized) {
+        const now = Date.now();
+        const ts = this.timestamps.get(normalized);
+        const owner = this.owners.get(normalized);
+        const customMode = this.modes.get(normalized);
+        const atimeMs = ts?.atimeMs ?? now;
+        const mtimeMs = ts?.mtimeMs ?? now;
+        const file = this.files.get(normalized);
+        if (file) {
+            return {
+                mode: customMode ?? (S_IFREG | 0o644),
+                size: file.byteLength,
+                isDirectory: false,
+                isSymbolicLink: false,
+                atimeMs,
+                mtimeMs,
+                ctimeMs: now,
+                birthtimeMs: now,
+            };
+        }
+        if (this.dirs.has(normalized)) {
+            return {
+                mode: customMode ?? (S_IFDIR | 0o755),
+                size: 4096,
+                isDirectory: true,
+                isSymbolicLink: false,
+                atimeMs,
+                mtimeMs,
+                ctimeMs: now,
+                birthtimeMs: now,
+            };
+        }
+        throw new Error(`ENOENT: no such file or directory, stat '${normalized}'`);
+    }
+    async exists(path) {
+        const normalized = normalizePath(path);
+        if (this.symlinks.has(normalized)) {
+            try {
+                this.resolveSymlink(normalized);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return this.files.has(normalized) || this.dirs.has(normalized);
+    }
+    async stat(path) {
+        const normalized = normalizePath(path);
+        const resolved = this.resolveSymlink(normalized);
+        return this.statEntry(resolved);
+    }
+    async removeFile(path) {
+        const normalized = normalizePath(path);
+        if (!this.files.delete(normalized)) {
+            throw new Error(`ENOENT: no such file or directory, unlink '${normalized}'`);
+        }
+    }
+    async removeDir(path) {
+        const normalized = normalizePath(path);
+        if (normalized === "/") {
+            throw new Error("EPERM: operation not permitted, rmdir '/'");
+        }
+        if (!this.dirs.has(normalized)) {
+            throw new Error(`ENOENT: no such file or directory, rmdir '${normalized}'`);
+        }
+        const prefix = normalized.endsWith("/") ? normalized : `${normalized}/`;
+        for (const filePath of this.files.keys()) {
+            if (filePath.startsWith(prefix)) {
+                throw new Error(`ENOTEMPTY: directory not empty, rmdir '${normalized}'`);
+            }
+        }
+        for (const dirPath of this.dirs.values()) {
+            if (dirPath !== normalized && dirPath.startsWith(prefix)) {
+                throw new Error(`ENOTEMPTY: directory not empty, rmdir '${normalized}'`);
+            }
+        }
+        this.dirs.delete(normalized);
+    }
+    async rename(oldPath, newPath) {
+        const oldNormalized = normalizePath(oldPath);
+        const newNormalized = normalizePath(newPath);
+        if (oldNormalized === newNormalized) {
+            return;
+        }
+        if (!this.dirs.has(dirname(newNormalized))) {
+            throw new Error(`ENOENT: no such file or directory, rename '${oldNormalized}' -> '${newNormalized}'`);
+        }
+        if (this.files.has(oldNormalized)) {
+            if (this.dirs.has(newNormalized)) {
+                throw new Error(`EISDIR: illegal operation on a directory, rename '${oldNormalized}' -> '${newNormalized}'`);
+            }
+            const content = this.files.get(oldNormalized);
+            this.files.set(newNormalized, content);
+            this.files.delete(oldNormalized);
+            return;
+        }
+        if (!this.dirs.has(oldNormalized)) {
+            throw new Error(`ENOENT: no such file or directory, rename '${oldNormalized}' -> '${newNormalized}'`);
+        }
+        if (oldNormalized === "/") {
+            throw new Error(`EPERM: operation not permitted, rename '${oldNormalized}'`);
+        }
+        if (newNormalized.startsWith(`${oldNormalized}/`)) {
+            throw new Error(`EINVAL: invalid argument, rename '${oldNormalized}' -> '${newNormalized}'`);
+        }
+        if (this.dirs.has(newNormalized) || this.files.has(newNormalized)) {
+            throw new Error(`EEXIST: file already exists, rename '${oldNormalized}' -> '${newNormalized}'`);
+        }
+        const sourcePrefix = `${oldNormalized}/`;
+        const targetPrefix = `${newNormalized}/`;
+        const dirPaths = Array.from(this.dirs.values())
+            .filter((path) => path === oldNormalized || path.startsWith(sourcePrefix))
+            .sort((a, b) => a.length - b.length);
+        const filePaths = Array.from(this.files.keys()).filter((path) => path.startsWith(sourcePrefix));
+        for (const path of dirPaths) {
+            this.dirs.delete(path);
+        }
+        for (const path of filePaths) {
+            const content = this.files.get(path);
+            this.files.delete(path);
+            this.files.set(`${targetPrefix}${path.slice(sourcePrefix.length)}`, content);
+        }
+        this.dirs.add(newNormalized);
+        for (const path of dirPaths) {
+            if (path === oldNormalized) {
+                continue;
+            }
+            this.dirs.add(`${targetPrefix}${path.slice(sourcePrefix.length)}`);
+        }
+    }
+    async symlink(target, linkPath) {
+        const normalized = normalizePath(linkPath);
+        if (this.files.has(normalized) || this.dirs.has(normalized) || this.symlinks.has(normalized)) {
+            throw new Error(`EEXIST: file already exists, symlink '${target}' -> '${normalized}'`);
+        }
+        await this.mkdir(dirname(normalized));
+        this.symlinks.set(normalized, target);
+    }
+    async readlink(path) {
+        const normalized = normalizePath(path);
+        const target = this.symlinks.get(normalized);
+        if (target === undefined) {
+            throw new Error(`EINVAL: invalid argument, readlink '${normalized}'`);
+        }
+        return target;
+    }
+    async lstat(path) {
+        const normalized = normalizePath(path);
+        const target = this.symlinks.get(normalized);
+        if (target !== undefined) {
+            const now = Date.now();
+            return {
+                mode: S_IFLNK | 0o777,
+                size: new TextEncoder().encode(target).byteLength,
+                isDirectory: false,
+                isSymbolicLink: true,
+                atimeMs: now,
+                mtimeMs: now,
+                ctimeMs: now,
+                birthtimeMs: now,
+            };
+        }
+        return this.statEntry(normalized);
+    }
+    async link(oldPath, newPath) {
+        const oldNormalized = normalizePath(oldPath);
+        const newNormalized = normalizePath(newPath);
+        const file = this.files.get(oldNormalized);
+        if (!file) {
+            throw new Error(`ENOENT: no such file or directory, link '${oldNormalized}' -> '${newNormalized}'`);
+        }
+        if (this.files.has(newNormalized) || this.dirs.has(newNormalized)) {
+            throw new Error(`EEXIST: file already exists, link '${oldNormalized}' -> '${newNormalized}'`);
+        }
+        await this.mkdir(dirname(newNormalized));
+        this.files.set(newNormalized, file);
+        this.hardLinks.set(newNormalized, oldNormalized);
+    }
+    async chmod(path, mode) {
+        const normalized = normalizePath(path);
+        const resolved = this.resolveSymlink(normalized);
+        if (!this.files.has(resolved) && !this.dirs.has(resolved)) {
+            throw new Error(`ENOENT: no such file or directory, chmod '${normalized}'`);
+        }
+        const existing = this.modes.get(resolved);
+        const typeBits = existing ? (existing & 0o170000) : (this.files.has(resolved) ? S_IFREG : S_IFDIR);
+        this.modes.set(resolved, typeBits | (mode & 0o7777));
+    }
+    async chown(path, uid, gid) {
+        const normalized = normalizePath(path);
+        const resolved = this.resolveSymlink(normalized);
+        if (!this.files.has(resolved) && !this.dirs.has(resolved)) {
+            throw new Error(`ENOENT: no such file or directory, chown '${normalized}'`);
+        }
+        this.owners.set(resolved, { uid, gid });
+    }
+    async utimes(path, atime, mtime) {
+        const normalized = normalizePath(path);
+        const resolved = this.resolveSymlink(normalized);
+        if (!this.files.has(resolved) && !this.dirs.has(resolved)) {
+            throw new Error(`ENOENT: no such file or directory, utimes '${normalized}'`);
+        }
+        this.timestamps.set(resolved, { atimeMs: atime * 1000, mtimeMs: mtime * 1000 });
+    }
+    async truncate(path, length) {
+        const normalized = normalizePath(path);
+        const resolved = this.resolveSymlink(normalized);
+        const file = this.files.get(resolved);
+        if (!file) {
+            throw new Error(`ENOENT: no such file or directory, truncate '${normalized}'`);
+        }
+        if (length >= file.byteLength) {
+            const padded = new Uint8Array(length);
+            padded.set(file);
+            this.files.set(resolved, padded);
+        }
+        else {
+            this.files.set(resolved, file.slice(0, length));
+        }
+    }
+}
+export function createInMemoryFileSystem() {
+    return new InMemoryFileSystem();
+}

package/dist/shared/permissions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Permission enforcement layer.
+ *
+ * Wraps filesystem, network, and command-executor adapters with permission
+ * checks that throw EACCES on denial. When no permission callback is provided
+ * for a category, guarded operations in that category are denied by default.
+ */
+import type { CommandExecutor, EnvAccessRequest, NetworkAdapter, Permissions, VirtualFileSystem } from "../types.js";
+export declare const allowAllFs: Pick<Permissions, "fs">;
+export declare const allowAllNetwork: Pick<Permissions, "network">;
+export declare const allowAllChildProcess: Pick<Permissions, "childProcess">;
+export declare const allowAllEnv: Pick<Permissions, "env">;
+export declare const allowAll: Permissions;
+/**
+ * Wrap a VirtualFileSystem so every operation passes through the fs permission check.
+ * Throws EACCES if the permission callback denies or is absent.
+ */
+export declare function wrapFileSystem(fs: VirtualFileSystem, permissions?: Permissions): VirtualFileSystem;
+/**
+ * Wrap a NetworkAdapter so externally-originating operations (`listen`, `fetch`,
+ * `dns`, `http`) pass through the network permission check.
+ * `httpServerClose` is forwarded as-is.
+ */
+export declare function wrapNetworkAdapter(adapter: NetworkAdapter, permissions?: Permissions): NetworkAdapter;
+/** Wrap a CommandExecutor so spawn passes through the childProcess permission check. */
+export declare function wrapCommandExecutor(executor: CommandExecutor, permissions?: Permissions): CommandExecutor;
+export declare function envAccessAllowed(permissions: Permissions | undefined, request: EnvAccessRequest): void;
+/** Create a stub VFS where every operation throws ENOSYS (no filesystem configured). */
+export declare function createFsStub(): VirtualFileSystem;
+/** Create a stub network adapter where every operation throws ENOSYS. */
+export declare function createNetworkStub(): NetworkAdapter;
+/** Create a stub executor where spawn throws ENOSYS. */
+export declare function createCommandExecutorStub(): CommandExecutor;
+/**
+ * Filter an env record through the env permission check, returning only
+ * allowed key-value pairs. Returns empty object if no permissions configured.
+ */
+export declare function filterEnv(env: Record<string, string> | undefined, permissions?: Permissions): Record<string, string>;

package/dist/shared/permissions.js

@@ -0,0 +1,283 @@
+/**
+ * Permission enforcement layer.
+ *
+ * Wraps filesystem, network, and command-executor adapters with permission
+ * checks that throw EACCES on denial. When no permission callback is provided
+ * for a category, guarded operations in that category are denied by default.
+ */
+import { createEaccesError, createEnosysError } from "./errors.js";
+/** Run the permission check; throw the deny error if no checker exists or it denies. */
+function checkPermission(check, request, onDenied) {
+    if (!check) {
+        throw onDenied(request);
+    }
+    const decision = check(request);
+    if (!decision?.allow) {
+        throw onDenied(request, decision?.reason);
+    }
+}
+// Permission callbacks must be self-contained (no closures) because they are
+// serialized via `.toString()` for transfer to the browser Web Worker.
+export const allowAllFs = {
+    fs: () => ({ allow: true }),
+};
+export const allowAllNetwork = {
+    network: () => ({ allow: true }),
+};
+export const allowAllChildProcess = {
+    childProcess: () => ({ allow: true }),
+};
+export const allowAllEnv = {
+    env: () => ({ allow: true }),
+};
+export const allowAll = {
+    ...allowAllFs,
+    ...allowAllNetwork,
+    ...allowAllChildProcess,
+    ...allowAllEnv,
+};
+function fsOpToSyscall(op) {
+    switch (op) {
+        case "read":
+            return "open";
+        case "write":
+            return "write";
+        case "mkdir":
+        case "createDir":
+            return "mkdir";
+        case "readdir":
+            return "scandir";
+        case "stat":
+            return "stat";
+        case "rm":
+            return "unlink";
+        case "rename":
+            return "rename";
+        case "exists":
+            return "access";
+        case "chmod":
+            return "chmod";
+        case "chown":
+            return "chown";
+        case "link":
+            return "link";
+        case "symlink":
+            return "symlink";
+        case "readlink":
+            return "readlink";
+        case "truncate":
+            return "open";
+        case "utimes":
+            return "utimes";
+        default:
+            return "open";
+    }
+}
+/**
+ * Wrap a VirtualFileSystem so every operation passes through the fs permission check.
+ * Throws EACCES if the permission callback denies or is absent.
+ */
+export function wrapFileSystem(fs, permissions) {
+    return {
+        readFile: async (path) => {
+            checkPermission(permissions?.fs, { op: "read", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.readFile(path);
+        },
+        readTextFile: async (path) => {
+            checkPermission(permissions?.fs, { op: "read", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.readTextFile(path);
+        },
+        readDir: async (path) => {
+            checkPermission(permissions?.fs, { op: "readdir", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.readDir(path);
+        },
+        readDirWithTypes: async (path) => {
+            checkPermission(permissions?.fs, { op: "readdir", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.readDirWithTypes(path);
+        },
+        writeFile: async (path, content) => {
+            checkPermission(permissions?.fs, { op: "write", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.writeFile(path, content);
+        },
+        createDir: async (path) => {
+            checkPermission(permissions?.fs, { op: "createDir", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.createDir(path);
+        },
+        mkdir: async (path) => {
+            checkPermission(permissions?.fs, { op: "mkdir", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.mkdir(path);
+        },
+        exists: async (path) => {
+            checkPermission(permissions?.fs, { op: "exists", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.exists(path);
+        },
+        stat: async (path) => {
+            checkPermission(permissions?.fs, { op: "stat", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.stat(path);
+        },
+        removeFile: async (path) => {
+            checkPermission(permissions?.fs, { op: "rm", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.removeFile(path);
+        },
+        removeDir: async (path) => {
+            checkPermission(permissions?.fs, { op: "rm", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.removeDir(path);
+        },
+        rename: async (oldPath, newPath) => {
+            checkPermission(permissions?.fs, { op: "rename", path: oldPath }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            checkPermission(permissions?.fs, { op: "rename", path: newPath }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.rename(oldPath, newPath);
+        },
+        symlink: async (target, linkPath) => {
+            checkPermission(permissions?.fs, { op: "symlink", path: linkPath }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.symlink(target, linkPath);
+        },
+        readlink: async (path) => {
+            checkPermission(permissions?.fs, { op: "readlink", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.readlink(path);
+        },
+        lstat: async (path) => {
+            checkPermission(permissions?.fs, { op: "stat", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.lstat(path);
+        },
+        link: async (oldPath, newPath) => {
+            checkPermission(permissions?.fs, { op: "link", path: newPath }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.link(oldPath, newPath);
+        },
+        chmod: async (path, mode) => {
+            checkPermission(permissions?.fs, { op: "chmod", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.chmod(path, mode);
+        },
+        chown: async (path, uid, gid) => {
+            checkPermission(permissions?.fs, { op: "chown", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.chown(path, uid, gid);
+        },
+        utimes: async (path, atime, mtime) => {
+            checkPermission(permissions?.fs, { op: "utimes", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.utimes(path, atime, mtime);
+        },
+        truncate: async (path, length) => {
+            checkPermission(permissions?.fs, { op: "truncate", path }, (req, reason) => createEaccesError(fsOpToSyscall(req.op), req.path, reason));
+            return fs.truncate(path, length);
+        },
+    };
+}
+/**
+ * Wrap a NetworkAdapter so externally-originating operations (`listen`, `fetch`,
+ * `dns`, `http`) pass through the network permission check.
+ * `httpServerClose` is forwarded as-is.
+ */
+export function wrapNetworkAdapter(adapter, permissions) {
+    return {
+        httpServerListen: adapter.httpServerListen
+            ? async (options) => {
+                checkPermission(permissions?.network, {
+                    op: "listen",
+                    hostname: options.hostname,
+                    url: options.hostname
+                        ? `http://${options.hostname}:${options.port ?? 3000}`
+                        : `http://0.0.0.0:${options.port ?? 3000}`,
+                    method: "LISTEN",
+                }, (req, reason) => createEaccesError("listen", req.url, reason));
+                return adapter.httpServerListen(options);
+            }
+            : undefined,
+        httpServerClose: adapter.httpServerClose
+            ? async (serverId) => {
+                return adapter.httpServerClose(serverId);
+            }
+            : undefined,
+        fetch: async (url, options) => {
+            checkPermission(permissions?.network, { op: "fetch", url, method: options?.method }, (req, reason) => createEaccesError("connect", req.url, reason));
+            return adapter.fetch(url, options);
+        },
+        dnsLookup: async (hostname) => {
+            checkPermission(permissions?.network, { op: "dns", hostname }, (req, reason) => createEaccesError("connect", req.hostname, reason));
+            return adapter.dnsLookup(hostname);
+        },
+        httpRequest: async (url, options) => {
+            checkPermission(permissions?.network, { op: "http", url, method: options?.method }, (req, reason) => createEaccesError("connect", req.url, reason));
+            return adapter.httpRequest(url, options);
+        },
+    };
+}
+/** Wrap a CommandExecutor so spawn passes through the childProcess permission check. */
+export function wrapCommandExecutor(executor, permissions) {
+    return {
+        spawn: (command, args, options) => {
+            checkPermission(permissions?.childProcess, { command, args, cwd: options.cwd, env: options.env }, (req, reason) => createEaccesError("spawn", req.command, reason));
+            return executor.spawn(command, args, options);
+        },
+    };
+}
+export function envAccessAllowed(permissions, request) {
+    checkPermission(permissions?.env, request, (req, reason) => createEaccesError("access", req.key, reason));
+}
+/** Create a stub VFS where every operation throws ENOSYS (no filesystem configured). */
+export function createFsStub() {
+    const stub = (op, path) => {
+        throw createEnosysError(op, path);
+    };
+    return {
+        readFile: async (path) => stub("open", path),
+        readTextFile: async (path) => stub("open", path),
+        readDir: async (path) => stub("scandir", path),
+        readDirWithTypes: async (path) => stub("scandir", path),
+        writeFile: async (path) => stub("write", path),
+        createDir: async (path) => stub("mkdir", path),
+        mkdir: async (path) => stub("mkdir", path),
+        exists: async (path) => stub("access", path),
+        stat: async (path) => stub("stat", path),
+        removeFile: async (path) => stub("unlink", path),
+        removeDir: async (path) => stub("rmdir", path),
+        rename: async (oldPath, newPath) => stub("rename", `${oldPath}->${newPath}`),
+        symlink: async (_target, linkPath) => stub("symlink", linkPath),
+        readlink: async (path) => stub("readlink", path),
+        lstat: async (path) => stub("stat", path),
+        link: async (_oldPath, newPath) => stub("link", newPath),
+        chmod: async (path) => stub("chmod", path),
+        chown: async (path) => stub("chown", path),
+        utimes: async (path) => stub("utimes", path),
+        truncate: async (path) => stub("open", path),
+    };
+}
+/** Create a stub network adapter where every operation throws ENOSYS. */
+export function createNetworkStub() {
+    const stub = (op, path) => {
+        throw createEnosysError(op, path);
+    };
+    return {
+        httpServerListen: async () => stub("listen"),
+        httpServerClose: async () => stub("close"),
+        fetch: async (url) => stub("connect", url),
+        dnsLookup: async (hostname) => stub("connect", hostname),
+        httpRequest: async (url) => stub("connect", url),
+    };
+}
+/** Create a stub executor where spawn throws ENOSYS. */
+export function createCommandExecutorStub() {
+    return {
+        spawn: () => {
+            throw createEnosysError("spawn");
+        },
+    };
+}
+/**
+ * Filter an env record through the env permission check, returning only
+ * allowed key-value pairs. Returns empty object if no permissions configured.
+ */
+export function filterEnv(env, permissions) {
+    if (!env)
+        return {};
+    if (!permissions?.env)
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(env)) {
+        const request = { op: "read", key, value };
+        const decision = permissions.env(request);
+        if (decision?.allow) {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/dist/shared/require-setup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get the isolate-side script that installs the global `require()` function,
+ * `_requireFrom()`, and require helpers (for example `require.resolve` and
+ * `require.cache` wiring to the pre-initialized `_moduleCache`).
+ */
+export declare function getRequireSetupCode(): string;

package/dist/shared/require-setup.js

@@ -0,0 +1,9 @@
+import { getIsolateRuntimeSource } from "../generated/isolate-runtime.js";
+/**
+ * Get the isolate-side script that installs the global `require()` function,
+ * `_requireFrom()`, and require helpers (for example `require.resolve` and
+ * `require.cache` wiring to the pre-initialized `_moduleCache`).
+ */
+export function getRequireSetupCode() {
+    return getIsolateRuntimeSource("requireSetup");
+}