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

package/dist/kernel/types.js

@@ -0,0 +1,89 @@
+/**
+ * Kernel type definitions.
+ *
+ * The kernel is the shared OS layer. All runtimes make "syscalls" to the
+ * kernel for filesystem, process, pipe, and FD operations.
+ */
+// FD open flags
+export const O_RDONLY = 0;
+export const O_WRONLY = 1;
+export const O_RDWR = 2;
+export const O_CREAT = 0o100;
+export const O_EXCL = 0o200;
+export const O_TRUNC = 0o1000;
+export const O_APPEND = 0o2000;
+export const O_NONBLOCK = 0o4;
+export const O_CLOEXEC = 0o2000000;
+// fcntl commands
+export const F_DUPFD = 0;
+export const F_GETFD = 1;
+export const F_SETFD = 2;
+export const F_GETFL = 3;
+export const F_DUPFD_CLOEXEC = 1030;
+// FD flags (for F_GETFD / F_SETFD)
+export const FD_CLOEXEC = 1;
+// Seek whence
+export const SEEK_SET = 0;
+export const SEEK_CUR = 1;
+export const SEEK_END = 2;
+// File types
+export const FILETYPE_UNKNOWN = 0;
+export const FILETYPE_CHARACTER_DEVICE = 2;
+export const FILETYPE_DIRECTORY = 3;
+export const FILETYPE_REGULAR_FILE = 4;
+export const FILETYPE_SYMBOLIC_LINK = 7;
+export const FILETYPE_PIPE = 6;
+/**
+ * Structured error for kernel operations.
+ * Carries a machine-readable `code` so callers can map to errno without
+ * string matching.
+ */
+export class KernelError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = "KernelError";
+    }
+}
+/** Returns the POSIX-standard default termios: canonical on, echo on, isig on, opost+onlcr on. */
+export function defaultTermios() {
+    return {
+        icrnl: true,
+        opost: true,
+        onlcr: true,
+        icanon: true,
+        echo: true,
+        isig: true,
+        cc: {
+            vintr: 0x03, // ^C
+            vquit: 0x1c, // ^\
+            vsusp: 0x1a, // ^Z
+            veof: 0x04, // ^D
+            verase: 0x7f, // DEL
+        },
+    };
+}
+// Signals
+export const SIGHUP = 1;
+export const SIGINT = 2;
+export const SIGQUIT = 3;
+export const SIGKILL = 9;
+export const SIGPIPE = 13;
+export const SIGALRM = 14;
+export const SIGTERM = 15;
+export const SIGCHLD = 17;
+export const SIGCONT = 18;
+export const SIGSTOP = 19;
+export const SIGTSTP = 20;
+export const SIGWINCH = 28;
+// sigaction flags
+export const SA_RESTART = 0x10000000;
+export const SA_RESETHAND = 0x80000000;
+export const SA_NOCLDSTOP = 0x00000001;
+// sigprocmask how values
+export const SIG_BLOCK = 0;
+export const SIG_UNBLOCK = 1;
+export const SIG_SETMASK = 2;
+// waitpid options (POSIX bitmask)
+export const WNOHANG = 1;

package/dist/kernel/user.d.ts

@@ -0,0 +1,29 @@
+/**
+ * User/group identity manager.
+ *
+ * Provides configurable uid/gid and passwd-entry generation for the kernel.
+ * OS-level concern — lives in the kernel so all runtimes share the same identity.
+ */
+export interface UserConfig {
+    uid?: number;
+    gid?: number;
+    euid?: number;
+    egid?: number;
+    username?: string;
+    homedir?: string;
+    shell?: string;
+    gecos?: string;
+}
+export declare class UserManager {
+    readonly uid: number;
+    readonly gid: number;
+    readonly euid: number;
+    readonly egid: number;
+    readonly username: string;
+    readonly homedir: string;
+    readonly shell: string;
+    readonly gecos: string;
+    constructor(config?: UserConfig);
+    /** Generate a passwd-format string for the given uid. */
+    getpwuid(uid: number): string;
+}

package/dist/kernel/user.js

