Commit06810868Recorded18 Oct 2026Repositorysigil-nat

Add bounded NAT probe wire format and conservative behaviour classifiers

Message

Keep missing controls and unstable observations inconclusive. Compare full mapped tuples, require distinct source ports for independent samples, and expose only classifications, counts and timings in public summaries. Runtime client and reflectors follow this offline-validated foundation.

Changed
 scripts/phantom-nat-probe-check.sh | 13 +++++++++++++
 tools/nat/nat-probe-analysis.mjs   | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 tools/nat/nat-probe-wire.mjs       | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 tools/nat/test-nat-probe.mjs       | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 225 insertions(+)
Diff
scripts/phantom-nat-probe-check.shadded
@@ -0,0 +1,13 @@
+1
#!/usr/bin/env bash
+2
set -euo pipefail
+3
cd "$(dirname "$0")/.."
+4
mkdir -p build/nat-probe
+5
result_path="$PWD/build/nat-probe/check-result.txt"
+6
record_result() {
+7
local job_rc=$?
+8
printf 'RESULT nat-probe-check rc=%s\n' "$job_rc" | tee -a "$result_path"
+9
}
+10
trap record_result EXIT
+11
printf 'RESULT operation=offline-probe-fixtures no-network\n' | tee "$result_path"
+12
timeout --foreground 30 node --test tools/nat/test-nat-probe.mjs 2>&1 | tee build/nat-probe/tests.log
+13
printf 'RESULT nat-probe-fixtures=PASS\n' | tee -a "$result_path"
tools/nat/nat-probe-analysis.mjsadded
@@ -0,0 +1,61 @@
+1
// Conservatively classify only matched observations with positive controls.
+2
import { probeEndpoint, sameEndpoint } from './nat-probe-wire.mjs';
+3
+4
function usableObservation(value) {
+5
if (value?.sent !== true || value?.matched !== true) return false;
+6
try { probeEndpoint(value.observed); return true; } catch { return false; }
+7
}
+8
export function classifyProbeMapping({ a1, a2, b, repeatedA1 }) {
+9
if (![a1, a2, b, repeatedA1].every(usableObservation)) return 'inconclusive';
+10
if (!sameEndpoint(a1.observed, repeatedA1.observed)) return 'inconclusive';
+11
if (!sameEndpoint(a1.observed, a2.observed)) return 'address-and-port-dependent';
+12
return sameEndpoint(a1.observed, b.observed) ? 'endpoint-independent' : 'address-dependent';
+13
}
+14
export function classifyProbeFiltering({ controls, alternateAddress, alternatePort }) {
+15
if (![controls?.primary, controls?.alternateAddress, controls?.alternatePort,
+16
controls?.recoveredPrimary].every(value => value === true)) return 'inconclusive';
+17
const valid = check => check?.sent === true && check?.ackMatched === true &&
+18
typeof check.received === 'boolean';
+19
if (!valid(alternateAddress)) return 'inconclusive';
+20
if (alternateAddress.received) return 'endpoint-independent';
+21
if (!valid(alternatePort)) return 'inconclusive';
+22
return alternatePort.received ? 'address-dependent' : 'address-and-port-dependent';
+23
}
+24
export function summarizeProbeLifetime(samples) {
+25
if (!Array.isArray(samples) || samples.length > 8) throw new Error('Invalid lifetime sample budget');
+26
const ports = samples.map(sample => sample.localPort);
+27
if (new Set(ports).size !== ports.length) throw new Error('Idle samples must use separate source ports');
+28
const trials = samples.map(sample => {
+29
const valid = Number.isInteger(sample.localPort) && sample.localPort >= 1024 && sample.localPort <= 65535 &&
+30
Number.isFinite(sample.idleMs) && sample.idleMs >= 1 && sample.idleMs <= 120000 &&
+31
sample.outboundPackets === 1 && sample.established === true && sample.probeSent === true &&
+32
sample.ackMatched === true && sample.controlHealthy === true && typeof sample.received === 'boolean';
+33
return { idleSeconds: sample.idleMs / 1000,
+34
result: !valid ? 'inconclusive' : sample.received ? 'survived' : 'not-observed' };
+35
});
+36
return { trials, lowerBoundSeconds: Math.max(0,
+37
...trials.filter(trial => trial.result === 'survived').map(trial => trial.idleSeconds)),
+38
// Missing UDP responses are not, by themselves, proof that a mapping expired.
+39
failureCount: trials.filter(trial => trial.result === 'not-observed').length,
+40
inconclusiveCount: trials.filter(trial => trial.result === 'inconclusive').length };
+41
}
+42
function counts(values) {
+43
const result = {};
+44
for (const value of values) result[value] = (result[value] ?? 0) + 1;
+45
return result;
+46
}
+47
export function summarizeNatProbe({ mapping, filtering, lifetime }) {
+48
if (!Array.isArray(mapping) || mapping.length < 3 || mapping.length > 5 ||
+49
!Array.isArray(filtering) || filtering.length < 1 || filtering.length > 5)
+50
throw new Error('Probe needs 3..5 mapping samples and 1..5 filtering samples');
+51
if (mapping.some(sample => !Number.isInteger(sample.localPort) || sample.localPort < 1024 || sample.localPort > 65535) ||
+52
new Set(mapping.map(sample => sample.localPort)).size !== mapping.length)
+53
throw new Error('Mapping samples must use different local source ports');
+54
const compared = mapping.filter(sample => usableObservation(sample.a1));
+55
return { mapping: counts(mapping.map(classifyProbeMapping)),
+56
filtering: counts(filtering.map(classifyProbeFiltering)),
+57
portPreservation: { compared: compared.length,
+58
preserved: compared.filter(sample => sample.a1.observed.port === sample.localPort).length },
+59
lifetime: summarizeProbeLifetime(lifetime),
+60
scope: 'observed-combined-IPv4-path', protocol: 'private-RFC-style-not-STUN' };
+61
}
tools/nat/nat-probe-wire.mjsadded
@@ -0,0 +1,59 @@
+1
// Private fixed-size probe protocol. RFC-style measurements, not STUN wire.
+2
import { isIP } from 'node:net';
+3
+4
export const probeOperations = Object.freeze({ lookup: 1, observed: 2,
+5
alternatePort: 3, alternateAddress: 4, forward: 5, probe: 6,
+6
sent: 7, deliverStored: 8 });
+7
const operations = new Set(Object.values(probeOperations));
+8
const magic = Buffer.from('SNP1');
+9
export const probePacketSize = 64;
+10
+11
function requireBytes(value, length, name) {
+12
if (!Buffer.isBuffer(value) || value.length !== length)
+13
throw new Error(`Invalid probe ${name}`);
+14
}
+15
export function probeEndpoint(value) {
+16
if (!value || isIP(value.address) !== 4 ||
+17
Number(value.address.split('.')[0]) === 0 || Number(value.address.split('.')[0]) >= 224 ||
+18
!Number.isInteger(value.port) || value.port < 1 || value.port > 65535)
+19
throw new Error('Invalid probe IPv4 endpoint');
+20
return { address: value.address, port: value.port };
+21
}
+22
export function encodeProbeMessage({ token, transaction, operation, endpoint }) {
+23
requireBytes(token, 32, 'run token');
+24
requireBytes(transaction, 12, 'transaction');
+25
if (!operations.has(operation)) throw new Error('Unknown probe operation');
+26
const bytes = Buffer.alloc(probePacketSize);
+27
magic.copy(bytes);
+28
token.copy(bytes, 4);
+29
transaction.copy(bytes, 36);
+30
bytes[48] = operation;
+31
if (endpoint) {
+32
const checked = probeEndpoint(endpoint);
+33
Buffer.from(checked.address.split('.').map(Number)).copy(bytes, 49);
+34
bytes.writeUInt16BE(checked.port, 53);
+35
}
+36
return bytes;
+37
}
+38
export function decodeProbeMessage(bytes, token) {
+39
requireBytes(token, 32, 'run token');
+40
requireBytes(bytes, probePacketSize, 'packet size');
+41
if (!bytes.subarray(0, 4).equals(magic) || !bytes.subarray(4, 36).equals(token))
+42
throw new Error('Unmatched probe version/run token');
+43
if (!operations.has(bytes[48]) || bytes.subarray(55).some(value => value !== 0))
+44
throw new Error('Unknown probe operation/reserved bytes');
+45
const addressBytes = bytes.subarray(49, 53);
+46
const port = bytes.readUInt16BE(53);
+47
const present = addressBytes.some(value => value !== 0) || port !== 0;
+48
return { operation: bytes[48], transaction: Buffer.from(bytes.subarray(36, 48)),
+49
endpoint: present ? probeEndpoint({ address: [...addressBytes].join('.'), port }) : undefined };
+50
}
+51
export function sameEndpoint(first, second) {
+52
return Boolean(first && second && first.address === second.address && first.port === second.port);
+53
}
+54
export function validateProbeReflectors({ a1, a2, b }) {
+55
for (const endpoint of [a1, a2, b]) probeEndpoint(endpoint);
+56
if (a1.address !== a2.address || a1.port === a2.port || a1.address === b.address)
+57
throw new Error('Probe needs two different IPv4 addresses and two ports on A');
+58
return { a1: { ...a1 }, a2: { ...a2 }, b: { ...b } };
+59
}
tools/nat/test-nat-probe.mjsadded
@@ -0,0 +1,92 @@
+1
import assert from 'node:assert/strict';
+2
import { test } from 'node:test';
+3
import { encodeProbeMessage, decodeProbeMessage, validateProbeReflectors,
+4
probeOperations as op } from './nat-probe-wire.mjs';
+5
import { classifyProbeMapping, classifyProbeFiltering, summarizeProbeLifetime,
+6
summarizeNatProbe } from './nat-probe-analysis.mjs';
+7
+8
const token = Buffer.alloc(32, 0x11), transaction = Buffer.alloc(12, 0x22);
+9
const observed = port => ({ sent: true, matched: true, observed: { address: '198.51.100.1', port } });
+10
const baseline = (localPort = 45000) => ({ localPort, a1: observed(localPort), a2: observed(localPort),
+11
b: observed(localPort), repeatedA1: observed(localPort) });
+12
const filter = received => ({ sent: true, ackMatched: true, received });
+13
const controls = { primary: true, alternateAddress: true, alternatePort: true, recoveredPrimary: true };
+14
const idle = (seconds, port) => ({ idleMs: seconds * 1000, localPort: port,
+15
outboundPackets: 1, established: true, probeSent: true, ackMatched: true,
+16
controlHealthy: true, received: true });
+17
+18
test('probe wire has exact independent header/tuple positions and no amplification', () => {
+19
const bytes = encodeProbeMessage({ token, transaction, operation: op.observed,
+20
endpoint: { address: '203.0.113.7', port: 50000 } });
+21
assert.equal(bytes.length, 64);
+22
assert.equal(bytes.subarray(0, 4).toString(), 'SNP1');
+23
assert.equal(bytes[48], 2);
+24
assert.equal(bytes.subarray(49, 55).toString('hex'), 'cb007107c350');
+25
const decoded = decodeProbeMessage(bytes, token);
+26
assert.deepEqual(decoded.endpoint, { address: '203.0.113.7', port: 50000 });
+27
assert.deepEqual(decoded.transaction, transaction);
+28
});
+29
+30
test('wrong run tokens, truncated/oversized frames and reserved bits fail closed', () => {
+31
const bytes = encodeProbeMessage({ token, transaction, operation: op.lookup });
+32
assert.throws(() => decodeProbeMessage(bytes, Buffer.alloc(32)), /token/);
+33
for (const bad of [bytes.subarray(0, 63), Buffer.concat([bytes, Buffer.alloc(1)])])
+34
assert.throws(() => decodeProbeMessage(bad, token), /size/);
+35
const reserved = Buffer.from(bytes); reserved[63] = 1;
+36
assert.throws(() => decodeProbeMessage(reserved, token), /reserved/);
+37
});
+38
+39
test('reflector topology rejects same outside IP and identical A ports', () => {
+40
const topology = { a1: { address: '198.51.100.1', port: 41000 },
+41
a2: { address: '198.51.100.1', port: 41001 }, b: { address: '203.0.113.2', port: 41000 } };
+42
assert.deepEqual(validateProbeReflectors(topology), topology);
+43
assert.throws(() => validateProbeReflectors({ ...topology, b: topology.a1 }), /different IPv4/);
+44
assert.throws(() => validateProbeReflectors({ ...topology, a2: topology.a1 }), /two ports/);
+45
});
+46
+47
test('mapping categories depend on the observed full tuple, including public IP', () => {
+48
assert.equal(classifyProbeMapping(baseline()), 'endpoint-independent');
+49
assert.equal(classifyProbeMapping({ ...baseline(), b: observed(50001) }), 'address-dependent');
+50
assert.equal(classifyProbeMapping({ ...baseline(), a2: observed(50001) }), 'address-and-port-dependent');
+51
const alternateAddress = observed(45000); alternateAddress.observed.address = '203.0.113.9';
+52
assert.equal(classifyProbeMapping({ ...baseline(), b: alternateAddress }), 'address-dependent');
+53
});
+54
+55
test('loss or changing baseline is inconclusive, never invented restrictive mapping', () => {
+56
assert.equal(classifyProbeMapping({ ...baseline(), b: undefined }), 'inconclusive');
+57
assert.equal(classifyProbeMapping({ ...baseline(), a2: { ...observed(50001), matched: false } }), 'inconclusive');
+58
assert.equal(classifyProbeMapping({ ...baseline(), repeatedA1: observed(50001) }), 'inconclusive');
+59
});
+60
+61
test('filtering distinguishes alternate address from alternate port responses', () => {
+62
assert.equal(classifyProbeFiltering({ controls, alternateAddress: filter(true) }), 'endpoint-independent');
+63
assert.equal(classifyProbeFiltering({ controls, alternateAddress: filter(false), alternatePort: filter(true) }), 'address-dependent');
+64
assert.equal(classifyProbeFiltering({ controls, alternateAddress: filter(false), alternatePort: filter(false) }), 'address-and-port-dependent');
+65
});
+66
+67
test('missing send acknowledgement or failed positive control cannot prove filtering', () => {
+68
assert.equal(classifyProbeFiltering({ controls, alternateAddress: { ...filter(false), sent: false },
+69
alternatePort: filter(false) }), 'inconclusive');
+70
assert.equal(classifyProbeFiltering({ controls: { ...controls, alternateAddress: false },
+71
alternateAddress: filter(false), alternatePort: filter(false) }), 'inconclusive');
+72
});
+73
+74
test('independent idle sockets report lower bounds without converting UDP loss to expiry', () => {
+75
const samples = [idle(15, 45001), idle(30, 45002), idle(60, 45003), { ...idle(120, 45004), received: false }];
+76
const result = summarizeProbeLifetime(samples);
+77
assert.equal(result.lowerBoundSeconds, 60);
+78
assert.equal(result.failureCount, 1);
+79
assert.equal(result.trials[3].result, 'not-observed');
+80
assert.throws(() => summarizeProbeLifetime([samples[0], samples[0]]), /separate/);
+81
assert.equal(summarizeProbeLifetime([{ ...samples[0], outboundPackets: 2 }]).inconclusiveCount, 1);
+82
});
+83
+84
test('public summary exposes counts/classifications/timings without addresses or local ports', () => {
+85
const summary = summarizeNatProbe({ mapping: [baseline(45000), baseline(45010), baseline(45020)],
+86
filtering: [{ controls, alternateAddress: filter(true) }], lifetime: [idle(15, 45001)] });
+87
assert.deepEqual(summary.mapping, { 'endpoint-independent': 3 });
+88
assert.deepEqual(summary.portPreservation, { compared: 3, preserved: 3 });
+89
assert.doesNotMatch(JSON.stringify(summary), /198\.51|203\.0|45000|45001/);
+90
assert.throws(() => summarizeNatProbe({ mapping: [baseline(), baseline(), baseline()],
+91
filtering: [{ controls, alternateAddress: filter(true) }], lifetime: [] }), /different local/);
+92
});