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

```json
{
  "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

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

### 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`:

```csharp
// 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"));
```

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