docs: add consumer audience split and external deps

2026-01-15 09:09:59 +01:00
parent 10ec58f744
commit a732a5afc4
19 changed files with 327 additions and 16 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@ -10,6 +10,22 @@ Safe Kiddo Daemon ist ein FastAPI-basierter Service, der lokale Systemkonten ver
 - Systemaktionen via sudo/usermod/pkill/shutdown
 - Update-Client-Integration (externes Update-Service-Backend)

+## Externe Abhaengigkeiten
+- Update-Service (intern): https://git.wlkns.org/stephan/update-webservice
+- OIDC-Service (intern): https://git.wlkns.org/stephan/oicd
+
+## Integrationspunkte
+### Update-Service
+Die Update-Integration nutzt v1-Endpunkte des Update-Services:
+- `POST /v1/enroll` (Enrollment fuer Langzeit-Token)
+- `GET /v1/projects/{project_id}/manifest`
+- `POST /v1/projects/{project_id}/status`
+Der Langzeit-Token wird lokal in `SKD_UPDATE_TOKEN_FILE` gespeichert und fuer Manifest/Status als Bearer-Token verwendet.
+
+### OIDC-Service
+OIDC nutzt Discovery unter `/.well-known/openid-configuration` basierend auf `SKD_OIDC_ISSUER`.
+Der Login-Flow tauscht einen Code gegen ein ID-Token (RS256) und validiert es gegen JWKS.
+
 ## Module und Verantwortlichkeiten
 - `backend/app.py`: API-Routing, Web-UI-Endpunkte, Update-Endpunkte.
 - `backend/auth.py`: PAM-Login, JWT-Handling, Auth-Guards, Allowlists.
@ -57,3 +73,7 @@ Safe Kiddo Daemon ist ein FastAPI-basierter Service, der lokale Systemkonten ver

 ## Spezifikationen
 - Update-Service OpenAPI: `docs/architecture/openapi.yaml` und `docs/architecture/openapi/`.
+
+## Weitere Dokumente
+- Entwicklung: `docs/DEVELOPMENT.md`
+- Deployment: `docs/DEPLOYMENT.md`
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@ -23,6 +23,26 @@ OIDC ist optional und zusaetzlich zu PAM.
 - `SKD_OIDC_SCOPES` (default `openid profile email`)
 - `SKD_SESSION_COOKIE_SECURE` (default `false`): Setze `true` fuer HTTPS.
 - `SKD_OIDC_STATE_COOKIE_NAME` (default `skd_oidc_state`)
+Referenz: OIDC-Service (intern) https://git.wlkns.org/stephan/oicd
+
+### OIDC-Einbindung (Kurz)
+1. Issuer setzen (muss der externen URL des IdP entsprechen):
+   - `SKD_OIDC_ISSUER=https://auth.example.org`
+2. Client registrieren (DCR), falls der IdP es erlaubt:
+```bash
+export SKD_OIDC_ISSUER="https://auth.example.org"
+export SKD_OIDC_REDIRECT_URI="https://kiddo.example.org/login/oidc/callback"
+export OIDC_INITIAL_ACCESS_TOKEN="example-token"
+./scripts/register_oidc_client.sh
+```
+3. Client-Credentials in `/etc/skd/env` setzen:
+```
+SKD_OIDC_CLIENT_ID=example-client-id
+SKD_OIDC_CLIENT_SECRET=example-client-secret
+SKD_OIDC_REDIRECT_URI=https://kiddo.example.org/login/oidc/callback
+SKD_SESSION_COOKIE_SECURE=true
+```
+Hinweis: OIDC ist aktiv, sobald Issuer, Client-ID und Secret gesetzt sind.

 ## Session/Benutzerverwaltung
 - `SKD_SESSION_COOKIE_NAME` (default `skd_session`)
@ -49,6 +69,17 @@ OIDC ist optional und zusaetzlich zu PAM.
 ## Dry-Run
 - `SKD_DRY_RUN` (default `false`): Keine echten System-Aktionen, nur Logging.

