README

Guardian für TYPO3

Admin-Cockpit für Composer-Updates, Backups, Wiederherstellung und Erweiterungsverwaltung in TYPO3 13.4 und 14 – von V&T Innovations.

Guardian ist eine native TYPO3-Backend-Erweiterung, die eine TYPO3-Installation aktualisierbar und wiederherstellbar hält. Aus einem einzigen, ausschließlich für Administratoren zugänglichen Modul steuert sie Composer-Updates, vollständige und geplante Backups, die Wiederherstellung im Backend und über ein eigenständiges Panel sowie die vollständige Erweiterungsverwaltung – jeweils über dieselbe Sicherheits-Pipeline (verpflichtendes Backup vor jeder Änderung → Wartungsmodus → Änderung → Verifizierung → automatisches Rollback bei Fehler).

Produktionsstatus. Guardian ist eine voll funktionsfähige Erweiterung. Jeder nachfolgend beschriebene Bereich ist durchgängig implementiert – von der Backend-Oberfläche bis zur serverseitigen Ausführung. Destruktive Operationen laufen in abgekoppelten PHP-Worker-Prozessen, sind durch eine ausdrückliche Bestätigung abgesichert, werden von einem verpflichtenden Sicherheits-Backup vorbereitet und rollen bei einem Fehler automatisch zurück. Guardian entstand ursprünglich als Portierung des Contao-Guardian-Bundles; heute ist es eine eigenständige native TYPO3-Erweiterung und wird hier so beschrieben, wie es aktuell funktioniert.

Voraussetzungen

TYPO3 13.4.9 bis 14.x (typo3/cms-core: ^13.4.9 || ^14.0). Ein einziges Paket unterstützt beide; 13.4.9 ist das Minimum.
PHP 8.2+ (~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0). Die effektive Untergrenze ist das, was der installierte TYPO3-Core erzwingt.
Composer-basierte Installation. Die Update- und Erweiterungsfunktionen arbeiten auf composer.json/composer.lock und setzen den Composer-Modus voraus.
ext-json (erforderlich). ext-zip wird zum Erstellen/Lesen von Backup-Archiven genutzt; ext-pdo dient als reiner PHP-Fallback für den Datenbank-Dump, wenn mysqldump nicht verfügbar ist.
Ein beschreibbares var/-Verzeichnis – Guardian speichert seinen gesamten Laufzeitzustand unter var/guardian/.

PHP-CLI- und Composer-Konfiguration

Update- und Wiederherstellungsjobs laufen in einem abgekoppelten PHP-CLI-Worker, nicht im Web-Request. Guardian benötigt daher zur Laufzeit:

eine erreichbare PHP-CLI-Binärdatei – automatisch erkannt und unter Einstellungen → PHP-CLI-Einstellungen konfigurierbar, falls die Erkennung fehlschlägt;
eine erreichbare composer.phar (oder Composer-Binärdatei) im Projekt;
die Konsolen-Binärdatei vendor/bin/typo3 (in jeder Composer-basierten TYPO3-Installation vorhanden).

Backups nutzen zusätzlich mysqldump/mysql, sofern verfügbar (mit einem reinen PHP-PDO-Fallback für den Dump), sowie den ext-zip-Archiv-Writer.

Dateisystem-Berechtigungen

Der PHP-Prozess (Web und CLI) muss var/guardian/ lesen und beschreiben können und – für Updates/Installationen – auf composer.json, composer.lock, vendor/ und packages/ des Projekts zugreifen können. Guardian legt seine privaten Unterverzeichnisse mit restriktiven Berechtigungen an und macht sie niemals welt-beschreibbar.

Installation

composer require vtinnovations/guardian-typo3

Anschließend die TYPO3-Caches leeren, damit das Backend-Modul registriert wird:

vendor/bin/typo3 cache:flush

Das Guardian-Modul erscheint unter System und ist ausschließlich für TYPO3-Administratoren sichtbar. Es gibt keine ext_emconf.php und keinen Legacy-Installationsschritt – die Composer-Metadaten sind maßgeblich.

Zugriff auf das Backend-Modul

