rinkplanner/docs/hub.md
torsten ab88a84d5d feat: Kür-Hub in der App anbinden
- Hub-Adresse und API-Token in den Sync-Einstellungen verbinden
- Verbindungstest über /api/v1/me, Token getrennt unter user://hub.cfg
- Datei → Kür-Hub… nur bei geprüfter Verbindung
- Alle veröffentlichten Küren durchsuchen, laden, veröffentlichen, verstecken
- Kollisionen: nummerierte Kopie mit Musik-Umbenennung oder Überschreiben
- HubSettings/HubClient/HubJob mit Worker-Thread und SHA-256-Prüfung
- Tests für Einstellungen, Fehler, Menü, Download und Kollisionen
2026-11-11 13:45:25 +01:00

14 KiB
Raw Blame History

Kür-Hub

Der Kür-Hub ist die geschlossene Beta-Ablage für Küren und ihre Musik. Nutzer laden ein Paket aus Rinkplanner-JSON und Audiodatei hoch, andere Beta-Nutzer sehen die Kür in einer Liste und laden sie wieder herunter. Die Godot-App bekommt dafür eine kleine JSON-API mit persönlichen Tokens.

Lebt unter https://rinkplanner-hub.programmschmiede.de. Der Code liegt im Repo unter hub/, die Binärdaten und die Serverkonfiguration bleiben auf dem Host.

Entscheidungen

Thema Entscheidung
Zugang Einladungscodes; genau ein Konto pro Code
Erster Nutzer HUB_ADMIN_USER aus docs/credentials.txt, Rolle admin
Inhalte Kür-Paket: JSON + optionale Audiodatei (MP3/OGG/WAV/M4A/AAC)
Sichtbarkeit Alles nur nach Anmeldung; versteckte Küren sieht der Eigentümer und der Admin
App-Anbindung Web-UI plus JSON-API v1 mit Bearer-Tokens
Stack PHP 8.5 ohne Framework, MariaDB 10.11, Apache/FTP-Deployment

Umgebung

Geprüft am 2026-11-11:

  • PHP 8.5.12 (FPM), pdo_mysql, mbstring, fileinfo, openssl, zip, intl.
  • MariaDB 10.11, DB d048f0d5, Zugriff nur vom Host (localhost).
  • upload_max_filesize/post_max_size 256 MB, max_allowed_packet 64 MB.
  • Kein SSH, kein Composer auf dem Host. Deployment per FTPS.

Verzeichnisse

Repo:

hub/
├── app/          # PHP: Bootstrap, DB, Auth, Routinen, Seiten, API
├── views/        # Server-gerenderte Templates
├── sql/          # schema.sql
├── web/          # DocumentRoot: index.php, .htaccess, assets/ (hub.css, logo.png)
├── install.php   # Einmal-Installer (löscht sich selbst)
└── app/config.example.php
tools/deploy_hub.sh

Server (rinkplanner-hub.programmschmiede.de/):

index.php, .htaccess, assets/
app/              # Konfiguration mit DB-Zugang, per .htaccess gesperrt
views/, sql/      # per .htaccess gesperrt
storage/
├── uploads/YYYY/MM/   # Zufallsnamen, nie direkt ausgeliefert
├── logs/php.log
├── .htaccess          # Require all denied
└── .installed

Datenmodell

Schema: hub/sql/schema.sql, Migrationstabelle schema_migrations.

Tabelle Zweck
users Konten, Rolle (admin/user), Status, Passwort-Hash, auth_epoch
invites Einmal-Codes (nur SHA-256 gespeichert), optional an E-Mail gebunden
routines Kür-Metadaten, Eigentümer, Status, aktuelle Revision, Downloadzähler
routine_revisions Jede hochgeladene Fassung mit Dateipfaden, Größe und SHA-256
downloads Download-Protokoll je Kür/Revision/Nutzer
api_tokens Persönliche App-Tokens (nur SHA-256, Präfix für die Anzeige)
remember_tokens „Angemeldet bleiben“ (Selector + Validator-Hash, Rotation)
login_attempts Fehlversuche für die Ratenbegrenzung
audit_log Admin- und Inhaltsereignisse

