cesnimda
4ce2df0a2b
CI / backend (push) Successful in 52s
CI / frontend (push) Successful in 14s
Deploy Staging / deploy (push) Successful in 18s
CI / backend (pull_request) Successful in 52s
CI / frontend (pull_request) Successful in 15s
Security / secrets (push) Successful in 4s
Security / dependencies (push) Successful in 55s
Security / secrets (pull_request) Successful in 4s
Security / dependencies (pull_request) Successful in 54s
46 lines
2.8 KiB
Markdown
46 lines
2.8 KiB
Markdown
# 05 — Admin System (Part 4)
|
|
|
|
An Admin-only panel to run the instance. **Admins manage the platform, not people's
|
|
inboxes** — no admin route can read another user's mail (see [06](06-security-model.md)).
|
|
|
|
## Sections
|
|
| Section | Admin can | Notes |
|
|
|---------|-----------|-------|
|
|
| **Users** | List users; view role/status/last-login; **promote/demote** (Admin↔Member); **suspend/reactivate**; **revoke sessions**; remove user (with data-deletion policy) | **Never** view a user's email contents |
|
|
| **Feature flags** | List all flags; toggle `enabled`; set scope/rollout; per-role rollout | Includes AI + provider flags |
|
|
| **AI (global)** | Master `ai.enabled` toggle + per-feature (`ai.summaries`, `ai.semantic_search`, `ai.ask_inbox`…); see Ollama/model status | Off ⇒ AI hidden for everyone ([04](04-settings-and-flags.md)) |
|
|
| **Providers** | Enable/disable `provider.google` / `provider.microsoft` / `provider.imap` | Disabled ⇒ hidden on login picker; existing accounts pause |
|
|
| **System config** | Maintenance mode (off/read-only/locked); `registration_open`; org name; default theme; retention | Sensitive → step-up + audit |
|
|
| **Monitoring** | Basic health overview (below) | Read-only |
|
|
| **Audit log** | Search/filter admin + security events | Append-only |
|
|
|
|
## Monitoring overview (basic)
|
|
- **Sync health:** per-account last-sync time, `ReauthNeeded` count, error rate; job-queue depth.
|
|
- **AI/Ollama:** reachable? loaded models, VRAM headroom, recent latency, failure rate.
|
|
- **Sessions:** active session count; recent logins.
|
|
- **System:** DB size / message count; background-job backlog; recent errors (from Serilog).
|
|
- Deliberately **overview-only** — deep observability is a future opportunity, not v1.
|
|
|
|
## Access control & bootstrap
|
|
- Every admin route requires the **Admin policy**; sensitive mutations require **confirmation/
|
|
step-up** + are **rate-limited** and **audited**.
|
|
- **Bootstrap:** the first user to sign in becomes **Admin** (one-time). Afterwards, admin is
|
|
granted only by an existing Admin (audited, forces target session refresh so new/removed
|
|
privileges take effect immediately).
|
|
- Guardrails: an Admin cannot demote/suspend the **last remaining Admin** (lock-out prevention).
|
|
|
|
## Audit logging (what's recorded)
|
|
Actor · action · target (user/flag/setting/provider) · old→new · ip · timestamp — for **all**
|
|
admin mutations and security events (role change, flag toggle, provider disable, maintenance
|
|
on/off, session revoke, user suspend). Append-only `audit_logs`; visible in the Audit section;
|
|
exportable.
|
|
|
|
## API surface (Admin-scoped, all audited)
|
|
```
|
|
GET/PATCH /admin/users /admin/users/{id}/role /admin/users/{id}/status
|
|
GET/PATCH /admin/flags /admin/flags/{key}
|
|
GET/PATCH /admin/system-settings
|
|
GET /admin/monitoring /admin/audit
|
|
```
|
|
All behind the Admin policy + maintenance-aware middleware.
|