@fluxo-dev/api-client-base 26.4.1 → 26.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxo-dev/api-client-base",
-  "version": "26.4.1",
+  "version": "26.5.0",
   "type": "commonjs",
   "peerDependencies": {
     "react": "^18.3.1",
@@ -8,7 +8,7 @@
     "react-router-dom": "^6.11.2",
     "react-redux": "^8.0.5",
     "@reduxjs/toolkit": "^1.9.1",
-    "@fluxo-dev/state": "^26.4.0"
+    "@fluxo-dev/state": "^26.5.0"
   },
   "main": "./index.cjs.js",
   "types": "./index.cjs.d.ts"

package/src/index.d.ts

@@ -13,6 +13,7 @@ export * from './lib/security/user';
 export * from './lib/security/apikey';
 export * from './lib/security/domain-role';
 export * from './lib/security/permission';
+export * from './lib/security/policy';
 export * from './lib/auth';
 export * from './lib/communication';
 export * from './lib/korebi';

package/src/lib/auth/activity-tracker.d.ts

@@ -0,0 +1,73 @@
+export interface ActivityTimeoutConfig {
+    /** Inattività dopo cui la sessione viene chiusa */
+    timeoutMs: number;
+    /** Anticipo con cui mostrare l'avviso */
+    warningMs: number;
+    /** Chiamato una sola volta allo scadere del timeout */
+    onTimeout: () => void;
+}
+export interface ActivitySnapshot {
+    /** Ultima attività dell'utente in una qualsiasi tab (ms epoch), 0 se il tracker non è attivo */
+    lastActivityAt: number;
+    /** Secondi alla chiusura per inattività mentre l'avviso è in corso, altrimenti null */
+    warningSecondsLeft: number | null;
+}
+/**
+ * Rileva l'attività dell'utente (mouse, tastiera, touch, scroll) condividendola tra le tab tramite localStorage:
+ * l'attività in una tab tiene viva la sessione in tutte. I tempi si misurano sull'orologio, non contando i tick
+ * dei timer, perché le tab in background li rallentano e il computer può andare in sospensione.
+ * Segnala periodicamente l'attività al server, che chiude le sessioni inattive anche a browser chiuso.
+ */
+export declare class ActivityTracker {
+    private static _instance;
+    private running;
+    private localLastActivity;
+    private lastStorageWrite;
+    private pingInFlight;
+    private checkInterval;
+    private timeoutConfig;
+    private snapshot;
+    private listeners;
+    private readonly onUserActivity;
+    private readonly onVisibilityChange;
+    static get Instance(): ActivityTracker;
+    start(): void;
+    stop(): void;
+    /**
+     * Attiva (o disattiva con null) la chiusura per inattività. Senza configurazione il tracker continua
+     * comunque a rilevare l'attività e a segnalarla al server.
+     */
+    configureTimeout(config: ActivityTimeoutConfig | null): void;
+    /**
+     * Registra un'attività dell'utente. Con `immediate` (es. "Resta connesso", login) la condivide subito con le altre tab.
+     */
+    registerActivity(immediate?: boolean): void;
+    /**
+     * Tiene viva la sessione finché non si chiama la funzione restituita: registra subito un'attività
+     * e poi una ogni 30 secondi. Vale anche per il server, quindi va usato solo per operazioni avviate
+     * dall'utente in cui lui aspetta senza interagire (upload, elaborazioni lunghe), mai per tenere aperta una pagina.
+     * @returns la funzione che interrompe il keep-alive
+     */
+    keepAlive(): () => void;
+    /**
+     * Tiene viva la sessione finché l'operazione non termina, con successo o con errore.
+     * @example await ActivityTracker.Instance.keepAliveWhile(uploadService.upload(file));
+     */
+    keepAliveWhile<T>(operation: Promise<T>): Promise<T>;
+    /**
+     * Dimentica l'attività della sessione chiusa, così non conta per il login successivo.
+     */
+    clear(): void;
+    getSnapshot(): ActivitySnapshot;
+    /**
+     * L'utente è inattivo da almeno `thresholdMs` (false se il tracker non è attivo).
+     */
+    isIdle(thresholdMs: number): boolean;
+    subscribe(listener: () => void): () => void;
+    private check;
+    /**
+     * Segnala al server l'attività nuova, al massimo una volta al minuto per tutte le tab insieme.
+     */
+    private pingIfNeeded;
+    private setSnapshot;
+}

