@secure-exec/nodejs 0.2.0-rc.1

package/dist/builtin-modules.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Module classification and resolution helpers.
+ *
+ * Node built-ins are split into three tiers:
+ * - Bridge modules: fully polyfilled by the bridge (fs, process, http, etc.)
+ * - Deferred core modules: known but not yet bridge-supported; surfaced via
+ *   deferred stubs in require paths and polyfills/wrappers in ESM paths
+ * - Unsupported core modules: known but intentionally unimplemented
+ *
+ * Everything else falls through to node-stdlib-browser polyfills or node_modules.
+ */
+/**
+ * Known named exports for each built-in module. Used by the ESM wrapper
+ * generator to create `export const X = _builtin.X;` re-exports so that
+ * `import { readFile } from 'fs'` works inside the isolate.
+ */
+export declare const BUILTIN_NAMED_EXPORTS: Record<string, string[]>;
+/**
+ * Normalize a module specifier to its canonical form if it's a known built-in.
+ * Returns null for non-builtin specifiers.
+ * Preserves the `node:` prefix when present, strips it otherwise.
+ */
+export declare function normalizeBuiltinSpecifier(request: string): string | null;
+/** Extract the directory portion of a path (lightweight dirname without node:path). */
+export declare function getPathDir(path: string): string;

package/dist/builtin-modules.js

