AtlatestRepositorysigil-nat

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

1// Private fixed-size probe protocol. RFC-style measurements, not STUN wire.
2import { isIP } from 'node:net';
3
4export const probeOperations = Object.freeze({ lookup: 1, observed: 2,
5 alternatePort: 3, alternateAddress: 4, forward: 5, probe: 6,
6 sent: 7, deliverStored: 8 });
7const operations = new Set(Object.values(probeOperations));
8const magic = Buffer.from('SNP1');
9export const probePacketSize = 64;
11function requireBytes(value, length, name) {
12 if (!Buffer.isBuffer(value) || value.length !== length)
13 throw new Error(`Invalid probe ${name}`);
15export 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 };
22export 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;
38export 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 };
51export function sameEndpoint(first, second) {
52 return Boolean(first && second && first.address === second.address && first.port === second.port);
54export function validateProbeReflectors({ a1, a2, b }) {
55 validateSingleHostReflectors({ a1, a2 });
56 for (const endpoint of [a1, a2, b]) probeEndpoint(endpoint);
57 if (a1.address !== a2.address || a1.port === a2.port || a1.address === b.address)
58 throw new Error('Probe needs two different IPv4 addresses and two ports on A');
59 return { a1: { ...a1 }, a2: { ...a2 }, b: { ...b } };
61export function validateSingleHostReflectors({ a1, a2 }) {
62 for (const endpoint of [a1, a2]) probeEndpoint(endpoint);
63 if (a1.address !== a2.address || a1.port === a2.port)
64 throw new Error('Single-host probe needs two ports on A with one IPv4 address and different port numbers');
65 return { a1: { ...a1 }, a2: { ...a2 } };