Kez/kez-chat/TODO.md

# kez-chat security + protocol TODO

Consolidated from a nostr-protocol expert review and an independent security
audit (both run 2026-06-08). Ordered by impact-per-hour-of-work, not by
review severity — a CRIT that's a half-week of design discussion isn't a
ship-stopper when there are real CRITs that take 30 minutes.

Update the status column as we land things. Cross-links to the original
review reports are at the bottom.

## Status legend

- `TODO` — not started
- `WIP` — actively being worked
- `DONE` — landed in main
- `ROADMAP` — committed but multi-day; will need its own design doc
- `WONTFIX` — accepted trade-off, documented

---

## Day 1 — ~half a day of work, biggest wins

### #1. Strip envelope metadata (ephemeral x25519 per message)  [DONE]

**Why it matters:** the `SealedEnvelope.from` (KEZ identity) and `to` (handle)
fields sit in cleartext alongside the ciphertext in `event.content`. Any
nostr relay can JSON-parse the content and build a perfect social graph:
who-messages-whom, when, how often. The actual message body stays encrypted;
all the metadata is wide open.

**Files:**
- `kez-chat/web/src/lib/crypto.ts:42-54` (the `SealedEnvelope` shape)
- `kez-chat/web/src/lib/crypto.ts:115-153` (`sealMessage` / `openMessage`)

**Fix:** replace `envelope.from` (the KEZ identity) with `envelope.eph_pub`
(a 32-byte x25519 public key sender generated for this message only).
Recipient does ECDH against `eph_pub` instead of deriving it from the KEZ
identity. The decrypted plaintext already carries `from` for identity
verification.

Bonus: a fresh ephemeral key per message gives partial forward secrecy —
compromise of the recipient's long-term seed still decrypts retained
ciphertexts, but a captured single-message ECDH key reveals only that one
message.

**Migration:** envelope `v: 1 → v: 2`. Recipient accepts both during a
1-week window, then drops v1 support.

### #3. Empty Web Push payload  [DONE]

**Why it matters:** we send `{type, to: <handle>, seq}` to FCM/APNs/Mozilla
on every fanout. RFC 8291 encrypts the payload so the push provider can't
read the bytes, but the provider already knows the endpoint's owner — the
`to` field adds no information for the recipient and *does* give Google a
clear "message arrived for alice at T" timeline.

**Files:**
- `kez-chat/src/messages.rs:123-127` (the payload we hand to `push.fanout`)
- `kez-chat/web/src/sw.ts:78-99` (the `push` handler)

**Fix:** send `{}` as the payload. The service worker shows a generic
"New kez-chat message" notification — it can still focus an existing tab,
which navigates to the conversation list. Deep-linking to a specific peer
goes away on cold-open (acceptable trade-off — one extra tap to open the
right thread is the price of *not* exporting metadata to FCM).

### #5. Rename the routing tag from `h` to something less claimed  [DONE]

**Why it matters:** `h` is informally used by NIP-29 (Simple Groups) as the
group id. Today's three relays don't enforce NIP-29 semantics, but the
moment a NIP-29-aware relay enters our pool it will try to route our `#h`
filter as a group join, and we'll get cryptic failures.

**Files:**
- `kez-chat/web/src/lib/nostr-id.ts:28` (`ADDR_TAG = "h"`)
- `kez-chat/web/src/lib/nostr-transport.ts:201, 269` (publish + subscribe)
- `kez-chat/src/nostr_listener.rs:113` (server-side mirror)

**Fix:** switch to `q` (less-claimed single letter, still indexable per
NIP-01). Bump envelope/event `v` so the listener can tell old-tag events
from new ones during the migration window. Server-side listener subscribes
to BOTH `#h` and `#q` for one week.

### #17. Demote handle-revealing logs to `debug!`  [DONE]

