@prohost/cli 0.13.2 → 0.14.0

package/dist/codehost/relay.d.ts

@@ -0,0 +1,170 @@
+/**
+ * This Mac's side of the code-host relay (`api_public/websockets/code_host_relay.py`).
+ *
+ * One **control** socket to `/v1/code-hosts/control`, authenticated with the
+ * paired agent's API key, open while Code-thread hosting is on. It says the
+ * machine is online, reports its stats and its `allowRemoteTerminal` switch,
+ * and receives:
+ *
+ * - `host_token` — the narrow `host_events` credential the hooks post with,
+ *   written to `hook.json` (see `events.ts`);
+ * - `dial` — a viewer wants a terminal. Each dial opens a **fresh stream
+ *   socket** to `/v1/code-hosts/stream` for that one viewer: terminal bytes are
+ *   never multiplexed on the control socket, so one slow viewer can't stall
+ *   another or the control channel.
+ *
+ * The relay refuses viewers unless this machine last said
+ * `allow_remote_terminal: true`; this side checks the switch again, on disk,
+ * at every dial, so turning it off takes effect for the next attach even
+ * before the relay has heard.
+ */
+import WebSocket from 'ws';
+import type { HostStats } from './host_stats.js';
+import type { CodeHostSettings } from './settings.js';
+import type { CodeTerminals, TerminalStream } from './terminals.js';
+import type { TerminalWindow } from './tmux.js';
+export declare const CONTROL_PATH = "/v1/code-hosts/control";
+export declare const STREAM_PATH = "/v1/code-hosts/stream";
+/** How often a status frame refreshes the relay's view of this machine. */
+export declare const STATUS_INTERVAL_MS = 30000;
+/**
+ * A flipped switch is sent at once and again this long after: the relay takes a
+ * flip inside its status window but at most once a second
+ * (`STATUS_SWITCH_MIN_INTERVAL_SECONDS`), so one that landed within a second of
+ * another status is dropped, and the repeat carries it.
+ */
+export declare const STATUS_SWITCH_RESEND_MS = 1200;
+/** No frame from the relay for this long means the control socket is dead. */
+export declare const CONTROL_SILENCE_MS = 75000;
+/** A relay that upgraded but never answered the auth frame is a dead socket. */
+export declare const CONTROL_AUTH_TIMEOUT_MS = 20000;
+/** Output buffered toward a slow relay before the stream is dropped (tmux redraws on reconnect). */
+export declare const MAX_STREAM_BUFFERED_BYTES: number;
+/** `ws(s)://host/prefix<route>` from the API base URL; `undefined` when unusable. */
+export declare function relayUrl(baseUrl: string, route: string): string | undefined;
+export interface DialFrame {
+    streamId: string;
+    streamToken: string;
+    terminalId: string;
+    window: TerminalWindow;
+    cols?: number;
+    rows?: number;
+    mode: 'type' | 'watch';
+}
+/** A `dial` frame, or `null` when it is not one this host can act on. */
+export declare function parseDial(frame: Record<string, unknown>): DialFrame | null;
+/** Pipe one terminal stream over one open socket until either side ends. */
+export declare function pipeStream(ws: WebSocket, stream: TerminalStream, onClosed: (reason: string) => void): void;
+/** Whose pairing this is, as the relay's `auth_ok` names it. */
+export interface PairingIdentity {
+    accountId: string;
+    ownerUserId: string;
+}
+/** The pairing identity in an `auth_ok`, or `undefined` from a relay that sends none. */
+export declare function parseIdentity(frame: Record<string, unknown>): PairingIdentity | undefined;
+/** The relay's answer to `verify_viewer`: who the token's bearer is, and what it may attach to. */
+export type ViewerVerdict = {
+    ok: true;
+    userId: string;
+    codeThreadId: string | null;
+    terminalId: string;
+    window: TerminalWindow | null;
+    mode: 'type' | 'watch';
+    /**
+     * The token was minted for this Mac's own desktop app (`loc`): the desktop socket admits it
+     * with the remote switch off. Only a literal `true` counts; an older server sends none.
+     */
+    local: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** How long the relay gets to answer a `verify_viewer`. */
+export declare const VERIFY_VIEWER_TIMEOUT_MS = 5000;
+/** A `viewer_verified` frame, or `null` when it is malformed (treated as a refusal). */
+export declare function parseViewerVerdict(frame: Record<string, unknown>): ViewerVerdict | null;
+export interface CodeHostRelayOptions {
+    baseUrl: string;
+    apiKey: string;
+    machineId: string;
+    /**
+     * This home's CLI instance (see `codeHostInstanceId`): its presence and control
+     * channel on the relay are its own, so a thread's terminal is dialed only
+     * through the instance the thread is bound to.
+     */
+    instanceId?: string;
+    machine: string;
+    clientVersion: string;
+    settings: () => CodeHostSettings;
+    stats: () => Promise<HostStats | undefined>;
+    terminals: Pick<CodeTerminals, 'attach'>;
+    onHostToken: (token: string, expiresAt: number) => void;
+    /**
+     * The relay authorized this machine (`auth_ok`), or refused it (`auth_error`:
+     * a revoked key, a pairing no longer active). The host closes every other
+     * way into its terminals — the desktop socket — on a refusal.
+     */
+    onAuthorization?: (authorized: boolean, reason?: string, identity?: PairingIdentity) => void;
+    /**
+     * The current control socket closed. Authorization is unknown until the
+     * next `auth_ok`: the host fails closed on its other ways in (the desktop
+     * socket) for the gap, since a revocation during an outage can't be heard.
+     */
+    onDisconnected?: () => void;
+    log?: (line: string) => void;
+    WebSocketCtor?: typeof WebSocket;
+    setTimer?: (fn: () => void, ms: number) => () => void;
+    random?: () => number;
+}
+export declare class CodeHostRelay {
+    private readonly options;
+    private ws;
+    private stopped;
+    private attempt;
+    private readonly timers;
+    private readonly streams;
+    private lastFrameAt;
+    private authed;
+    /** `verify_viewer` requests awaiting the relay's answer, by request id. */
+    private readonly verifying;
+    /** Bumped by {@link dropStreams}: a dial begun before a drop never opens. */
+    private generation;
+    private refused;
+    private readonly log;
+    private readonly Ctor;
+    private readonly setTimer;
+    constructor(options: CodeHostRelayOptions);
+    /** Whether the control socket is authenticated right now. Exposed for assertions. */
+    connected(): boolean;
+    /** Open streams. Exposed for assertions. */
+    openStreams(): number;
+    start(): void;
+    /**
+     * End every attached viewer now. A terminal is attached only while this
+     * machine is authorized: losing the control socket, the relay refusing the
+     * pairing (revoked key, `pairing_revoked`), or the owner turning the remote
+     * terminal off all drop what is open — viewers reconnect through a fresh,
+     * fully checked attach.
+     */
+    /**
+     * Ask the relay who a viewer token's bearer is (the desktop fast path's only
+     * source of identity: the app page's own word is never taken). Resolves a
+     * refusal when the relay is unreachable, slow, or says no. Never rejects.
+     */
+    verifyViewer(token: string): Promise<ViewerVerdict>;
+    private refuseVerifications;
+    dropStreams(reason: string): void;
+    /** The owner's switch changed: tell the relay now, and once more a moment later, not at the next 30 s status. */
+    statusChanged(): void;
+    stop(): void;
+    private later;
+    private reconnect;
+    private send;
+    private sendStatus;
+    private statusLoop;
+    private connect;
+    private onFrame;
+    private acceptToken;
+    private dialError;
+    private onDial;
+}