mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-09 08:14:42 +00:00
Johnathan Corgan
823b830289
Forward-merge of the docs-overhaul squash (5abf9a9) and top-level README rewrite (18019bb). Conflict resolution: - README.md: master's rewritten feature lists adopted, with the encryption bullets reflecting next's two-layer Noise XX (replacing the IK/XK pair master describes for v0.3.0). - 6 design/reference markdown files (fips-bloom-filters.md, fips-mesh-layer.md, fips-mesh-operation.md, fips-session-layer.md, fips-transport-layer.md, reference/wire-formats.md): master's reorg taken, next's protocol details preserved (XX handshake naming, bloom v2 RLE/delta wire format, v2 LookupRequest sizing). - fips-intro.md modify/delete: accepted master's split into fips-architecture.md / fips-concepts.md / fips-prior-work.md, then re-applied next's IK/XK -> XX transition and spin-bit removal across the relevant split files. Same pass swept docs/reference/security.md, docs/design/fips-mmp.md, docs/design/fips-security.md, docs/design/fips-nostr-discovery.md, docs/design/port-advertisement-and-nat-traversal.md, docs/how-to/enable-nostr-discovery.md, and the affected tutorials so no IK/XK or spin-bit prose remains in current-state docs. - Diagram path conflicts: noise-ik-msg{1,2}.svg removed (IK is gone); noise-xx-msg{1,2,3}.svg moved from docs/design/diagrams/ to docs/reference/diagrams/ to match master's diagram reorg. The wire-formats.md image references resolve correctly to the new path. Local verification: cargo build --release, cargo test (1265 passed, 4 ignored), cargo clippy -D warnings, cargo fmt --check all green.
FIPS Design
Architectural and protocol-level explanations for FIPS — the why and the how behind the wire and the system. For wire formats and configuration keys, see reference/. For task recipes, see how-to/. For end-to-end lessons, see tutorials/.
Reading Order
Start with fips-concepts.md for the novice-friendly framing of what FIPS is and why, then move to fips-architecture.md for the protocol stack, identity model, and two-layer encryption walkthrough. From there, follow the protocol stack from bottom to top. After the stack, fips-mesh-operation.md explains how the pieces work together at runtime. Cross-cutting and supporting documents cover specific subsystems in detail.
Foundations
| Document | Description |
|---|---|
| fips-concepts.md | What FIPS is, why it exists, mental model |
| fips-architecture.md | Protocol stack, identity, two-layer encryption |
| fips-prior-work.md | Designs and protocols FIPS builds on |
Protocol Stack
| Document | Description |
|---|---|
| fips-transport-layer.md | Transport layer: datagram delivery over arbitrary media |
| fips-mesh-layer.md | FIPS Mesh Protocol (FMP): peer authentication, link encryption, forwarding |
| fips-session-layer.md | FIPS Session Protocol (FSP): end-to-end encryption, sessions |
| fips-ipv6-adapter.md | IPv6 adaptation: TUN interface, DNS, MTU enforcement |
Cross-Cutting
| Document | Description |
|---|---|
| fips-mmp.md | Metrics Measurement Protocol (link + session) |
| fips-mtu.md | Path MTU model, encapsulation overhead, PMTUD |
| fips-security.md | fips0 interface threat model and default-deny baseline |
Mesh Behavior
| Document | Description |
|---|---|
| fips-mesh-operation.md | How the mesh operates: routing, discovery, error recovery |
| fips-nostr-discovery.md | Optional Nostr-mediated peer discovery and UDP NAT hole-punch |
| port-advertisement-and-nat-traversal.md | Nostr-signaled port advertisement and UDP NAT-traversal protocol; generic, with FIPS as an example implementation |
Deeper Dives
| Document | Description |
|---|---|
| fips-spanning-tree.md | Spanning tree algorithms: root discovery, parent selection, coordinates |
| fips-bloom-filters.md | Bloom filter properties: FPR analysis, size classes, split-horizon |
| spanning-tree-dynamics.md | Spanning tree walkthroughs: convergence scenarios, worked examples |
Adjacent Components
| Document | Description |
|---|---|
| fips-gateway.md | fips-gateway service: outbound (LAN-to-mesh) DNS-proxy + virtual-IP NAT and inbound (mesh-to-LAN) port-forwarding, sharing one nftables table |