@secure-exec/core 0.1.1-rc.2 → 0.2.0-rc.1

package/dist/shared/permissions.js

@@ -133,9 +133,9 @@ export function wrapFileSystem(fs, permissions) {
             checkFs("createDir", path);
             return fs.createDir(path);
         },
-        mkdir: async (path) => {
+        mkdir: async (path, options) => {
             checkFs("mkdir", path);
-            return fs.mkdir(path);
+            return fs.mkdir(path, options);
         },
         exists: async (path) => {
             checkFs("exists", path);
@@ -190,33 +190,20 @@ export function wrapFileSystem(fs, permissions) {
             checkFs("truncate", path);
             return fs.truncate(path, length);
         },
+        realpath: async (path) => {
+            checkFs("read", path);
+            return fs.realpath(path);
+        },
+        pread: async (path, offset, length) => {
+            checkFs("read", path);
+            return fs.pread(path, offset, length);
+        },
     };
 }
-/**
- * Wrap a NetworkAdapter so externally-originating operations (`listen`, `fetch`,
- * `dns`, `http`) pass through the network permission check.
- * `httpServerClose` is forwarded as-is.
- */
+/** Wrap a NetworkAdapter so external client operations pass through the network permission check. */
 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,
+    const loopbackAwareAdapter = adapter;
+    const wrapped = {
         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);
@@ -229,7 +216,16 @@ export function wrapNetworkAdapter(adapter, permissions) {
             checkPermission(permissions?.network, { op: "http", url, method: options?.method }, (req, reason) => createEaccesError("connect", req.url, reason));
             return adapter.httpRequest(url, options);
         },
+        // Forward upgrade socket methods for bidirectional WebSocket relay
+        upgradeSocketWrite: adapter.upgradeSocketWrite?.bind(adapter),
+        upgradeSocketEnd: adapter.upgradeSocketEnd?.bind(adapter),
+        upgradeSocketDestroy: adapter.upgradeSocketDestroy?.bind(adapter),
+        setUpgradeSocketCallbacks: adapter.setUpgradeSocketCallbacks?.bind(adapter),
     };
+    if (typeof loopbackAwareAdapter.__setLoopbackPortChecker === "function") {
+        wrapped.__setLoopbackPortChecker = (checker) => loopbackAwareAdapter.__setLoopbackPortChecker(checker);
+    }
+    return wrapped;
 }
 /** Wrap a CommandExecutor so spawn passes through the childProcess permission check. */
 export function wrapCommandExecutor(executor, permissions) {
@@ -269,6 +265,8 @@ export function createFsStub() {
         chown: async (path) => stub("chown", path),
         utimes: async (path) => stub("utimes", path),
         truncate: async (path) => stub("open", path),
+        realpath: async (path) => stub("realpath", path),
+        pread: async (path) => stub("open", path),
     };
 }
 /** Create a stub network adapter where every operation throws ENOSYS. */
@@ -277,8 +275,6 @@ export function createNetworkStub() {
         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),

package/dist/types.d.ts

@@ -1,100 +1,8 @@
 /**
- * Minimal filesystem interface for secure-exec.
+ * Core-only types for secure-exec SDK.
  *
- * This interface abstracts filesystem operations needed by the sandbox.
+ * VFS and permission types are now defined in src/kernel/ (canonical source).
  */
-export interface VirtualDirEntry {
-    name: string;
-    isDirectory: boolean;
-}
-export interface VirtualStat {
-    mode: number;
-    size: number;
-    isDirectory: boolean;
-    isSymbolicLink?: boolean;
-    atimeMs: number;
-    mtimeMs: number;
-    ctimeMs: number;
-    birthtimeMs: number;
-}
-export interface VirtualFileSystem {
-    /**
-     * Read a file as binary data.
-     * @throws Error if file doesn't exist.
-     */
-    readFile(path: string): Promise<Uint8Array>;
-    /**
-     * Read a file as text (UTF-8).
-     * @throws Error if file doesn't exist.
-     */
-    readTextFile(path: string): Promise<string>;
-    /**
-     * Read directory entries (file/folder names).
-     * @throws Error if directory doesn't exist.
-     */
-    readDir(path: string): Promise<string[]>;
-    /**
-     * Read directory entries with type metadata.
-     * @throws Error if directory doesn't exist.
-     */
-    readDirWithTypes(path: string): Promise<VirtualDirEntry[]>;
-    /**
-     * Write a file (creates parent directories as needed).
-     * @param path - Absolute path to the file.
-     * @param content - String or binary content.
-     */
-    writeFile(path: string, content: string | Uint8Array): Promise<void>;
-    /**
-     * Create a single directory level.
-     * @throws Error if parent doesn't exist.
-     */
-    createDir(path: string): Promise<void>;
-    /**
-     * Create a directory recursively (creates parent directories as needed).
-     * Should not throw if directory already exists.
-     */
-    mkdir(path: string): Promise<void>;
-    /**
-     * Check if a path exists (file or directory).
-     */
-    exists(path: string): Promise<boolean>;
-    /**
-     * Get file or directory metadata.
-     * @throws Error if path doesn't exist.
-     */
-    stat(path: string): Promise<VirtualStat>;
-    /**
-     * Remove a file.
-     * @throws Error if file doesn't exist.
-     */
-    removeFile(path: string): Promise<void>;
-    /**
-     * Remove an empty directory.
-     * @throws Error if directory doesn't exist or is not empty.
-     */
-    removeDir(path: string): Promise<void>;
-    /**
-     * Rename or move a file/directory.
-     * Behavior SHOULD be atomic when supported by the backing store.
-     */
-    rename(oldPath: string, newPath: string): Promise<void>;
-    /** Create a symbolic link at linkPath pointing to target. */
-    symlink(target: string, linkPath: string): Promise<void>;
-    /** Read the target of a symbolic link. */
-    readlink(path: string): Promise<string>;
-    /** Like stat but does not follow symlinks. */
-    lstat(path: string): Promise<VirtualStat>;
-    /** Create a hard link from oldPath to newPath. */
-    link(oldPath: string, newPath: string): Promise<void>;
-    /** Change file mode bits. */
-    chmod(path: string, mode: number): Promise<void>;
-    /** Change file owner and group. */
-    chown(path: string, uid: number, gid: number): Promise<void>;
-    /** Update access and modification timestamps. */
-    utimes(path: string, atime: number, mtime: number): Promise<void>;
-    /** Truncate a file to a specified length. */
-    truncate(path: string, length: number): Promise<void>;
-}
 export interface SpawnedProcess {
     writeStdin(data: Uint8Array | string): void;
     closeStdin(): void;
@@ -132,12 +40,14 @@ export interface NetworkServerListenOptions {
     port?: number;
     hostname?: string;
     onRequest(request: NetworkServerRequest): Promise<NetworkServerResponse> | NetworkServerResponse;
+    /** Called when an HTTP upgrade request arrives (e.g. WebSocket). */
+    onUpgrade?(request: NetworkServerRequest, head: string, socketId: number): void;
+    /** Called when the real upgrade socket receives data from the remote peer. */
+    onUpgradeSocketData?(socketId: number, dataBase64: string): void;
+    /** Called when the real upgrade socket closes. */
+    onUpgradeSocketEnd?(socketId: number): void;
 }
 export interface NetworkAdapter {
-    httpServerListen?(options: NetworkServerListenOptions): Promise<{
-        address: NetworkServerAddress | null;
-    }>;
-    httpServerClose?(serverId: number): Promise<void>;
     fetch(url: string, options: {
         method?: string;
         headers?: Record<string, string>;
@@ -170,38 +80,18 @@ export interface NetworkAdapter {
         body: string;
         url: string;
         trailers?: Record<string, string>;
+        upgradeSocketId?: number;
     }>;
-}
-export interface PermissionDecision {
-    allow: boolean;
-    reason?: string;
-}
-export type PermissionCheck<T> = (request: T) => PermissionDecision;
-export interface FsAccessRequest {
-    op: "read" | "write" | "mkdir" | "createDir" | "readdir" | "stat" | "rm" | "rename" | "exists" | "chmod" | "chown" | "link" | "symlink" | "readlink" | "truncate" | "utimes";
-    path: string;
-}
-export interface NetworkAccessRequest {
-    op: "fetch" | "http" | "dns" | "listen";
-    url?: string;
-    method?: string;
-    hostname?: string;
-}
-export interface ChildProcessAccessRequest {
-    command: string;
-    args: string[];
-    cwd?: string;
-    env?: Record<string, string>;
-}
-export interface EnvAccessRequest {
-    op: "read" | "write";
-    key: string;
-    value?: string;
-}
-export interface Permissions {
-    fs?: PermissionCheck<FsAccessRequest>;
-    network?: PermissionCheck<NetworkAccessRequest>;
-    childProcess?: PermissionCheck<ChildProcessAccessRequest>;
-    env?: PermissionCheck<EnvAccessRequest>;
+    /** Write data from the sandbox to a real upgrade socket on the host. */
+    upgradeSocketWrite?(socketId: number, dataBase64: string): void;
+    /** End a real upgrade socket on the host. */
+    upgradeSocketEnd?(socketId: number): void;
+    /** Destroy a real upgrade socket on the host. */
+    upgradeSocketDestroy?(socketId: number): void;
+    /** Register callbacks for client-side upgrade socket data push. */
+    setUpgradeSocketCallbacks?(callbacks: {
+        onData: (socketId: number, dataBase64: string) => void;
+        onEnd: (socketId: number) => void;
+    }): void;
 }
 export type { DriverRuntimeConfig, NodeRuntimeDriver, NodeRuntimeDriverFactory, PythonRuntimeDriver, PythonRuntimeDriverFactory, RuntimeDriver, RuntimeDriverFactory, RuntimeDriverOptions, SharedRuntimeDriver, SystemDriver, } from "./runtime-driver.js";

package/dist/types.js

@@ -1 +1,6 @@
+/**
+ * Core-only types for secure-exec SDK.
+ *
+ * VFS and permission types are now defined in src/kernel/ (canonical source).
+ */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secure-exec/core",
-  "version": "0.1.1-rc.2",
+  "version": "0.2.0-rc.1",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
@@ -60,6 +60,11 @@
       "import": "./dist/types.js",
       "default": "./dist/types.js"
     },
+    "./internal/kernel": {
+      "types": "./dist/kernel/index.d.ts",
+      "import": "./dist/kernel/index.js",
+      "default": "./dist/kernel/index.js"
+    },
     "./internal/generated/isolate-runtime": {
       "types": "./dist/generated/isolate-runtime.d.ts",
       "import": "./dist/generated/isolate-runtime.js",
@@ -74,34 +79,19 @@
       "types": "./dist/shared/*.d.ts",
       "import": "./dist/shared/*.js",
       "default": "./dist/shared/*.js"
-    },
-    "./internal/bridge": {
-      "types": "./dist/bridge/index.d.ts",
-      "import": "./dist/bridge/index.js",
-      "default": "./dist/bridge/index.js"
     }
   },
-  "dependencies": {
-    "buffer": "^6.0.3",
-    "esbuild": "^0.27.1",
-    "node-stdlib-browser": "^1.3.1",
-    "sucrase": "^3.35.0",
-    "text-encoding-utf-8": "^1.0.2",
-    "whatwg-url": "^15.1.0"
-  },
   "devDependencies": {
     "@types/node": "^22.10.2",
-    "typescript": "^5.7.2"
+    "@xterm/headless": "^6.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
   },
   "scripts": {
     "check-types:src": "tsc --noEmit",
     "check-types:isolate-runtime": "tsc -p tsconfig.isolate-runtime.json --noEmit",
-    "check-types": "pnpm run build:generated && pnpm run check-types:src && pnpm run check-types:isolate-runtime",
-    "build:bridge": "esbuild src/bridge/index.ts --bundle --format=iife --global-name=bridge --outfile=dist/bridge.js",
-    "build:polyfills": "node scripts/build-polyfills.mjs",
-    "build:isolate-runtime": "node scripts/build-isolate-runtime.mjs",
-    "build:generated": "pnpm run build:polyfills && pnpm run build:isolate-runtime",
-    "build": "pnpm run build:bridge && pnpm run build:generated && tsc",
-    "test": "echo 'no tests yet'"
+    "check-types": "pnpm run check-types:src && pnpm run check-types:isolate-runtime",
+    "build": "tsc",
+    "test": "vitest run"
   }
 }

