A few weeks ago I published a post about building Halonyx which is a Signal Protocol messenger that I implemented from scratch with X3DH key exchange, Double Ratchet, Safety Numbers, and peer-to-peer file transfer via WebTorrent.
The response surprised me. Siyu, who is building agent-to-agent communication infrastructure, spotted that X3DH's "establish a session with someone who isn't present" property was exactly what they needed. Evans, who runs an anonymous Q&A app, asked why I chose X3DH over simpler approaches. Both conversations went deep into protocol design, which was genuinely useful.
But I also noticed something. Most people who clicked through were engineers who already knew what a Diffie-Hellman operation was. Everyone else that include my friends, classmates, faculty members and people who messaged me after seeing a WhatsApp status, read the README, hit the X3DH section, and left.
That gap bothered me. The whole point of publishing Halonyx was to be transparent about how it works, including where it falls short. A README that only engineers can follow is not really transparency.
So I built a simulator.
What it is
A single HTML file with no framework, no build step, no external dependencies that walks through the complete Halonyx protocol in 14 steps. It runs entirely in the browser.
Two modes, same steps:
Beginner mode uses plain English and consistent analogies. Bob's key bundle is a padlock on a public noticeboard. The Double Ratchet is a combination lock that changes its own combination after every use. Safety Numbers are two people reading out the same number over a phone call. The technical terms are introduced, explained in one sentence, and then used consistently.
Protocol mode shows the actual implementation — Halonyx API endpoints, SQLite schemas, WebSocket frame structures, real cryptographic parameters, code snippets from the source.
A toggle switches between them. Both modes share the same interactive elements and the same "show me the technical detail" expandable panel on every step.
What the 14 steps cover
The simulator does not skip the uncomfortable parts.
Key setup and OPK exhaustion. Bob uploads his X3DH key bundle — Identity Key, Signed Pre-Key, ten One-Time Pre-Keys. The simulator then immediately shows what happens when an attacker drains all ten OPKs on purpose. The session falls back from four DH operations to three. The forward secrecy guarantee weakens. Halonyx has a replenishment endpoint but no automatic client-side top-up yet — the simulator shows this gap explicitly, not buried in a footnote.
X3DH key exchange. All four DH operations, each labeled with what security property it provides. DH1 binds identities. DH2 and DH3 add ephemeral randomness. DH4 uses the consumed one-time key for deniability. The shared secret appears on Alice's side and Bob's side simultaneously — the server shown passing only an opaque packet between them.
Double Ratchet. A ratchet that visibly clicks forward with each message, each click producing a different key that disappears immediately after use. The "send message" button lets you click through several messages and watch the keys change. Forward secrecy and post-compromise security labeled as properties that become true as the ratchet advances.
The key substitution attack. This is step six of fourteen, which is earlier than most explainers put the attack. That is intentional. The simulator shows the attack before showing the defense — Mallory sliding in between Alice and the server, swapping Bob's public key with her own, reading everything, re-encrypting and forwarding so neither party notices. A red banner: "Server reading all messages. Neither party is aware." It is supposed to feel alarming.
Safety Numbers. The defense against step six. Both parties independently compute SHA-256 of their combined identity keys, formatted as sixty digits in twelve groups of five. They compare over a voice call. An "attack mode" toggle lets you watch the numbers diverge when Mallory is active, and snap back to matching when she is not.
Complete message flow. The full nine-step sequence from Alice hitting send to Bob reading the message, including the AES-256-GCM encryption, the WebSocket frame structure, the offline mailbox queue, and the delete-on-delivery guarantee. The server shown at every step receiving only an encrypted blob it cannot open.
WebTorrent file transfer. Files arc over the server entirely, bypassing it. The server receives only the magnet URI. The IP exposure via WebRTC STUN is shown as a labeled limitation with its mitigation — not hidden.
Triple database isolation. The three SQLite databases and the one-way SHA-256(USID) link that connects them. An attacker stealing app.db shown receiving only hashed identifiers and encrypted payloads.
USID identity. No phone number. No email required. A 256-bit random number as your identity, with only its hash stored server-side.
Why HTML, CSS, and JavaScript with no dependencies
A few reasons.
The obvious one is that anyone can open it, inspect every line, and verify it matches what the README claims. There is no compiled bundle to dig through.
The less obvious one is that it felt right for a transparency tool to be fully legible. Halonyx is trying to be a system where the security properties are verifiable, not just claimed. A simulator explaining it should work the same way.
The constraint also kept the scope honest. No framework means no component library, no routing, no build configuration — just the explanation itself.
The part I was most uncertain about
The OPK exhaustion step almost did not make it in.
It is a real limitation. Showing it means admitting that a specific attack on Halonyx produces a measurable weakening of the forward secrecy guarantee on a session. That is not comfortable to put in a public explainer.
But the dev.to comments on the first post convinced me. Vinicius Pereira's comment about the WebCrypto curve inconsistency that X25519 for X3DH alongside P-256 for identity keys is a forced trade-off rather than a mistake, because non-exportable CryptoKey objects were only reliably available for NIST curves until recently that was the most technically useful response I got. It came from being honest about limitations in the original post, not from presenting the project as finished.
The simulator takes the same approach. If you are going to explain how a security system works, the limitations are part of how it works.
Try it
The simulator is linked from the Halonyx README and runs directly in the browser.
GitHub: https://github.com/ABHIRAM-CREATOR06/Halonyx
Previous Post: https://tinyurl.com/28ru6uzm
Live demo:
If you find something the beginner explanation gets wrong, or a protocol detail in protocol mode that does not match the source, I want to know. The point is accuracy, not just accessibility.
Top comments (0)