# DESKTOP-1 · Electron-Client produktionsreif fertigstellen | Feld | Wert | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Typ** | Dev (Desktop / Release) | | **Owner** | Raffael | | **Phase** | Nachzug außerhalb der aktuellen v1/v2-Kernkette | | **Cycle/Fenster** | Backlog · bewusst später | | **Status** | Backlog · Prototyp 6/12 DoD = 50 % done | | **Plane** | [HIVEGRID-249](https://project.tool-ctrl.de/toolctrl/projects/35d0d968-8ab3-40cc-97b8-b81d917dc5df/issues/64897557-907f-4f7c-8431-0fe352ab66df) | ## Entscheidung und aktueller Kontext Der User hat am 2026-08-03 einen ersten Desktop-Prototyp für macOS, Windows und Linux ausdrücklich beauftragt und anschließend entschieden, die Produktionsreife als Backlog-Nachzug zu parken. Der Desktop-Client bleibt eine dünne Electron-Hülle um die bestehende HiveGrid-Web-App. Es entsteht keine zweite UI-, Fachlogik-, Auth- oder Datenschicht. Die Desktop-Entscheidung ist im lokalen Prototyp-Branch als **AD-33** vorbereitet. Sie ändert **AD-17 nicht**: Mobile bleibt responsive Web/PWA-only. Vor einem Code-Merge müssen der AD-33-Eintrag und die zugehörige operative Klarstellung in `AGENTS.md` gemeinsam mit dem Desktop-Paket geprüft und übernommen werden. Damit wird die noch auf `main` vorhandene allgemeine Anti-Listen-Formulierung nicht stillschweigend durch diese Ticket-Doc gelockert. **Wichtig:** Der Prototyp-Branch und seine Commits existieren zum Zeitpunkt dieser Doc nur lokal und wurden noch nicht gepusht. - Worktree: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-feat-desktop-client-prototype` - Branch: `feat/desktop-client-prototype` - Basis: `origin/main@b1f14d63e5252e0a70029ece139591b98e26d3b8` - Paket-Dokumentation im Prototyp-Branch: `apps/desktop/README.md` - Lokale Build-Artefakte: `artifacts/desktop/` (gitignored) ## Abhängigkeiten & Parallelität - **blocked-by:** Keine Plane- oder Ticket-Abhängigkeit hinterlegt. - **blocks:** Keine Plane- oder Ticket-Abhängigkeit hinterlegt. - **Externe Voraussetzungen vor Release:** Apple Developer ID und Notarisierungszugang, Windows-Authenticode-Zertifikat sowie ausführbare macOS-/Windows-/Linux-Release-Runner oder gleichwertige kontrollierte Build-Maschinen. Verfügbarkeit und Owner werden beim Wiederaufnehmen geprüft; sie sind aktuell nicht als formale Plane-Blocker modelliert. - Die Arbeit ist unabhängig von Prisma, RLS, Entity Model und der fachlichen v1/v2-Kernkette. Es gibt keine Schema- oder Migrationsänderung. - Web-App, Auth und fachliche Screens bleiben alleinige Produktquelle. Änderungen an diesen Flächen gehören in ihre jeweiligen Tickets, nicht in `DESKTOP-1`. - Mobile und App-Store-Scope bleiben außerhalb dieses Tickets. Desktop-Store- Distribution darf nur nach eigener Produktentscheidung ergänzt werden. ## Was wir bauen Der vorhandene Prototyp wird zu einem reproduzierbar veröffentlichten, signierten und updatefähigen Desktop-Client für: - macOS Apple Silicon und Intel, - Windows x64, - Linux x64. Der Client lädt ausschließlich die freigegebene HiveGrid-Web-Origin. Native Zuständigkeit bleibt auf sicheren Web-Container, Lifecycle, Single Instance, Fensterzustand, Menüs, Deep Links, Badge, Offline-Fallback und Updates begrenzt. Der Produktionsnachzug umfasst außerdem: - native Signierung, Notarisierung und installierbare Paketformate, - reproduzierbare Gitea-Release-Jobs auf den Zielplattformen, - unveränderliche Release-Artefakte und Prüfsummen, - einen signierten Update-Kanal mit echtem Upgrade-/Rollback-Drill, - native Smoke-Tests auf allen Zielbetriebssystemen, - Installations-, Release- und Rollback-Dokumentation. ## Benötigte Screens Keine neue Fach- oder Subframe-Oberfläche. Die bestehende Web-App bleibt die vollständige sichtbare Produktsurface. Native beziehungsweise lokale Systemflächen sind auf Folgendes begrenzt: | Fläche | Inhalt | | ---------------- | ---------------------------------------------------------------------- | | App-Menü | Zurück/Vorwärts, Reload, Zoom, Vollbild, Update-Prüfung, Hilfe | | Offline-Fallback | Klartextstatus, Ziel-Origin und erneuter Verbindungsversuch | | Update-Dialog | Update verfügbar, Downloadstatus, Neustart jetzt/später | | Betriebssystem | Installer, Signatur-/Notarisierungsdialoge und Deep-Link-Registrierung | Die finale Web-Optik wird nicht im Electron-Paket dupliziert. Es gibt keinen `design-nachzug` und keinen eigenen Subframe-Screen für dieses Ticket. ## Definition of Done - [x] **Dünne Sicherheitsarchitektur:** `apps/desktop` lädt nur die bestehende Web-App; Node-Integration und Webviews sind aus, Context Isolation, Sandbox, Web Security, enge Navigation und validierte Preload-IPC sind aktiv. AD-17 bleibt für Mobile unverändert. - [x] **Native Desktop-Grundfunktionen:** Single Instance, Fensterzustand, native Menüs, Deep Links, Badge, sichere externe Links und Offline-Fallback sind implementiert. - [x] **Vier reproduzierbare Prototyp-Builds:** macOS arm64/x64, Windows x64 und Linux x64 werden aus demselben Workspace gebaut; ASAR-Integrität, gehärtete Electron-Fuses und HiveGrid-Branding sind enthalten. - [x] **Update-Grundlage fail-closed:** macOS/Windows verwenden Electrons `autoUpdater`, Linux einen manuellen Downloadpfad; ohne konfigurierte Release-URL bleiben automatische Updates deaktiviert. Öffentliche URLs sind build-time einbettbar und zur Laufzeit überschreibbar. - [x] **Automatisierte Qualität:** Desktop-Typecheck, Unit-Tests, Build und echter Electron-E2E sind vorhanden; Root-Docker- und Gitea-CI-Verträge berücksichtigen das Workspace-Paket. - [x] **Lokaler macOS-Proof:** Der finale arm64-Prototyp startet nativ, stellt das App-Menü bereit und beendet sich über den normalen App-Lifecycle; Binärformat, ZIP-Integrität, lokale Signatur und Fuses sind geprüft. - [ ] **Branch gesichert und integriert:** Der lokale Prototyp-Branch ist gepusht, per PR geprüft und mit normalem Merge-Commit in `main` integriert; AD-33, `AGENTS.md` und diese Ticket-Doc sind widerspruchsfrei. - [ ] **Echte Zielsystem-Smokes:** Installation, Start, Login, Session-Restore, Navigation, Deep Link, Offline-Fallback und Deinstallation sind auf Windows x64 und Linux x64 sowie erneut auf einem produktionssignierten macOS-Build geprüft. - [ ] **Produktionspakete signiert:** macOS besitzt Developer-ID-Signatur und Notarisierung; Windows besitzt Authenticode und einen update-kompatiblen Installer; Linux besitzt mindestens AppImage sowie die entschiedenen DEB-/RPM-Pakete. Keine produktive Warnung wird durch Test-Flags umgangen. - [ ] **Release-Automation:** Native Gitea-Runner bauen aus einem Tag unveränderliche Artefakte, veröffentlichen SHA-256-Prüfsummen und hängen sie an einen versionierten Gitea-Release. Secrets bleiben ausschließlich im jeweiligen Runner-/Signing-Kontext. - [ ] **Update- und Rollback-Drill:** Ein signierter Build aktualisiert sich über den veröffentlichten Kanal auf die nächste Version; Feed, Signatur, Neustart, fehlgeschlagener Download und Rückkehr zum letzten freigegebenen Artefakt sind auf macOS und Windows bewiesen. Linux folgt dem dokumentierten Paketmanager-/Downloadpfad. - [ ] **Release-Abnahme:** Security-Review, Lizenz-/SBOM-Prüfung, Installations-, Release- und Rollback-Runbook sowie abschließender UAT sind dokumentiert; Ticket-Doc und Plane enthalten den Proof. **Fortschritt: 6/12 DoD = 50 % done · 6 Punkte offen · aktuell keine formale `blocked-by`-Kante; das Ticket ist bewusst zurückgestellt.** ## DoD-Proof und Nicht-genug-Kriterien | DoD | Fertigkeitskriterium | Proof | Zählt nicht als fertig | | --- | --------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------ | | 1 | Sicherheitsoptionen und IPC-Grenze im Release-Build aktiv | Unit-/E2E-Test und Fuse-Ausgabe | nur ein `BrowserWindow`, das eine URL lädt | | 2 | Alle begrenzten nativen Flows funktionieren | Desktop-Tests und manueller Smoke | Menüpunkte ohne funktionalen Handler | | 3 | vier portable Test-Bundles reproduzierbar | Paketbefehle, `file`, `unzip -t`, Fuses | nur der Host-Mac-Build | | 4 | kein Feed führt sicher zu deaktivierten Updates | Unit-Test und Status-API | ungeprüfte oder hartkodierte Download-URL | | 5 | Desktop ist Teil der lokalen/CI-Qualitätsverträge | grüne fokussierte Tests und CI-Verifier | nur ein lokaler manueller Start | | 6 | finaler arm64-Build startet und beendet sauber | nativer macOS-Smoke | nur Dev-Electron über Playwright | | 7 | Commits sind remote geprüft und normal gemerged | PR, grüne CI, Merge-Commit | lokaler Branch oder Squash-Merge | | 8 | Nutzerflows laufen auf echten Zielsystemen | UAT-Protokoll je OS | Cross-Packaging auf macOS | | 9 | OS-Vertrauenskette und Installer sind produktiv | Signatur-, Notarisierungs- und Installer-Proof | ad-hoc signiertes ZIP | | 10 | Tag erzeugt veröffentlichte immutable Releases | grüner Release-Run, Assets, Prüfsummen | manuell erzeugtes `artifacts/`-Verzeichnis | | 11 | echtes N→N+1-Update und Rollback bewiesen | Feed-/Installer-/Rollback-Protokoll | Unit-Test des Update-Controllers | | 12 | Übergabe ist operativ vollständig | Review, SBOM, Runbooks, UAT-Sign-off | README ohne ausgeführten Release-Proof | ## Technische Bausteine - `apps/desktop/src/main.ts`: Lifecycle und gehärtetes `BrowserWindow`. - `apps/desktop/src/preload.ts` und `ipc.ts`: kleine, validierte Native-Bridge. - `apps/desktop/src/url-policy.ts`: Trusted-Origin-, Deep-Link- und External-Navigation-Vertrag. - `apps/desktop/src/updates.ts` und `update-settings.ts`: Update-Modi, Statusmodell und öffentliche Release-Konfiguration. - `apps/desktop/scripts/build.mjs`: deterministischer Main-/Preload-Build. - `apps/desktop/scripts/package.mjs`: Plattformpakete, Branding, ASAR, Signatur-Hook und Fuses. - `apps/desktop/scripts/e2e.mjs`: echter Electron-E2E gegen einen lokalen Testserver. - `scripts/ci/run-quality-groups.sh`: Desktop-Qualitätsgruppe nach den bestehenden bounded Core-Gruppen. Öffentliche Konfiguration: - `HIVEGRID_DESKTOP_WEB_URL`: Ziel-Web-App; im Paket nur HTTPS. - `HIVEGRID_DESKTOP_UPDATE_URL`: macOS-/Windows-Update-Feed. - `HIVEGRID_DESKTOP_DOWNLOAD_URL`: manueller Linux-/Fallback-Download. - `HIVEGRID_DESKTOP_MAC_SIGN_IDENTITY`: macOS-Signing-Identität beim Build. Keine Signing-Zertifikate, Passwörter, PATs oder Update-Secrets werden in Git, Plane, Build-Logs oder Artefakt-Metadaten geschrieben. ## Vorhandener Prototyp-Proof (2026-08-03) Atomare lokale Commits: 1. `0e7c8e906` · `feat(desktop): add secure Electron shell` 2. `df496a297` · `feat(desktop): add native lifecycle and updates` 3. `5c5cc3af3` · `build(desktop): package branded cross-platform clients` 4. `6d9f322c8` · `feat(desktop): embed public update configuration` 5. `006d319f2` · `ci(desktop): enforce client quality gates` 6. `8b9071fa3` · `docs(desktop): record client release contract` 7. `1f66d3562` · `fix(desktop): guard shutdown navigation race` Prüfstand: - `pnpm typecheck` und `pnpm lint` grün. - `pnpm test`: 1.194 Testdateien und 8.325 Tests grün; 60 bewusst deaktivierte Integrationstests übersprungen. - Desktop: 44/44 Unit-Tests, Typecheck, Build und echter Electron-E2E auf macOS arm64 grün. - Alle vier ZIPs bestehen `unzip -t`; Binärformate sind Mach-O arm64/x64, PE32+ x64 und ELF x64. - Beide Mac-Prototypen bestehen die lokale ad-hoc-Signaturprüfung; alle vier Builds besitzen die erwarteten gehärteten Fuses. - Der native Mac-Smoke nutzte für den wiederholt ad-hoc signierten lokalen Build Chromiums isolierten Test-Keychain. Das ist kein Release-Flag und darf in produktiven Startpfaden nicht verwendet werden; eine stabile Developer-ID- Signatur muss den regulären Keychain-Pfad beweisen. Lokale SHA-256-Prüfsummen des letzten Prototyp-Builds: - macOS arm64: `252bb76b248a378106a8f7e071a61cd806cc1e8928589c50ec3a82a9d5edc3b1` - macOS x64: `05c23c17db3a051fab472bc54507158ccd2a7d7dba775884f2ca36781d8c6137` - Linux x64: `3fd15c50439750f9b8bb1f8b97c449e46d6002855770d16dc5169284d8d61be1` - Windows x64: `1ccb839161f66c00511b02c8e658b51b5a5429fd69f6eb22769648bbf4ca04ea` Die Prüfsummen sind nur lokaler Proof. Sie werden nicht als veröffentlichter Release-Vertrag behandelt, weil `artifacts/desktop/` gitignored ist. ## Verifikation vor Commit, Push und Release Fokussiert: ```bash pnpm --filter @hivegrid/desktop typecheck pnpm --filter @hivegrid/desktop test pnpm --filter @hivegrid/desktop build pnpm --filter @hivegrid/desktop test:e2e ``` Vor Push/PR zusätzlich die vollständige `docs/AGENT-CHECKLIST.md` und alle betroffenen CI-/Docker-Verifier. Vor Release außerdem: - ZIP-/Installer-Integrität und SHA-256, - Fuse- und ASAR-Integritätsprüfung, - native Signatur- und Notarisierungsprüfung, - SBOM-/Lizenz- und Production-Audit, - echter Installations-/Update-/Rollback-Smoke je Zielbetriebssystem. ## Rollback - Vor dem Merge: den Desktop-PR schließen; die bestehende Web-App bleibt unverändert nutzbar. - Nach dem Merge ohne Release: die Desktop-Commits normal reverten. Es gibt keine Datenbankmigration und keinen serverseitigen Zustand zurückzusetzen. - Nach Release: Update-Feed auf das letzte freigegebene, weiterhin signierte Artefakt zurücksetzen und dieses erneut als aktuelle Version veröffentlichen. Bereits installierte Clients werden nicht durch Löschen alter Assets unbrauchbar gemacht. - Zertifikate oder Secrets werden nur nach ausdrücklichem Auftrag rotiert. ## Quellen - Plane: `HIVEGRID-249` / `DESKTOP-1`. - User-Auftrag und ausdrückliche Desktop-Freigabe vom 2026-08-03. - Lokaler Branch `feat/desktop-client-prototype`, insbesondere `apps/desktop/README.md` und der dort vorbereitete AD-33-Nachzug. - `AGENTS.md` · Arbeitsmodus, Ticket-Treue, Desktop-/Mobile-Grenzen und operative Checkliste. - [Electron Security](https://www.electronjs.org/docs/latest/tutorial/security) - [Electron Updates](https://www.electronjs.org/docs/latest/tutorial/updates) - [Electron Distribution](https://www.electronjs.org/docs/latest/tutorial/application-distribution) - [Electron Code Signing](https://www.electronjs.org/docs/latest/tutorial/code-signing) ## Umsetzungs-Notiz ### 2026-08-03 · Prototyp gebaut und Produktionsnachzug geparkt Der sichere Desktop-Prototyp wurde in sieben atomaren lokalen Commits erstellt, für vier Plattform-/Architekturziele paketiert und auf macOS arm64 automatisiert sowie nativ geprüft. Plane-Ticket `HIVEGRID-249` wurde im Backlog mit Priorität Low und Owner Raffael angelegt. Der User hat entschieden, die Produktionsreife erst nach anderen Aufgaben fortzusetzen. **DESKTOP-1: 6/12 DoD = 50 % done · 6 Punkte offen · 0 formale Plane-Blocker · bewusst zurückgestellt.**