diff --git a/docs/superpowers/specs/2026-06-14-accounts-sessions-restart-design.md b/docs/superpowers/specs/2026-06-14-accounts-sessions-restart-design.md new file mode 100644 index 0000000..63e636c --- /dev/null +++ b/docs/superpowers/specs/2026-06-14-accounts-sessions-restart-design.md @@ -0,0 +1,113 @@ +# 0.9.0 — Accounts, Sessions, Auto-Restart, SMTP, Audit-Retention — Design + +**Date:** 2026-06-14 · **Branch:** `feat/v1-foundation` · **Status:** approved (build all, then release 0.9.0) + +Operator-approved scope + decisions: +- **Multi-User:** additional accounts are **all equal admins** (no RBAC). The audit log already records + the actor, so "who did what" is covered. +- **Sessions:** active-session list + **per-user** and **global** "log out everywhere", remember-token + rotation. Requires switching the session store to the database (see §2). +- **Auto-Restart:** a **restart sentinel** — the app writes a request file, a host-side watcher + restarts the stack. No Docker socket in the container. +- **Settings extras:** **SMTP configuration** + **Audit-log retention** (no theme, no API tokens now). + +Foundational refactor (enables clean parallel work + scalable Settings): + +## §0. Settings → per-tab nested Livewire components +`Settings\Index` currently inlines Profil + Sicherheit in one big Blade with a `$tab` switch. Refactor +the tab bodies into **nested full components** so each area is isolated, testable, and independently +ownable: +- `Settings\Profile` (name/email/password — lift the existing profile + password forms out of Index). +- `Settings\Security` (the 2FA/TOTP card + recovery modal trigger + ``). +- New `Settings\Users`, `Settings\Sessions`, `Settings\Email` (§3/§2/§4). +`Settings\Index` keeps only: the identity header, the `#[Url] $tab` tab nav (now: Profil · Sicherheit +· Benutzer · Sitzungen · E-Mail), and `@if($tab===…) @endif`. The `tabs` array +gains the new keys + icons (`user-plus`, a sessions icon, `mail`). Each nested component owns its own +state/validation/audit — no more one-giant-class. + +## §1. Auto-restart sentinel +Goal: replace the manual `docker compose -f docker-compose.prod.yml restart` notice with a one-click, +self-applying restart — without giving the container the Docker socket. +- **App:** `DeploymentService::requestRestart()` writes a sentinel file to a path on a **bind-mounted + shared volume** the host watches, e.g. `storage/app/restart.request` mapped to a host dir (or a + dedicated `./run/restart.request`). `restartRequested(): bool` checks it exists. +- **Host watcher (installed once by `install.sh`/documented):** a tiny script + **systemd path unit** + (`clusev-restart.path` → `clusev-restart.service`) that, when the sentinel appears, runs + `docker compose -f docker-compose.prod.yml restart` (or `up -d`) in the project dir and deletes the + sentinel. Ship the unit files + script under `docker/restart-sentinel/` + wire `install.sh`. +- **UI:** the "Neustart erforderlich" block loses the raw command; instead a button **"Jetzt neu + starten"** → `requestRestart()` → shows "Neustart wird ausgeführt …". If the host watcher isn't + installed (sentinel lingers > N s), fall back to a muted "falls nichts passiert: `… restart` auf dem + Host" hint. Domain/TLS/mode saves call `requestRestart()` automatically per operator confirm. +- Files: `app/Services/DeploymentService.php` (+ maybe `RestartService`), `docker/restart-sentinel/*`, + `install.sh`, `docker-compose.prod.yml` (the shared sentinel volume), the System view, lang/system. + +## §2. Database sessions + session management +- **Switch the session store to the database** so sessions are per-row + enumerable. Add the standard + Laravel `sessions` table migration (id, user_id, ip_address, user_agent, payload, last_activity). + Set `SESSION_DRIVER=database` in `.env`/`.env.example`/compose. **One-time effect:** existing Redis + sessions are dropped → everyone re-logs-in once (documented in the changelog + the restart notice). + Redis stays the cache/queue store. Register `Illuminate\Session\Middleware\AuthenticateSession` so + password changes invalidate other sessions. +- **`Settings\Sessions` component:** lists the current user's active sessions from the `sessions` table + (this device flagged; ip, user-agent summarized, last activity relative). Actions: + - **"Andere Geräte abmelden"** (self): delete the user's other session rows + `Auth::logoutOtherDevices` + pattern (rotate so other sessions die), keep the current one. + - **(Admin) "Diesen Account überall abmelden"** per listed user (in `Settings\Users`): delete all that + user's session rows + rotate their `remember_token`. + - **(Admin) "Alle abmelden (global)"**: truncate `sessions` + rotate every user's `remember_token` + (logs everyone out incl. self). Confirm via wire-elements/modal (R5), audited. +- Files: migration, `app/Livewire/Settings/Sessions.php` + view, `app/Services/SessionService.php` + (the delete/rotate logic, testable), `bootstrap/app.php` (AuthenticateSession), `.env*`/compose, + `lang/{de,en}/settings.php`. + +## §3. Multi-user accounts (all equal admins) +- **`Settings\Users` component:** lists all users (name, email, 2FA badge, last login if available); + **create** (name, email unique, a generated temp password shown once + `must_change_password=true` + so the new admin rotates on first login); **remove** (R5 modal; cannot remove yourself or the last + remaining user). Each action audited (`user.create` / `user.delete`, actor = current). Per-row + **"überall abmelden"** (→ §2). All created users are full admins (no role column needed now). +- New-user password: generate a strong temp password, show once in a modal (like recovery codes), do + NOT email it unless SMTP configured (then offer "Zugangsdaten per E-Mail senden"). +- Files: `app/Livewire/Settings/Users.php` + view, maybe `app/Livewire/Modals/CreateUser.php` for the + temp-password reveal, `lang/{de,en}/settings.php`. The `User` factory/model already suffices. + +## §4. SMTP configuration +- **`Settings\Email` component:** form for host, port, username, password (encrypted Setting), + encryption (none/tls/ssl), from-address, from-name. Persist as `Setting` keys (`mail_*`); the password + via an encrypted Setting. **Apply at runtime** by overriding `config(['mail.*' => …])` in + `AppServiceProvider::boot()` when the settings exist (mirrors the existing reverb override). A + **"Testmail senden"** button sends a test to the current user + surfaces success/failure. When SMTP is + unset, the app stays on the `log` mailer (current behaviour) and forgot-password keeps the 2FA/CLI path. +- Files: `app/Livewire/Settings/Email.php` + view, `app/Providers/AppServiceProvider.php` (runtime mail + override), `lang/{de,en}/settings.php`. Password stored encrypted; never rendered back (show a "set" + placeholder). + +## §5. Audit-log retention +- **Setting `audit_retention_days`** (0/empty = keep forever; default keep-forever). A control in the + Audit page header (or a small Settings block) to set it. A scheduled command **`clusev:prune-audit`** + deletes `audit_events older than N days`; register it on the scheduler (daily). Audited that a prune + ran (count). Files: `app/Console/Commands/PruneAudit.php`, the scheduler (routes/console.php or + Kernel), a control in `audit/index` or `Settings`, `lang`. + +## Security invariants +- New accounts are created by an authenticated admin only; temp password is `must_change_password`. +- Global logout / per-user logout rotate `remember_token` so stolen cookies die. +- SMTP password stored encrypted (APP_KEY), never rendered, never logged. +- The restart sentinel grants NO new container privilege (no Docker socket); the host watcher is the + only thing that can restart, scoped to the project dir. +- Cannot delete yourself or the last admin (no lock-out). +- All destructive actions: wire-elements/modal confirm (R5) + AuditEvent. + +## Testing (per feature, TDD) +- Settings refactor: each nested component renders + its tab loads; Index hosts them by `$tab`. +- Sentinel: `requestRestart()` writes the file, `restartRequested()` reads it; UI button calls it. +- Sessions: list reflects `sessions` rows; per-user logout deletes that user's rows + rotates token; + global logout truncates + rotates all; self "other devices" keeps current. +- Users: create makes a `must_change_password` admin + audits; cannot delete self/last; remove audits. +- Email: settings persist (password encrypted), runtime override applies, test-send path. +- Retention: prune deletes only old rows, keeps recent; command is scheduled. +- Full suite green, Pint, Codex clean, R12 (DE+EN, 3 breakpoints), then bump + tag **v0.9.0**. + +## Out of scope (later) +- RBAC/roles, API tokens, theme preference, per-event audit export, email templates beyond the test.