- SDK: optionale Connector-Methode updateCustomerInfo (Capability
license.customer_info), null = personenbezogene Felder leeren.
- Lizenz-Connector: PUT /licenses/{id} mit customer_name/_contact/_email/
_reference (Zielwerte, wiederholbar); Herkunftsfelder werden nie gesendet;
ohne Anbieter-Fähigkeit oder licenses:write klar UNSUPPORTED.
- Auftrag customer.provider_sync: nach Änderung des Kundennamens bzw. Name/
E-Mail des Inhabers automatisch; Endpunkt + Knöpfe für Abgleich und
Löschanspruch. Audit nur mit Zählern, keine Personendaten.
Tests: Connector (Werte, Leeren, Ablehnungen), Verdrahtung + Überspringen.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.9 KiB
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 nur gemäß Rechten (#43): Mit Service-Token zählen die in der Verbindung eingetragenen Scopes (Feld „Scopes des Service-Tokens“ – das Lizenzsystem bietet keine Introspektion; ohne Eintrag ist die Verbindung nur lesend): licenses:suspend → sperren/entsperren, licenses:extend → verlängern, licenses:write → anlegen, licenses:read → Schlüssel anzeigen, licenses:revoke → widerrufen (terminate, destruktiv). Mit Benutzer/Passwort (Lizenzsystem-Benutzer = alle Rechte) wie bisher ohne Widerruf. Ein 403 (fehlender Scope) wird als „fehlendes Recht“ gemeldet und nicht als Anmeldefehler; nur 401 löst beim Altweg eine erneute Anmeldung aus. Lebenszyklus-Aufrufe senden Idempotency-Key: kc:<Auftrags-ID>. Health prüft /ready (Fallback /).
3. Endpunkte, die das Kundencenter nutzt
| Methode/Pfad | Zweck | Wo |
|---|---|---|
GET /ready (Fallback GET /) |
Health inkl. Datenbank | Connector |
GET / |
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: kc:<Auftrags-ID>) |
Connector (lifecycle, Widerruf = terminate), 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):
{ "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; Änderungen (Kundenname, Inhaber-Name/-E-Mail) werden per Auftrag customer.provider_sync nachgezogen, Löschanspruch leert Name/Ansprechpartner/E-Mail/Kundennummer (PUT /licenses/{id}, #64). Unveränderlich beim Anbieter und bewusst nicht gelöscht: Quelle, Bestell- und Vertragsnummer (keine direkten Personendaten; Aufbewahrung) |
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).