VPN App

Private Android/Desktop client built as a small monorepo:

• app/ — Flet/Python UI, profiles, settings, runtime state and common business logic.
• native/android/ — Flet service extension and Kotlin service boundary. VPN lifecycle, TUN, foreground service, hotspot and mobile libraries belong here, not in Python.
• backend/ — deliberately small FastAPI + SQLite operator API and device subscription endpoint.
• docs/ — architecture, upstream research, implementation status and device test plan.

The current product scope is Android first and desktop proxy-only. iOS is intentionally not in this repository. macOS is not a target of the first build; if added later it will be proxy-only unless a separate native implementation is approved.

Current product model

The app has two top-level tabs:

• VPN — Основная (VLESS) and Усиленная (AmneziaWG 3.1), both through the SignBox adapter contract.
• Белые списки — FreeTurn, with stream presets 1..4, CAPTCHA handling and optional stability mode.

The Python engine manager is real and tested. Desktop SignBox proxy mode can launch a configured local executable when one is supplied. Android native lifecycle and command protocol are implemented; FreeTurn is integrated from a pinned local AAR during the build, while SignBox remains UNSUPPORTED until the exact signed artifact and API are supplied. Engine AARs are intentionally not checked into git. The UI never treats an unsupported result as a successful connection.

The exact remaining functional blockers are tracked in docs/implementation-status.md; an APK build alone is not evidence that the missing VPN data path works.

Quick start

uv sync
uv run flet run app/main.py
uv run pytest

Run the backend locally:

export VPNAPP_ADMIN_TOKEN='replace-this-in-a-secret-shell'
uv run uvicorn backend.main:app --reload --port 8080

The backend deliberately requires HTTPS in deployment. VPNAPP_ADMIN_TOKEN is an operator credential only. Devices use a separate random bearer credential; UUIDs and User-Agent strings are not authentication.

Build scripts

./scripts/fetch-engine-artifacts.sh       # optional, requires upstream build tools
./scripts/build-android.sh                # flet build apk (requires Android SDK/Flutter)
./scripts/build-desktop.sh linux          # flet build linux
./scripts/run-backend.sh                  # local backend

For Android, ./scripts/build-android.sh builds an arm64 APK with any reviewed artifacts present locally; missing engines report UNSUPPORTED at runtime. For a releasable build, place the exact freeturn.aar and compatible libbox.aar under native/android/libs/ (the directory is ignored to avoid silently shipping unreviewed native code) and set REQUIRE_NATIVE_ARTIFACTS=1.

Security posture

The default proxy bind is localhost. Wi-Fi sharing is explicit, binds to the discovered LocalOnlyHotspot address, and requires authentication by default. Management/debug APIs are disabled by default. Secrets are redacted from logs. Application routing models distinguish PROXY, DIRECT, and VOID; native UID matching and fail-closed VOID enforcement are not yet shipped and are never presented as active security.

License and upstreams

This repository's original code is MIT-licensed; see LICENSE. Upstream components, versions, URLs and license obligations are recorded in THIRD_PARTY_NOTICES.md. Do not copy the GPL Android reference application's UI or source into this project.