Threat Model

This document defines who Komms defends against, what it protects, and, just as importantly, what it does not claim to protect. Every design decision in 03: Architecture and 04: Cryptography traces back to a row in this document.

1. Assets

Asset	Description
Message content	Text, media, and files exchanged between users.
Message metadata	Who talks to whom, when, how often, from where, and message sizes.
Identity keys	Long-term Ed25519/X25519 key material that is a user's identity.
Session state	Ratchet state whose compromise could expose past or future messages.
Local message history	Decrypted content visible to an unlocked endpoint and its independently sealed at-rest representation.
Social graph	Contact lists, private local petnames, and group memberships.
Private organization	Local folder/label definitions, exact typed conversation pins, stable IDs, order, memberships, selected views/filters, and stale-reference diagnostics.
Availability	The ability to communicate at all, including when infrastructure is down or hostile.

2. Adversaries

Listed roughly in ascending order of capability.

A1: Mass content scanning (the ChatControl model)

An actor with legal or technical leverage over service providers, compelling them to scan, filter, or report message content (client-side or server-side).

Defense: no service provider is required to communicate, and no relay or optional convenience service receives message plaintext or message keys. A provider can be compelled to log service-use metadata, deny service, or alter its own software, but it cannot add server-side content scanning to ciphertext it cannot open. Persistently compromised endpoint software remains A7; optional service boundaries are pinned by ADR-0017.

A2: Passive network observer

An ISP, IXP tap, or national passive-collection program recording traffic.

Defense: all traffic is end-to-end encrypted (content) and transport-encrypted (links). Padding to size buckets and encrypted ratchet headers reduce what traffic analysis yields. Full traffic-analysis resistance is partial; see §5.

A3: Active network attacker / censor

An actor who can block, throttle, inject, or MITM traffic: national firewalls, hostile Wi-Fi, BGP hijackers.

Defense: transport authentication (Noise/TLS with pinned peer keys) defeats MITM. Censorship is countered by transport diversity: if the internet path is blocked, the same envelopes flow over LAN, BLE, LoRa mesh, or sneakernet (05: Transports). Obfuscated internet transports are on the roadmap (08: Roadmap, M6).

A4: Infrastructure seizure / shutdown

Confiscation of relays, takedown of bootstrap nodes, or a regional internet blackout.

Defense: no single point of failure exists in the core. Any node can relay; discovery is DHT-based with multiple bootstrap paths; the Meshtastic/LoRa fallback functions with zero internet infrastructure. Loss of any relay loses that relay's queued ciphertext copy, which is sealed and padded; the sender retains its original until an encrypted receipt and can retry another route. Loss of every optional rendezvous or native-wake service removes convenience only and must fall back to the same direct, DHT, mailbox, LAN, mesh, and sneakernet paths.

A5: Malicious peer, relay, or optional service

A participant in the network (a relay holding mailboxes, a DHT node, a mesh repeater, rendezvous provider, or native-wake gateway) that logs, drops, replays, correlates, or forges traffic.

Defense: relays receive sealed envelopes rather than message plaintext or an encoded sender identity. Mailbox v2 durably commits row-bound records under opaque indexes, leases bounded pages, and deletes only exact rows acknowledged after endpoint commit. Replay and response loss therefore do not create a false custody acknowledgement. Rendezvous stores fixed-size encrypted route records, and native push carries only a static wake shape. AEAD, ratchet ordering, rendezvous generation/expiry checks, and bounded wake capabilities defeat accepted-content forgery and stale-state rollback.

These are not anonymity or operator-inability claims. A mailbox operator sees network sources, opaque recipient tokens, padded sizes, timing, volume, expiry, pseudonymous client activity, random row/lease ids, and quota outcomes; it controls live memory and can log, correlate, refuse, delay, replay, or destroy work. At-rest row sealing protects a copied database without its separate key, not the running operator. Redundant delivery, sender retention, and encrypted receipts make total dropping degrade into adversary A4.

A6: Retrospective decryption ("harvest now, decrypt later")

An actor recording ciphertext today, hoping to decrypt it with a future cryptanalytic advance or quantum computer.

Defense: hybrid post-quantum key agreement (X25519 and ML-KEM-768; both must fall) plus forward secrecy from the Double Ratchet. See 04: Cryptography.

A7: Endpoint compromise (targeted)

Malware, forensic seizure of an unlocked device, or a coerced unlock, against a specific target.

