emilsoftware-utilities 2.0.0-dev.67 → 2.0.0-dev.69

package/integration-prompt.md

@@ -74,6 +74,60 @@ const { nestApp, document } = await initializeAccessiModule(app, options);
 
 Aprire la porta HTTP solo dopo l'await.
 
+### Avvio standalone
+
+Per un servizio Accessi autonomo:
+
+```ts
+import { startAccessiService } from "emilsoftware-utilities/accessi/server";
+
+await startAccessiService({
+  port: Number(process.env.PORT ?? 3000),
+  healthPath: "/health",
+  metrics: true,
+});
+```
+
+Oppure:
+
+```bash
+npm run accessi:serve
+```
+
+Endpoint:
+
+```text
+GET /health/live
+GET /health/ready
+GET /health/metrics
+```
+
+`/health/ready` controlla bootstrap, database, schema, store Redis configurati e `readinessChecks` custom. `startAccessiService` registra SIGTERM/SIGINT e chiude Nest e i pool Firebird.
+
+In produzione il servizio viene eseguito come processo Node con systemd/PM2/supervisor:
+
+```bash
+npm run accessi:serve:dist
+```
+
+Dettagli e esempio systemd: `docs/standalone-service.md`.
+
+### Validazione configurazione
+
+```ts
+import {
+  assertValidAccessiOptions,
+  validateAccessiOptions,
+} from "emilsoftware-utilities/accessi/server";
+
+const validation = validateAccessiOptions(options);
+// validation.errors / validation.warnings
+
+assertValidAccessiOptions(options); // fail-fast
+```
+
+`createAccessiService` la applica automaticamente. Controlla JWT/key, DB, encryption key, URL email, rate limit, console entry e `http`.
+
 ### Bootstrap Nest
 
 ```ts
@@ -150,6 +204,151 @@ const merged = mergeOpenApiDocuments(hostDocument, accessiDocument, {
 });
 ```
 
