From 5029b40d4999ed559a4ea85634ab519e530e0171 Mon Sep 17 00:00:00 2001 From: Johnathan Corgan Date: Mon, 13 Apr 2026 06:33:01 +0000 Subject: [PATCH] Update README for current platform, transport, and example state - Correct the transport matrix: UDP, TCP, and Tor work on Windows (previously shown as unsupported). Add an OpenWrt column with BLE disabled due to missing libdbus on the target. - Mention the `.fips` DNS resolver and outbound LAN gateway in the Features list, and add the gateway bullet under What works today. - Reframe the Linux DNS resolver setup: the `.deb` package now auto-configures the available backend; the manual resolvectl snippet is shown for tarball and manual installs. - Expand the Examples section to list all three example deployments (Nostr relay sidecar, K8s sidecar, macOS WireGuard sidecar) rather than only the macOS one. - Refresh Project Structure to include the `fips-gateway` binary, the full packaging list (macOS .pkg, Windows ZIP, OpenWrt ipk, AUR in addition to Debian and systemd tarball), and the examples directory. - Mention macOS `.pkg` and Windows ZIP/service packaging in the packaging line of What works today. --- README.md | 64 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 43 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index ceccad3..8cf6cc8 100644 --- a/README.md +++ b/README.md @@ -44,8 +44,12 @@ endpoints. end-to-end session encryption (XK), with periodic rekey for forward secrecy - **Nostr-native identity** — secp256k1 keypairs as node addresses, no registration or central authority -- **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses for - unmodified IP applications; static hostname mapping (`/etc/fips/hosts`) +- **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses + for unmodified IP applications; built-in `.fips` DNS resolver with + optional static hostname mapping (`/etc/fips/hosts`) +- **Outbound LAN gateway** — optional `fips-gateway` daemon lets + unmodified LAN hosts reach `.fips` destinations via a + DNS-allocated virtual IP pool and kernel nftables NAT - **Metrics Measurement Protocol** — per-link RTT, loss, jitter, and goodput measurement with mesh size estimation - **ECN congestion signaling** — hop-by-hop CE flag relay with RFC 3168 IPv6 @@ -68,18 +72,21 @@ supported (see transport matrix below). ### Transport support by platform -| Transport | Linux | macOS | Windows | -|-----------|:-----:|:-----:|:-------:| -| UDP | ✅ | ✅ | ❌ | -| TCP | ✅ | ✅ | ❌ | -| Ethernet | ✅ | ✅ | ❌ | -| Tor | ✅ | ✅ | ❌ | -| BLE | ✅ | ❌ | ❌ | +| Transport | Linux | macOS | Windows | OpenWrt | +|-----------|:-----:|:-----:|:-------:|:-------:| +| UDP | ✅ | ✅ | ✅ | ✅ | +| TCP | ✅ | ✅ | ✅ | ✅ | +| Ethernet | ✅ | ✅ | ❌ | ✅ | +| Tor | ✅ | ✅ | ✅ | ✅ | +| BLE | ✅ | ❌ | ❌ | ❌ | On **Linux**, the BLE transport requires BlueZ and libdbus. On Debian/Ubuntu: `sudo apt install bluez libdbus-1-dev`. Then build with BLE enabled: `cargo build --release --features ble`. +On **OpenWrt**, BLE is disabled because libdbus is not available on +the target. All other transports work and ship in the default ipk. + ## Installation After building, choose one of the following methods to install. @@ -261,7 +268,11 @@ for the full reference. FIPS includes a DNS resolver (enabled by default, port 5354) that maps `.fips` names to fd00::/8 IPv6 addresses. -**Linux** (systemd-resolved): +**Linux**: The `.deb` package auto-detects and configures whichever +resolver is present (systemd dns-delegate, systemd-resolved, dnsmasq, +or NetworkManager with dnsmasq); no manual setup is needed. For +manual or tarball installs, point your resolver at `127.0.0.1:5354` +for the `fips` domain — e.g., with systemd-resolved: ```bash sudo resolvectl dns fips0 127.0.0.1:5354 @@ -322,13 +333,20 @@ including static topology tests and stochastic chaos simulation. ## Examples -- [examples/wireguard-sidecar-macos/](examples/wireguard-sidecar-macos/) - - Run a local WireGuard sidecar on macOS so `.fips` traffic can reach the mesh - through Docker. - -The macOS WireGuard sidecar only forwards FIPS IPv6 traffic destined for -`fd00::/8` from `wg0` to `fips0`. Regular internet traffic does not transit the -sidecar and continues to use the host network normally. +- [examples/sidecar-nostr-relay/](examples/sidecar-nostr-relay/) — + Run a [strfry](https://github.com/hoytech/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/k8s-sidecar/](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/](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. ## Documentation @@ -345,8 +363,9 @@ If you want to contribute, start with: ## Project Structure ```text -src/ Rust source (library + fips/fipsctl/fipstop binaries) -packaging/ Debian, systemd tarball, and shared packaging files +src/ Rust source (library + fips/fipsctl/fipstop/fips-gateway binaries) +packaging/ Debian, macOS .pkg, Windows ZIP, OpenWrt ipk, AUR, systemd tarball +examples/ Deployment examples (Nostr relay, K8s sidecar, macOS WireGuard) docs/design/ Protocol design specifications testing/ Docker-based integration test harnesses ``` @@ -363,14 +382,17 @@ Ethernet, Tor, and Bluetooth (BLE) with a small live mesh of deployed nodes. - Noise IK (link layer) and Noise XK (session layer) encryption - Periodic Noise rekey with hitless cutover for forward secrecy (FMP + FSP) - Persistent node identity with key file management -- IPv6 TUN adapter with DNS resolution of `.fips` names +- 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, and BLE transports (BLE via L2CAP CoC with per-link MTU negotiation) +- Outbound LAN gateway for unmodified hosts via DNS-allocated virtual IPs and nftables NAT - Runtime inspection and peer management via `fipsctl` and `fipstop` - Reproducible builds with toolchain pinning and SOURCE_DATE_EPOCH -- Linux (Debian, systemd tarball, OpenWrt, AUR) and macOS packaging +- Linux (Debian, systemd tarball, OpenWrt, AUR), macOS (`.pkg`), and Windows (ZIP, service) packaging - Docker-based integration and chaos testing ### Near-term priorities