README.md
sigil-nat
Bounded IPv4 gateway discovery, UDP port mapping, and NAT measurement helpers for Sigil. The package provides a small Sigil lease policy module and dependency-free JavaScript tools for PCP (RFC 6887), NAT-PMP (RFC 6886), and UPnP IGD.
Status
Early development. Protocol codecs, bounded gateway discovery, mapping ownership and cleanup, and token-scoped UDP reflectors have offline tests. The lease coordinator manages one UDP mapping at a time with a maximum 30-minute lifetime. Ambiguous replies block protocol fallback until cleanup. UPnP routers that require permanent mappings are unsupported. NAT measurements keep missing controls inconclusive; one reflector address cannot measure address dependence. This is not a complete Sigil NAT traversal API, and the measurement protocol is not STUN.
Dependency
Add this entry to your package.sgl dependencies, then run sigil deps install:
(from-pkg name: "sigil/sigil-nat" version: "^0.1.1")Requires Sigil 0.24.11 or later. The JavaScript tools run directly from a checkout with Node.js 20 or later. Gateway discovery uses Linux ip route.
Usage
(import (sigil nat policy))
(sigil-nat-lease-valid? 120) ; => #t
(sigil-nat-lease-valid? 3600) ; => #fJavaScript applications can import SingleUdpLease from tools/nat/lease.mjs and supply protocol candidates plus a journal callback. The coordinator records ownership before network changes, renews before expiry, and deletes only its own mapping. Call close() during shutdown.
scripts/nat-probe.mjs CONFIG.json measures an IPv4 path against reflectors controlled by the caller. Use a caller-owned regular config file with mode 0600, schema 1, expectedHost matching the local hostname, localAddress matching the default route, a 64-digit hexadecimal tokenHex, a new absolute runDirectory, and reflectors.a1/a2 with the same public address and different port values. mappingSamples is optional (3 through 5). Results keep observed addresses in private detail files; the printed summary contains classifications, counts, and timings. Idle samples use 15, 30, 60, and 120 seconds.
The Perl reflector in tools/nat/reflectors/nat-probe.pl needs only base Perl modules. Its private config has four lines: bind IPv4, token hex, lifetime in milliseconds (at most 900000), and an absolute receipt path. Two optional lines select distinct ports from 1024 through 65535; otherwise the kernel selects ports. The reflector latches one client's source IP and bounds packets, state, and lifetime.
The live inspection and mapping examples retain their phantom- filenames for compatibility. Set NAT_EXPECTED_HOST, NAT_EXPECTED_GATEWAY, and NAT_EXPECTED_LOCAL_ADDRESS explicitly to match the intended Linux host and route. The inspection script sends discovery requests; the mapping example creates one lease of at most 120 seconds and waits for an outside challenge. Neither script changes firewall rules.
Tests
From the checkout, with Node.js 20 or later, Perl, and loopback UDP available:
node --test tools/nat/test-*.mjsThese checks use fixtures and loopback sockets, including the real Perl reflector. They send no requests to an outside gateway or public reflector. scripts/phantom-nat-probe-check.sh runs just the probe checks with timeouts. scripts/phantom-nat-check.sh additionally performs live gateway inspection and requires the explicit route settings described above.
License
BSD-3-Clause. See LICENSE.