rebreak-monorepo/ops/mdm/bootstrap-tool/README.md

ReBreak Supervise Bootstrap-Tool

CLI-Wrapper das ein unsupervised iPhone in den Zustand supervised + Rebreak-Schutz-Profil installiert überführt, ohne sichtbaren Daten-Verlust.

Mechanismus: TechLockdown-Stil Backup → Wipe → Supervise → Restore → Install-Profile. Aus User-Perspektive bleiben Apps + Daten + Login-States intakt; technisch wird das iPhone aber kurz gewiped.

Status

Prototype, Mac-only. Einige Steps (cfgutil-Syntax, idevicebackup2-Restore-Flags) sind erst nach Hardware-in-Loop-Test final verifiziert — markiert mit VERIFY ON DEVICE im Code.

Voraussetzungen (Mac des Users)

Tool	Installation
macOS	(jede aktuelle Version)
Apple Configurator 2	xcrun simctl install ... nein — Mac App Store, kostenlos
cfgutil CLI	Wird mit Apple Configurator 2 mitgeliefert (in .app/Contents/MacOS/)
libimobiledevice	brew install libimobiledevice
OpenSSL	Auf macOS vorhanden (/usr/bin/openssl)
Supervision-Identity (.p12)	Einmalig: siehe SUPERVISION-IDENTITY-SETUP.md

Voraussetzungen (iPhone des Users)

• iPhone wird per USB-C mit dem Mac verbunden
• iPhone ist entsperrt
• "Diesem Computer vertrauen?" wurde auf dem iPhone bestätigt
• Find My iPhone ist DEAKTIVIERT (sonst blockt Activation Lock den Wipe-Step)
  • Settings → [Name] → iCloud → Wo ist? → Mein iPhone suchen → Aus
  • Verlangt Apple-ID-Passwort des Users
• iCloud-Backup-Sync ist NICHT mitten in der Sitzung aktiv (idle)

Schnellstart

# Einmalig: Supervision-Identity generieren (siehe separates Doc)
cat SUPERVISION-IDENTITY-SETUP.md

# Dry-Run zum Check ob alle Deps + iPhone gefunden werden
./rebreak-supervise.sh --dry-run

# Echter Lauf
./rebreak-supervise.sh

# Falls's mittendrin failt: ab dem letzten OK-Step weitermachen
./rebreak-supervise.sh --resume

Was das Script macht — Schritt für Schritt

1. Preflight — Deps prüfen, iPhone-UDID detecten, Supervision-Identity laden, Profil-Plist validieren
2. Backup — idevicebackup2 backup --encryption on mit zufälligem Passwort (in ~/.rebreak-supervise/backup-pass-<UDID>.txt)
3. Supervise — cfgutil prepare --supervised --supervisor-host-certs <p12> wiped Gerät, setzt Supervised-Flag, rebootet
4. Restore — Nach Reconnect: idevicebackup2 restore mit selbem Passwort. Supervised-Flag bleibt persistent über Restore (Apple-Verhalten: Restore preserved supervision/enrollment-state, nicht den User-State der vorher unsupervised war)
5. Install-Profile — cfgutil install-profile rebreak-iphone-protection.mobileconfig

State + Logs

Artefakt	Zweck
~/.rebreak-supervise/state-<UDID>.env	Welche Steps erledigt (für --resume)
~/.rebreak-supervise/backups/<UDID>/	Encrypted Backup
~/.rebreak-supervise/backup-pass-<UDID>.txt	Backup-Encryption-Passwort (chmod 600)
~/.rebreak-supervise/supervision-identity.p12	Persistent über alle Devices/Sessions
~/.rebreak-supervise/log-<TIMESTAMP>.txt	Komplettes Log dieser Session

Alles unter ~/.rebreak-supervise/ (chmod 700). Niemals committen.

Failure-Pfade

Wann	Was tun
Preflight fail (Deps fehlen)	Deps installieren, neu starten
Backup fail (zB iPhone-Disconnect)	USB-Kabel checken, Trust-Dialog erneut. Backup neu starten (Script ist idempotent)
Supervise fail (Find-My noch aktiv)	iPhone ist NICHT gewiped, läuft normal weiter. Find-My deaktivieren, dann --resume
Supervise fail (Identity ungültig)	Neue Identity generieren (siehe Setup-Doc), dann --resume
Restore fail (Passwort verloren)	NICHT recoverbar. iPhone ist gewiped + Setup-Assistant aktiv. User muss neu einrichten oder iCloud-Backup nutzen
Profil-Install fail	Manuell via cfgutil install-profile <path> oder per AirDrop des .mobileconfig

Kritisch: Das Backup-Passwort darf nicht verloren gehen zwischen Step 2 und Step 4. Es liegt automatisch in ~/.rebreak-supervise/backup-pass-<UDID>.txt — falls der Mac dazwischen neu startet ist es noch da, aber für Disaster-Recovery sollte der User es notieren.

Post-Supervise: iOS-Setup-Stage

Nach Step 3 (Wipe) zeigt das iPhone wieder den "Hallo"-Screen. Folgender Stand wird vom Script erwartet bevor Restore startet:

• iPhone-Sprache wählen, Land/Region bestätigen
• Bis zum Screen "Apps & Daten übertragen" durchklicken
• NICHT "Aus iCloud-Backup wiederherstellen" wählen — wir restoren via libimobiledevice vom Mac
• "Nicht übertragen oder zurücksetzen" wählen ODER zurück bis zum Stage "Computer-Verbindung"

Das ist die einzige Stelle wo der User aktiv interagieren muss. Das Script prompted bevor es weiter macht.

Cross-Plattform-Pfad (Phase 2)

• Windows: braucht entweder iMazing-Lizenz (kommerzielle Whitelabel-Option, ähnlich TechLockdown) oder substantielle libimobiledevice-Erweiterung (Supervise ist heute nicht supported, GitHub-Issue offen). Aktuell out-of-scope.
• GUI (Tauri/Electron Wrapper): wenn der Bash-Flow stabil läuft. Vorerst CLI reicht für Validierung.

Bekannte Tücken

• iOS 18+ cfgutil-Syntax ist nicht 100% verifiziert. Apple-Doku-Lücken — cfgutil ist intern bei Apple priorisiert. VERIFY ON DEVICE-Marker im Script-Code zeigen wo's exakt zu testen ist.
• idevicebackup2 + iOS 18: libimobiledevice-Maintainer holen auf, neuere iOS-Versionen können Edge-Cases haben (z.B. neue Backup-Formate). Falls Backup-Tool failed mit "unknown response": auf libimobiledevice HEAD updaten (brew install --HEAD libimobiledevice).
• Supervised-State-Persistenz nach Restore: Apple-Doku sagt ja, Community-Reports sagen meistens ja, Edge-Cases existieren. Im Akzeptanz-Test (M2) explizit zu verifizieren.