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

package/docs/accessi-openapi-fingerprint.json

@@ -0,0 +1,190 @@
+{
+  "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/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",
+    "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/gateway-rate-limit.md

@@ -0,0 +1,98 @@
+# Gateway rate limit per Accessi Service
+
+Il rate limit applicativo di Accessi protegge login, 2FA, reset password, console entry e service token. Il gateway/API gateway resta utile per una protezione per IP, connessioni e bot prima che la richiesta raggiunga Node.
+
+Regole consigliate:
+
+- `/api/accessi/auth/*`: soglia bassa, burst contenuto
+- `/api/accessi/console/entry/exchange`: soglia bassa
+- `/api/accessi/*`: soglia media
+- `/accessi/openapi*` e `/accessi/.well-known/jwks.json`: soglia alta o cache CDN
+
+## Nginx
+
+```nginx
+limit_req_zone $binary_remote_addr zone=accessi_auth:10m rate=2r/s;
+limit_req_zone $binary_remote_addr zone=accessi_api:10m rate=10r/s;
+limit_conn_zone $binary_remote_addr zone=accessi_conn:10m;
+
+server {
+    # Se Accessi e dietro un proxy/load balancer, configura real_ip
+    # prima di usare $binary_remote_addr.
+
+    location /api/accessi/auth/ {
+        limit_req zone=accessi_auth burst=10 nodelay;
+        limit_conn accessi_conn 20;
+        proxy_pass http://accessi_service;
+    }
+
+    location /api/accessi/ {
+        limit_req zone=accessi_api burst=50 nodelay;
+        limit_conn accessi_conn 20;
+        proxy_pass http://accessi_service;
+    }
+
+    location /accessi/ {
+        limit_req zone=accessi_api burst=50 nodelay;
+        proxy_pass http://accessi_service;
+    }
+}
+```
+
+## Traefik
+
+```yaml
+http:
+  middlewares:
+    accessi-auth-ratelimit:
+      rateLimit:
+        average: 2
+        burst: 10
+        period: 1s
+    accessi-api-ratelimit:
+      rateLimit:
+        average: 10
+        burst: 50
+        period: 1s
+  routers:
+    accessi-auth:
+      rule: PathPrefix(`/api/accessi/auth/`)
+      middlewares: [accessi-auth-ratelimit]
+      service: accessi
+    accessi-api:
+      rule: PathPrefix(`/api/accessi/`) || PathPrefix(`/accessi/`)
+      middlewares: [accessi-api-ratelimit]
+      service: accessi
+```
+
+## Cloudflare
+
+Regole di rate limiting:
+
+- path `/api/accessi/auth/*`: 10 richieste/minuto per IP, azione `managed challenge`
+- path `/api/accessi/console/entry/exchange`: 30 richieste/5 minuti per IP
+- path `/api/accessi/*`: 300 richieste/minuto per IP, azione `block`
+- path `/accessi/.well-known/jwks.json`: cache CDN, limite alto
+
+Aggiungere bot fight mode/WAF secondo il piano disponibile.
+
+## AWS WAF / API Gateway
+
+- rate-based rule: 300 richieste/5 minuti per IP
+- scope-down statement: `URI starts with /api/accessi`
+- regola più severa su `/api/accessi/auth/*`
+- AWS Shield/WAF Bot Control se disponibile
+
+## Rapporto con `edgeRateLimit` della libreria
+
+`edgeRateLimit` e un ultimo livello applicativo:
+
+- usa lo stesso `RateLimitStore` Redis dei rate limit per account;
+- copre Accessi anche se il gateway non ha regole specifiche;
+- non sostituisce WAF, bot protection, limiti di connessione o protezione DDoS.
+
+In produzione usare entrambi:
+
+```text
+Client -> CDN/WAF -> API gateway -> edgeRateLimit Accessi -> rate limit per account
+```

package/docs/standalone-service.md

@@ -0,0 +1,176 @@
+# Accessi Service standalone
+
+Accessi puo girare come servizio autonomo, senza un backend ospitante.
+
+## Avvio da codice
+
+```ts
+import { startAccessiService } from "emilsoftware-utilities/accessi/server";
+
+await startAccessiService({
+  port: Number(process.env.PORT ?? 3000),
+  healthPath: "/health",
+  metrics: true,
+});
+```
+
+`startAccessiService`:
+
+- valida `AccessiOptions` con `assertValidAccessiOptions`
+- crea l'app Express
+- monta `/health/live`, `/health/ready`, `/health/metrics`
+- inizializza Accessi
+- avvia il server
+- registra `SIGTERM`/`SIGINT` per lo shutdown graceful
+- chiude Nest e i pool Firebird
+
+Per un controllo manuale usare `createAccessiService`, che restituisce `start()` e `stop()`.
+
+## Avvio da CLI
+
+```bash
+npm run accessi:serve
+npm run accessi:serve:dist
+```
+
+La configurazione viene letta da `createAccessiOptionsFromEnv()`.
+
+## Health
+
+```text
+GET /health/live      -> 200 se il processo e vivo
+GET /health/ready     -> 200 se DB e store configurati sono pronti
+GET /health/metrics   -> metriche Prometheus testuali
+```
+
+`/health/ready` controlla:
+
+- bootstrap completato
+- database Accessi raggiungibile e schema inizializzato
+- `healthCheck()` degli store Redis configurati
+- `readinessChecks` aggiuntivi passati dal chiamante
+
+## Esecuzione come processo
+
+In produzione il servizio viene eseguito come processo Node gestito da systemd, PM2 o dal supervisor del cliente:
+
+```bash
+npm run accessi:serve:dist
+# oppure
+node dist/scripts/startAccessiService.js
+```
+
+Esempio systemd minimale:
+
+```ini
+[Unit]
+Description=Accessi Service
+After=network.target
+
+[Service]
+WorkingDirectory=/opt/accessi-service
+EnvironmentFile=/etc/accessi/accessi.env
+ExecStart=/usr/bin/node dist/scripts/startAccessiService.js
+Restart=on-failure
+RestartSec=5
+KillSignal=SIGTERM
+TimeoutStopSec=15
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Il readiness endpoint `/health/ready` va usato dal load balancer o dal supervisore per decidere quando inviare traffico.
+
+## Configurazione consigliata
+
+- `ACCESSI_DB_*`
+- `ACCESSI_ENCRYPTION_KEY`
+- `ACCESSI_JWT_SECRET`
+- `ACCESSI_JWT_ISSUER`
+- `ACCESSI_JWT_AUDIENCE`
+- `ACCESSI_JWT_ALGORITHM`, `ACCESSI_JWT_PRIVATE_KEY`, `ACCESSI_JWT_PUBLIC_KEY`, `ACCESSI_JWT_KEY_ID` per RS/ES
+- `ACCESSI_JWKS_PATH`
+- SMTP
+- `PORT`
+
+Per Redis, passare gli store nel bootstrap applicativo:
+
+```ts
+import { createRedisRateLimitStore, createRedisConsoleEntryStore } from "emilsoftware-utilities/accessi/server";
+```
+
+## Generazione chiavi JWT
+
+```bash
+npm run accessi:generate-jwt-keys -- --algorithm RS256 --out ./keys
+```
+
+Genera:
+
+- `jwt-private.pem`
+- `jwt-public.pem`
+- `jwks.json`
+- `jwt-keys.json` con `algorithm` e `keyId`
+
+Configurare poi:
+
+```env
+ACCESSI_JWT_ALGORITHM=RS256
+ACCESSI_JWT_PRIVATE_KEY=<contenuto jwt-private.pem>
+ACCESSI_JWT_PUBLIC_KEY=<contenuto jwt-public.pem>
+ACCESSI_JWT_KEY_ID=<keyId>
+```
+
+## Revoca sessioni
+
+```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>
+```
+
+I resource server fratelli devono ricevere lo stesso store in `revocation.store`.
+
+## Console su dominio separato
+
+Se la console è servita da un dominio diverso dall’API:
+
+```ts
+accessiOptions: {
+  ...options,
+  consoleApiBaseUrl: "https://accessi.example.com",
+}
+```
+
+Accessi inietta `window.__ACCESSI_API_BASE_URL__` nella pagina della console.
+
+## CORS e proxy
+
+```ts
+accessiOptions: {
+  ...options,
+  http: {
+    cors: {
+      origin: ["https://app.example.com"],
+      credentials: false,
+    },
+    trustProxy: 1, // load balancer/reverse proxy
+    securityHeaders: true,
+  },
+}
+```
+
+Con Bearer token non serve CSRF. Se in futuro si passasse a cookie httpOnly, aggiungere CSRF e configurazione cookie same-site.