Registriert mit access: admin (nur Administratoren) und zusätzlich im Code abgesichert (assertAdministrator()) bei jedem Request und jedem AJAX-Endpunkt – die Zugriffsgarantie hängt niemals allein von der Routing-Konfiguration ab.
Alle zustandsändernden Endpunkte sind ausschließlich POST und tragen das CSRF-Route-Token von TYPO3.
Der Funktionszugriff über „Administrator“ hinaus wird durch die aktive Lizenzstufe geregelt (siehe Lizenz- und Berechtigungsmatrix).

Navigation

Das Modul ist eine einzelne Seite mit sechs clientseitigen Reitern, in dieser Reihenfolge:

Dashboard
Update
Backup
Recovery (Wiederherstellung)
Extensions (Erweiterungen)
Settings (Einstellungen)

Dashboard

Zusammenfassung von Lizenz und Berechtigung (Keine / Free / Pro) mit der Liste der freigeschalteten Funktionen sowie einem Aufruf zum Upgrade bzw. zur Lizenzeingabe.
Systeminformationen: erkannte TYPO3-Version, Anzahl installierter Pakete, Anzahl verfügbarer Backups.
Aktueller Betriebsstatus (Leerlaufanzeige).
Starter für die Vor-Update-Analyse: eine schreibgeschützte Umgebungsprüfung (Composer-Modus, Composer-Dateien, PHP-Version, Beschreibbarkeit des Arbeitsverzeichnisses, PHP-CLI, Datenbankverbindung, Speicherplatz, Lizenz, laufender Job, Backup-Fähigkeit).

Update

Erkennt die installierte TYPO3-Version und führt eine Online-Release-Ermittlung über den öffentlichen TYPO3-Release-Feed durch: das neueste Release der aktuellen Hauptversion und die nächste stabile Hauptversion.
Auswahl der Zielversion, danach ein Composer-Probelauf, der die betroffenen Pakete und Erweiterungen meldet, ohne das Live-Projekt zu verändern.
Run Live bleibt deaktiviert, bis eine Zielversion ausgewählt ist und ein Probelauf erfolgreich war.
Ein Live-Update durchläuft die vollständige Sicherheits-Pipeline: verpflichtendes Sicherheits-Backup → Wartungsmodus → composer update → TYPO3-Extension-Setup / Datenbankschema → Cache-Leerung → Verifizierung der resultierenden Installation, mit automatischem Rollback aus dem Sicherheits-Backup bei jedem Fehler. Ein manuelles Rollback ist ebenfalls verfügbar.
Live-Fortschritt, Schrittzustände und Streaming-Logs; eine Liste der letzten Update-Jobs; sowie das erneute Öffnen eines abgeschlossenen Jobs zur Einsicht in Endstatus und Logs.

Backup

Manuelle Backups mit komponentenweiser Auswahl: der stets enthaltene Kernsatz (composer.json + composer.lock + Datenbank-Dump), fileadmin, lokale packages/, generierte Extension-Assets und das vendor/-Verzeichnis.
Datenbank-Dump über mysqldump mit einem reinen PHP-PDO-Fallback.
Korrekte Behandlung von Composer-Path-Repository-Symlinks, damit lokale Pakete als echte Dateien erfasst werden.
Jedes Archiv trägt ein Manifest und Prüfsummen; Backups werden vor der Wiederherstellung validiert. Aufbewahrungsgrenzen werden pro Profil durchgesetzt.
Geplante Backups (Mini-/Voll-Profile mit Frequenz-, Zeit- und Wochentags-/Tagesregeln) werden hier konfiguriert und vom Konsolenbefehl guardian:backup:run-due ausgeführt (siehe Deployment).
Sicherheits-Backups vor Updates werden von den Update- und Extensions-Pipelines vor jeder Änderung automatisch erstellt.
Backups auflisten, Details einsehen, herunterladen und löschen.

Recovery (Wiederherstellung)

Zwei unabhängige Wiederherstellungswege:

