Lizenzdatei

Jedes CLI-Archiv, das im Kundenportal heruntergeladen wird, kann eine Datei mit dem Namen codecharter.license enthalten. Sie ist ein signiertes JWS-Token und bindet den Download an den Kunden, der ihn ausgelöst hat. Ohne gültige Lizenz weigert sich die CLI zu starten und beendet sich mit Exit-Code 6.

Mit Lizenz oder ohne Lizenz herunterladen

Auf der Downloads-Seite findet ihr pro Asset zwei Buttons:

• Download with license liefert das Archiv mit eurer persönlichen codecharter.license bereits eingebettet. Das ist die schnellste Variante und reicht aus, solange dasselbe Konto sowohl den Download als auch die CI-Workflows verantwortet.
• Without license liefert das generische, kunden-agnostische Archiv ohne eingebettete Lizenz. Sinnvoll, wenn ihr in eurer CI/CD-Pipeline die Lizenz separat aus einem Secret-Store mountet, einen internen Mirror pflegt oder den Build deterministisch von einer Customer-Identität trennen wollt.

Beide Varianten erfordern ein aktives Abonnement. Der Unterschied liegt ausschließlich darin, ob die Lizenz im Archiv enthalten ist; die Inhalte des CLI selbst sind identisch.

Wo die CLI nach der Lizenz sucht

Die CLI prüft folgende Pfade in dieser Reihenfolge und nimmt die erste Datei, die existiert:

1. Der Pfad, der per --license <pfad> übergeben wurde.
2. Die Umgebungsvariable CODECHARTER_LICENSE.
3. codecharter.license direkt neben dem CLI-Binary.
4. codecharter.license im aktuellen Arbeitsverzeichnis.
5. $XDG_CONFIG_HOME/codecharter/codecharter.license (Linux/macOS).
6. %APPDATA%\CodeCharter\codecharter.license (Windows).
7. $HOME/.config/codecharter/codecharter.license (Fallback für Unix-Systeme ohne XDG_CONFIG_HOME).

Die einfachste Variante: die codecharter.license aus dem heruntergeladenen Archiv neben das CLI-Binary kopieren. Damit funktionieren alle Aufrufe ohne weitere Konfiguration.

Automatische Erneuerung in der CI (API-Key)

In der CI lädst du normalerweise gar keine Lizenz herunter. Stattdessen hinterlegst du deinen Portal-API-Key als CI-Secret (CODECHARTER_API_KEY). Beim Start stellt die CLI daraus eine kurzlebige Lizenz aus (standardmäßig 24h) und cacht sie im benutzereigenen Konfigverzeichnis (Pfad 5/6/7 oben), wobei sie kurz vor Ablauf automatisch erneuert wird. Es gibt keinen Daemon und nichts zu planen: ein frischer Runner holt sich eine Lizenz, ein langlebiger Runner erneuert nur, wenn die gecachte Lizenz unter eine Stunde Restlaufzeit fällt.

So bleibt der API-Key das einzige langlebige Geheimnis. Eine geleakte gecachte Lizenz läuft innerhalb von 24h von selbst ab, und ein Widerruf des Keys im Portal deaktiviert jede daraus abgeleitete Lizenz im selben Fenster, ganz ohne Schlüsselrotation.

Die Erneuerung authentifiziert sich ausschließlich über den API-Key. Die vorhandene Lizenzdatei wird nie an das Portal zurückgeschickt, eine geleakte codecharter.license kann also nicht für eine neue Lizenz verwendet werden.

Ist das Portal kurz nicht erreichbar, während eine noch gültige Lizenz gecacht ist, nutzt die CLI diese weiter bis sie wirklich abläuft (Fail-open) und gibt eine Warnung aus, damit ein kurzer Netzausfall den Build nicht abbricht.

