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.
This commit is contained in:
Johnathan Corgan
2026-04-13 06:33:01 +00:00
parent 6698c4d669
commit 5029b40d49

View File

@@ -44,8 +44,12 @@ endpoints.
end-to-end session encryption (XK), with periodic rekey for forward secrecy end-to-end session encryption (XK), with periodic rekey for forward secrecy
- **Nostr-native identity** — secp256k1 keypairs as node addresses, no - **Nostr-native identity** — secp256k1 keypairs as node addresses, no
registration or central authority registration or central authority
- **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses for - **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses
unmodified IP applications; static hostname mapping (`/etc/fips/hosts`) 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 - **Metrics Measurement Protocol** — per-link RTT, loss, jitter, and goodput
measurement with mesh size estimation measurement with mesh size estimation
- **ECN congestion signaling** — hop-by-hop CE flag relay with RFC 3168 IPv6 - **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 support by platform
| Transport | Linux | macOS | Windows | | Transport | Linux | macOS | Windows | OpenWrt |
|-----------|:-----:|:-----:|:-------:| |-----------|:-----:|:-----:|:-------:|:-------:|
| UDP | ✅ | ✅ | | | UDP | ✅ | ✅ | ✅ | ✅ |
| TCP | ✅ | ✅ | | | TCP | ✅ | ✅ | ✅ | ✅ |
| Ethernet | ✅ | ✅ | ❌ | | Ethernet | ✅ | ✅ | ❌ | ✅ |
| Tor | ✅ | ✅ | | | Tor | ✅ | ✅ | ✅ | ✅ |
| BLE | ✅ | ❌ | ❌ | | BLE | ✅ | ❌ | ❌ | ❌ |
On **Linux**, the BLE transport requires BlueZ and libdbus. On On **Linux**, the BLE transport requires BlueZ and libdbus. On
Debian/Ubuntu: `sudo apt install bluez libdbus-1-dev`. Then build with Debian/Ubuntu: `sudo apt install bluez libdbus-1-dev`. Then build with
BLE enabled: `cargo build --release --features ble`. 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 ## Installation
After building, choose one of the following methods to install. 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 includes a DNS resolver (enabled by default, port 5354) that maps
`.fips` names to fd00::/8 IPv6 addresses. `.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 ```bash
sudo resolvectl dns fips0 127.0.0.1:5354 sudo resolvectl dns fips0 127.0.0.1:5354
@@ -322,13 +333,20 @@ including static topology tests and stochastic chaos simulation.
## Examples ## Examples
- [examples/wireguard-sidecar-macos/](examples/wireguard-sidecar-macos/) - - [examples/sidecar-nostr-relay/](examples/sidecar-nostr-relay/)
Run a local WireGuard sidecar on macOS so `.fips` traffic can reach the mesh Run a [strfry](https://github.com/hoytech/strfry) Nostr relay
through Docker. reachable exclusively over the FIPS mesh. The relay container shares
the FIPS sidecar's network namespace and is isolated from the host
The macOS WireGuard sidecar only forwards FIPS IPv6 traffic destined for network.
`fd00::/8` from `wg0` to `fips0`. Regular internet traffic does not transit the - [examples/k8s-sidecar/](examples/k8s-sidecar/) — Run FIPS as a
sidecar and continues to use the host network normally. 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 ## Documentation
@@ -345,8 +363,9 @@ If you want to contribute, start with:
## Project Structure ## Project Structure
```text ```text
src/ Rust source (library + fips/fipsctl/fipstop binaries) src/ Rust source (library + fips/fipsctl/fipstop/fips-gateway binaries)
packaging/ Debian, systemd tarball, and shared packaging files 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 docs/design/ Protocol design specifications
testing/ Docker-based integration test harnesses 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 - Noise IK (link layer) and Noise XK (session layer) encryption
- Periodic Noise rekey with hitless cutover for forward secrecy (FMP + FSP) - Periodic Noise rekey with hitless cutover for forward secrecy (FMP + FSP)
- Persistent node identity with key file management - 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 - Static hostname mapping (`/etc/fips/hosts`) with auto-reload
- Per-link metrics (RTT, loss, jitter, goodput) and mesh size estimation - 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) - 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) - 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` - Runtime inspection and peer management via `fipsctl` and `fipstop`
- Reproducible builds with toolchain pinning and SOURCE_DATE_EPOCH - 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 - Docker-based integration and chaos testing
### Near-term priorities ### Near-term priorities