124 lines
6.7 KiB
Markdown
124 lines
6.7 KiB
Markdown
# Zugang und API · Athena Deck 0.3
|
||
|
||
## Ersteinrichtung
|
||
|
||
Bei der ersten Einrichtung legt der Betreiber zwei getrennte
|
||
Zugangsdaten fest:
|
||
|
||
1. **Oberflächenkennwort**: 16–256 Zeichen, ein Administratorzugang.
|
||
2. **API-Token**: 32–256 Zeichen aus Buchstaben, Ziffern, Bindestrich/Unterstrich.
|
||
„Sicheren Token erzeugen“ erzeugt mit dem Browser-Zufallsgenerator 32 zufällige
|
||
Bytes, dargestellt als Hexwert mit `ad_`-Präfix. Alternativ eigenen Token einsetzen.
|
||
|
||
Kennwort und Token dürfen nicht identisch sein. Der Token kann während der Eingabe
|
||
angezeigt/kopiert werden. **Vor dem Speichern im Passwortmanager sichern.** Ein
|
||
vorhandener Token ist anschließend nicht abrufbar; bei Verlust einen neuen setzen.
|
||
„Neuen Token kopieren“ ist nur bei gefülltem Eingabefeld verfügbar und kopiert
|
||
ausschließlich diesen neuen Wert, niemals den gespeicherten Prüfwert. Bei gesperrter
|
||
Clipboard-API wird die browserinterne Kopieralternative versucht. Lehnt der Browser
|
||
auch diese ab, „Token anzeigen“ verwenden und manuell kopieren. Im ersten Schritt wird noch keine Sitzung erzeugt:
|
||
nach dem Einrichten mit dem gewählten Kennwort anmelden.
|
||
|
||
Der Debian-Installer richtet die Zugangsdaten vor dem Start ein. Speicherung unter
|
||
`state/auth.json` im privaten Installationsverzeichnis, Datei 0600. Es gibt keine
|
||
voreingestellten Zugangsdaten. Status, Hardware und Steuerung sind anmeldepflichtig.
|
||
Der Ersteinrichtungs-Endpunkt ist im provisionierten Serverbetrieb deaktiviert.
|
||
Die isolierte Entwicklungsinstanz erlaubt eine neue einmalige Einrichtung über
|
||
den SSH-Tunnel. Zugangsdaten der früheren Vorschau werden nicht übertragen.
|
||
|
||
## Einstellungen → Zugang & API
|
||
|
||
- **Kennwort ändern:** aktuelles Kennwort, neues Kennwort und Wiederholung eingeben.
|
||
Nach erfolgreicher Speicherung sind alle Browser-Sitzungen ungültig. Erneut mit
|
||
dem neuen Kennwort anmelden. Der API-Token bleibt gültig.
|
||
- **API-Token ändern:** aktuelles Oberflächenkennwort bestätigen und neuen Token
|
||
einsetzen oder erzeugen. Nach Speicherung wird der alte Token sofort abgewiesen.
|
||
Browser-Sitzungen bleiben gültig. API-Clients müssen den neuen Token erhalten.
|
||
- **Abmelden:** beendet die aktuelle Sitzung serverseitig.
|
||
|
||
Die Einstellungsseite benennt die gerade verwaltete Instanz auf dem Debian-Server.
|
||
Es gibt zunächst **einen Administrator**, keine Benutzernamen, weiteren Benutzer,
|
||
Rollen, persönlichen Tokens oder Passwort-zurücksetzen-per-E-Mail.
|
||
|
||
## Browser und API sind getrennt
|
||
|
||
Die Oberfläche verwendet acht Stunden gültige HttpOnly-/SameSite=Strict-Cookies.
|
||
Mutationen im Browser benötigen zusätzlich `X-Athena-Deck: 1` und einen passenden
|
||
Origin. Kennwortprüfung und sensible Änderungen sind auf zehn Versuche pro Minute
|
||
und Instanz begrenzt. Zugangsdaten werden niemals in Querystrings übertragen.
|
||
|
||
API-Clients verwenden `Authorization: Bearer <API-TOKEN>`. Aktuell erlaubt sind:
|
||
|
||
| Methode | Endpunkt |
|
||
|---|---|
|
||
| GET | `/api/v1/status` |
|
||
| GET | `/api/v1/hardware` |
|
||
| GET | API-Port: `/v1/models`, `/health` |
|
||
| POST | API-Port: `/v1/chat/completions`, `/v1/images/generations` |
|
||
|
||
API-Clients brauchen weder Cookie noch Browser-CSRF-Header. Ein vorhandener
|
||
Authorization-Header wird ausdrücklich geprüft; ein ungültiger Token wird nicht
|
||
über ein zusätzliches gültiges Browser-Cookie umgangen. Der API-Token erlaubt
|
||
**keine** Zugangsdaten-, WireGuard-, Installations- oder sonstigen Admin-Aktionen.
|
||
|
||
Beispiel (Platzhalter ersetzen):
|
||
|
||
```sh
|
||
curl -H 'Authorization: Bearer <API-TOKEN>' http://127.0.0.1:8108/api/v1/status
|
||
```
|
||
|
||
Der separate Inferenz-Listener prüft denselben Deck-Token bei jeder Anfrage.
|
||
Endpunkt starten/stoppen, Port und Profilfreigaben ändern erfordert weiterhin die
|
||
Admin-Sitzung. Der alte produktive Router-Token wird nicht geändert. Der neue
|
||
Listener ist zunächst nur via Loopback/SSH erreichbar; das bestehende
|
||
WireGuard-Modul wird nicht automatisch erweitert. Details: [ENDPOINT.md](ENDPOINT.md).
|
||
|
||
## Speicherung und Serverbetrieb
|
||
|
||
Kennwörter: PBKDF2-HMAC-SHA256 mit 600.000 Iterationen und individuellem Salt.
|
||
API-Tokens: ausschließlich SHA-256-Prüfwert (bei generierten Tokens 256 Bit Zufall).
|
||
Keine Klartext-Speicherung von Kennwort oder Token. Statusantworten enthalten nur
|
||
Einrichtungsstatus und Änderungszeiten, keine Hashes, Kennwörter oder Tokenwerte.
|
||
|
||
Lokale Schreibvorgänge sind atomar; bei fehlgeschlagenem Schreiben bleibt der alte
|
||
Stand gültig. Die lokale Anwendung serialisiert Einrichtung und Änderungen. Im
|
||
Servercontainer persistiert der Root-Helper Änderungen unter `/data/auth.json` über
|
||
eine fest definierte RPC-Schnittstelle; der Webprozess bleibt unprivilegiert.
|
||
Versionsprüfung verhindert das Überschreiben inzwischen geänderter Zugangsdaten.
|
||
Der Webprozess liest den aktuellen Stand bei der Autorisierung. Es gibt keinen
|
||
veralteten Credential-Snapshot in Umgebungsvariablen. Neustarts erhalten geänderte
|
||
Zugangsdaten und verwerfen Sitzungen.
|
||
|
||
Die Netzwerkschicht leitet Authorization gezielt weiter, vertraut jedoch weiterhin
|
||
keinen vom Client gesetzten Ingress-Headern. Kein CORS-Zugriff, kein Docker-Socket im
|
||
Webprozess. Die bestehende Transportgrenze bleibt: lokale Nutzung über Loopback,
|
||
Server über WireGuard/SSH; der direkte LAN-Zugang bietet derzeit HTTP, kein HTTPS.
|
||
|
||
## API für die Oberfläche
|
||
|
||
| Methode / Endpunkt | Inhalt / Verhalten |
|
||
|---|---|
|
||
| GET `/api/v1/auth/status` | Öffentlich nur initialized/authenticated; angemeldet zusätzlich Zeiten und Tokenstatus |
|
||
| POST `/api/v1/auth/setup` | password, api_token; einmalige lokale Einrichtung |
|
||
| POST `/api/v1/login` | password; setzt Sitzungscookie |
|
||
| POST `/api/v1/logout` | aktuelle Sitzung beenden |
|
||
| POST `/api/v1/auth/password` | current_password, new_password; Sitzung erforderlich |
|
||
| POST `/api/v1/auth/token` | current_password, new_token; Sitzung erforderlich |
|
||
| POST `/api/v1/network/install` | password, api_token für die neue Server-Instanz; lokale Admin-Sitzung erforderlich |
|
||
|
||
Keine generische Benutzerverwaltung oder API für das Auslesen der Geheimnisse.
|
||
|
||
## Verifikation
|
||
|
||
26 lokale Tests: Ersteinrichtung, parallele Einrichtung, fehlende Anmeldung,
|
||
Kennwort-/Tokenwechsel, alte und neue Credentials, alle Sitzungen, Token-Rechte,
|
||
Logout, Legacy-Stand, Dateirechte, fehlgeschlagenes Schreiben, keine Klartexte in
|
||
der Persistenz, vorhandene Demo-/WireGuard-Regressionsprüfungen.
|
||
|
||
Zusätzlich echte Tests in zwei kurzlebigen Docker-Containern auf Athena:
|
||
Token durch Proxy, gesperrte Admin-Endpunkte, beide Rotationen, alte Credentials
|
||
abgewiesen, neue Credentials nach Container-Neustart gültig. WireGuard-Handshake,
|
||
Ingress-Sperren und Rückfallverhalten weiterhin erfolgreich. Keine Host-Ports
|
||
für Tests veröffentlicht; Testcontainer und Test-Secrets entfernt. Startzeiten
|
||
aller zuvor vorhandenen Container unverändert.
|