first commit

README.md

@@ -0,0 +1,75 @@
+# 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.
+
+## 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.
+
+## Quick Start (Local/Target Device)
+```bash
+git clone <repo> /opt/sk
+cd /opt/sk
+./scripts/install.sh
+sudo systemctl status skd.service
+```
+Then open `http://localhost:8000/` and set the API token in the UI.
+
+## Configuration
+Set in `/etc/skd/env` (see `env.example`):
+- `SKD_AUTH_SECRET`: HMAC secret for bearer tokens (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.
+- `SKD_AUTH_ALLOWED_GROUPS`: groups whose members may log in (default `sudo`).
+- `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.
+Notes:
+- `./scripts/install.sh` will create `/etc/skd/env` from `env.example` if missing (edit afterwards) and ensure the `skd` service user/group exist.
+
+## 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.
+- Manual run: `./scripts/run.sh` (uses `.venv`, defaults to `0.0.0.0:8000`).
+- Login: `curl -X POST -H "Content-Type: application/json" -d '{"username":"root","password":"..."}' http://localhost:8000/login`
+- Health: `curl -H "Authorization: Bearer <token>" http://localhost:8000/health`
+
+## API (Bearer token via `/login`)
+- `GET /users` → `[{user, logged_in}]` (manageable system users; excludes root)
+- `POST /users/{name}/disable` with JSON `{countdown?, sound?, message?}`
+- `POST /users/{name}/enable`
+- `GET /health`
+
+Example:
+```bash
+token=$(curl -s -X POST -H "Content-Type: application/json" -d '{"username":"root","password":"..."}' http://localhost:8000/login | jq -r .token)
+curl -X POST -H "Authorization: Bearer $token" \
+  -H "Content-Type: application/json" \
+  -d '{"countdown":90,"sound":true}' \
+  http://localhost:8000/users/child1/disable
+```
+
+## Web UI
+Served at `/`. Login mit Root-Account, danach werden verfügbare System-User angezeigt; Aktionen senden Bearer Token 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.
+
+## Legacy Script
+`sk.sh` remains for direct SSH use. Plan to replace its logic with API-backed helpers; keep it as emergency fallback.