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 and starts foreground immediately. The pinned libbox core asks PlatformInterface.openTun() to establish the TUN from its effective config; this prevents a fake Connected state with an unowned black-hole interface. Runtime state is persisted in SharedPreferences.

Native artifacts

Put reviewable, pinned artifacts in libs/ locally:

• libbox.aar from Leadaxe/sing-box-lx, version pinned in libbox.version.
• freeturn.aar may be kept for review, but is not packaged with libbox yet because their independently generated gomobile runtimes use conflicting global classes.

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 downloads the pinned libbox release and verifies its upstream SHA256SUMS.

scripts/build-android.sh extracts libbox'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 native milestone still needs physical-device testing for VPN consent, foreground service timing, packet forwarding, hotspot interface discovery, VLESS and AmneziaWG.