# Onyx: A Paradigm Shift in Privacy Centric Communication **A Research Document** **Written by Bhoid-Loid** **Date: July 13, 2026** ## Abstract We live in an era where our conversations are harvested, analyzed, and monetized. Traditional messaging applications rely on outdated paradigms like phone numbers for identity, which intrinsically ties a user's digital persona to their physical life and cellular provider. Onyx was conceived to sever this link. It provides a secure, decentralized feel while leveraging modern infrastructure. This document outlines the philosophy, the architectural decisions, and the technical implementation of the Onyx project. ## 1. The Philosophy of Digital Silence Why do we need another messaging app? It is a fair question. The market is saturated. But look closer at the foundation of these existing networks. They demand your phone number. They store your messages indefinitely on their servers. They know who you talk to, when you talk to them, and often, what you are saying. We needed a system where the server is blind. We needed an identity model that does not require a physical SIM card. Onyx is built on the belief that communication should be ephemeral in transit but permanent in the hands of the user. What good does it do? It returns ownership to the individual. You control your data. The server is merely a postal worker who cannot read the letters. ## 2. Building the Foundation: Problems We Fixed Before we could write a single line of feature code, we had to dismantle the assumptions of modern app development. ### The Phone Number Dilemma Most secure messengers still require a phone number. This is a massive privacy loophole. Onyx fixes this by deriving identity from a Google Account. We hash this account into an 8 character hexadecimal Routing ID. Your identity is mathematically detached from your physical device.
Google Account SHA 256 Hash Routing ID 0x3F9A1B2C
### The Data Hoarding Problem Centralized servers are honeypots. A breach means exposed conversations. Onyx utilizes a blind relay server hosted on Vercel. Messages are routed through this server but never stored. Once a message is delivered via Firebase Cloud Messaging, it vanishes from the network ether. ### The Local Storage Bottleneck In the early days, we used flat files for storage. It was slow and prone to corruption. We solved this by implementing a robust Room SQLite database. This provides instantaneous read and write speeds, real time flow updates to the UI, and a structured way to handle complex data like threaded replies and rich media. The transition to Version 3 of our database allowed us to preserve history while adding advanced threading capabilities. ### The Backup Conundrum If the server does not store your messages, what happens when you lose your phone? Other apps force you to trust their proprietary cloud. We fixed this by giving the power back to you. Onyx encrypts your chat history locally using AES 256 and syncs it directly to your private Google Drive appDataFolder. We never see your backup. We never see your keys. ## 3. System Architecture Let us take a walk through the layers of Onyx. The architecture is deliberately separated to ensure that UI changes do not break database operations, and network failures do not corrupt local data.
Blind Relay (Vercel API) FCM Push Onyx Client Room Database UI Layer Crypto Engine Google Drive HTTPS Send Wake & Deliver AES Backup
### 3.1 Application Entry and Presence The heartbeat of the app begins in the OnyxApp class. When the user opens the app, a presence poller quietly signals the network. We do not maintain persistent WebSocket connections, which drain battery life rapidly. Instead, we use a smart polling mechanism combined with push notifications to strike a balance between real time responsiveness and battery efficiency. ### 3.2 The UI Layer The user interface is designed to be fluid and responsive, providing an experience that feels alive. * **LoginActivity** acts as the gateway. It checks for permissions and authenticates without fuss. * **SetupProfileActivity** allows users to define themselves purely for their contacts, detached from a global directory. * **MainActivity** houses the inbox, dynamically updating as new database records arrive. * **ChatActivity** is the core of the experience. It spans nearly a thousand lines of meticulously crafted logic to handle swipe to reply, message editing, and rendering of custom payloads like Emoji Kitchen creations. * **ParticleNetworkView** gives the background a beautiful, animated canvas that reacts to the environment, proving that privacy does not have to look boring. ### 3.3 The Transport Layer We employ Retrofit to communicate with our Vercel backend. The API is remarkably simple. It consists of precise endpoints to register nodes, lookup users, and send payloads. When a payload is fired, it hits Vercel, which immediately hands it off to Firebase Cloud Messaging. FCM acts as a silent carrier pigeon that wakes up the receiving device, even if the app is completely closed. This mechanism ensures instant delivery without polling. ### 3.4 The Database Layer Our Room database is the absolute source of truth. The ChatMessageEntity stores everything from the raw text to delivery status integers and reaction emojis. All database operations run on background coroutines. By keeping heavy read and write cycles off the main thread, the user interface remains flawlessly smooth regardless of how large the conversation history grows. ### 3.5 The Backup Layer A cornerstone of our philosophy is data ownership. The DriveBackupEngine serializes all messages and profiles, encrypts them heavily using a key derived from the user's account, and uploads the secure vault directly to Google Drive. The DriveAuthManager handles the OAuth boundaries, ensuring the app only has access to its specific application data folder. ### 3.6 The Cryptographic Engine: Post-Quantum Resilience To future-proof our communications against emerging threats, Onyx utilizes a highly vetted, hybrid cryptographic model designed to pass rigorous security audits. We do not roll our own crypto; our implementation relies entirely on BouncyCastle's PQC provider (`org.bouncycastle.pqc.crypto.mlkem`), which is an industry standard. * **Envelope-Around-the-Ratchet Architecture:** We run an outer envelope alongside the stock, unmodified `libsignal` Double Ratchet protocol. The outer layer (ML-KEM-768 static key + AES-GCM) provides immediate defense against "harvest-now-decrypt-later" attacks on the initial handshake. The inner layer provides classic Perfect Forward Secrecy (PFS) and Post-Compromise Security (PCS). The PQ integration takes the plaintext, encrypts it via AES-GCM using the derived Hybrid Key, and passes that ciphertext directly into the Double Ratchet alongside classic X3DH. * **Key Encapsulation & Long-Term Identity Keys:** The ML-KEM-768 keypair is generated during `initializeIfNeeded()` and stored as a Long-Term Static Identity Key. This design provides robust post-quantum authentication and initial confidentiality. Because the KEM keys are not ephemeral, Onyx correctly relies on the inner Double Ratchet layer for forward secrecy. * **The Combiner Function:** To merge classical and quantum-resistant secrets, we use HKDF-SHA256. In `PQCryptoHelper.kt`, the classic ECDH shared secret and the ML-KEM-768 shared secret are concatenated (`classicSecret + pqSecret`) and fed into BouncyCastle's HKDFBytesGenerator using SHA256Digest with the info string `"OnyxHybridKeyExchange"`. This exactly mirrors industry best practices for Post-Quantum combinations. * **Nonce/IV Handling for AES-GCM:** The nonce is randomly generated per message rather than using a stateful counter. Within `PQCryptoHelper.kt`, we use `SecureRandom().nextBytes(iv)` to generate a fresh 12-byte (96-bit) IV for every encryption operation, which is then prepended to the ciphertext. This perfectly suits a static-key scenario where maintaining a synchronized stateful counter is impossible; it entirely neutralizes the risk of counter resets on app reinstalls or multi-device desyncs. With a 96-bit random nonce, the birthday bound requires over 4 billion messages encrypted under the same key to risk a collision, ensuring it is cryptographically safe for high-volume chat applications. ## 4. The Data Flow Understanding how a message travels is crucial to understanding the security model. **Sending a Message** 1. The user types a message in ChatActivity. 2. The payload is instantly written to the local Room database as pending. 3. The VercelApiClient fires a POST request to the server. 4. If the network fails, a PendingMessageWorker takes over, retrying gracefully in the background using WorkManager. **Receiving a Message** 1. Firebase wakes up the OnyxMessagingService. 2. The service acquires a temporary wake lock and processes the payload. 3. The message is decrypted if necessary and written to the Room database. 4. The user receives a high priority notification, complete with inline reply capabilities. ## 5. Conclusion We have laid the groundwork for something entirely different. We solved the identity problem by moving away from phone numbers. We built a fast, local first database that outpaces legacy file systems. We established a secure, user controlled backup system that respects boundaries. The next steps involve refining the cryptographic layers, expanding media support, and continuing to optimize the footprint of the application. Onyx is not just a messaging app. It is a statement. It is a proof of concept that we can build robust, real time communication tools without sacrificing the fundamental right to privacy. It is yours. Keep it safe.