@@ -0,0 +1,35 @@
+/**
+ * User/group identity manager.
+ *
+ * Provides configurable uid/gid and passwd-entry generation for the kernel.
+ * OS-level concern — lives in the kernel so all runtimes share the same identity.
+ */
+export class UserManager {
+    uid;
+    gid;
+    euid;
+    egid;
+    username;
+    homedir;
+    shell;
+    gecos;
+    constructor(config) {
+        this.uid = config?.uid ?? 1000;
+        this.gid = config?.gid ?? 1000;
+        this.euid = config?.euid ?? this.uid;
+        this.egid = config?.egid ?? this.gid;
+        this.username = config?.username ?? "user";
+        this.homedir = config?.homedir ?? "/home/user";
+        this.shell = config?.shell ?? "/bin/sh";
+        this.gecos = config?.gecos ?? "";
+    }
+    /** Generate a passwd-format string for the given uid. */
+    getpwuid(uid) {
+        if (uid === this.uid) {
+            return `${this.username}:x:${this.uid}:${this.gid}:${this.gecos}:${this.homedir}:${this.shell}`;
+        }
+        // Generic entry for unknown uids
+        const name = `user${uid}`;
+        return `${name}:x:${uid}:${uid}::/home/${name}:/bin/sh`;
+    }
+}

