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

package/docs/auth-cookies.md

@@ -0,0 +1,123 @@
+# Autenticazione via cookie httpOnly e CSRF
+
+Bearer resta il default: nessun comportamento cambia finché non si abilita
+esplicitamente la modalità cookie.
+
+```ts
+const accessiOptions: AccessiOptions = {
+  // ...
+  authCookie: {
+    enabled: true,
+    secure: true,
+    sameSite: 'lax',
+  },
+};
+```
+
+Con `authCookie` presente (e `enabled` diverso da `false`) Accessi:
+
+- invia access e refresh token in cookie `HttpOnly`, con `Max-Age` derivato
+  dalla scadenza reale del token;
+- non restituisce più i token nel body JSON (salvo `exposeTokens: true`);
+- accetta l'access token dal cookie su tutte le rotte Accessi, senza toccare
+  guard, middleware e resource server già esistenti;
+- emette un cookie CSRF leggibile dal client e richiede il relativo header sulle
+  richieste che modificano stato;
+- legge il refresh token dal cookie quando il body di `/auth/refresh` è vuoto;
+- cancella i cookie a revoca del token corrente o di tutte le sessioni.
+
+## Opzioni
+
+| Opzione | Default | Note |
+| --- | --- | --- |
+| `enabled` | `true` se l'oggetto è presente | `false` disabilita |
+| `secure` | `true` | disattivare solo in sviluppo HTTP |
+| `sameSite` | `lax` | `none` richiede `secure: true` |
+| `domain` | assente | impostare solo se serve la condivisione tra sottodomini |
+| `accessTokenName` | `accessi_access` | |
+| `refreshTokenName` | `accessi_refresh` | |
+| `csrfTokenName` | `accessi_csrf` | non httpOnly, serve al double-submit |
+| `accessPath` | `/api/accessi` | |
+| `refreshPath` | `/api/accessi/auth` | |
+| `csrfPath` | `/` | |
+| `csrfHeaderName` | `x-csrf-token` | case-insensitive |
+| `csrf` | `double-submit` | `off` solo con protezione CSRF esterna |
+| `exposeTokens` | `false` | `true` reintroduce i token nel body |
+| `refreshFromCookie` | `true` | |
+
+I nomi dei tre cookie devono essere validi e distinti: la validazione
+fail-fast lo controlla all'avvio.
+
+## Flusso
+
+1. `POST /api/accessi/auth/login` (eventuali passi passwordless/2FA inclusi)
+   risponde con i profili utente e i `Set-Cookie` di access, refresh e CSRF.
+   `Result.token` e `Result.refreshToken` sono assenti.
+2. Il browser chiama le API con `credentials: 'include'`; il middleware copia il
+   cookie access nell'header `Authorization` interno, quindi le guard esistenti
+   funzionano invariate.
+3. Per `POST`, `PUT`, `PATCH` e `DELETE` il client invia
+   `x-csrf-token: <valore del cookie accessi_csrf>`. Token mancante o diverso
+   produce `403 AUTH_CSRF_INVALID`.
+4. `POST /api/accessi/auth/refresh` può essere chiamato con body `{}`: il refresh
+   token viene letto dal cookie. I nuovi token ruotano i cookie.
+5. `POST /api/accessi/auth/revoke-token` senza `jti` revoca il token corrente e
+   cancella i cookie; `revoke-sessions` cancella tutti i cookie dell'utente.
+
+### SPA
+
+```ts
+await fetch(`${base}/api/accessi/auth/login`, {
+  method: 'POST',
+  credentials: 'include',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ email, password }),
+});
+
+const csrf = document.cookie
+  .split('; ')
+  .find((entry) => entry.startsWith('accessi_csrf='))
+  ?.split('=')[1];
+
+await fetch(`${base}/api/accessi/user/set-stato`, {
+  method: 'POST',
+  credentials: 'include',
+  headers: { 'Content-Type': 'application/json', 'x-csrf-token': csrf },
+  body: JSON.stringify(payload),
+});
+```
+
+Se la SPA e l'API sono su origini diverse servono `sameSite: 'none'`,
+`secure: true`, CORS con `credentials: true` e `X-CSRF-Token` tra gli header
+esposti. Il token CSRF è anche restituito nell'header di risposta
+`X-CSRF-Token`, così una SPA su altra origine può leggerlo senza accedere al
+cookie dell'API. Preferire, quando possibile, la stessa origine dietro un
+reverse proxy.
+
+## Endpoint esenti da CSRF
+
+Sono le entry point che non hanno ancora una sessione: login, refresh, verifica e
+reinvio 2FA, conferma reset password, invio email di reset, bootstrap admin,
+scambio federated e registrazione pubblica. Tutte le altre richieste non sicure
+autenticate via cookie richiedono l'header.
+
+Se un host applica già una propria protezione CSRF può impostare `csrf: 'off'`;
+la validazione emette il warning `ACCESSI_AUTH_COOKIE_CSRF_DISABLED`.
+
+## Console amministrativa
+
+La shell console riceve dal server i flag `__ACCESSI_AUTH_COOKIE__` e i nomi di
+cookie/header CSRF; in modalità cookie usa `credentials: 'include'`, invia il
+token CSRF e non richiede un JWT in `sessionStorage`. Il ticket di ingresso
+console (`#entry=`) imposta i cookie al posto del token nel body.
+
+## Note operative
+
+- Non impostare `Cache-Control` pubblico sulle risposte di login/refresh: i
+  `Set-Cookie` non devono essere condivisi.
+- Con HTTPS terminato dal reverse proxy, inoltrare `X-Forwarded-Proto` e
+  configurare `http.trustProxy` su Accessi.
+- I cookie sono un'alternativa a Bearer, non un'aggiunta: se il client invia
+  `Authorization`, quel token vince e il CSRF non viene applicato.
+- La revoca per `jti` e la revoca sessioni restano valide anche con cookie: il
+  cookie contiene lo stesso JWT emesso in modalità Bearer.

