# pvtcoms — Master Plan

> A private, **serverless, peer-to-peer, anonymous, post-quantum** encrypted messenger.
> Android · Desktop (Windows/Linux/macOS) · iOS (constrained — see §7). Legally neutral; the user is responsible.
>
> This README is the **organized front door**. The deep technical detail lives in **[`DESIGN.md`](./DESIGN.md)** (§1–15),
> reconciled across three independent advisors — **Claude** (web research, 2025–2026), **Codex**, and **Gemini** — over
> several design rounds. Last updated 2026-05-30.

---

## What it is, in one paragraph
pvtcoms is closest in spirit to **SimpleX Chat**, pushed further: serverless DHT-style rendezvous, a **Rust** core, and
**post-quantum** crypto from day one. It borrows proven designs (SimpleX oblivious mailboxes, Signal PQXDH/Triple-Ratchet,
Briar's pull-not-push) and is honest about the three things that can't be wished away: the **anonymity ⊕ instant ⊕ battery**
trilemma, **first-contact MITM**, and **mobile push notifications**. Where those bite, we ship honest modes, not magic.

## Non-negotiables
1. No central server owns messages. 2. Anonymous & unlinkable (no phone/email/global ID; rotating addresses).
3. Post-quantum. 4. Cross-platform from one core. 5. Legally neutral — no built-in illegal features.

## Positioning (decided direction)
An **uncompromised tool for privacy-conscious users, journalists, activists, and high-stakes professionals** — *not* a
WhatsApp clone. Embrace the friction (occasional latency, more battery); privacy is the feature. Don't paper over it with
convenience that leaks.

---

## Plan structure (reorganized) — and where to read it

| Part | Topic | Detail in DESIGN.md |
|---|---|---|
| **0. Vision & constraints** | Vision, non-negotiables, positioning, the honest trilemma/push/MITM constraints | §1, §2 |
| **1. Threat model & red lines** ⚠️ *to write* | Explicit assets, adversaries (Cellebrite? NSO 0-click? global passive?), and out-of-scope list | §15 (gap) |
| **2. Cryptography** | Hybrid X25519+ML-KEM-768 handshake; PQ Double/Triple Ratchet; ML-DSA signatures (identity only); deniability; AEAD | §3.1–3.2 |
| **3. Transport & anonymity** | Tor (`arti`) now, Nym later; **identity-bound transport profiles** (Anon vs Direct-capable); NAT | §3.3, §13.1 |
| **4. Discovery & offline delivery** | Shared-secret rotating rendezvous tokens; oblivious mailbox; **pull-not-push** presence | §3.4–3.6 |
| **5. Conversations** | 1:1 semantics; groups (Sender-Keys→MLS); multi-device (host/controller); voice/video (notes + live); anti-spam | §3.7–3.9, §11 |
| **6. Product: features & settings** | KEEP/ADAPT/DROP matrix; settings spec; security↔perf tradeoffs; local logs; ephemerality; killer/anti-features | §12, §13 |
| **7. Engineering & platforms** | **The stack** (Rust core + native UI + Tauri desktop); per-platform reality; build/CI; distribution | §14 |
| **8. Trust & operations** ⚠️ *partly to write* | Audit, reproducible builds, abuse handling, crash reporting, threat-model doc, identity recovery, funding | §15 (gaps) |
| **9. Roadmap, risks & open decisions** | Phased plan, risk register, decisions for Rui | §7, §8, §9 |
| **Appendices** | Research findings, advisor disagreements, curated repos/papers | §10 + appendix |

---

## The stack decision (§14) — settled
**One Rust core, many native UIs** — the Signal/Molly model, which the research found is what *every* leading secure
messenger converges on (nobody ships the secure UI in Flutter/React-Native).

- **Rust core** (one workspace): crypto, PQ ratchet, **`arti` Tor transport**, oblivious-mailbox/pull logic, storage — exposed
  over a **narrow JSON command/event FFI** generated by **UniFFI** (Swift + Kotlin bindings auto-generated; no hand-written JNI).
- **Android** → Kotlin + Jetpack Compose. **iOS** → Swift + SwiftUI. **Desktop (Win/Linux/macOS)** → **Tauri 2** (Rust core
  in-process; ~3 MB vs Electron's ~96 MB).
- **The discipline (reconciling the one advisor split):** Rust owns the *bytes and the Tor logic*; the **native layer owns
  lifecycle/scheduling/power** (Android foreground service / WorkManager; iOS BGTask). Don't let Rust try to be an always-on
  daemon — the OS will kill it silently.
- **Rejected:** pure-Rust mobile UI (94% of Rust GUI libs not production-ready), Tauri-on-mobile for the messenger, Flutter for
  the secure surface (acceptable only as a fallback to cut cost).

### Platform reality (the honest answer to "Apple, Android, Windows, Linux")
| Platform | True serverless pull-not-push? | Notes |
|---|---|---|
| **Android** | ✅ Yes | Persistent foreground service over Tor (~few % battery/day, survives reboot) — like SimpleX/Briar. |
| **Windows / Linux / macOS desktop** | ✅ Yes | Real background daemons allowed. Tauri 2. |
| **iOS** | ⚠️ **No** | No background Tor/sockets. Needs an **oblivious APNs notification relay** (SimpleX pattern: encrypted metadata envelope, server links nothing) just to wake the app — a required small server even in a "serverless" product. Briar is Android-only for this reason. **Recommendation: Android + Desktop for v1; iOS foreground-only/with-relay as v2.** |

---

## Gaps to close (newly identified — §15)
The crypto is the *easy* part. These were under-specified and are now tracked workstreams:
1. **Formal threat model doc** — assets, adversaries, explicit out-of-scope (a maintained artifact, not a one-off).
2. **Onboarding / "first 60 seconds"** — Tor cold-start is 5–30 s; a "Connecting over Tor…" spinner loses users. Needs design.
3. **Identity recovery** — key loss = identity loss. Define recovery (BIP39/encrypted backup) + the irreversible-loss UX.
4. **The "dead token" rediscovery problem** (Gemini's catch) — if a user is offline past the token-rotation window, how do
   contacts re-find them without an out-of-band leak? Needs a protocol answer.
5. **State/UI consistency under high latency** (Gemini: most under-thought) — "Sent / Delivered-to-mailbox / ?" semantics
   when the peer is asleep; concurrent edits to un-pulled messages.
6. **Distribution strategy** ⏰ urgent — **Google Developer Verification (Sept 2026)** forbids anonymous Android publishing
   and may break F-Droid. → publish under a **named legal entity/foundation** (users stay anonymous); plan for F-Droid risk.
7. **Reproducible builds** — first-class CI requirement (a primary trust signal for an anonymity tool; hard to retrofit).
8. **Named third-party audit** (Quarkslab/Cure53/Trail of Bits/NCC) of PQ crypto + Tor + mailbox **before** any "secure"
   claim — months of lead time + real budget; a release gate.
9. **Abuse handling in E2EE** — message/transcript **franking** so victims can report specific content without breaking E2EE.
10. **Telemetry-free crash reporting** — opt-in, user-reviewable, scrubbed local dumps (no off-the-shelf option exists).
11. **Accessibility, i18n/RTL, secure update + rollback, crypto-agility/PQ-migration policy, legal/export posture, funding &
    maintainer bus-factor.**

---

## Open decisions for Rui (unblock everything downstream)
1. **License** (MIT/Apache vs GPL/AGPL — gates reuse of AGPL SPQR/RingRTC).
2. **iOS in v1, or Android+Desktop first?** (Given the iOS background reality.)
3. **Target user** — privacy daily-driver vs high-threat activist (sets the battery/latency budget).
4. **Live calls or async voice/video notes only?** And if live: Direct vs self-hosted-Relayed default (§11.6).
5. **Per-contact transport?** → resolved: **identity-bound profiles**, not per-contact (§13.1). Confirm.
6. **Positioning/MVP scope** — how aggressively to cut features (§12).

**Next concrete step options:** lock the decisions above · write the **threat-model doc** · write **`SETTINGS.md`** (exact
toggle text + warnings) · or scaffold the **Phase-1 Rust crypto crate** (hybrid handshake + ratchet + test vectors).

---

## License

pvtcoms is free software under the **GNU Affero General Public License v3 or later** (`AGPL-3.0-or-later`) — full text in
[`LICENSE`](./LICENSE), with an **App Store additional permission** and notes in [`LICENSE-EXCEPTIONS.md`](./LICENSE-EXCEPTIONS.md).
The license is free (no fee). Copyleft keeps any fork/hosted version open — protecting against closed, backdoored builds.

- Contributions use a **DCO** (sign off with `git commit -s`), **not** a CLA — see [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`DCO`](./DCO).
- The code is AGPL; the pvtcoms **name/logo** are governed separately by [`TRADEMARK.md`](./TRADEMARK.md).
- Dependency licenses are gated in CI by [`deny.toml`](./deny.toml) (allow permissive + MPL-2.0; deny GPLv2-only/proprietary).
- Rationale: [ADR-002](./docs/ADR/002-license-agpl-3.0.md).

SPDX header for source files: `// SPDX-License-Identifier: AGPL-3.0-or-later`