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

```text
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.