Backend-Wiederherstellung (innerhalb von TYPO3): Backup-Ermittlung, ein verpflichtender Preflight und Probelauf, Komponentenauswahl, Staging, Wiederherstellung lokaler Pakete, ein sicherer Vendor-Neuaufbau aus composer.lock in isoliertem Staging mit atomarem Vendor-Wechsel, Datenbank-Wiederherstellung, Wartungsmodus, ein Transaktionsjournal, Rollback, Erkennung und Rollback unterbrochener Wiederherstellungen sowie Verifizierung nach der Wiederherstellung.
Eigenständiges Wiederherstellungspanel: ein einzelner, in sich geschlossener PHP-Einstiegspunkt, den Guardian in das öffentliche Web-Root ausliefert und der ein Guardian-Backup auch dann wiederherstellt, wenn TYPO3 nicht mehr startet. Es authentifiziert sich mit dem Wiederherstellungs-Token (gehasht gespeichert oder über die Umgebungsvariable GUARDIAN_RECOVERY_TOKEN bereitgestellt), ist ratenbegrenzt und nutzt dieselbe Wiederherstellungs-Engine wie das Backend. Dateiname, Bereitstellung und Token werden unter Recovery/Einstellungen verwaltet.
Wiederherstellungs-E-Mail-Benachrichtigungen: Vor einem Live-Update kann Guardian die Wiederherstellungs-URL und das Zugriffstoken an eine konfigurierte Adresse senden, über die MailerInterface von TYPO3.

Extensions (Erweiterungen)

Vollständige Composer-basierte Erweiterungsverwaltung (Pro):

Auflistung installierter Erweiterungen/Pakete mit Klassifizierung (TYPO3-Core, System-Extension, Drittanbieter-Extension, lokale Extension, Composer-Bibliothek) und Update-Ermittlung.
Paketweises Update, Aktivieren, Deaktivieren und Entfernen, jeweils mit Probelauf, Bestätigung, Sicherheits-Backup und Rollback.
Guardian-Selbstverwaltung: ein verzögertes Selbst-Deaktivieren und ein kontrolliertes Selbst-Entfernen, beide mit eingetippten Bestätigungsphrasen; Guardian löscht sein eigenes Paketverzeichnis niemals implizit.
TER: das TYPO3 Extension Repository durchsuchen, Kompatibilitätsangaben für die laufende TYPO3-Version anzeigen und über einen Ablauf Probelauf → Installation installieren.
Eigener ZIP-Upload: in einen privaten Staging-Bereich hochgeladen, durch eine ZIP-Sicherheitsprüfung und eine Erkennung der Extension-Metadaten geführt, danach ein Ablauf Probelauf → Installation.
Lokale Installationen registrieren eine exakte Path-Repository-Versionszuordnung und von Guardian verwaltete Eigentümer-Metadaten, sodass ein späteres Entfernen das zugehörige Quellverzeichnis löscht (über eine Quarantäne) und eine zuvor entfernte hochgeladene Erweiterung sauber erneut hochgeladen und installiert werden kann (Erkennung verwaister Verzeichnisse).
Durchgehend Live-Fortschritt, strukturierte Fehlerberichte und Job-Logs.

Lizenz (System → VTOne Licensing)

Lizenz: eine Lizenz aktivieren, Lizenz aktualisieren und entfernen. Diese Bedienelemente liegen an genau einer Stelle: unter System → VTOne Licensing, einer gemeinsamen Seite mit je einem Abschnitt pro installiertem V-T.ONE-Produkt. Der Einstellungs-Tab von Guardian verlinkt dorthin und enthält selbst keine Lizenzsteuerung mehr. Nutze diese Seite für Aktivierung, Aktualisierung und Entfernen; es gibt keinen unterstützten Weg, eine Lizenz von Hand einzuspielen oder zu bearbeiten.