@@ -0,0 +1,312 @@
+/**
+ * Module classification and resolution helpers.
+ *
+ * Node built-ins are split into three tiers:
+ * - Bridge modules: fully polyfilled by the bridge (fs, process, http, etc.)
+ * - Deferred core modules: known but not yet bridge-supported; surfaced via
+ *   deferred stubs in require paths and polyfills/wrappers in ESM paths
+ * - Unsupported core modules: known but intentionally unimplemented
+ *
+ * Everything else falls through to node-stdlib-browser polyfills or node_modules.
+ */
+/**
+ * Static set of Node.js stdlib module names that have browser polyfills
+ * available via node-stdlib-browser. Hardcoded to avoid importing
+ * node-stdlib-browser at runtime (its ESM entry crashes on missing
+ * mock/empty.js in published builds).
+ */
+const STDLIB_BROWSER_MODULES = new Set([
+    "assert",
+    "buffer",
+    "child_process",
+    "cluster",
+    "console",
+    "constants",
+    "crypto",
+    "dgram",
+    "dns",
+    "domain",
+    "events",
+    "fs",
+    "http",
+    "https",
+    "http2",
+    "module",
+    "net",
+    "os",
+    "path",
+    "punycode",
+    "process",
+    "querystring",
+    "readline",
+    "repl",
+    "stream",
+    "_stream_duplex",
+    "_stream_passthrough",
+    "_stream_readable",
+    "_stream_transform",
+    "_stream_writable",
+    "string_decoder",
+    "sys",
+    "timers/promises",
+    "timers",
+    "tls",
+    "tty",
+    "url",
+    "util",
+    "vm",
+    "zlib",
+]);
+/** Check if a module has a polyfill available via node-stdlib-browser. */
+function hasPolyfill(moduleName) {
+    const name = moduleName.replace(/^node:/, "");
+    return STDLIB_BROWSER_MODULES.has(name);
+}
+/** Modules with full bridge implementations injected into the isolate. */
+const BRIDGE_MODULES = [
+    "fs",
+    "fs/promises",
+    "module",
+    "os",
+    "http",
+    "https",
+    "http2",
+    "dns",
+    "child_process",
+    "process",
+    "v8",
+];
+/**
+ * Recognized built-ins that lack bridge support.
+ * Runtime handling differs by path (require stubs vs ESM/polyfill handling).
+ */
+const DEFERRED_CORE_MODULES = [
+    "net",
+    "tls",
+    "readline",
+    "perf_hooks",
+    "async_hooks",
+    "worker_threads",
+    "diagnostics_channel",
+];
+/** Built-ins that are intentionally unimplemented (throw on use). */
+const UNSUPPORTED_CORE_MODULES = [
+    "dgram",
+    "cluster",
+    "wasi",
+    "inspector",
+    "repl",
+    "trace_events",
+    "domain",
+];
+const KNOWN_BUILTIN_MODULES = new Set([
+    ...BRIDGE_MODULES,
+    ...DEFERRED_CORE_MODULES,
+    ...UNSUPPORTED_CORE_MODULES,
+    "assert",
+    "buffer",
+    "constants",
+    "crypto",
+    "events",
+    "path",
+    "querystring",
+    "stream",
+    "stream/web",
+    "string_decoder",
+    "timers",
+    "tty",
+    "url",
+    "util",
+    "vm",
+    "zlib",
+]);
+/**
+ * Known named exports for each built-in module. Used by the ESM wrapper
+ * generator to create `export const X = _builtin.X;` re-exports so that
+ * `import { readFile } from 'fs'` works inside the isolate.
+ */
+export const BUILTIN_NAMED_EXPORTS = {
+    fs: [
+        "promises",
+        "readFileSync",
+        "writeFileSync",
+        "appendFileSync",
+        "existsSync",
+        "statSync",
+        "mkdirSync",
+        "readdirSync",
+        "createReadStream",
+        "createWriteStream",
+    ],
+    "fs/promises": [
+        "access",
+        "readFile",
+        "writeFile",
+        "appendFile",
+        "copyFile",
+        "cp",
+        "open",
+        "opendir",
+        "mkdir",
+        "mkdtemp",
+        "readdir",
+        "rename",
+        "stat",
+        "lstat",
+        "chmod",
+        "chown",
+        "utimes",
+        "truncate",
+        "unlink",
+        "rm",
+        "rmdir",
+        "realpath",
+        "readlink",
+        "symlink",
+        "link",
+    ],
+    module: [
+        "createRequire",
+        "Module",
+        "isBuiltin",
+        "builtinModules",
+        "SourceMap",
+        "syncBuiltinESMExports",
+    ],
+    os: [
+        "arch",
+        "platform",
+        "tmpdir",
+        "homedir",
+        "hostname",
+        "type",
+        "release",
+        "constants",
+    ],
+    http: [
+        "request",
+        "get",
+        "createServer",
+        "Server",
+        "IncomingMessage",
+        "ServerResponse",
+        "Agent",
+        "validateHeaderName",
+        "validateHeaderValue",
+        "METHODS",
+        "STATUS_CODES",
+    ],
+    https: ["request", "get", "createServer", "Agent", "globalAgent"],
+    dns: ["lookup", "resolve", "resolve4", "resolve6", "promises"],
+    child_process: [
+        "spawn",
+        "spawnSync",
+        "exec",
+        "execSync",
+        "execFile",
+        "execFileSync",
+        "fork",
+    ],
+    process: [
+        "argv",
+        "env",
+        "cwd",
+        "chdir",
+        "exit",
+        "pid",
+        "platform",
+        "version",
+        "versions",
+        "stdout",
+        "stderr",
+        "stdin",
+        "nextTick",
+    ],
+    path: [
+        "sep",
+        "delimiter",
+        "basename",
+        "dirname",
+        "extname",
+        "format",
+        "isAbsolute",
+        "join",
+        "normalize",
+        "parse",
+        "relative",
+        "resolve",
+    ],
+    async_hooks: [
+        "AsyncLocalStorage",
+        "AsyncResource",
+        "createHook",
+        "executionAsyncId",
+        "triggerAsyncId",
+    ],
+    perf_hooks: [
+        "performance",
+        "PerformanceObserver",
+        "PerformanceEntry",
+        "monitorEventLoopDelay",
+        "createHistogram",
+        "constants",
+    ],
+    diagnostics_channel: [
+        "channel",
+        "hasSubscribers",
+        "tracingChannel",
+        "Channel",
+    ],
+    stream: [
+        "Readable",
+        "Writable",
+        "Duplex",
+        "Transform",
+        "PassThrough",
+        "Stream",
+        "pipeline",
+        "finished",
+        "promises",
+        "addAbortSignal",
+        "compose",
+    ],
+    "stream/web": [
+        "ReadableStream",
+        "ReadableStreamDefaultReader",
+        "ReadableStreamBYOBReader",
+        "ReadableStreamBYOBRequest",
+        "ReadableByteStreamController",
+        "ReadableStreamDefaultController",
+        "TransformStream",
+        "TransformStreamDefaultController",
+        "WritableStream",
+        "WritableStreamDefaultWriter",
+        "WritableStreamDefaultController",
+        "ByteLengthQueuingStrategy",
+        "CountQueuingStrategy",
+        "TextEncoderStream",
+        "TextDecoderStream",
+        "CompressionStream",
+        "DecompressionStream",
+    ],
+};
+/**
+ * Normalize a module specifier to its canonical form if it's a known built-in.
+ * Returns null for non-builtin specifiers.
+ * Preserves the `node:` prefix when present, strips it otherwise.
+ */
+export function normalizeBuiltinSpecifier(request) {
+    const moduleName = request.replace(/^node:/, "");
+    if (KNOWN_BUILTIN_MODULES.has(moduleName) || hasPolyfill(moduleName)) {
+        return request.startsWith("node:") ? `node:${moduleName}` : moduleName;
+    }
+    return null;
+}
+/** Extract the directory portion of a path (lightweight dirname without node:path). */
+export function getPathDir(path) {
+    const normalizedPath = path.replace(/\\/g, "/");
+    const lastSlash = normalizedPath.lastIndexOf("/");
+    if (lastSlash <= 0)
+        return "/";
+    return normalizedPath.slice(0, lastSlash);
+}

