net-bridge/docs/security.md

Security Design and Threat Model

Security Objectives

• Only approved devices can use the gateway.
• Local attackers cannot read or alter tunneled traffic.
• A stolen QR code expires quickly and cannot silently enroll a device.
• The gateway does not log browsing history, DNS names, or packet payloads.
• A malicious peer cannot access the phone LAN or other peers by default.

Trust Boundaries

• Trusted: phone owner approval, installed VPN app, VPN Share signed binaries.
• Semi-trusted: paired devices after explicit approval.
• Untrusted: local Wi-Fi, hotspot participants, USB host before approval, mDNS announcements, QR observers.

Threats and Mitigations

Threat	Mitigation
Local MITM on Wi-Fi	Noise authenticated encryption, transcript binding, peer keys
Stolen QR	One-time PSK, 2-minute expiry, phone-side confirmation
Malicious paired device	Per-peer revocation, no inbound LAN access, rate limits
Replay	Monotonic packet numbers and replay windows
DNS leak	Client DNS points to VPN Share gateway; gateway forwards through Android default VPN network
VPN bypass	Gateway does not protect forwarded sockets; UI warns if no active VPN is detected
Battery drain	Foreground service only while active, batched stats, adaptive keepalive
DoS by paired client	Per-peer queue limits, flow caps, overload close code

Data Collection Policy

Default telemetry is local only:

• Connected peer labels.
• Bytes in/out.
• Session duration.
• Error counters.

VPN Share must not collect:

• Packet payloads.
• Browsing history.
• DNS query names.
• Destination IP history outside short-lived in-memory flow tables.

Key Storage

• Android gateway identity key is generated on first run and stored in Android Keystore when available.
• Peer public keys and labels are stored in app-private encrypted storage.
• Desktop clients store their device key in the OS credential store where available, with file-permission fallback.

Play Store Compliance

The gateway mode itself does not use VpnService. If Android client mode is shipped in the same package, the release must:

• Declare the VpnService use in the store listing.
• Show prominent in-app disclosure before Android client VPN permission.
• Explain that traffic is encrypted to the paired VPN Share gateway.
• Avoid traffic redirection for ads or monetization.
• Submit the Play Console VpnService declaration.

Foreground Service Compliance

Active sharing uses a foreground service with connectedDevice because it maintains live communication with external devices. The service must expose a persistent notification and stop action.