docs: design per-installation DWH REST auth

docs/operations/psd-server-survey-remediation-checklist.md

@@ -29,7 +29,8 @@ Authentik, Aritmolab o repository esterni.
 
 - Current activity: `1`
 - Title: Rotate or revoke the exposed DWH credential safely
-- Resume from: Activity 1, identify the accountable credential owner and the credential type without revealing its value
+- Resume from: Activity 1, review the written per-installation authentication design, then prepare
+  its executable implementation and rotation plan
 - Discussion rule: una sola attività può essere `IN_DISCUSSION`
 - Allowed states: `PENDING`, `IN_DISCUSSION`, `BLOCKED`, `PASS`
 
@@ -51,7 +52,7 @@ Authentik, Aritmolab o repository esterni.
 
 | ID | Attività | Stato | Responsabile | Prossimo gate |
 |---|---|---|---|---|
-| 1 | Rotazione controllata della credenziale DWH esposta | `IN_DISCUSSION` | Unassigned | Identificare owner e tipo di credenziale |
+| 1 | Rotazione controllata della credenziale DWH esposta | `IN_DISCUSSION` | Proprietario del progetto | Revisionare la specifica scritta e approvare il piano eseguibile |
 | 2 | Assegnazione dei responsabili dei componenti condivisi | `PENDING` | Unassigned | Elenco owner confermato |
 | 3 | Risoluzione del dominio pubblico `.it` oppure `.com` | `PENDING` | Unassigned | Origine autorevole documentata |
 | 4 | Topologia e responsabilità del load balancer | `PENDING` | Unassigned | Route, health, TLS, rollback e allowlist verificati |
@@ -65,7 +66,7 @@ Authentik, Aritmolab o repository esterni.
 ## Activity 1: Rotate or revoke the exposed DWH credential safely
 
 - Status: `IN_DISCUSSION`
