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](./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

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