Bind every message to a globally verifiable now. If an AI wants to impersonate you, it has to impersonate this very second.
A research demo / open-source reference implementation of HEARTBEAT — a
messaging protocol that pins each message to a publicly verifiable randomness
beacon (drand). The repo ships:
- A working protocol implementation (Python, ~800 LOC, zero home-grown cryptography — Ed25519 + BLS-12-381 standard libs only).
- A live attack/defense web app where a real OpenAI LLM plays the adversary, and you watch the protocol either let it through or reject it, token-by-token, in your browser.
- A solo CLI demo if you don't want to set up an OpenAI key.
This is the first public combination of drand + Ed25519 message signing
designed specifically as a defense layer against AI-driven impersonation,
replay and forgery attacks on human-to-human communications.
Every message carries a freshly-pulled drand round number. The receiver rejects any message whose round is more than ±10 rounds (~30 seconds) away from "right now". An AI can forge content but it cannot forge the future output of a 20-node distributed beacon — so impersonation must happen in real time, every single message, killing the AI attacker's core advantages: offline, remote, parallel.
git clone https://github.com/zhou2030109-glitch/heartbeat.git
cd heartbeat
pip install -e .
# Generate the three demo identities (alice / bob / eve)
python -m heartbeat.tools.gen_keys
# Run the unit tests against the real drand network
pytest tests/test_smoke.py # 8 passed in ~6s
# (Optional) for the live web demo, set your OpenAI key first
export OPENAI_API_KEY=sk-... # Linux/macOS
$env:OPENAI_API_KEY = "sk-..." # Windows PowerShell
python -m heartbeat.live # opens on http://127.0.0.1:8000Open the URL — you'll see a 3-column UI:
┌────────────────┬──────────────────────┬─────────────────────┐
│ 👤 ALICE │ 👁 BOB │ 🤖 AI ATTACKER │
│ type & send │ chat + green/red │ 4 attack buttons │
│ │ badges per message │ + live reasoning │
└────────────────┴──────────────────────┴─────────────────────┘
Type a sentence as Alice. Watch Bob get a 🟢 verified bubble. Then trigger any of the four attacks and watch GPT-4o-mini try — and fail.
Every one of these calls the real OpenAI API. You see the LLM's tokens stream into the attacker pane in real time.
| Mode | What the LLM is asked to do | Why HEARTBEAT rejects |
|---|---|---|
| 🦹 MITM rewrite | Toggle on. Each time Alice sends, intercept and rewrite into a deceptive variant ("meeting at 10" → "send me 50k") | Ed25519 fails — attacker doesn't hold alice.sk |
| ✏ Forge | Read the chat history; write a brand-new message impersonating Alice's tone | Ed25519 fails |
| 🔁 Smart replay | Look at captured envelopes; pick the most valuable one to replay later | Round out of window (Δ > 10) |
| 💀 Flood with leaked key | Assume alice.sk was stolen; auto-generate N phishing variants |
Even with the real key, attacker is forced to fetch a fresh drand round every 3s — parallel attacks collapse to serial |
The flood attack is the most interesting: HEARTBEAT does not stop a leaked key from sending, but it bounds the damage from "permanent compromise" to "must be online continuously and serial" — which destroys the AI attacker's scaling advantage.
We didn't invent any cryptography. Every primitive is off-the-shelf:
drand(League of Entropy, since 2019) — distributed randomness beacon- Ed25519 (RFC 8032) — message signatures
- BLS-12-381 (IETF draft / ETH 2.0) — beacon signatures
- HKDF (RFC 5869) — key derivation
The contribution is the combination, the threat model, and the
demonstration. See docs/07-prior-art.md for the
full Prior Art write-up.
Specifically, we haven't found any other open-source project that:
- Treats a public randomness beacon as a mandatory freshness anchor on each message (not just an auxiliary randomness source).
- Targets AI-driven impersonation / deepfake as the explicit threat model rather than blockchain randomness or VRFs.
- Ships a live demo where a real LLM is the attacker and the user can watch it lose token-by-token.
If you find prior art that overlaps, please open an issue — we'll cite it.
┌─────────────────────────────────────────────────────────────────┐
│ drand quicknet (3-second period, 20-node BLS-12-381 threshold)│
└─────────────────────────────────────────────────────────────────┘
▲ HTTP GET / public/latest
│
┌───────────────┴────────────────────────────────────────────────┐
│ heartbeat.beacon — fetch + verify R_t │
│ heartbeat.sender — Ed25519 sign payload = msg ‖ ts ‖ round │
│ heartbeat.verifier — 3-step check: BLS · window · Ed25519 │
└───────────────┬────────────────────────────────────────────────┘
│ in-process function calls
┌───────────────┴────────────────────────────────────────────────┐
│ heartbeat.live — FastAPI + WebSocket app │
│ heartbeat.live.attackers.{mitm,forge,replay,flood} │
│ ↓ │
│ OpenAI GPT-4o-mini (streamed) │
└────────────────────────────────────────────────────────────────┘
Each module is small, single-purpose, and unit-tested against the real
network. See docs/02-architecture.md for full
data-flow diagrams.
heartbeat/
├─ heartbeat/ # protocol core (~800 LOC)
│ ├─ beacon.py # drand HTTP + BLS-G1 verify
│ ├─ identity.py # Ed25519 keypair
│ ├─ wire.py # JSON envelope
│ ├─ sender.py # sign
│ ├─ verifier.py # 3-step check
│ ├─ config.py
│ ├─ demo.py # CLI 4-scene runner
│ ├─ tools/gen_keys.py
│ └─ live/ # web demo
│ ├─ app.py # FastAPI + WebSocket
│ ├─ llm.py # AsyncOpenAI streaming
│ ├─ attackers/
│ │ ├─ mitm.py
│ │ ├─ forge.py
│ │ ├─ replay.py
│ │ └─ flood.py
│ └─ static/index.html
├─ keys/ # generated demo identities
├─ tests/test_smoke.py # 8 tests vs real drand
├─ docs/ # protocol spec, threat model, etc.
├─ CONSTRAINTS.md
└─ pyproject.toml
We're explicit about what HEARTBEAT cannot do:
- Real-time deepfake calls — an attacker physically present and pulling drand in real time can still send valid messages. We squash the scaling/automation advantage, not the attack class itself.
- drand network compromise — if 11+ of 20 nodes collude, all bets are off. This is currently harder than 51%-attacking Bitcoin.
- Clock skew > 30s on the receiver — falls back to "reject", never to "accept a stale R as fresh".
Full analysis in docs/03-threat-model.md.
| File | Content |
|---|---|
docs/01-spec.md |
Wire format, state machine, API |
docs/02-architecture.md |
Three-layer stack + data flow |
docs/03-threat-model.md |
Attacker capabilities + defense matrix |
docs/04-demo-script.md |
4-scene CLI walkthrough |
docs/05-cost-and-trust.md |
Trust assumptions, FMEA |
docs/06-roadmap.md |
v1 → v4 evolution |
docs/07-prior-art.md |
Related work + our delta |
docs/CHEATSHEET.md |
1-page demo cheatsheet |
CONSTRAINTS.md |
Project ground truth (locked decisions) |
MIT. See LICENSE.
- drand / League of Entropy — the public beacon this project depends on
- OpenAI — adversary GPT-4o-mini (any chat-completions-compatible model
works; see
heartbeat/live/llm.py) - The original PPT framing was developed for the Hunan University 2026 Hackathon by Team 11 (周洛玄 / 王硕 / 于海跃)