@livedesk/hub 0.1.74 → 0.1.76

package/src/console-router-mapping.test.mjs

@@ -0,0 +1,323 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { setTimeout as delay } from 'node:timers/promises';
+import { createConsoleRouterMapping, parseRouterMappingCandidate } from './console-router-mapping.mjs';
+import { parseDefaultRouterRoute, parseUpnpService, routerUrl, createUpnpSoapGateway, reserveConsoleIceSocket } from './console-upnp-gateway.mjs';
+import { createConsoleIceSetupGate } from './console-ice-setup-gate.mjs';
+
+const key = n => `11111111-1111-4111-8111-111111111111:22222222-2222-4222-8222-222222222222:${n}`;
+const reflected = (port = 54443) => `candidate:2 1 UDP 123 8.8.8.8 ${port} typ srflx raddr 0.0.0.0 rport 0`;
+function observe(handle, port = 54443) { handle.observe(candidate(port)); handle.observe(reflected(port)); }
+const candidate = (port = 54443, address = '192.168.0.4') => `candidate:1 1 UDP 123 ${address} ${port} typ host`;
+async function waitFor(condition) {
+  const end = Date.now() + 1000;
+  while (!condition() && Date.now() < end) await delay(2);
+  assert.ok(condition(), 'condition did not settle');
+}
+function fixture(extra = {}) {
+  const entries = new Map();
+  const calls = [];
+  const gateway = {
+    address: '192.168.0.1', localAddress: '192.168.0.4', publicAddress: '8.8.8.8',
+    async read(port) { calls.push(['read', port]); return entries.get(port) || null; },
+    async add(port, internalPort, description) {
+      calls.push(['add', port]);
+      entries.set(port, { port: internalPort, description, localAddress: gateway.localAddress, enabled: true, leaseSeconds: 120 });
+    },
+    async remove(port) { calls.push(['remove', port]); entries.delete(port); },
+    ...extra
+  };
+  let nextPort = 54443;
+  const manager = createConsoleRouterMapping({ isEnabled: () => true, discover: async () => gateway,
+    reserveSocket: async () => ({ port: nextPort++, async close() {} }) });
+  return { entries, calls, gateway, manager };
+}
+
+test('mapping is opt-in and only accepts private host UDP candidates on unprivileged ports', async () => {
+  let calls = 0;
+  const disabled = createConsoleRouterMapping({ discover: async () => { calls++; } });
+  assert.equal(disabled.createOwner(key(1)), null);
+  assert.equal(calls, 0);
+  for (const value of [candidate(80), candidate(70000), candidate(5000, '203.0.113.2'),
+    candidate().replace('UDP', 'TCP'), candidate().replace('typ host', 'typ srflx'),
+    candidate().replace('typ host', 'typ relay'), 'x'.repeat(4097)]) assert.equal(parseRouterMappingCandidate(value), null);
+  assert.deepEqual(parseRouterMappingCandidate(candidate()), { type: 'host', address: '192.168.0.4', port: 54443, relatedPort: 0 });
+});
+
+test('exact concurrent owners release only their own actual candidate ports, with no renewal', async () => {
+  const { entries, calls, manager } = fixture();
+  const a = manager.createOwner(key(1)), b = manager.createOwner(key(2));
+  try {
+    observe(a); observe(b, 54444);
+    await waitFor(() => manager.inspect().activeMappings === 2);
+    await a.release();
+    a.observe(candidate(54445)); // stale callback after cleanup cannot restart work
+    assert.equal(entries.has(54443), false);
+    assert.equal(entries.has(54444), true);
+    assert.equal(calls.filter(c => c[0] === 'add').length, 2);
+    assert.equal(manager.inspect().activeMappings, 1);
+  } finally { await manager.releaseAll(); }
+  assert.equal(entries.size, 0);
+  assert.equal(manager.inspect().activeOwners, 0);
+  assert.equal(manager.inspect().resourceTimers, 0);
+  assert.doesNotMatch(JSON.stringify(manager.inspect()), /192\.168|VuvoDesk-ICE-/);
+});
+
+test('media setup waits for one of four router slots and cancellation cannot start stale work', async () => {
+  const { manager, calls } = fixture();
+  const active = Array.from({length:4}, (_,n)=>manager.createOwner(key(n+1)));
+  try {
+    await Promise.all(active.map(owner=>owner.ready));
+    const queued = manager.createOwner(key(5), {queue:true});
+    const cancelled = manager.createOwner(key(6), {queue:true});
+    assert.equal(manager.inspect().activeOwners,4);
+    assert.equal(manager.inspect().queuedOwners,2);
+    assert.equal(manager.inspect().resourceSockets,4);
+    assert.equal(manager.createOwner(key(7)),null, 'legacy caller still has four immediate slots');
+    await cancelled.release();
+    await active[0].release();
+    await queued.ready;
+    assert.equal(manager.inspect().activeOwners,4);
+    assert.equal(manager.inspect().queuedOwners,0);
+    assert.equal(calls.filter(call=>call[0]==='add').length,5);
+  } finally { await manager.releaseAll(); }
+  assert.equal(manager.inspect().activeOwners,0);
+  assert.equal(manager.inspect().resourceSockets,0);
+  assert.equal(manager.inspect().resourceTimers,0);
+});
+
+test('queued setup is bounded and closing the family starts no queued router operations', async () => {
+  const { manager, calls } = fixture();
+  const active=Array.from({length:4},(_,n)=>manager.createOwner(key(n+1)));
+  await Promise.all(active.map(owner=>owner.ready));
+  for(let n=0;n<64;n++) assert.ok(manager.createOwner(key(n+5),{queue:true}));
+  assert.equal(manager.createOwner(key(100),{queue:true}),null);
+  await manager.releaseAll();
+  assert.equal(calls.filter(call=>call[0]==='add').length,4);
+  assert.equal(manager.inspect().queuedOwners,0);
+  assert.equal(manager.inspect().activeOwners,0);
+  assert.equal(manager.inspect().resourceTimers,0);
+});
+
+test('existing mappings and changed ownership are never overwritten or deleted', async () => {
+  const { entries, calls, manager } = fixture();
+  const foreign = { port: 54443, localAddress: '192.168.0.9', description: 'another-program', leaseSeconds: 0 };
+  entries.set(54443, foreign);
+  observe(manager.createOwner(key(1)));
+  await waitFor(() => manager.inspect().activeOwners === 0);
+  assert.deepEqual(calls, [['read', 54443]]);
+  assert.equal(entries.get(54443), foreign);
+  const a = manager.createOwner(key(2)); observe(a, 54444);
+  await waitFor(() => manager.inspect().activeMappings === 1);
+  entries.set(54444, { ...foreign, port: 54444 });
+  await a.release();
+  assert.equal(calls.some(c => c[0] === 'remove'), false);
+  assert.equal(manager.inspect().recent.at(-1).cleanup, 'ownership-changed');
+});
+
+test('a reserved port is mapped before native candidates can start STUN', async () => {
+  const f = fixture();
+  const a = f.manager.createOwner(key(1));
+  await a.ready;
+  assert.equal(f.entries.get(54443).port, 54443);
+  assert.deepEqual(await a.handoff(), { port: 54443 });
+  a.observe(candidate()); a.observe(reflected());
+  await a.release();
+  assert.deepEqual(f.calls.filter(c => c[0] === 'remove'), [['remove', 54443]]);
+});
+
+test('workspace cleanup suppresses late history and cancels a stalled discovery', async () => {
+  const manager = createConsoleRouterMapping({ isEnabled: () => true,
+    discover: signal => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true })) });
+  const a = manager.createOwner(key(1)); observe(a);
+  await manager.releaseAll({ forgetHistory: true });
+  assert.equal(manager.inspect().activeOwners, 0);
+  assert.equal(manager.inspect().pendingOperations, 0);
+  assert.equal(manager.inspect().resourceTimers, 0);
+  assert.deepEqual(manager.inspect().recent, []);
+});
+
+test('rejected permanent leases are removed and an expired entry is not renewed', async () => {
+  const f = fixture();
+  const originalAdd = f.gateway.add;
+  f.gateway.add = async (...args) => { await originalAdd(...args); f.entries.get(args[0]).leaseSeconds = 0; };
+  observe(f.manager.createOwner(key(1)));
+  await waitFor(() => f.manager.inspect().activeOwners === 0);
+  assert.equal(f.entries.size, 0);
+  assert.equal(f.manager.inspect().recent[0].state, 'lease-rejected');
+  f.gateway.add = originalAdd;
+  const a = f.manager.createOwner(key(2)); observe(a);
+  await waitFor(() => f.manager.inspect().activeMappings === 1);
+  f.entries.clear(); // ipTIME can expire a lease; setup owner does not renew it
+  await a.release();
+  assert.equal(f.manager.inspect().recent.at(-1).cleanup, 'absent');
+  assert.equal(f.calls.filter(c => c[0] === 'add').length, 2);
+});
+
+test('cancellation after an in-flight add removes a late mapping before the slot is reusable', async () => {
+  let completeAdd;
+  const f = fixture();
+  const originalAdd = f.gateway.add;
+  f.gateway.add = (...args) => new Promise(resolve => { completeAdd = async () => { await originalAdd(...args); resolve(); }; });
+  const a = f.manager.createOwner(key(1)); observe(a);
+  await waitFor(() => !!completeAdd);
+  const closing = a.release();
+  assert.equal(f.manager.inspect().activeOwners, 1);
+  await completeAdd(); await closing;
+  assert.equal(f.entries.size, 0);
+  assert.equal(f.manager.inspect().resourceTimers, 0);
+  assert.equal(f.manager.inspect().recent[0].cleanup, 'removed');
+});
+
+test('stalled socket reservation expires with zero mutations, and bounds remain exact', async () => {
+  const f = fixture();
+  const manager = createConsoleRouterMapping({ isEnabled: () => true, discover: async () => f.gateway, setupMs: 15,
+    reserveSocket: (_route, signal) => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(new Error('cancelled')), { once: true })) });
+  const handles = [1, 2, 3, 4].map(n => manager.createOwner(key(n)));
+  assert.equal(manager.createOwner(key(5)), null);
+  handles.forEach(h => h.observe(candidate(5000, '10.0.0.2')));
+  await waitFor(() => manager.inspect().activeOwners === 0);
+  assert.equal(f.calls.length, 0);
+  assert.equal(manager.inspect().resourceTimers, 0);
+  assert.equal(manager.inspect().recent[0].state, 'setup-expired');
+  for (let n = 10; n < 30; n++) await manager.createOwner(key(n)).release();
+  assert.equal(manager.inspect().recent.length, 8);
+});
+
+test('route parsing uses only the current local interface and pins every URL to that gateway', () => {
+  const interfaces = { en0: [{ family: 'IPv4', internal: false, address: '192.168.0.4' }] };
+  const expected = { address: '192.168.0.1', localAddress: '192.168.0.4' };
+  assert.deepEqual(parseDefaultRouterRoute('win32', '{"gateway":"192.168.0.1","address":"192.168.0.4"}', interfaces), expected);
+  assert.deepEqual(parseDefaultRouterRoute('linux', '[{"gateway":"192.168.0.1","prefsrc":"192.168.0.4"}]', interfaces), expected);
+  assert.deepEqual(parseDefaultRouterRoute('darwin', 'gateway: 192.168.0.1\ninterface: en0', interfaces), expected);
+  assert.throws(() => parseDefaultRouterRoute('win32', '{"gateway":"192.168.0.1","address":"192.168.0.8"}', interfaces));
+  for (const url of ['http://127.0.0.1/', 'https://192.168.0.1/', 'http://other.invalid/', 'http://user@192.168.0.1/']) {
+    assert.throws(() => routerUrl(url, expected.address));
+  }
+  const doc = '<service><serviceType>urn:schemas-upnp-org:service:WANIPConnection:1</serviceType><controlURL>/control</controlURL></service>';
+  assert.equal(parseUpnpService(doc, 'http://192.168.0.1/desc', expected.address).control.href, 'http://192.168.0.1/control');
+  assert.throws(() => parseUpnpService(doc.replace('/control', 'http://127.0.0.1/'), 'http://192.168.0.1/desc', expected.address));
+  assert.throws(() => parseUpnpService('<!DOCTYPE anything>' + doc, 'http://192.168.0.1/desc', expected.address));
+});
+
+test('SOAP reports absence only for 714, sends a temporary UDP lease, and bounds responses', async () => {
+  const requests = [];
+  let body = '<errorCode>714</errorCode>', status = 500;
+  const gateway = createUpnpSoapGateway({ address: '192.168.0.1', localAddress: '192.168.0.4' },
+    { control: new URL('http://192.168.0.1/control'), service: 'urn:schemas-upnp-org:service:WANIPConnection:1' },
+    async (url, options) => { requests.push(options); return new Response(body, { status }); });
+  const signal = new AbortController().signal;
+  assert.equal(await gateway.read(54443, signal), null);
+  body = '<errorCode>401</errorCode>';
+  await assert.rejects(gateway.read(54443, signal), /router-request-rejected/);
+  status = 200; body = '<u:AddPortMappingResponse/>';
+  await gateway.add(54443, 50000, 'fixture', signal);
+  assert.match(requests.at(-1).body, /<NewInternalPort>50000<\/NewInternalPort>/);
+  assert.match(requests.at(-1).body, /<NewProtocol>UDP<\/NewProtocol>/);
+  assert.match(requests.at(-1).body, /<NewLeaseDuration>120<\/NewLeaseDuration>/);
+  assert.equal(requests.at(-1).redirect, 'error');
+  body = 'x'.repeat(8193);
+  await assert.rejects(gateway.read(54443, signal), /router-response-too-large/);
+});
+
+test('trickled candidates wait in order for native setup and duplicates consume no extra reservation', () => {
+  const gate = createConsoleIceSetupGate();
+  const lan = candidate(50000);
+  const publicCandidate = reflected(55000);
+  const ipv6 = 'candidate:3 1 UDP 123 2001:4860::1 50000 typ host';
+  assert.equal(gate.defer(lan, '0'), true);
+  assert.equal(gate.defer(publicCandidate, '0'), true);
+  assert.equal(gate.defer(publicCandidate, '0'), true);
+  assert.equal(gate.defer(ipv6, '0'), true);
+  assert.equal(gate.inspect().candidates, 3);
+  const applied = [];
+  gate.flush((...args) => applied.push(args), () => true);
+  assert.deepEqual(applied, [[lan, '0'], [publicCandidate, '0'], [ipv6, '0']]);
+  assert.equal(gate.defer(publicCandidate, '0'), false);
+  assert.equal(gate.inspect().candidates, 0);
+});
+
+test('setup candidate bounds and closed/replaced-owner cleanup retain no deferred callbacks', () => {
+  const gate = createConsoleIceSetupGate();
+  for (let i = 0; i < 16; i++) gate.defer(reflected(50000 + i), '0');
+  assert.equal(gate.defer(reflected(50000), '0'), true);
+  assert.throws(() => gate.defer(reflected(50016), '0'), /candidate-invalid/);
+  const applied = [];
+  gate.flush(value => applied.push(value), () => applied.length === 0);
+  assert.equal(applied.length, 1);
+  assert.equal(gate.inspect().candidates, 0);
+  const cancelled = createConsoleIceSetupGate();
+  cancelled.defer(reflected(), '0'); cancelled.close();
+  cancelled.flush(() => assert.fail('retired candidate applied'), () => true);
+  assert.deepEqual(cancelled.inspect(), { waiting: false, candidates: 0 });
+});
+
+test('setup readiness resolves at accepted mapping or cancellation without waiting for lease expiry', async () => {
+  const f = fixture();
+  const a = f.manager.createOwner(key(1));
+  observe(a);
+  await a.ready;
+  assert.equal(f.manager.inspect().activeMappings, 1);
+  await a.release();
+  const b = f.manager.createOwner(key(2));
+  await b.release(); await b.ready;
+  assert.equal(f.manager.inspect().activeOwners, 0);
+});
+
+test('native preconnect reserves a vacant socket before mapping and hands it off exactly once', async () => {
+  const f = fixture();
+  let socketOpen = false, closes = 0;
+  const manager = createConsoleRouterMapping({ isEnabled: () => true, discover: async () => f.gateway,
+    reserveSocket: async () => {
+      socketOpen = true;
+      return { port: 53000, async close() { if (socketOpen) closes++; socketOpen = false; } };
+    } });
+  const a = manager.createOwner(key(10), { preconnect: true });
+  assert.deepEqual(await a.ready, { port: 53000 });
+  assert.equal(socketOpen, true);
+  assert.equal(f.entries.get(53000).port, 53000);
+  assert.deepEqual(await a.handoff(), { port: 53000 });
+  assert.equal(socketOpen, false);
+  assert.equal(manager.inspect().resourceSockets, 0);
+  a.observe(candidate(53000)); a.observe(reflected(53000));
+  await a.release();
+  assert.equal(f.entries.size, 0);
+  assert.equal(closes, 1);
+  assert.equal(manager.inspect().resourceTimers, 0);
+});
+
+test('preconnect cancellation drains its reserved socket and a changed STUN port removes its mapping', async () => {
+  const f = fixture();
+  let closed = 0;
+  const manager = createConsoleRouterMapping({ isEnabled: () => true, discover: async () => f.gateway,
+    reserveSocket: async () => ({ port: 53000, async close() { closed++; } }) });
+  const a = manager.createOwner(key(1), { preconnect: true });
+  await a.ready; await a.release();
+  assert.equal(closed, 1);
+  assert.equal(f.entries.size, 0);
+  const b = manager.createOwner(key(2), { preconnect: true });
+  await b.ready; await b.handoff();
+  b.observe(reflected(53001));
+  await waitFor(() => manager.inspect().activeOwners === 0);
+  assert.equal(f.entries.size, 0);
+  assert.equal(manager.inspect().recent.at(-1).state, 'candidate-mismatch');
+});
+
+test('real UDP reservations release on handoff, collision and cancellation during bind', async () => {
+  const udpCount = () => process.getActiveResourcesInfo().filter(name => name === 'UDPWrap').length;
+  const baseline = udpCount();
+  const route = { localAddress: '127.0.0.1' };
+  const controller = new AbortController();
+  const socket = await reserveConsoleIceSocket(route, controller.signal);
+  try {
+    assert.ok(socket.port >= 1024 && socket.port <= 65535);
+    await assert.rejects(reserveConsoleIceSocket(route, controller.signal, socket.port), { code: 'EADDRINUSE' });
+  } finally { await socket.close(); await socket.close(); }
+  const successor = await reserveConsoleIceSocket(route, controller.signal, socket.port);
+  await successor.close();
+  const cancelled = new AbortController();
+  const pending = reserveConsoleIceSocket(route, cancelled.signal);
+  cancelled.abort();
+  await assert.rejects(pending, /router-socket-reservation-unavailable/);
+  await waitFor(() => udpCount() === baseline);
+});

