KDX Client & Server

A from-scratch Rust rebuild of KDX — an early-2000s Hotline-style chat and file-sharing system. A custom binary protocol over TLS 1.3, a challenge-response login where the password never leaves the machine, chat rooms, a virtual file tree with drop boxes, and resumable chunked transfers both directions. The client is a Tauri desktop app in the classic black / blood-red / phosphor-green aesthetic.

This document is the reference for what the interface does and how each feature works underneath. Read the interface sections to operate the app; read "Under the hood" to understand or extend the machinery each window drives.

System map

Every user action follows one path: the webview calls a Tauri command, the command forwards to the async client library, which frames the request and writes it to the TLS socket. Server pushes travel back the same channels as events.

The desktop

The client is a single OS window hosting a desktop metaphor: four draggable, focusable panels rendered in the webview, not separate OS windows. A menu bar across the top focuses (and un-hides) each panel; a footer shows connection state. Click a title bar to drag; click anywhere in a panel to bring it forward.

Connect window

The entry point. Enter server host, port, and account, then Authenticate. The window remembers your last host / port / username via local storage, and stays available after login so it doubles as the reconnect surface.

Trust-on-first-use prompt

KDX pins server certificates SSH-style. The first time you reach a server, or any time its key changes, the connect step is refused and an inline prompt shows the certificate fingerprint for you to verify out-of-band before trusting it.

Chat window

A topic bar, a scrolling message stream, a live user list, and an input line. The title-bar tag shows the current member count.

Message line types

• normal — <sender> text, phosphor green, sender highlighted.
• action — /me messages, italic, *** sender text.
• system — join/leave and server notices, dim italic (clients can't forge these).
• warning — flood control and advisories, amber.
• error — server error frames, red.

Input commands

Files window

A path bar with Up / Refresh / Upload controls over a directory listing. Each row shows a kind tag and — for files — a size. Clicking a folder navigates in; clicking a file opens a native save dialog and downloads it. Uploading opens a native file picker and sends into the current directory.

Transfers window

One card per active transfer, each with a live chunk-bitmap grid: every cell is one chunk, lighting up phosphor-green as it is sent (upload) or received and hash-verified (download). The card shows direction (↑/↓), percent, and done/total chunks; on completion it flips to verified ✓ or a failure message.

The bitmap is driven directly by the transfer_progress event's bitmap field, so what you see is the actual resume state — the same bytes persisted for resuming an interrupted transfer.

Command reference

The webview calls these via __TAURI__.core.invoke. Each is a thin async forward into kdx-client-core; none holds business logic. Errors return a tagged object — kind: "untrusted_certificate" (with host, port, fingerprint, previous) drives the TOFU prompt, everything else is kind: "message".

Event stream

The server's pushes and transfer progress arrive on one channel. kdx-client-core emits a typed Event; the Tauri shell forwards each as a "kdx" webview event whose payload is tagged by type (snake_case). The UI switches on that tag.

Protocol & framing

Every message is a length-framed packet. The header is a fixed 20 bytes, all multi-byte fields big-endian:

// 20-byte header
magic       4  b"KDX\0"
version     1
packet_type 1  handshake / auth / file / chat / system ranges
flags       2  bitfield incl. fragmented, more-fragments
sequence    4  per-connection monotonic
length      4  payload bytes (u32)
reserved    2
checksum    2  CRC32C-folded — framing guard, not security

• Fragmentation — payloads over a 16 KB frame cap (a file chunk, say) split across frames flagged FRAGMENTED / MORE_FRAGMENTS and reassemble on the far side, guarded by a size cap and timeout.
• Integrity comes from TLS and per-chunk SHA-256 — the header checksum only catches framing corruption.

Auth & trust

Challenge-response login

The server stores only an Argon2id hash. To log in, the client receives a one-time random challenge plus the account's salt and cost parameters, recomputes the Argon2 verifier locally, and answers with SHA-256(challenge ‖ verifier). The server compares in constant time. The password never crosses the wire — not even inside TLS — and a captured answer is useless because each login gets a fresh challenge. Unknown usernames still get a plausible decoy challenge, so the wire can't distinguish "no such user" from "wrong password."

Trust-on-first-use

The client pins the SHA-256 of the server's certificate per host:port in known_hosts.toml. An unknown or changed key fails the TLS handshake; the library surfaces the observed fingerprint (and any previous one) so the UI can prompt. This is the desktop-app answer to self-signed and rotating server certs without a CA.

Chat & user classes

Each chat room is its own actor task owning its membership, topic, and per-member flood gate — broadcasting a message is N channel sends with no shared lock on the hot path. A token-bucket flood gate (burst 5, refill 1/s) throttles a spammer with a server_warning. Clients cannot forge system-flagged messages.

Classes & privileges

Four base classes with strictly-increasing privilege sets; per-account overrides can grant beyond or revoke from the class.

Files & ACLs

The file tree is loaded from SQLite into memory (read-heavy, write-rare) and written through on mutation. Every folder carries a minimum-class-to-read and minimum-class-to-write. File bytes live on the filesystem, never in the database.

• Drop boxes reject listing and reading structurally — the check sits in the ACL layer and fires for every caller regardless of class, so write-only is a property of the node, not a convention.
• Downloads resolve the file through the same read-ACL path, so a file inside a drop box can be uploaded but never downloaded.

Transfers & resume

Files move in 32 KB chunks, each carrying its own SHA-256; the whole file is SHA-256-verified before it's accepted. Both directions are throttled by a token bucket and support resume — the difference is who remembers what:

The chunk grid in the Transfers window is a direct view of this bitmap — the visualization and the resume mechanism are the same bytes.

Running it

Server

# create an account: guest | user | power | admin
cargo run -p kdxd -- useradd phraq s3cret power

# start it (defaults to 0.0.0.0:10700, self-signed dev cert)
cargo run -p kdxd

Client

cargo run -p kdx-client

The window opens; enter host 127.0.0.1, port 10700, your account, and Authenticate. Accept the TOFU fingerprint on first contact. No Node toolchain is needed — the bundled frontend is served directly.

Verification

The whole stack runs green under cargo test --workspace — 107 tests, no external services. The client library is tested headlessly against a real in-process kdxd (real TLS over 127.0.0.1), and the server's own tests are an independent second implementation of the wire flows.

• Protocol — codec round-trips, checksum corruption, fragment reassembly.
• Crypto — Argon2 verify, challenge round-trip, replay rejection.
• End-to-end — login, chat both directions, uploads/downloads with kill-and-resume in both directions, DropBox refusal, throttle pacing.
• Cross-process smoke — cargo run -p kdx-client-core --example smoke drives a separately-running kdxd: TOFU-pin → login → join → chat → list, over a real socket.

Gaps & next steps

• Private messaging — the CHAT_PRIVATE privilege exists but direct messages aren't wired end to end yet.
• Multi-room UI — the client fixes on #lobby; the protocol supports many rooms, so a room switcher is a UI-only addition.
• Postgres — persistence is SQLite; a Postgres swap is confined to kdx-storage.
• GUI manual smoke — the desktop window itself is verified by hand (cargo run -p kdx-client); every layer it wraps is covered by automated tests.