# `dwh-auth`: server guide

`dwh-auth` protects the REST `/dwh/` route with a separate key for each ThothII installation.
It runs as a separate Linux service, does not read DWH data, and does not connect directly to
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"]
```

## Security boundaries

- A key identifies an installation, not a person.
- Keys and backups stay in protected files and never enter Git, logs, arguments, or public JSON.
- The registry stores digests and metadata, never the key in plaintext.
- The REST route must be exposed only through verified TLS.

## Installation

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/` |

Install the binary and unit with `root` ownership, create the `dwh-auth` service user, and enable
the unit with `systemctl enable --now dwh-auth`. The socket must be accessible to Nginx's group.

## Creating and revoking keys

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

Deliver the file through an enterprise vault or an authenticated channel. To rotate a key, create
a new one, distribute it, update the client, and revoke the old one using its public ID:

```bash
sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \
  --key-id PUBLIC_KEY_ID \
  --reason scheduled-rotation
```

Revocation is permanent. Keep encrypted registry backups before every mutation.

## Nginx integration

Nginx forwards the key to the `dwh-auth` socket. Only an authorized response allows the request
to reach DWH REST. Missing, unknown, expired, or revoked keys receive `401`; an unavailable
service or registry produces `503`.