whale-code 6.4.0 → 6.5.1

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

@@ -0,0 +1,140 @@
+/**
+ * Portal Wire Protocol — frame encoding/decoding for multiplexed portal connections.
+ *
+ * Relay Envelope (over WebSocket binary):
+ *   Byte 0:      0x01 (portal frame marker)
+ *   Bytes 1-16:  Session UUID (16 bytes, binary)
+ *   Bytes 17+:   Multiplexed frame (forwarded as-is)
+ *
+ * Multiplexed Frame (inner protocol, between nodes):
+ *   ┌──────────┬──────────┬──────────┬──────────┬───────────────┐
+ *   │ Version  │  Type    │  Flags   │ StreamID │  Length        │
+ *   │  1 byte  │  1 byte  │  2 bytes │  4 bytes │  4 bytes      │
+ *   └──────────┴──────────┴──────────┴──────────┴───────────────┘
+ *   Total header: 12 bytes + variable payload (max 1MB per frame)
+ */
+export declare const PORTAL_MARKER = 1;
+export declare const PROTOCOL_VERSION = 1;
+export declare const HEADER_SIZE = 12;
+export declare const MAX_PAYLOAD_SIZE: number;
+export declare const SESSION_UUID_SIZE = 16;
+export declare const RELAY_HEADER_SIZE: number;
+export declare enum FrameType {
+    DATA = 0,
+    SYN = 1,
+    ACK = 2,
+    FIN = 3,
+    RST = 4,
+    PING = 5,
+    PONG = 6
+}
+export declare enum FrameFlag {
+    SYN = 1,
+    ACK = 2,
+    FIN = 4
+}
+export type ChannelType = "shell" | "file" | "forward" | "clipboard" | "screen";
+export interface SynShell {
+    channel: "shell";
+    term: string;
+    cols: number;
+    rows: number;
+    cwd?: string;
+    command?: string;
+}
+export interface SynFilePush {
+    channel: "file";
+    direction: "push";
+    name: string;
+    size: number;
+    mode: number;
+    mtime: number;
+    isDirectory?: boolean;
+}
+export interface SynFilePull {
+    channel: "file";
+    direction: "pull";
+    path: string;
+}
+export interface SynForward {
+    channel: "forward";
+    remotePort: number;
+    description?: string;
+}
+export interface SynScreen {
+    channel: "screen";
+    control: boolean;
+}
+export interface SynClipboard {
+    channel: "clipboard";
+    mode: "push" | "pull" | "sync";
+}
+export type SynPayload = SynShell | SynFilePush | SynFilePull | SynForward | SynScreen | SynClipboard;
+export interface Frame {
+    version: number;
+    type: FrameType;
+    flags: number;
+    streamId: number;
+    payload: Buffer;
+}
+export interface PortalRequest {
+    type: "portal_request";
+    session_id: string;
+    target_node_id: string;
+    capabilities: ChannelType[];
+    requester_node_id: string;
+    requester_hostname: string;
+    requester_role: string;
+}
+export interface PortalAccept {
+    type: "portal_accept";
+    session_id: string;
+    hostname: string;
+}
+export interface PortalReject {
+    type: "portal_reject";
+    session_id: string;
+    reason: string;
+}
+export interface PortalClose {
+    type: "portal_close";
+    session_id: string;
+}
+export interface ResizeMessage {
+    type: "resize";
+    cols: number;
+    rows: number;
+}
+export type ControlMessage = PortalRequest | PortalAccept | PortalReject | PortalClose | ResizeMessage;
+export declare function encodeFrame(frame: Frame): Buffer;
+export declare function encodeRelayEnvelope(sessionUuid: Buffer, innerFrame: Buffer): Buffer;
+export interface DecodeResult {
+    frame: Frame;
+    bytesConsumed: number;
+}
+/**
+ * Try to decode a frame from the buffer. Returns null if not enough data.
+ */
+export declare function decodeFrame(buf: Buffer, offset?: number): DecodeResult | null;
+/**
+ * Parse a relay envelope. Returns session UUID and inner frame buffer.
+ */
+export declare function decodeRelayEnvelope(buf: Buffer): {
+    sessionUuid: Buffer;
+    innerFrame: Buffer;
+} | null;
+/**
+ * Convert a UUID string (with dashes) to a 16-byte buffer.
+ */
+export declare function uuidToBuffer(uuid: string): Buffer;
+/**
+ * Convert a 16-byte buffer to a UUID string (with dashes).
+ */
+export declare function bufferToUuid(buf: Buffer): string;
+export declare function makeDataFrame(streamId: number, data: Buffer): Buffer;
+export declare function makeSynFrame(streamId: number, payload: SynPayload): Buffer;
+export declare function makeAckFrame(streamId: number): Buffer;
+export declare function makeFinFrame(streamId: number): Buffer;
+export declare function makeRstFrame(streamId: number, reason?: string): Buffer;
+export declare function makePingFrame(): Buffer;
+export declare function makePongFrame(): Buffer;