package/src/lib/auth/auth-service.d.ts

@@ -1,4 +1,23 @@
 import { SecurityPolicyInfo } from '../security/user';
+import { SessionEndReason } from './session-end-reason';
+/**
+ * Motivo per cui il login chiede di impostare una nuova password prima di aprire la sessione.
+ */
+export declare enum PasswordChangeReason {
+    Expired = 1,
+    RequiredByAdmin = 2
+}
+/**
+ * Esito di un passaggio del login. Se è richiesto un altro passaggio, `challengeToken` va passato
+ * a verify2FA (require2FA) o a completeRequiredPasswordChange (requirePasswordChange).
+ */
+export interface LoginAttemptResult {
+    success: boolean;
+    require2FA: boolean;
+    requirePasswordChange: boolean;
+    passwordChangeReason: PasswordChangeReason | null;
+    challengeToken: string | null;
+}
 export interface FluxoUserProfile {
     userId: string;
     firstname: string;
@@ -15,19 +34,37 @@ export interface FluxoUserProfile {
     canHandle2FA: boolean;
     canHandleAccessTokens: boolean;
     canDisable2FA: boolean;
+    /** Escluso dal logout per inattività */
+    idleTimeoutExempt: boolean;
+    /** Il logout per inattività si applica a questo utente: calcolato dal server, è il valore da seguire */
+    idleTimeoutApplies: boolean;
+    /** Scadenza della password (UTC), null se per l'utente non scade */
+    passwordExpiresAt: string | null;
 }
 export declare class AuthService {
-    private isRefreshingToken;
+    private refreshInFlight;
     constructor();
     setup(): Promise<void>;
     getProfile(): Promise<FluxoUserProfile | null>;
     private tryAutoLogin;
-    login(username: string, password: string): Promise<{
+    /**
+     * Primo passaggio del login. Se servono altri passaggi (2FA, nuova password) restituisce il challengeToken.
+     */
+    login(username: string, password: string): Promise<LoginAttemptResult>;
+    /**
+     * @param challengeToken restituito da login() quando require2FA è true (valido 5 minuti)
+     */
+    verify2FA(code: string, challengeToken: string): Promise<LoginAttemptResult>;
+    /**
+     * Imposta la nuova password quando il login la richiede (password scaduta o da cambiare) e apre la sessione.
+     * @param challengeToken restituito da login() o verify2FA() con requirePasswordChange (valido 5 minuti)
+     * @returns gli errori di validazione della nuova password, vuoti se il cambio è riuscito
+     */
+    completeRequiredPasswordChange(challengeToken: string, newPassword: string): Promise<{
         success: boolean;
-        require2FA: boolean;
-        userId: string;
+        errors: string[];
     }>;
-    verify2FA(code: string, userId: string): Promise<boolean>;
+    private handleLoginResponse;
     enable2FA(userId: string): Promise<{
         qrCodeUri: string;
         sharedKey: string;
@@ -37,7 +74,21 @@ export declare class AuthService {
     }>;
     disable2FA(userId: string): Promise<boolean>;
     updateSecurityPolicyInfo(userId: string, info: SecurityPolicyInfo): Promise<void>;
-    logout(): void;
+    /**
+     * @param reason motivo da mostrare nella pagina di login quando la chiusura non è stata chiesta dall'utente
+     */
+    logout(reason?: SessionEndReason): void;
+    /**
+     * Chiusura della sessione decisa dal server (revoca, inattività, password scaduta) o da un amministratore.
+     * Ignorata se la sessione è già chiusa, così più notifiche dello stesso evento non si sovrappongono.
+     */
+    endSession(reason: SessionEndReason): void;
+    /**
+     * Chiude la sessione solo in questa tab, senza chiamare il server né notificare le altre tab.
+     */
+    private clearLocalSession;
     refreshToken(): Promise<boolean>;
+    private executeRefreshToken;
+    private postRefreshToken;
     static getJwtTokenRemainingLifetime(): number | null;
 }

package/src/lib/auth/index.d.ts

@@ -1 +1,3 @@
-export { FluxoUserProfile } from './auth-service';
+export { FluxoUserProfile, PasswordChangeReason, LoginAttemptResult } from './auth-service';
+export * from './session-end-reason';
+export * from './activity-tracker';

package/src/lib/auth/session-end-reason.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Motivo per cui la sessione è stata chiusa senza un logout esplicito dell'utente.
+ * `session_*` e `password_expired` arrivano dal server (error_description dell'header WWW-Authenticate).
+ */
+export declare const SessionEndReason: {
+    readonly Revoked: "session_revoked";
+    readonly Idle: "session_idle";
+    readonly PasswordExpired: "password_expired";
+    readonly ForcedLogout: "forced_logout";
+};
+export type SessionEndReason = typeof SessionEndReason[keyof typeof SessionEndReason];
+/**
+ * Estrae il motivo dall'header WWW-Authenticate di una risposta 401
+ * (es. `Bearer error="invalid_token", error_description="session_revoked"`).
+ * Restituisce null per i 401 che non riguardano la sessione.
+ */
+export declare function parseSessionEndReason(wwwAuthenticate: string | null | undefined): SessionEndReason | null;
+/**
+ * Motivo dell'ultima chiusura di sessione, conservato nella tab finché la pagina di login non lo mostra.
+ */
+export declare const LogoutReasonStore: {
+    set(reason: SessionEndReason): void;
+    consume(): SessionEndReason | null;
+};

package/src/lib/auth/tab-sync-auth-manager.d.ts

@@ -1,15 +1,17 @@
+import { SessionEndReason } from "./session-end-reason";
 export declare class TabSyncAuthManager {
     private static _instance;
     private broadcastChannel;
     private tabId;
     private refreshTokenAction;
-    private onErrorCallback;
+    private onLogoutCallback;
+    private refreshWaiters;
     private refreshTimeout;
     private heartbeatInterval;
     private lockCleanupInterval;
     private isDestroyed;
     private constructor();
-    static Init(refreshAction: () => Promise<boolean>, onErrorCallback: () => void): void;
+    static Init(refreshAction: () => Promise<boolean>, onLogoutCallback: (reason?: SessionEndReason) => void): void;
     static get Instance(): TabSyncAuthManager;
     private generateTabId;
     private initBroadcastChannel;
@@ -18,12 +20,25 @@ export declare class TabSyncAuthManager {
     private handleTabMessage;
     private handleTokenRefreshed;
     private handleTokenRefreshFailed;
+    private handleLogout;
+    /**
+     * Notifica alle altre tab che la sessione è stata chiusa. Va chiamato solo dalla tab che esegue il logout:
+     * senza, le altre tab continuerebbero a rinnovare il token con il refresh token condiviso.
+     */
+    notifyLogout(reason?: SessionEndReason): void;
     private syncWithStoredToken;
     startRefreshTimer(timeoutMs: number): Promise<void>;
     stopRefreshTimer(): void;
     start(timeoutMs: number): void;
     stop(): void;
-    private coordinatedRefresh;
+    /**
+     * Refresh coordinato tra le tab: lo esegue solo la tab che ottiene il lock. Le altre attendono l'esito
+     * invece di usare in parallelo lo stesso refresh token (il server lo ha già ruotato).
+     * Usato dal timer e all'avvio quando il token in localStorage è già scaduto.
+     */
+    refreshNow(): Promise<boolean>;
+    private waitForOtherTabRefresh;
+    private resolveRefreshWaiters;
     private acquireLock;
     private tryAcquireLockOnce;
     private releaseLock;

package/src/lib/http-client/http-client.d.ts

@@ -1,10 +1,16 @@
 import { AxiosInstance } from "axios";
 import { AuthenticationType } from "@fluxo-dev/state";
+import { SessionEndReason } from "../auth/session-end-reason";
 export declare class HttpClient {
     private static _instance;
+    private static _sessionEndedHandler;
     private _axiosInstance;
     get client(): AxiosInstance;
     constructor(authenticationType: AuthenticationType, baseUrl: string);
+    /**
+     * Registra chi chiude la sessione quando il server rifiuta una richiesta perché la sessione non è più valida.
+     */
+    static onSessionEnded(handler: (reason: SessionEndReason) => void): void;
     static Instance(): HttpClient;
     static Init(authenticationType: AuthenticationType, baseUrl: string, apiKeyOrAccessToken: string): void;
 }

package/src/lib/security/policy/index.d.ts

@@ -0,0 +1,2 @@
+export * from './security-policy';
+export * from './security-policy-service';

package/src/lib/security/policy/security-policy-service.d.ts

@@ -0,0 +1,28 @@
+import { SecurityPolicy, SecurityPolicySettings, UpdateSecurityPolicySettings } from "./security-policy";
+export declare class SecurityPolicyService {
+    private cachedPolicy;
+    private changeListeners;
+    /**
+     * Policy pubblica di sicurezza. Viene letta una sola volta e riusata da tutte le schermate:
+     * in caso di errore la cache si svuota e la richiesta successiva riprova.
+     */
+    getSecurityPolicy(): Promise<SecurityPolicy>;
+    /**
+     * Registra chi deve rileggere la policy quando cambia (es. il gestore dell'inattività).
+     * @returns la funzione per annullare la registrazione
+     */
+    onChanged(listener: () => void): () => void;
+    /**
+     * La policy (globale o le eccezioni dell'utente) è cambiata sul server: svuota la cache e avvisa i listener.
+     * Chiamato alla notifica `SecurityPolicyChanged` dell'hub di sessione.
+     */
+    notifyChanged(): void;
+    /**
+     * Policy completa (solo amministratori).
+     */
+    getSettings(): Promise<SecurityPolicySettings>;
+    /**
+     * Aggiorna la policy (solo amministratori). Le altre istanze del server la applicano entro 30 secondi.
+     */
+    updateSettings(settings: UpdateSecurityPolicySettings): Promise<SecurityPolicySettings>;
+}

package/src/lib/security/policy/security-policy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Policy di sicurezza pubblica esposta da `GET /identity/security-policy` (leggibile anche senza login).
+ */
+export interface SecurityPolicy {
+    password: PasswordPolicy;
+    session: SessionPolicy;
+    passwordExpiration: PasswordExpirationPolicy;
+}
+/**
+ * Criteri effettivi di ASP.NET Identity per le nuove password.
+ */
+export interface PasswordPolicy {
+    requiredLength: number;
+    requiredUniqueChars: number;
+    requireDigit: boolean;
+    requireLowercase: boolean;
+    requireUppercase: boolean;
+    requireNonAlphanumeric: boolean;
+    /** Password precedenti non riutilizzabili (0 se lo storico è disattivato): verificabile solo dal server */
+    historySize: number;
+}
+export interface SessionPolicy {
+    idleTimeoutEnabled: boolean;
+    idleTimeoutMinutes: number;
+    idleWarningSeconds: number;
+}
+export declare enum PasswordExpirationScope {
+    UsersWithout2FA = 1,
+    AllUsers = 2
+}
+export interface PasswordExpirationPolicy {
+    enabled: boolean;
+    days: number;
+    scope: PasswordExpirationScope;
+    warningDays: number;
+}
+/**
+ * Policy completa modificabile dagli amministratori (`/identity/security-policy/settings`).
+ */
+export interface UpdateSecurityPolicySettings {
+    idleTimeoutEnabled: boolean;
+    idleTimeoutMinutes: number;
+    idleWarningSeconds: number;
+    /** Applica il logout per inattività anche agli utenti esterni */
+    idleTimeoutIncludeExternalUsers: boolean;
+    passwordExpirationEnabled: boolean;
+    passwordExpirationDays: number;
+    passwordExpirationScope: PasswordExpirationScope;
+    passwordExpiryWarningDays: number;
+    /** Applica la scadenza della password anche agli utenti esterni */
+    passwordExpirationIncludeExternalUsers: boolean;
+    passwordHistoryEnabled: boolean;
+    passwordHistorySize: number;
+    lockoutEnabled: boolean;
+    maxFailedAccessAttempts: number;
+    lockoutMinutes: number;
+}
+export interface SecurityPolicySettings extends UpdateSecurityPolicySettings {
+    updatedAt: string | null;
+    updatedBy: string | null;
+}
+export interface PasswordRequirementCheck {
+    key: 'length' | 'lowercase' | 'uppercase' | 'digit' | 'nonAlphanumeric' | 'uniqueChars';
+    label: string;
+    satisfied: boolean;
+}
+export interface PasswordPolicyCheck {
+    isValid: boolean;
+    requirements: PasswordRequirementCheck[];
+}
+/**
+ * Verifica una password contro i criteri della policy, replicando le regole del server.
+ * Solo un aiuto per l'utente: il server resta l'unico a validare (anche con eventuali validator personalizzati).
+ */
+export declare function checkPasswordPolicy(password: string, policy: PasswordPolicy): PasswordPolicyCheck;

package/src/lib/security/security-facade.d.ts

@@ -2,6 +2,7 @@ import { UserService } from "./user/user-service";
 import { DomainRoleService } from "./domain-role";
 import { ApiKeyService } from "./apikey";
 import { PermissionService } from "./permission/permission.service";
+import { SecurityPolicyService } from "./policy/security-policy-service";
 import { CurrentUser } from "@fluxo-dev/api-client-base";
 export declare class SecurityFacade {
     private readonly _userService;
@@ -9,7 +10,9 @@ export declare class SecurityFacade {
     private readonly _apiKeyService;
     private readonly _domainRoleService;
     private readonly _permissionService;
+    private readonly _policyService;
     constructor();
+    get policy(): SecurityPolicyService;
     get user(): UserService;
     get currentUser(): CurrentUser;
     get permission(): PermissionService;

package/src/lib/security/user/new-user.d.ts

@@ -6,6 +6,8 @@ export interface NewUser {
     firstPassword?: string;
     accessType?: NewUserAccessType;
     sendEmailWithCredentials: boolean;
+    /** Obbliga l'utente a scegliere una nuova password al primo accesso */
+    requirePasswordChange?: boolean;
 }
 export interface NewUserUser {
     firstName: string;

package/src/lib/security/user/reset-password.d.ts

@@ -1,4 +1,6 @@
 export interface ResetPassword {
     userId: string;
     password?: string;
+    /** Obbliga l'utente a scegliere una nuova password al prossimo accesso */
+    requirePasswordChange?: boolean;
 }

package/src/lib/security/user/user-service.d.ts

@@ -18,6 +18,10 @@ export declare class UserService {
     forgotPassword(email: string): Promise<IdentityOperationResult>;
     forgotPasswordConfirm(forgotPassword: ForgotPassword): Promise<IdentityOperationResult>;
     disableUserLogin(userId: string): Promise<IdentityOperationResult>;
+    /**
+     * Revoca tutte le sessioni dell'utente (solo amministratori): dovrà rifare il login su ogni dispositivo.
+     */
+    revokeSessions(userId: string): Promise<IdentityOperationResult>;
     enableUserLogin(userId: string): Promise<IdentityOperationResult>;
     resetPassword(command: ResetPassword): Promise<IdentityOperationResult>;
     changeEmail(command: ChangeEmail): Promise<IdentityOperationResult>;

package/src/lib/security/user/user.d.ts

@@ -12,9 +12,24 @@ export interface User {
     lockoutEnd: string | null;
     lockoutEnabled: boolean;
     isLockedOut: boolean;
+    accessFailedCount: number;
+    lockoutReason: UserLockoutReason;
+    passwordChangedAt: string;
+    /** Deve scegliere una nuova password al prossimo accesso */
+    mustChangePassword: boolean;
+    /** Scadenza della password (UTC), null se per l'utente non scade */
+    passwordExpiresAt: string | null;
     twoFactorEnabled: boolean;
     securityPolicyInfo: SecurityPolicyInfo;
 }
+/**
+ * Motivo del blocco: tentativi di accesso falliti (temporaneo) o accesso disattivato dall'amministratore.
+ */
+export declare enum UserLockoutReason {
+    None = 0,
+    FailedAttempts = 1,
+    Disabled = 2
+}
 export interface UserData {
     FirstName: string;
     LastName: string;
@@ -24,4 +39,8 @@ export interface SecurityPolicyInfo {
     canHandle2FA: boolean;
     canHandleAccessTokens: boolean;
     canDisable2FA: boolean;
+    /** Escluso dal logout per inattività (es. postazioni kiosk) */
+    idleTimeoutExempt: boolean;
+    /** Esclusa dalla scadenza periodica della password (es. account tecnici) */
+    passwordNeverExpires: boolean;
 }