feat: Kür-Hub mit Einladungen, Uploads und API
- PHP-App unter hub/ für rinkplanner-hub.programmschmiede.de - MariaDB-Schema, Argon2id, Sessions, CSRF und Ratenbegrenzung - Einladungscodes, Admin-Bereich und Kür-Pakete mit Audiodatei - JSON-API v1 mit Bearer-Tokens für die Godot-App - Deployment und Erstinstallation über tools/deploy_hub.sh - Doku und Credentials-Vorlage ergänzt
This commit is contained in:
parent
e79b477ee0
commit
055a2919c3
38 changed files with 5111 additions and 0 deletions
|
|
@ -35,3 +35,18 @@ GOOGLE_CLIENT_ID=
|
|||
GOOGLE_CLIENT_SECRET=
|
||||
DROPBOX_APP_KEY=
|
||||
DROPBOX_APP_SECRET=
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Kür-Hub (rinkplanner-hub.programmschmiede.de)
|
||||
# ---------------------------------------------------------------------------
|
||||
# MariaDB-Datenbank des Hubs. Der DB-Benutzer braucht alle Rechte auf DB_NAME
|
||||
# (CREATE, ALTER, INDEX, SELECT, INSERT, UPDATE, DELETE).
|
||||
DB_NAME=
|
||||
DB_USER=
|
||||
DB_PASSWORD=
|
||||
|
||||
# Erster Benutzer der Installation; wird von tools/deploy_hub.sh --install
|
||||
# einmalig als Administrator angelegt. Das Passwort wird nie gespeichert,
|
||||
# sondern nur per HTTPS an den Installer übergeben.
|
||||
HUB_ADMIN_USER=
|
||||
HUB_ADMIN_PASSWORD=
|
||||
|
|
|
|||
293
docs/hub.md
Normal file
293
docs/hub.md
Normal file
|
|
@ -0,0 +1,293 @@
|
|||
# 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
|
||||
├── 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Offene Punkte
|
||||
|
||||
- Godot-Client an die API anbinden (Token im Client speichern, Upload/Download
|
||||
als Paket).
|
||||
- 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue