# Architektur — Web‑UI für Ansible‑TUI

Kurzer Überblick
Dieses Dokument beschreibt die finale Architektur für das MVP Web‑UI gemäß dem gewählten Profil:
Minimal — extern gepflegte .htpasswd, direkte ansible‑playbook‑CLI, ZIP/TAR‑Uploads, SSH‑Keys nur abgelegt.

Authentifizierung
- Nur externe .htpasswd zur HTTP‑Basic‑Authentifizierung.
- Die Applikation validiert Anfragen gegen die Webserver‑auth (keine DB‑Sync, keine interne Benutzerverwaltung).
- Betrieb: Ops pflegt .htpasswd; die Applikation nimmt keine Änderungen an .htpasswd vor.

Executor
- Playbooks werden durch Aufruf der systemweiten ansible‑playbook CLI ausgeführt.
- Kein Einsatz von ansible‑runner oder eines persistenten Hintergrund‑Executors im MVP.
- Die Applikation erstellt bei Bedarf temporäre Arbeitsverzeichnisse, schreibt erforderliche Metadaten und ruft ansible‑playbook mit den passenden Parametern.

SSH‑Key‑Handling
- SSH‑Keys werden als Dateien im Dateisystem abgelegt (Uploads oder durch Ops bereitgestellt).
- Die Applikation ändert keine Besitz‑ oder Berechtigungsattribute; Berechtigungsmanagement liegt bei den Betriebsprozessen/Opsteam.
- Keys werden referenziert, aber nicht automatisch verteilt oder in externe Stores synchronisiert.

Netzwerk / Deployment
- Kein integrierter Reverse‑Proxy oder TLS im MVP.
- Container/Service horcht direkt auf Port 8000 (HTTP).
- TLS, Reverse‑Proxy oder Ingress werden von der Ziel‑Betriebsumgebung bereitgestellt und in späteren Releases integriert.

Uploads / Artefakte
- Unterstützte Uploads: ZIP und TAR. Eingangsprüfung auf erlaubte Dateitypen und Größenlimits.
- Entpackung erfolgt in sicheren, temporären Verzeichnissen; keine automatische Ausführung von hochgeladenem Code außer kontrollierten Ansible‑Playbooks.

Persistenz / Datenbank
- Minimales MVP vermeidet eigene Benutzer‑DB. Falls Metadaten nötig sind, begrenzt auf leichtgewichtige lokale Speicherung (z. B. SQLite).
- Keine Speicherung sensitiver Geheimnisse in der Applikations‑DB; Secrets verbleiben unter Ops‑Verwaltung.

Sicherheitshinweise
- Ops ist verantwortlich für sichere Aufbewahrung und Rollout von .htpasswd und SSH‑Keys.
- Applikationslogs vermeiden sensitive Inhalte; Playbook‑Outputs können ggf. redigiert werden.

Offene Fragen
- Keine offenen Fragen — alle Entscheidungen sind gemäß dem Minimal‑Profil finalisiert.
## Erweiterung: Automatisches Host‑Onboarding (Feature‑Spec)

Zweck
- Erlaubt automatisches Onboarding neuer Zielhosts mit wählbaren Optionen:
  1. Pro‑Host SSH‑Key: serverseitig erzeugtes Schlüsselpaar (Ed25519, Fallback RSA‑4096).
  2. Login per Username + temporärem Passwort (Sudo‑fähiger Account) für initiale Berechtigungsaufgaben.
  3. Passwort wird nur einmalig verwendet und danach unverzüglich verworfen.

Kontext / Referenzen
- Diese Erweiterung baut auf bestehender Architektur auf; siehe Hauptdokumentation und API‑Liste: [`webapp/entwicklung/api_endpoints.md`](webapp/entwicklung/api_endpoints.md:1), DB‑Schema: [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1) und Roadmap: [`webapp/entwicklung/roadmap.md`](webapp/entwicklung/roadmap.md:1).