package/dist/bridge/active-handles.d.ts

@@ -1,22 +0,0 @@
-/**
- * Register an active handle that keeps the sandbox alive.
- * Throws if the handle cap (_maxHandles) would be exceeded.
- * @param id Unique identifier for the handle
- * @param description Human-readable description for debugging
- */
-export declare function _registerHandle(id: string, description: string): void;
-/**
- * Unregister a handle. If no handles remain, resolves all waiters.
- * @param id The handle identifier to unregister
- */
-export declare function _unregisterHandle(id: string): void;
-/**
- * Wait for all active handles to complete.
- * Returns immediately if no handles are active.
- */
-export declare function _waitForActiveHandles(): Promise<void>;
-/**
- * Get list of currently active handles (for debugging).
- * Returns array of [id, description] tuples.
- */
-export declare function _getActiveHandles(): Array<[string, string]>;

package/dist/bridge/active-handles.js

@@ -1,55 +0,0 @@
-import { exposeCustomGlobal } from "../shared/global-exposure.js";
-// Map of active handles: id -> description (for debugging)
-const _activeHandles = new Map();
-// Resolvers waiting for all handles to complete
-let _waitResolvers = [];
-/**
- * Register an active handle that keeps the sandbox alive.
- * Throws if the handle cap (_maxHandles) would be exceeded.
- * @param id Unique identifier for the handle
- * @param description Human-readable description for debugging
- */
-export function _registerHandle(id, description) {
-    // Enforce handle cap (skip check for re-registration of existing handle)
-    if (typeof _maxHandles !== "undefined" && !_activeHandles.has(id) && _activeHandles.size >= _maxHandles) {
-        throw new Error("ERR_RESOURCE_BUDGET_EXCEEDED: maximum active handles exceeded");
-    }
-    _activeHandles.set(id, description);
-}
-/**
- * Unregister a handle. If no handles remain, resolves all waiters.
- * @param id The handle identifier to unregister
- */
-export function _unregisterHandle(id) {
-    _activeHandles.delete(id);
-    if (_activeHandles.size === 0 && _waitResolvers.length > 0) {
-        const resolvers = _waitResolvers;
-        _waitResolvers = [];
-        resolvers.forEach((r) => r());
-    }
-}
-/**
- * Wait for all active handles to complete.
- * Returns immediately if no handles are active.
- */
-export function _waitForActiveHandles() {
-    if (_activeHandles.size === 0) {
-        return Promise.resolve();
-    }
-    return new Promise((resolve) => {
-        _waitResolvers.push(resolve);
-    });
-}
-/**
- * Get list of currently active handles (for debugging).
- * Returns array of [id, description] tuples.
- */
-export function _getActiveHandles() {
-    return Array.from(_activeHandles.entries());
-}
-// Install on globalThis for use by other bridge modules and exec().
-// Lock bridge internals so sandbox code cannot replace lifecycle hooks.
-exposeCustomGlobal("_registerHandle", _registerHandle);
-exposeCustomGlobal("_unregisterHandle", _unregisterHandle);
-exposeCustomGlobal("_waitForActiveHandles", _waitForActiveHandles);
-exposeCustomGlobal("_getActiveHandles", _getActiveHandles);

