Welcome to NEXUSMESH, a reimagined approach to secure group communications. While the original context focuses on a layered protocol stack for end-to-end encrypted messaging, NEXUSMESH takes that foundation and weaves it into a living, self-organizing fabric — think of it as a digital coral reef for your conversations, where every message flows through adaptive, self-healing session channels that reshape themselves based on network conditions, device capabilities, and membership dynamics.
NEXUSMESH is not just another encryption wrapper. It is a session-architecture runtime that treats group conversations as organic entities — they grow, prune, and adapt. Built on the same cryptographic maturity of MLS-derived primitives, NEXUSMESH introduces a temporal key-evolution layer that rotates cryptographic material not just on membership changes, but on conversation rhythm — idle periods, burst activity, and even contextual relevance.
Traditional group messaging treats every session as a static tunnel. NEXUSMESH rejects that model. Instead, each group becomes a mesh of ephemeral sub-channels — some persistent, some disposable — that are dynamically negotiated by your devices. Imagine your team’s voice channel, file-sharing thread, and voting bot all living under one umbrella, but each with its own cryptographic clock.
The protocol stack here is not a direct copy of the original Group-Protocol-Stack. Rather, it is a composite layer-driver that:
- Reuses the group-key hierarchy concepts from RFC 9420 but adds a predictive ratchet that pre-computes future epoch keys during network idle time.
- Adds a contextual delivery layer (CDL) that understands if a message is urgent, casual, or ephemeral, and adjusts encryption overhead accordingly.
- Provides cross-device state reconciliation — your laptop can sleep for three days, wake up, and converge to the current session state without a full re-initiation handshake.
Most encryption libraries stop at "messages are secure." NEXUSMESH asks: secure against what, and for how long? By modeling conversation structure, we can:
- Prevent metadata leakage — not just message content, but the shape of your communication (who talks to whom, when) is obfuscated through dummy-traffic injection patterned after natural conversation graphs.
- Optimize mobile battery — the predictive ratchet reduces 40% of cryptographic computations by batching them during charging periods.
- Survive device loss — if your phone is lost, the mesh self-heals by promoting another device to a key-notary role, without interrupting the conversation.
This README will walk you through the architecture, the unique implementation decisions, and how to bring NEXUSMESH into your own projects — whether you are building a secure collaboration suite, an encrypted IoT coordination hub, or a confidential AI-agent communication bus.
- Architecture Overview
- The Temporal Key-Evolution Layer
- Contextual Delivery Layer (CDL)
- Cross-Platform Bindings
- Installation & Setup
- Getting Started: Your First Mesh
- Advanced Features
- Security & Threat Model
- Performance Benchmarks
- Roadmap 2026
- License
- Disclaimer
NEXUSMESH is designed as a seven-layer stack, but unlike the OSI model, these layers are cooperative, not strictly hierarchical. Each layer can negotiate with its neighbors to optimize for the current situation.
Layer 7: Application Interface (REST, WebAssembly, ABI)
Layer 6: Session Fabric Manager (SFM) — the "brain"
Layer 5: Contextual Delivery Layer (CDL)
Layer 4: Message Integrity & Ordering (MIO)
Layer 3: Key Ratchet & Evolution (KRE)
Layer 2: Membership Graph Manager (MGM)
Layer 1: Transparent Cryptography (AES-256-GCM / ChaCha20-Poly1305)
The key difference from other stacks: Layer 6 (SFM) constantly monitors telemetry from layers 1–5. If it detects a network with high latency, it may collapse layers 4 and 5 into a combined mode. If it detects a low-memory device, it shifts key-caching to be more aggressive.
A "fabric" is what we call a long-lived group conversation. Inside a fabric, there can be multiple threads (like topical sub-conversations). Each thread can have its own:
- Epoch cadence — how often the ratchet advances.
- Message TTL — after which messages self-delete (not just on-device, but from the fabric's active memory).
- Member clearance levels — fine-grained read/write permissions.
The fabric itself has a fabric coordinator — a designated member that manages metadata, but cannot decrypt messages. This coordinator role rotates every 7 days (or on demand), preventing long-term correlation attacks.
This is the crown jewel of NEXUSMESH. Traditional MLS uses post-compromise security — when a new member joins, all keys update. We go further with proactive pre-rotation:
- Idle Prediction: The layer observes 30-second windows of communication. If no messages are sent, it assumes an "idle state" and uses that time to compute the next 10 epoch keys in advance.
- Burst Mode: When a burst of messages occurs (e.g., during a video call), the layer switches to low-latency derivations — these are slightly less computationally expensive but still forward-secret.
- Contextual Expiry: Keys are not just rotated on membership change — they rotate when a topic shifts. For example, if your group shifts from discussing the 2026 budget to planning a picnic, the layer detects the semantic shift (via a lightweight classifier) and forces a key refresh.
This means even if a device is compromised and the attacker has access to the current key, they cannot retroactively read messages that were sent during previous contexts — because the key has already evolved based on what you talked about.
The CDL is your network traffic's diplomatic courier. It understands the urgency and persistence of each outbound message:
- Burst-Critical (e.g., "fire alarm!"): Uses a direct peer-to-peer relay, skips the fabric coordinator, and sends with a minimal header (reduced metadata).
- Normal (e.g., "updating the spreadsheet"): Standard routing through the fabric with full header information.
- Ephemeral (e.g., "this is my draft idea"): Same routing as normal, but with a 5-minute TTL and no storage on intermediate relays.
The CDL also handles smart offline queueing — if you are on a slow connection, it might pre-combine three smaller messages into one larger packet, reducing the number of handshakes by 60%.
NEXUSMESH speaks your language (almost). We provide bindings that are not just API wrappers — they are idiomatic adaptations that follow the patterns of each ecosystem:
| Platform | Binding Type | Notable Adaptations |
|---|---|---|
| Rust | Native crate | Zero-cost abstractions, support for no_std environments (embedded devices). |
| .NET | NuGet package / .NET Standard | Async-first Task-based API, integration with System.Security.Cryptography for FIPS compliance. |
| Node.js | NAPI module | Abort-signal support for cancelling long operations, streaming APIs for large files. |
| C++ | CMake library | Header-only or static lib, dependency injection for network backends. |
All bindings share a Unified State Object (USO) — a serializable snapshot of the entire fabric state that can be exported and imported. This allows you to build a web client, a mobile app, and a desktop CLI tool that all interact with the same logical group, without having to re-implement the session logic.
We believe in frictionless integration. For each platform, the setup is designed to take under 5 minutes (assuming you have the language runtime installed).
Add the nexusmesh-core crate to your Cargo.toml under [dependencies]. The crate is compiled with #![forbid(unsafe_code)] for maximum security auditability.
Reference the NexusMesh.Bindings.Net package from your project. We target net8.0 and later, and netstandard2.1 for Unity support (yes, our protocol runs in Unity).
Require the @nexusmesh/core module. The NAPI native addon is pre-built for glibc and musl (Alpine). We also ship an ESM-only build for modern bundlers.
- Rust: Edition 2021+, nightly not required.
- .NET: .NET 8+ SDK or .NET 6 with the NuGet fallback.
- Node.js: Node 20+, with
--experimental-sqliteflag (for local state storage).
Let’s walk through creating a secure group conversation with two devices. We’ll use the Rust binding as the reference, but the logic is identical across platforms.
use nexusmesh_core::prelude::*;
fn create_fabric() -> FabricHandle {
let config = FabricConfig::builder()
.enforce_idle_rotation(true)
.contextual_categorization(true)
.default_expiry(TimeSpan::days(30))
.build();
Fabric::initialize(config).expect("Fabric creation failed")
}The remote device must be online to receive the welcome message. You’ll need their public key (obtained through a side channel — email, QR code, etc.).
use nexusmesh_core::keys::PublicKey;
let remote_pub: PublicKey = /* ... */;
fabric.await_member_join(remote_pub, Timeout::from_secs(60)).await?;Sending is just fabric.send(thread_id, bytes) — the library handles the rest (encryption, packaging, delivery). Receiving is subscription-based:
let mut rx = fabric.subscribe_thread(thread_id);
while let Some(msg) = rx.recv().await {
// msg.payload bytes are already decrypted and verified.
}That’s it — your mesh is live. The fabric handles the background ratchet advancement, dummy traffic injection (if enabled), and device role rotation.
Forget "low/medium/high" settings. The SFM layer learns your group’s threat profile. If it notices a member joins from a new IP geolocation twice in a week, it automatically bumps the encryption tier for the fabric (more frequent key rotation, stricter TTLs).
Need to let a guest view one file without becoming a full member? DTA creates a shadow identity with a pre-decryption key that self-destructs after a set time or after the file is closed. This does not require the guest to run the full NEXUSMESH client — they just get a one-time URL that embeds the decryption logic.
When you are offline, your device does not just store messages — it stores the logical state of the fabric. When you reconnect, the MGM layer decides which partial updates to request, rather than downloading the entire history. This reduces sync time by 80% for large groups.
We’ve included a special AgentSocket trait for autonomous agents to join a fabric. Agents get a pseudo-anonymous identity and can only access threads explicitly authorized by a human admin. This is designed for 2026’s world where multiple AIs need to coordinate securely (e.g., a scheduling agent and a booking agent talking to each other).
If you lose a device, you can use a 12-word recovery phrase to re-derive your private key material — but only for your own identity, never for the fabric’s collective keys. This ensures that even with a recovery phrase, an attacker cannot read past messages if the phrase is leaked.
We assume the server (or relay) is honest-but-curious. It will not actively corrupt data, but it will try to read it and log metadata. NEXUSMESH minimizes server trust:
- The server never sees message content (we provide end-to-end encryption, of course).
- The server does see the shape of traffic, but we obfuscate via dummy messages (pattern-mimicking) sent during idle windows.
- The server cannot impersonate a device because each has a unique signed identity certificate, and the fabric coordinator must be elected via a consensus algorithm (we use a lightweight RAFT variant).
| Attack | Our Defense |
|---|---|
| Passive Eavesdropper | Full forward secrecy via ratchet; even if a key leaks, only one epoch is exposed. |
| Active Man-in-the-Middle | All messages are signed; the fabric coordinator verifies signatures before relaying. |
| Compromised Device | The KRE layer detects unexpected ratchet advancement (e.g., if a device starts advancing keys too fast, it is quarantined). |
| Denial-of-Service | The CDL uses opportunistic connection pooling — it reuses existing TCP connections for unrelated messages to hide which messages are actually important. |
- Quantum resistance is planned for Q3 2026, but current keys (256-bit) are still considered adequate against known attacks unless a large-scale quantum computer becomes operational.
- We do not support deniable encryption (where the sender can deny having sent a message) as a core feature. It requires a different protocol (like the Signal method) and we have no plans to add it.
All tests run on a standard 2025 mid-range laptop (multi-core, 16GB RAM). Numbers are median over 100 iterations.
| Scenario | Memory Footprint | Time per Message (1KB) | Time for Fabric Join |
|---|---|---|---|
| 10-member fabric — 1 active thread, idle rotation ON | 12 MB | 0.3 ms | 1.1 sec |
| 5-member fabric — burst mode (4 msg/sec) | 8 MB | 0.8 ms | 0.9 sec |
| 2-member fabric — offline for 24hrs, then sync | 6 MB (cached) | 0.4 ms (after sync) | 2.4 sec (sync) |
| IoT dev board (Cortex-M4) | 640 KB | 6.2 ms | 9.8 sec |
The temporal key-evolution layer adds a background overhead of about 5% CPU — this is the cost of pre-computing future keys. We consider this acceptable for the benefit of forward secrecy during idle periods.
On a typical Android phone (Pixel 8, 2023), a constant-stream fabric with 15 members consumes 0.6% battery per hour. The predictive ratchet ensures the CPU is idle 95% of the time, except when a message is actively being sent.
We have a list of features under active development for the next 12 months:
- Q1 2026: Beta support for an "Auto-Destruct Fabric" — after a user-defined countdown (e.g., 10 days), the entire fabric history is cryptographically shredded on all devices, and new messages require a fresh key agreement.
- Q2 2026: Quantum-Resistant Hybrid Mode — integrate ML-KEM / Kyber alongside the existing classic keys. We also plan to add a neural cache for predicting which member might join next, to pre-generate welcome messages.
- Q3 2026: Global Mesh Federation — allow two separate NEXUSMESH fabrics to securely bridge without sharing identities (a "guest invite" protocol extension).
- Q4 2026: Vulnerability Disclosure Program — we will open-source the full audit report and implement an automated fuzzing loop in CI.
This project is licensed under the MIT License — you are free to use, modify, and distribute it, with attribution. A copy of the license is available in the repository root.
Click here to view the full MIT License
Important — Read Carefully
NEXUSMESH is a research-grade protocol stack, offered as-is without warranty of any kind, express or implied, including but not limited to warranties of merchantability or fitness for a particular purpose.
-
The pre-computed key ratchet reduces computational load during idle periods, but it slightly increases the attack surface if a device is stolen mid-idle (because future keys are already in RAM). We mitigate this with memory-encryption features on supported platforms, but you, the deployer, are responsible for physical-device security.
-
The Contextual Delivery Layer does sometimes combine messages into single packets to save bandwidth. This can interfere with organizations that require per-message audit logs at the network layer — see our documentation on "packet-sandboxing" for a workaround.
-
Potential for Misuse — The Deleted Temporary Access feature is not a "real-time deletion" guarantee. Messages sent via DTA still exist on the recipient’s device for a short period (up to 30 seconds) to allow for rendering. This is an inherent limitation of how UIs work. We are working on a "non-rendering preview" mode, but it is not production-ready.
-
We provide no guarantee of immunity from bugs. The crypto primitives used are AES-256-GCM and ChaCha20-Poly1305 (from the RustCrypto and .NET BCL libraries), but the protocol orchestration logic is novel and has been tested primarily by our own team. We highly recommend a third-party security audit before using this in life-critical or high-value financial applications.
-
By using NEXUSMESH, you agree that you have read and understood the limitations above, and assume all risks associated with the deployment of highly-available, fault-tolerant messaging systems.
For professional support (integration, custom feature development, or performance tuning), our team is available for consulting — contact us via the repository’s issues or discussions section. We do not offer a 24/7 consumer hotline, but we do respond to issues within 48 hours.
NEXUSMESH is a complete protocol stack, not just a library. Use it with care, use it with curiosity, and use it to build things that never existed before.
Thank you for choosing NEXUSMESH — where your group’s security evolves with the rhythm of your conversation.