@gtc6244/immediacy-daemon 0.2.2 → 0.2.4

package/dist/src/lan.js

@@ -0,0 +1,182 @@
+/**
+ * LAN direct transport (docs/WEBRTC_MIGRATION.md Phase 3).
+ *
+ * Priority-2 path: when a client and daemon share a network segment they talk
+ * directly over TCP — no Cloudflare, no relay, works with the router's WAN link
+ * unplugged. The daemon:
+ *   - advertises `_immediacy._tcp` over mDNS (TXT `rid=<rendezvous id>`) so a
+ *     client can discover it without any typed address;
+ *   - listens on TCP and, per connection, runs the §5.3 session handshake over
+ *     the frame `Mux` (tcp-transport.ts + transport.ts), then hands the caller a
+ *     `SecureChannel` for that peer.
+ *
+ * The handshake and frame codec are the SAME modules the loopback and (future)
+ * relay/WebRTC paths use — only the byte transport differs.
+ */
+import { createServer, connect as tcpConnect } from "node:net";
+import { Bonjour } from "bonjour-service";
+import { Mux } from "./transport.js";
+import { TcpTransport } from "./tcp-transport.js";
+import { Channel } from "./framing.js";
+import { acceptHandshake, startHandshake, } from "./session.js";
+/** bonjour "type" (it prepends `_` and appends `._tcp`) ⇒ `_immediacy._tcp`. */
+export const LAN_SERVICE_TYPE = "immediacy";
+/**
+ * Run the responder (daemon) side of the handshake over `mux`'s control channel:
+ * receive msg1, verify the device against `isPaired`, reply msg2, and resolve
+ * with the established `SecureChannel`. Rejects on an unknown/revoked device or a
+ * malformed/failed handshake.
+ */
+export function respondHandshakeOverMux(mux, opts, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("handshake timeout")), timeoutMs);
+        let done = false;
+        mux.onMessage((channelId, message) => {
+            if (done || channelId !== Channel.control)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                const msg1 = JSON.parse(message.toString("utf8"));
+                const { msg2, channel, devicePub, paired, label } = acceptHandshake(msg1, opts);
+                void mux.send(Channel.control, Buffer.from(JSON.stringify(msg2), "utf8"));
+                resolve({ channel, devicePub, paired, label });
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    });
+}
+/**
+ * Run the initiator (client) side over `mux`'s control channel: send msg1, wait
+ * for msg2, and resolve with the `SecureChannel`. Used by the LAN test and
+ * mirrored by the Flutter/macOS LAN clients.
+ */
+export function initiateHandshakeOverMux(mux, opts, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
+        const { msg1, finish } = startHandshake(opts);
+        const timer = setTimeout(() => reject(new Error("handshake timeout")), timeoutMs);
+        mux.onMessage((channelId, message) => {
+            if (channelId !== Channel.control)
+                return;
+            clearTimeout(timer);
+            try {
+                const msg2 = JSON.parse(message.toString("utf8"));
+                resolve(finish(msg2));
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        void mux.send(Channel.control, Buffer.from(JSON.stringify(msg1), "utf8"));
+    });
+}
+export class LanServer {
+    rendezvous;
+    server;
+    bonjour;
+    service;
+    constructor(rendezvous) {
+        this.rendezvous = rendezvous;
+    }
+    /** Called for each peer that completes the handshake over LAN. */
+    onSession;
+    /**
+     * Start the TCP listener and advertise it over mDNS. Returns the bound port.
+     * `advertise: false` skips mDNS (useful in tests / restricted networks).
+     */
+    async start(port = 0, opts) {
+        const server = createServer((socket) => this.onConnection(socket));
+        this.server = server;
+        const boundPort = await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, opts?.host, () => {
+                const addr = server.address();
+                resolve(typeof addr === "object" && addr ? addr.port : port);
+            });
+        });
+        if (opts?.advertise !== false)
+            this.advertise(boundPort);
+        return boundPort;
+    }
+    advertise(port) {
+        try {
+            this.bonjour = new Bonjour();
+            this.service = this.bonjour.publish({
+                name: `immediacy-${this.rendezvous.identity.rendezvousId().slice(0, 8)}`,
+                type: LAN_SERVICE_TYPE,
+                port,
+                txt: { rid: this.rendezvous.identity.rendezvousId() },
+            });
+        }
+        catch {
+            // mDNS can fail on locked-down networks; LAN still works if the client
+            // reaches the port another way. Best-effort.
+        }
+    }
+    onConnection(socket) {
+        const transport = new TcpTransport(socket);
+        const mux = new Mux(transport);
+        const pairing = this.rendezvous.pairing;
+        respondHandshakeOverMux(mux, {
+            daemonSignSecret: this.rendezvous.identity.signSecretKey(),
+            rendezvousId: this.rendezvous.identity.rendezvousId(),
+            isPaired: (dev) => this.rendezvous.devices.has(dev),
+            redeemCode: pairing ? (_dev, code) => pairing.consume(code) : undefined,
+        })
+            .then(async ({ channel, devicePub, paired, label }) => {
+            // A first-pairing handshake authorized via a valid code — record the
+            // device now (the code is already consumed) before serving the session.
+            if (paired)
+                await this.rendezvous.devices.add(devicePub, label ?? "device");
+            void this.rendezvous.devices.touch(devicePub).catch(() => { });
+            this.onSession?.({
+                mux,
+                channel,
+                devicePub,
+                close: () => transport.close(),
+                onClose: (cb) => transport.onClose(cb),
+            });
+        })
+            .catch(() => transport.close());
+    }
+    async stop() {
+        this.service?.stop?.();
+        this.bonjour?.destroy();
+        await new Promise((resolve) => {
+            if (!this.server)
+                return resolve();
+            this.server.close(() => resolve());
+        });
+    }
+}
+/**
+ * Browse the LAN for advertised daemons. Calls `onPeer` for each service that
+ * carries a rendezvous-id TXT record. Returns a stop function.
+ */
+export function browseLan(onPeer) {
+    const bonjour = new Bonjour();
+    const browser = bonjour.find({ type: LAN_SERVICE_TYPE }, (service) => {
+        const rid = service.txt?.rid;
+        const host = service.referer?.address ?? service.host;
+        if (rid && host) {
+            onPeer({ rendezvousId: rid, host, port: service.port, name: service.name });
+        }
+    });
+    return () => {
+        browser.stop();
+        bonjour.destroy();
+    };
+}
+/** Open a LAN TCP connection to `host:port` and wrap it in a `Mux`. */
+export function lanConnect(host, port) {
+    return new Promise((resolve, reject) => {
+        const socket = tcpConnect({ host, port }, () => {
+            const transport = new TcpTransport(socket);
+            resolve({ mux: new Mux(transport), close: () => transport.close() });
+        });
+        socket.once("error", reject);
+    });
+}
+//# sourceMappingURL=lan.js.map

