The first line of defense ensures that only someone physically present in the same room can initiate a secure connection.
- Rotating QR Code: Refreshes every 3 seconds with a new payload containing the session ID, server endpoint, and certificate fingerprint.
- 4-Digit Verification Code: Displayed alongside the QR code. Must be entered manually by the user.
- IP Highlight Confirmation: The server IP is prominently displayed on screen. The user must visually confirm it matches their device's network.
Trust anchor: The act of scanning the QR code is assumed to be private (no one else can see the screen).
Trust On First Use (TOFU) pins the server's public key fingerprint to the QR code payload.
- The QR code contains a SHA-256 hash of the server's public key.
- The client verifies this fingerprint on first connection and stores it.
- Any subsequent connection with a different fingerprint is rejected (MITM detection).
This defends against ARP spoofing, DNS hijacking, and other LAN-level MITM attacks.
The core security mechanism. A single handshake code can only be verified once.
States: Idle → Active → Consumed | Expired
- Atomic state transitions: Uses
tokio::sync::RwLockto prevent race conditions. - One-code-one-verify: After verification, the state immediately transitions to
Consumed. Any replay attempt returns HTTP 409 Conflict. - Brute-force protection: After max attempts (default 3), the state transitions to
Expired. Returns HTTP 410 Gone. - Constant-time comparison: Uses
constant_time_eqto prevent timing side-channels.
After successful handshake, the client receives two tokens:
- Access Token: Short-lived (5-15 minutes, random expiry). Used for API access.
- Refresh Token: Long-lived (1 hour). Bound to the TLS channel via a channel binding hash.
Channel binding prevents token reuse across different TLS sessions. If an attacker steals a Refresh Token, they cannot use it without the same TLS channel.
All randomness comes from the OS kernel:
getrandomon Linux/macOSBCryptGenRandomon Windows (viarand::rngs::OsRng)
No application-layer entropy mixing. We trust the kernel's ChaCha20-based CSPRNG.
Sensitive data is protected in memory:
- mlock / VirtualLock: Prevents memory pages from being swapped to disk.
- zeroize: Sensitive data is explicitly overwritten with zeros when dropped.
- SecureToken / SecureMemory / SecureString: Wrapper types that enforce these protections.
- NIC binding: The server only binds to specific network interfaces. Binding to
0.0.0.0is explicitly forbidden. - Traffic padding (optional): Constant-rate padding packets to obscure traffic patterns.
See THREAT_MODEL.md for the complete threat model and security assumptions.