rinkplanner/docs/cloud-setup.md
torsten 74d9d6b61f feat: Cloud-Sync über Dropbox und Google Drive
- FTP-Sync durch Cloud-Backends ersetzt (Dropbox, Google Drive)
- OAuth-Flow mit nutzereigenen Tokens und App-Key-Konfiguration
- Zeit-Tooltips für Timeline-Labels und Abschnittsbanner beim Playback
- Tests, Build-Konfiguration und Doku aktualisiert
2026-11-09 06:25:21 +01:00

238 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Cloud-Sync einrichten (Google Drive / Dropbox)
Rinkplanner speichert Kürdateien und Musik im **eigenen Cloud-Konto jedes
Nutzers**. Dafür registriert der Entwickler einmalig eine OAuth-App pro
Anbieter. Nutzer melden sich in ihrem Browser mit ihrem eigenen Konto an; die
App sieht niemals deren Passwort.
## Warum keine E-Mail-/Passwort-Anmeldung?
Google Drive und Dropbox haben die Anmeldung mit Benutzername und Passwort
über ihre APIs abgeschaltet. Ein `GOOGLE_PASSWORD` oder `DROPBOX_PASSWORD` in
`docs/credentials.txt` kann deshalb nicht verwendet werden. Nötig sind:
- eine **App-Registrierung** (Client-ID/App-Key) für Rinkplanner,
- pro Nutzer ein **Refresh-Token** aus dem OAuth-Flow.
Die App-Registrierung ist öffentlich (vergleichbar mit einem Paketnamen). Der
Refresh-Token ist das eigentliche Geheimnis und bleibt auf dem Gerät des
Nutzers in `user://sync.cfg`.
## Google Drive
1. In der [Google Cloud Console](https://console.cloud.google.com/) ein
Projekt anlegen (z. B. `Rinkplanner`).
2. **APIs & Dienste → Bibliothek → Google Drive API** aktivieren.
3. **OAuth-Zustimmungsbildschirm** einrichten:
- Nutzertyp **Extern**
- App-Name `Rinkplanner`, Support- und Entwickler-E-Mail
- Scopes:
- `https://www.googleapis.com/auth/drive.file`
- `openid`
- `email`
- Solange die App im Status **Testing** ist, müssen Testkonten unter
„Testnutzer“ eingetragen werden. Refresh-Tokens aus dem Testing-Status
laufen nach sieben Tagen ab; für den Dauerbetrieb die App
veröffentlichen („In Produktion“).
4. **Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID**:
- Anwendungstyp **TVs and Limited Input devices** (Device Flow).
- Die Client-ID und das Client-Secret notieren.
5. Werte in `docs/credentials.txt` eintragen:
```ini
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
```
6. `./tools/sync_apps_config.sh` ausführen. Das schreibt die App-Werte nach
`rinkplanner/sync_apps.cfg` (gitignored, wird in den Build eingebettet).
`drive.file` ist ein nicht-sensibler Scope: Die App darf nur Dateien sehen,
die sie selbst angelegt hat. Sie kann nicht das übrige Google Drive des
Nutzers lesen. Rinkplanner legt dafür den Ordner `Rinkplanner` an.
## Dropbox
1. In der [Dropbox App Console](https://www.dropbox.com/developers/apps) eine
App anlegen.
2. **Zugriffstyp: App folder** (nicht „Full Dropbox“). Damit landet alles in
`Apps/<App-Name>/` und Rinkplanner sieht keine anderen Dateien. Der
App-Name bestimmt den Ordnernamen; nach der Produktionsfreigabe ist er
nicht mehr änderbar.
3. **Permissions** setzen:
- `files.content.read` (Download)
- `files.content.write` (Upload/Überschreiben)
- `files.metadata.read` (Ordner auflisten)
- `files.metadata.write` (Zielordner anlegen, umbenennen, löschen)
- `account_info.read` (nur für die Anzeige der Konto-E-Mail)
Änderungen mit **Save changes** speichern. Bereits verbundene Konten
müssen sich danach neu verbinden, weil der Token die alten Rechte behält.
4. **Settings → OAuth 2**:
- **Redirect-URI leer lassen** (wir nutzen den Code-Flow ohne Redirect).
- **Allow public clients / PKCE** aktivieren, falls vorhanden.
5. **App Key** notieren. Ein App Secret ist für den PKCE-Flow nicht nötig;
optional kann es ebenfalls eingetragen werden.
6. Werte in `docs/credentials.txt` eintragen:
```ini
DROPBOX_APP_KEY=...
# optional:
DROPBOX_APP_SECRET=...
```
7. `./tools/sync_apps_config.sh` ausführen.
8. **Settings → App configuration → Development users**: **Enable additional
users** aktivieren, sonst kann nur dein eigenes Dropbox-Konto die App
verbinden. In der Development-Phase sind bis zu 500 Nutzer möglich.
Der Dropbox-Flow nutzt **PKCE ohne Redirect-URI**: Nach der Anmeldung zeigt
Dropbox einen Autorisierungscode an, den der Nutzer in Rinkplanner einfügt.
Das funktioniert auf Desktop und Android ohne lokalen Callback-Server.
## Veröffentlichungsstatus: Testing vs. Produktion
„Veröffentlichen“ ist keine Veröffentlichung im App-Store, sondern der
Wechsel der OAuth-App vom Test- in den Produktivstatus beim jeweiligen
Anbieter. Das ist nötig, damit Tokens nicht ablaufen und beliebig viele
Nutzer das Konto verbinden können.
### Google Drive
| | Testing | In Produktion |
| :--- | :--- | :--- |
| Nutzer | max. 100 Testnutzer | beliebige Google-Konten |
| Refresh-Token | **läuft 7 Tage nach der Zustimmung ab** | bleibt gültig, bis der Nutzer den Zugriff widerruft |
| Warnung | „Ungeprüfte App“ möglich | für `drive.file` in der Regel keine Scope-Prüfung |
Die 7-Tage-Regel gilt, weil Rinkplanner neben `openid`/`email` auch
`drive.file` anfragt. Die Ausnahme für reine Anmelde-Scopes greift hier
nicht.
**Konkret zu tun:**
1. Im Google-Cloud-Projekt unter **Google Auth Platform → Branding**:
App-Name, Support-E-Mail, Entwicklerkontakt, Startseite, Datenschutz-URL
und autorisierte Domain eintragen. Diese Links sind für externe
Produktions-Apps erforderlich.
2. Unter **Audience** auf **Publish app** klicken. Der Status wechselt zu
**In production**.
3. Eine **Markenprüfung** kann nötig sein, damit Name und Logo auf dem
Zustimmungsbildschirm erscheinen. Sie ist kein Security-Audit und dauert
laut Google meist nur Minuten, kann aber einige Tage brauchen.
4. Eine **Datenzugriffsprüfung** ist für `drive.file` nicht erforderlich,
weil der Scope als nicht-sensibel gilt. Ein teures Security-Assessment
ist damit nicht verbunden.
5. Nutzer, die schon im Testing-Status verbunden waren, müssen sich nach
dem Veröffentlichen **einmal neu verbinden**, damit sie einen
langlebigen Refresh-Token erhalten.
Kosten: keine. Google verlangt für `drive.file` keine Verifikationsgebühr.
Wenn nur du und ein paar Testgeräte den Sync nutzen, kannst du im
Testing-Status bleiben – dann muss jedes Gerät wöchentlich neu verbinden.
Für den echten Betrieb ist „In production“ die richtige Wahl.
### Dropbox
| | Development | Production |
| :--- | :--- | :--- |
| Nutzer | bis 500 verbundene Dropbox-Konten | unbegrenzt |
| Review | erst ab 50 verbundenen Nutzern (oder early review) | erforderlich |
| App-Name | änderbar | **nach der Freigabe nicht mehr änderbar** |
**Konkret zu tun:**
1. In der Dropbox App Console unter **Branding** ein App-Icon hinterlegen.
2. Unter **Settings → App configuration → Apply for production** den Antrag
ausfüllen: wie die App die API nutzt, warum App-Folder-Zugriff reicht,
Datenschutz-URL usw.
3. Der Antrag wird regulär erst geprüft, wenn die App **50 Nutzer** verbunden
hat. Ab 50 Nutzern hast du zwei Wochen Zeit, die Produktionsfreigabe zu
erhalten; sonst werden weitere Verbindungen blockiert.
4. Nach der Freigabe sind unbegrenzt viele Nutzer möglich. Der App-Name
bleibt dann fest.
Für eine kleine geschlossene Testgruppe reicht Development. Sobald
Rinkplanner an mehr als 50 Personen geht, sollte der Produktionsantrag
vorbereitet sein.
Wichtig für die Musik: Dropbox genehmigt keine Apps, die
Urheberrechtsverletzungen fördern. Rinkplanner stellt keine Dateien bereit
und teilt keine Musik zwischen Nutzern; die App sollte auch im Store-Text
nicht so beworben werden. Musik im eigenen Konto des Nutzers ist der
vorgesehene Fall.
## App-Werte ohne Repository-Datei
`SyncAppConfig` liest die App-Zugänge in dieser Reihenfolge (spätere Quellen
überschreiben frühere):
1. Umgebungsvariablen
`RINKPLANNER_GOOGLE_CLIENT_ID`, `RINKPLANNER_GOOGLE_CLIENT_SECRET`,
`RINKPLANNER_DROPBOX_APP_KEY`, `RINKPLANNER_DROPBOX_APP_SECRET`
2. `res://sync_apps.cfg` (beim Build eingebettet)
3. `user://sync_apps.cfg` (lokale Entwickler-Installation)
Für Release-Builds muss `rinkplanner/sync_apps.cfg` vor dem Export existieren.
Fehlt sie, startet die App normal, zeigt beim Verbinden aber einen Hinweis,
dass der Cloud-Sync in diesem Build nicht eingerichtet ist.
Die Datei wird am besten mit `./tools/sync_apps_config.sh` erzeugt. Godots
`ConfigFile`-Format erwartet Kommentare mit `;` und Strings in
Anführungszeichen (`dropbox_app_key="..."`); `#`-Kommentare oder unquoted
Werte führen zu einem Parse-Fehler.
## Nutzerfluss in der App
1. **Datei → Sync-Einstellungen…**
2. Anbieter wählen (Dropbox oder Google Drive).
3. **Verbinden…**:
- Google Drive: Rinkplanner zeigt einen Code und öffnet die
Google-Anmeldeseite. Nach der Bestätigung schließt sich der Dialog.
- Dropbox: Rinkplanner öffnet die Dropbox-Seite. Den dort angezeigten Code
in die App einfügen und **Verbinden** drücken.
4. Cloud-Ordner festlegen. Bei Dropbox leer lassen, dann liegt alles direkt
im App-Ordner `Apps/<App-Name>`. Bei Google Drive legt die App den Ordner
`Rinkplanner` an.
5. **Speichern**, danach **Datei → Jetzt synchronisieren**.
Jedes Gerät (Desktop und Tablet) wird einmal verbunden. Beide Geräte können
dasselbe Konto verwenden; der Abgleich läuft über den Cloud-Ordner.
## Lizenzen und Musikdateien
- Musikdateien werden ausschließlich im Konto des Nutzers gespeichert.
Rinkplanner betreibt keinen Speicher und keine zentrale Kopie.
- Die App greift bei Google Drive nur auf `drive.file`-Dateien zu, bei Dropbox
nur auf den App-Ordner. Es gibt keinen Zugriff auf fremde Konten.
- Es gibt kein gemeinsames Rinkplanner-Konto, über das Musik weitergegeben
würde. Jeder Nutzer ist für die Rechte an seinen hochgeladenen Dateien
selbst verantwortlich.
- In der App und in der Datenschutzerklärung sollte dieser Hinweis stehen:
„Musikdateien werden im eigenen Cloud-Konto gespeichert. Für die
Nutzungsrechte ist der Nutzer verantwortlich.“
## Sicherheit
- Nutzerpasswörter werden nie abgefragt und nie gespeichert.
- Refresh-Tokens liegen in `user://sync.cfg` (app-privat). Auf Android ist das
der interne App-Speicher; auf dem Desktop
`~/.local/share/godot/app_userdata/Rinkplanner/`.
- **Trennen** in den Sync-Einstellungen löscht den Token auf dem Gerät. Die
Cloud-Dateien bleiben erhalten.
- Ein widerrufener Zugriff führt beim nächsten Sync zu einer verständlichen
Fehlermeldung; anschließend neu verbinden.
- Das Google-Client-Secret ist bei installierten Apps nicht geheim. Es
identifiziert die App, nicht den Nutzer. Dropbox nutzt PKCE und kommt ohne
Secret aus.
## Veröffentlichung
- Google: OAuth-Zustimmungsbildschirm veröffentlichen. `drive.file` ist
nicht-sensibel; trotzdem können Angaben zu Datenschutz und
Entwickleridentität verlangt werden.
- Dropbox: Produktionszugriff in der App Console beantragen. App-Folder-Apps
haben vor der Freigabe ein Nutzerlimit.
- Für Stores eine Datenschutzerklärung hinterlegen, die den Cloud-Zugriff und
die Musikverantwortung beschreibt.