Defense (bounded): at-rest encryption under an Argon2id-derived key protects a powered-off/locked device's sealed record bodies. ADR-0027 replaces sensitive plaintext SQLite lookup values with database- and domain-separated keyed indexes, and binds each ciphertext to its final database, schema, table, and locator identity. A locked copy still exposes approximate row counts/sizes, insertion order, within-domain equality, access patterns, and change timing. The implementation has Linux/ext4 test evidence, while independent review and physical filesystem, power-loss, backup-exclusion, and forensic qualification remain open. Forward secrecy means a captured device does not reveal messages deleted before capture; post-compromise security means a transient compromise is healed by the next DH ratchet step. A persistently compromised endpoint sees everything its user sees; no messenger can prevent that (§5).

A8: Local display capture (opportunistic)

Shoulder surfing, an accidental screenshot or recording, an app-switcher/recent preview, or ordinary capture software observing a sensitive Komms view.

Defense (bounded): B14 enables the strongest honest native shell control before unlock: Android FLAG_SECURE, iOS inactive/live-capture privacy shields, and best-effort desktop content protection plus rapid lock. These reduce accidental disclosure but do not defeat A7, privileged capture software, a compromised OS/compositor, accessibility or overlay abuse, or an external camera. iOS still screenshots cannot be universally blocked. Exact guarantees and the qualification matrix are in 13: Screen Security.

A9: Local input retention (opportunistic)

A keyboard, spelling service, writing tool, autofill system, or webview retains or later suggests sensitive text typed into Komms.

Defense (bounded): B15 marks every textual field with the strongest native non-learning, correction, prediction, spelling, and autofill controls available. Passphrases and recovery mnemonics use masked secret entry. Android's explicit no-personalized-learning flag remains a request an IME may ignore; iOS and desktop expose no per-field learning guarantee. This does not defeat A7, a malicious input method, accessibility or overlay abuse, privileged writing tools, hardware with its own storage, or external observation. Exact behavior and qualification are in 14: Incognito Keyboard.

A10: Malicious received files (opportunistic or targeted)

A peer sends active content, a disguised executable, or bytes whose authenticated filename and media-type hints are misleading, hoping the recipient or a local viewer executes them.

Defense (bounded): C1 never auto-opens attachments, marks all names and types as untrusted sender claims, makes active/mismatched/unknown/nameless files export-only, and requires an unscanned warning plus explicit confirmation for the reviewed external-open set. Materialization is app-private and temporary. This does not prove content safe, replace malware scanning, sandbox a third-party viewer, or defeat A7. Exact behavior is in 17: Safe File Presentation.

3. Security goals

Goal	Meaning	Mechanism
Confidentiality	Only intended recipients read content.	XChaCha20-Poly1305 AEAD under Double Ratchet keys.
Integrity & authenticity	Pairwise messages, recipient-authenticated group events, and signed authority state cannot be altered or forged as another accepted sender.	AEAD tags and identity-key-signed handshakes protect pairwise lanes; ADR-0029 binds each shared group ciphertext to the verified sender account/device separately for every recipient; signed group authority state is attributable. Group event authentication remains recipient-deniable rather than publicly verifiable.
Forward secrecy	Key compromise doesn't expose past messages.	Symmetric + DH ratchets; keys zeroized after use.
Post-compromise security	Security self-heals after transient compromise.	DH ratchet steps on every round trip.
Post-quantum confidentiality	A6 resistance for content.	Hybrid PQXDH-style handshake (ML-KEM-768).
Metadata minimization	Network learns as little as possible about who/when/how much.	Sealed sender, encrypted headers, size-bucket padding, no mandatory identity-indexed rendezvous; optional pairwise capabilities.
Deniability	Transcripts are not cryptographic proof of authorship to third parties.	No signatures over message content; authentication via shared MAC keys (Signal-style).
No mandatory identifiers	No phone number, email, or real name, ever.	Keypair-as-identity (06: Identity & Trust).
Availability off-grid	Communication may continue when ordinary infrastructure is lost and at least one supported alternate path remains usable.	Transport abstraction with LoRa mesh + sneakernet fallbacks; no guarantee against simultaneous blocking, jamming, device loss, or power loss.
Local display minimization	Reduce accidental disclosure from capture and task/app-switcher previews where native APIs permit.	Always-on B14 shell protections and explicit unsupported states; not an endpoint-compromise defense.
Local input minimization	Reduce keyboard learning, correction, spellcheck, autofill, and secret-field exposure where native APIs permit.	Always-on B15 field controls and explicit best-effort/unavailable states; not an endpoint-compromise defense.
Identity-text safety	Keep mutable human labels from becoming identity or silently hiding spoofing risk.	Exact peer-key targeting, NFC normalization, duplicate/confusable/bidi/invisible warnings, and explicit review for warned B5 renames.
Active-content isolation	Authenticated message text must not become executable or network-active content.	B9 keeps exact source, applies a bounded local parser, exports only inert block/run tokens, literal-falls back on complexity, and never interprets HTML, links, images, or URL schemes.
Edit provenance	An accepted peer or group member must not rewrite another author's message, and offline endpoints must agree about the visible version.	C3 immutable edit events bind exact author/content ids inside authenticated content; ADR-0029 derives group authors from a verified sender device before state application; wrong-author/wrong-scope events never apply, and maximum (revision, edit id) converges without clocks.
Poll convergence and honesty	Replicas must tally the same received events and one member must not cast another member's vote.	C5 fixes the creation-declared electorate, selects maximum (revision, event id), and freezes a close snapshot from the recipient-authenticated creator. Votes remain visible and the protocol does not claim anonymity, fairness, completeness, or protection from a creator closing early.
Group authority convergence	A stale admin or losing ownership fork must not regain authority or future group secrets.	C6 signs canonical full role state and transfer certificates, binds admin requests to one generation, serializes mutations at one owner, rejects non-extending transfer chains, and re-keys every accepted transition.
Sovereignty	Users hold their own keys and data; anyone can run every component.	Local-first storage, AGPLv3, no privileged nodes.

