mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 19:18:25 +00:00

Files

T

Johnathan Corgan 1cc069f1a2 Gather the host-side IPv6 plane into the ipv6tun module

The TUN adapter, the .fips DNS responder, ICMPv6 generation and TCP MSS
clamping are the host-side IPv6 plane, but the code was split between
src/upper and inline bodies in the node's session handler and lifecycle.
Gather it into one module, src/ipv6tun, and reduce its calls into the
rest of the crate to a small explicit set. This prepares the TUN adapter
to run later as a separate daemon over the native API, and gives
embedders one place to find the host-side surface. Behaviour is
unchanged apart from log target names.

- Rename src/upper to src/ipv6tun. A `pub use ipv6tun as upper;` alias
  keeps every crate::upper:: and fips::upper:: path resolving, so no
  consumer has to change.
- Move hosts.rs whole to src/hosts.rs, a top-level public module: the
  hosts file also serves peer display names, the peer ACL and fipsctl,
  so it is not host-side only. ipv6tun re-exports it for the old path.
- Move the DNS socket helpers (dual-stack bind, IPV6_RECVPKTINFO,
  interface index lookup) from Node into ipv6tun::dns, unchanged.
  Node::mesh_ifindex, which reads the live TUN device name, becomes
  Handles::mesh_ifindex.
- Move ICMPv6 Destination Unreachable and Packet Too Big sending into
  ipv6tun::icmp behind IcmpContext, which borrows the TUN channel, our
  address and the Packet Too Big rate limiter for one use. Packet Too
  Big is still rate limited and Destination Unreachable still is not.
  The discovery lookup timeout hands its queued packets over as one
  no-route report.
- Split handle_tun_outbound. The host-side half, in ipv6tun::outbound,
  validates the packet, makes both Packet Too Big decisions and sends
  the ICMPv6 replies, reaching the mesh through a small Mesh trait Node
  implements. The mesh-side half, Node::send_outbound, stays with the
  pending queue. The checks run in the same order with the same
  thresholds, and Node::handle_tun_outbound remains the entry point.
- Move the TUN and DNS child start and stop bodies into
  ipv6tun::lifecycle, and gather their nine supervisor fields and the
  node's TUN device name into one Handles struct the supervisor holds.
  The supervisor arms, their order and the child-exit reporting are
  unchanged. A TUN still counts as up when it has a device
  name, so an app-owned TUN produces no TUN teardown, and DNS counts as
  up while its task runs. The node passes a new peer-alias base to the
  running responder through Handles::publish_aliases. Node::tun_name,
  tun_tx, dns_local_addr and enable_app_owned_tun keep their behaviour;
  tests install a TUN sender through a test-only Node::install_tun.

Tracing targets follow module paths, so lines from the moved code now
log under fips::ipv6tun::* and fips::hosts instead of fips::upper::*,
fips::node::lifecycle and fips::node::handlers::session. Update the
RUST_LOG example in the MTU diagnosis guide and the test harness
filters that relied on the old targets, and note the rename in the
changelog.

2026-10-05 16:27:45 +00:00

node

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

relay

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

router

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

scripts

Retry test, package and NAT lab image builds across transient registry failures

2026-09-19 15:43:27 +00:00

stun

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

.gitignore

Give the NAT lab per-run generated configs

2026-07-27 14:34:33 +00:00

docker-compose.external-net.yml

Claim the NAT lab's two bridges per run and derive every address from them

2026-07-27 14:34:46 +00:00

docker-compose.yml

Gather the host-side IPv6 plane into the ipv6tun module

2026-10-05 16:27:45 +00:00

README.md

test(nat): contain strfry relay aborts in the NAT lab

2026-09-19 09:11:46 +00:00

README.md

NAT Lab Harness

Real Docker-based NAT traversal integration tests for the mainline FIPS Nostr/STUN bootstrap path.

This harness spins up:

two FIPS nodes
a local Nostr relay
a local STUN server
one or two Linux router containers performing NAT with iptables

For the NAT scenarios, the node LAN interfaces are not attached to Docker bridge networks. The harness creates explicit veth pairs and moves them into the node and router namespaces after docker compose up so every packet must traverse the router namespace.

It covers three scenarios:

cone: both peers behind explicit namespace/veth full-cone emulation, UDP traversal succeeds
symmetric: both peers behind symmetric-style NAT, UDP traversal fails, TCP fallback succeeds
lan: both peers share a LAN subnet, LAN targets are preferred over reflexive addresses

NAT model notes

The harness does not rely on plain Docker MASQUERADE for the cone case.

cone
- uses explicit full-cone emulation in the router namespace
- outbound UDP is SNATed to the router WAN address while preserving the source port
- inbound UDP to the router WAN address is DNATed back to the single LAN host regardless of remote source
symmetric
- uses UDP MASQUERADE --random-fully
- outbound mappings may be port-randomized and are only reopened by matching conntrack state

This distinction matters because plain MASQUERADE is convenient source NAT, but it does not by itself model the "accept from any remote once mapped" behavior expected from a full-cone NAT.

Prerequisites

Docker with Compose support
locally built fips-test:latest

Build the test image with:

./testing/scripts/build.sh

Run

Run all scenarios:

./testing/nat/scripts/nat-test.sh

Run one scenario:

./testing/nat/scripts/nat-test.sh cone
./testing/nat/scripts/nat-test.sh symmetric
./testing/nat/scripts/nat-test.sh lan

Layout

docker-compose.yml
- relay/STUN/WAN topology plus container definitions
node/
- node bootstrap wrapper that waits for the injected veth interface
router/
- NAT router image and iptables setup
stun/
- minimal STUN binding responder
relay/
- local strfry config. The relay image's strfry build is pinned by digest in docker-compose.yml (STRFRY_IMAGE); bump it there deliberately.
scripts/generate-configs.sh
- derives ephemeral identities and writes per-scenario FIPS configs
scripts/setup-topology.sh
- injects and configures the NAT LAN veth pairs in the container namespaces
scripts/nat-test.sh
- boots the lab, waits for convergence, and asserts the resulting path
scripts/nostr-relay-test.sh
- exercises the Nostr overlay advert publish/consume round-trip, including rejection of a malformed advert event
scripts/stun-faults-test.sh
- cycles the daemon through STUN drop, delay and outage faults and asserts graceful behavior at each step

Assertions

cone
- both nodes connect
- connected transport is UDP
- active link remote addresses are on the WAN NAT subnet
symmetric
- NAT bootstrap does not establish a UDP link
- fallback converges
- connected transport is TCP via router-published WAN addresses
lan
- both nodes connect
- connected transport is UDP
- active link remote addresses stay on the shared LAN subnet