AtlatestRepositorysigil-nat
1
// Conservatively classify only matched observations with positive controls.2
import { probeEndpoint, sameEndpoint } from './nat-probe-wire.mjs';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
validateSamples(mapping, filtering);49
const compared = mapping.filter(sample => usableObservation(sample.a1));50
return { mapping: counts(mapping.map(classifyProbeMapping)),51
filtering: counts(filtering.map(classifyProbeFiltering)),52
portPreservation: { compared: compared.length,53
preserved: compared.filter(sample => sample.a1.observed.port === sample.localPort).length },54
lifetime: summarizeProbeLifetime(lifetime),55
scope: 'observed-combined-IPv4-path', protocol: 'private-RFC-style-not-STUN' };56
}57
function validateSamples(mapping, filtering) {58
if (!Array.isArray(mapping) || mapping.length < 3 || mapping.length > 5 ||59
!Array.isArray(filtering) || filtering.length < 1 || filtering.length > 5)60
throw new Error('Probe needs 3..5 mapping samples and 1..5 filtering samples');61
if (mapping.some(sample => !Number.isInteger(sample.localPort) || sample.localPort < 1024 || sample.localPort > 65535) ||62
new Set(mapping.map(sample => sample.localPort)).size !== mapping.length)63
throw new Error('Mapping samples must use different local source ports');64
}65
export function summarizeSingleHostNatProbe({ mapping, filtering, lifetime }) {66
validateSamples(mapping, filtering);67
const mappingClass = sample => {68
if (![sample.a1, sample.a2, sample.repeatedA1].every(usableObservation) ||69
!sameEndpoint(sample.a1.observed, sample.repeatedA1.observed)) return 'inconclusive';70
return sameEndpoint(sample.a1.observed, sample.a2.observed)71
? 'port-independent-for-tested-address' : 'port-dependent-for-tested-address';72
};73
const filteringClass = sample => {74
if (![sample.controls?.primary, sample.controls?.alternatePort, sample.controls?.recoveredPrimary].every(value => value === true) ||75
sample.alternatePort?.sent !== true || sample.alternatePort?.ackMatched !== true ||76
typeof sample.alternatePort?.received !== 'boolean') return 'inconclusive';77
return sample.alternatePort.received ? 'alternate-port-allowed' : 'alternate-port-not-observed';78
};79
const compared = mapping.filter(sample => usableObservation(sample.a1));80
return { mapping: counts(mapping.map(mappingClass)), filtering: counts(filtering.map(filteringClass)),81
addressDependence: 'unmeasured-single-reflector-IP',82
portPreservation: { compared: compared.length,83
preserved: compared.filter(sample => sample.a1.observed.port === sample.localPort).length },84
lifetime: summarizeProbeLifetime(lifetime),85
scope: 'observed-combined-IPv4-path', protocol: 'private-RFC-style-not-STUN' };86
}