210 lines
8.2 KiB
Markdown
210 lines
8.2 KiB
Markdown
# Rebreak Magic (Mac)
|
|
|
|
End-User-Wizard für Self-Binding eines iPhones an Rebreak. Macht in einem 5-Step-Flow:
|
|
|
|
1. **Welcome** — Detect iPhone via USB (lockdownd)
|
|
2. **Pre-Flight** — Find-My-iPhone + Stolen-Device-Protection prüfen/ausschalten
|
|
3. **Supervise** — `supervise-magic` Plist-Inject + Reboot (kein Erase)
|
|
4. **Enroll** — MDM-Enrollment-Profile auf iPhone installieren
|
|
5. **Configure** — NanoMDM pusht: Lock-Profile + Take-Management + Settings(mdmSupervised=true)
|
|
|
|
Resultat: iPhone supervised by "Rebreak", App nicht löschbar, NEFilter aktiv (kein User-Toggle in Settings).
|
|
|
|
## Warum "Magic"?
|
|
|
|
Normalerweise muss ein iPhone **komplett zurückgesetzt** werden um es zu supervisen (alle Daten weg, Werks-Setup, Apple-Configurator-Kabel-Pairing mit komplexem Setup).
|
|
|
|
Rebreak Magic macht das **ohne Reset** — deine Fotos, Apps, Settings bleiben. Das ist in der Branche unüblich und spart den Betroffenen massiv Zeit und Frust beim Onboarding.
|
|
|
|
**Pre-Requirement**: Rebreak-App muss VOR Wizard-Start aus TestFlight installiert sein. Wizard nutzt `InstallApplication` mit `ChangeManagementState: Managed` (kein ManifestURL nötig, kein ABM-Account). Auto-Install via MDM-Push ist Phase 2 (braucht ABM oder Manifest-Hosting).
|
|
|
|
## Voraussetzungen
|
|
|
|
| Tool | Wie |
|
|
|---|---|
|
|
| Xcode 16+ | App Store |
|
|
| xcodegen | `brew install xcodegen` |
|
|
| libimobiledevice | `brew install libimobiledevice` |
|
|
| supervise-magic binary | aus `../../ops/mdm/supervise-magic/` (`make build`) |
|
|
| cfgutil | Apple Configurator (App Store) → `/Applications/Apple Configurator.app/Contents/MacOS/cfgutil` für silent profile install |
|
|
| create-dmg | `brew install create-dmg` (für DMG-Build)
|
|
|
|
Ja. Es nutzt Apple-offizielle MDM-APIs (gleiche wie Schul-iPads). Es installiert nichts Apple-Fremdes. Die Supervision kann jederzeit aufgehoben werden (Settings → Allgemein → VPN & Geräteverwaltung → Profile entfernen → Reboot).
|
|
|
|
### Was bedeutet das für mich?
|
|
|
|
- Die Rebreak-App ist nicht mehr per "App wackelt → X tippen" löschbar
|
|
- Der NEFilter (Gambling-Domain-Blocker) lässt sich nicht in den Settings ausschalten
|
|
- Du brauchst die Rebreak-Vertrauensperson um die Bindung zu lösen
|
|
|
|
### Kann ich das rückgängig machen?
|
|
|
|
Ja, aber mit Absicht — nicht im Affekt. Siehe Rebreak-App → Settings → Trustee-Override (7-Tage-Cooldown).
|
|
|
|
### Welche Daten sieht Rebreak?
|
|
|
|
Nur dass dein Device supervised IST + an unseren MDM-Server enrollt. Keine Inhalte, keine Browsing-History, keine Telemetrie über deine Nutzung.
|
|
|
|
## Status
|
|
|
|
🚧 Phase 1 — Skelett. Nur lokal nutzbar (User+Olfa+Dev-iPhones).
|
|
|
|
## Voraussetzungen
|
|
|
|
| Tool | Wie |
|
|
|---|---|
|
|
| Xcode 26+ | App Store |
|
|
| xcodegen | `brew install xcodegen` |
|
|
| libimobiledevice | `brew install libimobiledevice` |
|
|
| supervise-magic binary | aus `../../ops/mdm/supervise-magic/` (`make build`) |
|
|
| cfgutil | Apple Configurator (App Store) → `/Applications/Apple Configurator.app/Contents/MacOS/cfgutil` für silent profile install |
|
|
|
|
## Build
|
|
|
|
### Development-magic-mac
|
|
|
|
# Einmalig: dependencies + supervise-magic-binary bauen
|
|
(cd ../../ops/mdm/supervise-magic && make tidy && make build)
|
|
|
|
# Xcode-Project generieren (oder neu generieren nach project.yml Änderungen)
|
|
xcodegen generate
|
|
|
|
# Bauen + öffnen
|
|
open RebreakMagic.xcodeproj
|
|
# → ⌘R in Xcode
|
|
```
|
|
|
|
Oder CLI-only:
|
|
|
|
```bash
|
|
xcodebuild -project RebreakMagic.xcodeproj -scheme RebreakMagic -configuration Debug build
|
|
open build/Build/Products/Debug/RebreakMagic.app
|
|
```
|
|
|
|
### Production-DMG (für Distribution)
|
|
|
|
```bash
|
|
./build-dmg.sh
|
|
```
|
|
|
|
Output: `build/RebreakMagic-0.1.0.dmg`
|
|
|
|
**Hinweis**: App ist unsigned (ad-hoc signature). User braucht Right-Click → Öffnen beim ersten Start (Gatekeeper-Warning). Für Production: Developer ID Application Cert nötig.
|
|
|
|
Falls das Icon nicht sofort erscheint nach Installation:
|
|
|
|
```bash
|
|
sudo rm -rf /Library/Caches/com.apple.iconservices.store && killall Dock
|
|
```
|
|
- Notarization via `xcrun notarytool`
|
|
- Staple Notarization-Ticket: `xcrun stapler staple`
|
|
- DMG dann ohne Gatekeeper-Warning installierbar
|
|
|
|
### App-Icon
|
|
|
|
Das Rebreak-Logo ist im `Sources/Resources/Assets.xcassets/AppIcon.appiconset/` integriert (alle macOS-Größen von 16x16 bis 1024x1024). Icons werden aus `apps/rebreak-native/assets/icon.png` generiert.
|
|
|
|
Falls Icons neu generiert werden müssen (z.B. nach Logo-Update):
|
|
|
|
```bash
|
|
# Master-Icon aus rebreak-native kopieren
|
|
cp ../rebreak-native/assets/icon.png /tmp/master-icon.png
|
|
|
|
# macOS-Icon-Größen generieren via sips
|
|
cd Sources/Resources/Assets.xcassets/AppIcon.appiconset/
|
|
sips -z 16 16 /tmp/master-icon.png --out icon_16x16.png
|
|
sips -z 32 32 /tmp/master-icon.png --out icon_16x16@2x.png
|
|
sips -z 32 32 /tmp/master-icon.png --out icon_32x32.png
|
|
sips -z 64 64 /tmp/master-icon.png --out icon_32x32@2x.png
|
|
sips -z 128 128 /tmp/master-icon.png --out icon_128x128.png
|
|
sips -z 256 256 /tmp/master-icon.png --out icon_128x128@2x.png
|
|
sips -z 256 256 /tmp/master-icon.png --out icon_256x256.png
|
|
sips -z 512 512 /tmp/master-icon.png --out icon_256x256@2x.png
|
|
sips -z 512 512 /tmp/master-icon.png --out icon_512x512.png
|
|
sips -z 1024 1024 /tmp/master-icon.png --out icon_512x512@2x.png
|
|
```
|
|
|
|
## Config (lokal)
|
|
|
|
NanoMDM-API-Key braucht die App für Step 5 (Configure). Lege ein lokales config-file an:
|
|
|
|
```bash
|
|
cat > ~/.config/rebreak-binder/config.json <<'EOF'
|
|
{
|
|
"mdmServer": "https://mdm.rebreak.org",
|
|
"mdmUser": "nanomdm",
|
|
"mdmApiKey": "<32-char-hex from /root/.nanomdm_admin_pass on rebreak-mdm>"
|
|
}
|
|
EOF
|
|
chmod 600 ~/.config/rebreak-binder/config.json
|
|
```
|
|
|
|
Production-Version legt das in Keychain ab — heute reicht plain JSON.
|
|
|
|
## Troubleshooting
|
|
|
|
### iPhone wird nicht erkannt
|
|
|
|
```bash
|
|
# Prüfe libimobiledevice
|
|
idevice_id -l
|
|
# Falls leer: USB-Kabel-/Port-Problem oder "Diesem Computer vertrauen?" Dialog nicht bestätigt
|
|
|
|
# PRelated Docs
|
|
|
|
- [ops/mdm/ARCHITECTURE.md](../../ops/mdm/ARCHITECTURE.md) — MDM-Infrastruktur-Overview
|
|
- [ops/mdm/PHASES.md](../../ops/mdm/PHASES.md) — Roadmap (Self-Binding → ABM-DEP → Mac-Support)
|
|
- [ops/mdm/RUNBOOK.md](../../ops/mdm/RUNBOOK.md) — NanoMDM-Server-Operations
|
|
- [ops/mdm/supervise-magic/README.md](../../ops/mdm/supervise-magic/README.md) — supervise-magic-Technical-Deep-Dive
|
|
|
|
## License
|
|
|
|
Proprietary. © 2026 Raynis GmbH.
|
|
|
|
../../ops/mdm/supervise-magic/bin/supervise-magic --device <udid>
|
|
# Check stdout/stderr
|
|
```
|
|
|
|
### MDM-Enrollment schlägt fehl
|
|
|
|
- Prüfe NanoMDM-Server: `ssh rebreak-mdm 'pm2 status'` → `nanomdm-server` muss `online` sein
|
|
- Prüfe nginx: `ssh rebreak-mdm 'curl -I https://mdm.rebreak.org'` → 200 OK
|
|
- Prüfe APNs-Cert-Ablauf: siehe `ops/mdm/RUNBOOK.md` → APNs-Cert-Renewal-Section
|
|
|
|
### Icon wird als Placeholder angezeigt
|
|
|
|
macOS Icon-Cache clearen:
|
|
|
|
```bash
|
|
sudo rm -rf /Library/Caches/com.apple.iconservices.store
|
|
killall Dock Finder
|
|
```
|
|
|
|
Dann App neu starten.
|
|
|
|
## TODOs (post-Skelett)
|
|
|
|
- [ ] **Lock-Profile-Refactor**: `allowAppRemoval=false` GLOBAL raus aus `rebreak-content-filter-sideload.mobileconfig`. Per-App-Lock kommt über Managed-App-State (MDM `InstallApplication` mit `ChangeManagementState: Managed` → iOS deaktiviert App-Wackel-„X" automatisch für managed apps). Andere Apps bleiben löschbar (bessere UX).
|
|
- [ ] App-Versions-Mgmt: `InstallApplication`-Manifest-URL-Pointer auf latest IPA (siehe `ops/mdm/PHASES.md` Phase F.5)
|
|
- [ ] Trustee-Setup-Optional in DoneView (Email an Vertrauensperson)
|
|
- [ ] 7-Tage-Cooldown-Persistenz (lokale SQLite oder Backend)
|
|
- [ ] Code-Signing + Notarization (Developer-ID)
|
|
- [ ] Backend `/api/binder/*` Endpoints — Mac-App spricht heute MDM-Server direkt
|
|
|
|
## Architektur
|
|
|
|
- **SwiftUI macOS-App** mit `@Observable` State-Machine (`WizardModel`)
|
|
- **Services** sind dünne Wrapper um:
|
|
- `ideviceinfo` (libimobiledevice) — Device-Detection
|
|
- `supervise-magic` Go-CLI — Supervise + Status-Check
|
|
- `cfgutil` (optional, Apple Configurator 2) — Silent Profile-Install
|
|
- NanoMDM HTTP-API (`mdm.rebreak.org`) — InstallProfile + Settings-Commands
|
|
- **Kein Backend-Account-Login** für MVP — API-Key in lokalem Config
|
|
|
|
## Sicherheit
|
|
|
|
- API-Key sollte langfristig in Keychain (heute: plain JSON, chmod 600)
|
|
- App ist **unsigned** für lokales Testen — Gatekeeper-Warning beim ersten Öffnen (Right-Click → Öffnen)
|
|
- Production: Developer ID Application Cert + Notarization nötig (siehe Build → DMG)
|
|
- Process-Spawn von go-binaries braucht **disabled App-Sandbox** (gesetzt in `project.yml`)
|