I Built a Signal Protocol Messenger from Scratch with X3DH, Double Ratchet, Safety Numbers, P2P File Transfer

TL;DR: Halonyx is a self-hostable, end-to-end encrypted messenger built on the Signal Protocol (X3DH + Double Ratchet). The relay server architecturally cannot read your messages. Files transfer peer-to-peer via WebTorrent (BitTorrent over WebRTC). Identity is pseudonymous — no phone number, no email required.

🔗 GitHub · 🌐 Live Demo

Why Build Another Messenger?

Most "secure messenger" projects I've seen fall into one of two categories:

1. They use TLS and call it "encrypted" — which protects the transport, not the content from the server
2. They use a crypto library as a black box without understanding what's happening inside I wanted to actually implement the Signal Protocol from first principles: understand every DH operation in X3DH, trace how the Double Ratchet chains evolve, and design a system where the relay server is architecturally excluded from reading anything — not just by policy, but by cryptographic design.

This is Halonyx. Here's what we built and what we learned.

The Core Problem: Trust No Server

The typical E2EE claim is "only you and the recipient can read messages." But there's a hidden assumption: that the server gives you the real public key of your contact.

A malicious server can silently substitute its own key during the X3DH handshake. You encrypt to the server's key, it decrypts, re-encrypts to your contact, and neither party knows. This is a MITM attack at the key distribution layer.

Signal solves this with Safety Numbers. We implemented the same mechanism — more on that later.

Signal Protocol: What's Actually Happening

X3DH Key Exchange

X3DH (Extended Triple Diffie-Hellman) lets two parties establish a shared secret even if one of them is offline. It uses four DH operations:

DH1 = DH(IKa,  SPKb)   — Alice's identity key    × Bob's signed pre-key
DH2 = DH(EKa,  IKb)    — Alice's ephemeral key   × Bob's identity key
DH3 = DH(EKa,  SPKb)   — Alice's ephemeral key   × Bob's signed pre-key
DH4 = DH(EKa,  OPKb)   — Alice's ephemeral key   × Bob's one-time pre-key

SK  = HKDF(DH1 ‖ DH2 ‖ DH3 ‖ DH4)

Why four operations instead of one? Each adds a layer:

• DH1 binds both parties' long-term identities
• DH2 + DH3 add ephemeral randomness — even if Alice's long-term key is later compromised, past sessions are safe
• DH4 uses a one-time pre-key (OPK) — once consumed, it's gone. Provides deniability and replay protection. The server stores Bob's pre-key bundle and relays Alice's x3dh_init packet. It never derives SK — it never has enough information to.

Double Ratchet

After X3DH establishes the root key, every message advances the Double Ratchet:

Symmetric ratchet: Each message derives a unique message key from the current chain key via HKDF. The chain key advances. Message keys are used once and discarded.

DH ratchet: Every time the conversation direction changes (reply), a new DH exchange runs. This derives fresh root and chain keys, "healing" the session even if a message key was previously compromised.

The result:

• Forward secrecy — compromising key N reveals nothing about keys 1…N-1
• Post-compromise security — after a breach, the DH ratchet step re-randomises the session ### Key Persistence: The Hard Part

WebCrypto's CryptoKey objects can be marked non-exportable — the raw key material is never accessible to JavaScript. We store these directly in IndexedDB.

// Keys never leave as raw bytes
const keyPair = await crypto.subtle.generateKey(
  { name: "ECDH", namedCurve: "P-256" },
  false, // non-exportable
  ["deriveKey", "deriveBits"]
);

Session state (root key, chain keys, ratchet DH keys, message counters) is serialised and persisted across page reloads. Each USID maps 1:1 to a stable cryptographic identity.

Safety Numbers: Closing the MITM Gap

Even with perfect E2EE, a malicious key server breaks everything. Safety Numbers are the solution.

Each user generates a P-256 ECDH identity key pair at registration. Both parties independently compute:

safetyNumber = SHA-256(
    sort_lex([
        SHA256(aliceUsid) + alicePubKey,
        SHA256(bobUsid)   + bobPubKey
    ])
)
// → 12 groups of 5 digits, 60 digits total

Lexicographic sorting ensures both parties derive an identical result regardless of who initiates. They compare the number out-of-band (voice call, in person). If they match — no MITM. If they differ — a key was substituted.

We also implement key change detection: the last-seen safety number is stored in localStorage. On every subsequent session, if the number changes, a prominent warning is shown before proceeding.

