ID: DOC_000012 | Version: 0.2.2 | Status: Draft
By: Codex (GPT-5)

# Architektur

## Systemuebersicht
Safe Kiddo Daemon ist ein FastAPI-basierter Service, der lokale Systemkonten verwaltet. Er kombiniert:
- API und Web-UI (FastAPI + Jinja2 Templates)
- Authentifizierung (PAM und optional OIDC)
- 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.
- `backend/oidc.py`: OIDC Discovery, Token-Exchange, JWT-Validierung.
- `backend/actions.py`: Systemaktionen (lock/unlock, notify, sound, shutdown).
- `backend/update.py`: Update-Enrollment, Manifest-Check, Update/Rollback-Start, Status/Logs.
- `backend/settings.py`: Zentrale ENV-Konfiguration.
- `backend/templates/` + `backend/static/`: Web-UI.
- `scripts/*.sh`: Installation, Deployment, Update-Client, Rollback, OIDC-Registration.

## Daten- und Kontrollfluss
### Login und Auth
1. `POST /login` authentifiziert via PAM.
2. JWT wird erstellt und als Cookie oder Bearer-Token genutzt.
3. Schutz aller Admin-Endpunkte via `get_current_admin`.

### OIDC-Flow (optional)
1. `GET /login/oidc/start` generiert State und leitet zum IdP.
2. Callback `GET /login/oidc/callback` validiert State, tauscht Code gegen ID-Token.
3. ID-Token wird gegen JWKS geprueft, Username extrahiert, Session gesetzt.

### Benutzeraktionen
1. `POST /users/{username}/disable` ruft `actions.disable_user`.
2. Systemaktionen: `usermod -L`, optional notify/sound, `pkill`, optional `shutdown`.
3. `POST /users/{username}/enable` fuehrt `usermod -U` aus.

### Update-Flow
1. `POST /update/enroll` schreibt Langzeit-Token in `SKD_UPDATE_TOKEN_FILE`.
2. `POST /update/check` ruft Manifest beim Update-Service ab.
3. `POST /update/apply` startet `scripts/update_client.sh` asynchron.
4. `POST /update/rollback` startet `scripts/rollback_client.sh` asynchron.
5. Status/Logs werden lokal in Dateien geschrieben und optional an den Update-Service gemeldet.

## Designentscheidungen und Tradeoffs
- **Root-Run**: Service laeuft als root, da PAM und Systemkommandos Root erfordern.
- **JWT + Cookie**: Einfache lokale Auth; keine externe Session-Datenbank.
- **OIDC optional**: OIDC ist optional, PAM bleibt als Fallback aktiv.
- **Update als Script**: Update/Backup/Swap via Bash-Skripte fuer einfache Ops, Tradeoff: weniger granularer Fehler-Handling.

## Erweiterungspunkte
- **Auth**: Weitere Auth-Mechanismen koennen in `backend/auth.py` integriert werden.
- **UI**: Templates unter `backend/templates/` und CSS in `backend/static/`.
- **Update-Client**: Anpassung der Update-Strategie in `scripts/update_client.sh`.
- **Notifications/Sound**: Konfigurierbar per `SKD_NOTIFY_SEND_PATH`, `SKD_SOUND_PLAYER`, `SKD_SOUND_FILE`.

## Spezifikationen
- Update-Service OpenAPI: `docs/architecture/openapi.yaml` und `docs/architecture/openapi/`.

## Weitere Dokumente
- Entwicklung: `docs/DEVELOPMENT.md`
- Deployment: `docs/DEPLOYMENT.md`