Amministrazione

Guida operativa per amministratori: utenti, ruoli (RBAC), workspace, audit, licenze e backup amministrativi. Tutte le operazioni richiedono authMiddleware più permessi specifici - vedi la API Reference per l'inventario completo degli endpoint.

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

Delete: DELETE è un hard delete con cleanup delle relazioni (UserRole, ProjectAccess, WorkspaceAccess) e invalidazione della auth cache; l'admin non può eliminare sé stesso. updateUserSchema valida username/email/password/firstName/lastName/customInstructions/textSize (le custom instructions sono preposte al system prompt nell'agente); i non-admin non possono cambiare la propria password da questo endpoint.

Ruoli & RBAC - /api/roles

44 permessi definiti in packages/shared/src/constants/permissions.ts (PERMISSION_NAMES). 15 sezioni menu (MENU_SECTIONS, include uploads, skills e plugins).

Ruoli default: admin (tutti i 44 permessi) e user (16 permessi: i 9 base più memory:read/memory:write per le memorie per-utente, skill:create/skill:read/ skill:write/skill:delete per le skill custom e widget:manage; filters:manage è riservato a admin/superuser). "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 entityType/entityId/userId + limit/offset (paginazione). eventLogService.logEvent delega la scrittura al plugin enterprise (no-op in Community) e dispatcha i webhook fire-and-forget. Entità loggate (EntityType, 24 tipi): user, role, workspace, project, chat, document, mcp_connection, mcp_catalog_entry, dlp, archive/archive_page/archive_import, ocr_job, synthesis_run, wiki_edit, skill, upload_draft, chat_connector, widget, quota, backup_destination/backup_job, provider, memory. 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: le licenze sono JWT RS256 (asimmetrico) - la chiave pubblica è embedded nel sorgente server (packages/server/src/services/license-public-key.ts), quindi basta LICENSE_KEY (vendor-issued, nessun segreto env: il vecchio LICENSE_SECRET HS256 di v0.22 è morto con la rotazione asimmetrica). Payload validato vs licensePayloadSchema. Scaduto/invalido → fallback Community con warn, graceful degradation a runtime (no restart).
• Endpoint: GET /api/license/info (pubblico) → { license, features }.
• Slot licenza istanza a runtime (Phase 221, no-.env): **Settings → Security → License** (admin, admin:settings) incolla il JWT vendor RS256. Verifica probe-first (una key rifiutata non viene mai salvata), salvata SOLO come cifrato AES-256-GCM (SystemConfig INSTANCE_LICENSE - il plaintext e il suo cifrato non transitano mai in nessuna response), applicata all'istanza live dallo stesso resolver del boot. Precedenza sorgenti (identica a boot e runtime): slot INSTANCE_LICENSE → riga plugin verificata (licenza enterprise-tier) → ENV LICENSE_KEY → Community.
• API del slot: PUT /api/license/instance ({ licenseKey } → 200 { licenseStatus: "verified", tier, licensee, expiresAt }; rifiuti 400 { error, reason } con reason chiuso invalid/expired/plugin_bound/ community_tier), GET /api/license/instance (surface metadata-only), DELETE /api/license/instance (ripulisce la paste: l'istanza torna a ciò che il NEXT BOOT deriverebbe, parità boot/runtime). La paste deve essere UNCLAIMED (le key plugin-bound agiscono solo come licenza del plugin - il slot istanza le rifiuta con plugin_bound) e solo una ENTERPRISE-tier key può essere salvata (una paste community verrebbe a degradare silenziosamente una env key valida - rifiutata con community_tier). Il canale bulk settings (PUT /api/system/settings) rifiuta la key - la route paste è il suo unico write path.
• 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.

Provenienza v0.28.1

Riferimento operativo - Simmetric Chat v0.28.1 (docs aggiornate 2026-10-02, census SHA `aca5b8ff`).

Cross-link

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