rinkplanner/docs/cloud-setup.md

239 lines
10 KiB
Markdown
Raw Normal View History

# 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.