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 with presence and private messages, threaded public news, a virtual file tree with drop boxes, in-app account and role administration, 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: a thin top menubar (brand + connection chip) over an open desktop, plus a vertical Button Bar — itself a floating, draggable window sized to its content — that launches all 14 feature windows. Windows are lazily built on first open, are resizable and rememeber their geometry, can be minimized to a bottom-left dock, and support a per-window "Keep on Top" toggle. F1 opens a window switcher; Ctrl/Cmd+W closes the focused window.

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

Both / and \ are accepted as the command prefix. New in v0.2: /away, /back, /afk, /clear, /help — plus right-click on any member for Send Message or Get Info, which opens the Messages or User Info window.

/name and /desc are recognized but stubbed — see Gaps & next steps.

Files window

A path bar with Up / New Folder / Refresh / Upload controls over a filterable 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. Right-click a row for Download / Delete / Copy name / Get Info (Delete needs FILE_DELETE).

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.

User List & User Info

User List is server-wide, not room-scoped — every logged-in session, anywhere on the server, with a class-colored bar per row, idle time, and a filter box. Click a row to open User Info (class, login time, idle duration, IP address); right-click for Send Message, Get Info, or Disconnect (needs USER_KICK).

Presence is pushed live: the presence event fires on every login/logout server-wide, so the list updates incrementally without a manual refresh.

Messages window

Classic two-pane private messaging: a conversation list on the left (unread ones highlighted red), the selected thread and an input line on the right. Sending echoes the message back into your own conversation so the sent line appears immediately. An incoming private message while the window is closed or on another conversation opens/updates it and lights the Button Bar's Messages LED.

Public News window

A three-pane newsreader: newsgroups on the left, the selected group's posts (threaded by reply depth) in the center, the selected post's full text on the right. New Message starts a thread, Reply nests under the open post; the author (or an admin) can delete a post, which removes it from the list for everyone.

Administration window

Three panels behind one Discord-shaped model: custom roles (name, sort rank, color swatch, a checkbox grid of privileges), a role-assignment panel (assign/unassign a role to a username, or look up a user's current roles), and a Disconnect panel (username, optional reason, and a ban duration — none, 5m, 1h, 1 day, 1 week, 1 year). Every action here needs USER_ADMIN (roles) or USER_KICK/USER_BAN (disconnect).

Accounts window

Closes the old "accounts only via CLI" gap. Lists every account with its base class and a summary of privilege overrides; Create takes a username, password, and base class; Edit changes the class and lets you flip each privilege to inherit / grant / revoke independent of role assignment. Password is only set at creation — there's no in-app reset yet. Needs USER_ADMIN.

Address Book, Trackers, Settings & About

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". 33 commands total, up from 11 in v0.1.

Session & chat

Presence & tracker

Files & transfers

Roles & accounts USER_ADMIN

Public news

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.

packet_type ranges (v0.2)

The original four ranges (handshake / auth / file / chat) are unchanged; presence, private messages, roles/accounts, and news each claimed a new range as they were wired in:

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; custom roles and per-account overrides can grant beyond or revoke from the class (see Roles & overrides).

The underlying bitflags, from kdx-server-core/src/auth/classes.rs:

CHAT_SEND        = 1 << 0
CHAT_PRIVATE     = 1 << 1
CHAT_CREATE_ROOM = 1 << 2
CHAT_SET_TOPIC   = 1 << 3
FILE_LIST        = 1 << 4
FILE_DOWNLOAD    = 1 << 5
FILE_UPLOAD      = 1 << 6
FILE_DELETE      = 1 << 7
FILE_MANAGE_TREE = 1 << 8   // create/remove folders, dropboxes
USER_KICK        = 1 << 16
USER_BAN         = 1 << 17
USER_ADMIN       = 1 << 18  // create/edit accounts, manage roles
SERVER_ADMIN     = 1 << 19  // config, shutdown

Roles & overrides

On top of the four base classes, P3 added a Discord-shaped custom-role layer: a SysOp defines named roles (with a sort rank and a color) as arbitrary privilege bundles, and assigns any number of them to an account. Independently, each account can carry per-privilege grant/revoke bits that apply on top of everything else.

This is exactly what the Administration and Accounts windows edit: roles are the reusable bundle, account overrides are the one-off exception.

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.

Private messaging

Closes the v0.1 gap where CHAT_PRIVATE existed but wasn't wired end to end. send_private(to, text) sends a PrivateSend (0x40) packet; the server delivers a PrivateMessage (0x41) to every one of the recipient's sessions and echoes it back to every one of the sender's own sessions, so a user logged in twice sees the same conversation on both.

There's no persistence yet — a message not received live (recipient offline) is simply not delivered; there's no mailbox or history replay.

News & threading

Newsgroups and posts persist in SQLite (kdx-storage/src/news.rs), with domain logic in kdx-server-core/src/news.rs. A post is a root (empty parent_id) or a reply nested under any existing post in the same group; the server returns the whole group as a flat list and the client threads it by walking parent_id and indenting by depth.

Access is per-group, not per-post: min_read_class gates list_thread, min_post_class gates create_post. Deleting a post is restricted to its author or an admin (USER_ADMIN) — there's no edit, only delete-and-repost.

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 — 162 tests (up from 107), 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.
• Presence & messaging — server-wide login/logout fan-out, private message delivery + sender echo.
• Roles & accounts — effective-privilege resolution (base ∪ roles ∪ grants − revokes), CRUD round-trips.
• News — newsgroup creation, threaded post/reply, per-class read/post gating, delete authorization.
• 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

• Postgres — persistence is SQLite; a Postgres swap is confined to kdx-storage.
• No PM history — private messages aren't persisted; a message to an offline user is simply not delivered, there's no mailbox or replay.
• No password reset UI — Accounts sets a password only at creation; changing an existing account's password still needs direct DB access.
• File manager — no drag-drop and no batch upload/download; the resumable-chunk plumbing exists but the UI never surfaces a partial-download resume prompt.
• 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.