# Integration mit der Universal License Platform

## Verantwortungsgrenze

Die AI-Disclosure-Anwendung ist ausschließlich ein Lizenz-Client. Die Universal License Platform ist die einzige Autorität für:

- Schlüsselverwaltung;
- Produkterfassung;
- Lizenzausstellung;
- Token-Registry;
- Widerruf und Reaktivierung;
- Onlineprüfung;
- Signierung kurzlebiger Leases;
- Audit- und Benutzerverwaltung.

Das Hauptprojekt enthält keine dieser Funktionen.

## Produkt in der Plattform anlegen

Verwende als unveränderliche Produkt-ID:

```text
ai-disclosure-standard
```

Die aktuell ausgewerteten Feature-IDs sind:

| Feature | Wirkung |
|---|---|
| `custom_text` | eigener Titel und eigener Erklärungstext |
| `custom_badge` | eigene Badge-Beschriftungen und Farben |
| `white_label` | reserviert für markenneutrale Ausgaben |

Unbekannte Features werden vom Produkt ignoriert und können für andere Produkte weiterverwendet werden.

## Trust Store installieren

Die Plattform liefert unter folgendem Endpunkt ausschließlich öffentliche Schlüssel:

```text
GET /api/v1/trust-store
```

Die Antwort muss vor dem Produkt-Build als folgende Datei gespeichert werden:

```text
internal/app/trusted_keys.json
```

Erwartetes Format:

```json
{
  "licenseKeys": {
    "issuer-2026": "PUBLIC_KEY_BASE64URL"
  },
  "leaseKeys": {
    "lease-2026": "PUBLIC_KEY_BASE64URL"
  }
}
```

Anschließend muss das Produkt neu kompiliert beziehungsweise das Container-Image neu gebaut werden. Der Trust Store ist absichtlich nicht per Umgebungsvariable konfigurierbar.

## Runtime-Konfiguration

Minimal für Offline-Lizenzen:

```env
LICENSE_TOKEN=...
LICENSE_MODE=offline
```

Hybrid:

```env
LICENSE_TOKEN=...
LICENSE_MODE=hybrid
LICENSE_CACHE_FILE=/data/license-lease.json
LICENSE_REFRESH_INTERVAL=15m
LICENSE_REQUEST_TIMEOUT=5s
```

Online:

```env
LICENSE_TOKEN=...
LICENSE_MODE=online
LICENSE_REQUEST_TIMEOUT=5s
```

Optional:

```env
LICENSE_SERVER_URL=https://licenses.example.org
LICENSE_INSTANCE_ID=production-eu-1
```

Die in der Lizenz signierte `verification.serverUrl` wird automatisch erkannt. Die Auflösungsreihenfolge ist:

1. `licenseclient.Config.ServerURL` beziehungsweise `LICENSE_SERVER_URL`;
2. signierte `verification.serverUrl` aus dem Lizenz-Token;
3. `/.well-known/license-server` auf der Produkt-Basis-URL.

## Onlineprotokoll

Der Client sendet an:

```text
POST /api/v1/licenses/validate
```

Anfrage:

```json
{
  "token": "...",
  "product": "ai-disclosure-standard",
  "baseUrl": "https://ai.example.org",
  "host": "ai.example.org",
  "instanceId": "production-eu-1",
  "clientVersion": "2.0.2"
}
```

Erwartete Antwort:

```json
{
  "valid": true,
  "leaseToken": "..."
}
```

Der Lease-Token wird erneut lokal gegen die eingebetteten Lease-Public-Keys geprüft. Eine bloße positive JSON-Antwort ohne gültige Signatur schaltet keine Funktionen frei.

## Domain- und Instanzbindung

Die Plattform kann Lizenzen binden an:

```text
example.org
*.example.org
*
```

`*` erlaubt alle Domains. `*.example.org` erlaubt nur echte Subdomains und nicht automatisch `example.org` selbst.

Instanz-IDs funktionieren entsprechend. Ist eine Lizenz an Instanzen gebunden, muss `LICENSE_INSTANCE_ID` gesetzt sein.

## Schlüsselrotation

1. In der Universal License Platform einen neuen Issuer- oder Lease-Key aktivieren.
2. Einen Trust Store herunterladen, der alten und neuen Public Key enthält.
3. Das Produkt mit beiden Schlüsseln neu bauen und ausrollen.
4. Neue Lizenzen beziehungsweise Leases mit dem neuen Key ausstellen.
5. Den alten Public Key erst entfernen, wenn alle damit signierten Tokens abgelaufen oder ersetzt sind.

## Client-Snapshot

Unter `third_party/license-platform-client` liegt eine client-only, protokollkompatible Momentaufnahme des Go-SDK aus Universal License Platform v1.0.0. Sie enthält nur:

- öffentliche Protokolltypen;
- Trust-Store-Parsing;
- Ed25519-Verifikation;
- Kontext-, Domain- und Instanzprüfung;
- Offline-/Hybrid-/Online-Client;
- signierten Lease-Cache.

Private-Key-Handling, Signierfunktionen, Admin-Server und Persistenz wurden bewusst nicht übernommen.

Sobald das eigenständige Modul über einen stabilen Go-Modul-Tag erreichbar ist, kann in `go.mod` der lokale `replace`-Eintrag entfernt und direkt die veröffentlichte SDK-Version verwendet werden.

## Capabilities used by 2.0

```text
custom_text
custom_badge
white_label
bulk_api
export_bundle
```

The optional numeric limit `bulk_items` caps the number of items accepted by a single Bulk API request. The application always applies the stricter value of the runtime configuration and the signed licence limit.

For an official deployment that must fail closed when the licence is unavailable, set:

```env
REQUIRE_LICENSE=true
```

This affects both readiness and ordinary application requests. Liveness, readiness, metrics and capability inspection remain available for operations and diagnosis.