+### HTTP, CORS e proxy
+
+```ts
+http: {
+  cors: {
+    origin: ["https://app.example.com"],
+    credentials: false,
+  },
+  trustProxy: 1, // load balancer/reverse proxy
+  securityHeaders: true,
+}
+```
+
+- `cors: false` disabilita CORS.
+- `trustProxy` e obbligatorio per rate limit corretti dietro proxy.
+- `securityHeaders` aggiunge `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`.
+- Con Bearer token non serve CSRF. Se usi cookie httpOnly, aggiungi CSRF e cookie same-site.
+
+### JWKS e rotazione chiavi
+
+Con RS256/ES256 Accessi pubblica automaticamente:
+
+```text
+GET /accessi/.well-known/jwks.json
+```
+
+Configurazione:
+
+```ts
+jwtOptions: {
+  algorithm: "RS256",
+  privateKey: process.env.ACCESSI_JWT_PRIVATE_KEY,
+  publicKey: process.env.ACCESSI_JWT_PUBLIC_KEY,
+  keyId: "accessi-2026-02",
+  jwksPath: "accessi/.well-known/jwks.json",
+  previousPublicKeys: [
+    {
+      publicKey: process.env.ACCESSI_JWT_PUBLIC_KEY_2026_01!,
+      keyId: "accessi-2026-01",
+      algorithm: "RS256",
+    },
+  ],
+}
+```
+
+Rotazione:
+
+1. generare la nuova coppia
+2. pubblicare la nuova chiave mantenendo la precedente in `previousPublicKeys`
+3. firmare con la nuova `keyId`
+4. attendere la scadenza massima dei token + il TTL cache della JWKS (default 5 minuti)
+5. rimuovere la chiave precedente
+
+Per un'app Nest esistente si può usare `setupAccessiJwks(app.getHttpAdapter().getInstance(), options)`.
+
+### Store ticket console
+
+Il default è in memoria, adatto a una sola istanza. In multi-istanza configurare uno store condiviso:
+
+```ts
+import { createRedisConsoleEntryStore } from "emilsoftware-utilities/accessi/server";
+
+consoleEntry: {
+  ttlMs: 60_000,
+  store: createRedisConsoleEntryStore({
+    client: redis, // ioredis o client compatibile con eval(script, numKeys, ...args)
+    encryptionKey: process.env.ACCESSI_CONSOLE_ENTRY_KEY!,
+    keyPrefix: "accessi:console-entry:",
+  }),
+}
+```
+
+Lo store Redis:
+
+- cifra il JWT con AES-256-GCM
+- usa `SET ... PX ... NX` con TTL
+- consuma con `GET` + `DEL` atomici in Lua
+- rende il ticket monouso anche tra istanze diverse
+
+Se lo store condiviso non è raggiungibile, la console deve fallire chiusa.
+
+### Rate limit condiviso
+
+Con più istanze anche i rate limit devono usare uno store condiviso:
+
+```ts
+import { createRedisRateLimitStore } from "emilsoftware-utilities/accessi/server";
+
+const rateLimitStore = createRedisRateLimitStore({
+  client: redis, // ioredis o client compatibile con eval(script, numKeys, ...args)
+  keyPrefix: "accessi:rate:",
+});
+
+publicAuthRateLimit: {
+  enabled: true,
+  store: rateLimitStore,
+  login: { windowMs: 15 * 60_000, maxAttempts: 10 },
+  twoFactorVerify: { windowMs: 15 * 60_000, maxAttempts: 20 },
+},
+
+serviceTokens: {
+  enabled: true,
+  rateLimitStore: rateLimitStore,
+},
+```
+
+Lo store Redis usa `INCR` + `PEXPIRE` atomici:
+
+- conta tentativi per IP e per soggetto (email, challenge, ticket, tokenId);
+- il limite è globale tra le istanze;
+- non viene azzerato da un restart;
+- se Redis non è raggiungibile il controllo fallisce chiuso: l’endpoint risponde con errore, non autorizza.
+
+Default: store in memoria. Va bene per una singola istanza o per ambienti di sviluppo.
+
+### Edge rate limit per IP
+
+Per una soglia grossolana davanti alle rotte Accessi:
+
+```ts
+edgeRateLimit: {
+  enabled: true,
+  windowMs: 60_000,
+  maxAttempts: 300,
+  store: rateLimitStore, // stesso store Redis, opzionale
+}
+```
+
+Viene applicato prima del dispatcher Accessi e copre `/api/accessi/*`, OpenAPI e JWKS. In caso di store non disponibile risponde `503 ACCESSI_RATE_LIMIT_UNAVAILABLE`; quando la soglia è superata risponde `429 ACCESSI_EDGE_RATE_LIMITED` con `Retry-After`.
+
+Il gateway/API gateway resta consigliato per:
+
+- limiti di connessione e burst;
+- bot protection e WAF;
+- rate limit per IP a livello di rete;
+- blocco geografico o reputazionale.
+
+Configurazioni di riferimento: `docs/gateway-rate-limit.md`.
+
+### Audit
+
+Resource server ed edge rate limit producono eventi strutturati tramite `auditAccessi`. I campi sensibili vengono redatti dal Logger. Disattivabile con `audit: false` nelle rispettive opzioni.
+
+Nel servizio standalone le metriche Prometheus sono su `/health/metrics`.
+
 ---
 
 ## 4. Backend fratello — Express
@@ -190,7 +389,9 @@ Dopo il middleware:
 - **HS256**: usare `jwt.serverSecret` con `ACCESSI_JWT_SECRET`. Il resource server deriva la chiave access con la stessa KDF del server.
 - **RS256/ES256**: usare `jwt.publicKey` PEM oppure `jwt.jwks.url`. Consigliato in multi-servizio.
 - Il server Accessi supporta `jwtOptions.algorithm`, `privateKey`, `publicKey`, `keyId`.
-- Accessi non espone ancora un endpoint JWKS integrato: pubblicare la chiave pubblica con il proprio hosting/reverse proxy oppure usare `publicKey` PEM.
+- Accessi espone la JWKS su `jwtOptions.jwksPath` (default `accessi/.well-known/jwks.json`) quando usa RS/ES.
+- La JWKS include la chiave corrente e le `previousPublicKeys`, per la rotazione senza downtime.
+- Configurare il resource server con `jwks: { url: "https://accessi.example.com/accessi/.well-known/jwks.json" }`.
 
 ### Errori
 
@@ -274,6 +475,60 @@ Risposta:
 - Il resource server cachea i risultati attivi per `cacheTtlMs` (default 30s). I risultati inattivi non sono cachati.
 - Fail closed: se Accessi Service non risponde, la richiesta non viene autorizzata.
 
