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

dwh-auth: guida server

dwh-auth autentica la route REST /dwh/ con una chiave per installazione. È un componente Linux opzionale e server-side: usa systemd, non tht né Docker Compose, non legge risultati clinici e non si collega a PostgreSQL. La chiave serve solo a rest_api; postgres_direct e ssh_tunnel non la usano.

Prerequisiti e confini

• Usare un checkout revisionato, Docker per la build e un operatore autorizzato sul server DWH.
• Una chiave identifica un'installazione, non una persona. L'installation-id è unico, non personale e senza dati clinici.
• Chiavi, digest, file di consegna e backup restano in file protetti: mai Git, argv, variabili d'ambiente, log, JSON pubblico o evidenze.
• Preparare backup e rollback prima di Nginx. Installare il servizio non autorizza una modifica della route pubblica.

Percorsi, owner e mode

Oggetto	Percorso	Owner e mode
Binario	/usr/local/sbin/dwh-auth	root:root, 0755
Unit	/etc/systemd/system/dwh-auth.service	root:root, 0644
Tmpfiles	/usr/lib/tmpfiles.d/dwh-auth.conf	root:root, 0644
Registro, active, revoked	/var/lib/dwh-auth/	root:dwh-auth, 2750
Lock	/var/lib/dwh-auth/.writer.lock	root:dwh-auth, 0640
Record	/var/lib/dwh-auth/{active,revoked}/<public-key-id>.json	root:dwh-auth, 0640
Socket runtime	/run/dwh-auth/verify.sock	dwh-auth:www-data, 0660
Consegne e backup	/root/dwh-auth-provision/	directory root:root 0700, file 0600

Il record conserva un digest interno (secret_sha256) e metadati, mai la chiave in chiaro. Non leggere, stampare, calcolare o mettere quel digest in una prova operativa.

Build, installazione e avvio

Costruire dal commit congelato e registrare solo checksum del binario e SHA sorgente:

cd /srv/thothii/app
bash scripts/build-dwh-auth.sh --output /tmp/dwh-auth-release
sha256sum /tmp/dwh-auth-release/dwh-auth-linux-amd64

Scegliere l'architettura corretta. Il template PSD usa il gruppo Nginx www-data; confermarlo prima dell'installazione su un host diverso.

sudo groupadd --system dwh-auth
sudo useradd --system --no-create-home --shell /usr/sbin/nologin --gid dwh-auth dwh-auth
sudo install -o root -g root -m 0755 /tmp/dwh-auth-release/dwh-auth-linux-amd64 /usr/local/sbin/dwh-auth
sudo install -o root -g root -m 0644 deploy/dwh-auth/dwh-auth.service /etc/systemd/system/dwh-auth.service
sudo install -o root -g root -m 0644 deploy/dwh-auth/dwh-auth.tmpfiles.conf /usr/lib/tmpfiles.d/dwh-auth.conf
sudo install -d -o root -g root -m 0700 /root/dwh-auth-provision
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/dwh-auth.conf
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth check
sudo systemd-analyze verify /etc/systemd/system/dwh-auth.service
sudo systemctl daemon-reload
sudo systemctl enable --now dwh-auth
sudo systemctl status dwh-auth --no-pager

Controllare i mode con stat. Il servizio apre il registro in sola lettura e crea solo il socket. Non creare JSON, lock o socket a mano: oggetti insicuri devono fallire chiusi.

Check, elenco e stato

Usare sempre un root assoluto. Questi comandi espongono solo ID pubblici, stato, date e scadenza:

sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth check
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key list --json
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key status --key-id <public-key-id> --json

Un errore di integrità, permessi, symlink o JSON malformato richiede ripristino da backup protetto, non una correzione manuale del record.

Creazione, consegna, scadenza e revoca

Il comando crea la chiave una volta in un nuovo file assoluto 0600; stdout contiene solo ID pubblico, installazione e percorso. Il file di output non deve esistere.

sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key create \
  --installation-id <installation-id> \
  --description <metadato-non-segreto> \
  --output /root/dwh-auth-provision/<installation-id>-<generation>.key

Aggiungere --expires-at <RFC3339-UTC> solo se la policy impone una scadenza; il default è nessuna scadenza. Consegnare il file solo con vault aziendale, secret manager, MDM o trasferimento autenticato ristretto. Mai email, chat, ticket, cat o copia-incolla. Il client conferma ID pubblico e ping, poi il materiale temporaneo viene rimosso secondo policy.

L'import legacy è temporaneo PSD: il file sorgente è già root:root 0600 e non viene mai letto o stampato dall'operatore.

sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key import \
  --legacy-raw --installation-id legacy-shared \
  --from-file /root/dwh-auth-provision/legacy-shared.key

Per rotare: creare seconda generazione, consegnarla, configurarla e provare /rpc/ping; confermare l'ID pubblico; attendere l'osservazione; poi revocare la precedente e provare nuova=successo, precedente=401.

sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key revoke \
  --key-id <previous-public-key-id> --reason <non-secret-reason>

La revoca non è annullabile e un ID revocato non si ricrea.

Backup, rollback e disinstallazione

Prima di mutare, creare un archivio cifrato e protetto del registro e copie protette delle sole configurazioni coinvolte. L'archivio contiene digest, quindi è riservato: evidenza ammessa solo percorso, owner, mode, timestamp e checksum dell'archivio. Il rollback dual-key ripristina la route e il servizio revisionati, esegue nginx -t e fa reload solo autorizzato; non ripristina chiavi revocate, PostgreSQL, sessioni legacy, indici Qdrant o cache Ollama.

La disinstallazione richiede autorizzazione esplicita, client REST migrati/revocati e rollback non più necessario. Solo allora disabilitare l'unità; conservare registro e backup fino alla retention approvata. Non inserire dwh-auth in Compose o in tht start/tht stop.

Troubleshooting

Sintomo	Interpretazione e azione
401	Chiave assente, malformata, sconosciuta, scaduta, revocata o errata. Verificare trasporto, ID pubblico e consegna; non cercare dettagli nel messaggio.
503	Servizio, socket o registro non disponibile/sicuro. Controllare systemctl, socket, mode e check; ripristinare il backup approvato.
check fallisce	Integrità del registro non valida. Fermare le scritture, preservare stato e ripristinare; non editare JSON.
TLS fallisce	CA o SAN non validi. Seguire TLS, senza bypass.

Per il rollout PSD con i due gate separati vedere il runbook PSD.