whale-code 6.4.0 → 6.5.0

package/dist/node/portal/index.js

@@ -0,0 +1,250 @@
+/**
+ * PortalManager — coordinator for portal connections.
+ *
+ * Manages portal sessions, handles incoming requests on the target side,
+ * and provides the public API used by the CLI and runtime.
+ */
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { PORTAL_MARKER } from "./protocol.js";
+import { PortalSession } from "./session.js";
+import { handleShell } from "./shell.js";
+import { handleFilePush, handleFilePull } from "./transfer.js";
+import { handleForward } from "./forward.js";
+import { handleScreen } from "./screen.js";
+import { handleClipboard } from "./clipboard.js";
+import { checkPermission } from "./permissions.js";
+export class PortalManager extends EventEmitter {
+    config;
+    sessions = new Map();
+    gateway;
+    constructor(config) {
+        super();
+        this.config = config;
+        this.gateway = config.gateway;
+        this.setupHandlers();
+    }
+    // ============================================================================
+    // PUBLIC API — used by CLI commands (initiator side)
+    // ============================================================================
+    /**
+     * Open a portal to a target node.
+     * Returns a PortalSession that can be used to open streams.
+     */
+    async connect(targetNodeId, capabilities) {
+        const sessionId = randomUUID();
+        const session = new PortalSession({
+            sessionId,
+            isInitiator: true,
+            targetNodeId,
+            sendBinary: (data) => this.gateway.sendBinary(data),
+            sendJson: (msg) => this.sendJson(msg),
+        });
+        this.sessions.set(sessionId, session);
+        // Send portal request via JSON
+        this.sendJson({
+            type: "portal_request",
+            session_id: sessionId,
+            target_node_id: targetNodeId,
+            capabilities,
+            requester_node_id: this.config.nodeConfig.node_id,
+            requester_hostname: (await import("node:os")).hostname(),
+            requester_role: "admin", // role determined by server/target
+        });
+        // Wait for accept/reject
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.sessions.delete(sessionId);
+                session.close("timeout");
+                reject(new Error("Portal request timed out"));
+            }, 30_000);
+            session.once("accepted", () => {
+                clearTimeout(timeout);
+                resolve(session);
+            });
+            session.once("close", (reason) => {
+                clearTimeout(timeout);
+                this.sessions.delete(sessionId);
+                reject(new Error(`Portal rejected: ${reason}`));
+            });
+        });
+    }
+    /**
+     * Get all active sessions.
+     */
+    getSessions() {
+        return Array.from(this.sessions.values()).map(s => s.getInfo());
+    }
+    /**
+     * Close a session by ID.
+     */
+    closeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return false;
+        session.close();
+        this.sessions.delete(sessionId);
+        return true;
+    }
+    /**
+     * Close all sessions.
+     */
+    closeAll() {
+        for (const [id, session] of this.sessions) {
+            session.close();
+            this.sessions.delete(id);
+        }
+    }
+    // ============================================================================
+    // SETUP — wire gateway handlers
+    // ============================================================================
+    setupHandlers() {
+        // Handle incoming JSON messages (portal_request, portal_accept, etc.)
+        this.gateway.onCommand("portal_request", async (msg) => {
+            await this.handlePortalRequest(msg);
+            return null;
+        });
+        // Handle binary frames — route to correct session
+        this.gateway.onBinary((data) => {
+            if (data.length > 17 && data[0] === PORTAL_MARKER) {
+                this.routeBinaryFrame(data);
+            }
+        });
+        // Also handle portal_accept, portal_reject, portal_close as regular messages
+        this.gateway.onCommand("portal_accept", async (msg) => {
+            const session = this.sessions.get(msg.session_id);
+            if (session) {
+                session.accept();
+                if (msg.hostname) {
+                    session.targetHostname = msg.hostname;
+                }
+            }
+            return null;
+        });
+        this.gateway.onCommand("portal_reject", async (msg) => {
+            const session = this.sessions.get(msg.session_id);
+            if (session) {
+                this.sessions.delete(msg.session_id);
+                session.close(msg.reason || "rejected");
+            }
+            return null;
+        });
+        this.gateway.onCommand("portal_close", async (msg) => {
+            const session = this.sessions.get(msg.session_id);
+            if (session) {
+                this.sessions.delete(msg.session_id);
+                session.close("remote closed");
+            }
+            return null;
+        });
+    }
+    // ============================================================================
+    // TARGET SIDE — handle incoming portal requests
+    // ============================================================================
+    async handlePortalRequest(request) {
+        const maxSessions = this.config.maxSessions || 5;
+        if (this.sessions.size >= maxSessions) {
+            this.sendJson({
+                type: "portal_reject",
+                session_id: request.session_id,
+                reason: `Max sessions reached (${maxSessions})`,
+            });
+            return;
+        }
+        // Check permissions
+        const autoAccept = this.config.autoAcceptAdmins !== false;
+        const { accepted, reason } = await checkPermission(request, this.config.nodeConfig.store_id, autoAccept);
+        if (!accepted) {
+            this.sendJson({
+                type: "portal_reject",
+                session_id: request.session_id,
+                reason: reason || "Permission denied",
+            });
+            return;
+        }
+        // Create session (responder side)
+        const os = await import("node:os");
+        const session = new PortalSession({
+            sessionId: request.session_id,
+            isInitiator: false,
+            targetNodeId: request.requester_node_id,
+            targetHostname: request.requester_hostname,
+            sendBinary: (data) => this.gateway.sendBinary(data),
+            sendJson: (msg) => this.sendJson(msg),
+        });
+        this.sessions.set(request.session_id, session);
+        // Handle incoming streams (shell, file, etc.)
+        session.on("stream", (stream, meta) => {
+            this.handleIncomingStream(stream, meta);
+        });
+        // Accept
+        session.accept();
+        this.sendJson({
+            type: "portal_accept",
+            session_id: request.session_id,
+            hostname: os.hostname(),
+        });
+        // Cleanup on close
+        session.on("close", () => {
+            this.sessions.delete(request.session_id);
+        });
+        console.log(`[portal] Accepted session ${request.session_id.slice(0, 8)} from ${request.requester_hostname}`);
+    }
+    // ============================================================================
+    // STREAM ROUTING
+    // ============================================================================
+    handleIncomingStream(stream, meta) {
+        switch (meta.channel) {
+            case "shell":
+                handleShell(stream, meta).catch(err => {
+                    console.error("[portal:shell]", err.message);
+                });
+                break;
+            case "file":
+                if ("direction" in meta) {
+                    if (meta.direction === "push") {
+                        handleFilePush(stream, meta, this.config.receiveDir).catch(err => {
+                            console.error("[portal:file:push]", err.message);
+                        });
+                    }
+                    else {
+                        handleFilePull(stream, meta).catch(err => {
+                            console.error("[portal:file:pull]", err.message);
+                        });
+                    }
+                }
+                break;
+            case "forward":
+                handleForward(stream, meta);
+                break;
+            case "screen":
+                handleScreen(stream, meta, this.config.screenCapture || null);
+                break;
+            case "clipboard":
+                handleClipboard(stream, meta);
+                break;
+            default:
+                stream.destroy(new Error(`Unknown channel type: ${meta.channel}`));
+        }
+    }
+    // ============================================================================
+    // BINARY ROUTING
+    // ============================================================================
+    routeBinaryFrame(data) {
+        // Extract session UUID from bytes 1-16
+        const uuidHex = data.subarray(1, 17).toString("hex");
+        const sessionId = `${uuidHex.slice(0, 8)}-${uuidHex.slice(8, 12)}-${uuidHex.slice(12, 16)}-${uuidHex.slice(16, 20)}-${uuidHex.slice(20)}`;
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.receiveRelay(data);
+        }
+    }
+    // ============================================================================
+    // HELPERS
+    // ============================================================================
+    sendJson(msg) {
+        if (this.gateway.isConnected) {
+            this.gateway.sendJson(msg);
+        }
+    }
+}

