Isolate optional desktop shortcut failures

2026-08-24 13:02:58 +02:00
parent 3219c3f1bc
commit 3b4a621cd3
16 changed files with 311 additions and 45 deletions
@@ -0,0 +1,56 @@
+# Optionale Desktop-Verknüpfung für alle Benutzer
+
+## Befund
+
+Bis Version 2.2.3 war die Option **Desktop-Verknüpfung für alle Benutzer erstellen** standardmäßig aktiviert. Der Installer verwaltet den Link über Windows Script Host im von `Environment.SpecialFolder.CommonDesktopDirectory` gelieferten gemeinsamen Desktop-Verzeichnis, üblicherweise `%PUBLIC%\Desktop`.
+
+Obwohl der Link fachlich optional war, lagen alle Zugriffe innerhalb der transaktionskritischen Windows-Integrationsphase. Eine `UnauthorizedAccessException`, COM-/WSH-Exception oder Zustandsabweichung konnte daher nach bereits erfolgreicher Payload-Aktivierung einen `SETUP-WINDOWS-INTEGRATION`-Fehler und den vollständigen Rollback auslösen. Betroffen waren nicht nur das Erstellen, sondern fünf Pfade:
+
+1. Lesen des vorhandenen Links für den Rollback-Snapshot.
+2. Erstellen oder Entfernen entsprechend der Setup-Auswahl.
+3. Rücklesende Validierung des gewünschten Zustands.
+4. Wiederherstellung des vorherigen Links während eines Rollbacks.
+5. Entfernen und Prüfen bei der Deinstallation.
+
+Der konkrete Berechtigungsgeber kann erst anhand des vollständigen `setup-*.log`, der effektiven ACL und gegebenenfalls EDR-Ereignisse bestimmt werden. Unabhängig davon war die bisherige Kritikalität für eine reine Komfortfunktion zu hoch.
+
+## Fix in Version 2.2.4
+
+- Die Desktop-Option ist standardmäßig abgewählt und muss bewusst aktiviert werden.
+- Alle fünf Desktop-Pfade laufen über eine gemeinsame optionale Exception-Grenze.
+- Jeder Fehler wird mit Exceptiontyp, HRESULT, Stacktrace, Rolle und Pfad als `optional_windows_integration_warning` protokolliert.
+- Die Setup-Oberfläche zeigt eine Warnung und erklärt ausdrücklich, dass die Kerninstallation fortgesetzt wird.
+- Auch eine Exception der Warnungsweiterleitung wird isoliert und als `optional_windows_integration_report_failed` protokolliert.
+- Ein Desktop-Snapshot, der wegen fehlender Rechte nicht gelesen werden konnte, wird beim späteren Rollback nicht erfunden oder überschrieben.
+- Ein fehlgeschlagener Desktop-Zugriff bei der Deinstallation kann einen alten Link zurücklassen, verhindert aber nicht die Entfernung der Anwendung.
+
+Der Installer ändert keine ACLs, übernimmt keinen Besitz und umgeht keine Sicherheitsrichtlinie. Die Sicherheitsentscheidung des Systems bleibt bestehen; lediglich die optionale Verknüpfung wird aus der Kerntransaktion entfernt.
+
+## Weiterhin verpflichtende Integration
+
+Diese Bestandteile bleiben transaktionskritisch:
+
+- Startmenü-Verknüpfung für alle Benutzer,
+- Uninstaller unter `%ProgramData%\BizTalkPlatformManagementTool\Setup`,
+- Uninstall-Eintrag unter `HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall`.
+
+Ein Fehler dieser Elemente verhindert weiterhin einen inkonsistenten Erfolg und löst bei Installation oder Update den Rollback aus.
+
+## Diagnose und Abnahme
+
+Bei nicht angeforderter oder erfolgreicher Desktop-Operation enthält das Log `event=optional_windows_integration_completed`. Bei einem tolerierten Fehler enthält es:
+
+```text
+event=optional_windows_integration_warning role=desktop_shortcut_... path="..." exception_type=... hresult=...
+event=setup_completed result=success_with_optional_desktop_shortcut_warning optional_desktop_shortcut_warning=True
+```
+
+Für die Windows-Abnahme:
+
+1. Setup 2.2.4 zunächst mit abgewählter Desktop-Option installieren oder aktualisieren.
+2. `setup_version=2.2.4.0`, erfolgreichen Kernabschluss, Startmenü-Link, Uninstaller und Registry prüfen.
+3. Die Option in einem weiteren Update gezielt aktivieren. Wird der gemeinsame Desktop blockiert, muss das Setup mit Warnung erfolgreich bleiben und die Anwendung startbar sein.
+4. Danach **Diagnose** und einen Dry-run ausführen.
+5. Deinstallation separat prüfen; ein nicht löschbarer optionaler Desktop-Link darf höchstens als Warnung verbleiben.
+
+Die portable Regressionstestsuite injiziert einen ACL-Fehler, eine Validierungsabweichung und einen fehlerhaften Warnungs-Sink. Reale `%PUBLIC%\Desktop`-ACLs, WSH/COM, Endpoint-Schutz und Gruppenrichtlinien bleiben auf Windows zu validieren.