+## Tuning und Betrieb (Power-User)
+- `SKD_TOKEN_TTL_SECONDS`: kuerzere Tokens reduzieren Risiko, laengere Tokens reduzieren Login-Haeufigkeit.
+- `SKD_DEFAULT_COUNTDOWN`: steuert Nutzerwarnung vor Sperre/Shutdown.
+- `SKD_NOTIFY_TIMEOUT`: Dauer der Desktop-Benachrichtigung.
+- `SKD_SESSION_COOKIE_SECURE=true`: zwingend bei HTTPS, sonst Login-Cookies unsicher.
+
 ## Hinweise
 - `scripts/install.sh` erstellt `/etc/skd/env` und setzt Default-Werte fuer PAM/Allowed-User.
 - Aenderungen in `/etc/skd/env` erfordern einen Service-Restart (`sudo systemctl restart skd.service`).
+
+## Weitere Dokumente
+- Nutzung/Automation: `docs/USAGE.md`
+- Deployment: `docs/DEPLOYMENT.md`
+- Architektur: `docs/ARCHITECTURE.md`
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@ -54,6 +54,31 @@ Wichtige ENV-Variablen:
 - `SKD_UPDATE_TOKEN` oder `SKD_UPDATE_TOKEN_FILE`
 Voraussetzungen auf dem Host:
 - `curl`, `tar`, `sha256sum`, `python3`, `systemctl`
