emilsoftware-utilities 2.0.0-dev.8 → 2.0.0-dev.80

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

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

package/docs/accessi-openapi-fingerprint.json

@@ -0,0 +1,192 @@
+{
+  "paths": [
+    "DELETE /api/accessi/federated-auth/identities/{identityKey} disableFederatedIdentity",
+    "DELETE /api/accessi/federated-auth/providers/{provider} deleteFederatedProvider",
+    "DELETE /api/accessi/federated-auth/users/{codiceUtente}/identities/{identityKey} deleteFederatedIdentityPermanently",
+    "DELETE /api/accessi/filtri/tipi/{tipFil} deleteTipoFiltro",
+    "DELETE /api/accessi/permission/delete-role/{codiceRuolo} deleteRole",
+    "DELETE /api/accessi/permission/menu-groups/{codiceGruppo} deleteMenuGroup",
+    "DELETE /api/accessi/permission/menu-types/{codiceTipo} deleteMenuType",
+    "DELETE /api/accessi/permission/menus/{codiceMenu} deleteMenu",
+    "DELETE /api/accessi/permission/scopes/{codiceScope} deleteScope",
+    "DELETE /api/accessi/service-token/{tokenId} revokeServiceToken",
+    "DELETE /api/accessi/user/delete-user-permanent/{codiceUtente} deleteUserPermanently",
+    "DELETE /api/accessi/user/delete-user/{codiceUtente} deleteUser",
+    "GET /api/accessi/auth/bootstrap-admin/status getAdminBootstrapStatus",
+    "GET /api/accessi/email/reset-password-page/{token} serveResetPasswordPage",
+    "GET /api/accessi/federated-auth/providers getFederatedProviders",
+    "GET /api/accessi/federated-auth/users/{codiceUtente}/identities getFederatedIdentities",
+    "GET /api/accessi/filtri/tipi getTipiFiltro",
+    "GET /api/accessi/filtri/utente getFiltriUtente",
+    "GET /api/accessi/permission/grants/{codiceUtente} getUserRolesAndGrants",
+    "GET /api/accessi/permission/groups-with-menus getGroupsWithMenus",
+    "GET /api/accessi/permission/menu-types getMenuTypes",
+    "GET /api/accessi/permission/menus getMenus",
+    "GET /api/accessi/permission/menus/{codiceMenu}/scopes getMenuScopes",
+    "GET /api/accessi/permission/roles getRoles",
+    "GET /api/accessi/permission/scopes getScopes",
+    "GET /api/accessi/schema getSchema",
+    "GET /api/accessi/service-token getServiceTokens",
+    "GET /api/accessi/user/get-users getUsers",
+    "GET /api/accessi/user/reset-password/{token} serveResetPasswordPageUser",
+    "PATCH /api/accessi/configurator/groups/{codiceGruppo}/enabled setGroupEnabled",
+    "PATCH /api/accessi/configurator/menus/{codiceMenu}/enabled setMenuEnabled",
+    "PATCH /api/accessi/federated-auth/identities/{identityKey} updateFederatedIdentity",
+    "PATCH /api/accessi/federated-auth/providers/{provider} updateFederatedProvider",
+    "PATCH /api/accessi/federated-auth/users/{codiceUtente}/password-login setPasswordLoginPolicy",
+    "PATCH /api/accessi/user/set-gdpr/{codiceUtente} setGdpr",
+    "POST /api/accessi/auth/bootstrap-admin bootstrapAdmin",
+    "POST /api/accessi/auth/confirm-reset-password/{token} resetPassword",
+    "POST /api/accessi/auth/get-user-by-token getUserByToken",
+    "POST /api/accessi/auth/introspect introspectAccessiToken",
+    "POST /api/accessi/auth/login login",
+    "POST /api/accessi/auth/refresh refreshAccessToken",
+    "POST /api/accessi/auth/revoke-sessions revokeSessions",
+    "POST /api/accessi/auth/revoke-token revokeToken",
+    "POST /api/accessi/auth/two-factor/resend resendTwoFactor",
+    "POST /api/accessi/auth/two-factor/verify verifyTwoFactor",
+    "POST /api/accessi/console/entry createConsoleEntryTicket",
+    "POST /api/accessi/console/entry/exchange exchangeConsoleEntryTicket",
+    "POST /api/accessi/email/send-reset-password-email sendPasswordResetEmail",
+    "POST /api/accessi/federated-auth/exchange exchangeFederatedIdentity",
+    "POST /api/accessi/federated-auth/providers createFederatedProvider",
+    "POST /api/accessi/federated-auth/users createFederatedUser",
+    "POST /api/accessi/federated-auth/users/{codiceUtente}/identities linkFederatedIdentity",
+    "POST /api/accessi/filtri/tipi createTipoFiltro",
+    "POST /api/accessi/filtri/utente saveFiltriUtente",
+    "POST /api/accessi/permission/assign-permissions/{codiceUtente} assignPermissionsToUser",
+    "POST /api/accessi/permission/assign-roles/{codiceUtente} assignRolesToUser",
+    "POST /api/accessi/permission/create-role createRole",
+    "POST /api/accessi/permission/menu-groups createMenuGroup",
+    "POST /api/accessi/permission/menu-types createMenuType",
+    "POST /api/accessi/permission/menus createMenu",
+    "POST /api/accessi/permission/scopes createScope",
+    "POST /api/accessi/service-token createServiceToken",
+    "POST /api/accessi/service-token/{tokenId}/rotate rotateServiceToken",
+    "POST /api/accessi/user/create-managed-user createManagedUser",
+    "POST /api/accessi/user/force-password-reset-legacy forcePasswordResetLegacy",
+    "POST /api/accessi/user/force-password-reset/{codiceUtente} forcePasswordReset",
+    "POST /api/accessi/user/login-as/{codiceUtente} createLoginAsUrl",
+    "POST /api/accessi/user/register register",
+    "POST /api/accessi/user/set-password/{codiceUtente} setUserPassword",
+    "POST /api/accessi/user/set-stato setStatoRegistrazione",
+    "PUT /api/accessi/filtri/tipi/{tipFil} updateTipoFiltro",
+    "PUT /api/accessi/permission/menu-groups/{codiceGruppo} updateMenuGroup",
+    "PUT /api/accessi/permission/menu-types/{codiceTipo} updateMenuType",
+    "PUT /api/accessi/permission/menus/{codiceMenu} updateMenu",
+    "PUT /api/accessi/permission/menus/{codiceMenu}/scopes setMenuScopes",
+    "PUT /api/accessi/permission/scopes/{codiceScope} updateScope",
+    "PUT /api/accessi/permission/scopes/{codiceScope}/menus setScopeMenus",
+    "PUT /api/accessi/permission/update-role/{codiceRuolo} updateRole",
+    "PUT /api/accessi/user/update-user/{codiceUtente} updateUtente"
+  ],
+  "schemas": [
+    "AbilitazioneMenu",
+    "AccessiIntrospectionResultDto",
+    "ActionResponse",
+    "AdminBootstrapStatusResponse",
+    "AdminBootstrapStatusResult",
+    "AssignPermissionsToUserRequest",
+    "AssignRolesToUserRequest",
+    "AuthenticatedTokenPayloadDto",
+    "AuthenticatedUserPayloadDto",
+    "BootstrapAdminRequest",
+    "BootstrapAdminResponse",
+    "BootstrapAdminResultDto",
+    "ConfirmResetPasswordRequest",
+    "ConsoleEntryExchangeRequest",
+    "ConsoleEntrySessionResponse",
+    "ConsoleEntrySessionResult",
+    "ConsoleEntryTicketResponse",
+    "ConsoleEntryTicketResult",
+    "ConsoleEntryTokenResult",
+    "CreateFederatedIdentityRequest",
+    "CreateFederatedProviderRequest",
+    "CreateFederatedUserRequest",
+    "CreateFilterTypeRequest",
+    "CreateMenuGroupRequest",
+    "CreateMenuRequest",
+    "CreateMenuTypeRequest",
+    "CreateScopeRequest",
+    "CreateServiceTokenRequest",
+    "CreateServiceTokenResponse",
+    "ErrorResponse",
+    "ExchangeFederatedIdentityRequest",
+    "FederatedAuthenticationResultDto",
+    "FederatedExchangeResponse",
+    "FederatedIdentityListResponse",
+    "FederatedIdentityResponse",
+    "FederatedIdentityResponseDto",
+    "FederatedProviderListResponse",
+    "FederatedProviderResponse",
+    "FederatedProviderResponseDto",
+    "FiltriUtente",
+    "GetFiltriResponse",
+    "GetFiltriUtenteResponse",
+    "GetGroupsWithMenusResponse",
+    "GetMenuScopesResponse",
+    "GetMenuTypesResponse",
+    "GetMenusResponse",
+    "GetRolesResponse",
+    "GetSchemaResponse",
+    "GetScopesResponse",
+    "GetServiceTokensResponse",
+    "GetUserByTokenRequest",
+    "GetUserByTokenResponse",
+    "GetUsersResponse",
+    "GetUsersResult",
+    "GroupWithMenusEntity",
+    "IntrospectAccessiTokenRequest",
+    "IntrospectAccessiTokenResponse",
+    "IssuedServiceTokenDto",
+    "LoginAsRequest",
+    "LoginAsResponse",
+    "LoginAsResult",
+    "LoginRequest",
+    "LoginResponse",
+    "LoginResult",
+    "MenuEntity",
+    "MenuTypeEntity",
+    "PasswordExpiredResponse",
+    "Permission",
+    "PublicRegisterRequest",
+    "RefreshTokenRequest",
+    "RefreshTokenResponse",
+    "RefreshTokenResult",
+    "RegisterRequest",
+    "RegisterResponse",
+    "ResendTwoFactorRequest",
+    "RevokeTokenRequest",
+    "Role",
+    "RuoliMenu",
+    "SchemaDdlResult",
+    "SchemaDdlSection",
+    "ScopeEntity",
+    "SendResetPasswordEmailRequest",
+    "ServiceTokenDto",
+    "SetMenuScopesRequest",
+    "SetPasswordLoginPolicyRequest",
+    "SetScopeMenusRequest",
+    "SetStatoRegistrazioneDto",
+    "SetUserPasswordRequest",
+    "Status",
+    "TipoFiltro",
+    "TokenResult",
+    "TwoFactorChallengeDto",
+    "UpdateEnabledStatusRequest",
+    "UpdateFederatedIdentityRequest",
+    "UpdateFederatedProviderRequest",
+    "UpdateFilterTypeRequest",
+    "UpdateMenuGroupRequest",
+    "UpdateMenuRequest",
+    "UpdateMenuTypeRequest",
+    "UpdateScopeRequest",
+    "UserDto",
+    "UserGrantsDto",
+    "UserGrantsResponse",
+    "VerifyTwoFactorRequest"
+  ],
+  "securitySchemes": [
+    "bearer"
+  ]
+}

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/adr/0002-multi-tenancy.md

