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

package/dist/kernel/permissions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Permission enforcement layer.
+ *
+ * Deny-by-default access control. Wraps VFS and other kernel operations
+ * with permission checks that throw on denial.
+ */
+import type { Permissions } from "./types.js";
+import type { VirtualFileSystem } from "./vfs.js";
+/**
+ * Wrap a VFS with permission checks on every operation.
+ */
+export declare function wrapFileSystem(fs: VirtualFileSystem, permissions?: Permissions): VirtualFileSystem;
+/**
+ * Filter an env record through the env permission check.
+ * Returns only allowed key-value pairs.
+ */
+export declare function filterEnv(env: Record<string, string> | undefined, permissions?: Permissions): Record<string, string>;
+/**
+ * Check childProcess permission before spawning.
+ * No-op when no permissions or no childProcess check is configured.
+ */
+export declare function checkChildProcess(permissions: Permissions | undefined, command: string, args: string[], cwd?: string): void;
+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;

package/dist/kernel/permissions.js

@@ -0,0 +1,118 @@
+/**
+ * Permission enforcement layer.
+ *
+ * Deny-by-default access control. Wraps VFS and other kernel operations
+ * with permission checks that throw on denial.
+ */
+import { KernelError } from "./types.js";
+function checkPermission(check, request, errorFactory) {
+    if (!check)
+        throw errorFactory(request);
+    const decision = check(request);
+    if (!decision?.allow)
+        throw errorFactory(request, decision?.reason);
+}
+function fsError(op, path, reason) {
+    const msg = reason
+        ? `permission denied, ${op} '${path ?? ""}': ${reason}`
+        : `permission denied, ${op} '${path ?? ""}'`;
+    return new KernelError("EACCES", msg);
+}
+/**
+ * Wrap a VFS with permission checks on every operation.
+ */
+export function wrapFileSystem(fs, permissions) {
+    const check = (op, path) => {
+        checkPermission(permissions?.fs, { op, path }, (req, reason) => fsError(op, req.path, reason));
+    };
+    const wrapped = {
+        prepareOpenSync: (path, flags) => {
+            if ((flags & 0o100) !== 0 || (flags & 0o1000) !== 0) {
+                check("write", path);
+            }
+            const syncFs = fs;
+            return syncFs.prepareOpenSync?.(path, flags) ?? false;
+        },
+        readFile: async (path) => { check("read", path); return fs.readFile(path); },
+        readTextFile: async (path) => { check("read", path); return fs.readTextFile(path); },
+        readDir: async (path) => { check("readdir", path); return fs.readDir(path); },
+        readDirWithTypes: async (path) => { check("readdir", path); return fs.readDirWithTypes(path); },
+        writeFile: async (path, content) => { check("write", path); return fs.writeFile(path, content); },
+        createDir: async (path) => { check("createDir", path); return fs.createDir(path); },
+        mkdir: async (path, options) => { check("mkdir", path); return fs.mkdir(path, options); },
+        exists: async (path) => { check("exists", path); return fs.exists(path); },
+        stat: async (path) => { check("stat", path); return fs.stat(path); },
+        removeFile: async (path) => { check("rm", path); return fs.removeFile(path); },
+        removeDir: async (path) => { check("rm", path); return fs.removeDir(path); },
+        rename: async (oldPath, newPath) => {
+            check("rename", oldPath);
+            check("rename", newPath);
+            return fs.rename(oldPath, newPath);
+        },
+        realpath: async (path) => { check("read", path); return fs.realpath(path); },
+        symlink: async (target, linkPath) => { check("symlink", linkPath); return fs.symlink(target, linkPath); },
+        readlink: async (path) => { check("readlink", path); return fs.readlink(path); },
+        lstat: async (path) => { check("stat", path); return fs.lstat(path); },
+        link: async (oldPath, newPath) => { check("link", newPath); return fs.link(oldPath, newPath); },
+        chmod: async (path, mode) => { check("chmod", path); return fs.chmod(path, mode); },
+        chown: async (path, uid, gid) => { check("chown", path); return fs.chown(path, uid, gid); },
+        utimes: async (path, atime, mtime) => { check("utimes", path); return fs.utimes(path, atime, mtime); },
+        truncate: async (path, length) => { check("truncate", path); return fs.truncate(path, length); },
+        pread: async (path, offset, length) => { check("read", path); return fs.pread(path, offset, length); },
+    };
+    return wrapped;
+}
+/**
+ * Filter an env record through the env permission check.
+ * Returns only allowed key-value pairs.
+ */
+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;
+}
+/**
+ * Check childProcess permission before spawning.
+ * No-op when no permissions or no childProcess check is configured.
+ */
+export function checkChildProcess(permissions, command, args, cwd) {
+    if (!permissions?.childProcess)
+        return;
+    const request = { command, args, cwd };
+    const decision = permissions.childProcess(request);
+    if (!decision?.allow) {
+        const msg = decision?.reason
+            ? `permission denied, spawn '${command}': ${decision.reason}`
+            : `permission denied, spawn '${command}'`;
+        throw new KernelError("EACCES", msg);
+    }
+}
+// Permission presets
+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,
+};

