@bivy/bivy 0.0.0 → 0.1.0-staging.10

package/dist/relay-cli-crypto.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Client half of the Bivy relay E2E handshake, for a CLI that reaches a node
+// through the hosted relay (the `bivy run --node <account-node>` path).
+//
+// This is the SECURITY-CRITICAL core of relay tunnelling, deliberately isolated
+// from the (network) transport so it can be unit-tested in-process against the
+// real node-side PairingStore (see test/relay-cli-crypto.test.ts). It mirrors the
+// browser client's crypto (packages/core transport-relay) using the same primitives
+// the node uses, so a CLI device pairs and exchanges frames exactly like a phone.
+//
+// Flow (transport carries these opaque):
+//   1. device keypair  = newDeviceKeypair()
+//   2. hello           = buildHello(pairSecret, keypair)         → send as t:"pair"
+//   3. node.handleHello(hello) → welcome                          (node side)
+//   4. roomKey         = acceptWelcome(keypair, welcome)          ← recover room key
+//   5. sealFrame(roomKey, msg) / openFrame(roomKey, payload)      ↔ bulk frames
+//
+// The pairSecret comes OUT OF BAND (a `bivy link`-style QR/token from the target
+// node); the relay never sees it, so it can route frames but never derive the
+// room key. See docs/relay-node-cli.md for the full transport design.
+import { generatePairingKeypair, pairingProof, deriveWrapKey, unwrapRoomKey, } from "./pairing-crypto.js";
+import { sealFrame, openFrame } from "./e2e.js";
+/** A fresh device identity for this CLI (persist privateKeyB64 to reuse a pairing). */
+export function newDeviceKeypair() {
+    return generatePairingKeypair();
+}
+/**
+ * Build the `pair.hello` payload proving knowledge of the out-of-band pairing
+ * secret without ever sending it. `label` shows up in the node's device list.
+ */
+export function buildHello(pairSecretB64, keypair, label = "Bivy CLI") {
+    return {
+        k: "pair.hello",
+        devicePublicKeyB64: keypair.publicKeyB64,
+        proofB64: pairingProof(pairSecretB64, keypair.publicKeyB64),
+        label,
+    };
+}
+/**
+ * Recover the shared room key from the node's `pair.welcome`. Derives the same
+ * ECDH wrap key the node used (ECDH is symmetric) and unwraps the room key.
+ * Throws if the welcome is malformed or the wrap doesn't open (wrong node/key).
+ */
+export function acceptWelcome(keypair, welcome) {
+    if (!welcome?.nodePublicKeyB64 || !welcome?.wrapped)
+        throw new Error("Malformed pair.welcome");
+    const wrapKey = deriveWrapKey(keypair.privateKeyB64, welcome.nodePublicKeyB64, "pair");
+    return unwrapRoomKey(wrapKey, welcome.wrapped);
+}
+/**
+ * A tiny stateful helper wrapping the room key for a session: seal outbound
+ * client messages and open inbound node frames. Transport-agnostic — feed it the
+ * relay's decrypted frame payloads and send its sealed output over the relay.
+ */
+export class RoomCipher {
+    roomKey;
+    constructor(roomKey) {
+        this.roomKey = roomKey;
+    }
+    seal(message) {
+        return sealFrame(this.roomKey, message);
+    }
+    open(payload) {
+        return openFrame(this.roomKey, payload);
+    }
+    key() {
+        return this.roomKey;
+    }
+}

package/dist/relay-client.js

