rinkplanner/docs/cloud-setup.md
torsten 6f22350934 feat: Sync-Einstellungen auf Dropbox festlegen
- Cloud-Ordner-Feld entfernt; der Sync nutzt fest den Dropbox-App-Ordner
  Apps/<App-Name>
- Alte directory-Einträge werden beim Laden einmalig entfernt, bei Bedarf
  mit Reset des Sync-Stands
- Google Drive erscheint nur noch, wenn Zugangsdaten im Build konfiguriert
  sind; sonst wird der Anbieter auf Dropbox normalisiert
- Roadmap, Sync-Doku und Cloud-Setup an den Dropbox-only-Stand angepasst
- Sync-Tests für Migration und Anbieter-Sichtbarkeit erweitert
2026-11-10 16:26:24 +01:00

11 KiB
Raw Blame 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 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:

    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 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:

    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 (derzeit Dropbox; Google Drive ist vorbereitet, aber nicht freigeschaltet).
  3. Verbinden…: Rinkplanner öffnet die Dropbox-Seite. Den dort angezeigten Code in die App einfügen und Verbinden drücken. (Die Google-Drive-Anmeldung per Gerätecode ist im Code vorhanden und wird aktiv, sobald die OAuth-App freigeschaltet ist.)
  4. Speichern, danach Datei → Jetzt synchronisieren.

Der Sync nutzt direkt den Dropbox-App-Ordner Apps/<App-Name>; bei Google Drive den von der App angelegten Ordner Rinkplanner. Ein eigener Cloud-Unterordner wird nicht abgefragt.

Jedes Gerät (Desktop und Tablet) wird einmal verbunden. Beide Geräte können dasselbe Konto verwenden; der Abgleich läuft über den gemeinsamen App-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.