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

package/dist/openapi/OpenApiMerge.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeOpenApiDocuments = mergeOpenApiDocuments;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneDocument(document) {
+    return JSON.parse(JSON.stringify(document));
+}
+function sameValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function mergeRecord(target, source, policy, section) {
+    if (!source)
+        return target;
+    const merged = Object.assign({}, (target !== null && target !== void 0 ? target : {}));
+    for (const [key, value] of Object.entries(source)) {
+        if (!(key in merged)) {
+            merged[key] = value;
+            continue;
+        }
+        if (sameValue(merged[key], value))
+            continue;
+        if (policy === "keep")
+            continue;
+        if (policy === "overwrite") {
+            merged[key] = value;
+            continue;
+        }
+        throw new Error(`Conflitto OpenAPI in ${section}.${key}.`);
+    }
+    return merged;
+}
+function mergeTags(target, source, policy) {
+    if (!Array.isArray(target) || !Array.isArray(source))
+        return target !== null && target !== void 0 ? target : source;
+    const merged = [...target];
+    for (const tag of source) {
+        if (!isRecord(tag) || typeof tag.name !== "string") {
+            merged.push(tag);
+            continue;
+        }
+        const existingIndex = merged.findIndex((candidate) => isRecord(candidate) && candidate.name === tag.name);
+        if (existingIndex < 0) {
+            merged.push(tag);
+            continue;
+        }
+        const existing = merged[existingIndex];
+        if (sameValue(existing, tag))
+            continue;
+        if (policy === "keep")
+            continue;
+        if (policy === "overwrite") {
+            merged[existingIndex] = tag;
+            continue;
+        }
+        throw new Error(`Conflitto OpenAPI nel tag "${tag.name}".`);
+    }
+    return merged;
+}
+function mergeServers(target, source, policy) {
+    if (!Array.isArray(target) || !Array.isArray(source))
+        return target !== null && target !== void 0 ? target : source;
+    const merged = [...target];
+    for (const server of source) {
+        if (!isRecord(server) || typeof server.url !== "string") {
+            merged.push(server);
+            continue;
+        }
+        const existingIndex = merged.findIndex((candidate) => isRecord(candidate) && candidate.url === server.url);
+        if (existingIndex < 0) {
+            merged.push(server);
+            continue;
+        }
+        const existing = merged[existingIndex];
+        if (sameValue(existing, server))
+            continue;
+        if (policy === "keep")
+            continue;
+        if (policy === "overwrite") {
+            merged[existingIndex] = server;
+            continue;
+        }
+        throw new Error(`Conflitto OpenAPI nel server "${server.url}".`);
+    }
+    return merged;
+}
+/**
+ * Unisce il documento Accessi nel documento OpenAPI dell'host.
+ *
+ * Per default un conflitto su path, schema o security scheme produce errore:
+ * e meglio accorgersi subito di due contratti incompatibili. Usare
+ * `conflict: "overwrite"` solo quando il documento host deve vincere.
+ */
+function mergeOpenApiDocuments(target, source, options = {}) {
+    var _a;
+    if (!target || !source) {
+        throw new Error("mergeOpenApiDocuments richiede due documenti OpenAPI validi.");
+    }
+    const policy = (_a = options.conflict) !== null && _a !== void 0 ? _a : "error";
+    const result = cloneDocument(target);
+    const sourceDocument = source;
+    result.paths = mergeRecord(isRecord(result.paths) ? result.paths : undefined, isRecord(sourceDocument.paths) ? sourceDocument.paths : undefined, policy, "paths");
+    const targetComponents = isRecord(result.components) ? result.components : {};
+    const sourceComponents = isRecord(sourceDocument.components) ? sourceDocument.components : {};
+    const componentSections = new Set([
+        ...Object.keys(targetComponents),
+        ...Object.keys(sourceComponents),
+    ]);
+    const mergedComponents = Object.assign({}, targetComponents);
+    for (const section of componentSections) {
+        mergedComponents[section] = mergeRecord(isRecord(targetComponents[section]) ? targetComponents[section] : undefined, isRecord(sourceComponents[section]) ? sourceComponents[section] : undefined, policy, `components.${section}`);
+    }
+    result.components = mergedComponents;
+    result.tags = mergeTags(result.tags, sourceDocument.tags, policy);
+    result.servers = mergeServers(result.servers, sourceDocument.servers, policy);
+    return result;
+}
+//# sourceMappingURL=OpenApiMerge.js.map