+### SSO exchange service-to-service
+
+Se un backend fratello valida un provider SSO proprio, non deve duplicare utenti o grant. Dopo aver verificato firma, issuer, audience e subject del provider, chiama:
+
+```http
+POST /api/accessi/federated-auth/exchange
+Authorization: Bearer <service-token>
+Content-Type: application/json
+
+{ "provider": "azure-ad-acme-produzione", "subject": "<oid o sub>" }
+```
+
+Scope richiesto: `accessi:federated:exchange`.
+
+La risposta contiene:
+
+- `codiceUtente`
+- `login` con profilo, grant e token
+- `token` assente quando è richiesta la verifica 2FA
+
+Accessi non riceve il token del provider: riceve solo l'identità esterna già verificata.
+
+### Revoca sessioni
+
+Configurazione:
+
+```ts
+import { createRedisSessionRevocationStore } from "emilsoftware-utilities/accessi/server";
+
+sessionRevocation: {
+  store: createRedisSessionRevocationStore({
+    client: redis,
+    ttlMs: 30 * 24 * 60 * 60 * 1000, // maggiore della durata massima dei token
+  }),
+}
+```
+
+Endpoint utente:
+
+```http
+POST /api/accessi/auth/revoke-sessions
+Authorization: Bearer <access-token>
+```
+
+Invalida i token emessi prima della chiamata. I token emessi dopo restano validi. Per i backend fratelli configurare lo stesso store anche nel resource server:
+
+```ts
+revocation: {
+  store: revocationStore,
+}
+```
+
+Senza store condiviso la revoca vale solo nel processo che la esegue.
+
 ---
 
 ## 7. Frontend
@@ -303,6 +558,29 @@ configureAccessiClient({
 });
 ```
 
+Se `jwtOptions.refreshExpiresIn` è configurato, la risposta contiene anche `refreshToken`. Conservarlo separatamente dall’access token e usarlo su:
+
+```http
+POST /api/accessi/auth/refresh
+Content-Type: application/json
+
+{ "refreshToken": "<refresh-token>" }
+```
+
+La risposta contiene un nuovo `token` e un nuovo `refreshToken`. Il refresh token ha `typ: "refresh"` e non va mai usato come Bearer sulle API.
+
+Per rendere il refresh token monouso anche in multi-istanza:
+
+```ts
+import { createRedisRefreshTokenRotationStore } from "emilsoftware-utilities/accessi/server";
+
+refreshTokenRotation: {
+  store: createRedisRefreshTokenRotationStore({ client: redis }),
+}
+```
+
+Ogni refresh consuma il vecchio `jti` in modo atomico. Due refresh concorrenti dello stesso token producono un solo successo.
+
 Per token che cambiano nel tempo:
 
 ```ts
