rinkplanner/docs/hub.md
torsten 9819311403 feat: Website und Hub zweisprachig (Deutsch/Englisch)
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.
2026-11-12 22:38:32 +01:00

353 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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