# pvtcoms — Threat Model

> A maintained artifact. It states **what pvtcoms protects, against whom, and — crucially — what it does NOT protect.**
> Honesty about the boundary is itself a security feature: users must not over-trust "post-quantum + Tor."
> Companion to [`README.md`](./README.md) and [`DESIGN.md`](./DESIGN.md). Last updated 2026-05-30.

---

## 1. Assets we protect
1. **Message content** — text, media, voice/video (notes and calls).
2. **Who-talks-to-whom (the social graph)** — the hardest and most valuable asset.
3. **User identity / anonymity** — no link to a phone, email, legal name, or stable network identifier.
4. **Presence & behavioural patterns** — when you're online, sleep/timezone, routine.
5. **Contact list & relationships** — stored only locally.
6. **Long-term identity keys & session state** — must never leave the device in usable form.
7. **The fact that you use pvtcoms at all** (where feasible).

## 2. Security goals
- **Confidentiality** — end-to-end, post-quantum (`X25519+ML-KEM-768`); content unreadable by any third party, including a future quantum computer.
- **Forward secrecy & post-compromise security** — per-message key rotation (Double Ratchet); a stolen key can't read the past, and the session self-heals after a one-time compromise.
- **Authenticity / integrity** — messages provably from the verified peer; tampering detected.
- **Deniability** — no cryptographic proof, after the fact, that a specific person sent a specific message.
- **Metadata minimisation** — no central server learns the social graph; rotating unlinkable addresses; pull-not-push presence.
- **Anonymity** — no phone/email/global ID; IP hidden via Tor; rotating identities.
- **Local data protection** — at-rest encryption; safe against another app and offline/seized-disk extraction (device locked).

## 3. Adversaries (by capability)

