kundencenter/docs/connector-lizenzsystem.md
Claude (KI) f5c689a6ad Kundenangaben an Lizenzen nachziehen und auf Wunsch leeren (#64)
- 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>
2026-10-06 13:11:46 +02:00

6.9 KiB
Raw Permalink Blame History

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).