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!
@@ -0,0 +1,18 @@
+# Deploymentcenter — AI Agent Integration Guides
+
+Willkommen in der Entwickler- und Agenten-Dokumentation von **Deploymentcenter**. 
+
+Diese Anleitungen sind speziell dafür strukturiert, KI-Agenten und Entwicklern klare, praxiserprobte Vorgaben zur Integration unserer zentralen Dienste bereitzustellen:
+
+- **[Lizenzsystem-Integration (Hardware-ID v2)](./LICENSE_INTEGRATION_GUIDE.md)**: Hardware-Anbindung, Lizenzschlüssel-Validierung, verschlüsselter Offline-Cache (`LLS2`), CLI-Befehle und Multi-Plattform-Betrieb (Windows & Linux / Docker).
+- **[Watchdog-Integration (Heartbeat & Telemetrie)](./WATCHDOG_INTEGRATION_GUIDE.md)**: Überwachung von Anwendungen, Diensten und Infrastruktur-Knoten via Ping-API, Agent-Tokens und automatisiertem Heartbeat.
+
+---
+
+## Modulübersicht
+
+| Modul | Hauptaufgabe | Endpunkte | .NET Client SDK |
+| :--- | :--- | :--- | :--- |
+| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache | `/api/license/v1/validate`<br>`/api/license/v1/deactivate` | `Deploymentcenter.Client` (`LicenseClient`, `HardwareId`) |
+| **Watchdog** | Heartbeat-Monitoring, Status & Alerting | `/api/watchdog/v1/ping` | `HttpClient` + Header `X-Agent-Token` |
+| **UpdateService** | Automatic Software Release Checks | `/api/updateservice/v1/check` | `HttpClient` GET Request |
@@ -0,0 +1,153 @@
+# Deploymentcenter — Watchdog Integration für KI-Agenten
+
+> **Zielgruppe**: KI-Agenten & Softwareentwickler  
+> **Zweck**: Einbindung von Heartbeat-Monitoring, Statusmeldungen und Telemetrie in Anwendungen & Serverdienste.
+
+---
+
+## 1. Übersicht
+
+Der **Watchdog** in Deploymentcenter überwacht kontinuierlich den Zustand von Hosts, Diensten, Cronjobs und Proxmox-Hypervisoren. 
+
+Anwendungen senden in regelmäßigen Abständen (standardmäßig alle 60 Sekunden) einen HTTP POST Ping an die Watchdog API. Ausbleibende Pings oder gemeldete Fehler erzeugen automatisch Warnungen im Admin-Dashboard.
+
+---
+
+## 2. API Endpunkt & Authentifizierung
+
+- **URL**: `POST https://dc.mhdf.de/api/watchdog/v1/ping`
+- **Content-Type**: `application/json`
+- **Header**: `X-Agent-Token: <dein_watchdog_agent_token>`
+
+### Request Body Schema (JSON)
+```json
+{
+  "source": "srv-db-01",
+  "instance": "default",
+  "type": "heartbeat",
+  "status": "ok",
+  "message": "Service running smoothly",
+  "interval": 60,
+  "group": "Infrastructure",
+  "os": "Ubuntu 24.04 LTS"
+}
+```
+
+#### Felder:
+- `source` *(string, erforderlich)*: Eindeutiger Name des Dienstes oder Hostnames (z.B. `srv-db-01` oder `PolyTrader Worker`).
+- `instance` *(string, optional)*: Instanzbezeichner (Standard: `default`).
+- `type` *(string)*: `heartbeat`, `host`, `hypervisor_node` oder `guest`.
+- `status` *(string)*: `ok`, `warning` oder `error`.
+- `message` *(string, optional)*: Status- oder Fehlermeldung.
+- `interval` *(int)*: Erwarteter Abstand in Sekunden zwischen zwei Pings (Standard: `60`).
+- `group` *(string, optional)*: Gruppierung im Dashboard (z.B. `Applications`, `Infrastructure`).
+- `os` *(string, optional)*: Betriebssystem-Name (z.B. `.NET 8 Service`, `Debian 12`).
+
+---
+
+## 3. Implementierungsbeispiele
+
+### 3.1 C# (.NET Core / .NET 8+)
+
+```csharp
+using System;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Tasks;
+
+public class WatchdogHeartbeatService
+{
+    private static readonly HttpClient Client = new HttpClient();
+    private static readonly string PingUrl = "https://dc.mhdf.de/api/watchdog/v1/ping";
+    private static readonly string Token = "wd_live_token_infra_01_secure";
+
+    public static async Task SendPingAsync(string sourceName, string status = "ok", string message = "Service active")
+    {
+        var payload = new
+        {
+            source = sourceName,
+            instance = "default",
+            type = "heartbeat",
+            status = status,
+            message = message,
+            interval = 60,
+            group = "Services",
+            os = Environment.OSVersion.ToString()
+        };
+
+        string json = JsonSerializer.Serialize(payload);
+        var request = new HttpRequestMessage(HttpMethod.Post, PingUrl)
+        {
+            Content = new StringContent(json, Encoding.UTF8, "application/json")
+        };
+        request.Headers.Add("X-Agent-Token", Token);
+
+        try
+        {
+            HttpResponseMessage response = await Client.SendAsync(request);
+            if (response.IsSuccessStatusCode)
+            {
+                Console.WriteLine("[✔] Watchdog Heartbeat erfolgreich gesendet.");
+            }
+        }
+        catch (Exception ex)
+        {
+            Console.WriteLine($"[✖] Watchdog Ping Fehlgeschlagen: {ex.Message}");
+        }
+    }
+}
+```
+
+### 3.2 Python 3
+
+```python
+import requests
+
+WATCHDOG_URL = "https://dc.mhdf.de/api/watchdog/v1/ping"
+AGENT_TOKEN = "wd_live_token_infra_01_secure"
+
+def send_heartbeat(source_name, status="ok", message="Python Background Task running"):
+    headers = {
+        "Content-Type": "application/json",
+        "X-Agent-Token": AGENT_TOKEN
+    }
+    payload = {
+        "source": source_name,
+        "instance": "default",
+        "type": "heartbeat",
+        "status": status,
+        "message": message,
+        "interval": 60,
+        "group": "Python Services"
+    }
+    try:
+        response = requests.post(WATCHDOG_URL, json=payload, headers=headers, timeout=10)
+        if response.status_code == 200:
+            print("[✔] Watchdog Ping OK")
+    except Exception as e:
+        print(f"[✖] Watchdog Ping Error: {e}")
+```
+
+### 3.3 Bash / Cronjob (Linux)
+
+```bash
+#!/usr/bin/env bash
+
+WATCHDOG_URL="https://dc.mhdf.de/api/watchdog/v1/ping"
+TOKEN="wd_live_token_infra_01_secure"
+SOURCE="$(hostname)"
+
+curl -s -X POST "$WATCHDOG_URL" \
+     -H "Content-Type: application/json" \
+     -H "X-Agent-Token: $TOKEN" \
+     -d '{"source": "'"$SOURCE"'", "status": "ok", "message": "Hourly Backup Task Completed", "interval": 3600}'
+```
+
+---
+
+## 4. Best Practices für KI-Agenten
+
+1. **Heartbeat-Schleife**: Lasse in eigenständigen Hoster-Diensten einen periodischen Timer (z.B. `System.Threading.Timer` oder `BackgroundService`) alle 60s `SendPingAsync` aufrufen.
+2. **Graceful Shutdown**: Sende beim Beenden des Dienstes einen Ping mit Status `stopped` oder `maintenance`.
+3. **Fehlerbehandlung**: Fange Netzwerkfehler bei Watchdog-Pings stets stumm/abgefangen ab, damit der Ausfall des Monitoring-Servers niemals den Hauptanwendungsfluss unterbricht.