AtlatestRepositorysigil-nat

sigil-nat / tree / tools / natnat-probe-analysis.mjs

1// Conservatively classify only matched observations with positive controls.
2import { probeEndpoint, sameEndpoint } from './nat-probe-wire.mjs';
3
4function usableObservation(value) {
5 if (value?.sent !== true || value?.matched !== true) return false;
6 try { probeEndpoint(value.observed); return true; } catch { return false; }
7}
8export 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';
14export 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';
24export 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 };
42function counts(values) {
43 const result = {};
44 for (const value of values) result[value] = (result[value] ?? 0) + 1;
45 return result;
47export 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' };
57function 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');
65export 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' };