# Threat model ## Introduction This document defines the threat model for the `oxpulse-partner-edge` bundle — the open-source AGPL-3.0 component that partner operators self-host to extend the OxPulse encrypted communication mesh. It is intended for independent security auditors, partners evaluating whether to deploy a node, and grant reviewers assessing the maturity of the project's security posture. It should be read alongside [ARCHITECTURE.md](ARCHITECTURE.md) for the system layout and cryptographic boundary, [SECURITY.md](../SECURITY.md) for the responsible-disclosure process, and [DECISION.md](../DECISION.md) for architectural rationale. This is a living document. It is reviewed quarterly and updated whenever a cryptographic primitive changes, the architecture changes materially, or a newly-disclosed adversary capability affects the model. Material updates are noted in `CHANGELOG.md` and called out in the next `TRANSPARENCY.md` update. ## Assets we protect The following assets are within scope of the threat model: - **Message content.** End-to-end encrypted among up to six participants per room. Neither the partner-edge node nor the OxPulse control plane possesses the keys to decrypt message content. - **Real-time media streams.** Audio, video, and screen-share streams are SRTP-encrypted (1:1 mesh calls) or SFrame-encrypted (group calls through the SFU). The SFU forwards encrypted frames without decryption. - **Connection metadata at the partner-edge boundary.** Room IDs, partner IDs, timestamps, byte counters, and ICE candidate addresses are visible at the edge. We document this exposure explicitly rather than claiming zero metadata leakage. The design minimizes metadata to what is operationally necessary for call routing. - **Partner node operator identity.** Minimized by default — operators are not visible to other partners unless they opt in to public listing. The control plane holds the mapping between partner IDs and operator identities. - **Mesh topology and trust-score state.** Held by the control plane, not exposed to individual partner nodes. A compromised partner cannot enumerate the full mesh. ## Adversary classes ### Class A: network-level filtering infrastructure **Capabilities.** Deep packet inspection (DPI), TLS fingerprinting at scale, machine-learning traffic classification, active probing of suspected proxy IP addresses, and dynamic IP/domain blocking. **Operators.** National filtering systems deployed in Russia (ТСПУ / TSPU), Iran, China (GFW), Belarus, and Cuba (ETECSA). These systems operate at ISP level with state backing and can be updated rapidly in response to new circumvention techniques. **Motive.** Prevent users from reaching communication services that operate outside state surveillance frameworks. Blocking is the primary goal; decryption of content is secondary to preventing access entirely. ### Class B: coerced infrastructure **Capabilities.** Legal compulsion of ISPs and certificate authorities operating within filtering jurisdictions. This includes court-ordered traffic redirection, compelled TLS interception via trusted root certificates, and forced DNS poisoning. **Operators.** ISPs and CAs subject to legal regimes that can compel cooperation without public disclosure. **Motive.** Enable targeted surveillance of specific users or degrade the trust properties of encrypted connections within a jurisdiction. ### Class C: compromised partner operator **Capabilities.** A node operator who is coerced, compelled, or who voluntarily turns hostile. The compromised operator has full access to the partner-edge node, including container logs, network captures, and configuration files. They can attempt to deanonymize participants, harvest metadata, or disrupt service. **Motive.** Extract identifying information about users routing through the node, or inject disruption to undermine trust in the mesh. ### Class D: passive global observer **Capabilities.** Long-term traffic recording at scale, with the intent to decrypt recorded traffic in the future if cryptographic primitives weaken or quantum computing advances reach the necessary capability. **Motive.** Record-now-decrypt-later. This adversary is patient and well-resourced, collecting encrypted traffic flows today against the possibility of future decryption. ## Mitigations per class ### Class A mitigations - **VLESS + Reality + XHTTP transport.** The xray-client tunnel presents as standard HTTPS traffic to network-level observers. The Reality protocol uses the TLS certificates of legitimate domains, making the tunnel indistinguishable from genuine traffic to those domains. Configuration: `xray-client.json.tpl`. - **ML-KEM-768 post-quantum encryption.** The tunnel layer uses ML-KEM-768 (NIST FIPS 203) on the xray connection, providing resistance to future quantum decryption of recorded tunnel traffic. - **8-name SNI pool, daily per-node rotation.** The tunnel's server name indicator rotates across a pool of eight major-brand HTTPS domains supplied by the control plane (5 Samsung subdomains plus 3 Microsoft 365 subdomains — Outlook, Teams, login.microsoftonline). Per-node selection is deterministic via `sha256(node_id : YYYY-MM-DD) mod pool_size` and re-evaluated daily by a systemd timer at 04-06 UTC randomised. No two partner-edges look identical to a network observer correlating across nodes, and a node's SNI is non-stationary across days. Reduces the effectiveness of static SNI-based blocking rules and increases the cost of any single-brand block. Implemented in `oxpulse-partner-edge-sni-rotate.sh`. - **Deterministic per-node SNI selection.** Each node selects its SNI value deterministically via `sha256(node_id)`, ensuring that the (IP, SNI) tuple is unique per node. This diversification prevents a single blocking rule from disabling multiple nodes simultaneously. - **Cover page with active-probing defense.** Direct HTTP requests to the partner-edge domain receive a static cover page. The `@probe` Caddy matcher identifies and deflects active-probing attempts that filtering infrastructure uses to confirm proxy endpoints. Source: `cover/` directory and `Caddyfile.tpl`. ### Class B mitigations - **AGPL transparency.** The full partner-edge source is publicly auditable. Partners and third parties can verify that no backdoor or covert interception mechanism exists in the open-source components. - **Reproducible builds.** On the roadmap (not yet implemented). Once complete, partners will be able to verify that released container images match the published source. - **Warrant canary.** Published in `TRANSPARENCY.md` and updated quarterly. Tracks whether OxPulse has received National Security Letters, FISA court orders, or requests to insert backdoors. - **US legal jurisdiction.** OxPulse is being incorporated as a US Delaware C-Corp; the operating entity is subject to US legal process, which requires judicial oversight for surveillance orders. This is documented transparently, not presented as absolute protection. - **Minimal data retention.** The partner-edge node does not store call content, participant identities, or session logs beyond what is necessary for real-time operation. Operational metadata (byte counters, health checks) is retained locally on the partner's own infrastructure. ### Class C mitigations - **No plaintext exposure.** Even with full access to the partner-edge node, a compromised operator cannot decrypt media or message content. SFrame keys are negotiated end-to-end between participants and never transit through the edge node. - **Control-plane trust scoring.** The OxPulse control plane continuously evaluates partner node behavior. Anomalous patterns (unusual traffic volumes, configuration deviations, connectivity irregularities) trigger trust-score degradation and, at threshold, automated disconnection from the mesh. - **Automated disconnect.** Nodes that fall below the trust-score threshold are removed from active rotation automatically. Users are rerouted to other nodes without disruption. - **Limited blast radius.** Each partner node receives independent credentials. Compromise of one node does not yield credentials or key material for any other node in the mesh. ### Class D mitigations - **ML-KEM-768 forward-secrecy layer.** The post-quantum encryption on the tunnel transport ensures that recorded ciphertext cannot be decrypted even if classical key-exchange algorithms are broken by future quantum computers. - **Ratchet key exchange with regular re-keying.** Group media keys use a ratchet-based key exchange (X25519 + ChaCha20-Poly1305) with periodic re-keying. Compromise of a single session key does not compromise past or future sessions. - **No long-term plaintext storage.** No layer of the system stores plaintext content persistently. Call content exists only in memory during active sessions. ## Mesh underlay (AmneziaWG) Partner-edges optionally form a layer-3 mesh between themselves over AmneziaWG, an obfuscated WireGuard fork ([github.com/amnezia-vpn/amneziawg-go](https://github.com/amnezia-vpn/amneziawg-go)) that adds packet-shape randomization, junk-packet injection, and configurable handshake-magic obfuscation to defeat WireGuard fingerprinting at the DPI layer. The mesh is used for cascade-relay hand-off (Phase 7 SFU relay) and inter-partner control-plane heartbeats; it does **not** carry user media. SRTP frames remain end-to-end encrypted client-to-client and would not be decryptable by a compromised mesh peer. **Adversaries and properties:** - *Class A (network filtering).* AmneziaWG is the project's primary defense against WireGuard-handshake fingerprint blocking observed in Russian and Iranian DPI in 2024–2026. The AmneziaWG `Jc/Jmin/Jmax/S1/S2/S4/H1..H4` parameters are deployment-wide (shared across the server and every partner-edge that joined the mesh), distributed at install time via the control-plane registration response. They MUST match byte-for-byte across all peers — see `docs/AWG_PARAM_INVARIANT.md` for the failure mode if drift occurs. Per-deployment randomization defeats DPI rules tuned to a known WireGuard wire shape; deployment uniqueness is what hides the protocol, not per-node uniqueness. - *Class C (compromised partner operator).* A hostile partner that joins the mesh sees only encrypted partner-to-partner control packets and other partner-edges' source IPs. They do not see user media (different cryptographic boundary) and they cannot inject arbitrary peers (mesh peers are explicitly enumerated by the control-plane registration; AmneziaWG enforces the static peer set). The trust-scoring pipeline (Class C mitigations above) treats AmneziaWG-layer anomalies (excessive heartbeat misses, peer-count drift, unexpected cross-mesh traffic) as input signals. - *Class D (passive global observer).* AmneziaWG headers are per-deployment-randomized, but a sufficiently capable global observer with traffic-analysis capability can in principle correlate encrypted flows by volume and timing. We do not claim resistance to this class for the mesh layer; user media is end-to-end encrypted independently of the mesh. **Out of scope for the mesh layer:** anonymizing the existence of the inter-partner connection itself. A peer in the mesh is a known operator with a registered public key; we do not attempt to hide the fact that two partner-edges are talking to each other. We do hide *what* they are saying (encrypted) and *what protocol the link runs* (AmneziaWG vs. plain WireGuard). ## Out of scope (residual risk) The following risks are acknowledged but are outside the protection boundary of the partner-edge system: - **Compromised endpoint devices.** Malware on a user's phone or laptop defeats end-to-end encryption at the endpoint. OxPulse encrypts data in transit and at the application layer, but cannot protect against a compromised operating system or keylogger on the user's device. - **Traffic-analysis-grade anonymization.** OxPulse is not Tor. Content is protected by end-to-end encryption, but transport-layer metadata (connection timing, packet sizes, IP addresses) is not anonymized beyond standard TLS. An observer who can see both ends of a connection can correlate them by timing analysis. - **Social engineering of partner operators.** The trust-scoring system can detect behavioral anomalies, but cannot prevent an operator from being socially engineered into actions that do not manifest as detectable technical deviations. - **Legal compulsion of the OxPulse operating entity.** OxPulse is being incorporated as a US Delaware C-Corp and will be subject to standard US legal process (subpoenas, court orders, National Security Letters). The warrant canary in `TRANSPARENCY.md` tracks this risk. The system is designed so that even under compulsion, the operating entity cannot decrypt end-to-end encrypted content — it does not possess the keys. - **Compromise of upstream cryptographic libraries.** OxPulse depends on established libraries (libsodium, ring, xray-core, str0m). A vulnerability in these dependencies would affect OxPulse. We track CVEs and apply updates following the standard release process documented in `SECURITY.md`. ## Cryptographic primitives in use | Use | Primitive | Source | |---|---|---| | Real-time media (1:1 mesh) | DTLS-SRTP, AES-128-GCM | WebRTC standard | | Group media (3–6 SFU rooms) | SFrame + ratchet KX | IETF Proposed Standard RFC 9605 (2025) | | Ratchet key exchange | X25519 + ChaCha20-Poly1305 | libsodium / ring | | Post-quantum tunnel layer | ML-KEM-768 | xray 26.x (NIST FIPS 203) | | Tunnel transport | VLESS + Reality + XHTTP | xray-core | | Mesh underlay (partner ↔ partner) | AmneziaWG (WireGuard + obfuscation params) | amnezia-vpn/amneziawg-go | | TLS / ACME | Caddy auto-TLS | TLS 1.3 (RFC 8446) | ## Assumptions - Adversary cannot break standard cryptographic primitives under standard hardness assumptions (X25519, AES-128-GCM, ML-KEM-768). - Adversary can compel some ISPs and certificate authorities within filtering jurisdictions but cannot compel all global infrastructure simultaneously. - Adversary can run active probes against suspected proxy IP addresses but cannot break TLS 1.3 with current parameters. - Partner operators are honest by default. The trust-scoring system detects and responds to behavioral drift over time, but does not assume adversarial intent from the outset. ## Document maintenance - Reviewed quarterly, aligned with the `TRANSPARENCY.md` update cycle. - Updated on any cryptographic primitive change, any architectural change, or any newly-disclosed adversary capability that materially affects the model. - Material changes are summarized in `CHANGELOG.md` and called out in the next `TRANSPARENCY.md` update.