Commit2a507e89Recorded18 Oct 2026Repositorysigil-nat
Make one-probe mapping teardown idempotent and measure CGNAT on Phantom
Changed
scripts/phantom-nat-check.sh | 2 +-
scripts/phantom-upnp-mapping-check.mjs | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------------------------------------------------
tools/nat/external-udp-probe.mjs | 26 ++++++++++++------------
3 files changed, 114 insertions(+), 83 deletions(-)Diff
scripts/phantom-nat-check.shmodified
@@ -9,7 +9,7 @@ record_result() {
9
} 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+12
timeout --foreground 30 node --test tools/nat/test-codecs.mjs tools/nat/test-upnp.mjs tools/nat/test-lease.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.mjsscripts/phantom-upnp-mapping-check.mjsmodified
@@ -1,13 +1,15 @@
−1
// One short, owned UPnP UDP mapping with explicit deletion after one echo.+1
// One <=120-second lease, one challenge echo, explicit 714 verification. 2
import { randomBytes } from 'node:crypto'; 3
import { hostname } from 'node:os'; 4
import { createSocket } from 'node:dgram'; 5
import { mkdirSync, writeFileSync } from 'node:fs'; 6
import { once } from 'node:events';−7
import { gatewayRoute, discoverGateway } from '../tools/nat/discovery.mjs';+7
import { isIP } from 'node:net';+8
import { gatewayRoute } from '../tools/nat/discovery.mjs'; 9
import { discoverIgd } from '../tools/nat/igd-discovery.mjs'; 10
import { UpnpIgdClient, upnpUdpCandidate } from '../tools/nat/upnp.mjs'; 11
import { SingleUdpLease } from '../tools/nat/lease.mjs';+12
import { closeUdpSocket } from '../tools/nat/socket-cleanup.mjs'; 13
14
if (!process.env.NAT_EXPECTED_HOST || hostname() !== process.env.NAT_EXPECTED_HOST) 15
throw new Error('Set NAT_EXPECTED_HOST to the intended network host');@@ -17,105 +19,134 @@ if (!process.env.NAT_EXPECTED_GATEWAY || !process.env.NAT_EXPECTED_LOCAL_ADDRESS
19
route.localAddress !== process.env.NAT_EXPECTED_LOCAL_ADDRESS) 20
throw new Error('Set NAT_EXPECTED_GATEWAY and NAT_EXPECTED_LOCAL_ADDRESS to the intended route'); 21
−20
const resultPath = 'build/nat/mapping-receipt.json'; 22
mkdirSync('build/nat', { recursive: true });+23
const resultPath = 'build/nat/mapping-receipt.json'; 24
const token = randomBytes(32); 25
const responder = createSocket('udp4');−24
responder.bind(0, route.localAddress);−25
await once(responder, 'listening');−26
const internalPort = responder.address().port;−27
let lease;−28
let echoCount = 0;−29
let deleted = false;−30
let responderTimer;−31
const receipt = { route, protocol: 'upnp-igd', internalPort, challenge: token.toString('hex'),+26
const abort = new AbortController();+27
const receipt = { route, protocol: 'upnp-igd', challenge: token.toString('hex'), 28
processId: process.pid, mappingRequests: 0, echoCount: 0, deleted: false, responderStopped: false, 29
startedAt: new Date().toISOString() }; 30
const save = () => writeFileSync(resultPath, JSON.stringify(receipt, null, 2) + '\n', { mode: 0o600 });−35
const finish = async () => {−36
if (lease && !deleted) {+31
let lease;+32
let finishing;+33
let probeTimer;+34
let retentionTimer;+35
let successfulProbe = false;+36
const finish = () => {+37
if (finishing) return finishing;+38
finishing = (async () => {+39
clearTimeout(probeTimer);+40
clearTimeout(retentionTimer); 41
try {−38
const state = await lease.close();−39
deleted = state.phase === 'deleted' || state.phase === 'unavailable';−40
receipt.deleted = deleted;−41
receipt.deleteState = state.phase;−42
} catch (error) {−43
receipt.deleteError = error.message;+42
if (lease) {+43
const state = await lease.close();+44
receipt.deleteState = state.phase;+45
receipt.deletionVerification = state.deletion;+46
receipt.deleted = state.phase === 'deleted' && state.deletion?.absenceCode === 714;+47
if (!receipt.deleted) throw new Error('Owned mapping absence was not confirmed by 714');+48
}+49
} catch (error) { receipt.deleteError = error.message; }+50
finally {+51
await closeUdpSocket(responder);+52
receipt.responderStopped = true;+53
receipt.endedAt = new Date().toISOString();+54
save(); 55
}−45
}−46
clearTimeout(responderTimer);−47
responder.close();−48
receipt.responderStopped = true;−49
receipt.endedAt = new Date().toISOString();−50
save();+56
})();+57
return finishing; 58
};−52
process.once('SIGTERM', () => { void finish().finally(() => process.exit(0)); });−53
process.once('SIGINT', () => { void finish().finally(() => process.exit(0)); });−54
+59
const stop = () => abort.abort(new Error('Mapping experiment interrupted'));+60
process.once('SIGTERM', stop);+61
process.once('SIGINT', stop);+62
responder.on('error', error => abort.abort(error));+63
// Errors and signals abort waits; the single finally block owns all cleanup.+64
const aborted = () => { if (abort.signal.aborted) throw abort.signal.reason; }; 65
try {−56
await discoverGateway(route);+66
responder.bind(0, route.localAddress);+67
await once(responder, 'listening', { signal: abort.signal });+68
const internalPort = responder.address().port;+69
receipt.internalPort = internalPort; 70
const igd = await discoverIgd(route); 71
const service = igd.services[0]; 72
if (!service) throw new Error('No usable WANIPConnection IGD service'); 73
const client = new UpnpIgdClient(service, route); 74
const externalAddress = await client.getExternalAddress();−62
receipt.serviceType = service.serviceType;−63
receipt.externalAddress = externalAddress;−64
const deadline = Date.now() + 15 * 60 * 1000;+75
// Observe the public address from the host that creates the mapping.+76
const observation = await fetch('https://api.ipify.org', { signal: AbortSignal.timeout(3000) });+77
if (!observation.ok) throw new Error('External address observation failed');+78
const observedAddress = (await observation.text()).trim();+79
if (isIP(observedAddress) !== 4) throw new Error('Invalid externally observed IPv4 address');+80
Object.assign(receipt, { serviceType: service.serviceType, externalAddress, observedAddress,+81
cgnat: externalAddress === observedAddress ? 'no' : 'yes' });+82
save();+83
console.log(`RESULT CGNAT: ${receipt.cgnat}`);+84
aborted(); 85
lease = new SingleUdpLease({ candidates: [upnpUdpCandidate(client, { internalPort,−66
internalClient: route.localAddress, externalAddress })], deadline, leaseSeconds: 120,−67
journal: async state => {+86
internalClient: route.localAddress, externalAddress })], deadline: Date.now() + 150000,+87
leaseSeconds: 120, journal: async state => { 88
receipt.leaseState = state; 89
if (state.phase === 'creating') receipt.mappingRequests += 1; 90
save(); 91
} }); 92
const active = await lease.create();−73
lease.maintain(error => {−74
receipt.renewalError = error.message;−75
save();−76
});+93
aborted();+94
// Intentionally no maintain(): this experiment must issue only one lease. 95
receipt.externalPort = active.mapping.externalPort; 96
receipt.grantedLeaseSeconds = active.mapping.lifetime;+97
const echo = new Promise((resolveEcho, rejectEcho) => {+98
let claimed = false;+99
responder.on('message', (bytes, peer) => {+100
if (claimed || !bytes.equals(token) || abort.signal.aborted) return;+101
claimed = true;+102
responder.send(bytes, peer.port, peer.address, error => {+103
if (error) return rejectEcho(error);+104
receipt.echoCount = 1;+105
receipt.probePeer = peer;+106
save();+107
resolveEcho();+108
});+109
});+110
abort.signal.addEventListener('abort', () => rejectEcho(abort.signal.reason), { once: true });+111
probeTimer = setTimeout(() => rejectEcho(new Error('Outside probe timed out')), 90000);+112
}); 113
receipt.readyAt = new Date().toISOString(); 114
save(); 115
console.log(`READY protocol=upnp-igd externalPort=${receipt.externalPort} leaseSeconds=${receipt.grantedLeaseSeconds}`);+116
await echo;+117
clearTimeout(probeTimer);+118
const state = await lease.close();+119
if (state.phase !== 'deleted' || state.deletion?.absenceCode !== 714)+120
throw new Error('Delete did not confirm 714');+121
receipt.deleted = true;+122
receipt.deletedAt = new Date().toISOString();+123
receipt.deletionVerification = state.deletion;+124
save();+125
console.log('RESULT explicit-delete=true verification=714 responder-retained=15s');+126
// A second exact challenge is echoed during retention so an outside timeout+127
// can distinguish router deletion from a responder that was already stopped. 128
responder.on('message', (bytes, peer) => {−83
if (!bytes.equals(token) || echoCount >= 2) return;−84
echoCount += 1;−85
receipt.echoCount = echoCount;+129
if (!bytes.equals(token) || receipt.echoCount >= 2) return;+130
receipt.echoCount += 1; 131
responder.send(bytes, peer.port, peer.address, error => {−87
if (error) receipt.echoError = error.message;+132
if (error) abort.abort(error); 133
save();−89
if (echoCount === 1) {−90
void lease.close().then(state => {−91
deleted = state.phase === 'deleted';−92
receipt.deleted = deleted;−93
receipt.deleteState = state.phase;−94
receipt.deletedAt = new Date().toISOString();−95
save();−96
console.log(`RESULT explicit-delete=${deleted} state=${state.phase}; responder-retained=15s`);−97
responderTimer = setTimeout(() => { void finish(); }, 15000);−98
}).catch(async error => {−99
receipt.deleteError = error.message;−100
save();−101
await finish();−102
});−103
} 134
}); 135
});−106
setTimeout(() => {−107
if (echoCount === 0) {−108
console.log('RESULT probe-timeout; attempting explicit deletion');−109
void finish();−110
}−111
}, 90000).unref();−112
await new Promise(resolve => responder.once('close', resolve));−113
if (!receipt.deleted) throw new Error('Owned UPnP mapping deletion was not confirmed');−114
if (echoCount !== 1) throw new Error('Expected exactly one pre-delete echo probe');−115
console.log(`RESULT mappingRequests=${receipt.mappingRequests} preDeleteEchoes=${echoCount} deleted=true responderStopped=true`);+136
await new Promise((resolveWait, rejectWait) => {+137
retentionTimer = setTimeout(resolveWait, 15000);+138
abort.signal.addEventListener('abort', () => rejectWait(abort.signal.reason), { once: true });+139
if (abort.signal.aborted) rejectWait(abort.signal.reason);+140
});+141
if (receipt.echoCount !== 1) throw new Error('A probe reached the retained responder after deletion');+142
successfulProbe = true; 143
} catch (error) { 144
receipt.error = error.message;−118
save();+145
process.exitCode = 1;+146
} finally { 147
await finish();−120
throw error;+148
process.off('SIGTERM', stop);+149
process.off('SIGINT', stop);+150
if (!successfulProbe || !receipt.deleted || !receipt.responderStopped) process.exitCode = 1;+151
console.log(`RESULT outsideEcho=${successfulProbe} deleted=${receipt.deleted} verification=${receipt.deletionVerification?.absenceCode ?? 'unconfirmed'} responderStopped=${receipt.responderStopped}`); 152
}tools/nat/external-udp-probe.mjsmodified
@@ -6,7 +6,7 @@ import { resolve } from 'node:path';
6
import { performance } from 'node:perf_hooks'; 7
import { pathToFileURL } from 'node:url'; 8
−9
function probe(externalAddress, externalPort, challenge, timeoutMs) {+9
function probe(externalAddress, externalPort, challenge, timeoutMs, excludedPort) { 10
return new Promise((resolveProbe, reject) => { 11
const socket = createSocket('udp4'); 12
const started = performance.now();@@ -20,12 +20,16 @@ function probe(externalAddress, externalPort, challenge, timeoutMs) {
20
}; 21
const timer = setTimeout(() => finish(null, { echoed: false }), timeoutMs); 22
socket.on('error', error => finish(error));−23
socket.on('message', bytes => {−24
if (!bytes.equals(challenge)) return;−25
finish(null, { echoed: true, rttMs: Number((performance.now() - started).toFixed(3)) });+23
socket.on('message', (bytes, peer) => {+24
if (peer.address !== externalAddress || peer.port !== externalPort || !bytes.equals(challenge)) return;+25
finish(null, { echoed: true, sourcePort: socket.address().port,+26
rttMs: Number((performance.now() - started).toFixed(3)) });+27
});+28
socket.bind(0, () => {+29
// Never label a reused source port as a fresh post-delete path.+30
if (socket.address().port === excludedPort) return finish(new Error('Post-delete source port was reused; no packet sent'));+31
socket.send(challenge, externalPort, externalAddress, error => { if (error) finish(error); }); 32
});−27
socket.bind(0, () => socket.send(challenge, externalPort, externalAddress,−28
error => { if (error) finish(error); })); 33
}); 34
} 35
@@ -33,19 +37,15 @@ export async function runExternalUdpProbe({ externalAddress, externalPort, chall
37
if (isIP(externalAddress) !== 4 || !Number.isInteger(externalPort) || 38
externalPort < 1 || externalPort > 65535 || !/^[0-9a-f]{64}$/i.test(challengeHex || '')) 39
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,+43
return { targetAddress: externalAddress, 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,+47
const afterDelete = await probe(externalAddress, externalPort, challenge, 2500, beforeDelete.sourcePort);+48
return { targetAddress: externalAddress, externalPort, 49
beforeDelete, afterDelete, checkedAt: new Date().toISOString() }; 50
} 51