# API Endpoints — Web‑UI für Ansible‑TUI

Hinweis zur Authentifizierung
- HTTP‑Basic wird extern via .htpasswd gepflegt; Webserver setzt Auth und ggf. REMOTE_USER.
- Die Applikation verifiziert keine internen Benutzer, erwartet ggf. REMOTE_USER zur Audit‑Zuordnung.

Endpunkte (MVP)

GET /health
- Beschreibung: Simple Health‑Check
- Antwort: 200 OK

GET /playbooks
- Beschreibung: Liste aller hochgeladenen Playbooks (Metadaten)
- Query: ?limit=&offset=
- Antwort: JSON Array [{id,name,filename,uploaded_by,uploaded_at}]

POST /uploads
- Beschreibung: Upload eines ZIP/TAR mit Playbook(s)
- Konsumiert: multipart/form-data file=...
- Validierung: MIME und Dateiendung (zip,tar,tgz), Größenlimit
- Antwort: 201 Created + Metadaten

GET /playbooks/{id}
- Beschreibung: Metadaten zu einem Playbook
- Antwort: JSON

POST /playbooks/{id}/run
- Beschreibung: Startet einen Run via systemweiter ansible-playbook CLI. Keine Nutzung von ansible-runner.
- Body: optional JSON {inventory: string, extra_vars: object, tags: [string], become: bool}
- Behaviour: Prozess wird vom Service gestartet; stdout/stderr werden in temporäre Dateien geschrieben.
- Antwort: 202 Accepted {run_id}

GET /runs/{run_id}/status
- Beschreibung: Statusabfrage (queued,running,success,failed)
- Antwort: JSON {run_id,status,exit_code,started_at,finished_at}

GET /runs/{run_id}/output
- Beschreibung: Holt vollständiges stdout/stderr des Runs (Text/stream)
- Antwort: text/plain (oder chunked)

GET /keys
- Beschreibung: Listet referenzierbare SSH‑Keys (nur lesend)
- Antwort: JSON [{key_id,filename,description}]

GET /logs?limit=&offset=
- Beschreibung: Zugriff auf Run‑Logs / Audit‑Einträge (keine sensiblen Daten)
- Antwort: JSON

Sicherheits‑Hinweis
- Die Applikation führt keine Änderung an SSH‑Keys oder .htpasswd durch.
- Alle schreibenden Betriebsaufgaben (Permissions, Key‑Rollout, TLS) sind außerhalb des MVP‑Scopes.
## Erweiterung: Onboarding API — Endpoints für automatisches Host‑Onboarding

Authentifizierung / Autorisierung
- Auth via vorhandene HTTP‑Basic/.htpasswd‑Integration; Webserver stellt REMOTE_USER zur Verfügung.
- Ops‑spezifische Endpoints (z. B. Approve) erfordern REMOTE_USER ∈ Ops‑Gruppe (Ops‑Policy).
- Transport: Produktion erfordert TLS (Ops‑Deployment‑Voraussetzung).

Zusätzliche Endpoints (Übersicht)
- POST /onboard/requests
- GET /onboard/requests
- GET /onboard/requests/{id}/status
- POST /onboard/requests/{id}/approve
- POST /onboard/requests/{id}/cancel
- GET /onboard/jobs
- GET /onboard/keys
- GET /onboard/requests/{id}/logs

POST /onboard/requests
- Zweck: Erstellt eine Onboarding‑Anfrage / startet ein Onboarding‑Job (sofern Pre‑Checks erfolgreich sind).
- Auth: REMOTE_USER (any authenticated user)
- Konsumiert: application/json
- Payload:
  {
    "host": "192.0.2.10",           // host oder IP
    "port": 22,                    // optional, default 22
    "login_user": "ubuntu",        // Account zur initialen Login‑Phase (sudo‑fähig)
    "login_password": "secret",    // nur in‑transit; wird nicht persistiert
    "desired_user": "ansible",     // Benutzer, der angelegt/wenn nötig benutzt wird
    "generate_key": true,          // true => Server erzeugt Schlüsselpaar (Ed25519/RSA‑4096 fallback)
    "public_key": null,            // optional, wenn false und Nutzer eigenen Schlüssel liefert
    "description": "Kurzinfo",
    "options": {                   // optional: z. B. {"force_approve":false}
      "force_approve": false
    }
  }
- Verhalten:
  - Validierung von Pflichtfeldern.
  - Erzeugt Onboard‑Request und Onboard‑Job, reply enthält { "job_id": "...", "status": "created" }.
  - Wenn Fingerprint nicht mit Ops known_hosts übereinstimmt, wird status = "awaiting_approval".
