Unraid-Navigator/TODO.md

U-Navigator – TODO

Stand: 2026-07-14

Ziel dieser Liste ist eine sichere, testbare und veröffentlichungsfähige Version des Plugins. Schreibzugriff sollte erst empfohlen werden, wenn alle Punkte unter P0 abgeschlossen und auf einer echten Unraid-Installation geprüft sind.

P0 – Sicherheitsblocker

Geschützte Root-Pfade

• Eine zentrale Funktion unav_assert_mutable_path() einführen.
• Löschen eines konfigurierten Root-Pfads verbieten.
• Verschieben und Umbenennen eines konfigurierten Root-Pfads verbieten.
• Rekursive Rechte- oder Besitzeränderungen direkt am Root-Pfad verbieten.
• Quelle und Ziel auch im Worker unmittelbar vor der Operation erneut prüfen.
• API-Tests für Delete, Move und Permissions auf /mnt/user beziehungsweise einem Test-Root ergänzen.

Abnahmekriterium: Kein mutierender API-Aufruf kann den erlaubten Root selbst verändern oder entfernen.

Sichere Symlink-Behandlung

• Eingabepfad und kanonischen Sicherheitspfad getrennt speichern.
• Für Dateioperationen lstat() statt ausschließlich realpath() verwenden.
• Beim Löschen eines Symlinks ausschließlich den Link entfernen, niemals dessen Ziel.
• Copy und Move von Symlinks entweder kontrolliert implementieren oder ausdrücklich ablehnen.
• Symlinks auf Ziele außerhalb erlaubter Roots für Listing, Vorschau und Download weiterhin blockieren.
• Rekursive Operationen dürfen Symlinks nicht verfolgen.
• Tests für interne Symlinks, externe Symlinks, kaputte Symlinks und Symlink-Schleifen ergänzen.

Abnahmekriterium: Eine Aktion auf einem Symlink wirkt niemals unerwartet auf dessen Ziel.

Upload-Pfade härten

• Relative Pfade vollständig validieren; .. nicht still entfernen, sondern als Fehler ablehnen.
• Absolute Pfade, Nullbytes und leere Pfadsegmente ablehnen.
• Jeden Parent-Pfad prüfen, bevor ein Verzeichnis angelegt wird.
• Beim Anlegen von Upload-Ordnern keine vorhandenen Symlinks durchlaufen.
• Zielpfad unmittelbar vor Schreiben beziehungsweise Rename erneut validieren.
• Temporäre Upload-Dateien in einem privaten Verzeichnis ablegen und zufällige IDs verwenden.
• Abgebrochene und veraltete Upload-Fragmente automatisch entfernen.
• Tests für Symlink-Parents und konkurrierende Pfadänderungen ergänzen.

Abnahmekriterium: Ein Upload kann außerhalb der erlaubten Roots weder Dateien noch Verzeichnisse erzeugen.

CSRF und Request-Schutz

• Auf einer aktuellen Unraid-7.x-Installation prüfen, ob die WebGUI-Schicht Plugin-PHP-Endpunkte automatisch gegen CSRF schützt.
• Direkte POST-Requests ohne, mit falschem und mit gültigem csrf_token testen.
• Falls nötig, CSRF-Prüfung zentral in common.php implementieren.
• Mutierende Endpunkte ausschließlich per POST erlauben.
• Für nicht erlaubte Methoden 405 Method Not Allowed und einen Allow-Header liefern.
• Für JSON- und Formular-Requests dieselben Schutzregeln anwenden.
• Authentifizierungsverhalten bei direktem Aufruf aller API-Endpunkte prüfen und dokumentieren.

Abnahmekriterium: Kein mutierender Aufruf funktioniert ohne gültige Unraid-Sitzung und gültigen CSRF-Schutz.

Ressourcenlimits

• Maximale Upload-Dateigröße konfigurierbar machen.
• Maximale Gesamtgröße und Dateianzahl pro Upload begrenzen.
• Raw-Uploads streamen, statt den gesamten Request in den PHP-Speicher zu laden.
• Maximale Dateianzahl und Gesamtgröße für ZIP-Downloads festlegen.
• Vor ZIP-Erstellung freien temporären Speicher prüfen.
• ZIP-Erstellung als Hintergrundjob ausführen.
• Laufzeit- und Rekursionstiefenlimits für Size, Copy, Delete und Permissions einführen.
• Große Verzeichnisse im Listing paginieren oder begrenzen.