package/dist/default-network-adapter.d.ts

@@ -0,0 +1,13 @@
+import type { NetworkAdapter } from "@secure-exec/core";
+export interface DefaultNetworkAdapterOptions {
+    /** Pre-seed loopback ports that should bypass SSRF checks (e.g. host-managed servers). */
+    initialExemptPorts?: Iterable<number>;
+}
+/** Check whether an IP address falls in a private/reserved range (SSRF protection). */
+export declare function isPrivateIp(ip: string): boolean;
+/**
+ * Create a Node.js network adapter that provides real fetch, DNS, and HTTP
+ * client support. Binary responses are base64-encoded with an
+ * `x-body-encoding` header so the bridge can decode them.
+ */
+export declare function createDefaultNetworkAdapter(options?: DefaultNetworkAdapterOptions): NetworkAdapter;

package/dist/default-network-adapter.js

@@ -0,0 +1,351 @@
+import * as dns from "node:dns";
+import * as net from "node:net";
+import * as http from "node:http";
+import * as https from "node:https";
+import * as zlib from "node:zlib";
+/** Check whether an IP address falls in a private/reserved range (SSRF protection). */
+export function isPrivateIp(ip) {
+    // Normalize IPv4-mapped IPv6 (::ffff:a.b.c.d → a.b.c.d)
+    const normalized = ip.startsWith("::ffff:") ? ip.slice(7) : ip;
+    if (net.isIPv4(normalized)) {
+        const parts = normalized.split(".").map(Number);
+        const [a, b] = parts;
+        return (a === 10 ||
+            (a === 172 && b >= 16 && b <= 31) ||
+            (a === 192 && b === 168) ||
+            a === 127 ||
+            (a === 169 && b === 254) ||
+            a === 0 ||
+            (a >= 224 && a <= 239) ||
+            (a >= 240));
+    }
+    if (net.isIPv6(normalized)) {
+        const lower = normalized.toLowerCase();
+        return (lower === "::1" ||
+            lower === "::" ||
+            lower.startsWith("fc") ||
+            lower.startsWith("fd") ||
+            lower.startsWith("fe80") ||
+            lower.startsWith("ff"));
+    }
+    return false;
+}
+/** Check whether a hostname is a loopback address (127.x.x.x, ::1, localhost). */
+function isLoopbackHost(hostname) {
+    const bare = hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+    if (bare === "localhost" || bare === "::1")
+        return true;
+    if (net.isIPv4(bare) && bare.startsWith("127."))
+        return true;
+    return false;
+}
+function getUrlPort(parsed) {
+    return parsed.port
+        ? Number(parsed.port)
+        : parsed.protocol === "https:" ? 443 : 80;
+}
+/**
+ * Resolve hostname to IP and block private/reserved ranges (SSRF protection).
+ *
+ * Loopback requests are allowed only when an explicit exemption or the
+ * runtime-provided kernel listener checker claims the requested port.
+ */
+async function assertNotPrivateHost(url, allowLoopbackPort) {
+    const parsed = new URL(url);
+    if (parsed.protocol === "data:" || parsed.protocol === "blob:")
+        return;
+    const hostname = parsed.hostname;
+    const bare = hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+    if (isLoopbackHost(hostname)) {
+        const port = getUrlPort(parsed);
+        if (allowLoopbackPort?.(hostname, port)) {
+            return;
+        }
+    }
+    if (net.isIP(bare)) {
+        if (isPrivateIp(bare)) {
+            throw new Error(`SSRF blocked: ${hostname} resolves to private IP`);
+        }
+        return;
+    }
+    const address = await new Promise((resolve, reject) => {
+        dns.lookup(bare, (err, addr) => {
+            if (err)
+                reject(err);
+            else
+                resolve(addr);
+        });
+    });
+    if (isPrivateIp(address)) {
+        throw new Error(`SSRF blocked: ${hostname} resolves to private IP ${address}`);
+    }
+}
+const MAX_REDIRECTS = 20;
+/**
+ * Create a Node.js network adapter that provides real fetch, DNS, and HTTP
+ * client support. Binary responses are base64-encoded with an
+ * `x-body-encoding` header so the bridge can decode them.
+ */
+export function createDefaultNetworkAdapter(options) {
+    const upgradeSockets = new Map();
+    const initialExemptPorts = new Set(options?.initialExemptPorts);
+    let nextUpgradeSocketId = 1;
+    let onUpgradeSocketData = null;
+    let onUpgradeSocketEnd = null;
+    let dynamicLoopbackPortChecker;
+    const allowLoopbackPort = (hostname, port) => {
+        if (initialExemptPorts.has(port))
+            return true;
+        if (dynamicLoopbackPortChecker?.(hostname, port))
+            return true;
+        return false;
+    };
+    const adapter = {
+        __setLoopbackPortChecker(checker) {
+            dynamicLoopbackPortChecker = checker;
+        },
+        upgradeSocketWrite(socketId, dataBase64) {
+            const socket = upgradeSockets.get(socketId);
+            if (socket && !socket.destroyed) {
+                socket.write(Buffer.from(dataBase64, "base64"));
+            }
+        },
+        upgradeSocketEnd(socketId) {
+            const socket = upgradeSockets.get(socketId);
+            if (socket && !socket.destroyed) {
+                socket.end();
+            }
+        },
+        upgradeSocketDestroy(socketId) {
+            const socket = upgradeSockets.get(socketId);
+            if (socket) {
+                socket.destroy();
+                upgradeSockets.delete(socketId);
+            }
+        },
+        setUpgradeSocketCallbacks(callbacks) {
+            onUpgradeSocketData = callbacks.onData;
+            onUpgradeSocketEnd = callbacks.onEnd;
+        },
+        async fetch(url, requestOptions) {
+            let currentUrl = url;
+            let redirected = false;
+            for (let i = 0; i <= MAX_REDIRECTS; i++) {
+                await assertNotPrivateHost(currentUrl, allowLoopbackPort);
+                const response = await fetch(currentUrl, {
+                    method: requestOptions?.method || "GET",
+                    headers: requestOptions?.headers,
+                    body: requestOptions?.body,
+                    redirect: "manual",
+                });
+                const status = response.status;
+                if (status === 301 || status === 302 || status === 303 || status === 307 || status === 308) {
+                    const location = response.headers.get("location");
+                    if (!location)
+                        break;
+                    currentUrl = new URL(location, currentUrl).href;
+                    redirected = true;
+                    if (status === 301 || status === 302 || status === 303) {
+                        requestOptions = { ...requestOptions, method: "GET", body: undefined };
+                    }
+                    continue;
+                }
+                const headers = {};
+                response.headers.forEach((value, key) => {
+                    headers[key] = value;
+                });
+                delete headers["content-encoding"];
+                const contentType = response.headers.get("content-type") || "";
+                const isBinary = contentType.includes("octet-stream") ||
+                    contentType.includes("gzip") ||
+                    currentUrl.endsWith(".tgz");
+                let body;
+                if (isBinary) {
+                    const buffer = await response.arrayBuffer();
+                    body = Buffer.from(buffer).toString("base64");
+                    headers["x-body-encoding"] = "base64";
+                }
+                else {
+                    body = await response.text();
+                }
+                return {
+                    ok: response.ok,
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers,
+                    body,
+                    url: currentUrl,
+                    redirected,
+                };
+            }
+            throw new Error("Too many redirects");
+        },
+        async dnsLookup(hostname) {
+            return new Promise((resolve) => {
+                dns.lookup(hostname, (err, address, family) => {
+                    if (err) {
+                        resolve({ error: err.message, code: err.code || "ENOTFOUND" });
+                    }
+                    else {
+                        resolve({ address, family });
+                    }
+                });
+            });
+        },
+        async httpRequest(url, requestOptions) {
+            await assertNotPrivateHost(url, allowLoopbackPort);
+            return new Promise((resolve, reject) => {
+                const urlObj = new URL(url);
+                const isHttps = urlObj.protocol === "https:";
+                const transport = isHttps ? https : http;
+                const reqOptions = {
+                    hostname: urlObj.hostname,
+                    port: urlObj.port || (isHttps ? 443 : 80),
+                    path: urlObj.pathname + urlObj.search,
+                    method: requestOptions?.method || "GET",
+                    headers: requestOptions?.headers || {},
+                    // Keep host-side pooling disabled so sandbox http.Agent semantics
+                    // are controlled entirely by the bridge layer.
+                    agent: false,
+                    ...(isHttps && requestOptions?.rejectUnauthorized !== undefined && {
+                        rejectUnauthorized: requestOptions.rejectUnauthorized,
+                    }),
+                };
+                const req = transport.request(reqOptions, (res) => {
+                    const chunks = [];
+                    res.on("data", (chunk) => chunks.push(chunk));
+                    res.on("end", async () => {
+                        let buffer = Buffer.concat(chunks);
+                        const contentEncoding = res.headers["content-encoding"];
+                        if (contentEncoding === "gzip" || contentEncoding === "deflate") {
+                            try {
+                                buffer = await new Promise((responseResolve, responseReject) => {
+                                    const decompress = contentEncoding === "gzip" ? zlib.gunzip : zlib.inflate;
+                                    decompress(buffer, (err, result) => {
+                                        if (err)
+                                            responseReject(err);
+                                        else
+                                            responseResolve(result);
+                                    });
+                                });
+                            }
+                            catch {
+                                // Preserve the original buffer when decompression fails.
+                            }
+                        }
+                        const contentType = res.headers["content-type"] || "";
+                        const isBinary = contentType.includes("octet-stream") ||
+                            contentType.includes("gzip") ||
+                            url.endsWith(".tgz");
+                        const headers = {};
+                        const rawHeaders = [...res.rawHeaders];
+                        Object.entries(res.headers).forEach(([key, value]) => {
+                            if (typeof value === "string")
+                                headers[key] = value;
+                            else if (Array.isArray(value))
+                                headers[key] = value.join(", ");
+                        });
+                        delete headers["content-encoding"];
+                        const trailers = {};
+                        if (res.trailers) {
+                            Object.entries(res.trailers).forEach(([key, value]) => {
+                                if (typeof value === "string")
+                                    trailers[key] = value;
+                            });
+                        }
+                        const hasTrailers = Object.keys(trailers).length > 0;
+                        const base = {
+                            status: res.statusCode || 200,
+                            statusText: res.statusMessage || "OK",
+                            headers,
+                            rawHeaders,
+                            url,
+                            ...(hasTrailers ? { trailers } : {}),
+                        };
+                        if (isBinary) {
+                            headers["x-body-encoding"] = "base64";
+                            resolve({ ...base, body: buffer.toString("base64") });
+                        }
+                        else {
+                            resolve({ ...base, body: buffer.toString("utf-8") });
+                        }
+                    });
+                    res.on("error", reject);
+                });
+                req.on("upgrade", (res, socket, head) => {
+                    const headers = {};
+                    const rawHeaders = [...res.rawHeaders];
+                    Object.entries(res.headers).forEach(([key, value]) => {
+                        if (typeof value === "string")
+                            headers[key] = value;
+                        else if (Array.isArray(value))
+                            headers[key] = value.join(", ");
+                    });
+                    const socketId = nextUpgradeSocketId++;
+                    upgradeSockets.set(socketId, socket);
+                    socket.on("data", (chunk) => {
+                        if (onUpgradeSocketData) {
+                            onUpgradeSocketData(socketId, chunk.toString("base64"));
+                        }
+                    });
+                    socket.on("close", () => {
+                        if (onUpgradeSocketEnd) {
+                            onUpgradeSocketEnd(socketId);
+                        }
+                        upgradeSockets.delete(socketId);
+                    });
+                    resolve({
+                        status: res.statusCode || 101,
+                        statusText: res.statusMessage || "Switching Protocols",
+                        headers,
+                        rawHeaders,
+                        body: head.toString("base64"),
+                        url,
+                        upgradeSocketId: socketId,
+                    });
+                });
+                req.on("connect", (res, socket, head) => {
+                    const headers = {};
+                    const rawHeaders = [...res.rawHeaders];
+                    Object.entries(res.headers).forEach(([key, value]) => {
+                        if (typeof value === "string")
+                            headers[key] = value;
+                        else if (Array.isArray(value))
+                            headers[key] = value.join(", ");
+                    });
+                    const socketId = nextUpgradeSocketId++;
+                    upgradeSockets.set(socketId, socket);
+                    socket.on("data", (chunk) => {
+                        if (onUpgradeSocketData) {
+                            onUpgradeSocketData(socketId, chunk.toString("base64"));
+                        }
+                    });
+                    socket.on("close", () => {
+                        if (onUpgradeSocketEnd) {
+                            onUpgradeSocketEnd(socketId);
+                        }
+                        upgradeSockets.delete(socketId);
+                    });
+                    resolve({
+                        status: res.statusCode || 200,
+                        statusText: res.statusMessage || "Connection established",
+                        headers,
+                        rawHeaders,
+                        body: head.toString("base64"),
+                        url,
+                        upgradeSocketId: socketId,
+                    });
+                });
+                req.on("error", reject);
+                if (requestOptions?.body)
+                    req.write(requestOptions.body);
+                req.end();
+            });
+        },
+    };
+    return adapter;
+}