mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-22 07:48:26 +00:00
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.
124 lines
5.6 KiB
Markdown
124 lines
5.6 KiB
Markdown
# 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](fips-architecture.md). For prior art and
|
|
academic citations, see [fips-prior-work.md](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](fips-architecture.md) — protocol stack,
|
|
identity system, two-layer encryption, MTU as a cross-cutting
|
|
concern
|
|
- [fips-spanning-tree.md](fips-spanning-tree.md) — how the tree forms
|
|
and reconverges
|
|
- [fips-bloom-filters.md](fips-bloom-filters.md) — how reachability
|
|
information propagates
|
|
- [fips-mesh-operation.md](fips-mesh-operation.md) — how the pieces
|
|
work together at runtime
|
|
- [fips-prior-work.md](fips-prior-work.md) — designs and protocols
|
|
FIPS builds on
|