emilsoftware-utilities 2.0.0-dev.72 → 2.0.0-dev.74

package/docs/accessi-openapi-breaking-allowlist.json

@@ -0,0 +1 @@
+[]

package/docs/adr/0001-split-package.md

@@ -0,0 +1,79 @@
+# ADR 0001 — Split in pacchetti separati: contracts, client, resource-server, server
+
+- **Stato:** accettato
+- **Data:** 2026-10-30
+- **Issue:** #9
+- **Ambito:** packaging e rilascio di `emilsoftware-utilities`
+
+## Contesto
+
+Il package espone gia entry point separati (`accessi/server`, `accessi/resource-server`,
+`accessi/client` con gli scope `public`/`admin`/`service`, `accessi/contracts`, `accessi/openapi`,
+`accessi/console`, `accessi/ui`). Hanno però un unico `package.json`, un unico numero di versione e
+un unico ciclo di rilascio, mentre i consumer reali hanno esigenze diverse:
+
+- i frontend usano solo `contracts` e `client/public` e non devono scaricare Nest, Firebird o SMTP;
+- i backend fratelli usano `resource-server` e `client/service`;
+- solo il backend proprietario usa `server` (database, migrazioni, console).
+
+Oggi il tarball contiene tutto (~950 KB) e una modifica server-side obbliga un bump che i frontend
+devono comunque recepire. Lo split è però un cambio invasivo per i consumer e per la release.
+
+## Opzioni valutate
+
+| Opzione | Pro | Contro |
+| --- | --- | --- |
+| **A. Pacchetto singolo con entry point per scope (attuale)** | Zero migrazioni; un solo `npm ci`; types condivisi per costruzione; release unica e semplice; il tree-shaking elimina il codice non importato | Il tarball contiene dipendenze server anche per i frontend; versione unica per domini diversi |
+| **B. Monorepo npm workspaces con 4 pacchetti** | Versioning indipendente; dipendenze minime per pacchetto; build/publish selettivi | Richiede cambiare toolchain, CI e release; 4 tarball da pubblicare; gestione versioni incrociate (`contracts` → `client`); migrazione dei consumer |
+| **C. Pacchetti in repository separati** | Massima indipendenza | Frammentazione, PR incrociate, release coordinate manualmente, overhead alto per un team piccolo |
+
+## Decisione
+
+Si adotta **l'opzione A** nel breve periodo, rafforzata dagli entry point per scope introdotti
+nell'issue #7 e verificati dal test `npm run test:pack`.
+
+Motivazioni:
+
+1. **Nessuna regressione:** gli import esistenti (`emilsoftware-utilities`,
+   `.../accessi/client`, ...) restano identici; una migrazione forzata avrebbe costo alto e
+   beneficio non dimostrato.
+2. **Tipi condivisi per costruzione:** un solo set di modelli generati da OpenAPI evita divergenze
+   tra client e contracts, che con pacchetti separati andrebbero versionati insieme.
+3. **Bundle:** i consumer browser usano `accessi/client/public` e `accessi/contracts`; con
+   `sideEffects` limitato ai soli moduli con effetti, i bundler eliminano il resto.
+4. **Release riproducibile:** `npm ci && npm run build && npm run test:pack` produce e verifica lo
+   stesso tarball; semantic-release pubblica un solo artefatto.
+
+Lo split resta un'opzione futura, non un rifiuto: le soglie che lo giustificherebbero sono elencate
+sotto.
+
+## Quando rivalutare
+
+Riaprire la decisione (ADR successivo) se si verifica almeno una di queste condizioni:
+
+- i frontend richiedono un rilascio di `contracts`/`client` indipendente da `server`;
+- il peso delle dipendenze server nel bundle browser diventa un problema non risolvibile con il
+  tree-shaking (es. consumer senza bundler);
+- il team cresce al punto da avere cicli di rilascio separati per server e client;
+- si rende necessario pubblicare su registry diversi o con licenze diverse.
+
+## Piano di migrazione (se e quando)
+
+1. Introdurre i workspace (`npm workspaces`) mantenendo i path pubblici attuali come facade.
+2. Estrarre per primo `contracts` (zero dipendenze runtime), poi `client`, poi `resource-server`,
+   infine `server`.
+3. Ogni pacchetto facade re-esporta dal nuovo package, così `accessi/client`, `accessi/contracts`,
+   ecc. continuano a funzionare senza modifiche ai consumer.
+4. Aggiungere una test matrix che installa i tarball di tutti i pacchetti insieme e verifica i path
+   legacy.
+5. Deprecare i facade solo in una major successiva, con guida di migrazione.
+
+## Conseguenze
+
+- **Versioning:** unico, gestito da semantic-release sul branch `dev` → `main`.
+- **Compatibilita:** garantita dall'export map e dallo smoke test del tarball
+  (`scripts/pack-smoke-consumer.cjs`) che copre ogni subpath e gli scope client.
+- **Build/publish riproducibili:** build dichiarativa (`npm run build`), configurazione npm
+  isolata nello smoke test, nessun passaggio manuale oltre al merge.
+- **Debito accettato:** il tarball include dipendenze server anche per i consumer frontend; è un
+  costo noto e monitorato, non un bug.

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/standalone-service.md

