@prohost/cli 0.13.2 → 0.14.0

package/dist/codehost/relay.js

@@ -0,0 +1,548 @@
+/**
+ * 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 { randomBytes } from 'node:crypto';
+import WebSocket from 'ws';
+import { endpointProblem } from '../agent/base-url.js';
+import { USER_AGENT } from '../version.js';
+import { isValidId, parseControl, TERMINAL_WINDOWS } from './tmux.js';
+export const CONTROL_PATH = '/v1/code-hosts/control';
+export const STREAM_PATH = '/v1/code-hosts/stream';
+/** How often a status frame refreshes the relay's view of this machine. */
+export const STATUS_INTERVAL_MS = 30_000;
+/**
+ * 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 const STATUS_SWITCH_RESEND_MS = 1_200;
+/** No frame from the relay for this long means the control socket is dead. */
+export const CONTROL_SILENCE_MS = 75_000;
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+const STREAM_READY_TIMEOUT_MS = 10_000;
+/** A relay that upgraded but never answered the auth frame is a dead socket. */
+export const CONTROL_AUTH_TIMEOUT_MS = 20_000;
+/** Output buffered toward a slow relay before the stream is dropped (tmux redraws on reconnect). */
+export const MAX_STREAM_BUFFERED_BYTES = 4 * 1024 * 1024;
+/** `ws(s)://host/prefix<route>` from the API base URL; `undefined` when unusable. */
+export function relayUrl(baseUrl, route) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return undefined;
+    const url = `${parsed.protocol === 'http:' ? 'ws' : 'wss'}://${parsed.host}${parsed.pathname.replace(/\/+$/, '')}${route}`;
+    return endpointProblem(url, 'ws') ? undefined : url;
+}
+/** A `dial` frame, or `null` when it is not one this host can act on. */
+export function parseDial(frame) {
+    const { stream_id: streamId, stream_token: streamToken, terminal_id: terminalId } = frame;
+    if (typeof streamId !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(streamId))
+        return null;
+    if (typeof streamToken !== 'string' || !streamToken)
+        return null;
+    if (!isValidId(terminalId))
+        return null;
+    const window = typeof frame.window === 'string' && TERMINAL_WINDOWS.has(frame.window) ? frame.window : 'agent';
+    return {
+        streamId,
+        streamToken,
+        terminalId,
+        window: window,
+        cols: typeof frame.cols === 'number' ? frame.cols : undefined,
+        rows: typeof frame.rows === 'number' ? frame.rows : undefined,
+        mode: frame.mode === 'watch' ? 'watch' : 'type',
+    };
+}
+/** Pipe one terminal stream over one open socket until either side ends. */
+export function pipeStream(ws, stream, onClosed) {
+    let done = false;
+    const finish = (reason) => {
+        if (done)
+            return;
+        done = true;
+        stream.close();
+        try {
+            ws.close(reason === 'slow_consumer' ? 1013 : 1000, reason);
+        }
+        catch {
+            /* already closing */
+        }
+        onClosed(reason);
+    };
+    stream.onData((chunk) => {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        if (ws.bufferedAmount > MAX_STREAM_BUFFERED_BYTES) {
+            finish('slow_consumer');
+            return;
+        }
+        ws.send(chunk, { binary: true });
+    });
+    stream.onExit(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+            try {
+                ws.send(JSON.stringify({ type: 'exit' }));
+            }
+            catch {
+                /* closing anyway */
+            }
+        }
+        finish('exit');
+    });
+    ws.on('message', (data, isBinary) => {
+        if (done)
+            return;
+        const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+        if (isBinary) {
+            stream.write(buffer);
+            return;
+        }
+        const control = parseControl(buffer.toString('utf8'));
+        if (!control)
+            return;
+        if (control.type === 'resize')
+            stream.resize(control.cols, control.rows);
+        else if (control.type === 'input')
+            stream.write(Buffer.from(control.data, 'utf8'));
+        else if (control.type === 'hello')
+            stream.hello?.(control.client);
+        else if (control.type === 'claim')
+            stream.claim?.();
+        else if (control.type === 'ping')
+            ws.send(JSON.stringify({ type: 'pong' }));
+    });
+    // Who sizes the window, for a viewer that said hello (`sizing.ts` sends nothing to one that didn't).
+    stream.onSizer?.((frame) => {
+        if (done || ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify(frame));
+        }
+        catch {
+            /* closing anyway */
+        }
+    });
+    ws.on('close', () => finish('closed'));
+    ws.on('error', () => finish('error'));
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The pairing identity in an `auth_ok`, or `undefined` from a relay that sends none. */
+export function parseIdentity(frame) {
+    const { account_id: accountId, owner_user_id: ownerUserId } = frame;
+    if (typeof accountId !== 'string' || !UUID.test(accountId))
+        return undefined;
+    if (typeof ownerUserId !== 'string' || !UUID.test(ownerUserId))
+        return undefined;
+    return { accountId: accountId.toLowerCase(), ownerUserId: ownerUserId.toLowerCase() };
+}
+/** How long the relay gets to answer a `verify_viewer`. */
+export const VERIFY_VIEWER_TIMEOUT_MS = 5_000;
+/** A `viewer_verified` frame, or `null` when it is malformed (treated as a refusal). */
+export function parseViewerVerdict(frame) {
+    if (frame.ok !== true)
+        return { ok: false, reason: typeof frame.reason === 'string' ? frame.reason : 'not_allowed' };
+    const { user_id: userId, terminal_id: terminalId } = frame;
+    if (typeof userId !== 'string' || !isValidId(terminalId))
+        return null;
+    // Only an explicit null leaves the window open; anything else unknown refuses (fail closed).
+    let window;
+    if (frame.window === null)
+        window = null;
+    else if (typeof frame.window === 'string' && TERMINAL_WINDOWS.has(frame.window))
+        window = frame.window;
+    else
+        return null;
+    return {
+        ok: true,
+        userId,
+        codeThreadId: typeof frame.code_thread_id === 'string' ? frame.code_thread_id : null,
+        terminalId,
+        window,
+        // Anything but an explicit `type` watches: a verdict never widens what the token said.
+        mode: frame.mode === 'type' ? 'type' : 'watch',
+        local: frame.local === true,
+    };
+}
+function defaultTimer(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+export class CodeHostRelay {
+    options;
+    ws;
+    stopped = true;
+    attempt = 0;
+    timers = new Set();
+    streams = new Set();
+    lastFrameAt = 0;
+    authed = false;
+    /** `verify_viewer` requests awaiting the relay's answer, by request id. */
+    verifying = new Map();
+    /** Bumped by {@link dropStreams}: a dial begun before a drop never opens. */
+    generation = 0;
+    refused;
+    log;
+    Ctor;
+    setTimer;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? (() => { });
+        this.Ctor = options.WebSocketCtor ?? WebSocket;
+        this.setTimer = options.setTimer ?? defaultTimer;
+    }
+    /** Whether the control socket is authenticated right now. Exposed for assertions. */
+    connected() {
+        return this.authed && this.ws?.readyState === WebSocket.OPEN;
+    }
+    /** Open streams. Exposed for assertions. */
+    openStreams() {
+        return this.streams.size;
+    }
+    start() {
+        if (!this.stopped)
+            return;
+        this.stopped = false;
+        this.connect();
+    }
+    /**
+     * 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) {
+        if (!this.authed || this.stopped || !token)
+            return Promise.resolve({ ok: false, reason: 'relay_unavailable' });
+        const requestId = randomBytes(12).toString('hex');
+        return new Promise((resolve) => {
+            const cancel = this.setTimer(() => {
+                this.verifying.delete(requestId);
+                resolve({ ok: false, reason: 'relay_unavailable' });
+            }, VERIFY_VIEWER_TIMEOUT_MS);
+            this.verifying.set(requestId, (verdict) => {
+                cancel();
+                resolve(verdict);
+            });
+            this.send({ type: 'verify_viewer', request_id: requestId, token });
+        });
+    }
+    refuseVerifications() {
+        for (const resolve of this.verifying.values())
+            resolve({ ok: false, reason: 'relay_unavailable' });
+        this.verifying.clear();
+    }
+    dropStreams(reason) {
+        this.generation += 1;
+        if (this.streams.size > 0)
+            this.log(`    ⏹ closing ${this.streams.size} remote terminal(s): ${reason}`);
+        for (const stream of this.streams)
+            stream.terminate();
+        this.streams.clear();
+    }
+    /** The owner's switch changed: tell the relay now, and once more a moment later, not at the next 30 s status. */
+    statusChanged() {
+        if (!this.authed || this.stopped)
+            return;
+        void this.sendStatus();
+        this.later(() => {
+            if (this.authed && !this.stopped)
+                void this.sendStatus();
+        }, STATUS_SWITCH_RESEND_MS);
+    }
+    stop() {
+        this.stopped = true;
+        this.refuseVerifications();
+        for (const cancel of this.timers)
+            cancel();
+        this.timers.clear();
+        for (const stream of this.streams)
+            stream.terminate();
+        this.streams.clear();
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* already closed */
+        }
+        this.ws = undefined;
+    }
+    later(fn, ms) {
+        const cancel = this.setTimer(() => {
+            this.timers.delete(cancel);
+            fn();
+        }, ms);
+        this.timers.add(cancel);
+    }
+    reconnect() {
+        if (this.stopped)
+            return;
+        this.ws = undefined;
+        this.attempt += 1;
+        const ceiling = Math.min(RECONNECT_MAX_MS, RECONNECT_MIN_MS * 2 ** Math.min(this.attempt, 6));
+        this.later(() => this.connect(), Math.round(ceiling * (0.5 + (this.options.random ?? Math.random)() / 2)));
+    }
+    send(frame) {
+        try {
+            if (this.ws?.readyState === WebSocket.OPEN)
+                this.ws.send(JSON.stringify(frame));
+        }
+        catch {
+            /* the close handler reconnects */
+        }
+    }
+    async sendStatus() {
+        const host = (await this.options.stats().catch(() => undefined)) ?? null;
+        // Read after the (up to seconds-long) stats sample, at the moment of sending: of two
+        // overlapping sends, the one that lands last carries the switch as it is then, never an
+        // older value it read before waiting.
+        this.send({ type: 'status', allow_remote_terminal: this.options.settings().allowRemoteTerminal, host });
+    }
+    statusLoop(ws) {
+        this.later(() => {
+            if (this.ws !== ws || this.stopped)
+                return;
+            if (Date.now() - this.lastFrameAt > CONTROL_SILENCE_MS) {
+                this.log('    … code-host relay went quiet — reconnecting');
+                ws.terminate();
+                return;
+            }
+            void this.sendStatus();
+            this.statusLoop(ws);
+        }, STATUS_INTERVAL_MS);
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        const url = relayUrl(this.options.baseUrl, CONTROL_PATH);
+        if (!url) {
+            this.log('    ! code-host relay disabled: the API base URL is not https (or loopback http)');
+            return;
+        }
+        const ws = new this.Ctor(url, { headers: { 'User-Agent': USER_AGENT }, handshakeTimeout: 15_000 });
+        this.ws = ws;
+        ws.on('open', () => {
+            this.lastFrameAt = Date.now();
+            // Until auth_ok the status loop (the silence watchdog) isn't running.
+            this.later(() => {
+                if (this.ws === ws && !this.authed && !this.stopped) {
+                    this.log('    … code-host relay never answered auth — reconnecting');
+                    ws.terminate();
+                }
+            }, CONTROL_AUTH_TIMEOUT_MS);
+            void (async () => {
+                const settings = this.options.settings();
+                const host = (await this.options.stats().catch(() => undefined)) ?? null;
+                try {
+                    ws.send(JSON.stringify({
+                        type: 'auth',
+                        api_key: this.options.apiKey,
+                        machine_id: this.options.machineId,
+                        ...(this.options.instanceId ? { instance_id: this.options.instanceId } : {}),
+                        machine: this.options.machine,
+                        client_version: this.options.clientVersion,
+                        allow_remote_terminal: settings.allowRemoteTerminal,
+                        host,
+                    }));
+                }
+                catch {
+                    /* close follows */
+                }
+            })();
+        });
+        ws.on('message', (data) => {
+            // After stop() — or from a socket this relay has replaced — nothing counts.
+            if (this.stopped || this.ws !== ws)
+                return;
+            this.lastFrameAt = Date.now();
+            let frame;
+            try {
+                const parsed = JSON.parse(data.toString());
+                if (!parsed || typeof parsed !== 'object')
+                    return;
+                frame = parsed;
+            }
+            catch {
+                return;
+            }
+            this.onFrame(ws, frame);
+        });
+        ws.on('close', () => {
+            if (this.ws !== ws)
+                return;
+            this.authed = false;
+            this.dropStreams('the relay control socket closed');
+            this.refuseVerifications();
+            if (!this.stopped)
+                this.options.onDisconnected?.();
+            if (this.refused) {
+                // Auth was refused: retrying the same key cannot succeed. Try again
+                // slowly in case the pairing is restored, without a log line per try.
+                this.attempt = Math.max(this.attempt, 6);
+            }
+            this.reconnect();
+        });
+        ws.on('error', () => {
+            /* close follows */
+        });
+    }
+    onFrame(ws, frame) {
+        switch (frame.type) {
+            case 'auth_ok': {
+                if (this.attempt > 0 || this.refused)
+                    this.log('    ● code-host relay connected');
+                this.attempt = 0;
+                this.authed = true;
+                this.refused = undefined;
+                this.acceptToken(frame.host_token, frame.host_token_expires_at);
+                this.statusLoop(ws);
+                this.options.onAuthorization?.(true, undefined, parseIdentity(frame));
+                return;
+            }
+            case 'auth_error': {
+                const reason = String(frame.reason ?? 'unknown');
+                if (this.refused !== reason)
+                    this.log(`    ✗ code-host relay refused this machine: ${reason}`);
+                this.refused = reason;
+                this.authed = false;
+                this.dropStreams(`the relay refused this machine (${reason})`);
+                this.options.onAuthorization?.(false, reason);
+                return;
+            }
+            case 'host_token':
+                this.acceptToken(frame.token, frame.expires_at);
+                return;
+            case 'viewer_verified': {
+                const requestId = typeof frame.request_id === 'string' ? frame.request_id : '';
+                const resolve = this.verifying.get(requestId);
+                if (!resolve)
+                    return;
+                this.verifying.delete(requestId);
+                resolve(parseViewerVerdict(frame) ?? { ok: false, reason: 'not_allowed' });
+                return;
+            }
+            case 'ping':
+                this.send({ type: 'pong' });
+                return;
+            case 'dial': {
+                const dial = parseDial(frame);
+                if (dial)
+                    void this.onDial(dial);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    acceptToken(token, expiresAt) {
+        if (typeof token !== 'string' || !token || typeof expiresAt !== 'number')
+            return;
+        try {
+            this.options.onHostToken(token, expiresAt);
+        }
+        catch (err) {
+            this.log(`    ! could not store the hook token: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    dialError(streamId, reason) {
+        this.send({ type: 'dial_error', stream_id: streamId, reason });
+    }
+    async onDial(dial) {
+        // The owner's switch, read from disk now — not whatever the relay last heard.
+        if (!this.options.settings().allowRemoteTerminal) {
+            this.dialError(dial.streamId, 'remote_terminal_disabled');
+            return;
+        }
+        const url = relayUrl(this.options.baseUrl, STREAM_PATH);
+        if (!url)
+            return;
+        const generation = this.generation;
+        /** Still authorized: nothing dropped since the dial, control authed, switch on. */
+        const current = () => generation === this.generation && this.authed && !this.stopped && this.options.settings().allowRemoteTerminal;
+        const attached = await this.options.terminals.attach({
+            terminalId: dial.terminalId,
+            window: dial.window,
+            cols: dial.cols,
+            rows: dial.rows,
+            mode: dial.mode,
+        });
+        if (!attached.ok) {
+            this.dialError(dial.streamId, attached.reason);
+            return;
+        }
+        const stream = attached.stream;
+        // Attaching took a moment; authorization may have ended in it.
+        if (!current()) {
+            stream.close();
+            return;
+        }
+        const ws = new this.Ctor(url, { headers: { 'User-Agent': USER_AGENT }, handshakeTimeout: 15_000 });
+        this.streams.add(ws);
+        let ready = false;
+        const cancelReady = this.setTimer(() => {
+            if (!ready)
+                ws.terminate();
+        }, STREAM_READY_TIMEOUT_MS);
+        const abandon = () => {
+            cancelReady();
+            this.streams.delete(ws);
+            if (!ready)
+                stream.close();
+        };
+        ws.on('open', () => ws.send(JSON.stringify({ type: 'auth', stream_token: dial.streamToken })));
+        ws.on('close', abandon);
+        ws.on('error', () => {
+            /* close follows */
+        });
+        const onFirst = (data, isBinary) => {
+            if (isBinary)
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(data.toString());
+            }
+            catch {
+                frame = undefined;
+            }
+            if (frame?.type !== 'ready' || !current()) {
+                ws.terminate();
+                return;
+            }
+            ready = true;
+            cancelReady();
+            ws.off('message', onFirst);
+            pipeStream(ws, stream, () => this.streams.delete(ws));
+        };
+        ws.on('message', onFirst);
+    }
+}

package/dist/codehost/settings.d.ts

@@ -0,0 +1,52 @@
+/**
+ * This Mac's Code-thread hosting switches, and the private files the host keeps.
+ *
+ * Two switches, both off until the machine's owner turns them on here — the
+ * server can read them (the heartbeat and the relay socket report them) but has
+ * no way to change them:
+ *
+ * - `enabled` — this machine hosts Code threads: it takes
+ *   `code_thread.start_requested` / `code_thread.input_requested` from the
+ *   event stream, keeps their terminals in tmux, and holds the relay's control
+ *   socket open.
+ * - `allowRemoteTerminal` — someone other than a shell on this machine may
+ *   attach to those terminals and type: a relay viewer, or the desktop app
+ *   with any viewer token. Off, the desktop app on this Mac still attaches
+ *   over loopback, but only with a token the relay vouches for as minted for
+ *   this Mac's own app (`local_server.ts`). A remote terminal is remote code
+ *   execution on this machine; it is never on by default.
+ *
+ * Everything lives under `$PROHOST_HOME/code-host/` with owner-only modes.
+ */
+export interface CodeHostSettings {
+    version: 1;
+    enabled: boolean;
+    allowRemoteTerminal: boolean;
+}
+export declare const DEFAULT_SETTINGS: CodeHostSettings;
+/** `$PROHOST_HOME/code-host`. */
+export declare function codeHostDir(env?: NodeJS.ProcessEnv): string;
+export declare function settingsPath(env?: NodeJS.ProcessEnv): string;
+/** Create `dir` (and parents) owner-only. Idempotent. */
+export declare function ensurePrivateDir(dir: string): void;
+/**
+ * Write `value` as JSON, atomically (a temp file beside it, then a rename) and
+ * owner-only, so a reader never sees half a file or a moment of wider mode.
+ */
+export declare function writePrivateJson(file: string, value: unknown, mode?: number): void;
+/**
+ * This home's Code-host instance id: minted once per `PROHOST_HOME`, kept in
+ * `code-host/instance.json`. The server binds each Mac thread to the instance
+ * that accepted its start (`coding_sessions.host_instance_id`) and sends its
+ * later frames to that instance alone: two harnesses on one pairing each keep
+ * their own tmux windows.
+ */
+export declare function codeHostInstanceId(env?: NodeJS.ProcessEnv): string;
+/** Parsed JSON object at `file`, or `undefined` for a missing or unreadable one. */
+export declare function readJsonObject(file: string): Record<string, unknown> | undefined;
+/**
+ * The switches as they are on disk now. A missing, unreadable or malformed file
+ * is the default — both off — and only a literal `true` turns a switch on.
+ */
+export declare function loadSettings(env?: NodeJS.ProcessEnv): CodeHostSettings;
+export declare function saveSettings(settings: CodeHostSettings, env?: NodeJS.ProcessEnv): void;