Abzu_Design_Overview_v0.3.1.md
1 # Abzu: Sovereign Mesh Network Protocol 2 3 > *A decentralized, censorship-resistant communication protocol built entirely in Rust.* 4 5 --- 6 7 ## What is Abzu? 8 9 Abzu is a multi-protocol mesh networking engine designed for **censorship resistance**, **privacy**, and **sovereignty**. It enables encrypted, peer-to-peer communication that operates beneath conventional internet infrastructure—using the existing network as a transport substrate while evading surveillance and filtering. 10 11 The protocol combines: 12 13 - **Geometric routing** from overlay networks (no central servers or directory authorities) 14 - **Content-addressed storage** (BLAKE3 hashing, local-first persistence) 15 - **Stealth transport** that evades Deep Packet Inspection (DPI) 16 17 --- 18 19 ## Core Philosophy 20 21 Abzu follows the **Sovereign OS** principle: your communication infrastructure should be something you *own*, not something you *rent* from a corporation. 22 23 ### Design Principles 24 25 1. **Kerckhoffs' Principle** — Security derives from cryptographic keys, not protocol secrecy. This document assumes the adversary has read it. 26 27 2. **Pure Logic Routing** — The routing layer performs no I/O. It takes state and returns decisions—enabling deterministic testing and clean separation from transport. 28 29 3. **Transport Agility** — The same node logic works over TCP, WebSocket, and (future) UDP, QUIC, or LoRa. 30 31 4. **Stealth First** — Every design decision considers DPI evasion. No protocol magic bytes, no distinguishing headers. 32 33 5. **Local First** — Data is stored locally by default. The network is for discovery and sync, not primary storage. 34 35 --- 36 37 ## Architecture 38 39 ``` 40 ┌─────────────────────────────────────────────────────────┐ 41 │ Control Plane │ 42 │ JSON-RPC 2.0 Interface │ 43 └─────────────────────────┬───────────────────────────────┘ 44 │ 45 ┌─────────────────────────▼───────────────────────────────┐ 46 │ abzu-daemon │ 47 │ (CLI, Configuration, RPC Server) │ 48 └─────────────────────────┬───────────────────────────────┘ 49 │ 50 ┌────────────────┼────────────────┐ 51 │ │ │ 52 ┌─────▼─────┐ ┌──────▼─────┐ ┌──────▼──────┐ 53 │ abzu-core │ │abzu-router │ │abzu-transport│ 54 │───────────│ │────────────│ │─────────────│ 55 │ Node │ │ Spanning │ │ AbzuFrame │ 56 │ Switchboard │ Tree Logic │ │ FakeTLS │ 57 │ Storage │ │ Sovereign │ │ ChaCha20 │ 58 │ │ │ IP Address │ │ Poly1305 │ 59 └───────────┘ └────────────┘ └─────────────┘ 60 ``` 61 62 | Crate | Responsibility | 63 |-------|----------------| 64 | **abzu-core** | Node lifecycle, peer management, storage, switchboard | 65 | **abzu-router** | Pure-logic routing decisions, tree coordinates, path building | 66 | **abzu-transport** | Wire protocol, encryption, DPI evasion, traffic shaping | 67 | **abzu-daemon** | CLI binary, configuration, RPC server | 68 69 --- 70 71 ## Key Capabilities 72 73 ### Cryptographic Identity 74 75 Each node generates an **Ed25519 keypair**. The public key deterministically maps to a stable IPv6 address in the `0200::/7` range—no DNS, no central registry. Your identity *is* your address. 76 77 ### Geometric Routing 78 79 Inspired by [Yggdrasil](https://yggdrasil-network.github.io/), nodes self-organize into a **spanning tree**. Routing decisions are made from local state alone—no global coordination required. 80 81 **Multi-hop routing** (v0.3.1+) enables classic onion-style packet forwarding: 82 83 - Path computed from tree coordinates (Lowest Common Ancestor algorithm) 84 - Frames wrapped in nested layers—each hop sees only the next destination 85 - Intermediate nodes forward without seeing the full route or payload 86 87 ### Stealth Transport (FakeTLS) 88 89 To evade Deep Packet Inspection, Abzu masquerades as TLS 1.3: 90 91 1. Connection opens with a valid **ClientHello** (randomized session ID, plausible SNI) 92 2. Both sides switch to encrypted framing 93 3. All traffic wrapped in standard **TLS Application Data records** (`0x17 0x03 0x03`) 94 95 To a passive observer, Abzu looks like normal HTTPS. 96 97 ### Tiered Security Model (v0.3.0) 98 99 | Tier | Name | Features | 100 |------|------|----------| 101 | **0** | Off | Raw encryption only (debugging) | 102 | **1** | Blend | FakeTLS handshake (default DPI evasion) | 103 | **2** | Shadow | MTU padding + jitter + TLS framing | 104 | **3** | Ghost | Adaptive cover traffic (local pattern mirroring) | 105 106 **Ghost mode** learns your traffic patterns locally and generates statistical noise to blend real activity into background chatter. Pattern models never leave your device. 107 108 ### Content-Addressed Storage 109 110 All content is stored by its **BLAKE3 hash**. Duplicate data shares storage. Retrieved content is verified against its hash before use—no trust in transit. 111 112 ### Encrypted Messaging 113 114 Persistent chat with: 115 116 - End-to-end encryption (ChaCha20-Poly1305) 117 - Delivery acknowledgments 118 - Local message history (Sled database) 119 - Contact address book 120 121 --- 122 123 ## Honest Limitations 124 125 We are explicit about what Abzu **cannot** defend against: 126 127 | Threat | Reality | 128 |--------|---------| 129 | **ISP disconnection** | If they cut the wire, no overlay helps | 130 | **Global traffic analysis** | Timing correlation attacks remain possible | 131 | **Endpoint compromise** | Malware on your device defeats all encryption | 132 | **BGP manipulation** | Abzu runs *over* the internet, not around it | 133 134 Abzu adds significant barriers for passive observers and moderately resourced adversaries. It is not magic. 135 136 --- 137 138 ## Current Status 139 140 **Version**: 0.3.1-alpha 141 **Tests**: 57+ passing 142 **License**: MIT 143 144 ### What Works Today 145 146 - ✓ Node lifecycle (create, run, graceful shutdown) 147 - ✓ Peer connections with FakeTLS and WebSocket transports 148 - ✓ Full wire protocol (KeepAlive, Chunk, Route, Chat, etc.) 149 - ✓ Content-addressed storage with network discovery 150 - ✓ Encrypted chat with delivery acknowledgments 151 - ✓ Tiered security (Blend, Shadow, Ghost modes) 152 - ✓ Multi-hop routing with onion-wrapped frames 153 - ✓ JSON-RPC control plane 154 - ✓ TLS record framing for statistical invisibility 155 156 ### Demonstrated 157 158 **First file teleportation** between two nodes with: 159 160 - FakeTLS encrypted connection 161 - Content-addressed round-trip 162 - Verified BLAKE3 hash on retrieval 163 164 --- 165 166 ## Roadmap 167 168 ### Near-term 169 170 - [ ] Bootstrap nodes for network entry 171 - [ ] Perfect forward secrecy per session 172 - [ ] NAT traversal (STUN/TURN hole punching) 173 174 ### Medium-term 175 176 - [ ] UDP/QUIC transport 177 - [ ] Mobile clients (iOS/Android via Rust FFI) 178 - [ ] Desktop interface 179 - [ ] Group messaging 180 181 ### Horizon 182 183 - [ ] LoRa transport (off-grid mesh) 184 - [ ] Mix-network integration (stronger anonymity) 185 - [ ] Threshold cryptography 186 187 --- 188 189 ## Lineage 190 191 Abzu is the successor to **Project Simurgh**, a Flutter/Meshtastic mesh experiment. The transition reflects a shift toward an "engine-first" Rust architecture—providing a stable foundation for multiple transports under a unified protocol. 192 193 --- 194 195 ## Cryptographic Primitives 196 197 | Primitive | Use | 198 |-----------|-----| 199 | **Ed25519** | Identity, signing, address derivation | 200 | **ChaCha20-Poly1305** | AEAD encryption for all traffic | 201 | **BLAKE3** | Content addressing, hashing | 202 203 --- 204 205 ## Contact 206 207 - GitHub: [adriancmurray/abzu](https://github.com/adriancmurray/abzu) *(private)* 208 - Threads: @adriancmurray 209 210 For security issues, please use responsible disclosure. 211 212 --- 213 214 > *"The system should not depend on secrecy, and it should be possible for it to fall into enemy hands without inconvenience."* 215 > — Auguste Kerckhoffs, 1883