Commitbd1ef24dRecorded18 Oct 2026Repositorysigil-nat
Prepare one-probe UPnP mapping experiment
Changed
scripts/phantom-nat-check.sh | 3 +++
scripts/phantom-upnp-mapping-check.mjs | 2 +-
tools/nat/external-udp-probe-from-receipt.mjs | 16 ++++++++++++++++
tools/nat/external-udp-probe.mjs | 66 +++++++++++++++++++++++++++++++++++++++++-------------------------
tools/nat/test-upnp.mjs | 2 +-
tools/nat/upnp.mjs | 2 +-
6 files changed, 63 insertions(+), 28 deletions(-)Diff
scripts/phantom-nat-check.shmodified
@@ -10,6 +10,9 @@ record_result() {
10
trap record_result EXIT 11
printf 'RESULT operation=offline-tests-plus-read-only-inspection mapping-requests=0\n' | tee "$result" 12
timeout --foreground 30 node --test tools/nat/test-codecs.mjs tools/nat/test-upnp.mjs 2>&1 | tee build/nat/tests.log+13
node --check tools/nat/external-udp-probe.mjs+14
node --check tools/nat/external-udp-probe-from-receipt.mjs+15
node --check scripts/phantom-upnp-mapping-check.mjs 16
printf 'RESULT offline-tests=PASS\n' | tee -a "$result" 17
timeout --foreground 30 node scripts/phantom-nat-inspect.mjs | tee build/nat/inspection.log 18
printf 'RESULT read-only-inspection=COMPLETE mapping-requests=0\n' | tee -a "$result"scripts/phantom-upnp-mapping-check.mjsmodified
@@ -29,7 +29,7 @@ let echoCount = 0;
29
let deleted = false; 30
let responderTimer; 31
const receipt = { route, protocol: 'upnp-igd', internalPort, challenge: token.toString('hex'),−32
mappingRequests: 0, echoCount: 0, deleted: false, responderStopped: false,+32
processId: process.pid, mappingRequests: 0, echoCount: 0, deleted: false, responderStopped: false, 33
startedAt: new Date().toISOString() }; 34
const save = () => writeFileSync(resultPath, JSON.stringify(receipt, null, 2) + '\n', { mode: 0o600 }); 35
const finish = async () => {tools/nat/external-udp-probe-from-receipt.mjsadded
@@ -0,0 +1,16 @@
+1
import { readFileSync, writeFileSync } from 'node:fs';+2
import { runExternalUdpProbe } from './external-udp-probe.mjs';+3
+4
const mapping = JSON.parse(readFileSync('mapping-receipt.json', 'utf8'));+5
const receipt = await runExternalUdpProbe({ externalAddress: mapping.externalAddress,+6
externalPort: mapping.externalPort, challengeHex: mapping.challenge });+7
writeFileSync('probe-receipt.json', JSON.stringify(receipt, null, 2) + '\n', { mode: 0o600 });+8
if (!receipt.beforeDelete.echoed) {+9
console.log('RESULT outsideEcho=false postDeleteProbe=not-sent');+10
process.exitCode = 1;+11
} else if (!receipt.afterDelete.echoed) {+12
console.log('RESULT outsideEcho=true rttMs=' + receipt.beforeDelete.rttMs + ' postDeleteProbe=timeout');+13
} else {+14
console.log('RESULT outsideEcho=true rttMs=' + receipt.beforeDelete.rttMs + ' postDeleteProbe=echoed');+15
process.exitCode = 1;+16
}tools/nat/external-udp-probe.mjsmodified
@@ -1,21 +1,13 @@
−1
// Outside-network probe helper. Send only a fixed 32-byte challenge and echo.+1
// Outside-network probe helper: send a fixed 32-byte challenge and echo. 2
import { createSocket } from 'node:dgram'; 3
import { isIP } from 'node:net'; 4
import { writeFileSync } from 'node:fs';+5
import { resolve } from 'node:path'; 6
import { performance } from 'node:perf_hooks';+7
import { pathToFileURL } from 'node:url'; 8
−7
const [externalAddress, portText, challengeHex, receiptPath = 'probe-receipt.json'] = process.argv.slice(2);−8
const externalPort = Number(portText);−9
if (isIP(externalAddress) !== 4 || !Number.isInteger(externalPort) || externalPort < 1 || externalPort > 65535 ||−10
!/^[0-9a-f]{64}$/i.test(challengeHex ?? '')) throw new Error('Invalid UDP probe target/32-byte challenge');−11
const challenge = Buffer.from(challengeHex, 'hex');−12
const observation = await fetch('https://api.ipify.org', { signal: AbortSignal.timeout(3000) });−13
if (!observation.ok) throw new Error(`External address observation returned HTTP ${observation.status}`);−14
const observedAddress = (await observation.text()).trim();−15
if (isIP(observedAddress) !== 4) throw new Error('External address observation returned invalid IPv4');−16
−17
function probe(timeoutMs) {−18
return new Promise((resolve, reject) => {+9
function probe(externalAddress, externalPort, challenge, timeoutMs) {+10
return new Promise((resolveProbe, reject) => { 11
const socket = createSocket('udp4'); 12
const started = performance.now(); 13
let finished = false;@@ -23,8 +15,8 @@ function probe(timeoutMs) {
15
if (finished) return; 16
finished = true; 17
clearTimeout(timer);−26
socket.close();−27
if (error) reject(error); else resolve(value);+18
try { socket.close(); } catch {}+19
if (error) reject(error); else resolveProbe(value); 20
}; 21
const timer = setTimeout(() => finish(null, { echoed: false }), timeoutMs); 22
socket.on('error', error => finish(error));@@ -37,13 +29,37 @@ function probe(timeoutMs) {
29
}); 30
} 31
−40
const beforeDelete = await probe(3000);−41
let afterDelete;−42
if (!beforeDelete.echoed) throw new Error('Outside UDP echo did not arrive before deletion');−43
await new Promise(resolve => setTimeout(resolve, 8000));−44
afterDelete = await probe(2500);−45
const result = { targetAddress: externalAddress, observedAddress,−46
externalPort, beforeDelete, afterDelete, checkedAt: new Date().toISOString() };−47
writeFileSync(receiptPath, JSON.stringify(result, null, 2) + '\n', { mode: 0o600 });−48
if (afterDelete.echoed) throw new Error('UDP mapping still passed traffic after explicit deletion');−49
console.log(`RESULT outsideEcho=true rttMs=${beforeDelete.rttMs} postDeleteProbe=timeout`);+32
export async function runExternalUdpProbe({ externalAddress, externalPort, challengeHex }) {+33
if (isIP(externalAddress) !== 4 || !Number.isInteger(externalPort) ||+34
externalPort < 1 || externalPort > 65535 || !/^[0-9a-f]{64}$/i.test(challengeHex || ''))+35
throw new Error('Invalid UDP probe target/32-byte challenge');+36
const observation = await fetch('https://api.ipify.org', { signal: AbortSignal.timeout(3000) });+37
if (!observation.ok) throw new Error('External address observation failed');+38
const observedAddress = (await observation.text()).trim();+39
if (isIP(observedAddress) !== 4) throw new Error('External address observation returned invalid IPv4');+40
const challenge = Buffer.from(challengeHex, 'hex');+41
const beforeDelete = await probe(externalAddress, externalPort, challenge, 3000);+42
if (!beforeDelete.echoed) {+43
return { targetAddress: externalAddress, observedAddress, externalPort, beforeDelete,+44
afterDelete: { echoed: false, skipped: true }, checkedAt: new Date().toISOString() };+45
}+46
await new Promise(resolveWait => setTimeout(resolveWait, 8000));+47
const afterDelete = await probe(externalAddress, externalPort, challenge, 2500);+48
return { targetAddress: externalAddress, observedAddress, externalPort,+49
beforeDelete, afterDelete, checkedAt: new Date().toISOString() };+50
}+51
+52
if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {+53
const [externalAddress, portText, challengeHex, receiptPath = 'probe-receipt.json'] = process.argv.slice(2);+54
const result = await runExternalUdpProbe({ externalAddress, externalPort: Number(portText), challengeHex });+55
writeFileSync(receiptPath, JSON.stringify(result, null, 2) + '\n', { mode: 0o600 });+56
if (!result.beforeDelete.echoed) {+57
console.log('RESULT outsideEcho=false postDeleteProbe=not-sent');+58
process.exitCode = 1;+59
} else if (!result.afterDelete.echoed) {+60
console.log('RESULT outsideEcho=true rttMs=' + result.beforeDelete.rttMs + ' postDeleteProbe=timeout');+61
} else {+62
console.log('RESULT outsideEcho=true rttMs=' + result.beforeDelete.rttMs + ' postDeleteProbe=echoed');+63
process.exitCode = 1;+64
}+65
}tools/nat/test-upnp.mjsmodified
@@ -41,7 +41,7 @@ test('UPnP mapping candidate probes only free ports and verifies its owner befor
41
const candidate = upnpUdpCandidate(client, { internalPort: 43123, internalClient: '192.0.2.44', 42
externalAddress: '198.51.100.4', randomPort: () => 51000 }); 43
const active = await candidate.exchange(120);−44
assert.equal(active.externalPort, 51000);+44
assert.equal(active.externalPort, 43123); 45
assert.equal(active.lifetime, 120); 46
const deleted = await candidate.exchange(0, active); 47
assert.equal(deleted.lifetime, 0);tools/nat/upnp.mjsmodified
@@ -263,7 +263,7 @@ export function upnpUdpCandidate(client, { internalPort, internalClient, externa
263
async exchange(lifetime, previous) { 264
requireValue(Number.isInteger(lifetime) && lifetime >= 0 && lifetime <= 1800, 265
'UPnP lease must be within 30 minutes');−266
const port = previous?.externalPort ?? ownedPort ?? randomPort();+266
const port = previous?.externalPort ?? ownedPort ?? internalPort; 267
ownedPort = port; 268
if (lifetime === 0) { 269
const entry = await verifyOwned(port, false);