package/dist/node/portal/protocol.js

@@ -0,0 +1,193 @@
+/**
+ * Portal Wire Protocol — frame encoding/decoding for multiplexed portal connections.
+ *
+ * Relay Envelope (over WebSocket binary):
+ *   Byte 0:      0x01 (portal frame marker)
+ *   Bytes 1-16:  Session UUID (16 bytes, binary)
+ *   Bytes 17+:   Multiplexed frame (forwarded as-is)
+ *
+ * Multiplexed Frame (inner protocol, between nodes):
+ *   ┌──────────┬──────────┬──────────┬──────────┬───────────────┐
+ *   │ Version  │  Type    │  Flags   │ StreamID │  Length        │
+ *   │  1 byte  │  1 byte  │  2 bytes │  4 bytes │  4 bytes      │
+ *   └──────────┴──────────┴──────────┴──────────┴───────────────┘
+ *   Total header: 12 bytes + variable payload (max 1MB per frame)
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+export const PORTAL_MARKER = 0x01;
+export const PROTOCOL_VERSION = 0x01;
+export const HEADER_SIZE = 12;
+export const MAX_PAYLOAD_SIZE = 1024 * 1024; // 1MB
+export const SESSION_UUID_SIZE = 16;
+export const RELAY_HEADER_SIZE = 1 + SESSION_UUID_SIZE; // marker + uuid
+// ============================================================================
+// FRAME TYPES
+// ============================================================================
+export var FrameType;
+(function (FrameType) {
+    FrameType[FrameType["DATA"] = 0] = "DATA";
+    FrameType[FrameType["SYN"] = 1] = "SYN";
+    FrameType[FrameType["ACK"] = 2] = "ACK";
+    FrameType[FrameType["FIN"] = 3] = "FIN";
+    FrameType[FrameType["RST"] = 4] = "RST";
+    FrameType[FrameType["PING"] = 5] = "PING";
+    FrameType[FrameType["PONG"] = 6] = "PONG";
+})(FrameType || (FrameType = {}));
+// ============================================================================
+// FLAGS
+// ============================================================================
+export var FrameFlag;
+(function (FrameFlag) {
+    FrameFlag[FrameFlag["SYN"] = 1] = "SYN";
+    FrameFlag[FrameFlag["ACK"] = 2] = "ACK";
+    FrameFlag[FrameFlag["FIN"] = 4] = "FIN";
+})(FrameFlag || (FrameFlag = {}));
+// ============================================================================
+// ENCODING
+// ============================================================================
+export function encodeFrame(frame) {
+    const payloadLen = frame.payload.length;
+    if (payloadLen > MAX_PAYLOAD_SIZE) {
+        throw new Error(`Payload too large: ${payloadLen} > ${MAX_PAYLOAD_SIZE}`);
+    }
+    const buf = Buffer.allocUnsafe(HEADER_SIZE + payloadLen);
+    buf[0] = frame.version;
+    buf[1] = frame.type;
+    buf.writeUInt16BE(frame.flags, 2);
+    buf.writeUInt32BE(frame.streamId, 4);
+    buf.writeUInt32BE(payloadLen, 8);
+    if (payloadLen > 0) {
+        frame.payload.copy(buf, HEADER_SIZE);
+    }
+    return buf;
+}
+export function encodeRelayEnvelope(sessionUuid, innerFrame) {
+    const buf = Buffer.allocUnsafe(RELAY_HEADER_SIZE + innerFrame.length);
+    buf[0] = PORTAL_MARKER;
+    sessionUuid.copy(buf, 1);
+    innerFrame.copy(buf, RELAY_HEADER_SIZE);
+    return buf;
+}
+/**
+ * Try to decode a frame from the buffer. Returns null if not enough data.
+ */
+export function decodeFrame(buf, offset = 0) {
+    const remaining = buf.length - offset;
+    if (remaining < HEADER_SIZE)
+        return null;
+    const version = buf[offset];
+    const type = buf[offset + 1];
+    const flags = buf.readUInt16BE(offset + 2);
+    const streamId = buf.readUInt32BE(offset + 4);
+    const payloadLen = buf.readUInt32BE(offset + 8);
+    if (payloadLen > MAX_PAYLOAD_SIZE) {
+        throw new Error(`Invalid payload length: ${payloadLen}`);
+    }
+    const totalLen = HEADER_SIZE + payloadLen;
+    if (remaining < totalLen)
+        return null;
+    const payload = Buffer.allocUnsafe(payloadLen);
+    buf.copy(payload, 0, offset + HEADER_SIZE, offset + totalLen);
+    return {
+        frame: { version, type, flags, streamId, payload },
+        bytesConsumed: totalLen,
+    };
+}
+/**
+ * Parse a relay envelope. Returns session UUID and inner frame buffer.
+ */
+export function decodeRelayEnvelope(buf) {
+    if (buf.length < RELAY_HEADER_SIZE)
+        return null;
+    if (buf[0] !== PORTAL_MARKER)
+        return null;
+    const sessionUuid = Buffer.allocUnsafe(SESSION_UUID_SIZE);
+    buf.copy(sessionUuid, 0, 1, 1 + SESSION_UUID_SIZE);
+    const innerFrame = Buffer.allocUnsafe(buf.length - RELAY_HEADER_SIZE);
+    buf.copy(innerFrame, 0, RELAY_HEADER_SIZE);
+    return { sessionUuid, innerFrame };
+}
+// ============================================================================
+// UUID HELPERS
+// ============================================================================
+/**
+ * Convert a UUID string (with dashes) to a 16-byte buffer.
+ */
+export function uuidToBuffer(uuid) {
+    return Buffer.from(uuid.replace(/-/g, ""), "hex");
+}
+/**
+ * Convert a 16-byte buffer to a UUID string (with dashes).
+ */
+export function bufferToUuid(buf) {
+    const hex = buf.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+// ============================================================================
+// HELPERS
+// ============================================================================
+export function makeDataFrame(streamId, data) {
+    return encodeFrame({
+        version: PROTOCOL_VERSION,
+        type: FrameType.DATA,
+        flags: 0,
+        streamId,
+        payload: data,
+    });
+}
+export function makeSynFrame(streamId, payload) {
+    return encodeFrame({
+        version: PROTOCOL_VERSION,
+        type: FrameType.SYN,
+        flags: FrameFlag.SYN,
+        streamId,
+        payload: Buffer.from(JSON.stringify(payload)),
+    });
+}
+export function makeAckFrame(streamId) {
+    return encodeFrame({
+        version: PROTOCOL_VERSION,
+        type: FrameType.ACK,
+        flags: FrameFlag.ACK,
+        streamId,
+        payload: Buffer.alloc(0),
+    });
+}
+export function makeFinFrame(streamId) {
+    return encodeFrame({
+        version: PROTOCOL_VERSION,
+        type: FrameType.FIN,
+        flags: FrameFlag.FIN,
+        streamId,
+        payload: Buffer.alloc(0),
+    });
+}
+export function makeRstFrame(streamId, reason = "") {
+    return encodeFrame({
+        version: PROTOCOL_VERSION,
+        type: FrameType.RST,
+        flags: 0,
+        streamId,
+        payload: reason ? Buffer.from(reason) : Buffer.alloc(0),
+    });
+}
+export function makePingFrame() {
+    return encodeFrame({
+        version: PROTOCOL_VERSION,
+        type: FrameType.PING,
+        flags: 0,
+        streamId: 0,
+        payload: Buffer.alloc(0),
+    });
+}
+export function makePongFrame() {
+    return encodeFrame({
+        version: PROTOCOL_VERSION,
+        type: FrameType.PONG,
+        flags: 0,
+        streamId: 0,
+        payload: Buffer.alloc(0),
+    });
+}

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

@@ -0,0 +1,18 @@
+/**
+ * ScreenChannel — bridges portal stream to ScreenCaptureService.
+ *
+ * Target side: subscribes to ScreenCaptureService events, forwards H.264 frames
+ * over the portal stream. Sends SPS/PPS config + latest frame immediately so the
+ * remote viewer gets an instant first frame.
+ *
+ * Initiator side: opens a portal stream and pipes it to the UI.
+ */
+import type { PortalStream } from "./stream.js";
+import type { SynScreen } from "./protocol.js";
+import type { PortalSession } from "./session.js";
+import type { ScreenCaptureService } from "../remote-desktop/index.js";
+export declare function openScreen(session: PortalSession, control: boolean): Promise<{
+    stream: PortalStream;
+    cleanup: () => void;
+}>;
+export declare function handleScreen(stream: PortalStream, meta: SynScreen, captureService: ScreenCaptureService | null): void;

package/dist/node/portal/screen.js

@@ -0,0 +1,93 @@
+/**
+ * ScreenChannel — bridges portal stream to ScreenCaptureService.
+ *
+ * Target side: subscribes to ScreenCaptureService events, forwards H.264 frames
+ * over the portal stream. Sends SPS/PPS config + latest frame immediately so the
+ * remote viewer gets an instant first frame.
+ *
+ * Initiator side: opens a portal stream and pipes it to the UI.
+ */
+// ============================================================================
+// INITIATOR SIDE — receive screen frames
+// ============================================================================
+export async function openScreen(session, control) {
+    const stream = session.openStream({
+        channel: "screen",
+        control,
+    });
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error("Screen open timed out")), 10_000);
+        session.once("stream:ack", (s) => {
+            if (s.streamId === stream.streamId) {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+    });
+    const cleanup = () => {
+        if (!stream.destroyed)
+            stream.end();
+    };
+    return { stream, cleanup };
+}
+// ============================================================================
+// TARGET SIDE — bridge ScreenCaptureService to portal stream
+// ============================================================================
+export function handleScreen(stream, meta, captureService) {
+    if (!captureService) {
+        stream.destroy(new Error("Screen capture not available on this node"));
+        return;
+    }
+    // Send SPS/PPS config immediately so remote decoder can initialize
+    const config = captureService.latestConfig;
+    if (config) {
+        stream.write(config);
+    }
+    // Send latest frame for instant first image
+    const latest = captureService.latestFrame;
+    if (latest) {
+        stream.write(latest);
+    }
+    // Forward all subsequent frames
+    const onFrame = (data) => {
+        if (!stream.destroyed) {
+            stream.write(data);
+        }
+    };
+    const onConfig = (data) => {
+        if (!stream.destroyed) {
+            stream.write(data);
+        }
+    };
+    captureService.on("frame", onFrame);
+    captureService.on("config", onConfig);
+    // Forward control input from remote viewer → capture service
+    if (meta.control) {
+        stream.on("data", (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                if (!msg.type)
+                    return;
+                // Input events (mouse, keyboard, scroll)
+                if (msg.type.startsWith("mouse_") || msg.type.startsWith("key_") || msg.type === "scroll") {
+                    captureService.injectInput(msg);
+                }
+                // Control messages (keyframe request, quality adjustment)
+                else if (msg.type === "request_keyframe" || msg.type === "quality" || msg.type === "set_fps") {
+                    captureService.sendControlMessage(msg);
+                }
+            }
+            catch {
+                // Binary frame data flowing the wrong direction, ignore
+            }
+        });
+    }
+    // Cleanup listeners when stream closes
+    const cleanup = () => {
+        captureService.removeListener("frame", onFrame);
+        captureService.removeListener("config", onConfig);
+    };
+    stream.on("end", cleanup);
+    stream.on("error", cleanup);
+    stream.on("close", cleanup);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * PortalSession — manages one peer-to-peer portal connection.
+ *
+ * Wraps a Multiplexer over the WebSocket transport. Handles session negotiation,
+ * binary framing through the relay, and channel lifecycle.
+ */
+import { EventEmitter } from "node:events";
+import { type SynPayload } from "./protocol.js";
+import { PortalStream } from "./stream.js";
+export interface PortalSessionConfig {
+    sessionId: string;
+    isInitiator: boolean;
+    sendBinary: (data: Buffer) => void;
+    sendJson: (msg: Record<string, unknown>) => void;
+    targetNodeId?: string;
+    targetHostname?: string;
+}
+export declare class PortalSession extends EventEmitter {
+    readonly sessionId: string;
+    readonly isInitiator: boolean;
+    readonly targetNodeId: string | undefined;
+    readonly targetHostname: string | undefined;
+    private sessionUuidBuf;
+    private multiplexer;
+    private sendBinary;
+    private sendJson;
+    private _accepted;
+    private _closed;
+    readonly createdAt: Date;
+    constructor(config: PortalSessionConfig);
+    get accepted(): boolean;
+    get closed(): boolean;
+    get activeStreams(): number;
+    /**
+     * Mark session as accepted (called after portal_accept received/sent).
+     */
+    accept(): void;
+    /**
+     * Open a new channel stream (initiator side).
+     */
+    openStream(meta: SynPayload): PortalStream;
+    /**
+     * Feed incoming binary data from the WebSocket.
+     * Strips the relay envelope and feeds to multiplexer.
+     */
+    receiveRelay(data: Buffer): void;
+    /**
+     * Feed raw inner frame data directly (no envelope, for testing).
+     */
+    receiveRaw(data: Buffer): void;
+    /**
+     * Close the session.
+     */
+    close(reason?: string): void;
+    /**
+     * Get session info.
+     */
+    getInfo(): {
+        session_id: string;
+        target_node_id?: string;
+        target_hostname?: string;
+        is_initiator: boolean;
+        accepted: boolean;
+        active_streams: number;
+        created_at: string;
+    };
+    private sendRelayFrame;
+}

