How Raven works

🔐 End-to-End Encryption

Every message in Raven is encrypted on the sender's device and can only be decrypted by the intended recipient. The server and mesh relay nodes never have access to plaintext.

• Keys are generated locally on the device and stored in the iOS Keychain (Secure Enclave on supported hardware)
• Ed25519 key pairs for identity — public keys are exchanged during pairing
• AES-256-GCM symmetric encryption for message payloads with per-message nonces
• HMAC-SHA256 for message authentication — tamper-proof delivery
• HKDF key derivation ensures unique session keys for every conversation
• Forward secrecy: compromising one key does not compromise past messages

📡 Bluetooth Mesh Protocol

Raven uses Bluetooth Low Energy (BLE) to create a device-to-device mesh network. Messages hop between nearby devices until they reach the recipient — no internet required.

• Discovery: BLE peripheral/central scanning discovers nearby Raven devices automatically
• Spray-and-Wait routing: Messages are sprayed to L nearby nodes, then wait for direct delivery — balancing reach and bandwidth
• TTL (Time-to-Live): Each message has a configurable hop limit (default: 5) to prevent infinite propagation
• Deduplication: SHA-256 envelope hashes prevent the same message from being relayed twice
• Anti-replay: Timestamp + nonce verification blocks replay attacks
• Relay-safe: Relay nodes forward encrypted envelopes they cannot read — zero-knowledge forwarding

🌐 Hybrid Delivery Architecture

Raven intelligently selects the optimal delivery path for every message. The decision engine runs entirely on-device — no cloud dependency for routing logic.

• Online mode: If internet is available, messages are delivered via the server API (FastAPI + WebSocket) with end-to-end encryption
• Direct mesh: If internet is unavailable but the recipient is nearby, BLE delivers directly
• Bridge mode: If neither is available, nearby devices store the message and forward it when they reconnect — store-and-forward relay
• Automatic failover: If the server is unreachable, Raven seamlessly falls back to mesh without user intervention
• Delivery receipts: End-to-end delivery tracking works across all three modes

📦 MeshEnvelope Structure

Every message — whether sent online or via mesh — is wrapped in a MeshEnvelope that provides routing metadata while keeping the payload opaque.

MeshEnvelope {
  id:           SHA-256 hash (dedup key)
  sender_id:    anonymized device ID
  recipient_id: target device hash
  payload:      AES-256-GCM encrypted blob
  signature:    Ed25519 signature
  hmac:         HMAC-SHA256 authentication
  ttl:          remaining hop count
  timestamp:    ISO-8601 creation time
  nonce:        anti-replay nonce
  route_type:   online | direct | bridge
}

⚡ Server Architecture

The server is a thin relay — it stores and forwards encrypted blobs but never has access to plaintext. Built with Python FastAPI for performance.

• Zero-knowledge relay: Server stores encrypted blobs — cannot decrypt messages
• WebSocket connections for real-time message delivery when online
• RESTful API for user management, posts, and media
• Horizontally scalable via Google Cloud Run
• Database stores only encrypted payloads and minimal routing metadata

📊 How Raven Compares

Raven combines the best of encrypted messaging with offline mesh capabilities: