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`](document.md). Spec for the underlying KEZ
identity layer in [`../SPEC.md`](../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)

```sh
# 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)

```sh
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

```sh
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`

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

### `GET /v1/u/:handle`

Returns:

```json
{
  "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:

```json
{
  "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`](../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.