package/dist/node/portal/session.js

@@ -0,0 +1,127 @@
+/**
+ * PortalSession — manages one peer-to-peer portal connection.
+ *
+ * Wraps a Multiplexer over the WebSocket transport. Handles session negotiation,
+ * binary framing through the relay, and channel lifecycle.
+ */
+import { EventEmitter } from "node:events";
+import { encodeRelayEnvelope, decodeRelayEnvelope, uuidToBuffer, bufferToUuid, } from "./protocol.js";
+import { Multiplexer } from "./multiplexer.js";
+export class PortalSession extends EventEmitter {
+    sessionId;
+    isInitiator;
+    targetNodeId;
+    targetHostname;
+    sessionUuidBuf;
+    multiplexer;
+    sendBinary;
+    sendJson;
+    _accepted = false;
+    _closed = false;
+    createdAt = new Date();
+    constructor(config) {
+        super();
+        this.sessionId = config.sessionId;
+        this.isInitiator = config.isInitiator;
+        this.targetNodeId = config.targetNodeId;
+        this.targetHostname = config.targetHostname;
+        this.sendBinary = config.sendBinary;
+        this.sendJson = config.sendJson;
+        this.sessionUuidBuf = uuidToBuffer(config.sessionId);
+        this.multiplexer = new Multiplexer({
+            isInitiator: config.isInitiator,
+            sendRaw: (data) => this.sendRelayFrame(data),
+        });
+        // Forward multiplexer events
+        this.multiplexer.on("stream", (stream, meta) => {
+            this.emit("stream", stream, meta);
+        });
+        this.multiplexer.on("stream:ack", (stream) => {
+            this.emit("stream:ack", stream);
+        });
+        this.multiplexer.on("timeout", () => {
+            this.close("keepalive timeout");
+        });
+        this.multiplexer.on("close", () => {
+            this._closed = true;
+            this.emit("close");
+        });
+        this.multiplexer.on("error", (err) => {
+            this.emit("error", err);
+        });
+    }
+    get accepted() { return this._accepted; }
+    get closed() { return this._closed; }
+    get activeStreams() { return this.multiplexer.activeStreams; }
+    /**
+     * Mark session as accepted (called after portal_accept received/sent).
+     */
+    accept() {
+        this._accepted = true;
+        this.emit("accepted");
+    }
+    /**
+     * Open a new channel stream (initiator side).
+     */
+    openStream(meta) {
+        return this.multiplexer.openStream(meta);
+    }
+    /**
+     * Feed incoming binary data from the WebSocket.
+     * Strips the relay envelope and feeds to multiplexer.
+     */
+    receiveRelay(data) {
+        if (this._closed)
+            return;
+        const decoded = decodeRelayEnvelope(data);
+        if (!decoded)
+            return;
+        // Verify session UUID matches
+        const uuid = bufferToUuid(decoded.sessionUuid);
+        if (uuid !== this.sessionId)
+            return;
+        this.multiplexer.receive(decoded.innerFrame);
+    }
+    /**
+     * Feed raw inner frame data directly (no envelope, for testing).
+     */
+    receiveRaw(data) {
+        if (this._closed)
+            return;
+        this.multiplexer.receive(data);
+    }
+    /**
+     * Close the session.
+     */
+    close(reason = "session closed") {
+        if (this._closed)
+            return;
+        this._closed = true;
+        this.sendJson({ type: "portal_close", session_id: this.sessionId });
+        this.multiplexer.close();
+        this.emit("close", reason);
+    }
+    /**
+     * Get session info.
+     */
+    getInfo() {
+        return {
+            session_id: this.sessionId,
+            target_node_id: this.targetNodeId,
+            target_hostname: this.targetHostname,
+            is_initiator: this.isInitiator,
+            accepted: this._accepted,
+            active_streams: this.activeStreams,
+            created_at: this.createdAt.toISOString(),
+        };
+    }
+    // ============================================================================
+    // INTERNAL
+    // ============================================================================
+    sendRelayFrame(innerFrame) {
+        if (this._closed)
+            return;
+        const envelope = encodeRelayEnvelope(this.sessionUuidBuf, innerFrame);
+        this.sendBinary(envelope);
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * ShellChannel — PTY spawn on target, stdin/stdout bridge on initiator.
+ *
+ * Initiator side: pipes process.stdin → stream, stream → process.stdout
+ * Target side: spawns node-pty, pipes PTY ↔ stream
+ */
+import type { PortalStream } from "./stream.js";
+import type { SynShell } from "./protocol.js";
+import type { PortalSession } from "./session.js";
+/**
+ * Open a remote shell from the initiator. Pipes local terminal to remote PTY.
+ */
+export declare function openShell(session: PortalSession, opts?: {
+    cols?: number;
+    rows?: number;
+    cwd?: string;
+    command?: string;
+}): Promise<{
+    stream: PortalStream;
+    cleanup: () => void;
+}>;
+/**
+ * Handle an incoming shell stream on the target node.
+ * Spawns a PTY and bridges it to the stream.
+ */
+export declare function handleShell(stream: PortalStream, meta: SynShell): Promise<void>;