@decentnetwork/peer 0.1.17 → 0.1.18

package/dist/ice-lite.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Minimal ICE-lite agent: gather candidates, exchange via an external
+ * signaling channel (Carrier friend-message), connectivity-check each
+ * (local, remote) pair, pick the highest-priority working pair as the
+ * data path, keepalive, re-run on failure.
+ *
+ * This is NOT full ICE:
+ *  - No controlling/controlled negotiation (both sides probe equally).
+ *  - No aggressive nomination, no Trickle phases.
+ *  - No TCP candidates.
+ *
+ * Just enough to upgrade a Carrier friend session from "tcp-relay only"
+ * to "UDP-direct or TURN-relayed", whichever works.
+ */
+import { type Socket as DgramSocket } from "dgram";
+import { AddressValue } from "./stun.js";
+export type CandidateKind = "host" | "srflx" | "relay";
+export interface Candidate {
+    kind: CandidateKind;
+    address: string;
+    port: number;
+    /** Higher beats lower. Convention: host=10000, srflx=5000, relay=1000. */
+    priority: number;
+}
+export interface CandidateOffer {
+    candidates: Candidate[];
+    ufrag: string;
+    password: string;
+    generation: number;
+}
+interface BootnodeRef {
+    host: string;
+    publicKey: Uint8Array;
+}
+interface SignalingHandle {
+    send(offer: CandidateOffer): void;
+    onOffer(cb: (offer: CandidateOffer) => void): void;
+}
+export interface IceAgentOpts {
+    /**
+     * The peer's UDP socket. ICE shares it so that once a pair wins, the
+     * caller can use the same socket for data traffic — bypassing any
+     * extra demultiplexing.
+     */
+    sock: DgramSocket;
+    /** Bootnodes we can use as STUN servers. ≥2 → can detect symmetric NAT. */
+    stunBootnodes: BootnodeRef[];
+    /** Bootnodes we can use as TURN servers (usually the same list). */
+    turnBootnodes: BootnodeRef[];
+    /** Our Carrier identity, used for TURN credential derivation. */
+    ourUserid: string;
+    ourSecretKey: Uint8Array;
+    /** How we tell the remote peer our candidates. */
+    signaling: SignalingHandle;
+    /** Called when ICE picks a winning pair. May be called again on re-run. */
+    onSelected: (pair: {
+        local: Candidate;
+        remote: Candidate;
+    }) => void;
+    /** Called for raw data received via the TURN relay (DATA-INDICATION). */
+    onRelayedData?: (peer: AddressValue, data: Uint8Array) => void;
+}
+export declare class IceLiteAgent {
+    #private;
+    constructor(opts: IceAgentOpts);
+    /** Gather local candidates and ship them via signaling. Idempotent-ish. */
+    start(): Promise<void>;
+    close(): void;
+}
+export {};

package/dist/ice-lite.js