| # | Adversary | Capability | In scope? |
|---|---|---|---|
| A1 | **Network eavesdropper** (ISP, Wi-Fi, local) | Reads/manipulates traffic on the wire | ✅ Defended (E2EE + Tor) |
| A2 | **Malicious / compelled relay or mailbox operator** | Runs infrastructure your traffic crosses | ✅ Defended (oblivious mailbox, content + routing E2E; operator learns nothing linkable — gated relays use a *shared* access capability, not per-identity signatures, so the operator still can't tell members apart; ADR-005) |
| A3 | **Global passive adversary** (nation-state watching much of the internet) | Correlates timing/volume across the whole network | ⚠️ Partial — Tor is weak here; padding/jitter/cover help; **Nym mixnet** is the real (future) answer |
| A4 | **The person you're talking to** | Is a legitimate endpoint | ⚠️ Bounded — can screenshot/record/forward; can't be prevented, only deterred; **verify identity (SAS)** to ensure it's really them |
| A5 | **First-contact MITM** | Intercepts/substitutes during initial key exchange | ✅ *Detectable* via mandatory out-of-band SAS/QR; not preventable by crypto alone |
| A6 | **Thief of a shared invite link** | Grabs the QR/code from an insecure channel | ✅ Defended — single-use self-detecting links (theft → victim's connect fails loudly) |
| A7 | **Forensic extraction of a seized, LOCKED device** (Cellebrite-class) | Physical possession, device locked | ✅ Defended at rest (SQLCipher + hardware-keystore + memory hygiene + short retention + duress wipe) |
| A8 | **Other malicious app on the same device** (no special privilege) | Normal app on an intact OS | ✅ Defended (OS sandbox + hardware keys + FLAG_SECURE + clipboard hygiene) |
| A9 | **Spammer / flooder** | Anonymous mass-messaging | ✅ Mostly — rotating single-use mailboxes + request-bound PoW gate (+ optional shared-capability access gate for private relays, ADR-005); no global identity to abuse |

## 4. Explicitly OUT OF SCOPE (we cannot defend — state plainly to users)

| # | Threat | Why it's out of scope |
|---|---|---|
| O1 | **Compromised / rooted / jailbroken OS, or 0-click mercenary spyware** (Pegasus/NSO, Paragon "Graphite" — which owned *fully-patched* iPhones, CVE-2025-43200) | Once the OS/kernel is owned, the attacker reads plaintext, keys, screen, and keystrokes directly. Sandbox, Keystore, SQLCipher, FLAG_SECURE are all bypassed. This is an OS-vendor responsibility. |
| O2 | **User-granted malicious accessibility service or full-access keyboard** (e.g. Sturnus, 2025 — reads Signal/WhatsApp plaintext *post-decryption*, bypasses FLAG_SECURE) | The user authorised it; an app can warn but cannot block what the OS lets an accessibility service see. |
| O3 | **Endpoint capture by humans** — shoulder-surfing, a second camera photographing the screen, an unlocked device in an attacker's hands | No software defeats a camera or a logged-in attacker. |
| O4 | **The human-authenticity gap at first contact** | Crypto can't prove the human who received an invite is the intended person — only the user doing the SAS/QR check can, and only if they actually do it. |
| O5 | **The user's own behaviour** — sending an invite carelessly, skipping verification, screenshotting, weak/forgotten passphrase, backing up plaintext elsewhere | Outside the protocol's control; mitigated by honest UX and safe defaults, not guarantees. |
| O6 | **Global traffic-correlation by a true global passive adversary** while on Tor (until the Nym path ships) | Tor doesn't defeat a global observer; this is a known limitation we mitigate, not eliminate, in v1. |
| O7 | **Targeted compromise of a self-hosted relay the user chose** (e.g. a direct/relayed call) | If the user opts into a direct/relayed mode, the trust/metadata cost is theirs by design. |

> **The one-sentence boundary:** *pvtcoms protects the network/transport (serverless P2P, Tor, post-quantum E2EE, oblivious
> mailboxes) and on-device data against other normal apps and offline/seized-disk extraction — provided the OS is intact and
> the device is locked. It does NOT protect plaintext endpoints against a compromised OS or user-granted spyware; that is the
> device/OS-vendor trust boundary.*

## 5. Trust assumptions
- The **device OS and hardware are intact** (not rooted/compromised). *If false, all bets are off.*
- The user **performs out-of-band verification (SAS/QR)** for any contact whose authenticity matters.
- The user keeps a **strong DB passphrase** and a **safe recovery secret** (key loss = identity loss).
- **No trust in any server/relay** for content or social-graph privacy (that's the design goal).
- Cryptographic primitives (`X25519`, `ML-KEM-768`, `ML-DSA-65`, `ChaCha20-Poly1305`, `SHA-2/3`, `BLAKE3`) are sound as currently understood.

## 6. Residual risks & mitigations (accepted, not eliminated)
- **Traffic correlation on Tor** → fixed-size blocks, randomised latency/jitter, cover traffic; prioritise the Nym path.
- **First-contact MITM if SAS is skipped** → default UI to "unverified", nudge verification, block on key change.
- **Endpoint compromise** → minimise on-device data (disappearing messages default), tiny binary + fast updates, recommend GrapheneOS for high-threat users.
- **Bleeding-edge PQ ratchet** → ship the mature PQ *handshake* first; version-gate the ongoing PQ ratchet.
- **Mobile push reintroducing metadata (iOS)** → oblivious APNs relay (encrypted envelope) only; pull-not-push elsewhere.
- **Offline store-and-forward at rest** (ADR-009) → offline messages sit encrypted on the oblivious relay under rotating, identity-unlinkable tokens (the relay sees only a counter + padded ciphertext — no sender/recipient/mix-header/length), and media sits in a **decoupled** bulk store as uniform, random-id'd, padded chunks whose key never leaves the E2E channel. Forward secrecy from a per-message symmetric chain; post-compromise security re-injected whenever a one-time hybrid prekey (`X25519+ML-KEM-768`) is available, **fail-closed** otherwise. Residual: a leak of the pairwise root `R` exposes message metadata + content only **up to the next PCS mix-in** (then it heals); `chunk_count` leaks a coarse media-size bucket. The relay/bulk store remain untrusted by construction.

## 7. Posture by user tier
- **Everyday privacy user:** default app, Android/desktop, safe defaults — strong against A1–A2, A6–A9.
- **High-threat (journalist/activist/source):** dedicated **GrapheneOS** device, in-person/voice-verified contacts only, disappearing messages, no live calls (async notes), duress passcode — pushes toward defending A3/A4 within the stated limits; still cannot beat O1.

## 8. Maintenance
This document is **versioned and reviewed** every release and whenever a subsystem changes. New adversary capabilities (new
spyware, new OS side-channels) are added as discovered. A **named third-party audit** (Quarkslab/Cure53/Trail of Bits/NCC) of
the PQ crypto + Tor integration + mailbox protocol is a **release gate** before any "secure/anonymous" claim is made publicly.