Commit2579c236Recorded25 Oct 2026Repositorysigil-nat
Document public NAT policy and portable validation tools
Changed
README.md | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------------------------
1 file changed, 81 insertions(+), 56 deletions(-)Diff
README.mdmodified
@@ -1,58 +1,83 @@
1
# sigil-nat 2
−3
Small, bounded gateway discovery and UDP port-mapping helpers for Sigil−4
applications. PCP (RFC 6887), NAT-PMP (RFC 6886), and UPnP IGD are supported.−5
UPnP control uses a minimal internal HTTP/1.1 client. It does not follow−6
redirects, resolve off-gateway control URLs, parse external entities, or accept−7
unbounded responses.−8
−9
The lease coordinator creates one mapping at a time, caps every requested and−10
observed lease at 30 minutes, renews before expiry, records ownership before−11
network changes, and deletes only a mapping whose ownership tuple matches.−12
An ambiguous create or renewal must be reconciled or explicitly deleted before−13
trying another protocol. A UPnP router that only supports permanent mappings−14
is not used.−15
−16
The JavaScript modules in `tools/nat` are dependency-free operational helpers.−17
Live scripts require explicit host and route configuration.−18
−19
The protocol codec sources are RFC 6887 and RFC 6886. UPnP service actions and−20
lease semantics follow the [WANIPConnection:1 service template](https://upnp.org/specs/gw/UPnP-gw-WANIPConnection-v1-Service.pdf),−21
including `GetSpecificPortMappingEntry`, `AddPortMapping`,−22
`DeletePortMapping`, and `GetExternalIPAddress`.−23
−24
`tools/nat/nat-probe.mjs` measures the current combined IPv4 path using owned,−25
run-specific reflectors. Its private fixed-size protocol is not STUN wire.−26
The client checks reachability once per reflector port before measuring,−27
uses fresh source ports for filtering before contacting alternates, compares−28
full observed address/port tuples and checks the primary tuple again. Idle−29
samples use separate receive-only data sockets and a control socket; the−30
measured socket sends only its initial lookup. Missing send acknowledgements−31
or positive controls remain inconclusive. A missing idle reply is reported−32
as not observed, not proof of expiration.−33
−34
For a single-host run, `tools/nat/reflectors/nat-probe.pl` uses only−35
base Perl modules and two high UDP ports on one exact IPv4 interface.−36
Its private owned config contains four lines: bind IPv4, 64-hex run token,−37
lifetime milliseconds (at most 900000), and absolute receipt path. Two optional−38
additional lines select distinct explicit ports (1024..65535); omit both for−39
kernel-selected ephemeral ports. An occupied explicit port fails without−40
fallback, so firewall-scoped runs never bind outside their admitted range. It latches−41
the first valid token holder's source IP, responds only to that client, and−42
can deliver idle probes only to tuples it previously observed. Packet/state−43
budgets and expiry bound the listener. Its private receipt records its PID−44
and ports; the `.done` receipt records shutdown. Stop only that admitted PID.−45
No package installation or firewall change is part of this helper.−46
−47
`scripts/nat-probe.mjs PRIVATE_CONFIG.json` runs the client on the−48
default-route source. The config names schema 1, expectedHost,−49
localAddress, tokenHex, a new absolute runDirectory, optional mappingSamples−50
(3..5), and reflectors.a1/a2 with the same public address and different ports.−51
This wrapper rejects a VPN/private reflector address and uses the−52
15/30/60/120-second idle plan. The library also supports two distinct-address−53
reflectors with explicit configuration. A single-host result explicitly leaves−54
address dependence unmeasured. Public summaries contain only classifications,−55
counts and timings; observed addresses stay in private details receipts.−56
−57
Validate with `node --test tools/nat/test-*.mjs`. Tests include real loopback UDP and the actual Perl reflector; these−58
are apparatus checks, not observations about an outside NAT.+3
Bounded IPv4 gateway discovery, UDP port mapping, and NAT measurement helpers+4
for [Sigil](https://codeberg.org/sigil/sigil). The package provides a small+5
Sigil lease policy module and dependency-free JavaScript tools for PCP+6
(RFC 6887), NAT-PMP (RFC 6886), and UPnP IGD.+7
+8
## Status+9
+10
Early development. Protocol codecs, bounded gateway discovery, mapping+11
ownership and cleanup, and token-scoped UDP reflectors have offline tests.+12
The lease coordinator manages one UDP mapping at a time with a maximum+13
30-minute lifetime. Ambiguous replies block protocol fallback until cleanup.+14
UPnP routers that require permanent mappings are unsupported. NAT measurements+15
keep missing controls inconclusive; one reflector address cannot measure+16
address dependence. This is not a complete Sigil NAT traversal API, and the+17
measurement protocol is not STUN.+18
+19
## Dependency+20
+21
Add this entry to your `package.sgl` dependencies, then run `sigil deps install`:+22
+23
```scheme+24
(from-git url: "codeberg:sigil/sigil-nat" branch: "master")+25
```+26
+27
Requires Sigil 0.22 or later. The JavaScript tools run directly from a checkout+28
with Node.js 20 or later. Gateway discovery uses Linux `ip route`.+29
+30
## Usage+31
+32
```scheme+33
(import (sigil nat policy))+34
+35
(sigil-nat-lease-valid? 120) ; => #t+36
(sigil-nat-lease-valid? 3600) ; => #f+37
```+38
+39
JavaScript applications can import `SingleUdpLease` from `tools/nat/lease.mjs`+40
and supply protocol candidates plus a journal callback. The coordinator+41
records ownership before network changes, renews before expiry, and deletes+42
only its own mapping. Call `close()` during shutdown.+43
+44
`scripts/nat-probe.mjs CONFIG.json` measures an IPv4 path against reflectors+45
controlled by the caller. Use a caller-owned regular config file with mode+46
0600, schema 1, `expectedHost` matching the local hostname, `localAddress`+47
matching the default route, a 64-digit hexadecimal `tokenHex`, a new absolute+48
`runDirectory`, and `reflectors.a1`/`a2` with the same public `address` and+49
different `port` values. `mappingSamples` is optional (3 through 5). Results+50
keep observed addresses in private detail files; the printed summary contains+51
classifications, counts, and timings. Idle samples use 15, 30, 60, and 120 seconds.+52
+53
The Perl reflector in `tools/nat/reflectors/nat-probe.pl` needs only base Perl+54
modules. Its private config has four lines: bind IPv4, token hex, lifetime in+55
milliseconds (at most 900000), and an absolute receipt path. Two optional lines+56
select distinct ports from 1024 through 65535; otherwise the kernel selects+57
ports. The reflector latches one client's source IP and bounds packets, state,+58
and lifetime.+59
+60
The live inspection and mapping examples retain their `phantom-` filenames+61
for compatibility. Set `NAT_EXPECTED_HOST`, `NAT_EXPECTED_GATEWAY`, and+62
`NAT_EXPECTED_LOCAL_ADDRESS` explicitly to match the intended Linux host and+63
route. The inspection script sends discovery requests; the mapping example+64
creates one lease of at most 120 seconds and waits for an outside challenge.+65
Neither script changes firewall rules.+66
+67
## Tests+68
+69
From the checkout, with Node.js 20 or later, Perl, and loopback UDP available:+70
+71
```sh+72
node --test tools/nat/test-*.mjs+73
```+74
+75
These checks use fixtures and loopback sockets, including the real Perl+76
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 inspection+79
and requires the explicit route settings described above.+80
+81
## License+82
+83
BSD-3-Clause. See [LICENSE](LICENSE).