mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-22 07:48:26 +00:00
docs: rewrite top-level README for v0.3.0-dev
- Status badge v0.2.0 → v0.3.0-dev. - Lede rewritten around the two equally-supported deployment modes (overlay on existing IP networks; ground-up over raw Ethernet, WiFi, Bluetooth) matching docs/README.md and docs/getting-started.md. - Features list refreshed: Nostr-mediated discovery and UDP NAT traversal called out, LAN gateway described as both halves (outbound + inbound port forwarding), peer ACL and control-socket-per-binary noted. - Quick start trimmed to the Debian inline path + pointer at docs/getting-started.md for the multi-platform walkthrough; transport-by-platform matrix retained. - Documentation section reorganised around the four-section docs/ tree (tutorials, how-to, reference, design) with one entry-point pointer per section. - Stale doc links fixed (docs/design/fips-intro.md → docs/design/fips-concepts.md; docs/design/fips-configuration.md no longer linked). - Status & roadmap rewritten for the v0.3.0-dev release-line scope (no new wire-format changes; FMP swap deferred to the next-branch post-v0.3.0 line). 422 → 235 lines.
This commit is contained in:
Johnathan Corgan
550
README.md
550
README.md
@@ -3,419 +3,231 @@
|
||||
|
||||
[](LICENSE)
|
||||
[](https://www.rust-lang.org/)
|
||||
[](#status--roadmap)
|
||||
[](#status--roadmap)
|
||||
|
||||
A distributed, decentralized network routing protocol for mesh nodes
|
||||
connecting over arbitrary transports.
|
||||
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](#status--roadmap) below.
|
||||
> FIPS is under active development. The protocol and APIs are not
|
||||
> yet stable. See [Status & roadmap](#status--roadmap) below.
|
||||
|
||||
## Overview
|
||||
## What FIPS does
|
||||
|
||||
FIPS is a self-organizing mesh network that operates natively over a variety
|
||||
of physical and logical media — local area networks, Bluetooth, serial links,
|
||||
radio, or the existing internet as an overlay. Nodes generate their own
|
||||
identities, discover each other, and route traffic without any central
|
||||
authority or global topology knowledge.
|
||||
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.
|
||||
|
||||
FIPS uses Nostr keypairs (secp256k1/schnorr) as native node identities,
|
||||
allowing users to generate their own persistent or ephemeral node addresses.
|
||||
Nodes address each other by npub, and the same cryptographic identity serves
|
||||
as both the routing address and the basis for end-to-end encrypted sessions
|
||||
across the mesh.
|
||||
**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.
|
||||
|
||||
FIPS allows existing TCP/IP based network software to use the FIPS mesh
|
||||
network by generating a local IP address from the node npub and tunnelling
|
||||
IP packets to other endpoints transparently knowing only their npub. Native
|
||||
FIPS-aware applications do not need this IP tunneling or emulation capability.
|
||||
**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.
|
||||
|
||||
All traffic over the FIPS mesh is encrypted and authenticated both
|
||||
hop-to-hop between peers and independently end-to-end between FIPS
|
||||
endpoints.
|
||||
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
|
||||
- **Multi-transport** — UDP, TCP, Ethernet, Tor, and Bluetooth (BLE L2CAP)
|
||||
today; designed for serial and radio
|
||||
- **Noise encryption** — hop-by-hop link encryption (IK) plus independent
|
||||
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; 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
|
||||
marking, transport kernel drop detection
|
||||
- **Operator visibility** — `fipsctl` CLI and `fipstop` TUI dashboard for
|
||||
runtime inspection and runtime peer management
|
||||
- **Zero configuration** — sensible defaults; a node can start with no config
|
||||
file, though peer addresses are needed to join a network
|
||||
- **Self-organizing mesh routing.** Spanning-tree coordinates with
|
||||
bloom-filter-guided discovery; no global routing tables, no
|
||||
flooding.
|
||||
- **Multi-transport.** UDP, TCP, Ethernet, Tor, 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.
|
||||
- **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.
|
||||
- **Operator visibility.** `fipsctl` CLI for control and inspection,
|
||||
`fipstop` TUI for live status, and a JSON-line control socket on
|
||||
each binary for direct programmatic access.
|
||||
- **Reproducible builds** with toolchain pinning and
|
||||
`SOURCE_DATE_EPOCH`.
|
||||
|
||||
## Building
|
||||
## Quick start
|
||||
|
||||
The shortest path on Debian / Ubuntu:
|
||||
|
||||
```bash
|
||||
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, or a from-source
|
||||
build, see [docs/getting-started.md](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](docs/tutorials/join-the-test-mesh.md).
|
||||
|
||||
### Building from source
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
Requires Rust 1.85+ (edition 2024). Linux, macOS, and Windows are
|
||||
supported (see transport matrix below).
|
||||
|
||||
### Transport support by platform
|
||||
supported; transport availability varies by platform.
|
||||
|
||||
| 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.
|
||||
|
||||
### Debian / Ubuntu (.deb)
|
||||
|
||||
Requires [cargo-deb](https://crates.io/crates/cargo-deb):
|
||||
|
||||
```bash
|
||||
cargo install cargo-deb
|
||||
cargo deb
|
||||
sudo dpkg -i target/debian/fips_*.deb
|
||||
```
|
||||
|
||||
This installs the daemon, CLI tools, systemd units, and a default
|
||||
configuration. Edit `/etc/fips/fips.yaml` before starting:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/fips/fips.yaml
|
||||
sudo systemctl start fips
|
||||
```
|
||||
|
||||
The service is enabled at boot automatically. To use `fipsctl` and
|
||||
`fipstop` without sudo, add your user to the `fips` group:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG fips $USER # log out and back in to take effect
|
||||
```
|
||||
|
||||
Remove with `sudo dpkg -r fips` (preserves config) or
|
||||
`sudo dpkg -P fips` (removes everything including identity keys).
|
||||
|
||||
### Generic Linux (systemd tarball)
|
||||
|
||||
```bash
|
||||
./packaging/systemd/build-tarball.sh
|
||||
tar xzf deploy/fips-*-linux-*.tar.gz
|
||||
cd fips-*-linux-*/
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
See [packaging/systemd/README.install.md](packaging/systemd/README.install.md)
|
||||
for the full installation and configuration guide.
|
||||
|
||||
### macOS (.pkg)
|
||||
|
||||
```bash
|
||||
./packaging/macos/build-pkg.sh
|
||||
sudo installer -pkg deploy/fips-*-macos-*.pkg -target /
|
||||
```
|
||||
|
||||
This installs binaries to `/usr/local/bin/`, config to
|
||||
`/usr/local/etc/fips/`, sets up `.fips` DNS resolution via
|
||||
`/etc/resolver/fips`, and registers a launchd daemon. Edit
|
||||
`/usr/local/etc/fips/fips.yaml` before starting:
|
||||
|
||||
```bash
|
||||
sudo nano /usr/local/etc/fips/fips.yaml
|
||||
sudo launchctl load -w /Library/LaunchDaemons/com.fips.daemon.plist
|
||||
```
|
||||
|
||||
Remove with `sudo packaging/macos/uninstall.sh` (preserves config).
|
||||
|
||||
To restart the node after making configuration changes:
|
||||
|
||||
```bash
|
||||
sudo launchctl unload -w /Library/LaunchDaemons/com.fips.daemon.plist
|
||||
sudo launchctl load -w /Library/LaunchDaemons/com.fips.daemon.plist
|
||||
```
|
||||
|
||||
Check logs for troubleshooting:
|
||||
|
||||
```bash
|
||||
sudo tail -f /usr/local/var/log/fips/fips.log
|
||||
```
|
||||
|
||||
> **Note:** On macOS, the TUN device is named `utun<N>` (kernel-assigned)
|
||||
> rather than `fips0`.
|
||||
|
||||
### Windows
|
||||
|
||||
Build without BLE (requires Linux-only libdbus):
|
||||
|
||||
```powershell
|
||||
cargo build --release --no-default-features --features tui
|
||||
```
|
||||
|
||||
The [wintun](https://www.wintun.net/) driver is required for TUN support.
|
||||
Download `wintun.dll` and place it in the same directory as `fips.exe`.
|
||||
Running the daemon requires Administrator privileges for TUN creation.
|
||||
|
||||
**Foreground mode:**
|
||||
|
||||
```powershell
|
||||
.\fips.exe -c fips.yaml
|
||||
```
|
||||
|
||||
**Windows Service:**
|
||||
|
||||
```powershell
|
||||
# Install (requires Administrator)
|
||||
.\fips.exe --install-service
|
||||
|
||||
# Manage via standard service tools
|
||||
sc start fips
|
||||
sc stop fips
|
||||
|
||||
# Uninstall
|
||||
.\fips.exe --uninstall-service
|
||||
```
|
||||
|
||||
Place `fips.yaml` in the current directory or `%APPDATA%\fips\`, or set
|
||||
the `FIPS_CONFIG` environment variable.
|
||||
|
||||
The control socket uses TCP on `localhost:21210` instead of a Unix domain
|
||||
socket. `fipsctl` and `fipstop` connect to this port automatically.
|
||||
|
||||
## Configuration
|
||||
|
||||
The default configuration file is installed at `/etc/fips/fips.yaml`:
|
||||
|
||||
```yaml
|
||||
# FIPS Node Configuration
|
||||
|
||||
node:
|
||||
identity:
|
||||
# By default, a new ephemeral keypair is generated on each start.
|
||||
# Uncomment persistent to keep the same identity across restarts;
|
||||
# on first start a keypair is saved to fips.key/fips.pub next to
|
||||
# this config file (mode 0600/0644).
|
||||
# persistent: true
|
||||
#
|
||||
# Or set an explicit key (overrides persistent):
|
||||
# nsec: "nsec1..."
|
||||
|
||||
tun:
|
||||
enabled: true
|
||||
name: fips0
|
||||
mtu: 1280
|
||||
|
||||
dns:
|
||||
enabled: true
|
||||
bind_addr: "127.0.0.1"
|
||||
port: 5354
|
||||
|
||||
transports:
|
||||
udp:
|
||||
bind_addr: "0.0.0.0:2121"
|
||||
|
||||
tcp:
|
||||
# Accepts inbound connections. No static outbound peers.
|
||||
bind_addr: "0.0.0.0:8443"
|
||||
|
||||
# Ethernet transport — uncomment and set your interface name.
|
||||
# ethernet:
|
||||
# interface: "eth0"
|
||||
# discovery: true
|
||||
# announce: true
|
||||
# auto_connect: true
|
||||
# accept_connections: true
|
||||
|
||||
peers:
|
||||
# Static peers for bootstrapping (UDP or TCP):
|
||||
- npub: "npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98"
|
||||
alias: "fips-test-node"
|
||||
addresses:
|
||||
- transport: udp
|
||||
addr: "217.77.8.91:2121"
|
||||
connect_policy: auto_connect
|
||||
```
|
||||
|
||||
See [docs/design/fips-configuration.md](docs/design/fips-configuration.md)
|
||||
for the full reference.
|
||||
|
||||
## Usage
|
||||
|
||||
### DNS Resolution
|
||||
|
||||
FIPS includes a DNS resolver (enabled by default, port 5354) that maps
|
||||
`.fips` names to fd00::/8 IPv6 addresses.
|
||||
|
||||
**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
|
||||
sudo resolvectl domain fips0 ~fips
|
||||
```
|
||||
|
||||
**macOS**: DNS is configured automatically by the `.pkg` installer via
|
||||
`/etc/resolver/fips`. No manual setup is needed.
|
||||
|
||||
Then reach any FIPS node by npub with standard IPv6 tools:
|
||||
|
||||
```bash
|
||||
ping6 npub1bbb....fips
|
||||
ssh -6 npub1bbb....fips
|
||||
```
|
||||
|
||||
> **macOS note:** Use `ping6` instead of `ping`. macOS ships separate
|
||||
> `ping` (IPv4-only) and `ping6` (IPv6) binaries; `ping` will not
|
||||
> resolve AAAA records. Similarly, use `curl -6`, `ssh -6`, etc. when
|
||||
> connecting by `.fips` hostname.
|
||||
|
||||
### Monitoring
|
||||
|
||||
Use `fipsctl` to query a running node:
|
||||
|
||||
```bash
|
||||
fipsctl show status # Node status overview
|
||||
fipsctl show peers # Authenticated peers and security state
|
||||
fipsctl show links # Active links
|
||||
fipsctl show tree # Spanning tree state
|
||||
fipsctl show sessions # End-to-end sessions and rekey health
|
||||
fipsctl show bloom # Bloom filter state
|
||||
fipsctl show mmp # MMP metrics summary
|
||||
fipsctl show cache # Coordinate cache entries and routes
|
||||
fipsctl show connections # Pending handshake connections
|
||||
fipsctl show transports # Transport instances
|
||||
fipsctl show routing # Routing, discovery, and retry state
|
||||
fipsctl show identity-cache # Known node identities (npubs)
|
||||
```
|
||||
|
||||
`fipstop` provides an interactive TUI dashboard with live-updating
|
||||
views of node status, peers, links, sessions, tree state, transports,
|
||||
and routing:
|
||||
|
||||
```bash
|
||||
fipstop # connect to local daemon
|
||||
fipstop -r 1 # 1-second refresh interval
|
||||
```
|
||||
|
||||
### Service Management
|
||||
|
||||
```bash
|
||||
sudo systemctl start fips
|
||||
sudo systemctl stop fips
|
||||
sudo systemctl restart fips
|
||||
sudo journalctl -u fips -f
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
See [testing/](testing/) for Docker-based integration test harnesses
|
||||
including static topology tests and stochastic chaos simulation.
|
||||
|
||||
## Examples
|
||||
|
||||
- [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.
|
||||
| UDP | ✅ | ✅ | ✅ | ✅ |
|
||||
| TCP | ✅ | ✅ | ✅ | ✅ |
|
||||
| Ethernet | ✅ | ✅ | ❌ | ✅ |
|
||||
| Tor | ✅ | ✅ | ✅ | ✅ |
|
||||
| BLE | ✅ | ❌ | ❌ | ❌ |
|
||||
|
||||
On Linux, BLE requires BlueZ and libdbus
|
||||
(`sudo apt install bluez libdbus-1-dev` on Debian / Ubuntu) and 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.
|
||||
|
||||
## Documentation
|
||||
|
||||
Protocol design documentation is in [docs/design/](docs/design/), organized as
|
||||
a layered protocol specification. Start with
|
||||
[fips-intro.md](docs/design/fips-intro.md) for the full protocol overview.
|
||||
`docs/` is organised by reader purpose:
|
||||
|
||||
If you want to contribute, start with:
|
||||
- **[Tutorials](docs/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](docs/how-to/)** — 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](docs/reference/)** — `fips.yaml` configuration,
|
||||
wire formats, control-socket protocol, CLI references for each
|
||||
binary, security posture matrix, Nostr events catalog, transport
|
||||
statistics inventory.
|
||||
- **[Design](docs/design/)** — protocol-level architecture and
|
||||
layer specifications. Start with
|
||||
[fips-concepts.md](docs/design/fips-concepts.md) for the framing,
|
||||
then [fips-architecture.md](docs/design/fips-architecture.md) for
|
||||
the protocol stack.
|
||||
|
||||
- [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- [docs/design/README.md](docs/design/README.md)
|
||||
- [testing/README.md](testing/README.md)
|
||||
If you want to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
and [testing/README.md](testing/README.md).
|
||||
|
||||
## Project Structure
|
||||
## Examples
|
||||
|
||||
- **[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.
|
||||
|
||||
## Project structure
|
||||
|
||||
```text
|
||||
src/ Rust source (library + fips/fipsctl/fipstop/fips-gateway binaries)
|
||||
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)
|
||||
docs/design/ Protocol design specifications
|
||||
testing/ Docker-based integration test harnesses
|
||||
testing/ Docker-based integration test harnesses + chaos simulation
|
||||
```
|
||||
|
||||
## Status & Roadmap
|
||||
## Status & roadmap
|
||||
|
||||
FIPS is at **v0.2.0**. The core protocol works end-to-end over UDP, TCP,
|
||||
Ethernet, Tor, and Bluetooth (BLE) with a small live mesh of deployed nodes.
|
||||
FIPS is at **v0.3.0-dev**. The core protocol works end-to-end over
|
||||
UDP, TCP, Ethernet, Tor, and Bluetooth on a small live mesh of
|
||||
deployed nodes. v0.3.0 is the testing-and-polishing track for
|
||||
everything accumulated since v0.2.0 on the v0.2.x wire format —
|
||||
Nostr-mediated peer discovery, UDP NAT traversal, peer ACL, the
|
||||
DNS-responder fix, packaging hardening, and discovery rate-limit
|
||||
retuning. New wire-format work is staged on the `next` branch for
|
||||
the post-v0.3.0 release line.
|
||||
|
||||
### What works today
|
||||
|
||||
- Spanning tree construction with greedy coordinate routing
|
||||
- Bloom filter guided discovery (no flooding, single-path with retry)
|
||||
- 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 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), macOS (`.pkg`), and Windows (ZIP, service) packaging
|
||||
- Docker-based integration and chaos testing
|
||||
- Nostr-mediated overlay endpoint discovery and UDP hole punching for
|
||||
NAT traversal — peers publish endpoint adverts on public Nostr
|
||||
relays, exchange candidates via NIP-59 gift-wrapped offers/answers,
|
||||
and establish direct paths through NATs using STUN-assisted
|
||||
punching
|
||||
- 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, and BLE transports (BLE via L2CAP CoC
|
||||
with per-link MTU negotiation).
|
||||
- Nostr-mediated overlay endpoint discovery and UDP hole punching
|
||||
for NAT traversal.
|
||||
- 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)
|
||||
- Security audit of cryptographic protocols
|
||||
- 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 versioned wire format
|
||||
- Published crate
|
||||
- Mobile platform support.
|
||||
- Bandwidth-aware routing and QoS.
|
||||
- Protocol stability and a versioned wire format.
|
||||
- Published crate.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user