@livedesk/hub 0.1.74 → 0.1.76

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 } : {}),
@@ -295,6 +298,120 @@ function offer(signal, connectionId = CONNECTION_ONE, sdp = 'v=0\r\na=fake-offer
   return FakePeerConnection.instances.at(-1);
 }
 
+function openPeerControl(peer) {
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.callbacks.dataChannel(control);
+  control.open();
+  return control;
+}
+
+function mediaSignal(control, mediaId, signal, parentConnectionId = CONNECTION_ONE) {
+  sendWire(control, { type: 'media-signal', connectionId: parentConnectionId,
+    hubEpoch: HUB_EPOCH, mediaId, signal: { hubEpoch: HUB_EPOCH, ...signal } });
+}
+
+test('dedicated media peers isolate congestion and retirement from HTTP, siblings and other Consoles', async () => {
+  const { direct, signal } = await connectedDirect();
+  try {
+    const root = offer(signal), control = openPeerControl(root);
+    const externalSignals = signal.sent.length;
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const first = FakePeerConnection.instances.at(-1), firstControl = openPeerControl(first);
+    mediaSignal(control, CHANNEL_ID_TWO, { type: 'rtc-offer', connectionId: REQUEST_ID,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const second = FakePeerConnection.instances.at(-1); openPeerControl(second);
+    assert.notEqual(first, root);
+    assert.notEqual(first, second);
+    assert.equal(signal.sent.length, externalSignals, 'media SDP/ICE never goes through the Worker');
+    assert.equal(direct.inspect().consoleConnections, 1);
+    assert.equal(direct.inspect().mediaPeerConnections, 2);
+    const replies = decodeWireMessages(control.sent).map(m => JSON.parse(m.data));
+    assert.ok(replies.some(m => m.type === 'media-signal' && m.mediaId === CHANNEL_ID
+      && m.signal.type === 'rtc-answer' && m.connectionId === CONNECTION_ONE));
+    firstControl.buffered = 900_000;
+    sendWire(control, { type: 'http-request', requestId: REQUEST_ID, method: 'GET', path: '/api/remote/status' });
+    await settle();
+    assert.ok(decodeWireMessages(control.sent).map(m => JSON.parse(m.data)).some(m => m.type === 'http-response'));
+    first.emitState('failed');
+    assert.equal(first.closed, true);
+    assert.equal(root.closed, false);
+    assert.equal(second.closed, false);
+    assert.equal(direct.inspect().mediaPeerConnections, 1);
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_ONE,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const replacement = FakePeerConnection.instances.at(-1); openPeerControl(replacement);
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-close', connectionId: CONNECTION_TWO });
+    assert.equal(replacement.closed, false, 'old media close cannot retire a replacement');
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    assert.equal(replacement.closed, false, 'an older offer cannot replace the active media owner');
+    assert.equal(FakePeerConnection.instances.at(-1), replacement);
+    root.emitState('closed');
+    assert.equal(second.closed, true);
+    assert.equal(replacement.closed, true);
+    assert.equal(direct.inspect().peerConnections, 0);
+    assert.equal(direct.inspect().retainedAssemblyBytes, 0);
+    assert.equal(direct.inspect().wireBudgetCleanupFailures, 0);
+  } finally { direct.close(); }
+});
+
+test('media offers cannot cross parent authority, nest children or consume the four Console slots', async () => {
+  const { direct, signal } = await connectedDirect();
+  try {
+    const root = offer(signal), control = openPeerControl(root);
+    const description = { type: 'offer', sdp: 'v=0\r\n' };
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO, description }, CONNECTION_TWO);
+    assert.equal(direct.inspect().peerConnections, 1, 'stale parent rejected');
+    let childControl;
+    for (let n = 0; n < 16; n++) {
+      const id = `bbbbbbbb-bbbb-4bbb-8bbb-${String(n).padStart(12, '0')}`;
+      mediaSignal(control, id, { type: 'rtc-offer', connectionId: CONNECTION_TWO, description });
+      childControl = openPeerControl(FakePeerConnection.instances.at(-1));
+    }
+    const child = FakePeerConnection.instances.at(-1);
+    mediaSignal(childControl, CHANNEL_ID, { type: 'rtc-offer', connectionId: REQUEST_ID, description }, CONNECTION_TWO);
+    assert.equal(direct.inspect().mediaPeerConnections, 16, 'child cannot create a grandchild');
+    const forbiddenInput = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:input`);
+    child.callbacks.dataChannel(forbiddenInput);
+    assert.equal(forbiddenInput.closed, true, 'media child cannot acquire input');
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO, description });
+    assert.equal(direct.inspect().mediaPeerConnections, 16);
+    for (let n = 1; n <= 3; n++) {
+      offer(signal, CONNECTION_TWO, 'v=0\r\n', { consoleId: `aaaaaaaa-aaaa-4aaa-8aaa-${String(n).padStart(12, '0')}` });
+    }
+    assert.equal(direct.inspect().consoleConnections, 4);
+    assert.equal(direct.inspect().peerConnections, 20);
+    offer(signal, CONNECTION_TWO, 'v=0\r\n', { consoleId: CHANNEL_ID });
+    assert.equal(direct.inspect().consoleConnections, 4);
+  } finally { direct.close(); }
+  assert.equal(direct.inspect().peerConnections, 0);
+});
+
+test('media assembly shares one Console budget and closing a child releases only its reservations', async () => {
+  const { direct, signal } = await connectedDirect();
+  try {
+    const root = offer(signal), control = openPeerControl(root);
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const child = FakePeerConnection.instances.at(-1), childControl = openPeerControl(child);
+    const partial = encodeDirectConsoleWireMessage('x'.repeat(40_000), { messageId: 77, kind: 'control' })[0];
+    childControl.receive(partial);
+    const childBytes = direct.inspect().retainedAssemblyBytes;
+    assert.ok(childBytes > 0);
+    control.receive(partial);
+    assert.equal(direct.inspect().retainedAssemblyBytes, childBytes * 2,
+      'a shared budget is counted once, not once per transport');
+    child.emitState('failed');
+    assert.equal(direct.inspect().retainedAssemblyBytes, childBytes);
+    assert.equal(direct.inspect().wireBudgetCleanupFailures, 0);
+    assert.equal(root.closed, false);
+  } finally { direct.close(); }
+  assert.equal(direct.inspect().retainedAssemblyBytes, 0);
+  assert.equal(direct.inspect().resourceTimers, 0);
+  assert.equal(direct.inspect().wireBudgetCleanupFailures, 0);
+});
+
 test('native buffered sends complete each media message without closing input or control', async () => {
   const { direct, signal } = await connectedDirect();
   try {
@@ -340,6 +457,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 +472,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');
@@ -664,7 +906,8 @@ test('reliable control channel bridges bounded HTTP over fragmented wire message
   assert.deepEqual(JSON.parse(messages[0].data), {
     type: 'direct-ready',
     connectionId: CONNECTION_ONE,
-    hubEpoch: HUB_EPOCH
+    hubEpoch: HUB_EPOCH,
+    mediaPeerVersion: 1
   });
 
   sendWire(control, {

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 })
+  };
+}

package/src/console-router-mapping.mjs

@@ -0,0 +1,206 @@
+import { randomUUID } from 'node:crypto';
+import { discoverConsoleUpnpGateway, reserveConsoleIceSocket, isPrivateRouterIPv4, isPublicRouterIPv4 } from './console-upnp-gateway.mjs';
+
+export const CONSOLE_ROUTER_MAPPING_BOUNDS = Object.freeze({
+  owners: 4, queuedOwners: 64, candidates: 8, setupMs: 8000, cleanupMs: 1800, leaseSeconds: 120, history: 8
+});
+
+export function parseRouterMappingCandidate(value) {
+  if (typeof value !== 'string' || value.length > 4096) return null;
+  const parts = value.trim().replace(/^a=/, '').split(/\s+/);
+  const port = Number(parts[5]);
+  if (!/^candidate:/i.test(parts[0]) || parts[1] !== '1' || parts[2]?.toLowerCase() !== 'udp'
+    || parts[6] !== 'typ' || !['host', 'srflx'].includes(parts[7])
+    || !(parts[7] === 'host' ? isPrivateRouterIPv4(parts[4]) : isPublicRouterIPv4(parts[4]))
+    || !Number.isInteger(port) || port < 1024 || port > 65535) return null;
+  const relatedPort = parts.includes('rport') ? Number(parts[parts.indexOf('rport') + 1]) : 0;
+  return { type: parts[7], address: parts[4], port, relatedPort };
+}
+
+function untilAborted(signal) {
+  return new Promise(resolve => {
+    if (signal.aborted) return resolve();
+    signal.addEventListener('abort', resolve, { once: true });
+  });
+}
+
+// One short-lived setup owner per authenticated peer. This never owns a peer,
+// frame, encoder or retransmit queue. Mapping removal does not close ICE.
+export function createConsoleRouterMapping(options = {}) {
+  const enabled = options.isEnabled || (() => false);
+  const discover = options.discover || discoverConsoleUpnpGateway;
+  const reserveSocket = options.reserveSocket || reserveConsoleIceSocket;
+  const bounds = CONSOLE_ROUTER_MAPPING_BOUNDS;
+  const setupMs = Math.min(bounds.setupMs, Math.max(1, Number(options.setupMs) || bounds.setupMs));
+  const cleanupMs = Math.min(bounds.cleanupMs, Math.max(1, Number(options.cleanupMs) || bounds.cleanupMs));
+  const owners = new Set();
+  const waiting = new Set();
+  const reservedPorts = new Map();
+  const history = [];
+  let historyEpoch = 0;
+  let attempts = 0, mapped = 0, cleanupUnconfirmed = 0;
+
+  function finish(owner) {
+    owners.delete(owner);
+    if (reservedPorts.get(owner.reservation) === owner) reservedPorts.delete(owner.reservation);
+    if (owner.historyEpoch === historyEpoch) history.push(Object.freeze({ owner: owner.key, state: owner.state, cleanup: owner.cleanup,
+      durationMs: Math.max(0, Date.now() - owner.startedAt) }));
+    if (history.length > bounds.history) history.shift();
+    owner.gateway = null;
+    owner.candidates.length = 0;
+    owner.finished = true;
+    owner.resolveDone();
+    for (const next of waiting) {
+      if (owners.size >= bounds.owners) break;
+      waiting.delete(next);
+      if (!next.controller.signal.aborted && enabled()) start(next);
+      else next.release();
+    }
+  }
+
+  function start(owner) {
+    owner.state = 'discovering';
+    owners.add(owner);
+    void run(owner);
+  }
+
+  const own = (entry, owner) => entry && entry.localAddress === owner.gateway.localAddress
+    && entry.port === owner.port && entry.description === owner.description;
+
+  async function cleanup(owner) {
+    if (!owner.attempted || !owner.gateway) return;
+    const controller = new AbortController();
+    owner.cleanupTimer = setTimeout(() => controller.abort(), cleanupMs);
+    try {
+      const entry = await owner.gateway.read(owner.externalPort, controller.signal);
+      if (entry === null) { owner.cleanup = 'absent'; return; }
+      if (!own(entry, owner)) { owner.cleanup = 'ownership-changed'; return; }
+      await owner.gateway.remove(owner.externalPort, controller.signal);
+      owner.cleanup = await owner.gateway.read(owner.externalPort, controller.signal) === null ? 'removed' : 'unconfirmed';
+    } catch { owner.cleanup = 'unconfirmed'; }
+    finally {
+      clearTimeout(owner.cleanupTimer);
+      owner.cleanupTimer = null;
+      if (owner.cleanup === 'unconfirmed') cleanupUnconfirmed += 1;
+    }
+  }
+
+  async function run(owner) {
+    attempts += 1;
+    const signal = owner.controller.signal;
+    owner.setupTimer = setTimeout(() => {
+      owner.state = 'setup-expired';
+      owner.controller.abort();
+    }, setupMs);
+    try {
+      owner.gateway = await discover(signal);
+      signal.throwIfAborted();
+      const range = owner.portRange;
+      const requestedPort = range?.portRangeBegin || 0;
+      const lastPort = range?.portRangeEnd || requestedPort;
+      if (!Number.isInteger(requestedPort) || !Number.isInteger(lastPort)
+        || requestedPort < 0 || (requestedPort > 0 && requestedPort < 1024)
+        || (requestedPort === 0 && lastPort !== 0)
+        || lastPort < requestedPort || lastPort > 65535 || lastPort - requestedPort >= 64) {
+        throw new Error('router-port-range-invalid');
+      }
+      for (let port = requestedPort; port <= lastPort; port++) {
+        try { owner.socket = await reserveSocket(owner.gateway, signal, port); break; }
+        catch (error) { if (error?.code !== 'EADDRINUSE' || port === lastPort) throw error; }
+      }
+      signal.throwIfAborted();
+      owner.port = owner.socket.port;
+      owner.externalPort = owner.socket.port;
+      owner.reservation = `${owner.gateway.address}:${owner.externalPort}`;
+      if (reservedPorts.has(owner.reservation)) { owner.state = 'port-busy'; return; }
+      reservedPorts.set(owner.reservation, owner);
+      if (await owner.gateway.read(owner.externalPort, signal) !== null) { owner.state = 'port-busy'; return; }
+      signal.throwIfAborted();
+      owner.attempted = true;
+      await owner.gateway.add(owner.externalPort, owner.port, owner.description, signal);
+      signal.throwIfAborted();
+      const accepted = await owner.gateway.read(owner.externalPort, signal);
+      if (!own(accepted, owner) || !accepted.enabled || !Number.isInteger(accepted.leaseSeconds)
+        || accepted.leaseSeconds < 1 || accepted.leaseSeconds > bounds.leaseSeconds) {
+        owner.state = 'lease-rejected';
+        return;
+      }
+      owner.state = 'mapped';
+      mapped += 1;
+      owner.resolveReady({ port: owner.port });
+      await untilAborted(signal);
+    } catch {
+      if (!signal.aborted) owner.state = 'unavailable';
+    } finally {
+      owner.resolveReady();
+      clearTimeout(owner.setupTimer);
+      owner.setupTimer = null;
+      await cleanup(owner);
+      await owner.socket?.close();
+      owner.socket = null;
+      finish(owner);
+    }
+  }
+
+  function createOwner(key, { portRange, queue = false } = {}) {
+    if (!enabled() || (owners.size >= bounds.owners && (!queue || waiting.size >= bounds.queuedOwners)) || typeof key !== 'string'
+      || !/^[a-f0-9-]{36}:[a-f0-9-]{36}:\d{1,12}$/i.test(key)) return null;
+    const owner = { key, historyEpoch, portRange, socket: null, state: 'discovering', cleanup: 'not-needed', finished: false,
+      controller: new AbortController(), description: `VuvoDesk-ICE-${randomUUID()}`,
+      candidates: [], gateway: null, port: 0, reservation: '', attempted: false,
+      setupTimer: null, cleanupTimer: null, promise: null, startedAt: Date.now() };
+    const ready = new Promise(resolve => { owner.resolveReady = resolve; });
+    owner.promise = new Promise(resolve => { owner.resolveDone = resolve; });
+    const release = () => {
+      if (owner.finished) return owner.promise || Promise.resolve();
+      owner.state = 'released';
+      owner.controller.abort();
+      owner.resolveReady();
+      if (!owners.has(owner)) { waiting.delete(owner); finish(owner); }
+      return owner.promise || Promise.resolve();
+    };
+    owner.release = release;
+    if (owners.size < bounds.owners) start(owner);
+    else { owner.state = 'queued'; waiting.add(owner); }
+    return Object.freeze({
+      ready,
+      async handoff() {
+        await owner.socket?.close();
+        owner.socket = null;
+        if (owner.controller.signal.aborted || owner.finished) return null;
+        return owner.state === 'mapped' ? { port: owner.port } : null;
+      },
+      observe(value) {
+        if (owner.finished || owner.controller.signal.aborted || !enabled() || owner.state !== 'mapped') return;
+        const candidate = parseRouterMappingCandidate(value);
+        if (!candidate || owner.candidates.length >= bounds.candidates
+          || owner.candidates.some(c => c.type === candidate.type && c.address === candidate.address && c.port === candidate.port)) return;
+        owner.candidates.push(candidate);
+        if (candidate.type === 'srflx'
+          && (candidate.address !== owner.gateway?.publicAddress || candidate.port !== owner.externalPort)) {
+          owner.state = 'candidate-mismatch';
+          owner.controller.abort();
+        }
+      },
+      release
+    });
+  }
+
+  return Object.freeze({
+    createOwner,
+    releaseAll: ({ forgetHistory = false } = {}) => {
+      if (forgetHistory) { historyEpoch += 1; history.length = 0; }
+      // Remove waiting owners before releasing active slots: a shutdown must
+      // never start a queued router operation while draining the active ones.
+      const pending = [...waiting];
+      waiting.clear();
+      return Promise.all([...pending, ...owners].map(owner => owner.release()));
+    },
+    inspect: () => ({ enabled: Boolean(enabled()), activeOwners: owners.size, queuedOwners: waiting.size,
+      activeMappings: [...owners].filter(owner => owner.state === 'mapped').length,
+      pendingOperations: [...owners].filter(owner => owner.promise).length,
+      resourceTimers: [...owners].reduce((n, owner) => n + Number(!!owner.setupTimer) + Number(!!owner.cleanupTimer), 0),
+      resourceSockets: [...owners].filter(owner => owner.socket).length,
+      attempts, mapped, cleanupUnconfirmed, recent: history.map(value => ({ ...value })) })
+  });
+}