@@ -0,0 +1,154 @@
+# ADR 0002 - Multi-tenancy con database separati
+
+- **Stato**: accettato
+- **Data**: 2026-10-30
+- **Contesto**: issue #10
+
+## Contesto
+
+Accessi nasce single-tenant: un database Firebird, un issuer JWT, un set di
+store e una console. Due tenant richiedono isolamento esplicito di dati, chiavi
+e osservabilità. Il modello dati non ha una colonna tenant e tutte le query
+assumono un solo insieme di utenti e menu.
+
+Vincoli:
+
+- Firebird/InterBase: non esistono schema o `search_path` per tenant; un
+  database separato è l'unità di isolamento naturale.
+- Le migrazioni e le seed sono per database.
+- `AccessiModule.forRoot` registra una configurazione globale nel contenitore
+  Nest: due tenant nello stesso processo condividerebbero DI, audit e logger.
+- L'isolamento richiesto dall'issue è "nessun dato o token di un tenant visibile
+  a un altro".
+
+## Decisione
+
+**Un database per tenant, nessuna colonna `TENANT`, nessuna modifica allo
+schema.** Un tenant è una cartella di configurazione:
+
+```
+tenants/
+  acme.env
+  beta.env
+```
+
+Ogni file contiene le normali variabili `ACCESSI_*` già lette da
+`createAccessiOptionsFromEnv`, più un manifest minimo:
+
+```dotenv
+ACCESSI_TENANT_HOSTS=accessi.acme.example.com,*.acme.example.com
+ACCESSI_TENANT_PATH=/acme
+ACCESSI_TENANT_PORT=3201
+ACCESSI_TENANT_ENABLED=true
+
+ACCESSI_DB_HOST=db-acme
+ACCESSI_DB_DATABASE=/data/acme.fdb
+ACCESSI_JWT_ISSUER=https://accessi.acme.example.com
+ACCESSI_JWT_AUDIENCE=accessi-api
+ACCESSI_JWT_SECRET=...
+ACCESSI_ENCRYPTION_KEY=...
+```
+
+`loadAccessiTenants({ directory })` valida l'intera cartella prima di avviare
+qualsiasi cosa:
+
+- `ACCESSI_TENANT_ID` (o nome file) univoco, minuscole/numeri/`-`/`_`;
+- almeno host o path; host e path non duplicati;
+- chiave JWT distinta per tenant (un token non deve valere su due tenant);
+- issuer/audience condivisi producono un warning;
+- un tenant con path `/` e senza host non può convivere con altri;
+- errori aggregati con nome file, senza stampare segreti.
+
+La risoluzione runtime è **host → path → header**:
+
+1. host esatto o wildcard `*.example.com`;
+2. prefisso path più lungo;
+3. header `x-accessi-tenant`, **solo** se `allowHeader: true` e quindi solo
+   dietro un proxy/API gateway che lo sovrascrive.
+
+Nessun fallback implicito: una richiesta senza tenant valido viene rifiutata
+dal router, non servita dal "primo" tenant.
+
+### Processo per tenant
+
+Ogni tenant gira in un **processo Accessi separato** con il proprio environment,
+database, pool, chiavi, store Redis e logger. Il supervisore
+`node scripts/accessi-tenants.cjs --serve` avvia un figlio per ogni file `.env`
+abilitato e passa `PORT`, `ACCESSI_TENANT_ID` e le variabili del file.
+
+Questo evita di condividere:
+
+- `AccessiModule.forRoot` e la DI Nest;
+- il registry globale di audit e metriche;
+- il pool Firebird e la cache delle migrazioni;
+- la chiave JWT e l'issuer.
+
+### Store condivisi
+
+Se più tenant condividono lo stesso Redis, ogni store deve usare un prefisso
+diverso:
+
+```ts
+const prefix = getAccessiTenantRedisPrefix('acme'); // accessi:acme:
+createRedisRateLimitStore({ client, keyPrefix: `${prefix}rate:` });
+createRedisSessionRevocationStore({ client, keyPrefix: `${prefix}session:` });
+```
+
+La configurazione del tenant espone `options.tenantId`, utile per comporre i
+prefissi e per le etichette di metriche e audit.
+
+### Osservabilità
+
+- Metriche: `countAccessiMetric` e `observeAccessiMetric` aggiungono
+  automaticamente il label `tenant` quando `options.tenantId` è impostato.
+- Audit: `configureAccessiAudit` aggiunge `tenant` a ogni record quando il
+  modulo è avviato con `tenantId`.
+- Log: il processo figlio ha il proprio `ACCESSI_TENANT_ID`; includerlo nel
+  formato del logger dell'host.
+- Health: ogni processo espone `/health/live`, `/health/ready` e
+  `/health/metrics` sulla propria porta interna.
+
+## Alternative scartate
+
+| Alternativa | Perché no |
+| --- | --- |
+| Colonna `TENANT` su tutte le tabelle | Migrazione invasiva, rischio di dimenticare un filtro, chiavi primarie e vincoli da rifare. Non necessaria con DB separati. |
+| Schema per tenant | Firebird non offre schema/search_path; sarebbe un database separato con altro nome. |
+| Due `AccessiModule` nello stesso processo | La configurazione Nest è globale; audit/metriche/logger condividono stato. |
+| Selezione tenant da header non fidato | Permetterebbe a un client di cambiare tenant e tentare leakage; consentito solo dietro proxy che sovrascrive l'header. |
+| Hot reload dei file `.env` | Nest non smonta moduli a caldo; il riavvio del supervisore è più semplice e sicuro. |
+
+## Conseguenze
+
+Positive:
+
+- isolamento forte: database, chiavi e processi separati;
+- nessuna migrazione dello schema esistente;
+- aggiunta tenant = nuovo file `.env` + riavvio del supervisore;
+- rollback per tenant indipendente.
+
+Negative:
+
+- più processi e pool Firebird da dimensionare;
+- migrazioni/seed da eseguire per ogni database;
+- backup, monitoring e rotazione chiavi per tenant;
+- l'header di risoluzione richiede disciplina sul proxy;
+- il supervisore deve essere gestito da systemd/docker/Kubernetes.
+
+## Piano
+
+1. **Fase 1 (questa)**: loader cartella, validazione isolamento, CLI
+   `accessi:tenants` (`--check`, `--list`, `--resolve`, `--serve`), documentazione
+   e test.
+2. **Fase 2**: template systemd/docker e reverse proxy host/path; health check
+   per tenant nel supervisore.
+3. **Fase 3**: migrazione del deployment single-tenant esistente: creare
+   `tenants/<id>.env` dal `.env` attuale, avviare in parallelo, spostare il DNS,
+   spegnere il vecchio servizio.
+4. **Fase 4 (opzionale)**: router in-process con `createAccessiTenantRouter`
+   solo se il costo dei processi diventa un problema e dopo test di leakage
+   dedicati; richiede audit/metriche per istanza, non globali.
+
+## Migrazione
+
+Vedi `docs/multi-tenancy.md` per la procedura operativa completa.

