stephan/kiddo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a732a5afc4c77063945595368a1f9f225a510247
kiddo/docs/ARCHITECTURE.md

3.7 KiB
Raw Blame History

ID: DOC_000012 | Version: 0.2.1 | 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

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