package/dist/kernel/pipe-manager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pipe manager.
+ *
+ * Creates and manages pipes for inter-process communication.
+ * Supports cross-runtime pipes: data flows through kernel-managed buffers.
+ * SharedArrayBuffer ring buffers are deferred — this uses buffered pipes.
+ */
+import type { FileDescription } from "./types.js";
+import { FILETYPE_PIPE } from "./types.js";
+import type { ProcessFDTable } from "./fd-table.js";
+export interface PipeEnd {
+    description: FileDescription;
+    filetype: typeof FILETYPE_PIPE;
+}
+/** Maximum buffered bytes per pipe before writers block or O_NONBLOCK returns EAGAIN. */
+export declare const MAX_PIPE_BUFFER_BYTES = 65536;
+export declare class PipeManager {
+    private pipes;
+    /** Map description ID → pipe ID for routing reads/writes */
+    private descToPipe;
+    private nextPipeId;
+    private nextDescId;
+    /** Called before EPIPE when a write hits a closed read end. Receives writer PID. */
+    onBrokenPipe: ((pid: number) => void) | null;
+    /**
+     * Create a pipe. Returns two FileDescriptions:
+     * one for reading and one for writing.
+     */
+    createPipe(): {
+        read: PipeEnd;
+        write: PipeEnd;
+    };
+    /** Write data to a pipe's write end. Delivers SIGPIPE via onBrokenPipe when read end is closed. */
+    write(descriptionId: number, data: Uint8Array, writerPid?: number): number | Promise<number>;
+    /** Read data from a pipe's read end. Returns null on EOF. */
+    read(descriptionId: number, length: number): Promise<Uint8Array | null>;
+    /** Close one end of a pipe. */
+    close(descriptionId: number): void;
+    /** Check if a description ID belongs to a pipe */
+    isPipe(descriptionId: number): boolean;
+    /** Query poll state for a pipe end (used by poll/select syscalls). */
+    pollState(descriptionId: number): {
+        readable: boolean;
+        writable: boolean;
+        hangup: boolean;
+    } | null;
+    /** Get the pipe ID for a description, or undefined if not a pipe */
+    pipeIdFor(descriptionId: number): number | undefined;
+    /** Wait for a pipe poll state change (data, capacity, or hangup). */
+    waitForPoll(descriptionId: number, timeoutMs?: number): Promise<void>;
+    /**
+     * Create pipe FDs in the given FD table.
+     * Returns the FD numbers for {read, write}.
+     */
+    createPipeFDs(fdTable: ProcessFDTable): {
+        readFd: number;
+        writeFd: number;
+    };
+    private bufferSize;
+    private drainBuffer;
+    private writeBlocking;
+    private writeAvailable;
+    private assertWriteOpen;
+}

package/dist/kernel/pipe-manager.js

