DEV Community

Ahmad Faraz
Ahmad Faraz

Posted on

I built an end-to-end encrypted chat app for the terminal (and the browser)

I wanted a chat app with no accounts, no sign-up, and no server that could read my messages — one I could run from a terminal. So I built shhterm.

Create a room, get a secret key, share it. Anyone with the key joins and chats. Messages are end-to-end encrypted, so the server only ever relays ciphertext.

shhterm demo


The idea

Most "secure" chat apps want your phone number, an account, and a lot of trust. I wanted the opposite:

  • No accounts. A random room key is the only credential.
  • Nothing stored. Rooms and messages live only in server memory and are never logged. Empty rooms vanish after 5 minutes.
  • The server can't read your messages. End-to-end encryption, not just TLS.
  • Runs anywhere — terminal on macOS/Linux/Android, any browser (including iPhone), or fully offline on a local network.

The stack

  • C++20 for the server and terminal client
  • Boost.Asio for asynchronous networking
  • OpenSSL for TLS + the crypto primitives
  • FTXUI for the terminal UI (colored names, themes, typing indicators)
  • A browser client using the Web Crypto API
  • CMake + Ninja, with CI on GitHub Actions

How it works

shhterm is client–server: everyone connects to one server, which routes messages between members of a room. Clients never talk directly to each other.

  You ─┐                          ┌─ Friend
       ├──►  shhterm server  ◄──┤
  Web ─┘    (relays ciphertext)   └─ Terminal
Enter fullscreen mode Exit fullscreen mode

The interesting part is how the server routes messages it can't read.

The split-key design

The room key has two halves:

  • a routing half the server uses to find the room, and
  • a secret half that never leaves the clients.

The secret half derives the message-encryption key via HKDF-SHA256. Because the server only ever receives the routing half, it can match you to a room but has no way to derive the key. Each message is encrypted with AES-256-GCM and a fresh nonce; the server just forwards the opaque blob.

full key  =  [ routing half ]  +  [ secret half ]
                   │                     │
             sent to server       stays in client → HKDF → AES-256-GCM key
Enter fullscreen mode Exit fullscreen mode

What E2E does not hide (and I'm upfront about this in the README): metadata the server must act on — usernames, who's in a room, and message size/timing.

Three bugs that taught me something

1. Keeping C++ and JavaScript crypto byte-compatible

The terminal client encrypts in C++ (OpenSSL); the browser encrypts in JavaScript (Web Crypto). For a browser user and a terminal user to read each other, both must produce identical ciphertext layout and derive the identical key.

I wrote an interop test that encrypts in one language and decrypts in the other, both directions:

C++ encrypt -> JS decrypt : PASS
JS  encrypt -> C++ decrypt: PASS
Enter fullscreen mode Exit fullscreen mode

A subtle gotcha: HKDF with an empty salt. OpenSSL and Web Crypto both follow RFC 5869, and because HMAC zero-pads short keys, an empty salt and a "HashLen of zeros" salt produce the same result — so they interop cleanly. Verifying that with an actual round-trip test (rather than trusting the spec) saved me later.

2. A relay that crashed on a bad URL

The web gateway bridges browser WebSockets to the C++ server. Internet scanners constantly hit any public server with malformed URLs like /%ZZ. decodeURIComponent throws on those, and one uncaught exception took down the entire gateway — dropping every active connection. Users saw "disconnected."

Lesson: a network relay should never die from one bad request. Wrap the parse, and add a last-resort guard:

try { urlPath = decodeURIComponent(req.url.split("?")[0]); }
catch { res.writeHead(400).end("bad request"); return; }
Enter fullscreen mode Exit fullscreen mode

3. Share links that served HTML as JavaScript

/room/<key> links let someone open a room directly. But the page loaded its scripts with relative paths (src="app.js"), so on /room/<key> the browser requested /room/app.js — which my SPA routing served as index.html. The browser tried to execute HTML as JS and threw Uncaught SyntaxError: Unexpected token '<'. The whole app silently failed to initialize.

Fix: absolute script paths (/app.js), plus serving the SPA shell only for extensionless routes. Classic SPA footgun, obvious in hindsight.

Bonus: it works with no internet at all

One mode I'm weirdly proud of: a single command spins up a local server on your machine, and anyone on the same WiFi/LAN connects to it — no cloud, no internet. Great for an office or a flight.

./scripts/run-lan-server.sh   # auto-detects your LAN IP, makes a cert, prints the connect command
Enter fullscreen mode Exit fullscreen mode

Try it

# Terminal (macOS/Linux)
git clone https://github.com/AhmadFaraz-crypto/shhterm && cd shhterm
cmake -S . -B build -G Ninja
cmake --build build
./build/shhterm create --name YourName
Enter fullscreen mode Exit fullscreen mode

Or just open https://shhterm.duckdns.org in any browser — including an iPhone.

Honesty section

This is a hobby/educational project, not a hardened or audited product. It's end-to-end encrypted and I've tried to be careful, but please don't use it for anything where real-world confidentiality matters. The security model (and its limits) is documented in the repo.

It's open source under MIT — feedback, issues, and PRs are very welcome.

Thanks for reading! What would you add — message reactions, file sharing, forward secrecy? I'd love to hear it.

Top comments (0)