package/dist/kernel/vfs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Virtual Filesystem interface.
+ *
+ * POSIX-complete interface that all filesystem backends must implement.
+ * Extends the original secure-exec VirtualFileSystem with symlinks,
+ * links, permissions, and metadata operations needed by WasmVM's WASI polyfill.
+ */
+export interface VirtualDirEntry {
+    name: string;
+    isDirectory: boolean;
+    isSymbolicLink?: boolean;
+    ino?: number;
+}
+export interface VirtualStat {
+    mode: number;
+    size: number;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    ino: number;
+    nlink: number;
+    uid: number;
+    gid: number;
+}
+export interface VirtualFileSystem {
+    readFile(path: string): Promise<Uint8Array>;
+    readTextFile(path: string): Promise<string>;
+    readDir(path: string): Promise<string[]>;
+    readDirWithTypes(path: string): Promise<VirtualDirEntry[]>;
+    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<VirtualStat>;
+    removeFile(path: string): Promise<void>;
+    removeDir(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    realpath(path: string): Promise<string>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    lstat(path: string): Promise<VirtualStat>;
+    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>;
+    /** Read a range from a file without loading the entire file into memory. */
+    pread(path: string, offset: number, length: number): Promise<Uint8Array>;
+}

package/dist/kernel/vfs.js

@@ -0,0 +1,8 @@
+/**
+ * Virtual Filesystem interface.
+ *
+ * POSIX-complete interface that all filesystem backends must implement.
+ * Extends the original secure-exec VirtualFileSystem with symlinks,
+ * links, permissions, and metadata operations needed by WasmVM's WASI polyfill.
+ */
+export {};

package/dist/kernel/wait.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Unified blocking I/O wait system.
+ *
+ * Provides WaitHandle and WaitQueue primitives for all kernel subsystems
+ * (pipes, sockets, flock, poll) to share the same wait/wake mechanism.
+ * Promise-based — no Atomics.
+ */
+/**
+ * A single wait/wake handle. Callers await wait(), producers call wake().
+ * Each handle resolves exactly once (either by wake or timeout).
+ */
+export declare class WaitHandle {
+    private resolve;
+    private timer;
+    private settled;
+    readonly promise: Promise<void>;
+    /** True if the handle resolved via timeout rather than wake(). */
+    timedOut: boolean;
+    constructor(timeoutMs?: number);
+    /** Suspend until woken or timed out. */
+    wait(): Promise<void>;
+    /** Wake this handle. No-op if already settled. */
+    wake(): void;
+    /** Whether this handle has already been resolved. */
+    get isSettled(): boolean;
+}
+/**
+ * A FIFO queue of WaitHandles. Subsystems enqueue waiters and producers
+ * wake them one-at-a-time or all-at-once.
+ */
+export declare class WaitQueue {
+    private waiters;
+    /** Create and enqueue a new WaitHandle. */
+    enqueue(timeoutMs?: number): WaitHandle;
+    /** Remove a waiter from the queue without waking it. */
+    remove(handle: WaitHandle): void;
+    /** Wake exactly one waiter (FIFO order). Returns true if a waiter was woken. */
+    wakeOne(): boolean;
+    /** Wake all enqueued waiters. Returns the number woken. */
+    wakeAll(): number;
+    /** Number of pending (unsettled) waiters. */
+    get pending(): number;
+    /** Remove all waiters without waking them. */
+    clear(): void;
+}

package/dist/kernel/wait.js

@@ -0,0 +1,112 @@
+/**
+ * Unified blocking I/O wait system.
+ *
+ * Provides WaitHandle and WaitQueue primitives for all kernel subsystems
+ * (pipes, sockets, flock, poll) to share the same wait/wake mechanism.
+ * Promise-based — no Atomics.
+ */
+/**
+ * A single wait/wake handle. Callers await wait(), producers call wake().
+ * Each handle resolves exactly once (either by wake or timeout).
+ */
+export class WaitHandle {
+    resolve = null;
+    timer = null;
+    settled = false;
+    promise;
+    /** True if the handle resolved via timeout rather than wake(). */
+    timedOut = false;
+    constructor(timeoutMs) {
+        this.promise = new Promise((resolve) => {
+            this.resolve = resolve;
+        });
+        if (timeoutMs !== undefined && timeoutMs >= 0) {
+            this.timer = setTimeout(() => {
+                if (!this.settled) {
+                    this.timedOut = true;
+                    this.settled = true;
+                    this.resolve();
+                    this.resolve = null;
+                }
+            }, timeoutMs);
+        }
+    }
+    /** Suspend until woken or timed out. */
+    wait() {
+        return this.promise;
+    }
+    /** Wake this handle. No-op if already settled. */
+    wake() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.resolve();
+        this.resolve = null;
+    }
+    /** Whether this handle has already been resolved. */
+    get isSettled() {
+        return this.settled;
+    }
+}
+/**
+ * A FIFO queue of WaitHandles. Subsystems enqueue waiters and producers
+ * wake them one-at-a-time or all-at-once.
+ */
+export class WaitQueue {
+    waiters = [];
+    /** Create and enqueue a new WaitHandle. */
+    enqueue(timeoutMs) {
+        const handle = new WaitHandle(timeoutMs);
+        this.waiters.push(handle);
+        return handle;
+    }
+    /** Remove a waiter from the queue without waking it. */
+    remove(handle) {
+        const index = this.waiters.indexOf(handle);
+        if (index >= 0) {
+            this.waiters.splice(index, 1);
+        }
+    }
+    /** Wake exactly one waiter (FIFO order). Returns true if a waiter was woken. */
+    wakeOne() {
+        while (this.waiters.length > 0) {
+            const handle = this.waiters.shift();
+            if (!handle.isSettled) {
+                handle.wake();
+                return true;
+            }
+            // Skip already-settled handles (timed out)
+        }
+        return false;
+    }
+    /** Wake all enqueued waiters. Returns the number woken. */
+    wakeAll() {
+        let count = 0;
+        for (const handle of this.waiters) {
+            if (!handle.isSettled) {
+                handle.wake();
+                count++;
+            }
+        }
+        this.waiters.length = 0;
+        return count;
+    }
+    /** Number of pending (unsettled) waiters. */
+    get pending() {
+        // Compact settled handles while counting
+        let count = 0;
+        for (const handle of this.waiters) {
+            if (!handle.isSettled)
+                count++;
+        }
+        return count;
+    }
+    /** Remove all waiters without waking them. */
+    clear() {
+        this.waiters.length = 0;
+    }
+}

package/dist/kernel/wstatus.d.ts