package/dist/src/lan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lan.js","sourceRoot":"","sources":["../../src/lan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAA4B,OAAO,IAAI,UAAU,EAAE,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,OAAO,EAA8B,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,eAAe,EACf,cAAc,GAKf,MAAM,cAAc,CAAC;AAItB,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAa5C;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAAQ,EACR,IAMC,EACD,SAAS,GAAG,MAAM;IAElB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAClF,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,GAAG,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE;YACnC,IAAI,IAAI,IAAI,SAAS,KAAK,OAAO,CAAC,OAAO;gBAAE,OAAO;YAClD,IAAI,GAAG,IAAI,CAAC;YACZ,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAkB,CAAC;gBACnE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAChF,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;gBAC1E,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YACjD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,GAAQ,EACR,IAAmB,EACnB,SAAS,GAAG,MAAM;IAElB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAClF,GAAG,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE;YACnC,IAAI,SAAS,KAAK,OAAO,CAAC,OAAO;gBAAE,OAAO;YAC1C,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAkB,CAAC;gBACnE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACxB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC,CAAC,CAAC;QACH,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC;AAYD,MAAM,OAAO,SAAS;IAKS;IAJrB,MAAM,CAAU;IAChB,OAAO,CAAW;IAClB,OAAO,CAAW;IAE1B,YAA6B,UAA0B;QAA1B,eAAU,GAAV,UAAU,CAAgB;IAAG,CAAC;IAE3D,kEAAkE;IAClE,SAAS,CAAiC;IAE1C;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,IAA6C;QACjE,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,MAAM,SAAS,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC9D,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;gBACnC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC9B,OAAO,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/D,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,EAAE,SAAS,KAAK,KAAK;YAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,SAAS,CAAC,IAAY;QAC5B,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;gBAClC,IAAI,EAAE,aAAa,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;gBACxE,IAAI,EAAE,gBAAgB;gBACtB,IAAI;gBACJ,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE;aACtD,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,6CAA6C;QAC/C,CAAC;IACH,CAAC;IAEO,YAAY,CAAC,MAAc;QACjC,MAAM,SAAS,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QACxC,uBAAuB,CAAC,GAAG,EAAE;YAC3B,gBAAgB,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,aAAa,EAAE;YAC1D,YAAY,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE;YACrD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YACnD,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SACxE,CAAC;aACC,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE;YACpD,qEAAqE;YACrE,wEAAwE;YACxE,IAAI,MAAM;gBAAE,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,IAAI,QAAQ,CAAC,CAAC;YAC5E,KAAK,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC9D,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,GAAG;gBACH,OAAO;gBACP,SAAS;gBACT,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE;gBAC9B,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;aACvC,CAAC,CAAC;QACL,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,IAAI,CAAC,IAAI,CAAC,MAAM;gBAAE,OAAO,OAAO,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAUD;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,MAA+B;IACvD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAY,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE;QAC5E,MAAM,GAAG,GAAI,OAAO,CAAC,GAA0C,EAAE,GAAG,CAAC;QACrE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;QACtD,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;YAChB,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE;QACV,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAY;IACnD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE;YAC7C,MAAM,SAAS,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,OAAO,CAAC,EAAE,GAAG,EAAE,IAAI,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACvE,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/pairing.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pairing — single-use pairing codes + the QR payload a client scans (§3.4).
+ *
+ * A pairing code is a 128-bit secret, **in-memory only**, with a 60 s TTL and
+ * single use: it is discarded the moment it is consumed or expires. It gates a
+ * *new* device joining the daemon's device table; once paired, a device
+ * reconnects with its own key and never needs a code again.
+ *
+ * The QR payload is small JSON: `{ v, r, k, c, s }` — protocol version,
+ * rendezvous id, daemon Ed25519 pubkey (base64), the pairing code (base64), and
+ * the signal-server URL. The client scans it, dials the rendezvous, presents the
+ * code + a fresh device key, and proceeds straight into the session handshake.
+ */
+/** Default signal server (§8: ownership/deploy pipeline still to be confirmed). */
+export declare const DEFAULT_SIGNAL_URL = "wss://signal.ixiomsoftware.com";
+/** Pairing-code lifetime. Short enough that a leaked QR photo goes stale fast. */
+export declare const PAIRING_CODE_TTL_MS = 60000;
+/** The QR payload a daemon renders and a client scans. Keep it tiny. */
+export interface PairingPayload {
+    v: 1;
+    r: string;
+    k: string;
+    c: string;
+    s: string;
+}
+/**
+ * Issues and validates single-use pairing codes. All state is in memory, so a
+ * daemon restart invalidates every outstanding code — intentional.
+ */
+export declare class PairingCodes {
+    private pending;
+    private readonly ttlMs;
+    /** Injectable clock so tests don't sleep. */
+    private readonly now;
+    constructor(opts?: {
+        ttlMs?: number;
+        now?: () => number;
+    });
+    /** Mint a fresh 128-bit code, remember it until its TTL, and return it. */
+    issue(): {
+        code: string;
+        expiresAt: number;
+    };
+    /**
+     * Consume a code. Returns true exactly once for a live code, then discards it
+     * (single use). Returns false for an unknown, already-used, or expired code.
+     * Comparison is constant-time to avoid leaking which prefix matched.
+     */
+    consume(code: string): boolean;
+    /** Number of live (unexpired) codes — for tests/telemetry. */
+    size(): number;
+    /** Drop expired codes so they never accumulate. */
+    private sweep;
+}
+/** Build the QR payload object a client scans. */
+export declare function buildPairingPayload(opts: {
+    rendezvousId: string;
+    daemonPublicKeyB64: string;
+    code: string;
+    signalUrl?: string;
+}): PairingPayload;
+/** Serialize a pairing payload to the compact JSON string that goes in the QR. */
+export declare function encodePairingPayload(payload: PairingPayload): string;
+/**
+ * Render a pairing payload as a terminal QR code, with a plaintext fallback so
+ * the user can still pair on a terminal that can't draw the QR (or via copy /
+ * paste). Resolves to the string that was printed's source payload.
+ */
+export declare function renderPairingQr(payload: PairingPayload, out?: (line: string) => void): Promise<string>;

