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

package/dist/initEmilsoftwareModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"initEmilsoftwareModule.js","sourceRoot":"","sources":["../src/initEmilsoftwareModule.ts"],"names":[],"mappings":"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","sourcesContent":["import express, { Application, Request } from \"express\";\nimport { NestFactory } from \"@nestjs/core\";\nimport { ExpressAdapter } from \"@nestjs/platform-express\";\nimport type { INestApplication } from \"@nestjs/common\";\nimport type { OpenAPIObject } from \"@nestjs/swagger\";\nimport {\n    buildOpenApiExcludePaths,\n    isOpenApiRequestPath,\n    resolveAccessiOpenApiOptions,\n    setupOpenApi\n} from \"./openapi/OpenApiConfig\";\nimport { Logger } from \"./Logger\";\nimport { EmilsoftwareModule, EmilsoftwareOptions } from \"./EmilsoftwareModule\";\nimport {\n    beginAccessiAuthInitialization,\n    failAccessiAuthInitialization,\n    setAccessiAuthService\n} from \"./accessi-module/middleware/authenticateGen\";\nimport { registerAccessiModuleServices } from \"./accessi-module/accessiRuntime\";\nimport { logAccessiStartup } from \"./accessi-module/startupLog\";\nimport { createAccessiValidationPipe } from './accessi-module/security/accessiValidation';\nimport { AccessiHttpExceptionFilter } from './accessi-module/security/AccessiHttpExceptionFilter';\nimport { getAccessiJwksPath, setupAccessiJwks } from './accessi-module/security/jwks';\nimport { createAccessiEdgeRateLimitMiddleware } from './accessi-module/security/edgeRateLimit';\n\n/** Esito del bootstrap del modulo unificato. */\nexport interface EmilsoftwareModuleInitializationResult {\n    /** Sotto-app Nest che serve Accessi, Allegati e la documentazione. */\n    nestApp: INestApplication;\n    /** Documento OpenAPI generato, mergiabile nel documento unico dell'host. */\n    document: OpenAPIObject;\n}\n\n/**\n * Initializes the unified module that combines Accessi and Allegati functionality\n * @param app Express application instance\n * @param options Configuration options for both modules\n * @returns Il sotto-app Nest e il documento OpenAPI generato.\n */\nexport async function initEmilsoftwareModule(\n    app: Application,\n    options: EmilsoftwareOptions\n): Promise<EmilsoftwareModuleInitializationResult> {\n    const logger: Logger = new Logger(initEmilsoftwareModule.name);\n    if (options?.accessiOptions) {\n        beginAccessiAuthInitialization();\n    }\n\n    try {\n        // Isolate Nest on a dedicated Express instance and dispatch only module routes.\n        // This keeps pre-existing routes/middlewares on the host app untouched.\n        // Prefisso OpenAPI configurabile (default `accessi/openapi`), cosi' piu'\n        // documentazioni possono convivere (backend su `/openapi`, moduli sotto\n        // `/<modulo>/openapi`).\n        // Precedenza: EmilsoftwareOptions.openapi > AccessiOptions.openapi > default.\n        const resolvedOpenApi = resolveAccessiOpenApiOptions(\n            options?.accessiOptions?.openapi,\n            options?.openapi\n        );\n\n        const nestHostApp = express();\n        const jwksPath = options?.accessiOptions\n            ? getAccessiJwksPath(options.accessiOptions)\n            : undefined;\n        const isNestRoute = (path: string) =>\n            path === \"/api\" ||\n            path.startsWith(\"/api/\") ||\n            isOpenApiRequestPath(path, resolvedOpenApi) ||\n            (jwksPath !== undefined && path === jwksPath);\n        const edgeRateLimit = options?.accessiOptions?.edgeRateLimit\n            ? createAccessiEdgeRateLimitMiddleware({\n                ...options.accessiOptions.edgeRateLimit,\n                match: options.accessiOptions.edgeRateLimit.match ?? ((path) => isNestRoute(path)),\n            })\n            : undefined;\n        if (edgeRateLimit) {\n            app.use(edgeRateLimit);\n        }\n\n        app.use((req: Request, res, next) => {\n            if (!isNestRoute(req.path)) {\n                return next();\n            }\n            return nestHostApp(req, res, next);\n        });\n\n        if (options?.accessiOptions) {\n            setupAccessiJwks(app, options.accessiOptions);\n            if (jwksPath) {\n                logger.info(`JWKS accessi disponibile su: ${jwksPath}`);\n            }\n        }\n\n        const nestExpressInstance = new ExpressAdapter(nestHostApp);\n        const nestApp = await NestFactory.create(EmilsoftwareModule.forRoot(options), nestExpressInstance, {\n            bufferLogs: options?.bufferLogs !== false,\n            ...(options?.logger ? { logger: options.logger } : {})\n        });\n\n        nestApp.enableCors();\n        if (options?.accessiOptions) {\n            // Keep the Accessi API contract identical for standalone and unified bootstraps.\n            nestApp.useGlobalPipes(createAccessiValidationPipe());\n            nestApp.useGlobalFilters(new AccessiHttpExceptionFilter());\n        }\n\n        nestApp.setGlobalPrefix('api', {\n            exclude: buildOpenApiExcludePaths(resolvedOpenApi)\n        });\n\n        // Documentazione OpenAPI del modulo unificato (Accessi + Allegati).\n        const document = setupOpenApi(nestApp, resolvedOpenApi);\n\n        await nestApp.init();\n        if (options?.accessiOptions) {\n            const accessiServices = registerAccessiModuleServices(app, nestApp);\n            app.locals.accessiAuthService = accessiServices.authenticateGenService;\n            setAccessiAuthService(accessiServices.authenticateGenService);\n            logAccessiStartup(options.accessiOptions, resolvedOpenApi);\n        }\n\n        logger.info(\"Emilsoftware module initialized successfully\");\n\n        return { nestApp, document };\n    } catch (error) {\n        if (options?.accessiOptions) {\n            failAccessiAuthInitialization(error);\n        }\n        logger.error(\"Error initializing Emilsoftware Module:\", error);\n        throw error;\n    }\n}\n"]}
+{"version":3,"file":"initEmilsoftwareModule.js","sourceRoot":"","sources":["../src/initEmilsoftwareModule.ts"],"names":[],"mappings":"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","sourcesContent":["import express, { Application, Request } from \"express\";\nimport { NestFactory } from \"@nestjs/core\";\nimport { ExpressAdapter } from \"@nestjs/platform-express\";\nimport type { INestApplication } from \"@nestjs/common\";\nimport type { OpenAPIObject } from \"@nestjs/swagger\";\nimport {\n    buildOpenApiExcludePaths,\n    isOpenApiRequestPath,\n    resolveAccessiOpenApiOptions,\n    setupOpenApi\n} from \"./openapi/OpenApiConfig\";\nimport { Logger } from \"./Logger\";\nimport { EmilsoftwareModule, EmilsoftwareOptions } from \"./EmilsoftwareModule\";\nimport {\n    beginAccessiAuthInitialization,\n    failAccessiAuthInitialization,\n    setAccessiAuthService\n} from \"./accessi-module/middleware/authenticateGen\";\nimport { registerAccessiModuleServices } from \"./accessi-module/accessiRuntime\";\nimport { logAccessiStartup } from \"./accessi-module/startupLog\";\nimport { createAccessiValidationPipe } from './accessi-module/security/accessiValidation';\nimport { AccessiHttpExceptionFilter } from './accessi-module/security/AccessiHttpExceptionFilter';\nimport { getAccessiJwksPath, setupAccessiJwks } from './accessi-module/security/jwks';\nimport { createAccessiEdgeRateLimitMiddleware } from './accessi-module/security/edgeRateLimit';\n\n/** Esito del bootstrap del modulo unificato. */\nexport interface EmilsoftwareModuleInitializationResult {\n    /** Sotto-app Nest che serve Accessi, Allegati e la documentazione. */\n    nestApp: INestApplication;\n    /** Documento OpenAPI generato, mergiabile nel documento unico dell'host. */\n    document: OpenAPIObject;\n}\n\n/**\n * Initializes the unified module that combines Accessi and Allegati functionality\n * @param app Express application instance\n * @param options Configuration options for both modules\n * @returns Il sotto-app Nest e il documento OpenAPI generato.\n */\nexport async function initEmilsoftwareModule(\n    app: Application,\n    options: EmilsoftwareOptions\n): Promise<EmilsoftwareModuleInitializationResult> {\n    const logger: Logger = new Logger(initEmilsoftwareModule.name);\n    if (options?.accessiOptions) {\n        beginAccessiAuthInitialization();\n    }\n\n    try {\n        // Isolate Nest on a dedicated Express instance and dispatch only module routes.\n        // This keeps pre-existing routes/middlewares on the host app untouched.\n        // Prefisso OpenAPI configurabile (default `accessi/openapi`), cosi' piu'\n        // documentazioni possono convivere (backend su `/openapi`, moduli sotto\n        // `/<modulo>/openapi`).\n        // Precedenza: EmilsoftwareOptions.openapi > AccessiOptions.openapi > default.\n        const resolvedOpenApi = resolveAccessiOpenApiOptions(\n            options?.accessiOptions?.openapi,\n            options?.openapi\n        );\n\n        const nestHostApp = express();\n        if (options?.accessiOptions?.http?.trustProxy !== undefined) {\n            app.set('trust proxy', options.accessiOptions.http.trustProxy);\n            nestHostApp.set('trust proxy', options.accessiOptions.http.trustProxy);\n        }\n        const jwksPath = options?.accessiOptions\n            ? getAccessiJwksPath(options.accessiOptions)\n            : undefined;\n        const isNestRoute = (path: string) =>\n            path === \"/api\" ||\n            path.startsWith(\"/api/\") ||\n            isOpenApiRequestPath(path, resolvedOpenApi) ||\n            (jwksPath !== undefined && path === jwksPath);\n        const edgeRateLimit = options?.accessiOptions?.edgeRateLimit\n            ? createAccessiEdgeRateLimitMiddleware({\n                ...options.accessiOptions.edgeRateLimit,\n                match: options.accessiOptions.edgeRateLimit.match ?? ((path) => isNestRoute(path)),\n            })\n            : undefined;\n        if (edgeRateLimit) {\n            app.use(edgeRateLimit);\n        }\n        if (options?.accessiOptions?.http?.securityHeaders !== false) {\n            app.use((req: Request, res, next) => {\n                if (!isNestRoute(req.path)) {\n                    return next();\n                }\n                res.setHeader('X-Content-Type-Options', 'nosniff');\n                res.setHeader('X-Frame-Options', 'SAMEORIGIN');\n                res.setHeader('Referrer-Policy', 'no-referrer');\n                res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');\n                return next();\n            });\n        }\n\n        app.use((req: Request, res, next) => {\n            if (!isNestRoute(req.path)) {\n                return next();\n            }\n            return nestHostApp(req, res, next);\n        });\n\n        if (options?.accessiOptions) {\n            setupAccessiJwks(app, options.accessiOptions);\n            if (jwksPath) {\n                logger.info(`JWKS accessi disponibile su: ${jwksPath}`);\n            }\n        }\n\n        const nestExpressInstance = new ExpressAdapter(nestHostApp);\n        const nestApp = await NestFactory.create(EmilsoftwareModule.forRoot(options), nestExpressInstance, {\n            bufferLogs: options?.bufferLogs !== false,\n            ...(options?.logger ? { logger: options.logger } : {})\n        });\n\n        if (options?.accessiOptions?.http?.cors !== false) {\n            nestApp.enableCors(options?.accessiOptions?.http?.cors);\n        }\n        if (options?.accessiOptions) {\n            // Keep the Accessi API contract identical for standalone and unified bootstraps.\n            nestApp.useGlobalPipes(createAccessiValidationPipe());\n            nestApp.useGlobalFilters(new AccessiHttpExceptionFilter());\n        }\n\n        nestApp.setGlobalPrefix('api', {\n            exclude: buildOpenApiExcludePaths(resolvedOpenApi)\n        });\n\n        // Documentazione OpenAPI del modulo unificato (Accessi + Allegati).\n        const document = setupOpenApi(nestApp, resolvedOpenApi);\n\n        await nestApp.init();\n        if (options?.accessiOptions) {\n            const accessiServices = registerAccessiModuleServices(app, nestApp);\n            app.locals.accessiAuthService = accessiServices.authenticateGenService;\n            setAccessiAuthService(accessiServices.authenticateGenService);\n            logAccessiStartup(options.accessiOptions, resolvedOpenApi);\n        }\n\n        logger.info(\"Emilsoftware module initialized successfully\");\n\n        return { nestApp, document };\n    } catch (error) {\n        if (options?.accessiOptions) {\n            failAccessiAuthInitialization(error);\n        }\n        logger.error(\"Error initializing Emilsoftware Module:\", error);\n        throw error;\n    }\n}\n"]}