Abnahmekriterium: Einzelne Requests können weder PHP-Speicher noch temporären Speicher unkontrolliert erschöpfen.

P1 – Datenintegrität und Jobs

Robuste Copy-/Move-Operationen

• Kopien zunächst unter einem temporären Zielnamen erstellen.
• Ziel erst nach erfolgreicher vollständiger Kopie atomar sichtbar machen.
• Unvollständige Ziele bei Fehlern zuverlässig entfernen.
• Quelle bei einem Cross-Filesystem-Move erst nach verifizierter Kopie löschen.
• Dateigröße und optional Prüfsumme vor dem Löschen der Quelle vergleichen.
• Rechte, Owner, Gruppe und Zeitstempel erhalten.
• Verhalten für Sparse Files, Hardlinks und Special Files definieren.
• Zielkonflikte auch unmittelbar vor dem finalen Rename prüfen.
• Tests für Fehler mitten in einer Verzeichniskopie ergänzen.

Job-System

• Job-Verzeichnis mit 0700 statt 0777 erstellen.
• Jobdateien atomar über temporäre Datei plus Rename schreiben.
• Beim Lesen passende Locks beziehungsweise atomare Snapshots verwenden.
• Kryptografisch zufällige Job-IDs verwenden.
• Prüfen, ob der Worker wirklich gestartet ist; nicht nur den Shell-Exitcode auswerten.
• Hängende Jobs nach Timeout als fehlgeschlagen markieren.
• Abbruch-Endpunkt für laufende Jobs implementieren.
• Abbruchstatus in rekursiven Operationen regelmäßig prüfen.
• Abbruchschaltfläche im Transfer-Panel ergänzen.
• Alte abgeschlossene Jobs automatisch löschen.
• Gleichzeitige, kollidierende Jobs auf denselben Pfaden erkennen und serialisieren oder ablehnen.
• Jobfehler mit verständlicher Meldung und technischem Logeintrag trennen.

Löschschutz

• Optionalen Papierkorb pro Root implementieren.
• Direktes permanentes Löschen als gesonderte Aktion behandeln.
• Anzahl und geschätzte Größe vor rekursivem Löschen anzeigen.
• Mehrfachauswahl vor dem Start vollständig validieren.
• Optional eine zweite Bestätigung für sehr große Löschvorgänge verlangen.

P1 – Tests

PHP-Backend testen

• Eigenständige Tests für die tatsächlich ausgelieferten PHP-Endpunkte aufbauen.
• Die Tests in einer Unraid-kompatiblen PHP-Version ausführen.
• Listing innerhalb und außerhalb erlaubter Roots testen.
• Upload, Download, Preview, Copy, Move, Delete, Size und Permissions testen.
• Read-only-Modus für jede mutierende Aktion testen.
• Zielkonflikte und ungültige Request-Methoden testen.
• Sonderzeichen, Unicode, sehr lange Namen und versteckte Dateien testen.
• Mehrere konfigurierte Roots testen.
• Regressionstests für alle P0-Sicherheitsfälle ergänzen.

CI und statische Prüfung

• php -l für alle PHP-Dateien in CI ausführen.
• JavaScript-Syntaxprüfung ausführen.
• ShellCheck für build-plugin.sh aktivieren.
• XML beziehungsweise PLG-Manifest validieren.
• Paket bauen und mit den Quellen vergleichen.
• Manifest-Prüfsumme automatisch verifizieren.
• Tests bei jedem Push und Pull Request ausführen.

Test auf echter Unraid-Instanz

• Installation auf unterstützten Unraid-Versionen testen.
• Upgrade von einer vorherigen Plugin-Version testen.
• Deinstallation und Neuinstallation testen.
• Verhalten bei gestopptem und gestartetem Array prüfen.
• User Shares, Pools und Disk Shares getrennt prüfen.
• Große Ordner und große Dateien testen.
• WebGUI-Neustart und Server-Neustart während laufender Jobs testen.
• Alle offiziellen Themes und mobile Darstellung prüfen.

P2 – Konfiguration und Bedienung

Root-Konfiguration

