# 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 . 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 ```bash 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: ```json {"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. ### Sprache der API-Meldungen Die `message`-Felder sind übersetzt, das `code`-Feld bleibt maschinenlesbar und unverändert. Die Sprache folgt dem Cookie `RHUB_LANG`; ohne Cookie antwortet die API deutsch. Die App sollte sich auf `code` verlassen, nicht auf den Text. ## Sprache der Web-Oberfläche Die Oberfläche ist deutsch und englisch. Standard ist Deutsch; umgeschaltet wird ausschließlich über den DE/EN-Umschalter in der Kopfzeile, der das Cookie `RHUB_LANG` (ein Jahr, `SameSite=Lax`) setzt. Es gibt keine automatische Erkennung – der Hub ist eine geschlossene Beta, und die Deutschfassung bleibt die Vorgabe. - Alle Texte stehen in `hub/app/i18n_strings.php` unter `de` und `en`, Zugriff über `t('schlüssel', ['platzhalter' => …])`. - `hub_locale()` liest das Cookie, `hub_locale_set()` schreibt es; die Route `/language?lang=de|en&next=…` setzt es und leitet zurück. - Datum und Zahlen folgen der Sprache: deutsch `12.11.2026 10:30` und `5,0 MB`, englisch `2026-11-12 10:30` und `5.0 MB`. - In den Texten steht kein HTML; sie werden an der Ausgabestelle mit `e()` maskiert. - `./tools/deploy_hub.sh --check` prüft, dass beide Sprachblöcke dieselben Schlüssel haben und dass jeder in `t()` verwendete Schlüssel existiert. - Neuer Text gehört immer in beide Blöcke; fehlt eine Übersetzung, zeigt `t()` den Schlüssel an, und der Check schlägt an. ## Deployment `tools/deploy_hub.sh` liest die Zugänge aus `docs/credentials.txt` (`FTP_*`, `DB_*`, `HUB_ADMIN_*`) und arbeitet über FTPS: ```bash ./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.