Architektur und Sicherheit

Komponenten

Listener

Der Listener öffnet den JSON-Stream des ntfy-Topics per Basic Auth, liest message-Events und extrahiert die erste HTTP(S)-URL. Vor dem eigentlichen Download wird der Auftrag in SQLite gespeichert.

Die Queue sorgt für:

• Deduplizierung anhand der ntfy-Nachrichten-ID
• Wiederaufnahme nach Prozess- oder Hostneustart
• Speicherung des letzten ntfy-Zeitpunkts für Stream-Fortsetzung
• klaren Status für wartende, laufende, erfolgreiche und fehlgeschlagene Jobs

Fehlgeschlagene Downloads werden gemeldet und nicht automatisch endlos wiederholt. Nach einem Fehler lauscht der Dienst weiter. Authentifizierungsfehler am ntfy-Server beenden den Listener, weil Wiederholungen ohne neue Zugangsdaten nicht erfolgreich wären.

Downloader

Der Download erfolgt mit yt-dlp. ffmpeg steht für Merging und Medienverarbeitung im Image bereit. Bestimmte Seiten können vorab auf ihre eingebettete Video-URL aufgelöst werden.

Web-UI

Die FastAPI-Web-UI liest das Downloadverzeichnis, erzeugt Thumbnails und verwaltet Tags in einer separaten SQLite-Datenbank. Verändernde Formulare sind per Basic Auth und CSRF-Token geschützt. Pfade werden normalisiert und gegen das reale Download-Root geprüft.

Container-Härtung

Beide Dienste laufen:

• ohne Root-Rechte
• mit read-only Root-Dateisystem
• ohne Linux-Capabilities
• mit no-new-privileges
• mit Prozess-, CPU- und Speicherlimits
• mit separatem beschreibbarem /tmp als tmpfs

Schreibbar sind nur die benötigten Mounts. Die Web-UI benötigt absichtlich Schreibzugriff auf das Downloadverzeichnis.

Vertrauensgrenzen

ntfy-Topic

Jeder Schreibberechtigte kann den Downloader zu ausgehenden HTTP(S)-Zugriffen veranlassen. Das Topic ist deshalb eine Ausführungsschnittstelle und darf nur vertrauenswürdigen Benutzern offenstehen. In nicht vollständig vertrauten Umgebungen sind ausgehende Firewall-Regeln oder Netzwerkisolation sinnvoll.

Basic Auth

Basic Auth verschlüsselt keine Verbindung. ntfy und Web-UI dürfen außerhalb eines vertrauenswürdigen Netzes nur über HTTPS betrieben werden. Passwörter sollten lang, zufällig und für jeden Dienst unterschiedlich sein.

Signierte WhatsApp-Links

Signierte Links umgehen Basic Auth für genau eine Datei und einen begrenzten Zeitraum. Sie sind für Messenger-Vorschauen notwendig, aber bis zum Ablauf wie ein Bearer-Token zu behandeln. Eine Weitergabe erlaubt den Dateizugriff.

Reverse Proxy

Der Proxy sollte mindestens:

• TLS terminieren
• große beziehungsweise langsame Downloads streamen können
• Query-Strings nicht in öffentlich einsehbare Analyse- oder Fehlerlogs geben
• keine kurzen Request-Timeouts für Videostreams erzwingen
• WEBUI_PUBLIC_URL exakt auf die von Clients erreichbare HTTPS-URL abbilden

GIF- und MP4-Codierung selbst läuft im Hintergrund; der Proxy muss nicht für die gesamte ffmpeg-Laufzeit eine einzelne Anfrage offenhalten.

Secrets

• .env nicht committen.
• Dateirechte auf dem Host auf den Betriebsbenutzer begrenzen.
• Keine signierten URLs, Passwörter oder ntfy-Topics in Tickets oder Wikis veröffentlichen.
• Nach einem vermuteten Leak Passwörter rotieren. Ein Wechsel von WEBUI_PASSWORD widerruft zugleich alle noch gültigen Share-Links.