@@ -332,6 +610,7 @@ const consoleUrl = buildAccessiConsoleUrl("https://accessi.example.com", {
 - Il ticket e monouso, dura 60 secondi.
 - Per il 2FA handoff usare `twoFactorChallengeId`.
 - Se la console deve stare sullo stesso dominio, fare reverse proxy di `/api/accessi/*` verso Accessi Service, non copiare gli asset.
+- Se la UI della console è su un dominio diverso dall’API, configurare `consoleApiBaseUrl`: Accessi inietta `window.__ACCESSI_API_BASE_URL__` nella pagina servita.
 
 ### Web component
 
@@ -362,6 +641,7 @@ Per chiamare l'introspection o API tecniche:
 2. Creare un token dalla console o con `POST /api/accessi/service-token`.
 3. Assegnare lo scope minimo necessario:
    - `accessi:introspect` per l'introspection
+   - `accessi:federated:exchange` per scambiare un'identita SSO verificata
    - altri scope applicativi secondo necessita
 4. Conservarlo come secret nel backend fratello.
 5. Ruotarlo periodicamente; il segreto e mostrato una sola volta.
@@ -397,6 +677,7 @@ ACCESSI_DB_PASSWORD=
 ACCESSI_ENCRYPTION_KEY=
 ACCESSI_JWT_SECRET=
 ACCESSI_JWT_EXPIRES=24h
+ACCESSI_JWT_REFRESH_EXPIRES=30d
 ACCESSI_JWT_ISSUER=accessi
 ACCESSI_JWT_AUDIENCE=backend-app
 # Opzionale RS256
@@ -404,6 +685,9 @@ ACCESSI_JWT_ALGORITHM=RS256
 ACCESSI_JWT_PRIVATE_KEY=
 ACCESSI_JWT_PUBLIC_KEY=
 ACCESSI_JWT_KEY_ID=
+ACCESSI_JWKS_PATH=accessi/.well-known/jwks.json
+ACCESSI_CONSOLE_ENTRY_TTL_MS=60000
+ACCESSI_CONSOLE_ENTRY_KEY=
 SMTP_HOST=
 SMTP_PORT=587
 SMTP_USER=
@@ -428,6 +712,7 @@ Frontend:
 ```env
 ACCESSI_API_BASE_URL=https://accessi.example.com
 ACCESSI_CONSOLE_URL=https://accessi.example.com/api/accessi/console
+ACCESSI_JWKS_URL=https://accessi.example.com/accessi/.well-known/jwks.json
 ```
 
 ---
@@ -443,16 +728,22 @@ Checklist:
 5. Spostare la console una sola volta.
 6. Passare i backend fratelli a `resource-server`.
 7. Configurare un service token con `accessi:introspect`.
-8. Testare:
+8. Pubblicare la JWKS e configurare i resource server su `jwks.url`.
+9. In multi-istanza configurare `consoleEntry.store`, `publicAuthRateLimit.store` e `serviceTokens.rateLimitStore` con Redis.
+10. Testare:
    - login
    - token valido
    - token scaduto
    - utente disabilitato
    - revoca grants
    - Accessi Service spento (fail closed)
-   - console entry ticket
-9. Aggiornare CORS se i frontend cambiano dominio.
-10. Aggiornare monitoraggio e log senza includere token.
+   - console entry ticket su istanze diverse
+   - rate limit condiviso tra istanze
+   - rotazione JWKS con vecchia chiave ancora valida
+11. Aggiornare CORS se i frontend cambiano dominio.
+12. Aggiornare monitoraggio e log senza includere token.
+13. Eseguire `npm run check:accessi-openapi` e `npm run typecheck` prima del rilascio.
+14. Dopo una modifica intenzionale al contratto, aggiornare il fingerprint con `npm run accessi:update-openapi-fingerprint` e includerlo nel commit.
 
 ---
 
@@ -474,8 +765,8 @@ Checklist:
 
 ## 14. Limiti attuali da conoscere
 
-- I ticket di ingresso console sono in memoria del processo: con piu istanze di Accessi Service servono sticky session o uno store condiviso.
-- I rate limit pubblici e dei service token sono in memoria.
-- Accessi non espone ancora un endpoint JWKS pronto: il resource server sa verificare una JWKS, ma la chiave pubblica va pubblicata dall'host.
+- I ticket di ingresso console usano lo store in memoria per default: in multi-istanza configurare `consoleEntry.store` con Redis. Lo store Redis e cifrato e monouso, ma richiede un client Redis compatibile.
+- I rate limit usano lo store in memoria per default: in multi-istanza configurare `publicAuthRateLimit.store` e `serviceTokens.rateLimitStore` con Redis. Il gateway resta comunque consigliato per i limiti grossolani per IP.
 - Il client generato e completo (include endpoint amministrativi): non distribuirlo a frontend non amministrativi senza valutare gli endpoint esposti. Per un client pubblico ridotto, generare un sottoinsieme per tag con Orval.
 - I DTO in `accessi/contracts/dtos` dipendono da Nest/class-validator: non sono pensati per bundle frontend minimali.
+- La JWKS viene pubblicata solo con algoritmi asimmetrici: con HS256 non esiste una chiave pubblica da distribuire.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emilsoftware-utilities",
-  "version": "2.0.0-dev.67",
+  "version": "2.0.0-dev.69",
   "description": "Utilities for EmilSoftware",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -87,7 +87,9 @@
   },
   "scripts": {
     "release": "semantic-release",
-    "build": "npm run generate: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 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",
     "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",
@@ -95,14 +97,17 @@
     "copy-views": "node copy-views.js",
     "db:update:accessi": "ts-node src/accessi-module/database-updates/runAccessiDbUpdate.ts",
     "db:update:accessi:dist": "npm run build && node dist/accessi-module/database-updates/runAccessiDbUpdate.js",
+    "accessi:serve": "ts-node src/scripts/startAccessiService.ts",
+    "accessi:serve:dist": "node dist/scripts/startAccessiService.js",
+    "accessi:generate-jwt-keys": "node scripts/generate-accessi-jwt-keys.cjs",
     "db:catalog:accessi": "ts-node src/accessi-module/database-updates/runAccessiCatalogMigrations.ts",
     "db:catalog:accessi:check": "ts-node src/accessi-module/database-updates/runAccessiCatalogMigrations.ts --check",
     "prepublishOnly": "npm run build",
     "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: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: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: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:accessi": "npm run test:unit",
     "test:all": "npm test && npm run test:integration",
     "test:integration": "node test/integration/run-firebird.cjs 5",
@@ -183,7 +188,8 @@
   },
   "files": [
     "dist",
-    "integration-prompt.md"
+    "integration-prompt.md",
+    "docs"
   ],
   "config": {
     "commitizen": {