Kez/kez-chat/SECURITY.md

kez-chat Security Model

A plain-language description of how kez-chat protects your messages. Written for the curious — read top to bottom, or skip to whichever section you care about.

TL;DR

kez-chat is end-to-end encrypted. Only the people you're talking to can read what you write — not the nostr relays the messages flow through, not the push providers that wake your phone, nobody.

Messages have forward secrecy (an attacker who steals your identity key TODAY can't decrypt messages from more than ~2 weeks ago) and post-compromise security (after a 2-week window elapses, any new messages are safe again, even if the attacker briefly held your key in the past).

Message encryption is post-quantum hybrid (X25519 + ML-KEM-768), so traffic recorded today can't be decrypted by a future quantum computer.

Profile pictures are optionally visually encrypted so people who aren't your contacts see colored noise instead of your face.

This document explains how. Honestly — including where the design isn't quite as strong as Signal's, and why we think the trade is worth it for a chat built on nostr.

What kez-chat protects against

• Nostr relays reading your messages. They see encrypted bytes and routing tags. They cannot read content, even if every relay you use colludes.
• Push providers (FCM / APNs / Mozilla) reading your messages. Push payloads are empty by design. The provider knows "kez-chat woke a device," nothing about who messaged whom.
• A passive observer who logs everything for years. If they later compromise your KEZ identity key, they STILL cannot decrypt messages older than your forward-secrecy window (default 16 days). Those keys are gone.
• Brief device compromise (an attacker had your phone for 30 seconds at a bar). Anything within the current retention window is exposed, but new messages sent AFTER the compromise are safe again once the window rolls over.
• Identity impersonation. Every message is signed by the sender's long-term Ed25519 key. Forgeries don't verify.
• Replay attacks. Each event has a unique id; envelopes carry a timestamp; the receiving client rejects anything more than ±5 minutes off the wall clock or older than the freshness window.
• Metadata leak in the message body. Sender identity, recipient identity, and message content all live INSIDE the encrypted blob. Relays see only an opaque "to addr X" routing tag.
• Stranger profile-picture scraping. If you enable visual encryption (default), strangers see scrambled noise. Only people who've messaged you can see your actual face.

What kez-chat does NOT protect against (be honest)

• A determined attacker on your device DURING the retention window. Anything in your IndexedDB at the moment of compromise is exposed. Mitigation: shorter retention window (Settings → Forward Secrecy slider) trades offline tolerance for tighter exposure.
• Per-message forward secrecy at Signal's granularity. Our window is days, not "until you've decrypted the next message." More on this below.
• The chat-server operator learning who's registered with them. Handle registration is on a public directory. If you want your handle private, don't register it.
• Traffic-analysis metadata. Nostr relays see "Alice posted an event tagged to Bob's routing addr at 14:35." That's enough to build a social graph. We don't onion-route or pad messages. (If you need that, use a chat that does — there are real trade-offs.)
• First-message-ever-to-a-brand-new-contact fallback. When you message someone who has never published a heartbeat, that ONE message uses a fallback path with no receiver-side forward secrecy. Every subsequent message in the conversation gets the full protection.
• Multi-device. Today, signing in on a second device generates a fresh set of heartbeats and effectively orphans the first device's decryption history. This is documented as a v0.1 limitation; the fix is on the roadmap.
• Quantum computers — partially. Message encryption is post-quantum: v4 envelopes combine X25519 with ML-KEM-768 (the NIST standard, same idea as Signal PQXDH and Apple PQ3), so messages harvested from relays today stay safe. Two gaps remain: the very first message to a contact who has never published a heartbeat is classical-only, and signatures (Ed25519, nostr secp256k1) are still classical — a future quantum attacker could impersonate someone in real time, though not decrypt past messages.

How identity works

Each kez-chat account is a single 32-byte random number (the "seed"), generated on first install. From the seed we derive:

• Ed25519 signing key — your KEZ identity. The public half (ed25519:<hex>) IS your long-term identity. You sign every message envelope with it so recipients know it's you.
• X25519 key — used for ECDH (key exchange) with peers. Derived from the same seed via standard Montgomery conversion.
• Secp256k1 / Schnorr key — your nostr signing key. Derived via HKDF with a domain separator (kez-chat:nostr-signkey/v1). Used only to sign nostr events so relays accept them. Never surfaced to the user.

The seed itself is encrypted at rest under your passphrase (PBKDF2 → AES-GCM) and stored in browser IndexedDB. Unlock decrypts it into memory; lock zeroes it.

Optionally: a 30-day "persistent session" wraps the seed under a non-extractable WebCrypto AES key for fast re-unlocks. This is designed as the same trust boundary as the biometric-unlock path: an attacker with code execution in your browser origin can decrypt the seed, but cannot exfiltrate the key off the device.

How messages are encrypted (the envelope)

When you send a message, kez-chat builds a "v3 envelope" that looks roughly like this:

{
  "v": 3,
  "eph_pub":                "<32 bytes hex>",
  "recipient_heartbeat_pub":"<32 bytes hex>",
  "nonce":                  "<12 bytes hex>",
  "ciphertext":             "<AEAD output, hex>",
  "sender_sig":             "<64 bytes hex>"
}

The full envelope is JSON-stringified, then carried as the content field of a nostr DM event (kind 4242). The nostr event is signed with your nostr key and broadcast to ~5 relays.

Encryption process:

1. Generate a fresh ephemeral X25519 keypair just for this one message. Discard the private the moment you're done.
2. Look up the recipient's most recent heartbeat public key from nostr (more on this below). Fall back to their identity X25519 pub if they've never published one.
3. Perform X25519 ECDH using the ephemeral private + recipient's heartbeat public. This produces a shared secret known only to you and the recipient.
4. Run the shared secret through HKDF-SHA256 (with the nonce as salt and a domain-separated info string) to get a single-use AES-256 key.
5. Encrypt your message text with AES-256-GCM, using a 12-byte random nonce and Additional Authenticated Data that binds the envelope's {v, eph_pub, recipient_heartbeat_pub, nonce, fallback} fields into the auth tag. A relay tampering with any routing field would break decryption.
6. Sign the envelope (minus signature) with your Ed25519 key. This proves YOU sent it.

The plaintext that gets encrypted carries {from, body, sent_at}. Your identity is INSIDE the ciphertext; the relay never sees it.

The Heartbeat Ratchet — kez-chat's forward secrecy

This is the interesting part.

Traditional end-to-end systems either (a) accept that compromise of your long-term key compromises ALL history (no forward secrecy) or (b) implement Signal's Double Ratchet (excellent forward secrecy but significant complexity and dependence on a central prekey server).

kez-chat takes a third path that's specific to chat over nostr:

How it works

• Each day, on first activity, your device generates a fresh random X25519 keypair — the "heartbeat."
• The PUBLIC half is published to nostr as a parameterized replaceable event (kind 10142, d-tag heartbeat-v1), signed with your nostr key. Anyone can fetch your latest heartbeat.
• The PRIVATE half lives only on your device, in IndexedDB.
• When someone messages you, their client fetches your latest heartbeat and uses ITS public key as the ECDH target — not your long-term identity key.
• You decrypt by looking up the matching private key from your local IDB store.
• After your configurable retention window (default 16 days; 3–60 in Settings), old heartbeat privates are deleted.

Why this gives you forward secrecy

The heartbeat privates are random bytes, NOT derived from your seed. The seed only signs the heartbeat publish to prove it's yours. So:

• A passive observer who has been logging every encrypted message for years, then later compromises your seed, cannot decrypt messages older than ~16 days. The private keys for those messages were random and have been deleted. The seed alone is not enough.

Why this gives you post-compromise security

If your device is briefly compromised (one-shot attacker, no persistence):

• They can decrypt anything in your IDB at that moment — up to 16 days of stored heartbeat privates.
• After 16 days, those privates have been swept. The captured data is now permanently undecryptable, even from your seed.
• Meanwhile, fresh heartbeats your device generates AFTER the compromise are random bytes the attacker never saw. They can sign fake heartbeats AS you (impersonation), but they cannot predict the randomness your real device produces. Future messages to your real device are safe.

Why this is simpler than Double Ratchet

• No per-peer session state. One heartbeat keyset serves all contacts. Signal has to maintain a separate ratchet state per conversation.
• No prekey distribution server. Signal users publish prekey bundles to Signal's server; new senders fetch them. We publish heartbeats to nostr — the same publish/subscribe infrastructure we use for messages.
• No X3DH initial handshake. First contact uses a documented fallback (no FS on that one message) and the very next reply bootstraps full v3.
• No out-of-order message bookkeeping. Each message is independently sealable to whichever heartbeat the sender saw at send time.

The honest trade — granularity

Signal's forward secrecy is per-message. The moment a message is decrypted, that key is gone. Our forward secrecy is per-window (default 16 days). Anything in IDB at the moment of compromise is readable.

For chat-style threat models — "someone steals my phone, sees what's there" — both approaches give the attacker WHAT'S ON THE DEVICE NOW. Signal's edge is the brief gap between decrypting a message and the next one arriving. Real-world significance: small but not zero.

The relevant question: is the simpler protocol worth a coarser FS window? We think yes, because:

1. Implementation correctness matters. A correctly-implemented simple ratchet beats a subtly-broken Double Ratchet every time. Signal-style ratchet implementations are notoriously bug-prone.
2. It naturally fits nostr. Signal was designed for a central server; our design uses nostr's actual semantics (replaceable events for keys, broadcast for messages). No fighting the substrate.
3. The chat threat model is "phone theft" not "subtle ratchet misuse." Most real attacks fall into the category our window handles correctly.
4. You can tune the window. Slide it to 3 days for tighter FS, or 60 days if you travel offline a lot. Signal's per-message granularity isn't tunable.

Profile picture privacy (visual encryption)

Your nostr kind:0 profile event is fundamentally public — every nostr client can read it. Putting your face directly in your profile means anyone scraping nostr sees you.

kez-chat's solution: by default, the profile picture you publish is visually scrambled.

How it works

• You pick a picture in Settings → Profile.
• Your device generates a random 256-bit symmetric key K and a per-image nonce.
• The image's pixels are deterministically shuffled by a PRNG seeded from K — Fisher-Yates shuffle. The output is a valid PNG with the same dimensions and color palette, but the content is garbled.
• The scrambled PNG goes in your kind:0 event under picture.
• For each of your contacts (people you've ever DM'd), your client wraps K under a SealedEnvelope (the same v3 envelope crypto used for DMs) addressed to that contact's KEZ primary. The wrapped keys go in a kez_visual_keys field of your kind:0.
• A "self-wrap" is also included so any other device of yours can rebuild K from your own seed.

What strangers see

A scrambled PNG. Same colors, same dimensions, no recognizable content. They cannot decrypt — the per-recipient wraps are encrypted to specific contacts.

What contacts see

Their client fetches your kind:0, finds the wrap addressed to them, opens it via your existing DM crypto, recovers K, and uses K to unscramble the picture. They see your real face.

What this gives you

Your face is private by default and visible only to people you've actually talked to. No additional infrastructure, no separate image host, no permission requests. Same nostr publish/subscribe path.

You can turn it off in Settings if you want a public profile picture.

Comparison with Signal Protocol

Property	Signal	kez-chat
End-to-end encryption	✅	✅
Authentication / sender forgery resistance	✅	✅
Replay protection	✅	✅
Sender-side per-message forward secrecy	✅	✅
Receiver-side forward secrecy	per-message	per-window (default 16d)
Post-compromise security after seed leak	per-DH-step (~per-reply)	per-window
Multi-device	first-class	single-device in v0.1
Group chat	✅	❌ (future)
Prekey distribution	central Signal server	nostr (decentralized)
Identity / contact discovery	Signal's server	KEZ + nostr (decentralized)
Per-peer session state	yes (real bookkeeping)	none
Code complexity	high	moderate
Post-quantum encryption	PQXDH (X25519 + ML-KEM)	v4 hybrid (X25519 + ML-KEM-768)

Where Signal wins: per-message FS granularity, multi-device today, groups today, longer track record of stress-testing.

Where kez-chat wins: no central server, no Signal-account registration, no Signal-prekey-store dependence, identities portable across the KEZ graph, the entire system fits in a PWA you can run from any browser.

Trust assumptions

To use kez-chat, you're trusting:

• Your browser's WebCrypto implementation. Same as Signal Web, same as iMessage Web, same as any browser-delivered crypto.
• Standard cryptographic primitives. Ed25519 (signatures), X25519 (key exchange), AES-256-GCM (encryption), SHA-256 (hashing), HKDF (key derivation). All well-studied and widely deployed.
• @noble/curves and @noble/hashes — pure JavaScript crypto libraries with formal audits, used by many production wallets and chat tools.
• The nostr-tools library — for relay communication. Doesn't touch your private keys (we sign locally before handing off).
• At least ONE of the configured nostr relays staying honest enough to forward your events. Of the default 5 (relay.damus.io, nos.lol, relay.primal.net, relay.snort.social, nostr.wine), only one needs to work for delivery to succeed.

You are NOT trusting:

• The kez-chat home server (kez.lat) for message delivery. Chat flows directly through nostr; the home server is only used for handle directory lookups and Web Push fanout.
• Any single nostr relay. All 5 would have to refuse independently.
• Any push provider. Push payloads are empty.

Glossary

AAD (Additional Authenticated Data) — extra metadata that an AEAD cipher includes in the authentication tag. We bind envelope routing fields so a relay can't tamper without breaking the auth check.

AEAD (Authenticated Encryption with Associated Data) — encryption + integrity + tampering detection in one primitive. We use AES-256-GCM.

ECDH (Elliptic Curve Diffie-Hellman) — two parties compute the same shared secret from their respective private keys + each other's public keys. The foundation of all our message encryption.

Forward Secrecy — past messages stay safe even if your key leaks later.

Heartbeat — a fresh random X25519 keypair your client publishes daily to nostr. Senders use the public half for ECDH instead of your long-term identity.

HKDF (HMAC-based Key Derivation Function) — turns a high-entropy input (like an ECDH output) into one or more cryptographic keys suitable for use in AEAD.

KEZ identity — your long-term Ed25519 keypair, the canonical "this is who I am" in the kez-chat / KEZ system.

Nostr — a simple publish/subscribe protocol over WebSockets we use as the message-delivery substrate. Decentralized; you publish events to relays, others subscribe.

Post-Compromise Security (PCS) — even if your key was compromised in the past, future messages eventually become safe again as keys evolve.

v3 envelope — kez-chat's current message format. Carries a sender ephemeral pub, a recipient heartbeat pub, a nonce, the ciphertext, and the sender's signature. See crypto.ts.

---

Last updated: 2026-06-12. Source: kez-chat/web/src/lib/crypto.ts, heartbeat-store.ts, nostr-transport.ts, visual-crypto.ts, profile-store.ts.