Guardian benötigt eine aktivierte V-T.ONE-Lizenz und wird als Free oder Pro vertrieben. Beide Stufen benötigen einen aktivierten Schlüssel, und Free- wie Pro-Funktionen werden serverseitig durchgesetzt. Reguläre Berechtigungsprüfungen erfolgen lokal anhand authentifizierter und integritätsgeschützter Lizenzdaten, sodass eine geprüfte Lizenz bis zu ihrem Ablauf auch ohne Netzwerkzugriff weiterarbeitet. Eine abgelaufene Pro-Lizenz fällt nur dann auf den Free-Funktionsumfang zurück, wenn die Lizenz das ausdrücklich erlaubt; andernfalls deaktiviert der Ablauf die geschützten Funktionen.

Eine Lizenz autorisiert eine bestimmte Menge von Hostnamen. Guardian gewährt Free oder Pro, wenn einer dieser Hosts auch in der TYPO3-Site-Konfiguration konfiguriert ist – als base einer Site, base einer Sprache oder Eintrag unter baseVariants. Mehrere Domains sind zulässig; eine exakte Übereinstimmung genügt. www.example.com und example.com gelten als verschiedene Hosts, und eine Installation ohne Site-Konfiguration kann nicht lizenziert werden.

Settings (Einstellungen)

PHP-CLI-Einstellungen: den Pfad zur PHP-CLI-Binärdatei automatisch erkennen, testen und speichern.
Wiederherstellungs-E-Mail: Empfänger/Absender konfigurieren und eine Test-E-Mail senden (über MailerInterface).
Konfiguration des eigenständigen Wiederherstellungspanels: Panel-Dateiname, Bereitstellung und Token.

Lizenz- und Berechtigungsmatrix

Der Zugriff wird serverseitig an jedem Endpunkt durchgesetzt (Administrator-Gate → Lizenz-Gate). „Free“ bedeutet eine aktivierte Free-Lizenz oder eine abgelaufene Pro-Lizenz, die den Free-Fallback erlaubt; „Pro“ bedeutet eine aktive Pro-Lizenz.

Funktion	Zugriff
Manuelles Backup	Free und Pro
Geplantes Backup	Nur Pro
Update	Nur Pro
Extensions	Nur Pro
Recovery (Backend)	Nur Pro
Eigenständige Wiederherstellung (bereitstellen & verwalten)	Nur Pro
Lizenzaktivierung / Update / Entfernen (VTOne Licensing)	Verfügbar (Administrator)
Vor-Update-Analyse (Dashboard)	Verfügbar (Administrator)

Effektiver Zugriff je Lizenzzustand:

Lizenzzustand	Manuelles Backup	Geplantes Backup	Update	Extensions	Recovery	Eigenständige Wiederherstellung
Keine Lizenz	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend
Aktive Free	Verfügbar	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend
Aktive Pro	Verfügbar	Verfügbar	Verfügbar	Verfügbar	Verfügbar	Verfügbar
Noch nicht gültig	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend
Abgelaufene Pro, die den Free-Fallback erlaubt	Verfügbar (Free-Fallback)	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend
Abgelaufene Pro ohne diese Erlaubnis oder abgelaufene Free	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend
Lizenz für diese Installation nicht gültig	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend	Nicht zutreffend

Ohne gültige Lizenz sind nur Dashboard und Einstellungen nutzbar (damit eine Lizenz eingegeben werden kann). Verwendete Statusbezeichnungen: Verfügbar, Nur Pro, Free und Pro, Nicht zutreffend.

Sicherheitsarchitektur

Nur für Administratoren zugängliches Modul und Endpunkte (access: admin + Prüfung im Code); POST + CSRF-Token bei jeder Mutation.
Pfad-Eingrenzung: der gesamte Guardian-Zustand ist auf var/guardian/ begrenzt und wird symlink-unabhängig validiert; Uploads sind auf ein privates Staging-Verzeichnis eingegrenzt.
Keine Shell-String-Ausführung: externe Prozesse laufen über symfony/process mit Argument-Arrays – niemals exec()/shell_exec()/system()/Backticks.
ZIP-Sicherheitsprüfung (Path-Traversal, Symlinks, Anzahl/Größe der Einträge und Prüfung auf Dekomprimierungsbomben) bei jedem hochgeladenen Archiv.
Schwärzung von Geheimnissen: Logs und API-Antworten geben niemals den vollständigen Lizenzschlüssel, Lizenz-Authentifizierungsmaterial, Wiederherstellungs-Token, Transport-Zugangsdaten, DSNs, Stacktraces oder absolute Installationspfade preis.
Lizenzdaten liegen außerhalb des öffentlichen Web-Roots und werden vor ihrer Verwendung auf Echtheit und Integrität geprüft; das Token des eigenständigen Wiederherstellungspanels wird nicht in wiederherstellbarer Form gespeichert.

