mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +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
@@ -3,419 +3,231 @@
|
|||||||
|
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
[](https://www.rust-lang.org/)
|
[](https://www.rust-lang.org/)
|
||||||
[](#status--roadmap)
|
[](#status--roadmap)
|
||||||
|
|
||||||
A distributed, decentralized network routing protocol for mesh nodes
|
A self-organizing encrypted mesh network built on Nostr identities,
|
||||||
connecting over arbitrary transports.
|
capable of operating over arbitrary transports without central
|
||||||
|
infrastructure.
|
||||||
|
|
||||||
> FIPS is under active development. The protocol and APIs are not yet stable.
|
> FIPS is under active development. The protocol and APIs are not
|
||||||
> See [Status & Roadmap](#status--roadmap) below.
|
> 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
|
A machine running FIPS becomes a node in the mesh with a
|
||||||
of physical and logical media — local area networks, Bluetooth, serial links,
|
self-generated cryptographic identity (a Nostr keypair). There are
|
||||||
radio, or the existing internet as an overlay. Nodes generate their own
|
two equally-supported deployment modes.
|
||||||
identities, discover each other, and route traffic without any central
|
|
||||||
authority or global topology knowledge.
|
|
||||||
|
|
||||||
FIPS uses Nostr keypairs (secp256k1/schnorr) as native node identities,
|
**As an overlay** on top of existing IP networks, FIPS lets your
|
||||||
allowing users to generate their own persistent or ephemeral node addresses.
|
node reach any other FIPS node wherever it sits — behind a NAT, on
|
||||||
Nodes address each other by npub, and the same cryptographic identity serves
|
a different ISP, on a phone over cellular, on a laptop with only
|
||||||
as both the routing address and the basis for end-to-end encrypted sessions
|
Bluetooth in range, or behind a Tor onion. The mesh forwards IPv6
|
||||||
across the mesh.
|
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
|
**Ground up** over raw Ethernet, WiFi, or Bluetooth, FIPS provides
|
||||||
network by generating a local IP address from the node npub and tunnelling
|
a complete permissionless network without any pre-existing IP
|
||||||
IP packets to other endpoints transparently knowing only their npub. Native
|
infrastructure, ISP, or DNS. Any node that joins the link gets
|
||||||
FIPS-aware applications do not need this IP tunneling or emulation capability.
|
routable IPv6 addresses, peer discovery, and a path to every other
|
||||||
|
node automatically.
|
||||||
|
|
||||||
All traffic over the FIPS mesh is encrypted and authenticated both
|
Either way, existing networking software runs over it unchanged —
|
||||||
hop-to-hop between peers and independently end-to-end between FIPS
|
SSH, HTTP servers, file transfer, anything IPv6-native works the
|
||||||
endpoints.
|
same way it would on a local network.
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Self-organizing mesh routing** — spanning tree coordinates with bloom
|
- **Self-organizing mesh routing.** Spanning-tree coordinates with
|
||||||
filter guided discovery, no global routing tables
|
bloom-filter-guided discovery; no global routing tables, no
|
||||||
- **Multi-transport** — UDP, TCP, Ethernet, Tor, and Bluetooth (BLE L2CAP)
|
flooding.
|
||||||
today; designed for serial and radio
|
- **Multi-transport.** UDP, TCP, Ethernet, Tor, and Bluetooth (BLE
|
||||||
- **Noise encryption** — hop-by-hop link encryption (IK) plus independent
|
L2CAP) ship today; transports compose on a single mesh and a
|
||||||
end-to-end session encryption (XK), with periodic rekey for forward secrecy
|
node may run several at once.
|
||||||
- **Nostr-native identity** — secp256k1 keypairs as node addresses, no
|
- **Two-layer encryption.** Noise IK between peers (hop-by-hop) and
|
||||||
registration or central authority
|
Noise XK between mesh endpoints (independent end-to-end), with
|
||||||
- **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses
|
periodic rekey for forward secrecy.
|
||||||
for unmodified IP applications; built-in `.fips` DNS resolver with
|
- **Nostr-native identity.** secp256k1 / schnorr keypairs as node
|
||||||
optional static hostname mapping (`/etc/fips/hosts`)
|
addresses; self-generated, no registration, no central authority.
|
||||||
- **Outbound LAN gateway** — optional `fips-gateway` daemon lets
|
- **IPv6 adapter.** A TUN interface maps each remote npub to an
|
||||||
unmodified LAN hosts reach `.fips` destinations via a
|
`fd00::/8` address, so unmodified IPv6 software reaches mesh
|
||||||
DNS-allocated virtual IP pool and kernel nftables NAT
|
peers as `<npub>.fips`. Built-in `.fips` DNS resolver, with
|
||||||
- **Metrics Measurement Protocol** — per-link RTT, loss, jitter, and goodput
|
optional static name mapping via `/etc/fips/hosts`.
|
||||||
measurement with mesh size estimation
|
- **Nostr-mediated discovery and NAT traversal.** Peers publish
|
||||||
- **ECN congestion signaling** — hop-by-hop CE flag relay with RFC 3168 IPv6
|
endpoint adverts on public Nostr relays, exchange candidates via
|
||||||
marking, transport kernel drop detection
|
NIP-59 gift-wrapped offers and answers, and establish direct
|
||||||
- **Operator visibility** — `fipsctl` CLI and `fipstop` TUI dashboard for
|
paths through NATs using STUN-assisted hole punching.
|
||||||
runtime inspection and runtime peer management
|
- **LAN gateway.** Optional `fips-gateway` service folds an entire
|
||||||
- **Zero configuration** — sensible defaults; a node can start with no config
|
unmodified LAN into the mesh: outbound (LAN clients reach mesh
|
||||||
file, though peer addresses are needed to join a network
|
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
|
```bash
|
||||||
git clone https://github.com/jmcorgan/fips.git
|
git clone https://github.com/jmcorgan/fips.git
|
||||||
cd fips
|
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
|
cargo build --release
|
||||||
```
|
```
|
||||||
|
|
||||||
Requires Rust 1.85+ (edition 2024). Linux, macOS, and Windows are
|
Requires Rust 1.85+ (edition 2024). Linux, macOS, and Windows are
|
||||||
supported (see transport matrix below).
|
supported; transport availability varies by platform.
|
||||||
|
|
||||||
### Transport support by platform
|
|
||||||
|
|
||||||
| Transport | Linux | macOS | Windows | OpenWrt |
|
| 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, BLE requires BlueZ and libdbus
|
||||||
Debian/Ubuntu: `sudo apt install bluez libdbus-1-dev`. Then build with
|
(`sudo apt install bluez libdbus-1-dev` on Debian / Ubuntu) and is
|
||||||
BLE enabled: `cargo build --release --features ble`.
|
gated on a build-script probe — install the dependencies first and
|
||||||
|
the `cargo build` line above picks it up. The OpenWrt ipk omits
|
||||||
On **OpenWrt**, BLE is disabled because libdbus is not available on
|
BLE because libdbus is not available on the target.
|
||||||
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.
|
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
Protocol design documentation is in [docs/design/](docs/design/), organized as
|
`docs/` is organised by reader purpose:
|
||||||
a layered protocol specification. Start with
|
|
||||||
[fips-intro.md](docs/design/fips-intro.md) for the full protocol overview.
|
|
||||||
|
|
||||||
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)
|
If you want to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||||
- [docs/design/README.md](docs/design/README.md)
|
and [testing/README.md](testing/README.md).
|
||||||
- [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
|
```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
|
packaging/ Debian, macOS .pkg, Windows ZIP, OpenWrt ipk, AUR, systemd tarball
|
||||||
examples/ Deployment examples (Nostr relay, K8s sidecar, macOS WireGuard)
|
examples/ Deployment examples (Nostr relay, K8s sidecar, macOS WireGuard)
|
||||||
docs/design/ Protocol design specifications
|
testing/ Docker-based integration test harnesses + chaos simulation
|
||||||
testing/ Docker-based integration test harnesses
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Status & Roadmap
|
## Status & roadmap
|
||||||
|
|
||||||
FIPS is at **v0.2.0**. The core protocol works end-to-end over UDP, TCP,
|
FIPS is at **v0.3.0-dev**. The core protocol works end-to-end over
|
||||||
Ethernet, Tor, and Bluetooth (BLE) with a small live mesh of deployed nodes.
|
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
|
### What works today
|
||||||
|
|
||||||
- Spanning tree construction with greedy coordinate routing
|
- Spanning-tree construction with greedy coordinate routing.
|
||||||
- Bloom filter guided discovery (no flooding, single-path with retry)
|
- Bloom-filter-guided destination discovery (no flooding,
|
||||||
- Noise IK (link layer) and Noise XK (session layer) encryption
|
single-path with retry).
|
||||||
- Periodic Noise rekey with hitless cutover for forward secrecy (FMP + FSP)
|
- Two-layer Noise encryption (IK at the link, XK at the session)
|
||||||
- Persistent node identity with key file management
|
with periodic hitless rekey for forward secrecy at both layers.
|
||||||
- IPv6 TUN adapter with built-in `.fips` DNS resolver and multi-backend
|
- Persistent or ephemeral node identity with key-file management.
|
||||||
auto-configuration (systemd dns-delegate, systemd-resolved, dnsmasq,
|
- IPv6 TUN adapter with built-in `.fips` DNS resolver and
|
||||||
NetworkManager)
|
multi-backend auto-configuration (systemd dns-delegate,
|
||||||
- Static hostname mapping (`/etc/fips/hosts`) with auto-reload
|
systemd-resolved, dnsmasq, NetworkManager).
|
||||||
- Per-link metrics (RTT, loss, jitter, goodput) and mesh size estimation
|
- Static hostname mapping (`/etc/fips/hosts`) with auto-reload.
|
||||||
- ECN congestion signaling (hop-by-hop CE relay, IPv6 CE marking, kernel drop detection)
|
- Per-link metrics (RTT, loss, jitter, goodput) and mesh size
|
||||||
- UDP, TCP, Ethernet, Tor, and BLE transports (BLE via L2CAP CoC with per-link MTU negotiation)
|
estimation.
|
||||||
- Outbound LAN gateway for unmodified hosts via DNS-allocated virtual IPs and nftables NAT
|
- ECN congestion signaling (hop-by-hop CE relay, IPv6 CE marking,
|
||||||
- Runtime inspection and peer management via `fipsctl` and `fipstop`
|
kernel-drop detection).
|
||||||
- Reproducible builds with toolchain pinning and SOURCE_DATE_EPOCH
|
- UDP, TCP, Ethernet, Tor, and BLE transports (BLE via L2CAP CoC
|
||||||
- Linux (Debian, systemd tarball, OpenWrt, AUR), macOS (`.pkg`), and Windows (ZIP, service) packaging
|
with per-link MTU negotiation).
|
||||||
- Docker-based integration and chaos testing
|
- Nostr-mediated overlay endpoint discovery and UDP hole punching
|
||||||
- Nostr-mediated overlay endpoint discovery and UDP hole punching for
|
for NAT traversal.
|
||||||
NAT traversal — peers publish endpoint adverts on public Nostr
|
- LAN gateway (`fips-gateway`) with both outbound (LAN-to-mesh)
|
||||||
relays, exchange candidates via NIP-59 gift-wrapped offers/answers,
|
and inbound (mesh-to-LAN port-forwarding) modes.
|
||||||
and establish direct paths through NATs using STUN-assisted
|
- Peer ACL: per-npub allow / deny admission control at the link
|
||||||
punching
|
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
|
### Near-term priorities
|
||||||
|
|
||||||
- Native API for FIPS-aware applications (npub:port addressing)
|
- Native API for FIPS-aware applications (npub:port addressing
|
||||||
- Security audit of cryptographic protocols
|
without the IPv6-shim path).
|
||||||
|
- Security audit of the cryptographic protocols.
|
||||||
|
|
||||||
### Longer-term
|
### Longer-term
|
||||||
|
|
||||||
- Mobile platform support
|
- Mobile platform support.
|
||||||
- Bandwidth-aware routing and QoS
|
- Bandwidth-aware routing and QoS.
|
||||||
- Protocol stability and versioned wire format
|
- Protocol stability and a versioned wire format.
|
||||||
- Published crate
|
- Published crate.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user