@@ -0,0 +1,21 @@
+/**
+ * POSIX wstatus encoding/decoding.
+ *
+ * Encodes how a process terminated into a single integer matching
+ * the layout expected by WIFEXITED / WEXITSTATUS / WIFSIGNALED / WTERMSIG.
+ *
+ *   Normal exit:  (exitCode & 0xFF) << 8  (bits 8-15 = exit code, bits 0-6 = 0)
+ *   Signal death: signalNumber & 0x7F     (bits 0-6 = signal, bits 8-15 = 0)
+ */
+/** Encode a normal exit into POSIX wstatus. */
+export declare function encodeExitStatus(exitCode: number): number;
+/** Encode a signal death into POSIX wstatus. */
+export declare function encodeSignalStatus(signal: number): number;
+/** True if process exited normally (not killed by a signal). */
+export declare function WIFEXITED(status: number): boolean;
+/** Extract exit code (only valid when WIFEXITED is true). */
+export declare function WEXITSTATUS(status: number): number;
+/** True if process was killed by a signal. */
+export declare function WIFSIGNALED(status: number): boolean;
+/** Extract signal number (only valid when WIFSIGNALED is true). */
+export declare function WTERMSIG(status: number): number;

package/dist/kernel/wstatus.js

@@ -0,0 +1,33 @@
+/**
+ * POSIX wstatus encoding/decoding.
+ *
+ * Encodes how a process terminated into a single integer matching
+ * the layout expected by WIFEXITED / WEXITSTATUS / WIFSIGNALED / WTERMSIG.
+ *
+ *   Normal exit:  (exitCode & 0xFF) << 8  (bits 8-15 = exit code, bits 0-6 = 0)
+ *   Signal death: signalNumber & 0x7F     (bits 0-6 = signal, bits 8-15 = 0)
+ */
+/** Encode a normal exit into POSIX wstatus. */
+export function encodeExitStatus(exitCode) {
+    return (exitCode & 0xff) << 8;
+}
+/** Encode a signal death into POSIX wstatus. */
+export function encodeSignalStatus(signal) {
+    return signal & 0x7f;
+}
+/** True if process exited normally (not killed by a signal). */
+export function WIFEXITED(status) {
+    return (status & 0x7f) === 0;
+}
+/** Extract exit code (only valid when WIFEXITED is true). */
+export function WEXITSTATUS(status) {
+    return (status >> 8) & 0xff;
+}
+/** True if process was killed by a signal. */
+export function WIFSIGNALED(status) {
+    return (status & 0x7f) !== 0;
+}
+/** Extract signal number (only valid when WIFSIGNALED is true). */
+export function WTERMSIG(status) {
+    return status & 0x7f;
+}

package/dist/module-resolver.d.ts

@@ -1,4 +1,8 @@
 /**
+ * @deprecated Canonical source moved to @secure-exec/nodejs (US-003).
+ * This copy is retained for backward compatibility during phased migration.
+ * Will be removed in US-005 when kernel merges into core.
+ *
  * Module classification and resolution helpers.
  *
  * Node built-ins are split into three tiers:

package/dist/module-resolver.js

@@ -1,4 +1,8 @@
 /**
+ * @deprecated Canonical source moved to @secure-exec/nodejs (US-003).
+ * This copy is retained for backward compatibility during phased migration.
+ * Will be removed in US-005 when kernel merges into core.
+ *
  * Module classification and resolution helpers.
  *
  * Node built-ins are split into three tiers:

package/dist/package-bundler.d.ts

@@ -1,4 +1,9 @@
-import type { VirtualFileSystem } from "./types.js";
+/**
+ * @deprecated Canonical source moved to @secure-exec/nodejs (US-003).
+ * This copy is retained for backward compatibility during phased migration.
+ * Will be removed in US-005 when kernel merges into core.
+ */
+import type { VirtualFileSystem } from "./kernel/vfs.js";
 type ResolveMode = "require" | "import";
 interface PackageJson {
     main?: string;

package/dist/runtime-driver.d.ts

@@ -1,5 +1,7 @@
 import type { StdioHook, ExecOptions, ExecResult, OSConfig, PythonRunOptions, PythonRunResult, ProcessConfig, RunResult, TimingMitigation } from "./shared/api-types.js";
-import type { CommandExecutor, NetworkAdapter, Permissions, VirtualFileSystem } from "./types.js";
+import type { Permissions } from "./kernel/types.js";
+import type { VirtualFileSystem } from "./kernel/vfs.js";
+import type { CommandExecutor, NetworkAdapter } from "./types.js";
 export interface DriverRuntimeConfig {
     process: ProcessConfig;
     os: OSConfig;