Huddle

End-to-end-encrypted chat rooms over Tor — as a native desktop app (huddle-gui, egui/eframe) or a terminal UI (huddle). Both drive the same core, identity, and relay.

Open either client, start a room or paste an invite, and chat. Rooms can be public (cleartext payloads) or encrypted (per-sender Megolm group sessions, session keys wrapped with an Argon2id-derived passphrase key). Either way the transport is end-to-end: the relay only ever sees ciphertext.

huddle 1.0 runs LAN discovery and the relay together by default — no mode switch. Friends on the same network connect directly over libp2p (mDNS); everyone else is reached through a self-hostable relay (crates/huddle-server). Each message rides whichever path reaches the peer, and the per-chat header shows which (via lan / via relay). The relay is a dumb encrypted router + offline mailbox — it never holds keys and never decrypts.

The relay has several "doors", each a different anti-censorship tradeoff (run huddle transports to see them): a Tor v3 onion via your system Tor (most private, the default); the same onion via a private obfs4/WebTunnel bridge (for networks that block Tor); an in-process Arti onion (with --features arti); and clearnet ws:///wss:// straight to a raw IP (fast, for VPN users or where Tor is fully blocked — the relay sees your IP, but messages stay end-to-end encrypted). The same huddle-server process can be exposed as an onion and on a public IP at once, so all doors share one set of rooms + mailboxes. Pick a door with --transport <id>, set an order with --transport-order, or point at a clearnet relay with --clearnet-server ws://<ip>:<port>/ws.

As of 1.1, huddle also ships with the operator's clearnet relay baked in (a cloudflared wss:// tunnel onto the very same rooms + mailboxes), so a client that can't reach Tor connects with zero config. It's tried only after the onion, so a Tor user never touches it; --clearnet-server, clearnet_url in config.toml, or Settings → Network override it.

Contacts are a durable, fingerprint-keyed address book — keyed by identity, not by an ephemeral LAN address — so a conversation keeps working after a peer leaves the LAN. a adds a contact by HD-ID; over the relay this reaches them across the internet (live or via the mailbox), and they accept from the Contacts pane to open a DM. DMs persist across restarts and keep flowing over the relay.