Wichtige Beziehungen:

  • routines.owner_id → users.id (ON DELETE CASCADE).
  • routine_revisions.routine_id → routines.id (ON DELETE CASCADE); routines.current_revision_id → routine_revisions.id (ON DELETE SET NULL).
  • Alte Revisionen bleiben erhalten; heruntergeladen wird immer die aktuelle.
  • Zeitstempel sind UTC, die Oberfläche zeigt Europe/Berlin.

Authentifizierung

Einladungen und Registrierung

  1. Admin erzeugt unter /admin/invites einen Code im Format RHUB-XXXX-XXXX-XXXX-XXXX. Der Klartext wird genau einmal angezeigt.
  2. In der DB liegt nur SHA-256(code); zusätzlich Notiz, optionale E-Mail-Bindung und Ablaufdatum.
  3. Registrierung unter /register?code=…: Benutzername, Anzeigename, optional E-Mail, Passwort, Beta-Regeln.
  4. In einer Transaktion wird der Nutzer angelegt und der Code atomar als eingelöst markiert. Schlägt die Markierung fehl, wird der Nutzer zurückgerollt. Ein eingelöster Code bleibt auch nach Löschen des Nutzers verbraucht (used_at).

Benutzername: 3–32 Zeichen, a-z 0-9 . _ -, Anfang/Ende alphanumerisch, reservierte Namen gesperrt. Passwort: mindestens 10 Zeichen.

Passwörter

  • password_hash() mit Argon2id, falls verfügbar, sonst PHP-Standard.
  • password_needs_rehash() wird bei der Anmeldung geprüft.
  • Kein Klartextpasswort in der DB, in Logs oder in der Konfiguration.
  • Der Installer erhält das Admin-Passwort per HTTPS, hasht es und speichert es nie im Klartext.

Sessions

  • Native PHP-Session, Cookie RHUB_SESSION: HttpOnly, Secure (unter HTTPS), SameSite=Lax, use_strict_mode.
  • Nach Login und Remember-Restore wird die Session-ID erneuert.
  • Idle-Timeout 14 Tage, absolute Lebensdauer 30 Tage.
  • users.auth_epoch wird bei Passwortwechsel, Admin-Reset, Sperre und Löschung erhöht. Jede Session speichert die Epoche; alte Sessions sind damit sofort ungültig, auch ohne Session-Tabelle.
  • Passwortwechsel, Reset und Sperre löschen zusätzlich alle „Angemeldet bleiben“- und API-Tokens des Kontos.

„Angemeldet bleiben“

  • Cookie RHUB_REMEMBER = selector:validator (30 Tage).
  • DB speichert den SHA-256 des Validators; bei Nutzung wird das Token rotiert (altes gelöscht, neues gesetzt).
  • Wird bei Passwortwechsel, Reset und Sperre gelöscht.

Ratenbegrenzung und CSRF

  • Fehlversuche: maximal 5 pro Benutzername und 10 pro IP in 15 Minuten; danach 429 mit Retry-After.
  • Alle Web-POSTs brauchen ein CSRF-Token aus der Session (hash_equals, Feld _csrf). Die API nutzt stattdessen Bearer-Tokens.
  • Login-Fehler sind bewusst generisch; bei unbekanntem Nutzer wird trotzdem ein Dummy-Hash geprüft.

Rollen

admin darf Einladungen, Nutzer und alle Küren verwalten. user darf Küren hochladen, eigene Küren verstecken/ändern und alles Sichtbare herunterladen. Der eigene Account lässt sich weder sperren noch löschen, damit immer ein Admin bleibt.

Dateien und Validierung

Upload (/upload, /routines/{id}/revise, POST /api/v1/routines):

  • Kürdatei: .json, max. 8 MiB, gültiges JSON, format = rinkplanner.routine, format_version 1, sections als Liste (max. 500).
  • Audiodatei: max. 50 MiB, Magic-Bytes-Prüfung (MP3/OGG/WAV/M4A/AAC), der Dateiname muss exakt dem Feld music_file der Kür entsprechen.
  • Eine Kür mit music_file braucht die Audiodatei; eine Kür ohne music_file darf keine Audiodatei mitbringen.
  • Rechte-Checkbox ist Pflicht (Web und API).
  • Ablage unter storage/uploads/YYYY/MM/ mit Zufallsnamen; Originalnamen stehen nur in der DB. storage/ ist per .htaccess und Rewrite gesperrt.
  • Download nur über PHP mit Anmeldung, Content-Disposition: attachment, SHA-256-Prüfsumme in der Detailansicht. Audio unterstützt HTTP-Range.
  • Upload-Limit: 20 Revisionen pro Nutzer und Stunde.
  • Doppelte Pakete desselben Nutzers (gleiche Kür- und Audio-SHA) werden erkannt und nicht doppelt angelegt.

