Administration

Guida operativa per amministratori: utenti, ruoli (RBAC), workspace, audit, licenze, backup amministrativi. Tutte le operazioni richiedono authMiddleware + permessi specifici (vedi 04 — API Reference).

Bootstrap admin

Al primo avvio (se SEED_BOOTSTRAP_ADMIN=true), il server crea un admin con credenziali da env (SEED_ADMIN_USERNAME=admin, SEED_ADMIN_PASSWORD=admin123, [email protected]). L'account ha mustChangePassword=true → primo login impone il cambio. Setup wizard via GET /api/system/is-initialized → POST /api/system/initialize.

Sicurezza: cambia immediatamente la password bootstrap e imposta un JWT_SECRET forte in produzione. Il fallback scryptSync(JWT_SECRET, ...) per ENCRYPTION_KEY rende JWT_SECRET materiale critografico — non esporlo.

Utenti — /api/users

Operazione	Endpoint	Permesso
Lista paginata	GET /users	requireAdmin
Dettaglio	GET /users/:id	self/admin
Modifica	PUT/PATCH /users/:id	self/admin (updateUserSchema)
Elimina	DELETE /users/:id	requireAdmin
Avatar	POST/DELETE /users/:id/avatar	JWT (multipart)

Soft-delete: DELETE imposta deletedAt (non rimuove righe). updateUserSchema valida username/email/displayName/customInstructions (system prompt prepend nell'agente).

Ruoli & RBAC — /api/roles

27 permessi definiti in packages/shared/src/constants/permissions.ts (PERMISSION_NAMES). 13 sezioni menu (MENU_SECTIONS, include uploads).

Discrepanza nota: CONTRIBUTING cita "28 permissions" / "12 menu sections" ma il codice ha 27 / 13. La fonte di verità è il codice.

Operazione	Endpoint	Permesso
Sezioni menu visibili	GET /roles/me/menu-sections	JWT
Lista ruoli	GET /roles	requireAdmin
Dettaglio	GET /roles/:roleId	requireAdmin (UUID)
Crea	POST /roles	requireAdmin (createRoleSchema, isDefault=false)
Update	PUT /roles/:roleId	requireAdmin (replace atomico permessi)
Sezioni menu ruolo	PUT /roles/:roleId/menu-sections	requireAdmin
Elimina	DELETE /roles/:roleId	requireAdmin
Assegna/Revoca	POST /roles/assign /revoke	requireAdmin

Ruoli default: admin (tutti i 27 permessi) e user (9 permessi base). "Superuser" coincide con admin. I permessi sono verificati via requirePermission(name) o shortcut requireAdmin. L'assegnazione è many-to-many (UserRole).

Workspaces & Projects

Workspace (/api/workspaces): unità di isolamento per chat, documenti, agent config.

• Creazione: workspace:create + license max_workspaces (Community 3, Enterprise ∞).
• Accesso: requireWorkspaceAccess middleware (WorkspaceAccess join table).
• Soft-delete + restore (PUT /:id/restore).
• Cartelle chat: /:id/folders[/:folderId] + restore.

Project (/api/projects): raggruppa workspace correlati.

• Creazione: project:create + license max_projects.
• Accesso: requireProjectAccess (ProjectAccess).
• Export archivio: GET /:projectId/export (stream).
• Usage stats: GET /:projectId/usage.

Audit / Event Log — /api/event-logs

License audit_log_immutable (Enterprise). GET con filtri type/user/workspace/date/action, paginazione cursor. eventLogService.logEvent è chiamato post-DB (async, non blocca). Entità loggate: user, workspace, mcp_connection, backup, chat, document, license. Quando il flag immutable è attivo, i record non sono modificabili/cancellabili (append-only a livello app).

Licenze

• Community (default): flag limitati (vedi 03 — Configuration).
• Enterprise: LICENSE_KEY (JWT HS256) + LICENSE_SECRET. Payload validato vs licensePayloadSchema. Scaduto/invalido → fallback Community con warn, graceful degradation a runtime (no restart).
• Endpoint: GET /api/license/info (pubblico) → { license, features }.
• Gating: requireFeature(flag) → 402; requireFeatureLimit(flag, model) → 402 se count >= limit (Enterprise = Infinity).

Backup amministrativi

Vedi 05 — Feature Guide § Backup. Endpoint admin:

• Logs /api/system/backups (backup:log:read).
• Destinations /api/backup-destinations (backup:destination:read/write, license max_backup_destinations).
• Jobs /api/backup-jobs (backup:job:read/write), trigger manuale POST /:id/run.
• Restore /api/backups/restore/:logId[/dry-run] (backup:restore:write).
• Test destinazione POST /backup-destinations/:id/test.

Settings — /api/system/settings

GET/PUT bulk (ritorna { updated, rejected }). Gruppi: LLM, Embedding/Vector, porte/URL, Auth, Branding (gated white_label), Feature, OCR, Synthesis, Retention. Chiavi ALWAYS_READONLY rifiutate. Chat retention solo via PUT /api/system/chat-retention (audited, confirmDataLoss: true). Dettagli in 03 — Configuration.

SSO — /api/sso

License sso_enabled. GET/PUT /config, POST /test. Config SAML/OIDC enterprise.

Cross-link

• Permessi/flag: 03 — Configuration
• Endpoint completi: 04 — API Reference
• Deploy operativo: 09 — Deployment