package/docs/gateway-rate-limit.md

@@ -0,0 +1,98 @@
+# Gateway rate limit per Accessi Service
+
+Il rate limit applicativo di Accessi protegge login, 2FA, reset password, console entry e service token. Il gateway/API gateway resta utile per una protezione per IP, connessioni e bot prima che la richiesta raggiunga Node.
+
+Regole consigliate:
+
+- `/api/accessi/auth/*`: soglia bassa, burst contenuto
+- `/api/accessi/console/entry/exchange`: soglia bassa
+- `/api/accessi/*`: soglia media
+- `/accessi/openapi*` e `/accessi/.well-known/jwks.json`: soglia alta o cache CDN
+
+## Nginx
+
+```nginx
+limit_req_zone $binary_remote_addr zone=accessi_auth:10m rate=2r/s;
+limit_req_zone $binary_remote_addr zone=accessi_api:10m rate=10r/s;
+limit_conn_zone $binary_remote_addr zone=accessi_conn:10m;
+
+server {
+    # Se Accessi e dietro un proxy/load balancer, configura real_ip
+    # prima di usare $binary_remote_addr.
+
+    location /api/accessi/auth/ {
+        limit_req zone=accessi_auth burst=10 nodelay;
+        limit_conn accessi_conn 20;
+        proxy_pass http://accessi_service;
+    }
+
+    location /api/accessi/ {
+        limit_req zone=accessi_api burst=50 nodelay;
+        limit_conn accessi_conn 20;
+        proxy_pass http://accessi_service;
+    }
+
+    location /accessi/ {
+        limit_req zone=accessi_api burst=50 nodelay;
+        proxy_pass http://accessi_service;
+    }
+}
+```
+
+## Traefik
+
+```yaml
+http:
+  middlewares:
+    accessi-auth-ratelimit:
+      rateLimit:
+        average: 2
+        burst: 10
+        period: 1s
+    accessi-api-ratelimit:
+      rateLimit:
+        average: 10
+        burst: 50
+        period: 1s
+  routers:
+    accessi-auth:
+      rule: PathPrefix(`/api/accessi/auth/`)
+      middlewares: [accessi-auth-ratelimit]
+      service: accessi
+    accessi-api:
+      rule: PathPrefix(`/api/accessi/`) || PathPrefix(`/accessi/`)
+      middlewares: [accessi-api-ratelimit]
+      service: accessi
+```
+
+## Cloudflare
+
+Regole di rate limiting:
+
+- path `/api/accessi/auth/*`: 10 richieste/minuto per IP, azione `managed challenge`
+- path `/api/accessi/console/entry/exchange`: 30 richieste/5 minuti per IP
+- path `/api/accessi/*`: 300 richieste/minuto per IP, azione `block`
+- path `/accessi/.well-known/jwks.json`: cache CDN, limite alto
+
+Aggiungere bot fight mode/WAF secondo il piano disponibile.
+
+## AWS WAF / API Gateway
+
+- rate-based rule: 300 richieste/5 minuti per IP
+- scope-down statement: `URI starts with /api/accessi`
+- regola più severa su `/api/accessi/auth/*`
+- AWS Shield/WAF Bot Control se disponibile
+
+## Rapporto con `edgeRateLimit` della libreria
+
+`edgeRateLimit` e un ultimo livello applicativo:
+
+- usa lo stesso `RateLimitStore` Redis dei rate limit per account;
+- copre Accessi anche se il gateway non ha regole specifiche;
+- non sostituisce WAF, bot protection, limiti di connessione o protezione DDoS.
+
+In produzione usare entrambi:
+
+```text
+Client -> CDN/WAF -> API gateway -> edgeRateLimit Accessi -> rate limit per account
+```

