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

package/dist/kernel/socket-table.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Virtual socket table.
+ *
+ * Manages kernel-level sockets: create, bind, listen, accept, connect,
+ * send, recv, close, poll, per-process isolation, and resource limits.
+ * Loopback connections are routed entirely in-kernel without touching
+ * the host network stack.
+ */
+import { WaitQueue } from "./wait.js";
+import type { NetworkAccessRequest, PermissionCheck } from "./types.js";
+import type { ProcessSignalState } from "./types.js";
+import type { HostNetworkAdapter, HostSocket, HostListener, HostUdpSocket } from "./host-adapter.js";
+import type { VirtualFileSystem } from "./vfs.js";
+export declare const AF_INET = 2;
+export declare const AF_INET6 = 10;
+export declare const AF_UNIX = 1;
+export declare const SOCK_STREAM = 1;
+export declare const SOCK_DGRAM = 2;
+export declare const SOL_SOCKET = 1;
+export declare const IPPROTO_TCP = 6;
+export declare const SO_REUSEADDR = 2;
+export declare const SO_KEEPALIVE = 9;
+export declare const SO_RCVBUF = 8;
+export declare const SO_SNDBUF = 7;
+export declare const TCP_NODELAY = 1;
+export declare const MSG_PEEK = 2;
+export declare const MSG_DONTWAIT = 64;
+export declare const MSG_NOSIGNAL = 16384;
+export declare const MAX_DATAGRAM_SIZE = 65535;
+export declare const MAX_UDP_QUEUE_DEPTH = 128;
+export declare const S_IFSOCK = 49152;
+export type InetAddr = {
+    host: string;
+    port: number;
+};
+export type UnixAddr = {
+    path: string;
+};
+export type SockAddr = InetAddr | UnixAddr;
+export declare function isInetAddr(addr: SockAddr): addr is InetAddr;
+export declare function isUnixAddr(addr: SockAddr): addr is UnixAddr;
+export interface UdpDatagram {
+    data: Uint8Array;
+    srcAddr: SockAddr;
+}
+/** Canonical string key for a socket address ("host:port" or unix path). */
+export declare function addrKey(addr: SockAddr): string;
+/** Canonical string key for a socket option ("level:optname"). */
+export declare function optKey(level: number, optname: number): string;
+export type SocketState = "created" | "bound" | "listening" | "connecting" | "connected" | "read-closed" | "write-closed" | "closed";
+export interface KernelSocket {
+    readonly id: number;
+    readonly domain: number;
+    readonly type: number;
+    readonly protocol: number;
+    state: SocketState;
+    nonBlocking: boolean;
+    localAddr?: SockAddr;
+    remoteAddr?: SockAddr;
+    options: Map<string, number>;
+    readonly pid: number;
+    readBuffer: Uint8Array[];
+    readWaiters: WaitQueue;
+    backlog: number[];
+    backlogLimit: number;
+    acceptWaiters: WaitQueue;
+    /** Peer socket ID for connected loopback/socketpair sockets. */
+    peerId?: number;
+    /** True when the peer has shut down its write side (half-close EOF). */
+    peerWriteClosed?: boolean;
+    /** True when connected via host adapter (external network). */
+    external?: boolean;
+    /** Host socket for external connections (data relay). */
+    hostSocket?: HostSocket;
+    /** Host listener for external-facing server sockets. */
+    hostListener?: HostListener;
+    /** Queued datagrams for UDP sockets (preserves message boundaries). */
+    datagramQueue: UdpDatagram[];
+    /** Host UDP socket for external datagram routing. */
+    hostUdpSocket?: HostUdpSocket;
+    /** Tracks whether bind() was originally requested with port 0. */
+    requestedEphemeralPort?: boolean;
+}
+type BlockingSocketWait = {
+    block: true;
+    pid: number;
+};
+export declare class SocketTable {
+    private sockets;
+    private nextSocketId;
+    private readonly maxSockets;
+    private readonly networkCheck?;
+    private readonly hostAdapter?;
+    private readonly vfs?;
+    private readonly getSignalState?;
+    /** Bound/listening address → socket ID. Used for EADDRINUSE and TCP routing. */
+    private listeners;
+    /** Bound UDP address → socket ID. Separate from TCP listeners. */
+    private udpBindings;
+    constructor(options?: {
+        maxSockets?: number;
+        networkCheck?: PermissionCheck<NetworkAccessRequest>;
+        hostAdapter?: HostNetworkAdapter;
+        vfs?: VirtualFileSystem;
+        getSignalState?: (pid: number) => ProcessSignalState;
+    });
+    /**
+     * Create a new socket owned by the given process.
+     * Returns the kernel socket ID.
+     */
+    create(domain: number, type: number, protocol: number, pid: number): number;
+    /**
+     * Get a socket by ID. Returns null if not found.
+     */
+    get(socketId: number): KernelSocket | null;
+    /**
+     * Check network permission for an operation. Throws EACCES if the
+     * configured policy denies the request or if no policy is set
+     * (deny-by-default). Loopback callers should skip this method.
+     */
+    checkNetworkPermission(op: NetworkAccessRequest["op"], addr?: SockAddr): void;
+    /**
+     * Bind a socket to an address. Transitions to 'bound' and registers
+     * the address in the listeners map for port reservation.
+     *
+     * For Unix domain sockets (UnixAddr), creates a socket file in the
+     * VFS if one is configured.
+     */
+    bind(socketId: number, addr: SockAddr, options?: {
+        mode?: number;
+    }): Promise<void>;
+    /**
+     * Mark a bound socket as listening. The socket must already be bound.
+     * Checks network permission before transitioning.
+     *
+     * When `external` is true and a host adapter is available, creates a
+     * real TCP listener via `hostAdapter.tcpListen()` and starts an accept
+     * pump that feeds incoming connections into the kernel backlog.
+     */
+    listen(socketId: number, backlogSize?: number, options?: {
+        external?: boolean;
+    }): Promise<void>;
+    /**
+     * Accept a pending connection from a listening socket's backlog.
+     * Returns the connected socket ID, or null if backlog is empty (EAGAIN).
+     */
+    accept(socketId: number): number | null;
+    accept(socketId: number, options: BlockingSocketWait): Promise<number | null>;
+    /**
+     * Find a listening socket that matches the given address.
+     * Checks exact match first, then wildcard (0.0.0.0 / ::).
+     */
+    findListener(addr: SockAddr): KernelSocket | null;
+    /**
+     * Shut down part of a full-duplex connection.
+     * - 'write': peer recv() gets EOF, local send() returns EPIPE
+     * - 'read': local recv() returns EOF immediately
+     * - 'both': equivalent to shutdown('read') + shutdown('write')
+     */
+    shutdown(socketId: number, how: "read" | "write" | "both"): void;
+    /** Signal EOF to the peer by waking their readWaiters. */
+    private shutdownWrite;
+    /** Discard unread data and mark the read side as closed. */
+    private shutdownRead;
+    /**
+     * Create a pair of connected sockets atomically (for IPC).
+     * Returns [socketId1, socketId2]. Both are pre-connected with
+     * peerId linking, so data written to one appears in the other's
+     * readBuffer via send/recv.
+     */
+    socketpair(domain: number, type: number, protocol: number, pid: number): [number, number];
+    /**
+     * Set a socket option. Stores the value keyed by "level:optname".
+     */
+    setsockopt(socketId: number, level: number, optname: number, optval: number): void;
+    /** Toggle non-blocking behavior for an existing socket. */
+    setNonBlocking(socketId: number, nonBlocking: boolean): void;
+    /**
+     * Get a socket option. Returns the value, or undefined if not set.
+     */
+    getsockopt(socketId: number, level: number, optname: number): number | undefined;
+    /** Get the bound/local address for a socket. */
+    getLocalAddr(socketId: number): SockAddr;
+    /** Get the connected peer address for a socket. */
+    getRemoteAddr(socketId: number): SockAddr;
+    /**
+     * Connect a socket to a remote address. For loopback (addr matches a
+     * kernel listener), creates a paired server-side socket and queues it
+     * in the listener's backlog — loopback is always allowed regardless of
+     * permission policy. External addresses are checked against the network
+     * permission policy and routed through the host adapter.
+     */
+    connect(socketId: number, addr: SockAddr): Promise<void>;
+    /**
+     * Send data to the connected peer. Writes to the peer's readBuffer
+     * and wakes one pending reader. Returns bytes written.
+     *
+     * Flags: MSG_NOSIGNAL suppresses SIGPIPE — returns EPIPE error
+     * instead of raising SIGPIPE on a broken connection.
+     *
+     * For external sockets, checks network permission before sending.
+     */
+    send(socketId: number, data: Uint8Array, flags?: number): number;
+    /**
+     * Receive data from the socket's readBuffer. Returns null if no data
+     * is available and the socket is non-blocking, or if the peer has
+     * closed (EOF).
+     *
+     * Flags:
+     * - MSG_PEEK: read data without consuming it from the buffer
+     * - MSG_DONTWAIT: return EAGAIN if no data (even on blocking socket)
+     */
+    recv(socketId: number, maxBytes: number, flags?: number): Uint8Array | null;
+    recv(socketId: number, maxBytes: number, flags: number, options: BlockingSocketWait): Promise<Uint8Array | null>;
+    /**
+     * Send a datagram to a specific address (UDP only).
+     * For loopback, delivers to the kernel-bound UDP socket. For external
+     * addresses, routes through the host adapter (fire-and-forget). Sends
+     * to unbound ports are silently dropped (UDP semantics).
+     *
+     * Returns bytes "sent" (always data.length for UDP — drops are silent).
+     */
+    sendTo(socketId: number, data: Uint8Array, flags: number, destAddr: SockAddr): number;
+    private getUdpSourceAddr;
+    /**
+     * Receive a datagram from a UDP socket. Returns the datagram and the
+     * source address, or null if no datagram is queued.
+     *
+     * Message boundaries are preserved: each sendTo produces exactly one
+     * recvFrom result. If the datagram exceeds maxBytes, excess is
+     * discarded (UDP truncation semantics).
+     *
+     * Flags: MSG_PEEK reads without consuming, MSG_DONTWAIT throws EAGAIN.
+     */
+    recvFrom(socketId: number, maxBytes: number, flags?: number): {
+        data: Uint8Array;
+        srcAddr: SockAddr;
+    } | null;
+    /**
+     * Set up external UDP routing for a bound datagram socket.
+     * Creates a host UDP socket via the host adapter and starts a recv
+     * pump that feeds incoming datagrams into the kernel datagramQueue.
+     */
+    bindExternalUdp(socketId: number): Promise<void>;
+    /**
+     * Close a socket. The caller must own the socket (per-process isolation).
+     * Wakes all pending waiters and frees resources.
+     */
+    close(socketId: number, pid: number): void;
+    /**
+     * Poll a socket for readability, writability, and hangup.
+     */
+    poll(socketId: number): {
+        readable: boolean;
+        writable: boolean;
+        hangup: boolean;
+    };
+    /**
+     * Clean up all sockets owned by a process (called on process exit).
+     */
+    closeAllForProcess(pid: number): void;
+    /**
+     * Clean up all sockets (called on kernel dispose).
+     */
+    disposeAll(): void;
+    /** Number of open sockets. */
+    get size(): number;
+    /** Create a socket file in the VFS with S_IFSOCK mode. */
+    private createSocketFile;
+    private requireSocket;
+    /** Wait for an inbound connection, restarting when SA_RESTART applies. */
+    private acceptBlocking;
+    private destroySocket;
+    /** Background pump: reads from host socket and feeds kernel readBuffer. */
+    private startReadPump;
+    /** Complete a non-blocking external connect in the background. */
+    private startExternalConnect;
+    /** Background pump: accepts incoming connections from host listener and feeds kernel backlog. */
+    private startAcceptPump;
+    /** Look up a listening socket by exact address key. */
+    private getListeningSocket;
+    /** Peek up to maxBytes from a socket's readBuffer without consuming. */
+    private peekFromBuffer;
+    /** Consume up to maxBytes from a socket's readBuffer. */
+    private consumeFromBuffer;
+    /** Wait for readable data, restarting when SA_RESTART applies. */
+    private recvBlocking;
+    /** Check whether recv() could still yield data later instead of EOF. */
+    private canBlockForRecv;
+    /** Wait for socket readiness or an interrupting signal. */
+    private waitForSocketWake;
+    /** Find a bound UDP socket that matches the given address (exact + wildcard). */
+    findBoundUdp(addr: SockAddr): KernelSocket | null;
+    /** Look up a bound UDP socket by exact address key. */
+    private getBoundUdpSocket;
+    /** Check if a UDP address conflicts with an existing UDP binding. */
+    private isUdpAddrInUse;
+    /** Background pump: receives datagrams from host UDP socket and feeds kernel datagramQueue. */
+    private startUdpRecvPump;
+    /** Check if an address conflicts with an existing TCP binding. */
+    private isAddrInUse;
+    /** Assign a kernel-managed ephemeral port for bind(port=0). */
+    private assignEphemeralPort;
+}
+export {};