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