Website (rinkplanner.programmschmiede.de) liegt jetzt im Repo unter web/: Sprachweiche nach Accept-Language (der User-Agent enthält keine Sprache), /de/ und /en/ als eigene URLs mit hreflang, Cookie für die manuelle Wahl, Texte in web/i18n.php, Markup in web/template.php. Deployment über tools/deploy_web.sh (--sync, --check, --all); /index.html leitet weiter. Hub: optionale englische Oberfläche über den DE/EN-Umschalter, Cookie RHUB_LANG, Route /language. Alle Texte (Views, Meldungen, Validierung, API-messages) stehen in hub/app/i18n_strings.php und laufen über t(); Datum und Zahlen folgen der Sprache. Die API behält ihre code-Felder und antwortet ohne Cookie weiter deutsch. deploy_hub.sh --check prüft jetzt Schlüsselparität und fehlende t()-Schlüssel. Doku: docs/website.md neu, docs/hub.md und AGENTS.md ergänzt.
353 lines
15 KiB
Markdown
353 lines
15 KiB
Markdown
# 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
|
||
|
||
```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.
|