ArjenandJohnathan Corgan
106ca7b00d
The seam that exposes the UDP transport's descriptor, and the label that
makes it usable on a node running more than one listener. They land as
one commit because the second replaces the first's channel item: the
seam alone publishes a bare `RawFd` signature that the label then
breaks, so landing them separately would publish an interface only to
break it a commit later.
Each original commit message follows in full.
--- expose the UDP transport's socket fd for app-owned network binding ---
The UDP transport binds one socket and selects the egress path per
destination address. That assumes the host routes by destination alone —
true on an ordinary Unix box, not true everywhere. On hosts that instead
associate each socket with exactly one interface or "network" and steer
inbound traffic by that association, a peer reachable only over a
secondary, non-default network is unreachable in a way FIPS can neither
see nor fix: the address is well-formed, the send succeeds, the peer
receives our handshake and replies, and the host discards the reply
before it reaches our socket. The link retries msg1 forever with no
error surfaced anywhere.
FIPS cannot correct that from the inside, because the correction is a
socket option on a socket the transport keeps entirely private, chosen
against host-specific network state FIPS has no basis to reason about.
So hand the embedder the descriptor:
let rx = node.enable_app_owned_udp_fd(); // after new(), before start()
node.start().await?;
let fd = rx.recv_timeout(timeout)?; // once the transport is up
This follows the existing `enable_app_owned_tun` contract — call after
`Node::new` and before `start()`, get a channel back — and its state
lives in the same place, as a `Supervisor` field fired from the
transport-spawn arm of `start()`. It stays deliberately narrow: FIPS
keeps owning the socket, and the fd carries no promise beyond "this is
the transport's socket, and it is open now". One message is sent per UDP
transport that successfully binds, so the usual single-listener config
yields exactly one while a multi-listener config yields all of them —
an embedder pinning sockets to a network needs every one, so the seam
does not latch after the first. If no UDP transport is configured, or
one fails to bind, nothing is ever sent, so an embedder distinguishes
"no socket" from "here is the socket" by the receive timing out.
Also plumbs `raw_fd()` through `TransportHandle` and `UdpTransport`,
following the shape of the existing `local_addr()` / `interface_name()`
accessors: the UDP arm reports the bound socket, every other transport
reports `None`, and the whole thing is unix-only since `RawFd` is a unix
concept and the Windows UDP backend has no descriptor. Because non-UDP
handles report `None`, the lifecycle hook needs no transport-type test.
Two limits worth naming rather than leaving to be discovered. The fd is
the transport's wildcard listen socket: on targets that also run the
per-peer connected-UDP fast path (Linux and macOS), the additional
`connect()`-ed sockets that path opens per established peer, after
`start()` has returned, are not covered by this seam — on targets
without that path the wildcard socket is the only UDP socket the
transport opens. And a transport that adopts a socket handed in from
outside (the NAT-traversal bootstrap handoff) does not fire the seam,
since whoever supplied the socket already held its fd.
There is no in-tree consumer, exactly as with `enable_app_owned_tun`:
the seam exists for embedders, and the tests cover the contract
directly — delivery of the live socket's fd and only after the bind,
one message per listener that binds, silence when there is no UDP
transport and when one fails to bind, per-node channels on a rebuilt
node, and last-arming-wins on a re-arm.
--- label each app-owned UDP fd with the instance it belongs to ---
`enable_app_owned_udp_fd` handed out a bare `RawFd`. That is sufficient for
one listener and useless for more than one: a node configured with named UDP
instances delivers one message per instance, and the embedder — whose whole
reason for holding the descriptor is to associate the socket with one host
network — has no way to tell which socket it just received. Transports are
created by iterating a `HashMap`, so arrival order is not a tiebreaker; it is
luck. Guessing wrong pins one lane's socket to the other lane's network, which
is exactly the failure the seam exists to let an embedder correct.
Send `AppOwnedUdpSocket { instance, fd }` instead. `instance` is the name the
listener was configured under — the same name a peer address qualifies its
transport field with (`"udp/aware"`), so the label the embedder binds by and
the label the dialer routes by are one string. `None` for a `Single` config,
which has no name to give.
A struct rather than a tuple: the receiving side reads `socket.instance` /
`socket.fd` rather than `.0` / `.1`, and adding the bound local address later
would not break every embedder.
The single-listener case is unchanged in substance — one message, `instance:
None` — but it is a breaking signature change for anyone matching on the
channel item.
--- changelog ---
One entry under Added, describing what the release ships rather than the
order the commits landed in: the channel carries `AppOwnedUdpSocket {
instance, fd }`, and the entry says why the label is what makes more
than one listener usable at all.
FIPS: Free Internetworking Peering System
A self-organizing encrypted mesh network built on Nostr identities, capable of operating over arbitrary transports without central infrastructure.
FIPS is under active development. The protocol and APIs are not yet stable. See Status & roadmap below.
What FIPS does
A machine running FIPS becomes a node in the mesh with a self-generated cryptographic identity (a Nostr keypair). There are two equally-supported deployment modes.
As an overlay on top of existing IP networks, FIPS lets your node reach any other FIPS node wherever it sits — behind a NAT, on a different ISP, on a phone over cellular, on a laptop with only Bluetooth in range, or behind a Tor onion. The mesh forwards IPv6 traffic transparently and end-to-end encrypted, with no central VPN concentrator or coordinating server.
Ground up over raw Ethernet, WiFi, or Bluetooth, FIPS provides a complete permissionless network without any pre-existing IP infrastructure, ISP, or DNS. Any node that joins the link gets routable IPv6 addresses, peer discovery, and a path to every other node automatically.
Either way, existing networking software runs over it unchanged — SSH, HTTP servers, file transfer, anything IPv6-native works the same way it would on a local network.
Features
- Self-organizing mesh routing. Spanning-tree coordinates with bloom-filter-guided discovery; no global routing tables, no flooding.
- Multi-transport. UDP, TCP, Ethernet, Tor, Nym, and Bluetooth (BLE L2CAP) ship today; transports compose on a single mesh and a node may run several at once.
- Two-layer encryption. Noise IK between peers (hop-by-hop) and Noise XK between mesh endpoints (independent end-to-end), with periodic rekey for forward secrecy.
- Nostr-native identity. secp256k1 / schnorr keypairs as node addresses; self-generated, no registration, no central authority.
- IPv6 adapter. A TUN interface maps each remote npub to an
fd00::/8address, so unmodified IPv6 software reaches mesh peers as<npub>.fips. Built-in.fipsDNS resolver, with optional static name mapping via/etc/fips/hosts. - Nostr-mediated discovery and NAT traversal. Peers publish endpoint adverts on public Nostr relays, exchange candidates via NIP-59 gift-wrapped offers and answers, and establish direct paths through NATs using STUN-assisted hole punching. On the local network, mDNS LAN discovery finds peers directly without relays.
- LAN gateway. Optional
fips-gatewayservice folds an entire unmodified LAN into the mesh: outbound (LAN clients reach mesh destinations through a DNS-allocated virtual IPv6 pool and nftables NAT) and inbound (LAN-side services exposed to the mesh through 1:1 port forwards). - Per-link metrics. RTT, loss, jitter, and goodput on every hop, plus mesh-size estimation, via the Metrics Measurement Protocol.
- ECN congestion signaling. Hop-by-hop CE-flag relay with RFC 3168 IPv6 marking and transport kernel-drop detection.
- Mesh-interface security baseline. Optional default-deny
nftables policy for
fips0shipped as a packaged conffile (/etc/fips/fips.nft) with an operator drop-in directory (/etc/fips/fips.d/) and a disabled-by-defaultfips-firewall.service. The baseline polices only the mesh interface, leaving Docker, Tor, and the host firewall untouched. - Operator visibility.
fipsctlCLI for control and inspection with time-series stats history queryable for any metric,fipstopTUI for live status with inline sparkline dashboards, and a JSON-line control socket on each binary for direct programmatic access. - Reproducible builds with toolchain pinning and
SOURCE_DATE_EPOCH.
Quick start
The shortest path on Debian / Ubuntu:
git clone https://github.com/jmcorgan/fips.git
cd fips
cargo install cargo-deb
cargo deb
sudo dpkg -i target/debian/fips_*.deb
sudo systemctl start fips
This installs the daemon, CLI tools (fipsctl, fipstop), the
optional fips-gateway service, systemd units, and a default
/etc/fips/fips.yaml you can edit before starting.
For macOS, Windows, OpenWrt, the systemd tarball, a Nix flake, or a from-source build, see docs/getting-started.md for the full multi-platform installation guide.
To join a live mesh and reach your first peer, follow the new-user tutorial progression starting at docs/tutorials/join-the-test-mesh.md.
Building from source
cargo build --release
Requires Rust 1.94.1+ (edition 2024). Linux, macOS, FreeBSD, and Windows
run as standalone daemons; Android is supported as an embedded library
(the host app owns the TUN, e.g. a VpnService). Transport availability
varies by platform.
| Transport | Linux | macOS | FreeBSD | Windows | Android | OpenWrt |
|---|---|---|---|---|---|---|
| UDP | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| TCP | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Ethernet | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
| Tor | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| Nym | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| BLE | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
On Linux, a source build requires libclang — the LAN gateway's
nftables bindings are generated by bindgen at build time, which
needs libclang.so on the build host. Install it before building
(sudo apt install libclang-dev on Debian / Ubuntu); without it the
build fails inside the rustables crate with an "Unable to find
libclang" error. This is a build-time prerequisite only — it is not a
runtime dependency, and the pre-built .deb artifacts do not need it.
BLE is optional and, on Linux, requires BlueZ and libdbus
(sudo apt install bluez libdbus-1-dev on Debian / Ubuntu). It is
gated on a build-script probe — install the dependencies first and
the cargo build line above picks it up. The OpenWrt ipk omits
BLE because libdbus is not available on the target.
Nym (mixnet) transport builds on all desktop platforms. The OpenWrt
❌ is provisional, pending verification of nym-socks5-client
availability on the target; it will flip to ✅ only if confirmed
buildable there.
Alternatively, the repo ships a Nix flake: nix develop
drops you into a shell with the pinned toolchain and every build
prerequisite (libclang, dbus, pkg-config) already provided, and
nix build .#fips builds all four binaries with no host setup. See the
Nix / NixOS section of packaging/README.md.
Documentation
docs/ is organised by reader purpose:
- Tutorials — hand-held walk-throughs from a fresh install through to a participating mesh node, plus advanced deployments (gateway on OpenWrt, hosting services, ground-up two-device mesh).
- How-to guides — operator recipes for specific tasks: firewall activation, Nostr discovery, Tor onion service, Bluetooth peering, LAN gateway deployment and troubleshooting, MTU diagnostics, host aliases, persistent identity, unprivileged-user setup, UDP buffer tuning.
- Reference —
fips.yamlconfiguration, wire formats, control-socket protocol, CLI references for each binary, security posture matrix, Nostr events catalog, transport statistics inventory. - Design — protocol-level architecture and layer specifications. Start with fips-concepts.md for the framing, then fips-architecture.md for the protocol stack.
If you want to contribute, see CONTRIBUTING.md and testing/README.md.
Examples
- examples/sidecar-nostr-relay/ — Run a strfry Nostr relay reachable exclusively over the FIPS mesh. The relay container shares the FIPS sidecar's network namespace and is isolated from the host network.
- examples/sidecar-nostr-mixnet-relay/ — Single-container demo of FIPS peering through a mixnet (implemented with Nym): the FIPS daemon, the mixnet proxy, and a strfry Nostr relay all in one isolated container, with the direct route to the peer firewalled off so traffic provably crosses the mixnet.
- examples/k8s-sidecar/ — Run FIPS as
a Kubernetes Pod sidecar. The sidecar creates
fips0in the Pod's shared network namespace so every other container in the Pod gets mesh access without modification. - examples/wireguard-sidecar-macos/ —
Reach the FIPS mesh from a macOS host through a local Docker
container over a WireGuard tunnel. Only traffic destined for
fd00::/8transits the sidecar; regular internet traffic continues to use the host network.
Project structure
src/ Rust source: library + fips, fipsctl, fipstop, fips-gateway binaries
docs/ Documentation: tutorials, how-to, reference, design
packaging/ Debian, macOS .pkg, Windows ZIP, OpenWrt ipk, AUR, systemd tarball
examples/ Deployment examples (Nostr relay, K8s sidecar, macOS WireGuard)
testing/ Docker-based integration test harnesses + chaos simulation
Status & roadmap
FIPS is at v0.5.0-dev on the master branch.
v0.4.1 has
shipped; this development line continues the testing-and-polishing
track toward v0.5.0. The core protocol works end-to-end over
UDP, TCP, Ethernet, Tor, Nym, and Bluetooth on a global, public test
mesh of thousands of nodes. v0.4.0 added the Nym mixnet transport and
mDNS LAN discovery alongside the existing Nostr-mediated peer discovery,
UDP NAT traversal, peer ACL, and packaging hardening. New wire-format work
continues to be staged on the next branch for the subsequent
release line.
What works today
- Spanning-tree construction with greedy coordinate routing.
- Bloom-filter-guided destination discovery (no flooding, single-path with retry).
- Two-layer Noise encryption (IK at the link, XK at the session) with periodic hitless rekey for forward secrecy at both layers.
- Persistent or ephemeral node identity with key-file management.
- IPv6 TUN adapter with built-in
.fipsDNS resolver and multi-backend auto-configuration (systemd dns-delegate, systemd-resolved, dnsmasq, NetworkManager). - Static hostname mapping (
/etc/fips/hosts) with auto-reload. - Per-link metrics (RTT, loss, jitter, goodput) and mesh size estimation.
- ECN congestion signaling (hop-by-hop CE relay, IPv6 CE marking, kernel-drop detection).
- UDP, TCP, Ethernet, Tor, Nym (mixnet), and BLE transports (BLE via L2CAP CoC with per-link MTU negotiation).
- Nostr-mediated overlay endpoint discovery and UDP hole punching for NAT traversal, plus mDNS LAN discovery for local peers.
- LAN gateway (
fips-gateway) with both outbound (LAN-to-mesh) and inbound (mesh-to-LAN port-forwarding) modes. - Peer ACL: per-npub allow / deny admission control at the link
layer; opt-in mesh-firewall baseline at
fips0ingress. - Runtime inspection and peer management via
fipsctlandfipstop. - Reproducible builds with toolchain pinning and
SOURCE_DATE_EPOCH. - Linux (Debian, systemd tarball, OpenWrt, AUR), macOS (
.pkg), FreeBSD (.pkg), and Windows (ZIP, service) packaging. - Docker-based integration and chaos testing.
Near-term priorities
- Native API for FIPS-aware applications (npub:port addressing without the IPv6-shim path).
- Security audit of the cryptographic protocols.
Longer-term
- Mobile platform support.
- Bandwidth-aware routing and QoS.
- Protocol stability and a versioned wire format.
- Published crate.
License
MIT — see LICENSE.