# `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.

```mermaid
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:

```bash
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:

```bash
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`.