mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-12 01:27:32 +00:00
Johnathan Corgan
00e26765bd
Wire format diagrams: - Add 24 SVG diagrams covering every FMP and FSP wire format: common prefix, established frame headers, Noise IK handshake messages, handshake flow, TreeAnnounce, AncestryEntry, FilterAnnounce, LookupRequest/Response, SessionDatagram, Disconnect, SenderReport, ReceiverReport, FSP complete message, SessionSetup/Ack/Msg3, PathMtuNotification, CoordsRequired, PathBroken, and MtuExceeded - Replace ASCII art in fips-wire-formats.md with SVG references - Apply text edits to fips-mesh-layer.md, fips-mesh-operation.md, fips-transport-layer.md, and fips-ipv6-adapter.md Spanning tree dynamics: - Add 12 topology SVG diagrams: node join (overview + 3-panel steps), three-node convergence (4-panel), link addition with depth labels, link removal, partition formation, and 6 real-world example diagrams (office, mixed-link, two-site WAN topologies) - Rewrite all code blocks to narrative prose with diagram references - Add inline prior art attributions distinguishing Yggdrasil-derived concepts from FIPS-novel contributions - Add 3 new references (De Couto ETX, IEEE 802.1D, RFC 2328 OSPF) and Prior Art summary - Remove outdated sections: indirect partition note, integration test gaps, DHT-based lookup reference - Change "must elect a new root" to "must rediscover its new root" Spanning tree design review (fips-spanning-tree.md): - Rename "Root Election" to "Root Discovery" across docs - Add "What Is a Spanning Tree?" introductory section - Add parent selection intro explaining self-organization role - Fix tree distance example: 4 hops, not 2 - Clarify timestamp field as advisory only - Remove unimplemented ROOT_TIMEOUT and TREE_ENTRY_TTL from timing parameters and implementation status tables Bloom filter design review (fips-bloom-filters.md): - Add "What Is a Bloom Filter?" intro section - Rewrite Purpose section to frame filters as routing path identification - Correct FPR analysis (old values were 3-50x overstated) - Add Filter Occupancy Model based on network size and tree position - Fix filter expiration to describe actual MMP-based cleanup - Combine Scale Considerations with Size Classes after Wire Format - Fix stale FPR values in src/bloom/mod.rs comments Session layer review (fips-session-layer.md): - Add inline prior art attributions: Noise Protocol Framework, WireGuard, DTLS (RFC 6347), IKEv2 (RFC 7296), RFC 1191 PMTUD, Yggdrasil, NIP-44 - Replace warmup state machine ASCII art with SVG diagram - Convert CoordsWarmup wire format code block to prose - Add External References section with full citations Level 5 implementation doc cleanup: - Delete fips-software-architecture.md (redundant with protocol layer docs) - Delete fips-state-machines.md (Rust tutorial, not protocol design) - Add fipsctl command reference to README.md - Update cross-references in fips-intro.md, docs/design/README.md, fips-transport-layer.md, fips-configuration.md Fixes: - Correct fd::/8 to fd00::/8 in fips-session-layer.md, fips-identity-derivation.svg, and fips-node-architecture.svg - Fix config example MTU: 1197 → 1472 in fips-configuration.md File organization: - Move all SVG diagrams into docs/design/diagrams/ subdirectory - Update all diagram references to use new paths
75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# FIPS Design Documents
|
|
|
|
Protocol design specifications for the Federated Interoperable Peering
|
|
System — a self-organizing encrypted mesh network built on Nostr identities.
|
|
|
|
## Reading Order
|
|
|
|
Start with the introduction, then follow the protocol stack from bottom to
|
|
top. After the stack, the mesh operation document explains how all the
|
|
pieces work together. Supporting references provide deeper dives into
|
|
specific topics.
|
|
|
|
### Protocol Stack
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [fips-intro.md](fips-intro.md) | Protocol introduction: goals, architecture, layer model |
|
|
| [fips-transport-layer.md](fips-transport-layer.md) | Transport layer: datagram delivery over arbitrary media |
|
|
| [fips-mesh-layer.md](fips-mesh-layer.md) | FIPS Mesh Protocol (FMP): peer authentication, link encryption, forwarding |
|
|
| [fips-session-layer.md](fips-session-layer.md) | FIPS Session Protocol (FSP): end-to-end encryption, sessions |
|
|
| [fips-ipv6-adapter.md](fips-ipv6-adapter.md) | IPv6 adaptation: TUN interface, DNS, MTU enforcement |
|
|
|
|
### Mesh Behavior
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [fips-mesh-operation.md](fips-mesh-operation.md) | How the mesh operates: routing, discovery, error recovery |
|
|
| [fips-wire-formats.md](fips-wire-formats.md) | Wire format reference for all message types |
|
|
|
|
### Supporting References
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [fips-spanning-tree.md](fips-spanning-tree.md) | Spanning tree algorithms: root discovery, parent selection, coordinates |
|
|
| [fips-bloom-filters.md](fips-bloom-filters.md) | Bloom filter math: FPR analysis, size classes, split-horizon |
|
|
|
|
### Implementation
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [fips-configuration.md](fips-configuration.md) | YAML configuration reference |
|
|
|
|
### Supplemental
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [spanning-tree-dynamics.md](spanning-tree-dynamics.md) | Spanning tree walkthroughs: convergence scenarios, worked examples |
|
|
|
|
## Document Relationships
|
|
|
|
```text
|
|
fips-intro.md
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
▼ ▼ │
|
|
fips-transport-layer fips-mesh- │
|
|
│ operation │
|
|
▼ │ │
|
|
fips-mesh-layer ◄────────┤ │
|
|
│ │ │
|
|
▼ ├──► fips-spanning-tree
|
|
fips-session-layer │ │
|
|
│ └──► fips-bloom-filters
|
|
▼
|
|
fips-ipv6-adapter
|
|
fips-wire-formats
|
|
(referenced by all layer docs)
|
|
|
|
fips-configuration
|
|
(standalone reference)
|
|
|
|
spanning-tree-dynamics
|
|
(pedagogical companion to fips-spanning-tree)
|
|
```
|