diff --git a/docs/design/fips-architecture-overview.svg b/docs/design/fips-architecture-overview.svg new file mode 100644 index 0000000..d75f960 --- /dev/null +++ b/docs/design/fips-architecture-overview.svg @@ -0,0 +1,122 @@ + + + + + + + + + + Node A + npub1aaa... + (source) + + + App + + FIPS + + WiFi + + + Node B + npub1bbb... + (relay) + + + FIPS + + WiFi + + Eth + + + Node C + npub1ccc... + (relay) + + + FIPS + + Eth + + UDP + + + Node D + npub1ddd... + (relay) + + + FIPS + + UDP + + Tor + + + Node E + npub1eee... + (dest) + + + App + + FIPS + + Tor + + + + + + + WiFi + + + + + + Ethernet + + + + + + UDP/IP + + + + + + Tor + + + + End-to-end encrypted session (A ↔ E) + + + Link + + Link + + Link + + Link + + diff --git a/docs/design/fips-intro.md b/docs/design/fips-intro.md index 1646c4a..233d49d 100644 --- a/docs/design/fips-intro.md +++ b/docs/design/fips-intro.md @@ -65,23 +65,12 @@ routing logic works regardless of the underlying transport mix. ## Architecture Overview -``` -┌─────────────────────────────────────────────────────────────┐ -│ Application Layer │ -│ (native FIPS API, or IPv6 via TUN adapter) │ -├─────────────────────────────────────────────────────────────┤ -│ FIPS Router │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ -│ │ Identity │ │ Spanning │ │ Bloom Filter │ │ -│ │ (npub) │ │ Tree │ │ Routing Table │ │ -│ └─────────────┘ └─────────────┘ └─────────────────────┘ │ -├─────────────────────────────────────────────────────────────┤ -│ Transport Abstraction │ -│ ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ -│ │ UDP │ │ Ethernet │ │ WiFi │ │ Radio │ │ Onion │ │ -│ └────────┘ └──────────┘ └────────┘ └────────┘ └────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` +![Architecture Overview](fips-architecture-overview.svg) + +Each link uses a different transport, but the end-to-end session encryption +is independent of the transport mix. Intermediate nodes decrypt the link +layer to make routing decisions, then re-encrypt for the next hop. They +cannot read the session-layer payload. Applications can use the native FIPS datagram service directly, or access the mesh through an IPv6 adaptation layer (TUN device) for compatibility with @@ -255,6 +244,8 @@ See [fips-wire-protocol.md](fips-wire-protocol.md) for link encryption and ## Spanning Tree Protocol +![Mesh Topology](fips-mesh-topology.svg) + The spanning tree is a subset of the full mesh network that connects all nodes, forming a tree structure rooted at a deterministically-elected node. Each node selects a single parent, and the resulting tree serves as the routing backbone. @@ -411,24 +402,7 @@ A **transport** is a physical or logical interface: a UDP socket, an Ethernet NIC, a Tor client, a radio modem. A **link** is a connection instance to a specific peer over a transport. -``` -┌─────────────────────────────────────────┐ -│ FIPS Node │ -│ ┌─────────────────────────────────┐ │ -│ │ Router Core │ │ -│ └──────────┬──────────┬───────────┘ │ -│ │ │ │ -│ ┌──────┴────┐ ┌───┴─────┐ │ -│ │ UDP │ │ LoRa │ │ -│ │ Transport │ │Transport│ │ -│ └────┬──────┘ └────┬────┘ │ -└───────────┼─────────────┼──────────────┘ - │ │ - ┌────┴────┐ ┌─────┴────┐ - │Internet │ │ Radio │ - │ Peers │ │ Peers │ - └─────────┘ └──────────┘ -``` +![Transport Abstraction](fips-transport-abstraction.svg) ### Multi-Transport Bridging diff --git a/docs/design/fips-mesh-topology.svg b/docs/design/fips-mesh-topology.svg new file mode 100644 index 0000000..4c8e9a1 --- /dev/null +++ b/docs/design/fips-mesh-topology.svg @@ -0,0 +1,139 @@ + + + + + + + + FIPS Mesh Network + Spanning tree highlighted — root elected by smallest node_addr + + + + + + + + UDP + + + + Satellite + + + + UDP + + + + Tor + + + + + + WiFi + + + + WiFi + + + + UDP + + + + Bluetooth + + + + UDP + + + + Ethernet + + + + Tor + + + + + + A + npub1aaa... + ★ root + + + + B + npub1bbb... + + + + C + npub1ccc... + + + + D + npub1ddd... + + + + E + npub1eee... + + + + F + npub1fff... + + + + G + npub1ggg... + + + + H + npub1hhh... + + + + + + + Spanning tree link (parent → child) + + + + Additional mesh link (peer connection) + + + + ★ Elected root (smallest node_addr) + + + Labels show transport type per link + diff --git a/docs/design/fips-transport-abstraction.svg b/docs/design/fips-transport-abstraction.svg new file mode 100644 index 0000000..e843ba6 --- /dev/null +++ b/docs/design/fips-transport-abstraction.svg @@ -0,0 +1,174 @@ + + + + + + + + FIPS Node Architecture + Application interfaces, router core, and transport abstraction layer + + + + FIPS Node + + + + + + + + + FIPS-Native API + Datagram service + Addressed by npub + + + + IPv6 TUN Adapter + fips0 + DNS (.fips) + npub → fd::/8 IPv6 + + + FIPS-aware apps + Legacy IP apps (ping, curl, ...) + + + + + + + + Router Core + Spanning tree · Bloom filters · Greedy routing · Session management · Noise IK + + + + + + + + + + + + + + + + + + + + + + + + Overlay + + + UDP + IP + + + QUIC + IP + + + WS + TCP + + + + Shared Medium + + + Ether + 802.3 + + + WiFi + 802.11 + + + BT + RFCOMM + + + LoRa + radio + + + + P-to-P + + + Serial + UART + + + + Anonymity + + + Tor + .onion + + + I2P + tunnel + + + + + Internet Peers + + + + Local / Radio Peers + + + + Wired Peer + + + + Anonymous Peers + + + + + + + Application interface + + + IPv6 compatibility layer + + + Router core (protocol engine) + + + Transport plugin + + + Transport category grouping + + All transports use the same Router Core interface +