@@ -0,0 +1,267 @@
+/**
+ * Pipe manager.
+ *
+ * Creates and manages pipes for inter-process communication.
+ * Supports cross-runtime pipes: data flows through kernel-managed buffers.
+ * SharedArrayBuffer ring buffers are deferred — this uses buffered pipes.
+ */
+import { FILETYPE_PIPE, O_NONBLOCK, O_RDONLY, O_WRONLY, KernelError } from "./types.js";
+import { WaitQueue } from "./wait.js";
+/** Maximum buffered bytes per pipe before writers block or O_NONBLOCK returns EAGAIN. */
+export const MAX_PIPE_BUFFER_BYTES = 65_536; // 64 KB — matches Linux default
+export class PipeManager {
+    pipes = new Map();
+    /** Map description ID → pipe ID for routing reads/writes */
+    descToPipe = new Map();
+    nextPipeId = 1;
+    nextDescId = 100_000; // High range to avoid FD table collisions
+    /** Called before EPIPE when a write hits a closed read end. Receives writer PID. */
+    onBrokenPipe = null;
+    /**
+     * Create a pipe. Returns two FileDescriptions:
+     * one for reading and one for writing.
+     */
+    createPipe() {
+        const id = this.nextPipeId++;
+        const readDesc = {
+            id: this.nextDescId++,
+            path: `pipe:${id}:read`,
+            cursor: 0n,
+            flags: O_RDONLY,
+            refCount: 0, // Not in any FD table yet — openWith() will bump
+        };
+        const writeDesc = {
+            id: this.nextDescId++,
+            path: `pipe:${id}:write`,
+            cursor: 0n,
+            flags: O_WRONLY,
+            refCount: 0, // Not in any FD table yet — openWith() will bump
+        };
+        const state = {
+            id,
+            buffer: [],
+            closed: { read: false, write: false },
+            readDescription: readDesc,
+            writeDescription: writeDesc,
+            readWaiters: [],
+            writeWaiters: new WaitQueue(),
+            pollWaiters: new WaitQueue(),
+        };
+        this.pipes.set(id, state);
+        this.descToPipe.set(readDesc.id, { pipeId: id, end: "read" });
+        this.descToPipe.set(writeDesc.id, { pipeId: id, end: "write" });
+        return {
+            read: { description: readDesc, filetype: FILETYPE_PIPE },
+            write: { description: writeDesc, filetype: FILETYPE_PIPE },
+        };
+    }
+    /** Write data to a pipe's write end. Delivers SIGPIPE via onBrokenPipe when read end is closed. */
+    write(descriptionId, data, writerPid) {
+        const ref = this.descToPipe.get(descriptionId);
+        if (!ref || ref.end !== "write")
+            throw new KernelError("EBADF", "not a pipe write end");
+        const state = this.pipes.get(ref.pipeId);
+        if (!state)
+            throw new KernelError("EBADF", "pipe not found");
+        const nonBlocking = (state.writeDescription.flags & O_NONBLOCK) !== 0;
+        const written = this.writeAvailable(state, data, writerPid);
+        if (written === data.length) {
+            return data.length;
+        }
+        if (nonBlocking) {
+            if (written === 0) {
+                throw new KernelError("EAGAIN", "pipe buffer full");
+            }
+            return written;
+        }
+        return this.writeBlocking(state, data, written, writerPid);
+    }
+    /** Read data from a pipe's read end. Returns null on EOF. */
+    read(descriptionId, length) {
+        const ref = this.descToPipe.get(descriptionId);
+        if (!ref || ref.end !== "read")
+            throw new KernelError("EBADF", "not a pipe read end");
+        const state = this.pipes.get(ref.pipeId);
+        if (!state)
+            throw new KernelError("EBADF", "pipe not found");
+        // Data available in buffer
+        if (state.buffer.length > 0) {
+            const data = this.drainBuffer(state, length);
+            state.writeWaiters.wakeOne();
+            state.pollWaiters.wakeAll();
+            return Promise.resolve(data);
+        }
+        // Write end closed — EOF
+        if (state.closed.write) {
+            return Promise.resolve(null);
+        }
+        // Block until data or EOF
+        return new Promise((resolve) => {
+            state.readWaiters.push(resolve);
+        });
+    }
+    /** Close one end of a pipe. */
+    close(descriptionId) {
+        const ref = this.descToPipe.get(descriptionId);
+        if (!ref)
+            return;
+        const state = this.pipes.get(ref.pipeId);
+        if (!state)
+            return;
+        if (ref.end === "read") {
+            state.closed.read = true;
+            state.writeWaiters.wakeAll();
+        }
+        else {
+            state.closed.write = true;
+            // Notify any blocked readers with EOF
+            for (const waiter of state.readWaiters) {
+                waiter(null);
+            }
+            state.readWaiters.length = 0;
+            state.writeWaiters.wakeAll();
+        }
+        state.pollWaiters.wakeAll();
+        this.descToPipe.delete(descriptionId);
+        // Clean up when both ends are closed
+        if (state.closed.read && state.closed.write) {
+            this.pipes.delete(ref.pipeId);
+        }
+    }
+    /** Check if a description ID belongs to a pipe */
+    isPipe(descriptionId) {
+        return this.descToPipe.has(descriptionId);
+    }
+    /** Query poll state for a pipe end (used by poll/select syscalls). */
+    pollState(descriptionId) {
+        const ref = this.descToPipe.get(descriptionId);
+        if (!ref)
+            return null;
+        const state = this.pipes.get(ref.pipeId);
+        if (!state)
+            return null;
+        if (ref.end === "read") {
+            const hasData = this.bufferSize(state) > 0;
+            return {
+                readable: hasData || state.closed.write,
+                writable: false,
+                hangup: state.closed.write,
+            };
+        }
+        else {
+            return {
+                readable: false,
+                writable: !state.closed.read && this.bufferSize(state) < MAX_PIPE_BUFFER_BYTES,
+                hangup: state.closed.read,
+            };
+        }
+    }
+    /** Get the pipe ID for a description, or undefined if not a pipe */
+    pipeIdFor(descriptionId) {
+        return this.descToPipe.get(descriptionId)?.pipeId;
+    }
+    /** Wait for a pipe poll state change (data, capacity, or hangup). */
+    async waitForPoll(descriptionId, timeoutMs) {
+        const ref = this.descToPipe.get(descriptionId);
+        if (!ref)
+            throw new KernelError("EBADF", "not a pipe description");
+        const state = this.pipes.get(ref.pipeId);
+        if (!state)
+            throw new KernelError("EBADF", "pipe not found");
+        const handle = state.pollWaiters.enqueue(timeoutMs);
+        try {
+            await handle.wait();
+        }
+        finally {
+            state.pollWaiters.remove(handle);
+        }
+    }
+    /**
+     * Create pipe FDs in the given FD table.
+     * Returns the FD numbers for {read, write}.
+     */
+    createPipeFDs(fdTable) {
+        const { read, write } = this.createPipe();
+        const readFd = fdTable.openWith(read.description, read.filetype);
+        const writeFd = fdTable.openWith(write.description, write.filetype);
+        return { readFd, writeFd };
+    }
+    bufferSize(state) {
+        let size = 0;
+        for (const chunk of state.buffer)
+            size += chunk.length;
+        return size;
+    }
+    drainBuffer(state, length) {
+        // Concatenate buffered chunks up to `length` bytes
+        const chunks = [];
+        let remaining = length;
+        while (remaining > 0 && state.buffer.length > 0) {
+            const chunk = state.buffer[0];
+            if (chunk.length <= remaining) {
+                chunks.push(chunk);
+                remaining -= chunk.length;
+                state.buffer.shift();
+            }
+            else {
+                chunks.push(chunk.subarray(0, remaining));
+                state.buffer[0] = chunk.subarray(remaining);
+                remaining = 0;
+            }
+        }
+        if (chunks.length === 1)
+            return chunks[0];
+        const total = chunks.reduce((sum, c) => sum + c.length, 0);
+        const result = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    }
+    async writeBlocking(state, data, offset, writerPid) {
+        while (offset < data.length) {
+            const handle = state.writeWaiters.enqueue();
+            try {
+                await handle.wait();
+            }
+            finally {
+                state.writeWaiters.remove(handle);
+            }
+            offset += this.writeAvailable(state, data.subarray(offset), writerPid);
+        }
+        return data.length;
+    }
+    writeAvailable(state, data, writerPid) {
+        this.assertWriteOpen(state, writerPid);
+        if (data.length === 0)
+            return 0;
+        // If readers are waiting, deliver directly without growing the buffer.
+        if (state.readWaiters.length > 0 && state.buffer.length === 0) {
+            const waiter = state.readWaiters.shift();
+            waiter(new Uint8Array(data));
+            state.pollWaiters.wakeAll();
+            return data.length;
+        }
+        const capacity = MAX_PIPE_BUFFER_BYTES - this.bufferSize(state);
+        if (capacity <= 0) {
+            return 0;
+        }
+        const bytesToWrite = Math.min(capacity, data.length);
+        state.buffer.push(new Uint8Array(data.subarray(0, bytesToWrite)));
+        state.pollWaiters.wakeAll();
+        return bytesToWrite;
+    }
+    assertWriteOpen(state, writerPid) {
+        if (state.closed.write)
+            throw new KernelError("EPIPE", "write end closed");
+        if (state.closed.read) {
+            // Deliver SIGPIPE before EPIPE (POSIX: signal first, then errno)
+            if (writerPid !== undefined && this.onBrokenPipe) {
+                this.onBrokenPipe(writerPid);
+            }
+            throw new KernelError("EPIPE", "read end closed");
+        }
+    }
+}

package/dist/kernel/proc-layer.d.ts

@@ -0,0 +1,11 @@
+import type { FDTableManager } from "./fd-table.js";
+import type { ProcessTable } from "./process-table.js";
+import type { VirtualFileSystem } from "./vfs.js";
+export interface ProcLayerOptions {
+    processTable: ProcessTable;
+    fdTableManager: FDTableManager;
+    hostname?: string;
+}
+export declare function resolveProcSelfPath(path: string, pid: number): string;
+export declare function createProcessScopedFileSystem(vfs: VirtualFileSystem, pid: number): VirtualFileSystem;
+export declare function createProcLayer(vfs: VirtualFileSystem, options: ProcLayerOptions): VirtualFileSystem;