@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/remote/client.js

@@ -0,0 +1,659 @@
+import { createHash, randomBytes } from 'node:crypto';
+import * as tls from 'node:tls';
+import { isIP } from 'node:net';
+import { hostname as osHostname } from 'node:os';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { RemotePeerError, InviteRejectedError } from './errors.js';
+import { pemFromDer } from './cert.js';
+import { resolvePeerAddress, resolvePeerAddresses } from './network.js';
+const REQUEST_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+/**
+ * How long one address attempt may still take inside an overall deadline.
+ *
+ * A walk covers every host a pairing advertised, and each host can answer with a dual-stack pair, so a
+ * machine that black-holes all of them costs the full connect timeout per ADDRESS: the eight hosts a
+ * pairing plan advertises are up to sixteen addresses and 240 seconds of waiting — longer than any
+ * caller's own budget, which would answer its user first and then start a second walk while the first
+ * was still on host one. A caller that passes a deadline gets the same offline verdict a settled walk
+ * produces, but from the walk itself rather than from its own client.
+ */
+export function addressAttemptBudgetMs(deadlineAt, now) {
+    return deadlineAt === undefined ? REQUEST_TIMEOUT_MS : Math.min(REQUEST_TIMEOUT_MS, deadlineAt - now);
+}
+function fingerprintOf(der) {
+    return createHash('sha256').update(der).digest('base64url');
+}
+/** Distinguishes "cannot reach it" from "the identity is wrong" from "the wire spoke badly". */
+function classifyTlsFailure(error, sawCertificate) {
+    const detail = `${error.code ?? ''} ${error.message}`;
+    if (/certificate|verify|self-|altname|ERR_TLS_CERT_ALTNAME/i.test(detail)) {
+        return new RemotePeerError('identity', 'The peer presented a different certificate than the one you paired. Re-pairing is required.');
+    }
+    if (/EPROTO|wrong version number|packet length|not secure|sslv3|alert/i.test(detail) && !sawCertificate) {
+        return new RemotePeerError('network', 'The peer port did not answer the TLS handshake.');
+    }
+    return new RemotePeerError('network', `Peer TLS failed: ${error.message}`);
+}
+/**
+ * Map any connect-, TLS-, or protocol-level failure onto exactly one peer-error kind.
+ *
+ * The order is deliberate: an identity gate that already fired outranks the generic socket error
+ * it caused (the destroy looks like a reset), then reachability (offline — the desktop shows the
+ * workspace as unreachable), then certificate validation against the pinned anchor (identity —
+ * the peer swapped certificates, which is the fail-closed re-pair state, not a retry-later), and
+ * everything else is a plain network problem.
+ */
+function classifyFailure(error, identityError) {
+    if (identityError)
+        return identityError;
+    const code = error.code ?? '';
+    const detail = `${code} ${error.message}`;
+    if (code === 'ECONNREFUSED' || code === 'EHOSTUNREACH' || code === 'ENETUNREACH' || code === 'ETIMEDOUT' || code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+        return new RemotePeerError('offline', `Could not reach the paired machine (${code}).`);
+    }
+    if (/certificate|verify|self-|ERR_TLS_CERT_ALTNAME|unable to verify/i.test(detail)) {
+        return new RemotePeerError('identity', 'The peer presented a certificate that does not match the one you paired. Re-pairing is required.');
+    }
+    if (/EPROTO|wrong version number|packet length|sslv3|alert|not secure/i.test(detail)) {
+        return new RemotePeerError('network', 'The peer port did not answer the TLS handshake.');
+    }
+    return new RemotePeerError('network', error.message);
+}
+/**
+ * One peer request, end to end: validated DNS answer -> pinned address -> fingerprint-gated TLS.
+ *
+ * The address is resolved through `resolvePeerAddress` once and the socket is created directly
+ * against that literal address, so DNS can never answer a second time between the check and the
+ * connect (the DNS-rebinding window). For https there is deliberately no request-level agent —
+ * including the implicit one `agent: false` creates, because an agent owns socket creation and
+ * would bypass the fingerprint gate: with no agent, the ClientRequest hands the connect to the
+ * `createConnection` below, which builds the TLS socket per attempt and delivers it only through
+ * the callback, AFTER verifying the fingerprint off `secureConnect`. Until that callback fires
+ * the ClientRequest has no socket and the request bytes stay unbuffered: a mismatch destroys the
+ * socket with the invitation or token still un-sent.
+ *
+ * The Host header keeps the name the user paired; the peer server has no allowlist to satisfy —
+ * the entire defense lives here, in this client.
+ */
+async function request(target, method, path, body, hostOrder, deadlineAt, limits = {}, signal) {
+    signal?.throwIfAborted();
+    const maxResponseBytes = limits.maxResponseBytes ?? MAX_RESPONSE_BYTES;
+    const host = hostOrder ?? target.host;
+    // Resolution failures are classified like any other connect failure: a MagicDNS name that cannot
+    // be looked up right now (ENOTFOUND/EAI_AGAIN — Tailscale's DNS is down, the tailnet is off) is a
+    // reachability answer, so the status probe reads `offline` rather than a generic network error.
+    // DNS is part of the same wall-clock probe budget as the socket walk. A stalled MagicDNS
+    // lookup must not outlive the desktop's request and permit overlapping sweeps.
+    const resolveAddresses = resolvePeerAddresses(host).catch((error) => {
+        throw classifyFailure(error, undefined);
+    });
+    let resolveTimer;
+    let removeAbortListener;
+    const pending = [resolveAddresses];
+    if (deadlineAt !== undefined)
+        pending.push(new Promise((_, reject) => {
+            const remaining = deadlineAt - Date.now();
+            if (remaining <= 0)
+                reject(new RemotePeerError('offline', `Reaching ${host} ran out of time.`));
+            else
+                resolveTimer = setTimeout(() => reject(new RemotePeerError('offline', `Reaching ${host} ran out of time.`)), remaining);
+        }));
+    if (signal)
+        pending.push(new Promise((_, reject) => {
+            const onAbort = () => reject(signal.reason ?? new Error('Peer request cancelled.'));
+            removeAbortListener = () => signal.removeEventListener('abort', onAbort);
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
+        }));
+    // Cancelling the screen ends DNS waiting immediately, before any authorized socket opens.
+    const addresses = await Promise.race(pending).finally(() => {
+        if (resolveTimer !== undefined)
+            clearTimeout(resolveTimer);
+        removeAbortListener?.();
+    });
+    signal?.throwIfAborted();
+    const certPem = target.certPem;
+    if (target.transport === 'https' && !certPem)
+        throw new RemotePeerError('network', 'No pinned certificate for this workspace — it must be re-paired.');
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+    const send = (address, attemptTimeoutMs) => new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('Peer request cancelled.'));
+            return;
+        }
+        let identityError;
+        let settled = false;
+        let deadlineTimer;
+        // Any verdict — including one the socket brought on its own — retires the shared-deadline guard.
+        const stopDeadline = () => { if (deadlineTimer !== undefined) {
+            clearTimeout(deadlineTimer);
+            deadlineTimer = undefined;
+        } };
+        const fail = (error) => { if (!settled) {
+            settled = true;
+            stopDeadline();
+            reject(error);
+        } };
+        const succeed = (value) => { if (!settled) {
+            settled = true;
+            stopDeadline();
+            resolve(value);
+        } };
+        const chunks = [];
+        let size = 0;
+        const options = {
+            host: address.address,
+            port: target.port,
+            method,
+            path,
+            ...(signal ? { signal } : {}),
+            // Omitted on https: the agent would own socket creation and bypass the fingerprint gate.
+            // The bare-HTTP path keeps `agent: false` so responses never ride the process-wide agent.
+            ...(target.transport === 'https' ? {} : { agent: false }),
+            headers: {
+                ...(target.token ? { authorization: `Bearer ${target.token}` } : {}),
+                ...(payload !== undefined ? { 'content-type': 'application/json', 'content-length': String(Buffer.byteLength(payload)) } : {}),
+                host: `${target.host}:${target.port}`,
+            },
+        };
+        if (target.transport === 'https' && certPem) {
+            const tlsOptions = {
+                host: address.address,
+                port: target.port,
+                // SNI only for a real name; an IP literal in `servername` is an error.
+                ...(isIP(host) ? {} : { servername: host }),
+                ca: [certPem],
+                rejectUnauthorized: true,
+                // Identity is the fingerprint gate below; the certificate's names are decorative.
+                checkServerIdentity: () => undefined,
+                timeout: attemptTimeoutMs,
+            };
+            Object.assign(options, tlsOptions);
+            options.createConnection = (_connectOptions, onCreated) => {
+                const socket = tls.connect(tlsOptions);
+                let gated = false;
+                if (signal) {
+                    const onAbort = () => {
+                        socket.destroy();
+                        if (!gated) {
+                            gated = true;
+                            onCreated(new Error('Peer request cancelled.'));
+                        }
+                    };
+                    signal.addEventListener('abort', onAbort, { once: true });
+                    socket.once('close', () => signal.removeEventListener('abort', onAbort));
+                    if (signal.aborted) {
+                        onAbort();
+                        return;
+                    }
+                }
+                socket.once('secureConnect', () => {
+                    if (gated)
+                        return;
+                    gated = true;
+                    const certificate = socket.getPeerCertificate(true);
+                    const der = certificate?.raw;
+                    if (!der) {
+                        identityError = new RemotePeerError('identity', 'The peer presented no certificate.');
+                        socket.destroy();
+                        onCreated(identityError);
+                        return;
+                    }
+                    const presented = fingerprintOf(Buffer.from(der));
+                    if (presented !== target.fingerprint) {
+                        identityError = new RemotePeerError('identity', 'The peer presented a different certificate than the one you paired. Re-pairing is required.');
+                        socket.destroy();
+                        onCreated(identityError);
+                        return;
+                    }
+                    onCreated(null, socket);
+                });
+                socket.once('error', (error) => {
+                    // Handshake failures (including a certificate the pin would never have admitted) reach
+                    // the request as-is only while the gate has not produced its own identity verdict.
+                    if (gated)
+                        return;
+                    gated = true;
+                    onCreated(error);
+                });
+                socket.on('timeout', () => {
+                    socket.destroy();
+                    if (!gated) {
+                        gated = true;
+                        onCreated(new RemotePeerError('offline', `Connecting to ${host}:${target.port} timed out.`));
+                    }
+                });
+                // Nothing is returned: delivering the socket solely through `onCreated` is what keeps the
+                // request bytes unwritten until the fingerprint has been checked.
+            };
+        }
+        else {
+            options.timeout = attemptTimeoutMs;
+        }
+        const req = (target.transport === 'https' ? httpsRequest : httpRequest)(options, res => {
+            res.on('data', chunk => {
+                size += chunk.length;
+                if (size > maxResponseBytes) {
+                    req.destroy();
+                    fail(new RemotePeerError('network', 'Peer response exceeded the size limit.'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('end', () => {
+                const status = res.statusCode ?? 0;
+                const text = Buffer.concat(chunks).toString('utf8');
+                let parsed;
+                try {
+                    parsed = text ? JSON.parse(text) : undefined;
+                }
+                catch {
+                    parsed = undefined;
+                }
+                const detail = parsed && typeof parsed === 'object' && 'error' in parsed && typeof parsed.error === 'string'
+                    ? parsed.error : undefined;
+                // Redirects are refused, not followed: a `Location` would be a new, unvalidated target.
+                if (status >= 300 && status < 400) {
+                    fail(new RemotePeerError('network', 'The peer tried to redirect this request, which remote browsing does not follow.'));
+                    return;
+                }
+                if (status === 401) {
+                    fail(new RemotePeerError('unauthorized', detail ?? 'This device is no longer authorized on that workspace.'));
+                    return;
+                }
+                if (status >= 400) {
+                    fail(new RemotePeerError('rejected', detail ?? `The peer refused the request (${status}).`));
+                    return;
+                }
+                if (!settled)
+                    succeed(parsed);
+            });
+            res.on('error', (error) => fail(new RemotePeerError('network', error.message)));
+        });
+        req.setTimeout(attemptTimeoutMs, () => { req.destroy(); fail(new RemotePeerError('offline', 'The peer did not answer in time.')); });
+        req.on('error', (error) => fail(classifyFailure(error, identityError)));
+        if (payload !== undefined)
+            req.write(payload);
+        req.end();
+        // Both timers above are INACTIVITY timers, and an inactivity timer is not a deadline: a peer that
+        // keeps sending bytes — headers and a chunk now and then, on a response it never finishes — resets
+        // them forever, and the attempt would outlive the walk that asked for it. The caller waiting on the
+        // deadline (the desktop's status probe) gives up at its own budget and starts a second walk, which is
+        // the overlap the deadline exists to prevent, so the deadline is enforced here too, as wall clock.
+        if (deadlineAt !== undefined) {
+            const left = deadlineAt - Date.now();
+            const spent = () => { fail(new RemotePeerError('offline', `Reaching ${host} ran out of time.`)); req.destroy(); };
+            if (left <= 0)
+                spent();
+            else {
+                deadlineTimer = setTimeout(spent, left);
+                deadlineTimer.unref?.();
+            }
+        }
+    });
+    // Each validated address is tried in turn: reachability is a fact about an ADDRESS, so a
+    // dual-stack name whose v4 answer is unreachable falls through to its validated v6 answer (and
+    // the reverse). Identity, authorization, and peer refusals are facts about the MACHINE — another
+    // address would repeat them or paper over a certificate swap — so those end the attempt.
+    let lastError;
+    for (const address of addresses) {
+        signal?.throwIfAborted();
+        const attemptTimeoutMs = addressAttemptBudgetMs(deadlineAt, Date.now());
+        // A walk that would answer after its caller's own deadline answered nothing: that caller gave up
+        // and asked again, stacking a second walk on the first. So the deadline decides here, and the
+        // answer it produces is the same verdict an exhausted walk gives — the machine was not reached.
+        if (attemptTimeoutMs <= 0) {
+            lastError ??= new RemotePeerError('offline', `Reaching ${host} ran out of time.`);
+            break;
+        }
+        try {
+            return await send(address, attemptTimeoutMs);
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            const failure = error instanceof RemotePeerError ? error : new RemotePeerError('network', String(error));
+            if (failure.kind === 'offline' || failure.kind === 'network') {
+                lastError = failure;
+                continue;
+            }
+            throw failure;
+        }
+    }
+    throw lastError ?? new RemotePeerError('network', `Could not reach ${host}.`);
+}
+export function peerWhoami(target, hostOrder, deadlineAt, signal) {
+    return request(target, 'GET', '/api/whoami', undefined, hostOrder, deadlineAt, {}, signal);
+}
+export function peerProjects(target, hostOrder) {
+    return request(target, 'GET', '/api/projects', undefined, hostOrder);
+}
+export function peerRoots(target, hostOrder) {
+    return request(target, 'GET', '/api/roots', undefined, hostOrder);
+}
+/** Full-grant pairings only; the peer refuses anything weaker before any key is read. */
+export function peerProviderExport(target, hostOrder, deadlineAt, signal) {
+    return request(target, 'GET', '/api/providers/export', undefined, hostOrder, deadlineAt, {}, signal);
+}
+export function peerBrowse(target, rootId, rel, hostOrder) {
+    return request(target, 'GET', `/api/browse?root=${encodeURIComponent(rootId)}&rel=${encodeURIComponent(rel)}`, undefined, hostOrder);
+}
+export function peerOwnerRoots(target, hostOrder) {
+    return request(target, 'GET', '/api/owner/roots', undefined, hostOrder);
+}
+export function peerOwnerBrowse(target, path, hostOrder) {
+    return request(target, 'GET', `/api/owner/browse?path=${encodeURIComponent(path)}`, undefined, hostOrder);
+}
+export function peerOwnerAddProject(target, path, hostOrder) {
+    return request(target, 'POST', '/api/owner/projects', { path }, hostOrder);
+}
+/**
+ * Capture a peer's certificate and prove it matches the pairing code — before any secret is sent.
+ *
+ * No pin exists yet (that is what pairing establishes), so the handshake accepts any certificate;
+ * the trust decision is the fingerprint equality check against the code, done here with no
+ * credential in flight. Only after it passes does the redemption carry the invitation.
+ */
+export async function capturePeerCertificate(host, port, transport, expectedFingerprint) {
+    if (transport === 'http') {
+        // No TLS to pin under an explicit HTTP opt-in; the code's fingerprint is not verifiable and
+        // the transport warning is the pair's agreed state, not a surprise to re-derive per request.
+        const address = await resolvePeerAddress(host).catch((error) => { throw new InviteRejectedError(error.message); });
+        void address;
+        return { host, certPem: '' };
+    }
+    const addresses = await resolvePeerAddresses(host).catch((error) => { throw new InviteRejectedError(error.message); });
+    const captureFrom = async (address) => {
+        const socket = await new Promise((resolve, reject) => {
+            const connecting = tls.connect({
+                host: address.address,
+                port,
+                ...(isIP(host) ? {} : { servername: host }),
+                rejectUnauthorized: false,
+                checkServerIdentity: () => undefined,
+                timeout: REQUEST_TIMEOUT_MS,
+            });
+            connecting.once('secureConnect', () => resolve(connecting));
+            connecting.once('error', (error) => reject(new InviteRejectedError(`Could not reach ${host}:${port} over TLS. ${error.message}`)));
+            connecting.once('timeout', () => { connecting.destroy(); reject(new InviteRejectedError(`Connecting to ${host}:${port} timed out.`)); });
+        });
+        try {
+            const certificate = socket.getPeerCertificate(true);
+            const der = certificate?.raw;
+            if (!der)
+                throw new InviteRejectedError('The peer presented no certificate.');
+            const presented = fingerprintOf(Buffer.from(der));
+            if (presented !== expectedFingerprint) {
+                throw new InviteRejectedError('The machine behind that pairing code presented a different certificate. The code may be mistyped, stale, or intercepted — nothing was paired.');
+            }
+            return pemFromDer(Buffer.from(der));
+        }
+        finally {
+            socket.destroy();
+        }
+    };
+    // Same rule as `request`: an unreachable address falls through to the next validated one (a
+    // dual-stack name), while a different certificate is the machine's identity and ends the attempt.
+    let lastError;
+    for (const address of addresses) {
+        try {
+            return { host, certPem: await captureFrom(address) };
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            if (failure instanceof InviteRejectedError && /different certificate/i.test(failure.message))
+                throw failure;
+            lastError = failure;
+        }
+    }
+    throw lastError ?? new InviteRejectedError(`Could not reach ${host}:${port} over TLS.`);
+}
+/**
+ * Turn a pairing code into a persisted workspace: pin first, redeem second, in that order.
+ *
+ * Pinning before redemption is what keeps a mistyped or intercepted code from burning a valid
+ * invitation against the wrong machine; redemption then runs once, against the host we just
+ * proved is behind the fingerprint.
+ */
+export async function redeemPairingPlan(plan, options = {}) {
+    let lastError;
+    for (const host of plan.hosts) {
+        try {
+            const pinned = await capturePeerCertificate(host, plan.port, plan.transport, plan.fingerprint);
+            const target = { host, port: plan.port, transport: plan.transport, fingerprint: plan.fingerprint, ...(plan.transport === 'https' ? { certPem: pinned.certPem } : {}) };
+            const response = await request(target, 'POST', '/api/pair/redeem', { invite: plan.invite, label: options.label ?? osHostname() }, host);
+            return { ...response, grant: response.grant === 'full' && plan.transport === 'https' ? 'full' : 'browse', host, certPem: pinned.certPem };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // A refusal (expired/used code) is the same against every host; only reachability varies.
+            if (error instanceof RemotePeerError && (error.kind === 'rejected' || error.kind === 'identity' || error.kind === 'unauthorized'))
+                throw error;
+            if (error instanceof InviteRejectedError && /different certificate/i.test(error.message))
+                throw error;
+        }
+    }
+    throw lastError ?? new InviteRejectedError('None of the addresses in that pairing code could be reached.');
+}
+/** Generate the per-workspace local id; ids are namespaced `rw:<id>` in the desktop. */
+export function newWorkspaceIdForClient() {
+    return `ws-${randomBytes(6).toString('hex')}`;
+}
+/**
+ * The largest a relayed call's answer may be — the host's own large-method bound. A local window
+ * displays multi-megabyte journal tails and diffs; the browse client's 2 MiB default would refuse
+ * exactly the payloads the full surface exists to carry.
+ */
+const MAX_ENGINE_RESPONSE_BYTES = 12 * 1024 * 1024;
+/** One relayed engine request against a host. The relay answers 200 with a result or an error. */
+export function peerEngineRequest(target, call, hostOrder, deadlineAt) {
+    return request(target, 'POST', '/api/engine/request', call, hostOrder, deadlineAt, { maxResponseBytes: MAX_ENGINE_RESPONSE_BYTES });
+}
+/** How long a quiet stream may sit before it is presumed dead; heartbeats arrive well inside it. */
+const EVENTS_INACTIVITY_MS = 45_000;
+/**
+ * The engine event stream: a server-sent-events GET over the same pinned connection every other
+ * peer call uses, delivered frame by frame for as long as the link lives.
+ *
+ * The promise RESOLVES when the stream ends — end of stream is a fact the caller retries on, not an
+ * exception. Only the machine-level verdicts (unauthorized, identity, rejected) reject, because
+ * those are the ones a retry would repeat forever.
+ */
+export function peerEngineEvents(target, host, connectionId, viewerWorkspaceId, onEvent, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let req;
+        let inactivity;
+        const armInactivity = () => {
+            clearTimeout(inactivity);
+            inactivity = setTimeout(() => { req?.destroy(new RemotePeerError('network', 'The event stream went quiet.')); }, EVENTS_INACTIVITY_MS);
+            inactivity.unref?.();
+        };
+        const cleanup = () => {
+            clearTimeout(inactivity);
+            signal.removeEventListener('abort', onAbort);
+            req?.destroy();
+        };
+        const finish = (outcome) => { if (!settled) {
+            settled = true;
+            cleanup();
+            resolve(outcome);
+        } };
+        const fail = (error) => { if (!settled) {
+            settled = true;
+            cleanup();
+            reject(error);
+        } };
+        function onAbort() {
+            finish({ kind: 'ended' });
+        }
+        signal.addEventListener('abort', onAbort);
+        void (async () => {
+            let addresses;
+            try {
+                addresses = await resolvePeerAddresses(host);
+            }
+            catch (error) {
+                fail(new RemotePeerError('offline', `Could not resolve ${host}: ${error.message}`));
+                return;
+            }
+            const certPem = target.certPem;
+            if (target.transport === 'https' && !certPem) {
+                fail(new RemotePeerError('network', 'No pinned certificate for this workspace — it must be re-paired.'));
+                return;
+            }
+            const query = `?connectionId=${encodeURIComponent(connectionId)}${viewerWorkspaceId !== undefined ? `&viewerWorkspaceId=${encodeURIComponent(viewerWorkspaceId)}` : ''}`;
+            let lastReachability;
+            for (const address of addresses) {
+                if (settled || signal.aborted)
+                    return;
+                const outcome = await new Promise(perAttempt => {
+                    let identityError;
+                    const options = {
+                        host: address.address,
+                        port: target.port,
+                        method: 'GET',
+                        path: `/api/engine/events${query}`,
+                        // Omitted on https: an agent would own socket creation and bypass the fingerprint gate.
+                        ...(target.transport === 'https' ? {} : { agent: false }),
+                        headers: {
+                            ...(target.token ? { authorization: `Bearer ${target.token}` } : {}),
+                            accept: 'text/event-stream',
+                            host: `${target.host}:${target.port}`,
+                        },
+                        timeout: REQUEST_TIMEOUT_MS,
+                    };
+                    if (target.transport === 'https' && certPem) {
+                        const tlsOptions = {
+                            host: address.address,
+                            port: target.port,
+                            ...(isIP(host) ? {} : { servername: host }),
+                            ca: [certPem],
+                            rejectUnauthorized: true,
+                            // Identity is the fingerprint gate below; the certificate's names are decorative.
+                            checkServerIdentity: () => undefined,
+                            timeout: REQUEST_TIMEOUT_MS,
+                        };
+                        Object.assign(options, tlsOptions);
+                        options.createConnection = (_connectOptions, onCreated) => {
+                            const socket = tls.connect(tlsOptions);
+                            let gated = false;
+                            socket.once('secureConnect', () => {
+                                if (gated)
+                                    return;
+                                gated = true;
+                                const der = socket.getPeerCertificate(true)?.raw;
+                                if (!der) {
+                                    identityError = new RemotePeerError('identity', 'The peer presented no certificate.');
+                                    socket.destroy();
+                                    onCreated(identityError);
+                                    return;
+                                }
+                                if (fingerprintOf(Buffer.from(der)) !== target.fingerprint) {
+                                    identityError = new RemotePeerError('identity', 'The peer presented a different certificate than the one you paired. Re-pairing is required.');
+                                    socket.destroy();
+                                    onCreated(identityError);
+                                    return;
+                                }
+                                // The handshake timeout does not govern the stream: heartbeats are scheduled at the
+                                // same interval this timeout would fire at, so a quiet stream could be destroyed
+                                // between them. Liveness is the 45-second inactivity timer's to prove.
+                                socket.setTimeout(0);
+                                onCreated(null, socket);
+                            });
+                            socket.once('error', (error) => {
+                                if (gated)
+                                    return;
+                                gated = true;
+                                onCreated(error);
+                            });
+                            socket.on('timeout', () => {
+                                socket.destroy();
+                                if (!gated) {
+                                    gated = true;
+                                    onCreated(new RemotePeerError('offline', `Connecting to ${host}:${target.port} timed out.`));
+                                }
+                            });
+                            // Nothing is returned: delivering the socket solely through `onCreated` is what keeps
+                            // the request bytes unwritten until the fingerprint has been checked.
+                        };
+                    }
+                    const attempt = (target.transport === 'https' ? httpsRequest : httpRequest)(options, res => {
+                        const status = res.statusCode ?? 0;
+                        if (status === 401) {
+                            res.resume();
+                            perAttempt(new RemotePeerError('unauthorized', 'This device is no longer authorized on that workspace.'));
+                            return;
+                        }
+                        if (status >= 500) {
+                            // A server-side failure (the listener's own handler catching, say, a config read that
+                            // failed) is a retryable condition, not a verdict about the pairing: the link's retry
+                            // loop reconnects, where a 4xx below still ends it as unrecoverable.
+                            res.resume();
+                            perAttempt(new RemotePeerError('network', `The peer's event stream failed (${status}).`));
+                            return;
+                        }
+                        if (status >= 400) {
+                            res.resume();
+                            perAttempt(new RemotePeerError('rejected', `The peer refused the event stream (${status}).`));
+                            return;
+                        }
+                        if (status >= 300) {
+                            res.resume();
+                            perAttempt(new RemotePeerError('network', 'The peer tried to redirect the event stream, which remote access does not follow.'));
+                            return;
+                        }
+                        // The stream is live: this attempt IS the link now, and the promise settles only when the
+                        // stream itself does.
+                        let buffer = '';
+                        armInactivity();
+                        res.setEncoding('utf8');
+                        res.on('data', (chunk) => {
+                            armInactivity();
+                            buffer += chunk;
+                            // Frames are separated by a blank line; a comment line (the heartbeat) is a frame too.
+                            let boundary = buffer.indexOf('\n\n');
+                            while (boundary >= 0) {
+                                const frame = buffer.slice(0, boundary);
+                                buffer = buffer.slice(boundary + 2);
+                                for (const line of frame.split('\n')) {
+                                    if (!line.startsWith('data: '))
+                                        continue;
+                                    try {
+                                        const parsed = JSON.parse(line.slice(6));
+                                        if (typeof parsed.engine === 'string' && typeof parsed.event === 'string') {
+                                            onEvent({ engine: parsed.engine, event: parsed.event, data: (parsed.data ?? {}) });
+                                        }
+                                    }
+                                    catch { /* A malformed frame is dropped; the stream's ordering continues. */ }
+                                }
+                                boundary = buffer.indexOf('\n\n');
+                            }
+                        });
+                        res.on('end', () => perAttempt({ kind: 'ended' }));
+                        res.on('error', (error) => perAttempt(new RemotePeerError('network', error.message)));
+                        res.on('close', () => perAttempt({ kind: 'ended' }));
+                    });
+                    req = attempt;
+                    attempt.on('error', (error) => perAttempt(classifyFailure(error, identityError)));
+                    // Headers are flushed on end: without it the socket completes its handshake and the
+                    // request is never sent, and the stream hangs unanswered on both ends.
+                    attempt.end();
+                });
+                if (outcome instanceof RemotePeerError) {
+                    if (outcome.kind === 'offline' || outcome.kind === 'network') {
+                        lastReachability = outcome;
+                        continue;
+                    }
+                    fail(outcome);
+                    return;
+                }
+                finish(outcome);
+                return;
+            }
+            fail(lastReachability ?? new RemotePeerError('network', `Could not reach ${host}.`));
+        })();
+    });
+}

package/dist/src/remote/command.d.ts

@@ -0,0 +1,4 @@
+export declare const REMOTE_USAGE = "Usage: andorra remote serve [--port N] [--insecure-http] [--rotate-cert]\n       andorra remote status\n       andorra remote code\n       andorra remote devices | andorra remote revoke <device-id>\n       andorra remote share <path> [--label name] | andorra remote unshare <share-id>\n       andorra remote pair <pairing-code> [--name nickname]\n       andorra remote workspaces | andorra remote unpair <workspace-id>\n       andorra remote rotate-cert";
+export declare function runRemoteCommand(args: string[], print: (line: string) => void, dependencies?: {
+    version?: string;
+}): Promise<number>;