package/dist/node/portal/multiplexer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Multiplexer — manages multiple streams over a single binary channel.
+ *
+ * Sits between the WebSocket transport and individual PortalStreams.
+ * Handles frame routing, stream lifecycle (SYN/ACK/FIN/RST), and keepalive.
+ */
+import { EventEmitter } from "node:events";
+import { type SynPayload } from "./protocol.js";
+import { PortalStream } from "./stream.js";
+export interface MultiplexerOptions {
+    /** Callback to send raw bytes to the transport (WebSocket) */
+    sendRaw: (data: Buffer) => void;
+    /** Whether this side is the initiator (odd stream IDs) or responder (even stream IDs) */
+    isInitiator: boolean;
+}
+export declare class Multiplexer extends EventEmitter {
+    private streams;
+    private nextStreamId;
+    private sendRaw;
+    private recvBuffer;
+    private keepaliveTimer;
+    private lastRecv;
+    private closed;
+    constructor(opts: MultiplexerOptions);
+    /**
+     * Open a new stream with the given channel metadata.
+     * Returns a Duplex stream that can be piped to/from.
+     */
+    openStream(meta: SynPayload): PortalStream;
+    /**
+     * Feed raw bytes from the transport into the multiplexer.
+     * Call this whenever data arrives on the WebSocket.
+     */
+    receive(data: Buffer): void;
+    /**
+     * Get a stream by ID.
+     */
+    getStream(streamId: number): PortalStream | undefined;
+    /**
+     * Close all streams and stop keepalive.
+     */
+    close(): void;
+    get activeStreams(): number;
+    get isClosed(): boolean;
+    private handleFrame;
+    private createStream;
+    private sendStreamData;
+}