@@ -50,6 +50,31 @@ GET /health/metrics   -> metriche Prometheus testuali
 - `healthCheck()` degli store Redis configurati
 - `readinessChecks` aggiuntivi passati dal chiamante
 
+### Host Nest con `AccessiModule.forRoot`
+
+Un'app Nest che monta Accessi in-process ottiene gli stessi endpoint con il modulo di health:
+
+```ts
+import { AccessiModule, createAccessiHealthModule } from "emilsoftware-utilities/accessi/server";
+
+@Module({
+  imports: [
+    AccessiModule.forRoot(accessiOptions),
+    createAccessiHealthModule({
+      accessiOptions,
+      readinessChecks: [{ name: "coda", check: async () => queue.isReady() }],
+      path: "/health", // default
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Il contratto e identico al servizio standalone (200/503, `checks` con `bootstrap`, `database`,
+store configurati e check aggiuntivi). Per un uso programmatico (senza controller) ci sono
+`checkAccessiReadiness(accessiOptions, checks)`, `createAccessiLiveReport()` e
+`readinessHttpStatus(report)`.
+
 ## Esecuzione come processo
 
 In produzione il servizio viene eseguito come processo Node gestito da systemd, PM2 o dal supervisor del cliente:

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "emilsoftware-utilities",
-  "version": "2.0.0-dev.72",
+  "version": "2.0.0-dev.74",
   "description": "Utilities for EmilSoftware",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "accessi/*": [
+        "dist/accessi/*"
+      ]
+    }
+  },
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/firebird-compat.js",
+    "./dist/accessi-module/Console/console.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -105,9 +117,11 @@
   },
   "scripts": {
     "release": "semantic-release",
-    "build": "npm run generate:accessi-openapi && npm run check:accessi-openapi && npm run generate:accessi-client && npm run generate:accessi-wiki && tsc && tsc -p tsconfig.console.json --noEmit && npm run build:accessi-console && npm run copy-views",
+    "build": "npm run generate:accessi-openapi && npm run check:accessi-openapi && npm run check:accessi-openapi-diff && npm run generate:accessi-client && npm run generate:accessi-wiki && tsc && tsc -p tsconfig.console.json --noEmit && npm run build:accessi-console && npm run copy-views",
     "check:accessi-openapi": "node scripts/check-accessi-openapi.cjs",
     "accessi:update-openapi-fingerprint": "node scripts/check-accessi-openapi.cjs --update",
+    "check:accessi-openapi-diff": "node scripts/openapi-semantic-diff.cjs",
+    "accessi:update-openapi-baseline": "node scripts/openapi-semantic-diff.cjs --update",
     "generate:accessi-openapi": "ts-node --transpile-only src/scripts/generateAccessiOpenApi.ts",
     "generate:accessi-client": "orval --config orval.config.ts",
     "generate:accessi-wiki": "ts-node --transpile-only src/scripts/generateAccessiWiki.ts",
@@ -124,8 +138,8 @@
     "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: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: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: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: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",
@@ -134,6 +148,8 @@
     "test:integration:fb3": "node test/integration/run-firebird.cjs 3",
     "test:integration:fb25": "node test/integration/run-firebird.cjs 2.5",
     "test:accessi-console": "npm run build && node test/console-two-factor.cjs",
+    "test:pack": "node scripts/pack-smoke-test.cjs",
+    "test:proxy-ip": "node --test test/proxy-ip.cjs test/readiness.cjs",
     "accessi:seed-admin": "node scripts/seed-accessi-admin.cjs",
     "accessi:console": "node scripts/run-accessi-console.cjs",
     "test:accessi-schema": "node --test test/accessi-schema.cjs",