ADR-0022: device_fingerprint lokal auf dem Geraet hinterlegt

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

adr/0022-device-fingerprint-lokal-hinterlegt.md

@@ -0,0 +1,46 @@
+# ADR-0022: Device-Fingerprint lokal auf dem Gerät hinterlegt
+
+**Status:** Beschlossen
+**Datum:** 28.08.2026
+
+## Kontext
+
+Beim Nachforschen, warum ein physisch installiertes Test-Notebook
+(`tuxflotte-mint-test`) in keiner Geräteliste auftauchte, stellte sich
+heraus: die Installation stammte aus der Zeit vor dem Mint-Backend
+(04.08.2026) bzw. vor dem WLAN-Zugangsdaten-Mechanismus (21.07.2026) — zu
+diesem Zeitpunkt gab es noch keinen Provisioning-Agent, die fehlende
+Registrierung war also erwartbar, kein Bug.
+
+Dabei kam aber eine echte Lücke ans Licht: `device_fingerprint` (SHA256 aus
+System-UUID, Seriennummern und MAC-Adressen, `10_hardware.sh:
+build_device_fingerprint()`) wird nur einmalig während des Live-Boots
+berechnet, an `/api/v1/activate` geschickt und danach **nirgends auf dem
+installierten Zielsystem hinterlegt**. Die Kundenplattform-Geräteliste
+zeigt ihn an (`geraete_liste.html`), aber steht man vor der physischen
+Maschine, gab es keine Möglichkeit, den angezeigten Wert gegenzuprüfen —
+Identifikation war nur in einer Richtung möglich.
+
+## Entscheidung
+
+Beide Backends (`backends/mint/backend.sh` + `postinstall.sh`,
+`backends/fedora/backend.sh` + `kickstart.tpl`) lesen den bereits während
+des Live-Boots berechneten Fingerprint jetzt zusätzlich aus der ohnehin
+vorhandenen `/run/tuxflotte/hardware/hardware.json` (`.identity.
+device_fingerprint`) — bewusst nicht aus der Serverantwort, die nur die
+zugewiesene `device_id` kennt, nicht den ursprünglichen Hardware-Hash.
+Wird per `envsubst` als neue Variable `TUXFLOTTE_DEVICE_FINGERPRINT` in
+den bestehenden Postinstall-/Kickstart-Renderpfad eingespeist (gleiches
+Muster wie `TUXFLOTTE_DEVICE_ID`/`TUXFLOTTE_BLUEPRINTS_JSON`) und landet
+in einer neuen Klartextdatei `/etc/tuxflotte/device_fingerprint` —
+bewusst ohne `chmod 0600` wie bei `agent.credentials`, da reiner
+Hardware-Hash ohne Geheimnischarakter.
+
+## Konsequenzen
+
+Kein Server-/Datenbankeingriff nötig — reine Installer-seitige Ergänzung,
+liest eine bereits vorhandene Datei erneut aus. Lokal verifiziert
+(`bash -n` auf dem mit Dummy-Werten `envsubst`-aufgelösten `%post`-Block
+bzw. zweistufig aufgelöstem `postinstall.sh`, keine unaufgelösten
+`${TUXFLOTTE_...}`-Platzhalter mehr). Volle Live-Verifikation folgt beim
+nächsten realen Geräte-Install im Rahmen des Self-Service-Flow-Tests.