# The Ghost Mesh: Technical White Paper

**Version:** 0.1.0 (Draft)
**Architecture:** Delay-Tolerant Network (DTN) / Store-and-Forward Mesh

## 1. System Architecture

The Ghost Mesh operates on a "Store-Carry-Forward" paradigm tailored for mobile devices with intermittent connectivity.

### 1.1. The Stack
*   **Application Layer:** Secure Chat Interface (Flutter/Dart).
*   **Encryption Layer:** Double Ratchet Algorithm (Signal Protocol Fork) + Libsodium.
*   **Routing Layer:** Epidemic Routing with Probabilistic TTL.
*   **Transport Layer (Physical):**
    *   **BLE (Bluetooth Low Energy):** Primary channel. Background discovery and handshake.
    *   **Wi-Fi Direct / Aware:** High-bandwidth channel for large file syncing (blob exchange).
    *   **Ultrasonic Audio (FSK):** Low-bandwidth, air-gapped data transfer (Near Field).
    *   **QR Codes:** Visual, camera-based key exchange.

## 2. Protocol Details

### 2.1. Discovery (The "Handshake")
Devices broadcast a rolling, ephemeral UUID via BLE Advertising Packets.
*   **Privacy:** This UUID changes every 15 minutes to prevent tracking user movement.
*   **Beacon:** `GHOST_V1 | BLOOM_FILTER_HASH`
*   When Device A sees Device B, it checks the Bloom Filter hash to see if B might have messages A needs, or if B is a suitable carrier for A's messages.

### 2.2. Routing Algorithm: "Viral Gossip"
Traditional mesh routing (AODV, OLSR) fails in sparse networks where paths don't exist concurrently. We use **Epidemic Routing**:

1.  **Message Creation:** User A creates message $M$.
2.  **Infection:** $M$ is tagged with a TTL (Time-To-Live) of 24 hours and a Hop Limit of 20.
3.  **Replication:** When A meets B, B copies $M$ if:
    *   B has storage space.
    *   B has not seen $M$ before (Dedup via Message ID Hash).
    *   B is not in the "Blacklist" (Reputation System).
4.  **Delivery:** If B meets Destination D, delivery is confirmed.
5.  **Cure (Ack):** An "Anti-Entropy" packet (Delivery Receipt) propagates back through the network to delete copies of $M$ from other nodes, freeing storage.

### 2.3. The "Ghost Link" Hardware Integration
While smartphones are the primary nodes, they have battery/OS limitations (killing background processes).
*   **Ghost Link Nodes (ESP32/LoRa):** Stationary relay nodes placed in the city (as described in Hardware Project #09).
*   These nodes act as "Dropboxes". Users can drop messages into a Ghost Link, and another user can pick them up hours later.

### 2.4. Viral Distribution Mechanism (P2P Installer)
To solve the "Chicken and Egg" problem (how to get the app without internet):
1.  **Hotspot Mode:** User A enables "Share App". Phone A starts a Wi-Fi Hotspot named `GhostMesh_Install`.
2.  **Captive Portal:** User B connects to the Wi-Fi. A DNS server redirects all traffic to a local web server running on Phone A.
3.  **Download:** User B sees a simple page: "Download Ghost Mesh". The APK is served directly from Phone A's storage.
4.  **Verification:** The APK is signed with the developer's key to ensure integrity.

## 3. Security Model

### 3.0. The "Vaccine" (Kill Switch)
Since the app can spread virally, a mechanism is needed to stop propagation on specific devices or globally in case of a critical flaw.
*   **Local Immunity:** If a user creates a file named `.ghost_immune` in the root directory or dials a specific USSD code (e.g., `*#0000#`), the app will:
    1.  Stop broadcasting beacons.
    2.  Refuse to download updates from peers.
    3.  Disable the "Share App" hotspot feature.
*   **Global Recall:** If the developer signs a special "Recall Packet" with the Master Key, this packet propagates through the mesh. Any node receiving it will display a "Critical Security Alert" and disable the app until manually updated.

### 3.1. Identity
*   No phone numbers, emails, or central accounts.
*   Identity = Ed25519 Public Key.
*   Users verify each other via "Safety Number" (QR Code scan) or assume "Trust On First Use" (TOFU).

### 3.2. Encryption
*   **End-to-End:** Payload is encrypted with XSalsa20-Poly1305. Only sender and receiver can read content.
*   **Metadata Privacy:** Intermediate nodes (Carriers) cannot see who the sender or receiver is (Onion Routing concepts applied to packet headers). They only see a "Topic ID" or "Hashed Recipient ID".

### 3.3. Threat Model
*   **Sybil Attack:** An attacker spawns 1000 fake nodes to flood the network.
    *   *Mitigation:* Proof-of-Work (Hashcash) required to generate a valid Identity. Bandwidth throttling per peer.
*   **Flooding:** Spamming junk data.
    *   *Mitigation:* Messages have a size limit (e.g., 10KB text, 1MB media). Oldest messages are dropped first when storage is full.

## 4. Development Roadmap (MVP)

### Phase 1: The Core (Rust)
Implement the networking and crypto logic in Rust (`libp2p` based custom implementation).
*   Why Rust? Memory safety, performance, and easy compilation to Android (JNI) and iOS (FFI).

### Phase 2: The Shell (Flutter)
Minimal UI for sending/receiving text.
*   Integration with Android Nearby Connections API and iOS Multipeer Connectivity framework.

### Phase 3: The Ghost Link (Embedded)
Porting the Rust Core to ESP32 (no_std) or using a simplified C++ bridge for hardware nodes.