How Tunnls works

End-to-end encryption

All conversation content — field values in both directions, and the labels the operator writes to describe those fields — is encrypted in the browser before it hits our servers. The server sees ciphertext, not plaintext, and never handles the keys that could decrypt it.

• Each side generates an ephemeral ECDH P-256 keypair on page load. Private keys never leave the browser.
• Public keys are exchanged as JWKs through the Phoenix channel. The server relays them but cannot derive the shared secret without one of the private keys.
• Both sides run HKDF-SHA-256 over the ECDH shared bits, salted with the 9-digit room code, to derive a per-session AES key.
• Each envelope is encrypted with AES-GCM (96-bit nonce, 128-bit tag). Additional authenticated data binds the ciphertext to room_code:field_id:kind:from:version:seq, where kind is value or label and from identifies the sending party — so a replayed or mis-routed envelope, or one reclassified by the server as the wrong kind or from the wrong side, fails to decrypt.
• What the server does see: field count, field ordering, the coarse type of each field (text, phone, email, date) — used to pick the right input keyboard and formatting on the visitor's device — and a timestamp on each message the operator sends to the visitor (used for the "sent at HH:MM" label that appears on both sides). The actual label text ("SSN", "DOB", etc.) and the message body itself are encrypted. If you're not comfortable with the server knowing the broad category of a field, set every field to text; no category is ever required.
• Key lifetime in the browser: the derived AES session key is cached in sessionStorage for the duration of the browser tab, so a page reload mid-session doesn't force a re-handshake. The ECDH private key is not persisted — it exists only in memory and dies on reload. When the session ends (either party clicks End, or the server's reaper times it out), the client wipes the cached key from sessionStorage.

The verification handshake

ECDH with server-relayed keys is vulnerable to an active server swapping both public keys — a classic man-in-the-middle. The bingo-ball handshake closes that gap with an out-of-band human channel.

• Both browsers HKDF-derive the same 5×5 grid from the session key. An active attacker with swapped keys derives a different grid on each side.
• The visitor picks three positions; the operator and visitor read those values aloud (phone, in-person, whatever out-of-band channel the two parties already trust).
• If the strings match, the keys weren't swapped. If they don't, something is wrong — end the session.

The session sandbox

A Tunnls session is a memory-only Erlang GenServer process. It exists for the duration of one conversation and dies when the operator ends it, the visitor disconnects, or the reaper timeout fires.

• In-memory only: session state — encrypted field values, encrypted field labels, pubkeys, and handshake positions — lives in the GenServer's state and nowhere else. No disk, no database, no log lines.
• What we do persist: operator accounts (email, hashed password), billing info (indirectly, through Stripe), and one session_events row per session for free-tier quota accounting. That row contains operator_id, room_code, and a timestamp — nothing about the conversation.
• Session end is terminal: when the GenServer exits, the state is garbage-collected by the BEAM. No rehydration path exists because no snapshot was ever taken.
• Two session shapes, one crypto pipeline: sessions come in two flavors — field collection (operator configures labeled fields the visitor fills) and live conversation (each party has a single text area the other sees update live). Both run the exact same encryption primitives; the difference is purely a rendering and ownership choice above the envelope layer.
• Process supervision and registry details are in lib/tunnel/session/ if you want to read the implementation.

Open-source crypto library

The entire E2E path — keypair generation, key agreement, HKDF, AES-GCM encryption, bingo-grid derivation — lives in a standalone, MIT-licensed library:

github.com/greghgradwell/tunnls-e2e

The web app pulls it in as a git submodule under assets/vendor/tunnls-e2e/. Nothing in the application code re-implements or overrides the crypto path — what you audit in the repo is what runs in the browser. You don't have to trust us on the encryption claims; audit the library yourself.