init

docs/security.md

@@ -0,0 +1,70 @@
+# 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.