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.mjs
scripts/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