Android ToolBox

📱 Android ToolBox — one-tap R3 onboarding

The SecuBox Android ToolBox is a tiny companion app that onboards a phone onto the VILLAGE3B cabine in one tap: it installs the cabine CA, brings up the WireGuard R3 tunnel, verifies reachability, then opens the live cartographie sociale. It replaces the manual Android tutorial.

• Source : clients/android-toolbox/
• Package : in.secubox.toolbox · Kotlin + Jetpack Compose · minSdk 26 / targetSdk 34
• License : LicenseRef-CMSD-1.0

Install

Grab the APK directly from the cabine — the toolbox serves it:

https://kbin.<board>.secubox.in/wg/toolbox.apk

The onboard panels in the kbin WebUI expose a 📱 Installer l'app ToolBoX (1-tap) button pointing at that endpoint. When the cabine has a locally fetched build it serves it (application/vnd.android.package-archive); otherwise it 302-redirects to the latest GitHub release asset secubox-toolbox-android.apk.

The MVP APK is debug-signed (sideload — enable Install unknown apps). A release-signed build with a published fingerprint is a follow-up (needs a keystore secret in CI).

Onboarding flows

Manual path (non-rooted)

1. Discover — scan the kbin QR or type the booth host (kbin.<board>.secubox.in).
2. Install CA — downloads /wg/ca.crt, launches the Android cert-install intent (KeyChain.createInstallIntent).
3. Import profile — downloads /wg/profile/new, hands the .conf to the official WireGuard app (FileProvider + ACTION_VIEW).
4. Verify — polls /wg/r3-check → Tunnel R3 actif ✓.
5. Live metrics — opens /social/me (cartographie sociale).

Android 11+ restricts user CA trust, so on a non-rooted device the browser CA confirm is a guided manual step.

Root path — fully-automated, silent (#538)

When the device is rooted, the Discover step shows an extra ⚡ Installation automatique (root) button. One tap runs everything with no further interaction (a RootAuto step streams the progress log):

1. System CA install — downloads /wg/ca.pem, computes the OpenSSL subject_hash_old in pure Kotlin, then bind-mounts a populated copy of the trust store over /system/etc/security/cacerts (+ the conscrypt APEX on Android 14), restoring the SELinux context u:object_r:system_security_cacerts_file:s0. Every app trusts the cabine CA — not just user-CA opt-in apps. Reversible via umount.
2. Native WireGuard — if the kernel has the WireGuard module + wg/ip, the tunnel comes up natively (ip link add … type wireguard + wg set) — no WireGuard app required.
3. Auto R3 verify — polls /wg/r3-check.

If the kernel lacks WireGuard, the root path installs the system CA then falls back to the manual WireGuard-app handoff.

Safety — every root action is gated behind the explicit tap; nothing runs as root unless the operator chooses root mode on their own device. Code: RootShell.kt (su wrapper) + RootOnboard.kt (silent sequence).

Build (CI)

No Gradle wrapper jar is committed (text-only scaffold). CI builds it:

• GitHub Actions build-android-apk.yml → debug APK artifact on push to master / PRs touching clients/android-toolbox/**.
• Tagging android-v* publishes the APK as a release asset.

Locally (Android SDK + Gradle 8.9 + JDK 17):

cd clients/android-toolbox
gradle :app:assembleDebug   # app/build/outputs/apk/debug/app-debug.apk

Cabine endpoints consumed

Endpoint	Purpose
/wg/ca.crt / /wg/ca.pem	cabine CA (user / system store)
/wg/profile/new	fresh WireGuard .conf
/wg/r3-check	tunnel reachability probe
/social/me	live cartographie sociale
/wg/toolbox.apk	the APK itself