@secure-exec/nodejs 0.2.0-rc.1

package/dist/driver.d.ts

@@ -0,0 +1,87 @@
+import { filterEnv } from "@secure-exec/core/internal/shared/permissions";
+import { NodeExecutionDriver } from "./execution-driver.js";
+import { createDefaultNetworkAdapter, isPrivateIp } from "./default-network-adapter.js";
+import type { OSConfig, ProcessConfig } from "@secure-exec/core/internal/shared/api-types";
+import type { Permissions, VirtualFileSystem } from "@secure-exec/core";
+import type { CommandExecutor, NetworkAdapter, NodeRuntimeDriverFactory, SystemDriver } from "@secure-exec/core";
+import type { ModuleAccessOptions } from "./module-access.js";
+/** Options for assembling a Node.js-backed SystemDriver. */
+export interface NodeDriverOptions {
+    filesystem?: VirtualFileSystem;
+    moduleAccess?: ModuleAccessOptions;
+    networkAdapter?: NetworkAdapter;
+    commandExecutor?: CommandExecutor;
+    permissions?: Permissions;
+    useDefaultNetwork?: boolean;
+    processConfig?: ProcessConfig;
+    osConfig?: OSConfig;
+}
+export interface NodeRuntimeDriverFactoryOptions {
+    createIsolate?(memoryLimit: number): unknown;
+}
+/** Thin VFS adapter that delegates directly to `node:fs/promises`. */
+export declare class NodeFileSystem implements VirtualFileSystem {
+    prepareOpenSync(filePath: string, flags: number): boolean;
+    readFile(path: string): Promise<Uint8Array>;
+    readTextFile(path: string): Promise<string>;
+    readDir(path: string): Promise<string[]>;
+    readDirWithTypes(path: string): Promise<Array<{
+        name: string;
+        isDirectory: boolean;
+    }>>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    createDir(path: string): Promise<void>;
+    mkdir(path: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<{
+        mode: number;
+        size: number;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+        atimeMs: number;
+        mtimeMs: number;
+        ctimeMs: number;
+        birthtimeMs: number;
+        ino: number;
+        nlink: number;
+        uid: number;
+        gid: number;
+    }>;
+    removeFile(path: string): Promise<void>;
+    removeDir(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    lstat(path: string): Promise<{
+        mode: number;
+        size: number;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+        atimeMs: number;
+        mtimeMs: number;
+        ctimeMs: number;
+        birthtimeMs: number;
+        ino: number;
+        nlink: number;
+        uid: number;
+        gid: number;
+    }>;
+    link(oldPath: string, newPath: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    utimes(path: string, atime: number, mtime: number): Promise<void>;
+    truncate(path: string, length: number): Promise<void>;
+    realpath(path: string): Promise<string>;
+    pread(path: string, offset: number, length: number): Promise<Uint8Array>;
+}
+/**
+ * Assemble a SystemDriver from Node.js-native adapters. Wraps the filesystem
+ * in a ModuleAccessFileSystem overlay and keeps capabilities deny-by-default
+ * unless explicit permissions are provided.
+ */
+export declare function createNodeDriver(options?: NodeDriverOptions): SystemDriver;
+export declare function createNodeRuntimeDriverFactory(options?: NodeRuntimeDriverFactoryOptions): NodeRuntimeDriverFactory;
+export { createDefaultNetworkAdapter, filterEnv, isPrivateIp, NodeExecutionDriver, };
+export type { ModuleAccessOptions };

package/dist/driver.js

@@ -0,0 +1,191 @@
+import * as fs from "node:fs/promises";
+import * as fsSync from "node:fs";
+import path from "node:path";
+import { filterEnv, } from "@secure-exec/core/internal/shared/permissions";
+import { ModuleAccessFileSystem } from "./module-access.js";
+import { NodeExecutionDriver } from "./execution-driver.js";
+import { createDefaultNetworkAdapter, isPrivateIp, } from "./default-network-adapter.js";
+import { KernelError, O_CREAT, O_EXCL, O_TRUNC } from "@secure-exec/core";
+/** Thin VFS adapter that delegates directly to `node:fs/promises`. */
+export class NodeFileSystem {
+    prepareOpenSync(filePath, flags) {
+        const hasCreate = (flags & O_CREAT) !== 0;
+        const hasExcl = (flags & O_EXCL) !== 0;
+        const hasTrunc = (flags & O_TRUNC) !== 0;
+        const exists = fsSync.existsSync(filePath);
+        if (hasCreate && hasExcl && exists) {
+            throw new KernelError("EEXIST", `file already exists, open '${filePath}'`);
+        }
+        let created = false;
+        if (!exists && hasCreate) {
+            fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+            fsSync.writeFileSync(filePath, new Uint8Array(0));
+            created = true;
+        }
+        if (hasTrunc) {
+            try {
+                fsSync.truncateSync(filePath, 0);
+            }
+            catch (error) {
+                const err = error;
+                if (err.code === "ENOENT") {
+                    throw new KernelError("ENOENT", `no such file or directory, open '${filePath}'`);
+                }
+                if (err.code === "EISDIR") {
+                    throw new KernelError("EISDIR", `illegal operation on a directory, open '${filePath}'`);
+                }
+                throw error;
+            }
+        }
+        return created;
+    }
+    async readFile(path) {
+        return fs.readFile(path);
+    }
+    async readTextFile(path) {
+        return fs.readFile(path, "utf8");
+    }
+    async readDir(path) {
+        return fs.readdir(path);
+    }
+    async readDirWithTypes(path) {
+        const entries = await fs.readdir(path, { withFileTypes: true });
+        return entries.map((entry) => ({
+            name: entry.name,
+            isDirectory: entry.isDirectory(),
+        }));
+    }
+    async writeFile(path, content) {
+        await fs.writeFile(path, content);
+    }
+    async createDir(path) {
+        await fs.mkdir(path);
+    }
+    async mkdir(path, _options) {
+        await fs.mkdir(path, { recursive: true });
+    }
+    async exists(path) {
+        try {
+            await fs.access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async stat(path) {
+        const info = await fs.stat(path);
+        return {
+            mode: info.mode,
+            size: info.size,
+            isDirectory: info.isDirectory(),
+            isSymbolicLink: false,
+            atimeMs: info.atimeMs,
+            mtimeMs: info.mtimeMs,
+            ctimeMs: info.ctimeMs,
+            birthtimeMs: info.birthtimeMs,
+            ino: info.ino,
+            nlink: info.nlink,
+            uid: info.uid,
+            gid: info.gid,
+        };
+    }
+    async removeFile(path) {
+        await fs.unlink(path);
+    }
+    async removeDir(path) {
+        await fs.rmdir(path);
+    }
+    async rename(oldPath, newPath) {
+        await fs.rename(oldPath, newPath);
+    }
+    async symlink(target, linkPath) {
+        await fs.symlink(target, linkPath);
+    }
+    async readlink(path) {
+        return fs.readlink(path);
+    }
+    async lstat(path) {
+        const info = await fs.lstat(path);
+        return {
+            mode: info.mode,
+            size: info.size,
+            isDirectory: info.isDirectory(),
+            isSymbolicLink: info.isSymbolicLink(),
+            atimeMs: info.atimeMs,
+            mtimeMs: info.mtimeMs,
+            ctimeMs: info.ctimeMs,
+            birthtimeMs: info.birthtimeMs,
+            ino: info.ino,
+            nlink: info.nlink,
+            uid: info.uid,
+            gid: info.gid,
+        };
+    }
+    async link(oldPath, newPath) {
+        await fs.link(oldPath, newPath);
+    }
+    async chmod(path, mode) {
+        await fs.chmod(path, mode);
+    }
+    async chown(path, uid, gid) {
+        await fs.chown(path, uid, gid);
+    }
+    async utimes(path, atime, mtime) {
+        await fs.utimes(path, atime, mtime);
+    }
+    async truncate(path, length) {
+        await fs.truncate(path, length);
+    }
+    async realpath(path) {
+        return fs.realpath(path);
+    }
+    async pread(path, offset, length) {
+        const handle = await fs.open(path, "r");
+        try {
+            const buf = new Uint8Array(length);
+            const { bytesRead } = await handle.read(buf, 0, length, offset);
+            return buf.slice(0, bytesRead);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+/**
+ * Assemble a SystemDriver from Node.js-native adapters. Wraps the filesystem
+ * in a ModuleAccessFileSystem overlay and keeps capabilities deny-by-default
+ * unless explicit permissions are provided.
+ */
+export function createNodeDriver(options = {}) {
+    const filesystem = new ModuleAccessFileSystem(options.filesystem, options.moduleAccess ?? {});
+    const permissions = options.permissions;
+    const networkAdapter = options.networkAdapter
+        ? options.networkAdapter
+        : options.useDefaultNetwork
+            ? createDefaultNetworkAdapter()
+            : undefined;
+    return {
+        filesystem,
+        network: networkAdapter,
+        commandExecutor: options.commandExecutor,
+        permissions,
+        runtime: {
+            process: {
+                ...(options.processConfig ?? {}),
+            },
+            os: {
+                ...(options.osConfig ?? {}),
+            },
+        },
+    };
+}
+export function createNodeRuntimeDriverFactory(options = {}) {
+    return {
+        createRuntimeDriver: (runtimeOptions) => new NodeExecutionDriver({
+            ...runtimeOptions,
+            createIsolate: options.createIsolate,
+        }),
+    };
+}
+export { createDefaultNetworkAdapter, filterEnv, isPrivateIp, NodeExecutionDriver, };

package/dist/esm-compiler.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ESM wrapper generator for built-in modules inside the isolate.
+ *
+ * The V8 isolate's ESM `import` can only resolve modules we explicitly provide.
+ * For Node built-ins (fs, path, etc.) we generate thin ESM wrappers that
+ * re-export the bridge-provided globalThis objects as proper ESM modules
+ * with both default and named exports.
+ */
+/** Get a pre-built ESM wrapper for a bridge-backed built-in, or null if not bridge-handled. */
+export declare function getStaticBuiltinWrapperSource(moduleName: string): string | null;
+/** Build a custom ESM wrapper for a dynamically-resolved module (e.g. polyfills). */
+export declare function createBuiltinESMWrapper(bindingExpression: string, namedExports: string[]): string;
+/** Wrapper for unsupported built-ins: exports an empty object as default. */
+export declare function getEmptyBuiltinESMWrapper(): string;

package/dist/esm-compiler.js

@@ -0,0 +1,68 @@
+/**
+ * ESM wrapper generator for built-in modules inside the isolate.
+ *
+ * The V8 isolate's ESM `import` can only resolve modules we explicitly provide.
+ * For Node built-ins (fs, path, etc.) we generate thin ESM wrappers that
+ * re-export the bridge-provided globalThis objects as proper ESM modules
+ * with both default and named exports.
+ */
+import { BUILTIN_NAMED_EXPORTS } from "./builtin-modules.js";
+function isValidIdentifier(value) {
+    return /^[$A-Z_][0-9A-Z_$]*$/i.test(value);
+}
+/** Generate `export const X = _builtin.X;` lines for each known named export. */
+function buildNamedExportLines(namedExports) {
+    return Array.from(new Set(namedExports))
+        .filter(isValidIdentifier)
+        .map((name) => "export const " +
+        name +
+        " = _builtin == null ? undefined : _builtin[" +
+        JSON.stringify(name) +
+        "];");
+}
+/**
+ * Build a complete ESM wrapper that reads a bridge global via `bindingExpression`
+ * and re-exports it as `default` plus individual named exports.
+ */
+function buildWrapperSource(bindingExpression, namedExports) {
+    const lines = [
+        "const _builtin = " + bindingExpression + ";",
+        "export default _builtin;",
+        ...buildNamedExportLines(namedExports),
+    ];
+    return lines.join("\n");
+}
+const MODULE_FALLBACK_BINDING = "globalThis.bridge?.module || {" +
+    "createRequire: globalThis._createRequire || function(f) {" +
+    "const dir = f.replace(/\\\\[^\\\\]*$/, '') || '/';" +
+    "return function(m) { return globalThis._requireFrom(m, dir); };" +
+    "}," +
+    "Module: { builtinModules: [] }," +
+    "isBuiltin: () => false," +
+    "builtinModules: []" +
+    "}";
+const STATIC_BUILTIN_WRAPPER_SOURCES = {
+    fs: buildWrapperSource("globalThis.bridge?.fs || globalThis.bridge?.default || {}", BUILTIN_NAMED_EXPORTS.fs),
+    "fs/promises": buildWrapperSource("(globalThis.bridge?.fs || globalThis.bridge?.default || {}).promises || {}", BUILTIN_NAMED_EXPORTS["fs/promises"]),
+    module: buildWrapperSource(MODULE_FALLBACK_BINDING, BUILTIN_NAMED_EXPORTS.module),
+    os: buildWrapperSource("globalThis.bridge?.os || {}", BUILTIN_NAMED_EXPORTS.os),
+    http: buildWrapperSource("globalThis._httpModule || globalThis.bridge?.network?.http || {}", BUILTIN_NAMED_EXPORTS.http),
+    https: buildWrapperSource("globalThis._httpsModule || globalThis.bridge?.network?.https || {}", BUILTIN_NAMED_EXPORTS.https),
+    http2: buildWrapperSource("globalThis._http2Module || {}", []),
+    dns: buildWrapperSource("globalThis._dnsModule || globalThis.bridge?.network?.dns || {}", BUILTIN_NAMED_EXPORTS.dns),
+    child_process: buildWrapperSource("globalThis._childProcessModule || globalThis.bridge?.childProcess || {}", BUILTIN_NAMED_EXPORTS.child_process),
+    process: buildWrapperSource("globalThis.process || {}", BUILTIN_NAMED_EXPORTS.process),
+    v8: buildWrapperSource("globalThis._moduleCache?.v8 || {}", []),
+};
+/** Get a pre-built ESM wrapper for a bridge-backed built-in, or null if not bridge-handled. */
+export function getStaticBuiltinWrapperSource(moduleName) {
+    return STATIC_BUILTIN_WRAPPER_SOURCES[moduleName] ?? null;
+}
+/** Build a custom ESM wrapper for a dynamically-resolved module (e.g. polyfills). */
+export function createBuiltinESMWrapper(bindingExpression, namedExports) {
+    return buildWrapperSource(bindingExpression, namedExports);
+}
+/** Wrapper for unsupported built-ins: exports an empty object as default. */
+export function getEmptyBuiltinESMWrapper() {
+    return buildWrapperSource("{}", []);
+}

package/dist/execution-driver.d.ts

@@ -0,0 +1,37 @@
+import type { NetworkAdapter, RuntimeDriver } from "@secure-exec/core";
+import type { ExecOptions, ExecResult, RunResult } from "@secure-exec/core/internal/shared/api-types";
+import { type NodeExecutionDriverOptions } from "./isolate-bootstrap.js";
+export { NodeExecutionDriverOptions };
+export declare class NodeExecutionDriver implements RuntimeDriver {
+    private state;
+    private memoryLimit;
+    private disposed;
+    private flattenedBindings;
+    private rawFilesystem;
+    private socketTable?;
+    private processTable?;
+    private timerTable;
+    private ownsProcessTable;
+    private ownsTimerTable;
+    private configuredMaxTimers?;
+    private configuredMaxHandles?;
+    private pid?;
+    constructor(options: NodeExecutionDriverOptions);
+    get network(): Pick<NetworkAdapter, "fetch" | "dnsLookup" | "httpRequest">;
+    get unsafeIsolate(): unknown;
+    private hasManagedResources;
+    private waitForManagedResources;
+    private ensureBridgeProcessEntry;
+    private clearKernelTimersForProcess;
+    private finalizeExecutionState;
+    createUnsafeContext(_options?: {
+        env?: Record<string, string>;
+        cwd?: string;
+        filePath?: string;
+    }): Promise<unknown>;
+    run<T = unknown>(code: string, filePath?: string): Promise<RunResult<T>>;
+    exec(code: string, options?: ExecOptions): Promise<ExecResult>;
+    private executeInternal;
+    dispose(): void;
+    terminate(): Promise<void>;
+}