package/dist/openapi/OpenApiMerge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiMerge.js","sourceRoot":"","sources":["../../src/openapi/OpenApiMerge.ts"],"names":[],"mappings":"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","sourcesContent":["import type { OpenAPIObject } from \"@nestjs/swagger\";\n\n/** Politica di risoluzione quando due documenti definiscono la stessa chiave. */\nexport type OpenApiMergeConflictPolicy = \"error\" | \"keep\" | \"overwrite\";\n\nexport interface MergeOpenApiOptions {\n  /** Default: `error`. */\n  conflict?: OpenApiMergeConflictPolicy;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction cloneDocument(document: OpenAPIObject): Record<string, unknown> {\n  return JSON.parse(JSON.stringify(document)) as Record<string, unknown>;\n}\n\nfunction sameValue(left: unknown, right: unknown): boolean {\n  return JSON.stringify(left) === JSON.stringify(right);\n}\n\nfunction mergeRecord(\n  target: Record<string, unknown> | undefined,\n  source: Record<string, unknown> | undefined,\n  policy: OpenApiMergeConflictPolicy,\n  section: string,\n): Record<string, unknown> | undefined {\n  if (!source) return target;\n  const merged: Record<string, unknown> = { ...(target ?? {}) };\n\n  for (const [key, value] of Object.entries(source)) {\n    if (!(key in merged)) {\n      merged[key] = value;\n      continue;\n    }\n    if (sameValue(merged[key], value)) continue;\n    if (policy === \"keep\") continue;\n    if (policy === \"overwrite\") {\n      merged[key] = value;\n      continue;\n    }\n    throw new Error(`Conflitto OpenAPI in ${section}.${key}.`);\n  }\n\n  return merged;\n}\n\nfunction mergeTags(\n  target: unknown,\n  source: unknown,\n  policy: OpenApiMergeConflictPolicy,\n): unknown {\n  if (!Array.isArray(target) || !Array.isArray(source)) return target ?? source;\n  const merged = [...target];\n  for (const tag of source) {\n    if (!isRecord(tag) || typeof tag.name !== \"string\") {\n      merged.push(tag);\n      continue;\n    }\n    const existingIndex = merged.findIndex(\n      (candidate) => isRecord(candidate) && candidate.name === tag.name,\n    );\n    if (existingIndex < 0) {\n      merged.push(tag);\n      continue;\n    }\n    const existing = merged[existingIndex];\n    if (sameValue(existing, tag)) continue;\n    if (policy === \"keep\") continue;\n    if (policy === \"overwrite\") {\n      merged[existingIndex] = tag;\n      continue;\n    }\n    throw new Error(`Conflitto OpenAPI nel tag \"${tag.name}\".`);\n  }\n  return merged;\n}\n\nfunction mergeServers(\n  target: unknown,\n  source: unknown,\n  policy: OpenApiMergeConflictPolicy,\n): unknown {\n  if (!Array.isArray(target) || !Array.isArray(source)) return target ?? source;\n  const merged = [...target];\n  for (const server of source) {\n    if (!isRecord(server) || typeof server.url !== \"string\") {\n      merged.push(server);\n      continue;\n    }\n    const existingIndex = merged.findIndex(\n      (candidate) => isRecord(candidate) && candidate.url === server.url,\n    );\n    if (existingIndex < 0) {\n      merged.push(server);\n      continue;\n    }\n    const existing = merged[existingIndex];\n    if (sameValue(existing, server)) continue;\n    if (policy === \"keep\") continue;\n    if (policy === \"overwrite\") {\n      merged[existingIndex] = server;\n      continue;\n    }\n    throw new Error(`Conflitto OpenAPI nel server \"${server.url}\".`);\n  }\n  return merged;\n}\n\n/**\n * Unisce il documento Accessi nel documento OpenAPI dell'host.\n *\n * Per default un conflitto su path, schema o security scheme produce errore:\n * e meglio accorgersi subito di due contratti incompatibili. Usare\n * `conflict: \"overwrite\"` solo quando il documento host deve vincere.\n */\nexport function mergeOpenApiDocuments(\n  target: OpenAPIObject,\n  source: OpenAPIObject,\n  options: MergeOpenApiOptions = {},\n): OpenAPIObject {\n  if (!target || !source) {\n    throw new Error(\"mergeOpenApiDocuments richiede due documenti OpenAPI validi.\");\n  }\n\n  const policy = options.conflict ?? \"error\";\n  const result = cloneDocument(target);\n  const sourceDocument = source as unknown as Record<string, unknown>;\n\n  result.paths = mergeRecord(\n    isRecord(result.paths) ? result.paths : undefined,\n    isRecord(sourceDocument.paths) ? sourceDocument.paths : undefined,\n    policy,\n    \"paths\",\n  );\n\n  const targetComponents = isRecord(result.components) ? result.components : {};\n  const sourceComponents = isRecord(sourceDocument.components) ? sourceDocument.components : {};\n  const componentSections = new Set([\n    ...Object.keys(targetComponents),\n    ...Object.keys(sourceComponents),\n  ]);\n  const mergedComponents: Record<string, unknown> = { ...targetComponents };\n  for (const section of componentSections) {\n    mergedComponents[section] = mergeRecord(\n      isRecord(targetComponents[section]) ? targetComponents[section] : undefined,\n      isRecord(sourceComponents[section]) ? sourceComponents[section] : undefined,\n      policy,\n      `components.${section}`,\n    );\n  }\n  result.components = mergedComponents;\n\n  result.tags = mergeTags(result.tags, sourceDocument.tags, policy);\n  result.servers = mergeServers(result.servers, sourceDocument.servers, policy);\n\n  return result as unknown as OpenAPIObject;\n}\n"]}

