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

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Emil Software
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,373 @@
+# Emilsoftware Utilities
+
+Libreria e servizio di identità per le applicazioni EmilSoftware.
+
+## Accessi
+
+Accessi gestisce autenticazione JWT, autorizzazione per menu, utenti e ruoli,
+2FA, SSO, token macchina-a-macchina e console amministrativa su database
+Firebird/InterBase. Può girare dentro un backend esistente oppure come servizio
+autonomo, con backend fratelli che verificano i token senza accedere al database
+Accessi.
+
+### Da dove iniziare
+
+| Sei... | Parti da |
+| --- | --- |
+| Frontend | [Quickstart frontend](docs/quickstart-frontend.md) |
+| Backend che possiede Accessi | [Quickstart servizio](docs/quickstart-service.md) |
+| Backend fratello (resource server) | [Quickstart resource server](docs/quickstart-resource-server.md) |
+| Operations / sicurezza | [WIKI.md](WIKI.md), [standalone-service.md](docs/standalone-service.md) |
+| Multi-tenant | [multi-tenancy.md](docs/multi-tenancy.md), [deploy/](deploy/) |
+| Migrazione o deprecazioni | [import-migration.md](docs/import-migration.md) |
+| Agente AI | [WIKI.ai.md](WIKI.ai.md), [integration-prompt.md](integration-prompt.md) |
+
+Indice completo per ruolo in [docs/README.md](docs/README.md).
+
+### Entry point
+
+| Import | Uso |
+| --- | --- |
+| `emilsoftware-utilities/accessi/server` | Backend proprietario: modulo Nest, bootstrap Express, DB, migrazioni, console, health |
+| `emilsoftware-utilities/accessi/resource-server` | Backend fratello: verifica JWT, guard/middleware, introspection, revoche |
+| `emilsoftware-utilities/accessi/client/public` | Frontend: login, refresh, 2FA, reset password, ticket console |
+| `emilsoftware-utilities/accessi/client/admin` | Console e tool amministrativi |
+| `emilsoftware-utilities/accessi/client/service` | Solo backend: service token e introspezione |
+| `emilsoftware-utilities/accessi/contracts` | Tipi e helper browser-safe |
+| `emilsoftware-utilities/accessi/openapi` | Setup e merge OpenAPI |
+| `emilsoftware-utilities/accessi/console` | URL console e ticket |
+| `emilsoftware-utilities/accessi/ui` | Asset Web Component |
+
+Il livello pubblico è `src/accessi/`; l'implementazione del servizio è
+`src/accessi-service/`. I consumer importano solo gli entry point
+`emilsoftware-utilities/accessi/*`: la regola completa è in
+[docs/conventions.md](docs/conventions.md#layout-di-accessi).
+
+### Documentazione
+
+- **[WIKI.md](WIKI.md)** — guida completa: percorsi, bootstrap, configurazione, autenticazione, autorizzazione, frontend, dominio, console, operazioni, FAQ e glossario.
+- **[WIKI.ai.md](WIKI.ai.md)** — versione compatta da fornire a un'IA.
+- **[integration-prompt.md](integration-prompt.md)** — contesto e prompt operativi per backend, frontend e agenti.
+- **[docs/README.md](docs/README.md)** — indice completo per ruolo e per documento.
+- **[src/accessi-service/README.md](src/accessi-service/README.md)** — documentazione operativa del servizio.
+- **[SECURITY.md](SECURITY.md)** — come segnalare una vulnerabilità e versioni supportate.
+
+Rigenera WIKI.md e WIKI.ai.md con `npm run generate:accessi-wiki` (incluso in
+`npm run build`).
+
+
+## Convenzioni
+
+Naming di file e cartelle, pulizia del repository ed eccezioni sono in
+[docs/conventions.md](docs/conventions.md). La CI esegue `npm run check:naming`.
+
+## Catalog migrations SQL
+
+Per allineare menu, ruoli e cataloghi su più database, configura `catalogScripts` in `AccessiOptions`
+(cartella con script `.sql` versionati nel backend) e usa le CLI:
+
+```bash
+ACCESSI_CATALOG_FOLDER=./db/accessi-catalog npm run db:catalog:accessi
+ACCESSI_CATALOG_FOLDER=./db/accessi-catalog npm run db:catalog:accessi:check
+```
+
+Gli script sono applicati dopo la riconciliazione dello schema, una sola volta per database,
+con tracking in `ACCESSI_CATALOG_SCRIPT` (nome + checksum). Dettagli nella Wiki, sezione
+"Catalog migrations SQL".
+
+---
+
+Convenzioni per i Commit Message
+
+1. feat:
+Descrizione: Nuova feature
+Esempio: feat: aggiunta endpoint per notifiche
+Trigger: MINOR release (es. 1.3.0 -> 1.4.0)
+Su dev: 1.4.0-dev.0
+
+2. fix:
+Descrizione: Correzione di bug
+Esempio: fix: gestione errore null in login
+Trigger: PATCH release (es. 1.3.1)
+Su dev: 1.3.1-dev.0
+
+3. BREAKING CHANGE:
+Descrizione: Cambiamento che rompe la compatibilità all'indietro
+Esempio:
+feat!: rimozione supporto legacy
+BREAKING CHANGE: cambia lo schema JWT
+Trigger: MAJOR release (es. 1.0.0 -> 2.0.0)
+
+4. Altri tipi di commit
+Esempi: chore:, docs:, test:, refactor:
+Descrizione: Non triggerano una release di default, a meno che non siano configurati esplicitamente nel commit-analyzer.
+Esempio: chore: aggiorna dipendenze
+
+5. Forzare una Release
+Descrizione: Utile in caso di merge o altre operazioni.
+Comandi:
+git commit --allow-empty -m "feat: trigger test release"
+Poi:
+git push origin dev
+Oppure:
+git push origin main
+
+## Componenti Angular / Browser
+
+Componenti UI frameworkless (Web Components) pubblicati in
+`dist/angular-components/`. Non richiedono Angular, Ionic o React; supportano
+temi light/dark e i token Bootstrap 5.3.
+
+- [Catalogo componenti](src/angular-components/README.md)
+- [`aree-disponibili`](src/angular-components/aree-disponibili/README.md)
+
+## Test e qualita
+
+| Comando | Descrizione |
+| --- | --- |
+| `npm run typecheck` | Typecheck TypeScript in modalita `strict` (piu flag di igiene) |
+| `npm run lint` | Lint dependency-free (no `any`, no `@ts-ignore`, no `console.*` fuori dal logger) |
+| `npm test` | Typecheck + lint + test unitari |
+| `npm run test:unit` | Solo test unitari (`node --test`) |
+| `npm run test:coverage` | Test unitari con report e **soglie minime** di copertura |
+| `npm run test:integration` | Integration test su Firebird reale (default: porta 3055) |
+| `npm run test:integration:fb5` / `:fb3` / `:fb25` | Integration test su Firebird 5 / 3 / 2.5 |
+| `npm run test:integration:redis` | Integration test degli store Redis (opt-in, salta senza `ACCESSI_TEST_REDIS_URL`) |
+| `npm run test:accessi-console` | Test end-to-end della console (richiede un browser Chromium e la build) |
+
+### Integration test su Firebird reale
+
+Avvia i database di test (Firebird 5 sulla 3055, Firebird 3 sulla 3056, Firebird 2.5 sulla 3057) e lancia la suite:
+
+```bash
+docker compose -f docker-compose.test.yml up -d
+npm run test:integration:fb5
+npm run test:integration:fb3
+npm run test:integration:fb25
+docker compose -f docker-compose.test.yml down -v
+```
+
+Firebird 2.5 usa l'immagine `jacobalberty/firebird:v2.5.9-ss` (l'immagine ufficiale non copre la 2.5) con `Legacy_Auth` e wire crypt disabilitato: lo script `test:integration:fb25` imposta da solo plugin e wireCrypt.
+
+Il database viene creato dal test stesso (`attachOrCreate`) e lo schema costruito dal migrator
+della libreria (`AccessiDatabaseUpdater`), quindi gli integration test validano anche migrazione e
+compatibilita dello schema. Senza un Firebird raggiungibile i test vengono marcati come `skip`; con
+`ACCESSI_TEST_REQUIRE_DB=1` falliscono invece di essere saltati (usato dalla CI).
+
+Variabili: `ACCESSI_TEST_DB_HOST`, `ACCESSI_TEST_DB_PORT`, `ACCESSI_TEST_DB_DATABASE`,
+`ACCESSI_TEST_DB_USER`, `ACCESSI_TEST_DB_PASSWORD`, `ACCESSI_TEST_DB_WIRE_CRYPT`,
+`ACCESSI_TEST_DB_AUTH_PLUGIN`.
+
+I container usano le porte host **3055** e **3056** per non entrare in conflitto con un Firebird
+locale spesso in ascolto sulla 3050. Per cambiare porta/percorso, modifica i mapping in
+`docker-compose.test.yml` e passa `ACCESSI_TEST_DB_PORT` / `ACCESSI_TEST_DB_DATABASE`.
+
+La CI (`.github/workflows/ci.yml`) esegue typecheck, test con coverage e build, piu un job di
+integration test in matrice su Firebird 5 e 3. Il workflow di release (`publish.yml`) esegue
+typecheck e test prima di build e pubblicazione.
+
+### Packaging
+
+Il pacchetto e pubblicato come **CommonJS** (build `tsc` in `dist/`) con export map esplicita per
+ogni entry point; gli `import` ESM funzionano tramite interop Node. La scelta CJS e intenzionale:
+il pacchetto gira in host Nest/Express e non esiste un bundle ESM separato da mantenere.
+
+- `sideEffects` elenca solo i moduli con effetti collaterali (root barrel, `firebirdCompat`,
+  bundle console), tutto il resto resta tree-shakable.
+- `typesVersions` copre i TypeScript precedenti al campo `exports`.
+- `npm run test:pack` crea il tarball con `npm pack`, lo installa in un progetto temporaneo e
+  verifica ogni subpath (`accessi/server`, `resource-server/*`, `client/*`, `contracts`, `openapi`,
+  `console`, `ui`), l'assenza di dipendenze server-side in `contracts` e l'interop ESM. La CI lo
+  esegue in un job dedicato dopo la build.
+
+La decisione di mantenere un pacchetto singolo (con entry point per scope) e il piano per un
+eventuale split futuro sono documentati nell'[ADR 0001](docs/adr/0001-split-package.md).
+
+### OpenAPI semantic diff
+
+`docs/accessi-openapi-fingerprint.json` blocca la rimozione di operation e schema, ma non i cambi
+di tipo o le nuove restrizioni. Il build esegue anche un diff semantico contro
+`docs/accessi-openapi-baseline.json`:
+
+```bash
+npm run check:accessi-openapi-diff     # verifica (eseguita dal build e dalla CI)
+npm run accessi:update-openapi-baseline  # accetta il contratto corrente come nuova baseline
+```
+
+Sono **breaking**: operation/parametri/risposte rimosse, cambi di tipo o formato, `required` aggiunto
+in input o rimosso in output, valori enum rimossi, `security` cambiata e vincoli piu stretti
+sull'input. Aggiungere campi opzionali (input o output) non e breaking.
+
+Un breaking change intenzionale va dichiarato in
+`docs/accessi-openapi-breaking-allowlist.json` con `id`, `reason` (obbligatoria) e, se esiste, `issue`:
+
+```json
+[{ "id": "operation:legacyLogin:removed", "reason": "Rimosso nella major 3.0", "issue": "#123" }]
+```
+
+La CI fallisce se un breaking change non e coperto, se un'eccezione non ha `reason` o se l'eccezione
+e diventata obsoleta (il cambio non esiste piu).
+
+### Integration test su Redis reale
+
+Gli store condivisi (rate limit, ticket console, revoca sessioni, revoca `jti`, rotazione refresh
+token) hanno adapter Redis che nei test unitari girano su fake in memoria. La suite di integrazione
+li verifica contro un Redis reale, inclusi i `consume` atomici in concorrenza e gli `healthCheck()`.
+
+E' **opt-in**: senza la variabile `ACCESSI_TEST_REDIS_URL` i test vengono marcati come `skip`.
+
+```bash
+docker run --rm -d --name accessi-test-redis -p 6380:6379 redis:7-alpine
+npm run test:integration:redis
+docker stop accessi-test-redis
+```
+
+Su PowerShell:
+
+```powershell
+$env:ACCESSI_TEST_REDIS_URL = 'redis://127.0.0.1:6380'
+npm run test:integration:redis
+```
+
+Variabili: `ACCESSI_TEST_REDIS_URL` (formato `redis://[:password@]host:port[/db]`) e
+`ACCESSI_TEST_REQUIRE_REDIS=1` per fallire invece di saltare quando Redis non e raggiungibile
+(usato dalla CI). I test usano chiavi con prefisso per processo e cancellano solo quelle, quindi
+possono girare anche su un Redis condiviso. `docker-compose.test.yml` resta dedicato solo a
+Firebird: la CI avvia Redis come service del job `Redis stores`.
+
+## Firebird: drop-in di `es-node-firebird`
+
+La libreria **ri-esporta l'intera API di `node-firebird`** (`export * from "node-firebird"` piu il
+namespace `Firebird`), quindi sostituisce il fork deprecato `es-node-firebird` senza modifiche al
+codice applicativo: basta cambiare l'import.
+
+```ts
+// prima
+import * as Firebird from 'es-node-firebird';
+// dopo
+import { Firebird } from 'emilsoftware-utilities';
+// oppure, con import nominati
+import { attach, create, pool, ISOLATION_READ_COMMITTED } from 'emilsoftware-utilities';
+```
+
+I comportamenti storici del fork sono riprodotti da un **layer di compatibilita esterno**
+(`src/firebirdCompat.ts`), senza toccare il driver ufficiale:
+
+- **Date come UTC** (`utcDates`, default `true`): `DATE`/`TIME`/`TIMESTAMP` vengono reinterpretati
+  come UTC, come faceva il fork con `setUTCMilliseconds`. Con `utcDates: false` restano in ora locale.
+- **Trim dei campi testo** (`trimStringResults`, default `true`): le stringhe vengono trimmate come
+  il fork (`.trim()`). Con `trimStringResults: false` restano intatte.
+- **Compatibilita wire/auth** (`wireCrypt`, `pluginName`): normalizzazione dei valori e diagnostica
+  arricchita sugli errori di connessione.
+
+Le opzioni si passano in `databaseOptions` (vedi `FirebirdOptions` in `src/firebirdCompat.ts`).
+
+## Service token (macchina-a-macchina)
+
+Credenziali di servizio per chiamate tecniche, **non legate a un utente** e senza login giornaliero.
+Sostituiscono l'uso di un `secret` nel body: si inviano con `Authorization: Bearer <token>`.
+
+- Formato: `st_<id>.<segreto>`. Il segreto e mostrato **una sola volta** alla creazione/rotazione.
+- Storage: tabella `ACCESSI_SERVICE_TOKEN` (schema Accessi, migrazione automatica `1.7.0`). Il segreto e salvato solo come hash SHA-256 e confrontato a tempo costante.
+- Metadati e audit: descrizione, scope, creazione/scadenza, ultimo utilizzo con **IP** (`lastUsedIp`), revoca con **autore** (`revokedBy`).
+- Rate limit anti-abuso per IP sulla verifica (HTTP 429).
+- API amministrative (solo superutente): `POST /api/accessi/service-token`, `GET /api/accessi/service-token` (`includeRevoked=true`), `DELETE /api/accessi/service-token/:tokenId`, `POST /api/accessi/service-token/:tokenId/rotate`.
+- Console: sezione **Token di servizio** (crea, ruota, revoca; copia il token una sola volta).
+- Utilizzo lato consumer: guard `ServiceTokenGuard` con `@RequireServiceTokenScopes('ia')`; il token verificato e disponibile con `getAccessiServiceToken(req)`.
+- Opzione: `serviceTokens: { enabled?: boolean; defaultTtlDays?: number }` in `AccessiOptions`.
+
+```ts
+import { Module } from '@nestjs/common';
+import { ServiceTokenGuard, RequireServiceTokenScopes } from 'emilsoftware-utilities';
+
+@UseGuards(ServiceTokenGuard)
+@RequireServiceTokenScopes('ia')
+@Controller('ia')
+export class IaController {}
+```
+
+## Login as (impersonazione temporanea)
+
+Superutenti e admin possono generare un accesso temporaneo a un utente per entrare in un'altra
+applicazione senza conoscerne la password. Dalla console Accessi il pulsante **Login as** nella
+lista utenti apre un pannello in cui inserire l'URL dell'applicazione e generare il link.
+
+- Endpoint: `POST /api/accessi/user/login-as/:codiceUtente` con body `{ "url": "https://app.example.com/..." }`.
+- Risposta: `Result.loginUrl` con `?loginAsToken=<jwt>`, `token`, `expiresInSeconds` e `expiresAt`.
+- Il token ha la **stessa durata della sessione Accessi standard** (`jwtOptions.expiresIn`) ed e' un normale access token Accessi con `amr: ["login_as"]`, `loginAs: true` e `act` valorizzato con l'amministratore che lo ha generato.
+- E' accettato da `get-user-by-token` e da `authorizeAccessi`, anche se l'utente target ha la 2FA attiva: l'attore ha gia' completato l'autenticazione amministrativa.
+- Gerarchia **ADMIN > SUPER**: un admin puo' impersonare chiunque, un superutente non puo' impersonare un admin.
+- L'URL viene composto con `buildLoginAsUrl` (esportata dalla libreria), che accetta solo URL assoluti `http`/`https` e conserva query e fragment esistenti.
+- Accessi non consuma il token al posto dell'applicazione: da quel momento e' l'app di destinazione a leggere `loginAsToken`, validarlo e decidere cosa consentire. Il token e' una credenziale: non condividerlo e non registrarlo nei log.
+
+## Hardening e opzioni
+
+- I log delle query **non includono i valori dei parametri** (segreti, credenziali, PII). Per riattivare esplicitamente i valori: `logQueryParameters: true` nelle `databaseOptions`.
+- Pool di connessioni **attivo di default** (`poolSize` default `5`); `poolSize: 0` disabilita e torna a una connessione per query. Gli script di breve durata devono chiamare `await Orm.closePools()` prima di uscire.
+- I JWT sono verificati con algoritmo fissato a `HS256` ed e obbligatoria una scadenza (`expiresIn`) valida. `TokenResult.expiresIn` e sempre riportato in secondi, anche con configurazioni come `24h`.
+- **Chiavi JWT separate per scopo** (`access`, `reset`, `2fa`), derivate dal segreto configurato; il claim `typ: 'access'` e **obbligatorio** per gli access token.
+- La backdoor mock `admin`/`demo` non e mai attiva quando `NODE_ENV=production`.
+- Gli allegati sono **protetti di default**: senza `allegatiOptions.authorize` le richieste rispondono 403. Per la migrazione da versioni precedenti impostare `requireAuthorization: false` (sconsigliato in produzione).
+- Upload allegati: limite di 1 file / 90 MB applicato da Multer e validazione dei magic byte oltre al mimetype dichiarato.
+- **IP reali dietro proxy**: `http.trustProxy` deve corrispondere al numero di proxy davanti al servizio (default `false`). Rate limit e audit usano `req.ip`: un valore errato rende i bucket inefficaci o aggirabili via `X-Forwarded-For`. Guida per Nginx/Traefik/Cloudflare: [docs/proxy-ip.md](docs/proxy-ip.md).
+
+## Integrazione
+
+| Scenario | API |
+| --- | --- |
+| Backend Express esistente | `await initializeAccessiModule(app, accessiOptions)` monta le rotte `/api/accessi` su un host Nest isolato |
+| Applicazione NestJS | importa `AccessiModule.forRoot(accessiOptions)` (e/o `AllegatiModule.forRoot(allegatiOptions)`) |
+| Accessi + Allegati insieme | `EmilsoftwareModule.forRoot({ accessiOptions, allegatiOptions })` |
+| Health/readiness in host Nest | `createAccessiHealthModule({ accessiOptions })` espone `/health/live` e `/health/ready` con lo stesso contratto del servizio standalone |
+| Client multi-istanza / multi-tenant | `createAccessiClient({ baseUrl, getToken })` isola base URL e token per istanza (concorrenza sicura); `configureAccessiClient` resta il default globale |
+| Client per scope | `accessi/client/public` (frontend), `accessi/client/admin` (tool admin), `accessi/client/service` (backend fratelli): stesse tipi del client completo, nessuna operazione fuori scope |
+
+Tutta la configurazione e riservata al backend: segreti JWT/SMTP/DB non devono mai raggiungere il browser.
+
+## Riferimento `AccessiOptions`
+
+| Campo | Tipo | Note |
+| --- | --- | --- |
+| `databaseOptions` | `Options` | Connessione Firebird (`DatabaseUtilities.createOption`). Supporta `logQueryParameters`, `poolSize`, `wireCrypt`, `pluginName`, `utcDates`, `trimStringResults`. |
+| `confirmationEmailUrl` / `confirmationEmailReturnUrl` | `string` | URL per le email di reset. |
+| `customResetPage` / `confirmationEmailPrefix` | `string?` | Pagina di reset personalizzata. |
+| `encryptionKey` | `string` | Solo compatibilita/migrazione password legacy cifrate. |
+| `mockDemoUser` | `boolean` | Utenti fittizi `admin`/`demo`; **mai** attivi in produzione. |
+| `passwordExpiration` / `passwordExpirationDays` | `boolean?` / `number?` | Scadenza password (default 90 giorni). |
+| `legacyPasswordMigrationOnStartup` | `boolean?` | Migrazione password legacy al bootstrap (default `true`). |
+| `autoUpdateDatabase` | `boolean?` | Riconcilia lo schema al bootstrap (default `true`); con `false` verifica in sola lettura. |
+| `jwtOptions` | `{ secret: string; expiresIn: string }` | HS256 con scadenza obbligatoria. |
+| `emailOptions` | `EmailOptions` | SMTP per reset e codici 2FA. |
+| `publicAuthRateLimit` | `PublicAuthRateLimitOptions?` | Limiti degli endpoint pubblici (default attivi). |
+| `publicRegistration` | `{ enabled?: boolean }?` | Registrazione pubblica opt-in. |
+| `federatedAuthentication` | `{ enabled?; allowSelfRegistration? }?` | SSO provider-agnostico. |
+| `extensionFieldsOptions` | `ExtensionFieldsOptions[]?` | Campi applicativi estesi. |
+| `serviceTokens` | `{ enabled?: boolean; defaultTtlDays?: number }?` | Token macchina-a-macchina (default abilitati). |
+
+## Riferimento `AllegatiOptions`
+
+| Campo | Tipo | Note |
+| --- | --- | --- |
+| `databaseOptions` | `Options` | Connessione Firebird. |
+| `authorize` | `(req) => boolean \| Promise<boolean>?` | Controllo di autorizzazione applicato a ogni richiesta; `false` → 403. |
+| `requireAuthorization` | `boolean?` | **Default `true`**: senza `authorize` le richieste sono rifiutate con 403 (secure by default). `false` ripristina il comportamento storico (endpoint aperti) durante la migrazione. |
+
+## Contratto risposte ed errori
+
+- Successo generico: `RestUtilities.sendOKMessage` → `{ severity, status, statusCode, message }`.
+- Payload: `RestUtilities.sendBaseResponse` → `{ Status: { errorCode, errorDescription }, Result, Message }`.
+- Errore: `{ severity: 'error', status, statusCode, code, message, error, details? }`, con `code` stabile (es. `ACCESSI_UNAUTHORIZED`, `ACCESSI_INVALID_CREDENTIALS`, `PASSWORD_EXPIRED`, `ACCESSI_DATABASE_SCHEMA_OUTDATED`, `ACCESSI_SERVICE_TOKEN_RATE_LIMITED`). Lo status deriva dalla `HttpException` (validazione → 400); errori di schema DB → 503. SQL, stack e dati sensibili non vengono mai esposti.
+
+## Migrazioni e schema
+
+- Lo schema Accessi e versionato in `accessiSchema.ts` (`ACCESSI_SCHEMA_VERSION`) e riconciliato in modo **idempotente e ripartibile** da `AccessiDatabaseUpdater` (nessun DDL distruttivo, FK/indici/trigger verificati, sequence avanzate solo in avanti).
+- La versione viene aggiornata **solo dopo** `assertCompatible`; su errore la migrazione si puo rieseguire.
+- Firebird non rende utilizzabili gli oggetti creati nella stessa transazione, quindi il DDL non e racchiuso in un'unica transazione: la robustezza e data da idempotenza + verifica finale.
+- Con `autoUpdateDatabase: false` la libreria verifica lo schema in sola lettura e blocca l'avvio se incompatibile (`AccessiDatabaseUpdater.inspectSchema`).
+
+## Osservabilita
+
+- `Logger` strutturato (console colorata + file JSON giornaliero), condiviso per directory.
+- Livello minimo configurabile per istanza (`new Logger(tag, { level: 'info' })`) o globalmente con la variabile `LOG_LEVEL` (default `database` = tutto).
+- Redazione automatica dei campi sensibili (`password`, `token`, `secret`, ...) e serializzazione degli `Error` con stack.
+- I log delle query non contengono i valori dei parametri (salvo `logQueryParameters: true`).