package/dist/scripts/startAccessiService.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/startAccessiService.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("../accessi/server");
+const Logger_1 = require("../Logger");
+(0, server_1.startAccessiService)().catch((error) => {
+    new Logger_1.Logger('startAccessiService').error('Avvio Accessi Service fallito:', error instanceof Error
+        ? { name: error.name, message: error.message, stack: error.stack }
+        : { error: String(error) });
+    process.exitCode = 1;
+});
+//# sourceMappingURL=startAccessiService.js.map

package/dist/scripts/startAccessiService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startAccessiService.js","sourceRoot":"","sources":["../../src/scripts/startAccessiService.ts"],"names":[],"mappings":";;AAAA,8CAAwD;AACxD,sCAAmC;AAEnC,IAAA,4BAAmB,GAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC7C,IAAI,eAAM,CAAC,qBAAqB,CAAC,CAAC,KAAK,CACrC,gCAAgC,EAChC,KAAK,YAAY,KAAK;QACpB,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;QAClE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAC7B,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["import { startAccessiService } from '../accessi/server';\nimport { Logger } from '../Logger';\n\nstartAccessiService().catch((error: unknown) => {\n  new Logger('startAccessiService').error(\n    'Avvio Accessi Service fallito:',\n    error instanceof Error\n      ? { name: error.name, message: error.message, stack: error.stack }\n      : { error: String(error) },\n  );\n  process.exitCode = 1;\n});\n"]}

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/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.

