Connector-Doku Lizenzsystem aus dem aktuellen Code (#3)

Authentisierung (Service-Token vs. Altweg), Fähigkeitserkennung über
features, alle genutzten Endpunkte mit Zweck, Fehlerabbildung, anonymisiertes
Beispiel der Normalisierung, alte Lückenliste mit heutigem Stand (erledigt /
konkret offen: Service-Token live #60, Scopes→Capabilities #43, Kundendaten-
Sync #64, Source-Abgleich #114).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Claude (KI) 2026-10-06 12:14:27 +02:00
parent 87e2a2038b
commit b397c3e3bf

View file

@ -0,0 +1,76 @@
# Connector: Lizenzsystem (licensing.flessinglabs.com)
Stand: 06.10.2026, abgeleitet aus `packages/connector-licensing/src/index.ts` (Ressourcen-Connector) und `src/admin.ts` (Lizenzverwaltung im Kundencenter). Ersetzt die alte Bestandsanalyse von 26.09. (deren Lückenliste ist überholt, siehe Abschnitt 5). Für die **eigene** Lizenz der Installation (FLS1-signierte `/license/verify`-Antworten) siehe `packages/platform/src/license.ts` und `docs/sicherheit-und-bedrohungsmodell.md` (T16).
## 1. Verbindung und Authentisierung
| Feld | Bedeutung |
|---|---|
| `baseUrl` | z. B. `http://127.0.0.1:8001` (Lizenzsystem auf demselben Server) |
| `token` (Secret) | **empfohlen:** Service-Token, Header `Authorization: Bearer …`, kein Login nötig |
| `username`/`password` (Secret, Altweg) | Login über `POST /token` (Form), JWT 20 min im Speicher gecacht, bei 401 einmal neu angemeldet |
| `timezone` | nur für ältere Lizenzsysteme ohne `utc_timestamps` |
Benötigte Scopes eines Service-Tokens (laut Verwaltungs-Client): `programs:read`, `products:read`, `licenses:read`, `licenses:write` (anlegen, ändern, Lebenszyklus, Entitlement, Trial) und `activations:reset` (Aktivierung freigeben). `revoke` nur, wenn Lizenzen aus dem Kundencenter widerrufen werden sollen. Die aktive Live-Verbindung nutzt noch Benutzer/Passwort (Stand Codex-Prüfung 06.10.) → Umstellung #60/#43.
## 2. Fähigkeitserkennung
`GET /` liefert `features` (60 s gecacht). Der Connector schaltet abhängig davon frei:
| Feature | Wirkung im Connector |
|---|---|
| `utc_timestamps` | Zeiten werden als UTC gelesen/geschrieben (sonst Umrechnung aus der konfigurierten Ortszeit) |
| `lifecycle` | sperren/entsperren/verlängern über eigene Endpunkte (`POST /licenses/{id}/{action}`), sonst Altweg `PUT /licenses/{id}` |
| `key_prefix` | Edition per Schlüssel-Präfix (Altmodell; neu: Produkt-ID, #63) |
| `explicit_expiry` | festes Ablaufdatum bei Anlage |
| `customer_info` | Kundenkontext bei Anlage (Name, E-Mail, Kontakt, Kundennummer, Bestell-/Vertragsnummer, Quelle „Kundencenter“) |
`capabilities()`: Lesen immer; Schreiben (`lifecycle.*`, `secret.reveal`) derzeit, sobald Zugangsdaten vorhanden sind. **Offen (#43):** Fähigkeiten aus den tatsächlich erlaubten Token-Scopes ableiten.
## 3. Endpunkte, die das Kundencenter nutzt
| Methode/Pfad | Zweck | Wo |
|---|---|---|
| `GET /` | Health + Features | Connector |
| `POST /token` | Login (Altweg) | Connector, Verwaltung |
| `GET /programs/?limit=1000` | Programme (Namen) | Katalog, Abgleich, Anlage |
| `GET /products/groups` | Produktkatalog (Gruppen → Produkte, Preis, Dauer, Module, Plan, Kundengrenze, Add-ons) | Katalogimport, Vergabe |
| `GET /licenses/?limit=1000` | Abgleich aller Lizenzen | Connector `listResources` |
| `GET /licenses/{id}` | Detail, Schlüssel nur für `reveal` | Connector, Verwaltung |
| `GET /licenses/{id}/activations` | Aktivierungen | Verwaltung |
| `DELETE /licenses/{id}/activations/{aid}` | Aktivierung freigeben | Verwaltung |
| `POST /licenses/` | Lizenz anlegen (Programm, Produkt, Nutzer-Grenze, Dauer, Kundenkontext) | Bereitstellung, Verwaltung |
| `POST /licenses/trials` | Trial vergeben | Verwaltung |
| `PUT /licenses/{id}` | Felder ändern (Altweg sperren/verlängern) | Connector, Verwaltung |
| `POST /licenses/{id}/{suspend\|unsuspend\|extend\|revoke}` | Lebenszyklus, `Idempotency-Key` | Connector (`lifecycle`), Verwaltung |
| `POST /licenses/{id}/entitlement` | Plan/Module/Kundengrenze setzen (Entitlement-Version) | Verwaltung |
Fehlerabbildung (`admin.ts`): 401/403 → `AUTH_FAILED`, 404 → `NOT_FOUND`, 409 → `CONFLICT`, 400/422 → `INVALID_INPUT` (Text aus `detail`), 429 → `RATE_LIMITED`, sonst `UPSTREAM_ERROR`; Zeitüberschreitung 15 s → `TIMEOUT`.
## 4. Abbildung auf den Ressourcen-Vertrag (anonymisiertes Beispiel)
Rohdaten (gekürzt, Werte erfunden):
```json
{ "id": 4711, "program_id": 3, "product_id": 12, "license_key": "PREMIUM-XXXX-…", "user_limit": 5, "duration_type": "YEAR",
"starts_at": "2026-01-10T09:00:00Z", "expires_at": "2027-01-10T09:00:00Z", "is_active": true, "status": "active",
"plan_key": "premium", "modules": ["backup"], "customer_limit": null, "activations": [{ "hardware_id": "abcd…", "activated_at": "…", "last_seen_at": "…" }] }
```
Normalisiert (`mapLicense`): `externalRef = "4711"`, `type = license`, Name = Programm + Produkt + **maskierter** Schlüssel (`PREM…XXXX`), `state` = `suspended` (inaktiv/gesperrt/widerrufen/blockiert) | `expired` (Status oder Ablauf < jetzt) | `active`, `validFrom/validUntil` in UTC, `limits.users`, Details (Programm, Produkt, Plan, Module, Kundengrenze, Add-on-Kennzeichen, Trial, Aktivierungen mit maskierter Hardware-ID). Der Klartext-Schlüssel wird nie gespeichert, nur auf Abruf (`reveal`, berechtigt, auditiert) angezeigt.
## 5. Alte Lückenliste (26.09.) – Stand heute
| Lücke damals | Stand |
|---|---|
| GET /programs und /licenses ohne Authentisierung (Schlüssel lesbar) | behoben im Lizenzsystem (Auth Pflicht), Schlüssel rotiert (26.09.) |
| Dienst als root auf 0.0.0.0 | behoben (systemd-Dienst mit eigenem Benutzer, nur 127.0.0.1, gehärtet) |
| CORS `*` | im aktuellen Licensing-Source zu prüfen (#114) – hier nicht belegt |
| Keine Health-Route | `/health`, `/ready` vorhanden |
| Kein Service-Token | Service-Tokens mit Scopes vorhanden – **Live-Verbindung noch nicht umgestellt** (#60) |
| Sperren/Verlängern nur per PUT, Laufzeit approximiert | Lebenszyklus-Endpunkte mit Idempotenz, explizites Ablaufdatum |
| Eine Aktivierung je Lizenz | mehrere Aktivierungen (Aktivierungslimit), Freigabe einzeln |
| Naive Ortszeit | `utc_timestamps` |
| Keine Kundendaten am Provider | `customer_info` bei Anlage; Änderung/Löschung danach offen (#64) |
Abnahme gegen den aktuellen Licensing-Source (Schema-/Endpunktvergleich) erst nach dem Abgleich Server ↔ Forge (#114). Testabdeckung im KC: `packages/connector-licensing/test` (18 Tests, gegen nachgebildete Antworten; keine echten Schlüssel in Fixtures).