Siehe Documentation/SecurityModel.md.

Sicherheit bei Update, Backup und Wiederherstellung

Update-Sicherheit: verpflichtendes Backup vor dem Update, Wartungsmodus, isolierter Composer-Probelauf, Verifizierung des Ergebnisses und automatisches Rollback aus dem Sicherheits-Backup, falls ein Schritt fehlschlägt. Siehe Documentation/UpdateImplementation.md.
Backup-Sicherheit: Manifeste + Prüfsummen, Validierung vor der Wiederherstellung, Durchsetzung der Aufbewahrung sowie korrekte Behandlung von Symlinks/Vendor/lokalen Paketen.
Wiederherstellungs-Sicherheit: verpflichtender Probelauf, atomarer Vendor-Wechsel, ein Transaktionsjournal, Erkennung/Rollback unterbrochener Wiederherstellungen und Verifizierung nach der Wiederherstellung. Siehe Documentation/RecoverySafety.md und Documentation/StandaloneRecoveryPanel.md.
Sicherheit bei der Extension-Installation: privates Staging, ZIP-Prüfung, Probelauf, verwaltete Eigentümer-Metadaten sowie sicheres Entfernen/erneutes Installieren verwalteter Quellverzeichnisse.

Laufzeitverzeichnisse

Guardian hält den gesamten Zustand unter var/guardian/, darunter: Lizenzdaten, die Laufzeitkonfiguration, Backup-Zeitpläne, Prozess-Locks, Update-Jobs und deren Logs, erstellte Backups, das Wiederherstellungs-Staging und das Transaktionsjournal, das Extension-Upload-Staging sowie die Quarantäne entfernter verwalteter Verzeichnisse und das Token des eigenständigen Wiederherstellungspanels. Dieses Verzeichnis liegt außerhalb des öffentlichen Web-Roots und muss dort bleiben. Außerhalb von var/guardian/ wird nichts geschrieben – außer den Operationen, die der Administrator ausdrücklich auslöst (Composer-Änderungen, die ausgelieferte Recovery-Panel-Datei im Web-Root und wiederhergestellte Projektdateien).

Externe V-T.ONE-Kommunikation

Guardian kommuniziert ausschließlich mit vertrauenswürdigen V-T.ONE-HTTPS-Diensten unter www.v-t.one, stets mit aktivierter Transportverschlüsselungs-Prüfung, und verhält sich ausfallsicher, falls diese nicht erreichbar sind. Es gibt zwei Arten ausgehenden Verkehrs:

Lizenzaktivierung und -aktualisierung – erfolgt nur, wenn eine Administratorin eine Lizenz über die Guardian-Oberfläche aktiviert oder ausdrücklich aktualisiert.
Betriebssignale – Fire-and-forget, blockieren niemals einen Request oder eine Lizenzentscheidung:
- einmal pro Web-Aufruf, überträgt ausschließlich den Produktbezeichner und die normalisierte Domain;
- einmal pro angemeldeter Backend-Session, wenn eine Administratorin das Modul erstmals öffnet, überträgt ausschließlich die normalisierte Domain und den Lizenzschlüssel. Das geschieht Server-zu-Server; der Schlüssel erreicht weder den Browser noch die Logs.

Guardian empfängt zusätzlich autorisierte, authentifizierte Lizenzaktualisierungen, die von V-T.ONE ausgelöst werden. Sie treffen auf einem maschinellen Endpunkt dieser Installation ein, sind also keine Adresse, die Guardian aufruft; sie werden erst nach erfolgreicher Authentifizierung und dann atomar oder gar nicht angewendet.

