Deploymentcenter/docs/LICENSE_INTEGRATION_GUIDE.md

Deploymentcenter — Lizenzsystem Integration für KI-Agenten

Zielgruppe: KI-Agenten & Softwareentwickler Gültig ab: Hardware-ID v2, Deploymentcenter 2.0 Plattformen: Windows, Linux (inkl. systemd und Docker), macOS

⚠️ Änderungen in Version 2.0

• /api/license/v1/validate bleibt unverändert und ohne Token erreichbar. Ausgelieferte Clients laufen ohne Anpassung weiter.
• /api/license/v1/deactivate verlangt weiterhin Authentifizierung — aber mit dem neu erzeugten shared_key. Der alte Wert lag im Repository und wurde ersetzt; wer ihn irgendwo eingetragen hat, muss nachziehen.
• Die Signatur der Offline-Lizenzdateien heißt jetzt ehrlich HMAC-SHA256 statt irreführend ED25519_SIG_. Der frühere „Server Public Key" im WebUI war frei erfunden und wurde entfernt.

Umstellungsschritte: UPGRADE.md

---

0. Antwortformat — bitte beachten

Die Lizenz-Endpunkte antworten ohne den status/error-Umschlag der übrigen Deploymentcenter-API. Das Feld status auf oberster Ebene trägt den Lizenzzustand:

{
  "type":            "validation_result",
  "status":          "valid",
  "issued_at":       1786435199,
  "expires_at":      1817971199,
  "cache_ttl_hours": 168,
  "hardware_id":     "2:win:a765bd47...",
  "license_key":     "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
  "nonce":           "der übergebene Wert",
  "endpoints":       { "validate": "/api/license/v1/validate",
                       "deactivate": "/api/license/v1/deactivate" },
  "message":         "License is valid"
}

status	Bedeutung
valid	Lizenz gültig, Aktivierung eingetragen
not_found	Projekt oder Schlüssel unbekannt
revoked	Lizenz widerrufen oder diese Hardware gesperrt
suspended	Lizenz vorübergehend ausgesetzt
expired	Ablaufdatum überschritten
activation_limit	Maximale Anzahl Aktivierungen erreicht

Diese Sonderstellung ist bewusst: Ein Umschlag mit status: "success" würde von jedem bestehenden Client als „nicht valid" gelesen — sämtliche Lizenzen gälten schlagartig als ungültig. Wer eine eigene Anbindung schreibt, muss status also von der obersten Ebene lesen, nicht aus einem result-Objekt.

---

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

Deaktivierung braucht Authentifizierung

/api/license/v1/deactivate gibt einen Aktivierungsplatz frei und ist deshalb geschützt — sonst könnte jeder fremde Installationen abmelden. Der Aufruf verlangt den shared_key aus config/config.php:

// Der Schlüssel gehört auf den Administrationsrechner, nicht in die
// ausgelieferte Anwendung.
var client = new LicenseClient();
bool released = await client.DeactivateAsync(
    productSlug: "myapp",
    licenseKey:  "LLAB1-98A72-B3C4D-5E6F7-89012",
    serverBaseUrl: "https://dc.mhdf.de",
    authToken:   Environment.GetEnvironmentVariable("DC_SHARED_KEY"));

curl -X POST https://dc.mhdf.de/api/license/v1/deactivate \
  -H "Authorization: Bearer $DC_SHARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"myapp","license_key":"XXXXX-...","hardware_id":"2:win:a765..."}'

Alternativ genügt für Einzelfälle der Knopf Freigeben in der Hardware-Liste des WebUI — das ist der übliche Weg und braucht keinen Schlüssel im Feld.

Was passiert bei Ratenbegrenzung

/validate ist auf 120 Anfragen pro Minute und IP begrenzt. Darüber kommt 429 mit {"status":"error","error":{"code":"rate_limited"}} — hier greift ausnahmsweise das Umschlagformat, weil die Drosselung vor der Lizenzlogik zuschlägt. Ein Client sollte in dem Fall den lokalen Cache verwenden und es später erneut versuchen, statt die Anwendung zu blockieren.

---

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!