How GuardianMesh Works

GuardianMesh is a distributed relay fabric with end-to-end encryption, seven transport types, and multi-guardian federation. Messages are encrypted before they leave your device and can travel over any available path — internet, Bluetooth, satellite, or physical media.

Message Path (WebSocket Relay)

The primary relay path uses authenticated WebSocket connections to guardian nodes:

1. Client encrypts the message with the Double Ratchet (forward secrecy per message), signs the DTN bundle with Ed25519, and sends it to a guardian endpoint over an authenticated WebSocket session (Noise XX handshake).
2. If destination is online, guardian delivers directly and returns delivered.
3. If destination is offline, guardian stores bundle with expiresAtMs and returns stored.
4. Federated guardians exchange registry and bloom-filter hints, forwarding bundles when beneficial.
5. When destination reconnects, bundle is delivered and pending state is cleared.

This is the most common path, but not the only one. GuardianMesh supports seven transport types that can all carry the same encrypted bundles.

End-to-End Encryption

All messages are end-to-end encrypted before leaving the sender's device. No relay, guardian, or intermediary can read message content.

Session Establishment (X3DH)

Sessions are established using the Extended Triple Diffie-Hellman protocol with four DH operations:

• DH1: Sender identity key (IK) ↔ Recipient signed pre-key (SPK)
• DH2: Sender ephemeral key (EK) ↔ Recipient identity key (IK)
• DH3: Sender ephemeral key (EK) ↔ Recipient signed pre-key (SPK)
• DH4: Sender ephemeral key (EK) ↔ Recipient one-time pre-key (OPK), if available

The shared secret is derived via HKDF-SHA256. No trusted third party is involved.

Per-Message Encryption (Double Ratchet)

• Symmetric ratchet: Each message uses a unique key derived from a chain key. Past message keys cannot be reconstructed from current state.
• DH ratchet: Each round-trip rotates Diffie-Hellman keys. If an attacker compromises current keys, future messages become secure again after one exchange.
• Out-of-order handling: Up to 256 skipped message keys per chain are cached so messages arriving out of order can still be decrypted.

Group Messaging (MLS RFC 9420)

Group conversations use Messaging Layer Security with TreeKEM for O(log n) key updates. Epoch-based transitions provide forward secrecy for groups. Credentials are Ed25519-signed and validated on every KeyPackage.

Transport Types

GuardianMesh supports seven transport types plus gateway adapters. The adaptive transport scorer selects the best available path automatically.

Guardian (WebSocket Relay)

Primary transport. Clients connect to guardian relay nodes via Noise XX authenticated WebSocket sessions. Bundles are stored with configurable TTL and forwarded across federated guardians. Noise cipher suite: Noise_XX_25519_AESGCM_SHA256.

BLE Mesh

Bluetooth Low Energy mesh networking for device-to-device communication without internet. Key capabilities:

• Multi-hop forwarding: Messages relay through up to 3 hops by default, with LRU deduplication to prevent loops.
• Automatic fragmentation: Payloads are split to fit the BLE ATT MTU and reassembled on the other side, with timeout-based cleanup for incomplete fragments.
• Store-and-forward offline queue: Up to 500 messages are queued locally when peers are disconnected, delivered automatically on reconnection.
• Identity verification: Ed25519 challenge-response authentication with 30-second challenge expiry to prevent replay attacks.
• Connection management: Maximum 7 concurrent BLE connections, exponential backoff reconnection (100 ms base, 30 s cap), stale connection reaping.
• Rate limiting: 20 sends per peer per second, 10 mesh forwards per second to prevent flooding.
• Compression: Optional payload compression for bandwidth-constrained BLE links.

WebRTC

Direct peer-to-peer communication via WebRTC data channels. ICE candidate negotiation through the signaling server, with STUN for NAT traversal. No relay needed when peers can reach each other directly.

Tor

Anonymous transport via SOCKS5 proxy with full circuit management. Supports onion service operation for receiving connections. Circuit lifecycle tracking (building, open, closed, failed) with automatic renewal. Traffic obfuscation via obfs4 and meek pluggable transports.

LAN Discovery

Local network peer discovery via mDNS Zeroconf. Publishes and discovers peers using _ratchet._tcp and _guardian-mesh._tcp service types. Zero-config setup for same-network communication.

Satellite

Gateway adapter for satellite uplink and downlink. Broadcast-based delivery suitable for one-to-many distribution in remote areas without terrestrial infrastructure.

Sneakernet

Physical media transfer for fully offline scenarios. Bundles are encoded as QR codes (FN2 format with HMAC-SHA256 integrity verification) or exported as JSON files for USB/SD card transfer. Multi-QR chunking supports payloads larger than a single QR code.

Radio Gateway

HF and VHF radio transceiver gateway for long-range communication without any network infrastructure. Adapts the standard Transport interface to radio hardware.

Privacy and Anti-Surveillance

GuardianMesh includes multiple layers of protection against traffic analysis and surveillance:

• Onion routing: Multi-hop layered encryption with constant-size padding (512 B to 64 KB). No single relay knows both sender and recipient. Circuit states are tracked through building, open, closed, and failed phases.
• Cover traffic: Optional constant-rate dummy packet generation (512-byte packets every 2 seconds). Battery-aware: pauses below 30% battery, resumes above 50%. Cellular-aware mode available. Real messages transparently replace cover packets.
• Message mixing: Random delay injection (100–2000 ms uniform distribution), Fisher-Yates batch shuffling, dummy message padding, and constant-rate output (2 messages per second) to defeat timing correlation.
• Traffic obfuscation: obfs4 (packet scrambling with randomized sizes and timing jitter), meek (CDN tunneling so traffic looks like normal HTTPS), and domain fronting.

Trust and Discovery

Guardians announce using Ed25519-signed payloads, and the directory verifies the signature and identity hash binding (identityHash = SHA-256(Ed25519_publicKey)). Public network views consume privacy-safe API projections at region level by default.

A web-of-trust system with 6 trust levels (Unknown, FirstContact, UnverifiedKnown, Extended, Indirect, Direct) allows users to verify peer identities without a central authority. Key rotation uses cryptographic rotation certificates where the old key signs the transition to a new key.

Federation

Guardian nodes form a federated relay network:

• Federated connections use Noise XX mutual authentication with prologue binding (guardian-mesh-signaling/3).
• Bloom-filter hints (512-byte filters with 4 hash functions) efficiently indicate which bundles each guardian has pending.
• Relay receipts are Ed25519-signed proofs of delivery, binding bundleId, relay identity, and a SHA-256 hash of the bundle content.
• Credit weights vary by priority: emergency (100), high (25), normal (5), low (2), bulk (1), with 2× multiplier for federation boundary crossings.

Routing Guarantees

• Idempotent by bundleId (duplicate suppression via bloom filters)
• TTL-bounded by expiresAtMs
• Hop-bounded forwarding (configurable per bundle)
• Rate limits and quota rejections with deterministic rejection reasons and retry hints
• Priority levels: Emergency (3), High (2), Normal (1), Low (0)
• Gossip-based discovery with adaptive transport scoring for optimal path selection