feat: complete evidence restructuring worktree

This commit is contained in:
Codex
2026-08-26 11:39:02 +02:00
parent a54d4769dd
commit 38f02cfd08
56 changed files with 1981 additions and 1801 deletions
+20 -22
View File
@@ -1,8 +1,8 @@
# `dwh-auth`: guida server
# `dwh-auth`: server guide
`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.
`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
@@ -12,14 +12,14 @@ flowchart LR
AUTH -->|"authorized"| REST["DWH REST"]
```
## Confini di sicurezza
## Security boundaries
- 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.
- 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.
## Installazione
## Installation
Il servizio usa questi percorsi:
@@ -31,11 +31,10 @@ Il servizio usa questi percorsi:
| 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.
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.
## Creazione e revoca delle chiavi
## Creating and revoking keys
Esempio per l'installazione ACME Limited:
@@ -46,9 +45,8 @@ sudo dwh-auth --registry-root /var/lib/dwh-auth key create \
--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:
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 \
@@ -56,10 +54,10 @@ sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \
--reason scheduled-rotation
```
La revoca è definitiva. Conservare backup cifrati del registro prima di ogni mutazione.
Revocation is permanent. Keep encrypted registry backups before every mutation.
## Integrazione Nginx
## Nginx integration
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`.
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`.