Files
Khaemhat/docs/wiki/Licenze-e-moduli.md
T
Alby96andClaude Opus 5.5 032c602b49
CI / Build and test (SQLite) (pull_request) Successful in 55s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Failing after 2m4s
feat: system and security - start-up, accounts, sign-in, licences, log, jobs, companies (M2)
The instance now starts on its own from KHAEMHAT_* variables: it migrates the system
and company databases, creates the super user and the first company, and only then
reports ready. Users sign in with password and TOTP through revocable database
sessions, and licences decide which modules and how many companies are available.

- Configuration: every wrong variable reported at once (exit code 2), _FILE variants
- Accounts, password policy and lockout, TOTP with recovery codes, session states
  with token rotation, security audit with a hash chain
- Sign-in pages (mockups 001-003), authorization attributes, security headers and a
  CSP without inline scripts, login rate limit
- Signed licences, activation codes, test mode, licence tool
- DataProtection keys in the system database, encrypted with the instance key
- Memory or Redis cache (in-house RESP client) that falls back to memory
- Database log by section with trace id; cron scheduler with locks and system jobs;
  record history (audit_log)
- Company creation, states, company context and X-Company, 503 in maintenance
- In-memory SQLite databases stay alive for the process (tests, demo)
- Tests for all of the above, ADR 0019, wiki, SECURITY, CHANGELOG, STATUS, DATA-MODEL

Refs #15 #16 #17 #18 #19 #20 #21 #22 #23 #24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 15:29:24 +01:00

8.9 KiB

Licenze e moduli

Stato: parziale · Ultima revisione: 2026-11-11 · Versione software: 0.2.0 (milestone M2) Modulo di licenza: CORE · Livello richiesto: super utente (attivazione); amministratore (consultazione) · Specifica: SPEC §1.8, §6, §8, §12.2

Nella versione 0.2.0 ci sono verifica e applicazione della licenza: trial di 60 giorni, file .khl firmati (ECDSA P-256) da KHAEMHAT_LICENSE o caricati, codici di attivazione dei moduli, modalità test con i codici fittizi, controllo orario della scadenza con notifiche, limite di aziende e di utenti contemporanei. La schermata Licenze e moduli arriva in M12.

A cosa serve

Khaemhat è diviso in moduli attivabili con licenza. La pagina Licenze e moduli mostra la licenza dell'istanza, i moduli attivi e non attivi, gli utenti concorrenti consentiti e la scadenza, e permette al super utente di caricare una licenza o attivare un modulo con un codice di attivazione.

Dove si trova

Amministrazione → Licenze e moduli. L'attivazione di moduli e licenze è possibile solo da questa pagina e solo per il super utente: gli amministratori non possono attivare moduli né caricare licenze.

Schermata

080 · Amministrazione · licenze e moduli attivabili con codice

Mockup 080 — riepilogo della licenza (licenziatario, utenti, scadenza) e badge "Modalità test"; campo Codice di attivazione con selettore dell'azienda e pulsante Attiva; una scheda per ognuno dei 13 moduli con codice, contenuto e stato (Attivo / Non attivo con Attiva con codice); in fondo lo Storico attivazioni (anteprima ridotta)

Nella parte alta compaiono Attiva con codice e Carica licenza .khl, il riepilogo "N di 13 moduli attivi · utenti concorrenti usati/consentiti · scadenza" e, nella barra del titolo, la licenza in uso (es. Khaemhat Demo S.r.l. · 25 utenti · valida fino al 31/12/2027).

I moduli

Codice Modulo Contenuto
CORE Base anagrafiche, articoli e listini, preventivi/ordini/DDT/fatture, acquisti base, magazzino, tabelle, report base, amministrazione, allegati
ACCT Contabilità piano dei conti, causali, prima nota, partitari, registri IVA, liquidazioni, dati LIPE/F24, ritenute e casse, bollo, chiusura esercizio, bilancio CEE
ASSET Cespiti registro beni ammortizzabili, ammortamenti, dismissioni
FIN Tesoreria scadenzario, incassi/pagamenti, RiBa/SDD/SEPA, riconciliazione bancaria, solleciti, flusso di cassa
EINV Fatturazione elettronica XML attivo/passivo, canali SDI (PEC integrata, SdICoop, intermediari), notifiche, autofatture, dichiarazioni d'intento, bollo virtuale
INTRA Intrastat elenchi cessioni/acquisti e file per l'Agenzia delle Dogane
CRM CRM lead, pipeline/opportunità, attività e agenda, campagne, ticket
SVC Servizi contratti di assistenza, squadre, interventi, rapportini
CHAN Canali e-commerce connettore generico, ordini web, sincronizzazione giacenze/prezzi
AUTO Automazioni regole quando → se → allora, procedure pianificabili oltre quelle di sistema
API Integrazioni API REST, MCP, webhook, chiavi API
MULTI Multi-azienda aziende oltre la prima sulla stessa istanza
REPORT Report avanzati margini, analisi, report pianificati, export per il commercialista

Cosa succede senza un modulo

Se un modulo non è attivo:

  • le sue voci di menu sono nascoste;
  • le sue API e i suoi tool MCP non sono registrati;
  • le sue procedure non sono eseguibili (anche da attività programmate o regole);
  • i dati già presenti sono conservati: riattivando il modulo tornano disponibili.