package/docs/import-migration.md

@@ -0,0 +1,65 @@
+# Migrazione agli entry point Accessi
+
+Il root barrel (`emilsoftware-utilities`) e i deep import
+(`emilsoftware-utilities/dist/accessi-module/...`) restano supportati **fino
+alla prossima major**. Da questa minor sono considerati legacy: i consumer
+devono passare agli entry point dichiarati in `package.json#exports`.
+
+## Mappa consigliata
+
+| Uso | Import consigliato | Legacy |
+| --- | --- | --- |
+| Avvio Accessi Service | `emilsoftware-utilities/accessi/server` | root barrel, `dist/accessi-module` |
+| Contratti e helper browser-safe | `emilsoftware-utilities/accessi/contracts` | `dist/accessi-module/Dtos` |
+| DTO Nest con validazione | `emilsoftware-utilities/accessi/contracts/dtos` | `dist/accessi-module/Dtos` |
+| Verifica JWT in un backend fratello | `emilsoftware-utilities/accessi/resource-server` | `dist/accessi-module/...` |
+| Client OpenAPI completo | `emilsoftware-utilities/accessi/client` | root barrel |
+| Client solo API pubbliche | `emilsoftware-utilities/accessi/client/public` | — |
+| Client solo API admin | `emilsoftware-utilities/accessi/client/admin` | — |
+| Client service-to-service | `emilsoftware-utilities/accessi/client/service` | — |
+| OpenAPI merge/setup | `emilsoftware-utilities/accessi/openapi` | root barrel |
+| URL console e ticket | `emilsoftware-utilities/accessi/console` | root barrel |
+| Asset UI frameworkless | `emilsoftware-utilities/accessi/ui` | — |
+
+```ts
+// Corretto
+import { initializeAccessiModule } from 'emilsoftware-utilities/accessi/server';
+import { createAccessiTokenVerifier } from 'emilsoftware-utilities/accessi/resource-server';
+import { login } from 'emilsoftware-utilities/accessi/client/public';
+
+// Legacy: continua a funzionare, ma verra rimosso in una major
+import { initializeAccessiModule } from 'emilsoftware-utilities';
+```
+
+## Perché
+
+- Il root barrel importa NestJS, modulo Accessi, Allegati, OpenAPI e utility:
+  un frontend che importa un solo helper paga tutto il grafo.
+- Gli scope `client/public`, `client/admin` e `client/service` impediscono che
+  un bundle pubblico includa operazioni amministrative o service token.
+- `accessi/contracts` è browser-safe: non trascina database, SMTP o Nest.
+- Gli entry point sono parte del contratto del pacchetto: i deep import non lo
+  sono e possono cambiare layout in una minor.
+
+## Piano
+
+1. **Ora**: nuovi consumer usano gli entry point; il root barrel e i deep import
+   funzionano senza warning runtime.
+2. **Prossima major**: il root barrel Accessi verrà ridotto ai soli simboli non
+   Accessi (Logger, Orm, Utilities, ...). I deep import non saranno più
+   supportati.
+3. **Dopo la major**: eventuale split in pacchetti separati, secondo
+   `docs/adr/0001-split-package.md`.
+
+Nessuna rimozione avviene in una minor: i consumer hanno almeno un ciclo di
+rilascio per migrare.
+
+## Verifica
+
+```bash
+npm run test:pack   # importa il tarball pubblicato e i subpath
+```
+
+Il test `test/import-entrypoints.cjs` carica ogni entry point consigliato,
+verifica i simboli principali e controlla che ogni subpath sia dichiarato in
+`package.json#exports`.

package/docs/jwt-key-rotation.md

