vpn/native/android/README.md

Android native layer

This directory is a Flet Flutter service extension. The Python NativeBridge control sends small versioned commands over the extension; Kotlin owns the actual Android lifecycle.

The native layer is deliberately split from the Flet Activity:

Python/Flet -> FletService -> MethodChannel -> Kotlin bridge
                                      -> VpnRuntimeService (VpnService)
                                      -> ProxyRuntimeService (foreground service)
                                      -> FreeTurn/libbox adapters

VpnRuntimeService calls VpnService.prepare() through the bridge, starts foreground immediately, configures a predictable 10.0.0.1/24 TUN, and persists state in SharedPreferences. The current adapter refuses to report success unless the expected native engine classes are bundled. This avoids a fake VPN that installs a black-hole interface.

Native artifacts

Put reviewable, pinned artifacts in libs/ locally:

• freeturn.aar from the FreeTurn mobile package.
• libbox.aar or the exact private SignBox AAR with VLESS + AmneziaWG 3.1 support.

The files are git-ignored. Record version, commit and SHA-256 in THIRD_PARTY_NOTICES.md before distributing an APK. scripts/fetch-engine-artifacts.sh prints the upstream build commands and checks for the files; it does not silently download an unpinned binary.

scripts/build-android.sh extracts each present AAR's classes.jar and jni/* into the packaged Flutter plugin. This is required because Gradle does not allow a direct local .aar dependency while producing the plugin AAR. A missing artifact does not make a smoke APK pretend to work: the corresponding adapter returns UNSUPPORTED.

The first native milestone still needs device testing for VPN consent, foreground service timing, packet forwarding, hotspot interface discovery, and engine ABI/API.