@@ -0,0 +1,306 @@
+/**
+ * Minimal ICE-lite agent: gather candidates, exchange via an external
+ * signaling channel (Carrier friend-message), connectivity-check each
+ * (local, remote) pair, pick the highest-priority working pair as the
+ * data path, keepalive, re-run on failure.
+ *
+ * This is NOT full ICE:
+ *  - No controlling/controlled negotiation (both sides probe equally).
+ *  - No aggressive nomination, no Trickle phases.
+ *  - No TCP candidates.
+ *
+ * Just enough to upgrade a Carrier friend session from "tcp-relay only"
+ * to "UDP-direct or TURN-relayed", whichever works.
+ */
+import { networkInterfaces } from "os";
+import { buildBindingRequest, decodeStun, decodeXorMappedAddress, encodeStun, encodeXorMappedAddress, findAttr, newTransactionId, shortTermIntegrityKey, STUN_ATTR_USERNAME, STUN_ATTR_XOR_MAPPED_ADDRESS, STUN_BINDING_REQUEST, STUN_BINDING_SUCCESS } from "./stun.js";
+import { TurnClient } from "./turn.js";
+import { deriveCarrierTurnCreds } from "./turn-creds.js";
+import { randomBytes } from "./utils/bytes.js";
+const HOST_PRIORITY = 10_000;
+const SRFLX_PRIORITY = 5_000;
+const RELAY_PRIORITY = 1_000;
+const CHECK_INTERVAL_MS = 200;
+const PING_TIMEOUT_MS = 3_000;
+const KEEPALIVE_MS = 5_000;
+const LOST_THRESHOLD = 3;
+export class IceLiteAgent {
+    #opts;
+    #ufrag = base64url(randomBytes(6));
+    #password = base64url(randomBytes(16));
+    #generation = 0;
+    #localCandidates = [];
+    #remoteOffer;
+    #turnByBootnode = new Map();
+    #pairs = [];
+    #selected;
+    #keepaliveTimer;
+    #pendingChecks = new Map(); // txnHex -> resolve
+    #closed = false;
+    constructor(opts) {
+        this.#opts = opts;
+        this.#opts.sock.on("message", this.#onSocketMessage);
+        this.#opts.signaling.onOffer((offer) => this.#onRemoteOffer(offer));
+    }
+    /** Gather local candidates and ship them via signaling. Idempotent-ish. */
+    async start() {
+        this.#generation++;
+        this.#localCandidates = [];
+        // 1. HOST candidates — every non-loopback IPv4 we own
+        const localPort = this.#opts.sock.address().port;
+        for (const iface of Object.values(networkInterfaces())) {
+            if (!iface)
+                continue;
+            for (const addr of iface) {
+                if (addr.family === "IPv4" && !addr.internal) {
+                    this.#localCandidates.push({
+                        kind: "host",
+                        address: addr.address,
+                        port: localPort,
+                        priority: HOST_PRIORITY
+                    });
+                }
+            }
+        }
+        // 2. SRFLX candidates — STUN binding-request to ≥2 bootnodes
+        const srflxResults = await Promise.all(this.#opts.stunBootnodes.slice(0, 3).map((bn) => this.#probeSrflx(bn.host)));
+        const uniqueSrflx = new Map();
+        for (const r of srflxResults) {
+            if (!r)
+                continue;
+            const key = `${r.address}:${r.port}`;
+            if (!uniqueSrflx.has(key)) {
+                uniqueSrflx.set(key, {
+                    kind: "srflx",
+                    address: r.address,
+                    port: r.port,
+                    priority: SRFLX_PRIORITY
+                });
+            }
+        }
+        this.#localCandidates.push(...uniqueSrflx.values());
+        // 3. RELAY candidates — one TURN allocation per bootnode (start with one)
+        if (this.#opts.turnBootnodes.length > 0) {
+            const bn = this.#opts.turnBootnodes[0];
+            const creds = deriveCarrierTurnCreds({
+                bootnodeHost: bn.host,
+                bootnodePublicKey: bn.publicKey,
+                ourUserid: this.#opts.ourUserid,
+                ourSecretKey: this.#opts.ourSecretKey
+            });
+            try {
+                const turn = await this.#ensureTurnClient(bn.host, creds);
+                const allocation = await turn.allocate();
+                this.#localCandidates.push({
+                    kind: "relay",
+                    address: allocation.relayedAddress.address,
+                    port: allocation.relayedAddress.port,
+                    priority: RELAY_PRIORITY
+                });
+            }
+            catch (err) {
+                // Best-effort — if TURN fails, we still have host/srflx.
+                console.error(`[ice-lite] TURN allocate via ${bn.host} failed:`, err.message);
+            }
+        }
+        // 4. Ship offer to remote
+        this.#opts.signaling.send({
+            candidates: this.#localCandidates,
+            ufrag: this.#ufrag,
+            password: this.#password,
+            generation: this.#generation
+        });
+        if (this.#remoteOffer) {
+            this.#runChecks();
+        }
+    }
+    close() {
+        this.#closed = true;
+        if (this.#keepaliveTimer)
+            clearInterval(this.#keepaliveTimer);
+        this.#opts.sock.off("message", this.#onSocketMessage);
+        for (const turn of this.#turnByBootnode.values())
+            turn.close();
+        this.#turnByBootnode.clear();
+    }
+    // -- internal -------------------------------------------------------------
+    async #probeSrflx(host) {
+        return new Promise((resolve) => {
+            const req = buildBindingRequest();
+            const txnKey = Buffer.from(req.slice(8, 20)).toString("hex");
+            const timer = setTimeout(() => {
+                this.#pendingChecks.delete(`srflx:${txnKey}`);
+                resolve(undefined);
+            }, PING_TIMEOUT_MS);
+            this.#pendingChecks.set(`srflx:${txnKey}`, () => {
+                // resolved out-of-band by #onSocketMessage; here we just clear timer
+                clearTimeout(timer);
+            });
+            // Stash a one-shot resolver
+            const oneShot = (data, rinfo) => {
+                if (rinfo.address !== host)
+                    return;
+                const msg = decodeStun(data);
+                if (!msg || msg.type !== STUN_BINDING_SUCCESS)
+                    return;
+                const xma = findAttr(msg, STUN_ATTR_XOR_MAPPED_ADDRESS);
+                if (!xma)
+                    return;
+                const addr = decodeXorMappedAddress(xma, msg.transactionId);
+                if (addr) {
+                    clearTimeout(timer);
+                    this.#opts.sock.off("message", oneShot);
+                    this.#pendingChecks.delete(`srflx:${txnKey}`);
+                    resolve(addr);
+                }
+            };
+            this.#opts.sock.on("message", oneShot);
+            this.#opts.sock.send(Buffer.from(req), 3478, host);
+        });
+    }
+    async #ensureTurnClient(bootnodeHost, creds) {
+        const existing = this.#turnByBootnode.get(bootnodeHost);
+        if (existing)
+            return existing;
+        const turn = new TurnClient({ sock: this.#opts.sock, creds });
+        if (this.#opts.onRelayedData) {
+            turn.onData(this.#opts.onRelayedData);
+        }
+        this.#turnByBootnode.set(bootnodeHost, turn);
+        return turn;
+    }
+    #onRemoteOffer(offer) {
+        if (this.#remoteOffer && offer.generation <= this.#remoteOffer.generation)
+            return;
+        this.#remoteOffer = offer;
+        if (this.#localCandidates.length > 0)
+            this.#runChecks();
+    }
+    #runChecks() {
+        if (!this.#remoteOffer)
+            return;
+        const pairs = [];
+        for (const local of this.#localCandidates) {
+            for (const remote of this.#remoteOffer.candidates) {
+                pairs.push({ local, remote, ok: false, lastPingMs: 0, lostInARow: 0 });
+            }
+        }
+        // Sort by combined priority — try best first
+        pairs.sort((a, b) => b.local.priority + b.remote.priority - (a.local.priority + a.remote.priority));
+        this.#pairs = pairs;
+        // Fire connectivity checks (staggered to spread bursts on the same socket)
+        let i = 0;
+        const interval = setInterval(() => {
+            if (this.#closed || i >= pairs.length || this.#selected) {
+                clearInterval(interval);
+                return;
+            }
+            const p = pairs[i++];
+            this.#sendCheck(p);
+        }, CHECK_INTERVAL_MS);
+        if (!this.#keepaliveTimer) {
+            this.#keepaliveTimer = setInterval(() => this.#keepalive(), KEEPALIVE_MS);
+        }
+    }
+    #sendCheck(p) {
+        if (!this.#remoteOffer)
+            return;
+        const username = `${this.#remoteOffer.ufrag}:${this.#ufrag}`;
+        const txn = newTransactionId();
+        const pkt = encodeStun({
+            type: STUN_BINDING_REQUEST,
+            transactionId: txn,
+            attributes: [{ type: STUN_ATTR_USERNAME, value: Buffer.from(username, "utf8") }]
+        }, { integrityKey: shortTermIntegrityKey(this.#remoteOffer.password), fingerprint: true });
+        const key = `check:${Buffer.from(txn).toString("hex")}:${p.remote.address}:${p.remote.port}`;
+        p.lastPingMs = Date.now();
+        this.#pendingChecks.set(key, () => {
+            p.ok = true;
+            p.lostInARow = 0;
+            if (!this.#selected)
+                this.#selectIfBetter(p);
+        });
+        setTimeout(() => {
+            if (this.#pendingChecks.delete(key)) {
+                p.lostInARow++;
+            }
+        }, PING_TIMEOUT_MS);
+        this.#opts.sock.send(Buffer.from(pkt), p.remote.port, p.remote.address);
+    }
+    #selectIfBetter(p) {
+        const score = (pp) => pp.local.priority + pp.remote.priority;
+        if (!this.#selected) {
+            this.#selected = { local: p.local, remote: p.remote };
+            this.#opts.onSelected(this.#selected);
+            return;
+        }
+        const current = this.#pairs.find((x) => x.local === this.#selected.local && x.remote === this.#selected.remote);
+        if (current && score(p) > score(current)) {
+            this.#selected = { local: p.local, remote: p.remote };
+            this.#opts.onSelected(this.#selected);
+        }
+    }
+    #keepalive() {
+        for (const p of this.#pairs) {
+            if (!p.ok)
+                continue;
+            this.#sendCheck(p);
+            if (p.lostInARow >= LOST_THRESHOLD) {
+                p.ok = false;
+                if (this.#selected &&
+                    this.#selected.local === p.local &&
+                    this.#selected.remote === p.remote) {
+                    this.#selected = undefined;
+                    // Promote the next still-OK pair, or run discovery again
+                    const next = this.#pairs.find((x) => x.ok);
+                    if (next)
+                        this.#selectIfBetter(next);
+                    else
+                        this.start().catch(() => { });
+                }
+            }
+        }
+    }
+    #onSocketMessage = (data, rinfo) => {
+        const msg = decodeStun(data);
+        if (!msg)
+            return;
+        if (msg.type === STUN_BINDING_REQUEST) {
+            this.#respondToCheck(msg, rinfo);
+            return;
+        }
+        if (msg.type === STUN_BINDING_SUCCESS) {
+            const txn = Buffer.from(msg.transactionId).toString("hex");
+            for (const key of this.#pendingChecks.keys()) {
+                if (key.startsWith("check:" + txn + ":")) {
+                    const cb = this.#pendingChecks.get(key);
+                    this.#pendingChecks.delete(key);
+                    cb();
+                    return;
+                }
+            }
+        }
+    };
+    #respondToCheck(req, rinfo) {
+        if (!this.#remoteOffer)
+            return;
+        const pkt = encodeStun({
+            type: STUN_BINDING_SUCCESS,
+            transactionId: req.transactionId,
+            attributes: [
+                {
+                    type: STUN_ATTR_XOR_MAPPED_ADDRESS,
+                    value: encodeXorMappedAddress({ family: 4, address: rinfo.address, port: rinfo.port }, req.transactionId)
+                }
+            ]
+        }, { integrityKey: shortTermIntegrityKey(this.#password), fingerprint: true });
+        this.#opts.sock.send(Buffer.from(pkt), rinfo.port, rinfo.address);
+    }
+}
+function base64url(bytes) {
+    return Buffer.from(bytes)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}