package/src/console-upnp-gateway.mjs

@@ -0,0 +1,230 @@
+import dgram from 'node:dgram';
+import { execFile } from 'node:child_process';
+import { networkInterfaces, platform } from 'node:os';
+import { isIP } from 'node:net';
+
+export function isPrivateRouterIPv4(address) {
+  if (isIP(address) !== 4) return false;
+  const [a, b] = address.split('.').map(Number);
+  return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+}
+
+export function isPublicRouterIPv4(address) {
+  if (isIP(address) !== 4 || isPrivateRouterIPv4(address)) return false;
+  const [a, b, c] = address.split('.').map(Number);
+  return a > 0 && a < 224 && a !== 127 && !(a === 169 && b === 254)
+    && !(a === 100 && b >= 64 && b <= 127)
+    && !(a === 192 && b === 0 && [0, 2].includes(c))
+    && !(a === 198 && [18, 19, 51].includes(b)) && !(a === 203 && b === 0 && c === 113);
+}
+
+function command(file, args, signal) {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { signal, timeout: 1800, maxBuffer: 16 * 1024, windowsHide: true },
+      (error, stdout) => error ? reject(new Error('router-route-unavailable')) : resolve(stdout));
+  });
+}
+
+export function parseDefaultRouterRoute(os, output, interfaces = networkInterfaces()) {
+  let address, localAddress;
+  if (os === 'win32') {
+    const data = JSON.parse(output);
+    address = data.gateway;
+    localAddress = data.address;
+  } else if (os === 'linux') {
+    const data = JSON.parse(output)?.[0];
+    address = data?.gateway;
+    localAddress = data?.prefsrc;
+  } else if (os === 'darwin') {
+    address = output.match(/^\s*gateway:\s*(\S+)\s*$/m)?.[1];
+    const device = output.match(/^\s*interface:\s*(\S+)\s*$/m)?.[1];
+    localAddress = interfaces[device]?.find(item => item.family === 'IPv4' && !item.internal)?.address;
+  }
+  const local = Object.values(interfaces).flat().some(item => (
+    item?.family === 'IPv4' && !item.internal && item.address === localAddress
+  ));
+  if (!local || !isPrivateRouterIPv4(address) || !isPrivateRouterIPv4(localAddress)) {
+    throw new Error('router-route-unavailable');
+  }
+  return { address, localAddress };
+}
+
+async function resolveRoute(signal) {
+  const os = platform();
+  let output;
+  if (os === 'win32') {
+    // Fixed command, no caller text or shell interpolation. Find-NetRoute reads
+    // the selected route; it sends no traffic to this reference destination.
+    output = await command('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+      "$r = Find-NetRoute -RemoteIPAddress 1.1.1.1; $a = $r | Where-Object { $_.IPAddress } | Select-Object -First 1; $g = $r | Where-Object { $_.NextHop } | Select-Object -First 1; @{ address=$a.IPAddress; gateway=$g.NextHop } | ConvertTo-Json -Compress"], signal);
+  } else if (os === 'linux') output = await command('ip', ['-j', 'route', 'get', '1.1.1.1'], signal);
+  else if (os === 'darwin') output = await command('/sbin/route', ['-n', 'get', '1.1.1.1'], signal);
+  else throw new Error('router-platform-unavailable');
+  return parseDefaultRouterRoute(os, output);
+}
+
+export function routerUrl(value, gateway, base) {
+  const url = new URL(value, base);
+  if (url.protocol !== 'http:' || url.hostname !== gateway || url.username || url.password || url.hash) {
+    throw new Error('router-control-url-invalid');
+  }
+  return url;
+}
+
+async function discoverLocation(route, signal) {
+  signal.throwIfAborted();
+  const socket = dgram.createSocket('udp4');
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error, location) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener('abort', abort);
+      try { socket.close(); } catch { /* no bound UDP handle remains */ }
+      error ? reject(error) : resolve(location);
+    };
+    const abort = () => finish(new Error('router-discovery-cancelled'));
+    const timer = setTimeout(() => finish(new Error('router-discovery-unavailable')), 1200);
+    signal.addEventListener('abort', abort, { once: true });
+    socket.once('error', () => finish(new Error('router-discovery-unavailable')));
+    socket.on('message', (message, source) => {
+      if (source.address !== route.address || message.length > 8192) return;
+      const location = message.toString().match(/^location:\s*(\S+)\s*$/im)?.[1];
+      if (!location) return;
+      try { finish(null, routerUrl(location, route.address)); } catch { /* ignore unrelated SSDP */ }
+    });
+    socket.bind(0, route.localAddress, () => {
+      if (settled) return;
+      socket.setMulticastTTL(1);
+      socket.send(Buffer.from('M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\nMAN: "ssdp:discover"\r\nMX: 1\r\nST: urn:schemas-upnp-org:device:InternetGatewayDevice:1\r\n\r\n'),
+        1900, '239.255.255.250', error => { if (error) finish(new Error('router-discovery-unavailable')); });
+    });
+  });
+}
+
+export function upnpField(xml, name) {
+  return xml.match(new RegExp(`<(?:[\\w-]+:)?${name}\\b[^>]*>\\s*([^<]*)\\s*</(?:[\\w-]+:)?${name}>`))?.[1]?.trim();
+}
+
+async function boundedText(response, limit) {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error('router-response-invalid');
+  let bytes = 0;
+  const chunks = [];
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      bytes += next.value.byteLength;
+      if (bytes > limit) {
+        await reader.cancel().catch(() => {});
+        throw new Error('router-response-too-large');
+      }
+      chunks.push(next.value);
+    }
+    return Buffer.concat(chunks, bytes).toString('utf8');
+  } finally { reader.releaseLock(); }
+}
+
+export function parseUpnpService(document, location, gateway) {
+  if (document.length > 64 * 1024 || /<!DOCTYPE|<!ENTITY/i.test(document)) throw new Error('router-description-invalid');
+  const base = upnpField(document, 'URLBase') || location;
+  routerUrl(base, gateway);
+  for (const match of document.matchAll(/<(?:[\w-]+:)?service>([\s\S]*?)<\/(?:[\w-]+:)?service>/g)) {
+    const service = upnpField(match[1], 'serviceType');
+    const control = upnpField(match[1], 'controlURL');
+    if (/^urn:schemas-upnp-org:service:WAN(?:IP|PPP)Connection:[12]$/.test(service || '') && control) {
+      return { service, control: routerUrl(control, gateway, base) };
+    }
+  }
+  throw new Error('router-service-unavailable');
+}
+
+export function createUpnpSoapGateway(route, endpoint, fetchImpl = fetch) {
+  const controlUrl = routerUrl(endpoint.control, route.address);
+  async function soap(action, fields, signal) {
+    signal.throwIfAborted();
+    const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
+    const xml = Object.entries(fields).map(([key, value]) => `<${key}>${escape(value)}</${key}>`).join('');
+    const response = await fetchImpl(controlUrl, {
+      method: 'POST', redirect: 'error', signal,
+      headers: { 'Content-Type': 'text/xml; charset="utf-8"', SOAPAction: `"${endpoint.service}#${action}"` },
+      body: `<?xml version="1.0"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><s:Body><u:${action} xmlns:u="${endpoint.service}">${xml}</u:${action}></s:Body></s:Envelope>`
+    });
+    const body = await boundedText(response, 8192);
+    const error = Number(upnpField(body, 'errorCode') || 0);
+    if (error === 714 && action === 'GetSpecificPortMappingEntry') return null;
+    if (!response.ok || error || !body.includes(`${action}Response`)) throw new Error('router-request-rejected');
+    return body;
+  }
+  const identity = port => ({ NewRemoteHost: '', NewExternalPort: port, NewProtocol: 'UDP' });
+  return {
+    ...route,
+    async requirePublicWan(signal) {
+      const address = upnpField(await soap('GetExternalIPAddress', {}, signal), 'NewExternalIPAddress');
+      if (!isPublicRouterIPv4(address)) {
+        throw new Error('router-public-address-unavailable');
+      }
+      return address;
+    },
+    async read(port, signal) {
+      const body = await soap('GetSpecificPortMappingEntry', identity(port), signal);
+      return body === null ? null : {
+        localAddress: upnpField(body, 'NewInternalClient'),
+        port: Number(upnpField(body, 'NewInternalPort')),
+        description: upnpField(body, 'NewPortMappingDescription'),
+        leaseSeconds: Number(upnpField(body, 'NewLeaseDuration')),
+        enabled: upnpField(body, 'NewEnabled') === '1'
+      };
+    },
+    async add(port, internalPort, description, signal) {
+      await soap('AddPortMapping', { ...identity(port), NewInternalPort: internalPort,
+        NewInternalClient: route.localAddress, NewEnabled: 1,
+        NewPortMappingDescription: description, NewLeaseDuration: 120 }, signal);
+    },
+    async remove(port, signal) { await soap('DeletePortMapping', identity(port), signal); }
+  };
+}
+
+export async function discoverConsoleUpnpGateway(signal) {
+  const route = await resolveRoute(signal);
+  const location = await discoverLocation(route, signal);
+  const response = await fetch(location, { redirect: 'error', signal });
+  if (!response.ok) throw new Error('router-description-unavailable');
+  const endpoint = parseUpnpService(await boundedText(response, 64 * 1024), location, route.address);
+  const gateway = createUpnpSoapGateway(route, endpoint);
+  gateway.publicAddress = await gateway.requirePublicWan(signal);
+  return gateway;
+}
+
+// Reserve an OS-assigned socket before exposing a port at the router. The
+// caller closes this exact reservation immediately before native ICE binds it.
+export function reserveConsoleIceSocket(route, signal, port = 0) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const socket = dgram.createSocket('udp4');
+    let settled = false;
+    let closePromise;
+    const close = () => closePromise ||= new Promise(done => {
+      try { socket.close(done); } catch { done(); }
+    });
+    const failed = error => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', failed);
+      void close();
+      const failure = new Error('router-socket-reservation-unavailable');
+      if (error?.code === 'EADDRINUSE') failure.code = 'EADDRINUSE';
+      reject(failure);
+    };
+    socket.on('error', failed);
+    signal.addEventListener('abort', failed, { once: true });
+    socket.bind(port, route.localAddress, () => {
+      if (settled || signal.aborted) { void close(); return; }
+      settled = true;
+      signal.removeEventListener('abort', failed);
+      resolve({ port: socket.address().port, close });
+    });
+  });
+}