- Antwort: 201 Created
  {
    "job_id": "uuid",
    "status": "created" | "awaiting_approval" | "queued"
  }
- Fehlercodes:
  - 400 Bad Request (Validierungsfehler)
  - 401 Unauthorized
  - 429 Too Many Requests (Rate‑Limit pro User/Host)

GET /onboard/requests
- Zweck: Listet Onboarding‑Requests (nur Metadaten)
- Query: ?limit=&offset=&status=
- Antwort: JSON Array [{job_id, host, requested_by, status, created_at, fingerprint_sha256?}]

GET /onboard/requests/{id}/status
- Zweck: Statusabfrage für einen Request
- Antwort:
  {
    "job_id": "...",
    "host": "...",
    "status": "created|queued|running|awaiting_approval|approved|onboarded|failed|cancelled",
    "retries": 0,
    "started_at": "...",
    "finished_at": "...",
    "error_message": "kurze Fehlerdiagnose (sensitivitäts‑gefiltert)"
  }

POST /onboard/requests/{id}/approve
- Zweck: Ops‑Endpoint zur Freigabe eines abweichenden Host‑Fingerprints
- Auth: REMOTE_USER muss Ops sein (Server‑Side check)
- Payload:
  {
    "approve": true,
    "operator_note": "Fingerprint validiert via call",
    "operator_id": "ops-username"
  }
- Verhalten: Wenn genehmigt, Job wird zur Fortsetzung freigegeben; Audit‑Eintrag mit operator_id erzeugt.
- Antwort: 200 OK { "job_id": "...", "status": "approved" }
- Fehler: 403 Forbidden (wenn nicht Ops), 404 Not Found

POST /onboard/requests/{id}/cancel
- Zweck: Bricht laufenden/queued Onboarding‑Job ab (z. B. User Abbruch)
- Auth: Requester oder Ops
- Antwort: 200 OK { "job_id": "...", "status": "cancelled" }

GET /onboard/jobs
- Zweck: Admin/Operator Sicht auf Onboard‑Jobs (Metadaten)
- Filters: status, requested_by, host
- Antwort: Array von job‑Metadaten (keine sensitiven Inhalte)

GET /onboard/keys
- Zweck: Listet erzeugte Public‑Keys (Metadaten only)
- Antwort: [{ "key_id": "...", "host_id": "...", "public_key_fingerprint": "...", "created_at": "..." }]

GET /onboard/requests/{id}/logs
- Zweck: Liefert redigierte Logs des Onboarding‑Jobs (Ausgaben, Schritte)
- Sicherheits‑Hinweis: Logs sind gesäubert; keine Passwörter oder private Key‑Material enthalten.
- Antwort: text/plain oder JSON { "lines":[ ... ] }

Sicherheits‑Hinweise für API‑Design
- Login‑Password darf niemals geloggt werden; im API‑Server mittelbar nur in‑memory übergeben.
- API darf niemals privaten Schlüssel in Responses zurückliefern.
- Alle Endpoints, die sensible Ablaufsteuerung erlauben (approve, cancel), müssen REMOTE_USER‑Checks durchführen.
- Rate‑Limits: Schutz gegen bruteforce / DOS.
- Input‑Sanitization: host/username dürfen keine Shell‑Injection ermöglichen; SSH‑Interaktionen erfolgen kontrolliert.
- Audit: Jeder state‑wechsel (created, awaiting_approval, approved, onboarded, failed, cancelled) schreibt ein Metadaten‑Audit (siehe [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1) Anpassungen).

Mapping UI ↔ API
- UI‑Form "Host Onboarding" ↟ POST /onboard/requests
- UI‑Ops Dashboard ↟ GET /onboard/requests?status=awaiting_approval
- UI‑Ops Approve Button ↟ POST /onboard/requests/{id}/approve
- UI‑User Status Polling ↟ GET /onboard/requests/{id}/status
- UI‑Logs ↟ GET /onboard/requests/{id}/logs

Beispiel‑Flow (Kurz)
1. User sendet POST /onboard/requests mit login_password.
2. API antwortet job_id.
3. Onboarding Service führt Pre‑Check aus; bei Fingerprint‑Mismatch → awaiting_approval.
4. Ops Approver ruft POST /onboard/requests/{id}/approve → Service fährt fort.
5. Job schreibt audit_logs und setzt Host Status auf onboarded oder failed.

Referenzen zur weiteren Anpassung
- Architektur: [`webapp/entwicklung/architektur.md`](webapp/entwicklung/architektur.md:1)
- DB Schema: [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1)
- Roadmap: [`webapp/entwicklung/roadmap.md`](webapp/entwicklung/roadmap.md:1)