Designing a mobile VPN connection lifecycle with WireGuard

The scenario

Imagine a subscription VPN application for iOS and Android. A person should be able to enrol a device, connect to an available gateway, and understand why a connection failed. The reference design would separate the encrypted tunnel from the account and device control service, with explicit states in the mobile interface.

Separate device enrolment from tunnel traffic

The control API would authenticate the account, check entitlement, and register a device public key. The device private key would be generated and retained on the client using a platform-appropriate protected storage design. It would not be included in ordinary API requests or diagnostic logs.

WireGuard peers use public and private keys together with endpoint and allowed-address configuration. A gateway controller would provision the permitted public peer information. Account authentication and subscription checks would belong to the control plane; WireGuard itself would not replace those product systems.

Model the connection lifecycle in the app

The interface would distinguish disconnected, requesting permission, configuring, connecting, connected, reconnecting, and failed. An authenticated account would not imply a working tunnel. A handshake alone would not prove DNS or application traffic is routed as intended.

Android’s VPN service lifecycle and iOS Network Extension integration would need native platform handling. Permission denial, service revocation, process restarts, and a change from Wi-Fi to cellular would each have an explicit transition. Connection attempts would be cancellable, with bounded retry behaviour rather than a permanent loading state.

Design revocation and diagnostics together

Revoking a device would remove its permitted peer configuration from the relevant gateway and prevent a fresh configuration from being issued. A key rotation would have a recovery path if the update is interrupted. Gateway health and regional capacity would be evaluated separately from the account API’s availability.

Diagnostics would record only the operational information needed to investigate a connection: application version, coarse failure category, and timing where appropriate. The product would define retention and access rules before collecting it. Claims about logging, anonymity, or independent audits would require evidence from the actual service.

What to validate

• Permission denial returns the app to a usable state.
• Wi-Fi and cellular transitions follow the intended routing policy.
• DNS, IPv4, and IPv6 behaviour are tested explicitly.
• Revoking a device blocks the old peer and fresh enrolment attempts.

The tradeoff

A tunnel library is only one part of a VPN product. Gateway operations, platform entitlements, routing, subscription state, and recovery flows all need validation. A minimal native prototype should establish those constraints before polishing the connection screen.