5abf9a9325
Restructures /docs/ by reader purpose (tutorials, how-to, reference, design), adds the new-user-progression and operator-recipe content the prior layout lacked, runs an accuracy pass against current source across the pre-existing design docs, and rewrites the gateway feature-set documentation end-to-end around its actual operational profile (a niche feature designed for systems already serving DHCP/DNS to a LAN, with two independent halves — outbound LAN→mesh, inbound mesh→LAN — sharing one nftables table, one binary, and one control socket). Top-level README and getting-started rewritten around two equally-weighted deployment modes (overlay on existing IP networks; ground-up over non-IP transports). ## Additions - 11 new tutorials in docs/tutorials/: an 8-step new-user progression from single-daemon test-mesh peering through to a ground-up two-device mesh, an IPv6-adapter side-trip walkthrough, an Advanced Tutorials index, and a hand-held OpenWrt walk-through for fips-gateway deployment that exercises both halves of the feature. - 12 new how-tos in docs/how-to/: firewall activation, Nostr discovery (resolve / advertise / open across five scenarios), Tor onion (directory + control_port modes), UDP buffer tuning, unprivileged-user setup, persistent identity, host aliases, Bluetooth LE peering, MTU diagnostics, manual Linux-host gateway deployment (covers both halves), gateway troubleshooting (organised by half), and a section index. - 9 new reference docs in docs/reference/: configuration, wire formats, control-socket protocol, four CLI references (fips, fipsctl, fipstop, fips-gateway), security posture matrix, and Nostr events catalog. Configuration and wire-formats are renamed-and-extended from prior design/ versions; the other seven are net-new. - 6 new design docs: fips-concepts, fips-architecture, and fips-prior-work split out of the deleted fips-intro.md; consolidated fips-mmp and fips-mtu aggregations; and a new generic port-advertisement-and-nat-traversal doc (Nostr-signaled port advertisement plus UDP NAT-traversal protocol, FIPS as an example implementation, suitable for eventual NIP submission). - Top-level docs/getting-started.md walking through the binary-installer-only Install story. - packaging/common/hosts pre-populated with the eight public test-mesh nodes so shortnames resolve out of the box on every fresh install. ## Changes - 23 wire-format diagrams relocated to reference/diagrams/ alongside the wire-formats move. - 4 design diagrams corrected against source code (fips-protocol-stack, fips-identity-derivation, fips-coordinate-discovery, fips-routing-decision). - 10 pre-existing design docs reconciled with current source. Numeric corrections: stale link-MMP report bounds (now [1s, 5s] with 200 ms cold-start floor); UDP default MTU (now 1280, IPv6 minimum); node_addr formula (SHA-256(pubkey)[..16]); Noise patterns (IK at link, XK at session); peer-ACL semantics (strict allowlist requires ALL in peers.deny); daemon DNS upstream ([::1]:5354); on-the-wire bloom-filter size (1,071 bytes); obsolete Cargo-feature references (PR #79 dropped them) removed. - Transport framing tightened across the docs: TCP is for UDP-filtered networks (not NAT traversal); Tor is a deployment mode (not failover); WebSocket dropped (not a shipped FIPS transport); WiFi promoted to Implemented via Ethernet in infrastructure mode; classic-Bluetooth row removed (BLE is the only Bluetooth-mode transport). - docs/design/fips-gateway.md rewritten end-to-end to lead with the niche-feature framing and the two-halves structure. Title moved from "FIPS Outbound LAN Gateway" to "FIPS Gateway"; architecture section describes the common machinery (the fips-gateway service, the nftables table, the control socket) before splitting into separate "Outbound Half" and "Inbound Half" sections of equal weight; security considerations split per-half; no Future Work section (speculative directions live in the project tracker, not in protocol design docs). Inbound port forwarding is a first-class half rather than a buried "Implemented Extensions" subsection. - Gateway terminology unified across all gateway docs as a separate Linux service running alongside the fips daemon (its own systemd unit / OpenWrt init script). Container- pattern terms (sidecar) are reserved for the Docker/Kubernetes sidecar deployment examples — the testing/sidecar/ tree, examples/k8s-sidecar/, examples/sidecar-nostr-relay/, examples/wireguard-sidecar-macos/, and the related CHANGELOG / top-level README entries — where the term carries its standard container meaning. - Net-new design body content: rekey section in fips-mesh-layer (Noise IK msg1/msg2 over the established link, K-bit cutover, drain window, smaller-NodeAddr-wins tie-breaker on dual-init); Mesh Size Estimation and Antipoison FPR Cap sections in fips-bloom-filters; Mesh-Interface Query Filter subsection in fips-ipv6-adapter; failure-suppression knobs and clock- skew tolerance in fips-nostr-discovery; loop-rejection and mid-chain ancestor swap added to spanning-tree propagation / stability rules; Priority Chain in fips-mesh-operation renumbered to match the routing-decision diagram. - Top-level README: dropped the stale nostr-discovery cargo-feature parenthetical. docs/README.md and the four section READMEs (tutorials, how-to, reference, design) refreshed for the new structure; index rows reflect both halves of the gateway feature and the new fips-gateway CLI reference. - Cargo.toml [package.metadata.deb] assets path updated for the fips-security.md move; .gitignore /reference/ rule anchored to repo root so docs/reference/ is trackable. - packaging/openwrt-ipk/files/etc/fips/fips.yaml configuration-doc URL updated to the new docs/reference/configuration.md location. ## Deletions - docs/design/fips-intro.md (split into the three new intro design docs). - docs/design/document-relationships.svg (orphan, no longer referenced). - docs/proposals/ tree removed; the only proposal it contained (the Nostr UDP hole-punch protocol) was rewritten as the new generic design/port-advertisement-and-nat-traversal.md.
5.6 KiB
FIPS Concepts
A novice-friendly introduction to what FIPS is, why it exists, and the mental model behind a self-organizing mesh. For the protocol stack, identity system, and encryption walkthrough, see fips-architecture.md. For prior art and academic citations, see fips-prior-work.md.
What is FIPS?
FIPS is a self-organizing mesh network that can operate natively over a variety of physical and logical media, such as local area networks, Bluetooth, serial links, or the existing internet as an overlay. The long-term goal is infrastructure that can function alongside or ultimately replace dependence on the Internet itself. Systems running FIPS establish peer connections, authenticate each other, and route traffic for each other without any central authority or global topology knowledge, and allow end-to-end encrypted sessions between any two nodes regardless of how many hops separate them.
Nodes in the mesh route traffic for each other using Nostr identities (npubs) as network addresses. Applications can access the mesh through a native FIPS datagram service, or through an IPv6 adaptation layer that presents each node as an IPv6 endpoint for compatibility with existing IP-based applications.
Why FIPS?
Self-sovereign identity: FIPS nodes generate their own addresses, node IDs, and security credentials without coordination with any central authority. These identities can be long-term fixed or may be ephemeral, changed at any time. These identities are not visible to the FIPS network itself — they are used only at the application layer and for end-to-end session encryption.
Infrastructure independence: The internet depends on centralized infrastructure — ISPs, backbone providers, DNS, certificate authorities. FIPS works over any transport that can carry packets: a serial connection, onion-routed connections through Tor, local area networking, radio links between remote sites, or the existing internet as an overlay. When the internet is unavailable, unreliable, or untrusted, the mesh still works.
Privacy by design: FIPS provides secure, authenticated, and encrypted communication between any two nodes in the mesh, independent of the mix of transports used along the routed path between them. Furthermore, the mesh itself is designed to minimize metadata exposure — intermediate nodes route packets without learning the identities of the endpoints.
Zero configuration: Nodes discover each other and build routing automatically. Connect to one peer and you can reach the entire mesh. The network self-heals around failures and adapts to changing topology.
A Self-Organizing Mesh
Traditional networks are built top-down. A central authority assigns addresses, configures routing tables, provisions hardware, and manages the topology. If the authority disappears or the infrastructure fails, the network fails with it. Nodes cannot reach each other without infrastructure mediating the connection.
FIPS inverts this model. There is no central authority, no address assignment service, no routing table pushed from above. Each node generates its own identity from a cryptographic keypair. Each node independently decides which peers to connect to and which transports to use. From these local decisions alone, the network self-organizes:
- A spanning tree forms through distributed parent selection, giving every node a coordinate in the network without any node knowing the full topology
- Bloom filters propagate through gossip, so each node learns which peers can reach which destinations — again without global knowledge
- Routing decisions are made locally at each hop, using only the node's immediate peers and cached coordinate information
Each peer link and end-to-end session actively measures RTT, loss, jitter, and goodput through a lightweight in-band Metrics Measurement Protocol (MMP), providing operator visibility and a foundation for quality-aware routing.
The result is a network that builds itself from the bottom up, heals around failures automatically, and scales without central coordination. Adding a node is as simple as connecting to one existing peer — the network integrates the new node through its normal mesh protocols.
Specific Design Goals
- Nostr-native identity and cryptography — Use Nostr keypairs as node identities and leverage secp256k1, Schnorr signatures, and SHA-256
- Transport agnostic — Support overlay, shared medium, and point-to-point transports transparently
- Self-organizing — Automatic topology discovery and route optimization
- Privacy preserving — Minimize metadata leakage across untrusted links
- Resilient — Self-healing with graceful degradation
Non-goals include:
- Reliable delivery — FIPS provides a best-effort datagram service; retransmission and ordering are left to applications or higher-layer protocols
- Anonymity — Direct peers learn each other's identity; FIPS minimizes metadata exposure but is not an anonymity network like Tor
- Congestion control — FIPS measures link quality but does not implement flow control or congestion avoidance at the mesh layer
Where to Read Next
- fips-architecture.md — protocol stack, identity system, two-layer encryption, MTU as a cross-cutting concern
- fips-spanning-tree.md — how the tree forms and reconverges
- fips-bloom-filters.md — how reachability information propagates
- fips-mesh-operation.md — how the pieces work together at runtime
- fips-prior-work.md — designs and protocols FIPS builds on