package/dist/node/portal/multiplexer.js

@@ -0,0 +1,207 @@
+/**
+ * Multiplexer — manages multiple streams over a single binary channel.
+ *
+ * Sits between the WebSocket transport and individual PortalStreams.
+ * Handles frame routing, stream lifecycle (SYN/ACK/FIN/RST), and keepalive.
+ */
+import { EventEmitter } from "node:events";
+import { FrameType, decodeFrame, makeDataFrame, makeSynFrame, makeAckFrame, makeFinFrame, makeRstFrame, makePingFrame, makePongFrame, } from "./protocol.js";
+import { PortalStream } from "./stream.js";
+const CHUNK_SIZE = 64 * 1024; // 64KB max per DATA frame
+const KEEPALIVE_INTERVAL = 15_000;
+const KEEPALIVE_TIMEOUT = 30_000;
+export class Multiplexer extends EventEmitter {
+    streams = new Map();
+    nextStreamId;
+    sendRaw;
+    recvBuffer = Buffer.alloc(0);
+    keepaliveTimer = null;
+    lastRecv = Date.now();
+    closed = false;
+    constructor(opts) {
+        super();
+        this.sendRaw = opts.sendRaw;
+        // Initiator uses odd IDs (1, 3, 5...), responder uses even (2, 4, 6...)
+        this.nextStreamId = opts.isInitiator ? 1 : 2;
+        this.keepaliveTimer = setInterval(() => {
+            if (this.closed)
+                return;
+            const now = Date.now();
+            if (now - this.lastRecv > KEEPALIVE_TIMEOUT) {
+                this.emit("timeout");
+                this.close();
+                return;
+            }
+            this.sendRaw(makePingFrame());
+        }, KEEPALIVE_INTERVAL);
+        this.keepaliveTimer.unref();
+    }
+    /**
+     * Open a new stream with the given channel metadata.
+     * Returns a Duplex stream that can be piped to/from.
+     */
+    openStream(meta) {
+        if (this.closed)
+            throw new Error("Multiplexer is closed");
+        const streamId = this.nextStreamId;
+        this.nextStreamId += 2;
+        const stream = this.createStream(streamId, meta);
+        this.streams.set(streamId, stream);
+        // Send SYN
+        this.sendRaw(makeSynFrame(streamId, meta));
+        return stream;
+    }
+    /**
+     * Feed raw bytes from the transport into the multiplexer.
+     * Call this whenever data arrives on the WebSocket.
+     */
+    receive(data) {
+        if (this.closed)
+            return;
+        this.lastRecv = Date.now();
+        // Append to buffer
+        if (this.recvBuffer.length === 0) {
+            this.recvBuffer = data;
+        }
+        else {
+            const combined = Buffer.concat([this.recvBuffer, data]);
+            this.recvBuffer = combined;
+        }
+        // Decode frames
+        let offset = 0;
+        while (true) {
+            let result;
+            try {
+                result = decodeFrame(this.recvBuffer, offset);
+            }
+            catch (err) {
+                this.emit("error", err);
+                // Skip corrupted data
+                this.recvBuffer = Buffer.alloc(0);
+                return;
+            }
+            if (!result)
+                break;
+            offset += result.bytesConsumed;
+            this.handleFrame(result.frame);
+        }
+        // Compact buffer
+        if (offset > 0) {
+            this.recvBuffer = this.recvBuffer.subarray(offset);
+        }
+    }
+    /**
+     * Get a stream by ID.
+     */
+    getStream(streamId) {
+        return this.streams.get(streamId);
+    }
+    /**
+     * Close all streams and stop keepalive.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.keepaliveTimer) {
+            clearInterval(this.keepaliveTimer);
+            this.keepaliveTimer = null;
+        }
+        for (const [id, stream] of this.streams) {
+            stream.pushRst("Multiplexer closed");
+            this.streams.delete(id);
+        }
+        this.emit("close");
+    }
+    get activeStreams() {
+        return this.streams.size;
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    // ============================================================================
+    // INTERNAL
+    // ============================================================================
+    handleFrame(frame) {
+        switch (frame.type) {
+            case FrameType.DATA: {
+                const stream = this.streams.get(frame.streamId);
+                if (stream) {
+                    stream.pushData(frame.payload);
+                }
+                break;
+            }
+            case FrameType.SYN: {
+                // Remote wants to open a new stream
+                let meta;
+                try {
+                    meta = JSON.parse(frame.payload.toString());
+                }
+                catch {
+                    this.sendRaw(makeRstFrame(frame.streamId, "Invalid SYN payload"));
+                    return;
+                }
+                const stream = this.createStream(frame.streamId, meta);
+                this.streams.set(frame.streamId, stream);
+                // Send ACK
+                this.sendRaw(makeAckFrame(frame.streamId));
+                this.emit("stream", stream, meta);
+                break;
+            }
+            case FrameType.ACK: {
+                const stream = this.streams.get(frame.streamId);
+                if (stream) {
+                    this.emit("stream:ack", stream);
+                }
+                break;
+            }
+            case FrameType.FIN: {
+                const stream = this.streams.get(frame.streamId);
+                if (stream) {
+                    stream.pushFin();
+                    if (stream.isFullyClosed) {
+                        this.streams.delete(frame.streamId);
+                    }
+                }
+                break;
+            }
+            case FrameType.RST: {
+                const stream = this.streams.get(frame.streamId);
+                if (stream) {
+                    stream.pushRst(frame.payload.length > 0 ? frame.payload.toString() : undefined);
+                    this.streams.delete(frame.streamId);
+                }
+                break;
+            }
+            case FrameType.PING: {
+                this.sendRaw(makePongFrame());
+                break;
+            }
+            case FrameType.PONG: {
+                // Just updates lastRecv (already done at top of receive())
+                break;
+            }
+        }
+    }
+    createStream(streamId, meta) {
+        return new PortalStream({
+            streamId,
+            channelMeta: meta,
+            sendFrame: (id, data) => this.sendStreamData(id, data),
+            sendFin: (id) => this.sendRaw(makeFinFrame(id)),
+            sendRst: (id, reason) => this.sendRaw(makeRstFrame(id, reason)),
+        });
+    }
+    sendStreamData(streamId, data) {
+        if (this.closed)
+            return;
+        // Chunk large writes
+        let offset = 0;
+        while (offset < data.length) {
+            const end = Math.min(offset + CHUNK_SIZE, data.length);
+            const chunk = data.subarray(offset, end);
+            this.sendRaw(makeDataFrame(streamId, chunk));
+            offset = end;
+        }
+    }
+}

package/dist/node/portal/permissions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Portal Permissions — role checks, approval prompts, and approval cache.
+ *
+ * Permission model:
+ *   Admin  → all capabilities, auto-accept
+ *   Member → shell + file + clipboard, requires first-connect approval
+ *   Viewer → screen (view only) + file pull, always requires approval
+ */
+import type { ChannelType, PortalRequest } from "./protocol.js";
+export type Role = "admin" | "member" | "viewer";
+export declare function setApprovalTtl(minutes: number): void;
+export declare function cacheApproval(requesterNodeId: string, storeId: string, capabilities: ChannelType[]): void;
+export declare function getCachedApproval(requesterNodeId: string, storeId: string): ChannelType[] | null;
+export declare function clearApprovalCache(): void;
+/**
+ * Check if a role can access the requested capabilities.
+ * Returns the subset of capabilities that are allowed.
+ */
+export declare function getAllowedCapabilities(role: Role, requested: ChannelType[]): ChannelType[];
+/**
+ * Check if a role requires interactive approval.
+ */
+export declare function requiresApproval(role: Role): boolean;
+/**
+ * Show an interactive approval prompt on the target node's terminal.
+ * Returns true if accepted, false if denied.
+ */
+export declare function promptApproval(request: PortalRequest): Promise<boolean>;
+/**
+ * Decide whether to accept a portal request.
+ * For admins: auto-accept. For others: check cache, then prompt.
+ */
+export declare function checkPermission(request: PortalRequest, storeId: string, autoAcceptAdmins: boolean): Promise<{
+    accepted: boolean;
+    reason?: string;
+}>;

package/dist/node/portal/permissions.js

@@ -0,0 +1,131 @@
+/**
+ * Portal Permissions — role checks, approval prompts, and approval cache.
+ *
+ * Permission model:
+ *   Admin  → all capabilities, auto-accept
+ *   Member → shell + file + clipboard, requires first-connect approval
+ *   Viewer → screen (view only) + file pull, always requires approval
+ */
+import { createInterface } from "node:readline";
+// ============================================================================
+// CAPABILITY MATRIX
+// ============================================================================
+const ROLE_CAPABILITIES = {
+    admin: ["shell", "file", "clipboard", "forward", "screen"],
+    member: ["shell", "file", "clipboard"],
+    viewer: ["screen", "file"], // file = pull only, enforced at channel level
+};
+// ============================================================================
+// APPROVAL CACHE
+// ============================================================================
+const approvalCache = new Map();
+let approvalTtlMs = 60 * 60 * 1000; // default 1 hour
+export function setApprovalTtl(minutes) {
+    approvalTtlMs = minutes * 60 * 1000;
+}
+function getCacheKey(requesterNodeId, storeId) {
+    return `${storeId}:${requesterNodeId}`;
+}
+export function cacheApproval(requesterNodeId, storeId, capabilities) {
+    approvalCache.set(getCacheKey(requesterNodeId, storeId), {
+        requesterNodeId,
+        capabilities,
+        expiresAt: Date.now() + approvalTtlMs,
+    });
+}
+export function getCachedApproval(requesterNodeId, storeId) {
+    const key = getCacheKey(requesterNodeId, storeId);
+    const entry = approvalCache.get(key);
+    if (!entry)
+        return null;
+    if (Date.now() > entry.expiresAt) {
+        approvalCache.delete(key);
+        return null;
+    }
+    return entry.capabilities;
+}
+export function clearApprovalCache() {
+    approvalCache.clear();
+}
+// ============================================================================
+// PERMISSION CHECKS
+// ============================================================================
+/**
+ * Check if a role can access the requested capabilities.
+ * Returns the subset of capabilities that are allowed.
+ */
+export function getAllowedCapabilities(role, requested) {
+    const allowed = ROLE_CAPABILITIES[role];
+    return requested.filter(c => allowed.includes(c));
+}
+/**
+ * Check if a role requires interactive approval.
+ */
+export function requiresApproval(role) {
+    return role !== "admin";
+}
+// ============================================================================
+// APPROVAL PROMPT
+// ============================================================================
+/**
+ * Show an interactive approval prompt on the target node's terminal.
+ * Returns true if accepted, false if denied.
+ */
+export async function promptApproval(request) {
+    const caps = request.capabilities.join(", ");
+    const from = request.requester_hostname || request.requester_node_id;
+    return new Promise((resolve) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stderr, // use stderr so it doesn't interfere with stdout piping
+        });
+        process.stderr.write(`\n[portal] Connection request from "${from}" (${request.requester_role})\n` +
+            `  Capabilities: ${caps}\n` +
+            `  [A]ccept / [D]eny: `);
+        const timeout = setTimeout(() => {
+            process.stderr.write("\n[portal] Approval timed out, denying.\n");
+            rl.close();
+            resolve(false);
+        }, 30_000);
+        rl.once("line", (line) => {
+            clearTimeout(timeout);
+            rl.close();
+            const answer = line.trim().toLowerCase();
+            resolve(answer === "a" || answer === "accept" || answer === "y" || answer === "yes");
+        });
+    });
+}
+/**
+ * Decide whether to accept a portal request.
+ * For admins: auto-accept. For others: check cache, then prompt.
+ */
+export async function checkPermission(request, storeId, autoAcceptAdmins) {
+    const role = (request.requester_role || "member");
+    // Admin auto-accept
+    if (role === "admin" && autoAcceptAdmins) {
+        return { accepted: true };
+    }
+    // Check capability restrictions
+    const allowed = getAllowedCapabilities(role, request.capabilities);
+    if (allowed.length === 0) {
+        return { accepted: false, reason: `Role "${role}" has no access to requested capabilities` };
+    }
+    // Check approval cache
+    const cached = getCachedApproval(request.requester_node_id, storeId);
+    if (cached) {
+        const allCached = request.capabilities.every(c => cached.includes(c));
+        if (allCached) {
+            return { accepted: true };
+        }
+    }
+    // Interactive prompt (if terminal available)
+    if (process.stdin.isTTY) {
+        const accepted = await promptApproval(request);
+        if (accepted) {
+            cacheApproval(request.requester_node_id, storeId, allowed);
+        }
+        return { accepted, reason: accepted ? undefined : "Denied by user" };
+    }
+    // Headless mode — deny unless cached
+    return { accepted: false, reason: "No interactive terminal for approval (headless mode)" };
+}