Changeset 0.28.0.1 (#173)

2026-03-11 14:45:37 +00:00
parent 93c72daadf
commit 58313f7e31
57 changed files with 5139 additions and 3206 deletions
--- a/docs/ICD/admin.md
+++ b/docs/ICD/admin.md
@@ -0,0 +1,198 @@
+# Platform Administration
+
+Cross-cutting admin operations that don't belong to a specific domain.
+
+### User Management
+
+```
+GET    /admin/users                  → { "users": [...] }
+POST   /admin/users                  ← { "username", "password", "email", "role" }
+PUT    /admin/users/:id/role         ← { "role": "admin|user" }
+PUT    /admin/users/:id/active       ← { "active": false }
+DELETE /admin/users/:id
+POST   /admin/users/:id/reset-password  ← { "new_password": "..." }
+POST   /admin/users/:id/vault/reset     → destroys user's UEK (BYOK keys lost)
+```
+
+### Global Settings & Policies
+
+Settings are key-value pairs in `global_settings`. Policies are
+boolean flags that gate features.
+
+```
+GET /admin/settings                  → all settings
+GET /admin/settings/:key             → single setting
+PUT /admin/settings/:key             ← { "value": ... }
+```
+
+The handler auto-detects: if the value is a string and the key is a
+known policy name, it writes to the `policies` table. Otherwise it
+writes to `global_config` as JSON.
+
+**Public settings** (non-admin, for FE bootstrapping):
+
+```
+GET /settings/public
+```
+
+```json
+{
+  "banner": { "enabled": true, "text": "DEVELOPMENT", "bg": "#007a33", "fg": "#ffffff", "position": "both" },
+  "branding": { "instance_name": "Switchboard", "logo_url": "...", "tagline": "..." },
+  "has_admin_prompt": true,
+  "storage_configured": true,
+  "paste_to_file_chars": 2000,
+  "policies": {
+    "allow_registration": "true",
+    "allow_user_byok": "true",
+    "allow_user_personas": "true"
+  }
+}
+```
+
+### Banner Configuration
+
+The environment banner is stored as a single `global_config` entry
+under the key `"banner"`. It's a simple object:
+
+```json
+{
+  "enabled": true,
+  "text": "DEVELOPMENT",
+  "position": "both|top|bottom",
+  "bg": "#007a33",
+  "fg": "#ffffff"
+}
+```
+
+Set via `PUT /admin/settings/banner` with `{ "value": { ... } }`.
+The admin UI provides a color picker, position selector, and preset
+dropdown. The Go template base layout reads the banner from
+`PageData` and renders top/bottom strips with CSS custom properties.
+
+### Platform Stats
+
+```
+GET /admin/stats
+```
+
+```json
+{
+  "users": 42,
+  "channels": 156,
+  "messages": 12847
+}
+```
+
+### Storage & Vault
+
+**Storage status:**
+
+```
+GET /admin/storage/status            → { "backend", "healthy", "file_count", "total_bytes", ... }
+GET /admin/storage/orphans           → { "count": 3 }
+POST /admin/storage/cleanup          → removes orphaned blobs
+GET /admin/storage/extraction        → extraction queue status
+```
+
+**Vault:**
+
+```
+GET /admin/vault/status              → { "encryption_key_set", "user_vaults_count", ... }
+```
+
+### Audit Log
+
+```
+GET /admin/audit?page=1&per_page=50&action=user.create&actor_id=uuid
+GET /admin/audit/actions             → { "actions": ["user.create", "policy.update", ...] }
+```
+
+Audit entry:
+
+```json
+{
+  "id": "uuid",
+  "actor_id": "uuid",
+  "action": "user.create",
+  "resource_type": "user",
+  "resource_id": "uuid",
+  "metadata": {},
+  "created_at": "..."
+}
+```
+
+### Usage & Pricing
+
+```
+GET /admin/usage                     → { "totals", "results" }
+GET /admin/usage/teams/:id           → team-specific usage
+GET /admin/usage/users/:id           → user-specific usage
+GET /admin/pricing                   → { "data": [...] }
+PUT /admin/pricing                   ← { "provider", "model", "input_per_m", "output_per_m" }
+DELETE /admin/pricing/:provider/:model
+```
+
+**Personal usage** (non-admin):
+
+```
+GET /usage                           → { "totals", "results" }
+```
+
+Scoped to the user's BYOK provider usage only.
+
+### Roles (Platform)
+
+```
+GET    /admin/roles                  → { "roles": [...] }
+GET    /admin/roles/:role
+PUT    /admin/roles/:role            ← { "permissions": {...} }
+POST   /admin/roles/:role/test       ← test role permissions
+```
+
+### Email Test
+
+```
+POST /admin/notifications/test-email
+```
+
+```json
+{ "to": "admin@example.com" }
+```
+
+Sends a test email using the configured SMTP settings.
+
+---
+
+### Archived Channels
+
+```
+GET    /admin/channels/archived      → { "data": [...] }
+DELETE /admin/channels/:id/purge     → permanent delete (ignores retention)
+```
+
+**Auth:** Platform admin.
+
+### Surfaces Admin
+
+See [surfaces.md](surfaces.md) for the full surface management API.
+
+```
+GET    /admin/surfaces               → all surfaces (including disabled)
+GET    /admin/surfaces/:id           → surface with manifest
+POST   /admin/surfaces/install       ← multipart .surface archive
+PUT    /admin/surfaces/:id/enable
+PUT    /admin/surfaces/:id/disable
+DELETE /admin/surfaces/:id
+```
+
+### Tasks Admin
+
+See [tasks.md](tasks.md) for the full task management API.
+
+```
+GET    /admin/tasks                  → all tasks across all users/teams
+POST   /admin/tasks/:id/run          → force run
+POST   /admin/tasks/:id/kill         → cancel active run
+DELETE /admin/tasks/:id              → delete task
+```