@bivy/bivy 0.0.0 → 0.1.0-staging.2

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,344 @@
+// 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;
+    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 }) }));
+    }
+    start() {
+        this.closed = false;
+        void this.connect();
+    }
+    stop() {
+        this.closed = true;
+        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) {
+            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.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";
+                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.stopHeartbeat();
+            this.clearBackoffReset();
+            this.scheduleReconnect();
+        });
+        ws.on("error", (error) => {
+            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);
+    }
+}

package/dist/relay-setup.js

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { NodeIdentity } from "./identity.js";
+import { hostedEndpoints } from "./hosted-endpoints.mjs";
+import { openBrowser } from "./browser-open.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * One-time node relay setup.
+ *
+ * Signs into the control plane (hands-free magic-link by default), enrolls THIS
+ * node (using its stable nodeId), generates an E2E key, and writes
+ * `.bivy/relay.json`. After this the daemon dials the relay automatically
+ * on next start.
+ *
+ * Endpoints default to the baked-in hosted service (see hosted-endpoints.mjs);
+ * a user never has to type a URL. Everything is overridable for self-hosting:
+ *
+ *   npm run relay:setup -- --email you@example.com
+ *   BIVY_HOSTED_DOMAIN=bivy.sh npm run relay:setup -- --email you@…
+ *   npm run relay:setup -- --control-plane https://app.x --relay wss://relay.x \
+ *     --email you@example.com
+ *
+ * Sign-in is hands-free: we email a link, you click it in a browser, and this
+ * command detects completion by polling. Pass `--session-token` to skip sign-in
+ * when you already have an account session.
+ */
+function arg(name, fallback) {
+    const i = process.argv.indexOf(`--${name}`);
+    if (i !== -1 && process.argv[i + 1])
+        return process.argv[i + 1];
+    return fallback;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchJson(url, init) {
+    let response;
+    try {
+        response = await fetch(url, init);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not reach ${url}: ${message}`);
+    }
+    const data = await response.json().catch(() => ({}));
+    return { ok: response.ok, status: response.status, data };
+}
+async function askYesNo(question, defaultYes) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const hint = defaultYes ? "Y/n" : "y/N";
+    try {
+        for (;;) {
+            const answer = await new Promise((resolve) => rl.question(`\n${question} (${hint})\n  > `, resolve));
+            const v = answer.trim().toLowerCase();
+            if (!v)
+                return defaultYes;
+            if (v === "y" || v === "yes")
+                return true;
+            if (v === "n" || v === "no")
+                return false;
+            console.log("Please answer yes or no.");
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function checkControlPlane(controlPlaneUrl) {
+    // /me returns 401 when healthy and unauthenticated. That is good enough to
+    // catch DNS/TLS/reverse-proxy mistakes before the user waits for email.
+    try {
+        const response = await fetch(`${controlPlaneUrl}/me`);
+        if (response.status === 401 || response.ok)
+            return;
+        throw new Error(`health check returned HTTP ${response.status}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Hosted control plane is not reachable at ${controlPlaneUrl}. ${message}`);
+    }
+}
+/** Poll a started device login until it completes; returns the session token. */
+async function pollDevice(controlPlaneUrl, start) {
+    const intervalMs = Number(start.intervalMs) || 2000;
+    const deadline = Date.now() + (Number(start.expiresInMs) || 15 * 60_000);
+    process.stdout.write("Waiting for you to finish sign-in");
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        process.stdout.write(".");
+        const pollResult = await fetchJson(`${controlPlaneUrl}/auth/device/poll`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ deviceId: start.deviceId, deviceSecret: start.deviceSecret }),
+        }).catch(() => null);
+        const poll = pollResult?.data;
+        if (poll?.status === "complete" && poll.token) {
+            process.stdout.write("\n");
+            return poll.token;
+        }
+        if (poll?.status === "expired")
+            break;
+    }
+    process.stdout.write("\n");
+    throw new Error("Sign-in timed out or expired. Run setup again.");
+}
+/**
+ * Hands-free magic-link sign-in. Emails a link, opens/prints it, polls until
+ * clicked. Returns an account session token.
+ */
+async function deviceLogin(controlPlaneUrl, email) {
+    const started = await fetchJson(`${controlPlaneUrl}/auth/device/start`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email }),
+    });
+    const start = started.data;
+    if (!started.ok || !start?.deviceId || !start?.deviceSecret) {
+        throw new Error(`Sign-in could not start (${started.status}): ${JSON.stringify(start)}`);
+    }
+    if (start.devLink) {
+        const opened = openBrowser(start.devLink);
+        console.log(opened
+            ? `\nOpening sign-in link (no email configured on the server):\n  ${start.devLink}`
+            : `\nNo email configured on the server — open this sign-in link in a browser (this machine has none):\n  ${start.devLink}`);
+    }
+    else {
+        console.log(`\nWe emailed a sign-in link to ${email}. Open it in your browser to continue.`);
+    }
+    return pollDevice(controlPlaneUrl, start);
+}
+/**
+ * Hands-free GitHub sign-in (primary). Opens the GitHub authorize URL and polls
+ * until the OAuth callback completes the device login. Returns a session token.
+ */
+async function githubDeviceLogin(controlPlaneUrl) {
+    const started = await fetchJson(`${controlPlaneUrl}/auth/device/github/start`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+    });
+    const start = started.data;
+    if (started.status === 501)
+        throw new Error("GitHub sign-in is not enabled on this control plane. Use --email instead.");
+    if (!started.ok || !start?.deviceId || !start?.authorizeUrl) {
+        throw new Error(`GitHub sign-in could not start (${started.status}): ${JSON.stringify(start)}`);
+    }
+    const opened = openBrowser(start.authorizeUrl);
+    console.log(opened
+        ? `\nSign in with GitHub in your browser:\n  ${start.authorizeUrl}`
+        : `\nSign in with GitHub — open this link in a browser on any device (this machine has none):\n  ${start.authorizeUrl}`);
+    return pollDevice(controlPlaneUrl, start);
+}
+async function main() {
+    const repoRoot = path.resolve(__dirname, "..");
+    // Honor the same override as every other entry point (server.ts, native-pi.ts,
+    // bivy-login.ts, secrets-cli.ts, …) so a global/packaged install writes
+    // relay.json and the node identity into the real data dir instead of a
+    // package directory that gets wiped on update. See issue #2.
+    const appDir = process.env.BIVY_DATA_DIR ?? path.join(repoRoot, ".bivy");
+    const endpoints = hostedEndpoints();
+    const controlPlaneUrl = (arg("control-plane", process.env.BIVY_CONTROL_PLANE_URL) ?? endpoints.controlPlane).replace(/\/$/, "");
+    const relayUrl = (arg("relay", process.env.BIVY_RELAY_URL) ?? endpoints.relay).replace(/\/$/, "");
+    const clientBaseUrl = (arg("client", process.env.BIVY_CLIENT_BASE_URL) ?? endpoints.clientBaseUrl).replace(/\/$/, "") || controlPlaneUrl;
+    const email = arg("email", process.env.BIVY_EMAIL);
+    const sessionToken = arg("session-token", process.env.BIVY_SESSION_TOKEN);
+    // GitHub is the primary sign-in: used when --github is passed, or by default
+    // when neither an email nor an existing session token is supplied.
+    const useGithub = process.argv.includes("--github") || process.env.BIVY_AUTH === "github" || (!email && !sessionToken);
+    const identity = NodeIdentity.load(appDir);
+    console.log(`Node: ${identity.name} (${identity.nodeId})`);
+    console.log(`Control plane: ${controlPlaneUrl}`);
+    console.log(`Relay:         ${relayUrl}`);
+    await checkControlPlane(controlPlaneUrl);
+    const token = sessionToken ?? (useGithub ? await githubDeviceLogin(controlPlaneUrl) : await deviceLogin(controlPlaneUrl, email));
+    async function enrollNode() {
+        return fetchJson(`${controlPlaneUrl}/nodes/enroll`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+            body: JSON.stringify({ nodeId: identity.nodeId, name: identity.name }),
+        });
+    }
+    let enrolled = await enrollNode();
+    let enroll = enrolled.data;
+    if (!enrolled.ok && enrolled.status === 402 && /node limit/i.test(String(enroll?.error ?? ""))) {
+        const listed = await fetchJson(`${controlPlaneUrl}/nodes`, { headers: { authorization: `Bearer ${token}` } });
+        const nodes = Array.isArray(listed.data) ? listed.data : [];
+        if (nodes.length) {
+            // Lead with the upgrade paths — subscribing or increasing the plan is the
+            // intended way to add a node. Removing an existing node is the fallback.
+            const accountUrl = `${clientBaseUrl}/?account=1`;
+            console.log("\nYour plan's node limit is reached.");
+            console.log(`To connect more nodes, subscribe or increase your plan:\n  ${accountUrl}`);
+            console.log("\nOr free a slot by removing an existing node:");
+            for (const [i, node] of nodes.entries()) {
+                console.log(`  ${i + 1}. ${node.name ?? "Node"} — ${node.online ? "online" : "offline"} — ${node.id}`);
+            }
+            const replace = await askYesNo(`Remove ${nodes[0].name ?? nodes[0].id} and enroll this node instead?`, !nodes[0].online);
+            if (replace) {
+                const removed = await fetchJson(`${controlPlaneUrl}/nodes/${encodeURIComponent(nodes[0].id)}`, {
+                    method: "DELETE",
+                    headers: { authorization: `Bearer ${token}` },
+                });
+                if (!removed.ok)
+                    throw new Error(`Could not remove old node (${removed.status}): ${JSON.stringify(removed.data)}`);
+                enrolled = await enrollNode();
+                enroll = enrolled.data;
+            }
+        }
+    }
+    if (!enrolled.ok || !enroll?.enrollmentToken)
+        throw new Error(`Enroll failed (${enrolled.status}): ${JSON.stringify(enroll)}`);
+    // The control plane keeps node names unique per account, so a colliding name may
+    // have been auto-suffixed (e.g. "Mac-2"). Adopt the assigned name locally so the
+    // node serves the matching `bivy/<name>` label (and the UI agrees on the name).
+    const assignedName = typeof enroll?.node?.name === "string" ? enroll.node.name : undefined;
+    if (assignedName && assignedName !== identity.name) {
+        try {
+            identity.setName(assignedName);
+            console.log(`Node name adjusted to "${assignedName}" (kept unique on your account).`);
+        }
+        catch {
+            /* non-fatal — routing still works via the shared bivy label */
+        }
+    }
+    const config = {
+        url: relayUrl,
+        controlPlaneUrl,
+        clientBaseUrl,
+        enrollmentToken: enroll.enrollmentToken,
+    };
+    const filePath = path.join(appDir, "relay.json");
+    fs.writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(filePath, 0o600);
+    // Optional handoff: when `bivy setup` runs us with --emit-session, drop the
+    // account session we just obtained (plus this node's id) into a 0600 file so
+    // setup can open the remote app signed into the whole account — not a
+    // node-scoped grant that would show only this node. The account bearer never
+    // goes into relay.json (the node keeps only its enrollment token); this file is
+    // read once and deleted by setup. We skip it when the caller supplied a session
+    // token only via --session-token/env with no --emit-session, i.e. non-setup use.
+    const emitSession = arg("emit-session");
+    if (emitSession) {
+        try {
+            const handoff = JSON.stringify({ session: token, nodeId: identity.nodeId });
+            fs.writeFileSync(emitSession, `${handoff}\n`, { mode: 0o600 });
+            fs.chmodSync(emitSession, 0o600);
+        }
+        catch {
+            // best effort — setup falls back to opening the plain remote app URL
+        }
+    }
+    console.log(`\n✓ Signed in and enrolled this node. Wrote ${filePath}`);
+    console.log('Run "bivy link" to pair a phone, or use "Link remote device" in the app (bivy open).');
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});