stephan/kiddo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: overhaul repository documentation

Browse Source
This commit is contained in:
Stephan Wilkens
2026-01-15 08:54:52 +01:00
parent c41482a7b3
commit 10ec58f744
22 changed files with 575 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
README.md
View File

@ -1,121 +1,61 @@
ID: README_000001 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)
# Safe Kiddo Daemon
Service to lock/unlock local user accounts on kids' laptops with countdown, notifications, optional sound, and shutdown. Provides a REST API plus a small web UI for remote control; retains the original `sk.sh` script as legacy/CLI fallback.
## Kurzbeschreibung
Safe Kiddo Daemon ist ein lokaler Systemdienst, der Benutzerkonten auf Linux-Systemen sperrt/entsperrt, Sitzungen beendet und optional einen Shutdown ausloest. Der Dienst bietet eine REST-API und eine Web-UI fuer die Fernsteuerung. Ein Legacy-CLI-Script (`sk.sh`) bleibt als Fallback erhalten.
## Features
- Disable/enable accounts, terminate sessions, optionally trigger shutdown.
- Desktop notifications and optional sound during countdown.
- Login-protected API with minimal web UI (PAM auth for root users, bearer token for calls).
- Systemd-managed service, virtualenv-based deploy, remote update script.
- Dry-run mode to validate flows without touching accounts.
## Zielgruppe
- Einsteiger: moechten den Dienst schnell installieren und erste Aktionen ausfuehren.
- Admins/Operatoren: konfigurieren Auth, OIDC und Update-Mechanik.
- Entwickler: verstehen Architektur, Module und Erweiterungspunkte.
## Quick Start (Local/Target Device)
## Hauptfunktionen
- Sperren/Entsperren lokaler Nutzerkonten inkl. Session-Management und optionalem Shutdown.
- Benachrichtigungen und optionaler Sound waehrend Countdown.
- PAM-Login (immer aktiv) und optionaler OIDC-Login.
- Systemd-Service mit Installations- und Update-Skripten.
- Update-Client-Integration (Enrollment, Manifest, Apply, Rollback, Logs).
- Dry-Run-Modus zum sicheren Testen.
## Badges
Derzeit keine offiziellen Badges, da im Repository keine CI, Coverage, Release oder Docker-Pipeline definiert ist.
## Quickstart (5 Minuten)
```bash
git clone <repo> /opt/sk
# 1) Repo holen
sudo mkdir -p /opt/sk
sudo git clone ssh://git@git.wlkns.org:2222/stephan/kiddo /opt/sk
# Hinweis: verwende hier die Repo-URL deiner Instanz
cd /opt/sk
# 2) Installieren (legt User, env und Systemd-Unit an)
./scripts/install.sh
# 3) Status pruefen
sudo systemctl status skd.service
# 4) Login testen (PAM)
curl -s -X POST -H "Content-Type: application/json" \
-d '{"username":"root","password":"example-password"}' \
http://localhost/login
```
Then open `http://localhost/` and log in via PAM (default) to start quickly.
Danach die Web-UI unter `http://localhost/` oeffnen und anmelden.
## Configuration
Set in `/etc/skd/env` (see `env.example`):
- PAM-Login ist immer aktiv. OIDC wird zusaetzlich angeboten, wenn konfiguriert.
- `SKD_AUTH_SECRET`: HMAC secret for bearer tokens/cookies (set a strong value).
- `SKD_TOKEN_TTL_SECONDS`: token lifetime (default 900s).
- `SKD_AUTH_ALLOWED_USERS`: optional comma list of accounts allowed to log in (used for PAM and as an allowlist for OIDC claims).
- `SKD_AUTH_ALLOWED_GROUPS`: groups whose members may log in (PAM only, default `sudo`).
- `SKD_AUTH_PAM_SERVICE`: PAM service name; Ubuntu/Debian uses `/etc/pam.d/skd` (created by `scripts/install.sh`), other distros may prefer `login` or `sshd`.
- `SKD_OIDC_*`: `ISSUER`, `CLIENT_ID`, `CLIENT_SECRET`, `REDIRECT_URI`, `SCOPES` to point at your OIDC provider; set `SKD_SESSION_COOKIE_SECURE=true` for HTTPS.
- OIDC dynamic registration helper: `scripts/register_oidc_client.sh` (requires `OIDC_INITIAL_ACCESS_TOKEN` and `SKD_OIDC_ISSUER`; uses `SKD_OIDC_REDIRECT_URI` for the redirect). Run once during setup if your provider issues initial access tokens for client creation.
- `SKD_ALLOWED_USERS`: optional comma list to limit manageable accounts (must exist on the system).
- `SKD_DEFAULT_COUNTDOWN`, `SKD_DEFAULT_SOUND`, `SKD_NOTIFY_TIMEOUT`: behavior defaults.
- `SKD_DRY_RUN=true` to test without real account changes or shutdown.
- `SKD_SOUND_PLAYER`/`SKD_SOUND_FILE`, `SKD_NOTIFY_SEND_PATH` if defaults differ.
- Update client:
- `SKD_UPDATE_SERVICE_URL` (default `https://update.wlkns.org`)
- `SKD_UPDATE_PROJECT_ID` (default `safe-kiddo-control`)
- `SKD_UPDATE_ENROLL_TOKEN` (one-time enrollment token for `/update/enroll`)
- `SKD_UPDATE_TOKEN` (API token for update service; or load from `SKD_UPDATE_TOKEN_FILE`)
- `SKD_UPDATE_TOKEN_FILE` (default `/var/lib/skd/update_token`)
- `SKD_UPDATE_INTERVAL` (seconds; default 3600)
- `SKD_UPDATE_STATUS_FILE` (default `/var/lib/skd/update_status.json`)
- `SKD_UPDATE_LOG_FILE` (default `/var/lib/skd/update_logs.jsonl`)
Notes:
- `./scripts/install.sh` will create `/etc/skd/env` from `env.example` if missing (edit afterwards) and ensure the `skd` service user/group exist.
## Dokumentation
- Einstieg und erster Lauf: `docs/GETTING_STARTED.md`
- Nutzung (API, Web-UI, CLI): `docs/USAGE.md`
- Konfiguration (ENV-Variablen): `docs/CONFIGURATION.md`
- Architektur und Module: `docs/ARCHITECTURE.md`
- Entwicklung: `docs/DEVELOPMENT.md`
- Deployment & Betrieb: `docs/DEPLOYMENT.md`
- FAQ: `docs/FAQ.md`
- Troubleshooting: `docs/TROUBLESHOOTING.md`
## OIDC Setup
OIDC ist optional. PAM bleibt immer verfuegbar; `SKD_AUTH_MODE` ist optional.
1. Issuer muss der externen URL des Providers entsprechen (TLS trust erforderlich).
2. OIDC Client registrieren (DCR), z.B.:
```bash
export SKD_OIDC_ISSUER="https://auth.example.org"
export SKD_OIDC_REDIRECT_URI="https://<device-host>/login/oidc/callback"
export OIDC_INITIAL_ACCESS_TOKEN="<initial-access-token>"
./scripts/register_oidc_client.sh
```
3. Danach in `/etc/skd/env` setzen:
```
SKD_AUTH_MODE=oidc
SKD_OIDC_ISSUER=...
SKD_OIDC_CLIENT_ID=...
SKD_OIDC_CLIENT_SECRET=...
SKD_OIDC_REDIRECT_URI=...
SKD_OIDC_SCOPES=openid profile email
SKD_SESSION_COOKIE_SECURE=true
```
Hinweise:
- Redirect-URI muss exakt sein (keine Wildcards).
- Bei Host/Port-Aenderung neu registrieren und neue Credentials setzen.
- Allowlist fuer OIDC: `SKD_AUTH_ALLOWED_USERS` prueft `preferred_username`, `email` oder `sub`.
## Running
- Service: managed by systemd; `./scripts/install.sh` writes the unit dynamically to `/etc/systemd/system/skd.service` with the current repo path and restarts it (runs as root for PAM).
- Manual run: `./scripts/run.sh` (uses `.venv`, defaults to `0.0.0.0:80`).
- Login (PAM): `curl -X POST -H "Content-Type: application/json" -d '{"username":"root","password":"..."}' http://localhost/login`
- Login (OIDC): open `http://localhost/login/oidc/start` → provider → redirected back with session cookie set.
- Health: `curl -H "Authorization: Bearer <token>" http://localhost/health`
## OIDC Validation & Fallbacks
- Validierungsschritte: `docs/oidc-validation.md` (State, Token-Exchange, Claims, Cookie).
- Falls Discovery/JWKS nicht verfuegbar: OIDC deaktivieren und PAM nutzen.
- Falls DCR nicht verfuegbar: Client manuell im IdP anlegen und `SKD_OIDC_*` setzen.
- Bei Self-Signed TLS: CA im System trusten oder in Dev PAM nutzen.
## API (Bearer token via `/login`)
- `GET /users` → `[{user, logged_in, account_locked}]` (manageable system users; excludes root)
- `POST /users/{name}/disable` with JSON `{countdown?, sound?, message?}`
- `POST /users/{name}/enable`
- `GET /health`
- `GET /me` (returns current user + auth mode when a session/bearer token is present)
Example:
```bash
token=$(curl -s -X POST -H "Content-Type: application/json" -d '{"username":"root","password":"..."}' http://localhost/login | jq -r .token)
curl -X POST -H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-d '{"countdown":90,"sound":true}' \
http://localhost/users/child1/disable
```
## Web UI
Served at `/`. Nutze den Button „Login via OIDC“ (setzt Session-Cookie) oder das PAM-Formular, falls OIDC deaktiviert; danach werden verfügbare System-User angezeigt und Aktionen senden Token/Cookies automatisch.
## Updates
- Remote update via SSH: `ssh user@kid-laptop 'cd /opt/sk && ./scripts/update.sh'` (fetch/reset to `origin/main`, reinstalls deps, restarts service).
- Manual: `git pull && source .venv/bin/activate && pip install -r backend/requirements.txt && sudo systemctl restart skd`
## Deployment (zip/SSH)
- Quick copy: create `sk_deploy.zip` (already in repo root) and unzip on target under `/opt/sk`, then refresh venv deps and restart service.
- Scripted deploy: edit `deploy_hosts.yml` (host/user/port/install_dir/service user/group), then run `./scripts/deploy.sh <host-name>`; accepts JSON configs too. Requires SSH access and `sudo` on target.
- After deploy on target: `sudo -u skd /opt/sk/.venv/bin/pip install -r /opt/sk/backend/requirements.txt && sudo systemctl restart skd.service`
## Security Hardening
- Restrict access to API/Web UI to LAN/VPN; firewall the port.
- Set a strong `SKD_AUTH_SECRET`; rotate tokens by changing the secret.
- Create dedicated `skd` user/group; no login shell.
- Configure sudoers minimally: allow `skd` to run `usermod -L/-U`, `pkill -KILL -u`, `shutdown now`, and sound/notify binaries if needed (no full passwordless sudo).
- Consider mTLS or IP allowlisting for added protection.
## Hinweise
- Abweichung von der Zielstruktur: Die OpenAPI-Spezifikation des Update-Services bleibt unter `docs/architecture/openapi.yaml` und `docs/architecture/openapi/` erhalten.
- Altdokumente liegen unter `docs/_archive/` und sind nicht geloescht.
## Legacy Script
`sk.sh` remains for direct SSH use. Plan to replace its logic with API-backed helpers; keep it as emergency fallback.
Das Script `sk.sh` bleibt als CLI-Fallback. Details und Beispiele: `docs/USAGE.md`.