emilsoftware-utilities 2.0.0-dev.83 → 2.0.0-dev.85

package/docs/quickstart-frontend.md

@@ -0,0 +1,217 @@
+# Quickstart: frontend
+
+Questa guida è per SPA, app mobile web o qualsiasi client browser che deve
+autenticare l'utente su Accessi e chiamare i backend con il JWT.
+
+Regola principale: il frontend usa **solo** `accessi/client/public`. Non importa
+`accessi/server`, `accessi/client/admin` o `accessi/client/service` e non vede
+mai il database, `encryptionKey`, SMTP o chiavi JWT.
+
+## Installazione
+
+```bash
+npm install emilsoftware-utilities
+```
+
+## Configurazione
+
+```ts
+import { configureAccessiClient } from 'emilsoftware-utilities/accessi/client/public';
+
+configureAccessiClient({
+  baseUrl: 'https://accessi.example.com',
+});
+```
+
+Se il token cambia nel tempo, usa un provider invece di un valore statico:
+
+```ts
+configureAccessiClient({
+  baseUrl: 'https://accessi.example.com',
+  getToken: () => authStore.getAccessToken(),
+});
+```
+
+## Login
+
+```ts
+import { login } from 'emilsoftware-utilities/accessi/client/public';
+
+const response = await login({ email, password });
+const result = response.data.Result;
+
+if (result.challenge?.twoFactorRequired) {
+  // Login incompleto: chiedi il codice e chiama verifyTwoFactor.
+  return showTwoFactorForm(result.challenge);
+}
+
+if (!result.token) {
+  // Può succedere con passwordless o configurazioni particolari:
+  // leggi result.passwordRequired e completa il flusso richiesto.
+  throw new Error('Login incompleto');
+}
+
+authStore.setAccessToken(result.token.value);
+authStore.setRefreshToken(result.refreshToken?.value ?? null);
+```
+
+Campi principali della risposta:
+
+| Campo | Significato |
+| --- | --- |
+| `Result.token.value` | Access token JWT |
+| `Result.token.expiresIn` | Durata in secondi |
+| `Result.refreshToken` | Refresh token, se `refreshExpiresIn` è configurato |
+| `Result.challenge` | Challenge 2FA: il login non è completo |
+| `Result.passwordRequired` | Passo password richiesto dal flusso passwordless |
+| `Result.utente` | Profilo utente |
+| `Result.userGrants` | Ruoli e abilitazioni per la UI |
+
+## 2FA
+
+```ts
+import { verifyTwoFactor, resendTwoFactor } from 'emilsoftware-utilities/accessi/client/public';
+
+const verified = await verifyTwoFactor({
+  challengeId: challenge.challengeId,
+  code,
+});
+const result = verified.data.Result;
+authStore.setAccessToken(result.token!.value);
+authStore.setRefreshToken(result.refreshToken?.value ?? null);
+```
+
+La challenge è un identificativo opaco, non un JWT: non usarla come Bearer e non
+conservarla come sessione. `resendTwoFactor` rispetta `resendAfterSeconds`.
+
+## Refresh e chiamate ai backend
+
+Il token va inviato ai backend, non solo ad Accessi:
+
+```ts
+async function apiFetch(input: RequestInfo, init: RequestInit = {}) {
+  const token = authStore.getAccessToken();
+  const response = await fetch(input, {
+    ...init,
+    headers: { ...init.headers, Authorization: `Bearer ${token}` },
+  });
+
+  if (response.status !== 401) return response;
+
+  const refreshToken = authStore.getRefreshToken();
+  if (!refreshToken) throw new Error('Sessione scaduta');
+
+  const refreshed = await refreshAccessToken({ refreshToken });
+  authStore.setAccessToken(refreshed.data.Result.token.value);
+  authStore.setRefreshToken(refreshed.data.Result.refreshToken?.value ?? null);
+
+  // Un solo retry: se fallisce di nuovo, torna al login.
+  return fetch(input, {
+    ...init,
+    headers: { ...init.headers, Authorization: `Bearer ${authStore.getAccessToken()}` },
+  });
+}
+```
+
+```ts
+import { refreshAccessToken } from 'emilsoftware-utilities/accessi/client/public';
+```
+
+Il refresh token ha `typ: "refresh"` e non è accettato dai backend come Bearer.
+
+## Reset password
+
+```ts
+import {
+  sendPasswordResetEmail,
+  resetPassword,
+} from 'emilsoftware-utilities/accessi/client/public';
+
+await sendPasswordResetEmail({ email });
+
+// Il token arriva dal link inviato per email.
+await resetPassword(tokenFromLink, { newPassword });
+```
+
+La password deve avere almeno 8 caratteri, una maiuscola, una minuscola, una
+cifra e un carattere speciale. Se non è conforme l'API risponde 400 con
+`ACCESSI_WEAK_PASSWORD`.
+
+## Logout e revoca
+
+```ts
+import { revokeToken, revokeSessions } from 'emilsoftware-utilities/accessi/client/public';
+
+await revokeToken({});          // revoca il token corrente
+await revokeSessions();        // revoca tutte le sessioni dell'utente
+authStore.clear();
+```
+
+La revoca per token richiede `accessTokenRevocation.store` configurato su Accessi
+Service; la revoca di tutte le sessioni richiede `sessionRevocation.store`.
+
+## Console
+
+```ts
+import { buildAccessiConsoleUrl } from 'emilsoftware-utilities/accessi/console';
+
+const url = buildAccessiConsoleUrl('https://accessi.example.com', {
+  entryTicket: ticket, // da POST /api/accessi/console/entry
+});
+window.location.assign(url);
+```
+
+Il ticket è monouso e dura 60 secondi. Il JWT non va mai nell'URL.
+
+## Più Accessi Service o più tenant
+
+```ts
+import { createAccessiPublicClient } from 'emilsoftware-utilities/accessi/client/public';
+
+const milano = createAccessiPublicClient({ baseUrl: 'https://accessi-milano.example.com' });
+const roma = createAccessiPublicClient({
+  baseUrl: 'https://accessi-roma.example.com',
+  token: tokenRoma,
+});
+```
+
+Le istanze non condividono base URL né token: sono sicure anche con richieste
+concorrenti.
+
+## Modalità cookie HttpOnly
+
+Se Accessi Service è configurato con `authCookie`, i token viaggiano in cookie
+`HttpOnly` e il browser non li legge da JavaScript. In questa modalità:
+
+- le richieste usano `credentials: 'include'`;
+- le richieste `POST`, `PUT`, `PATCH`, `DELETE` inviano `x-csrf-token` letto dal cookie `accessi_csrf`;
+- il client generato attiva il comportamento quando `window.__ACCESSI_AUTH_COOKIE__` è `true`;
+- non serve conservare il token in `localStorage`.
+
+Dettagli e limiti in [auth-cookies.md](auth-cookies.md).
+
+## Errori
+
+| HTTP / codice | Comportamento consigliato |
+| --- | --- |
+| 401 `AUTH_TOKEN_MISSING` / `AUTH_TOKEN_INVALID` | Prova refresh; se fallisce, torna al login |
+| 401 `AUTH_USER_DISABLED` | Logout e messaggio dedicato |
+| 403 `AUTH_INSUFFICIENT_PERMISSIONS` | Non fare logout: mostra permessi insufficienti |
+| 403 `AUTH_CSRF_INVALID` | Cookie mode: rileggi il cookie CSRF e ripeti |
+| 429 | Rispetta `Retry-After`, non ritentare in loop |
+| 503 `AUTH_INTROSPECTION_UNAVAILABLE` / `AUTH_JWKS_UNAVAILABLE` | Riprova con backoff; non cancellare la sessione |
+
+## Sicurezza
+
+- Non mettere JWT, refresh token, ticket console o service token nell'URL, nei log o nei messaggi di errore.
+- Non importare mai il client admin o service nel bundle pubblico.
+- Valuta token in memoria più refresh in storage sicuro; se non è possibile, usa la modalità cookie HttpOnly.
+- Configura CSP e header di sicurezza lato backend.
+- Non fidarti dei dati di autorizzazione presenti nel token per decisioni sensibili: il backend deve verificare i grant correnti con introspection.
+
+## Prossimi passi
+
+- [WIKI.md](../WIKI.md#login-refresh-2fa-e-reset-password) per il flusso completo.
+- [WIKI.md](../WIKI.md#modalità-cookie-httponly-e-csrf) per cookie e CSRF.
+- [auth-cookies.md](auth-cookies.md) per la configurazione server.
+- [quickstart-resource-server.md](quickstart-resource-server.md) se stai integrando anche il backend.

package/docs/quickstart-resource-server.md

@@ -0,0 +1,177 @@
+# Quickstart: backend fratello (resource server)
+
+Questa guida è per un backend che deve accettare i token emessi da Accessi
+Service ma **non** possiede il database Accessi. Non installare
+`AccessiModule` e non configurare credenziali Firebird di Accessi.
+
+## Scegli la modalità
+
+| Modalità | Quando usarla | Cosa serve |
+| --- | --- | --- |
+| Solo verifica JWT | La firma e i claim bastano; i grant non cambiano durante la sessione | Chiave pubblica/JWKS oppure segreto HS256 |
+| JWT + introspection | Servono ruoli e grant correnti, revoche e stato utente aggiornato | Service token con scope `accessi:introspect` |
+| Solo introspection | Vuoi che Accessi Service decida ogni richiesta | Service token e latenza di rete accettabile |
+
+In produzione multi-servizio usa RS256/ES256 con JWKS. HS256 con segreto
+condiviso è accettabile solo come transizione.
+
+## Express
+
+```ts
+import {
+  createAccessiAuthMiddleware,
+} from 'emilsoftware-utilities/accessi/resource-server';
+
+app.use(createAccessiAuthMiddleware({
+  mode: 'local',
+  jwt: {
+    jwks: { url: 'https://accessi.example.com/accessi/.well-known/jwks.json' },
+    issuer: 'https://accessi.example.com',
+    audience: 'backend-a',
+  },
+  introspection: {
+    url: 'https://accessi.example.com/api/accessi/auth/introspect',
+    serviceToken: process.env.ACCESSI_SERVICE_TOKEN!,
+    cacheTtlMs: 30_000,
+    timeoutMs: 3_000,
+  },
+  authorization: {
+    requirements: [{ menuCode: 'ORDINI', minPermissionLevel: 20 }],
+  },
+}));
+```
+
+Dopo il middleware:
+
+- `req.user`: payload autenticato.
+- `req.data`: alias storico di `req.user`.
+- `req.userGrants`: presente solo se la policy richiede i grant.
+- `req.accessi`: `{ token, user, codiceUtente, grants?, payload? }`.
+
+## NestJS
+
+```ts
+import { UseGuards, Get, Req } from '@nestjs/common';
+import {
+  createAccessiAuthGuard,
+  type AccessiAuthenticatedRequest,
+} from 'emilsoftware-utilities/accessi/resource-server';
+
+@UseGuards(createAccessiAuthGuard({
+  jwt: {
+    publicKey: process.env.ACCESSI_JWT_PUBLIC_KEY,
+    algorithms: ['RS256'],
+    issuer: 'https://accessi.example.com',
+    audience: 'backend-a',
+  },
+  introspection: {
+    url: process.env.ACCESSI_INTROSPECT_URL!,
+    serviceToken: process.env.ACCESSI_SERVICE_TOKEN!,
+  },
+  authorization: {
+    requirements: [{ menuCode: 'ORDINI', minPermissionLevel: 20 }],
+  },
+}))
+@Get('ordini')
+list(@Req() req: AccessiAuthenticatedRequest) {
+  return req.user;
+}
+```
+
+## Verifica solo JWT
+
+Se non ti servono i grant correnti, puoi usare il verifier senza middleware:
+
+```ts
+import { createAccessiTokenVerifier } from 'emilsoftware-utilities/accessi/resource-server';
+
+const verify = createAccessiTokenVerifier({
+  jwks: { url: process.env.ACCESSI_JWKS_URL! },
+  issuer: 'https://accessi.example.com',
+  audience: 'backend-a',
+});
+
+const payload = await verify(token);
+```
+
+## Introspection
+
+`POST /api/accessi/auth/introspect` richiede un service token con scope
+`accessi:introspect`.
+
+```json
+{
+  "Status": { "errorCode": "0", "errorDescription": "" },
+  "Result": {
+    "active": true,
+    "user": { "codiceUtente": 123, "email": "utente@example.com" },
+    "grants": { "abilitazioni": [], "ruoli": [], "grants": [] }
+  },
+  "Message": "Dati recuperati con successo."
+}
+```
+
+Regole:
+
+- `active: false` per token invalido, scaduto o utente disabilitato.
+- Gli errori di database o configurazione sono 500: non vanno interpretati come token scaduto.
+- I risultati attivi sono cachati per `cacheTtlMs` (default 30 secondi).
+- Fail closed: se Accessi Service non risponde, la richiesta non viene autorizzata.
+
+## Revoche
+
+Per applicare le revoche anche nel backend fratello, usa gli stessi store di
+Accessi Service:
+
+```ts
+import {
+  createRedisAccessTokenRevocationStore,
+  createRedisRefreshTokenRotationStore,
+  createRedisSessionRevocationStore,
+} from 'emilsoftware-utilities/accessi/resource-server';
+
+const revocation = {
+  store: createRedisSessionRevocationStore({ client: redis, ttlMs }),
+  accessTokenStore: createRedisAccessTokenRevocationStore({ client: redis }),
+  familyStore: createRedisRefreshTokenRotationStore({ client: redis }),
+};
+```
+
+Se il backend fratello non può dipendere da `accessi/server` (per esempio per
+non trascinare Nest), applica la revoca tramite introspection: Accessi Service
+restituisce `active: false` per un token revocato.
+
+## Errori da gestire
+
+| HTTP | Codice | Significato |
+| --- | --- | --- |
+| 401 | `AUTH_TOKEN_MISSING` | Header Bearer assente o malformato |
+| 401 | `AUTH_TOKEN_INVALID` | Firma, scadenza, issuer/audience o tipo token non validi |
+| 401 | `AUTH_USER_CODE_MISSING` | Token senza `codiceUtente` |
+| 403 | `AUTH_INSUFFICIENT_PERMISSIONS` | Policy non soddisfatta |
+| 500 | `AUTH_CONFIG_INVALID` | Configurazione resource server incompleta |
+| 500 | `AUTH_GRANTS_SOURCE_MISSING` | Policy richiede grant ma introspection non configurata |
+| 503 | `AUTH_INTROSPECTION_UNAVAILABLE` | Accessi Service non raggiungibile: fail closed |
+| 503 | `AUTH_INTROSPECTION_UNAUTHORIZED` | Service token invalido o senza scope |
+| 503 | `AUTH_JWKS_UNAVAILABLE` | JWKS non raggiungibile: fail closed |
+
+## Service token
+
+1. Abilita `serviceTokens` su Accessi Service.
+2. Crea il token dalla console o con `POST /api/accessi/service-token`.
+3. Assegna lo scope minimo: `accessi:introspect` per l'introspection.
+4. Conservalo nel secret manager del backend fratello.
+5. Ruotalo periodicamente; il segreto è mostrato una sola volta.
+
+Non usare un service token nel browser e non registrarlo nei log.
+
+## Checklist
+
+- Nessuna credenziale del database Accessi nel backend fratello.
+- `issuer` e `audience` allineati ad Accessi Service.
+- JWKS con cache e timeout, oppure `publicKey` statica.
+- Introspection con service token e cache breve se servono i grant.
+- Policy esplicita sulle rotte sensibili.
+- 401, 403 e 503 gestiti senza autorizzare per errore.
+- `trust proxy` e rate limit configurati se il backend è dietro un proxy.
+- Test con token valido, scaduto, utente disabilitato, permessi insufficienti e introspection non raggiungibile.

package/docs/quickstart-service.md

@@ -0,0 +1,214 @@
+# Quickstart: backend che possiede Accessi
+
+Questa guida è per il backend (o servizio) che possiede il database Accessi.
+Se il tuo backend deve solo verificare i token emessi da un altro servizio, usa
+il [quickstart resource server](quickstart-resource-server.md).
+
+## Prerequisiti
+
+- Node.js 18 o superiore.
+- Firebird/InterBase 2.5 o superiore raggiungibile dal servizio.
+- Un server SMTP: Accessi lo richiede per reset password, 2FA e inviti.
+- Un secret manager o variabili d'ambiente per database, `encryptionKey`, SMTP e chiavi JWT.
+
+## Installazione
+
+```bash
+npm install emilsoftware-utilities
+```
+
+## Configurazione minima
+
+Con `NODE_ENV=production` il servizio rifiuta i segreti di default locali:
+`ACCESSI_JWT_SECRET` e `ACCESSI_ENCRYPTION_KEY` devono essere presenti e diversi
+dai valori di sviluppo. Anche `mockDemoUser` deve restare `false`.
+
+```ts
+import type { AccessiServerOptions } from 'emilsoftware-utilities/accessi/server';
+
+const options: AccessiServerOptions = {
+  databaseOptions: {
+    host: process.env.ACCESSI_DB_HOST!,
+    port: Number(process.env.ACCESSI_DB_PORT ?? 3050),
+    database: process.env.ACCESSI_DB_DATABASE!,
+    user: process.env.ACCESSI_DB_USER!,
+    password: process.env.ACCESSI_DB_PASSWORD!,
+  },
+  encryptionKey: process.env.ACCESSI_ENCRYPTION_KEY!,
+  confirmationEmailUrl: process.env.ACCESSI_CONFIRMATION_EMAIL_URL!,
+  confirmationEmailReturnUrl: process.env.ACCESSI_CONFIRMATION_RETURN_EMAIL_URL!,
+  emailOptions: {
+    host: process.env.ACCESSI_EMAIL_HOST!,
+    port: Number(process.env.ACCESSI_EMAIL_PORT ?? 587),
+    secure: false,
+    requireTLS: true,
+    from: process.env.ACCESSI_EMAIL_FROM!,
+    auth: {
+      user: process.env.ACCESSI_EMAIL_USER!,
+      pass: process.env.ACCESSI_EMAIL_PASSWORD!,
+    },
+  },
+  jwtOptions: {
+    secret: process.env.ACCESSI_JWT_SECRET!,
+    expiresIn: process.env.ACCESSI_JWT_EXPIRES ?? '24h',
+    refreshExpiresIn: process.env.ACCESSI_JWT_REFRESH_EXPIRES ?? '30d',
+    issuer: process.env.ACCESSI_JWT_ISSUER ?? 'accessi',
+    audience: process.env.ACCESSI_JWT_AUDIENCE ?? 'backend-app',
+  },
+  autoUpdateDatabase: true,
+  mockDemoUser: false,
+};
+```
+
+In produzione preferisci RS256/ES256 con JWKS:
+
+```ts
+jwtOptions: {
+  algorithm: 'RS256',
+  secret: process.env.ACCESSI_JWT_SECRET!,
+  privateKey: process.env.ACCESSI_JWT_PRIVATE_KEY!,
+  publicKey: process.env.ACCESSI_JWT_PUBLIC_KEY!,
+  keyId: process.env.ACCESSI_JWT_KEY_ID!,
+  issuer: 'https://accessi.example.com',
+  audience: 'backend-app',
+}
+```
+
+La rotazione delle chiavi è descritta in [jwt-key-rotation.md](jwt-key-rotation.md).
+
+## Bootstrap su Express
+
+```ts
+import express from 'express';
+import {
+  initializeAccessiModule,
+  authorizeAccessi,
+} from 'emilsoftware-utilities/accessi/server';
+
+const app = express();
+app.use(express.json());
+
+// Attendi il bootstrap prima di aprire la porta HTTP.
+await initializeAccessiModule(app, options);
+
+app.get('/api/ordini', authorizeAccessi, (req, res) => {
+  res.json({ utente: req.user });
+});
+
+app.listen(3000);
+```
+
+`initializeAccessiModule` restituisce `{ nestApp, document }`: il documento
+OpenAPI può essere unito a quello dell'host con `mergeOpenApiDocuments` di
+`emilsoftware-utilities/accessi/openapi`.
+
+## Bootstrap su Nest
+
+```ts
+import { Module } from '@nestjs/common';
+import { AccessiModule } from 'emilsoftware-utilities/accessi/server';
+
+@Module({
+  imports: [AccessiModule.forRoot(options)],
+})
+export class AppModule {}
+```
+
+`AccessiModule` è `@Global()`: inizializzalo una sola volta per processo.
+
+## Database e primo admin
+
+Al primo avvio con `autoUpdateDatabase: true` Accessi riconcilia lo schema
+Firebird. In produzione:
+
+1. Esegui la migrazione con un solo processo:
+
+   ```bash
+   npm run db:update:accessi
+   ```
+
+2. Avvia le repliche con `autoUpdateDatabase: false` (oppure `ACCESSI_AUTO_UPDATE_DATABASE=false` nel servizio standalone).
+3. Crea il primo admin dalla console, abilitando temporaneamente `adminBootstrap`.
+   Il token di bootstrap viene stampato all'avvio, è monouso e dura fino al riavvio.
+4. Disabilita `adminBootstrap` dopo la creazione.
+
+Per diagnostica:
+
+```bash
+npm run db:check:accessi
+```
+
+## Health e readiness
+
+Se usi il servizio standalone, gli endpoint sono già presenti. In un host Nest:
+
+```ts
+import { createAccessiHealthModule } from 'emilsoftware-utilities/accessi/server';
+
+@Module({
+  imports: [
+    AccessiModule.forRoot(options),
+    createAccessiHealthModule({ accessiOptions: options, path: '/health' }),
+  ],
+})
+export class AppModule {}
+```
+
+Endpoint:
+
+- `GET /health/live`: processo vivo.
+- `GET /health/ready`: bootstrap, database, schema e store pronti.
+- `GET /health/metrics`: metriche Prometheus.
+
+## Servizio standalone
+
+Se non hai già un backend, avvia Accessi come servizio autonomo:
+
+```ts
+import { startAccessiService } from 'emilsoftware-utilities/accessi/server';
+
+await startAccessiService({ port: 3000, healthPath: '/health', metrics: true });
+```
+
+Oppure:
+
+```bash
+npm run accessi:serve
+```
+
+Dettagli, systemd e Docker in [standalone-service.md](standalone-service.md).
+
+## Multi-istanza
+
+Con più repliche configura gli store Redis:
+
+- `publicAuthRateLimit.store`
+- `serviceTokens.rateLimitStore`
+- `consoleEntry.store`
+- `sessionRevocation.store`
+- `accessTokenRevocation.store`
+- `refreshTokenRotation.store`
+
+Senza store condivisi ticket console, revoche e rate limit restano locali al
+processo. Vedi [WIKI.md](../WIKI.md#store-condivisi-e-multi-istanza).
+
+## Checklist di produzione
+
+- `mockDemoUser: false`.
+- `encryptionKey`, SMTP e chiavi JWT da un secret manager.
+- `issuer` e `audience` espliciti e diversi per ambiente.
+- `http.trustProxy` corretto per il numero di proxy.
+- CORS con origin espliciti.
+- Rate limit pubblico e service token configurati.
+- Store Redis condivisi in multi-istanza.
+- Audit con sink e retention.
+- Backup del database e migrazione collaudata.
+- `/health/ready` usato dal load balancer.
+
+## Prossimi passi
+
+- [WIKI.md](../WIKI.md#accessioptions-riferimento-completo) per tutte le opzioni.
+- [WIKI.md](../WIKI.md#login-locale-e-jwt) per login, 2FA e reset password.
+- [WIKI.md](../WIKI.md#authorizeaccessi-middleware) per policy e requisiti.
+- [operazioni](../WIKI.md#deploy-del-servizio) per deploy, Redis e sicurezza.
+- [multi-tenancy.md](multi-tenancy.md) se devi isolare più clienti.

package/docs/redis-load-testing.md

@@ -1,5 +1,9 @@
 # Test di concorrenza e carico su Redis
 
+Per sviluppatori e operations che modificano store condivisi. Indice completo in
+[README.md](README.md); store e multi-istanza in
+[WIKI.md](../WIKI.md#store-condivisi-e-multi-istanza).
+
 `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.

package/docs/security-headers.md

@@ -1,5 +1,8 @@
 # Header di sicurezza e CSP
 
+Per backend e team di sicurezza. Indice completo in [README.md](README.md);
+checklist di hardening in [WIKI.md](../WIKI.md#hardening-e-checklist-di-sicurezza).
+
 Accessi applica header di sicurezza alle proprie rotte (`/api/accessi/*`, JWKS e
 documentazione OpenAPI). La configurazione avviene in `http.securityHeaders`: