Nyx // ghost protocol · v0.1.0-alpha

A serverless, end-to-end encrypted mesh communication engine. No central servers. No registration. No metadata. The network is its users.

Nyx is a fully decentralized, anonymous peer-to-peer communication terminal written in Rust. Every instance is a sovereign node in a globally distributed mesh. The architecture layers three independent systems: the Kademlia DHT for global peer discovery, GossipSub for mesh-level message routing, and a request-response whisper channel for direct one-to-one key delivery.

---

🌐 Overview

• QUIC over UDP (Transport): Zero-RTT reconnection, multiplexed streams, and built-in TLS 1.3 at the network layer.
• Dual-Engine Routing (Discovery): mDNS for instant LAN peer discovery and Kademlia DHT for global $O(\log N)$ resolution, backed by an $O(1)$ LRU routing cache.
• Signature-Enforced Gossip (Mesh): GossipSub running in strict validation mode. Every message is signed by the sender's Ed25519 keypair — spoofing is structurally impossible.
• Zero-Trust Rooms (Crypto): 256-bit AES keys live only in RAM. The mesh routes ciphertext; nodes without the key receive incomprehensible binary noise.
• RAM Remanence Protection (Memory): Keys are wrapped in ZeroizeOnDrop structs. A volatile memset to 0x00 fires the exact microsecond a room is exited.
• NAT Traversal (Network): dcutr punches through symmetric NAT firewalls without manual port forwarding via a libp2p relay circuit upgrade.

---

🏛 Architecture

Nyx composes nine distinct libp2p protocol behaviours into a single unified swarm, all feeding into a unified tokio::select! event bus.

The Behaviour Stack

• Transport & Discovery: QUIC + Yamux, Noise, relay::client (Circuit Relay v2), dcutr (Hole Punching), autonat (Reachability), kademlia (Global Routing), mdns (LAN Zero-Config), identify.
• Messaging: gossipsub (Mesh Pub/Sub), request_response (/nyx/invite/1.0.0).
• Security Layer: connection_limits, AES-256-GCM, ZeroizeOnDrop, Token Bucket Rate Limiter.

Message Flow: Plaintext to Wire

When a user types a message, it never touches the network in plaintext. Every publish generates a fresh nonce + ciphertext blob. Nodes without the room key fail decryption silently.

Payload Wire Format: [ 12B Nonce ‖ Ciphertext ‖ 16B GCM Tag ]

---

🔐 Cryptography

Nyx strictly separates transport security from application-layer secrecy. While QUIC provides TLS 1.3 between adjacent peers, that only protects the physical hop. AES-256-GCM secures the room end-to-end regardless of how many relay hops or mesh nodes the packet traverses.

Room Key Lifecycle

1. /create room: OsRng generates 32 bytes $\rightarrow$ loaded into SecureRoomKey(RAM).
2. /invite peer: Key encoded to Base64 $\rightarrow$ CBOR request over direct Whisper channel.
3. /accept: Target decodes Base64 $\rightarrow$ loads key bytes into RAM.
4. /exit: ZeroizeOnDrop fires $\rightarrow$ memset 0x00 to RAM.

The key is NEVER written to disk, NEVER logged, and NEVER leaves the process in plaintext. Cold-boot window = process lifetime (encrypted swap partition strongly recommended).

Implementation Details

// Per-message encryption — src/main.rs
let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(&current_room_key.0));
let nonce  = Aes256Gcm::generate_nonce(&mut OsRng);      // 96-bit fresh nonce
let mut payload = nonce.to_vec();                          // prepend nonce
payload.extend_from_slice(&cipher.encrypt(&nonce, cmd.as_bytes())?);
swarm.behaviour_mut().gossipsub.publish(topic, payload);   // ciphertext on the wire
🛡 DoS HardeningExposing a raw UDP listener to the internet risks amplification and FD exhaustion attacks. Nyx implements two layered defenses directly in the swarm loop:1. Token Bucket Rate LimiterEach unique source IP is tracked. Buckets refill at 0.5 tokens/second up to a capacity of 5 tokens. When the bucket is empty, the connection is silently throttled.2. Hard Connection BoundsThe connection_limits behaviour enforces hard caps before any cryptographic negotiation begins to conserve CPU cycles:LimitValuePurposemax_pending_incoming10Half-open handshake queue guardmax_pending_outgoing5Outbound dial queue limitmax_established_incoming30Maximum inbound peer slotsmax_established_outgoing30Maximum outbound peer slotsmax_established_total60Global simultaneous peer capmax_established_per_peer2Multi-stream deduplication guard📦 InstallationNyx requires the latest stable Rust toolchain.Bash# Install Rust (if not present)
curl --proto '=https' --tlsv1.2 -sSf [https://sh.rustup.rs](https://sh.rustup.rs) | sh
source ~/.cargo/env

# Clone and install globally
git clone [https://github.com/tyrobro/nyx.git](https://github.com/tyrobro/nyx.git)
cd nyx
cargo install --path . --force
(Note: On Ubuntu/Debian, you may need the C build toolchain: sudo apt install build-essential pkg-config)💻 UsageLaunch the terminal by typing nyx. The node will bind a random QUIC port and bootstrap into the global Kademlia DHT. Share your Global Peer ID out-of-band to establish secure rooms.CommandDescription/create <room_name>Generates a 256-bit AES key in RAM and isolates you in a sealed mesh topic./invite <PeerID>Dials the target peer and dispatches the AES key over the direct Whisper channel./dm <PeerID>Creates an ephemeral room, generates a key, and atomically invites the target in one command./acceptProcesses a pending invite, decodes the key into RAM, and drops you into the encrypted room./connect <PeerID>Resolves a Peer ID (via LRU or DHT) and negotiates a QUIC tunnel./exitTriggers ZeroizeOnDrop, tears down all sockets, and terminates the process safely.⚠️ Security Disclaimer: Nyx uses industry-standard algorithms but has not undergone a formal security audit. Do not use it where interception would have life-threatening or legal consequences.🛠 Tech Stacktokio: Async runtime · select! event looplibp2p: P2P networking stack (quic, kad, gossipsub, mdns, dcutr, relay, autonat)aes-gcm: AES-256-GCM AEADzeroize: Secure key erasurelru: $O(1)$ routing cacheserde / cbor / base64: Invite serialization and encodingrustyline-async / clap: Async terminal UI & CLI parsing🗺 Roadmap[In Progress] Refining dcutr hole-punch success rates across complex NAT topologies.[Planned] Multi-Relay Failover: Maintain a ranked list of known relays and automatically re-circuit when offline.[Planned] Encrypted File Transfer: Chunked, AES-encrypted binary streaming over the Yamux multiplexer.[Planned] Forward Secrecy: Rotate room keys on a configurable interval using a ratchet construction.[Planned] Persistent Identity: Optional Ed25519 identity persistence with passphrase encryption.For complete documentation and architecture breakdowns, visit the Official Nyx Website. built with ♥ in rust · no servers · no logs · no trace