@@ -0,0 +1,143 @@
+# Rotazione delle chiavi JWT
+
+Accessi firma gli access token (e i refresh token, se abilitati) con una chiave
+corrente e pubblica le chiavi pubbliche nella JWKS. La rotazione non deve
+invalidare i token gia emessi: durante il rollout la JWKS contiene la chiave
+nuova e quelle precedenti, e la verifica accetta entrambe.
+
+Riferimenti:
+
+- `jwtOptions.keyId`, `jwtOptions.previousPublicKeys`, `jwtOptions.onUnknownKeyId`
+- `generate-accessi-jwt-keys.cjs` (prima generazione)
+- `rotate-accessi-jwt-keys.cjs` (rotazione)
+
+## Modello
+
+| Elemento | Ruolo |
+| --- | --- |
+| `jwtOptions.privateKey` / `publicKey` | chiave corrente: firma i nuovi token |
+| `jwtOptions.keyId` | `kid` pubblicato nell'header e nella JWKS |
+| `jwtOptions.previousPublicKeys` | chiavi pubbliche ancora accettate in verifica |
+| `ACCESSI_JWT_PREVIOUS_PUBLIC_KEYS` | le stesse chiavi lette da env, in JSON |
+| `jwtOptions.onUnknownKeyId` | alert quando un token usa un `kid` sconosciuto |
+
+Senza `keyId`, Accessi usa il fingerprint SHA-256 della chiave pubblica
+(`base64url`, primi 16 caratteri). Lo stesso valore viene usato dallo script di
+rotazione e dal resource server.
+
+## Configurazione da env
+
+```bash
+ACCESSI_JWT_ALGORITHM=RS256
+ACCESSI_JWT_PRIVATE_KEY="$(cat jwt-private.pem)"
+ACCESSI_JWT_PUBLIC_KEY="$(cat jwt-public.pem)"
+ACCESSI_JWT_KEY_ID=2026-10
+ACCESSI_JWT_PREVIOUS_PUBLIC_KEYS='[
+  { "keyId": "2026-04", "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" }
+]'
+```
+
+Forme accettate nell'array:
+
+- stringa PEM;
+- oggetto `{ "publicKey": "<PEM>", "keyId": "<kid>", "algorithm": "RS256" }`.
+
+`keyId` e `algorithm` sono opzionali. Le sequenze `\n` letterali vengono
+convertite in newline, cosi il valore resta su una riga nel secret manager. Un
+JSON malformato o una chiave non PEM bloccano il boot (`ACCESSI_JWT_PREVIOUS_KEY_INVALID`),
+invece di lasciare token non verificabili in produzione.
+
+Con `HS256` le chiavi precedenti sono ignorate: la rotazione HMAC richiede di
+cambiare `jwtOptions.secret`, che invalida tutti i token. Per una rotazione
+senza interruzioni usare RS256 o ES256.
+
+## Procedura di rotazione
+
+1. **Genera la nuova coppia** con lo script, passando la chiave corrente come
+   precedente:
+
+   ```bash
+   npm run accessi:rotate-jwt-keys -- \
+     --out ./keys-2026-10 \
+     --current-public-key-file ./keys-2026-04/jwt-public.pem \
+     --current-key-id 2026-04
+   ```
+
+   Lo script scrive `jwt-private.pem`, `jwt-public.pem`, `jwks.json` e
+   `rotation.json` (contiene i valori `ACCESSI_*` da mettere nel secret manager).
+   Con `--previous-file` o `--previous` importa le chiavi precedenti gia in uso;
+   `--retain N` limita quante mantenerne (default 3).
+
+2. **Consumatori con JWKS**: nessuna azione. Al primo token con `kid` nuovo il
+   resource server forza un refresh della JWKS (throttle default 5 s,
+   `jwt.jwks.minRefreshIntervalMs`) e continua a verificare i token vecchi con le
+   chiavi precedenti.
+
+3. **Consumatori con `publicKey` statica**: distribuisci prima la nuova chiave
+   pubblica (o passa a `jwt.jwks`), poi cambia la chiave di firma. Chi usa la
+   sola chiave statica non puo conoscere in anticipo la chiave nuova.
+
+4. **Deploy di Accessi** con i nuovi valori. La JWKS pubblica subito nuova
+   chiave + precedenti, quindi i token emessi prima restano validi.
+
+5. **Verifica il rollout**:
+
+   ```bash
+   node scripts/rotate-accessi-jwt-keys.cjs --out ./keys-2026-10 \
+     --check https://accessi.example.com/api/accessi/.well-known/jwks.json --only-check
+   ```
+
+   Il comando fallisce se un `kid` del documento non e pubblicato. Esegui la
+   verifica su ogni istanza dietro il load balancer (o sull'endpoint pubblico)
+   prima di considerare conclusa la rotazione.
+
+6. **Rimuovi le chiavi precedenti** solo dopo la durata massima dei token:
+   `max(jwtOptions.expiresIn, jwtOptions.refreshExpiresIn)`. Finche restano in
+   `previousPublicKeys` i refresh token firmati con la vecchia chiave continuano
+   a funzionare.
+
+## Rollback
+
+Se il deploy della nuova chiave va storto, ripristina i valori precedenti di
+`privateKey`, `publicKey`, `keyId` e `previousPublicKeys`: i token firmati con la
+chiave nuova smettono di essere validi, quelli vecchi tornano a esserlo. Per
+questo la vecchia chiave privata va conservata nel secret manager finche la
+rotazione non e conclusa.
+
+## Alert su `kid` sconosciuto
+
+Un `kid` assente da chiave corrente e precedenti indica una rotazione incompleta
+o un token manomesso. Collega l'evento al tuo sistema di allerta:
+
+```ts
+const accessiOptions: AccessiOptions = {
+  // ...
+  jwtOptions: {
+    // ...
+    onUnknownKeyId: ({ keyId, algorithm, purpose }) => {
+      logger.warn({ keyId, algorithm, purpose }, 'JWT kid sconosciuto');
+      metrics.increment('accessi_jwt_unknown_kid');
+    },
+  },
+};
+
+// Resource server con JWKS remoto
+const jwtOptions: AccessiResourceServerJwtOptions = {
+  jwks: { url: 'https://accessi.example.com/api/accessi/.well-known/jwks.json' },
+  onUnknownKeyId: ({ kid, algorithm, source }) => {
+    logger.warn({ kid, algorithm, source }, 'kid non presente nella JWKS');
+  },
+};
+```
+
+L'evento non cambia l'esito dell'autenticazione: l'eccezione di un logger o di
+un webhook non trasforma un `401` in un `500`.
+
+## Cache e tempi
+
+- La JWKS Accessi risponde con `Cache-Control: public, max-age=300`.
+- Il resource server usa `cacheTtlMs` (default 300000) e, su `kid` sconosciuto,
+  un solo refresh forzato non piu frequente di `minRefreshIntervalMs` (default
+  5000). Un flood di `kid` inventati non puo martellare la JWKS.
+- Con CDN o reverse proxy davanti alla JWKS, non impostare un TTL superiore a
+  `cacheTtlMs`: la rotazione resterebbe invisibile fino alla scadenza della cache.

package/docs/metrics.md

@@ -0,0 +1,153 @@
+# Metriche e alert
+
+Accessi espone metriche di dominio in formato Prometheus. Il servizio standalone
+le include in `/health/metrics` insieme alle metriche HTTP di base; un host
+Nest/Express può montare `renderAccessiMetrics()` su una propria rotta protetta.
+
+```ts
+import { renderAccessiMetrics } from 'emilsoftware-utilities/accessi/server';
+
+app.get('/internal/accessi-metrics', (_req, res) => {
+  res.type('text/plain; version=0.0.4').send(renderAccessiMetrics());
+});
+```
+
+Le metriche sono attive per default. Per disattivarle:
+
+```ts
+const accessiOptions: AccessiOptions = {
+  // ...
+  metrics: { enabled: false },
+};
+```
+
+Per inviarle a OpenTelemetry, StatsD o un altro sistema:
+
+```ts
+const accessiOptions: AccessiOptions = {
+  metrics: {
+    prefix: 'accessi',
+    sink: {
+      increment: (name, value, labels) => meter.createCounter(name).add(value, labels),
+      observe: (name, valueMs, labels) => histogram.record(valueMs, labels),
+    },
+  },
+};
+```
+
+`prefix` (default `accessi`) si applica alle metriche emesse dai controller; gli
+store Redis usano il registry globale, sempre renderizzabile con
+`renderAccessiMetrics()`.
+
+## Metriche di dominio
+
+| Metrica | Tipo | Label | Significato |
+| --- | --- | --- | --- |
+| `accessi_auth_login_total` | counter | `result` = `success`, `failure`, `challenge`, `password_required`, `password_expired`, `sso_only`, `rate_limited`, `error` | esito del login |
+| `accessi_auth_login_duration_ms` | histogram | — | durata del login |
+| `accessi_auth_two_factor_total` | counter | `action` = `verify`/`resend`, `result` | verifica e reinvio 2FA |
+| `accessi_auth_two_factor_duration_ms` | histogram | `action` | durata verifica 2FA |
+| `accessi_auth_refresh_total` | counter | `result` = `success`, `invalid`, `reuse`, `family_revoked`, `store_unavailable`, `rate_limited` | esito del refresh |
+| `accessi_auth_refresh_duration_ms` | histogram | — | durata del refresh |
+| `accessi_refresh_reuse_total` | counter | `user_sessions_revoked` | riuso di refresh token oltre la grace |
+| `accessi_refresh_family_revoked_total` | counter | `reason` | famiglie revocate |
+| `accessi_rate_limit_blocked_total` | counter | `scope`, `layer` = `public`/`edge`/`service_token` | richieste bloccate dal rate limit |
+| `accessi_introspection_total` | counter | `result` = `active`, `inactive`, `bad_request`, `error` | introspection service-to-service |
+| `accessi_introspection_duration_ms` | histogram | — | durata introspection |
+| `accessi_jwks_requests_total` | counter | `result` = `ok`, `unavailable` | richieste JWKS |
+| `accessi_jwt_unknown_key_id_total` | counter | `purpose`, `source`, `algorithm` | token con `kid` non riconosciuto |
+| `accessi_sessions_revoked_total` | counter | `reason` = `manual`, `password_change`, `disabled`, `deleted`, `refresh_token_reuse`, ... | revoche sessioni |
+| `accessi_console_ticket_total` | counter | `action` = `create`/`exchange`, `result` | ticket di ingresso console |
+| `accessi_store_errors_total` | counter | `store` | errori degli store Redis |
+| `accessi_store_operation_duration_ms` | histogram | `store` | latenza degli script Lua Redis |
+
+Gli store strumentati sono `rate_limit`, `edge_rate_limit`, `service_token_rate_limit`,
+`console_entry`, `session_revocation`, `access_token_revocation` e
+`refresh_token_rotation`.
+
+## Alert suggeriti
+
+Esempio di regole Prometheus. Le soglie vanno tarate sul traffico reale.
+
+```yaml
+groups:
+  - name: accessi
+    rules:
+      - alert: AccessiLoginErrorRate
+        expr: |
+          sum(rate(accessi_auth_login_total{result=~"failure|error"}[5m]))
+            /
+          clamp_min(sum(rate(accessi_auth_login_total[5m])), 0.001)
+            > 0.3
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Oltre il 30% dei login fallisce da 10 minuti"
+
+      - alert: AccessiRefreshReuse
+        expr: increase(accessi_refresh_reuse_total[5m]) > 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Riuso di refresh token rilevato: verificare possibili furti"
+
+      - alert: AccessiRateLimitSpike
+        expr: sum(rate(accessi_rate_limit_blocked_total[5m])) > 20
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Molte richieste bloccate dal rate limit: possibile brute force"
+
+      - alert: AccessiUnknownJwtKid
+        expr: increase(accessi_jwt_unknown_key_id_total[5m]) > 0
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Token con kid sconosciuto: rotazione chiavi incompleta?"
+
+      - alert: AccessiRedisStoreDown
+        expr: increase(accessi_store_errors_total[5m]) > 3
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Errori Redis: revoca, rotazione o rate limit non affidabili"
+
+      - alert: AccessiStoreLatency
+        expr: |
+          histogram_quantile(
+            0.95,
+            sum by (le, store) (rate(accessi_store_operation_duration_ms_bucket[5m]))
+          ) > 50
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "p95 degli script Redis sopra 50 ms per {{ $labels.store }}"
+
+      - alert: AccessiIntrospectionErrors
+        expr: |
+          sum(rate(accessi_introspection_total{result="error"}[5m]))
+            /
+          clamp_min(sum(rate(accessi_introspection_total[5m])), 0.001)
+            > 0.05
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Errori di introspection oltre il 5%"
+```
+
+## Note
+
+- Non usare label ad alta cardinalità (email, `jti`, IP): le metriche Accessi
+  non le includono.
+- `accessi_jwt_unknown_key_id_total` collega la rotazione chiavi descritta in
+  `docs/jwt-key-rotation.md`: un aumento dopo un deploy segnala che un
+  consumatore non ha aggiornato la JWKS o la chiave statica.
+- Le metriche non sostituiscono l'audit: per gli eventi di sicurezza usare
+  `auditAccessi` e la sua persistenza.