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).