package/integration-prompt.md

@@ -0,0 +1,481 @@
+# Integration prompt — Accessi (`emilsoftware-utilities`)
+
+Questo documento e il contesto unico da passare a un agente AI o a uno sviluppatore che deve integrare Accessi in un backend, in un frontend o in un altro servizio.
+
+L'obiettivo e evitare l'errore piu comune: **montare `AccessiModule` ovunque**. Accessi e un servizio di identita; gli altri backend sono resource server.
+
+---
+
+## 1. Architettura da seguire
+
+```text
+Frontend A ─┐
+Frontend B ─┼──> Accessi Service (DB, SMTP, utenti, ruoli, console, SSO, 2FA)
+            │         ▲
+Backend A ──┼─────────┤  introspection / service token
+Backend B ──┘         │
+                      └──> Accessi DB (solo Accessi Service)
+```
+
+Regole:
+
+- **Accessi Service** e l'unico proprietario di:
+  - database Accessi e migrazioni
+  - `encryptionKey`
+  - SMTP
+  - chiavi JWT
+  - admin bootstrap
+  - console amministrativa
+- **Backend A/B** non hanno credenziali del DB Accessi e non eseguono migrazioni Accessi.
+- **Frontend A/B** fanno login su Accessi Service e usano il JWT verso i backend.
+- La console e centralizzata su Accessi Service.
+- Non montare `AccessiModule` in due backend puntati allo stesso database.
+
+Se per ora Accessi e montato dentro Backend A, va bene: Backend A e il proprietario. Backend B usa solo `accessi/resource-server` e `accessi/client`.
+
+---
+
+## 2. Entry point del pacchetto
+
+| Import | Quando usarlo |
+|---|---|
+| `emilsoftware-utilities/accessi/server` | Backend che ospita Accessi: `AccessiModule`, `initializeAccessiModule`, updater DB, migrazioni, console. |
+| `emilsoftware-utilities/accessi/resource-server` | Backend fratello: middleware Express, guard Nest, verifica JWT e introspection. |
+| `emilsoftware-utilities/accessi/client` | Client OpenAPI generato per chiamare Accessi Service. |
+| `emilsoftware-utilities/accessi/contracts` | Tipi, enum e helper puri browser-safe. |
+| `emilsoftware-utilities/accessi/contracts/dtos` | DTO Nest con `class-validator` e decoratori OpenAPI. Solo backend. |
+| `emilsoftware-utilities/accessi/openapi` | `setupOpenApi`, `mergeOpenApiDocuments`. |
+| `emilsoftware-utilities/accessi/console` | `buildAccessiConsoleUrl`, URL console e ticket. |
+| `emilsoftware-utilities/accessi/ui` | Percorsi asset Web Component frameworkless. |
+
+Il root export `emilsoftware-utilities` resta per retrocompatibilita, ma nei nuovi progetti usare gli entry point sopra.
+
+---
+
+## 3. Backend che ospita Accessi
+
+### Bootstrap Express
+
+```ts
+import { initializeAccessiModule } from "emilsoftware-utilities/accessi/server";
+
+const { nestApp, document } = await initializeAccessiModule(app, options);
+// document e il documento OpenAPI Accessi, gia con /api/accessi/*
+```
+
+`initializeAccessiModule` restituisce:
+
+```ts
+{
+  nestApp: INestApplication;
+  document: OpenAPIObject;
+}
+```
+
+Aprire la porta HTTP solo dopo l'await.
+
+### Bootstrap Nest
+
+```ts
+import { AccessiModule } from "emilsoftware-utilities/accessi/server";
+
+@Module({
+  imports: [AccessiModule.forRoot(options)],
+})
+export class AppModule {}
+```
+
+### Configurazione minima
+
+```ts
+import type { AccessiServerOptions } from "emilsoftware-utilities/accessi/server";
+
+const options: AccessiServerOptions = {
+  databaseOptions: {
+    host: process.env.ACCESSI_DB_HOST!,
+    port: Number(process.env.ACCESSI_DB_PORT ?? 3050),
+    database: process.env.ACCESSI_DB_NAME!,
+    user: process.env.ACCESSI_DB_USER!,
+    password: process.env.ACCESSI_DB_PASSWORD!,
+  },
+  confirmationEmailUrl: "https://app.example.com",
+  confirmationEmailReturnUrl: "https://app.example.com/login",
+  encryptionKey: process.env.ACCESSI_ENCRYPTION_KEY!,
+  mockDemoUser: false,
+  autoUpdateDatabase: true,
+  legacyPasswordMigrationOnStartup: true,
+  jwtOptions: {
+    secret: process.env.ACCESSI_JWT_SECRET!,
+    expiresIn: "24h",
+    issuer: "accessi",
+    audience: "backend-app",
+    // Per multi-servizio:
+    // algorithm: "RS256",
+    // privateKey: process.env.ACCESSI_JWT_PRIVATE_KEY,
+    // publicKey: process.env.ACCESSI_JWT_PUBLIC_KEY,
+    // keyId: "accessi-2026-01",
+  },
+  emailOptions: {
+    host: process.env.SMTP_HOST!,
+    port: Number(process.env.SMTP_PORT ?? 587),
+    secure: false,
+    requireTLS: true,
+    tls: { rejectUnauthorized: true },
+    from: "no-reply@example.com",
+    auth: { user: process.env.SMTP_USER!, pass: process.env.SMTP_PASS! },
+  },
+  serviceTokens: { enabled: true, defaultTtlDays: 365 },
+};
+```
+
+### OpenAPI
+
+```ts
+import { setupOpenApi, mergeOpenApiDocuments } from "emilsoftware-utilities/accessi/openapi";
+
+const document = setupOpenApi(nestApp, {
+  openApiPath: "accessi/openapi",
+  openApiJsonPath: "accessi/openapi.json",
+  title: "Accessi API Documentation",
+  description: "API del modulo accessi",
+  enabled: true,
+});
+```
+
+Per un documento unico host:
+
+```ts
+const merged = mergeOpenApiDocuments(hostDocument, accessiDocument, {
+  conflict: "error", // "keep" | "overwrite"
+});
+```
+
+---
+
+## 4. Backend fratello — Express
+
+```ts
+import { createAccessiAuthMiddleware } from "emilsoftware-utilities/accessi/resource-server";
+
+app.use(createAccessiAuthMiddleware({
+  mode: "local",
+  jwt: {
+    // HS256: passare il segreto grezzo Accessi, la KDF viene applicata qui
+    serverSecret: process.env.ACCESSI_JWT_SECRET,
+    issuer: "accessi",
+    audience: "backend-a",
+  },
+  // Opzionale: serve per leggere i grant correnti
+  introspection: {
+    url: "https://accessi.example.com/api/accessi/auth/introspect",
+    serviceToken: process.env.ACCESSI_SERVICE_TOKEN!,
+    cacheTtlMs: 30_000,
+    timeoutMs: 3_000,
+  },
+  authorization: {
+    requirements: [{ menuCode: "ORDINI", minPermissionLevel: 20 }],
+  },
+}));
+```
+
+Dopo il middleware:
+
+- `req.user`: payload autenticato (compatibile con il middleware storico)
+- `req.data`: alias di `req.user`
+- `req.userGrants`: presente solo se la policy richiede grant
+- `req.accessi`: `{ token, user, codiceUtente, grants?, payload? }`
+
+### HS256 vs RS256/JWKS
+
+- **HS256**: usare `jwt.serverSecret` con `ACCESSI_JWT_SECRET`. Il resource server deriva la chiave access con la stessa KDF del server.
+- **RS256/ES256**: usare `jwt.publicKey` PEM oppure `jwt.jwks.url`. Consigliato in multi-servizio.
+- Il server Accessi supporta `jwtOptions.algorithm`, `privateKey`, `publicKey`, `keyId`.
+- Accessi non espone ancora un endpoint JWKS integrato: pubblicare la chiave pubblica con il proprio hosting/reverse proxy oppure usare `publicKey` PEM.
+
+### Errori
+
+| HTTP | Codice | Significato |
+|---|---|---|
+| 401 | `AUTH_TOKEN_MISSING` | Header Bearer assente o malformato. |
+| 401 | `AUTH_TOKEN_INVALID` | Firma, scadenza, issuer/audience o tipo token non validi. |
+| 401 | `AUTH_USER_CODE_MISSING` | Token senza `codiceUtente`. |
+| 403 | `AUTH_INSUFFICIENT_PERMISSIONS` | Policy di autorizzazione non soddisfatta. |
+| 500 | `AUTH_CONFIG_INVALID` | Configurazione resource server incompleta. |
+| 500 | `AUTH_GRANTS_SOURCE_MISSING` | Policy richiede grant ma introspection non configurata. |
+| 503 | `AUTH_INTROSPECTION_UNAVAILABLE` | Accessi Service non raggiungibile; fail closed. |
+| 503 | `AUTH_INTROSPECTION_UNAUTHORIZED` | Service token invalido o senza `accessi:introspect`. |
+| 503 | `AUTH_JWKS_UNAVAILABLE` | JWKS non raggiungibile. |
+
+---
+
+## 5. Backend fratello — NestJS
+
+```ts
+import {
+  createAccessiAuthGuard,
+  type AccessiAuthenticatedRequest,
+} from "emilsoftware-utilities/accessi/resource-server";
+
+@UseGuards(createAccessiAuthGuard({
+  jwt: { publicKey: process.env.ACCESSI_JWT_PUBLIC_KEY, algorithms: ["RS256"] },
+  introspection: {
+    url: process.env.ACCESSI_INTROSPECT_URL!,
+    serviceToken: process.env.ACCESSI_SERVICE_TOKEN!,
+  },
+  authorization: {
+    requirements: [{ menuCode: "ORDINI", minPermissionLevel: 20 }],
+  },
+}))
+@Get("ordini")
+list(@Req() req: AccessiAuthenticatedRequest) {
+  return req.user;
+}
+```
+
+Il guard mappa gli errori in `UnauthorizedException`, `ForbiddenException`, `ServiceUnavailableException` o `InternalServerErrorException`.
+
+---
+
+## 6. Introspection
+
+Endpoint:
+
+```http
+POST /api/accessi/auth/introspect
+Authorization: Bearer <service-token>
+Content-Type: application/json
+
+{ "token": "<access-token-utente>" }
+```
+
+Scope richiesto:
+
+```text
+accessi:introspect
+```
+
+Risposta:
+
+```json
+{
+  "Status": { "errorCode": "0", "errorDescription": "" },
+  "Result": {
+    "active": true,
+    "user": { "codiceUtente": 123, "email": "utente@example.com" },
+    "grants": { "abilitazioni": [], "ruoli": [], "grants": [] }
+  },
+  "Message": "Dati recuperati con successo."
+}
+```
+
+- `active: false` per token invalido, scaduto o utente disabilitato.
+- Gli errori di database/configurazione sono 500: non vanno interpretati come token scaduto.
+- Il client `createAccessiIntrospectionClient` normalizza `Result`, applica timeout e cache.
+- 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.
+
+---
+
+## 7. Frontend
+
+### Login
+
+Il frontend chiama Accessi Service:
+
+```ts
+import { configureAccessiClient, login } from "emilsoftware-utilities/accessi/client";
+
+configureAccessiClient({
+  baseUrl: "https://accessi.example.com",
+  token: null,
+});
+
+const response = await login({ email, password });
+const token = response.data.Result.token.value;
+```
+
+Dopo il login:
+
+```ts
+configureAccessiClient({
+  baseUrl: "https://accessi.example.com",
+  token,
+});
+```
+
+Per token che cambiano nel tempo:
+
+```ts
+configureAccessiClient({
+  baseUrl: "https://accessi.example.com",
+  getToken: () => authStore.getToken(),
+});
+```
+
+### Chiamate ai backend
+
+Il frontend usa il JWT Accessi come Bearer verso Backend A/B. Non serve che il frontend importi il resource server.
+
+### Console
+
+Non incorporare la console in ogni applicazione. Linkare Accessi Service:
+
+```ts
+import { buildAccessiConsoleUrl } from "emilsoftware-utilities/accessi/console";
+
+const consoleUrl = buildAccessiConsoleUrl("https://accessi.example.com", {
+  entryTicket: ticket, // da POST /api/accessi/console/entry
+});
+```
+
+- Il JWT non va mai nell'URL.
+- 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.
+
+### Web component
+
+```html
+<script type="module" src="/assets/aree-disponibili/aree-disponibili.js"></script>
+<es-aree-disponibili></es-aree-disponibili>
+```
+
+I componenti sono frameworkless e ricevono i dati via proprieta; non fanno chiamate di rete.
+
+---
+
+## 8. Contratti e DTO
+
+- `accessi/contracts`: tipi/enum/helper puri, adatti anche al browser.
+- `accessi/contracts/dtos`: DTO Nest con decoratori; non usarli in bundle frontend leggeri.
+- `accessi/client`: tipi generati dall'OpenAPI e funzioni HTTP; e la fonte consigliata per frontend e backend fratelli.
+
+Non usare i DTO server come contratto pubblico se il frontend non ha `class-validator`, `class-transformer` e `reflect-metadata`.
+
+---
+
+## 9. Service token
+
+Per chiamare l'introspection o API tecniche:
+
+1. Abilitare `serviceTokens: { enabled: true }` su Accessi Service.
+2. Creare un token dalla console o con `POST /api/accessi/service-token`.
+3. Assegnare lo scope minimo necessario:
+   - `accessi:introspect` per l'introspection
+   - altri scope applicativi secondo necessita
+4. Conservarlo come secret nel backend fratello.
+5. Ruotarlo periodicamente; il segreto e mostrato una sola volta.
+
+Non usare un service token nel browser.
+
+---
+
+## 10. Sicurezza: regole non negoziabili
+
+- Il database Accessi è solo di Accessi Service.
+- `encryptionKey`, SMTP, chiavi private JWT e admin bootstrap restano solo su Accessi Service.
+- In multi-servizio usare RS256/ES256 con chiave pubblica/JWKS. HS256 con segreto condiviso e accettabile solo come fase transitoria.
+- Non inserire JWT, ticket console o service token nei log.
+- Non mettere JWT o ticket nell'URL; il ticket console va nel fragment `#entry=`.
+- La console va centralizzata.
+- Le rotte amministrative richiedono policy esplicite; non fidarsi dei flag nel token senza introspection.
+- Le richieste con introspection non raggiungibile devono fallire chiuse.
+- Usare `issuer` e `audience` per evitare token di ambienti diversi.
+
+---
+
+## 11. Variabili ambiente consigliate
+
+Accessi Service:
+
+```env
+ACCESSI_DB_HOST=
+ACCESSI_DB_PORT=3050
+ACCESSI_DB_NAME=
+ACCESSI_DB_USER=
+ACCESSI_DB_PASSWORD=
+ACCESSI_ENCRYPTION_KEY=
+ACCESSI_JWT_SECRET=
+ACCESSI_JWT_EXPIRES=24h
+ACCESSI_JWT_ISSUER=accessi
+ACCESSI_JWT_AUDIENCE=backend-app
+# Opzionale RS256
+ACCESSI_JWT_ALGORITHM=RS256
+ACCESSI_JWT_PRIVATE_KEY=
+ACCESSI_JWT_PUBLIC_KEY=
+ACCESSI_JWT_KEY_ID=
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASS=
+ACCESSI_EMAIL_FROM=
+```
+
+Backend fratello:
+
+```env
+ACCESSI_JWT_PUBLIC_KEY=
+# oppure, solo HS256 transitorio:
+ACCESSI_JWT_SECRET=
+ACCESSI_JWT_ISSUER=accessi
+ACCESSI_JWT_AUDIENCE=backend-a
+ACCESSI_INTROSPECT_URL=https://accessi.example.com/api/accessi/auth/introspect
+ACCESSI_SERVICE_TOKEN=
+```
+
+Frontend:
+
+```env
+ACCESSI_API_BASE_URL=https://accessi.example.com
+ACCESSI_CONSOLE_URL=https://accessi.example.com/api/accessi/console
+```
+
+---
+
+## 12. Migrazione da Accessi embedded
+
+Checklist:
+
+1. Scegliere il proprietario: Accessi Service o un backend esistente.
+2. Se il DB resta lo stesso, non migrare i dati; cambiare solo rete e credenziali.
+3. Mantenere la stessa `encryptionKey` finche tutte le password legacy non sono migrate.
+4. Introdurre `issuer`/`audience` o RS256 solo con una finestra di migrazione: i token vecchi possono diventare invalidi.
+5. Spostare la console una sola volta.
+6. Passare i backend fratelli a `resource-server`.
+7. Configurare un service token con `accessi:introspect`.
+8. Testare:
+   - login
+   - token valido
+   - token scaduto
+   - utente disabilitato
+   - revoca grants
+   - Accessi Service spento (fail closed)
+   - console entry ticket
+9. Aggiornare CORS se i frontend cambiano dominio.
+10. Aggiornare monitoraggio e log senza includere token.
+
+---
+
+## 13. Prompt operativo da copiare
+
+### Per un backend
+
+> Integra Accessi usando l'entry point corretto. Se questo backend possiede il database Accessi, usa `emilsoftware-utilities/accessi/server` e `initializeAccessiModule`/`AccessiModule.forRoot`. Se non lo possiede, non importare `AccessiModule` e non configurare il database Accessi: usa `emilsoftware-utilities/accessi/resource-server` con `createAccessiAuthMiddleware` (Express) o `createAccessiAuthGuard` (Nest). Configura `jwt` con `publicKey`/`jwks` (preferito) o `serverSecret` (HS256), `issuer` e `audience`. Se servono grant, configura `introspection` con URL e service token scope `accessi:introspect`, e una cache breve. Applica una policy `authorization` esplicita sulle rotte sensibili. Non fidarti dei flag nel token senza introspection. Usa `accessi/client` per chiamare Accessi Service e `accessi/contracts` per i tipi. Non inserire token nei log o negli URL.
+
+### Per un frontend
+
+> Usa `emilsoftware-utilities/accessi/client`: chiama `configureAccessiClient({ baseUrl, token })` dopo il login e `getToken` se il token cambia. Il login, il refresh, il 2FA e il reset password passano da Accessi Service. Verso i backend usa `Authorization: Bearer <access-token>`. Non incorporare il database o il server Accessi. Per la console usa `buildAccessiConsoleUrl` con il ticket monouso restituito da `POST /api/accessi/console/entry`; non mettere mai il JWT nell'URL. Per i componenti UI usa gli asset di `accessi/ui`. Gestisci gli errori 401 (`AUTH_TOKEN_INVALID`) portando l'utente al login e 403 (`AUTH_INSUFFICIENT_PERMISSIONS`) mostrando un messaggio di permessi insufficienti.
+
+### Per un agente AI
+
+> Prima di modificare codice, leggi `integration-prompt.md`, `WIKI.md` e `src/accessi-module/Console/changelog.md`. Rispetta la separazione dei ruoli: `accessi/server` solo sul proprietario del DB, `accessi/resource-server` sui backend fratelli. Non aggiungere dipendenze dal database Accessi nei resource server. Non inventare endpoint: l'introspection e `POST /api/accessi/auth/introspect` con service token scope `accessi:introspect`. Non cambiare i default HS256 senza una finestra di migrazione. Aggiungi test per token valido, scaduto, utente disabilitato, permessi insufficienti e introspection non raggiungibile.
+
+---
+
+## 14. Limiti attuali da conoscere
+
+- I ticket di ingresso console sono in memoria del processo: con piu istanze di Accessi Service servono sticky session o uno store condiviso.
+- I rate limit pubblici e dei service token sono in memoria.
+- Accessi non espone ancora un endpoint JWKS pronto: il resource server sa verificare una JWKS, ma la chiave pubblica va pubblicata dall'host.
+- Il client generato e completo (include endpoint amministrativi): non distribuirlo a frontend non amministrativi senza valutare gli endpoint esposti. Per un client pubblico ridotto, generare un sottoinsieme per tag con Orval.
+- I DTO in `accessi/contracts/dtos` dipendono da Nest/class-validator: non sono pensati per bundle frontend minimali.