Shade/THREAT-MODEL.md

Threat Model

This document describes what Shade protects against and what it doesn't. Read this before deploying Shade in any context where the answers matter.

Assets

The thing we're protecting:

• Message plaintext — the actual content of encrypted messages between peers
• Identity private keys — long-term Ed25519 signing key + X25519 DH key
• Session state — Double Ratchet root keys, chain keys, DH keypairs

Adversaries we consider

1. Network attacker (active)

Can intercept, modify, drop, replay, and inject network traffic between clients and the prekey server, and between two clients.

Mitigations:

• All identity-key writes to the prekey server are signed (Ed25519). Tampering is detected.
• Signed requests have a 5-minute replay window.
• The Double Ratchet binds message headers to ciphertext via AES-GCM AAD, so header tampering breaks decryption.
• Forward secrecy: even if an attacker captures all traffic, compromising a key later doesn't help them read past messages.

NOT mitigated:

• Initial session establishment can be MITM'd if users don't verify identity fingerprints. The prekey server could distribute a fake bundle on first contact. Always compare safety numbers out-of-band for high-stakes communications.

2. Malicious or compromised prekey server

The server holds identity public keys and prekey bundles. It can serve them to anyone.

Mitigations:

• The server only stores PUBLIC keys, never private ones.
• Write operations are signed with the identity private key, so the server can't forge new identities or replenishments without the user's key.
• Bundle fetches are unauthenticated, so a malicious server can serve fake bundles. Detection requires out-of-band fingerprint comparison.

NOT mitigated:

• A malicious server can substitute one user's prekey bundle with the server operator's own keys, enabling MITM at session establishment. Users must verify safety numbers to detect this.

3. Compromised endpoint (post-compromise)

Attacker briefly gains code execution or filesystem access on a user's device, exfiltrates session state, then loses access.

Mitigations:

• Forward secrecy: messages sent BEFORE the compromise cannot be decrypted with the leaked state. Old chain keys are zeroed after use.
• Post-compromise security: as soon as a peer initiates a new DH ratchet step, the leaked state becomes useless for new messages.
• Memory zeroization: message keys and chain keys are wiped from JS memory after use (best-effort — V8 may retain copies).

NOT mitigated:

• An ongoing endpoint compromise can read messages in real time and exfiltrate identity private keys.
• Attackers with persistent access can intercept new identity rotations.

4. Compromised device storage

Attacker gains access to the persistent storage (e.g., steals the SQLite file or dumps the PostgreSQL table).

Mitigations:

• Stored data includes private keys but is unencrypted at rest. Shade does NOT encrypt the storage layer — it assumes the database is in a trusted environment.

NOT mitigated:

• Filesystem-level encryption (LUKS, FileVault) is the user's responsibility.
• Database TLS in transit is the user's responsibility.

5. Side-channel attacks (timing)

Attacker measures timing of identity verification operations to recover key bits.

Mitigations:

• All comparisons of secret material use constant-time XOR-accumulator comparison (constantTimeEqual).
• AES-GCM and the underlying primitives are constant-time as implemented by SubtleCrypto and @noble/curves.

NOT mitigated:

• JavaScript JIT compilation can introduce timing variability that's hard to control.
• We don't claim resistance to power-analysis or fault-injection attacks (out of scope for a JS library).

6. Denial of service

Attacker floods the prekey server to exhaust resources or one-time prekeys.

Mitigations:

• Per-IP rate limiting on registration and bundle fetches.
• Per-identity rate limiting on replenish and delete.
• 64KB body size limit on POST endpoints.
• Address validation rejects path traversal and malformed inputs.

NOT mitigated:

• Application-level DDoS at the network layer is your hosting platform's responsibility.

Assumptions

1. The user has a secure way to bootstrap trust. Either:
   • Trust on first use (TOFU) — accept the first identity key seen for a peer
   • Out-of-band verification — compare safety numbers in person/video before trusting
2. Cryptographic primitives are sound. We trust X25519, Ed25519, AES-256-GCM, HKDF-SHA256, HMAC-SHA256.
3. The runtime is honest. A malicious Bun/Node/browser runtime can defeat any JS library.
4. The prekey server is reachable. If it's offline, new sessions can't be established (but existing sessions continue working).

Residual risks

Risk	Severity	Mitigation
MITM at first session establishment	High	Compare safety numbers out-of-band
Identity private key theft from device	Critical	Filesystem encryption, secure enclave (future)
Prekey server operator runs a "key oracle" attack	Medium	Distributed/federated prekey servers (future)
Side-channel via JIT timing variability	Low	Constant-time primitives reduce but don't eliminate
Metadata visibility to prekey server	Low	Acceptable for most use cases; mix networks for stronger metadata protection