@livedesk/hub 0.1.73 → 0.1.75

package/src/console-direct.js

@@ -10,6 +10,12 @@ import {
 } from '../../runtime-core/src/console-direct-wire.js';
 import { workspaceRoleCanControl, workspaceRoleCanRequest } from './auth/workspace-access.js';
 import { createConsoleFrameAdmission } from './console-direct-frame-admission.mjs';
+import { createConsoleRouterMapping } from './console-router-mapping.mjs';
+import { createConsoleIceSetupGate } from './console-ice-setup-gate.mjs';
+import {
+  createConsoleIceEvidence, normalizeConsoleIcePortRange, recordConsoleIceCandidate, recordConsoleIceDescription,
+  retainConsoleIceRetirement, safeIceState, snapshotConsoleIceEvidence
+} from './console-direct-ice-evidence.mjs';
 
 const DEFAULT_SIGNAL_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
 const DEFAULT_STUN_URLS = Object.freeze(['stun:stun.cloudflare.com:3478']);
@@ -328,6 +334,10 @@ export function createHubConsoleDirect(options = {}) {
   const httpBaseUrl = String(options.httpBaseUrl || '').replace(/\/+$/, '');
   const canonicalHttpBaseUrl = normalizeHttpBaseUrl(httpBaseUrl);
   const stunUrls = normalizeStunUrls(options.stunUrls);
+  const icePortRange = normalizeConsoleIcePortRange(options.icePortRange);
+  const routerMapping = options.routerMapping || createConsoleRouterMapping({
+    isEnabled: options.isRouterMappingEnabled
+  });
   const SignalingWebSocketImpl = options.SignalingWebSocketImpl || options.WebSocketImpl || WebSocket;
   const LocalWebSocketImpl = options.LocalWebSocketImpl || options.WebSocketImpl || WebSocket;
   const fetchImpl = options.fetchImpl || globalThis.fetch;
@@ -380,6 +390,7 @@ export function createHubConsoleDirect(options = {}) {
     Number(options.logicalBindTimeoutMs) || LOGICAL_BIND_TIMEOUT_MS
   );
   const peers = new Map();
+  const recentPeerConnections = [];
   const revokedMembers = new Map();
   let signalSocket = null;
   let signalGeneration = 0;
@@ -569,6 +580,9 @@ export function createHubConsoleDirect(options = {}) {
   const retirePeer = (owner, reason = 'console-direct-peer-closed', options = {}) => {
     if (!owner || owner.retired) return;
     owner.retired = true;
+    owner.iceSetupGate?.close();
+    void owner.routerMapping?.release();
+    retainConsoleIceRetirement(recentPeerConnections, owner, reason);
     if (peers.get(owner.consoleId) === owner) peers.delete(owner.consoleId);
     clearTimeout(owner.iceTimer);
     owner.iceTimer = null;
@@ -774,6 +788,7 @@ export function createHubConsoleDirect(options = {}) {
       }
       return false;
     }
+    const sendStartedAt = performance.now();
     for (const [chunkIndex, chunk] of chunks.entries()) {
       if (!isOwnerActive(owner) || channelState.closed || !channelIsOpen(channelState.channel)) return false;
       try {
@@ -810,6 +825,8 @@ export function createHubConsoleDirect(options = {}) {
         return false;
       }
     }
+    if (!isOwnerActive(owner) || channelState.closed) return false;
+    channelState.frameAdmission?.sent(wireBytes, sendStartedAt);
     return true;
   }
 
@@ -1252,6 +1269,8 @@ export function createHubConsoleDirect(options = {}) {
     channel.onOpen(() => {
       if (!isOwnerActive(owner) || channelState.closed) return;
       if (channelState === owner.control) {
+        owner.controlOpened = true;
+        void owner.routerMapping?.release();
         clearTimeout(owner.iceTimer);
         owner.iceTimer = null;
         sendControl(owner, {
@@ -1315,7 +1334,7 @@ export function createHubConsoleDirect(options = {}) {
       && existing.connectionId === connectionId
       && existing.hubEpoch === ownerHubEpoch
       && !existing.retired) {
-      const current = existing.peer.localDescription?.();
+      const current = existing.peer?.localDescription?.();
       if (current?.type === 'answer' && typeof current.sdp === 'string') {
         sendSignal({
           type: 'rtc-answer',
@@ -1337,29 +1356,6 @@ export function createHubConsoleDirect(options = {}) {
     }
     if (existing) retirePeer(existing, 'console-direct-peer-replaced');
     let peer;
-    try {
-      peer = createPeerConnection(`console-${consoleId}`, {
-        iceServers: [...stunUrls],
-        iceTransportPolicy: 'all',
-        disableAutoNegotiation: false,
-        disableFingerprintVerification: false,
-        // Each native send is one wire chunk. libdatachannel also uses this
-        // setting as the minimum SCTP socket buffer size, below bufferedAmount.
-        // A whole-frame limit here hides megabytes from our admission gate.
-        // Complete frame/HTTP limits remain enforced by the wire assemblers.
-        maxMessageSize: DIRECT_CONSOLE_WIRE_CHUNK_BYTES
-      });
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-      sendSignal({
-        type: 'rtc-close',
-        consoleId,
-        connectionId,
-        hubEpoch: ownerHubEpoch,
-        reason: 'console-direct-peer-create-failed'
-      });
-      return null;
-    }
     const owner = {
       consoleId,
       connectionId,
@@ -1377,70 +1373,18 @@ export function createHubConsoleDirect(options = {}) {
       accessTimer: null,
       peerState: 'new',
       iceState: 'new',
+      controlOpened: false,
+      routerMapping: null,
+      iceSetupGate: null,
+      iceEvidence: createConsoleIceEvidence(),
       retired: false,
       createdAt: Date.now()
     };
     peers.set(consoleId, owner);
+    owner.routerMapping = routerMapping.createOwner(`${consoleId}:${connectionId}:${owner.generation}`,
+      { portRange: icePortRange });
+    if (owner.routerMapping?.handoff) owner.iceSetupGate = createConsoleIceSetupGate();
     armOwnerAccessDeadline(owner);
-    peer.onLocalDescription((sdp, type) => {
-      if (!isOwnerActive(owner) || String(type).toLowerCase() !== 'answer' || byteLength(sdp) > SDP_MAX_BYTES) return;
-      if (candidateIsRelay(sdp)) {
-        rejectedRelayCandidates += 1;
-        retirePeer(owner, 'console-direct-relay-candidate-rejected');
-        return;
-      }
-      sendSignal({
-        type: 'rtc-answer',
-        ...ownerEnvelope(owner),
-        description: { type: 'answer', sdp: String(sdp) }
-      });
-    });
-    peer.onLocalCandidate((candidate, sdpMid) => {
-      if (!isOwnerActive(owner)) return;
-      const candidateText = String(candidate || '');
-      if (byteLength(candidateText) > ICE_CANDIDATE_MAX_BYTES) {
-        retirePeer(owner, 'console-direct-candidate-invalid');
-        return;
-      }
-      if (candidateIsRelay(candidateText)) {
-        rejectedRelayCandidates += 1;
-        retirePeer(owner, 'console-direct-relay-candidate-rejected');
-        return;
-      }
-      sendSignal({
-        type: 'rtc-ice',
-        ...ownerEnvelope(owner),
-        candidate: candidateText,
-        sdpMid: sdpMid === undefined || sdpMid === null ? null : String(sdpMid).slice(0, 256)
-      });
-    });
-    peer.onDataChannel(channel => bindDataChannel(owner, channel));
-    peer.onStateChange(nextState => {
-      if (!isOwnerActive(owner)) return;
-      const normalized = String(nextState || '').toLowerCase();
-      owner.peerState = normalized;
-      if (normalized === 'connected') {
-        if (peerSelectedRelay(peer)) {
-          rejectedRelayCandidates += 1;
-          retirePeer(owner, 'console-direct-relay-pair-rejected');
-          return;
-        }
-      } else if (normalized === 'failed' || normalized === 'closed') {
-        retirePeer(owner, `console-direct-peer-${normalized}`);
-        return;
-      }
-      refreshPeerDisconnectDeadline(owner);
-    });
-    peer.onIceStateChange?.(nextState => {
-      if (!isOwnerActive(owner)) return;
-      const normalized = String(nextState || '').toLowerCase();
-      owner.iceState = normalized;
-      if (normalized === 'failed' || normalized === 'closed') {
-        retirePeer(owner, `console-direct-ice-${normalized}`);
-        return;
-      }
-      refreshPeerDisconnectDeadline(owner);
-    });
     owner.iceTimer = setTimeout(() => {
       owner.iceTimer = null;
       if (isOwnerActive(owner)
@@ -1449,13 +1393,117 @@ export function createHubConsoleDirect(options = {}) {
       }
     }, iceConnectTimeoutMs);
     owner.iceTimer.unref?.();
-    try {
-      peer.setRemoteDescription(description.sdp, 'offer');
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-      retirePeer(owner, 'console-direct-description-failed');
-      return null;
-    }
+    const initializePeer = reservedPort => {
+      if (!isOwnerActive(owner)) return null;
+      try {
+        peer = createPeerConnection(`console-${consoleId}`, {
+          iceServers: [...stunUrls],
+          iceTransportPolicy: 'all',
+          ...icePortRange,
+          ...(reservedPort ? { portRangeBegin: reservedPort, portRangeEnd: reservedPort } : {}),
+          disableAutoNegotiation: false,
+          disableFingerprintVerification: false,
+          // Keep the native SCTP socket's hidden buffer at the wire chunk bound.
+          maxMessageSize: DIRECT_CONSOLE_WIRE_CHUNK_BYTES
+        });
+        owner.peer = peer;
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+        retirePeer(owner, 'console-direct-peer-create-failed');
+        return null;
+      }
+      peer.onLocalDescription((sdp, type) => {
+        if (!isOwnerActive(owner) || String(type).toLowerCase() !== 'answer' || byteLength(sdp) > SDP_MAX_BYTES) return;
+        if (candidateIsRelay(sdp)) {
+          rejectedRelayCandidates += 1;
+          retirePeer(owner, 'console-direct-relay-candidate-rejected');
+          return;
+        }
+        const sent = sendSignal({
+          type: 'rtc-answer',
+          ...ownerEnvelope(owner),
+          description: { type: 'answer', sdp: String(sdp) }
+        });
+        owner.iceEvidence.localDescriptionSent = sent;
+        recordConsoleIceDescription(owner.iceEvidence.local, sdp);
+        if (!owner.controlOpened) {
+          for (const line of sdp.split(/\r?\n/)) {
+            if (line.startsWith('a=candidate:')) owner.routerMapping?.observe(line);
+          }
+        }
+      });
+      peer.onLocalCandidate((candidate, sdpMid) => {
+        if (!isOwnerActive(owner)) return;
+        const candidateText = String(candidate || '');
+        if (byteLength(candidateText) > ICE_CANDIDATE_MAX_BYTES) {
+          retirePeer(owner, 'console-direct-candidate-invalid');
+          return;
+        }
+        if (candidateIsRelay(candidateText)) {
+          rejectedRelayCandidates += 1;
+          retirePeer(owner, 'console-direct-relay-candidate-rejected');
+          return;
+        }
+        const sent = sendSignal({
+          type: 'rtc-ice',
+          ...ownerEnvelope(owner),
+          candidate: candidateText,
+          sdpMid: sdpMid === undefined || sdpMid === null ? null : String(sdpMid).slice(0, 256)
+        });
+        recordConsoleIceCandidate(owner.iceEvidence.local, candidateText);
+        if (!owner.controlOpened) owner.routerMapping?.observe(candidateText);
+        if (!sent) owner.iceEvidence.localCandidateSendFailures = Math.min(65_535,
+          owner.iceEvidence.localCandidateSendFailures + 1);
+      });
+      peer.onGatheringStateChange?.(nextState => {
+        if (isOwnerActive(owner)) owner.iceEvidence.gatheringState = safeIceState(String(nextState).toLowerCase());
+      });
+      peer.onDataChannel(channel => bindDataChannel(owner, channel));
+      peer.onStateChange(nextState => {
+        if (!isOwnerActive(owner)) return;
+        const normalized = String(nextState || '').toLowerCase();
+        owner.peerState = normalized;
+        if (normalized === 'connected') {
+          if (peerSelectedRelay(peer)) {
+            rejectedRelayCandidates += 1;
+            retirePeer(owner, 'console-direct-relay-pair-rejected');
+            return;
+          }
+        } else if (normalized === 'failed' || normalized === 'closed') {
+          retirePeer(owner, `console-direct-peer-${normalized}`);
+          return;
+        }
+        refreshPeerDisconnectDeadline(owner);
+      });
+      peer.onIceStateChange?.(nextState => {
+        if (!isOwnerActive(owner)) return;
+        const normalized = String(nextState || '').toLowerCase();
+        owner.iceState = normalized;
+        if (normalized === 'failed' || normalized === 'closed') {
+          retirePeer(owner, `console-direct-ice-${normalized}`);
+          return;
+        }
+        refreshPeerDisconnectDeadline(owner);
+      });
+      try {
+        peer.setRemoteDescription(description.sdp, 'offer');
+        owner.iceEvidence.remoteDescriptionApplied = true;
+        recordConsoleIceDescription(owner.iceEvidence.remote, description.sdp);
+        owner.iceSetupGate?.flush((candidate, mid) => peer.addRemoteCandidate(candidate, mid),
+          () => isOwnerActive(owner));
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+        retirePeer(owner, 'console-direct-description-failed');
+        return null;
+      }
+      return owner;
+    };
+    if (owner.routerMapping?.handoff) {
+      void owner.routerMapping.ready.then(async () => {
+        const reservation = await owner.routerMapping.handoff();
+        if (isOwnerActive(owner)) initializePeer(reservation?.port);
+      }).catch(() => retirePeer(owner, 'console-direct-peer-create-failed'));
+    } else initializePeer();
     return owner;
   };
 
@@ -1594,7 +1642,12 @@ export function createHubConsoleDirect(options = {}) {
         return;
       }
       try {
-        if (candidate) owner.peer.addRemoteCandidate(candidate, String(payload.sdpMid || ''));
+        if (candidate) {
+          recordConsoleIceCandidate(owner.iceEvidence.remote, candidate);
+          if (!owner.iceSetupGate?.defer(candidate, String(payload.sdpMid || ''))) {
+            owner.peer.addRemoteCandidate(candidate, String(payload.sdpMid || ''));
+          }
+        }
       } catch {
         retirePeer(owner, 'console-direct-candidate-failed');
       }
@@ -1951,6 +2004,8 @@ export function createHubConsoleDirect(options = {}) {
     retryTimer = null;
     nextRetryAt = '';
     retireAllPeers('hub-shutdown');
+    void routerMapping.releaseAll({ forgetHistory: true });
+    recentPeerConnections.length = 0;
     hubEpoch = '';
     const socket = signalSocket;
     signalSocket = null;
@@ -1961,6 +2016,8 @@ export function createHubConsoleDirect(options = {}) {
 
   const invalidateWorkspaceAccess = (reason = 'console-workspace-access-invalidated') => {
     retireAllPeers(String(reason || 'console-workspace-access-invalidated').slice(0, 120));
+    void routerMapping.releaseAll({ forgetHistory: true });
+    recentPeerConnections.length = 0;
     refresh();
   };
 
@@ -2018,6 +2075,7 @@ export function createHubConsoleDirect(options = {}) {
         generation: owner.generation,
         peerState: owner.peerState,
         iceState: owner.iceState,
+        iceEvidence: snapshotConsoleIceEvidence(owner.iceEvidence),
         rttMs: optionalPeerMetric(owner.peer, 'rtt'),
         bytesSent: optionalPeerMetric(owner.peer, 'bytesSent'),
         bytesReceived: optionalPeerMetric(owner.peer, 'bytesReceived'),
@@ -2041,6 +2099,7 @@ export function createHubConsoleDirect(options = {}) {
     const accessTokenDeadlineActive = Boolean(accessTokenAttempt);
     const signalReadyDeadlineActive = Boolean(signalReadyDeadline);
     const signalHeartbeatTimerActive = Boolean(signalHeartbeat?.timer);
+    const routerResources = routerMapping.inspect();
     return Object.freeze({
       enabled: signalUrl instanceof URL && Boolean(deviceId),
       state,
@@ -2055,6 +2114,8 @@ export function createHubConsoleDirect(options = {}) {
       retainedAssemblyBytes,
       bufferedSendBytes,
       peerDiagnostics,
+      routerMapping: routerResources,
+      recentPeerConnections: recentPeerConnections.map(entry => snapshotConsoleIceEvidence(entry)),
       iceConnectTimers,
       peerDisconnectTimers,
       assemblyDeadlineTimers,
@@ -2075,7 +2136,8 @@ export function createHubConsoleDirect(options = {}) {
         + workspaceAccessTimers
         + Number(Boolean(workspaceReauthAttempt?.timer))
         + Number(signalReadyDeadlineActive)
-        + Number(signalHeartbeatTimerActive),
+        + Number(signalHeartbeatTimerActive)
+        + Number(routerResources.resourceTimers || 0),
       rejectedRelayCandidates,
       dataChannelBackpressureCloses,
       dataChannelSendFailures,
@@ -2096,7 +2158,8 @@ export function createHubConsoleDirect(options = {}) {
     close,
     invalidateWorkspaceAccess,
     revokeWorkspaceMember,
-    inspect
+    inspect,
+    releaseRouterMappings: () => routerMapping.releaseAll()
   });
 }
 

package/src/console-direct.test.mjs

@@ -158,6 +158,7 @@ class FakePeerConnection {
   onDataChannel(callback) { this.callbacks.dataChannel = callback; }
   onStateChange(callback) { this.callbacks.state = callback; }
   onIceStateChange(callback) { this.callbacks.iceState = callback; }
+  onGatheringStateChange(callback) { this.callbacks.gatheringState = callback; }
 
   setRemoteDescription(sdp, type) {
     this.remote = { sdp, type };
@@ -233,6 +234,8 @@ async function connectedDirect(options = {}) {
     hubInstanceId: options.hubInstanceId || HUB_EPOCH,
     httpBaseUrl: 'http://127.0.0.1:5179',
     stunUrls: options.stunUrls || ['stun:stun.example.test:3478'],
+    icePortRange: options.icePortRange,
+    routerMapping: options.routerMapping,
     getAccessToken: async () => 'access-token',
     ...(options.workspaceAccess ? { getWorkspaceAccess: () => options.workspaceAccess } : {}),
     ...(options.consoleProxyToken ? { consoleProxyToken: options.consoleProxyToken } : {}),
@@ -340,6 +343,8 @@ test('native buffered sends complete each media message without closing input or
     assert.equal(peer.closed, false);
     assert.equal(direct.inspect().dataChannelSendFailures, 0);
     assert.equal(direct.inspect().dataChannelBackpressureCloses, 0);
+    assert.ok(direct.inspect().peerDiagnostics[0].lanes.find(l => l.channelId === CHANNEL_ID).frameAdmission.sendBatches > 0,
+      'accepted native false returns are accounted before the lane closes');
     lane.sendMessageBinary = () => { throw new Error('native-send-failed'); };
     local.receive(Buffer.alloc(10), true);
     assert.equal(lane.closed, true, 'an actual native exception still retires the exact lane');
@@ -353,11 +358,134 @@ test('native buffered sends complete each media message without closing input or
   }
 });
 
+test('an explicit direct port range reaches the native peer without enabling relay or ICE TCP', async () => {
+  const { direct, signal } = await connectedDirect({ icePortRange: '54443-54450' });
+  try {
+    const peer = offer(signal);
+    assert.equal(peer.config.portRangeBegin, 54443);
+    assert.equal(peer.config.portRangeEnd, 54450);
+    assert.equal(peer.config.enableIceTcp, undefined);
+    assert.equal(peer.config.disableFingerprintVerification, false);
+    assert.deepEqual(peer.config.iceServers, ['stun:stun.example.test:3478']);
+  } finally { direct.close(); }
+});
+
+test('router setup belongs to the exact peer and ends on control ready without closing that peer', async () => {
+  const leases = [];
+  const routerMapping = {
+    createOwner(key) {
+      const lease = { key, candidates: [], released: false,
+        observe(candidate) { this.candidates.push(candidate); },
+        async release() { this.released = true; } };
+      leases.push(lease);
+      return lease;
+    },
+    async releaseAll() { await Promise.all(leases.map(lease => lease.release())); },
+    inspect() { return { resourceTimers: 0 }; }
+  };
+  const { direct, signal } = await connectedDirect({ routerMapping });
+  try {
+    const first = offer(signal);
+    const second = offer(signal, CONNECTION_TWO, 'v=0\r\n', { consoleId: CONNECTION_TWO });
+    first.emitLocalCandidate('candidate:1 1 udp 1 192.168.0.4 54443 typ host');
+    assert.equal(leases[0].candidates.length, 1);
+    assert.notEqual(leases[0].key, leases[1].key);
+    const control = new FakeDataChannel('livedesk-control-v1');
+    first.emitDataChannel(control); control.open();
+    assert.equal(leases[0].released, true);
+    assert.equal(leases[1].released, false);
+    assert.equal(first.closed, false);
+    assert.equal(second.closed, false);
+    first.emitLocalCandidate('candidate:2 1 udp 1 192.168.0.4 54444 typ host');
+    assert.equal(leases[0].candidates.length, 1, 'late gathering cannot reopen an established peer mapping');
+    direct.invalidateWorkspaceAccess();
+    await direct.releaseRouterMappings();
+    assert.ok(leases.every(lease => lease.released));
+  } finally { direct.close(); }
+});
+
+test('router readiness precedes native gathering and a retired peer cannot consume late setup completion', async () => {
+  const completions = [];
+  const routerMapping = {
+    createOwner() {
+      return { ready: new Promise(resolve => completions.push(resolve)),
+        async handoff() { return { port: 54443 }; }, observe() {}, release() {} };
+    },
+    async releaseAll() {},
+    inspect: () => ({ resourceTimers: 0 })
+  };
+  const { direct, signal } = await connectedDirect({ routerMapping });
+  const candidate = 'candidate:7 1 UDP 123 8.8.8.8 50000 typ srflx';
+  const sdp = `v=0\r\nm=application 9 UDP/DTLS/SCTP webrtc-datachannel\r\na=mid:0\r\na=${candidate}\r\n`;
+  try {
+    offer(signal, CONNECTION_ONE, sdp);
+    assert.equal(FakePeerConnection.instances.length, 0);
+    signal.receive(JSON.stringify({ type: 'rtc-ice', consoleId: CONSOLE_ID, connectionId: CONNECTION_ONE,
+      hubEpoch: HUB_EPOCH, candidate, sdpMid: '0' }));
+    assert.equal(FakePeerConnection.instances.length, 0);
+    completions[0](); await settle();
+    const first = FakePeerConnection.instances[0];
+    assert.equal(first.config.portRangeBegin, 54443);
+    assert.equal(first.config.portRangeEnd, 54443);
+    assert.equal(first.remote.sdp, sdp);
+    assert.deepEqual(first.remoteCandidates, [{ candidate, sdpMid: '0' }]);
+    offer(signal, CONNECTION_TWO, sdp);
+    direct.invalidateWorkspaceAccess();
+    completions[1](); await settle();
+    assert.equal(FakePeerConnection.instances.length, 1, 'retired setup must not create a native peer');
+    assert.equal(first.closed, true);
+  } finally { direct.close(); }
+});
+
+test('failed ICE owners retain bounded evidence while a healthy peer and signaling survive', async () => {
+  const { direct, signal } = await connectedDirect({ iceConnectTimeoutMs: 30 });
+  try {
+    const healthy = offer(signal, CONNECTION_TWO, 'v=0\r\n', { consoleId: CONNECTION_TWO });
+    const control = new FakeDataChannel('livedesk-control-v1');
+    healthy.emitDataChannel(control);
+    control.open();
+    const failed = offer(signal);
+    failed.emitLocalCandidate('candidate:1 1 udp 1 203.0.113.1 40000 typ srflx raddr 192.168.0.4 rport 40000');
+    failed.callbacks.gatheringState('complete');
+    failed.callbacks.iceState('checking');
+    signal.receive(JSON.stringify({ type: 'rtc-ice', consoleId: CONSOLE_ID,
+      connectionId: CONNECTION_ONE, hubEpoch: HUB_EPOCH, sdpMid: '0',
+      candidate: 'candidate:2 1 udp 1 2001:db8::abcd 50000 typ host' }));
+    await waitFor(() => failed.closed);
+    const evidence = direct.inspect().recentPeerConnections.at(-1);
+    assert.equal(evidence.reason, 'console-direct-ice-timeout');
+    assert.equal(evidence.localDescriptionSent, true);
+    assert.equal(evidence.remoteDescriptionApplied, true);
+    assert.equal(evidence.gatheringState, 'complete');
+    assert.equal(evidence.local.srflx, 1);
+    assert.equal(evidence.remote.ipv6, 1);
+    assert.equal(evidence.controlOpened, false);
+    assert.equal(healthy.closed, false);
+    assert.equal(direct.inspect().controlChannels, 1);
+    assert.equal(direct.inspect().state, 'connected');
+    assert.equal(direct.inspect().iceConnectTimers, 0);
+    failed.emitLocalCandidate('candidate:3 1 udp 1 192.168.0.7 40000 typ host');
+    failed.callbacks.gatheringState('new');
+    assert.deepEqual(direct.inspect().recentPeerConnections.at(-1), evidence);
+    evidence.remote.ipv6 = 500;
+    assert.equal(direct.inspect().recentPeerConnections.at(-1).remote.ipv6, 1);
+    assert.doesNotMatch(JSON.stringify(direct.inspect().recentPeerConnections), /203\.0\.113|192\.168|2001:db8/);
+    direct.invalidateWorkspaceAccess();
+    assert.deepEqual(direct.inspect().recentPeerConnections, []);
+  } finally {
+    direct.close();
+    assert.equal(direct.inspect().resourceTimers, 0);
+    assert.deepEqual(direct.inspect().recentPeerConnections, []);
+  }
+});
+
 test('STUN-only peer answers and rejects stale owner callbacks after replacement', async () => {
   const { direct, signal } = await connectedDirect();
   const firstPeer = offer(signal, CONNECTION_ONE);
   assert.deepEqual(firstPeer.config.iceServers, ['stun:stun.example.test:3478']);
   assert.equal(firstPeer.config.iceTransportPolicy, 'all');
+  assert.equal(firstPeer.config.portRangeBegin, undefined);
+  assert.equal(firstPeer.config.portRangeEnd, undefined);
   assert.equal(firstPeer.config.disableFingerprintVerification, false);
   assert.equal(firstPeer.config.maxMessageSize, DIRECT_CONSOLE_WIRE_CHUNK_BYTES,
     'native SCTP accepts wire chunks, not whole frames; a frame-sized setting silently enlarges its hidden buffers');

package/src/console-ice-setup-gate.mjs

@@ -0,0 +1,30 @@
+// The authenticated offer retains its original SDP while the native socket is
+// prepared. Only bounded trickled candidates wait here, with no timer or peer.
+export function createConsoleIceSetupGate() {
+  let waiting = true;
+  let closed = false;
+  const candidates = [];
+  function defer(candidate, mid) {
+    if (closed || !waiting) return false;
+    mid = String(mid || '');
+    if (candidate.length > 4096 || mid.length > 256) throw new Error('console-direct-candidate-invalid');
+    if (candidates.some(value => value.candidate === candidate && value.mid === mid)) return true;
+    if (candidates.length >= 16) throw new Error('console-direct-candidate-invalid');
+    candidates.push({ candidate, mid });
+    return true;
+  }
+  return {
+    defer,
+    flush(apply, isCurrent) {
+      if (closed) return;
+      waiting = false;
+      while (candidates.length > 0) {
+        const value = candidates.shift();
+        if (!isCurrent()) { candidates.length = 0; return; }
+        apply(value.candidate, value.mid);
+      }
+    },
+    close() { closed = true; waiting = false; candidates.length = 0; },
+    inspect: () => ({ waiting: waiting && !closed, candidates: candidates.length })
+  };
+}