ThothII/docs/install/dwh-auth-server.md

dwh-auth: guida server

dwh-auth protegge la route REST /dwh/ con una chiave distinta per ogni installazione ThothII. Il componente gira come servizio Linux separato, non legge i dati del DWH e non si collega direttamente a PostgreSQL.

flowchart LR
    CLIENT["Installazione ThothII"] -->|"X-API-Key"| NGINX["Nginx"]
    NGINX --> AUTH["dwh-auth\nUnix socket"]
    AUTH --> REGISTRY["Registro chiavi\nactive e revoked"]
    AUTH -->|"authorized"| REST["DWH REST"]

Confini di sicurezza

• Una chiave identifica un'installazione, non una persona.
• Chiavi e backup restano in file protetti e non entrano in Git, log, argomenti o JSON pubblico.
• Il registro conserva digest e metadati, mai la chiave in chiaro.
• La route REST deve essere esposta esclusivamente tramite TLS verificato.

Installazione

Il servizio usa questi percorsi:

Oggetto	Percorso
Binario	/usr/local/sbin/dwh-auth
Unit systemd	/etc/systemd/system/dwh-auth.service
Registro	/var/lib/dwh-auth/
Socket	/run/dwh-auth/verify.sock
Consegne protette	/root/dwh-auth-provision/

Installare binario e unit con owner root, creare l'utente di servizio dwh-auth, quindi abilitare l'unità con systemctl enable --now dwh-auth. Il socket deve essere accessibile al gruppo usato da Nginx.

Creazione e revoca delle chiavi

Esempio per l'installazione ACME Limited:

sudo dwh-auth --registry-root /var/lib/dwh-auth key create \
  --installation-id acme-factory-primary \
  --description acme-factory-primary \
  --output /root/dwh-auth-provision/acme-factory-primary.key

Consegnare il file attraverso un vault aziendale o un canale autenticato. Per la rotazione, creare una nuova chiave, distribuirla, aggiornare il client e revocare la precedente usando il suo ID pubblico:

sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \
  --key-id PUBLIC_KEY_ID \
  --reason scheduled-rotation

La revoca è definitiva. Conservare backup cifrati del registro prima di ogni mutazione.

Integrazione Nginx

Nginx inoltra la chiave al socket di dwh-auth. Solo una risposta autorizzata permette il passaggio verso il DWH REST; chiavi assenti, sconosciute, scadute o revocate ricevono 401, mentre indisponibilità del servizio o del registro producono 503.