@johnhenry/browsermesh-transport 0.0.0 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/browsermesh-transport",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "WebSocket, WebRTC, WebTransport, and relay adapters for BrowserMesh",
   "type": "module",
   "main": "./src/index.mjs",
@@ -21,8 +21,12 @@
   "peerDependencies": {
     "@johnhenry/browsermesh-primitives": ">=0.0.0"
   },
+  "devDependencies": {
+    "node-datachannel": "^0.33.2"
+  },
   "scripts": {
-    "test": "node --import ./test/_setup-globals.mjs --test test/*.test.mjs"
+    "test": "node --import ./test/_setup-globals.mjs --test test/*.test.mjs",
+    "test:real-peer": "node --import ./test/_setup-globals.mjs --test --test-concurrency=1 test/real-peer/*.test.mjs"
   },
   "homepage": "https://opensource.johnhenry.me/browsermesh/",
   "engines": {

package/src/cross-origin.mjs

@@ -344,6 +344,29 @@ export class CrossOriginBridge {
     const fromPeerId = data.fromPodId
     const peer = fromPeerId ? this.#peers.get(fromPeerId) : null
 
+    /*
+     * An unknown sender is REFUSED, not exempted.
+     *
+     * Every check below used to be written `if (peer && ...)`, and `peer` is
+     * null whenever `fromPodId` is absent or names a pod that was never
+     * registered. So omitting the field skipped origin validation, the
+     * ISOLATED block and the method allowlist in one go, and execution
+     * carried on into the handler. Identifying yourself as an ISOLATED peer
+     * was blocked; identifying yourself as nobody was not, which made the
+     * anonymous caller the privileged one.
+     *
+     * The reply made it worse: `#sendResponse` fell back to
+     * `postMessage(msg, '*')` with no peer, so the result went to any origin.
+     *
+     * Scoped to XO_REQUEST: a RESPONSE legitimately carries no `fromPodId` --
+     * it is correlated by `requestId` against a request this side sent -- so
+     * refusing peerless messages outright breaks every reply.
+     */
+    if (!peer && data.type === XO_REQUEST) {
+      this.#log(`Blocked request from unregistered sender: ${fromPeerId ?? '(no fromPodId)'}`)
+      return
+    }
+
     // Origin validation -- reject if the event origin doesn't match the registered origin
     if (peer && event.origin && event.origin !== peer.origin) {
       this.#log(`Origin mismatch for ${fromPeerId}: expected ${peer.origin}, got ${event.origin}`)
@@ -372,13 +395,13 @@ export class CrossOriginBridge {
     const { requestId, method, params, fromPodId } = data
 
     // ISOLATED peers cannot invoke anything
-    if (peer && peer.trust === TRUST_LEVELS.ISOLATED) {
+    if (peer.trust === TRUST_LEVELS.ISOLATED) {
       this.#log(`Blocked request from isolated peer ${fromPodId}`)
       return
     }
 
     // For VERIFIED peers, enforce the method allowlist
-    if (peer && peer.trust === TRUST_LEVELS.VERIFIED && peer.allowedMethods.size > 0) {
+    if (peer.trust === TRUST_LEVELS.VERIFIED && peer.allowedMethods.size > 0) {
       if (!peer.allowedMethods.has(method)) {
         this.#sendResponse(source, peer, requestId, null, `Method "${method}" not allowed`)
         return

package/src/relay.mjs

@@ -347,6 +347,13 @@ export class MeshRelayClient {
       const onOpen = () => {
         // Send register immediately on open. Server may or may not ack.
         this.#sendWs({ type: 'register', fingerprint: this.#fingerprint });
+        // Re-announce what we advertised before the socket dropped. A relay
+        // keeps presence per connection, so a reconnect starts with an empty
+        // record for us -- while this client goes on reporting connected:true
+        // and the old capabilities, leaving the peer undiscoverable with
+        // nothing on either side saying so. Empty on a first connect, so the
+        // initial handshake is unchanged.
+        if (this._announcedCapabilities.length > 0) this.#sendAnnounceWs();
         if (!settled) { settled = true; resolve(); }
       };
       const onMessage = (ev) => this.#handleWsMessage(ev);
@@ -456,14 +463,24 @@ export class MeshRelayClient {
     if (this.#server) {
       this.#server.broadcastPresence(this.#fingerprint, capabilities);
     } else if (this.#ws) {
-      this.#sendWs({
-        type: 'announce',
-        fingerprint: this.#fingerprint,
-        capabilities: [...capabilities],
-      });
+      this.#sendAnnounceWs();
     }
   }
 
+  /**
+   * Send the announce message for the capabilities currently on record.
+   * Always sends -- announcePresence([]) is a deliberate "I advertise
+   * nothing" and must reach the relay. The reconnect path guards on empty
+   * itself, so a first connect stays a bare register.
+   */
+  #sendAnnounceWs() {
+    this.#sendWs({
+      type: 'announce',
+      fingerprint: this.#fingerprint,
+      capabilities: [...this._announcedCapabilities],
+    });
+  }
+
   /**
    * Query the relay for peers matching criteria.
    *

package/src/webrtc.mjs

@@ -27,31 +27,89 @@ export function supportsWebRTC() {
   return typeof RTCPeerConnection !== 'undefined'
 }
 
+/**
+ * Extract the session id from an SDP's `o=` (origin) line.
+ *
+ * RFC 4566 gives the origin line as
+ * `o=<username> <sess-id> <sess-version> <nettype> <addrtype> <address>`,
+ * and RFC 3264 requires a follow-up offer for an existing session to reuse
+ * that `<sess-id>`. So two offers carrying the same session id came from the
+ * same peer connection, and an offer whose session id differs from the one
+ * already applied is a *new* session -- the peer restarted.
+ *
+ * Used only as a fallback when the signaling payload lacks the explicit
+ * `renegotiation` flag (see `handleOffer`), so that a peer running an older
+ * build of this class can still be renegotiated with.
+ *
+ * @param {string} sdp
+ * @returns {string|null} The session id, or null if the SDP has no origin line.
+ */
+export function sdpSessionId(sdp) {
+  const m = /^o=\S+ (\S+) /m.exec(sdp || '')
+  return m ? m[1] : null
+}
+
 // ---------------------------------------------------------------------------
 // ICE defaults
 // ---------------------------------------------------------------------------
 
-/** @type {RTCIceServer[]} */
-const DEFAULT_ICE_SERVERS = Object.freeze([
+/**
+ * Default ICE configuration: none.
+ *
+ * With no ICE servers a peer gathers host candidates only, which is all two
+ * devices on the same LAN need and involves no third party. Contacting a
+ * public STUN server discloses the client's public IP, and the fact that it
+ * is pairing, to whoever runs it — so that is opt-in, not the default. See
+ * PUBLIC_STUN_SERVERS to opt in, or supply your own STUN/TURN.
+ *
+ * @type {RTCIceServer[]}
+ */
+export const DEFAULT_ICE_SERVERS = Object.freeze([])
+
+/**
+ * A public STUN server, for callers who need reflexive candidates to traverse
+ * NAT and have decided that the disclosure is acceptable.
+ *
+ * Using this sends a STUN binding request to Google from every peer that
+ * gathers candidates, revealing the device's public IP address and the timing
+ * of the pairing attempt. Prefer a STUN server you control.
+ *
+ * @type {RTCIceServer[]}
+ */
+export const PUBLIC_STUN_SERVERS = Object.freeze([
   { urls: 'stun:stun.l.google.com:19302' },
 ])
 
 /**
  * Merge user-configured ICE servers (typically TURN, for NAT traversal
- * when direct/STUN connectivity fails) with the STUN defaults. Silently
+ * when direct/STUN connectivity fails) with the defaults. Silently
  * ignores malformed entries rather than throwing, since this is usually
  * fed by user-editable settings.
  *
+ * An explicit empty array means "no ICE servers" and is honoured as given:
+ * `mergeIceServers([])` returns `[]`, never the defaults. Omitting the
+ * argument (or passing null) is what asks for the defaults.
+ *
  * @param {RTCIceServer[]} [userServers] - e.g. [{urls: 'turn:relay.example.com', username, credential}]
  * @param {RTCIceServer[]} [defaults=DEFAULT_ICE_SERVERS]
  * @returns {RTCIceServer[]}
  */
 export function mergeIceServers(userServers, defaults = DEFAULT_ICE_SERVERS) {
+  // An explicit [] is a decision, not an absence. Respect it.
+  if (Array.isArray(userServers) && userServers.length === 0) return []
   const valid = (Array.isArray(userServers) ? userServers : [])
     .filter(s => s && typeof s === 'object' && typeof s.urls === 'string' && s.urls.length > 0)
   return [...defaults, ...valid]
 }
 
+/**
+ * How many remote ICE candidates to hold while waiting for the remote
+ * description. A handful of interfaces gather a handful of candidates each;
+ * generous for that, and still bounded against a peer that floods candidates
+ * and never answers.
+ */
+const MAX_PENDING_REMOTE_CANDIDATES = 64
+
 // ---------------------------------------------------------------------------
 // WebRTCPeerConnection
 // ---------------------------------------------------------------------------
@@ -73,13 +131,23 @@ export class WebRTCPeerConnection {
   #dataChannel = null
   #iceServers
   #onLog
-  #state = 'new'   // new | connecting | connected | closed
+  #state = 'new'   // new | connecting | connected | failed | closed
+
+  /**
+   * Remote candidates that arrived before the remote description existed.
+   * Flushed by #flushPendingCandidates() once it is set.
+   * @type {Array<RTCIceCandidate|object>}
+   */
+  #pendingRemoteCandidates = []
+  #closing = false // reentrancy guard for close(); see close()
   #iceCandidateCbs = []
   #messageCbs = []
   #closeCbs = []
   #errorCbs = []
   #stateChangeCbs = []
   #stats = { bytesSent: 0, bytesReceived: 0, messagesIn: 0, messagesOut: 0 }
+  #disconnectedGraceMs
+  #disconnectedTimer = null
 
   /**
    * @param {object} opts
@@ -87,14 +155,19 @@ export class WebRTCPeerConnection {
    * @param {string} opts.remotePodId - Target pod's identifier
    * @param {RTCIceServer[]} [opts.iceServers]
    * @param {Function} [opts.onLog]   - Optional logging callback
+   * @param {number} [opts.disconnectedGraceMs=5000] - How long a peer connection
+   *   may sit in the transient `disconnected` state before it is reported
+   *   through `onError()`. `failed` is reported immediately and is not
+   *   subject to this delay.
    */
-  constructor({ localPodId, remotePodId, iceServers, onLog } = {}) {
+  constructor({ localPodId, remotePodId, iceServers, onLog, disconnectedGraceMs = 5000 } = {}) {
     if (!localPodId) throw new Error('localPodId is required')
     if (!remotePodId) throw new Error('remotePodId is required')
     this.#localPodId = localPodId
     this.#remotePodId = remotePodId
     this.#iceServers = iceServers || [...DEFAULT_ICE_SERVERS]
     this.#onLog = onLog || null
+    this.#disconnectedGraceMs = disconnectedGraceMs
   }
 
   // -- Accessors ------------------------------------------------------------
@@ -145,17 +218,65 @@ export class WebRTCPeerConnection {
   }
 
   /**
-   * Handle an incoming SDP offer (callee side).
-   * Creates a peer connection, waits for the remote DataChannel, and
-   * returns an SDP answer to send back through signaling.
+   * Handle an incoming SDP offer (callee side) and return the answer to send
+   * back through signaling.
+   *
+   * Two different things arrive here, and telling them apart is the whole
+   * point of the `renegotiation` flag:
    *
-   * @param {{type: string, sdp: string}} offer
-   * @returns {Promise<{type: 'answer', sdp: string}>}
+   * - A **fresh** offer starts a new session. A new RTCPeerConnection is
+   *   built for it, replacing (and releasing) any connection we already had
+   *   with this peer -- which is the right response to a peer that restarted.
+   *
+   * - A **renegotiation** offer -- an ICE restart, or any other mid-session
+   *   re-offer -- must be applied to the *existing* RTCPeerConnection. It has
+   *   to be: the answer carries this side's ICE credentials and DTLS
+   *   fingerprint, and a renegotiation whose answer changes either of those
+   *   is rejected by the offerer. Building a new connection here is what
+   *   issue #13 measured, and it killed both peers:
+   *   `libdatachannel error while adding remote description: Invalid ICE
+   *   settings from remote SDP`.
+   *
+   * `offer.renegotiation === true` is the marker on the wire. It is a plain
+   * extra field on the same JSON payload the offer already is, so a peer that
+   * does not understand it simply ignores it and behaves exactly as it does
+   * today. For a sender too old to set it, `#isRenegotiation()` falls back to
+   * comparing SDP session ids, which recovers the same answer without any
+   * cooperation from the sender.
+   *
+   * @param {{type: string, sdp: string, renegotiation?: boolean}} offer
+   * @returns {Promise<{type: 'answer', sdp: string, renegotiation?: boolean}>}
+   * @throws {Error} If the offer is a renegotiation but there is no live
+   *   connection to renegotiate -- the sender must start a fresh one.
    */
   async handleOffer(offer) {
     this.#ensureNotClosed()
     if (!offer || !offer.sdp) throw new Error('Invalid offer: missing sdp')
 
+    if (this.#isRenegotiation(offer)) {
+      if (!this.#pc) {
+        throw new Error(
+          'Cannot answer a renegotiation offer: no existing connection — the peer must send a fresh offer',
+        )
+      }
+      // Deliberately no #setState() and no new handlers: a renegotiation
+      // keeps the DataChannel, the callbacks and the transport state it
+      // already has. Data keeps flowing over the old path until the new one
+      // is nominated -- that is what makes an ICE restart a repair rather
+      // than a reconnection.
+      await this.#pc.setRemoteDescription({ type: 'offer', sdp: offer.sdp })
+      await this.#flushPendingCandidates()
+      const answer = await this.#pc.createAnswer()
+      await this.#pc.setLocalDescription(answer)
+      this.#log(`Created renegotiation answer for ${this.#remotePodId}`)
+      return { type: 'answer', sdp: answer.sdp, renegotiation: true }
+    }
+
+    // A fresh offer supersedes anything we were holding. Release it rather
+    // than overwriting the field: the old RTCPeerConnection is otherwise
+    // unreachable and, with a native stack, keeps threads and sockets alive.
+    this.#releasePeerConnection()
+
     this.#pc = new RTCPeerConnection({ iceServers: this.#iceServers })
     this.#setupIceHandling()
     this.#setupConnectionStateHandling()
@@ -166,6 +287,7 @@ export class WebRTCPeerConnection {
     }
 
     await this.#pc.setRemoteDescription({ type: 'offer', sdp: offer.sdp })
+    await this.#flushPendingCandidates()
     const answer = await this.#pc.createAnswer()
     await this.#pc.setLocalDescription(answer)
     this.#setState('connecting')
@@ -182,6 +304,7 @@ export class WebRTCPeerConnection {
     if (!this.#pc) throw new Error('No peer connection — call createOffer() first')
     if (!answer || !answer.sdp) throw new Error('Invalid answer: missing sdp')
     await this.#pc.setRemoteDescription({ type: 'answer', sdp: answer.sdp })
+    await this.#flushPendingCandidates()
     this.#log(`Applied answer from ${this.#remotePodId}`)
   }
 
@@ -190,11 +313,71 @@ export class WebRTCPeerConnection {
   /**
    * Add a remote ICE candidate received through signaling.
    *
+   * `RTCPeerConnection.addIceCandidate()` is asynchronous and rejects on a
+   * malformed candidate, on a candidate for an m-line that does not exist,
+   * and on any candidate that arrives before the remote description is set.
+   * All three are ordinary events on a real signaling channel -- candidates
+   * race the answer, and the string on the wire came from another machine --
+   * and this method used to drop that promise on the floor. An unhandled
+   * rejection terminates a Node process by default and raises an uncaught
+   * error event in a browser, so one bad candidate from a peer could take the
+   * process down. Verified against two real RTCPeerConnections; see
+   * `test/real-peer/webrtc.test.mjs`.
+   *
+   * A rejected candidate is not a connection failure: ICE is designed to try
+   * many candidates and keep the ones that work. It is therefore logged and
+   * swallowed rather than routed to `onError()`, which WebRTCMeshManager wires
+   * to its reconnect backoff -- a peer sending junk candidates should not be
+   * able to force ICE restarts.
+   *
    * @param {RTCIceCandidate|object} candidate
+   * @returns {Promise<boolean>} Resolves true if the candidate was accepted,
+   *   false if it was rejected. Never rejects.
+   * @throws {Error} Synchronously, if there is no peer connection yet.
    */
   addIceCandidate(candidate) {
     if (!this.#pc) throw new Error('No peer connection')
-    this.#pc.addIceCandidate(candidate)
+
+    // "Candidates race the answer" is stated above as an ordinary event, and
+    // it was then handled by discarding them. That is not a test artifact: a
+    // peer gathers in 1-2ms while an answer crosses a signaling server, so on
+    // any real network the candidates arrive FIRST and every one was thrown
+    // away. What survives is peer-reflexive discovery from the other side's
+    // binding requests -- one inferred pair instead of every signalled one,
+    // with no redundancy if it fails.
+    //
+    // Measured on two real peers: with the answer delayed, 0 of 5 of the
+    // remote's candidates were accepted and the selected pair was `prflx`;
+    // with no delay, 5 of 5 were accepted and the pair was `host`.
+    //
+    // So hold them and apply them when the description lands, which is the
+    // standard trickle-ICE pattern.
+    // Not `!remoteDescription`. The spec says it is null until set, but
+    // node-datachannel's polyfill returns a truthy `{ sdp: '' }`, so that
+    // test silently never fires there -- measured, after writing it that way
+    // first. Checking the sdp works on both.
+    const remote = this.#pc.remoteDescription
+    if (!remote || !remote.sdp) {
+      if (this.#pendingRemoteCandidates.length >= MAX_PENDING_REMOTE_CANDIDATES) {
+        // Bounded: a peer that floods candidates before answering must not be
+        // able to grow this without limit.
+        this.#log(
+          `Dropped an early ICE candidate from ${this.#remotePodId}: ` +
+          `already holding ${MAX_PENDING_REMOTE_CANDIDATES}`,
+        )
+        return Promise.resolve(false)
+      }
+      this.#pendingRemoteCandidates.push(candidate)
+      return Promise.resolve(true)
+    }
+
+    return Promise.resolve(this.#pc.addIceCandidate(candidate)).then(
+      () => true,
+      (err) => {
+        this.#log(`Ignored ICE candidate from ${this.#remotePodId}: ${err?.message || err}`)
+        return false
+      },
+    )
   }
 
   /**
@@ -262,25 +445,72 @@ export class WebRTCPeerConnection {
    * Attempt to recover a failed/disconnected connection via ICE restart.
    * Only valid once an underlying RTCPeerConnection exists (i.e. after
    * createOffer() or handleOffer() has run at least once) — generates a
-   * fresh offer with `iceRestart: true`.
+   * renegotiation offer on the *existing* connection with `iceRestart: true`.
    *
-   * ICE restart still requires a full signaling round-trip: the caller
-   * must send the returned offer through the same external signaling
-   * channel used originally, and route the answer back via
-   * handleAnswer() as usual. This class doesn't own signaling — see
-   * WebRTCMeshManager.onReconnectOffer() for the orchestrated version.
+   * **A healthy connection is left alone.** This used to flip the state to
+   * `connecting` as its first act, so calling it on a working connection made
+   * `isOpen` false — and `broadcast()` skips a peer that is not open — before
+   * anything had gone wrong. It now returns `null` and touches nothing.
+   * `{ force: true }` overrides that for a caller who knows something the
+   * connection state does not (a changed network interface, say). The state
+   * is never moved from here at all: a renegotiation does not interrupt the
+   * DataChannel, and the state machine is driven by the channel's own events.
    *
-   * @returns {Promise<{type: 'offer', sdp: string}>}
+   * It also declines while a negotiation is already in flight
+   * (`signalingState !== 'stable'`), so a retry loop cannot stack offers on
+   * top of each other.
+   *
+   * Known limitation: if the answer to a renegotiation offer never comes
+   * back, the connection stays in `have-local-offer` and every later
+   * `reconnect()` declines. Recovering from that needs a rollback
+   * (`setLocalDescription({type: 'rollback'})`), which libdatachannel does
+   * not implement, so it is not attempted here. In practice the peer
+   * connection reaches `failed` on its own and the connection is torn down;
+   * the visible symptom until then is a peer that stops being repaired.
+   *
+   * ICE restart still requires a full signaling round-trip: the caller must
+   * send the returned offer through the same external signaling channel used
+   * originally, and route the answer back via handleAnswer() as usual. The
+   * offer carries `renegotiation: true` so the receiving peer answers on its
+   * existing connection instead of building a new one — without that marker
+   * the answer comes back with a different DTLS fingerprint and is rejected.
+   * This class doesn't own signaling — see WebRTCMeshManager.onReconnectOffer()
+   * for the orchestrated version.
+   *
+   * Whether the ICE credentials actually change is up to the underlying
+   * stack. Browsers mint new ones for `iceRestart: true`; libdatachannel
+   * currently ignores the flag and `restartIce()` throws `Not implemented`
+   * there. The renegotiation round-trip below is correct either way — on a
+   * stack without ICE restart it re-runs connectivity checks over the same
+   * credentials, which is strictly better than the connection teardown it
+   * replaces.
+   *
+   * @param {object} [opts]
+   * @param {boolean} [opts.force=false] - Renegotiate even if the connection
+   *   currently looks healthy.
+   * @returns {Promise<{type: 'offer', sdp: string, renegotiation: true}|null>}
+   *   null when there is nothing to repair, or a negotiation is already
+   *   in flight.
    * @throws {Error} If there's no underlying connection yet, or it's closed
    */
-  async reconnect() {
+  async reconnect({ force = false } = {}) {
     this.#ensureNotClosed()
     if (!this.#pc) throw new Error('Cannot reconnect: no underlying connection — call createOffer() first')
-    this.#setState('connecting')
+
+    const signalingState = this.#pc.signalingState
+    if (signalingState !== undefined && signalingState !== 'stable') {
+      this.#log(`ICE restart for ${this.#remotePodId} skipped: negotiation already in flight (${signalingState})`)
+      return null
+    }
+    if (!force && this.#isHealthy()) {
+      this.#log(`ICE restart for ${this.#remotePodId} skipped: connection is healthy`)
+      return null
+    }
+
     const offer = await this.#pc.createOffer({ iceRestart: true })
     await this.#pc.setLocalDescription(offer)
     this.#log(`ICE restart offer created for ${this.#remotePodId}`)
-    return { type: 'offer', sdp: offer.sdp }
+    return { type: 'offer', sdp: offer.sdp, renegotiation: true }
   }
 
   /**
@@ -327,16 +557,47 @@ export class WebRTCPeerConnection {
    * Close the connection and clean up all resources.
    */
   close() {
-    if (this.#state === 'closed') return
-    this.#setState('closed')
-    if (this.#dataChannel) {
-      try { this.#dataChannel.close() } catch (e) { silentCatch('clawser-mesh-webrtc', 'this', e) }
-      this.#dataChannel = null
-    }
-    if (this.#pc) {
-      try { this.#pc.close() } catch (e) { silentCatch('clawser-mesh-webrtc', 'this', e) }
-      this.#pc = null
+    const alreadyClosed = this.#state === 'closed'
+
+    // Release the underlying objects unconditionally, even when the state is
+    // already 'closed'. It used to return early on that check, which meant a
+    // connection closed *by the remote peer* -- where the DataChannel's
+    // onclose set the state before anyone released anything -- kept its
+    // RTCPeerConnection forever. That is one leaked peer connection per
+    // remote disconnect, and with a real WebRTC stack it also keeps the
+    // process alive: a Node test that connected two real peers and let one
+    // hang up would never exit. Verified against two real
+    // RTCPeerConnections; see test/real-peer/webrtc.test.mjs.
+    // Releasing the DataChannel fires its onclose, and onclose routes back
+    // into close() -- that is how a remote hangup releases our peer
+    // connection. Re-entering here before #setState('closed') has run means
+    // the guard in onclose still sees a live state, so close() calls itself
+    // until the stack runs out. The RangeError is then swallowed by the
+    // release try/catch below, so the symptom is not a crash but a *missing*
+    // 'closed' transition, appearing only on whichever runs exhaust the stack
+    // inside #setState's callback loop. Measured at 2227 frames deep.
+    //
+    // Browsers dispatch onclose asynchronously, which is why this hides in a
+    // real browser and surfaces against a synchronous mock or binding.
+    if (this.#closing) return
+    this.#closing = true
+    try {
+      if (this.#dataChannel) {
+        try { this.#dataChannel.close() } catch (e) { silentCatch('clawser-mesh-webrtc', 'this', e) }
+        this.#dataChannel = null
+      }
+      if (this.#pc) {
+        try { this.#pc.close() } catch (e) { silentCatch('clawser-mesh-webrtc', 'this', e) }
+        this.#pc = null
+      }
+    } finally {
+      this.#closing = false
     }
+
+    // The state transition and the close callbacks fire exactly once, so a
+    // second close() -- or a close() following a remote hangup -- is silent.
+    if (alreadyClosed) return
+    this.#setState('closed')
     this.#fireClose()
     this.#log(`Connection closed with ${this.#remotePodId}`)
   }
@@ -349,8 +610,86 @@ export class WebRTCPeerConnection {
     }
   }
 
+  /**
+   * Is this offer a re-offer on the connection we already have?
+   *
+   * The explicit flag is authoritative in both directions, so a sender can
+   * also assert `renegotiation: false`. Absent the flag, fall back to the
+   * SDP session id: RFC 3264 requires a re-offer to reuse the `o=` session id
+   * of the session it updates, so an offer matching the description already
+   * applied is a re-offer and one that differs is a new session. That
+   * fallback is what makes a peer running an older build -- one that cannot
+   * set the flag -- renegotiable rather than fatal.
+   */
+  #isRenegotiation(offer) {
+    if (offer.renegotiation === true) return true
+    if (offer.renegotiation === false) return false
+    if (!this.#pc) return false
+    const applied = this.#pc.remoteDescription?.sdp
+    if (!applied) return false
+    const incoming = sdpSessionId(offer.sdp)
+    return incoming !== null && incoming === sdpSessionId(applied)
+  }
+
+  /**
+   * A connection is healthy when our DataChannel is open *and* the peer
+   * connection itself agrees. The second half matters: a peer connection can
+   * report `failed` while the DataChannel has not yet noticed, and treating
+   * that as healthy would refuse the very repair it needs. Stacks that do not
+   * expose `connectionState` fall back to the DataChannel alone.
+   */
+  #isHealthy() {
+    if (!this.isOpen) return false
+    const pcState = this.#pc?.connectionState
+    return pcState === undefined || pcState === 'connected'
+  }
+
+  /**
+   * Drop the underlying RTCPeerConnection and DataChannel without announcing
+   * a close. Handlers are detached first: closing a DataChannel fires its
+   * `onclose`, which would otherwise report this connection as closed to
+   * every listener -- including WebRTCMeshManager, which would delete it --
+   * even though we are only swapping the transport underneath.
+   */
+  #releasePeerConnection() {
+    const dc = this.#dataChannel
+    const pc = this.#pc
+    this.#dataChannel = null
+    this.#pc = null
+    if (dc) {
+      dc.onopen = null; dc.onmessage = null; dc.onclose = null; dc.onerror = null
+      try { dc.close() } catch (e) { silentCatch('clawser-mesh-webrtc', 'release-dc', e) }
+    }
+    if (pc) {
+      pc.onicecandidate = null; pc.ondatachannel = null; pc.onconnectionstatechange = null
+      try { pc.close() } catch (e) { silentCatch('clawser-mesh-webrtc', 'release-pc', e) }
+    }
+  }
+
+  /**
+   * Apply the candidates held while there was no remote description.
+   *
+   * Failures are logged and dropped exactly as on the live path -- ICE tries
+   * many candidates and keeps the ones that work.
+   */
+  async #flushPendingCandidates() {
+    if (this.#pendingRemoteCandidates.length === 0) return
+    const held = this.#pendingRemoteCandidates
+    this.#pendingRemoteCandidates = []
+    this.#log(`Applying ${held.length} ICE candidate(s) held for ${this.#remotePodId}`)
+    for (const candidate of held) {
+      if (!this.#pc) return
+      try {
+        await this.#pc.addIceCandidate(candidate)
+      } catch (err) {
+        this.#log(`Ignored held ICE candidate from ${this.#remotePodId}: ${err?.message || err}`)
+      }
+    }
+  }
+
   #setState(next) {
     if (this.#state === next) return
+    if (next === 'closed') this.#clearDisconnectedGrace()
     this.#state = next
     for (const cb of this.#stateChangeCbs) {
       try { cb(next) } catch (e) { silentCatch('clawser-mesh-webrtc', 'swallow', e) }
@@ -367,15 +706,123 @@ export class WebRTCPeerConnection {
     }
   }
 
+  /**
+   * `failed` and `disconnected` are not the same event and must not be
+   * reported the same way.
+   *
+   * `failed` is terminal: ICE has exhausted its candidate pairs. Report it at
+   * once.
+   *
+   * `disconnected` means connectivity checks are currently failing. It is
+   * transient by design and very often recovers on its own within a couple of
+   * seconds -- a Wi-Fi roam, a dropped consent check. This used to be
+   * reported as an error immediately, and WebRTCMeshManager wires `onError`
+   * straight to its reconnect backoff, so an ordinary network blip triggered
+   * a renegotiation on a connection that was in the middle of healing. It is
+   * now reported only if it is *still* disconnected after
+   * `disconnectedGraceMs`; any other state in the meantime cancels it.
+   */
   #setupConnectionStateHandling() {
     this.#pc.onconnectionstatechange = () => {
       const pcState = this.#pc?.connectionState
-      if (pcState === 'failed' || pcState === 'disconnected') {
-        this.#fireError(new Error(`PeerConnection state: ${pcState}`))
+      if (pcState === 'failed') {
+        this.#clearDisconnectedGrace()
+        /*
+         * `failed` is terminal, and it is the ONLY terminal signal a browser
+         * gives for a handshake that dies remotely.
+         *
+         * Measured against native WebRTC (two RTCPeerConnections, corrupted
+         * DTLS fingerprint in the answer):
+         *
+         *     t=51ms  connectionState = failed
+         *     ...20s later, connectionState = failed
+         *
+         * `closed` never arrives, and the spec agrees: connectionState
+         * `closed` means the local object was closed, i.e. someone called
+         * close(). So the `closed` branch below cannot fire in a browser for
+         * this case -- libdatachannel merely happens to send `closed` as
+         * well most of the time, which is why the Node tests mostly pass and
+         * flake at ~9%.
+         *
+         * The state therefore has to move here. It does NOT close: closing
+         * on `failed` was tried and broke auto-reconnect, and ICE restart can
+         * still recover this connection (the DataChannel reopening sets
+         * 'connected' again). What changes is that `state` stops claiming
+         * 'connecting' and `isOpen` is false, so a caller polling either one
+         * learns the truth instead of waiting forever.
+         *
+         * State before the error, deliberately: WebRTCMeshManager reconnects
+         * from onError, and a handler that inspects state must not see
+         * 'connecting' on a connection that has terminally failed.
+         */
+        if (this.#state !== 'closed') this.#setState('failed')
+        this.#fireError(new Error('PeerConnection state: failed'))
+        return
+      }
+      if (pcState === 'disconnected') {
+        this.#startDisconnectedGrace()
+        return
       }
+      /*
+       * `closed` arriving here means the STACK closed the connection, not us:
+       * our own close() nulls `#pc` first, so this handler cannot see it.
+       *
+       * It was falling through to the line below and doing nothing, which
+       * left a dead connection looking alive. Measured by corrupting one hex
+       * pair of the DTLS fingerprint in the answer -- an answer that cannot
+       * verify, which is what a corrupted or hostile one looks like:
+       *
+       *     t=   0ms  pc0[ice=checking conn=connecting]
+       *     t=  52ms  pc0[ice=closed   conn=closed]      <- stack gave up
+       *     t=12013ms  state=connecting  error=none      <- we never said so
+       *
+       * Twelve seconds after both peer connections had closed themselves,
+       * `state` was still `connecting`, no error had fired, and no close
+       * callback had run. A caller waiting on `isOpen` waits forever, and
+       * WebRTCMeshManager -- which reconnects on `onError` -- never hears
+       * anything to reconnect from.
+       *
+       * The DataChannel's own close path cannot cover this: the channel never
+       * opened, so `dc.onclose` never fires.
+       *
+       * Reported as an error and then closed, which is the order `dc.onerror`
+       * already uses, so a caller listening only for errors still learns the
+       * cause before the terminal close.
+       */
+      if (pcState === 'closed' && this.#state !== 'closed') {
+        this.#clearDisconnectedGrace()
+        this.#fireError(new Error('PeerConnection closed before the DataChannel opened'))
+        this.close()
+        return
+      }
+      this.#clearDisconnectedGrace()
     }
   }
 
+  #startDisconnectedGrace() {
+    if (this.#disconnectedTimer) return
+    this.#log(
+      `PeerConnection with ${this.#remotePodId} is disconnected; ` +
+      `allowing ${this.#disconnectedGraceMs}ms to recover`,
+    )
+    this.#disconnectedTimer = setTimeout(() => {
+      this.#disconnectedTimer = null
+      if (this.#state === 'closed') return
+      if (this.#pc?.connectionState !== 'disconnected') return  // recovered
+      this.#log(`PeerConnection with ${this.#remotePodId} stayed disconnected`)
+      this.#fireError(new Error('PeerConnection state: disconnected'))
+    }, this.#disconnectedGraceMs)
+    // A pending grace period must never be the reason a Node process stays
+    // alive; browsers have no unref() and do not need one.
+    if (typeof this.#disconnectedTimer?.unref === 'function') this.#disconnectedTimer.unref()
+  }
+
+  #clearDisconnectedGrace() {
+    if (!this.#disconnectedTimer) return
+    clearTimeout(this.#disconnectedTimer)
+    this.#disconnectedTimer = null
+  }
+
   #setupDataChannel(dc) {
     dc.onopen = () => {
       this.#setState('connected')
@@ -392,10 +839,9 @@ export class WebRTCPeerConnection {
       }
     }
     dc.onclose = () => {
-      if (this.#state !== 'closed') {
-        this.#setState('closed')
-        this.#fireClose()
-      }
+      // The remote hung up. Go through close() rather than just flipping the
+      // state, so our own RTCPeerConnection is released too.
+      if (this.#state !== 'closed') this.close()
     }
     dc.onerror = (event) => {
       this.#fireError(event?.error || new Error('DataChannel error'))
@@ -442,6 +888,7 @@ export class WebRTCMeshManager {
   #reconnectTimers = new Map()    // remotePodId -> timer handle
   #maxReconnectAttempts
   #reconnectBaseDelayMs
+  #disconnectedGraceMs
   #lastStats = []
 
   /**
@@ -451,14 +898,21 @@ export class WebRTCMeshManager {
    * @param {Function} [opts.onLog]
    * @param {number} [opts.maxReconnectAttempts=5] - Give up auto-reconnecting after this many failures
    * @param {number} [opts.reconnectBaseDelayMs=1000] - Backoff base; doubles each attempt
+   * @param {number} [opts.disconnectedGraceMs=5000] - Passed to every connection:
+   *   how long a peer connection may sit in the transient `disconnected` state
+   *   before it counts as an error worth reconnecting over.
    */
-  constructor({ localPodId, iceServers, onLog, maxReconnectAttempts = 5, reconnectBaseDelayMs = 1000 } = {}) {
+  constructor({
+    localPodId, iceServers, onLog,
+    maxReconnectAttempts = 5, reconnectBaseDelayMs = 1000, disconnectedGraceMs = 5000,
+  } = {}) {
     if (!localPodId) throw new Error('localPodId is required')
     this.#localPodId = localPodId
     this.#iceServers = iceServers || [...DEFAULT_ICE_SERVERS]
     this.#onLog = onLog || null
     this.#maxReconnectAttempts = maxReconnectAttempts
     this.#reconnectBaseDelayMs = reconnectBaseDelayMs
+    this.#disconnectedGraceMs = disconnectedGraceMs
   }
 
   /** Local pod identifier. */
@@ -500,6 +954,7 @@ export class WebRTCMeshManager {
       remotePodId,
       iceServers: this.#iceServers,
       onLog: this.#onLog,
+      disconnectedGraceMs: this.#disconnectedGraceMs,
     })
     // Forward messages to manager-level listeners
     conn.onMessage((data) => {
@@ -524,13 +979,19 @@ export class WebRTCMeshManager {
 
   /**
    * Manually trigger reconnection for a peer (bypasses backoff).
+   *
    * @param {string} remotePodId
-   * @returns {Promise<{type: 'offer', sdp: string}|null>} null if no connection exists
+   * @param {object} [opts]
+   * @param {boolean} [opts.force=false] - Renegotiate even if the connection
+   *   looks healthy. Without it a healthy connection is left alone.
+   * @returns {Promise<{type: 'offer', sdp: string, renegotiation: true}|null>}
+   *   null if there is no such connection, or nothing to repair.
    */
-  async reconnectPeer(remotePodId) {
+  async reconnectPeer(remotePodId, { force = false } = {}) {
     const conn = this.#connections.get(remotePodId)
     if (!conn) return null
-    const offer = await conn.reconnect()
+    const offer = await conn.reconnect({ force })
+    if (!offer) return null
     this.#notifyReconnectOffer(offer, remotePodId)
     return offer
   }
@@ -564,7 +1025,14 @@ export class WebRTCMeshManager {
       if (!this.#connections.has(remotePodId)) return // closed/removed meanwhile
       try {
         const offer = await conn.reconnect()
-        this.#notifyReconnectOffer(offer, remotePodId)
+        if (offer) {
+          this.#notifyReconnectOffer(offer, remotePodId)
+        } else {
+          // Nothing was wrong with the connection after all -- the error that
+          // scheduled this attempt was spurious, or it healed while we waited.
+          // Refund the backoff rather than counting it against the peer.
+          this.#clearReconnectState(remotePodId)
+        }
       } catch (e) { silentCatch('clawser-mesh-webrtc', 'reconnect-attempt', e) }
     }, delay)
     this.#reconnectTimers.set(remotePodId, timer)

package/src/websocket.mjs

@@ -494,7 +494,15 @@ export class WebRTCTransport {
     // Set up signaler listeners for remote ICE candidates
     this.#signaler.onIceCandidate((candidate) => {
       if (this.#pc) {
-        this.#pc.addIceCandidate(candidate);
+        // The promise must not be dropped. addIceCandidate rejects on a
+        // malformed candidate and on one that arrives before the remote
+        // description -- both ordinary on a real signaling channel -- and an
+        // unhandled rejection ends a Node process by default. webrtc.mjs's
+        // addIceCandidate docblock records this being fixed there; this path
+        // still had it.
+        Promise.resolve(this.#pc.addIceCandidate(candidate)).catch((e) => {
+          silentCatch('clawser-mesh-websocket', 'ignore-rejected-ice-candidate', e);
+        });
       }
     });
 
@@ -884,11 +892,17 @@ export class NATTraversal {
 
   /**
    * @param {object} [opts]
-   * @param {string[]} [opts.stunServers] - STUN server URLs
+   * @param {string[]} [opts.stunServers] - STUN server URLs. Defaults to none:
+   *   host candidates suffice on a LAN, and contacting a public STUN server
+   *   discloses this device's public IP to a third party.
    * @param {object[]} [opts.turnServers] - TURN server configs with urls, username, credential
    */
   constructor(opts = {}) {
-    this.#stunServers = opts.stunServers || ['stun:stun.l.google.com:19302'];
+    // Default to no STUN. Host candidates alone connect two peers on the same
+    // LAN, and a STUN binding request discloses this device's public IP to
+    // whoever runs the server. Callers who need reflexive candidates pass
+    // stunServers explicitly.
+    this.#stunServers = opts.stunServers || [];
     this.#turnServers = opts.turnServers || [];
   }