Architecture
Trust model
On this page
The Pug Network server is a blind relay. It is structurally incapable of reading the conversation it carries. This page explains exactly what that means, why the construction works, and what the worst-case server breach actually exposes.
What the server sees vs. does not see
| The server sees | The server does not see |
|---|---|
| Room ID (random, opaque) | Room secret (lives in URL fragment) |
| Connection lifetimes | AES-256-GCM key (lives in URL fragment) |
| Ciphertext byte counts | Message contents |
| IP addresses (during the TCP session, not logged) | Sender identity beyond a per-connection ephemeral ID |
Why the server cannot decrypt
A room link has the form:
https://host/r/<roomID>#<base64(roomSecret ‖ AES-256-GCM key)>
Per the HTTP specification
(RFC 3986 §3.5),
browsers never transmit the URL fragment (the #…
portion) in any HTTP request. This is not a Pug Network policy — it is a
bedrock rule of the URL standard, implemented identically in every browser
on the planet.
The key material therefore exists only in:
- The room creator's browser (which generated it locally via the Web Crypto API), and
- Any browser the link is shared with out-of-band.
The server has never possessed the key and cannot be compelled to produce it. There is no key-escrow path, no operator override, no debug build that unlocks anything — the key simply is not present in the server's address space.
The room secret is a separate 16-byte value, also carried in the URL fragment. It is required to join a room and is checked in constant time on the server. The AES-GCM key is a separate 32-byte value, also in the fragment. The server sees neither.
Why this matters operationally
Run through the worst-case scenarios one at a time. None of them expose message contents:
- Server compromise. An attacker with full root on the host can read process memory and intercept traffic, but the in-flight ciphertext is still ciphertext and the key never enters the host.
- Coerced operator. A subpoena, a court order, or a man with a wrench cannot extract a key the operator has never had.
- Forensic image of RAM. Same outcome. The key lives in the participants' browsers, which are not on the server's machine.
- Logging misconfiguration. The most you can accidentally log is metadata — connection lifetimes, room IDs, ciphertext byte counts. Pug Network's default configuration logs none of this.
- Backup leak. There is nothing to back up. Rooms are in-memory only.
The worst-case server breach reveals: who connected to which opaque room ID, and when. It does not reveal what was said.
What this trust model does not cover
Pug Network's trust model is honest about what is in scope and what is not. The following are not defended against:
- Endpoint compromise. If your laptop is owned, the attacker can read everything you can read. End-to-end encryption protects the wire and the server, not your screen.
- Out-of-band link interception. If you share the room URL over an insecure channel, anyone who sees that channel sees the URL — and the URL is the entire credential set. Share full URLs only over channels you trust.
- Operator-level metadata. A determined operator can observe who connects to which room IDs and correlate with timing. Pug Network does not currently mix or shuffle this metadata.
- Adversaries on the network path who control TLS. Standard TLS protections apply; Pug Network does not pin certificates beyond the browser's default trust store.
For the explicit list of features that have been deliberately excluded (and why), see What it is not.