@@ -0,0 +1,372 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import { WebSocket } from "ws";
+import { seal, sealFrame, openFrame, ReplayGuard } from "./e2e.js";
+import { frameMessages, FrameReassembler } from "./relay-chunk.js";
+function isFatalRelayError(message) {
+    return /hosted relay is not enabled|unauthorized|missing token/i.test(message);
+}
+export function loadRelayConfig(appDir) {
+    const envUrl = process.env.BIVY_RELAY_URL;
+    const filePath = path.join(appDir, "relay.json");
+    let raw = {};
+    if (fs.existsSync(filePath)) {
+        try {
+            raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        }
+        catch {
+            raw = {};
+        }
+    }
+    const url = envUrl ?? raw.url;
+    const enrollmentToken = process.env.BIVY_RELAY_TOKEN ?? raw.enrollmentToken;
+    if (!url || !enrollmentToken)
+        return null;
+    const controlPlaneUrl = process.env.BIVY_CONTROL_PLANE_URL ?? raw.controlPlaneUrl;
+    const clientBaseUrl = process.env.BIVY_CLIENT_BASE_URL ?? raw.clientBaseUrl ?? controlPlaneUrl;
+    return { url, enrollmentToken, controlPlaneUrl, clientBaseUrl };
+}
+// Application-level keepalive. On flaky/mobile links the node→relay TCP socket
+// can half-open silently: the node still thinks it is connected and buffers
+// sends into a dead socket while clients see "node offline". The relay's own
+// heartbeat eventually reaps the dead socket, but on a lenient interval (up to a
+// few minutes). Pinging from the node and reconnecting when pongs stop cuts that
+// detection window to ~1 minute so the node redials (and clients recover) fast.
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_TIMEOUT_MS = 75_000;
+// Only reset reconnect backoff after a connection has held this long. The relay
+// accepts the WS upgrade and sends `ready` BEFORE its rate limiter may reject
+// and close the socket a moment later, so resetting on `ready` alone let a
+// rate-limited node reconnect every ~1s indefinitely — a storm that itself keeps
+// tripping the limiter. Requiring a stable window lets backoff escalate normally.
+const BACKOFF_STABLE_RESET_MS = 30_000;
+export class RelayConnector {
+    config;
+    onClientMessage;
+    ws;
+    closed = false;
+    backoff = 1000;
+    heartbeatTimer;
+    stableTimer;
+    lastPongAt = 0;
+    // True only between the relay's `ready` message (auth + entitlement passed)
+    // and the socket closing. This — not "a connector object exists" — is what
+    // "connected" means to the control plane, so it's what `bivy status` reports.
+    ready = false;
+    // Most recent relay-side failure (ticket mint, socket error, or an `error`
+    // frame), surfaced by `bivy status`/`doctor` so a node that never connects
+    // explains why instead of silently showing "configured".
+    lastErrorMessage;
+    replay = new ReplayGuard();
+    reassembler = new FrameReassembler();
+    pairing;
+    onWorkAvailable;
+    constructor(config, onClientMessage, options) {
+        this.config = config;
+        this.onClientMessage = onClientMessage;
+        this.pairing = options.pairing;
+        this.onWorkAvailable = options.onWorkAvailable;
+    }
+    /** Current bulk-encryption key: the pairing store's rotating room key. */
+    roomKey() {
+        return this.pairing.roomKey();
+    }
+    /** Push a room-key rotation (after a device revoke) to connected devices. */
+    pushRotate(deliveries) {
+        if (this.ws?.readyState !== WebSocket.OPEN || deliveries.length === 0)
+            return;
+        this.ws.send(JSON.stringify({ t: "pair", p: JSON.stringify({ k: "key.rotate", deliveries }) }));
+    }
+    /**
+     * True only while the relay link is live AND the relay has sent `ready`
+     * (auth/entitlement checks passed) — i.e. the node is actually reachable from
+     * the control plane. A socket that opened but was rejected, or one still
+     * reconnecting, reads false.
+     */
+    get connected() {
+        return this.ready && this.ws?.readyState === WebSocket.OPEN;
+    }
+    /** Most recent relay-side failure, if any — for status/diagnostics. */
+    get lastError() {
+        return this.lastErrorMessage;
+    }
+    start() {
+        this.closed = false;
+        void this.connect();
+    }
+    stop() {
+        this.closed = true;
+        this.ready = false;
+        this.stopHeartbeat();
+        this.clearBackoffReset();
+        this.ws?.close();
+    }
+    startHeartbeat(ws) {
+        this.stopHeartbeat();
+        this.lastPongAt = Date.now();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws !== ws || ws.readyState !== WebSocket.OPEN) {
+                this.stopHeartbeat();
+                return;
+            }
+            if (Date.now() - this.lastPongAt > HEARTBEAT_TIMEOUT_MS) {
+                // No pong since the last few pings — treat the link as half-open and
+                // force a reconnect rather than streaming into a dead socket.
+                console.warn("[relay] keepalive timed out; reconnecting");
+                this.stopHeartbeat();
+                ws.terminate();
+                return;
+            }
+            try {
+                ws.ping();
+            }
+            catch {
+                // A failed ping means the socket is already gone; close will follow.
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+        this.heartbeatTimer.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+    // Reset reconnect backoff only once this connection has stayed up for a stable
+    // window (see BACKOFF_STABLE_RESET_MS). Armed on `ready`, disarmed on close, so
+    // a connection that the relay rate-limits and drops seconds later never counts
+    // as healthy and backoff keeps escalating instead of hot-looping.
+    scheduleBackoffReset(ws) {
+        this.clearBackoffReset();
+        this.stableTimer = setTimeout(() => {
+            if (!this.closed && this.ws === ws && ws.readyState === WebSocket.OPEN)
+                this.backoff = 1000;
+        }, BACKOFF_STABLE_RESET_MS);
+        this.stableTimer.unref?.();
+    }
+    clearBackoffReset() {
+        if (this.stableTimer) {
+            clearTimeout(this.stableTimer);
+            this.stableTimer = undefined;
+        }
+    }
+    /**
+     * Encrypt a string with the current room key for AT-REST storage off-node
+     * (e.g. a session title in the control-plane index). Clients holding the room
+     * key decrypt it; the control plane only ever sees ciphertext.
+     */
+    sealString(value) {
+        return seal(this.roomKey(), value);
+    }
+    /** Push a local session event to remote clients (encrypted). */
+    sendEvent(event) {
+        if (this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        const payload = sealFrame(this.roomKey(), event);
+        // Large events (big file reads, long diffs, image attachments) are split
+        // into multiple relay frames so none exceeds the relay's max-frame limit;
+        // the client reassembles them before decrypting.
+        for (const msg of frameMessages(payload)) {
+            if (this.ws?.readyState !== WebSocket.OPEN)
+                return;
+            this.ws.send(msg);
+        }
+    }
+    /**
+     * Handle a pairing control frame from a device (X25519 handshake). These are
+     * forwarded verbatim by the relay (t === "pair") and never contain the room
+     * key in the clear. Only `pair.hello` is acted on; the node replies with
+     * `pair.welcome` carrying the ECDH-wrapped room key.
+     */
+    async handlePairFrame(payload) {
+        let msg;
+        try {
+            msg = JSON.parse(payload);
+        }
+        catch {
+            return;
+        }
+        let welcome = null;
+        let reason = "Pairing failed";
+        if (msg.k === "pair.hello" && msg.devicePublicKeyB64 && msg.proofB64) {
+            welcome = this.pairing.handleHello({
+                devicePublicKeyB64: msg.devicePublicKeyB64,
+                proofB64: msg.proofB64,
+                label: msg.label,
+            });
+        }
+        else if (msg.k === "pair.account" && msg.devicePublicKeyB64 && msg.sessionToken) {
+            const auth = await this.authorizeAccountPairing(msg.sessionToken, msg.devicePublicKeyB64, msg.label, msg.ephemeral === true);
+            if (auth.ok)
+                welcome = this.pairing.trustDevice({ devicePublicKeyB64: msg.devicePublicKeyB64, label: msg.label });
+            else
+                reason = auth.reason;
+        }
+        else {
+            return;
+        }
+        if (!welcome) {
+            this.ws?.send(JSON.stringify({ t: "pair", p: JSON.stringify({ k: "pair.error", error: reason }) }));
+            return;
+        }
+        this.ws?.send(JSON.stringify({ t: "pair", p: JSON.stringify({ k: "pair.welcome", ...welcome }) }));
+    }
+    /**
+     * Verify that an account-session client is allowed to link this node. Returns
+     * the control plane's concrete failure reason (e.g. "Device limit reached")
+     * so the node can relay it to the client instead of a bare "pairing rejected".
+     */
+    async authorizeAccountPairing(sessionToken, devicePublicKeyB64, label, ephemeral = false) {
+        if (!this.config.controlPlaneUrl)
+            return { ok: false, reason: "Node is not linked to a control plane." };
+        try {
+            const res = await fetch(`${this.config.controlPlaneUrl.replace(/\/$/, "")}/node/authorize-client`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${this.config.enrollmentToken}` },
+                body: JSON.stringify({ sessionToken, devicePublicKeyB64, label, ephemeral }),
+                // Node's fetch has no default timeout. Without this, a control plane that
+                // accepts the TCP connection but never responds would hang pairing (and,
+                // on the mintTicket path, the whole relay reconnect) indefinitely.
+                signal: AbortSignal.timeout(10_000),
+            });
+            const data = (await res.json().catch(() => ({})));
+            if (res.ok && data.ok === true)
+                return { ok: true };
+            return { ok: false, reason: data.error || `Pairing rejected (${res.status}).` };
+        }
+        catch (err) {
+            return { ok: false, reason: err?.message || "Could not reach the control plane to pair." };
+        }
+    }
+    /**
+     * Exchange the long-lived enrollment token for a short-lived, single-use
+     * relay ticket — directly against the control plane (over TLS). Only the
+     * ticket is presented to the relay, so the relay never sees a reusable
+     * credential. A fresh ticket is minted on every (re)connect.
+     */
+    async mintTicket() {
+        if (!this.config.controlPlaneUrl) {
+            throw new Error("relay.json missing controlPlaneUrl (required for relay tickets)");
+        }
+        const res = await fetch(`${this.config.controlPlaneUrl.replace(/\/$/, "")}/node/relay-ticket`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${this.config.enrollmentToken}` },
+            body: "{}",
+            // connect() awaits this on every (re)connect; a hung control plane must
+            // fail fast into scheduleReconnect() rather than wedge remote access.
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            throw new Error(`ticket request failed: ${res.status}`);
+        const data = (await res.json());
+        if (!data?.ticket)
+            throw new Error("control plane returned no ticket");
+        return { ticket: data.ticket, relayUrl: typeof data.relayUrl === "string" ? data.relayUrl : undefined };
+    }
+    async connect() {
+        let ticket;
+        let relayUrl;
+        try {
+            ({ ticket, relayUrl } = await this.mintTicket());
+        }
+        catch (error) {
+            this.lastErrorMessage = `ticket mint failed: ${error.message}`;
+            console.warn("[relay] could not mint relay ticket:", error.message);
+            this.scheduleReconnect();
+            return;
+        }
+        if (this.closed)
+            return;
+        // Connect to the shard the control plane assigned this node (docs/scaling.md),
+        // falling back to the statically configured relay for older control planes.
+        const relayBase = (relayUrl ?? this.config.url).replace(/\/$/, "");
+        const target = `${relayBase}/node?ticket=${encodeURIComponent(ticket)}`;
+        const ws = new WebSocket(target);
+        this.ws = ws;
+        ws.on("open", () => {
+            // The TCP/WebSocket handshake succeeded, but relay auth/entitlement
+            // checks happen after upgrade. Wait for the relay's `ready` message
+            // before declaring the connector usable or resetting reconnect backoff.
+        });
+        ws.on("message", (data) => {
+            let env;
+            try {
+                env = JSON.parse(data.toString());
+            }
+            catch {
+                return;
+            }
+            if (env.t === "ready") {
+                this.ready = true;
+                this.lastErrorMessage = undefined;
+                this.startHeartbeat(ws);
+                this.scheduleBackoffReset(ws);
+                console.log("[relay] connected");
+                return;
+            }
+            if (env.t === "pair" && typeof env.p === "string") {
+                void this.handlePairFrame(env.p);
+                return;
+            }
+            if (env.t === "work.available") {
+                const hint = env;
+                this.onWorkAvailable?.({ id: typeof hint.id === "string" ? hint.id : undefined, label: typeof hint.label === "string" ? hint.label : undefined });
+                return;
+            }
+            if (env.t === "frame" && typeof env.p === "string") {
+                // Reassemble chunked frames (large client uploads) before decrypting;
+                // returns null while more chunks are still in flight.
+                const payload = this.reassembler.accept(env);
+                if (payload === null)
+                    return;
+                try {
+                    const frame = openFrame(this.roomKey(), payload);
+                    if (!this.replay.accept(frame)) {
+                        console.warn("[relay] dropped stale or replayed client frame");
+                        return;
+                    }
+                    this.onClientMessage(frame.data);
+                }
+                catch {
+                    console.warn("[relay] failed to decrypt client frame");
+                }
+                return;
+            }
+            if (env.t === "error") {
+                const message = env.error || "Relay error";
+                this.lastErrorMessage = message;
+                console.warn("[relay] error:", message);
+                if (isFatalRelayError(message)) {
+                    console.warn("[relay] disabling connector; fix relay setup/plan and restart the node dev server");
+                    this.closed = true;
+                    ws.close();
+                }
+            }
+        });
+        ws.on("pong", () => {
+            this.lastPongAt = Date.now();
+        });
+        ws.on("close", () => {
+            this.ready = false;
+            this.stopHeartbeat();
+            this.clearBackoffReset();
+            this.scheduleReconnect();
+        });
+        ws.on("error", (error) => {
+            this.lastErrorMessage = error.message;
+            console.warn("[relay] socket error:", error.message);
+        });
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        const wait = this.backoff;
+        this.backoff = Math.min(this.backoff * 2, 30_000);
+        setTimeout(() => {
+            if (!this.closed)
+                void this.connect();
+        }, wait);
+    }
+}