mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-09 08:14:42 +00:00
Johnathan Corgan
45a8a4cd9b
Forward-merge of 12 master commits past the previous merge (823b830, master @18019bb): dep-audit bumps (rand, clap, tun, rtnetlink, windows-service, plus the bump-safe lockfile batch), bloom-storm chaos scenario, control-socket resolver consolidation, gateway dns.listen default change, OpenWrt ipk README refresh, gateway tutorial review, Ethernet MTU rustdoc fix, dead session-variant drop, CHANGELOG prep. Conflict resolution: - CHANGELOG.md: both bullets kept under [Unreleased] / Fixed. Master's spanning-tree internal-path-propagation fix precedes next's tree-ancestry-test determinism entry and the responder-Disconnect XX-handshake entry. - src/protocol/session.rs: kept next's SessionSetup/SessionAck variants and rustdoc. Master's drop of those variants suits v0.3.0's FSP phase-byte dispatch but is undone by next's v0.4.0 wire format, which retains the variants and uses the inner msg_type byte for handshake identification. - src/transport/ethernet/mod.rs: kept next's "interface MTU - 4" comment. Master corrected the v0.3.0 3-byte rustdoc; next redesigned the framing to a 4-byte header (type/flags/length) for shared-media beacons, so master's correction does not apply to next's format. Auto-merged cleanly: Cargo.toml (next's 0.4.0-dev + the new dep pins from master), Cargo.lock, all gateway docs, docs/reference/configuration.md, packaging files, .github/workflows/ci.yml, testing/chaos/sim/* and testing/ci-local.sh (bloom-storm additions), src/config/*. Local verification: cargo build --release, cargo test (1252 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 |