Android + Cloud Quickstart

Ziel

Diese Anleitung führt zum aktuell verifizierten lokalen Android-plus-Cloud-Pfad: Secure-Mux starten, tenant-gebundenes Token minten, Android-App auf ein USB-Gerät installieren und die ersten Read-/Write-Flows gegen das lokale Backend prüfen.

Voraussetzungen

• Workspace unter /Users/benediktpoller/code/sh
• Go-Toolchain
• JDK 17 oder 21
• Android SDK Platform 35
• curl, jq und adb
• Optional, aber für den verifizierten Pfad empfohlen: ein per USB angeschlossenes Android-Tablet

Schnell-Check: go version, java -version, adb version und ls "$HOME/Library/Android/sdk/platforms/android-35/". Fuer Details zu Umgebungsvariablen und SDK-Setup siehe Installation.

Hinweis

Superheld ist plattformgleich ausgerichtet. Store-Distribution, gehostete Produkt-Endpoints und Mehrplattform-Runtime sind hier nicht der verifizierte Ist-Stand.

Schritt 1: Lokales superheld-cloud im Secure-Mux starten

cd /Users/benediktpoller/code/sh/superheld-cloud
SUPERHELD_BOOTSTRAP_TOKEN=bootstrap-token \
SUPERHELD_BOOTSTRAP_TENANT_ID=tenant-local \
go run ./cmd/server

Fakten für diesen Lauf:

• Default-Bind ist 127.0.0.1:8080
• Secure-Mux verlangt SUPERHELD_BOOTSTRAP_TOKEN
• Persistenz liegt ohne Override standardmäßig unter ./data

Schritt 2: Tenant-gebundenes Android-Token minten

curl -s \
  -X POST http://127.0.0.1:8080/tokens \
  -H "Authorization: Bearer bootstrap-token" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["devices:write","events:write","status:read","alerts:read","incidents:read","jobs:read","jobs:write"]}' \
  | jq .

Das zurückgegebene Roh-Token ist der App-Token für den verifizierten Android-MVP. Die dazugehörige Tenant-Bindung bleibt die Runtime-Wahrheit. Wenn die App später mit einer anderen tenant_id startet, signalisiert sie den Drift jetzt explizit über Last backend tenant: ... plus Tenant-Mismatch-Warnung.

Schritt 3: Read-Pfade host-seitig prüfen

curl -s http://127.0.0.1:8080/status \
  -H "Authorization: Bearer <tenant-app-token>" | jq .

curl -s http://127.0.0.1:8080/alerts \
  -H "Authorization: Bearer <tenant-app-token>" | jq .

curl -s http://127.0.0.1:8080/incidents \
  -H "Authorization: Bearer <tenant-app-token>" | jq .

curl -s http://127.0.0.1:8080/jobs \
  -H "Authorization: Bearer <tenant-app-token>" | jq .

Damit ist vor dem Gerätestart geprüft, dass Token, Tenant-Bindung und Basis-Reads funktionieren.

Optional, aber im aktuellen Lauf verifiziert, um die Job-Karte mit echtem Backend-Inhalt zu fuellen:

curl -s \
  -X POST http://127.0.0.1:8080/jobs \
  -H "Authorization: Bearer <tenant-app-token>" \
  -H "Content-Type: application/json" \
  -d '{"job_class":"incident_triage","workflow_id":"incident_triage_v1","input_refs":{"event_ids":["evt-job-read-demo-missing"]}}' \
  | jq .

Schritt 4: Android-Build prüfen

cd /Users/benediktpoller/code/sh/superheld-android
ANDROID_USER_HOME=/Users/benediktpoller/code/sh/workspace/.android \
GRADLE_USER_HOME=/Users/benediktpoller/code/sh/workspace/.gradle-home \
./gradlew testDebugUnitTest assembleDebug

Schritt 5: USB-Tablet vorbereiten und App installieren

adb devices
adb reverse tcp:8080 tcp:8080

cd /Users/benediktpoller/code/sh/superheld-android
ANDROID_USER_HOME=/Users/benediktpoller/code/sh/workspace/.android \
GRADLE_USER_HOME=/Users/benediktpoller/code/sh/workspace/.gradle-home \
./gradlew connectedDebugAndroidTest \
  -Pandroid.testInstrumentationRunnerArguments.class=com.superheld.android.DeviceIdentityManagerInstrumentedTest

ANDROID_USER_HOME=/Users/benediktpoller/code/sh/workspace/.android \
GRADLE_USER_HOME=/Users/benediktpoller/code/sh/workspace/.gradle-home \
./gradlew installDebug \
  -Psuperheld.baseUrl=http://127.0.0.1:8080 \
  -Psuperheld.apiToken=<tenant-app-token> \
  -Psuperheld.tenantId=tenant-local

adb shell am start -W -n com.superheld.android/.MainActivity

Der verifizierte USB-Pfad verwendet in der App bewusst http://127.0.0.1:8080. 10.0.2.2:8080 bleibt nur der Emulatorpfad.

Schritt 6: Sichtbare App-Verifikation

Im aktuellen Geräteschnitt wurden diese Aktionen erfolgreich geprüft:

1. Register Device
2. Refresh Status
3. Send Demo Event
4. optional host-seitig Demo-Job anlegen
5. erneuter Refresh mit sichtbaren Alerts, Incidents und Jobs

Sichtbarer Negativfall:

• Mit einem Token ohne jobs:read zeigt die App Job read failed. plus HTTP 403 insufficient_scope.

Fehlerbehebung

Fehler	Ursache	Lösung
Server startet nicht sicher	Bootstrap-Token oder Tenant fehlen	SUPERHELD_BOOTSTRAP_TOKEN und SUPERHELD_BOOTSTRAP_TENANT_ID setzen
403 Forbidden	Fehlende Scope-Berechtigung	App-Token mit den nötigen Scopes neu minten
Tenant-Mismatch trotz erfolgreichem Refresh	Token ist an einen anderen Tenant gebunden als die in der App gesetzte tenant_id	App-Tenant an die Token-Bindung anpassen oder ein Token für den gewünschten Tenant neu minten
Tablet erreicht Backend nicht	adb reverse fehlt oder falsche Base-URL	adb reverse tcp:8080 tcp:8080 setzen und http://127.0.0.1:8080 verwenden
Keine Incident-Daten sichtbar	Es existiert aktuell noch kein tenant-sichtbarer Incident aus einem High-Severity-Alerting-Event oder Security-Monitor-Fall	Nach Send Demo Event erneut refreshen; alternativ vorhandene Security-Monitor-Incidents pruefen
Keine Job-Daten sichtbar	Es existiert aktuell kein tenant-sichtbarer Job	host-seitig einen kleinen Demo-Job über POST /jobs anlegen und erneut refreshen
Kein Emulator verfügbar	Lokale SDK-Installation enthält kein emulator-Binary	USB-Gerät als aktuellen Testpfad verwenden

Nächste Schritte

• Lokales Android-Cloud-Ops-Runbook — Start/Stop, Demo-Job, Trace-Lesen und Troubleshooting für denselben lokalen Pfad
• API-Übersicht — Alle Endpunkte und Schemas
• Authentifizierung — Token-Scopes und Secure-Mux
• Installation — kompletter lokaler Android-Installpfad
• Apps & Plattformen — aktueller Android-Stand vs. Zielarchitektur