package/integration-prompt.md

@@ -74,6 +74,60 @@ const { nestApp, document } = await initializeAccessiModule(app, options);
 
 Aprire la porta HTTP solo dopo l'await.
 
+### Avvio standalone
+
+Per un servizio Accessi autonomo:
+
+```ts
+import { startAccessiService } from "emilsoftware-utilities/accessi/server";
+
+await startAccessiService({
+  port: Number(process.env.PORT ?? 3000),
+  healthPath: "/health",
+  metrics: true,
+});
+```
+
+Oppure:
+
+```bash
+npm run accessi:serve
+```
+
+Endpoint:
+
+```text
+GET /health/live
+GET /health/ready
+GET /health/metrics
+```
+
+`/health/ready` controlla bootstrap, database, schema, store Redis configurati e `readinessChecks` custom. `startAccessiService` registra SIGTERM/SIGINT e chiude Nest e i pool Firebird.
+
+In produzione il servizio viene eseguito come processo Node con systemd/PM2/supervisor:
+
+```bash
+npm run accessi:serve:dist
+```
+
+Dettagli e esempio systemd: `docs/standalone-service.md`.
+
+### Validazione configurazione
+
+```ts
+import {
+  assertValidAccessiOptions,
+  validateAccessiOptions,
+} from "emilsoftware-utilities/accessi/server";
+
+const validation = validateAccessiOptions(options);
+// validation.errors / validation.warnings
+
+assertValidAccessiOptions(options); // fail-fast
+```
+
+`createAccessiService` la applica automaticamente. Controlla JWT/key, DB, encryption key, URL email, rate limit, console entry e `http`.
+
 ### Bootstrap Nest
 
 ```ts
@@ -150,6 +204,24 @@ const merged = mergeOpenApiDocuments(hostDocument, accessiDocument, {
 });
 ```
 
+### HTTP, CORS e proxy
+
+```ts
+http: {
+  cors: {
+    origin: ["https://app.example.com"],
+    credentials: false,
+  },
+  trustProxy: 1, // load balancer/reverse proxy
+  securityHeaders: true,
+}
+```
+
+- `cors: false` disabilita CORS.
+- `trustProxy` e obbligatorio per rate limit corretti dietro proxy.
+- `securityHeaders` aggiunge `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`.
+- Con Bearer token non serve CSRF. Se usi cookie httpOnly, aggiungi CSRF e cookie same-site.
+
 ### JWKS e rotazione chiavi
 
 Con RS256/ES256 Accessi pubblica automaticamente:
@@ -271,6 +343,12 @@ Il gateway/API gateway resta consigliato per:
 
 Configurazioni di riferimento: `docs/gateway-rate-limit.md`.
 
+### Audit
+
+Resource server ed edge rate limit producono eventi strutturati tramite `auditAccessi`. I campi sensibili vengono redatti dal Logger. Disattivabile con `audit: false` nelle rispettive opzioni.
+
+Nel servizio standalone le metriche Prometheus sono su `/health/metrics`.
+
 ---
 
 ## 4. Backend fratello — Express
@@ -397,6 +475,60 @@ Risposta:
 - Il resource server cachea i risultati attivi per `cacheTtlMs` (default 30s). I risultati inattivi non sono cachati.
 - Fail closed: se Accessi Service non risponde, la richiesta non viene autorizzata.
 
