emilsoftware-utilities 2.0.0-dev.8 → 2.0.0-dev.80

package/docs/multi-tenancy.md

@@ -0,0 +1,305 @@
+# Multi-tenancy operativa
+
+Accessi supporta più tenant con **un database per tenant** e un processo di
+servizio per tenant. La configurazione sta in una cartella di file `.env`; la
+decisione architetturale è in `docs/adr/0002-multi-tenancy.md`.
+
+## Layout
+
+```
+tenants/
+  acme.env
+  beta.env
+```
+
+`acme.env`:
+
+```dotenv
+ACCESSI_TENANT_HOSTS=accessi.acme.example.com,*.acme.example.com
+ACCESSI_TENANT_PATH=/acme
+ACCESSI_TENANT_PORT=3201
+ACCESSI_TENANT_ENABLED=true
+
+ACCESSI_DB_HOST=db-acme
+ACCESSI_DB_PORT=3050
+ACCESSI_DB_DATABASE=/data/acme.fdb
+ACCESSI_DB_USER=SYSDBA
+ACCESSI_DB_PASSWORD=...
+
+ACCESSI_PUBLIC_BASE_URL=https://accessi.acme.example.com
+ACCESSI_CONFIRMATION_EMAIL_URL=https://accessi.acme.example.com
+ACCESSI_CONFIRMATION_RETURN_EMAIL_URL=https://accessi.acme.example.com
+
+ACCESSI_JWT_ALGORITHM=RS256
+ACCESSI_JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+ACCESSI_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+ACCESSI_JWT_KEY_ID=acme-2026-10
+ACCESSI_JWT_ISSUER=https://accessi.acme.example.com
+ACCESSI_JWT_AUDIENCE=accessi-api
+ACCESSI_JWT_EXPIRES=1h
+ACCESSI_JWT_REFRESH_EXPIRES=30d
+
+ACCESSI_ENCRYPTION_KEY=...32+ caratteri casuali...
+ACCESSI_EMAIL_HOST=smtp.acme.example.com
+ACCESSI_EMAIL_USER=...
+ACCESSI_EMAIL_PASSWORD=...
+ACCESSI_EMAIL_FROM=noreply@acme.example.com
+```
+
+Regole:
+
+- `ACCESSI_TENANT_ID` è opzionale: se assente vale il nome del file.
+- Almeno uno tra `ACCESSI_TENANT_HOSTS` e `ACCESSI_TENANT_PATH`.
+- `ACCESSI_TENANT_HOSTS` accetta più host separati da virgola e wildcard
+  `*.example.com`.
+- `ACCESSI_TENANT_PATH` è un prefisso (`/acme`), non un host.
+- Ogni tenant deve avere chiave JWT e database propri. La validazione blocca
+  chiavi condivise: un token di un tenant non deve essere accettato da un altro.
+- I file contengono segreti: non committarli. Permessi `0600`, secret manager o
+  volumi montati a runtime.
+
+## Validazione
+
+```bash
+npm run accessi:tenants -- --dir ./tenants --check
+npm run accessi:tenants -- --dir ./tenants --list
+npm run accessi:tenants -- --dir ./tenants --resolve accessi.acme.example.com /api/accessi
+```
+
+`--check` esce con codice 1 e stampa tutti gli errori (file, variabile,
+duplicati, chiavi condivise). `--list` stampa un summary **senza segreti**:
+host, path, database, issuer, audience, algoritmo e porta.
+
+La validazione avviene prima di aprire qualsiasi connessione: un tenant rotto
+non deve avviarsi a metà.
+
+## Avvio
+
+### Supervisore incluso
+
+```bash
+npm run accessi:tenants -- --dir ./tenants --serve --base-port 3200
+```
+
+Avvia un processo figlio per ogni tenant abilitato:
+
+- `ACCESSI_TENANT_PORT` se presente, altrimenti `base-port + indice`;
+- passa `PORT`, `ACCESSI_TENANT_ID` e tutte le variabili del file;
+- inoltra `SIGTERM`/`SIGINT` e termina i figli dopo 10 secondi;
+- non riavvia automaticamente un figlio: un loop su configurazione rotta è
+  peggio di un processo che resta giù; usare systemd/docker/Kubernetes.
+
+Il supervisore legge la cartella all'avvio: **aggiungere o rimuovere un tenant
+richiede un riavvio**. Non c'è hot reload (Nest non smonta moduli a caldo).
+
+### systemd (consigliato in produzione)
+
+Un'unità template, una istanza per tenant:
+
+```ini
+# /etc/systemd/system/accessi@.service
+[Unit]
+Description=Accessi Service tenant %i
+After=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/opt/accessi
+EnvironmentFile=/etc/accessi/tenants/%i.env
+Environment=PORT=%i
+# assegnare una porta per tenant in un drop-in o in un file separato
+ExecStart=/usr/bin/node dist/scripts/startAccessiService.js
+Restart=on-failure
+RestartSec=5
+User=accessi
+Group=accessi
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ReadWritePaths=/var/lib/accessi
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Con `PORT` derivato dal nome istanza non è possibile: usare un file
+`/etc/accessi/ports/%i` o un drop-in `Environment=PORT=3201`. In alternativa
+lasciare che il supervisore includa gestisca le porte.
+
+### Docker Compose
+
+```yaml
+services:
+  accessi-acme:
+    image: emilsoftware/accessi:2
+    env_file: ./tenants/acme.env
+    environment:
+      PORT: "3201"
+      ACCESSI_TENANT_ID: acme
+    volumes:
+      - ./secrets/acme:/run/secrets:ro
+    ports:
+      - "127.0.0.1:3201:3201"
+
+  accessi-beta:
+    image: emilsoftware/accessi:2
+    env_file: ./tenants/beta.env
+    environment:
+      PORT: "3202"
+      ACCESSI_TENANT_ID: beta
+    ports:
+      - "127.0.0.1:3202:3202"
+```
+
+## Reverse proxy
+
+Il proxy instrada per host o path e **sovrascrive** l'header tenant se lo usa.
+Non fidarsi di un header inviato dal client.
+
+### Nginx (host)
+
+```nginx
+map $host $accessi_upstream {
+    accessi.acme.example.com  http://127.0.0.1:3201;
+    accessi.beta.example.com  http://127.0.0.1:3202;
+    default                   http://127.0.0.1:3201; # o 444
+}
+
+server {
+    listen 443 ssl http2;
+    server_name accessi.acme.example.com accessi.beta.example.com;
+    location / {
+        proxy_pass $accessi_upstream;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+### Traefik (host)
+
+```yaml
+http:
+  routers:
+    acme:
+      rule: Host(`accessi.acme.example.com`)
+      service: acme
+    beta:
+      rule: Host(`accessi.beta.example.com`)
+      service: beta
+  services:
+    acme:
+      loadBalancer:
+        servers:
+          - url: http://127.0.0.1:3201
+    beta:
+      loadBalancer:
+        servers:
+          - url: http://127.0.0.1:3202
+```
+
+### Path
+
+Con `ACCESSI_TENANT_PATH=/acme`, il proxy deve rimuovere il prefisso prima di
+inoltrare (Accessi non lo conosce) oppure il tenant deve essere servito alla
+radice. Esempio Nginx:
+
+```nginx
+location /acme/ {
+    rewrite ^/acme/(.*)$ /$1 break;
+    proxy_pass http://127.0.0.1:3201;
+}
+```
+
+Se si usa la risoluzione via header, impostarlo solo nel proxy:
+
+```nginx
+proxy_set_header X-Accessi-Tenant acme;
+```
+
+e avviare Accessi con `allowHeader: true` solo nel router che si fida del proxy.
+
+## Store Redis condivisi
+
+Con Redis condiviso ogni tenant deve avere un prefisso distinto. Nel codice che
+costruisce gli store:
+
+```ts
+const prefix = getAccessiTenantRedisPrefix(tenant.id); // accessi:acme:
+const options: AccessiOptions = {
+  ...tenant.options,
+  publicAuthRateLimit: {
+    store: createRedisRateLimitStore({ client, keyPrefix: `${prefix}rate:` }),
+  },
+  sessionRevocation: {
+    store: createRedisSessionRevocationStore({ client, keyPrefix: `${prefix}session:` }),
+  },
+  refreshTokenRotation: {
+    store: createRedisRefreshTokenRotationStore({ client, keyPrefix: `${prefix}refresh:` }),
+    enabled: true,
+  },
+  accessTokenRevocation: {
+    store: createRedisAccessTokenRevocationStore({ client, keyPrefix: `${prefix}jti:` }),
+  },
+};
+```
+
+Senza prefisso due tenant condividerebbero rate limit, revoche e refresh: è un
+leakage. La validazione non può verificarlo (gli store sono codice host), quindi
+va testato.
+
+## Metriche e audit
+
+- Ogni processo espone `/health/metrics` sulla propria porta: Prometheus può
+  scrapare per tenant oppure usare un label `tenant` aggiunto dai child process.
+- `countAccessiMetric` aggiunge `tenant` quando `options.tenantId` è presente.
+- `audit.tenantId` aggiunge `tenant` a ogni record; configurare un sink per
+  tenant o un sink condiviso che conserva il label.
+- Log: includere `ACCESSI_TENANT_ID` nel formato del logger dell'host.
+
+## Aggiungere, rimuovere, ruotare
+
+**Aggiungere un tenant**
+
+1. Creare `tenants/<id>.env` con DB e chiavi propri.
+2. `npm run accessi:tenants -- --dir ./tenants --check`.
+3. Creare il database, eseguire le migrazioni (`db:update:accessi`,
+   `db:catalog:accessi`) con l'env del tenant.
+4. Avviare/riavviare il supervisore o l'unità systemd del tenant.
+5. Aggiungere la rotta al proxy e verificare `/health/ready`.
+
+**Rimuovere un tenant**
+
+1. Rimuovere la rotta dal proxy (il traffico si ferma).
+2. Disabilitare `ACCESSI_TENANT_ENABLED=false` e riavviare.
+3. Conservare database e backup secondo la retention; solo dopo eliminare il
+   file `.env` e i segreti.
+
+**Ruotare le chiavi**
+
+Ogni tenant ha la propria rotazione (`docs/jwt-key-rotation.md`). Non copiare
+chiavi tra tenant; la validazione blocca chiavi JWT condivise.
+
+## Migrazione da single-tenant
+
+1. Copiare il `.env` attuale in `tenants/<id>.env`; aggiungere
+   `ACCESSI_TENANT_HOSTS`/`ACCESSI_TENANT_PATH` e `ACCESSI_TENANT_ID`.
+2. Validare con `--check`.
+3. Avviare il tenant sulla nuova porta mantenendo il servizio vecchio.
+4. Verificare login, refresh, JWKS, console, health e metriche sul nuovo.
+5. Spostare il DNS/rotta del proxy sul nuovo servizio.
+6. Spegnere il vecchio processo e mantenere il rollback per almeno un ciclo di
+   token (`max(expiresIn, refreshExpiresIn)`).
+
+Il database non cambia: la migrazione è di configurazione e deployment, non di
+schema.
+
+## Limiti
+
+- Un processo per tenant: più RAM, più pool Firebird, più connessioni SMTP.
+- Nessun hot reload: aggiunta/rimozione richiede restart.
+- Migrazioni e backup per database.
+- La risoluzione via header è ammessa solo dietro proxy fidato; il client non
+  deve poter scegliere il tenant.
+- Un tenant con path `/` senza host non può convivere con altri (validazione).

package/docs/proxy-ip.md

@@ -0,0 +1,99 @@
+# IP reali dietro proxy
+
+Rate limit, audit e revoca usano `req.ip`. Se il servizio sta dietro un load balancer o un reverse
+proxy, `req.ip` e l'indirizzo del proxy finche `http.trustProxy` non e configurato correttamente:
+
+- tutti i client finiscono nello stesso bucket → il rate limit blocca utenti legittimi;
+- oppure un header non fidato diventa la chiave → il rate limit si aggira cambiando
+  `X-Forwarded-For` a ogni richiesta;
+- i log di audit riportano l'IP del proxy invece del client.
+
+`http.trustProxy` viene applicato sia all'host sia al sotto-app Accessi (`app.set('trust proxy', …)`)
+e accetta la stessa sintassi di Express: `false`, numero di hop, `true`, `'loopback'`, CIDR.
+
+## Valore consigliato
+
+| Deploy | `http.trustProxy` | Note |
+| --- | --- | --- |
+| Servizio esposto direttamente | `false` (default) | `X-Forwarded-For` viene ignorato: nessun bypass via header |
+| Un proxy davanti (Nginx, Traefik, ALB) | `1` | Il proxy deve **accodare** l'IP reale in `X-Forwarded-For` |
+| Due proxy (Cloudflare + Nginx, CDN + ingress) | `2` | Contare solo i proxy che il servizio vede davvero |
+| Solo proxy locali | `'loopback'` | Fidarsi di `127.0.0.1`/`::1`, non di altre reti |
+| Rete privata dedicata ai proxy | `'loopback, 10.0.0.0/8'` | Elencare le CIDR dei proxy, non usare `true` |
+| `trustProxy: true` | **sconsigliato** | Fidarsi di tutti gli hop rende scegliibile dal client il valore piu a sinistra |
+
+`npm run test:proxy-ip` verifica questi comportamenti su Express: senza trust proxy l'header non
+cambia `req.ip`; con `1` il client reale e l'ultimo hop; un header anteposto dal client non sposta il
+bucket; con `true` il valore piu a sinistra (falsificabile) vince.
+
+## Regola d'oro: il proxy deve accodare, non fidarsi
+
+`X-Forwarded-For` e una lista `client, proxy1, proxy2`. Il client puo inviare il proprio header con
+qualsiasi valore: il proxy deve **accodare** (`$proxy_add_x_forwarded_for`) o **sovrascrivere**
+(`$remote_addr`). Con `trustProxy` numerico Express parte da destra e si ferma dopo N hop fidati,
+quindi i valori anteposti dal client vengono ignorati.
+
+Non usare `X-Real-IP` da solo: se il servizio e raggiungibile direttamente, e falsificabile quanto
+`X-Forwarded-For`.
+
+## Nginx
+
+```nginx
+location /api/accessi/ {
+    proxy_pass http://accessi_service;
+
+    # Un solo proxy: sovrascrivere l'header e evitare valori del client.
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Host $host;
+}
+```
+
+Con piu proxy davanti a Nginx usare `$proxy_add_x_forwarded_for` e impostare `trustProxy` al numero
+totale di hop fidati.
+
+## Traefik
+
+Traefik aggiunge `X-Forwarded-For` per impostazione predefinita. Con un solo Traefik davanti al
+servizio usare `trustProxy: 1`. Se Traefik e dietro un altro ingress, contare anche quello.
+
+## Cloudflare
+
+Cloudflare invia `CF-Connecting-IP` e accoda `X-Forwarded-For`. Due opzioni sicure:
+
+1. il servizio e raggiungibile **solo** da Cloudflare (firewall/authenticated origin pulls):
+   `trustProxy: 1`, perche l'unico hop e Cloudflare;
+2. c'e anche un ingress/Nginx tra Cloudflare e il servizio: `trustProxy: 2`.
+
+Non impostare `trustProxy: true`: chi raggiunge l'origin direttamente potrebbe falsificare l'IP.
+Se serve `CF-Connecting-IP`, va letto solo dopo aver verificato che la richiesta arrivi da un IP
+Cloudflare.
+
+## Configurazione
+
+```ts
+export const accessiOptions: AccessiOptions = {
+  // ...
+  http: {
+    trustProxy: 1, // un solo proxy davanti
+  },
+  edgeRateLimit: {
+    enabled: true,
+    windowMs: 60_000,
+    maxAttempts: 300,
+  },
+};
+```
+
+## Verifica in produzione
+
+1. Da un client esterno, chiamare un endpoint pubblico con un header inventato:
+
+   ```bash
+   curl -H 'X-Forwarded-For: 6.6.6.6' https://accessi.example.com/api/accessi/auth/login
+   ```
+
+2. Controllare che l'audit (`accessi_rate_limited`, `edge_rate_limited`) riporti l'IP reale del
+   client e non `6.6.6.6`.
+3. Superare il limite da due IP diversi: se il secondo IP e bloccato subito, il bucket e condiviso e
+   `trustProxy` e troppo basso. Se cambiando header si sblocca, `trustProxy` e troppo alto.

package/docs/redis-load-testing.md

@@ -0,0 +1,88 @@
+# Test di concorrenza e carico su Redis
+
+`npm run test:load:redis` verifica che rate limit, ticket console e refresh
+rotation restino corretti con più istanze Accessi sullo stesso Redis, e produce
+un report di throughput e latenza.
+
+```bash
+ACCESSI_TEST_REDIS_URL=redis://127.0.0.1:6379 npm run test:load:redis
+```
+
+La suite è opt-in: senza `ACCESSI_TEST_REDIS_URL` i test vengono saltati. In CI
+si imposta `ACCESSI_TEST_REQUIRE_REDIS=1` per far fallire il job se Redis non è
+raggiungibile. Usare un database Redis dedicato (es. `redis://127.0.0.1:6379/5`):
+tutte le chiavi hanno un prefisso per processo e vengono cancellate a fine suite,
+ma un database separato evita sorprese con Redis condivisi.
+
+## Scenari
+
+| Scenario | Cosa dimostra |
+| --- | --- |
+| Burst login/reset/2FA | il limite globale per IP è rispettato anche se le richieste sono distribuite su due store (due istanze) |
+| Ticket console | due istanze consumano lo stesso ticket: una sola ottiene il record, l'altra riceve `null` |
+| Refresh rotation | due istanze consumano lo stesso `jti`: una sola vince; la revoca di famiglia è visibile all'altra istanza |
+| Misure | throughput, p50, p95 e massimo per ogni scenario |
+
+Le "due istanze" sono simulate con due connessioni Redis indipendenti e due
+oggetti store distinti. La correttezza dipende dagli script Lua atomici degli
+store: il test non testa il processo Node in sé, ma il comportamento condiviso
+su Redis.
+
+## Parametri
+
+| Variabile | Default | Note |
+| --- | --- | --- |
+| `ACCESSI_TEST_REDIS_URL` | assente | abilita la suite |
+| `ACCESSI_TEST_REQUIRE_REDIS` | `0` | `1` trasforma lo skip in errore (CI) |
+| `ACCESSI_TEST_LOAD_ITERATIONS` | `200` | operazioni per refresh rotation |
+| `ACCESSI_TEST_LOAD_CONCURRENCY` | `50` | richieste concorrenti |
+| `ACCESSI_TEST_REPORT_FILE` | assente | path del report Markdown |
+
+Esempio con carico maggiore:
+
+```bash
+ACCESSI_TEST_REDIS_URL=redis://127.0.0.1:6379/5 \
+ACCESSI_TEST_LOAD_ITERATIONS=1000 \
+ACCESSI_TEST_LOAD_CONCURRENCY=100 \
+ACCESSI_TEST_REPORT_FILE=redis-load-report.md \
+npm run test:load:redis
+```
+
+## Report
+
+Il report viene sempre stampato a fine suite:
+
+```
+| Scenario | Operazioni | Errori | Throughput (ops/s) | p50 (ms) | p95 (ms) | max (ms) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| rate limit login | 60 | 0 | 3200.0 | 12.10 | 24.30 | 41.00 |
+| console ticket (2 istanze) | 100 | 0 | 2800.0 | 14.00 | 30.10 | 55.00 |
+| refresh rotation (2 istanze) | 200 | 0 | 3000.0 | 13.00 | 27.00 | 48.00 |
+```
+
+Con `ACCESSI_TEST_REPORT_FILE` viene scritto anche su file; la CI lo pubblica
+come artifact `redis-load-report`.
+
+Le asserzioni verificano correttezza e un limite di sicurezza sulla latenza
+(p95 sotto 1–2 secondi), non un throughput minimo: il throughput dipende
+dall'hardware del runner e non deve rendere la CI instabile. Per una valutazione
+di capacità usare un ambiente dedicato e confrontare i numeri tra release.
+
+## Interpretazione
+
+- **Errori > 0**: Redis irraggiungibile o script Lua in errore; il test fallisce.
+- **p95 molto alto con throughput basso**: rete verso Redis o Redis saturo;
+  controllare `latency monitor` lato Redis e il pool di connessioni.
+- **Più di un consumo riuscito**: violazione dell'atomicità; non distribuire la
+  release.
+- **Limite per IP superato**: due istanze non stanno condividendo lo store o
+  stanno usando prefissi diversi.
+
+## Limiti
+
+- Non misura il costo del database Firebird né il flusso HTTP completo: per
+  quello usare i test di integrazione Firebird e un ambiente di staging.
+- I tempi includono il client Redis di test (RESP2 minimale) e il round-trip di
+  rete: sono un limite superiore, non un benchmark dell'applicazione.
+- Non usare questo test contro un Redis di produzione: scrive e cancella chiavi
+  con prefisso, ma è comunque carico reale.

package/docs/security-headers.md

@@ -0,0 +1,151 @@
+# Header di sicurezza e CSP
+
+Accessi applica header di sicurezza alle proprie rotte (`/api/accessi/*`, JWKS e
+documentazione OpenAPI). La configurazione avviene in `http.securityHeaders`:
+
+```ts
+const accessiOptions: AccessiOptions = {
+  // ...
+  http: {
+    securityHeaders: {
+      frameOptions: 'SAMEORIGIN',
+      referrerPolicy: 'no-referrer',
+      permissionsPolicy: 'camera=(), microphone=(), geolocation=()',
+      cacheControl: 'no-store, max-age=0',
+      contentSecurityPolicy: {
+        reportOnly: false,
+        connectSrc: ['https://api.example.com'],
+        reportUri: 'https://csp.example.com/report',
+        directives: {
+          'img-src': ["'self'", 'data:', 'https:'],
+        },
+      },
+    },
+  },
+};
+```
+
+`securityHeaders: false` disabilita tutto; `securityHeaders: true` (o l'omissione)
+usa i default. La forma storica booleana resta valida.
+
+## Default
+
+| Header | Valore | Note |
+| --- | --- | --- |
+| `X-Content-Type-Options` | `nosniff` | sempre presente |
+| `X-Frame-Options` | `SAMEORIGIN` | `false` per non inviarlo |
+| `Referrer-Policy` | `no-referrer` | `false` per non inviarla |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | `false` per non inviarla |
+| `Cache-Control` (shell console) | `no-store, max-age=0` | `false` per non inviarlo |
+| `Content-Security-Policy` | vedi sotto | `false` per disabilitarla |
+
+La shell della console risponde sempre con `Cache-Control: no-store`,
+`Referrer-Policy: no-referrer` e `X-Content-Type-Options: nosniff`, anche con
+`securityHeaders: false`, per non regredire rispetto alle versioni precedenti.
+
+## Content Security Policy
+
+Direttive di base:
+
+```
+default-src 'self'
+base-uri 'none'
+object-src 'none'
+frame-ancestors 'self'
+form-action 'self'
+img-src 'self' data:
+font-src 'self'
+style-src 'self'
+script-src 'self'
+connect-src 'self'
+```
+
+La policy cambia per superficie:
+
+- **Console** (`/api/accessi/console*`): i due script inline della shell ricevono
+  un nonce casuale per richiesta (`script-src 'self' 'nonce-...'`). Non viene mai
+  usato `'unsafe-inline'`. Se la console chiama l'API su un'altra origine, quella
+  origine viene aggiunta automaticamente a `connect-src` da
+  `consoleApiBaseUrl`.
+- **OpenAPI** (`/accessi/openapi*`): la UI Swagger genera script e stili inline a
+  runtime, quindi la policy include `'unsafe-inline'` per `script-src` e
+  `style-src`. È l'unica eccezione documentata; per rimuoverla impostare
+  `contentSecurityPolicy.swaggerUnsafeInline: false` e servire una UI Swagger
+  compatibile con nonce/hash.
+- **API e JWKS**: policy stretta, senza `'unsafe-inline'`.
+
+`directives` vince sui default: una direttiva impostata a `false` viene rimossa,
+altrimenti i valori sostituiscono quelli predefiniti. `connectSrc` aggiunge
+origini a `connect-src`; `reportUri` aggiunge `report-uri`.
+
+### Rollout con Report-Only
+
+1. Imposta `contentSecurityPolicy.reportOnly: true` e un `reportUri`.
+2. Raccogli le violazioni per almeno un ciclo di utilizzo della console.
+3. Aggiungi le origini legittime a `connectSrc` o alle direttive.
+4. Passa a `reportOnly: false`.
+
+## Reverse proxy
+
+Accessi non imposta HSTS: va configurato sul terminatore TLS insieme ai
+redirect HTTP→HTTPS.
+
+### Nginx
+
+```nginx
+location / {
+    proxy_pass http://accessi_upstream;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # Non rimuovere gli header CSP inviati da Accessi.
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+}
+```
+
+`add_header` di Nginx si aggiunge solo se la risposta non ha già un header con
+lo stesso nome: non duplicare `Content-Security-Policy` a questo livello. Se il
+proxy deve imporre una policy propria, disattiva quella di Accessi
+(`contentSecurityPolicy: false`) e mantieni una sola policy, consapevole che la
+console richiede il nonce (il proxy non può generarlo al posto dell'app).
+
+### Traefik
+
+```yaml
+http:
+  middlewares:
+    accessi-headers:
+      headers:
+        stsSeconds: 31536000
+        stsIncludeSubdomains: true
+        contentTypeNosniff: true
+        referrerPolicy: no-referrer
+        customResponseHeaders:
+          Permissions-Policy: "camera=(), microphone=(), geolocation=()"
+```
+
+Non aggiungere `Content-Security-Policy` in `customResponseHeaders` se Accessi la
+invia già: due header CSP vengono applicati come intersezione e la console
+smetterebbe di funzionare. Per una policy unica, gestiscila in un solo punto.
+
+### Cloudflare
+
+- Abilita "Always Use HTTPS" e HSTS nelle impostazioni TLS/Edge.
+- Se usi Transform Rules per aggiungere header, escludi
+  `Content-Security-Policy`: Cloudflare non può generare il nonce della console.
+- Verifica che "Email Obfuscation" o altre feature che iniettano script inline
+  siano disattivate sulle pagine della console, altrimenti violano la CSP.
+- Con Cloudflare davanti alla JWKS, mantieni il TTL della cache allineato a
+  `jwt.jwks.cacheTtlMs` (default 300 s): un TTL più alto ritarda la rotazione
+  delle chiavi.
+
+## Verifica
+
+```bash
+curl -sSI https://accessi.example.com/api/accessi/console | grep -i -E 'content-security|x-frame|referrer|permissions'
+```
+
+La CSP della console cambia a ogni risposta per via del nonce: due richieste
+consecutive devono restituire policy diverse. Il nonce nell'header deve
+coincidere con quello dei due script inline nella pagina.