Zwei Overrides werden immer respektiert und von der Erneuerung nie angefasst: ein per --license übergebener Pfad und die Umgebungsvariable CODECHARTER_LICENSE. Damit kannst du eine bestimmte Datei festnageln, die CLI schreibt nur in den verwalteten Cache-Ort.

Offline- oder Dauer-Runner

Ein Runner ohne Zugriff auf codecharter.tools kann nicht erneuern. Gib ihm stattdessen eine vollständige codecharter.license aus dem Portal (herunterladen, dann auf einen der Suchpfade legen oder CODECHARTER_LICENSE darauf zeigen lassen). Da eine vollständige Lizenz ein weit entferntes Ablaufdatum trägt, bleibt sie deutlich über dem Erneuerungs-Schwellwert und der API-Key-Pfad wird nie betreten. Die CLI entscheidet rein anhand der Restlaufzeit, nicht anhand der Herkunft der Lizenz.

Was geprüft wird

Beim Start jedes gateten Subbefehls (analyze, validate, init, lsp) führt die CLI folgende Checks durch:

• Die Datei kann gelesen werden.
• Der Inhalt ist ein gültiges JWS-Token mit alg: RS256.
• Die Signatur passt zu einem der im Binary eingebetteten öffentlichen Schlüssel. Während einer Schlüsselrotation kennt das Binary mehrere Schlüssel parallel.
• Das exp-Claim (Ablaufdatum) liegt in der Zukunft (Toleranz von fünf Minuten gegen Uhrabweichungen).
• Optionale min_ver/max_ver-Claims schließen die laufende CLI-Version nicht aus.

Schlägt einer dieser Checks fehl, beendet sich die CLI mit Exit-Code 6 und schreibt eine kurze Diagnose auf stderr.

Häufige Fehlermeldungen

No codecharter.license file found

Keine der Suchpfade enthielt eine Lizenzdatei. Lade das aktuelle Archiv aus dem Portal neu herunter und kopiere codecharter.license neben das CLI-Binary, oder setze CODECHARTER_LICENSE auf den Pfad zur Datei.

License at '<pfad>' is not a valid JWS

Die Datei wurde gefunden, ist aber keine gültige JWS-Struktur. Mögliche Ursachen sind eine versehentlich überschriebene Datei, ein Zeilenende-Umbau durch ein Versionierungssystem oder eine Datei aus einer sehr alten Portal-Version. Lade die Lizenz neu aus dem Portal.

License at '<pfad>' is not signed by a key this CLI trusts

Das Token ist syntaktisch sauber, aber von einem Schlüssel signiert, den diese CLI nicht kennt. Tritt typischerweise bei einem Mismatch zwischen einer Lizenz aus einer alten Portal-Generation und einer aktuelleren CLI auf. Lösung: die aktuelle CLI-Version aus dem Portal neu ziehen.

License expired on <datum>

Das Token ist signaturseitig in Ordnung, aber das Ablaufdatum aus der Subscription ist überschritten. Verlängere die Subscription im Portal und lade danach das Archiv erneut herunter.

License requires CLI >= <version> / License only covers CLI <= <version>

Die Lizenz wurde mit einer Versionsklammer ausgestellt, die diese CLI nicht einschließt. Tritt nur auf, wenn das Portal mit Portal__License__DefaultMinVersion oder DefaultMaxVersion arbeitet. Lösung: Lizenz im Portal neu erzeugen, oder eine CLI-Version innerhalb der Klammer verwenden.

Datenschutz

Die Prüfung läuft komplett offline. Es findet kein Phone-Home statt, die CLI braucht keinen Netzwerkzugriff, um die Lizenz zu validieren. Die Signatur ist ausreichend.

Im Token stehen: User-ID (UUID), Account-Email, Plan-Name, Ausstellungs- und Ablaufdatum. Diese Werte sind für den Lizenznehmer ohnehin offensicht- lich; sie sind kein Geheimnis, sondern der Anker der Lizenz selbst.