Skip to content

Android: native privacy-first app foundation - #4

Draft
21Koblenz wants to merge 13 commits into
mainfrom
agent/android-app-foundation
Draft

Android: native privacy-first app foundation#4
21Koblenz wants to merge 13 commits into
mainfrom
agent/android-app-foundation

Conversation

@21Koblenz

Copy link
Copy Markdown
Owner

Summary

Starts a native Android port of Bitcoin Stack Tracker without touching the existing Home Assistant integration.

Included in this first foundation

  • native Kotlin / Jetpack Compose app shell under android/
  • embedded Guardian Project Tor Android runtime (tor-android 0.4.9.11)
  • fail-closed routing policy modeled after the Home Assistant implementation
  • public and onion routes require Tor; public non-onion HTTP is blocked
  • explicit local/private node route with private-address classification
  • local DNS rebinding guard: every resolved direct address must remain private/local
  • fixed SOCKS proxy for public OkHttp traffic, redirects and connection retries disabled
  • public SOCKS route only becomes available after Tor reports an established circuit
  • Android Network Security Config keeps public cleartext disabled
  • Android Auto Backup/device transfer excluded for app data
  • Android Keystore AES-256-GCM device envelope key with StrongBox preference where available
  • no seed/private-key/signing functionality
  • unit tests for the network policy
  • Android-specific GitHub Actions build/test workflow
  • migration/security roadmap in android/README.md

Network contract

The intended rule remains the same as the Home Assistant tracker:

explicit own local/private node -> direct LAN
.onion/public destination       -> embedded Tor SOCKS
Tor unavailable                 -> no public Clearnet fallback

Public non-onion traffic additionally requires HTTPS. The routed client fixes the SOCKS proxy explicitly and does not use the system proxy selector for public traffic.

Important security boundary

The Home Assistant Tor Gateway can enforce egress with nftables. A normal Android APK does not automatically have an equivalent kernel firewall. This PR therefore establishes a single audited application routing layer first. Before a production Android release claims a full OS-level killswitch equivalent, the Android egress/leak guard (likely a dedicated VpnService design) must be implemented and leak-tested.

Next migration blocks

  1. encrypted local database + compatible ledger/FIFO model
  2. backup/import format compatibility
  3. overview, portfolios, targets, charts and performance calculations
  4. Sats Sentinel watch-only engine and local Electrum/Fulcrum/electrs/Mempool sources
  5. CSV imports
  6. background monitoring/notifications, Tor isolation rotation and leak-test suite

This PR is intentionally a draft until the Android build workflow is green and the first egress tests are in place.

Copy link
Copy Markdown
Owner Author

Foundation status update:

  • Android unit tests: ✅
  • assembleDebug: ✅
  • Debug APK artifact upload: ✅
  • Existing Hassfest validation: ✅
  • Existing HACS validation: ✅
  • Latest Android CI run: 32212400012
  • Head: 1f28b3427521cd66acd48317aa38a119679a2492
  • APK artifact SHA-256 (GitHub ZIP artifact): 4ee6ef4b4e107ecb60e887a14400571e70268fbe4f57f30128a23d192ce6c784

The PR intentionally remains draft: the native Tor/routing/Keystore foundation now compiles and is installable, but the full Home Assistant feature set (ledger/FIFO, portfolio, charts, market assessment, Sats Sentinel, imports, background monitoring and the Android OS-level egress/leak guard) still has to be ported before this should be treated as a production Android release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant