- docs/PLAN.md: Architektur, Plugin-System, Self-Updater & Lizenz, Rückmeldungen, Berechtigungen, Entra-ID-Gruppen-Mapping, Performance, Pagebuilder, Branding & Theming, Phasen - docs/specs/: Vorgaben für Self-Updater und Rückmeldungen (unverändert) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
433 lines
23 KiB
Markdown
433 lines
23 KiB
Markdown
# Spezifikation: Self-Updater & Lizenzprüfung
|
||
|
||
> Vorgabe des Herstellers, unverändert übernommen (Stand 2026-09-25).
|
||
> Umsetzungsnotizen für dieses Projekt stehen in `docs/PLAN.md`, Abschnitt 5.
|
||
|
||
Baue in dieses Projekt einen selbstständigen In-App-Updater ein („Self-Updater"),
|
||
mit dem eine laufende Installation sich per Klick im Admin-Bereich auf den neuesten
|
||
Stand aktualisiert – OHNE SSH-Zugriff auf dem Zielserver. Übertrage das folgende
|
||
Konzept auf den Stack DIESES Projekts: passe Framework-spezifische Teile an
|
||
(Routing, Middleware, HTTP-Client, CLI-Aufrufe, Markdown-Renderer, Admin-Auth),
|
||
behalte Architektur, Ablauf und ALLE Sicherheitseigenschaften bei.
|
||
|
||
Deutsche UI-Texte mit echten Umlauten, technische Schlüssel und Routen bleiben ASCII.
|
||
|
||
## Gesamtidee
|
||
Die App kennt ihre installierte Version als Git-Commit-SHA (in einer DATEI, nicht in
|
||
der Datenbank – der Updater muss sie auch lesen können, wenn die DB gerade hängt) und
|
||
eine semantische Release-Version aus dem Code. Ein bereits laufender Update-Proxy
|
||
stellt den neuesten Stand eines Branches als ZIP bereit. Der Updater lädt das ZIP,
|
||
entpackt es kontrolliert über die Produktion (mit geschützten Pfaden), führt
|
||
ausstehende DB-Migrationen aus, leert Caches und schreibt die neue SHA. Während des
|
||
Updates zeigt die App eine Wartungsseite; der Fortschritt wird über eine Status-Datei
|
||
gepollt.
|
||
|
||
## Der Update-Proxy steht bereits – das ist sein Vertrag
|
||
Du musst KEINEN Proxy bauen. Er läuft unter:
|
||
|
||
https://update.loheide.cloud/mitarbeiterportal
|
||
|
||
Verfügbare Endpunkte (alle GET, Antworten JSON sofern nicht anders vermerkt):
|
||
|
||
GET https://update.loheide.cloud/mitarbeiterportal/version
|
||
-> { "sha": "<voller Commit-SHA>",
|
||
"version": "1.12.0"|null, aus dem Änderungsprotokoll
|
||
"released_at": "…"|null,
|
||
"release_note": "…" } NUR falls hinterlegt
|
||
|
||
GET https://update.loheide.cloud/mitarbeiterportal/check?current_sha=<sha>
|
||
Client ist aktuell:
|
||
-> { "has_update": false,
|
||
"latest_sha": "<sha>", "version": …, "released_at": … }
|
||
Es gibt Neues:
|
||
-> { "has_update": true,
|
||
"latest_sha": "<sha>",
|
||
"version": "1.12.0"|null,
|
||
"released_at": "…"|null,
|
||
"versions_behind": <int>,
|
||
"changelog_preview": {
|
||
"entries": [ { "version", "heading", "text" }, … ],
|
||
"complete": true|false } }
|
||
Ohne current_sha antwortet der Proxy wie „aktuell" – die erste Prüfung
|
||
einer frischen Installation liefert also latest_sha zum Merken.
|
||
|
||
Kanalwechsel (nur bei Software mit mehreren Kanälen):
|
||
-> { …, "channel_switch": { "from_channel", "to_channel",
|
||
"direction": "forward"|"back" } }
|
||
Steht das Feld da, stammt der gemeldete Stand aus einem anderen Kanal.
|
||
Dann ist "versions_behind" 1. Bei "direction": "back" ist der
|
||
Zielstand ÄLTER als der laufende; das ist beim Zurückschalten auf
|
||
den Hauptkanal der Normalfall. Ein Updater darf hier nicht abbrechen,
|
||
weil der Zeitstempel rückwärts geht: Er soll schlicht latest_sha
|
||
ziehen und einspielen.
|
||
|
||
GET https://update.loheide.cloud/mitarbeiterportal/zip?ref=<sha>
|
||
-> Binäres ZIP des Projektstands. GitHub-Stil: EIN gemeinsamer
|
||
Top-Level-Ordner ("repo-<sha>/"), der beim Entpacken entfernt wird.
|
||
Antwort beginnt mit "PK". Kopfzeilen X-Commit-Sha und
|
||
X-Content-Sha256 benennen den gelieferten Stand.
|
||
|
||
GET https://update.loheide.cloud/mitarbeiterportal/changelog?format=raw
|
||
-> Die CHANGELOG.md des aktuellen Stands als Markdown (text/markdown).
|
||
Mit format=json stattdessen { tool, file, latest_sha, content }.
|
||
|
||
GET https://update.loheide.cloud/mitarbeiterportal/files?path=<unterverzeichnis>
|
||
-> { "files": [ { "name", "path", "type": "file"|"dir", "size" }, … ] }
|
||
|
||
GET https://update.loheide.cloud/mitarbeiterportal/download/<pfad-im-repo>
|
||
-> Einzelne Datei. Nützlich, um vor dem Update z. B. nur die
|
||
CHANGELOG.md oder eine Versionsdatei zu ziehen.
|
||
|
||
Fehlerfälle, die kein Fehler des Clients sind:
|
||
503 mirror_pending Der Stand wird gerade gespiegelt. Später erneut.
|
||
503 not_released Es liegt etwas bereit, aber noch nichts ist
|
||
freigegeben. Ebenfalls später erneut – der Client
|
||
kann nichts richtig machen. Beide tragen retry_after.
|
||
|
||
WICHTIG zum Modell: Es gibt KEINE Tags und KEINE Releases. Es zählt der Stand des
|
||
Branches, und die Identität eines Stands ist sein Commit-SHA. „versions_behind"
|
||
zählt Commits, nicht Versionsnummern. Baue nichts, was Tags erwartet.
|
||
|
||
WICHTIG zur Anzeige: Es gibt KEINE Commit-Titel und KEINE Commit-Texte in diesen
|
||
Antworten, und es wird auch keine geben. Commit-Nachrichten sind für Entwickler
|
||
geschrieben ("Merge pull request #229 from …") und dürfen einem Anwender nie
|
||
unter die Augen kommen. Zeige deshalb genau zwei Dinge:
|
||
|
||
1. dass eine neue Version da ist – aus has_update, version, released_at,
|
||
2. was daran neu ist – aus changelog_preview.entries.
|
||
|
||
changelog_preview enthält die Abschnitte des Änderungsprotokolls, die seit dem
|
||
gemeldeten Stand dazugekommen sind, neueste zuerst; "text" ist Markdown. Das
|
||
FELD KANN FEHLEN – dann gibt es nichts zu berichten, und die Anzeige beschränkt
|
||
sich auf „neue Version verfügbar". Baue keinen leeren Kasten und erfinde keinen
|
||
Ersatztext. Bei "complete": false wurde gekürzt; dann ist ein Verweis auf
|
||
https://update.loheide.cloud/mitarbeiterportal/changelog richtig.
|
||
|
||
## Lizenzprüfung – dieser Teil ist der Unterschied
|
||
Dieses Programm ist lizenzpflichtig. Jede Anfrage an die Update-Endpunkte muss
|
||
sich ausweisen, sonst antwortet der Proxy mit 401 oder 403.
|
||
|
||
### Kopfzeilen
|
||
X-License-Email: <die auf der Lizenz hinterlegte Adresse>
|
||
Authorization: Bearer <Lizenzschlüssel>
|
||
X-Device-Id: <dauerhafte, einmalig erzeugte Gerätekennung>
|
||
X-Device-Token: <zuletzt erhaltenes Token, falls vorhanden>
|
||
|
||
Alles geht ersatzweise auch als Query-Parameter (email, key, device_id,
|
||
device_token). Bevorzuge die Kopfzeilen: Parameter landen in Server-Protokollen.
|
||
|
||
Die Lizenz-E-Mail ist NICHT zwingend die E-Mail des Kunden – sie gehört zur
|
||
Lizenz. Nimm sie als eigenständigen Wert entgegen und leite sie nicht aus
|
||
irgendeinem Benutzerkonto ab.
|
||
|
||
### Das rotierende Gerätetoken – bitte genau so umsetzen
|
||
JEDE Antwort auf eine Anfrage mit Lizenzdaten kann ein neues Token liefern: als
|
||
Kopfzeile `X-Device-Token` und, bei JSON-Antworten, im Feld `device_token`. Das
|
||
gilt auch für Dateidownloads und für die Meldungs-Endpunkte (Fehlerbericht,
|
||
Funktionswunsch, Beta-Anmeldung) – nicht nur für die Lizenzprüfung.
|
||
|
||
Speichere es SOFORT und sende es bei der nächsten Anfrage zurück –
|
||
auch dann, wenn die Antwort selbst ein Fehler war.
|
||
|
||
Hintergrund: Wird ein Installationsordner kopiert, halten beide Kopien zunächst
|
||
dasselbe Token. Sobald eine rotiert, legt die andere ein veraltetes vor – genau
|
||
daran erkennt der Server die Mehrfachnutzung.
|
||
|
||
Gültig bleibt nicht nur das jüngste Token, sondern die zuletzt ausgegebenen.
|
||
Eine verlorene Antwort, ein abgebrochener Download oder mehrere gleichzeitige
|
||
Anfragen sind deshalb unkritisch. Ein Client, der das Token gar nicht speichert,
|
||
meldet sich dagegen bei jedem Aufruf selbst als Verdachtsfall.
|
||
|
||
Verliert der Client das Token (Neuinstallation, gelöschte Einstellungen), sendet
|
||
er einfach keines. Ein einzelner Verlust ist unkritisch.
|
||
|
||
Schickst du mehrere Anfragen gleichzeitig los – etwa vier gesammelte Meldungen
|
||
auf einen Klick –, ist das erlaubt. Wenn es sich einfach machen lässt, ist es
|
||
trotzdem sauberer, sie nacheinander zu senden und das Token dazwischen
|
||
nachzuführen.
|
||
|
||
### Neuer Endpunkt: Lizenzauskunft
|
||
GET https://update.loheide.cloud/mitarbeiterportal/license
|
||
-> {
|
||
"licensing_required": true,
|
||
"license": { "status", "valid_until"|null, "unlimited": bool,
|
||
"days_remaining"|null, "expired": bool },
|
||
"registered_to": { "license_email", "company", "contact_name" },
|
||
"devices": { "used", "max", "policy" },
|
||
"updates": { "last_seen_sha", "last_download_sha", "last_download_at" }
|
||
}
|
||
|
||
"valid_until": null zusammen mit "unlimited": true bedeutet UNBEFRISTET.
|
||
Behandle das ausdrücklich – nicht als „abgelaufen" und nicht als Fehler.
|
||
|
||
Gut geeignet für einen „Über dieses Programm"-Dialog: auf wen die Lizenz läuft,
|
||
wie lange noch, wie viele Geräteplätze belegt sind.
|
||
|
||
### Fehlerbehandlung
|
||
Fehler kommen als JSON mit einem stabilen `code`. Prüfe auf `code`, NICHT auf
|
||
den Meldungstext – der Text kann sich ändern.
|
||
|
||
license_required 401 keine Lizenzdaten gesendet → Eingabemaske
|
||
invalid_key 403 Schlüssel unbekannt → Eingabemaske
|
||
email_mismatch 403 E-Mail passt nicht zum Schlüssel
|
||
license_expired 403 abgelaufen → Hinweis auf Verlängerung
|
||
license_revoked 403 gesperrt → Support-Hinweis
|
||
device_limit_reached 403 alle Plätze belegt; Antwort enthält
|
||
devices_used und devices_max
|
||
device_cloned 403 Mehrfachnutzung erkannt → Support-Hinweis
|
||
device_id_required 403 Lizenz ist gerätegebunden, Client sendet keine ID
|
||
rate_limited 429 Retry-After beachten
|
||
maintenance 503 Server aktualisiert sich gerade → später erneut
|
||
upstream_unavailable 503 vorübergehend → alten Stand behalten
|
||
|
||
GRUNDREGEL, die du strikt einhalten musst:
|
||
Ein Lizenzfehler darf das Programm NIE unbenutzbar machen. Er verhindert
|
||
ausschließlich den Update-Bezug. Alles andere führt zu Anrufen an Feiertagen.
|
||
Zeige einen Hinweis, protokolliere den Code – und lass das Programm laufen.
|
||
|
||
### Optional: Gerät selbst abmelden
|
||
POST https://api.loheide.cloud/v1/license/release-device?software=mitarbeiterportal
|
||
(mit denselben Kopfzeilen)
|
||
Gibt den Geräteplatz wieder frei. Baue das in einen Deinstallations- oder
|
||
„Diesen Rechner abmelden"-Ablauf ein, dann kann der Kunde ohne Rückfrage auf
|
||
einen neuen Rechner wechseln.
|
||
|
||
## Komponenten (Namen an die Konventionen des Projekts anpassen)
|
||
|
||
1) Version-Helper
|
||
- current(): volle SHA aus `storage/.version`, oder null bei Erstinstallation
|
||
- save(sha): schreibt sie zurück (vorher auf 40 Hex-Zeichen prüfen)
|
||
- short() (7 Zeichen), release() (SemVer aus dem Code), full() → "1.4.2 (a1b2c3d)"
|
||
Die Datei liegt bewusst in storage/ – das ist ein geschützter Pfad, ein Update
|
||
überschreibt sie also nie mit dem Stand aus dem Archiv.
|
||
|
||
2) Fortschritts-Datei
|
||
- schreibt bei jedem Schritt JSON nach `storage/.update-progress`:
|
||
{ pct: int, step: string, text: string, ts: int }
|
||
- get() liefert Default { pct: 0, step: "idle" }, wenn nichts da ist
|
||
- Fehler: pct = -1, step = "error" – dadurch eindeutig von "0 % erledigt"
|
||
unterscheidbar
|
||
- isRunning(): läuft nur als aktiv, wenn das letzte Lebenszeichen jünger als
|
||
~10 Minuten ist. Sonst blockiert ein abgestürzter Lauf dauerhaft den nächsten.
|
||
|
||
3) Wartungsmodus
|
||
- Flag-Datei `storage/.maintenance` mit { since, until }
|
||
- isActive() ist SELBSTHEILEND: ein abgelaufenes `until` wird beim Prüfen
|
||
automatisch entfernt. Ohne das legt ein Absturz mitten im Update die
|
||
Installation dauerhaft lahm – und niemand käme mehr an die Oberfläche,
|
||
um den Modus abzuschalten.
|
||
- activate(maxSeconds = 600), deactivate()
|
||
|
||
4) Updater (Kern), Methode installUpdate() mit Fortschritts-Meldungen:
|
||
(0 %) Wartungsmodus aktivieren
|
||
(5 %) GET /version → Ziel-SHA
|
||
(20 %) GET /zip?ref=<sha> in eine Datei streamen, NICHT in den Speicher.
|
||
Danach prüfen: beginnt die Datei mit "PK"? Wenn nicht, hat in
|
||
Wahrheit eine Fehlerseite geantwortet – mit klarer Meldung abbrechen.
|
||
(50 %) nach `storage/.update-staging` entpacken:
|
||
- gemeinsamen Top-Level-Ordner ermitteln und strippen
|
||
- ZIP-SLIP-SCHUTZ, zweistufig:
|
||
a) Eintragsnamen vorab ablehnen: absolute Pfade, Laufwerks-
|
||
buchstaben (C:\), ".."-Segmente, Null-Bytes
|
||
b) NACH dem Schreiben den aufgelösten Pfad prüfen – liegt er
|
||
wirklich im Staging? Sonst Datei sofort wieder löschen.
|
||
Die zweite Prüfung fängt ab, was die erste übersieht (Symlinks,
|
||
ungewöhnliche Kodierungen). Beides einbauen, nicht nur eins.
|
||
(65 %) Staging über die Produktion legen, geschützte Pfade auslassen.
|
||
Je Datei erst daneben schreiben, dann umbenennen – ein Abbruch
|
||
mittendrin hinterlässt sonst eine halbe Datei, die den nächsten
|
||
Aufruf mit einem Parse-Fehler abwürgt.
|
||
NUR überschreiben und ergänzen, NICHT löschen: eine im neuen Stand
|
||
fehlende Datei bleibt liegen. Etwas unaufgeräumter, aber ein Fehler
|
||
in der Pfadberechnung nimmt so keine Nutzdaten mit.
|
||
(80 %) ausstehende Migrationen ausführen, Anzahl zurückgeben
|
||
(90 %) Caches leeren (App-, View-, Config-, Route-Cache) und den
|
||
Bytecode-Cache verwerfen (opcache_reset o. ä.) – sonst läuft nach
|
||
dem Update noch eine Weile der alte Code
|
||
(100 %) neue SHA speichern, Audit-Eintrag schreiben, ZIP und Staging löschen
|
||
|
||
Fehlerbehandlung: bei einer Ausnahme step = "error", pct = -1, Meldung setzen,
|
||
Fehler ins Audit-Log. Im finally IMMER den Wartungsmodus deaktivieren.
|
||
Timeouts: maßvoll für die JSON-Aufrufe, großzügig für den ZIP-Download
|
||
(z. B. 180 s), Weiterleitungen begrenzen, nur HTTPS zulassen.
|
||
|
||
5) Geschützte Pfade (konfigurierbar, werden beim Übernehmen NIE überschrieben).
|
||
Mindestens: `.env`, `.git/`, `storage/`, `vendor/`, `node_modules/`,
|
||
`composer.lock`, `package-lock.json`, lokale Konfiguration, lokale DB-Datei.
|
||
Verzeichnisse per Schrägstrich am Ende matchen, Dateien exakt.
|
||
|
||
6) Auto-Migration beim ersten Seitenaufruf nach dem Update
|
||
Ohne SSH ist das der einzige verlässliche Zeitpunkt, zu dem neue Migrationen
|
||
laufen können.
|
||
- überspringen, wenn nicht installiert oder in Tests
|
||
- Fingerabdruck (Hash) über die Liste der Migrationsdateien bilden; nur wenn
|
||
der sich geändert hat, überhaupt migrieren. Sonst läuft der Migrator bei
|
||
JEDEM Request – das ist der Fehler, den man hier am häufigsten sieht.
|
||
- Sperre über Requests hinweg gegen Parallellauf (DB-Lock oder Lock-Datei)
|
||
- Fehler protokollieren, NICHT werfen: eine fehlgeschlagene Nachführung darf
|
||
nicht jede Seite unbenutzbar machen
|
||
|
||
7) Wartungs-Middleware
|
||
Solange der Wartungsmodus aktiv ist: 503 mit Retry-After und einer
|
||
verständlichen Wartungsseite – AUSSER für die Update-Endpunkte selbst, die
|
||
Anmeldeseite und den Health-Check. Sonst kann niemand mehr sehen, wie weit
|
||
das laufende Update ist.
|
||
8) Lizenz-Speicher
|
||
- hält Lizenz-E-Mail, Lizenzschlüssel, device_id und device_token
|
||
- device_id: EINMALIG erzeugen (16 Zufallsbytes als Hex genügen) und
|
||
dauerhaft neben der Konfiguration ablegen. Eine Hardware-Kennung tut es
|
||
auch, wechselt aber beim Tausch von Bauteilen und ist datenschutzrechtlich
|
||
heikler – eine gespeicherte Zufallszahl ist der ruhigere Weg.
|
||
- Zusätzlich bei JEDER Anfrage mitschicken: hostname (Rechnername) und
|
||
device_label (Rechnername + Installationspfad, z. B.
|
||
"web01:/var/www/kunde"). Beides ist optional, aber ohne das sieht der
|
||
Kunde im Portal nur namenlose Zeilen und kann nicht erkennen, welchen
|
||
Geräteplatz er freigeben darf. Ein „Gerät“ ist hier ein
|
||
Installationsverzeichnis: zwei Vhosts auf demselben Server zählen als
|
||
zwei, ein mitkopiertes Verzeichnis als eines.
|
||
- device_token: NACH JEDER ANTWORT sofort speichern, bevor irgendetwas
|
||
anderes passiert (siehe unten – das ist der Punkt, an dem die meisten
|
||
Implementierungen scheitern)
|
||
- Eingabemaske im Admin-Bereich für E-Mail und Schlüssel, mit
|
||
„Lizenz prüfen"-Knopf gegen https://update.loheide.cloud/mitarbeiterportal/license
|
||
|
||
## Admin-Oberfläche (nur für Administratoren)
|
||
Eine Seite „Aktualisierung" mit:
|
||
- aktueller Version (SemVer + Kurz-SHA) und aktivem Kanal
|
||
- Kanal-Auswahl, persistiert in den App-Einstellungen
|
||
- „Nach Updates suchen" → ruft /check und zeigt: Update ja/nein, Zielversion
|
||
und Ziel-SHA, „X Version(en) zurück" und die Abschnitte aus
|
||
changelog_preview. Fehlt das Feld, steht dort nur „neue Version verfügbar" –
|
||
ohne Ersatztext und ohne leeren Kasten
|
||
- „Jetzt aktualisieren" → startet die Installation und pollt den Fortschritt
|
||
alle ~2 s; Fortschrittsbalken + Statustext, im Fehlerfall die Meldung
|
||
- „Migrationen ausführen" (manuell) + Liste aller Migrationsdateien mit Status
|
||
angewendet/offen
|
||
- Changelog-Historie: liest die mitgelieferte CHANGELOG.md, zerlegt sie an
|
||
"## <version>"-Abschnitten, rendert je Abschnitt Markdown → HTML
|
||
(unsichere Links strippen) und zeigt sie chronologisch
|
||
- Lizenzbereich: hinterlegte Lizenz-E-Mail und Schlüssel (Schlüssel maskiert),
|
||
Laufzeit, verbleibende Tage, belegte von erlaubten Geräten, Knopf
|
||
„Lizenz prüfen". Bei einer bald ablaufenden Lizenz (< 30 Tage) ein Hinweis,
|
||
der NICHT blockiert.
|
||
|
||
Backend-Endpunkte, nur für Admins und CSRF-geschützt:
|
||
POST /admin/update/check
|
||
POST /admin/update/install
|
||
GET /admin/update/progress
|
||
POST /admin/update/channel
|
||
POST /admin/update/migrations
|
||
|
||
/install muss das Zeitlimit anheben (set_time_limit(0) o. ä.) und einen
|
||
Client-Abbruch ignorieren (ignore_user_abort(true)) – der Ablauf läuft
|
||
serverseitig weiter, das Frontend pollt nur den Fortschritt.
|
||
|
||
## Kanäle
|
||
Mehrere Kanäle über Konfiguration, jeweils eigene Proxy-Basis-URL, z. B.:
|
||
stable -> https://update.loheide.cloud/mitarbeiterportal
|
||
development -> https://update.loheide.cloud/mitarbeiterportal-development
|
||
Der aktive Kanal wird persistiert (Standard: stable). Eine Factory erzeugt die
|
||
Updater-Instanz für den aktiven oder einen übergebenen Kanal und lehnt
|
||
unbekannte Kanäle ab.
|
||
|
||
## Versionierung und Changelog (im Repo, nicht in der App)
|
||
Lege eine `CHANGELOG.md` an (neueste Version oben, Abschnitte
|
||
"## MAJOR.MINOR.PATCH", kurze deutsche Stichpunkte) und eine Konstante `VERSION`
|
||
(SemVer) im Code. Dokumentiere diesen Ablauf für JEDE Änderung:
|
||
|
||
1. CHANGELOG.md: neuen Versionsabschnitt ergänzen
|
||
2. VERSION anheben (Patch = Fehlerbehebung, Minor = Funktion)
|
||
3. Tests grün, ggf. Frontend-Build – kompilierte Assets werden MITVERSIONIERT,
|
||
weil beim Kunden kein Build läuft
|
||
4. Commit und Merge in den Branch, den der Proxy ausliefert
|
||
|
||
Damit ist die neue Fassung sofort über den Self-Updater verfügbar. Die
|
||
installierte SHA pflegt der Updater selbst.
|
||
|
||
## Datenschutzhinweis – Pflichtteil, nicht optional
|
||
Die Update-Prüfung überträgt personenbezogene Daten an einen Server, den
|
||
der Anwender nicht betreibt. Der Hinweis darauf gehört an die Stelle, an
|
||
der es passiert, und zwar VORHER: auf die Seite „Aktualisierung",
|
||
dauerhaft sichtbar unter oder neben dem Knopf „Nach Updates suchen" –
|
||
nicht in einen Dialog, den man einmal wegklickt.
|
||
|
||
Bei der Suche nach Updates und beim Herunterladen einer neuen Fassung
|
||
werden Daten an update.loheide.cloud übertragen. Übermittelt werden:
|
||
|
||
• die auf Ihrer Lizenz hinterlegte E-Mail-Adresse und der Lizenzschlüssel
|
||
• eine Gerätekennung, die dieses Programm einmalig als Zufallszahl erzeugt
|
||
hat (keine Hardwarekennung, keine Seriennummer) – damit wird gezählt,
|
||
auf wie vielen Geräten die Lizenz genutzt wird
|
||
• Rechnername, Betriebssystem und Programmversion, damit Sie Ihre Geräte
|
||
im Kundenportal auseinanderhalten können
|
||
• der bei Ihnen installierte Stand, damit die Gegenstelle weiß, was neu ist
|
||
• technisch bedingt: Ihre IP-Adresse, Datum und Uhrzeit des Abrufs
|
||
|
||
Zweck: Bereitstellung der Aktualisierung und Prüfung der Lizenz.
|
||
|
||
Nicht übertragen werden Inhalte aus diesem Programm: keine Dokumente,
|
||
keine Datenbank, keine Eingaben. Die Verbindung ist verschlüsselt.
|
||
|
||
Regeln für die Umsetzung:
|
||
|
||
- Text sichtbar anzeigen, nicht hinter „Mehr erfahren" verstecken.
|
||
- Den Wortlaut übernehmen, nicht umschreiben. Er ist an dem ausgerichtet,
|
||
was die Endpunkte tatsächlich entgegennehmen.
|
||
- Sendet dein Client ein Feld NICHT – etwa keinen Rechnernamen –, streiche
|
||
die entsprechende Zeile. Ein Hinweis, der mehr aufzählt als geschieht, ist
|
||
genauso falsch wie einer, der etwas verschweigt.
|
||
- Ist in der Anwendung eine eigene Datenschutzerklärung hinterlegt, verweise zusätzlich dorthin.
|
||
- KEINEN Zustimmungshaken vor die Update-Prüfung setzen. Die Prüfung ist
|
||
zur Vertragserfüllung nötig; ein Haken suggeriert eine Freiwilligkeit,
|
||
die es nicht gibt, und blockiert im Zweifel die Auslieferung von
|
||
Sicherheitskorrekturen.
|
||
- Zugriffe auf die Update-Endpunkte werden serverseitig 400 Tage
|
||
aufbewahrt, danach gelöscht. Nenne die Zahl, wenn du eine ausführliche
|
||
Fassung baust.
|
||
|
||
## Sicherheits- und Robustheitsanforderungen (MÜSSEN erfüllt sein)
|
||
- Nur Administratoren dürfen prüfen, aktualisieren und den Kanal wechseln.
|
||
- ZIP-Slip-Schutz beim Entpacken, beide Stufen (s. o.).
|
||
- Geschützte Pfade werden nie überschrieben – kein Verlust von .env, Datenbank,
|
||
storage, hochgeladenen Dateien.
|
||
- Der Wartungsmodus ist selbstheilend und läuft nach maxSeconds von allein aus.
|
||
- Auto-Migration nur bei geändertem Fingerabdruck, mit Sperre gegen Parallellauf.
|
||
- Jeder Lauf, Erfolg wie Fehler, erzeugt einen Audit-Eintrag: Kanal, Ziel-SHA,
|
||
Anzahl Migrationen, auslösender Benutzer.
|
||
- Fehlermeldungen benennen die Ursache verständlich: Proxy nicht erreichbar,
|
||
Antwort ist kein ZIP, Datei nicht schreibbar (dann Schreibrechte nennen).
|
||
|
||
## Abnahmekriterien
|
||
Automatisierte Tests für:
|
||
- SHA lesen und schreiben, inklusive Ablehnung ungültiger Werte
|
||
- Wartungsmodus inklusive Selbstheilung nach Ablauf
|
||
- Fortschritts-Datei, inklusive Fehlerzustand
|
||
- ZIP-Slip: ein Archiv mit "../evil" darf NICHTS außerhalb des Staging anlegen
|
||
- geschützte Pfade werden beim Übernehmen übersprungen
|
||
- Migrationszähler
|
||
- Changelog-Parsing
|
||
- Lizenzfehler führen zu verständlichen Meldungen und blockieren NICHT die
|
||
Benutzung des Programms
|
||
- ein neu erhaltenes device_token wird gespeichert, auch wenn die Antwort
|
||
gleichzeitig einen Fehler meldet
|
||
|
||
Manueller Durchlauf: Kanal wählen → suchen → aktualisieren → Fortschritt bis
|
||
100 % → Version und Changelog aktualisiert → Wartungsseite verschwindet wieder.
|
||
|
||
Erkläre am Ende kurz, welche Dateien du angelegt hast und welche
|
||
Framework-Details du angepasst hast.
|
||
|
||
## Reihenfolge beim Einführen
|
||
Falls dieses Programm bisher ohne Lizenzprüfung aktualisiert hat, ist die
|
||
Reihenfolge wichtig – sonst stehen Kunden ohne Updates da:
|
||
|
||
1. Diese Client-Fassung ausliefern. Sie KANN Lizenzdaten senden, auch wenn
|
||
noch keine hinterlegt sind. Verteilen und abwarten.
|
||
2. Lizenzen im Hub anlegen und verteilen.
|
||
3. Die Lizenzen zunächst auf „nur protokollieren" stellen und ein paar Tage
|
||
beobachten, wer sich meldet.
|
||
4. Erst dann die Software auf „lizenzpflichtig" und die Lizenzen auf
|
||
„durchsetzen" umstellen.
|
||
|
||
Schritt 3 ist die Versicherung: Du siehst vorher, welche Installationen noch
|
||
nicht umgestellt sind – statt es hinterher am Telefon zu erfahren.
|