# 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.