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

package/docs/multi-tenancy.md

@@ -0,0 +1,329 @@
+# 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
+`*.environment.ts` tipizzati; la decisione architetturale è in
+`docs/adr/0002-multi-tenancy.md`.
+
+## Layout
+
+```
+tenants/
+  acme.environment.ts
+  beta.environment.ts
+```
+
+`acme.environment.ts`:
+
+```ts
+import type { AccessiTenantEnvironment } from 'emilsoftware-utilities/accessi/server';
+import { defineAccessiTenantEnvironment } from 'emilsoftware-utilities/accessi/server';
+
+export default defineAccessiTenantEnvironment({
+  tenant: {
+    id: 'acme',
+    hosts: ['accessi.acme.example.com', '*.acme.example.com'],
+    path: '/acme',
+    port: 3201,
+    enabled: true,
+    description: 'Tenant ACME',
+  },
+
+  database: {
+    host: 'db-acme',
+    port: 3050,
+    database: '/data/acme.fdb',
+    user: 'SYSDBA',
+    password: process.env.ACME_DB_PASSWORD!,
+  },
+
+  jwt: {
+    algorithm: 'RS256',
+    secret: process.env.ACME_JWT_SECRET!,
+    privateKey: process.env.ACME_JWT_PRIVATE_KEY!,
+    publicKey: process.env.ACME_JWT_PUBLIC_KEY!,
+    keyId: 'acme-2026-10',
+    issuer: 'https://accessi.acme.example.com',
+    audience: 'accessi-api',
+    expiresIn: '1h',
+    refreshExpiresIn: '30d',
+  },
+
+  email: {
+    host: process.env.ACME_SMTP_HOST!,
+    port: 587,
+    secure: false,
+    requireTLS: true,
+    tls: { rejectUnauthorized: true },
+    from: 'noreply@acme.example.com',
+    auth: {
+      user: process.env.ACME_SMTP_USER!,
+      pass: process.env.ACME_SMTP_PASSWORD!,
+    },
+  },
+
+  encryptionKey: process.env.ACME_ENCRYPTION_KEY!,
+  confirmationEmailUrl: 'https://accessi.acme.example.com',
+  confirmationEmailReturnUrl: 'https://accessi.acme.example.com',
+  publicBaseUrl: 'https://accessi.acme.example.com',
+
+  // Opzionali, tutti tipizzati da AccessiTenantEnvironment:
+  http: { trustProxy: 1 },
+  authCookie: { enabled: true, secure: true, sameSite: 'lax' },
+  publicAuthRateLimit: { login: { windowMs: 900_000, maxAttempts: 10 } },
+  metrics: { enabled: true, prefix: 'accessi' },
+  audit: { retentionDays: 90, logger: true },
+} satisfies AccessiTenantEnvironment);
+```
+
+Regole:
+
+- `tenant.id` è obbligatorio (minuscole, numeri, `-`, `_`, max 63). Non serve
+  derivarlo dal nome file, ma dovrebbe coincidere per leggibilità.
+- Almeno uno tra `tenant.hosts` e `tenant.path`.
+- `tenant.hosts` accetta host esatti e wildcard `*.example.com`.
+- `tenant.path` è un prefisso (`/acme`), non un host.
+- Ogni tenant deve avere database, chiave JWT e `encryptionKey` propri. La
+  validazione blocca chiavi JWT condivise: un token di un tenant non deve essere
+  accettato da un altro.
+- I segreti vanno letti da `process.env` o dal secret manager: il file
+  `.environment.ts` può essere versionato senza contenere credenziali.
+- `store`, `sink`, `match`, `onDocument` e `logger` non sono nel tipo: sono
+  oggetti runtime e vanno collegati dal backend ospitante.
+
+Il loader usa **jiti** per eseguire TypeScript anche dal pacchetto compilato:
+non serve compilare i file tenant separatamente.
+
+## 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, campo, 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:
+
+- `tenant.port` se presente, altrimenti `base-port + indice`;
+- passa `PORT`, `ACCESSI_TENANT_ENVIRONMENT` (path assoluto del file) e
+  `ACCESSI_TENANT_ID`;
+- 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)
+
+```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/%i.secrets
+Environment=ACCESSI_TENANT_ENVIRONMENT=/etc/accessi/tenants/%i.environment.ts
+Environment=PORT=3201
+ExecStart=/usr/bin/node dist/scripts/startAccessiTenantService.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
+```
+
+`EnvironmentFile` contiene solo i segreti (`ACME_DB_PASSWORD`, ...), non il
+manifest: il manifest tipizzato resta nel file `.environment.ts`.
+
+### Docker Compose
+
+```yaml
+services:
+  accessi-acme:
+    image: emilsoftware/accessi:2
+    environment:
+      ACCESSI_TENANT_ENVIRONMENT: /config/acme.environment.ts
+      PORT: "3201"
+    env_file: ./secrets/acme.env
+    volumes:
+      - ./tenants:/config:ro
+    ports:
+      - "127.0.0.1:3201:3201"
+```
+
+## 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;
+}
+
+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 `tenant.path = '/acme'`, il proxy deve rimuovere il prefisso prima di
+inoltrare (Accessi non lo conosce) oppure il tenant deve essere servito alla
+radice:
+
+```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 il router con `allowHeader: true` solo nel servizio che si fida del
+proxy.
+
+## Store Redis condivisi
+
+Con Redis condiviso usare l'helper: crea tutti gli store con prefissi
+`accessi:<tenantId>:` e li collega alle opzioni.
+
+```ts
+import { createAccessiTenantStores } from 'emilsoftware-utilities/accessi/server';
+
+const stores = createAccessiTenantStores({
+  tenantId: tenant.id,
+  client: redisClient,
+  encryptionKey: tenant.options.encryptionKey,
+});
+const options: AccessiOptions = stores.applyTo(tenant.options);
+```
+
+`applyTo` collega `publicAuthRateLimit`, `serviceTokens`,
+`sessionRevocation`, `accessTokenRevocation`, `refreshTokenRotation` e
+`consoleEntry`, preservando le altre opzioni. I prefissi sono disponibili in
+`stores.prefixes`; `getAccessiTenantStorePrefixes(tenantId)` li espone anche
+senza creare gli store.
+
+Senza prefisso due tenant condividerebbero rate limit, revoche e refresh: è un
+leakage. I test di integrazione Redis verificano l'isolamento.
+
+## Metriche e audit
+
+- Ogni processo espone `/health/metrics` sulla propria porta: Prometheus può
+  scrapare per tenant.
+- `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>.environment.ts` 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 la configurazione 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. Impostare `tenant.enabled: false` e riavviare.
+3. Conservare database e backup secondo la retention; solo dopo eliminare il
+   file `.environment.ts` 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. Creare `tenants/<id>.environment.ts` partendo dal `.env` attuale, usando
+   `process.env` per i segreti.
+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).
+- I file `.environment.ts` sono eseguiti: trattarli come codice fidato e non
+  caricarli da input HTTP.

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.