Per il server un modulo non licenziato equivale a un permesso negato (codice di errore module_not_licensed): anche chi conosce l'indirizzo di una pagina o di un'API non può usarla.

Trial

Se l'istanza non ha una licenza (variabile KHAEMHAT_LICENSE assente e nessuna licenza caricata) funziona in Trial:

Voce Trial
Moduli CORE + ACCT
Utenti concorrenti 3
Durata 60 giorni
Segnalazione banner in tutte le pagine

La licenza di istanza (file .khl)

La licenza è un file .khl: un documento JSON firmato digitalmente (ECDSA P-256) che contiene:

Campo Significato
licensee licenziatario
instanceId istanza a cui la licenza è legata (facoltativo)
issuedAt / expiresAt data di emissione e di scadenza
maxConcurrentUsers utenti concorrenti consentiti
maxCompanies numero massimo di aziende
modules[] moduli inclusi
gracePeriodDays giorni di grazia dopo la scadenza

Si carica in due modi:

  1. dalla pagina, con Carica licenza .khl (solo super utente);
  2. dal container, mettendo il testo della licenza nella variabile KHAEMHAT_LICENSE.

La firma è verificata offline con la chiave pubblica incorporata nel programma: non serve connessione a Internet. Un file modificato anche di un solo carattere viene rifiutato.

Codici di attivazione

Un singolo modulo si può attivare con un codice di attivazione, verificato offline. Il formato dei codici definitivi è:

KH<v>-<MODULO>-<AAAAMM>-<payload base32>-<firma>

dove <v> è la versione del formato, <MODULO> il codice del modulo e <AAAAMM> l'anno e mese di riferimento.

Come si attiva un modulo

  1. Apri Amministrazione → Licenze e moduli come super utente.
  2. Premi Attiva con codice (in alto, oppure sulla scheda del modulo non attivo).
  3. Incolla il codice nel campo Codice di attivazione; nel campo Azienda il mockup propone Tutte le aziende dell'istanza (l'eventuale attivazione per singola azienda sarà definita in sviluppo).
  4. Premi Attiva. Se il codice è valido la scheda del modulo diventa Attivo e l'attivazione compare nello Storico attivazioni (con data, utente e codice).

In futuro è previsto un servizio di attivazione online (attivazione e disattivazione da remoto, controllo periodico); oggi l'attivazione è solo offline.

Verifica, scadenza e periodo di grazia

  • La licenza viene verificata all'avvio, a ogni accesso e ogni ora.
  • Il numero di utenti concorrenti è contato sulle sessioni attive di tutte le aziende dell'istanza: oltre il limite un nuovo accesso viene rifiutato (vedi Utenti e permessi).
  • Superata la scadenza più i giorni di grazia, l'istanza passa in sola lettura con un banner: i dati si consultano ma non si registrano nuove operazioni fino al rinnovo.
  • Lo stato della licenza compare anche in Stato sistema (controllo Licenza).

Modalità test e codici fittizi

Per lo sviluppo, i test e le dimostrazioni esistono codici fittizi fissi, accettati solo se il container è avviato con KHAEMHAT_LICENSE_MODE=test. In questa modalità la pagina mostra il banner "licenze fittizie". In produzione (KHAEMHAT_LICENSE_MODE=production, il valore predefinito) questi codici sono rifiutati con l'errore license_test_only.

Codice fittizio Effetto
KH-TEST-CORE-0000-0001 modulo CORE
KH-TEST-ACCT-0000-0002 modulo ACCT
KH-TEST-ASSET-0000-0003 modulo ASSET
KH-TEST-FIN-0000-0004 modulo FIN
KH-TEST-EINV-0000-0005 modulo EINV
KH-TEST-INTRA-0000-0006 modulo INTRA
KH-TEST-CRM-0000-0007 modulo CRM
KH-TEST-SVC-0000-0008 modulo SVC
KH-TEST-CHAN-0000-0009 modulo CHAN
KH-TEST-AUTO-0000-0010 modulo AUTO
KH-TEST-API-0000-0011 modulo API
KH-TEST-MULTI-0000-0012 modulo MULTI
KH-TEST-REPORT-0000-0013 modulo REPORT
KH-TEST-ALL-0000-9999 tutti i moduli (usato dai test automatici)
KH-TEST-USERS-0025-0014 25 utenti concorrenti
KH-TEST-TRIAL-0060-0015 proroga del Trial di 60 giorni

Attenzione: non avviare mai un'installazione reale con KHAEMHAT_LICENSE_MODE=test. La modalità test è segnalata anche in Stato sistema.

Domande frequenti

  • Ho attivato un modulo ma non vedo il menu. Oltre alla licenza servono i permessi: controlla i ruoli dell'utente in Utenti e permessi.
  • Cosa succede ai dati se disattivo un modulo o la licenza scade? I dati restano nel database; tornano utilizzabili quando il modulo è di nuovo attivo.
  • Posso creare una seconda azienda in Trial? No: le aziende oltre la prima richiedono il modulo MULTI (vedi Istanza e database).
  • Chi emette le licenze? Il titolare del progetto, con uno strumento separato che custodisce la chiave privata di firma, mai pubblicata.

Pagine correlate

Istanza e database · Utenti e permessi · Stato sistema · Installazione con Docker · Primi passi · FAQ