@meshwhisper/sdk 0.1.0

package/dist/transport/browser/index.js

@@ -0,0 +1,176 @@
+// ============================================================
+// MeshWhisper SDK — Browser Transport
+// Connects the SDK to a MeshWhisper Node using the native
+// browser WebSocket API. Drop-in replacement for NodeTransport
+// when running in a browser or PWA context.
+// ============================================================
+import { serializePacket, deserializePacket, HEADER_SIZE, } from '../websocket/serialize.js';
+// ---- Constants ----
+/** Foundation-hosted relay nodes. Used when node config is "mesh". */
+export const FOUNDATION_RELAY_NODES = [
+    'wss://relay.meshwhisper.io',
+];
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+// ---- BrowserTransport ----
+/**
+ * Transport that connects to a MeshWhisper Node using the native browser
+ * WebSocket API. Functionally identical to NodeTransport but uses
+ * `globalThis.WebSocket` instead of the `ws` npm package, so it bundles
+ * cleanly for browsers and PWAs.
+ */
+export class BrowserTransport {
+    nodeUrl;
+    getDestHashes;
+    pushConfig;
+    type = 'internet';
+    ws = null;
+    receiveCallbacks = [];
+    running = false;
+    reconnectAttempt = 0;
+    reconnectTimer = null;
+    constructor(nodeUrl, getDestHashes, pushConfig) {
+        this.nodeUrl = nodeUrl;
+        this.getDestHashes = getDestHashes;
+        this.pushConfig = pushConfig;
+    }
+    // ---- Transport interface ----
+    async start() {
+        this.running = true;
+        await this.connect();
+    }
+    async stop() {
+        this.running = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close(1000, 'shutdown');
+            this.ws = null;
+        }
+    }
+    async isAvailable() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    async send(packet, _destination) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('BrowserTransport: not connected to Node');
+        }
+        const binary = serializePacket(packet);
+        this.ws.send(binary);
+    }
+    onReceive(callback) {
+        this.receiveCallbacks.push(callback);
+    }
+    // ---- Connection management ----
+    resolveUrl() {
+        if (this.nodeUrl === 'mesh') {
+            return FOUNDATION_RELAY_NODES[0];
+        }
+        return this.nodeUrl;
+    }
+    connect() {
+        const url = this.resolveUrl();
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            const ws = new WebSocket(url);
+            ws.binaryType = 'arraybuffer';
+            ws.addEventListener('open', () => {
+                this.ws = ws;
+                this.reconnectAttempt = 0;
+                resolved = true;
+                ws.send(JSON.stringify(this.buildHello()));
+                resolve();
+            });
+            ws.addEventListener('message', (event) => {
+                this.handleMessage(event.data);
+            });
+            ws.addEventListener('close', () => {
+                this.ws = null;
+                if (this.running)
+                    this.scheduleReconnect();
+            });
+            ws.addEventListener('error', () => {
+                if (!resolved) {
+                    resolved = true;
+                    reject(new Error(`BrowserTransport: failed to connect to ${url}`));
+                }
+            });
+        });
+    }
+    scheduleReconnect() {
+        if (!this.running)
+            return;
+        const delay = Math.min(RECONNECT_BASE_MS * Math.pow(2, this.reconnectAttempt), RECONNECT_MAX_MS);
+        this.reconnectAttempt++;
+        this.reconnectTimer = setTimeout(async () => {
+            if (!this.running)
+                return;
+            try {
+                await this.connect();
+            }
+            catch {
+                this.scheduleReconnect();
+            }
+        }, delay);
+    }
+    // ---- Message handling ----
+    handleMessage(data) {
+        if (data instanceof ArrayBuffer && data.byteLength >= HEADER_SIZE) {
+            try {
+                const packet = deserializePacket(new Uint8Array(data));
+                const source = this.resolveUrl();
+                for (const cb of this.receiveCallbacks) {
+                    try {
+                        cb(packet, source);
+                    }
+                    catch { /* swallow */ }
+                }
+            }
+            catch {
+                // Malformed packet — discard
+            }
+            return;
+        }
+        if (typeof data === 'string') {
+            try {
+                JSON.parse(data);
+                // Reserved for future Node→client control messages
+            }
+            catch { /* not JSON */ }
+        }
+    }
+    // ---- Dest hash / push token refresh ----
+    refreshDestHashes() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify(this.buildHello()));
+    }
+    setPushConfig(pushConfig) {
+        this.pushConfig = pushConfig;
+        this.refreshDestHashes();
+    }
+    // ---- Private helpers ----
+    buildHello() {
+        const msg = {
+            type: 'hello',
+            destHashes: this.getDestHashes(),
+        };
+        if (this.pushConfig) {
+            if (this.pushConfig.platform === 'webpush') {
+                msg['pushSubscription'] = JSON.stringify(this.pushConfig.subscription);
+                msg['pushPlatform'] = 'webpush';
+            }
+            else {
+                msg['pushToken'] = this.pushConfig.token;
+                msg['pushPlatform'] = this.pushConfig.platform;
+                if ('topic' in this.pushConfig && this.pushConfig.topic) {
+                    msg['pushTopic'] = this.pushConfig.topic;
+                }
+            }
+        }
+        return msg;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/transport/browser/index.js.map

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

package/dist/transport/local/index.d.ts

@@ -0,0 +1,57 @@
+import type { Transport, Packet } from '../../types.js';
+export declare class LocalTransport implements Transport {
+    readonly type: "local_net";
+    private readonly deviceId;
+    private readonly deviceIdHex;
+    private readonly udpPort;
+    private readonly tcpPort;
+    private udpSocket;
+    private tcpServer;
+    private announceTimer;
+    private pruneTimer;
+    private readonly discoveredPeers;
+    private readonly connections;
+    private readonly pendingConnections;
+    private receiveCallback;
+    private running;
+    constructor(deviceId: Uint8Array, options?: {
+        udpPort?: number;
+        tcpPort?: number;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isAvailable(): Promise<boolean>;
+    send(packet: Packet, destination: string): Promise<void>;
+    onReceive(callback: (packet: Packet, source: string) => void): void;
+    startDiscovery(): Promise<void>;
+    /** Build and broadcast a MWSP announcement datagram. */
+    private broadcastAnnouncement;
+    /** Process an incoming UDP announcement. */
+    private handleAnnouncement;
+    /** Remove peers whose last announcement is older than PEER_TTL_MS. */
+    private pruneStalePeers;
+    startListener(port?: number): Promise<void>;
+    connectToPeer(address: string, port: number): Promise<void>;
+    /** Handle an incoming TCP connection from a remote peer. */
+    private handleIncomingConnection;
+    /**
+     * Attach length-prefixed framing to a TCP connection.
+     *
+     * The first message on every connection is a 16-byte device ID used to
+     * register the peer. All subsequent messages are serialized Packets.
+     *
+     * @param conn   The peer connection wrapper (mutated in place).
+     * @param isInitiator  True if we initiated the connection.
+     */
+    private setupTcpFraming;
+    /** Return the list of peers discovered via UDP announcements. */
+    getDiscoveredPeers(): Array<{
+        id: string;
+        address: string;
+        port: number;
+    }>;
+    /** Return the IDs of peers with an active TCP connection. */
+    getConnectedPeers(): string[];
+}
+export default LocalTransport;
+//# sourceMappingURL=index.d.ts.map

package/dist/transport/local/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transport/local/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAe,MAAM,gBAAgB,CAAC;AAgGrE,qBAAa,cAAe,YAAW,SAAS;IAC9C,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAGrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAGjC,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,aAAa,CAA+C;IACpE,OAAO,CAAC,UAAU,CAA+C;IAGjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IACjE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,eAAe,CAA2D;IAClF,OAAO,CAAC,OAAO,CAAS;gBAGtB,QAAQ,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAe5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4CrB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAoB/B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9D,SAAS,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAQ7D,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCrC,wDAAwD;IACxD,OAAO,CAAC,qBAAqB;IAmB7B,4CAA4C;IAC5C,OAAO,CAAC,kBAAkB;IAoC1B,sEAAsE;IACtE,OAAO,CAAC,eAAe;IAmBjB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3C,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCjE,4DAA4D;IAC5D,OAAO,CAAC,wBAAwB;IAiBhC;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAwFvB,iEAAiE;IACjE,kBAAkB,IAAI,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ1E,6DAA6D;IAC7D,iBAAiB,IAAI,MAAM,EAAE;CAG9B;AAED,eAAe,cAAc,CAAC"}

package/dist/transport/local/index.js

@@ -0,0 +1,442 @@
+// ============================================================
+// MeshWhisper SDK — Local Network Transport (LAN)
+// Bearer: local_net
+//
+// Uses UDP broadcast for peer discovery and TCP for reliable
+// data transfer. Designed for device self-clustering on the
+// same subnet (phone ↔ laptop in the same home).
+// ============================================================
+import * as dgram from 'node:dgram';
+import * as net from 'node:net';
+// --- Constants ---
+const MAGIC = 0x4d575350; // "MWSP"
+const DEFAULT_UDP_PORT = 19205;
+const DEFAULT_TCP_PORT = 19206;
+const ANNOUNCE_INTERVAL_MS = 5_000;
+const PEER_TTL_MS = 15_000;
+const DEVICE_ID_LENGTH = 16;
+const ANNOUNCEMENT_SIZE = 4 + DEVICE_ID_LENGTH + 2; // magic + id + port
+const LENGTH_PREFIX_SIZE = 4; // uint32 big-endian frame header
+// --- Helpers ---
+/** Encode a 16-byte device ID to a hex string. */
+function deviceIdToHex(buf) {
+    return Buffer.from(buf).toString('hex');
+}
+/** Decode a hex string back to a 16-byte Uint8Array. */
+function hexToDeviceId(hex) {
+    return new Uint8Array(Buffer.from(hex, 'hex'));
+}
+/** Serialize a Packet to a binary buffer. */
+function serializePacket(packet) {
+    const headerSize = 1 + // version
+        1 + // flags
+        8 + // destHash
+        16 + // senderEphemeralId
+        1 + // ttl
+        4; // payloadLength (uint32)
+    const buf = Buffer.alloc(headerSize + packet.encryptedPayload.length);
+    let offset = 0;
+    buf.writeUInt8(packet.version, offset);
+    offset += 1;
+    buf.writeUInt8(packet.flags, offset);
+    offset += 1;
+    Buffer.from(packet.destHash).copy(buf, offset, 0, 8);
+    offset += 8;
+    Buffer.from(packet.senderEphemeralId).copy(buf, offset, 0, 16);
+    offset += 16;
+    buf.writeUInt8(packet.ttl, offset);
+    offset += 1;
+    buf.writeUInt32BE(packet.encryptedPayload.length, offset);
+    offset += 4;
+    Buffer.from(packet.encryptedPayload).copy(buf, offset);
+    return buf;
+}
+/** Deserialize a binary buffer back into a Packet. */
+function deserializePacket(buf) {
+    let offset = 0;
+    const version = buf.readUInt8(offset);
+    offset += 1;
+    const flags = buf.readUInt8(offset);
+    offset += 1;
+    const destHash = new Uint8Array(buf.subarray(offset, offset + 8));
+    offset += 8;
+    const senderEphemeralId = new Uint8Array(buf.subarray(offset, offset + 16));
+    offset += 16;
+    const ttl = buf.readUInt8(offset);
+    offset += 1;
+    const payloadLength = buf.readUInt32BE(offset);
+    offset += 4;
+    const encryptedPayload = new Uint8Array(buf.subarray(offset, offset + payloadLength));
+    return { version, flags, destHash, senderEphemeralId, ttl, payloadLength, encryptedPayload };
+}
+// ============================================================
+// LocalTransport
+// ============================================================
+export class LocalTransport {
+    type = 'local_net';
+    // --- Configuration ---
+    deviceId;
+    deviceIdHex;
+    udpPort;
+    tcpPort;
+    // --- Networking ---
+    udpSocket = null;
+    tcpServer = null;
+    announceTimer = null;
+    pruneTimer = null;
+    // --- State ---
+    discoveredPeers = new Map();
+    connections = new Map();
+    pendingConnections = new Set(); // addresses currently being connected to
+    receiveCallback = null;
+    running = false;
+    constructor(deviceId, options) {
+        if (deviceId.length !== DEVICE_ID_LENGTH) {
+            throw new Error(`deviceId must be ${DEVICE_ID_LENGTH} bytes, got ${deviceId.length}`);
+        }
+        this.deviceId = deviceId;
+        this.deviceIdHex = deviceIdToHex(deviceId);
+        this.udpPort = options?.udpPort ?? DEFAULT_UDP_PORT;
+        this.tcpPort = options?.tcpPort ?? DEFAULT_TCP_PORT;
+    }
+    // --------------------------------------------------------
+    // Transport interface — lifecycle
+    // --------------------------------------------------------
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        await Promise.all([
+            this.startDiscovery(),
+            this.startListener(this.tcpPort),
+        ]);
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        // Clear timers
+        if (this.announceTimer) {
+            clearInterval(this.announceTimer);
+            this.announceTimer = null;
+        }
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = null;
+        }
+        // Close all TCP peer connections
+        for (const [, conn] of this.connections) {
+            conn.socket.destroy();
+        }
+        this.connections.clear();
+        this.pendingConnections.clear();
+        // Close TCP server
+        await new Promise((resolve) => {
+            if (this.tcpServer) {
+                this.tcpServer.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+        this.tcpServer = null;
+        // Close UDP socket
+        await new Promise((resolve) => {
+            if (this.udpSocket) {
+                this.udpSocket.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+        this.udpSocket = null;
+        this.discoveredPeers.clear();
+    }
+    async isAvailable() {
+        // Local network is available if we can bind a UDP socket.
+        // In practice this checks whether the OS networking stack is usable.
+        return new Promise((resolve) => {
+            const probe = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+            probe.on('error', () => {
+                probe.close();
+                resolve(false);
+            });
+            probe.bind(0, () => {
+                probe.close();
+                resolve(true);
+            });
+        });
+    }
+    // --------------------------------------------------------
+    // Transport interface — messaging
+    // --------------------------------------------------------
+    async send(packet, destination) {
+        const conn = this.connections.get(destination);
+        if (!conn) {
+            throw new Error(`No active connection to peer ${destination}`);
+        }
+        const payload = serializePacket(packet);
+        const frame = Buffer.alloc(LENGTH_PREFIX_SIZE + payload.length);
+        frame.writeUInt32BE(payload.length, 0);
+        payload.copy(frame, LENGTH_PREFIX_SIZE);
+        await new Promise((resolve, reject) => {
+            conn.socket.write(frame, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    onReceive(callback) {
+        this.receiveCallback = callback;
+    }
+    // --------------------------------------------------------
+    // UDP Discovery
+    // --------------------------------------------------------
+    async startDiscovery() {
+        await new Promise((resolve, reject) => {
+            this.udpSocket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+            this.udpSocket.on('error', (err) => {
+                if (!this.running)
+                    return;
+                // Non-fatal in steady state; during bind it rejects the promise.
+                reject(err);
+            });
+            this.udpSocket.on('message', (msg, rinfo) => {
+                this.handleAnnouncement(msg, rinfo.address);
+            });
+            this.udpSocket.bind(this.udpPort, () => {
+                this.udpSocket.setBroadcast(true);
+                // Send first announcement immediately, then on interval
+                this.broadcastAnnouncement();
+                this.announceTimer = setInterval(() => this.broadcastAnnouncement(), ANNOUNCE_INTERVAL_MS);
+                // Periodically prune stale peers
+                this.pruneTimer = setInterval(() => this.pruneStalePeers(), ANNOUNCE_INTERVAL_MS);
+                resolve();
+            });
+        });
+    }
+    /** Build and broadcast a MWSP announcement datagram. */
+    broadcastAnnouncement() {
+        if (!this.udpSocket)
+            return;
+        const buf = Buffer.alloc(ANNOUNCEMENT_SIZE);
+        let offset = 0;
+        buf.writeUInt32BE(MAGIC, offset);
+        offset += 4;
+        Buffer.from(this.deviceId).copy(buf, offset, 0, DEVICE_ID_LENGTH);
+        offset += DEVICE_ID_LENGTH;
+        buf.writeUInt16BE(this.tcpPort, offset);
+        this.udpSocket.send(buf, 0, buf.length, this.udpPort, '255.255.255.255', (err) => {
+            if (err && this.running) {
+                // Best-effort; swallow transient send errors.
+            }
+        });
+    }
+    /** Process an incoming UDP announcement. */
+    handleAnnouncement(msg, senderAddress) {
+        if (msg.length < ANNOUNCEMENT_SIZE)
+            return;
+        const magic = msg.readUInt32BE(0);
+        if (magic !== MAGIC)
+            return;
+        const peerIdBytes = msg.subarray(4, 4 + DEVICE_ID_LENGTH);
+        const peerId = deviceIdToHex(peerIdBytes);
+        // Ignore our own announcements
+        if (peerId === this.deviceIdHex)
+            return;
+        const tcpPort = msg.readUInt16BE(4 + DEVICE_ID_LENGTH);
+        const existing = this.discoveredPeers.get(peerId);
+        if (existing) {
+            existing.lastSeen = Date.now();
+            existing.address = senderAddress;
+            existing.port = tcpPort;
+        }
+        else {
+            this.discoveredPeers.set(peerId, {
+                id: peerId,
+                address: senderAddress,
+                port: tcpPort,
+                lastSeen: Date.now(),
+            });
+        }
+        // Auto-connect if we don't already have a TCP connection
+        if (!this.connections.has(peerId) && !this.pendingConnections.has(peerId)) {
+            this.connectToPeer(senderAddress, tcpPort).catch(() => {
+                // Connection failed; will retry on next announcement.
+            });
+        }
+    }
+    /** Remove peers whose last announcement is older than PEER_TTL_MS. */
+    pruneStalePeers() {
+        const now = Date.now();
+        for (const [id, peer] of this.discoveredPeers) {
+            if (now - peer.lastSeen > PEER_TTL_MS) {
+                this.discoveredPeers.delete(id);
+                // Also tear down stale TCP connections
+                const conn = this.connections.get(id);
+                if (conn) {
+                    conn.socket.destroy();
+                    this.connections.delete(id);
+                }
+            }
+        }
+    }
+    // --------------------------------------------------------
+    // TCP Data Channel
+    // --------------------------------------------------------
+    async startListener(port) {
+        const listenPort = port ?? this.tcpPort;
+        await new Promise((resolve, reject) => {
+            this.tcpServer = net.createServer((socket) => {
+                this.handleIncomingConnection(socket);
+            });
+            this.tcpServer.on('error', (err) => {
+                reject(err);
+            });
+            this.tcpServer.listen(listenPort, () => {
+                resolve();
+            });
+        });
+    }
+    async connectToPeer(address, port) {
+        // Derive a temporary key until the peer identifies itself via handshake.
+        const addrKey = `${address}:${port}`;
+        this.pendingConnections.add(addrKey);
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection({ host: address, port }, () => {
+                // Send our device ID so the remote side knows who connected
+                const idFrame = Buffer.alloc(LENGTH_PREFIX_SIZE + DEVICE_ID_LENGTH);
+                idFrame.writeUInt32BE(DEVICE_ID_LENGTH, 0);
+                Buffer.from(this.deviceId).copy(idFrame, LENGTH_PREFIX_SIZE);
+                socket.write(idFrame);
+                // We don't yet know the peer ID. We'll register the connection
+                // once we receive the peer's ID frame back.
+                const conn = {
+                    peerId: '', // will be populated
+                    socket,
+                    recvBuffer: Buffer.alloc(0),
+                };
+                this.setupTcpFraming(conn, true);
+                this.pendingConnections.delete(addrKey);
+                resolve();
+            });
+            socket.on('error', (err) => {
+                this.pendingConnections.delete(addrKey);
+                reject(err);
+            });
+        });
+    }
+    /** Handle an incoming TCP connection from a remote peer. */
+    handleIncomingConnection(socket) {
+        const conn = {
+            peerId: '', // unknown until the peer sends its ID frame
+            socket,
+            recvBuffer: Buffer.alloc(0),
+        };
+        // The first framed message from the connecting side is the device ID.
+        this.setupTcpFraming(conn, false);
+        // Send our own ID back so the remote side can register us.
+        const idFrame = Buffer.alloc(LENGTH_PREFIX_SIZE + DEVICE_ID_LENGTH);
+        idFrame.writeUInt32BE(DEVICE_ID_LENGTH, 0);
+        Buffer.from(this.deviceId).copy(idFrame, LENGTH_PREFIX_SIZE);
+        socket.write(idFrame);
+    }
+    /**
+     * Attach length-prefixed framing to a TCP connection.
+     *
+     * The first message on every connection is a 16-byte device ID used to
+     * register the peer. All subsequent messages are serialized Packets.
+     *
+     * @param conn   The peer connection wrapper (mutated in place).
+     * @param isInitiator  True if we initiated the connection.
+     */
+    setupTcpFraming(conn, isInitiator) {
+        let identified = false;
+        conn.socket.on('data', (chunk) => {
+            conn.recvBuffer = Buffer.concat([conn.recvBuffer, chunk]);
+            // Process as many complete frames as available
+            while (conn.recvBuffer.length >= LENGTH_PREFIX_SIZE) {
+                const frameLen = conn.recvBuffer.readUInt32BE(0);
+                // Guard against absurdly large frames (16 MiB limit)
+                if (frameLen > 16 * 1024 * 1024) {
+                    conn.socket.destroy(new Error('Frame too large'));
+                    return;
+                }
+                if (conn.recvBuffer.length < LENGTH_PREFIX_SIZE + frameLen) {
+                    break; // wait for more data
+                }
+                const frameData = conn.recvBuffer.subarray(LENGTH_PREFIX_SIZE, LENGTH_PREFIX_SIZE + frameLen);
+                conn.recvBuffer = Buffer.from(conn.recvBuffer.subarray(LENGTH_PREFIX_SIZE + frameLen));
+                if (!identified) {
+                    // First frame: device ID
+                    if (frameData.length !== DEVICE_ID_LENGTH) {
+                        conn.socket.destroy(new Error('Invalid identification frame'));
+                        return;
+                    }
+                    const peerId = deviceIdToHex(frameData);
+                    // Don't connect to ourselves
+                    if (peerId === this.deviceIdHex) {
+                        conn.socket.destroy();
+                        return;
+                    }
+                    // If we already have a connection to this peer, keep only one.
+                    // The tie-breaker: the side with the lexicographically smaller ID
+                    // keeps its *initiated* connection.
+                    const existingConn = this.connections.get(peerId);
+                    if (existingConn) {
+                        const weAreSmaller = this.deviceIdHex < peerId;
+                        if (isInitiator === weAreSmaller) {
+                            // We keep this connection; destroy the old one.
+                            existingConn.socket.destroy();
+                        }
+                        else {
+                            // We keep the existing connection; destroy this one.
+                            conn.socket.destroy();
+                            return;
+                        }
+                    }
+                    conn.peerId = peerId;
+                    this.connections.set(peerId, conn);
+                    identified = true;
+                }
+                else {
+                    // Subsequent frames: Packets
+                    try {
+                        const packet = deserializePacket(Buffer.from(frameData));
+                        this.receiveCallback?.(packet, conn.peerId);
+                    }
+                    catch {
+                        // Malformed packet — drop silently.
+                    }
+                }
+            }
+        });
+        conn.socket.on('close', () => {
+            if (conn.peerId && this.connections.get(conn.peerId) === conn) {
+                this.connections.delete(conn.peerId);
+            }
+        });
+        conn.socket.on('error', () => {
+            // Error is followed by close; cleanup happens there.
+        });
+    }
+    // --------------------------------------------------------
+    // Peer Queries
+    // --------------------------------------------------------
+    /** Return the list of peers discovered via UDP announcements. */
+    getDiscoveredPeers() {
+        return Array.from(this.discoveredPeers.values()).map(({ id, address, port }) => ({
+            id,
+            address,
+            port,
+        }));
+    }
+    /** Return the IDs of peers with an active TCP connection. */
+    getConnectedPeers() {
+        return Array.from(this.connections.keys());
+    }
+}
+export default LocalTransport;
+//# sourceMappingURL=index.js.map