Optional Hybrid Infrastructure Layer modes do not change the confidentiality, authenticity, deniability, identity, or off-grid goals above. They add a bounded metadata surface documented in ADR-0017: direct Standard-mode requests may expose a client address, opaque target, timing, and volume; a native wake gateway Private mode separates client address from target request through Tor or a non-colluding OHTTP relay, but it does not promise anonymity against collusion or a global passive observer. Service compromise can suppress convenience work but cannot decrypt or forge an accepted Komms message.

Message editing does not erase evidence or extend pairwise sender authority. The original and accepted versions remain sealed locally and in backups. In both a pairwise conversation and an upgraded group, only the exact authenticated author can target canonical text in that conversation. Group authors come from the verified pairwise sender device and accepted authority chain before the edit state machine runs; a content field, display name, timestamp, arrival order, delivery token alone, or sender-chain id cannot authorize an edit. Legacy group rows retain their membership-authenticated label. A malicious peer can send many authenticated attempts and consume its own conversation storage, so local authors are capped at 64 edits per target; authenticated inbound events remain durable to preserve convergence. Recipients may retain, copy, capture, or export any prior version, and the UI never describes editing as remote deletion. Exact limits are in 18: Authenticated Message Editing.

C4 ephemeral content narrows local retention; it does not create remote deletion authority. Exact deadlines and first-open state are authenticated and sealed per installation, and terminal tombstones prevent delayed ciphertext or backup restore from rehydrating removed plaintext. KKR6 excludes live ephemeral history/manifests/media. Envelope carriers learn one hour-aligned deletion bucket and may delete early, ignore the hint, or retain copied ciphertext; recipients and compromised endpoints may capture plaintext. View once blocks Komms's ordinary preview/export/playback paths but is not DRM or universal screenshot prevention. See 19: Disappearing Messages and View-Once Attachments.

C5 group polls protect content from intermediaries, authenticate each voter and creator separately to every recipient device, and deterministically converge. Every holder of the poll can inspect current voter identities and choices. The creator attests the fixed electorate and final observed vote-head snapshot, so a malicious creator can still close before an offline vote arrives or omit an observed head; deterministic convergence is not proof of fair or complete counting. Outsider, wrong-origin, unknown-option, duplicate, delayed, and reordered events do not change the defined result. Removed members retain what they already received. See 20: Group Polls, ADR-0022, and ADR-0029.

C6 group authority is attributable rather than deniable durable state. This is an intentional exception to ordinary deniable message content: identity signatures cover only canonical role/owner state, owner-transfer certificates, generation-bound admin requests, and owner moderation snapshots. They do not sign ordinary chat text or votes. A compromised legitimate owner can still remove members, grant admin, rename, transfer ownership, or moderate a poll; signatures provide validation and convergence, not an appeal system or fairness guarantee. Admin work waits for the owner, and removed endpoints retain content already received. Higher generations rooted in a losing transfer fork and stale requests from removed/demoted admins fail closed. See 21: Group Roles, Ownership, and Moderation and ADR-0023.

C2 prevents two installations from sharing live ratchet or sender-chain state, but it does not make an authorized device harmless. Every physical endpoint has an immutable device-owned certificate and independent delivery cryptography; KDA2 manifests, link transcripts, sync events, counters, and revocations are authenticated and rollback/replay checked. The account root is an offline recovery authority and never enters ordinary linked-device state. A compromised minority device can retain plaintext and emit device-authorized data events, but cannot unilaterally add, replace, rename, or revoke credentials; ordinary authority requires a strict majority of the previous active set. Compromise of a majority can authorize a branch. Concurrent branches and same-epoch root recoveries remain visible and fail closed. Theft of the offline root remains ultimate account takeover and can revoke every device. Explicit bounded sync has no server log and excludes live queues/ratchets, active ephemeral content, downloaded media, drafts, and scheduled outbox rows. See 22: Linked Devices and ADR-0026.

