@arsedizioni/ars-utils 22.5.13 → 22.5.15

package/fesm2022/arsedizioni-ars-utils-evolution.common.mjs

@@ -1,8 +1,8 @@
-import { HttpErrorResponse, HttpClient, HttpHeaders } from '@angular/common/http';
+import { HttpResponse, HttpClient } from '@angular/common/http';
 import * as i0 from '@angular/core';
 import { inject, signal, Service, DestroyRef } from '@angular/core';
 import { BroadcastService, SystemUtils } from '@arsedizioni/ars-utils/core';
-import { catchError, throwError, EMPTY, of } from 'rxjs';
+import { tap, catchError, throwError, EMPTY, of } from 'rxjs';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { catchError as catchError$1, map, finalize } from 'rxjs/operators';
 
@@ -20,6 +20,15 @@ const EvolutionMessages = {
     LOGOUT: '§evo-logout'
 };
 
+/**
+ * The `sessionStorage` key naming which account a tab is working as; its value travels on every
+ * request as `X-Evo-Account`.
+ *
+ * It lives here, and not on `CoreService`, so the auth interceptor can read it without importing a
+ * service: the interceptor is a factory precisely so that registering it does not pull the Evolution
+ * service graph into the eager bundle.
+ */
+const EVOLUTION_ACTIVE_ACCOUNT_KEY = 'evolution_account';
 var EvolutionServiceFlags;
 (function (EvolutionServiceFlags) {
     EvolutionServiceFlags[EvolutionServiceFlags["None"] = 0] = "None";
@@ -483,14 +492,81 @@ var ERPPlace;
 class EvolutionComplianceContextInfo {
 }
 
-/** Minimum milliseconds between consecutive error broadcasts (debounce guard). */
+/** Minimum milliseconds between consecutive generic error broadcasts (debounce guard). */
 const ERROR_DEBOUNCE_MS = 5000;
+/**
+ * Returns whether the URL is an authentication endpoint, where a 401 is a normal outcome -- wrong
+ * credentials, a rejected code, a refused passkey -- rather than an expired or invalid session.
+ *
+ * They are called by a visitor who has no session by definition, so answering "la sessione non è
+ * più valida" would send them back to the page they are already standing on and hide the real
+ * reason they were refused.
+ *
+ * The list covers the whole Evolution sign-in surface, including the ways in that this library does
+ * not itself offer: a host application registers one interceptor for every call it makes to the
+ * API, its own passkey and provider flows included.
+ * @param url - The request URL.
+ * @returns True when the URL is a login / confirm / otp / oauth / passkey endpoint.
+ */
+function isAuthEndpoint(url) {
+    return url.includes('/session/login')
+        || url.includes('/session/confirm')
+        || url.includes('/session/otp')
+        || url.includes('/session/oauth')
+        || url.includes('/passkeys/request-options')
+        || url.includes('/passkeys/login');
+}
+/**
+ * Resolves the user-facing message for a failed request.
+ * @param error - The raw HTTP error object.
+ * @param errorStatus - The numeric HTTP status code.
+ * @returns A localised message, ready to be rendered as HTML.
+ */
+function resolveErrorMessage(error, errorStatus) {
+    const message = error?.error?.message ?? error?.message;
+    switch (errorStatus) {
+        case 0:
+            return "In questo momento Evolution non è disponibile. Riprova tra qualche minuto.";
+        case 401:
+            // A 401 that reaches here comes from a sign-in attempt; anything else was classified as a
+            // dead session before this function was called.
+            return message ?? "Credenziali non valide o accesso non abilitato.";
+        case 403:
+            return "Non hai i permessi necessari per eseguire l'operazione richiesta.";
+        case 429:
+            return message ?? "Troppe richieste consecutive. Aspetta qualche secondo.";
+        default:
+            return (message ?? "Impossibile eseguire l'operazione richiesta.")
+                .replaceAll('\r\n', '</p><p>');
+    }
+}
 /**
  * Builds the Evolution auth HTTP interceptor.
  *
- * Takes its two inputs — the Evolution base URI and the service flags — directly
- * as arguments (captured in the closure), so it never injects EvolutionService:
- * registering it does not pull the full Evolution service into the eager bundle.
+ * Attaches the credentials, the service-worker bypass and the active-account header to every
+ * request aimed at the Evolution API, and turns HTTP failures into broadcast messages -- no UI
+ * dependency here.
+ *
+ * Takes the Evolution base URI and the service flags directly as arguments, captured in the
+ * closure, so it never injects `EvolutionService`: registering it does not pull the whole Evolution
+ * service into the eager bundle. The debounce and the expiry latch live in that same closure, so
+ * two applications registering two interceptors never share them.
+ *
+ * ## What the statuses mean
+ *
+ * Aligned with the Evolution API on 2026-08-25. The meaning of the status codes changed with it:
+ * failures used to arrive as `200 OK` with `success: false`, and a dead session had to be guessed
+ * from a 405, a 410 or any 5xx. Now the status is the truth -- a 401 on an already-authenticated
+ * request means the session is gone, a 403 means the permission is missing, a 5xx means the server
+ * broke, and those are three different things that used to be one. `invalidateSession` is
+ * therefore now, and only, a 401 outside the authentication endpoints.
+ *
+ * `EvolutionServiceFlags.NotifySystemErrors` still governs one narrow case, and only that one: a
+ * 5xx, i.e. a failure of the server rather than of the request. Without the flag it is swallowed,
+ * as it always was in this library.
+ *
+ * Errors are re-thrown rather than swallowed: call sites rely on their `error` callback firing, and
+ * on `finalize` clearing a busy dialog.
  *
  * Register it with `withInterceptors`:
  * @example
@@ -504,48 +580,31 @@ const ERROR_DEBOUNCE_MS = 5000;
  * @returns An `HttpInterceptorFn` ready to register.
  */
 function evolutionAuthInterceptor(serviceUri, flags = EvolutionServiceFlags.None) {
-    // Debounce state, persisted across requests via the factory closure.
+    /** Timestamp of the last generic error shown, used to debounce a burst of failures into one. */
     let lastErrorTime = -1;
     /**
-     * Broadcasts a user-friendly message for an Evolution HTTP error, debounced.
-     * @param error            - The raw error value thrown by the HTTP layer.
+     * Whether the session-expiry notification has already been sent. Prevents a storm of dialogs when
+     * several in-flight requests fail at once; re-armed on the next successful response.
+     */
+    let sessionExpiredNotified = false;
+    /**
+     * Broadcasts a generic, user-facing error for an Evolution HTTP failure, debounced.
+     * @param error - The raw error value thrown by the HTTP layer.
+     * @param errorStatus - The numeric HTTP status code.
      * @param broadcastService - The broadcast service for the current request.
      * @returns void
      */
-    function handleError(error, broadcastService) {
-        if (!(error instanceof HttpErrorResponse))
-            return;
-        // Only reject errors that explicitly belong to a different service; a missing
-        // url (network failure on an Evolution request) is allowed through.
-        if (error.url && !error.url.startsWith(serviceUri))
-            return;
-        const errorStatus = error.status;
-        const shouldNotify = errorStatus === 0 ||
-            (errorStatus > 0 && errorStatus < 500) ||
-            (flags & EvolutionServiceFlags.NotifySystemErrors) > 0;
-        if (!shouldNotify)
+    function notifyError(error, errorStatus, broadcastService) {
+        // A broken server is the one case the flag still governs.
+        if (errorStatus >= 500 && (flags & EvolutionServiceFlags.NotifySystemErrors) === 0)
             return;
         const now = Date.now();
         if (now - lastErrorTime <= ERROR_DEBOUNCE_MS)
             return;
         lastErrorTime = now;
-        let message;
-        switch (errorStatus) {
-            case 0:
-                message = "In questo momento Evolution non è disponibile. Riprova tra qualche minuto.";
-                break;
-            case 403:
-                message = "Non hai i permessi necessari per eseguire l'operazione richiesta.";
-                break;
-            default:
-                message = (error.error?.['message'] ??
-                    error.message ??
-                    "Impossibile eseguire l'operazione richiesta.").replaceAll('\r\n', '</p><p>');
-                break;
-        }
         broadcastService.sendMessage(EvolutionMessages.ERROR, {
-            invalidateSession: errorStatus === 405 || errorStatus === 410,
-            message,
+            invalidateSession: false,
+            message: resolveErrorMessage(error, errorStatus),
             title: "Errore in Evolution",
             errorStatus,
             service: serviceUri
@@ -558,14 +617,47 @@ function evolutionAuthInterceptor(serviceUri, flags = EvolutionServiceFlags.None
         }
         const broadcastService = inject(BroadcastService);
         const authenticatedRequest = request.clone({
+            // `withCredentials` is what carries the session: an HttpOnly cookie the application cannot
+            // read, cannot forge and cannot forget to send.
             withCredentials: true,
             setHeaders: {
                 'ngsw-bypass': 'ngsw-bypass',
-                'X-Client-Id': sessionStorage.getItem('evolution_client_id') ?? ''
+                // Which of the accounts inside the one session cookie this tab is working as. It replaces
+                // the per-tab random `X-Client-Id`, whose only job was to give each tab a cookie of its
+                // own -- one per tab ever opened, all of them sent on every request, until the header
+                // outgrew what the server accepts. Empty on a tab that has not signed in yet: the API then
+                // serves the active account.
+                'X-Evo-Account': sessionStorage.getItem(EVOLUTION_ACTIVE_ACCOUNT_KEY) ?? ''
             }
         });
-        return next(authenticatedRequest).pipe(catchError((error) => {
-            handleError(error, broadcastService);
+        return next(authenticatedRequest).pipe(tap(event => {
+            // A response means the session is valid again: re-arm the expiry notifier.
+            if (event instanceof HttpResponse) {
+                sessionExpiredNotified = false;
+            }
+        }), catchError((error) => {
+            // Which request this was is read from the request, not from `error.url`: a failure with no
+            // response -- the browser refusing the connection while the API restarts -- carries no URL
+            // at all. Everything that gets here is an Evolution request anyway: the others returned
+            // before the pipe was built.
+            const errorStatus = parseInt(error?.status ?? '0');
+            if (errorStatus === 401 && !isAuthEndpoint(authenticatedRequest.url)) {
+                // Expired or invalidated session on an authenticated request. Notified once: several
+                // in-flight requests failing together is how a single expiry becomes a wall of dialogs.
+                if (!sessionExpiredNotified) {
+                    sessionExpiredNotified = true;
+                    broadcastService.sendMessage(EvolutionMessages.ERROR, {
+                        invalidateSession: true,
+                        message: "La sessione di lavoro non è più valida.",
+                        title: "Errore in Evolution",
+                        errorStatus,
+                        service: serviceUri
+                    });
+                }
+            }
+            else {
+                notifyError(error, errorStatus, broadcastService);
+            }
             return throwError(() => error);
         }));
     };
@@ -587,9 +679,16 @@ class CoreService {
     constructor() {
         this.broadcastService = inject(BroadcastService);
         this._flags = EvolutionServiceFlags.None;
-        this._loggedIn = signal(false, /* @ts-ignore */
+        /**
+         * Seeded from the stored context, which means "this browser signed in at some point" and nothing
+         * more: the auth cookie is HttpOnly and may have expired while the stored context lived on.
+         * `LoginService.initialize` turns the hint into an answer by asking `/session/me`, and the hint
+         * is what keeps a visitor who never signed in from calling a route that would answer 401 and
+         * raise a dead-session error over the sign-in page.
+         */
+        this._loggedIn = signal(localStorage.getItem('evolution_context') !== null, /* @ts-ignore */
         ...(ngDevMode ? [{ debugName: "_loggedIn" }] : /* istanbul ignore next */ []));
-        /** `true` when the user has an active (non-temporary) session. */
+        /** `true` when this browser has a session the API has accepted. */
         this.loggedIn = this._loggedIn.asReadonly();
         /** `true` while a login request is in flight. */
         this.loggingIn = signal(false, /* @ts-ignore */
@@ -642,6 +741,11 @@ class CoreService {
         }
         return this._loginInfo;
     }
+    /**
+     * Gets the signed-in account.
+     * @returns The current {@link EvolutionUserInfo}, or `undefined` when there is no session.
+     */
+    get user() { return this.loginInfo?.context; }
     /**
      * Sets the logged-in state.
      * @param value - The new logged-in value.
@@ -650,19 +754,26 @@ class CoreService {
     setLoggedIn(value) {
         this._loggedIn.set(value);
     }
+    /** The `sessionStorage` key naming which account this tab is working as. */
+    static { this.activeAccountKey = EVOLUTION_ACTIVE_ACCOUNT_KEY; }
     /**
-     * Records the OAuth provider / remember flag on the login info, creating the
-     * container if needed.
-     * @param oauth - The OAuth provider type, if any.
-     * @param remember - Whether the session should persist across restarts.
+     * Records which account this tab is working as, so the interceptor can name it on every request.
+     *
+     * `sessionStorage` and not `localStorage`: the choice belongs to the tab. One cookie holds every
+     * account this browser has open, and two tabs may sit on two different licences while reading
+     * that same cookie -- which is what replaced the per-tab `X-Client-Id`, a random UUID that gave
+     * every tab ever opened a session cookie of its own until the header outgrew what the server
+     * accepts.
+     * @param userId - The account to work as, or `undefined` to stop naming one.
      * @returns void
      */
-    setAuthMeta(oauth, remember) {
-        if (!this._loginInfo) {
-            this._loginInfo = { context: undefined };
+    setActiveAccount(userId) {
+        if (userId && userId > 0) {
+            sessionStorage.setItem(CoreService.activeAccountKey, String(userId));
+        }
+        else {
+            sessionStorage.removeItem(CoreService.activeAccountKey);
         }
-        this._loginInfo.oauth = oauth;
-        this._loginInfo.remember = remember;
     }
     /**
      * Persists the current login info to `localStorage`.
@@ -694,17 +805,33 @@ class CoreService {
         this.broadcastService.sendMessage(EvolutionMessages.LOGOUT_COMPLETED);
     }
     /**
-     * Removes Evolution session data from `sessionStorage` and calls {@link reset}.
-     * @param clearOAuthToken - When true, also removes the stored OAuth2 access token.
+     * Clears every trace of the session on this device -- the stored context, the account this tab
+     * was working as and the leftovers of the token era -- and then calls {@link reset}. It asks the
+     * API nothing: use `LoginService.logout` for that.
+     *
+     * It takes no argument any more. `clearOAuthToken` decided whether to drop
+     * `evolution_oauth_token`, a provider access token this library no longer obtains, stores or
+     * sends: the whole exchange happens on the backend.
      * @returns void
      */
-    clear(clearOAuthToken = false) {
+    clear() {
+        // The stored context goes with the session it describes. It used to be removed by `logout()`
+        // alone, so every other way of losing a session -- an expiry, a rejected restore -- left it
+        // behind for the next bootstrap to trust.
+        localStorage.removeItem('evolution_context');
+        // The account this tab was working as. Left behind, the next request would name an account no
+        // longer in the cookie: harmless, because the API falls back to the active one, but it would
+        // also survive a sign-in as somebody else until the next `completeLogin` overwrote it.
+        sessionStorage.removeItem(CoreService.activeAccountKey);
+        // Leftovers of the token era, when the session travelled in session storage instead of an
+        // HttpOnly cookie, and of the per-tab cookie era. Nothing writes them any more; they are
+        // removed so a browser upgrading from the previous version does not keep them for good.
         sessionStorage.removeItem('evolution_auth');
         sessionStorage.removeItem('evolution_refresh');
         sessionStorage.removeItem('evolution_oauth');
-        if (clearOAuthToken) {
-            sessionStorage.removeItem('evolution_oauth_token');
-        }
+        sessionStorage.removeItem('evolution_auth_oauth');
+        sessionStorage.removeItem('evolution_oauth_token');
+        sessionStorage.removeItem('evolution_client_id');
         this.reset();
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: CoreService, deps: [], target: i0.ɵɵFactoryTarget.Service }); }
@@ -715,11 +842,35 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
         }] });
 
 /**
- * Authentication service for the Evolution module: login / logout / MFA,
- * session bootstrap, connectivity ping and the broadcast handler.
- * All session state lives in the private {@link CoreService}; this service
- * orchestrates the HTTP flows and re-publishes the parts of core that
- * consumers need.
+ * Authentication for the Evolution back end: password login, e-mailed code confirmation, account
+ * switch, logout and session restore. All session state lives in the private {@link CoreService};
+ * this service orchestrates the HTTP flows and re-publishes the parts of core that consumers need.
+ *
+ * Aligned with the Evolution API on 2026-08-25. Everything goes through `/session/*` and an
+ * HttpOnly cookie now: there is no bearer token, no `remember` credential the API can replay, and
+ * no provider token acquired by the caller -- the external-provider flow is a full-page redirect
+ * handled server-side, and all that reaches this service is the `/session/me` call on the way back.
+ *
+ * ## What this service no longer offers, and why
+ *
+ * - **`autoLogin`.** It was `login(undefined, undefined, true)`: a credential-less sign-in that
+ *   worked only because the API could decrypt a stored password from an `evolution_remember`
+ *   cookie. `POST /session/login` takes a user and a password and nothing else.
+ * - **`autoLogout`.** It wrapped {@link logout} in toasts and a callback, and ran the callback
+ *   from `complete` -- that is, before the request it was waiting for had said anything. A host
+ *   that wants a callback subscribes: `logout().subscribe(() => …)`.
+ * - **re-login on `LOGIN_CHANGED`.** The handler used to answer that message with a silent
+ *   `autoLogin`, which is the same replay by another name. The message is still broadcast by hosts
+ *   that link and unlink Evolution, and it is theirs to act on; this library no longer signs
+ *   anybody in without being asked.
+ * - **the OAuth `Authorization` header, and the per-tab `X-Client-Id`.** The first is server-side
+ *   now; the second was a random UUID that gave every tab a session cookie of its own. A tab says
+ *   which of the accounts in the one cookie it is working as with `X-Evo-Account`, written by
+ *   {@link CoreService.setActiveAccount}.
+ *
+ * This is a deliberately reduced subset of what the Evolution application itself does: passkeys and
+ * the provider redirect are not here. A library whose job is to let another application talk to
+ * Evolution signs in with a password; an application that offers the other ways in owns them.
  */
 class LoginService {
     constructor() {
@@ -745,9 +896,14 @@ class LoginService {
      * @returns The current {@link EvolutionLoginInfo}, or undefined.
      */
     get loginInfo() { return this.core.loginInfo; }
-    /** `true` when the user has an active (non-temporary) session. */
+    /**
+     * Gets the signed-in account with its licence context.
+     * @returns The current {@link EvolutionUserInfo}, or undefined when there is no session.
+     */
+    get user() { return this.core.user; }
+    /** `true` when this browser has a session the API has accepted. */
     get loggedIn() { return this.core.loggedIn; }
-    /** `true` while a login request is in flight. */
+    /** `true` while an authentication is in flight. */
     get loggingIn() { return this.core.loggingIn; }
     // ── Re-published core operations ────────────────────────────────────────────
     /**
@@ -767,26 +923,26 @@ class LoginService {
      */
     reset() { this.core.reset(); }
     /**
-     * Removes Evolution session data and resets the state (delegates to core).
-     * @param clearOAuthToken - When true, also removes the stored OAuth2 access token.
+     * Clears every trace of the session on this device without asking the API anything
+     * (delegates to core). Use {@link logout} for a real sign-out.
      * @returns void
      */
-    clear(clearOAuthToken = false) { this.core.clear(clearOAuthToken); }
+    clear() { this.core.clear(); }
     // ── Lifecycle ───────────────────────────────────────────────────────────────
     /**
-     * Initialises the service with the back-end URI and optional feature flags.
-     * Must be called once during application bootstrap before any other method.
+     * Initialises the service with the back-end URI and optional feature flags, and revalidates a
+     * session that survived a page refresh instead of assuming it is still there.
+     *
+     * Must be called once during application bootstrap, before any other method. What it used to do
+     * on a refresh was announce `LOGIN_COMPLETED` on the strength of a value in local storage; the
+     * auth cookie is HttpOnly and may have expired while that value lived on, so the claim was never
+     * verified and the consumer met the inevitable 401 as "your session just expired" rather than as
+     * a bootstrap that never got off the ground.
      * @param serviceUri - Base URL of the Evolution service.
      * @param flags - Bitmask of `EvolutionServiceFlags` (default: `None`).
      * @returns void
      */
     initialize(serviceUri, flags = EvolutionServiceFlags.None) {
-        // Create a unique per-tab client ID if not already set
-        if (!sessionStorage.getItem('evolution_client_id')) {
-            sessionStorage.setItem('evolution_client_id', (flags & EvolutionServiceFlags.Embedded) > 0
-                ? 'embedded'
-                : SystemUtils.generateUUID());
-        }
         this.core.setServiceUri(serviceUri);
         this.core.setFlags(flags);
         // Subscribe to broadcast messages (only once)
@@ -799,10 +955,11 @@ class LoginService {
                 this.handleBroadcastMessage(message);
             });
         }
-        // If a session is already active (e.g. after an F5 page refresh), notify consumers
+        // A stored context means this browser signed in at some point, never that the session is still
+        // alive: the API is the only one that knows, and it is asked here.
         if (this.core.loggedIn()) {
-            this.core.loggingIn.set(false);
-            this.broadcastService.sendMessage(EvolutionMessages.LOGIN_COMPLETED);
+            this.core.loggingIn.set(true);
+            this.restoreSession();
         }
     }
     /**
@@ -811,47 +968,26 @@ class LoginService {
      * @returns void
      */
     handleBroadcastMessage(message) {
-        if (message.id === EvolutionMessages.LOGIN_CHANGED) {
-            const data = message.data;
-            this.login(undefined, undefined, true, data?.['oauth'], data?.['oauthAccessToken']).subscribe({
-                next: r => {
-                    if (!r.success) {
-                        if ((this.core.flags & EvolutionServiceFlags.DisplayConnectionStateMessages) > 0) {
-                            this.broadcastService.sendMessage(EvolutionMessages.ERROR, { message: "Le credenziali di accesso sono cambiate o non sono più valide. Esegui un nuovo accesso." });
-                        }
-                        this.broadcastService.sendMessage(EvolutionMessages.LOGIN_FAILED);
-                    }
-                    else {
-                        if ((this.core.flags & EvolutionServiceFlags.DisplayConnectionStateMessages) > 0) {
-                            this.broadcastService.sendMessage(EvolutionMessages.SUCCESS_TOAST, { message: 'Connesso a Evolution', icon: 'power', duration: 1500 });
-                        }
-                    }
-                },
-                error: () => { console.error('Evolution non disponibile.'); }
-            });
+        if (message.id !== EvolutionMessages.LOGOUT)
+            return;
+        if (!this.core.loggedIn()) {
+            // No session to close server-side, but the device must still be left clean.
+            this.core.clear();
+            return;
         }
-        else if (message.id === EvolutionMessages.LOGOUT) {
-            if (this.core.loggedIn()) {
-                this.logout().subscribe(r => {
-                    if (!r.success) {
-                        if (r.message) {
-                            this.broadcastService.sendMessage(EvolutionMessages.ERROR, { message: "<p>" + r.message + "</p><br><br><hr><p class='small'><i>Per eliminare la configurazione di Evolution accedere a:<br><b>menu > personalizza > collegamenti</b></i></p>" });
-                        }
-                    }
-                    else {
-                        if ((this.core.flags & EvolutionServiceFlags.DisplayConnectionStateMessages) > 0) {
-                            this.broadcastService.sendMessage(EvolutionMessages.SUCCESS_TOAST, { message: 'Disconnesso da Evolution', icon: 'power_off', duration: 1500 });
-                        }
-                    }
-                });
+        this.logout().subscribe(r => {
+            if (!r.success) {
+                if (r.message) {
+                    this.broadcastService.sendMessage(EvolutionMessages.ERROR, { message: "<p>" + r.message + "</p><br><br><hr><p class='small'><i>Per eliminare la configurazione di Evolution accedere a:<br><b>menu > personalizza > collegamenti</b></i></p>" });
+                }
             }
-            else {
-                this.core.clear();
+            else if ((this.core.flags & EvolutionServiceFlags.DisplayConnectionStateMessages) > 0) {
+                this.broadcastService.sendMessage(EvolutionMessages.SUCCESS_TOAST, { message: 'Disconnesso da Evolution', icon: 'power_off', duration: 1500 });
             }
-        }
+        });
     }
     /**
-     * Sends a one-shot ping to the back end to verify connectivity.
+     * Sends a one-shot ping to the back end to verify connectivity. Errors are swallowed.
      * @returns void
      */
     ping() {
@@ -860,78 +996,30 @@ class LoginService {
             .pipe(catchError$1(() => EMPTY))
             .subscribe();
     }
+    // ── Session ─────────────────────────────────────────────────────────────────
     /**
-     * Performs an automatic login using the credentials already stored in the session.
-     * @param onSuccess - Optional callback invoked after a successful login.
-     * @returns `true` (always) — the result is handled via the subscription callbacks.
-     */
-    autoLogin(onSuccess) {
-        this.login(undefined, undefined, true)
-            .subscribe({
-            next: r => {
-                if (!r.success) {
-                    this.broadcastService.sendMessage(EvolutionMessages.ERROR, { message: r.message });
-                }
-                else {
-                    if (!r.value?.requiresMfa) {
-                        this.broadcastService.sendMessage(EvolutionMessages.SUCCESS_TOAST, { message: 'Connesso ad Evolution', icon: 'power', duration: 1500 });
-                    }
-                    onSuccess?.();
-                }
-            },
-            error: () => { this.broadcastService.sendMessage(EvolutionMessages.ERROR, { message: "Evolution non disponibile." }); }
-        });
-        return true;
-    }
-    /**
-     * Performs an automatic logout, notifying the user when the session ends.
-     * @param onSuccess - Optional callback invoked after the logout completes.
-     * @returns void
-     */
-    autoLogout(onSuccess) {
-        this.logout().subscribe({
-            next: r => {
-                if (!r.success) {
-                    if (r.message) {
-                        this.broadcastService.sendMessage(EvolutionMessages.ERROR, { message: r.message });
-                    }
-                    this.broadcastService.sendMessage(EvolutionMessages.LOGIN_CHANGED);
-                }
-                else {
-                    this.broadcastService.sendMessage(EvolutionMessages.SUCCESS_TOAST, { message: 'Disconnesso da Evolution', icon: 'power_off', duration: 1500 });
-                }
-            },
-            error: () => { },
-            complete: () => {
-                onSuccess?.();
-            }
-        });
-    }
-    /**
-     * Authenticates the user against the Evolution back end (credential or OAuth2).
-     * @param email - User e-mail (credential login only; omit for OAuth2).
-     * @param password - User password (credential login only; omit for OAuth2).
-     * @param remember - Whether to persist the session across browser restarts.
-     * @param oauth - OAuth2 provider type, when using federated login.
-     * @param oauthAccessToken - Bearer token from the OAuth2 provider.
+     * Authenticates the user with an e-mail address and a password, the only credentials
+     * `POST /session/login` accepts.
+     *
+     * On success the session cookie is issued and the context stored, unless the API answers
+     * `requiresMfa`: the device is not a trusted one, a six-digit code has been e-mailed and nothing
+     * about the account is disclosed until {@link confirmIdentity} redeems it.
+     *
+     * A failure is no longer a `200 OK` carrying `success: false`. Wrong credentials come back as a
+     * real 4xx with the message in the envelope, so the `next` branch of the caller is never reached.
+     * @param email - The user's e-mail address.
+     * @param password - The user's password.
      * @returns An observable that emits the `ApiResult<EvolutionLoginResult>`.
      */
-    login(email, password, remember, oauth, oauthAccessToken = sessionStorage.getItem('evolution_oauth_token') ?? undefined) {
+    login(email, password) {
+        // Kept for the confirmation step, which has to name the account the code was issued to.
+        this.pendingLoginEmail = email;
         return this.httpClient
-            .post(this.core.serviceUri + '/login2', {
-            user: oauth ? null : email,
-            password: oauth ? null : password,
-            remember,
-            oauth
-        }, {
-            headers: oauth && oauthAccessToken
-                ? new HttpHeaders().set('Authorization', oauthAccessToken)
-                : new HttpHeaders()
-        })
+            .post(this.core.serviceUri + '/session/login', { user: email ?? '', password: password ?? '' })
             .pipe(catchError$1(err => throwError(() => err)), map((r) => {
             if (r.success) {
-                this.core.setAuthMeta(oauth, remember);
-                if (!oauth && r.value?.requiresMfa) {
+                if (r.value?.requiresMfa) {
+                    // Notify the login is pending an e-mailed code.
                     this.broadcastService.sendMessage(EvolutionMessages.LOGIN_PENDING, {});
                 }
                 else {
@@ -942,24 +1030,20 @@ class LoginService {
         }));
     }
     /**
-     * Finalises a successful login by updating the stored context and notifying consumers.
-     * @param result - The login result payload from the server.
-     * @returns void
-     */
-    completeLogin(result) {
-        this.core.updateContext(result);
-        this.core.setLoggedIn(!result.context?.isTemporary);
-        this.core.loggingIn.set(false);
-        this.broadcastService.sendMessage(EvolutionMessages.LOGIN_COMPLETED);
-    }
-    /**
-     * Confirms a multi-factor authentication challenge and completes the login.
-     * @param code - The one-time MFA code entered by the user.
+     * Confirms a pending e-mailed code challenge, which establishes the session and marks this device
+     * as trusted: the next sign-in from it will not ask for a code again.
+     *
+     * The address travels with the code, in the body. The API stores each code under the account it
+     * was issued to, so naming the account is part of redeeming it; and a code in the body is a code
+     * that stays out of the URL, where `POST /login/confirm/{code}` left it for the access logs and
+     * the browser history to keep.
+     * @param code - The one-time confirmation code provided to the user.
+     * @param email - The address the code was sent to; defaults to the one the pending login started with.
      * @returns An observable that emits the `ApiResult<EvolutionLoginResult>`.
      */
-    confirmIdentity(code) {
+    confirmIdentity(code, email) {
         return this.httpClient
-            .post(this.core.serviceUri + '/login/confirm/' + code, {})
+            .post(this.core.serviceUri + '/session/confirm', { email: email ?? this.pendingLoginEmail, code: code })
             .pipe(catchError$1(err => throwError(() => err)), map((r) => {
             if (r.success) {
                 this.completeLogin(r.value);
@@ -968,33 +1052,119 @@ class LoginService {
         }));
     }
     /**
-     * Logs the current user out of the back end and clears local session data.
-     * @param forget - When `true`, instructs the server to discard all stored credentials.
-     * @returns An observable that emits `ApiResult<unknown>`.
+     * Reads the current session from the server, which resolves it from the auth cookie's claims.
+     * Used to restore the state after a page refresh instead of trusting what local storage holds.
+     *
+     * The route answers with the same `EvolutionLoginResult` a login answers with, built by the same
+     * `ResolveSignInContextAsync`, so a restored session and a fresh one are identical by
+     * construction.
+     * @returns An observable that emits the `ApiResult<EvolutionLoginResult>`.
      */
-    logout(forget = false) {
+    me() {
         return this.httpClient
-            .post(this.core.serviceUri + '/logout/?forget=' + forget, {})
-            .pipe(finalize(() => {
-            this.core.clear();
-            localStorage.removeItem('evolution_context');
-        }), catchError$1(() => of({ success: false, value: undefined, message: undefined })));
+            .get(this.core.serviceUri + '/session/me')
+            .pipe(map((r) => {
+            if (r?.success) {
+                // No LOGIN_COMPLETED from here: {@link restoreSession} announces it, so a consumer
+                // hears it once whether the session was opened or recovered.
+                this.completeLogin(r.value, false);
+            }
+            return r;
+        }));
+    }
+    /**
+     * Asks `/session/me` whether the restored session is still alive, and announces the login when it
+     * is.
+     *
+     * Nothing is cleared on failure, and that is deliberate: a failure here is not proof of a dead
+     * session -- the API may be unreachable, the proxy may have answered 502, the device may be
+     * offline -- and clearing on any of those would sign the user out with a perfectly valid cookie.
+     * A genuine 401 is a different matter and the interceptor has already reported it.
+     * @returns void
+     */
+    restoreSession() {
+        this.me()
+            .pipe(finalize(() => this.core.loggingIn.set(false)))
+            .subscribe({
+            next: r => {
+                if (r?.success) {
+                    this.broadcastService.sendMessage(EvolutionMessages.LOGIN_COMPLETED);
+                }
+            },
+            // Consumed so the rethrown error is not reported a second time as an unhandled one.
+            error: () => { }
+        });
     }
     /**
-     * Switches the active session to a different user account while retaining credentials.
+     * Switches this tab to another account of the same person -- same address, same stored password
+     * -- without re-entering credentials.
+     *
+     * The account being left stays open: a switch used to close its session, because each account had
+     * a cookie of its own, and they now share one cookie holding several. What changes here is only
+     * which account THIS tab names on its requests, which {@link completeLogin} records.
      * @param id - The user ID to switch to.
      * @returns An observable that emits the `ApiResult<EvolutionLoginResult>`.
      */
     loginSwitch(id) {
         return this.httpClient
-            .post(this.core.serviceUri + '/login/switch', { userId: id })
+            .post(this.core.serviceUri + '/session/switch', { userId: id })
             .pipe(catchError$1(err => throwError(() => err)), map((r) => {
             if (r.success) {
-                this.completeLogin(r.value);
+                this.completeLogin(r.value, false);
             }
             return r;
         }));
     }
+    /**
+     * Signs out: closes this browser's session on the API and clears the local state whatever the
+     * answer, since there is nothing useful to do with a logout that failed.
+     *
+     * `forget` no longer means "drop the stored credentials" -- there are none to drop. It means
+     * "stop trusting this device", that is clear the MFA cookie, so that the next sign-in from here
+     * is challenged with an e-mailed code again. It also closes one session and not all of them: an
+     * account may hold one per front end, and signing out of this browser must not sign the person
+     * out of their phone.
+     * @param forget - When `true`, the device stops being a trusted one. Defaults to `false`.
+     * @returns An observable that emits `ApiResult<unknown>`.
+     */
+    logout(forget = false) {
+        return this.httpClient
+            .post(this.core.serviceUri + '/session/logout?forget=' + forget, {})
+            .pipe(finalize(() => this.core.clear()), 
+        // A logout that failed is still a logout as far as this device is concerned: the local
+        // state has already been cleared by `finalize`, and there is nothing useful a caller could
+        // do with the failure. `message` is empty rather than absent because `ApiResponse` declares
+        // it as a string.
+        catchError$1(() => of({ success: false, value: undefined, message: '' })));
+    }
+    /**
+     * Finalises a login, a code confirmation, an account switch or a session restore: stores the
+     * context, raises the logged-in signal, records which account this tab is working as and
+     * optionally announces `LOGIN_COMPLETED`.
+     *
+     * `loggedIn` is raised unconditionally. It used to be `!result.context?.isTemporary`, and
+     * `isTemporary` was always false -- it is `[NotMapped]` on the API and never filled -- so the
+     * condition never did anything. An expired password is reported by `requiresPasswordChange` and
+     * does not mean there is no session: the cookie has been issued, and it is what the password
+     * change itself travels on.
+     *
+     * `loggingIn` is deliberately left alone. Whoever raised it lowers it -- {@link restoreSession}
+     * for a refresh, the host application for its own sign-in flow -- because lowering it here would
+     * drop the host's splash the instant the response arrived, before anything was on screen.
+     * @param result - The login result payload from the server.
+     * @param notify - Whether to broadcast `LOGIN_COMPLETED`. Defaults to `true`.
+     * @returns void
+     */
+    completeLogin(result, notify = true) {
+        this.core.updateContext(result);
+        this.core.setLoggedIn(true);
+        // Which account THIS TAB is working as. Per tab on purpose: two tabs may sit on two different
+        // licences, and they share the one cookie that holds both.
+        this.core.setActiveAccount(result?.context?.userId);
+        if (notify) {
+            this.broadcastService.sendMessage(EvolutionMessages.LOGIN_COMPLETED);
+        }
+    }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: LoginService, deps: [], target: i0.ɵɵFactoryTarget.Service }); }
     static { this.ɵprov = i0.ɵɵngDeclareService({ minVersion: "22.0.0", version: "22.1.3", ngImport: i0, type: LoginService }); }
 }
@@ -1093,7 +1263,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
             type: Service
         }] });
 
-/** Account endpoints (the `Links` section): user links management. */
+/**
+ * The `/account/*` endpoints: the links a user account carries, its settings, its password and the
+ * licence behind it.
+ *
+ * Everything here acts on the account the session names, which is why none of these methods takes
+ * one. The licence refresh is the exception in appearance only: the id in the route is ignored by
+ * the API, which reads the account from the session -- it used to be taken at face value, with no
+ * authorization at all, so any integer returned somebody else's company and expiry.
+ */
 class AccountService {
     constructor() {
         this.httpClient = inject(HttpClient);
@@ -1115,6 +1293,42 @@ class AccountService {
     deleteLink(item) {
         return this.httpClient.post(this.core.serviceUri + '/account/links/delete', item);
     }
+    /**
+     * Persists updated settings for the signed-in account (dashboard, flags).
+     * @param params - The settings to save.
+     * @returns An observable that emits `ApiResult<boolean>`.
+     */
+    updateSettings(params) {
+        return this.httpClient.post(this.core.serviceUri + '/account/settings/save', params);
+    }
+    /**
+     * Changes a password: the signed-in account's own, with `oldPassword`, or somebody else's when an
+     * administrator names it.
+     * @param params - The password change to apply.
+     * @returns An observable that emits `ApiResult<boolean>`.
+     */
+    resetPassword(params) {
+        return this.httpClient.post(this.core.serviceUri + '/account/password/reset', params);
+    }
+    /**
+     * Starts a password recovery, which mails a reset link to the given address.
+     * @param params - The address to recover, with the reCAPTCHA token that guards the route.
+     * @returns An observable that emits `ApiResult<boolean>`.
+     */
+    recoverPassword(params) {
+        return this.httpClient.post(this.core.serviceUri + '/account/password/recover', params);
+    }
+    /**
+     * Re-reads the licence of the signed-in account: company, expiry, quotas and allowed modules.
+     *
+     * Does NOT update the stored context: what the caller does with a fresh licence -- refresh a
+     * settings page, recompute a quota, store it -- is the caller's business, and a service that
+     * quietly rewrote the session context under it would be doing more than it was asked.
+     * @returns An observable that emits `ApiResult<EvolutionUserInfo>`.
+     */
+    refreshLicence() {
+        return this.httpClient.get(this.core.serviceUri + '/account/licenses/refresh/' + (this.core.user?.userId ?? -1));
+    }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: AccountService, deps: [], target: i0.ɵɵFactoryTarget.Service }); }
     static { this.ɵprov = i0.ɵɵngDeclareService({ minVersion: "22.0.0", version: "22.1.3", ngImport: i0, type: AccountService }); }
 }
@@ -1163,9 +1377,18 @@ class EvolutionService {
      * @returns The current {@link EvolutionLoginInfo}, or undefined.
      */
     get loginInfo() { return this.core.loginInfo; }
-    /** `true` when the user has an active (non-temporary) session. */
+    /**
+     * Gets the signed-in account with its licence context.
+     * @returns The current {@link EvolutionUserInfo}, or undefined when there is no session.
+     */
+    get user() { return this.core.user; }
+    /**
+     * `true` when this browser has a session the API has accepted. It starts from the stored context
+     * and is confirmed -- or left to the interceptor's 401 handling -- by the `/session/me` call
+     * {@link initialize} makes.
+     */
     get loggedIn() { return this.core.loggedIn; }
-    /** `true` while a login request is in flight. */
+    /** `true` while an authentication is in flight. */
     get loggingIn() { return this.core.loggingIn; }
     // ── Lifecycle (the only flattened sub-service methods) ──────────────────────
     /**
@@ -1204,5 +1427,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { AccountService, ComplianceService, ERPComplianceActivityState, ERPComplianceLawOrigin, ERPComplianceLawState, ERPComplianceLawsSelectionType, ERPComplianceNotificationLimit, ERPComplianceProfileFlags, ERPComplianceProfileRole, ERPComplianceRegisterNotificationType, ERPComplianceRegisterSiteImportOptions, ERPComplianceScope, ERPExportFormat, ERPExportPart, ERPExportSource, ERPExportType, ERPModule, ERPPlace, ERPPlacePermission, ERPRecurrenceFrequencyType, EvolutionComplianceActivityStates, EvolutionComplianceContextInfo, EvolutionComplianceLawChangeStates, EvolutionComplianceLawOrigins, EvolutionComplianceLawStates, EvolutionComplianceNotificationLimits, EvolutionComplianceNotifications, EvolutionComplianceObligationAuthorities, EvolutionComplianceObligationTypes, EvolutionComplianceProfileFlags, EvolutionComplianceProfileRoles, EvolutionComplianceScopes, EvolutionMessages, EvolutionRecurrenceFrequencyTypes, EvolutionService, EvolutionServiceFlags, LoginService, evolutionAuthInterceptor };
+export { AccountService, ComplianceService, ERPComplianceActivityState, ERPComplianceLawOrigin, ERPComplianceLawState, ERPComplianceLawsSelectionType, ERPComplianceNotificationLimit, ERPComplianceProfileFlags, ERPComplianceProfileRole, ERPComplianceRegisterNotificationType, ERPComplianceRegisterSiteImportOptions, ERPComplianceScope, ERPExportFormat, ERPExportPart, ERPExportSource, ERPExportType, ERPModule, ERPPlace, ERPPlacePermission, ERPRecurrenceFrequencyType, EVOLUTION_ACTIVE_ACCOUNT_KEY, EvolutionComplianceActivityStates, EvolutionComplianceContextInfo, EvolutionComplianceLawChangeStates, EvolutionComplianceLawOrigins, EvolutionComplianceLawStates, EvolutionComplianceNotificationLimits, EvolutionComplianceNotifications, EvolutionComplianceObligationAuthorities, EvolutionComplianceObligationTypes, EvolutionComplianceProfileFlags, EvolutionComplianceProfileRoles, EvolutionComplianceScopes, EvolutionMessages, EvolutionRecurrenceFrequencyTypes, EvolutionService, EvolutionServiceFlags, LoginService, evolutionAuthInterceptor };
 //# sourceMappingURL=arsedizioni-ars-utils-evolution.common.mjs.map