docs: overhaul repository documentation

2026-01-15 08:54:52 +01:00
parent c41482a7b3
commit 10ec58f744
22 changed files with 575 additions and 108 deletions
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@ -0,0 +1,80 @@
+ID: DOC_000010 | Version: 0.2.1 | Status: Draft
+By: Codex (GPT-5)
+
+# Usage
+
+## Authentifizierung
+- PAM-Login: `POST /login` mit Benutzername/Passwort. Liefert JWT und setzt Session-Cookie.
+- OIDC-Login: `GET /login/oidc/start` startet Flow, Callback setzt Session-Cookie.
+- Alle geschuetzten Endpunkte akzeptieren `Authorization: Bearer $TOKEN` oder Session-Cookie.
+
+### Beispiel: Login und Token nutzen
+```bash
+token=$(curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"username":"root","password":"example-password"}' \
+  http://localhost/login | jq -r .token)
+
+curl -s -H "Authorization: Bearer $token" http://localhost/me
+```
+Hinweis: `jq` ist optional; ohne jq das Token manuell aus der JSON-Antwort lesen.
+Login ist nur fuer erlaubte Nutzer moeglich (siehe `SKD_AUTH_ALLOWED_USERS` und `SKD_AUTH_ALLOWED_GROUPS`).
+
+## Web-UI
+- Aufruf: `http://localhost/`
+- Login per PAM oder OIDC (wenn konfiguriert).
+- Aktionen: Benutzer sperren/entsperren, Update-Status, Update-Check, Apply/Rollback.
+
+## API-Endpunkte (Auszug)
+### Health und Identitaet
+- `GET /health` (ohne Auth)
+- `GET /me`
+
+### Benutzerverwaltung
+- `GET /users`
+- `POST /users/{username}/disable` mit JSON `{countdown?, sound?, message?}`
+- `POST /users/{username}/enable`
+
+Beispiel (disable):
+```bash
+curl -X POST -H "Authorization: Bearer $token" \
+  -H "Content-Type: application/json" \
+  -d '{"countdown":90,"sound":true,"message":"Bitte speichern"}' \
+  http://localhost/users/child1/disable
+```
+
+### Update-API (lokal)
+Alle Update-Endpunkte erfordern Admin-Auth.
+- `GET /update/status`
+- `POST /update/enroll` (optional Body: `{ "enroll_token": "..." }`)
+- `POST /update/check`
+- `POST /update/apply` (optional Body: `{ "version": "x.y.z" }`)
+- `POST /update/rollback`
+- `GET /update/logs?limit=200`
+
+Beispiel (Enrollment):
+```bash
+ENROLL_TOKEN="example-enroll-token"
+curl -X POST -H "Authorization: Bearer $token" \
+  -H "Content-Type: application/json" \
+  -d "{\"enroll_token\":\"${ENROLL_TOKEN}\"}" \
+  http://localhost/update/enroll
+```
+
+Beispiel (Update-Check):
+```bash
+curl -X POST -H "Authorization: Bearer $token" http://localhost/update/check
+```
+Hinweis: Ohne gespeichertes Update-Token liefert der Check einen Fehler.
+
+## CLI-Fallback (sk.sh)
+Das Legacy-Script arbeitet direkt auf dem Host und benoetigt Root-Rechte.
+
+Aufruf:
+```bash
+sudo ./sk.sh USERNAME disable|enable [countdown] [sound] [countdown_time_in_seconds]
+```
+
+Beispiel:
+```bash
+sudo ./sk.sh demo_user disable countdown sound 90
+```