https://github.com/systemslibrarian/crypto-lab-ratchet-wire
Browser-based demo of the Double Ratchet Algorithm — the cryptographic protocol powering Signal, WhatsApp, and Google Messages. Live conversation with forward secrecy, break-in recovery, and key compromise simulation.
https://github.com/systemslibrarian/crypto-lab-ratchet-wire
aes-gcm browser-demo crypto-compare cryptography double-ratchet forward-secrecy hkdf key-exchange messaging-protocol post-quantum-ready signal-protocol typescript vite x25519
Last synced: 1 day ago
JSON representation
Browser-based demo of the Double Ratchet Algorithm — the cryptographic protocol powering Signal, WhatsApp, and Google Messages. Live conversation with forward secrecy, break-in recovery, and key compromise simulation.
- Host: GitHub
- URL: https://github.com/systemslibrarian/crypto-lab-ratchet-wire
- Owner: systemslibrarian
- Created: 2026-04-06T15:43:30.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T16:56:02.000Z (about 2 months ago)
- Last Synced: 2026-04-06T18:27:21.727Z (about 2 months ago)
- Topics: aes-gcm, browser-demo, crypto-compare, cryptography, double-ratchet, forward-secrecy, hkdf, key-exchange, messaging-protocol, post-quantum-ready, signal-protocol, typescript, vite, x25519
- Language: TypeScript
- Homepage: https://systemslibrarian.github.io/crypto-lab-ratchet-wire/
- Size: 37.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# crypto-lab-ratchet-wire
## 1. What It Is
Ratchet Wire is a browser-based demonstration of the Double Ratchet Algorithm with Simplified X3DH session setup, using X25519 for key agreement, HKDF-SHA256 for key derivation, and AES-256-GCM for message encryption. It shows how two parties keep deriving fresh keys while exchanging messages over an untrusted channel. The algorithm solves the problem of end-to-end message confidentiality with forward secrecy and break-in recovery after a state compromise. Its security model is hybrid: asymmetric key agreement establishes and refreshes shared secrets, while symmetric ratchets derive per-message encryption keys.
## 2. When to Use It
- Use it for asynchronous end-to-end messaging systems where each message needs its own fresh encryption key, because the Double Ratchet Algorithm is designed to preserve confidentiality across long conversations.
- Use it when you need forward secrecy and break-in recovery in a chat protocol, because compromised current state should not expose old traffic and should stop helping an attacker after a ratchet step.
- Use it for educational or prototype work that needs to illustrate X25519, HKDF-SHA256, AES-256-GCM, and Simplified X3DH together, because this demo exposes those pieces directly in the UI and source.
- Do not use this demo as a production messenger, because the Simplified X3DH implementation explicitly omits signatures, one-time pre-keys, and persistent state management.
## 3. Live Demo
Live demo: https://systemslibrarian.github.io/crypto-lab-ratchet-wire/
The demo lets you switch between Conversation, Ratchet State, Break-In Recovery, and How It Works tabs while sending messages as Alice or Bob and watching the live root-key and chain-key state update. It also includes the Compromise Bob's Keys, Alice Sends Message, and Bob Receives (DH Ratchet) controls so you can step through break-in recovery behavior. There are no key-size or iteration controls in this demo; the interactive controls are the sender selector, message input, tabs, and recovery buttons.
## 4. How to Run Locally
```bash
git clone https://github.com/systemslibrarian/crypto-lab-ratchet-wire.git
cd crypto-lab-ratchet-wire/ratchet-wire
npm install
npm run dev
```
No environment variables are required.
## 5. Part of the Crypto-Lab Suite
This demo is one entry in the broader Crypto-Lab collection at https://systemslibrarian.github.io/crypto-lab/.
Whether you eat or drink or whatever you do, do it all for the glory of God. — 1 Corinthians 10:31