-- Accountable owner: Unassigned
+- Accountable owner: Proprietario del progetto (confermato dall'utente)
 - Objective: sostituire o revocare in modo controllato la credenziale DWH comparsa nell'output
   interno del survey, senza interrompere consumer legittimi e senza esporne nuovamente il valore.
 - Why this is required: la credenziale deve essere considerata compromessa; non può essere usata
@@ -89,14 +90,82 @@ Authentik, Aritmolab o repository esterni.
   - timestamp e risultati dei test positivi e negativi;
   - conferma di revoca della credenziale precedente;
   - procedura di rollback e relativo esito.
-- Discussion notes: il survey ha osservato la credenziale durante l'analisi della configurazione
-  Nginx relativa al DWH. Non è ancora provato se sia una chiave API, un header condiviso o un altro
-  tipo di secret; non va confusa automaticamente con una password PostgreSQL.
-- Decision: No decision recorded
-- Blockers: owner non identificato; tipo di credenziale non verificato; consumer e supporto alla
-  doppia credenziale non inventariati.
-- Next step: il proprietario identifica il responsabile della credenziale della route DWH e indica
-  se appartiene al team Nginx, Supabase/PostgreSQL o a un altro team.
+- Discussion notes:
+  - la credenziale osservata è stata identificata, senza rileggerne il valore, come chiave statica
+    `X-API-Key` applicata da Nginx alla route DWH REST `/dwh/`; è distinta dalle password PostgreSQL;
+  - `/home/chirone/chirone/etl` documenta PostgREST come integrazione HTTP esterna, mentre i processi
+    ETL e Superset usano PostgreSQL diretto;
+  - il vecchio ThothII e Chirone WP3 usano PostgreSQL diretto nei profili locali/server; Supabase
+    Studio è un pannello amministrativo e non appartiene al data-plane applicativo;
+  - il design approvato resta invariato: il Mac usa `rest_api`, il nuovo ThothII sul server PSD usa
+    `postgres_direct` con ruolo DWH dedicato e realmente read-only;
+  - la ricognizione dei repository ha rilevato materiale sensibile hardcoded in file tracciati,
+    senza riportarne i valori. La bonifica e la rotazione dei segreti coinvolti restano obbligatorie.
+  - il censimento statico non trova consumer `/dwh/` in ETL, Superset o nel Chirone WP3 attivo:
+    usano PostgreSQL diretto. Il vecchio container `thothii-core-1` è configurato con
+    `transport: direct`; i due ThothII restano comunque tecnicamente capaci di usare REST;
+  - i log Nginx redatti provano 18.523 richieste `/dwh/` dal 23 luglio al 19 agosto 2026:
+    18.481 hanno user-agent classificato `python-requests` e gli endpoint RPC corrispondono
+    prevalentemente a introspezione e campionamento Thoth. La sorgente è una sola, privata e
+    compatibile con un proxy/load balancer; non prova che esista un solo client finale;
+  - l'ipotesi che il traffico sia generato dal job ETL delle 03:00 è smentita: nella finestra
+    02:30–03:30 Europe/Rome non compare nessuna richiesta `/dwh/`. Il 99,37% del traffico è
+    concentrato il 13 agosto tra le 17:38 e le 20:03;
+  - la firma del 13 agosto corrisponde a undici preprocessing Thoth: undici `list_tables`, e
+    per ciascuna esecuzione 163 chiamate a ognuno dei tre RPC per-tabella più 1.180 `top_values`,
+    cioè 1.670 richieste per ciclo. `PROJECT_STATE.md` registra proprio il preprocessing PSD live
+    del 13 agosto su 163 tabelle, con più rerun e correzioni emerse durante l'esecuzione;
+  - il DAG ETL `nightly_etl_orchestrator` è schedulato con `0 3 * * *`, ma scrive il DWH tramite
+    PostgreSQL/`psycopg2` diretto. Nel codice tracciato non chiama `/dwh/`, gli RPC Thoth o
+    `tht workspace preprocess`, né emerge un trigger indiretto verso Thoth;
+  - la configurazione Nginx nominalmente attiva accetta una sola chiave tramite confronto letterale
+    in un endpoint `auth_request`. Non esiste una mappa a più chiavi: la doppia credenziale richiede
+    un refactor, backup, `nginx -t`, reload e rollback in una fase di mutazione autorizzata.
+  - il proprietario conferma che il ThothII sul Mac deve continuare a usare REST e che sono previste
+    molte altre installazioni remote, senza tunnel SSH verso Supabase. `/dwh/` è quindi
+    un'interfaccia remota stabile e multi-client, non una compatibilità temporanea.
+  - il proprietario decide di mantenere il certificato TLS corrente. L'endpoint esterno REST
+    presenta lo stesso certificato self-issued di Nginx, valido fino al 21 giugno 2027 e con SAN
+    per `supabase-aritmolab.policlinicosandonato.it`; non copre un eventuale dominio `.com`;
+  - il manuale di installazione deve trattare `TLS_CA_FILE` come necessario per ogni client che
+    non abbia già quel certificato nel proprio trust store, spiegando consegna affidabile,
+    verifica del fingerprint, rinnovo e aggiornamento coordinato delle installazioni;
+  - non esiste un ambiente di test. La rotazione dovrà quindi usare una verifica production-safe:
+    backup, finestra dual-key, RPC `ping` senza dati clinici, test positivo/negativo e rollback.
+  - il proprietario approva un componente `dwh-auth` riutilizzabile ma opzionale, incluso nel
+    repository senza modificare il protocollo dei client portabili o il CLI `tht`;
+  - su PSD `dwh-auth` avrà un lifecycle `systemd` indipendente dallo stack ThothII e comunicherà
+    con Nginx tramite socket Unix. Lo stop o la sostituzione di ThothII non dovrà interrompere i
+    client REST;
+  - il registro sarà composto da file protetti, versionati e aggiornati atomicamente, con un file
+    per generazione della chiave. Conterrà digest SHA-256 di segreti casuali da almeno 256 bit e
+    metadati non sensibili, senza SQLite o nuove dipendenze runtime;
+  - le chiavi saranno assegnate alle installazioni, non alle persone. Saranno prive di scadenza
+    predefinita, con scadenza opzionale e revoca manuale;
+  - creazione e import leggeranno o scriveranno soltanto file protetti. Nessun segreto sarà
+    accettato come argomento, stampato o inserito in log, JSON, documenti o repository;
+  - la gestione sarà fail-closed: credenziali non valide riceveranno `401`, mentre guasti del
+    servizio o del registro saranno mappati a `503` senza fallback permissivo;
+  - il proprietario conferma che le sessioni, gli indici e le cache del vecchio ThothII erano solo
+    test e non richiedono migrazione o attività di salvaguardia dedicate. Restano necessari il
+    rollback della route DWH condivisa e il rispetto del gate esplicito prima di fermare lo stack;
+  - il design approvato è scritto in
+    `docs/superpowers/specs/2026-08-20-dwh-rest-per-installation-auth-design.md` e richiede una
+    revisione del proprietario prima del piano di implementazione.
+- Decision: il nuovo ThothII server userà PostgreSQL diretto; il Mac e le future installazioni
+  remote useranno REST. La chiave condivisa corrente non è un modello finale accettabile: la
+  rotazione esposta userà una transizione a doppia credenziale e l'architettura target assegnerà
+  un'identità revocabile distinta a ogni installazione. Supabase Studio non sarà usato come
+  trasporto. Il proprietario del progetto è accountable per coordinare la rotazione. Il meccanismo
+  target è il servizio server-only `dwh-auth`, indipendente dallo stack ThothII, con registro a file
+  e una chiave revocabile per installazione.
+- Blockers: la specifica scritta attende la revisione del proprietario; mancano ancora il piano
+  eseguibile, la sorgente protetta per importare la chiave legacy, la procedura realizzata di
+  aggiornamento/verifica del Mac, la documentazione TLS completa, l'autorizzazione alla mutazione
+  e la revoca provata della vecchia chiave.
+- Next step: dopo l'approvazione della specifica scritta, preparare il piano eseguibile di
+  implementazione e rotazione dual-key con test automatici, aggiornamento Mac, prova
+  positiva/negativa e rollback. Nessuna modifica Nginx avviene durante questa discussione.
 
 ## Activity 2: Identify accountable owners for shared components