package/dist/bridge/child-process.d.ts

@@ -1,99 +0,0 @@
-import type * as nodeChildProcess from "child_process";
-type EventListener = (...args: unknown[]) => void;
-interface StdinStream {
-    writable: boolean;
-    write(data: unknown): boolean;
-    end(): void;
-    on(): StdinStream;
-    once(): StdinStream;
-    emit(): boolean;
-}
-interface OutputStreamStub {
-    readable: boolean;
-    _listeners: Record<string, EventListener[]>;
-    _onceListeners: Record<string, EventListener[]>;
-    _maxListeners: number;
-    _maxListenersWarned: Set<string>;
-    on(event: string, listener: EventListener): OutputStreamStub;
-    once(event: string, listener: EventListener): OutputStreamStub;
-    emit(event: string, ...args: unknown[]): boolean;
-    read(): null;
-    setEncoding(): OutputStreamStub;
-    setMaxListeners(n: number): OutputStreamStub;
-    getMaxListeners(): number;
-    pipe<T extends NodeJS.WritableStream>(dest: T): T;
-}
-/**
- * Polyfill of Node.js `ChildProcess`. Provides event-emitting stdin/stdout/stderr
- * streams. In streaming mode, data arrives via the `_childProcessDispatch` global
- * that the host calls with stdout/stderr/exit events keyed by session ID.
- */
-declare class ChildProcess {
-    private _listeners;
-    private _onceListeners;
-    private _maxListeners;
-    private _maxListenersWarned;
-    pid: number;
-    killed: boolean;
-    exitCode: number | null;
-    signalCode: NodeJS.Signals | null;
-    connected: boolean;
-    spawnfile: string;
-    spawnargs: string[];
-    stdin: StdinStream;
-    stdout: OutputStreamStub;
-    stderr: OutputStreamStub;
-    stdio: [StdinStream, OutputStreamStub, OutputStreamStub];
-    constructor();
-    on(event: string, listener: EventListener): this;
-    once(event: string, listener: EventListener): this;
-    off(event: string, listener: EventListener): this;
-    removeListener(event: string, listener: EventListener): this;
-    setMaxListeners(n: number): this;
-    getMaxListeners(): number;
-    private _checkMaxListeners;
-    emit(event: string, ...args: unknown[]): boolean;
-    kill(_signal?: NodeJS.Signals | number): boolean;
-    ref(): this;
-    unref(): this;
-    disconnect(): void;
-    _complete(stdout: string, stderr: string, code: number): void;
-}
-interface ExecError extends Error {
-    code?: number;
-    killed?: boolean;
-    signal?: string | null;
-    cmd?: string;
-    stdout?: string;
-    stderr?: string;
-    status?: number;
-    output?: [null, string, string];
-}
-declare function exec(command: string, options?: nodeChildProcess.ExecOptions | ((error: ExecError | null, stdout: string, stderr: string) => void), callback?: (error: ExecError | null, stdout: string, stderr: string) => void): ChildProcess;
-declare function execSync(command: string, options?: nodeChildProcess.ExecSyncOptions): string | Buffer;
-declare function spawn(command: string, args?: readonly string[] | nodeChildProcess.SpawnOptions, options?: nodeChildProcess.SpawnOptions): ChildProcess;
-interface SpawnSyncResult {
-    pid: number;
-    output: [null, string | Buffer, string | Buffer];
-    stdout: string | Buffer;
-    stderr: string | Buffer;
-    status: number | null;
-    signal: NodeJS.Signals | null;
-    error?: Error;
-}
-declare function spawnSync(command: string, args?: readonly string[] | nodeChildProcess.SpawnSyncOptions, options?: nodeChildProcess.SpawnSyncOptions): SpawnSyncResult;
-declare function execFile(file: string, args?: readonly string[] | nodeChildProcess.ExecFileOptions | ((error: ExecError | null, stdout: string, stderr: string) => void), options?: nodeChildProcess.ExecFileOptions | ((error: ExecError | null, stdout: string, stderr: string) => void), callback?: (error: ExecError | null, stdout: string, stderr: string) => void): ChildProcess;
-declare function execFileSync(file: string, args?: readonly string[] | nodeChildProcess.ExecFileSyncOptions, options?: nodeChildProcess.ExecFileSyncOptions): string | Buffer;
-declare function fork(_modulePath: string, _args?: readonly string[] | nodeChildProcess.ForkOptions, _options?: nodeChildProcess.ForkOptions): never;
-declare const childProcess: {
-    ChildProcess: typeof ChildProcess;
-    exec: typeof exec;
-    execSync: typeof execSync;
-    spawn: typeof spawn;
-    spawnSync: typeof spawnSync;
-    execFile: typeof execFile;
-    execFileSync: typeof execFileSync;
-    fork: typeof fork;
-};
-export { ChildProcess, exec, execSync, spawn, spawnSync, execFile, execFileSync, fork };
-export default childProcess;