80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
ID: DOC_000012 | Version: 0.2.3 | 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`
|