Es findet kein weiteres ausgehendes HTTP statt, außer den Abfragen des TYPO3 Extension Repository / von Packagist im Reiter Extensions.

Protokollierung und Schwärzung von Geheimnissen

Betriebsausgaben werden in die Job-Logs von Guardian und das TYPO3-System-Log geschrieben. Alle Logzeilen und AJAX-Payloads durchlaufen vor dem Verlassen des Servers eine Schwärzung von Geheimnissen: der vollständige Lizenzschlüssel, Lizenz-Authentifizierungsmaterial, Wiederherstellungs-Token, Mail-Transport-DSNs/-Zugangsdaten und absolute Pfade werden niemals ausgegeben.

Deployment

# 1. Erweiterung installieren / aktualisieren
composer require vtinnovations/guardian-typo3

# 2. Autoloader neu erzeugen (Produktion)
composer dump-autoload -o

# 3. Modul registrieren/aktualisieren und Extension-Setup anwenden
vendor/bin/typo3 extension:setup

Geplante Backups erfordern einen externen Auslöser, der den Konsolenbefehl periodisch aufruft – einen echten Cron-Eintrag oder eine TYPO3-Scheduler-Aufgabe vom Typ „Konsolenbefehl ausführen“. Guardian registriert keine Scheduler-Aufgabe automatisch.

*/5 * * * * /usr/bin/php /path/to/project/vendor/bin/typo3 guardian:backup:run-due

Registrierte Konsolenbefehle:

guardian:backup:run-due – aktuell fällige geplante Backups ausführen (Cron/Scheduler).
guardian:update:run – interner abgekoppelter Update-/Extensions-Worker (von Guardian gestartet; nicht manuell auszuführen).
guardian:release:check – prüft, ob dieses Build ausgeliefert werden darf (prüft die eingebetteten Verifikationsschlüssel). Beendet sich bei einem Problem mit einem Fehlercode.

Cache leeren

vendor/bin/typo3 cache:flush

Nach dem Ausliefern aktualisierter Frontend-Assets das Backend hart neu laden, damit die aktualisierten guardian.js/guardian.css geladen werden.

Tests

composer install
vendor/bin/phpunit -c phpunit.xml.dist

Die Suite unter Tests/Unit/ deckt die CMS-unabhängige Logik ab (Lizenzinterpretation und Speicher-Schema, Pfadsicherheit, Archivvalidierung, Zeitplan-Berechnung, Lock-Verhalten, Konstruktion von Composer-Befehlen, Paketklassifizierung, Job-Übergänge, verwaltete Eigentümerschaft und Entfernung). Siehe Documentation/Testing.md für den vollständigen Befehlssatz.

Bekannte Einschränkungen

Der Composer-Modus ist erforderlich für Update und Extensions; auf einer Nicht-Composer-Installation können diese Reiter nicht arbeiten.
Geplante Backups benötigen einen externen Auslöser (echter Cron oder eine TYPO3-Scheduler-Aufgabe „Konsolenbefehl ausführen“) – es gibt keine automatisch registrierte Scheduler-Aufgabe.
Update-/Wiederherstellungs-Worker benötigen eine PHP-CLI-Binärdatei und eine erreichbare composer.phar; konfigurieren Sie den PHP-CLI-Pfad in den Einstellungen, falls die automatische Erkennung fehlschlägt.
Die Backend-Wiederherstellung läuft innerhalb von TYPO3. Startet TYPO3 nicht mehr, verwenden Sie das eigenständige Wiederherstellungspanel.
Die Unit-Tests sind CMS-unabhängig; eine vollständige funktionale TYPO3-Abdeckung hängt von den PHP-/Composer-/Datenbank-Werkzeugen der Zielumgebung ab.

Projektinformationen

GitHub: github.com/vtinnovations/guardian-typo3
Packagist: packagist.org/packages/vtinnovations/guardian-typo3
Installation: composer require vtinnovations/guardian-typo3
Lizenz: LGPL-3.0-or-later
Herausgeber: V&T Innovations

vtinnovations / guardian-typo3

Maintainers

Package info

Statistics

Security