**Why it matters:** every fanout currently logs `push: fanout triggered
handle=<plain handle> sub_count=N` at INFO level. Operator-side log
retention turns this into a permanent "who's chatting" ledger. Even if
we trust the operator (it's us), forensics on a stolen log file leaks the
social graph in plaintext.

**Files:**
- `kez-chat/src/push.rs:259-262, 275-281` (fanout + send logging)
- `kez-chat/src/api.rs:387-393` (subscribe registration)

**Fix:** demote the handle-bearing INFO lines to DEBUG. Replace the visible
field with a short HMAC of the handle under a server-instance secret so we
can still group "all sends for X" in logs without exposing X. Set log level
in production to INFO, so DEBUG lines are off by default.

---

## Day 2 — another half-day

### #2. Replay protection — bound + timestamp freshness  [DONE]

**Why it matters:** `SEEN_CAP=500` evicts oldest event ids once we've seen
500 messages. An active user rolls past that in days, then a malicious
relay can re-broadcast any old event and we accept it as a fresh message —
the decrypted `sent_at` is never compared to wall-clock.

**Files:**
- `kez-chat/web/src/lib/nostr-transport.ts:107` (`SEEN_CAP = 500`)
- `kez-chat/web/src/lib/nostr-transport.ts:142` (`slice(-SEEN_CAP)`)
- `kez-chat/web/src/lib/crypto.ts:161-205` (`openMessage` — no freshness check)

**Fix:**
1. Bump `SEEN_CAP` to 10_000 and move from localStorage to IndexedDB so the
   set isn't capped by the 5MB localStorage quota.
2. In `openMessage`, reject envelopes where `|now − sent_at| > 7 days`.
3. Also clamp `ev.created_at` to `[now − 7d, now + 5min]` before using it
   as a seq generator — otherwise a relay can backdate or future-date
   events and either replay or skip-ahead `bumpSince`.

### #4. Reveal-recovery-phrase requires fresh auth  [DONE]

**Why it matters:** 30 seconds of access to an unlocked phone = full
identity exfil. The Settings → Reveal Phrase button decrypts straight from
the persistent-session blob with no re-prompt.

**Files:**
- `kez-chat/web/src/routes/Settings.svelte` (the Reveal flow)

**Fix:** gate Reveal Phrase + Lock + biometric setup behind a fresh
passphrase prompt OR a WebAuthn assertion. Same model Apple/1Password use:
"this action requires your password again".

### #15. Rate-limit `POST /v1/messages`  [DONE]

**Why it matters:** the endpoint currently accepts anonymous posts (no
auth on send) capped at 256KB per envelope. A bot can fill any mailbox
until disk fills. Acknowledged in `messages.rs:18-20` ("Spam: v0.1 doesn't
gate POST").

**Files:**
- `kez-chat/src/messages.rs:70-133`

**Fix (v0.1):** per-IP token bucket — 60 messages/min per source IP. Drop
overflow with 429.
**Fix (v0.2):** require the sender to sign with their KEZ primary; chat-
server verifies. Becomes useless for cross-server v0.2 unless the sender's
server vouches.

---

## Roadmap — multi-day, needs design pass

### #6. Forward secrecy (Heartbeat Ratchet)  [DONE — alternative design to Double Ratchet]

Implemented a custom forward-secrecy protocol that fits nostr's
shape better than Signal's Double Ratchet would. Full reasoning
in `heartbeat-store.ts` and `crypto.ts` (search for "v3").

Summary:
  - Each user publishes a fresh random x25519 pub once per active
    day as a replaceable event (kind 10142, NIP-01 10000–19999
    range; d-tag "heartbeat-v1" informational). Content is signed
    by the KEZ identity; senders verify it against the recipient's
    primary before use.
  - Private half kept on the publishing device only; deleted after
    the user-configurable retention window (default 16 days,
    settable 3–60 in Settings).
  - Senders fetch the recipient's latest heartbeat and ECDH against
    it instead of the recipient's long-term identity key (v3
    envelope).
  - First-ever message to a brand-new contact (no heartbeat
    fetchable yet) falls back to identity ECDH with `fallback: true`
    on the envelope. Single message, no FS. Subsequent messages get
    full v3.
  - Receiver-side forward secrecy at retention-window granularity:
    after the window elapses, even seed compromise can't decrypt
    historical messages.
  - Sender-side FS preserved from v2 (per-message ephemeral).
  - Post-compromise security: one-shot seed compromise (no
    persistence) becomes invisible after retention window, because
    fresh heartbeats are random and live only on the legitimate
    device.
  - Migration: dual-decrypt. v1/v2/v3 all accepted; only v3 emitted.
  - Single-device scope for v0.1. Multi-device with shared heartbeat
    state is future work.
  - v4 (post-quantum hybrid): each heartbeat also carries an
    ML-KEM-768 key (signed with the rest of the heartbeat). Senders
    encapsulate to it and derive the AES key from
    HKDF(x25519_ss ‖ mlkem_ss) — PQXDH-style, so harvested ciphertexts
    need BOTH X25519 and ML-KEM broken. Emitted whenever the peer's
    heartbeat has an ML-KEM key; v3 otherwise. Identity-key fallback
    (first message to a new contact) stays classical-only. Signatures
    (Ed25519, nostr secp256k1) are still classical — ML-DSA is future
    work; forgery needs a live quantum attacker, unlike decryption.

**Why it matters:** today's static-static x25519 means whoever compromises
a seed once decrypts ALL retained history that any relay still has — and
relays retain indefinitely. The ephemeral-x25519 fix in #1 is partial
forward secrecy (per-message) but not post-compromise security.

**What's needed:** Signal-style X3DH + Double Ratchet. Significant
refactor of crypto.ts; needs careful API design so existing conversations
migrate cleanly. Owner: TBD. ETA: separate sprint.

### #7. WebAuthn-gated session rehydrate  [ROADMAP]

**Why it matters:** the persistent-session blob's non-extractable AES key
blocks `exportKey` but NOT `decrypt`-then-read-plaintext. Any malicious
extension with `<all_urls>`, any XSS, any compromised npm dep can call
`restoreSession()` and lift the seed. My comment in
`persistent-session.ts:18-23` overstates the actual protection.

**Fix:** gate `restoreSession()` on a user-gesture WebAuthn assertion
(touchID / passkey). Background scripts can't fake a user gesture, so the
seed never gets decrypted unattended. Falls back to passphrase on devices
without WebAuthn.

### #8. Rotate addr daily (`info = "v1|YYYYMMDD"`)  [ROADMAP]

**Why it matters:** a relay scrapes `#h` filter values + the public KEZ
directory + builds a rainbow table mapping `addr → primary → handle`. The
hash buys little when the input space is enumerable. Per-day addr
rotation forces the rainbow table to be rebuilt daily and stops long-term
correlation.

**Trade-off:** receivers need to subscribe to multiple addrs during the
boundary day (yesterday's + today's). Listener server-side needs the same.
Migration logic isn't hard but isn't free.

### #9. Unforgeable delivery acks  [DONE — Day 3 Option A]

**Why it matters:** anyone who saw an event id can publish a fake kind-4244
ack. Sender's UI shows false "delivered". Cosmetic-only today; will be a
real problem when someone builds a tracker bot.

**Fix:** ack payload = recipient's ed25519 signature over the acked event
id. Sender verifies against the recipient's known KEZ primary. Free —
already have ed25519 plumbing.

### #10. NIP-65 outbox model  [PARTIAL — Day 3 Option B]

Publish-side only. We now emit a `kind:10002` event on first session
alongside the kind:0 baseline, listing our 3 default relays as
read+write. NIP-65-aware clients can discover where to reach us.

What's still missing: when SENDING to a peer, we should fetch their
`kind:10002` and union their read-relays with ours. v0.2 — needs a
deeper transport refactor (per-message relay set).

We hardcode 3 relays for every user. Real nostr clients publish
`kind:10002` listing their preferred read+write relays; senders publish to
each recipient's published read-relays. Without this, isolated networks
of users on different relay sets can't reach each other.

### #11. NIP-42 AUTH support  [DONE — Day 3 Option B]

damus.io regularly requires NIP-42 AUTH for DM-kind reads. Without it our
subscriptions get rejected silently. Add the client AUTH handshake +
support being prompted by the relay.

### #12. Publish a minimal kind-0 profile on first use  [DONE — Day 3 Option B]

Some relays silently drop writes from "unknown" pubkeys (no kind-0). A
single minimal `kind:0` per derived nostr pubkey (just `{"name":"kez-chat
user"}`) unblocks this without revealing anything.

### #13. NIP-25 ack shape with `["p", senderNostrPubkey]`  [DONE — Day 3 Option B]

Our kind-4244 ack is custom. Adopting the NIP-25 shape gets free interop
with nostr clients that already render reactions — handy if we ever expose
the underlying events.

### #14. Shorten `since=` default cursor  [DONE — Day 3 Option A]

Default 7-day cursor exceeds most relay retention windows (often 1–3
days). Fresh devices on quiet conversations silently miss messages.
Shorten to 48h + augment with explicit "fetch full history" UI for the
rare resurrect case.

### #16. Bounded concurrency on push fanout  [DONE — Day 3 Option A]

**Why it matters:** every send spawns an unbounded `tokio::spawn` to fan
out push. Under flood, OOM.

**Files:**
- `kez-chat/src/messages.rs:128`

**Fix:** semaphore-bound to ~32 concurrent fanouts. Excess queues; under
extreme flood we drop with a warn-log rather than swap-thrash.

---

## Visually-encrypted profile pictures (new feature, in progress)

### Phase 1A — local scramble + per-contact key wrap  [DONE this commit]

- `kez-chat/web/src/lib/visual-crypto.ts` — keyed Fisher-Yates pixel
  permutation + xoshiro256** PRNG. Output is a valid PNG with same
  dimensions, scrambled content. Salt embedded as `#kez-visual-v1:<hex>`
  URL fragment so descramble doesn't need out-of-band metadata.
- `profile-store.ts` — profile gains `encrypted: boolean` (default
  true) + `picture_key` (local-only). On publish: scramble the picture,
  wrap the visual key for each contact via the existing
  `sealMessage()` envelope, embed as `kez_visual_keys` map in the
  kind:0 content.
- Settings — "Visually encrypt picture (recommended)" toggle, default ON.

### Phase 1B — peer descramble  [DONE this commit]

- `peer-profile-store.ts` (new): IDB cache + one-shot `pool.querySync`
  fetch of the peer's kind:0 metadata event. On hit, looks up our
  primary in `kez_visual_keys`, opens the SealedEnvelope wrap to
  recover the visual key, descrambles `metadata.picture`, caches the
  rendered data URL.
- `peer-profile-cell.svelte.ts` (new): reactive Svelte 5 mirror over
  the IDB cache so component re-renders are automatic on fetch.
- `nostr-transport.ts`: surfaces `sender_nostr_pubkey` on every
  inbound DM. `conversations-store.ts` persists it on the conversation
  row so we can locate the peer's kind:0 later.
- `inbox-service.svelte.ts`: on every fresh DM, fires off a profile
  fetch for the sender — first DM lights up their avatar.
- `Messages.svelte`: hydrates the cache on mount, kicks off refreshes
  for every visible conversation, threads cached pictures through
  both Avatar usages (conversation list + thread header).
- Conversation list re-renders on cache update; staleness window 24h.

Edges noted for later: peers we've only *sent* to (never received from)
have no `peer_nostr_pubkey` until they reply, so they don't get a
picture lookup yet. Easy follow-up: backfill pubkey from a NIP-05 or
WebFinger lookup, or proactively probe relays for `kind:0` events whose
content tags match a known primary.

### Phase 1C — UX polish  [TODO]

- "X contacts can see your real picture" hint in Settings.
- Re-publish kind:0 automatically when a new conversation is created
  (so the new contact gets key-wrapped without the user re-saving).
- Optional: per-image AES-CTR mode for uniform-noise output (stronger,
  less "visually meaningful").

---

## Acknowledged trade-offs (won't fix in v0.1)

### Persistent-session is no stronger than the biometric path

The `non-extractable AES key` story stops `exportKey`, NOT
`decrypt`+`read`. Anyone with origin-execution access (XSS, malicious
extension) can lift the seed. Document this honestly in the README and the
file header. Real fix is #7 above.

### 30-day TTL is client-only

`expiresAt` in localStorage is editable by anyone with file-system access.
Server-side device binding (issue a signed nonce on unlock, expire at the
server) would help but adds round-trips. v0.2 candidate.

### Identity-key reuse is safe under current crypto

ed25519 seed → ed25519 (sigchain, envelope sig) + x25519 (ECDH) + HKDF →
secp256k1 (nostr signer). The auditor confirmed: no cross-curve
chosen-message attack path. Standard libsodium pattern.

---

## Tracking + cross-references

- Nostr-protocol review: see commit message of this commit; full report in
  the audit-trail.
- Security audit: ditto.
- Owner: tudisco
- Last updated: 2026-06-08