# Zugang und API · Athena Deck 0.3 ## Ersteinrichtung Beim ersten Öffnen der lokalen Oberfläche 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. Auf HTTP-Adressen kann die Browser-Zwischenablage gesperrt sein. Dann „Token anzeigen“ verwenden und manuell kopieren. Im ersten Schritt wird noch keine Sitzung erzeugt: nach dem Einrichten mit dem gewählten Kennwort anmelden. Lokaler Zustand: `.state/auth.json`, Verzeichnis 0700, Datei 0600, in Git und Docker-Builds ausgeschlossen. Es gibt keine voreingestellten oder vom Agenten festgelegten Zugangsdaten. Auch die Mac-Verwaltungsoberfläche verlangt jetzt die Ersteinrichtung und Anmeldung. Status, Hardware und Steuerung sind davor gesperrt. Der Ersteinrichtungs-Endpunkt ist einmalig und nur in der Loopback-Instanz aktiv. Die optionale Athena-Serverinstallation erhält in ihrem Installationsformular **eigene** Zugangsdaten (Kennwort und API-Token). Diese gelten für die Server-Instanz, nicht für die Mac-Instanz. Die Server-Anwendung wird bereits provisioniert gestartet; es gibt keinen ungeschützten Fernzugriff, mit dem ein beliebiger Besucher den Server beanspruchen könnte. Ein vorhandener 0.2-Kennwortstand bleibt lesbar; API-Zugriff ist dort zunächst deaktiviert, bis ein Token eingerichtet wird. Bestehende Server-Container werden durch diese Codeänderung nicht automatisch aktualisiert. ## 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 (Mac oder Athena). 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 `. Aktuell erlaubt sind: | Methode | Endpunkt | |---|---| | GET | `/api/v1/status` | | GET | `/api/v1/hardware` | | GET | `/api/v1/demo` | | POST | `/api/v1/demo/start` | | POST | `/api/v1/demo/stop` | 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 ' http://127.0.0.1:8108/api/v1/status ``` Die späteren Modell-/Inferenz-Endpunkte existieren noch nicht. Ihre Autorisierung muss beim Ergänzen explizit an die Token-Prüfung angeschlossen werden. Es wird kein produktiver Router-Token verändert. Der WireGuard-Zugriffsmodus gilt weiterhin vor der Authentifizierung: ein gültiger Token umgeht keine gesperrte LAN-/Tunnelroute. ## 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.