emilsoftware-utilities 2.0.0-dev.77 → 2.0.0-dev.78

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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emilsoftware-utilities",
-  "version": "2.0.0-dev.77",
+  "version": "2.0.0-dev.78",
   "description": "Utilities for EmilSoftware",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -139,12 +139,13 @@
     "typecheck": "tsc --noEmit",
     "lint": "node scripts/lint.cjs",
     "test": "npm run typecheck && npm run lint && npm run test:unit",
-    "test:unit": "node --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs test/accessi-client-scopes.cjs test/openapi-semantic-diff.cjs test/proxy-ip.cjs test/readiness.cjs test/jwt-key-rotation.cjs test/security-headers.cjs test/auth-cookies.cjs",
-    "test:coverage": "node --experimental-test-coverage --test-coverage-lines=50 --test-coverage-functions=60 --test-coverage-branches=60 --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs test/accessi-client-scopes.cjs test/openapi-semantic-diff.cjs test/proxy-ip.cjs test/readiness.cjs test/jwt-key-rotation.cjs test/security-headers.cjs test/auth-cookies.cjs",
+    "test:unit": "node --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs test/accessi-client-scopes.cjs test/openapi-semantic-diff.cjs test/proxy-ip.cjs test/readiness.cjs test/jwt-key-rotation.cjs test/security-headers.cjs test/auth-cookies.cjs test/metrics.cjs",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-lines=50 --test-coverage-functions=60 --test-coverage-branches=60 --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs test/accessi-client-scopes.cjs test/openapi-semantic-diff.cjs test/proxy-ip.cjs test/readiness.cjs test/jwt-key-rotation.cjs test/security-headers.cjs test/auth-cookies.cjs test/metrics.cjs",
     "test:accessi": "npm run test:unit",
     "test:all": "npm test && npm run test:integration && npm run test:integration:redis",
     "test:integration": "node test/integration/run-firebird.cjs 5",
     "test:integration:redis": "node --test test/integration/redis-stores.integration.cjs",
+    "test:load:redis": "node --test --test-concurrency=1 test/integration/redis-load.integration.cjs",
     "test:integration:fb5": "node test/integration/run-firebird.cjs 5",
     "test:integration:fb3": "node test/integration/run-firebird.cjs 3",
     "test:integration:fb25": "node test/integration/run-firebird.cjs 2.5",