VianoBugAnalysis/docs/integration-keys.md

Integrationsschlüssel

Angemeldete Webnutzer finden unter API-Schlüssel eine eigene Verwaltungsseite. Programmname und mindestens ein Projekt auswählen, dann den Schlüssel erstellen. Anzeigen ruft ihn bei Bedarf erneut ab; Verbergen entfernt ihn aus dem Eingabefeld. Kopieren verwendet die Zwischenablage (HTTPS oder localhost). Widerrufen sperrt ihn sofort für nachfolgende API-Anfragen. Bereits laufende Anfragen werden dadurch nicht abgebrochen. Ein widerrufener Schlüssel wird nicht mehr angezeigt; für einen Ersatz einen neuen Schlüssel erstellen.

Alle angemeldeten menschlichen Nutzer haben dieselben Verwaltungsrechte. Maschinenzugänge können weder Schlüssel verwalten noch andere Schlüssel anzeigen. Webmutationen einschließlich Anzeigen benötigen die vorhandene CSRF-Absicherung.

Das aufrufende Programm sendet Authorization: Bearer <Schlüssel> an die Übergabe-API. Neue Schlüssel erlauben Auftragsübergabe einschließlich Rückgaben und lesenden Zugriff auf die ausgewählten Projekte. Sie erlauben keine Betriebssteuerung oder Beantwortung menschlicher Testanfragen. Zugriff auf weitere Projekte erfordert einen neuen Schlüssel. Bestehende env-basierte Integrationen bleiben unverändert nutzbar und erscheinen nicht in der SQLite-Schlüsselliste.

Speicherung und Sicherung

• SQLite unter <workspace>/runtime/integrations/keys.sqlite3 speichert Metadaten, SHA-256-Prüfwerte und mit Fernet authentifiziert verschlüsselte Schlüssel.
• Der separate Serverschlüssel entsteht beim ersten Erstellen automatisch unter <workspace>/runtime/integration-secrets/master.key, Dateimodus 0600. Nutzerkonten und ihre root-verwaltete SQLite-Datei werden nicht verändert.
• Mit VIANO_INTEGRATION_KEY_FILE kann die API stattdessen eine separate Schlüsseldatei verwenden. Vorhandene Dateien müssen einen gültigen Fernet-Key enthalten und für den API-Dienst lesbar sein; fehlt die Datei beim ersten Erstellen, muss der Dienst sie im gewählten Verzeichnis anlegen dürfen.
• SQLite und Serverschlüssel getrennt geschützt sichern. Das Laufzeitverzeichnis enthält damit dauerhaft notwendige Integrationsdaten und darf bei einer Bereinigung von Sessions nicht pauschal gelöscht werden. Unter Windows passende Dateisystem-ACLs verwenden; POSIX-Modusbits ersetzen dort keine ACLs.
• Geht der Serverschlüssel verloren oder wird er unpassend ausgetauscht, können Schlüssel nicht mehr angezeigt werden. Das System ersetzt ihn bei bestehenden Einträgen nicht stillschweigend. Vorhandene Schlüssel können anhand ihrer Prüfwerte weiterhin authentifiziert und über die Weboberfläche widerrufen werden. Zur Wiederherstellung die richtige Schlüsseldatei aus der Sicherung zurückspielen.

Nach einem Update die API-Abhängigkeiten neu installieren (.[api] umfasst jetzt cryptography) und den API-Dienst neu starten. Eine Datenbankmigration per Hand ist nicht nötig. Keine Änderung oder Neueingabe des Gemini-Schlüssels erforderlich.