Don't want to read out a 24-character HD-ID? As of 1.2.1 you can add a contact by a short connect code instead: generate an 8-character code (valid 5 minutes) — G in the terminal UI, or Generate a code to share in the desktop app's add-contact dialog — and the other person types it into their own "add a contact" box. The relay resolves the code to your identity and sends the request; the code grants nothing on its own and expires quickly. (The desktop app's About window — Settings → Account → About — links back to this repo.)

Tor is optional now. LAN works with no Tor at all, and a clearnet relay door needs no Tor either. The onion doors do need a local Tor daemon (SOCKS5 on 127.0.0.1:9050; override with --tor-socks). On Debian/Ubuntu: apt install tor && systemctl enable --now tor. If Tor is down, huddle falls through to the next available door.

This is a learning project, not production-audited chat. SQLCipher protects the database at rest under your master passphrase, Megolm sessions are persisted with an Argon2id-derived key, file bytes use ChaCha20-Poly1305, and SAS contact verification ships in v0.3 — but the protocol has not been audited and threat-modelling work is ongoing. Don't rely on it for real secrets without a careful review.

Install

huddle ships three binaries — install whichever you need:

• huddle-gui — the native desktop app (egui/eframe). Start here if you want a windowed client.
• huddle — the terminal UI (TUI).
• huddle-server — the relay + offline mailbox (only if you're hosting one; see Run your own relay).

From crates.io

With a stable Rust toolchain (edition 2021, 1.75+):

cargo install huddle-gui      # native desktop GUI
cargo install huddle          # terminal client
cargo install huddle-server   # relay (host-side only)

The binaries land in ~/.cargo/bin/ (make sure it's on your PATH), then launch the GUI with huddle-gui or the terminal client with huddle.

System prerequisites

You need the Rust toolchain and a C toolchain (the bundled SQLCipher compiles a vendored OpenSSL from source). Beyond that:

• macOS — just the Xcode Command Line Tools: xcode-select --install.

• Windows — the MSVC "C++ build tools" that rustup already prompts for. No extra SDK; the GUI uses the native file dialogs.

• Linux — a normal graphical desktop already has the runtime libraries the GUI needs (X11/Wayland + OpenGL). On a minimal or headless box, install the build/runtime deps:

  sudo apt-get install -y build-essential pkg-config perl \
    libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev
  

  No GTK required. huddle-gui's file dialogs go through the XDG desktop portal (rfd's default xdg-portal backend), so libgtk-3-dev is not needed — only a portal backend at runtime (standard on GNOME/KDE). Add libclang-dev only if a dependency's build complains about libclang.

Build from source

git clone https://github.com/richer-richard/huddle
cd huddle
cargo build --release
./target/release/huddle-gui     # desktop GUI
./target/release/huddle         # terminal client

huddle app — build, install & launch the GUI in one step

From a source clone, the terminal client doubles as an installer for the desktop app:

huddle app

This builds huddle-gui in release mode and installs it where your OS keeps desktop apps, then launches it:

• macOS — assembles Huddle.app in /Applications (falling back to ~/Applications if that isn't writable).
• Linux (Ubuntu / Debian / Kali / …) — copies the binary to ~/.local/bin and adds a huddle.desktop launcher to your app menu.
• Windows — installs to %LOCALAPPDATA%\Programs\Huddle with a Start-Menu shortcut.

Once the app is installed, huddle app reclaims the build cache for you — it runs cargo clean so the multi-gigabyte target/ from the release build doesn't linger (the app binary is already copied to its OS location, so this is safe). Pass HUDDLE_KEEP_BUILD=1 to keep the cache if you plan to keep building from the clone.

Plain huddle (no subcommand) still opens the terminal UI. Run huddle app from inside the repo, or point it at a clone with HUDDLE_SRC=/path/to/huddle huddle app.

Running the desktop GUI

Launch huddle-gui. On first run it walks you through a one-time signup: choose a username and a master passphrase (used to derive the at-rest encryption key for your local database — Argon2id, 64 MiB), then confirm it. Every later launch just asks for that passphrase to unlock. Pass --no-master-passphrase to run with an unencrypted database and skip the unlock screen.

The GUI takes the same transport flags as the TUI — e.g. huddle-gui --clearnet-server wss://host/ws to pin a clearnet relay, plus --server / --no-server, --tor-socks, --transport / --transport-order, --mode mdns (also run LAN discovery), and --name. Run huddle-gui doctor to print version + paths for a bug report. Your config and data live in the per-OS app directory:

OS	Location
Linux	~/.local/share/huddle/ (config: ~/.config/huddle/config.toml)
macOS	~/Library/Application Support/huddle/
Windows	%APPDATA%\huddle\

How it works (high level)

1. Launch — your Ed25519 identity loads (or generates) from disk silently. The TUI opens on the Welcome pane with the sidebar on the left. huddle connects to the Tor onion relay in the background (the relay dot ● next to your name turns solid once the link is up). With --mode mdns/--mode direct a libp2p swarm also starts for LAN discovery / direct dial alongside the relay.
2. First launch only — a versioned onboarding card explains huddle's leaderless model (rooms outlive the creator), the master passphrase vs room passphrase distinction, the sidebar layout, and the new keybindings.
3. Direct messages — press m, type a partner's HD-ID or username, hit Enter. The DM appears in the Direct messages section of the sidebar on both peers. DMs are end-to-end encrypted on the room layer via an ECDH derivation between the two parties' identity keys (huddle 0.7.1+).
4. Group rooms — press g to create a multi-peer room. Pick a name, choose public or encrypted (and a passphrase if encrypted). You become the room's first owner; only owners can kick, grant moderation, or rotate the room key. Discovered rooms you haven't joined appear under the Discover sub-row in the sidebar.
5. Inbound dial gate — if someone you don't know dials you, the TUI raises an Accept / Reject / Trust+Accept modal. The peer isn't added to your gossipsub mesh until you decide.
6. Chat, verify, moderate — see the Key bindings tables for SAS verification (Ctrl+V → s), kick (Ctrl+K), grant owner (Ctrl+G), invite links (Shift+I), join codes (Ctrl+J / c), and verified-only-mode toggles (Settings pane, o per room).

TUI layout

+----------------------------------------------------------------------+
| huddle 2.0.6  ·  745e-fe8a-…  ·  relay ●               12:34 UTC     |
+------------------------+---------------------------------------------+
| ▾ Profile              | # general                                   |
|   alice  HD-AAAA-…  ●  |   4 members · encrypted                     |
| ▾ Direct messages  (2) |                                             |
|   ● bob       1m   (1) |   12:32  bob          hey                   |
|   ○ dave       offline |   12:33  carol  ✓     same here              |
| ▾ Group rooms      (1) |   12:34  you          looks good            |
|   # general  4  E      |                                             |
|   + Discover (2)       |                                             |
| ▾ People               |                                             |
|   eve  HD-EEEE-…  ✓    |   > _                                       |
| ▸ Activity             |                                             |
| ▸ Settings             |                                             |
+------------------------+---------------------------------------------+
| ?help  /type  ^V verify  ^F search  ^A attach  ^L leave  ^I members  |
+----------------------------------------------------------------------+

Six sidebar sections, top-to-bottom: Profile (you), Direct messages, Group rooms (with a Discover row), People (known + verified + blocked), Activity (status history + transfers), Settings (toggles + go-dark). j/k moves the cursor; Tab / Shift+Tab jumps between sections; Space / → / ← toggles expand. Enter opens the selection in the right-hand pane. Esc focuses the sidebar from a chat pane.

Key bindings

Single source of truth: crates/huddle/src/keybindings.rs. The Help modal (?) renders the same table at runtime, so it can never drift from the actual key map.

Global (any pane, no modal open)

Key	Action
?	Help
: or Ctrl+P	Command palette — fuzzy search every action
Ctrl+H	Notification history (last 100 status events)
Shift+← / Shift+→	Focus sidebar / pane (tmux-style)
Esc	Close modal / blur input / focus sidebar
q / Ctrl+C	Quit (confirms first)

About the focus-jump binding (huddle 0.7.3+): Shift+← / Shift+→ toggle keyboard focus between the sidebar and the pane, including while typing in chat input. Shift+arrows are unclaimed at OS and terminal level on macOS, Linux, and Windows — no Mission Control / Spaces conflict. (0.7.2 briefly used Ctrl+← / Ctrl+→ but those collide with macOS's Move-between-Spaces shortcut.)

Sidebar / non-chat panes

Key	Action
m	Start a DM (Compose-DM modal)
g	Start a group room
p	Jump to the People pane
,	Jump to the Settings pane
a	Add friend by HD ID or username
d	Dial a peer by multiaddr or ip:port
i	Show your identity as a QR code
Shift+I	Generate an invite link (peer-only, or room-scoped from a chat pane)
v	Paste an invite link (huddle://invite#…)
c	Join with code (when an encrypted group is selected)
j / k / arrows	Move sidebar cursor
Tab / Shift+Tab	Jump to next / prev sidebar section
Space / → / ←	Toggle section expand
Enter	Open the selected row
r	Refresh / reconnect (context-sensitive)
x	Forget the selected peer
R (Shift+r)	Mark every room read

Chat pane (DM or Group)

Key	Action
/	Focus input
Enter	Send
Alt+Enter / Ctrl+J	Newline in input
Esc	Blur input (or focus sidebar)
Ctrl+V	Verify partner / member (SAS)
Ctrl+F	Search this room's history
Ctrl+A	Attach a file (in-terminal file picker)
p (in the attach picker)	Attach by typing a POSIX path (~ expands; also in the palette)
Ctrl+L	Leave the room
j / k	Scroll messages (input blurred)
g / G	Scroll to top / bottom
PageUp / PageDown	Scroll a page
f	Focus file cards (j/k steps)

Group pane only

Key	Action
Alt+M	Toggle the right-margin member list (Option+M on macOS)
Ctrl+K	Kick a member (owners only)
Ctrl+G	Grant owner role (owners only)
Ctrl+R	Rotate the room key (owners only)
Ctrl+J	Generate a single-use join code (owners)
Ctrl+M	Mute / unmute this room
Ctrl+O	Per-room verified-only-join toggle
Shift+B	List bans for this room (owners)

Settings pane (or Settings modal)

Key	Action
V	Toggle "reject inbound from unverified"
U	Toggle the crates.io update check (opt-in)
E	Edit your username
W	Replay onboarding (what's new)
B	Manage blocked peers
Alt+Shift+1 (Option+Shift+1 on macOS)	Delete account (go dark) — passphrase-gated

Username & ID display (huddle 0.5)

Every peer has a 96-bit fingerprint rendered as a branded HD-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX ID. Same security as before, just a friendlier format. The Profile pane (sidebar's top section) shows yours.

Set an optional username from the Profile or Settings pane (E). The username is broadcast in a signed ProfileUpdate event — peers receiving it verify the Ed25519 signature against the claimed fingerprint, so nobody can spoof "alice" by stuffing a string into a packet. If you clear the field (empty input), you broadcast as [anonymous].

In chat, your message label shows the username (or [anonymous]). SAS-verified peers also get a green ✓ next to their name in chat, matching the existing badge in the room member list.

Add friend by HD ID or username (huddle 0.5.1+)

Press a from the sidebar to open the add-friend modal. Takes either:

• an HD-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX ID (or the bare 24-hex form with/without dashes — normalized internally),
• or a username string (unique-match lookup in peer_profiles).

Resolution: huddle looks the fingerprint up across recent room announcements (creator_fingerprint + host_addrs) and the persisted known_peers table. Every candidate multiaddr is then handed to libp2p as a single DialOpts::peer_id().addresses() call — the swarm races them in parallel (huddle 0.5.2+) and the first to complete wins. The client also pre-sorts by transport preference (RFC1918 LAN ip4 → loopback → public ip4 → ip6 / dns → /p2p-circuit) so when latencies are close the LAN slot starts first. mDNS-discovered peers don't need this path at all — they show up in the sidebar's People section automatically.

The privacy trade-off worth knowing about: this works only for peers you've already seen on a shared gossipsub mesh — same LAN, a relay you both connect to, or a prior dial. There's deliberately no central "add by ID" directory; cold-start strangers must pass an invite link out-of-band first. Adding a directory (DHT, rendezvous server, central service) would either centralize the architecture or leak lookup metadata to bootstrap nodes — both fail the "trusted relay, absolute privacy" goal huddle's built around.

SAS verification

Both peers select each other in the Verify modal (^V), one presses s to start. Each generates an ephemeral X25519 keypair, exchanges pubkeys via signed envelopes, and derives a shared secret via ECDH. HKDF produces a 7-symbol + three-4-digit-group decimal code. The decimal follows the Matrix MSC 2241 shape, but the 7-symbol table is huddle's own 49-entry subset and does not interoperate with Matrix SAS. The TUI shows the symbols as their English words (dog, cat, lion, … — emoji-free) plus the decimal; both peers compare OOB (call/SMS/in-person) and press m to match. A MITM substituting an ephemeral key gets a different SAS code on each side — the OOB comparison catches it.

On match, the partner's fingerprint is marked verified (per-room + global). With the global "verified-only inbound" toggle on (Settings pane, V), unverified inbound dials auto-reject without prompting.

Invite links

Press Shift+I to generate an invite. From a chat pane the invite includes the current room; from anywhere else it's peer-only. The TUI shows a huddle://invite#<base64-JSON> URL plus a QR. The base64 JSON carries the host multiaddr (with /p2p/<peer-id> so libp2p enforces the peer-id check on dial), the human-display fingerprint, and an optional room summary.

Paste an invite from the sidebar with v. The TUI confirms the claimed fingerprint and dials. After dial, the post-dial fingerprint check (added in 0.3.x) re-derives the peer's fingerprint from their Ed25519 pubkey on Identify and disconnects if it doesn't match the invite's claim — defense in depth, since libp2p's /p2p/<peer-id> already enforces the cryptographic match.

If the invite includes an encrypted room, you're prompted for the passphrase next.

Owners, kick, ban

The room's creator is the first owner; owners can grant the role to others (Ctrl+G) or kick (Ctrl+K). Kick = signed BanMember broadcast + immediate RotateRoomKey with a freshly-generated passphrase (displayed to the owner for OOB re-share with the remaining members).

The banned peer still receives gossipsub bytes but can't decrypt the new outbound session key. Honest peers honour the ban (drop their messages); cryptographic enforcement is the key rotation, not the ban row itself. Soft owner model — kick is not a hard network quarantine.

B (Shift+b) lists the bans for the current room.

Internet reach

By default huddle uses LAN mDNS only. To accept dials across the internet, register with a Circuit Relay v2 host:

huddle --relay /dns4/relay.example.com/tcp/4001/p2p/12D3Koo...

…or persist in config.toml:

# macOS:  ~/Library/Application Support/huddle/config.toml
# Linux:  ~/.config/huddle/config.toml
# Windows: %APPDATA%\huddle\config.toml
relays = [
  "/dns4/relay.example.com/tcp/4001/p2p/12D3Koo...",
]

CLI flags override the config file. No relays are configured by default — you pick one explicitly. AutoNAT v2 probes test your reachability against the connected peer pool; DCUtR attempts a hole-punch upgrade to a direct connection whenever a relayed connection forms. When libp2p is enabled the Profile pane / sidebar badge shows the current state (reachable / LAN only / detecting…).

Room announcements optionally carry a host_addrs field with up to 4 of the announcer's reachable addresses (relay-circuit and AutoNAT-confirmed external). Peers receiving an announcement they have no direct connection for will opportunistically dial the first listed address (rate-limited per announcer). This lets cross-internet peers bootstrap without invite links.

Run your own relay (cloudflared, no domain)

The default relay is reached over Tor. If you (or the people you talk to) can't use Tor, run your own relay on a VPS and front it with a cloudflared tunnel — no registered domain, no TLS cert of your own:

# On the VPS:
cargo build --release -p huddle-server
./scripts/huddle-relay.sh
# → prints:  wss://<rand>.trycloudflare.com/ws

huddle-server only ever moves ciphertext (it never holds keys or decrypts). The script runs it on 127.0.0.1:8787 and points cloudflared at it; cloudflared supplies a publicly-trusted *.trycloudflare.com hostname, which huddle reaches through its TLS clearnet-wss door. Point clients at the URL:

• GUI: Settings → Network → "Set / edit" relay, paste the wss://…/ws.
• CLI: huddle --clearnet-server wss://<rand>.trycloudflare.com/ws, or set clearnet_url = "wss://…/ws" in config.toml.

A configured clearnet relay is tried first (you connect without waiting on a Tor timeout) and the onion stays as a fallback. Any invite you then generate embeds this relay (a signed v3 invite), so your contacts join with zero config — they just accept the invite.

No tunnel and don't mind exposing your IP? Run the server directly and use a raw plain-WebSocket door (open the firewall for the port):

HUDDLE_SERVER_BIND=0.0.0.0:8787 huddle-server      # on the VPS, e.g. 2.24.124.188
huddle --clearnet-server ws://2.24.124.188:8787/ws  # on each client

Caveats: free *.trycloudflare.com hostnames rotate when cloudflared restarts (so embedded-relay invites go stale — use a named cloudflared tunnel or a real domain for a stable URL); the raw ws:// door reveals your IP + WebSocket metadata to on-path observers (messages stay end-to-end encrypted); and the server's SQLite DB on the VPS is not encrypted at rest (it holds only ciphertext + routing metadata, never keys). See scripts/README.md for detail.

Join codes (read-only joiners)

Owners press Ctrl+J in a Group pane to generate a single-use, 10-minute XXXX-XXXX code. The owner shares it OOB. The joiner selects the encrypted group in the sidebar and presses c to enter the code. The joiner's TUI generates an ephemeral X25519 keypair, broadcasts a signed CodeJoinRequest, and waits for the owner's CodeJoinResponse (which wraps the room's session key under an ECDH-derived key). If no response arrives within 30 s, the TUI surfaces a timeout error — usually meaning the code was wrong or expired.

Code-joined members are read-only: they can read and send, but without the passphrase they can't wrap session keys for newer joiners. The Group pane header renders (read-only) next to the encryption marker. To upgrade, an owner can re-onboard them with the actual passphrase.

Go dark — irreversible account deletion (huddle 0.5)

Press Alt+Shift+1 (the Option key on macOS — same physical key) from anywhere — or use the labeled row on the Settings pane — to open the go dark modal. Single-field gate (huddle 0.7.6+):

• If you have a master passphrase, that's the gate — re-derived via Argon2id and constant-time compared to the in-memory SQLCipher subkey. Wrong passphrase clears the field and shows an inline error.
• In --no-master-passphrase sessions (no key to compare against), type the literal phrase DELETE EVERYTHING (case sensitive) instead.

On confirm, huddle:

• best-effort MemberLeaves every joined room (2-second cap so a flapping transport can't hang the wipe),
• shuts down the network task,
• zeroes-then-deletes huddle.db, huddle.db-shm, huddle.db-wal, keychain.salt, huddle.log (and any rotated logs), and config.toml from the data dir,
• removes the now-empty data dir, and
• shows a brief goodbye modal before exiting.

There is no recovery. Restarting huddle after a go-dark generates a fresh identity from scratch.

Architecture

huddle/
  huddle-protocol  runtime-free wire format + crypto — "the spec, as code" (see PROTOCOL.md)
  huddle-core      shared library: rooms, network, storage, Megolm sessions, the AppHandle
  huddle           terminal UI (ratatui TUI)
  huddle-gui       native desktop app (egui/eframe)
  huddle-server    WebSocket relay + offline mailbox (SQLite)

The wire format and cryptographic constructions are specified in PROTOCOL.md — a citable spec precise enough to build a second interoperable implementation against the published huddle-protocol crate.

Networking — libp2p 0.56 with TCP+Noise+Yamux transport, mDNS for LAN discovery, gossipsub for both global room advertisement and per-room message broadcast, identify, ping, request-response, Circuit Relay v2 client, AutoNAT v2 (client + server), DCUtR. Mesh topology — every member of a room receives every message; there's no "host" with special powers, and rooms survive the original creator leaving (as long as someone else is in them). The owner role is client-enforced state, not a network-level privilege.

Encryption — vodozemac Megolm group sessions (one outbound per peer). For group rooms entered via passphrase, you wrap your session key with ChaCha20-Poly1305 under an Argon2id key derived from (passphrase, salt) and broadcast that for every existing member to pick up. For group rooms entered via code, ECDH between owner and joiner gives a wrap key that delivers only the owner's session — the joiner's own outbound goes unwrapped. For DMs (huddle 0.7.1+), the wrap key is derived from the two parties' long-term identity keys, expanded with HKDF-SHA256 bound to the canonical room ID — both peers independently derive the same 32-byte wrap key. As of huddle 1.3 this DM agreement is hybrid post-quantum: a classical Ed25519→X25519 ECDH secret is combined (via HKDF) with an ML-KEM-768 (FIPS 203) secret, so the wrap key holds as long as either primitive does; a pre-1.3 peer that publishes no ML-KEM key falls back to classical X25519. huddle 1.3.1 pins a peer's post-quantum capability once seen, so the hybrid path can't be replayed back down to classical. See SECURITY.md for the full construction and threat model.

App-level signing — every protocol message whose authenticity matters (OwnerGrant, BanMember, RotateRoomKey, SAS handshake, CodeJoinRequest/Response, JoinRefused) is wrapped in a SignedRoomMessage Ed25519 envelope. Receivers verify the signature, re-derive the fingerprint from the envelope's pubkey, and gate on both verified_signer.is_some() and (where applicable) signer-is-owner.

Identity — Ed25519 keypair stored under your platform's data directory. Fingerprint format: six groups of four hex chars (a3b1-c2d4-e5f6-7890-1234-abcd).

Storage — SQLCipher (rusqlite + bundled SQLCipher + vendored OpenSSL). On launch you enter a master passphrase; it's stretched with Argon2id (m=64 MiB, t=3, p=4) against a per-installation salt and used as PRAGMA key, plus an HKDF subkey replaces the older hardcoded Megolm persistence key. Tables include identity, rooms (with kind ∈ {direct, group}), room_members (with role, ed25519_pubkey), room_megolm_sessions, room_messages, room_attachments, known_peers (with fingerprint, trusted), blocked_peers, room_bans, verified_peers, peer_profiles (self-declared usernames, signed at the wire layer), app_settings. Migrations are additive only and tracked via PRAGMA user_version. Pass --no-master-passphrase to fall back to an unencrypted database for testing.

File attachments — Ctrl+A opens a local file picker; selected files are SHA-256-hashed, chunked into 64 KiB pieces, and broadcast over the room's gossipsub topic with a FileOffer + N FileChunk messages. In encrypted rooms (DM or group) the bytes are ChaCha20-Poly1305-encrypted with a fresh file key that's Megolm-wrapped in the offer. Receivers see a focusable file card in chat — press f to enter card mode, j/k to step, Enter to save to your platform's Downloads folder. The per-file cap is 50 MiB. If the native picker is in your way (a headless box, an awkward window manager, or you simply know the path), attach by typing one instead: in the TUI press p in the file picker — or run "attach a file by path" from the command palette — where ~ expands to home and a bad path shows an inline error (your input is kept, not dropped); in the GUI, enable Settings → Privacy → "attach by typing a path" (off by default, persisted) to swap the Attach button's native dialog for a path-entry box.

Operator notes

• The first launch creates <data_dir>/keychain.salt. Don't move or delete it without your passphrase backed up — losing it forces a re-derive that won't unlock the existing DB.
• --no-master-passphrase opens an unencrypted DB. Testing only.
• --relay <multiaddr> (repeatable) registers a circuit-relay reservation. The relay's identify response is the cue to start listening on <relay>/p2p-circuit.
• --no-relay ignores any relays in config.toml for this run.

Current limitations

• LAN-only by default. Cross-network use needs a configured relay (Phase D), an invite link with a public multiaddr, or a manual d dial to a port-forwarded ip:port.
• Code-joined members are read-only — they don't have the passphrase and can't onboard further members.
• Kick / ban are honest-client-enforced at the gossipsub layer; the cryptographic teeth come from the key rotation that follows.
• File transfer is capped at 50 MiB per file (the whole file is held in memory on both ends). Truly large (GB) files would want a streaming / resumable transport (planned). A >1 MiB file only lands if both peers are ≥1.2.5 — the receiver enforces its own cap.
• mDNS may not work on some corporate / restricted networks.
• Verified-only inbound mode trusts SAS-verified + previously-trusted fingerprints. Don't enable it before you've verified at least one peer you can re-bootstrap from.
• The SAS symbol table is huddle-internal (a 49-entry subset derived by rejection sampling) and does not interoperate with Matrix SAS — only the decimal code follows the MSC 2241 shape, so SAS works huddle↔huddle only (both ends on a compatible huddle version).
• DM/group wrap keys still derive from long-term identity material, so there is no full forward secrecy at the wrap-key layer yet — an identity-key compromise can unlock historical session keys (Megolm message keys ratchet, but the wrap key doesn't). 2.0.0 narrows this with forward-only Megolm epoch rotation (the outbound session rotates on a schedule + on membership change), bounding the exposure window; the full fix — a Double Ratchet seeded from the hybrid root key — is sequenced in docs/ROADMAP-2.0-and-beyond.md.

What's new in 2.0.6 — hybrid post-quantum authentication (Ed25519 + ML-DSA-65)

A protocol-library release that extends huddle's post-quantum posture from confidentiality (the hybrid X25519 + ML-KEM-768 DM key agreement) to authenticity. No wire or behaviour change for existing peers — the additions are optional and additive, so 1.3.x / 2.0.x peers ignore them.

• Composite signatures. Identity / authority envelopes can now be signed with Ed25519 and ML-DSA-65 (FIPS 204), so a forgery requires breaking both — a future quantum computer that breaks Ed25519 still can't forge a huddle envelope. The ML-DSA keypair is derived deterministically from the same identity seed (no new on-disk material), exactly like the ML-KEM key.
• Downgrade-resistant verification. A verifier that has pinned a peer's ML-DSA key (learned from a signed announce) rejects an envelope carrying a different ML-DSA key, or a stripped / invalid signature.
• Where it lands. The capability ships in the huddle-protocol crate (crypto::mldsa, sign_message_hybrid_pq, verify_signed_mldsa), additive on the wire (two optional mldsa_* fields). Applying it across the app's authority envelopes mirrors the existing ML-KEM pinning path.

What's new in 2.0.5 — foundations: the SAS subsystem becomes an actor

An internal refactor with no wire or behaviour change (fully compatible with 1.3.x / 2.0.x peers and relays) — the first step of decomposing huddle-core's ~8.3k-line AppHandle god-object into focused, independently-testable actors behind a typed command seam.

• SAS verification is now its own I/O-free actor. The handshake state machine and crypto move into app::sas_actor::SasActor, which returns publish / emit / finalize intents the AppHandle facade carries out (signing, network send, the durable verification writes, events). The public surface is unchanged, so the TUI and GUI are untouched — and the state machine is now unit-testable without spinning up the whole app.
• Why it matters. This is the template for extracting the rest of the god-object (files, contacts, rooms) and the foundation the durable event journal and MLS group ordering will build on. See docs/ROADMAP-ecosystem-importance.md.

What's new in 2.0.4 — huddle-protocol: a runtime-free protocol crate

An engineering release with no wire or behaviour change — fully compatible with 1.3.x / 2.0.x peers and relays. The pure wire format and cryptographic constructions move out of huddle-core into a new standalone huddle-protocol crate that depends only on RustCrypto / serde (no tokio, libp2p, rusqlite, or vodozemac), so the client and the relay now speak from one shared definition instead of hand-duplicated copies.

• One source of truth for the wire. WireMessage / RoomMessage / SignedRoomMessage, the invite format, the signed-envelope + hybrid-PQ DM key agreement, SAS, and the relay control messages all live in huddle-protocol. huddle-core re-exports them at their original module paths, so nothing changes for the TUI / GUI.
• The relay drops its duplicated crypto. huddle-server no longer open-codes the fingerprint derivation and challenge verification — it shares them with the client, byte-for-byte.
• A foundation, not a feature. This is the first step of making huddle a protocol others can build on (see docs/ROADMAP-ecosystem-importance.md). Wire bytes are byte-identical, and a new conformance test pins them.

What's new in 2.0.3 — security audit hardening (round 2)

A second security-fix release closing the bulk of a fresh multi-agent audit of 2.0.2. Wire changes are additive only — the three signed control messages gain an optional room_id that older peers ignore — so 2.0.3 stays fully compatible with 1.3.x / 2.0.x peers and relays. Highlights:

• Relay mailbox-squat DoS (HIGH): the 2.0.2 global mailbox cap is no longer squattable by a single identity. The relay now rate-limits the mailbox-writing ops per connection and caps the rows any one sender can hold outstanding, so a free keypair can't fill the pool in a burst and shut off everyone's offline delivery. Clients send a lightweight keepalive and the relay reaps truly-idle sockets (connection-pool-exhaustion defense — the keepalive also keeps cloudflare-tunnelled connections from idling out).
• Release-pipeline token exposure (HIGH): cargo publish runs with --no-verify so the crates.io token is never in the env of a verify-build that executes untrusted transitive build scripts; the release workflow drops to a read-only default token with per-job write scope and persist-credentials: false.
• Cross-room signature replay (MEDIUM): signatures don't bind the gossip topic, so RoomSetting / RotateRoomKey / MemberLeave now carry and cross-check the room they apply to — a malicious relay can no longer replay a signed control message from one room into another.
• More authz & integrity fixes (MEDIUM): a banned room creator can no longer force a disappearing-messages TTL; mailbox-delivered edits/deletes/reactions are no longer ACK-dropped before their target arrives (no silent suppression of a retraction); JoinRefused is owner-authenticated (no spoofed phishing toast); the GUI recovery-seed "Copy" button is gone (the 24-word root secret no longer touches the OS clipboard / Universal Clipboard).
• Hardening: an 8-char floor on room/master passphrases at set time; onion dialing matches .onion as a host suffix, not a substring (which could tunnel a clearnet host through Tor); Windows reserved device filenames neutralized on saved files; the SQLCipher DB + GUI log are owner-only (0600); the discovered-rooms map is bounded and untrusted announcement fields clamped; cargo-deny is now a hard CI gate.

The relay stays transport-agnostic: clients on Tor, raw clearnet, and a cloudflare/clearnet TLS door all reach the same mailbox + room fan-out, so users on different transports chat together.

What's new in 2.0.2 — security audit hardening

A security-fix release closing findings from an exhaustive multi-agent audit of 2.0.1. No wire or on-disk format change — fully compatible with 1.3.x / 2.0.x peers and relays. Highlights:

• Sender-spoofing in encrypted rooms (HIGH): unsigned Plain messages are now rejected in encrypted rooms, so a node that learns a room id can no longer inject a forged message attributed to a trusted member.
• Relay disk-fill DoS (HIGH): the relay enforces a global mailbox ceiling (shed-on-full, never evicting other recipients) plus a per-identity membership cap; /metrics is now disabled unless a bearer token is configured.
• Relay-weaponizable integrity bugs (MEDIUM): inbound Megolm sessions never regress forward (no relay-assisted message suppression); mailbox messages are ACKed only after they're durably handled (no ACK-then-lose); message edits use the signature-bound timestamp for last-write-wins (a relay can't revert content by reordering); SessionKeyRequest re-announces are rate-limited (anti- amplification, with rotations exempt so key re-shares still flow.)
• Authorization: a ban now strips the target's owner role and is enforced at the is_owner gate; the Delete handler gained the banned-member filter every other content arm already had.
• At-rest hygiene: the data dir is 0700 and the keychain salt 0600; a minimum length is enforced on passphrase changes; file-transfer reassembly caps the chunk count (not just bytes); untrusted RoomAnnouncement fields are clamped on ingest; an invite-freshness integer overflow was fixed.

See AUDIT-2.0.1.md for the full findings and the per-fix mapping.

What's new in 2.0.1 — SAS verification fix (post-quantum capability binding)

A focused fix release. 2.0.0's SAS post-quantum capability binding (F1) was asymmetric: each peer folded the other peer's ML-KEM key into the SAS transcript, so two post-quantum-capable peers derived different safety numbers and could never complete out-of-band verification. It failed closed — the channel was never weakened and no MITM could forge a match — but verification between two 2.0 peers was effectively impossible, and the verified_peers.pq_capable anchor could never be set. 2.0.1 binds both peers' ML-KEM keys in a canonical (byte-sorted) order, so honest peers again derive the same code; a genuine capability mismatch, or a relay stripping one side's key, still makes the codes diverge (downgrade detection preserved). No wire or on-disk change — the relay and SAS against 1.3.x / classical / group peers are byte-for-byte unaffected; only client-side SAS derivation changed.

What's new in 2.0.0 — forward secrecy steps, recovery, and richer chat

A major release that adds a layer of long-wanted capabilities on top of the 1.3.x hardened base. All wire additions are backward-compatible — new RoomMessage variants and fields are optional, so a pre-2.0 peer simply ignores them and old database rows still decode; new behaviour is 2.0+-only where both ends must understand it. The whole feature set was built by a waved multi-agent fleet and then put through an adversarial multi-agent bug scan.

Security & cryptography

• Post-quantum downgrade residual closed. The inviter's/partner's ML-KEM-768 capability is now bound into the SAS verification transcript and into a new v4 signed invite (mlkem_ek_b64), and a peer's PQ capability is persisted in verified_peers. So once you've verified or been invited by a peer, a malicious relay can no longer silently force the classical fallback — the one first-contact gap SECURITY.md documented for 1.3.
• Forward-only Megolm epoch rotation. A room's outbound session now rotates on a schedule (every N messages / T hours, and on membership change), bounding how much history a single key compromise can expose — a concrete step toward forward secrecy without the full ratchet (see the roadmap).
• Content-layer replay protection. A durable per-(room, sender, session, message-index) seen-set silently drops a wire-level replay of an already-processed message — even across a restart or a cross-transport re-broadcast. Only content is deduped; control re-announces still work.
• Master-passphrase change + at-rest rekey. You can change your master passphrase: huddle re-derives the key and PRAGMA rekeys the SQLCipher database atomically (rollback-safe), re-wrapping the Megolm-persistence subkey.
• Safety-number-change alarm. A pinned identity-key change (TOFU drift) now raises a loud, explicit warning prompting re-verification instead of a silent drop.

Recovery

• BIP39 seed phrase. Export your identity as a 24-word checksummed mnemonic (shown once, re-entry-verified) and import it on a new machine to fully restore your identity — PeerId, ML-KEM key, and DM keys all derive from the one seed.

Reliability

• At-least-once relay delivery. The relay now tags each mailbox delivery with a row id and keeps the row until the client ACKs durable receipt, closing the window where a socket drop mid-drain could lose a queued message. Pre-2.0 clients (no ACK capability) keep the classical delete-on-deliver behaviour.

Product

• Full-text search. Local message search is now backed by SQLite FTS5 (ranked, tokenized, prefix/boolean queries) over the at-rest-encrypted body — no new exposure, just faster and better than the old substring scan.
• Disappearing messages. A per-room TTL (off by default) auto-deletes messages locally after the window — really removed from the database, and a replay can't resurrect an expired message.
• Reactions, replies, edits, and deletes. React with an emoji, reply in-thread, edit your own messages (with an "edited" marker), and delete for everyone (best-effort — an honest client honours it; an adversarial one can't be forced to). Each is an additive signed message keyed to a sender-minted stable message id.

Engineering

• Single-sourced workspace version ([workspace.package]) so a release is one bump, not seven. Added proptest property tests + cargo-fuzz targets for the wire/crypto decision logic, a Prometheus /metrics endpoint on the relay, and a cargo-deny supply-chain gate.

See docs/ROADMAP-2.0-and-beyond.md for the sequenced heavy work (MLS groups, a full Double Ratchet, hybrid PQ authentication, metadata blinding, multi-device, mobile) this release deliberately set the foundation for.

What's new in 1.3.4 — security & DoS hardening (73-agent audit of 1.3.3)

A focused hardening release on top of 1.3.3 (no wire-format change; fully compatible with 1.3.x and pre-1.3 peers), closing 19 issues confirmed by a multi-agent adversarial audit of the whole tree (each finding verified by three independent skeptics, then re-reviewed per file for regressions).

• Closed a critical invite version-downgrade. The invite v field isn't covered by the signature, so an attacker could flip a signed v2/v3 invite to v=1 — which skipped signature and freshness verification entirely — then swap the relay URL or fingerprint. decode now refuses any v=1 invite that carries signature fields (a genuine legacy v1 never does).
• Fail-secure database security checks. is_member_banned and is_peer_blocked masked any DB error as "0 rows" (.unwrap_or(0)), i.e. they failed open — a banned/blocked peer reported as allowed. Security COUNT(*) checks now apply a fail-secure default (deny on error) and log instead of silently swallowing.
• SAS can't be confirmed before the code exists. sas_match now refuses to send a match confirmation while the SAS code is still None (before the partner's response), so no alternate codepath can confirm a comparison the user never actually made.
• Relay-client DoS hardening. The client connecting to a relay now caps WebSocket frames at 512 KiB (matching the server; was tungstenite's 64 MiB default), bounds the challenge-nonce and message-payload sizes before decoding, and caps the pre-auth send backlog — so a malicious relay can't exhaust client memory.
• Relay-server connection limits. A single fingerprint may now register at most 16 concurrent sockets (each is a target in the per-room publish fan-out, so unlimited sockets meant O(N)-clone amplification), and a global semaphore caps total concurrent connections.
• Bounded memory everywhere a peer controls the count. Incomplete file transfers (LRU-capped + a global byte budget), the session reject-list, the per-peer profile-broadcast and per-room key-request throttle maps, attachment listings, and the TUI/GUI open-room message buffers are all now bounded, so a peer churning identities or spamming a room can't grow client/relay memory without limit.
• Path-traversal guard on file transfer. An attacker-supplied file_id is now validated as a 64-char hex digest before it's ever joined onto the cache path, closing a read-amplification/traversal vector via unauthenticated FileChunks.
• No more bricked database on a corrupt salt. load_or_create_salt used to silently regenerate the keychain salt whenever it read back the wrong length (or on an IO error), permanently locking the existing SQLCipher DB. It now refuses to overwrite a present-but-corrupt salt and returns actionable recovery guidance.
• Relay circuit registers without a /p2p/ suffix. A relay configured by bare address (no /p2p/<peer-id>) never registered its /p2p-circuit reservation, because the address re-match failed after dial_attempts was cleared. The reached address is now carried with the relay's PeerId, so the circuit registers either way.
• GUI unread counter is saturating (was a wrapping += 1, matching the TUI).

What's new in 1.3.3 — hardening follow-up (audit of 1.3.2)

A small fixes release on top of 1.3.2 (no wire-format change; fully compatible with 1.3.x and pre-1.3 peers), from a multi-agent audit of the 1.3.2 changes.

• Closed a dial-amplification regression. 1.3.2 capped the opportunistic host-address dial map, but once the cap was reached it still dialed without recording the attempt — so the per-announcer backoff stopped engaging and a flood of bogus room announcements could be turned into repeated outbound dials to an attacker-chosen address. The relay/peer now refuses the dial when it can't record the backoff, so both memory and dials stay bounded.
• SAS verification can't be starved by one peer. The in-memory SAS-handshake map now has a per-partner sub-cap (in addition to the global cap), so a single peer can no longer fill it and block everyone else's verification.
• Slow SAS comparisons no longer time out mid-handshake. The SAS flow TTL is now measured from last activity (and raised to 15 min), so taking your time reading the emoji/decimal codes out loud won't drop the handshake.
• Tighter relay pre-auth bound. The pre-WebSocket phase (peek + accept) now shares one timeout instead of two, so a stalled connection can't be held for a multiple of the documented pre-auth budget.
• Cleanup. Removed a dead branch in the GUI close path left by the 1.3.2 refactor (no behavior change).

What's new in 1.3.2 — bug-fix & hardening pass

A focused fixes release on top of 1.3.1 (no wire-format change; fully compatible with 1.3.x and pre-1.3 peers), from a multi-agent audit of the whole tree.

• huddle app reliably finds your checkout. It builds the GUI from a source clone; previously it only located the clone when this binary was itself built from one (cargo install --path) or you ran it from inside the repo — so a crates.io install (cargo install huddle) could fail with "couldn't find the huddle source checkout." It now also searches common clone locations under your home directory (and still honours HUDDLE_SRC).
• GUI Quit / Restart actually close the window. Confirming "Quit" tore down the connection but left the window open until you clicked the OS close button a second time; "Restart" could leave two windows. Both now close immediately.
• A failed send no longer eats your message. If a message can't be sent after the composer cleared, the text is restored instead of silently lost.
• Relay DoS hardening. The relay now applies its pre-auth timeout to the earliest connection phase (closing a slowloris hole) and caps inbound WebSocket frames at 512 KiB instead of tungstenite's 64 MiB default.
• Robustness. Guarded a panic in the inbound-message path that a concurrent room-leave could trigger; bounded two in-memory maps against a malicious-peer flood; debounced a DM key-request loop on a stalled handshake.
• Docs. Corrected the SAS code's overstated Matrix-interop claim, a couple of stale invite-keybinding hints (it's Shift+I / Alt+I), and several comments.

What's new in 1.3.1 — post-quantum downgrade hardening + DM handshake liveness

• PQ-capability pinning closes a downgrade hole. 1.3.0 stopped a relay from stripping the ML-KEM fields (they're signed), but a relay could still replay a peer's captured pre-1.3 (classical-only) announce to push the DM back onto the quantum-breakable classical key — reopening the very harvest-now-decrypt-later gap 1.3 closes. 1.3.1 pins a peer's post-quantum capability the first time it's seen (persisted across restarts) and then refuses the classical fallback for that peer, so a replayed classical announce is ignored.
• Self-healing classical→hybrid upgrade. If a DM ever ends up keyed classical (rollout timing, or a replay that won an initial race), it's upgraded to hybrid the moment the partner's capability is observed — no restart needed — and the upgrade rotates the outbound Megolm session so every message sent after the upgrade uses a key never exposed classically. (Rotation is forward-only: anything already sent during the brief classical window stays exposed — it bounds the window, it can't rewrite the past.) Upgrades are one-way; a hybrid DM is never downgraded.
• Sturdier hybrid handshake. The responder now explicitly asks for the KEM ciphertext if it's missing, and a bounded background nudge re-prompts a stalled handshake — so a single lost announce no longer leaves a DM wedged until restart.
• No wire-format change; fully compatible with 1.3.0 and pre-1.3 peers. See SECURITY.md for the updated threat model (including the documented first-contact residual).

What's new in 1.3.0 — post-quantum hybrid DM encryption (X25519 + ML-KEM-768)

• Direct-message key agreement is now hybrid post-quantum. A DM's wrap key is derived from both a classical X25519 ECDH and an ML-KEM-768 (FIPS 203) key encapsulation, mixed through HKDF-SHA256. The key is secure as long as either primitive holds, so a future quantum computer that breaks X25519 no longer threatens recorded DMs — this closes the "harvest now, decrypt later" gap, where an adversary stores ciphertext today to decrypt once quantum hardware exists. The same approach Signal's PQXDH uses.
• No new key to manage, no migration. Each identity's ML-KEM keypair is derived deterministically from the existing Ed25519 seed, so every current identity gains a post-quantum key for free; nothing changes on disk.
• Backward compatible. The ML-KEM public key and ciphertext ride in new, optional MemberAnnounce fields. A 1.3 peer talking to a pre-1.3 peer automatically falls back to the classical X25519 DM key — DMs keep working. A DM goes hybrid only when both peers are on 1.3+. Because the new fields live inside the signed announce envelope, a malicious relay can't strip them to force a downgrade without breaking the signature.
• Unchanged by design (and honest about it): message contents are still encrypted with Megolm (quantum-resistant already — it's symmetric AES-256 + HMAC), file bytes with ChaCha20-Poly1305, and identities/ message authenticity still use Ed25519 signatures (classical — forging a signature needs a quantum computer operating live, not "harvest now", and changing it would break the relay/identity ecosystem). Group-room key delivery via a passphrase is already post-quantum (Argon2id is symmetric). See SECURITY.md for the full posture.

What's new in 1.2.5 — bigger files (50 MiB) + attach-by-path polish

• Larger attachments — the per-file cap goes from 1 MiB to 50 MiB. Chunks are now 128 KiB (was 40 KiB), which keeps a full-size file at ~400 chunks — under the relay's per-recipient mailbox cap, so a big file still reaches an offline recipient. The whole file is held in memory on both ends, and the receiver enforces its own cap, so a >1 MiB file only lands if both peers are on 1.2.5+. (No relay change required — verified end-to-end against the live relay, including 3-member group fan-out and a multi-MiB round-trip.)
• attach-by-path polish (from the 1.2.4 review). TUI and GUI now share one ~-expansion helper (only ~ and ~/… expand; ~user stays literal); "attach by path" is guarded on being in a room (no palette dead-end); the GUI modal submits on Enter; empty input gives feedback; and the in-app help no longer advertises a bare p shortcut that only works inside the file picker.

What's new in 1.2.4 — attach a file by typing a path + a tidier composer

• Attach a file by typing its path — for when the native file dialog is in your way (a headless box, an awkward window manager, or you just know the path):
  • TUI: in the file picker press p (or run "attach a file by path" from the command palette) to type a POSIX path; ~ expands to your home. A path that doesn't point at a real file shows an inline error and keeps what you typed, instead of silently dropping it.
  • GUI: Settings → Privacy → "attach by typing a path" swaps the Attach button's system file picker for a path-entry box. Off by default; the choice persists.
• Tidier message composer (GUI). The input row no longer reserves a tall resizable band, so the dead space that used to sit under the message box is gone.

What's new in 1.2.3 — message timestamps show when there's a real gap

• No more "continuous" messages across a quiet gap. The chat view used to only break on a new calendar day, so two messages sent minutes (or hours) apart with nobody talking in between ran together as if they were one burst. Now a fresh, timestamped group starts whenever messages are more than a couple of minutes apart — so you can see when time actually passed.
• Seconds in timestamps. Message times now show HH:MM:SS (UTC), matching the logs (which were already UTC).
• The desktop app re-shows the sender + time header after a gap; the terminal UI draws a centered time divider (each message already carries its own time).

Seeing an old version number (e.g. v1.1.3) in the app? That's a stale install — the version is compiled in, so update with cargo install huddle-gui --force / cargo install huddle --force, or git pull && huddle app.

What's new in 1.2.2 — docs refresh + huddle app tidies up after itself

• huddle app reclaims the build cache. After it builds + installs the desktop app, it now runs cargo clean for you, so the multi-gigabyte target/ from the release build doesn't linger. Set HUDDLE_KEEP_BUILD=1 to keep it (e.g. when iterating from a source clone).
• Docs brought current for the 1.2 line — the huddle app installer, connect codes, the About window, and the relay's DM/friend-request delivery model (see SECURITY.md).

What's new in 1.2.1 — add a contact by short code, + an About window

A small UX follow-up to 1.2.0's working DMs: you no longer have to read out your full 24-character HD-ID to start a DM.

• Connect codes. Generate a short, single-screen code (8 characters, e.g. K7M9-Q2X4) that's valid for 5 minutes. A friend types it into their "add a contact" box and a contact request flies to you — no HD-ID required. The relay holds the (ephemeral) code→identity map; the code grants nothing on its own (redeeming it only sends you a request you still accept), and it expires fast so it can't be reused to track you. Generate one from the add-contact dialog (GUI) or with G (TUI); the same box accepts either a code, an HD-ID, or a username.
• About window (GUI). Settings → Account → About huddle shows the version and a link to the source: github.com/richer-richard/huddle.

What's new in 1.2.0 — the relay actually carries DMs + friend requests

The headline fix: two people can now reliably chat. Earlier builds delivered relay traffic only by room membership, so a 1:1 DM or a friend request needed both sides to have independently subscribed the exact same room before anything flowed — a fragile convergence that often left the chat window empty with no explanation. 1.2 moves that smarts into the server.

• Fingerprint-addressed direct delivery (server). The relay gains a SendDirect primitive: a message addressed to a recipient's fingerprint is delivered to every connection that identity has open, or queued in its per-fingerprint mailbox when it's offline — no shared-room subscription required. DMs and friend requests now ride this path, so they reach the other person live or as soon as they next connect. Group rooms keep using membership fan-out. (The relay must be on 1.2 for this; the protocol is backward-compatible — older clients still work over the membership path.)
• Offline first-contact actually works. Add someone by HD-ID while they're offline and the signed request now waits in their mailbox and is handed over on their next connect. Previously two bugs killed this: the request needed a live inbox subscription, and the signed envelope was rejected as "outside the ±5-minute replay window" once it had sat in the mailbox. 1.2 exempts store-and-forward control messages (contact requests, member announces, session-key requests) from the wall-clock window — the signature still proves identity, and replaying them is idempotent.
• Robust relay membership across reconnects. Every room you belong to — including encrypted groups and DMs parked awaiting a passphrase or the partner's key — is now re-asserted to the relay on every (re)connect, closing a window where a room created during the connect handshake (or restored at startup) was never registered and silently received nothing.
• Honest composer (TUI + GUI). The message box is now gated on real deliverability: when no transport can carry a message it tells you ("connecting to relay" / "offline") and keeps your text instead of showing a fake "sent" echo that reached no one.
• DMs self-heal. A DM that delivery reaches but that wasn't open locally is lazily re-activated so the partner's first message / session-key announce isn't dropped.

What's new in 1.1.5 — a permanent clearnet address (for Tor-blocked users)

The baked-in clearnet fallback is now a stable address that never rotates, so people in regions where Tor itself is blocked have a reliable non-Tor door.

• Stable clearnet relay default. DEFAULT_CLEARNET_URL now points at a permanent Cloudflare *.workers.dev proxy in front of the operator's relay, instead of a raw *.trycloudflare.com quick-tunnel hostname that rotated on every restart and went stale. The proxy reads the relay's current backend from KV (kept fresh automatically), so the address is durable. The Tor onion stays the canonical, preferred door; this clearnet fallback is tried only when the onion is unreachable, and any explicit --clearnet-server / clearnet_url / Settings value still wins over it.

What's new in 1.1.4 — security & robustness pass

A hardening release across the relay client, the DM/SAS key exchange, the mailbox, and the updater — plus the TUI catching up to the GUI's live themes. No new features; the wire/relay protocol gets stricter and a few classes of abuse close.

• Relay client auth via Ed25519 challenge-response. Connecting clients now prove control of their identity key to the relay through a signed challenge-response handshake before they can subscribe to an inbox or post to a mailbox — so a peer can't squat another fingerprint's inbox.
• X25519 small-order / contributory checks on DM + SAS. Both the DM wrap-key ECDH and the SAS ephemeral exchange now reject small-order and non-contributory public keys, closing key-substitution / forced-shared-secret attacks on the handshakes.
• Safer relay mailbox delivery. Queued ciphertext is now removed only after it's handed to the recipient's socket, over a bounded outbound queue, so a drop mid-drain no longer silently loses or double-delivers a message.
• Bounded retention GC. The relay's SQLite mailbox enforces a bounded retention window and garbage-collects expired ciphertext, so an offline recipient can't let the queue grow without limit.
• Update check routed via Tor. The opt-in crates.io update check now goes through the Tor SOCKS proxy instead of a direct clearnet request, so enabling it no longer leaks your IP to the index.
• TUI live Dark / Light themes. The terminal client gains the live Dark/Light theme toggle that shipped for the GUI in 1.1.2 — switchable from the Settings pane at runtime, no restart.

What's new in 1.1.3 — rustls fix, system theme, huddle app installer

A reliability + convenience release.

• rustls CryptoProvider fix. The desktop GUI's wss:// clearnet-relay worker could panic at startup ("could not automatically determine the process-level CryptoProvider"). huddle now links and installs the ring provider explicitly, so the clearnet door works in every binary.
• System theme (GUI). The desktop GUI gains a System option that follows your OS light/dark setting — now the default; existing Dark/Light choices are preserved.
• huddle app installer. From a source clone the terminal binary doubles as a one-step installer that builds, installs, and launches the GUI: huddle app.

What's new in 1.1.2 — high-contrast Dark + Light GUI themes

The desktop GUI gains a proper theming pass: hand-tuned, high-contrast Dark and Light palettes with a live toggle.

• Two high-contrast themes. Both Dark and Light are tuned for legible contrast across chat, sidebar, and modals rather than eframe's defaults.
• Live Settings toggle. Switch themes from Settings at runtime — the whole window re-skins immediately, no restart, and the choice persists.

What's new in 1.1.1 — GUI install guide on crates.io

A docs-only release so the published crate carries the new install guide.

• GUI install + run guide. The README's Install section (with the huddle-gui install + first-run walkthrough) ships in the crate published to crates.io. No code changes.

What's new in 1.1.0 — baked-in operator clearnet relay

huddle now ships with the operator's clearnet relay built in, so a client that can't reach Tor connects with zero config — and the GUI reaches clearnet parity.

• Operator clearnet relay door baked in. A cloudflared wss:// tunnel onto the very same rooms + mailboxes is compiled in as a default door. It's tried only after the onion, so a Tor user never touches it; --clearnet-server, clearnet_url in config.toml, or Settings → Network override it.
• GUI clearnet parity. The desktop GUI gets the same clearnet-relay controls as the TUI — set / edit a relay URL from Settings → Network, with invites embedding the configured relay.

What's new in 1.0.1 — the GUI catches up to the unified network

The native egui GUI gains the contacts book, transport doors, and unified LAN+relay network that landed for the TUI in 1.0.0.

• Contacts, doors & unified network in the GUI. The egui desktop client now wires up the fingerprint-keyed Contacts book, the add-by-HD-ID relay inbox flow, the multi-transport doors, and the LAN+relay-by-default network — reaching feature parity with the TUI's 1.0.0 release.

What's new in 1.0.0 — one app, every network, every door

A big one. huddle stops being "relay-only OR libp2p-only" and becomes a single E2EE core with both carriers on by default, a durable contact book, and a menu of anti-censorship transports onto the relay.

• LAN + relay on by default — no mode switch. The startup mode now resolves to libp2p mDNS (LAN) running alongside the relay; the Settings LAN toggle picks mDNS vs direct on the next launch, and --mode still overrides. Pure-relay (--mode server) and no-libp2p setups are still available, but you no longer choose between "nearby" and "internet" — you get both. LAN works even with Tor down.

• Contacts — a durable, fingerprint-keyed address book. A new contacts table keyed by the stable identity (not an ephemeral libp2p multiaddr) is the link that lets two people keep chatting after they leave the LAN: the relay routes by fingerprint/room, so the DM keeps working. The People pane is now Contacts; list_contacts() joins the book with derived username / verified / trusted / reachability.

• "Add by HD-ID" works over the internet. Each client subscribes to a private relay inbox (inbox:<hash(fingerprint)> — the relay never sees the raw fingerprint, and stores no contact graph). a sends a signed ContactRequest there; the recipient sees it in the Contacts pane's Requests tab and accepts to open a DM. An echo-back makes both sides converge over the relay. No huddle-server change — it's a pure client convention over the existing protocol.

• DMs persist across restarts. Pre-1.0, DMs (always encrypted) were parked as "restorable" on restart and silently dropped relay-delivered messages until reopened. Now DMs re-activate automatically at startup (their key derives from your identity + the partner's stored pubkey, no passphrase), so a conversation keeps flowing.

• Transport "doors" onto the relay (anti-censorship). huddle transports lists every door with its privacy tradeoff and whether it's usable: onion via system Tor (default, most private), onion via a private obfs4/WebTunnel bridge (for blocked-Tor networks), onion via in-process Arti (--features arti), and clearnet wss:// / ws:// to a raw IP (fast; the relay sees your IP, content stays E2E). The app tries them in a fallback order (most private first) or a pinned one (--transport). One huddle-server can serve an onion and a clearnet IP simultaneously — same rooms, same mailboxes. New flags: --clearnet-server, --transport, --transport-order, --tor-bridge.

• Per-chat transport indicator. Every DM/group header shows whether it's currently reaching peers via lan, via relay, or is offline — status only, no manual switch, so the security context is always legible. Settings → Network lists the doors + marks the active one.

• Clearnet relay needs no domain. A raw-IP ws://<ip>:<port>/ws relay works with zero extra setup (bind huddle-server to 0.0.0.0, open the port). wss:// (TLS) adds transport encryption via a real cert (a free subdomain + Caddy/Let's Encrypt, or Cloudflare Tunnel). This is the fast lane a VPN user can take when they can't bootstrap Tor.

What's new in 0.7.12 — self-review follow-ups to the 0.7.11 audit pass

A short follow-up after independent self-review of the 0.7.11 release caught three issues:

• Notification focus-default trade-off. 0.7.11 flipped the "haven't observed a focus event yet" default from false (always notify) to true (assume focused, suppress). That fixed the audit's spam complaint for tmux-without-focus-events but caused the opposite regression for the same cohort — they got zero notifications instead of all of them. 0.7.12 splits the difference: assume focused during a 5-second startup grace window, then if no FocusGained / FocusLost has ever fired, fall back to false (always notify). Terminals that DO speak focus events behave normally throughout.
• RelayReservationLost was dead-wired. 0.7.11 declared the variant and a consumer in app/mod.rs, but libp2p 0.56's relay::client::Event doesn't expose a ReservationReqFailed arm we can match on, so the producer never emitted it. 0.7.12 removes the dead variant and consumer rather than ship code that's silently unreachable. Reservation loss currently manifests as the next AutoNAT probe flipping to "private" once the circuit drops; a future health-check timer can re-introduce a dedicated signal when libp2p's API supports it.
• SAS code incompatibility documented. 0.7.11's rejection sampler is correct, but it produces different emoji codes than 0.7.10's mod 49 derivation in ~84% of pairings. A 0.7.11↔0.7.10 SAS verification will silently fail to match. This is a deliberate break (the new derivation is uniformly distributed; the old one wasn't), but it wasn't called out in the 0.7.11 notes. Both ends need to be on 0.7.11+ for SAS to succeed.

What's new in 0.7.11 — security + UX hardening pass

A wide audit pass on top of the 0.7.10 follow-up. The wire protocol, authorization gates, panic surface, modal handling, notifier, storage, clipboard, and SAS derivation all got tightened. Wire compat with 0.7.10 and earlier is broken on purpose — signed envelopes now carry a timestamp and several previously-plain messages now require a signature. The trade was deliberate: the 0.7.10 line had a few silent authentication failures that the audit caught.

Wire protocol

• MemberLeave, MemberAnnounce, and FileOffer must now arrive inside a SignedRoomMessage whose signer matches the claimed sender. Pre-0.7.11 these were plain, so any peer subscribed to a room topic could spoof another member's leave (evicting them from honest rosters) or pin a fabricated Ed25519 pubkey under a victim's fingerprint via a TOFU race.
• SignedRoomMessage gained a signed_at_ms field. The verifier rejects envelopes outside a ±5 min window — closing the indefinite replay of captured BanMember / OwnerGrant / SasConfirm / ProfileUpdate. The timestamp is signature-bound.
• Switched from Ed25519::verify to verify_strict, which rejects low-order / mixed-order pubkeys.

Invite links

• Bumped invite version to 2. v2 invites carry the creator's Ed25519 pubkey + an Ed25519 signature over the rest of the payload. Tampering with host_multiaddr, salt_b64, owner_fingerprints, or any other field is now detected before the receiver dials. v=1 invites still decode (with a "this invite is unsigned" hint) so older shared links keep working.

Authorization gaps

• The ban filter now applies to every content-bearing arm (Plain, Encrypted, FileOffer, FileChunk, Typing), not just MemberAnnounce. Banned peers in unencrypted rooms used to keep posting plaintext that honest clients rendered.
• The outbound dial-then-auto-DM flow now consults the persistent blocklist before opening a DM tab. Previously, dialing a blocked peer's address still triggered AutoOpenDm.
• send_file rejects read-only joiners (code-joined peers). Previously the read-only gate only covered send_room_message.
• The Direct-announcement auto-bootstrap rejects messages from blocked peers before creating a DM row.

Panic prevention

• now_unix returns 0 on a backwards clock instead of panicking. The network task used to crash on every encrypt/decrypt when the wall clock sat before 1970 (ARM SBCs without RTC, virt clones).
• wipe_file writes zeros in a fixed 64 KiB scratch buffer rather than allocating vec![0u8; meta.len()]. Go-dark used to OOM mid-wipe when a user had downloaded a multi-GB attachment.
• bootstrap_direct_room returns an error instead of .expect()-ing, so a transient DB write failure can't take down the spawned task.
• cleanup_expired_pending_friend_requests uses saturating_sub for the cutoff so a now < TTL clock doesn't match every row.

Critical UX

• Settings → Privacy c opens a confirmation modal before wiping the blocklist. Pre-0.7.11 it cleared everything instantly — one keystroke from total data loss, and the same c opened the join-code modal in the lobby so muscle memory was destructive.
• Clipboard yank now runs on a dedicated OS thread with a 2 s timeout. Previously, xclip/wl-copy with no display could hang the entire TUI on a routine y.
• File-chunk receiver caps per-chunk size (256 KiB), bounds chunk_index < total_chunks, and tracks bytes_received against the advertised expected_size. Pre-0.7.11 a hostile peer could advertise 1 MiB and stream multi-GB chunks before the SHA gate ran.
• DM sidebar "online" dot now compares the partner's fingerprint to known_peers[i].fingerprint instead of .label. Every DM showed ○ offline even when the partner was connected.
• The member-margin toggle is now bound to Alt+M (Ctrl+I was unreachable — terminals deliver it as Tab). Hint bar and help screen updated.
• Activity pane c now clears the status history, matching the hint text. Previously it fell through to OpenJoinWithCode.

Crypto correctness

• SAS emoji derivation switched from mod 49 (biased — indices 0..14 were twice as likely) to rejection sampling with HKDF re-expansion. Restores the full uniform distribution over the 49^7 table.
• Argon2id-derived passphrase keys returned in a Zeroizing<[u8; 32]> wrapper so they don't linger on the heap after their last use.

Network resilience

• ConnectionClosed now emits PeerDisconnected so the lobby's "online" dots clear for relay / internet peers, not just mDNS expiries. Also cleans gossipsub's explicit-peers set.
• RelayClient events are no longer swallowed — reservation status surfaces in the logs.
• DCUtR failures cap at 6 warn-logs per peer so symmetric-NAT pairs don't spam.

Modal + input

• Shift+? now opens the "what's new" card from the sidebar (the cheat sheet advertised this for a while; the handler was missing).
• Inside the command palette, Ctrl+N / Ctrl+P navigate the result list instead of typing literal n/p into the filter. Other Ctrl chords inside the palette are dropped instead of corrupting the query.
• Help / Info / QrIdentity / ShowJoinCode / ShowInvite now dismiss only on Esc / Enter / q. Pre-0.7.11 any unbound key closed them — reflexive vim-h or ? silently dismissed.
• Modal::Sas no longer cancels on bare c or q. Common letters when reading emoji words aloud used to abort the verification.
• Modal::AttachPicker no longer ascends on bare h (typo hazard).
• Ctrl+C only opens the quit-confirm modal when no modal is open. Mid-typing a passphrase / username / GoDark confirmation, an accidental Ctrl+C used to discard the typed buffer.
• Settings tab digits 1-4 require pane focus, matching the 0.7.9 Tab/BackTab fix.
• The Onboarding modal degrades gracefully on tiny terminals instead of returning a zero-rect and silently disappearing.

Storage

• Migrations now run inside BEGIN; …; PRAGMA user_version = N; COMMIT; so a partial-batch failure rolls back cleanly. Pre-0.7.11 a mid-migration error left the schema half-applied with user_version un-bumped and wedged every subsequent startup.
• After PRAGMA key, we run SELECT count(*) FROM sqlite_master as a sentinel. A wrong master passphrase now returns a clean "wrong master passphrase, or DB file corrupt" instead of a cryptic downstream CREATE TABLE error.

Notifier

• macOS / Linux / Windows notifier paths strip control characters from titles + bodies. Pre-0.7.11 a peer-controllable room name with a literal CR broke the AppleScript invocation silently.
• notify-send now passes --category=im.received for proper app-grouping in GNOME Shell / KDE.
• is_focused() defaults to true when no FocusChange event has ever been observed. tmux without set -g focus-events on and basic SSH shells no longer fire a desktop notification for every message regardless of focus.

Polish + dead code

• Removed dead let r = app.active_room() shadow, unused Theme.accent_dim, unused UnreadCounts::unread_count / pending_count. Build now warning-free at warn level.
• Mention detection bumped from a 4-hex-char prefix to 8 hex chars, cutting false positives from ~1/65 K to ~1/4 B per token and closing the trivial "include the victim's prefix to bell their terminal" weaponization.
• SAS double-fire race fixed via a finalized latch on SasFlow.
• Selected encrypted-room rows in the sidebar now preserve the magenta lock-marker color instead of stomping it to selection-yellow.
• Generate-join-code doc clarified: 31 chars / ~39.6 bits, not 32.

What's new in 0.7.10 — restore the Profile sidebar-nav gate

A follow-up to 0.7.9. Dropping the pane-focus gate on Profile's j/k/y trapped sidebar navigation: when the cursor scrolled into the Profile sub-item, sync_pane_from_selection live-previewed the pane (intentional 0.7 design), and the ungated j/k/y handler then stole every subsequent arrow/letter — so the cursor couldn't reach Direct, Group, People, Activity, or Settings without Shift+Tab'ing past it.

0.7.10 reinstates the SidebarFocus::Pane gate on j/k/y. Capital- case E / Q chords stay ungated — they don't conflict with sidebar nav and the one-keystroke discovery flow is worth keeping.

The People analogy 0.7.9 cited turned out to be sharper than it looked: People only captures j/k inside the Pending sub-tab, and reaching Pending requires Tab'ing into the pane first. Profile auto-switches on selection, so the equivalent gate is "user has explicitly Shift+→'d into the pane".

What's new in 0.7.9 — keybinding-scope fixes from a self-audit

A small follow-up patch from a self-review of the 0.7.8 release. No new features; three keybinding bugs that the 0.7.8 ship-checklist missed:

• Tab in Settings no longer swallows the focus toggle. In 0.7.8, pressing Tab anywhere in Pane::Settings cycled tabs even when the sidebar was focused, which silently disabled the universal "Tab = toggle sidebar↔pane focus" gesture for users in Settings. 0.7.9 only intercepts Tab / Shift+Tab for tab cycling when the pane itself is focused. From sidebar focus, Tab now correctly moves focus into the pane (one keystroke), then subsequent Tabs cycle.
• Profile j/k/y match People's pattern. 0.7.8 required pane focus for the Profile field cursor; People's analogous sublist nav has always worked regardless of focus. 0.7.9 makes Profile consistent — pane-active is enough to claim j/k/y, no separate focus gate.
• Dead Action::OpenSettings removed. The , chord routes through JumpToSettingsPane (which now resets to the Account tab). The legacy OpenSettings variant was unreachable in 0.7.8; removed in 0.7.9 along with its dispatcher.

What's new in 0.7.8 — three connection paths, tabbed Settings, copyable identity

A round of UX polish that borrows the right things from neighbouring apps without backsliding on huddle's privacy stance. Three discovery/connection paths now read as co-equal parallel options instead of "mDNS first, everything else as fallback", Settings became a tabbed pane that finally includes the toggles that used to live in config.toml, the Profile pane copies fields to the OS clipboard, and the People sidebar surfaces pending friend-request counts where you can actually see them.

• Three connection paths, equally surfaced. Welcome copy spells out the trio: LAN (mDNS) · direct IP dial · invite link. The Settings → Network tab shows the same three rows with their live status. A new M toggle in Settings → Network lets you disable LAN broadcast entirely for privacy — peers can still reach you over direct dial or invite link with no LAN advertisement (restart-required to apply; flipping a Toggle<Mdns> mid-run would have required a behaviour rebuild for negligible benefit).

• Tabbed Settings pane. Modal::Settings is gone. Pressing , lands you on Pane::Settings with four tabs cycled via Tab / Shift+Tab or numeric jumps 1–4:

  • Account — username (E), HD-ID, derived Safety Code (SAFE-XXXX-XXXX-XXXX), QR (Q), replay onboarding (W).
  • Network — LAN mDNS toggle (M), reachability badge, listen addresses, relay list from config.toml.
  • Appearance — placeholder (single read-only theme: dark row; light + high-contrast in a future release).
  • Privacy — verified-only inbound (V), desktop notifications (N), update check (U), blocked peers (c clears all), and the Go Dark Alt+Shift+1 chord.

• Copyable identity fields. The Profile pane is now a cursor- navigable list: j/k move, y copies the highlighted field to the OS clipboard. Username, HD-ID, Safety Code, full fingerprint, and every listen address each get their own yankable row. Clipboard helper shells out to pbcopy (macOS) / wl-copy then xclip / clip.exe (Windows) — no new crate dependency, failures degrade to a status message instead of crashing.

• Sidebar density. Direct messages and Group rooms each pin a + Add Friend / + New Group row at the top so the action is a cursor-and-Enter away, not a chord lookup. Pending friend requests surface twice in the People section: as N pending next to the section header, and as a dedicated row at the top of an expanded section when there's at least one outstanding request.

• Notifications opt-out. Settings → Privacy → N toggles the OS-native toast notifications introduced in 0.7.4. Default ON; turning it OFF skips both the per-message path and the startup catch-up summary. Notifications remain 100% local — the toggle is for users who don't want any signal leaving the terminal at all.

• No protocol changes. Only new local rows in the existing app_settings KV table (mdns_enabled, notifications_enabled). Both default to ON so existing users see zero functional change until they opt out.

What's new in 0.7.7 — friends, invites, and a fixed dial dead-end

Three coordinated UX fixes around the "first contact" flow. Dialing a peer now actually opens a chat instead of dead-ending at a connection, the People pane shows real usernames, friend requests survive longer than 15 seconds, and inviting peers to a group no longer requires pasting a link into Signal.

• Dial → DM auto-open. When you initiate a dial (d IP:port, a HD-ID, or paste-invite), the post-Identify handler now opens (or reuses) a DM with the peer and switches your pane to the new Dm(room_id). No more "connected to 192.168.1.5" status with no way to chat. Auto- reconnects and announcement-driven opportunistic dials do NOT trigger this — only paths the user explicitly chose register an address in pending_auto_dm_addrs.
• Usernames in Known peers. The People pane's Known sublist now renders each peer as username · HD-XXXX-XXXX · address · last, pulling the username from the cached peer_profiles table. Falls back to [anonymous] · HD-pending for peers we haven't yet seen a signed ProfileUpdate from.
• Row actions actually fire. The People pane header advertises m message · r reconnect · b block · x forget · u unblock, but those keystrokes were previously hitting the global handlers (e.g. m opened an empty Compose-DM modal instead of DM'ing the selected peer). Now they route to the selection-aware row actions. Tab cycles the sub-tabs (Pending / Known / Verified / Blocked).
• Friend requests survive 3 days. Previously an inbound dial modal auto-rejected (with a block_peer!) after 15 seconds. Now the 15-second timeout spills the request to a new pending_friend_requests table and just disconnects the live socket; the user has up to 3 days to Accept (re-dial + trust) or Reject (delete + block) from the People pane's new "Pending requests" sublist. A startup sweep prunes rows older than the TTL. The pane header shows (N pending) so a forgotten request from yesterday is the first thing you see on landing.
• Invite picker — pick peers and they get the link auto-DM'd. New Modal::InvitePicker (Ctrl+I inside a group room; also reachable from the + Add member row pinned at the bottom of the member margin, and from the command palette as invite peers to room…). Lists candidates in three tiers — Verified (SAS-completed, safest), DM partners (existing trust), Known peers (weakest) — with checkboxes, live / filter, soft-cap of 20 selections per send. Enter sends: each selected peer gets an idempotent DM (start_direct) containing the same invite link Shift+I produces. Shift+I (OOB link copy) is unchanged — the picker is purely additive for peers you already have some trust relationship with.

The dial-then-DM auto-open is the load-bearing fix: huddle now behaves the way a "basic social app" intuition expects — add someone, chat with them, invite them places — without users needing to memorize the fingerprint resolution flow under Compose-DM.

What's new in 0.7.6 — Go Dark single-field flow

A user report surfaced that the 0.5-era two-field Go Dark modal looked like it "didn't work" even after typing DELETE EVERYTHING. Root cause was UX, not logic: the modal required filling both a master passphrase field AND a typed DELETE EVERYTHING field, with Tab to switch between them. Default focus was the passphrase, so typing DELETE EVERYTHING straight away put the phrase into the wrong field and the validation error rendered at the bottom of an already-tall red modal — easy to miss.

• Single field, mode-aware. Sessions with a master passphrase now use the passphrase directly as the gate (the natural strong secret the user already knows — Argon2id-derived, constant-time compared). --no-master-passphrase sessions keep the typed DELETE EVERYTHING phrase as their only available gate, since they have no key to compare against.
• Loud error feedback. Wrong attempts now render ✗ <reason> with a bold red banner directly above the Enter/Esc hint bar, instead of being buried at the bottom of the modal. The input field also clears on failure so the next attempt starts fresh.
• No more Tab. Removed GoDarkNextField action and the KeyCode::Tab mapping inside the Go Dark modal arm — single field means nothing to switch to.
• New accessor AppHandle::has_master_passphrase() -> bool so the TUI can pick the right gate at modal-open time without leaking the in-memory subkey.

What's new in 0.7.5 — notifier hardening

Self-review of 0.7.4 surfaced four follow-up items. All landed in 0.7.5:

• Conservative initial focus state. 0.7.4 defaulted focused = true, which suppressed notifications if huddle launched in a terminal that was already in the background (no FocusGained event ever fired). 0.7.5 treats "no focus event observed yet" as unfocused — false positives (one extra notification) only.
• Sliding catch-up grace. The 5-second post-launch summary window now extends by 2s on every inbound message during the window, capped at a hard 30s ceiling from start. Slow gossipsub backlogs are correctly batched into one summary instead of leaking into per-message alerts.
• Notification rate-limit. A 2-second cooldown coalesces bursts: the first notification in a burst fires immediately with full detail (room / sender / preview); within the next 2s, additional notifications are counted and a single "N more new messages" summary fires when the window closes. Prevents process / thread spam for busy rooms.
• ASCII chord labels. ⌥⇧1 keycap glyphs were dropped in favor of Alt+Shift+1 (and Option+Shift+1 on macOS callouts where it helps) — fonts render the Unicode keycaps too inconsistently across terminals. The Mac runtime behavior is unchanged (the ⁄ glyph and the ALT|SHIFT+! event both still trigger Go Dark).

What's new in 0.7.4 — desktop notifications + safer go-dark chord

• Desktop notifications when the terminal isn't focused. Every inbound message fires a native notification (osascript on macOS, notify-send on Linux, PowerShell BalloonTip on Windows — no extra dependency) when crossterm reports the terminal as unfocused. Notifications include the room name, sender display name, and a trimmed message preview. When the terminal IS focused, no notification is sent — the message is already on screen and the unread badge does the work.
• Catch-up summary on startup. When huddle reopens, messages received during a 5-second catch-up window are batched into ONE notification: huddle · N new messages while you were away. After the window closes, real-time notifications kick in.
• Focus reporting via crossterm EnableFocusChange. Supported by iTerm2, Terminal.app, Alacritty, Kitty, wezterm, Windows Terminal, and GNOME Terminal. On a terminal that doesn't emit FocusGained / FocusLost, the app stays in "focused = true" mode and never fires per-message notifications — graceful degradation.
• Go dark rebound to Alt+Shift+1 (Option+Shift+1 on macOS). Plain ! was just Shift+1 — one accidental keystroke could open the destructive flow. The Mac chord works out of the box on Terminal.app via the unicode glyph ⁄ that Option+Shift+1 produces, AND via the ALT|SHIFT+! event that Alt-as-Meta terminals emit. On Linux/Windows the same Alt+Shift+1 chord is uncontested.
• First-time macOS notification permission prompt. macOS will ask to allow Script Editor (or Terminal) to send notifications the first time huddle fires one. Click Allow once and you're set.

What's new in 0.7.3 — UX polish round 2

• Focus-jump rebound to Shift+← / Shift+→. 0.7.2's Ctrl+← / Ctrl+→ collided with macOS Mission Control's Move-between-Spaces shortcut (and Cmd+← / Cmd+→ is Terminal/iTerm2 tab-switching, ruling that out too). Shift+arrows are unclaimed everywhere.
• Sidebar cursor is visible again. The previous bg-only highlight on the selected row used Color::Rgb(40, 40, 60) which is near-indistinguishable from default terminal bg on Terminal.app. Selected rows now recolor every span's foreground to yellow (warn) when the sidebar is focused, dim text when not — readable on every dark theme.
• 2-col gutter between sidebar and pane. Panes with Borders::NONE (Welcome, Profile) used to render text flush against the sidebar separator line. The outer layout now inserts a 2-column gap before the pane rect, so every pane has visible breathing room.
• Settings pane keybindings actually fire. The pane displays V verified-only / U update check / E username / W replay onboarding / ! go dark — but 0.7.0–0.7.2 only dispatched those inside the Settings modal, leaving the pane rows inert. They now fire from the pane itself.
• ! (go dark) is global. Previously only available from the Settings modal; now reachable from any non-chat pane. The modal's two-factor passphrase + "DELETE EVERYTHING" confirm protects against accidental triggers.

What's new in 0.7.2 — UX polish

• Ctrl+← / Ctrl+→ focus jump between sidebar and pane (works from any context, including while typing in chat input). One keystroke instead of Esc → Tab. macOS users may need to disable Mission Control's Move-left/right-a-space shortcut (System Settings → Keyboard → Keyboard Shortcuts → Mission Control). When focus jumps to a chat pane, the input is auto-activated so you can type immediately.
• Settings pane padding fix. The value column was jammed flush against the label column when a label was exactly 24 chars wide (update check (crates.io)on rendered with no gap). Labels now pad to 28 chars, guaranteeing visible whitespace before every value.
• Sidebar focus border continues to highlight which region owns the keystrokes (already shipped in 0.7; surfaced more clearly with the new focus-jump bindings).

What's new in 0.7.1 — E2E DMs

Direct messages are now end-to-end encrypted on the room layer.

• New crate::crypto::dm::derive_dm_key derives a 32-byte room key from one side's Ed25519 secret seed and the other side's Ed25519 public key via X25519 ECDH + HKDF-SHA256.
• start_direct creates DMs as encrypted = true with the ECDH-derived key as the Megolm wrap key. The "passphrase salt" slot stores the canonical room_id so re-bootstraps re-derive identically.
• When we don't yet have the partner's pubkey (e.g. fingerprint resolved from a QR / invite / username), the room is created with no wrap key. The next MemberAnnounce from the partner carries their pubkey; we derive the key lazily, then re-broadcast our own MemberAnnounce with the wrapped Megolm session key.
• Backward compatibility: DMs created against pre-0.7.1 peers stay in their original encrypted=false mode (the rooms table records it). New 0.7.1+ DMs are always E2E.

What's new in 0.7 — TUI 2.0

0.7.0 rewrote the TUI around a sidebar + pane layout (Discord/Slack-style), with explicit separation of Direct messages from Group rooms. The legacy Screen::{Lobby, InRoom} flat-screen model and the tab-bar were retired.

See TUI layout and Key bindings for the current state. Notable shipped items:

• New RoomKind::{Direct, Group} persisted on the rooms table; RoomAnnouncement.kind (serde-default for back-compat) tags every wire announcement so 0.7 peers can split DMs from groups.
• Canonical DM room IDs: sha256("huddle-dm-v1\0" || min(fp_a, fp_b) || "\0" || max(fp_a, fp_b)) — both peers, regardless of who presses m first, derive identical IDs. start_direct is idempotent across both peers and reinstalls.
• DM-visibility filter at honest 0.7+ consumers: Direct announcements addressed to anyone else are dropped, so a DM never leaks past the two participants' sidebars.
• 2-member cap enforced locally on RoomKind::Direct rooms.
• New panes: Profile, People (known + verified + blocked sublists), Activity (status history + transfers), Settings (toggles, blocked peers, go-dark).
• New Modal::ComposeDm with inline autocomplete from known_peers + peer_profiles; falls back to AddFriend semantics on unrecognized input — no modal-on-modal.
• Centralized Theme module so colors live in one place.

Retired in 0.7: Screen::{Lobby, InRoom}, the tab-bar, numeric 1..9 tab jumps, Ctrl+B (back-to-lobby in chat — Esc focuses sidebar instead), LobbyFocus (replaced by SidebarFocus), the flat discovered_rooms list (now split into DM / Group sections).

What's new in 0.6 (UX overhaul)

0.6.0 is a focused UX release. The protocol surface didn't change; the TUI did.

• Command palette (: or Ctrl+P) — fuzzy-search every action. Drives discoverability without bloating the visible chrome. You no longer need to remember a/d/i/,/c/I/v/!/u/o/^J/^I/^K/^G/^V to find things.
• Notification history (Ctrl+H) — the last 100 status-bar messages, scrollable, with timestamps. Replaces the "goldfish" status bar where two events in quick succession overwrote each other.
• Help is now generated from input.rs — every keybinding is documented, scroll with j/k. Help is sectioned by context (Lobby / In a room / Card focus / etc.) and can never drift from the actual key map again.
• Onboarding versioning — the welcome card now re-fires only the "what's new in X.Y" page when you upgrade between versions. You can also replay it any time from Settings → w.
• Pending-modal indicator — when an async event (inbound dial, rotation, error) arrives behind another modal, the status bar shows [N pending · Ctrl+H to view] so it never silently disappears. Queue is FIFO and capped at 16.
• Adaptive hint bar — the bottom-of-screen hints rotate based on what's most likely to be useful next (empty lobby surfaces "add friend"; unread tab surfaces "join"; etc.).
• Lobby header polish — huddle 0.6.0 version anchor, clock, live peer counter alongside the NAT reachability badge.
• Scroll indicator + day separators in chat — the message pane shows N/M · live (or N/M · ↑ K above) at the bottom border, and date dividers (─── 2026-05-15 ───) appear when conversations span days.
• Unread counts in tabs — [2] room-name (3) shows the actual count instead of a vague *. R (shift-r) in the lobby zeros every tab at once.
• Opt-in update detection — a tiny ureq-backed background task pings https://crates.io/api/v1/crates/huddle once per 24 h. If a newer version exists, a banner appears under the lobby header. OFF by default; toggle via Settings → U or the command palette.
• huddle doctor CLI — huddle doctor prints version, data paths, file sizes, and config without touching the network or asking for the master passphrase. Paste it into bug reports.

Testing

cargo test --workspace -- --test-threads=1

--test-threads=1 keeps the mDNS-based integration tests from fighting each other on a single host. The suite covers two-node plain + encrypted round-trip, Phase A inbound-dial accept and reject, Phase B kick-and-rotate (3-node), and Phase F code-join. See MANUAL_TESTING.md for the two-machine checklist.

Data directory

• macOS: ~/Library/Application Support/huddle/
• Linux: ~/.local/share/huddle/
• Windows: %APPDATA%\huddle\

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.