Private folders, conversation pins, and labels are endpoint organization, never communications metadata. Their definitions, single-folder assignments, exact typed peer/group/note-to-self pins, and many-to-many label memberships remain inside the independently sealed local_metadata domain; protected folder/label view preferences remain device-local. An organization operation creates no envelope, mailbox, mesh, sneakernet, LAN, internet, DHT, capability, sender-key, ratchet, delivery-token, analytics, or remote-notification work. A copied SQLite database reveals only the already accepted row count and approximate sealed blob sizes. KKR10 is the current folder, pin, or label backup format. None has server, contact, or service synchronization; C2 may carry them only in authenticated encrypted bundles between account-authorized owned devices. Once rendered on an unlocked endpoint, organization text has the same bounded A7 exposure as the rest of the user's visible local data.

Contact petnames have the same endpoint-only boundary. Rename rewrites only the sealed local contact record and emits a local event; it does not advertise or resolve a name, and C2 syncs it only to authorized devices of the same account. Names may duplicate, so every action targets the peer key and interfaces retain disambiguating context. Warning heuristics reduce accidental Unicode spoofing but are not a complete UTS #39 implementation and cannot make two visually similar labels safe by themselves. A user may explicitly accept a warned name; endpoint compromise and deliberate deception remain A7 limitations.

Some platform workflows require bounded plaintext transients after unlock—for example, an OS picker import, recorder review, image edit, playback, or explicit export. These live only in protected app-private locations, are excluded from backup, are never the core database source of truth, and are cleaned on the documented success, discard, failure, lock/background, shutdown, and restart paths. Their exposure on a persistently compromised unlocked endpoint remains A7.

C7 live audio is transient but not anonymous. Signaling remains inside the pairwise ratchet and media records use fresh call/device/direction-bound keys, so relays and transports receive no new plaintext call metadata field. The direct QUIC peers and a network observer can still see endpoint addresses, timing, duration, and traffic volume. Call secrets, Opus queues, and decoded PCM are memory-only and erased on terminal/background paths; a compromised endpoint, platform audio service, Bluetooth route, or external recorder remains A7. Calls never fall back to store-and-forward or radio merely to improve availability. See 23: Live Audio Calls.

4. Non-goals and accepted limitations

Honesty here is a security feature. Komms does not claim to provide:

1. Anonymity against a global passive adversary. Correlating traffic across the whole internet can link endpoints. Mitigations (Tor/arti integration, cover traffic) are roadmap items, not launch guarantees.
2. Protection on a persistently compromised endpoint (A7, persistent). If the OS is hostile, the screen and keyboard are hostile.
3. LoRa radio-layer anonymity. Transmitting on LoRa is physically observable and direction-findable. The mesh hides content and (with sealed envelopes) who inside the mesh is talking to whom, but not that a radio transmitted.
4. Spam/abuse-free open discovery. Decentralization trades away central moderation. Abuse controls are local (blocklists, contact gating, proof-of-work on introductions).
5. Guaranteed delivery latency. Store-and-forward over intermittent transports is eventually-consistent by design; the UI must communicate delivery state truthfully.
6. Metadata invisibility from an enabled convenience service. Pairwise capabilities prevent public enumeration, not observation of connections, timing, volume, or a native provider destination at the component that must process it.
7. Guaranteed mobile background execution. APNs/FCM and the operating system may throttle, delay, coalesce, or discard a wake; force-quit, permissions, battery policy, and provider outage remain honest failure cases.
8. Network anonymity for live calls. Direct peer-to-peer QUIC necessarily exposes each endpoint's network address to the other endpoint and remains traffic-analysis-visible. Komms adds no coordinator, TURN service, or relay fallback to conceal that fact.

5. Residual-risk summary

Adversary	Residual risk
A1	No server-side content-scanning point exists; malicious or compelled endpoint software remains A7.
A2	Coarse traffic patterns on internet transport and enabled convenience services until cover-traffic/Tor mitigations apply.
A3	Determined national censor can degrade or block internet transport; off-grid options still require usable hardware, power, configuration, and an unjammed path.
A4	Regional mesh partitions until a bridge node appears; optional-service outage leaves pure-core capabilities available but may still prevent delivery when no core path is currently reachable.
A5	Targeted denial and service-use correlation by a well-placed component; denial is mitigated by multipath core fallback.
A6	The hybrid handshake is intended to retain key-agreement security if either X25519 or ML-KEM-768 remains secure under the composition's assumptions; protocol, implementation, endpoint, and future-cryptanalysis failures remain possible.
A7	Persistent endpoint compromise is out of scope; transient compromise is healed.