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