mirror of
https://github.com/CyberMind-FR/secubox-deb.git
synced 2026-07-30 00:19:30 +00:00
CyberMind-FR
ac14e65353
- new wiki page Android-ToolBox.md (install via /wg/toolbox.apk, manual + root onboarding flows, CI build, endpoints) + sidebar link - README: document the root-mode silent path + revised constraints - WIP/TODO/HISTORY: Android client section (#531/#536/#538) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
92 lines
3.9 KiB
Markdown
92 lines
3.9 KiB
Markdown
<!-- SPDX-License-Identifier: LicenseRef-CMSD-1.0 -->
|
|
# 📱 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/`](https://github.com/CyberMind-FR/secubox-deb/tree/master/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):
|
|
|
|
```bash
|
|
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 |
|