android-vpn-app

Files (2)

• SKILL.md
• vpngate-connect-failures.md · references/

SKILL.md (first lines)

# Android VPN App Development

Build VPN apps for Android using OpenVPN3 engine (via tim06 fork) with VPN Gate public servers.

## When to Use

- Building a personal VPN client for Android
- Integrating OpenVPN3 engine (tim06 fork) with VPN Gate public servers
- Need Android 14+ foreground service compliance
- Working with VPN Gate API (free public VPN servers)

## Core Architecture

```
DebNet+ (Kotlin + Jetpack Compose, Material3 dark)
├─ data/VpnGateApi          → fetch + parse server list from vpngate.net/api/iphone/
├─ vpn/DebOpenVpnService    → VpnService + EngineCallback (main process)
├─ VpnController            → Engine runner + StateFlow state management
└─ ui/DebNetApp             → Material3 dark UI: server list, country filter, connect overlay
```

## Key Integration Points

### 1. VPN Gate API (Free, No Auth)

```
Endpoint: https://www.vpngate.net/api/iphone/
Format: CSV with 15 columns, last column = base64 OpenVPN config
```

**Parser gotcha:** VPN Gate configs **don't have `<tls-crypt>`** — tim06's `OpenVPNConfigParser` crashes looking for it. **Solution:** bypass parser, construct `OpenVPNConfig` manually with raw config string.

### 2. OpenVPN3 Engine (tim06 fork)

**Library:** `io.github.tim06:openvpn:1.1.3` (Maven Central)

**Critical bugs in library:**
- `OpenVPNConfigParser` crashes on VPN Gate configs (expects `<tls-crypt>`)
- `OpenVPNLogger` silenced in release AAR (`BuildConfig.DEBUG=false`) → all engine errors silenced
- `VpnServiceConnection.start(config)` **drops config parameter** — config only delivered via intent extra `CONFIGURATION_KEY`

**Workarounds implemented:**
1. Bypass parser → construct `OpenVPNConfig` manually with raw config
2. Hook engine callbacks → capture logs/events/errors to UI via `EngineCallback`
4. Use `EngineCallback` interface for all VpnService callbacks

### 3. Engine Callback Interface

```kotlin
interface EngineCallback {
    val ctResolver: ContentResolver
    val connectivityManager: ConnectivityManager
    fun setMtu(mtu: Int)
    fun addDNS(server: String)
    fun addRoute(cidrip: CIDRIP, include: Boolean)
    fun addRoute(dest: String, prefix: Int, gateway: String?, device: String?)
    fun addRoutev6(ip: String, prefix: Int)
    fun setDomain(domain: String)
    fun setLocalIP(cidrip: CIDRIP)
    fun setLocalIPv6(ip: String)
    fun protectFd(fd: Int): Boolean
    fun openTun(): ParcelFileDescriptor?
    fun onStateChanged(state: ConnectionState)
    fun onEngineLog(line: String)
    fun onEngineError(msg: String)
    fun onThreadFinished()
}
```

### 4. VpnService Implementation (Main Process)

```kotlin
class DebOpenVpnService : VpnService(), EngineCallback {
    // Implement EngineCallback methods → delegate to builder
    // Run engine in separate thread with try/catch
}
```

### 5. Android 14+ Foreground Service Compliance

**Manifest:**
```xml
<service
    android:name=".vpn.DebOpenVpnService"
    android:permission="android.permission.BIND_VPN_SERVICE"
    android:exported="false"
    android:foregroundServiceType="specialUse">
    <intent-filter>
        <action android:name="android.net.VpnService" />
    </intent-filter>
    <property
        android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
        android:value="vpn" />
</service>
```

**Permissions:**
```xml
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
```

### 6. VPN Gate Server Selection (TCP Only)

**VPN Gate reality:** Most free servers only support **TCP 443**. UDP 1194 often times out.

```kotlin
// Always use TCP, no UDP retry
fun buildVpnProfile(config: String, serverName: String): VpnProfile {
    // Parse host/port from config
    // Force proto = "tcp-client"
    // Add DNS fallback: dhcp-option DNS 1.1.1.1 / 8.8.8.8
}
```

**Server scoring:** Filter by `score > 0 && ping > 0`, pick from top 60% by score.

### 7. CIPHER FIX (mandatory — OpenVPN3 rejects CBC)

From debzroot/Debz-AI-Agent, MIT.

More from debzroot/Debz-AI-Agent