How encryption survives offline

🔐 End-to-end encryption

Every direct message, group message, post, and comment is encrypted on the sender's device. The server, relay nodes, and any device in between only ever see opaque ciphertext.

• Identity keys (Ed25519) are generated on first launch and stored in the iOS Keychain. On devices with Secure Enclave the private key never leaves the chip.
• Session keys are derived per-conversation via X25519 ECDH + HKDF, so each chat has its own independent symmetric secret.
• Payloads are sealed with AES-256-GCM using a per-message nonce. The GCM tag doubles as integrity protection; we additionally HMAC the routing envelope so relays can drop tampered packets early.
• Local storage: the on-device SQLite database is encrypted at rest with SQLCipher (AES-256). The database key itself is stored in the Keychain, behind device-unlock protection.
• Vault content adds a second key layer locked behind Face ID / Touch ID — even with the unlocked phone in hand, vaulted media stays sealed.

📡 Bluetooth-LE mesh protocol

Raven turns every device into both a BLE peripheral and a BLE central simultaneously. Encrypted message frames hop from device to device, store-and-forward, until they reach the recipient — no router, no cell tower, no internet required.

• Service UUID: a single fixed UUID identifies Raven peers in any environment, so iOS and Mac builds discover each other automatically. Mac Catalyst uses the same GATT service so cross-platform mesh works out of the box.
• Discovery: background scanning + advertising both run, even with the screen off on iOS (with the Bluetooth-Always entitlement) and with the window closed on Mac (via a LaunchAgent companion).
• Spray-and-Wait routing: messages are sprayed to up to L nearby nodes, then those nodes wait for a direct delivery opportunity. Balances reach against airtime so the mesh doesn't saturate.
• TTL: default hop limit of 5. Each relay decrements the counter; envelopes that expire are dropped silently.
• Deduplication: a SHA-256 of the envelope body keys a per-device LRU. Each device refuses to re-relay the same envelope, so loops can't form even with cyclic topologies.
• Anti-replay: timestamp + nonce verification rejects envelopes that fall outside a sliding window or reuse a known nonce.
• Zero-knowledge relay: a relay node only ever sees the envelope wrapper. Payloads, sender content, and reactions remain ciphertext throughout the path.

🌐 Hybrid delivery — three modes, one envelope

The on-device router picks the cheapest delivery path that's actually working. The decision logic is local — no cloud lookups, no pre-flight checks.

• Online: a persistent WebSocket to the FastAPI relay delivers in real-time and notifies recipients via APNs if they're offline.
• Direct mesh: if internet is unreachable but the recipient's BLE peer is in range, the envelope is delivered peer-to-peer with no intermediate hop.
• Bridge (multi-hop): if neither path works, nearby devices act as store-and-forward relays. Each carrier device passes the envelope on whenever it sees a node that's online or closer to the recipient — Raven catches up on first network or proximity event.
• Failover: mode transitions are silent. A WebSocket drop instantly switches the next outgoing message to mesh; a peer regaining LTE flushes its bridge queue to the server.
• End-to-end receipts: delivered/seen acks are themselves envelopes — the same routing applies, so receipts work just as well over a 5-hop bridge as they do online.

📦 MeshEnvelope — the universal message format

Every payload travels in the same envelope, regardless of transport. The wrapper carries just enough routing metadata for the network to do its job — and not a byte more.

MeshEnvelope {
  id:           SHA-256 hash         // dedup + content addressing
  sender_id:    Hash(device_pubkey)  // anonymised identity
  recipient_id: Hash(target_pubkey)  // routing target
  payload:      AES-256-GCM(blob)    // opaque ciphertext
  signature:    Ed25519(envelope)    // origin authentication
  hmac:         HMAC-SHA-256         // integrity (cheap drop)
  ttl:          uint8                // hops remaining (default 5)
  timestamp:    ISO-8601 UTC         // anti-replay window
  nonce:        uint64 random        // per-message uniqueness
  route_type:   online | direct | bridge
}

• The HMAC is verified before any expensive crypto so junk envelopes get dropped at line rate.
• The Ed25519 signature is verified once the envelope is admitted, before relay or local storage.
• Only the recipient can decrypt the payload — relays never have the symmetric key.

⚡ Server architecture

The server is a thin relay — a stateless FastAPI service that accepts encrypted envelopes, fans them out via WebSocket and APNs, and parks them in PostgreSQL for offline pickup. Cost-wise it scales to zero when nobody's chatting.

• Zero-knowledge: the database stores ciphertext blobs and routing hashes only. Decryption keys never leave the device.
• Realtime: a single WebSocket per device handles inbound delivery, presence heartbeats, and live audio room control. Falls back to APNs push when the socket is closed.
• Scale-to-zero: Cloud Run with min-instances 0 means idle traffic costs nothing. Cold-start adds ~1.5s on the first request, then the service stays warm during the burst.
• Stateless: any instance can serve any request. Persistent state lives in PostgreSQL (encrypted-at-rest) and Cloud Storage for media blobs.
• LiveKit Cloud SFU handles audio room media; the server only mints short-lived JWTs and never proxies audio.

🍎 One Swift codebase, two native binaries

Raven runs natively on iOS 17+ and macOS 14+ — same Swift sources, same business logic, same crypto. We use Mac Catalyst with platform-specific shells so the Mac build feels native to macOS 26 (Liquid Glass UI, capsule sidebar, ⌘-shortcuts) without forking the codebase.

• iOS: distributed via the App Store. Background BLE keeps mesh participation alive when the phone is locked.
• Mac: distributed as a signed DMG outside the Mac App Store so we can disable the sandbox — required for full BLE peripheral mode. A LaunchAgent companion keeps the mesh bridge running while the GUI is closed.
• Cross-platform mesh: a Mac next to an iPhone immediately becomes a relay node for the iPhone's traffic, and vice-versa. Same GATT service UUID, same envelope format.

🧠 On-device intelligence

Smart features run locally — no prompts ever leave the device.

• Smart replies: three short suggestions above the input bar, generated by Apple's on-device Foundation Model from the recent transcript. Never sent to a server.
• Inline translation: long-press a message → translate via Apple's Translation framework. On macOS Catalyst the equivalent UI is gated behind the same on-device models.
• Voice transcription: voice notes are transcribed locally with SFSpeechRecognizer so search and accessibility work without uploading the audio.

📊 How Raven compares

Raven sits at the intersection of mainstream encrypted messengers and offline-first mesh apps.

🎯 Threat model — what Raven defends against

• Network-level adversary: ISPs, Wi-Fi snoops, and state-level passive observers see only TLS-wrapped ciphertext. Even the relay server cannot decrypt it.
• Compromised relay node: a malicious mesh peer can drop or delay envelopes but cannot read, modify, or impersonate the sender (Ed25519 signature + HMAC).
• Lost / stolen device: the encrypted database needs the device unlock to open; Vault content needs an additional Face ID prompt.
• Server compromise: the server holds ciphertext blobs only. There are no plaintext messages, no encryption keys, no IP/contact metadata.

Out of scope: a sophisticated attacker with persistent access to the unlocked device, or one capable of compromising Apple's Secure Enclave. We document the boundary honestly rather than overpromise.

👨‍💻 Architected & built by Ahmadreza

Raven is independently designed and built — every line of crypto, mesh routing, server code, and UI ships from one author. Source isn't public, but the security-critical parts are available for review under NDA to vetted security researchers and serious partners.