docs: explain per-installation DWH access

2026-08-21 03:58:50 +02:00
parent d0f7e0497d
commit 7b9b8b308d
14 changed files with 551 additions and 0 deletions
@@ -0,0 +1,39 @@
+# Collaudo manuale `dwh-auth`
+
+Eseguire questo collaudo soltanto con consenso ai gate PSD e con dati sintetici. Non eseguire ora
+mutazioni server e non registrare chiavi, digest, certificate body, output Nginx grezzo o risultati
+clinici.
+
+## Precondizioni
+
+- SHA sorgente e checksum binario approvati; registry, lock e record hanno owner/mode attesi.
+- `dwh-auth check`, unit `systemd` e socket Unix sono sani; Nginx viene toccato solo al Gate B.
+- CA `.it` e fingerprint sono confermati fuori banda; nessun `.com` è usato senza SAN valido.
+- Il server ThothII PSD è `postgres_direct`; il Mac/remoti sono `rest_api`.
+
+## Matrice di accettazione
+
+| Caso | Azione autorizzata | Atteso | Evidenza ammessa |
+| --- | --- | --- | --- |
+| Registro | `check`, `key list`, `key status` | Stato e soli ID pubblici | ID, status, owner/mode, timestamp |
+| Socket locale | Config curl protetta, nuova/legacy | `204` durante dual-key | codice, unit/socket status |
+| Negativo locale | Config casuale e richiesta senza header | `401` | codice, nessun valore header |
+| Guasto controllato | Autenticatore/registro non disponibili nel test approvato | `503`, mai accesso | codice e rollback |
+| HTTPS reale | `/dwh/rpc/ping` con CA approvata | `204`/2xx, TLS valido | ID, esito e approvazione fingerprint |
+| Mac | **Validate workspace**, **Test connections** | Ping positivo | timestamp e stato GUI |
+| Revoca | Chiave precedente dopo osservazione | `401`; nuova ancora positiva | ID pubblico e codici |
+| Trasporti | Server PSD diretto e SSH diagnostico | nessuna chiave `dwh-auth` | trasporto selezionato |
+
+## Sequenza
+
+1. Fare il Gate A: verificare localmente 204/401 e che il servizio resti indipendente dal vecchio
+   stack. Nessun reload Nginx.
+2. Al Gate B, fare backup protetti, `nginx -t`, reload autorizzato e ping `.it` con CA verificata.
+3. Configurare il Mac nel vault GUI o con `API_KEY_FILE`; verificare ping e ID pubblico.
+4. Dopo la finestra approvata, revocare legacy, ripetere nuova positiva/legacy 401 e controllare
+   solo un journal bounded sanitizzato.
+5. Verificare rollback: backup leggibili, scope limitato a route/unit; nessuna migrazione di
+   sessioni legacy, indici Qdrant o cache Ollama.
+
+Il collaudo passa solo con tutti i casi attesi, owner acceptance e template evidenza completato. `ssh_tunnel` non usa chiavi `dwh-auth` e resta fuori dal runtime sessione.
+Per la diagnostica seguire [guida server](../install/dwh-auth-server.md) e [TLS](../install/dwh-auth-tls.md).
@@ -0,0 +1,40 @@
+# Template evidenza — rollout PSD `dwh-auth`
+
+Compilare dopo i gate autorizzati. Questa evidenza contiene solo metadati pubblici e sanitizzati.
+Non inserire chiavi, digest di credenziali, corpo/fingerprint completo del certificato, output Nginx
+grezzo, config curl, stringhe di connessione o risultati clinici.
+
+## Identità e approvazioni
+
+| Campo | Valore sanitizzato |
+| --- | --- |
+| SHA sorgente / checksum binario | `<sha-e-checksum>` |
+| Proprietario e approvazione Gate A | `<owner-e-timestamp>` |
+| Proprietario e approvazione Gate B | `<owner-e-timestamp>` |
+| ID pubblici interessati | `<public-key-ids>` |
+| Conferma fingerprint fuori banda | `<approvatore-e-timestamp>` |
+
+## Stato e permessi
+
+| Oggetto | Percorso | Owner/mode | Stato |
+| --- | --- | --- | --- |
+| Registro | `/var/lib/dwh-auth/` | `root:dwh-auth` `2750` | `<pass-fail>` |
+| Lock e record | `active` / `revoked` | `root:dwh-auth` `0640` | `<pass-fail>` |
+| Socket | `/run/dwh-auth/verify.sock` | `dwh-auth:www-data` `0660` | `<pass-fail>` |
+| Backup configurazione | `<protected-path>` | `root:root` `0600` | `<checksum-e-stato>` |
+
+## Test e decisione
+
+| Test | Esito atteso | Esito registrato |
+| --- | --- | --- |
+| Servizio/socket | 204 nuova e legacy nel dual-key | `<status-e-timestamp>` |
+| Negativi | 401 casuale, assente e legacy revocata | `<status-e-timestamp>` |
+| Guasto infrastruttura | 503 fail-closed | `<status-e-timestamp>` |
+| TLS `.it` | Ping verificato, SAN e conferma fuori banda | `<status-e-timestamp>` |
+| Mac | Ping positivo e vault/file configurato | `<status-e-timestamp>` |
+| Journal e scansioni | Nessuna chiave/digest esposti | `<solo-pass-fail>` |
+| Rollback | Backup leggibile, scope confermato | `<status-e-timestamp>` |
+
+Decisione Activity 1: `<PASS o stato non conclusivo>`. L'avanzamento a Activity 2 richiede nuova
+positiva, legacy 401, servizi validi, rollback e accettazione owner; il programma rimane
+`SURVEY_NO_GO`.