MERCURY — Decentralized Mesh Messaging Platform

⚠️ Experimental software. MERCURY is a simulation used to explore and demonstrate decentralized messaging and mesh-network behavior. It is not a production messaging app — the "network" runs as a local WebSocket bus connecting simulated nodes on one machine, not real internet-facing peers.

A simulated peer-to-peer messaging network built to explore end-to-end encryption, decentralized identity, and network resilience without relying on a central server for message delivery.

Screenshots

Login / Auth	Main Messenger
Add Contact via DID	Mesh Visualizer

What it does

• End-to-end encryption — messages are encrypted using PyNaCl's Box construction over Curve25519, giving each pair of nodes a shared secret derived from their public keys. Nonce handling: random per message (managed automatically by PyNaCl Box.encrypt).
• Decentralized identity (DID) — each node generates its own decentralized identifier and keypair locally; there is no central identity registry. DID format: did:key:z<base58btc(0xed01 + raw_pubkey_bytes)>. Identities are exchanged out-of-band via QR code.
• Password/local-identity hashing — local identity secrets are hashed with Argon2 (Argon2id), configured with time cost 3, memory cost 65536 KB, and parallelism 4.
• Session auth — JWT tokens signed with HS256, expiring after 24 hours.
• Mesh relay topology — nodes route through a WebSocket relay bus (ws://localhost:9999) in a diamond multi-hop topology rather than connecting directly, simulating how messages would traverse an untrusted network of relays.
• Chaos engineering layer — each node can be configured with an artificial packet-drop rate (range: 0.0 to 1.0) and injected latency (range/distribution: 0 to N ms fixed delay), so delivery reliability can be observed under degraded network conditions instead of assuming a perfect link.
• Live topology dashboard — an admin API + React frontend renders the current network graph (active nodes and their connections) in real time.

Architecture

frontend (React)  ──HTTP/WS──▶  backend (FastAPI, per-node)
                                     │
                                     ├─ core/crypto.py       Curve25519 / PyNaCl Box encryption
                                     ├─ core/identity.py      DID + Argon2-hashed local identity (SQLite)
                                     │
                              networking/virtual_bus.py   ◀── WebSocket relay bus (ws://localhost:9999)
                                     │
                              networking/manager.py        per-node connection + routing logic

Simulated nodes (node_0.toml … node_3.toml, 4 total) connect through the bus in a diamond relay pattern; demo.py boots the bus and all nodes together for a local demo.

Stack

Python · FastAPI · WebSockets · aiohttp · PyNaCl (Curve25519) · Argon2 · JWT (python-jose) · React

Running locally

pip install -r requirements.txt
python demo.py

This starts the relay bus and simulated nodes locally. Open the frontend to see the messenger UI, add a contact via DID/QR, and watch the live topology graph update.

Scope and limitations

This project demonstrates the cryptographic and architectural building blocks of a decentralized messenger (E2E encryption, DIDs, mesh relay, resilience testing via chaos engineering) in a fully local, simulated environment. It does not implement NAT traversal, real peer discovery over the internet, or persistence/sync across devices — those would be the next steps toward a production system.