+Referenz: Update-Service (intern) https://git.wlkns.org/stephan/update-webservice
+
+### Update-Service einbinden
+1. Service-URL und Projekt setzen:
+```
+SKD_UPDATE_SERVICE_URL=https://update.wlkns.org
+SKD_UPDATE_PROJECT_ID=safe-kiddo-control
+```
+2. Enrollment-Token besorgen (vom Update-Service-Admin) und einen Langzeit-Token erzeugen:
+   - Option A: Ueber lokale API
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"enroll_token\":\"example-enroll-token\"}" \
+  http://localhost/update/enroll
+```
+   - Option B: Direkter Enrollment-Client
+```bash
+./scripts/manual_enroll.py --url "https://update.wlkns.org" --project "safe-kiddo-control" --token "example-enroll-token"
+```
+3. Token-Datei pruefen:
+```
+sudo cat /var/lib/skd/update_token
+```
+Hinweis: Der Update-Check ist erst moeglich, wenn der Langzeit-Token gespeichert wurde.

 Enrollment-Tools:
 - `scripts/manual_enroll.py`: Enrollment direkt gegen den Update-Service, schreibt Token in `SKD_UPDATE_TOKEN_FILE`.
@ -66,3 +91,8 @@ Lokale Status/Logs:
 ## Backup/Restore
 - Bei Apply wird `/opt/sk` nach `/opt/sk_backup_1.2.3_1700000000` verschoben (Beispiel).
 - Rollback nutzt das letzte Backup (`/opt/sk_backup_*`).
+
+## Weitere Dokumente
+- Konfiguration: `docs/CONFIGURATION.md`
+- Nutzung: `docs/USAGE.md`
+- Troubleshooting: `docs/TROUBLESHOOTING.md`
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@ -42,3 +42,32 @@ Aktuell keine CI/CD-Pipeline im Repository definiert.

 ## Legacy/Interna
 - `SKD_UPDATE_URL` und `SKD_UPDATE_STATUS_URL` sind in `backend/settings.py` noch vorhanden, werden aber im aktuellen Code nicht genutzt.
+
+## Externe Abhaengigkeiten (mit Quelle und Zweck)
+### Python-Libraries (requirements.txt)
+- FastAPI: https://fastapi.tiangolo.com/ (Web-API und Routing)
+- Uvicorn: https://www.uvicorn.org/ (ASGI-Server)
+- Pydantic: https://docs.pydantic.dev/ (Datenmodelle und Validierung)
+- Jinja2: https://jinja.palletsprojects.com/ (HTML-Templates)
+- PyJWT: https://pyjwt.readthedocs.io/ (JWT-Erstellung und -Validierung)
+- python-pam: https://pypi.org/project/python-pam/ (PAM-Authentifizierung)
+- httpx: https://www.python-httpx.org/ (HTTP-Client fuer Update/OIDC)
+- cryptography: https://cryptography.io/ (Krypto-Abhaengigkeit fuer JWT)
+- PyYAML (optional): https://pyyaml.org/ (YAML-Parsing in `scripts/deploy.sh`)
+
+### System-Tools
+- systemd: https://www.freedesktop.org/software/systemd/man/systemd.html (Service-Management)
+- Linux-PAM: https://www.linux-pam.org/ (System-Authentifizierung)
+- usermod/pkill/shutdown: https://man7.org/linux/man-pages/ (Account- und Session-Management)
+- curl/tar/sha256sum/rsync/git/ssh: https://man7.org/linux/man-pages/ (Install/Update/Deploy)
+- jq (optional): https://stedolan.github.io/jq/ (JSON-Parsing in Beispielen)
+- notify-send: https://developer.gnome.org/libnotify/ (Desktop-Benachrichtigungen)
+- paplay/aplay: https://www.freedesktop.org/wiki/Software/PulseAudio/ und https://alsa-project.org/ (Sound)
+
+### Externe Services
+- Update-Service (intern): https://git.wlkns.org/stephan/update-webservice (Manifest/Status/Enrollment)
+- OIDC-Service (intern): https://git.wlkns.org/stephan/oicd (Login via OIDC)
+
+## Weitere Dokumente
+- Architektur: `docs/ARCHITECTURE.md`
+- Deployment: `docs/DEPLOYMENT.md`
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@ -19,3 +19,8 @@ Nein, im Repository ist kein Docker-Setup enthalten.
 ## Wo liegen Logs?
 - systemd: `journalctl -u skd.service`
 - Update-Status/Logs: siehe `SKD_UPDATE_STATUS_FILE` und `SKD_UPDATE_LOG_FILE`.
+
+## Weitere Dokumente
+- Einstieg: `docs/GETTING_STARTED.md`
+- Nutzung: `docs/USAGE.md`
+- Troubleshooting: `docs/TROUBLESHOOTING.md`
--- a/docs/FOR_USERS.md
+++ b/docs/FOR_USERS.md
@ -0,0 +1,37 @@
+ID: DOC_000017 | Version: 0.2.1 | Status: Draft
+By: Codex (GPT-5)
+
+# Fuer Nutzerinnen und Nutzer
+
+## Worum geht es?
+Safe Kiddo Daemon hilft dabei, lokale Benutzerkonten auf einem Familien- oder Schulgeraet zu sperren und wieder freizugeben. Ziel ist, klare Nutzungszeiten durchzusetzen und sicherzustellen, dass nach einer Sperrung keine Sitzung offen bleibt.
+
+## Welche Probleme loest es?
+- Ein Konto soll zu bestimmten Zeiten nicht nutzbar sein.
+- Offene Sitzungen sollen beendet werden, wenn ein Konto gesperrt wird.
+- Eltern/Betreuende wollen den Zustand zentral sehen und verwalten.
+
+## Typische Anwendungsfaelle
+- Abendliche Nutzungszeit endet, der Account wird gesperrt.
+- Bei Verstoessen gegen Regeln wird ein Konto kurzzeitig deaktiviert.
+- Eine Sitzung bleibt offen und muss beendet werden.
+
+## Wie wird es bedient?
+Die Bedienung erfolgt ueber eine einfache Web-Oberflaeche im lokalen Netzwerk.
+Dort kann eine berechtigte Person:
+- Konten sperren oder freigeben.
+- Den aktuellen Status sehen.
+
+## Grenzen und Sicherheit
+- Die Sperrung betrifft nur lokale Konten auf dem Geraet.
+- Wenn kein berechtigter Zugang vorhanden ist, kann die Web-Oberflaeche nicht genutzt werden.
+- Das System kann den Rechner im Bedarfsfall herunterfahren, um offene Sitzungen zu beenden.
+
+## Was tun, wenn etwas schiefgeht?
+- Wenn die Web-Oberflaeche nicht erreichbar ist, die betreuende Person informieren.
+- Wenn das Konto unerwartet gesperrt wurde, nicht weiter experimentieren, sondern nachfragen.
+- Bei wiederholten Problemen soll der Betreiber die technische Fehlerbehebung pruefen.
+
+## Weitere Informationen (fuer Betreiber)
+- Einstieg: `docs/GETTING_STARTED.md`
+- Hilfe bei Problemen: `docs/TROUBLESHOOTING.md`
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@ -46,3 +46,14 @@ Hinweis: `jq` ist optional; ohne jq das Token manuell aus der JSON-Antwort lesen
 - Konfiguration anpassen: `docs/CONFIGURATION.md`
 - API und Web-UI nutzen: `docs/USAGE.md`
 - Deployment und Updates: `docs/DEPLOYMENT.md`
+
+## Typische Einsteigerfehler
+- Service startet, aber Port 80 ist bereits belegt (loese den Konflikt oder nutze einen anderen Port).
+- Login scheitert, weil `SKD_AUTH_ALLOWED_USERS`/`SKD_AUTH_ALLOWED_GROUPS` den Nutzer nicht erlauben.
+- OIDC wird erwartet, ist aber nicht aktiv (Issuer/Client-ID/Secret fehlen).
+- Token wird nicht gesendet (fehlender `Authorization: Bearer` Header).
+
+## Weitere Dokumente
+- Endnutzer-Sicht: `docs/FOR_USERS.md`
+- FAQ: `docs/FAQ.md`
+- Troubleshooting: `docs/TROUBLESHOOTING.md`
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@ -35,3 +35,8 @@ By: Codex (GPT-5)
 ## Rollback meldet "no backup found"
 - Es existiert kein `/opt/sk_backup_*` vom vorherigen Update.
 - Rollback erst nach mindestens einem erfolgreichen Update moeglich.
+
+## Weitere Dokumente
+- Einstieg: `docs/GETTING_STARTED.md`
+- Konfiguration: `docs/CONFIGURATION.md`
+- Deployment: `docs/DEPLOYMENT.md`
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@ -24,6 +24,15 @@ Login ist nur fuer erlaubte Nutzer moeglich (siehe `SKD_AUTH_ALLOWED_USERS` und
 - Login per PAM oder OIDC (wenn konfiguriert).
 - Aktionen: Benutzer sperren/entsperren, Update-Status, Update-Check, Apply/Rollback.

+## Automatisierung (Power-User)
+Die API kann in Skripten oder Zeitplaenen genutzt werden, z.B. fuer regelmaessige Sperrungen.
+
+Beispiel (cron, taeglich 21:00 sperren):
+```bash
+0 21 * * * curl -s -X POST -H "Authorization: Bearer $TOKEN" http://localhost/users/child1/disable
+```
+Hinweis: Token sicher speichern (z.B. Root-Only Datei) und regelmaessig rotieren.
+
 ## API-Endpunkte (Auszug)
 ### Health und Identitaet
 - `GET /health` (ohne Auth)
@ -66,6 +75,11 @@ curl -X POST -H "Authorization: Bearer $token" http://localhost/update/check
 ```
 Hinweis: Ohne gespeichertes Update-Token liefert der Check einen Fehler.

+## Weitere Dokumente
+- Konfiguration: `docs/CONFIGURATION.md`
+- Deployment: `docs/DEPLOYMENT.md`
+- Troubleshooting: `docs/TROUBLESHOOTING.md`
+
 ## CLI-Fallback (sk.sh)
 Das Legacy-Script arbeitet direkt auf dem Host und benoetigt Root-Rechte.