Deploymentcenter/docs/LICENSE_INTEGRATION_GUIDE.md

Deploymentcenter — Lizenzsystem Integration für KI-Agenten

⚠️ Geändert in Version 2.0 — /api/license/v1/validate bleibt unverändert und ohne Token erreichbar. /api/license/v1/deactivate verlangt weiterhin Authentifizierung, allerdings mit dem neu erzeugten shared_key: der alte Wert lag im Repository und wurde ersetzt. Die Signatur der Offline-Lizenzdateien ist jetzt ein ehrlich benanntes HMAC-SHA256 statt der irreführenden Bezeichnung ED25519_SIG_. Umstellungsschritte: UPGRADE.md.

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

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:

# 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!