Athena-Deck/ACCESS.md

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 <API-TOKEN>. 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):

curl -H 'Authorization: Bearer <API-TOKEN>' 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.