package/SECURITY.md

@@ -0,0 +1,66 @@
+# Security policy
+
+Accessi gestisce identità, password, token e chiavi di firma: segnalazioni di
+sicurezza sono benvenute e vanno trattate in modo riservato.
+
+## Versioni supportate
+
+| Versione | Supporto |
+| --- | --- |
+| Ultima `2.x` stabile | Sì, con priorità |
+| Ultima `2.0.0-dev.N` su `@dev` | Sì, per problemi introdotti di recente |
+| Versioni precedenti o fork | Best effort |
+
+Le correzioni di sicurezza vengono pubblicate prima su `@dev` e poi nella
+prossima versione stabile.
+
+## Come segnalare una vulnerabilità
+
+Non aprire una issue pubblica per una vulnerabilità non ancora corretta.
+
+1. Usa la funzione **Report a vulnerability** nella scheda Security del
+   repository GitHub (private vulnerability reporting).
+2. Includi:
+   - versione del package e commit;
+   - topologia (servizio standalone, embedded, resource server, multi-tenant);
+   - configurazione rilevante **senza segreti**;
+   - passi di riproduzione, impatto e prerequisiti;
+   - eventuale proof of concept minimo.
+3. Non allegare database reali, token, password, chiavi private o file `.env`.
+   Usa valori fittizi.
+4. Indica se il problema è già pubblico o sfruttato.
+
+Se il canale privato non è disponibile, contatta i maintainer indicati in
+`package.json` senza divulgare dettagli sfruttabili.
+
+## Cosa aspettarsi
+
+- Conferma di ricezione appena possibile.
+- Valutazione di impatto e gravità.
+- Aggiornamenti periodici fino alla correzione.
+- Credito nella release, se desiderato.
+
+## Ambito
+
+Sono particolarmente rilevanti:
+
+- bypass di autenticazione o autorizzazione;
+- furto, riuso o revoca incompleta di token e refresh token;
+- esposizione di segreti, token o dati tra tenant;
+- CSRF, XSS o bypass di rate limit;
+- path traversal o esposizione della console;
+- injection SQL o comandi negli script di migrazione;
+- errori di configurazione che indeboliscono la sicurezza in produzione.
+
+Non sono vulnerabilità del progetto:
+
+- configurazioni esplicitamente insicure documentate come solo per sviluppo;
+- servizi di terze parti non aggiornati dal deploy;
+- mancanza di hardening del sistema operativo o del reverse proxy non
+  documentata come responsabilità di Accessi.
+
+## Segnalazioni non sensibili
+
+Per bug funzionali, domande o miglioramenti usa le issue pubbliche e allega
+solo log redatti. La guida alla risoluzione dei problemi è in
+[`WIKI.md`](WIKI.md#problemi-comuni-e-come-risolverli).

package/dist/EmilsoftwareModule.d.ts

@@ -1,6 +1,6 @@
 import { DynamicModule } from "@nestjs/common";
 import type { LoggerService } from "@nestjs/common";
-import { AccessiOptions } from "./accessi-module/AccessiModule";
+import { AccessiOptions } from "./accessi-service/AccessiModule";
 import { AllegatiOptions } from "./allegati-module/AllegatiModule";
 import type { OpenApiSetupOptions } from "./openapi/OpenApiConfig";
 /**

package/dist/EmilsoftwareModule.js

@@ -9,7 +9,7 @@ var EmilsoftwareModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmilsoftwareModule = void 0;
 const common_1 = require("@nestjs/common");
-const AccessiModule_1 = require("./accessi-module/AccessiModule");
+const AccessiModule_1 = require("./accessi-service/AccessiModule");
 const AllegatiModule_1 = require("./allegati-module/AllegatiModule");
 const Logger_1 = require("./Logger");
 /**

package/dist/EmilsoftwareModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"EmilsoftwareModule.js","sourceRoot":"","sources":["../src/EmilsoftwareModule.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AAEvD,kEAA+E;AAC/E,qEAAmF;AACnF,qCAAkC;AAuBlC;;;GAGG;AAEI,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAC3B,MAAM,CAAC,OAAO,CAAC,OAA4B;QAEvC,MAAM,MAAM,GAAW,IAAI,eAAM,CAAC,oBAAkB,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,IAAI,OAAO,GAAG,EAAE,CAAC;QAEjB,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;QAC5F,CAAC;QAGD,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;YACjE,OAAO,CAAC,IAAI,CAAC,6BAAa,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;YAC5D,OAAO,CAAC,IAAI,CAAC,6BAAa,CAAC,CAAC;QAChC,CAAC;aACI,CAAC;YACF,MAAM,CAAC,OAAO,CAAC,0EAA0E,CAAC,CAAC;QAC/F,CAAC;QAED,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;YAClE,OAAO,CAAC,IAAI,CAAC,+BAAc,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;YAC9D,OAAO,CAAC,IAAI,CAAC,+BAAc,CAAC,CAAC;QACjC,CAAC;aACI,CAAC;YACF,MAAM,CAAC,OAAO,CAAC,4EAA4E,CAAC,CAAC;QACjG,CAAC;QAED,OAAO;YACH,MAAM,EAAE,oBAAkB;YAC1B,OAAO;YACP,OAAO;SACV,CAAC;IACN,CAAC;CACJ,CAAA;AApCY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,kBAAkB,CAoC9B","sourcesContent":["import { DynamicModule, Module } from \"@nestjs/common\";\nimport type { LoggerService } from \"@nestjs/common\";\nimport { AccessiModule, AccessiOptions } from \"./accessi-module/AccessiModule\";\nimport { AllegatiModule, AllegatiOptions } from \"./allegati-module/AllegatiModule\";\nimport { Logger } from \"./Logger\";\nimport type { OpenApiSetupOptions } from \"./openapi/OpenApiConfig\";\n\n/**\n * Configuration options for the unified module that combines Accessi and Allegati functionality\n */\nexport interface EmilsoftwareOptions {\n    accessiOptions: AccessiOptions;\n    allegatiOptions: AllegatiOptions;\n    /**\n     * Documentazione OpenAPI del modulo unificato. Default: `accessi/openapi`\n     * (UI) e `accessi/openapi.json` (spec).\n     *\n     * Precedenza: questo campo vince su `accessiOptions.openapi`, che a sua\n     * volta vince sui default storici.\n     */\n    openapi?: OpenApiSetupOptions;\n    /** Logger Nest usato dal sotto-app unificato. Se assente Nest usa il proprio logger. */\n    logger?: LoggerService;\n    /** Buffer dei log di bootstrap del sotto-app. Default `true` (comportamento storico). */\n    bufferLogs?: boolean;\n}\n\n/**\n * Unified module that combines user access management (Accessi) and file attachment management (Allegati)\n * into a single NestJS module with shared OpenAPI documentation\n */\n@Module({})\nexport class EmilsoftwareModule {\n    static forRoot(options: EmilsoftwareOptions): DynamicModule {\n\n        const logger: Logger = new Logger(EmilsoftwareModule.name);\n        let imports = [];\n        let exports = [];\n\n        if (!options) {\n            throw new Error(\"EmilsoftwareModule requires valid accessiOptions and allegatiOptions\");\n        }\n\n\n        if (options.accessiOptions) {\n            logger.info(\"Initializing AccessiModule with provided options.\");\n            imports.push(AccessiModule.forRoot(options.accessiOptions));\n            exports.push(AccessiModule);\n        }\n        else {\n            logger.warning(\"Accessi options are not provided. AccessiModule will not be initialized.\");\n        }\n\n        if (options.allegatiOptions) {\n            logger.info(\"Initializing AllegatiModule with provided options.\");\n            imports.push(AllegatiModule.forRoot(options.allegatiOptions));\n            exports.push(AllegatiModule);\n        }\n        else {\n            logger.warning(\"Allegati options are not provided. AllegatiModule will not be initialized.\");\n        }\n\n        return {\n            module: EmilsoftwareModule,\n            imports,\n            exports\n        };\n    }\n} "]}
+{"version":3,"file":"EmilsoftwareModule.js","sourceRoot":"","sources":["../src/EmilsoftwareModule.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AAEvD,mEAAgF;AAChF,qEAAmF;AACnF,qCAAkC;AAuBlC;;;GAGG;AAEI,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAC3B,MAAM,CAAC,OAAO,CAAC,OAA4B;QAEvC,MAAM,MAAM,GAAW,IAAI,eAAM,CAAC,oBAAkB,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,IAAI,OAAO,GAAG,EAAE,CAAC;QAEjB,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;QAC5F,CAAC;QAGD,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;YACjE,OAAO,CAAC,IAAI,CAAC,6BAAa,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;YAC5D,OAAO,CAAC,IAAI,CAAC,6BAAa,CAAC,CAAC;QAChC,CAAC;aACI,CAAC;YACF,MAAM,CAAC,OAAO,CAAC,0EAA0E,CAAC,CAAC;QAC/F,CAAC;QAED,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;YAClE,OAAO,CAAC,IAAI,CAAC,+BAAc,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;YAC9D,OAAO,CAAC,IAAI,CAAC,+BAAc,CAAC,CAAC;QACjC,CAAC;aACI,CAAC;YACF,MAAM,CAAC,OAAO,CAAC,4EAA4E,CAAC,CAAC;QACjG,CAAC;QAED,OAAO;YACH,MAAM,EAAE,oBAAkB;YAC1B,OAAO;YACP,OAAO;SACV,CAAC;IACN,CAAC;CACJ,CAAA;AApCY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,kBAAkB,CAoC9B","sourcesContent":["import { DynamicModule, Module } from \"@nestjs/common\";\nimport type { LoggerService } from \"@nestjs/common\";\nimport { AccessiModule, AccessiOptions } from \"./accessi-service/AccessiModule\";\nimport { AllegatiModule, AllegatiOptions } from \"./allegati-module/AllegatiModule\";\nimport { Logger } from \"./Logger\";\nimport type { OpenApiSetupOptions } from \"./openapi/OpenApiConfig\";\n\n/**\n * Configuration options for the unified module that combines Accessi and Allegati functionality\n */\nexport interface EmilsoftwareOptions {\n    accessiOptions: AccessiOptions;\n    allegatiOptions: AllegatiOptions;\n    /**\n     * Documentazione OpenAPI del modulo unificato. Default: `accessi/openapi`\n     * (UI) e `accessi/openapi.json` (spec).\n     *\n     * Precedenza: questo campo vince su `accessiOptions.openapi`, che a sua\n     * volta vince sui default storici.\n     */\n    openapi?: OpenApiSetupOptions;\n    /** Logger Nest usato dal sotto-app unificato. Se assente Nest usa il proprio logger. */\n    logger?: LoggerService;\n    /** Buffer dei log di bootstrap del sotto-app. Default `true` (comportamento storico). */\n    bufferLogs?: boolean;\n}\n\n/**\n * Unified module that combines user access management (Accessi) and file attachment management (Allegati)\n * into a single NestJS module with shared OpenAPI documentation\n */\n@Module({})\nexport class EmilsoftwareModule {\n    static forRoot(options: EmilsoftwareOptions): DynamicModule {\n\n        const logger: Logger = new Logger(EmilsoftwareModule.name);\n        let imports = [];\n        let exports = [];\n\n        if (!options) {\n            throw new Error(\"EmilsoftwareModule requires valid accessiOptions and allegatiOptions\");\n        }\n\n\n        if (options.accessiOptions) {\n            logger.info(\"Initializing AccessiModule with provided options.\");\n            imports.push(AccessiModule.forRoot(options.accessiOptions));\n            exports.push(AccessiModule);\n        }\n        else {\n            logger.warning(\"Accessi options are not provided. AccessiModule will not be initialized.\");\n        }\n\n        if (options.allegatiOptions) {\n            logger.info(\"Initializing AllegatiModule with provided options.\");\n            imports.push(AllegatiModule.forRoot(options.allegatiOptions));\n            exports.push(AllegatiModule);\n        }\n        else {\n            logger.warning(\"Allegati options are not provided. AllegatiModule will not be initialized.\");\n        }\n\n        return {\n            module: EmilsoftwareModule,\n            imports,\n            exports\n        };\n    }\n} "]}

package/dist/Orm.js

@@ -46,7 +46,7 @@ exports.Orm = void 0;
 const Firebird = __importStar(require("node-firebird"));
 const Logger_1 = require("./Logger");
 const Utilities_1 = require("./Utilities");
-const firebird_compat_1 = require("./firebird-compat");
+const firebirdCompat_1 = require("./firebirdCompat");
 class Orm {
     static quote(value) {
         return "\"" + value + "\"";
@@ -72,7 +72,7 @@ class Orm {
     }
     static buildPoolKey(options, size) {
         var _a, _b, _c, _d, _e, _f;
-        const normalized = (0, firebird_compat_1.normalizeFirebirdOptions)(options);
+        const normalized = (0, firebirdCompat_1.normalizeFirebirdOptions)(options);
         return [
             size,
             (_a = normalized.host) !== null && _a !== void 0 ? _a : "",
@@ -102,11 +102,11 @@ class Orm {
         });
     }
     static getPool(options, size) {
-        const normalized = (0, firebird_compat_1.normalizeFirebirdOptions)(options);
+        const normalized = (0, firebirdCompat_1.normalizeFirebirdOptions)(options);
         const key = this.buildPoolKey(normalized, size);
         let pool = this.pools.get(key);
         if (!pool) {
-            this.logger.info(`Firebird pool created (max=${size}) using ${(0, firebird_compat_1.describeFirebirdCompatibilityOptions)(normalized)}`);
+            this.logger.info(`Firebird pool created (max=${size}) using ${(0, firebirdCompat_1.describeFirebirdCompatibilityOptions)(normalized)}`);
             pool = Firebird.pool(size, normalized);
             pool.on("error", (error) => {
                 this.logger.error(`Firebird pool error: ${error.message}`);
@@ -149,7 +149,7 @@ class Orm {
     }
     static attachWithTimeout(options) {
         return new Promise((resolve, reject) => {
-            const normalizedOptions = (0, firebird_compat_1.normalizeFirebirdOptions)(options);
+            const normalizedOptions = (0, firebirdCompat_1.normalizeFirebirdOptions)(options);
             const timeoutMs = this.getTimeoutMs(normalizedOptions);
             const poolSize = this.getPoolSize(options);
             let settled = false;
@@ -158,7 +158,7 @@ class Orm {
                     return;
                 }
                 settled = true;
-                reject((0, firebird_compat_1.enhanceFirebirdError)(this.createTimeoutError("attach", timeoutMs, normalizedOptions), normalizedOptions, { stage: "attach" }));
+                reject((0, firebirdCompat_1.enhanceFirebirdError)(this.createTimeoutError("attach", timeoutMs, normalizedOptions), normalizedOptions, { stage: "attach" }));
             }, timeoutMs);
             const handle = (err, db) => __awaiter(this, void 0, void 0, function* () {
                 if (settled) {
@@ -168,7 +168,7 @@ class Orm {
                 settled = true;
                 clearTimeout(timeoutId);
                 if (err) {
-                    return reject((0, firebird_compat_1.enhanceFirebirdError)(err, normalizedOptions, { stage: "attach" }));
+                    return reject((0, firebirdCompat_1.enhanceFirebirdError)(err, normalizedOptions, { stage: "attach" }));
                 }
                 return resolve(db);
             });
@@ -177,7 +177,7 @@ class Orm {
                     this.getPool(options, poolSize).get(handle);
                     return;
                 }
-                this.logger.info(`Firebird attach using ${(0, firebird_compat_1.describeFirebirdCompatibilityOptions)(normalizedOptions)}`);
+                this.logger.info(`Firebird attach using ${(0, firebirdCompat_1.describeFirebirdCompatibilityOptions)(normalizedOptions)}`);
                 Firebird.attach(normalizedOptions, handle);
             }
             catch (error) {
@@ -185,7 +185,7 @@ class Orm {
                 if (!settled) {
                     settled = true;
                     clearTimeout(timeoutId);
-                    reject((0, firebird_compat_1.enhanceFirebirdError)(error, normalizedOptions, { stage: "attach" }));
+                    reject((0, firebirdCompat_1.enhanceFirebirdError)(error, normalizedOptions, { stage: "attach" }));
                 }
             }
         });
@@ -210,7 +210,7 @@ class Orm {
     static query(options_1, query_1) {
         return __awaiter(this, arguments, void 0, function* (options, query, parameters = [], logQuery = true) {
             try {
-                const normalizedOptions = (0, firebird_compat_1.normalizeFirebirdOptions)(options);
+                const normalizedOptions = (0, firebirdCompat_1.normalizeFirebirdOptions)(options);
                 const db = yield this.attachWithTimeout(options);
                 return yield new Promise((resolve, reject) => {
                     const timeoutMs = this.getTimeoutMs(normalizedOptions);
@@ -221,7 +221,7 @@ class Orm {
                         }
                         settled = true;
                         yield this.detachQuietly(db);
-                        reject((0, firebird_compat_1.enhanceFirebirdError)(this.createTimeoutError("query", timeoutMs, normalizedOptions, query), normalizedOptions, { stage: "query", sql: query }));
+                        reject((0, firebirdCompat_1.enhanceFirebirdError)(this.createTimeoutError("query", timeoutMs, normalizedOptions, query), normalizedOptions, { stage: "query", sql: query }));
                     }), timeoutMs);
                     if (logQuery) {
                         this.logger.info(this.formatQueryForLog(query, parameters, this.shouldLogQueryParameters(options)));
@@ -235,14 +235,14 @@ class Orm {
                         clearTimeout(timeoutId);
                         yield this.detachQuietly(db);
                         if (error) {
-                            return reject((0, firebird_compat_1.enhanceFirebirdError)(error, normalizedOptions, { stage: "query", sql: query }));
+                            return reject((0, firebirdCompat_1.enhanceFirebirdError)(error, normalizedOptions, { stage: "query", sql: query }));
                         }
-                        return resolve((0, firebird_compat_1.normalizeFirebirdResult)(result, this.shouldTrimStringResults(normalizedOptions), this.shouldConvertDatesToUtc(normalizedOptions)));
+                        return resolve((0, firebirdCompat_1.normalizeFirebirdResult)(result, this.shouldTrimStringResults(normalizedOptions), this.shouldConvertDatesToUtc(normalizedOptions)));
                     }));
                 });
             }
             catch (error) {
-                const normalizedError = (0, firebird_compat_1.enhanceFirebirdError)(error, options, { stage: "query", sql: query });
+                const normalizedError = (0, firebirdCompat_1.enhanceFirebirdError)(error, options, { stage: "query", sql: query });
                 this.logger.error(normalizedError);
                 throw normalizedError;
             }
@@ -251,7 +251,7 @@ class Orm {
     static execute(options_1, query_1) {
         return __awaiter(this, arguments, void 0, function* (options, query, parameters = [], logQuery = true) {
             try {
-                const normalizedOptions = (0, firebird_compat_1.normalizeFirebirdOptions)(options);
+                const normalizedOptions = (0, firebirdCompat_1.normalizeFirebirdOptions)(options);
                 const db = yield this.attachWithTimeout(options);
                 return yield new Promise((resolve, reject) => {
                     const timeoutMs = this.getTimeoutMs(normalizedOptions);
@@ -262,7 +262,7 @@ class Orm {
                         }
                         settled = true;
                         yield this.detachQuietly(db);
-                        reject((0, firebird_compat_1.enhanceFirebirdError)(this.createTimeoutError("execute", timeoutMs, normalizedOptions, query), normalizedOptions, { stage: "execute", sql: query }));
+                        reject((0, firebirdCompat_1.enhanceFirebirdError)(this.createTimeoutError("execute", timeoutMs, normalizedOptions, query), normalizedOptions, { stage: "execute", sql: query }));
                     }), timeoutMs);
                     if (logQuery) {
                         this.logger.info(this.formatQueryForLog(query, parameters, this.shouldLogQueryParameters(options)));
@@ -276,14 +276,14 @@ class Orm {
                         clearTimeout(timeoutId);
                         yield this.detachQuietly(db);
                         if (error) {
-                            return reject((0, firebird_compat_1.enhanceFirebirdError)(error, normalizedOptions, { stage: "execute", sql: query }));
+                            return reject((0, firebirdCompat_1.enhanceFirebirdError)(error, normalizedOptions, { stage: "execute", sql: query }));
                         }
-                        return resolve((0, firebird_compat_1.normalizeFirebirdResult)(result, this.shouldTrimStringResults(normalizedOptions), this.shouldConvertDatesToUtc(normalizedOptions)));
+                        return resolve((0, firebirdCompat_1.normalizeFirebirdResult)(result, this.shouldTrimStringResults(normalizedOptions), this.shouldConvertDatesToUtc(normalizedOptions)));
                     }));
                 });
             }
             catch (error) {
-                const normalizedError = (0, firebird_compat_1.enhanceFirebirdError)(error, options, { stage: "execute", sql: query });
+                const normalizedError = (0, firebirdCompat_1.enhanceFirebirdError)(error, options, { stage: "execute", sql: query });
                 this.logger.error(normalizedError);
                 throw normalizedError;
             }