Authentifizierung

Cuby unterstützt mehrere Authentifizierungsmethoden. Die Auth-Funktion wird über die Umgebungsvariable USE_AUTH aktiviert.

Methoden

Methode	Verwendung	Ablauf
API Key (Bearer)	Server-zu-Server	`Authorization: Bearer {apiKey}` Header
Session Cookie	Browser	`cuby_session` Cookie, 24h gültig, HttpOnly, SameSite=None
PostMessage Token	iframe-Embedding	Kurzlebiger Token (60s), einmalige Verwendung

Auth-Endpunkte

Method	Endpunkt	Beschreibung
POST	`/api/auth`	Direkter Login: API Key → Session Cookie
POST	`/api/auth/token`	Token erstellen: API Key → kurzlebiger Auth-Token (60s)
POST	`/api/auth/session`	Token einlösen: Auth-Token → Session Cookie

Öffentliche Endpunkte (kein Auth nötig)

/api/health
/api/auth/*

Alle anderen Endpunkte sind geschützt, wenn USE_AUTH aktiviert ist.

Bearer-Authentifizierung

Für Server-zu-Server-Kommunikation wird der API Key als Bearer Token mitgesendet:


curl -H "Authorization: Bearer DEIN_API_KEY" http://localhost:3847/api/config

Session-Authentifizierung

Für Browser-Zugriff wird der API Key einmalig gegen ein Session Cookie getauscht:


# Login → Session Cookie erhalten
curl -X POST http://localhost:3847/api/auth \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "DEIN_API_KEY"}' \
  -c cookies.txt
 
# Weitere Requests mit Cookie
curl http://localhost:3847/api/config -b cookies.txt

Das Cookie cuby_session ist:

24 Stunden gültig
HttpOnly — nicht per JavaScript auslesbar
SameSite=None — ermöglicht Cross-Origin-Zugriff für iframe-Embedding

PostMessage-Authentifizierung

Für die Studio-Integration wird ein zweistufiger Token-Austausch über window.postMessage verwendet:

Studio ruft POST /api/auth/token mit apiKey auf → erhält kurzlebigen Token
Studio sendet window.postMessage({type: 'cuby:auth', token}) an das iframe
iframe-Hook empfängt Token → POST /api/auth/session
Server setzt cuby_session Cookie → alle weiteren Requests sind authentifiziert

Socket.IO-Authentifizierung

Socket.IO-Verbindungen werden über zwei Wege authentifiziert:

socket.handshake.auth.apiKey — API Key direkt im Handshake
Cookie cuby_session — Bestehende Browser-Session

Die Auth-Middleware wird automatisch auf Plugin-Namespaces (/plugins/<instanceId>) angewandt.


// Client-Beispiel
const socket = io('http://localhost:3847', {
  auth: { apiKey: 'DEIN_API_KEY' }
});

Sicherheitsmerkmale

Merkmal	Beschreibung
Timing-safe Vergleich	API-Key-Validierung mit `crypto.timingSafeEqual`
Einmal-Token	Auth-Tokens sind nach einmaliger Verwendung ungültig
HttpOnly Cookies	Session-Cookies nicht per JavaScript auslesbar
SameSite=None	Ermöglicht Cross-Origin-Zugriff für iframe-Embedding
UUID v4 Format	API Keys müssen dem UUID v4 Format entsprechen

Weiterführend

Studio-Integration — PostMessage-Auth im Detail
Umgebungsvariablen — USE_AUTH konfigurieren
API-Referenz — Alle Auth-Endpunkte