package/src/server.js

@@ -1880,6 +1880,9 @@ hubConsoleDirect = createHubConsoleDirect({
   deviceId: runtimeDeviceId,
   httpBaseUrl: `http://127.0.0.1:${httpPort}`,
   stunUrls: hubConsoleDirectStunUrls,
+  icePortRange: process.env.LIVEDESK_CONSOLE_ICE_PORT_RANGE,
+  isRouterMappingEnabled: () => runtimeRole === 'hub'
+    && liveDeskSettingsStore.getCached()?.connection?.temporaryRouterMapping === true,
   getAccessToken: () => getRuntimeAccessToken(),
   getWorkspaceAccess: () => runtimeWorkspaceAccess,
   consoleProxyToken
@@ -5152,7 +5155,10 @@ app.patch('/api/settings', async (req, res) => {
     const revision = body.revision === undefined ? undefined : Number(body.revision);
     const patch = { ...body };
     delete patch.revision;
-    const record = await liveDeskSettingsStore.update(patch, revision);
+    const record = await liveDeskSettingsStore.update(patch, revision);
+    if (patch.connection?.temporaryRouterMapping === false) {
+      await hubConsoleDirect?.releaseRouterMappings();
+    }
     if (patch.agent && Object.prototype.hasOwnProperty.call(patch.agent, 'enabled')) {
       await agentSettingsStore.update({ enabled: record.settings.agent?.enabled === true });
     }
@@ -7811,7 +7817,8 @@ function shutdownHub(signal) {
     forceCloseTimer.unref?.();
 
     const cleanupBudgetMs = Math.max(500, hubShutdownTimeoutMs - hubShutdownGraceMs - 500);
-    await Promise.all([
+    await Promise.all([
+      boundedShutdownStep('temporary router mappings removed', () => hubConsoleDirect?.releaseRouterMappings(), cleanupBudgetMs),
       boundedShutdownStep('atlas pool closed', () => atlasPool.close(), cleanupBudgetMs),
       boundedShutdownStep('host target lease cleared', () => clearHubHostTarget(`process-${String(signal).toLowerCase()}`), Math.min(3_000, cleanupBudgetMs)),
       boundedShutdownStep('remote transport closed', () => remoteHub.close(), cleanupBudgetMs)

package/src/settings/settings-schema.js

@@ -13,7 +13,8 @@ export const DEFAULT_LIVEDESK_SETTINGS = Object.freeze({
     approveNewDevices: true,
     startWithComputer: true,
     keepRunningInTray: true,
-    showConnectionNotifications: true,
+    showConnectionNotifications: true,
+    temporaryRouterMapping: false,
     showThisComputer: false
   },
   security: {
@@ -180,7 +181,7 @@ export function migrateLiveDeskSettings(value = {}) {
 
 const RULES = {
   connection: {
-    ...bools(['usePinToAddDevices', 'rotatePinAfterPairing', 'allowNewDevices', 'approveNewDevices', 'startWithComputer', 'keepRunningInTray', 'showConnectionNotifications', 'showThisComputer']),
+    ...bools(['usePinToAddDevices', 'rotatePinAfterPairing', 'allowNewDevices', 'approveNewDevices', 'startWithComputer', 'keepRunningInTray', 'showConnectionNotifications', 'temporaryRouterMapping', 'showThisComputer']),
     ...numbers([['pinValidityMinutes', 10, 1440]])
   },
   security: {