Design‑Prinzipien (Policy: Strict Ops‑First)
- Schlüssel: Ed25519 wird erzeugt. Falls Client/Host Ed25519 nicht unterstützt, Fallback RSA‑4096.
- Host‑Fingerprint: strikt — Fingerprint muss mit Ops' known_hosts übereinstimmen oder vorab durch Ops manuell freigegeben werden. Abweichende Fingerprints erzeugen eine Onboarding‑Sperre (Ops‑Review).
- Privater Schlüssel: niemals persistent auf Datenträger; nur im RAM des Onboarding‑Jobs verfügbar, nur für die Dauer des Jobs.
- Passwort: nur im RAM gehalten; nach erfolgreichem Onboarding sofort unwiederbringlich verworfen. Bei Fehlern sind maximal 3 unmittelbare Retries erlaubt, danach Ops‑Intervention.
- Audit: nur Metadaten (username, host, fingerprint‑SHA256, event=start|success|fail, timestamp, operator_id bei manueller Freigabe). Keine Passwörter oder Private‑Key‑Material in Logs oder DB. Audit‑Retention: 365 Tage.

Komponenten (Erweiterung)
- Onboarding UI (neues Formular, siehe API‑Mapping).
- Onboarding API (neue Endpoints; Auth via HTTP‑Basic/REMOTE_USER).
- Onboarding Service / Job Runner (zuständig für Erzeugung Key, SSH‑Verbindung, sudo‑Aufgaben, Key‑Copy).
- Ops Approval Queue (falls Host‑Fingerprint nicht bekannt).
- DB Erweiterungen (Hosts‑Tabelle, Onboard‑Jobs, Key‑Referenzen, ephemeral markers) — siehe vorgeschlagene Schema‑Änderungen in [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1).
- Audit‑Subsystem: schreibt streng limitierte Events in audit_logs mit Tagging.

Prozessablauf (High‑Level)
- UI: Benutzer öffnet "Host Onboarding" Formular und gibt ein: hostname/ip, ssh_port (optional), username (für initiales Passwort‑Login), temporäres Passwort (nur wenn Option 2 gewählt), gewünschter Ziel‑Benutzername (z. B. ansible user) und evtl. Beschreibung.
- API: POST /onboard/requests erzeugt Onboard‑Request, validiert Felder, erstellt Onboard‑Job und antwortet mit job_id.
- Pre‑Checks: Onboarding Service prüft Erreichbarkeit (TCP), prüft Host‑Fingerprint gegen Ops known_hosts.
  - Falls Fingerprint unbekannt/abweichend: Job wird in Ops‑Approval‑Queue gestellt; API gibt status=awaiting_approval zurück.
  - Falls Fingerprint OK: Fortsetzung.
- Key Generation: Service erzeugt temporäres Schlüsselpaar (Ed25519 oder RSA‑4096); privater Schlüssel bleibt nur in‑memory.
- SSH Login: Service stellt SSH‑Sitzung mit provided username+password auf. Die Login‑Phase verwendet sichere in‑memory Credentials; Zeitüberschreitung/Fehler führen zu Retry (max 3).
- Privilegien: Service führt via sudo (password prompted, one‑time use) die notwendigen Befehle aus (Erstellen Zieluser, setfacl/chown, Erstellen ~/.ssh, Deploy public key).
- Key‑Copy: öffentlicher Schlüssel wird in das target user's authorized_keys geschrieben; Dateirechte gesetzt.
- Verifizieren: Service versucht Login per SSH‑Key (key auth) und optional überprüft sudo‑Ausführung ohne Passwort (wenn operator gewünscht).
- Abschluss: Bei Erfolg markiert Job als completed, privater Schlüssel wird verworfen, Onboard‑Result in DB/Audit geschrieben. Bei Fehlern: bis 3 Retries, danach markiert als failed und Ops benachrichtigt.
- Cleanup: temporäre Verzeichnisse/Handles werden gelöscht, keine sensible Persistenz.

Mermaid: Ablaufdiagramm (vereinfachte Darstellung)
``` 
graph TB
  UI[User nutzt Onboarding‑Formular]
  API[POST /onboard/requests]
  JOB[Onboarding Service: Job erstellt]
  PRECHK[Pre‑Checks: TCP + Fingerprint vs Ops known_hosts]
  APPROVE[Ops Approval Queue]
  KEYGEN[Key‑Erzeugung: Ed25519 / RSA‑4096]
  SSHLOGIN[SSH Login mit User+Passwort (RAM)]
  SUDO[Sudo‑Aufgaben: create user, setup ~/.ssh, copy pubkey]
  VERIFY[Verify key auth]
  SUCCESS[Onboarding success -> Audit + DB]
  FAIL[Onboarding failed -> Audit + Ops Benachrichtigung]

  UI --> API --> JOB --> PRECHK
  PRECHK -- match --> KEYGEN --> SSHLOGIN --> SUDO --> VERIFY --> SUCCESS
  PRECHK -- mismatch --> APPROVE --> JOB
  VERIFY -- ok --> SUCCESS
  VERIFY -- nok --> FAIL
```

