docs: document device registration status

architecture/08-provisioning-api.md

@@ -96,7 +96,7 @@ Bei erfolgreicher Aktivierung antwortet der Provisioning-Server mit dem registri
     "id": "<device-uuid>",
     "fingerprint": "<sha256>",
     "hostname": "enterprise",
-    "created": false,
+    "registration_status": "existing", 
     "hardware_snapshot_id": "<hardware-snapshot-uuid>"
   },
   "customer": {
@@ -123,7 +123,11 @@ Bei erfolgreicher Aktivierung antwortet der Provisioning-Server mit dem registri
 
 `device.id` ist die interne, von Hardwaremerkmalen unabhängige Geräte-ID.
 
-`device.created` gibt an, ob das Gerät während dieses Aktivierungsvorgangs neu registriert wurde.
+`device.registration_status` beschreibt den Registrierungszustand des Geräts für den aktuellen Aktivierungsvorgang.
+
+Der Wert `registered` bedeutet, dass im Bootstrap-Modell ein neues Device registriert wurde.
+
+Der Wert `existing` bedeutet, dass ein bereits bekanntes Device anhand seines Hardware-Fingerprints wiedererkannt wurde.
 
 `device.hardware_snapshot_id` referenziert den für diesen Aktivierungsvorgang erzeugten Hardware-Snapshot.
 

architecture/11-device-enrollment.md

@@ -0,0 +1,186 @@
+# Device Enrollment
+
+**Status:** Entwurf
+
+## Zweck
+
+Dieses Dokument beschreibt die Aufnahme eines Geräts in eine Tuxflotte-Organisation.
+
+Device Enrollment ist von der Authentifizierung eines Benutzers zu unterscheiden.
+
+Die Authentifizierung beantwortet die Frage:
+
+> Wer führt den Provisionierungsvorgang aus?
+
+Das Device Enrollment beantwortet die Frage:
+
+> Darf dieses Gerät einer Organisation hinzugefügt und im Rahmen ihres Gerätekontingents provisioniert werden?
+
+## Zielmodell
+
+Der reguläre Provisionierungsablauf verwendet keine gerätespezifischen Aktivierungscodes.
+
+Eine Organisation besitzt ein Gerätekontingent.
+
+Ein neues Gerät kann nach erfolgreicher Autorisierung einer Organisation hinzugefügt werden, wenn das verfügbare Gerätekontingent dies erlaubt.
+
+Der grundlegende Ablauf ist:
+
+```text
+Authentifizierung oder Enrollment-Autorisierung
+  ↓
+Organisation bestimmen
+  ↓
+Gerät anhand des Hardware-Fingerprints erkennen
+  ↓
+Gerät bekannt?
+  ├── ja
+  │    ↓
+  │  bestehendes Device verwenden
+  │    ↓
+  │  Reprovisionierung ermöglichen
+  │
+  └── nein
+       ↓
+     Gerätekontingent prüfen
+       ↓
+     Aufnahme des Geräts explizit bestätigen
+       ↓
+     neues Device registrieren
+```
+
+## Gerätekontingent
+
+Eine Organisation kann nur die Anzahl neuer Geräte registrieren, die ihr aktuelles Gerätekontingent erlaubt.
+
+Ein neues Device belegt einen Geräteslot.
+
+Die erneute Provisionierung eines bereits registrierten Devices belegt keinen zusätzlichen Geräteslot.
+
+Die Wiedererkennung eines bestehenden Devices erfolgt über den Hardware-Fingerprint.
+
+Die interne Device-ID bleibt unabhängig von Hardwaremerkmalen.
+
+## Interaktive Geräteaufnahme
+
+Für die Provisionierung einzelner Geräte authentifiziert sich ein berechtigter Benutzer.
+
+Nach erfolgreicher Authentifizierung zeigt Tuxflotte die erkannte Organisation und den Status des Geräts an.
+
+Bei einem unbekannten Gerät zeigt der Installer eine Zusammenfassung der erfassten Hardwareinformationen und das verfügbare Gerätekontingent an.
+
+Die Aufnahme des Geräts in die Organisation muss explizit bestätigt werden.
+
+Beispiel:
+
+```text
+Organisation: Muster GmbH
+
+Neues Gerät erkannt
+
+Hersteller: Lenovo
+Modell: ThinkPad T14
+CPU: AMD Ryzen 7 PRO
+RAM: 32 GB
+Speicher: 953 GB
+
+Verfügbares Gerätekontingent: 13
+
+Dieses Gerät zur Organisation „Muster GmbH“ hinzufügen?
+[j/N]
+```
+
+Die erfolgreiche Authentifizierung eines Benutzers allein registriert kein neues Gerät.
+
+## Bekannte Geräte
+
+Wird ein bereits registriertes Device anhand seines Hardware-Fingerprints wiedererkannt, verwendet Tuxflotte die bestehende Device-ID.
+
+Es wird kein zusätzlicher Geräteslot belegt.
+
+Der Installer kann dem Benutzer eine Reprovisionierung des bestehenden Geräts anbieten.
+
+Beispiel:
+
+```text
+Bekanntes Gerät erkannt
+
+Gerät: enterprise
+Organisation: Muster GmbH
+
+Gerät erneut provisionieren?
+[j/N]
+```
+
+## Enrollment Sessions
+
+Für Massenrollouts und Werkstattumgebungen kann eine Organisation zeitlich begrenzte Enrollment Sessions erstellen.
+
+Eine Enrollment Session kann insbesondere auf folgende Eigenschaften begrenzt werden:
+
+- Organisation,
+- Gültigkeitszeitraum,
+- maximale Anzahl neuer Geräte,
+- erlaubte Provisioning-Profile.
+
+Eine Enrollment Session ist widerrufbar und auditierbar.
+
+Beispiel:
+
+```text
+Provisioning Session
+
+Organisation: Muster GmbH
+Maximale neue Geräte: 50
+Gültigkeit: 8 Stunden
+
+Erlaubte Profile:
+- Fedora Workstation
+- Linux Mint Desktop
+```
+
+Der Installer kann neben der interaktiven Benutzeranmeldung die Verwendung einer Enrollment Session anbieten.
+
+```text
+Provisionierung starten
+
+1) Mit Benutzerkonto anmelden
+2) Enrollment Session verwenden
+```
+
+Enrollment Sessions dienen der effizienten Provisionierung größerer Gerätemengen, ohne an jedem Gerät vollständige Benutzeranmeldedaten und zusätzliche Authentifizierungsfaktoren eingeben zu müssen.
+
+## Abgrenzung zu Aktivierungscodes
+
+Der bisher verwendete Aktivierungscode ist ein Bootstrap-Mechanismus zum Aufbau und Nachweis des Provisioning-Handshakes.
+
+Er ist nicht Bestandteil des langfristigen Customer-UX-Modells.
+
+Insbesondere werden keine gerätespezifischen Aktivierungscodes als regulärer Provisionierungsmechanismus vorgesehen.
+
+Das Zielmodell trennt:
+
+```text
+Authentifizierung
+→ Wer führt den Vorgang aus?
+
+Enrollment-Autorisierung
+→ Darf ein Gerät aufgenommen werden?
+
+Gerätekontingent
+→ Ist ein weiterer Geräteslot verfügbar?
+
+Hardware-Fingerprint
+→ Ist das Gerät bereits bekannt?
+```
+
+Der bestehende Aktivierungscode wird schrittweise durch dieses Enrollment-Modell ersetzt.
+
+## Sicherheitsprinzip
+
+Weder eine erfolgreiche Authentifizierung noch die Kenntnis eines Hardware-Fingerprints allein berechtigt zur Registrierung eines neuen Devices.
+
+Die Aufnahme eines unbekannten Geräts erfordert eine gültige Enrollment-Autorisierung und ein verfügbares Gerätekontingent.
+
+Bei interaktiver Geräteaufnahme muss die Registrierung des neuen Devices explizit bestätigt werden.
+