+### SSO exchange service-to-service
+
+Se un backend fratello valida un provider SSO proprio, non deve duplicare utenti o grant. Dopo aver verificato firma, issuer, audience e subject del provider, chiama:
+
+```http
+POST /api/accessi/federated-auth/exchange
+Authorization: Bearer <service-token>
+Content-Type: application/json
+
+{ "provider": "azure-ad-acme-produzione", "subject": "<oid o sub>" }
+```
+
+Scope richiesto: `accessi:federated:exchange`.
+
+La risposta contiene:
+
+- `codiceUtente`
+- `login` con profilo, grant e token
+- `token` assente quando è richiesta la verifica 2FA
+
+Accessi non riceve il token del provider: riceve solo l'identità esterna già verificata.
+
+### Revoca sessioni
+
+Configurazione:
+
+```ts
+import { createRedisSessionRevocationStore } from "emilsoftware-utilities/accessi/server";
+
+sessionRevocation: {
+  store: createRedisSessionRevocationStore({
+    client: redis,
+    ttlMs: 30 * 24 * 60 * 60 * 1000, // maggiore della durata massima dei token
+  }),
+}
+```
+
+Endpoint utente:
+
+```http
+POST /api/accessi/auth/revoke-sessions
+Authorization: Bearer <access-token>
+```
+
+Invalida i token emessi prima della chiamata. I token emessi dopo restano validi. Per i backend fratelli configurare lo stesso store anche nel resource server:
+
+```ts
+revocation: {
+  store: revocationStore,
+}
+```
+
+Senza store condiviso la revoca vale solo nel processo che la esegue.
+
 ---
 
 ## 7. Frontend
@@ -426,6 +558,29 @@ configureAccessiClient({
 });
 ```
 
+Se `jwtOptions.refreshExpiresIn` è configurato, la risposta contiene anche `refreshToken`. Conservarlo separatamente dall’access token e usarlo su:
+
+```http
+POST /api/accessi/auth/refresh
+Content-Type: application/json
+
+{ "refreshToken": "<refresh-token>" }
+```
+
+La risposta contiene un nuovo `token` e un nuovo `refreshToken`. Il refresh token ha `typ: "refresh"` e non va mai usato come Bearer sulle API.
+
+Per rendere il refresh token monouso anche in multi-istanza:
+
+```ts
+import { createRedisRefreshTokenRotationStore } from "emilsoftware-utilities/accessi/server";
+
+refreshTokenRotation: {
+  store: createRedisRefreshTokenRotationStore({ client: redis }),
+}
+```
+
+Ogni refresh consuma il vecchio `jti` in modo atomico. Due refresh concorrenti dello stesso token producono un solo successo.
+
 Per token che cambiano nel tempo:
 
 ```ts
@@ -455,6 +610,7 @@ const consoleUrl = buildAccessiConsoleUrl("https://accessi.example.com", {
 - Il ticket e monouso, dura 60 secondi.
 - Per il 2FA handoff usare `twoFactorChallengeId`.
 - Se la console deve stare sullo stesso dominio, fare reverse proxy di `/api/accessi/*` verso Accessi Service, non copiare gli asset.
+- Se la UI della console è su un dominio diverso dall’API, configurare `consoleApiBaseUrl`: Accessi inietta `window.__ACCESSI_API_BASE_URL__` nella pagina servita.
 
 ### Web component
 
@@ -485,6 +641,7 @@ Per chiamare l'introspection o API tecniche:
 2. Creare un token dalla console o con `POST /api/accessi/service-token`.
 3. Assegnare lo scope minimo necessario:
    - `accessi:introspect` per l'introspection
+   - `accessi:federated:exchange` per scambiare un'identita SSO verificata
    - altri scope applicativi secondo necessita
 4. Conservarlo come secret nel backend fratello.
 5. Ruotarlo periodicamente; il segreto e mostrato una sola volta.
@@ -520,6 +677,7 @@ ACCESSI_DB_PASSWORD=
 ACCESSI_ENCRYPTION_KEY=
 ACCESSI_JWT_SECRET=
 ACCESSI_JWT_EXPIRES=24h
+ACCESSI_JWT_REFRESH_EXPIRES=30d
 ACCESSI_JWT_ISSUER=accessi
 ACCESSI_JWT_AUDIENCE=backend-app
 # Opzionale RS256
@@ -584,6 +742,8 @@ Checklist:
    - rotazione JWKS con vecchia chiave ancora valida
 11. Aggiornare CORS se i frontend cambiano dominio.
 12. Aggiornare monitoraggio e log senza includere token.
+13. Eseguire `npm run check:accessi-openapi` e `npm run typecheck` prima del rilascio.
+14. Dopo una modifica intenzionale al contratto, aggiornare il fingerprint con `npm run accessi:update-openapi-fingerprint` e includerlo nel commit.
 
 ---