node-user-profiling

In sintesi

Servizio di autorizzazione enterprise: risponde alle domande "chi è questo utente?" e "cosa può fare?" per l'intero portale ditta. Mantiene la proiezione locale dell'identità applicativa — ruoli, permessi granulari, gruppi, team, policy ABAC dinamiche — e ne pubblica il risultato come decisione autorizzativa cache-friendly. Si distingue dal complementare node-user-auth, che gestisce come l'utente si autentica (cookie nginx, JWT, OAuth M2M): qui si concentra esclusivamente la logica RBAC/ABAC e l'analisi del rischio. Le route REST sono il canale primario; NATS è usato in modo puntuale per restare allineato a eventi di ciclo vita utente.

Funzionalità principali

• RBAC gerarchico su cinque livelli (superadmin > admin > manager > operatore > viewer) con ereditarietà permessi e prevenzione cicli a livello DB
• ABAC engine con policy allow / deny / conditional, condizioni runtime su orari, dipartimenti e attributi della richiesta, modalità fail_open / fail_closed
• Gestione gruppi e team: CRUD completo, membership, ruoli e permessi collettivi su auth.gruppi (tipogruppo progetto o organizzativo), invalidazione cache transitiva
• Check autorizzazione singolo e batch (POST /api/v1/authorization/check e /bulk-check) con cache distribuita Redis e TTL distinti per esiti positivi, sensibili e negativi
• Endpoint nginx auth_request: verifica l'autorizzazione di una richiesta a partire dagli header inoltrati dal reverse proxy (/nginx-auth)
• Anomaly detection con risk scoring 0-100, finestre di osservazione configurabili, alert su soglia, indagine pattern per singolo utente
• Audit trail delle decisioni autorizzative tramite event bus interno (audit, metrics, security alert) con correlation ID propagato
• Reconciliation utenti orfani (/api/v1/admin/users/exists) e endpoint internal S2S (/api/v1/internal/*) per fallback hard-delete e operazioni batch protette da X-Internal-Token
• Migrazioni SQL idempotenti con checksum tracking eseguite all'avvio del processo

Architettura

Stack: Fastify v5 · Inversify (DI con @injectable / @inject e profili default / high-performance / high-security / development) · PostgreSQL via driver pg (schema auth) · Redis opzionale per cache decisioni · NATS opzionale per un singolo subject di sincronizzazione · @pzeta/fastify-utils (authPlugin, securityPlugin, errorHandlerPlugin, openapiPlugin, healthcheckPlugin) · @pzeta/authorization (libreria interna che fornisce AuthorizationOrchestrator, PermissionEvaluationService, BusinessPolicyService, SecurityAnalyticsService) · @pzeta/log per logging strutturato · Zod per validazione input.

Layout DDD (src/):

Pattern adottati: Clean Architecture + DDD, Dependency Injection (Inversify), Repository, Factory, Strategy (profili AUTH_SERVICE_PROFILE), in-memory event bus per side-effects post-decisione (audit / metrics / security alert), Result monad per error handling funzionale nei servizi di dominio.

RBAC e ABAC: le route applicano requirePermission() sulla coppia resource:action derivata dal contesto. Il check finale è risolto dall'AuthorizationOrchestrator che combina decisione RBAC (materializzata dai ruoli effettivi dell'utente: diretti + ereditati + da gruppi/team), valutazione ABAC della policy applicabile e politica di fallback fail_open / fail_closed per ogni policy.

Casi d'uso

• Gestione ruoli da UI admin: il frontend Vue (sezione amministrativa) crea un nuovo ruolo via POST /api/v1/roles, ne dichiara il parentRoleId, associa permessi resource:action e lo assegna a gruppi/team o singoli utenti con eventuale scadenza
• Check permessi runtime da altri microservizi: un servizio applicativo (es. node-orchestrator) invia POST /api/v1/authorization/check con { userId, resource, action, context } per decidere se eseguire un task sensibile; le decisioni sono cacheable con TTL configurabili
• Autorizzazione del reverse proxy: nginx invoca /nginx-auth con header x-user-id e path target; il servizio risponde 200/403 e popola gli header inoltrati alla risorsa protetta
• Sincronizzazione utenti da provider esterno: node-user-auth, dopo aver registrato un nuovo utente nell'identity provider, può triggerare la reconciliation via GET /api/v1/admin/users/exists o pubblicare un evento di cancellazione su NATS (vedi sezione eventing) per propagare l'hard-delete GDPR
• Investigazione security: l'operatore SOC consulta /api/v1/anomalies per identificare utenti con risk score elevato, ricostruisce la timeline dei tentativi negati tramite gli aggregati esposti da /api/v1/stats e disabilita ruoli compromessi
• Operazioni batch internal: pipeline di sistema chiamano /api/v1/internal/users/:userId/roles/batch (protette da X-Internal-Token) per riassegnare massivamente ruoli a fronte di una riorganizzazione

Identità & esposizione

Endpoint operazionali

Endpoint convenzionali esposti da tutti i microservizi PZeta basati su @pzeta/fastify-utils:

Configurazione

Variabili d'ambiente che un integratore deve conoscere (per la lista completa vedi .env.example del repo):

Swagger UI e api-docs.json runtime sono esposti solo quando AUTH_SERVICE_PROFILE=development o, in produzione, se OPENAPI_EXPOSE_IN_PRODUCTION=true.

Note eventing NATS

Il servizio è principalmente HTTP-driven e usa NATS come canale secondario di sincronizzazione, non come trasporto primario delle decisioni autorizzative. La connessione NATS è opzionale: se NATS_URL non è configurato o non raggiungibile, il servizio prosegue in modalità degradata mantenendo intatte tutte le funzionalità REST.

Il subscriber NATS effettivamente registrato è uno solo: UserDeletedSubscriber ascolta ${NATS_NAMESPACE}.authz.user.deleted (override via USER_DELETED_SUBJECT) per ricevere notifiche di hard-delete GDPR pubblicate da node-user-auth. Alla ricezione invoca AuthorizationAppService.cleanupUser, idempotente per costruzione (DELETE su righe assenti = no-op). Le semantiche di delivery sono at-most-once (Core NATS senza JetStream): un errore nell'handler scarta il messaggio; il recupero avviene via endpoint HTTP /api/v1/internal/users/:userId/cleanup (manuale) o reconciliation batch /api/v1/admin/users/exists. L'upgrade a JetStream a livello infrastruttura aggiunge at-least-once senza modifiche al codice.

I dieci subject che lo scanner statico rileva nel file nats.json (permission.granted, permission.denied, anomaly.detected, policy.evaluated, cache.invalidated) non sono subject NATS: sono sottoscrizioni a un InMemoryEventPublisher interno usato per pipeline di side-effect (audit, metrics, security alert) generate dalle decisioni autorizzative. Vengono restituite dallo scanner perché l'API subscribe() è omonima a quella NATS, ma il dispatch avviene in-process. In altre parole, il servizio mantiene una proiezione locale dell'identità ma la mantiene per pull (HTTP) o per evento puntuale di lifecycle (cancellazione utente), non per stream continuo.

Dipendenze e dipendenti

Dipende da (servizi che questo servizio chiama):

• Nessuna dipendenza applicativa diretta.

Consumato da (chi chiama questo servizio):

• node-user-auth
• frontend Vue

Infrastruttura (PostgreSQL, NATS, Redis, MinIO) non è elencata qui — vedi sezione Architettura del singolo servizio.