Kez/kez-chat/README.md

kez-chat-server

Home server for the kez-chat application. One Rust binary that hosts:

• Handle registry (POST /v1/register, GET /v1/u/:handle)
• WebFinger discovery (GET /.well-known/webfinger)
• NATS auth callout endpoint (POST /internal/nats/auth) — stub in v0.1
• Static SPA serving (GET /) — placeholder until the Svelte build lands
• Healthz (GET /v1/healthz)

Designed in document.md. Spec for the underlying KEZ identity layer in ../SPEC.md.

What's in v0.1 (this is the scaffold)

✅ HTTP API end-to-end ✅ Ed25519-signed handle registration with replay protection ✅ SQLite-backed registry with uniqueness on both handle and primary key ✅ WebFinger endpoint ✅ Placeholder SPA at / ✅ docker-compose for full stack (chat + nats + sig-server) ✅ Multi-stage Dockerfiles ✅ 13 integration tests against a live router

⚠️ NATS auth callout returns 501 — wired up in v0.2 ⚠️ Svelte SPA build pipeline not yet in place — placeholder HTML for now ⚠️ TLS terminated upstream (no cert handling in this binary)

Quick start (local development)

# Run from source
cargo run -- --bind 127.0.0.1:6969 --db ./kez-chat.db --server kez.lat

# Or install once
cargo install --path .
kez-chat-server --bind 127.0.0.1:6969 --server kez.lat

Configuration via flags or env vars:

Flag	Env	Default
--bind	KEZ_CHAT_BIND	0.0.0.0:6969
--db	KEZ_CHAT_DB	kez-chat.db
--server	KEZ_CHAT_SERVER	kez.lat
--sig-server-url	KEZ_CHAT_SIG_SERVER_URL	http://localhost:7878
--web-dir	KEZ_CHAT_WEB_DIR	(unset → placeholder page)

Logging: RUST_LOG=debug,hyper=info etc.

Quick start (Docker compose, full stack)

cd deploy
docker compose up -d --build

Brings up three services:

Service	Port(s)	What it does
chat-server	6969	HTTP API + SPA
nats	4222 (native), 8443 (WebSocket), 8222 (monitoring)	Dumb broker, JetStream enabled
sig-server	7878	Sigchain storage (the existing rust-sig-server)

Then point a reverse proxy / Cloudflare tunnel at localhost:6969.

Testing

cargo test                       # 13 integration tests (real server, real HTTP)

The tests stand up the router on a random local port and exercise it via reqwest. No mocks. They cover: healthz, lookup, registration (success + duplicate + wrong-server + reserved-name + tampered-sig + stale-timestamp), WebFinger, the placeholder SPA, and the NATS auth callout stub.

Endpoints in detail

GET /v1/healthz

{ "status": "ok", "server": "kez.lat", "version": "0.1.0" }

GET /v1/u/:handle

Returns:

{
  "handle": "tudisco",
  "fqhn": "tudisco@kez.lat",
  "primary": "ed25519:2152f8d19b...",
  "sigchain_url": "https://sig.kez.lat/v1/sigchains/ed25519/2152f8d19b...",
  "registered_at": "2026-05-25T03:00:00Z"
}

Returns 404 if the handle isn't registered.

POST /v1/register

Request body — a signed registration envelope:

{
  "kez": "handle_registration",
  "payload": {
    "type": "kez.chat.handle_registration",
    "version": 1,
    "handle": "tudisco",
    "primary": "ed25519:2152f8d19b...",
    "server": "kez.lat",
    "created_at": "2026-05-25T03:00:00Z"
  },
  "signature": {
    "alg": "ed25519-sha512-jcs",
    "key": "ed25519:2152f8d19b...",
    "sig": "<128-char-hex>"
  }
}

Server validates:

1. Envelope tag is "handle_registration"
2. Payload type is "kez.chat.handle_registration", version 1
3. signature.key equals payload.primary
4. Signature verifies against the primary key (Ed25519 only for chat)
5. payload.server matches this server's configured domain
6. payload.handle passes validation (length 3-32, a-z0-9_-, starts with letter/digit, not in reserved list)
7. payload.created_at is within 5 minutes of server time

On success: 201 Created with the same body as GET /v1/u/:handle.

GET /.well-known/webfinger?resource=acct:user@server

Standard fediverse-style discovery. Returns the user's KEZ identity info as a WebFinger JRD. Used by other servers (federated lookup, future) and by tools like fediverse browsers.

POST /internal/nats/auth

NATS auth callout endpoint. Stub in v0.1 — returns 501. The real implementation (v0.2) will: parse the NATS auth request JWT, extract the connecting client's nkey, look up the corresponding handle, sign a response permitting kez.inbox.<pubkey>.> subjects.

Deployment notes

• The chat-server Docker image is built from the repo root as context (so it can copy rust/crates/kez-core for the path dep). docker-compose.yml sets this correctly.
• The sig-server is the existing ../rust-sig-server binary, built into a separate image via Dockerfile.sig-server.
• NATS config (nats.conf) has WebSocket enabled on port 8443 so the browser SPA can connect via nats.ws. The issuer field in auth_callout is a placeholder — generate a real nkey and replace before going to production.
• TLS is not handled by this binary. Put a reverse proxy (Caddy, nginx, Cloudflare tunnel) in front for HTTPS.

License

Dual-licensed under MIT or Apache-2.0.