A multi-day batch covering: a security review punch list (Day 1-3),
the visual-encryption profile-picture feature, a fast deploy
infrastructure, ack resilience + UX polish, several nostr ecosystem
alignment changes, and a key server-independence fix.
Security review (Day 1)
- Envelope v2 (ephemeral x25519 per message; AAD-bound AES-GCM;
no plaintext from/to). Big metadata-leak fix flagged by reviews.
Forward secrecy at the per-message level; v1 decrypt kept for
a one-week migration window.
- Routing tag rename h → q (NIP-29 collision fix).
- Web Push payload now empty (was leaking recipient handle to FCM).
- Log demotion + process-instance salt-hash of handles so debug
logs don't permanently encode the social graph.
Security review (Day 2)
- Replay protection: SEEN_CAP 500 → 10_000 ids; reject events with
impossibly old/future created_at; openMessage enforces ±7d/+5min
freshness on plaintext sent_at.
- Reveal Recovery Phrase now requires a fresh passphrase prompt.
Verifies via the same unlockIdentity that the initial unlock
uses. Bonus: works for biometric-only sessions (recovers the
phrase that wasn't in memory before).
- POST /v1/messages per-IP rate limit (60/min, capacity 60, with
a periodic idle-bucket sweep). New rate_limit.rs module + tests.
Security review (Day 3 Option A)
- Unforgeable acks: kind-4244 events now carry a `kez-sig` tag,
the recipient's ed25519 signature over the acked event id.
Sender verifies against the conversation peer's KEZ primary.
Unsigned acks still accepted during the migration window.
- Default `since=` lookback shortened 7d → 48h (matches relay
retention).
- Bounded concurrency on push fanout: tokio::sync::Semaphore(32).
Security review (Day 3 Option B — nostr ecosystem alignment)
- NIP-65 (kind:10002): publish our relay list so other clients
can discover where to find us.
- NIP-42 AUTH: attachSigner / detachSigner wires the user's seed
into the relay pool so AUTH-gated relays (damus.io DMs) deliver.
- Minimal kind:0 baseline on first session unlock (unblocks
writes on relays that reject unknown pubkeys).
- Acks now include ["p", senderNostrPubkey] for NIP-25 / NIP-10
routing convention.
Web Push end-to-end
- Server-side nostr listener (nostr_listener.rs): the chat-server
subscribes to relays for every registered handle's addr, so
Web Push fires even when chat goes over nostr (the live default).
- Push fanout from messages.rs spawned with bounded concurrency.
- Empty payload (no recipient handle leaked to FCM).
- Self-heal endpoint GET /v1/push/subscriptions/:handle —
auto-re-registers a subscription if server lost it.
- Auto-enable push on first unlock (was opt-in toggle hunt).
- In-chat nudge banner + iOS PWA install hint.
Persistent sessions
- persistent-session.ts: AES-GCM encrypt seed under a
non-extractable IDB key, 30-day sliding-window TTL, restore on
every boot.
- Auto-fetch own kind:0 from nostr on a fresh device so the user
sees their own avatar without re-setting it.
Profile pictures + visual encryption
- Avatar component accepts a `picture` prop (data URL); falls
back to the deterministic identicon when absent.
- profile-store.ts: pick → resize to 256×256 JPEG → save locally
+ publish as NIP-01 kind:0.
- Visual encryption (visual-crypto.ts): keyed Fisher-Yates pixel
permutation + xoshiro256** PRNG. Output is a valid PNG with
scrambled content. Salt embedded as a #kez-visual-v1:<hex>
URL fragment.
- Default ON for new pictures. Strangers see colored noise on
public nostr; contacts see the real face.
- Per-recipient AES wraps embedded in kind:0 content
(kez_visual_keys map). The picture's symmetric key is wrapped
via the same SealedEnvelope crypto our DMs use.
- Self-wrap (sender wraps to their own primary too) so a fresh
device of the same user can descramble its own picture.
- Stranger-view preview thumbnail in Settings (the badge tucked
into the avatar's bottom-right corner — "this is what the
world sees").
- Tap-to-zoom: header avatar in a thread opens a fullscreen
overlay.
Peer-profile resolution
- peer-profile-store.ts: IDB-cached one-shot kind:0 fetch +
descramble.
- peer-profile-cell.svelte.ts: reactive mirror for UI.
- 6h bulk-scan staleness + force-refresh on thread open.
- Avatar usages in Messages.svelte pass peer.picture through.
Local-echo + delivery receipts
- Outbound messages render instantly with status="sending"; flip
to "sent" when ≥1 relay accepts; "delivered" (check-in-circle)
when recipient's client publishes an ack.
- SVG status icons inside the bubble; "via X" footer on outbound.
- Persistent pending-ack queue with retry on next session start.
- Catch-up scan (fetchAcksForEventIds) self-heals delivered
state on conversation open.
- markDeliveredByEventId verifies the ack signature.
Active-relay tracking + reply preference
- SimplePool.trackRelays = true. Capture first-to-accept on send
via Promise.any over per-relay publish promises.
- InboxMessage.via_relay set from pool.seenOn on receive.
- Conversation.peer_via_relay persisted on every inbound DM.
- sendMessage takes `preferRelay` and orders publish targets
accordingly. Acks bias the same way.
- "via relay.X" footer renders on outbound bubbles.
Conversation list polish
- Per-conversation `unread_count` on the Conversation type.
- Bumped on every genuinely-new inbound; reset on thread open.
- Accent-color pill badge in the sidebar (rounds at "99+").
Server-independence fix
- sendMessage skips the /v1/u/:handle lookup when the caller
passes recipientPrimary (which Messages.svelte does, from the
cached peer_primary on the conversation row). Chat over nostr
no longer breaks when the chat-server is down — only brand-new
conversations still need the directory lookup.
Relay set
- Added wss://relay.snort.social and wss://nostr.wine to the
default pool (was 3, now 5).
Fast-deploy infrastructure (new in this batch)
- Dockerfile gains an `export` scratch stage (extracts binary +
web/dist only).
- Dockerfile.runtime: tiny runtime image that COPYs prebuilt
artifacts — no rust/npm on the remote.
- docker-compose.fast.yml: compose override pointing chat-server
build at Dockerfile.runtime.
- .dockerignore: excludes target/, node_modules/, prebuilt/,
.buildx-cache/, .git, *.db. Critical: without this, an earlier
bug had the buildx cache nested under the build context and
blew up to 17GB by feeding itself into itself.
- Old: ~10 min remote build. New: 3–5 min local + 5s remote
runtime swap. Cache lives at ~/.cache/kez-chat-buildx
(outside any project tree).
UI polish (margins, layout, banners)
- Authenticated routes (Welcome / Settings / Identity / Dashboard
/ Claims / AddClaim) wrapped in max-w-2xl mx-auto px-4 py-6.
- WhatsApp-style chat bubbles: shrink-wrap to content, asymmetric
rounded corners, inline bottom-right timestamp.
- Push-notification nudge banner at top of /chats with iOS
install hint.
- Relay state popover off the "● live (N)" indicator.
WebAuthn biometric fix
- user.id now uses the raw 32-byte ed25519 pubkey (was the
72-byte "ed25519:<hex>" identity string, which exceeded
WebAuthn's 64-byte limit — Android Chrome rejected it with
"user handle exceeds 64 bytes").
Documentation
- kez-chat/TODO.md tracks every reviewer finding with status,
file:line references, and a phased plan. All Day 1-3 items
marked DONE; remaining roadmap items (Double Ratchet,
WebAuthn-gated rehydrate, addr rotation, NIP-65 peer-relay
fetch on send) documented for future sprints.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
First real UI for kez-chat. Served by the chat-server as static
files; uses the same HTTP API a native client would (dogfoods the
contract).
Stack: Svelte 5 + TypeScript + Vite + Tailwind 4 + @noble/curves +
@scure/base + canonicalize + idb-keyval + svelte-spa-router.
Bundle: 113 KB JS / 14 KB CSS (gzip: 42 KB / 4 KB).
Pages (all behind hash routing):
/ Landing — sign up or restore from seed
/create Account creation flow:
1. Pick handle, set passphrase
2. Show seed for paper backup, require ack
3. Confirm
4. POST /v1/register, save passphrase-encrypted seed
to IndexedDB
/restore Stub for restore-from-seed (v0.2: needs
GET /v1/by-primary endpoint on the server)
/unlock Enter passphrase to derive the AES-GCM key,
decrypt the seed, populate session state
/dashboard Show handle, primary, registered_at, sigchain URL
/claims List locally-cached claims (with publication status)
/claims/add Add-a-claim wizard:
1. Pick channel (github/dns/web/nostr/bluesky/ap)
2. Enter identifier
3. SignedClaimEnvelope built + signed in-browser
using Ed25519 + JCS, matching the spec exactly
4. Show channel-appropriate publish instructions +
copyable markdown or JSON artifact
5. User marks it published (purely a local note —
actual verification is the verifier's job)
Crypto / KEZ helpers (src/lib/kez.ts):
- generateIdentity / identityFromSeed (32-byte Ed25519)
- canonicalBytes (RFC 8785 JCS via the `canonicalize` package — same
one our Node port uses; produces byte-identical output to Rust)
- signClaim, signRegistration (build envelopes; sign with
ed25519-sha512-jcs; same alg / key / sig shape as kez-core)
- toPrettyJson, toMarkdown (the same wire encodings the CLI emits)
Key storage (src/lib/identity-store.ts):
- IndexedDB via idb-keyval
- Seed encrypted under user passphrase: PBKDF2-SHA256
(600,000 iterations, OWASP 2024 guidance) → AES-GCM-256
- Documented limitation: browsers don't have an OS-keychain
equivalent. Native clients (future CLI/Tauri) will use the OS
keychain for better protection.
Bundle includes:
- Workaround for TS 5.6+ Uint8Array<ArrayBufferLike> vs ArrayBuffer
strictness (small asBuffer() helper that copies into a plain
ArrayBuffer for WebCrypto + Response calls).
Dockerfile updated: now multi-stage with a Node `webbuild` stage
that runs `npm run build` before the Rust binary stage. SPA dist
is copied into the runtime image at /app/web; chat-server's
KEZ_CHAT_WEB_DIR points at it so the SPA is served at /.
What works against the LIVE deployment right now (https://kez.lat):
- Open https://kez.lat → SPA loads (113 KB JS, 14 KB CSS)
- Create account → key gen happens in browser, seed shown for
backup, encrypted under passphrase, POSTed to /v1/register
- Dashboard → shows registered handle + primary + sigchain URL
- Claims wizard → sign for any of the 6 channels, get publish
instructions + the right wire format to copy
- Lock / unlock — passphrase-derived AES-GCM, no roundtrips
What's still TODO (v0.2):
- Restore-from-seed: needs GET /v1/by-primary on the server so the
SPA can discover the handle from a seed
- Actual NATS chat: needs server's auth callout (currently 501) +
nats.ws client (browser side; package is in deps but not used yet)
- Sigchain integration: append `add` event when user publishes a
claim, upload to sig-server (needs sig.kez.lat tunnel)
- Verification: in-browser channel fetches (some channels are
CORS-friendly, others need a server-side proxy)
- Compact (kez:z1:) form: the spec uses zstd, browsers don't have
native zstd CompressionStream support yet. Workaround in code
uses deflate-raw with a `kez:zd1:` prefix to make it obvious the
output isn't spec-compliant; replace with @bokuweb/zstd-wasm or
similar when we need true compact form in the SPA.
The auth_callout block required a real account nkey for the issuer
field and we don't have one yet — chat-server's callout endpoint is
a 501 stub for v0.1 anyway. NATS was crash-looping on startup
rejecting the placeholder nkey:
Expected callout user to be a valid public account nkey,
got "ABACVOI4POPS3SBFLDQYTQHHHACRVMCM2HK7PXX4UTI7XYWQHQGOA3PX"
Commented the block out with clear notes on how to re-enable in
v0.2 once we run `nsc generate nkey` for real issuer + user keys.
In v0.1 NATS runs with no auth, which is fine because:
- the deployment is behind a Cloudflare tunnel (not directly
internet-exposed)
- no KEZ client exists yet to connect
- even if one did, the chat-server's callout endpoint is a stub
Deployment verified live at tudisco@10.5.2.5:
chat-server :6969 → {"server":"kez.lat","status":"ok","version":"0.1.0"}
sig-server :7878 → {"status":"ok"}
nats :4222 → INFO frame, v2.14.1, JetStream on
:8222 → /varz monitoring
:8443 → WebSocket transport for browser SPA
deploy.sh has tudisco@10.5.2.5 + /home/tudisco/kez-chat baked into
its defaults — it's a personal deploy script, not a generic project
artifact. Same goes for any future *.local.sh / .env / .env.local
files in kez-chat/deploy/.
What stays in git:
- Dockerfile / Dockerfile.sig-server (project infrastructure)
- docker-compose.yml (project infrastructure)
- nats.conf (project infrastructure)
- install-docker.sh (generic Ubuntu setup, no
host-specific info)
What's now gitignored:
- deploy.sh (personal — kept locally)
- *.local.sh (any other personal scripts)
- .env / .env.local (any local config)
Two helper scripts in kez-chat/deploy/ so deployment is one command
once SSH access is set up:
- install-docker.sh — run once on a fresh Ubuntu host. Installs
Docker Engine + Compose plugin from Docker's apt repo, adds the
current user to the docker group, enables the systemd unit.
Idempotent (safe to re-run).
- deploy.sh — run from a workstation. Rsyncs the three subdirs we
need (rust/, kez-chat/, rust-sig-server/) to the target host,
excludes build artifacts (target/, node_modules/, *.db), then
SSHes in to run docker compose up -d --build, waits for the
chat-server healthcheck.
Defaults match what we agreed:
host = tudisco@10.5.2.5
path = /home/tudisco/kez-chat
server domain = kez.lat
Overridable via flags or env vars.
First runnable kez-chat-server binary plus its docker-compose deploy
recipe. Implements steps 2-3 of the document.md sequenced plan; the
rust-lib refactor (step 1) is deferred — chat-server path-deps on
rust/crates/kez-core for now, which works and matches what
rust-sig-server already does.
What's in this commit:
kez-core (1-line change)
- New public `verify_envelope<T>(payload, signature)` helper that
dispatches Schnorr / Ed25519 / future suites by signature.alg.
Used by chat-server's registration verifier; downstream value
beyond chat-server too.
kez-chat-server (new crate)
- src/main.rs: tokio + axum + tracing entry; clap config; graceful
Ctrl-C shutdown.
- src/lib.rs: re-exports so tests can drive the same router.
- src/config.rs: env/flag config (bind, db, server, sig_server_url,
web_dir) with defaults sane for both dev and prod.
- src/error.rs: typed ApiError → structured JSON responses with
stable error codes.
- src/store.rs: SQLite-backed handle registry, UNIQUE on both
(handle) and (primary_id); race-safe via SQL primary key.
- src/handles.rs: username validation (length, charset, reserved
list, must start with letter/digit).
- src/registration.rs: SignedRegistration envelope sharing KEZ's
JCS canonical-bytes pattern; signature verification via the new
kez-core helper; replay protection via ±5-minute clock skew check.
- src/api.rs: all six routes in one file —
GET /v1/healthz
GET /v1/u/:handle
POST /v1/register
GET /.well-known/webfinger
POST /internal/nats/auth (501 stub for v0.1; wired up in v0.2)
GET / (placeholder HTML; ServeDir when web/dist exists)
tests/http.rs — 13 integration tests
- Stands up the real router on a random port; uses reqwest.
- Coverage: healthz, lookup-404, full register→lookup round-trip,
duplicate-handle conflict, wrong-server rejection, reserved-name
rejection, tampered-signature rejection, stale-timestamp rejection,
WebFinger success + wrong-server-404, placeholder SPA renders,
NATS callout 501, JCS determinism sanity.
deploy/
- Dockerfile: multi-stage build (rust:1.86-slim → debian:bookworm-slim).
Build context is repo root so the path dep on kez-core resolves.
Runtime image ~50 MB; runs as non-root uid 10001.
- Dockerfile.sig-server: same pattern for the existing
rust-sig-server, so the stack builds from one git pull.
- docker-compose.yml: three services (chat-server + nats + sig-server)
with named volumes for persistence. Ports: 6969 (chat HTTP),
4222/8443/8222 (NATS native/ws/monitoring), 7878 (sig-server).
- nats.conf: WebSocket on 8443 for the browser SPA, JetStream
enabled, auth_callout pointing at chat-server's
/internal/nats/auth endpoint (issuer nkey is a placeholder — must
be replaced with a real one before going live).
README.md
- Documents all endpoints with example bodies.
- Quick-start for both local dev and full Docker compose.
- Honest list of what's in v0.1 vs what's still stubbed.
Smoke-tested running on 127.0.0.1:6969:
GET /v1/healthz → {"server":"kez.lat","status":"ok","version":"0.1.0"}
GET / → placeholder HTML rendering
GET /v1/u/ghost → 404
POST /internal/nats/auth → 501 with "wired up in v0.2"
cargo test → 13 passed.
cargo build --release → 19.6s, clean.
Tudisco