package/dist/src/pairing.js

@@ -0,0 +1,125 @@
+/**
+ * Pairing — single-use pairing codes + the QR payload a client scans (§3.4).
+ *
+ * A pairing code is a 128-bit secret, **in-memory only**, with a 60 s TTL and
+ * single use: it is discarded the moment it is consumed or expires. It gates a
+ * *new* device joining the daemon's device table; once paired, a device
+ * reconnects with its own key and never needs a code again.
+ *
+ * The QR payload is small JSON: `{ v, r, k, c, s }` — protocol version,
+ * rendezvous id, daemon Ed25519 pubkey (base64), the pairing code (base64), and
+ * the signal-server URL. The client scans it, dials the rendezvous, presents the
+ * code + a fresh device key, and proceeds straight into the session handshake.
+ */
+import sodium from "sodium-native";
+import qrcode from "qrcode-terminal";
+/** Default signal server (§8: ownership/deploy pipeline still to be confirmed). */
+export const DEFAULT_SIGNAL_URL = "wss://signal.ixiomsoftware.com";
+/** Pairing-code lifetime. Short enough that a leaked QR photo goes stale fast. */
+export const PAIRING_CODE_TTL_MS = 60_000;
+/** Pairing-code entropy: 128 bits, matching the rendezvous id. */
+const PAIRING_CODE_BYTES = 16;
+/**
+ * Issues and validates single-use pairing codes. All state is in memory, so a
+ * daemon restart invalidates every outstanding code — intentional.
+ */
+export class PairingCodes {
+    pending = new Map();
+    ttlMs;
+    /** Injectable clock so tests don't sleep. */
+    now;
+    constructor(opts) {
+        this.ttlMs = opts?.ttlMs ?? PAIRING_CODE_TTL_MS;
+        this.now = opts?.now ?? Date.now;
+    }
+    /** Mint a fresh 128-bit code, remember it until its TTL, and return it. */
+    issue() {
+        this.sweep();
+        const raw = Buffer.alloc(PAIRING_CODE_BYTES);
+        sodium.randombytes_buf(raw);
+        const code = raw.toString("base64");
+        const expiresAt = this.now() + this.ttlMs;
+        this.pending.set(code, { code, expiresAt });
+        return { code, expiresAt };
+    }
+    /**
+     * Consume a code. Returns true exactly once for a live code, then discards it
+     * (single use). Returns false for an unknown, already-used, or expired code.
+     * Comparison is constant-time to avoid leaking which prefix matched.
+     */
+    consume(code) {
+        this.sweep();
+        if (typeof code !== "string")
+            return false;
+        let candidate;
+        try {
+            candidate = Buffer.from(code, "base64");
+        }
+        catch {
+            return false;
+        }
+        if (candidate.length !== PAIRING_CODE_BYTES)
+            return false;
+        for (const [key, entry] of this.pending) {
+            const known = Buffer.from(entry.code, "base64");
+            if (known.length === candidate.length && sodium.sodium_memcmp(known, candidate)) {
+                this.pending.delete(key); // single use — gone even on the winning path
+                return entry.expiresAt > this.now();
+            }
+        }
+        return false;
+    }
+    /** Number of live (unexpired) codes — for tests/telemetry. */
+    size() {
+        this.sweep();
+        return this.pending.size;
+    }
+    /** Drop expired codes so they never accumulate. */
+    sweep() {
+        const t = this.now();
+        for (const [key, entry] of this.pending) {
+            if (entry.expiresAt <= t)
+                this.pending.delete(key);
+        }
+    }
+}
+/** Build the QR payload object a client scans. */
+export function buildPairingPayload(opts) {
+    return {
+        v: 1,
+        r: opts.rendezvousId,
+        k: opts.daemonPublicKeyB64,
+        c: opts.code,
+        s: opts.signalUrl ?? DEFAULT_SIGNAL_URL,
+    };
+}
+/** Serialize a pairing payload to the compact JSON string that goes in the QR. */
+export function encodePairingPayload(payload) {
+    return JSON.stringify(payload);
+}
+/**
+ * Render a pairing payload as a terminal QR code, with a plaintext fallback so
+ * the user can still pair on a terminal that can't draw the QR (or via copy /
+ * paste). Resolves to the string that was printed's source payload.
+ */
+export async function renderPairingQr(payload, out = (l) => console.log(l)) {
+    const encoded = encodePairingPayload(payload);
+    try {
+        const art = await new Promise((resolve, reject) => {
+            try {
+                qrcode.generate(encoded, { small: true }, (o) => resolve(o));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        out(art);
+    }
+    catch {
+        // Fallback: some terminals/CI can't render — print the payload to scan/paste.
+        out("[pairing] QR unavailable — paste this into the app to pair:");
+    }
+    out(encoded);
+    return encoded;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/src/pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.js","sourceRoot":"","sources":["../../src/pairing.ts"],"names":[],"mappings":"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"}

package/dist/src/protocol.d.ts

@@ -25,9 +25,9 @@ export interface Envelope<T extends MessageType = MessageType> {
     payload: PayloadFor<T>;
 }
 /** Client → daemon. */
-export type ClientMessageType = "project.list" | "project.create" | "project.delete" | "project.rename" | "project.reorder" | "project.branches" | "project.pulls" | "project.issues" | "issue.create" | "workspace.list" | "workspace.create" | "workspace.delete" | "workspace.archive" | "workspace.rename" | "workspace.action" | "workspace.setModel" | "delete.batch" | "prompt.send" | "agent.stop" | "permission.respond" | "question.respond" | "allowlist.list" | "allowlist.revoke" | "allowlist.clear" | "terminal.input" | "terminal.resize" | "terminal.snapshot" | "forward.list" | "forward.open" | "forward.data" | "forward.close" | "git.status" | "git.commit" | "git.push" | "git.resolve" | "git.merge" | "pr.create" | "pr.merge" | "workspace.open" | "diff.get" | "tree.get" | "file.get" | "file.set" | "media.get" | "chat.history" | "github.status" | "github.repos" | "models.list" | "job.list" | "job.create" | "job.update" | "job.delete" | "job.run" | "job.runs" | "settings.get" | "settings.set" | "config.set" | "log.tail" | "client.hello" | "hello" | "pair.info" | "daemon.get" | "daemon.rename" | "daemon.update.check" | "daemon.update" | "push.register" | "push.unregister" | "ping" | "echo";
+export type ClientMessageType = "project.list" | "project.create" | "project.delete" | "project.rename" | "project.reorder" | "project.branches" | "project.pulls" | "project.issues" | "issue.create" | "workspace.list" | "workspace.create" | "workspace.delete" | "workspace.archive" | "workspace.rename" | "workspace.action" | "workspace.setModel" | "delete.batch" | "prompt.send" | "agent.stop" | "permission.respond" | "question.respond" | "allowlist.list" | "allowlist.revoke" | "allowlist.clear" | "terminal.input" | "terminal.resize" | "terminal.snapshot" | "forward.list" | "forward.open" | "forward.data" | "forward.close" | "git.status" | "git.commit" | "git.push" | "git.resolve" | "git.merge" | "pr.create" | "pr.merge" | "workspace.open" | "diff.get" | "tree.get" | "file.get" | "file.set" | "media.get" | "chat.history" | "github.status" | "github.repos" | "models.list" | "job.list" | "job.create" | "job.update" | "job.delete" | "job.run" | "job.runs" | "settings.get" | "settings.set" | "config.set" | "log.tail" | "client.hello" | "pair.begin" | "session.begin" | "pairing.issue" | "daemon.get" | "daemon.rename" | "daemon.update.check" | "daemon.update" | "push.register" | "push.unregister" | "ping" | "echo";
 /** Daemon → client. */
-export type DaemonMessageType = "project.list.result" | "project.branches.result" | "project.pulls.result" | "project.issues.result" | "workspace.list.result" | "workspace.created" | "workspace.renamed" | "delete.batch.result" | "event.assistant_message" | "event.assistant_image" | "event.tool_use" | "event.permission_request" | "event.permission_resolved" | "event.ask_question" | "event.question_resolved" | "event.session" | "event.agent_done" | "event.session_limit" | "event.system_notice" | "event.auth_failure" | "terminal.data" | "terminal.snapshot.result" | "forward.available" | "git.status.result" | "git.result" | "diff.result" | "tree.result" | "file.result" | "file.saved" | "media.result" | "chat.history.result" | "github.status.result" | "github.repos.result" | "models.list.result" | "job.list.result" | "job.runs.result" | "event.job_run" | "settings.result" | "allowlist.result" | "log.tail.result" | "log.event" | "hello.ok" | "pair.info.result" | "daemon.info" | "daemon.update.result" | "pong" | "error" | "echo.result";
+export type DaemonMessageType = "project.list.result" | "project.branches.result" | "project.pulls.result" | "project.issues.result" | "workspace.list.result" | "workspace.created" | "workspace.renamed" | "delete.batch.result" | "event.assistant_message" | "event.assistant_image" | "event.tool_use" | "event.permission_request" | "event.permission_resolved" | "event.ask_question" | "event.question_resolved" | "event.session" | "event.agent_done" | "event.session_limit" | "event.system_notice" | "event.auth_failure" | "terminal.data" | "terminal.snapshot.result" | "forward.available" | "git.status.result" | "git.result" | "diff.result" | "tree.result" | "file.result" | "file.saved" | "media.result" | "chat.history.result" | "github.status.result" | "github.repos.result" | "models.list.result" | "job.list.result" | "job.runs.result" | "event.job_run" | "settings.result" | "allowlist.result" | "log.tail.result" | "log.event" | "pair.begin.result" | "session.begin.result" | "pairing.issue.result" | "daemon.info" | "daemon.update.result" | "pong" | "error" | "echo.result";
 export type MessageType = ClientMessageType | DaemonMessageType;
 export interface ProjectListPayload {
 }
@@ -1154,26 +1154,78 @@ export interface GithubReposResultPayload {
 }
 export interface PongPayload {
 }
-/** Client → daemon: announce this device's public key to establish E2E. */
-export interface HelloPayload {
-    /** base64 of the device's X25519 public key. */
-    pub: string;
+export type { HandshakeMsg1, HandshakeMsg2 } from "./session.js";
+import type { HandshakeMsg1, HandshakeMsg2 } from "./session.js";
+/**
+ * Client → daemon: redeem a single-use pairing code (from the scanned QR) and
+ * register this device's long-term Ed25519 public key. Sent cleartext (the code
+ * is the pairing secret); the daemon adds the device to its table and replies
+ * with its pinned identity so the client can persist a `KnownDaemon`.
+ */
+export interface PairBeginPayload {
+    /** The single-use pairing code from the QR (`c` field), base64. */
+    code: string;
+    /** This device's long-term Ed25519 public key, base64. */
+    devicePub: string;
     /** Optional human label for the paired-devices record. */
     label?: string;
 }
-/** Daemon → client: handshake ack carrying the daemon's public key. */
-export interface HelloOkPayload {
-    /** base64 of the daemon's public key (empty when E2E is off). */
-    pub: string;
-    /** Whether payloads on this socket are now sealed. */
-    sealed: boolean;
+/** Daemon → client: the outcome of `pair.begin`. */
+export interface PairBeginResultPayload {
+    /** True iff the code redeemed and the device was registered. */
+    ok: boolean;
+    /** The daemon's rendezvous id (base32) — present on success. */
+    rendezvousId?: string;
+    /** The daemon's long-term Ed25519 public key, base64 — present on success. */
+    daemonPub?: string;
+    /** The daemon's human name at pair time (for the client's `KnownDaemon`). */
+    label?: string;
+    /** Machine-readable failure reason (e.g. "bad_code", "bad_key") on !ok. */
+    error?: string;
 }
-/** Client → daemon: ask for the daemon's public key (to build a pairing QR). */
-export interface PairInfoPayload {
+/**
+ * Client → daemon: mint a fresh pairing payload to show as a QR (`pairing.issue`).
+ * No arguments — the daemon already knows its own rendezvous id, public key, and
+ * signal URL. Must arrive on an authenticated (sealed) session; the reply carries
+ * a live single-use code.
+ */
+export interface PairingIssuePayload {
 }
-/** Daemon → client: the daemon's public key, or empty when E2E is off. */
-export interface PairInfoResultPayload {
-    pub: string;
+/** Daemon → client: the outcome of `pairing.issue`. */
+export interface PairingIssueResultPayload {
+    /** True iff a fresh payload was minted (requester was authenticated). */
+    ok: boolean;
+    /**
+     * The pairing payload to encode as a QR, on success. Same `{v,r,k,c,s}` shape a
+     * scanning device redeems via `pair.begin`. `c` is a single-use code with a 60s
+     * TTL, so the client should re-request before it lapses.
+     */
+    payload?: {
+        v: 1;
+        r: string;
+        k: string;
+        c: string;
+        s: string;
+    };
+    /** Machine-readable failure reason (e.g. "not_authenticated", "not_supported"). */
+    error?: string;
+}
+/**
+ * Client → daemon: begin the §5.3 session handshake. Carries the signed
+ * ephemeral-key message (msg1). Sent cleartext; the reply (msg2) is also
+ * cleartext, after which BOTH sides seal every frame with the derived keys.
+ */
+export interface SessionBeginPayload {
+    msg1: HandshakeMsg1;
+}
+/** Daemon → client: the handshake reply, or a failure. */
+export interface SessionBeginResultPayload {
+    /** True iff the daemon verified the device and produced its reply. */
+    ok: boolean;
+    /** The daemon's signed ephemeral-key message (msg2) — present on success. */
+    msg2?: HandshakeMsg2;
+    /** Machine-readable failure reason (e.g. "unknown_device", "bad_signature"). */
+    error?: string;
 }
 /** Client → daemon: ask for this daemon's identity (name, id, host, version). */
 export interface DaemonGetPayload {
@@ -1475,8 +1527,9 @@ export interface PayloadMap {
     "config.set": ConfigSetPayload;
     "log.tail": LogTailPayload;
     "client.hello": ClientHelloPayload;
-    hello: HelloPayload;
-    "pair.info": PairInfoPayload;
+    "pair.begin": PairBeginPayload;
+    "pairing.issue": PairingIssuePayload;
+    "session.begin": SessionBeginPayload;
     "daemon.get": DaemonGetPayload;
     "daemon.rename": DaemonRenamePayload;
     "daemon.update.check": DaemonUpdateCheckPayload;
@@ -1526,8 +1579,9 @@ export interface PayloadMap {
     "allowlist.result": AllowlistResultPayload;
     "log.tail.result": LogTailResultPayload;
     "log.event": LogEventPayload;
-    "hello.ok": HelloOkPayload;
-    "pair.info.result": PairInfoResultPayload;
+    "pair.begin.result": PairBeginResultPayload;
+    "pairing.issue.result": PairingIssueResultPayload;
+    "session.begin.result": SessionBeginResultPayload;
     "daemon.info": DaemonInfoPayload;
     "daemon.update.result": DaemonUpdateResultPayload;
     pong: PongPayload;

package/dist/src/relay-transport.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Relay transport (daemon side) — docs/WEBRTC_MIGRATION.md Phase 4.
+ *
+ * The daemon keeps ONE persistent WebSocket to its Durable Object (`/daemon/
+ * <rid>`) whenever it's running. The DO multiplexes every client over that single
+ * socket, tagged by client id. `RelayDaemon` demuxes: each client id gets its own
+ * `Transport` (a `SubTransport` over the shared ws), which feeds a `Mux` + the
+ * §5.3 responder handshake — exactly the same session stack the loopback and LAN
+ * paths use. The relay only ever sees sealed frames.
+ */
+import { Mux } from "./transport.js";
+import type { SecureChannel } from "./session.js";
+import type { RendezvousIdentity } from "./rendezvous.js";
+import type { DeviceTable } from "./devices.js";
+export interface RelaySession {
+    clientId: number;
+    mux: Mux;
+    channel: SecureChannel;
+    devicePub: string;
+    close(): void;
+    /** Register a callback for when this client's relay socket drops. */
+    onClose(cb: () => void): void;
+}
+export interface RelayDaemonDeps {
+    identity: RendezvousIdentity;
+    devices: DeviceTable;
+    /**
+     * Single-use pairing codes. When present, a brand-new device can pair inline
+     * during the handshake (msg1 carries a code). Omit to disable relay pairing.
+     */
+    pairing?: {
+        consume(code: string): boolean;
+    };
+}
+/**
+ * Maintains the daemon's persistent relay socket and per-client sessions. Call
+ * `connect()` to dial; it reconnects with backoff on drop so the daemon is
+ * reachable over the relay whenever it's running (the Phase-4 acceptance:
+ * "daemon restart auto-reconnects with no user action").
+ */
+export declare class RelayDaemon {
+    private readonly deps;
+    private readonly relayUrl;
+    private readonly opts?;
+    private ws;
+    private readonly subs;
+    private closed;
+    private attempt;
+    private reconnectTimer;
+    /** Called for each client that completes the handshake over the relay. */
+    onSession?: (session: RelaySession) => void;
+    constructor(deps: RelayDaemonDeps, relayUrl: string, opts?: {
+        license?: string;
+    } | undefined);
+    /** The daemon endpoint for this daemon's rendezvous id. */
+    private url;
+    connect(): void;
+    private onMessage;
+    private openClient;
+    private onClose;
+    close(): void;
+}