ThothII/docs/install/dwh-auth-client-enrollment.md

Enrollment client per DWH REST

La credenziale dwh-auth appartiene a una installazione ThothII, non a una persona. Serve solo se il trasporto è rest_api; postgres_direct e ssh_tunnel non la usano.

Trasporto	Chiave dwh-auth	Materiale locale
rest_api	Sì, una per installazione.	URL HTTPS, API_KEY_FILE, eventuale TLS_CA_FILE.
postgres_direct	No.	Credenziali PostgreSQL e TLS PostgreSQL.
ssh_tunnel	No.	Credenziali PostgreSQL e materiali SSH; è diagnostico-only nel runtime corrente.

Il ThothII server PSD resta postgres_direct read-only. Il Mac PSD e le installazioni remote usano rest_api; non introdurre un tunnel SSH per aggirare REST.

Prerequisiti

Ricevere chiave e CA, se necessaria, attraverso canali protetti separati. Confermare fuori banda il fingerprint TLS prima dell'uso: guida TLS. Conservare la chiave nel vault o in un file protetto, mai Git, .env con il valore, argv, ambiente, log o evidenze. Annotare solo ID pubblico.

Percorso GUI: vault dell'installazione

1. In Workspace management, eseguire Update workspace repository se necessario e selezionare il workspace.
2. Scegliere rest_api, controllare URL/trust locali e usare Validate workspace.
3. Inserire la chiave nel campo write-only Data warehouse API key, poi Save runtime secrets. La GUI la conserva nel vault cifrato workspace-secrets, non la rileggere né la restituisce.
4. Eseguire Test connections. Il controllo innocuo è /rpc/ping: atteso 2xx e database/schema dichiarati.
5. Comunicare al server solo ID pubblico, timestamp e risultato. Forget rimuove il valore e va usato soltanto dopo conferma di sostituzione o revoca.

Percorso headless: binding reale

API_KEY_FILE significa che il valore è nel file, non nella variabile. Nel file PSD non tracciato workspace-bindings.env i binding effettivi sono:

THT_WS_PSD_CLINICAL_DWH_TRANSPORT=rest_api
THT_WS_PSD_CLINICAL_DWH_BASE_URL=https://supabase-aritmolab.policlinicosandonato.it/dwh/
THT_WS_PSD_CLINICAL_DWH_API_KEY_FILE=/run/secrets/psd-clinical-dwh-api-key
THT_WS_PSD_CLINICAL_DWH_TLS_CA_FILE=/run/secrets/psd-clinical-dwh-ca.pem

Nel file operator.env non tracciato, ogni suffisso _SOURCE indica solo il percorso assoluto del file protetto di origine. Il comando genera un override non tracciato che monta quei file nel core; non installa né avvia dwh-auth con Compose:

bash scripts/generate-connector-secrets-override.sh \
  --bindings-env /absolute/protected/workspace-bindings.env \
  --operator-env /absolute/protected/operator.env \
  --output /absolute/protected/connector-secrets.override.yaml \
  --service core --role dwh

La chiave sorgente è un file regolare 0600 per il solo account autorizzato. Per altri workspace, sostituire PSD_CLINICAL con ID immutabile maiuscolo (trattini in underscore). Vedere anche il protocollo diagnostico.

Ping, rotazione e revoca

Usare solo Test connections su /rpc/ping: successo è 2xx con TLS verificato; il server conferma l'ID con key status. Durante rotazione, ricevere nuova generazione, aggiornare vault o file API_KEY_FILE, ripetere ping, attendere osservazione e far revocare la precedente. Dopo la revoca: nuova positiva, precedente 401.

401 non distingue chiave assente, scaduta o revocata. 503 è un guasto fail-closed di servizio, socket o registro: non usare connessione diretta e non ridurre TLS. Non riattivare una chiave revocata. Il percorso PSD è nel runbook.