Schnittstellen / Integration (Kurz)
- Neue API Endpoints (voll spezifiziert in [`webapp/entwicklung/api_endpoints.md`](webapp/entwicklung/api_endpoints.md:1)):
  - POST /onboard/requests — erstellt Onboarding‑Request, Payload enthält host, port, username, password (nur in‑transit), desired_user, options (generate_key: true/false), description.
  - GET /onboard/requests/{id}/status — Jobstatus, ops approval indicator.
  - POST /onboard/requests/{id}/approve — Ops endpoint zum Freigeben eines Fingerprints (Auth: REMOTE_USER muss Ops sein).
  - GET /onboard/keys — listet public keys erzeugt (readonly metadata).
  - GET /onboard/jobs — Liste der Onboarding Jobs (nur Metadaten).
- Sicherheit: Passwords ONLY accepted via HTTPS (Ops deployment requirement). App muss niemals persistieren Passwörter; API akzeptiert Passwort im Request Body, Job Runner liest ihn und löscht danach.

DB‑Änderungen (high level; detail in schema.sql)
- Neue Tabelle hosts:
  - id, hostname/ip, primary_key_id (FK), fingerprint_sha256, onboarded_at, onboarded_by, status (pending/awaiting_approval/onboarded/failed), created_at
- Neue Tabelle onboard_jobs:
  - id, host_id, requested_by, desired_user, options_json, retries, status, started_at, finished_at, error_message
- ssh_keys erweitert / referenziert (public key metadata only; private key never stored)
- audit_logs Nutzung: nur Metadaten (wie oben)

Sicherheits‑ und Audit‑Aspekte (Details)
- Passwort‑Handling:
  - Password im API‑Request wird unmittelbar dem Job übergeben und nur im RAM gehalten.
  - Nach Jobabschluss oder nach Fehlern/Timeouts wird der Speicher unverzüglich ohne Swap/Logging freigegeben.
  - Implementationshinweis: nutze sichere Speicher‑APIs (mmap mit mlock wenn möglich) oder Host‑Mechanismen, um Swapping zu verhindern.
- Private Key Handling:
  - Erzeugung im Job‑Prozess oder in isolierter Secure Enclave; privater Key nie auf Disk.
  - Wenn Ops‑Review/Transfer erforderlich, Key kann kurzfristig (maximal Job‑Dauer) in verschlüsseltem Prozess‑Speicher gehalten werden; standardmäßig verboten.
- Fingerprint Handling:
  - Vergleich gegen Ops known_hosts (Ops liefert Pfad oder API für known_hosts‑Hash).
  - Bei Mismatch: keine automatische Akzeptanz; Ops‑Approval erforderlich.
- Auditing:
  - Erfasste Felder: event_type, job_id, host, fingerprint_sha256, requested_by, operator_id (bei approval), short status message, timestamp.
  - Keine Speicherung sensibler Inhalte (kein Passwort, kein privater Key).
  - Audit‑Retention: 365 Tage; älterer Einträge werden anonymisiert oder gelöscht gemäß Ops‑Policy.
- Log‑Sanitization:
  - Playbook/SSH Outputs werden auf sensitive Patterns geprüft/redigiert bevor sie persistiert oder angezeigt werden.

Betriebsverantwortung / Ops‑Aufgaben
- Ops liefert trusted known_hosts repository oder API‑Endpoint zur Fingerprint‑Prüfung.
- Ops sorgt für Transport‑TLS und sichere Deployment‑Konfiguration (no plaintext HTTP in Prod).
- Ops prüft und genehmigt Host‑Fingerprints in Approval‑Queue.
- Ops führt periodische Reviews/Key‑Rotation durch (nicht automatisch durch App).

Nächste Schritte (Dokumentation)
- API‑Specs aktualisieren: [`webapp/entwicklung/api_endpoints.md`](webapp/entwicklung/api_endpoints.md:1)
- Schema‑Änderungen in: [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1)
- Roadmap: neue Phase "Onboarding" mit Aufwandsschätzung und Meilensteine: [`webapp/entwicklung/roadmap.md`](webapp/entwicklung/roadmap.md:1)

(Ende Erweiterung)