Alte Revisionen bleiben auf der Platte, bis der Admin die Kür endgültig löscht. Die Kür-Detailseite zeigt immer die aktuelle Revision; Prüfsummen stehen darunter.

API v1

Basis: https://rinkplanner-hub.programmschmiede.de/api/v1

Token erzeugen

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -d '{"username":"…","password":"…","name":"Büro-PC"}' \
  https://rinkplanner-hub.programmschmiede.de/api/v1/tokens

Antwort 201 mit token (rhub_…), prefix, name, user. Das Token wird nur einmal ausgegeben; in der DB liegt nur der SHA-256. Alternativ lässt sich ein Token im Web unter /account erzeugen.

Endpunkte

Methode Pfad Zweck
GET /me eigenes Konto
GET /routines?q=&page=&per_page=&mine=1 Liste (max. 50 pro Seite)
GET /routines/{id} Metadaten + Download-URLs + Prüfsummen
POST /routines neues Paket (multipart: routine, audio, rights=1)
POST /routines/{id}/revisions neue Revision (Eigentümer/Admin)
DELETE /routines/{id} Kür verstecken (Eigentümer/Admin)
GET /routines/{id}/download Kür-JSON
GET /routines/{id}/audio Audiodatei (Range-fähig)

Alle außer /tokens brauchen Authorization: Bearer rhub_….

Fehlerformat:

{"error": {"code": "validation_failed", "message": "…"}, "errors": ["…"]}

Statuscodes: 401 Token fehlt/ungültig, 403 keine Berechtigung oder Passwortwechsel nötig, 404, 409 Duplikat, 422 Validierung, 429 Limit.

Deployment

tools/deploy_hub.sh liest die Zugänge aus docs/credentials.txt (FTP_*, DB_*, HUB_ADMIN_*) und arbeitet über FTPS:

./tools/deploy_hub.sh --sync      # Code + config.local.php hochladen
./tools/deploy_hub.sh --install   # Schema + ersten Admin anlegen (einmalig)
./tools/deploy_hub.sh --all       # sync + install + check
./tools/deploy_hub.sh --check     # Health, Login, Sperren, Installer prüfen

Ablauf der Erstinstallation:

  1. --sync lädt app/, views/, sql/, web/ und die generierte app/config.local.php (Modus 600) hoch.
  2. --install lädt install.php, ruft es per HTTPS mit Installations-Token und Admin-Zugang auf.
  3. Der Installer legt das Schema an, erzeugt den Admin, schreibt storage/.installed und löscht sich selbst.
  4. --check prüft /health, /login, dass app/config.local.php und storage/ gesperrt sind und der Installer weg ist.

Ein erneutes --sync ändert nur Code und Konfiguration; es installiert nicht neu. --install bricht ab, wenn bereits Benutzer existieren.

Administration

  • Einladungen: /admin/invites – Code erzeugen (Notiz, optionale E-Mail-Bindung, Gültigkeit), offene Codes widerrufen.
  • Benutzer: /admin/users – sperren/entsperren, Passwort zurücksetzen (temporäres Passwort wird einmal angezeigt, Wechsel beim nächsten Login erzwungen), Konto mit allen Küren löschen.
  • Küren: /admin/routines – suchen, verstecken/veröffentlichen, endgültig löschen (löscht auch alle Revisionsdateien).
  • Audit: /admin/audit – letzte Ereignisse (Login, Upload, Revision, Status, Einladungen, Token, Sperren).
  • API-Tokens: Nutzer verwalten ihre Tokens selbst unter /account.

Gespeicherte Kennwörter: nur Hashes. Für einen Notfallzugang kann der Admin sein Passwort über die Web-Oberfläche ändern; ohne funktionierenden Login hilft nur ein DB-Eingriff oder ein neuer Installationslauf.

