Merge pull request #7 from friloo/claude/ecstatic-cannon-H5hGy

Claude/ecstatic cannon h5h gy

Readme.md

@@ -1,25 +1,77 @@
-# UniFi Voucher Management System
+<div align="center">
 
-Webbasiertes System zur Verwaltung von WLAN-Vouchers für UniFi OS mit Multi-Site-Unterstützung, Benutzerverwaltung und Microsoft 365 Integration.
+# 🎫 UniFi Voucher Management System
 
-## Features
+**Webbasiertes WLAN-Voucher-Management für UniFi OS** – mit Multi-Site-Support, Benutzerverwaltung, Microsoft-365-Login und integriertem Auto-Updater.
 
-- **Voucher-Erstellung** mit QR-Code-Anzeige und E-Mail-Versand
-- **Multi-Site-Support** – mehrere UniFi-Standorte verwalten
-- **Benutzerverwaltung** mit granularer Site-Zugriffskontrolle
-- **Authentifizierung** via lokale Accounts oder Microsoft 365 OAuth
-- **CSV-Export** aller Vouchers pro Site
-- **Admin-Dashboard** mit Live-Statistiken und Sync-Funktion
-- **Öffentlicher Zugriff** – optional ohne Login nutzbar
-- CSRF-Schutz, bcrypt-Passwörter, Prepared Statements, Login-Rate-Limiting
+![PHP](https://img.shields.io/badge/PHP-7.4%2B-777BB4?logo=php&logoColor=white)
+![MySQL](https://img.shields.io/badge/MySQL-5.7%2B%20%2F%20MariaDB-4479A1?logo=mysql&logoColor=white)
+![UniFi OS](https://img.shields.io/badge/UniFi%20OS-7.0%2B-0559C9?logo=ubiquiti&logoColor=white)
+![License](https://img.shields.io/badge/Lizenz-MIT-green)
+![Version](https://img.shields.io/badge/Version-2.1.0-blueviolet)
 
-## Anforderungen
+</div>
 
-- PHP 7.4+, MySQL 5.7+ / MariaDB 10.2+, Apache/Nginx
-- PHP-Extensions: PDO, PDO_MySQL, cURL, mbstring, JSON
-- **UniFi Network Application 7.0+ mit UniFi OS** (z.B. UDM, UDR, UniFi OS Server)
+---
 
-## Installation
+<div align="center">
+  <img src="docs/screenshots/voucher-result.png" alt="Erstellter Voucher mit QR-Code" width="48%">
+  <img src="docs/screenshots/admin-dashboard.png" alt="Admin Dashboard" width="48%">
+</div>
+
+---
+
+## ✨ Features
+
+- 🎟️ **Voucher-Erstellung** mit sofortiger QR-Code-Anzeige, Druckvorlage und E-Mail-Versand
+- 🏢 **Multi-Site-Support** – beliebig viele UniFi-Standorte zentral verwalten
+- 👥 **Benutzerverwaltung** mit granularer Site-Zugriffskontrolle
+- 🔐 **Authentifizierung** via lokale Accounts **oder** Microsoft 365 OAuth
+- 🌍 **Öffentlicher Modus** – optional ohne Login nutzbar (mit CSRF-Schutz & Throttle)
+- 📊 **Admin-Dashboard** mit Live-Statistiken und Sync-Funktion
+- 📥 **CSV-Export** aller Vouchers pro Site
+- 🔄 **Integrierter Auto-Updater** – Updates per Klick aus dem Admin-Bereich
+- 🛡️ **Security-by-default**: CSRF-Schutz, bcrypt-Passwörter, Prepared Statements,
+  Login-Rate-Limiting, OAuth-State-Validierung, Verschlüsselung sensibler Daten
+
+---
+
+## 📸 Screenshots
+
+### Anmeldung & Voucher-Erstellung
+
+<div align="center">
+  <img src="docs/screenshots/login.png" alt="Login mit Microsoft 365" width="32%">
+  <img src="docs/screenshots/voucher-form.png" alt="Voucher erstellen" width="32%">
+  <img src="docs/screenshots/voucher-result.png" alt="Voucher-Ergebnis" width="32%">
+</div>
+
+### Administration & Updater
+
+<div align="center">
+  <img src="docs/screenshots/admin-dashboard.png" alt="Dashboard" width="48%">
+  <img src="docs/screenshots/updater-available.png" alt="Auto-Updater" width="48%">
+</div>
+
+<div align="center">
+  <img src="docs/screenshots/updater.png" alt="Updater – Ausgangszustand" width="48%">
+  <img src="docs/screenshots/maintenance.png" alt="Wartungsmodus" width="48%">
+</div>
+
+---
+
+## 📋 Anforderungen
+
+| Komponente | Version |
+|---|---|
+| PHP | 7.4+ (mit PDO, PDO_MySQL, cURL, mbstring, JSON; empfohlen: OpenSSL/libsodium, Zip) |
+| Datenbank | MySQL 5.7+ / MariaDB 10.2+ |
+| Webserver | Apache / Nginx |
+| UniFi | **Network Application 7.0+ mit UniFi OS** (z. B. UDM, UDR, UniFi OS Server) |
+
+---
+
+## 🚀 Installation
 
 ```bash
 git clone https://github.com/friloo/unifi-voucher-tool.git
@@ -27,136 +79,210 @@ cd unifi-voucher-tool
 ```
 
 1. Dateien auf den Webserver hochladen
-2. `http://ihre-domain.de/install.php` öffnen
-3. Den 5-Schritte-Assistenten durchlaufen:
-   - **Schritt 1:** Datenbank-Verbindungsdaten
-   - **Schritt 2:** Administrator-Account (Name, E-Mail, Passwort)
-   - **Schritt 3:** Allgemeine Einstellungen (Titel, Logo, öffentlicher Zugriff)
-   - **Schritt 4:** Microsoft 365 Integration (optional)
-   - **Schritt 5:** Installation abschließen
-4. `install.php` nach erfolgreicher Installation löschen
+2. `https://ihre-domain.de/install.php` öffnen
+3. Den **5-Schritte-Assistenten** durchlaufen:
+   1. Datenbank-Verbindungsdaten
+   2. Administrator-Account
+   3. Allgemeine Einstellungen (Titel, Logo, öffentlicher Zugriff)
+   4. Microsoft 365 Integration (optional)
+   5. Installation abschließen
+4. `install.php` nach erfolgreicher Installation **löschen**
 
-## Sites konfigurieren
+> 🔒 Der Installer erzeugt automatisch einen zufälligen `APP_KEY` (für die
+> Verschlüsselung der UniFi-Passwörter) und eine `.htaccess`, die sensible
+> Dateien sperrt. Ein erneuter Aufruf von `install.php?reinstall=1` ist nur
+> für **angemeldete Administratoren** möglich.
+
+### Sites konfigurieren
 
 1. **Administration → Sites verwalten → Neue Site hinzufügen**
 2. Felder ausfüllen:
-   - **Name:** Anzeigename (z.B. „Hauptgebäude")
+   - **Name:** Anzeigename (z. B. „Hauptgebäude")
    - **Site ID:** UniFi Site ID (meist `default`)
    - **Controller URL:** `https://unifi.example.com:11443`
    - **Benutzername / Passwort:** UniFi Admin-Zugangsdaten
 3. **Verbindung testen** klicken, dann speichern
 
-## Voucher erstellen
+### Voucher erstellen
 
 1. Startseite öffnen (Login je nach Konfiguration optional)
 2. Voucher-Name, Anzahl Geräte und Standort wählen
 3. **Voucher erstellen** – Code und QR-Code werden sofort angezeigt
 4. Code per E-Mail senden oder ausdrucken
 
-## Konfiguration
+---
+
+## 🔄 Auto-Updater
+
+Das System bringt einen vollständig integrierten Updater mit, der Quellcode und
+Datenbank-Migrationen über einen zentralen Update-Proxy nachzieht – ganz ohne
+SSH oder manuelles `git pull`.
+
+```
+[diese Instanz]  ←HTTPS→  [Update-Proxy]  ←pull→  [Git-Repo]
+```
+
+**Aufruf:** Administration → **System-Update** (`/admin/update.php`)
+
+- 🔍 **„Auf Updates prüfen"** zeigt verfügbare Versionen inkl. Changelog
+- ⬇️ **„Update installieren"** spielt das Update ein – mit Wartungsseite,
+  geschützten Pfaden (`config.php`, Uploads, …), automatischen DB-Migrationen
+  und OPcache-Reset
+- 🔀 **Channel-Auswahl** zwischen `stable` und `development`
+- 📊 **Migrations-Status** in einem eigenen Tab
+
+Während eines Updates wird die Anwendung kurz in den **Wartungsmodus** versetzt:
+
+<div align="center">
+  <img src="docs/screenshots/maintenance.png" alt="Wartungsmodus" width="60%">
+</div>
+
+> Der Updater ist vollständig isoliert im Ordner [`updater/`](updater/) gekapselt.
+> Details zur Architektur und eine Rückbau-Anleitung stehen in
+> [`updater/README.md`](updater/README.md).
+
+---
+
+## ⚙️ Konfiguration
+
+### `config.php`
 
-### config.php
 Wird automatisch durch den Installer erstellt:
+
 ```php
 <?php
 define('DB_HOST', 'localhost');
 define('DB_NAME', 'unifi_voucher');
 define('DB_USER', 'username');
 define('DB_PASS', 'password');
-define('SESSION_LIFETIME', 3600);
+define('APP_KEY', '...');            // Schlüssel für Verschlüsselung-at-rest
+define('SESSION_LIFETIME', 3600);    // Session-Timeout in Sekunden
 date_default_timezone_set('Europe/Berlin');
 ```
 
 ### Microsoft 365 OAuth (optional)
+
 1. Im [Azure Portal](https://portal.azure.com) eine App-Registrierung anlegen
 2. Umleitungs-URI: `https://ihre-domain.de/m365_callback.php`
-3. API-Berechtigungen: `User.Read`, `email`, `profile`, `openid`
+3. API-Berechtigungen: `openid`, `profile`, `email`, `User.Read`
 4. Client ID, Client Secret und Tenant ID in **Administration → Einstellungen** eintragen
 
 ### Cron-Job (empfohlen)
+
 Automatische Synchronisation alle 30 Minuten:
+
 ```bash
 */30 * * * * curl -s "https://ihre-domain.de/cron_sync.php?token=IHR_CRON_TOKEN"
 ```
+
 Den Token finden Sie unter **Administration → Einstellungen → Cron**.
 
-## Sicherheit
+---
+
+## 🛡️ Sicherheit
+
+Das Tool ist auf einen sicheren Standardbetrieb ausgelegt:
+
+| Schutz | Umsetzung |
+|---|---|
+| **Passwörter** | bcrypt (`password_hash`) für Accounts |
+| **UniFi-Passwörter** | Verschlüsselt-at-rest (AES-256-GCM / libsodium) über `APP_KEY` |
+| **SQL-Injection** | Durchgängig Prepared Statements (PDO) |
+| **CSRF** | Token für alle schreibenden Aktionen – auch im öffentlichen Modus |
+| **OAuth** | `state`-Validierung gegen Login-CSRF |
+| **Brute-Force** | Login-Rate-Limiting + Throttle der öffentlichen Voucher-Erstellung |
+| **Sessions** | HttpOnly, SameSite, strict mode + absolutes Timeout |
+| **Fehler** | `display_errors` aus, `log_errors` an (kein Info-Leak) |
+
+Empfohlene zusätzliche Härtung am Server:
 
 ```apache
-# .htaccess – sensible Dateien sperren
-<FilesMatch "^(config\.php|database\.sql|.*\.md)$">
-    Order Allow,Deny
-    Deny from all
+# .htaccess – sensible Dateien sperren (wird vom Installer erzeugt)
+<FilesMatch "^(config\.php|database\.sql|install\.php|test\.php|m365_debug\.php|.*\.md)$">
+    Require all denied
 </FilesMatch>
 ```
 
 ```sql
--- Dedizierter Datenbank-Benutzer
+-- Dedizierter Datenbank-Benutzer mit minimalen Rechten
 CREATE USER 'unifi_voucher'@'localhost' IDENTIFIED BY 'sicheres_passwort';
 GRANT SELECT, INSERT, UPDATE, DELETE ON unifi_voucher.* TO 'unifi_voucher'@'localhost';
 ```
 
-## Problembehandlung
+---
+
+## 🩺 Problembehandlung
+
+<details>
+<summary><b>Login funktioniert nicht</b></summary>
 
-**Login funktioniert nicht:**
 - Datenbankverbindung und PHP-Session-Konfiguration prüfen
+- Fehler werden ins PHP-Error-Log geschrieben (nicht mehr in den Browser)
+</details>
+
+<details>
+<summary><b>UniFi-Verbindung schlägt fehl</b></summary>
 
-**UniFi-Verbindung schlägt fehl:**
 - Controller-URL im Browser testen
-- Port 11443 für UniFi OS verwenden (nicht 8443)
+- Port **11443** für UniFi OS verwenden (nicht 8443)
 - Benutzername, Passwort und Site ID prüfen
 - cURL-Extension muss aktiviert sein
+</details>
+
+<details>
+<summary><b>UniFi OS: HTTP 404 oder 401</b></summary>
 
-**UniFi OS: HTTP 404 oder 401:**
 - Login-Endpunkt ist `/api/auth/login` (nicht `/api/login`)
 - API-Pfade benötigen Präfix `/proxy/network/api/s/{site}/...`
 - Älterer UniFi Network Controller (ohne UniFi OS) wird ab Version 2.1.0 nicht mehr unterstützt
+</details>
 
-**Voucher werden nicht erstellt:**
-- UniFi Controller Logs prüfen
-- API-Berechtigungen des Admin-Accounts prüfen
-- Site ID korrekt? (zu finden in der UniFi Controller URL)
+<details>
+<summary><b>Microsoft 365 Login funktioniert nicht</b></summary>
 
-**Microsoft 365 Login funktioniert nicht:**
 - Redirect URI in Azure AD prüfen
 - Client ID, Secret und Tenant ID kontrollieren
+- Diagnose unter `m365_debug.php` (nur als Admin erreichbar)
+</details>
 
-## API-Dokumentation
+---
 
-**Login (UniFi OS):**
-```
+## 📡 API-Dokumentation (UniFi OS)
+
+```http
+# Login
 POST /api/auth/login
 Body: {"username": "admin", "password": "password"}
 Response-Header: X-CSRF-Token: <token>
-```
 
-**Voucher erstellen:**
-```
+# Voucher erstellen
 POST /proxy/network/api/s/{site_id}/cmd/hotspot
 X-CSRF-Token: <token>
 Body: {"cmd": "create-voucher", "expire": 480, "n": 1, "note": "Name", "quota": 1}
-```
 
-**Vouchers abrufen:**
-```
+# Vouchers abrufen
 GET /proxy/network/api/s/{site_id}/stat/voucher
-```
 
-**Voucher löschen:**
-```
+# Voucher löschen
 POST /proxy/network/api/s/{site_id}/cmd/hotspot
-X-CSRF-Token: <token>
 Body: {"cmd": "delete-voucher", "_id": "<voucher_id>"}
 ```
 
-## Roadmap
+---
+
+## 🗺️ Roadmap
 
 - [ ] Voucher-Templates (vordefinierte Laufzeiten)
 - [ ] Bulk-Voucher-Erstellung
 - [ ] Erweiterte Reporting-Funktionen
 - [ ] Docker-Container
 - [ ] Mehrsprachigkeit
+- [x] Auto-Updater mit DB-Migrationen
 
 ---
 
-**Version:** 2.1.0 | **Autor:** Friederich Loheide | **Letztes Update:** April 2026
+<div align="center">
+
+**Version 2.1.0** · Autor: **Friederich Loheide** · Lizenz: **MIT**
+
+</div>

admin/index.php

@@ -661,6 +661,7 @@ $currentUser = $auth->getCurrentUser();
                 <li><a href="users.php"><i class="fas fa-users"></i> Benutzer verwalten</a></li>
                 <li><a href="vouchers.php"><i class="fas fa-ticket-alt"></i> Live Vouchers</a></li>
                 <li><a href="settings.php"><i class="fas fa-cog"></i> Einstellungen</a></li>
+                <li><a href="update.php"><i class="fas fa-sync-alt"></i> System-Update</a></li>
             </ul>
         </nav>
     </div>

admin/settings.php

@@ -290,6 +290,7 @@ $faviconUrl = $db->getSetting('favicon_url', '');
                 <li><a href="users.php"><i class="fas fa-users"></i> Benutzer verwalten</a></li>
                 <li><a href="vouchers.php"><i class="fas fa-ticket-alt"></i> Voucher-Historie</a></li>
                 <li><a href="settings.php" class="active"><i class="fas fa-cog"></i> Einstellungen</a></li>
+                <li><a href="update.php"><i class="fas fa-sync-alt"></i> System-Update</a></li>
             </ul>
         </nav>
     </div>

admin/sites.php

@@ -419,6 +419,7 @@ $currentUser = $auth->getCurrentUser();
                 <li><a href="users.php"><i class="fas fa-users"></i> Benutzer verwalten</a></li>
                 <li><a href="vouchers.php"><i class="fas fa-ticket-alt"></i> Voucher-Historie</a></li>
                 <li><a href="settings.php"><i class="fas fa-cog"></i> Einstellungen</a></li>
+                <li><a href="update.php"><i class="fas fa-sync-alt"></i> System-Update</a></li>
             </ul>
         </nav>
     </div>

admin/users.php

@@ -480,6 +480,7 @@ $currentUser = $auth->getCurrentUser();
                 <li><a href="users.php" class="active"><i class="fas fa-users"></i> Benutzer verwalten</a></li>
                 <li><a href="vouchers.php"><i class="fas fa-ticket-alt"></i> Voucher-Historie</a></li>
                 <li><a href="settings.php"><i class="fas fa-cog"></i> Einstellungen</a></li>
+                <li><a href="update.php"><i class="fas fa-sync-alt"></i> System-Update</a></li>
             </ul>
         </nav>
     </div>

admin/vouchers.php

@@ -633,6 +633,7 @@ $faviconUrl = $db->getSetting('favicon_url', '');
                 <li><a href="users.php"><i class="fas fa-users"></i> Benutzer verwalten</a></li>
                 <li><a href="vouchers.php" class="active"><i class="fas fa-ticket-alt"></i> Live Vouchers</a></li>
                 <li><a href="settings.php"><i class="fas fa-cog"></i> Einstellungen</a></li>
+                <li><a href="update.php"><i class="fas fa-sync-alt"></i> System-Update</a></li>
             </ul>
         </nav>
     </div>