• Erlaubte Roots in settings.json speichern.
• Einstellungsoberfläche zum Hinzufügen und Entfernen von Roots bauen.
• Nur existierende absolute Verzeichnisse akzeptieren.
• Gefährliche Systempfade wie /, /boot, /etc, /usr, /var und /root standardmäßig verbieten.
• Pro Root einen Anzeigenamen und Read-only-Status erlauben.
• Änderungen an Roots erst nach erneuter serverseitiger Validierung übernehmen.
• Root-Auswahl im Explorer anbieten.

Dateimanager-Funktionen

• Neuen Ordner anlegen.
• Leere Datei anlegen.
• Umbenennen mit serverseitiger Namensvalidierung verbessern.
• Suche nach Dateiname im aktuellen Ordner implementieren.
• Optionale rekursive Suche mit Ergebnislimit ergänzen.
• Sortierung nach Name, Typ, Größe und Änderungsdatum anbieten.
• Versteckte Dateien ein- und ausblendbar machen.
• Breadcrumb-Navigation ergänzen.
• Dateibaum beziehungsweise Share-Navigation ergänzen.
• Tastaturbedienung für Auswahl, Öffnen, Kopieren, Verschieben und Löschen verbessern.

Transfer-Oberfläche

• Reale Fortschrittswerte nach Bytes statt nur nach Top-Level-Einträgen berechnen.
• Quelle, Ziel, Geschwindigkeit und Restzeit anzeigen.
• Fehlgeschlagene Jobs wiederholbar machen.
• Abgeschlossene Einträge einzeln oder gesammelt entfernen.
• Uploads pausieren und abbrechen können.

Vorschau und Download

• MIME-Typ anhand des Dateiinhalts prüfen, nicht nur anhand der Erweiterung.
• SVG-Vorschau sicher behandeln oder deaktivieren.
• Medien- und PDF-Vorschau mit geeigneten Sandbox-Headern testen.
• HTTP-Range-Requests für große Audio- und Videodateien unterstützen.
• RFC-konforme UTF-8-Dateinamen im Content-Disposition-Header verwenden.
• Einzeldateien streamen, ohne unnötige Pufferung.

P2 – Protokollierung und Betrieb

• Audit-Log für Upload, Copy, Move, Delete und Permissions einführen.
• Zeitpunkt, Aktion, Quelle, Ziel, Ergebnis und Fehler protokollieren.
• Keine CSRF-Tokens oder sensiblen Inhalte ins Debug-Log schreiben.
• Logrotation und maximale Loggröße definieren.
• Diagnoseexport für Supportfälle anbieten.
• Gesundheitsstatus für Job-Worker und temporären Speicher anzeigen.

P3 – Paketierung und Veröffentlichung

• Version nur an einer Stelle pflegen und beim Build überall einsetzen.
• package.json-Version mit der Plugin-Version synchronisieren.
• Reproduzierbare TGZ-Pakete mit stabiler Sortierung und Zeitstempeln erzeugen.
• Nach Möglichkeit SHA-256 zusätzlich zur MD5-Prüfung veröffentlichen.
• Minimale und getestete Unraid-Version im Plugin-Manifest angeben.
• Changelog pro Version vollständig pflegen.
• Release-Build in einer sauberen Working Copy erzeugen.
• Community-Applications-Metadaten validieren.
• Installations-, Update- und Rollback-Anleitung ergänzen.
• Sicherheitsmodell und bekannte Einschränkungen dokumentieren.
• Read-only als empfohlenen Standard deutlich in README und Oberfläche anzeigen.

Definition of Done für die erste produktive Version

• Alle P0-Punkte sind abgeschlossen.
• PHP-Integrationstests decken alle mutierenden Operationen ab.
• Keine Root- oder Symlink-Regression ist offen.
• CSRF und Authentifizierung sind auf echter Unraid-Hardware bestätigt.
• Große Uploads, Downloads und Verzeichnisse besitzen getestete Limits.
• Fehlgeschlagene Copy-/Move-Jobs hinterlassen keine unbemerkten Teildaten.
• Installation, Upgrade, Neustart und Deinstallation wurden getestet.
• Paketinhalt und Manifest-Prüfsumme stimmen überein.
• Dokumentation und Changelog entsprechen dem ausgelieferten Funktionsumfang.