package/docs/audit.md

@@ -0,0 +1,136 @@
+# Audit persistente
+
+`auditAccessi` scrive un record strutturato per ogni evento di sicurezza. Di
+default il record finisce nel log (`AccessiAudit`); con `audit.sinks` può essere
+persistito su Redis, inoltrato a un collector HTTP o scritto su database e
+OpenTelemetry tramite una callback.
+
+```ts
+const accessiOptions: AccessiOptions = {
+  audit: {
+    retentionDays: 90,
+    logger: true,
+    store: createRedisAccessiAuditSink({
+      client: redisClient, // qualunque client con eval (ioredis, node-redis)
+      maxRecords: 100_000,
+      retentionMs: 90 * 24 * 60 * 60 * 1000,
+    }),
+    sinks: [
+      createHttpAccessiAuditSink({
+        url: 'https://siem.example.com/accessi/audit',
+        headers: { Authorization: `Bearer ${process.env.SIEM_TOKEN}` },
+      }),
+    ],
+  },
+};
+```
+
+`store` è il sink interrogabile usato dagli endpoint amministrativi. Se non è
+impostato, viene usato il primo sink con `query`/`purge` presente in `sinks`.
+Senza sink interrogabile gli endpoint rispondono `501 ACCESSI_AUDIT_STORE_DISABLED`
+e il log strutturato continua a funzionare.
+
+## Cosa viene registrato
+
+| Evento | Dettagli | Dove |
+| --- | --- | --- |
+| `login_succeeded` / `login_failed` | `codiceUtente`, `ip`, motivo | AuthController |
+| `two_factor_succeeded` / `two_factor_failed` | `codiceUtente`, `ip` | AuthController |
+| `refresh_succeeded` / `refresh_failed` | `ip`, motivo (`reuse`, `invalid`, ...) | AuthController |
+| `accessi_refresh_token_reuse` | `codiceUtente`, `jti`, `familyId` | AuthService |
+| `access_token_revoked` | utente, `jti`, self | AuthController |
+| `accessi_sessions_revoked` | utente, cutoff, motivo | sessionRevocation |
+| `public_rate_limited` / `edge_rate_limited` | scope, IP, retry | rate limit |
+| `console_ticket_issued` / `console_ticket_consumed` / `console_ticket_failed` | utente o esito | ConsoleEntryController |
+| `jwt_unknown_key_id` | `kid`, `purpose`, algoritmo | verifica JWT |
+
+Non vengono registrati token, password, header `Authorization`, cookie o chiavi
+private: la redazione è applicata prima del logger e di ogni sink.
+
+## Redazione
+
+`redactAccessiAuditValue` normalizza le chiavi (case-insensitive, ignora `-`,
+`_` e spazi) e sostituisce con `[REDACTED]`:
+
+`token`, `accessToken`, `refreshToken`, `idToken`, `bearer`, `jwt`,
+`authorization`, `cookie`, `set-cookie`, `password`, `passwordHash`,
+`hashedPassword`, `resetToken`, `secret`, `clientSecret`, `privateKey`,
+`apiKey`, `csrf`, `csrfToken`.
+
+Inoltre:
+
+- le stringhe oltre 512 caratteri vengono troncate;
+- gli array oltre 50 elementi e gli oggetti oltre 100 chiavi vengono limitati;
+- oltre 4 livelli di profondità il valore diventa `[TRUNCATED]`;
+- gli `Error` diventano `{ name, message }` senza stack.
+
+Aggiungere chiavi specifiche dell'host:
+
+```ts
+audit: { redact: ['cardNumber', 'iban'] }
+```
+
+## Retention
+
+`retentionDays` abilita la pulizia periodica (al massimo una volta all'ora,
+pigra, al primo evento successivo) dei sink che implementano `purge`. I sink
+in memoria hanno anche `maxRecords`. Il sink Redis usa `LTRIM` più `PEXPIRE`:
+
+```ts
+createRedisAccessiAuditSink({
+  client: redisClient,
+  maxRecords: 100_000,
+  retentionMs: 90 * 24 * 60 * 60 * 1000,
+});
+```
+
+La retention deve essere almeno pari agli obblighi di legge applicabili e alla
+durata massima dei token, così un incidente resta ricostruibile.
+
+## Endpoint amministrativi
+
+Richiedono un JWT Accessi di un superutente o admin:
+
+```http
+GET /api/accessi/audit?event=login_failed&from=2026-01-01T00:00:00Z&limit=100
+GET /api/accessi/audit/export?event=login_failed&from=2026-01-01T00:00:00Z
+```
+
+La query restituisce `{ records, total, limit, offset }`. L'export produce
+NDJSON (`application/x-ndjson`) con gli stessi filtri, senza paginazione, fino a
+100000 record per richiesta. I record sono già redatti.
+
+## Sink disponibili
+
+| Factory | Uso |
+| --- | --- |
+| `createMemoryAccessiAuditSink` | test, sviluppo, singola istanza |
+| `createRedisAccessiAuditSink` | persistenza condivisa multi-istanza |
+| `createHttpAccessiAuditSink` | SIEM/collector HTTP |
+| `createCallbackAccessiAuditSink` | database applicativo, OpenTelemetry, coda |
+
+Esempio database/OTel:
+
+```ts
+const dbSink = createCallbackAccessiAuditSink(async (record) => {
+  await db.insert('AUDIT_EVENTS', {
+    EVENT: record.event,
+    OCCURRED_AT: record.timestamp,
+    PAYLOAD: JSON.stringify(record),
+  });
+}, 'database');
+```
+
+La callback deve gestire i propri errori: un errore viene contato in
+`accessi_audit_sink_errors_total{sink}` e non blocca la richiesta.
+
+## Note
+
+- I sink sono globali per processo: configurare un solo modulo Accessi per
+  processo, come già avviene per il logger Accessi.
+- `audit.enabled: false` disattiva i sink ma **non** il log strutturato; usare
+  `logger: false` per silenziare anche quello.
+- Non inserire payload applicativi completi nei dettagli degli eventi: la
+  redazione è una rete di sicurezza, non un invito a loggare dati sensibili.
+- L'audit non sostituisce le metriche: usare `docs/metrics.md` per gli alert in
+  tempo reale.