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

Files

T

Johnathan Corgan ee2b70dcd3 Prepare the v0.4.2 release content

Everything the release needs except the version number, which stays at
0.4.2-dev until the tag.

The changelog entry is built from a walk of all 117 commits since v0.4.1
rather than from the open block, which is how the six gaps were found. Two
of them were whole missing effects: the identity write path discarded six
results, so a node configured for a persistent identity could fall through
to an ephemeral one in silence and change its npub, routing address and
mesh address on every start; and the OpenWrt zig download verification was
described only in part. Chronological fix sequences are collapsed to their
net state, and fixes for bugs introduced and closed inside this cycle are
folded away rather than described, since no user ever saw them. Sixty-one
CI and harness commits are summarized in four entries rather than left out,
because they change what a contributor running the local pipeline sees.

Two entries carry effects no commit message mentioned. Clearing every copy
of private key material added Drop to four public types, so their fields
can no longer be moved out, which is source-breaking for anyone using the
crate as a library and is reachable through node.identity on the public
config. And the responder-side rekey narrowing covers five call sites, not
the four the original entry claimed; the ack initiator arm is the one that
deliberately still abandons the whole rekey.

Release notes ship in both the versioned archive and the root mirror, kept
byte-identical. They carry an upgrade section for the two configurations
that now fail validation at start time, since a node that will not restart
after a package upgrade is the sharpest surprise a release can hold.

Four documentation defects are fixed alongside. The readme contradicted
itself about the required Rust version, so the badge no longer asserts one
and the toolchain file is the single source. The persistent-identity
tutorial still sent macOS readers to the Linux configuration directory. The
testing readme claimed twenty chaos scenarios where ten exist, and the
chaos readme documented three that exist nowhere. The bloom-storm scenario
is now described honestly as retired from both runners with no replacement,
which is a coverage gap rather than a migration.

The changelog entry is restructured by subsystem rather than by change kind.
Keep a Changelog puts Added/Changed/Fixed/Security at the top level, which for
a release this size scattered one subsystem across up to four disconnected
places: NAT traversal appeared four times, Admission three, the data plane
three, docs and tooling three. Subsystem is now the top level and the
Keep-a-Changelog kinds sit underneath it, so everything about one part of the
system is in one place. That takes 29 subsections down to 14 sections.

This is a reorganization and not a rewrite. All 80 entries are moved verbatim:
the bullet multiset is identical before and after, the word count is unchanged
at 14814, and everything from the [0.4.1] heading down is untouched. The
departure from Keep a Changelog is deliberate and is the cost of the change;
the trade is per-subsystem readability against per-kind readability, and with
Security at 60% of this release the per-kind reader is the one who loses.

Note this decides the format for [Unreleased] on master and next as well,
which still accumulate v0.5.0 entries in the old shape.

The release notes gain a section on the security content and drop the
references to individual reviews. Most of this release began with reviews
the project did not commission, and the note says so: they are driven by
current frontier language models, their authors say so, the findings have
been legitimate under adversarial re-reading, and none has been reported
active in a deployment. The reviews are described as a class rather than
enumerated, because naming each report tells a reader nothing they need in
order to decide whether to upgrade.

For the same reason the batch section no longer itemises what it leaves
open. It says that some findings are not addressed here, that a wire-format
fix is not a candidate for the 0.4.x line at all, and points at SECURITY.md
for the trust model, which is where that belongs and where it already is.

The notes describe the release rather than how it was assembled. The
opening said a further nineteen fixes landed after the notes were first
drafted, which is drafting history and tells a reader nothing about
whether to upgrade; it now states what the release closes, the added
items folded in beside the rest. The batch heading becomes "Limits,
provenance checks and fail-closed defaults", a description of the work
rather than of its arrival, and the portability paragraph leads with the
two defects fixed instead of with when CI caught them relative to a gate.

At a glance is grouped rather than listed. It was eleven bullets in no
order, with security split across three of them and configuration across
two. The groups are what a reader needs in the order they need it: what
to check before upgrading, security, connectivity and performance, the
new optional keys, and dependencies. The bullets themselves are
unchanged apart from the two that carried the chronology.

The provisional release date moves to 2026-08-24 in all three files that
carry it. It stays provisional: the playbook confirms the date and clears
that wording at the tag, in Phase 7, and this is still Phase 4 content.
All three are updated together because the v0.4.0 release shipped a wrong
date in two of them by scoping the step to one file.

2026-08-24 19:08:27 +01:00

12 KiB

Raw Blame History

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::/8 address, so unmodified IPv6 software reaches mesh peers as <npub>.fips. Built-in .fips DNS 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-gateway service 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 fips0 shipped as a packaged conffile (/etc/fips/fips.nft) with an operator drop-in directory (/etc/fips/fips.d/) and a disabled-by-default fips-firewall.service. The baseline polices only the mesh interface, leaving Docker, Tor, and the host firewall untouched.
Operator visibility. fipsctl CLI for control and inspection with time-series stats history queryable for any metric, fipstop TUI 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, and Windows are supported; transport availability varies by platform.

Transport	Linux	macOS	Windows	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.yaml configuration, 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 fips0 in 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::/8 transits 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.4.2 on the maint branch. v0.4.2 has shipped; this line carries patch-level fixes for the 0.4.x series. 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 .fips DNS 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 fips0 ingress.
Runtime inspection and peer management via fipsctl and fipstop.
Reproducible builds with toolchain pinning and SOURCE_DATE_EPOCH.
Linux (Debian, systemd tarball, OpenWrt, AUR), macOS (.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.

12 KiB Raw Blame History