Without Safety Numbers (vulnerable):

  Alice                  Server (malicious)              Bob
    │── GET /public-key ──→│                               │
    │←─ Mallory's key ─────│  ← server substitutes        │
    │  encrypts to Mallory  │                               │
    │── ciphertext ────────→│── re-encrypts to Bob ────────→│

With Safety Numbers (protected):

  Alice sees:  12345 67890 11111
  Bob   sees:  72891 23456 78901   ← mismatch → attack caught ✅

P2P File Transfer via WebTorrent

Server involvement in file transfer is a massive privacy leak. Our solution: the server never touches files.

1. Sender seeds the file using WebTorrent — BitTorrent running in the browser via WebRTC data channels
2. A magnet URI is sent to the recipient through the encrypted message channel
3. Recipient's browser leeches directly from the sender
4. Public trackers handle peer discovery only — they never see file contents
5. STUN/TURN handles NAT traversal for users behind symmetric NATs

Sender Browser                    Recipient Browser
  └── WebTorrent.seed(file)
        └── magnet URI (via encrypted WS)  ──→
                                              WebTorrent.download()
              WebRTC DataChannel ────────────────────────────→
              (direct P2P, server not involved)

Live upload speed, download speed, progress, and seeding ratio are displayed in real time via WebTorrent's event API.

Database Architecture: Dual Isolation

Identity metadata and operational data live in separate SQLite databases, linked only by SHA-256(USID). Plaintext identity is never stored anywhere.

identity.db    →   name · email · hashed_usid
app.db         →   users · contacts · mailbox (hashed_usid only)
keys.db        →   X3DH public key bundles (hashed_usid only)

Even if app.db is fully compromised, an attacker gets hashed USIDs and encrypted message payloads — no names, no emails, no identity. The databases are only correlated by SHA-256(USID), which is a one-way mapping.

Offline Mailbox: At-Most-Once Delivery

When a recipient is offline, the server queues the encrypted payload. On their next WebSocket reconnect, all queued messages are flushed and immediately deleted:

Sender → Server (recipient offline)
  └── INSERT INTO mailbox (encrypted_payload)
  └── { type: "queued" }   ← sender sees clock icon

Recipient reconnects
  └── SELECT * FROM mailbox WHERE recipient = ?
  └── forward each message via WebSocket
  └── DELETE FROM mailbox WHERE recipient = ?

The server stores only the already-encrypted payload — it cannot read the content. Deletion on flush ensures no permanent retention.

Cryptographic Primitives Summary

Guarantees: forward secrecy · post-compromise security · HMAC authentication · deniability · pseudonymity · MITM detection

What We Got Wrong (and Fixed)

Curve inconsistency. Signal uses Curve25519 throughout. We used P-256 for identity keys because WebCrypto's ECDH is more consistent across browsers for that curve. The trade-off: P-256 is NIST-standardised (some distrust NIST curves post-Snowden). X25519 is used for X3DH key exchange where performance matters more.

OPK exhaustion. One-time pre-keys are consumed per session. If a user goes offline for a long time, their OPK supply can be exhausted. We added a /keys/replenish endpoint and OPK monitoring, but automatic client-side replenishment is on the roadmap.

WebRTC IP leaks. WebTorrent uses WebRTC, which can leak local and public IPs via STUN. Documented in our STRIDE threat model — mitigation requires a VPN or disabling WebRTC at the browser level.

Roadmap

• [ ] Safety Number QR code scan
• [ ] Post-quantum cryptography (CRYSTALS-Dilithium / SPHINCS+)
• [ ] Multi-device session sync
• [ ] Group messaging via Sender Keys
• [ ] Voice & video (WebRTC)
• [ ] Push notifications (Web Push / VAPID)

Try It / Contribute

🔗 GitHub: https://github.com/ABHIRAM-CREATOR06/Halonyx
🌐 Live: https://halonyx.onrender.com
📄 Threat Model: datathreat/datathreat.md — STRIDE analysis, 17 attack surfaces
📊 Benchmarks: benchmark/benchmark.md — X3DH, Double Ratchet, WebSocket, SQLite latencies

Self-host in three commands:

git clone https://github.com/ABHIRAM-CREATOR06/Halonyx.git
cd halonyx && npm install
npm start

Happy to discuss any of the protocol decisions in the comments — especially the curve choice, the safety number design, or the dual-database isolation model.