feat(license): implement Hardware-ID v2, multi-platform Linux support, StateStore LLS2 hardening, and AI Agent docs

2026-08-06 11:39:21 +02:00
parent e9dbe793e2
commit 70b35f7b8b
16 changed files with 1602 additions and 41 deletions
@@ -0,0 +1,125 @@
+# Deploymentcenter — Lizenzsystem Integration für KI-Agenten
+
+> **Zielgruppe**: KI-Agenten & Softwareentwickler  
+> **Gültig ab**: Hardware-ID v2 Specification (August 2026)  
+> **Plattformen**: Windows, Linux (inkl. systemd Services & Docker-Container), macOS
+
+---
+
+## 1. Architektur & Konzepte
+
+Das Lizenzsystem von Deploymentcenter schützt Anwendungen über eine Kombination aus serverseitiger Validierung, plattformunabhängiger Hardware-ID v2 und einem gehärteten lokalen Cache (`LLS2` format with AES-GCM encryption).
+
+### 1.1 Hardware-ID v2 Format
+Format: `2:<plattform>:<64-Hex-Zeichen>`
+
+Beispiele:
+- `2:win:9f3ab7c1...` (Windows, `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid`)
+- `2:lin:41e0d5aa...` (Linux, `/etc/machine-id`)
+- `2:lin:7c9182ff...` (Linux/Container via Umgebungsvariable `DEPLOYMENTCENTER_HWID`)
+
+### 1.2 Hash-Berechnung (KEIN MachineName im Hash)
+`sha256("LicenseLabrador-HWID-v2" + "\n" + plattform + "\n" + quelle + "\n" + rohwert)`
+
+> **WICHTIG**: Der Rechnername steckt **nicht** im Hash. Ein Umbenennen der Maschine verändert die Hardware-ID nicht und verbraucht keine zusätzlichen Aktivierungsplätze.
+
+### 1.3 Quellen-Priorisierung je Plattform
+
+#### Windows:
+1. `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid` (`machine-guid`)
+2. Verkettete physische MAC-Adressen (`mac`)
+3. Erzeugte Schlüsseldatei `machine.key` im StorageDirectory (`keyfile`)
+
+#### Linux:
+1. `/etc/machine-id` (`machine-id`) — muss plausibel sein (Länge >= 16, nicht `uninitialized`, nicht nur Nullen).
+2. `/var/lib/dbus/machine-id` (`dbus-machine-id`)
+3. `/sys/class/dmi/id/product_uuid` (`dmi-uuid`)
+4. Verkettete physische MAC-Adressen (`mac`)
+5. Erzeugte Schlüsseldatei `machine.key` (`keyfile`)
+
+#### Container / Headless Overrides:
+Wenn `DEPLOYMENTCENTER_HWID` oder `LICENSELABRADOR_HWID` gesetzt ist, gewinnt diese Variable Plattform-weit (`override`).
+
+---
+
+## 2. Einbindung in C# (.NET Core / .NET 8+)
+
+Verwende das NuGet-Paket/Projekt `Deploymentcenter.Client` (Multi-Targeting `netstandard2.0;net8.0`).
+
+### 2.1 Initialisierung und Standard-Validierung
+
+```csharp
+using System;
+using System.Threading.Tasks;
+using Deploymentcenter.Client;
+
+public class Program
+{
+    private static readonly string ServerUrl = "https://dc.mhdf.de";
+    private static readonly string ProductSlug = "myapp"; // In dc_projects hinterlegter Slug
+
+    public static async Task Main(string[] args)
+    {
+        // 1. CLI Schalter für Headless/Admin-Operationen abfangen
+        if (args.Length > 0 && args[0] == "--license-status")
+        {
+            var hwInfo = HardwareId.GetHardwareId(ProductSlug);
+            Console.WriteLine($"HWID v2: {hwInfo.HardwareId} ({hwInfo.HwidSource})");
+            return;
+        }
+
+        // 2. LicenseClient instanziieren
+        var client = new LicenseClient();
+        string licenseKey = "LLAB1-98A72-B3C4D-5E6F7-89012";
+
+        // 3. Online-Validierung durchführen
+        LicenseValidationResult res = await client.ValidateAsync(ProductSlug, licenseKey, ServerUrl);
+
+        if (res.IsValid)
+        {
+            Console.WriteLine($"[✔] Lizenz gültig! (Status: {res.Status}, Cached: {res.IsCached})");
+        }
+        else
+        {
+            Console.WriteLine($"[✖] Lizenz ungültig: {res.Message}");
+            Environment.Exit(1);
+        }
+    }
+}
+```
+
+---
+
+## 3. Zustandsspeicher (`StateStore.cs`) & Cache-Härtung
+
+- **Format**: File Envelope mit Magic `"LLS2"`, 12-Byte Nonce, AES-256-GCM Ciphertext und 16-Byte GCM Tag.
+- **Schlüsselableitung**: HKDF-SHA256 aus `HardwareId` + `ProductSlug`.
+- **Windows**: DPAPI-Zusatzhülle um AES-GCM Payload.
+- **Linux**: Dateirechte `0600` (`chmod 600 state.dat`).
+- **Sicherheitsvorgabe**: Kein Klartext-Rückfall! Beschädigte oder manipulierte Cache-Dateien werden strikt als Cache-Fehltreffer behandelt.
+
+---
+
+## 4. Kopfloser Betrieb (Headless Services / systemd)
+
+Für Hintergrunddienste (ohne GUI) stehen folgende CLI-Schalter am Anwendungshost zur Verfügung:
+
+```bash
+# Status der Hardware-ID und des lokalen Caches ausgeben
+my-service --license-status
+
+# Lizenzschlüssel festlegen & aktivieren
+my-service --license-set-key LLAB1-98A72-B3C4D-5E6F7-89012
+
+# Aktivierung für diesen Host aufheben (Freigabe am Server)
+my-service --license-deactivate
+```
+
+---
+
+## 5. Migration v1 → v2 ohne Platzverlust
+
+Wenn ein bestehender Windows-Client auf Hardware-ID v2 aktualisiert wird:
+- Der Client schickt `hardware_id` (v2) **und** `legacy_hardware_id` (v1) mit.
+- Der Server findet die alte Aktivierung unter `legacy_hardware_id` und zieht den Datenbank-Eintrag lautlos auf v2 um.
+- Es wird kein zusätzlicher Aktivierungsplatz verbraucht!