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.
@@ -20,13 +20,14 @@ Vor Version 2.1.0 enthielt das Repository keinen Installer für die C#-Anwendung
 - Stabile Fehlercodes, vollständige Self-Test-Ausgaben, Exception-Ketten, HRESULTs und einzeln protokollierte Rollbackschritte.
 - Explizite Unterscheidung zwischen Fehlern vor der ersten Mutation und tatsächlich ausgeführtem Rollback.
 - Rücklesende Verifikation von Verknüpfungen, Uninstaller und zentralen Registrywerten.
+- Explizite optionale Exception-Grenze für sämtliche Zugriffe auf den gemeinsamen Desktop-Link; Startmenü, Uninstaller und Registry bleiben transaktionskritisch.
 - Deinstallation über Windows-Uninstall-Eintrag; Diagnoseprotokolle bleiben erhalten.
 - Äußere ZIP-Prüfsumme und Certutil-kompatible Base64-TXT für kontrollierte Übertragung.

 ## Lokal verifiziert

 - Release-Build aller Projekte mit Mono MSBuild.
- Neunundzwanzig Regressionstests einschließlich manipulierter/zusätzlicher/ausbrechender Payload-Pfade, Staging-Abbruch ohne Mutation, transienter Move-Erholung, verifiziertem Neuinstallations- und Updatefallback, begrenztem Updateabbruch, erzwungenem Fehler des zweiten Self-Tests mit Wiederherstellung der Vorversion, Deinstallation über ein Quarantäneverzeichnis, Diagnosekontext, Log-Fallback und Fehlerisolierung der UI-Ausgabe.
+- Dreißig Regressionstests einschließlich manipulierter/zusätzlicher/ausbrechender Payload-Pfade, Staging-Abbruch ohne Mutation, transienter Move-Erholung, verifiziertem Neuinstallations- und Updatefallback, begrenztem Updateabbruch, erzwungenem Fehler des zweiten Self-Tests mit Wiederherstellung der Vorversion, Deinstallation über ein Quarantäneverzeichnis, Diagnosekontext, Log-Fallback sowie Fehlerisolierung der UI- und optionalen Desktop-Ausgabe.
 - WMI-freier Self-Test der produktiven EXE.
 - Erstellung des Installationsordners, ZIPs, Base64-TXTs und der SHA-256-Datei.
 - Rückdekodierung der Base64-TXT und Bytevergleich mit dem ZIP.
@@ -43,10 +43,10 @@ Zwei neue Failure-Injection-Regressionstests belegen den erfolgreichen Updatefal

 1. Die 2.1.2-Datei nicht erneut starten.
 2. Screenshot und vollständiges `setup-*.log` aus `%ProgramData%\BizTalkPlatformManagementTool\InstallerLogs` als Vorfallevidenz sichern.
-3. `artifacts\BizTalkPlatformManagementTool-Setup.zip.b64.txt` aus Version 2.2.3 mit `certutil -decode` rekonstruieren.
+3. `artifacts\BizTalkPlatformManagementTool-Setup.zip.b64.txt` aus Version 2.2.4 mit `certutil -decode` rekonstruieren.
 4. Den SHA-256 des ZIPs mit `BizTalkPlatformManagementTool-Setup.zip.sha256.txt` vergleichen.
-5. Das ZIP in einen neuen Ordner entpacken und die dortige `Setup.exe` starten. Der Fenstertitel muss `2.2.3` zeigen.
-6. Im Erfolgslog `setup_version=2.2.3.0` und `activation_method=atomic_move` oder `activation_method=verified_copy_fallback` prüfen. Beim Fallback muss zusätzlich `scope=new_install` oder `scope=update_after_backup` protokolliert sein.
+5. Das ZIP in einen neuen Ordner entpacken und die dortige `Setup.exe` starten. Der Fenstertitel muss `2.2.4` zeigen.
+6. Im Erfolgslog `setup_version=2.2.4.0` und `activation_method=atomic_move` oder `activation_method=verified_copy_fallback` prüfen. Beim Fallback muss zusätzlich `scope=new_install` oder `scope=update_after_backup` protokolliert sein.
 7. Danach in der Anwendung zuerst **Diagnose** und anschließend mit aktiviertem **Dry run** den vorgesehenen Betriebsablauf prüfen.

 Eine Windows-/BizTalk-/EDR-Abnahme in PROD bleibt erforderlich; die lokale Mono-Suite kann reale ACLs, Endpoint-Schutz, Registry und Verknüpfungen nicht simulieren.