Betrieb und Sicherheit

  • .htaccess: HTTPS erzwingen (auch hinter Proxy), app/, storage/, sql/, versteckte Dateien sperren, unbekannte Pfade an index.php.
  • PHP sendet CSP (script-src 'none', kein Inline-JS), nosniff, X-Frame-Options: DENY, Referrer-Policy: same-origin, HSTS.
  • Kein JavaScript, keine externen CDNs, dadurch kleine Angriffsfläche.
  • Uploads werden nie als ausführbarer Code abgelegt; nur .json und Audio-Endungen, Zufallsnamen, Rechte 0640.
  • Fehler gehen nach storage/logs/php.log, nie in die Antwort.
  • Backups: DB und storage/uploads/ sichern. Auf dem Host gibt es kein SSH; DB-Backup über das Hoster-Werkzeug (phpMyAdmin/DB-Verwaltung) oder einen zusätzlichen PHP-Backup-Endpunkt (noch nicht gebaut).
  • Das Beta-Paket enthält fremde Küren und Musik. Die Rechte-Checkbox ist eine Zusicherung des Uploaders, keine Lizenzprüfung. Bei Beschwerden Kür verstecken/löschen und Audit-Log prüfen.

Getestet am 2026-11-11

Auf der echten Subdomain durchgespielt:

  • Installation, Admin-Login, Session, Dashboard.
  • Einladung erzeugen, Registrierung, Login als Beta-Nutzer.
  • Upload einer Kür mit MP3, Detailseite, Download von JSON und MP3 (SHA-256 identisch), Downloadzähler.
  • Duplikat-Erkennung (409), neue Revision (201), Verstecken und Wiederveröffentlichen.
  • API-Token, /me, Liste, Detail, Download, fehlendes Token (401).
  • Admin-Löschung von Nutzer samt Kür; Upload-Dateien wurden entfernt.
  • Sperren von app/config.local.php, storage/; Installer nach der Installation nicht mehr erreichbar.
  • Godot-Client: Verbindungstest, Veröffentlichen per Multipart, Liste, Download mit SHA-256-Prüfung, Verstecken; Hub-Menü erscheint nur mit gültiger Verbindung.
  • Lokale Kollisionen: nummerierte Kopie mit umgeschriebener Musikreferenz und Überschreiben getestet.

App-Anbindung

Die Desktop-App verbindet den Hub getrennt vom Cloud-Sync:

  1. Im Hub unter Konto → API-Tokens ein Token erzeugen (rhub_…).
  2. In Rinkplanner Datei → Sync-Einstellungen… öffnen.
  3. Im Bereich Kür-Hub (Beta) Adresse und Token eintragen, Verbinden & testen drücken. Die App ruft GET /api/v1/me auf und zeigt den Kontonamen an.
  4. Erst danach erscheint Datei → Kür-Hub… im Dateimenü. Beim Trennen oder nach einem abgelaufenen Token verschwindet der Eintrag wieder.

Der Token liegt getrennt von den Cloud-Zugängen unter user://hub.cfg (auf Unix Modus 600) und wird nicht in Kürdateien oder sync.cfg geschrieben.

Im Hub-Dialog:

  • Alle Küren / Meine Küren durchsuchen; die Liste enthält alle veröffentlichten Küren aller Beta-Konten.
  • Vom Hub laden lädt JSON und Musik in user://routines/. Existiert der Dateiname bereits, bietet die App Nummerierte Kopie (beide Dateien bekommen „(Hub 2)“ und die Kür wird auf die neue Musik umgeschrieben) oder Überschreiben an. Eine Musikdatei, die noch von einer anderen Kür verwendet wird, wird nie überschrieben.
  • Aktuelle Kür veröffentlichen speichert die geöffnete Kür als JSON und lädt sie zusammen mit ihrer Musik hoch. Die Rechte-Checkbox ist Pflicht.
  • Aus Hub nehmen versteckt eine eigene Kür (Admins dürfen alle verstecken). Andere Beta-Konten sehen sie danach nicht mehr.

Offene Punkte

  • Optional: E-Mail-Versand für Einladungen und Passwort-Reset.
  • Optional: Quota pro Nutzer, Aufräumen alter Revisionen, Suche nach Kategorien/Saison.
  • Optional: Vorschau/Validierung der Kür im Hub (Sections zählen, Musiklänge).
  • Lizenz-/Rechteprüfung der Musik bleibt Aufgabe der Administration.