AtlatestRepositorysigil-nat
1
# sigil-nat3
Bounded IPv4 gateway discovery, UDP port mapping, and NAT measurement helpers4
for [Sigil](https://codeberg.org/sigil/sigil). The package provides a small5
Sigil lease policy module and dependency-free JavaScript tools for PCP6
(RFC 6887), NAT-PMP (RFC 6886), and UPnP IGD.8
## Status10
Early development. Protocol codecs, bounded gateway discovery, mapping11
ownership and cleanup, and token-scoped UDP reflectors have offline tests.12
The lease coordinator manages one UDP mapping at a time with a maximum13
30-minute lifetime. Ambiguous replies block protocol fallback until cleanup.14
UPnP routers that require permanent mappings are unsupported. NAT measurements15
keep missing controls inconclusive; one reflector address cannot measure16
address dependence. This is not a complete Sigil NAT traversal API, and the17
measurement protocol is not STUN.19
## Dependency21
Add this entry to your `package.sgl` dependencies, then run `sigil deps install`:23
```scheme24
(from-pkg name: "sigil/sigil-nat" version: "^0.1.1")25
```27
Requires Sigil 0.24.11 or later. The JavaScript tools run directly from a checkout28
with Node.js 20 or later. Gateway discovery uses Linux `ip route`.30
## Usage32
```scheme33
(import (sigil nat policy))35
(sigil-nat-lease-valid? 120) ; => #t36
(sigil-nat-lease-valid? 3600) ; => #f37
```39
JavaScript applications can import `SingleUdpLease` from `tools/nat/lease.mjs`40
and supply protocol candidates plus a journal callback. The coordinator41
records ownership before network changes, renews before expiry, and deletes42
only its own mapping. Call `close()` during shutdown.44
`scripts/nat-probe.mjs CONFIG.json` measures an IPv4 path against reflectors45
controlled by the caller. Use a caller-owned regular config file with mode46
0600, schema 1, `expectedHost` matching the local hostname, `localAddress`47
matching the default route, a 64-digit hexadecimal `tokenHex`, a new absolute48
`runDirectory`, and `reflectors.a1`/`a2` with the same public `address` and49
different `port` values. `mappingSamples` is optional (3 through 5). Results50
keep observed addresses in private detail files; the printed summary contains51
classifications, counts, and timings. Idle samples use 15, 30, 60, and 120 seconds.53
The Perl reflector in `tools/nat/reflectors/nat-probe.pl` needs only base Perl54
modules. Its private config has four lines: bind IPv4, token hex, lifetime in55
milliseconds (at most 900000), and an absolute receipt path. Two optional lines56
select distinct ports from 1024 through 65535; otherwise the kernel selects57
ports. The reflector latches one client's source IP and bounds packets, state,58
and lifetime.60
The live inspection and mapping examples retain their `phantom-` filenames61
for compatibility. Set `NAT_EXPECTED_HOST`, `NAT_EXPECTED_GATEWAY`, and62
`NAT_EXPECTED_LOCAL_ADDRESS` explicitly to match the intended Linux host and63
route. The inspection script sends discovery requests; the mapping example64
creates one lease of at most 120 seconds and waits for an outside challenge.65
Neither script changes firewall rules.67
## Tests69
From the checkout, with Node.js 20 or later, Perl, and loopback UDP available:71
```sh72
node --test tools/nat/test-*.mjs73
```75
These checks use fixtures and loopback sockets, including the real Perl76
reflector. 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 inspection79
and requires the explicit route settings described above.81
## License83
BSD-3-Clause. See [LICENSE](LICENSE).