@molecule/app-auth 3.0.2 → 3.2.1

package/dist/client.js

@@ -5,10 +5,128 @@
  *
  * @module
  */
+import { HttpError, snapshotHttpErrorResponse, } from '@molecule/app-http';
 import { I18nError } from '@molecule/app-i18n';
-import { getLogger } from '@molecule/app-logger';
+import { getLogger, redactCredentials, snapshotCredentials } from '@molecule/app-logger';
 import { createBrowserStorageAdapter } from './browser-storage.js';
 import { createTokenStorage, getTokenExpiration, isTokenExpired } from './token.js';
+const HTTP_ERROR_BRAND = Symbol.for('@molecule/app-http/HttpError');
+const ERROR_DATA_FIELDS = new Set(['name', 'message', 'stack', 'cause', 'errors']);
+/** Copy only detached data onto the fresh error's public and diagnostic fields. */
+const copyFailureSnapshot = (error, snapshot, preserveHttpMetadata = false) => {
+    for (const [key, value] of Object.entries(snapshot)) {
+        if (preserveHttpMetadata && (key === 'response' || key === 'config'))
+            continue;
+        Object.defineProperty(error, key, {
+            value,
+            enumerable: !ERROR_DATA_FIELDS.has(key),
+            configurable: true,
+            writable: true,
+        });
+    }
+    if (Object.getOwnPropertySymbols(snapshot).includes(HTTP_ERROR_BRAND) &&
+        Reflect.get(error, HTTP_ERROR_BRAND) !== true) {
+        Object.defineProperty(error, HTTP_ERROR_BRAND, { value: true });
+    }
+};
+const hasHttpErrorBrand = (failure) => failure !== null &&
+    (typeof failure === 'object' || typeof failure === 'function') &&
+    Object.getOwnPropertyDescriptor(failure, HTTP_ERROR_BRAND)?.value === true;
+/** Capture every non-response field on the original error, preserving native stacks and receivers. */
+const snapshotHttpFailureFields = (failure, response) => {
+    const originalFields = new Error();
+    const visited = new Set();
+    for (const key of [...ERROR_DATA_FIELDS, ...Reflect.ownKeys(failure)]) {
+        if (key === 'response')
+            continue;
+        if (typeof key === 'string') {
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+        }
+        let value;
+        try {
+            value = Reflect.get(failure, key);
+        }
+        catch (_error) {
+            value = '[ACCESSOR_ERROR]';
+        }
+        Object.defineProperty(originalFields, key, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    const snapshot = snapshotCredentials(originalFields);
+    Object.defineProperty(snapshot, 'response', {
+        value: response,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+    return snapshot;
+};
+/** Snapshot once, scrub the detached data, and never let the original failure escape. */
+const snapshotAuthFailure = async (failure) => {
+    const httpFailure = hasHttpErrorBrand(failure);
+    let capturedResponse;
+    if (httpFailure) {
+        try {
+            const originalResponse = failure.response;
+            capturedResponse = originalResponse
+                ? await snapshotHttpErrorResponse(originalResponse)
+                : undefined;
+        }
+        catch (_unreadableResponse) {
+            capturedResponse = undefined;
+        }
+    }
+    const snapshot = httpFailure
+        ? snapshotHttpFailureFields(failure, capturedResponse)
+        : snapshotCredentials(failure);
+    const data = (snapshot && typeof snapshot === 'object' && !Array.isArray(snapshot) ? snapshot : {});
+    const message = typeof data.message === 'string'
+        ? data.message
+        : typeof snapshot === 'string'
+            ? snapshot
+            : 'Authentication failed';
+    let error;
+    if (failure instanceof I18nError && typeof data.i18nKey === 'string') {
+        error = new I18nError(data.i18nKey, data.i18nValues, message);
+    }
+    else if (httpFailure) {
+        error = new HttpError(message, typeof data.status === 'number' ? data.status : 0, capturedResponse ?? data.response, data.config, typeof data.errorKey === 'string' ? data.errorKey : undefined, data.aborted === true);
+    }
+    else if (failure instanceof AggregateError) {
+        error = new AggregateError(Array.isArray(data.errors) ? data.errors : [], message);
+    }
+    else if (failure instanceof TypeError) {
+        error = new TypeError(message);
+    }
+    else {
+        error = new Error(message);
+    }
+    copyFailureSnapshot(error, data, error instanceof HttpError);
+    if (httpFailure) {
+        Object.defineProperty(error, 'response', {
+            value: capturedResponse ?? data.response,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return error;
+};
+/** Give every auth operation the same detached, fresh-failure boundary. */
+const runAuthOperation = async (operation) => {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw await snapshotAuthFailure(error);
+    }
+};
 /**
  * Whether this app is running inside a CROSS-SITE iframe — i.e. the molecule.dev
  * live preview (the app at `127.0.0.1:<port>` embedded in the `localhost:3000`
@@ -164,18 +282,17 @@ const applyProfileAnswer = (profile, answer) => {
  *   fields (see {@link AuthProfileConstraint}), including a profile with no `id`.
  *   The default, `UserProfile`, requires `id: string`.
  * @template TRegister - The app's own registration fields, accepted at the top
- *   level of `register()` (e.g. `{ username: string }` for a RealWorld-shaped API).
+ *   level of `register()` (e.g. `{ username: string }` for an account API).
  *   An interface and a type alias are equally valid.
  * @param config - Auth client configuration including endpoints, storage, and refresh settings.
  * @returns A fully configured `AuthClient` instance.
  */
 export const createJWTAuthClient = (config = {}) => {
-    const { baseURL = '', loginEndpoint = '/auth/login', logoutEndpoint = '/users/logout', registerEndpoint = '/auth/register', refreshEndpoint = '/auth/refresh', profileEndpoint = '/auth/profile', profileUpdateMethod = 'PATCH', profileRequestBody, forgotPasswordEndpoint = '/auth/password/reset', resetPasswordEndpoint = '/auth/password/reset/confirm', changePasswordEndpoint = '/auth/password/change', currentUserEndpoint = '/users/me', storagePrefix = 'molecule:auth:', storage: configuredStorage, shouldRestoreUser, autoRefresh = true, refreshBuffer = 60, } = config;
+    const { baseURL = '', loginEndpoint = '/auth/login', logoutEndpoint = '/users/logout', registerEndpoint = '/auth/register', refreshEndpoint = '/auth/refresh', profileEndpoint = '/auth/profile', profileUpdateMethod = 'PATCH', profileRequestBody, forgotPasswordEndpoint = '/auth/password/reset', resetPasswordEndpoint = '/auth/password/reset/confirm', changePasswordEndpoint = '/auth/password/change', changePasswordMethod = 'POST', currentUserEndpoint = '/users/me', cookieRestore = 'hint', storagePrefix = 'molecule:auth:', storage: configuredStorage, shouldRestoreUser, autoRefresh = true, refreshBuffer = 60, } = config;
     const logger = getLogger('auth');
     // In a browser the default is Web Storage: a session kept in memory is lost on
     // every full page load, so a `page.goto` after sign-in signs the user out
-    // (xr-molecule-flash-m158: 40 of 65 local failures were this one default). SSR
-    // and Node tests have no Web Storage, so they keep `'memory'`.
+    // SSR and Node tests have no Web Storage, so they keep `'memory'`.
     const storage = configuredStorage ?? (hasBrowserStorage() ? createBrowserStorageAdapter() : 'memory');
     // `tokenKey` exists so something OUTSIDE this client reads the token at its own
     // key. An explicit in-memory store makes that impossible: nothing else can see
@@ -184,10 +301,25 @@ export const createJWTAuthClient = (config = {}) => {
         logger.warn(`tokenKey '${config.tokenKey}' is in memory — nothing outside this client can read it and a reload signs the user out; pass storage: createBrowserStorageAdapter()`);
     }
     const tokenStorage = createTokenStorage(storage, storagePrefix, config.tokenKey);
+    const signOutMarkerKey = `${storagePrefix}signedOut`;
+    let memorySignOutMarker = null;
+    const getSignOutMarker = () => typeof storage === 'object' ? storage.getItem(signOutMarkerKey) : memorySignOutMarker;
+    const setSignOutMarker = () => {
+        if (typeof storage === 'object')
+            storage.setItem(signOutMarkerKey, '1');
+        else
+            memorySignOutMarker = '1';
+    };
+    const clearSignOutMarker = () => {
+        if (typeof storage === 'object')
+            storage.removeItem(signOutMarkerKey);
+        else
+            memorySignOutMarker = null;
+    };
     const stateListeners = new Set();
     const eventListeners = new Set();
     let refreshTimer = null;
-    // [m95] The session restore `initialize()` started, or null when none is running.
+    // The session restore `initialize()` started, or null when none is running.
     // Assigned SYNCHRONOUSLY, before that call's first await, so a component effect
     // running in the same tick (bootstrapApp calls initialize() and then renders)
     // already sees the restore and its HTTP requests wait for it (`whenRestored`).
@@ -196,6 +328,30 @@ export const createJWTAuthClient = (config = {}) => {
     // sign-in/sign-out invalidates older profile writes, even if token strings
     // happen to match. Background profile reads do not replace the session.
     let sessionRevision = 0;
+    // Accepted profile writes also own the cached profile: a read captured before
+    // one must not restore the older record after the save has been published.
+    let profileRevision = 0;
+    let pendingSessionOperations = 0;
+    let lastSignOutRevision = -1;
+    // A cookie can authenticate without a script-readable bearer or presence hint.
+    // Keep its candidacy until a session decision, independently of token storage.
+    let cookieSessionCandidate = false;
+    /**
+     * Runs every asynchronous session operation under the epoch that started it.
+     * The pending count makes an otherwise settled-looking anonymous client a
+     * session candidate for `setUser(null)`; the guard owns every later effect.
+     */
+    const runSessionOperation = async (callback) => {
+        const revision = sessionRevision;
+        const operation = { revision, isCurrent: () => revision === sessionRevision };
+        pendingSessionOperations++;
+        try {
+            return await runAuthOperation(() => callback(operation));
+        }
+        finally {
+            pendingSessionOperations--;
+        }
+    };
     let state = {
         status: 'loading',
         initialized: false,
@@ -239,7 +395,7 @@ export const createJWTAuthClient = (config = {}) => {
         // `authenticated` changing is that decision (an explicit status short-circuits
         // above for every other one).
         if (state.status === 'unavailable' &&
-            tokenStorage.getAccessToken() &&
+            (tokenStorage.getAccessToken() || cookieSessionCandidate) &&
             next.authenticated === state.authenticated) {
             return 'unavailable';
         }
@@ -247,17 +403,16 @@ export const createJWTAuthClient = (config = {}) => {
             return 'authenticated';
         return 'unauthenticated';
     };
-    const setState = (updates) => {
+    const setState = (updates, revisionAdvanced = false) => {
         const previous = state;
         const next = { ...previous, ...updates };
-        if (previous.authenticated && !next.authenticated)
+        if (previous.authenticated && !next.authenticated && !revisionAdvanced)
             sessionRevision++;
         // A user REFERENCE changes only when its data changes. A background verification
         // (`validateSession`, a reload's cookie restore) answers with a freshly parsed object that
         // usually carries exactly the data already in state; handing that new reference to every
         // subscriber re-runs every effect keyed on `user`, and a form seeded from it resets whatever
-        // the user has typed since (xr-molecule-flash-m173: a Settings form wiped the test's bio
-        // between `fill` and submit, so the PUT sent `"bio": ""`).
+        // the user has typed since, replacing unsaved form input with cached data.
         if (updates.user !== undefined && sameUserData(updates.user, previous.user)) {
             next.user = previous.user;
         }
@@ -274,13 +429,33 @@ export const createJWTAuthClient = (config = {}) => {
         if (!unchanged)
             notify();
     };
+    /** Ends local ownership before any cleanup, so older operations cannot publish. */
+    const endLocalSession = () => {
+        sessionRevision++;
+        lastSignOutRevision = sessionRevision;
+        setSignOutMarker();
+        if (refreshTimer) {
+            clearTimeout(refreshTimer);
+            refreshTimer = null;
+        }
+        tokenStorage.clear();
+        cookieSessionCandidate = false;
+        clearSessionHintCookie();
+        setState({
+            initialized: true,
+            loading: false,
+            authenticated: false,
+            user: null,
+            status: 'unauthenticated',
+        }, true);
+    };
     /**
      * Whether `err` is the client's own "nothing to refresh with" error thrown by
      * `refresh()` when no refresh token is stored (and the cookie-restore fallback
      * found no session).
      */
     const isNoRefreshTokenError = (err) => err instanceof I18nError && err.i18nKey === 'auth.error.noRefreshToken';
-    const scheduleRefresh = () => {
+    const scheduleRefresh = (retryAfterTransient = false) => {
         if (!autoRefresh)
             return;
         const token = tokenStorage.getAccessToken();
@@ -291,7 +466,7 @@ export const createJWTAuthClient = (config = {}) => {
         // keep the durable session in an httpOnly cookie the SERVER refreshes. A
         // timer here can only fail with `auth.error.noRefreshToken` — and it used to
         // LOG THE USER OUT on that failure while their access token was still valid
-        // (a RealWorld-shaped app signed itself out right after register). Leave the
+        // (an app without refresh tokens signed itself out right after register). Leave the
         // session alone; the API's next 401 (see `validateSession`) or an explicit
         // sign-out decides when it ends.
         if (!tokenStorage.getRefreshToken())
@@ -299,33 +474,43 @@ export const createJWTAuthClient = (config = {}) => {
         const expiresAt = getTokenExpiration(token);
         if (!expiresAt)
             return;
-        const refreshTime = expiresAt - refreshBuffer * 1000 - Date.now();
+        // A transient failure must not consume the one timer permanently: the
+        // original expiry-based instant has already passed, so retry on a bounded
+        // delay while retaining the session as `unavailable`. A success replaces
+        // this retry with the new token's normal expiry-based schedule.
+        const refreshTime = retryAfterTransient ? 30_000 : expiresAt - refreshBuffer * 1000 - Date.now();
         if (refreshTime <= 0)
             return;
         if (refreshTimer) {
             clearTimeout(refreshTimer);
         }
         refreshTimer = setTimeout(() => {
-            client.refresh().catch((err) => {
-                // The refresh token can disappear between scheduling and firing (a
-                // logout in another tab, a cleared store). That is not a failed refresh,
-                // so it must not sign the user out: keep the session and let the API
-                // reject the token if it really is dead.
-                if (isNoRefreshTokenError(err)) {
-                    logger.debug('Token refresh skipped — no refresh token stored; keeping the session until the API rejects the token', err);
-                    return;
+            void runSessionOperation(async (operation) => {
+                try {
+                    await client.refresh();
                 }
-                // ONLY the server rejecting the refresh token (401/403) ends the session.
-                // A network drop, an aborted request, or a 5xx says nothing about the
-                // credential — signing out here did exactly that on every flaky refresh.
-                // The API's next 401 (`validateSession`) or an explicit sign-out decides.
-                const httpStatus = err.status;
-                if (httpStatus === 401 || httpStatus === 403) {
-                    logger.warn('Token refresh was rejected, signing out', err);
-                    void client.logout();
-                    return;
+                catch (err) {
+                    // The refresh token can disappear between scheduling and firing (a
+                    // logout in another tab, a cleared store). That is not a failed refresh,
+                    // so it must not sign the user out: keep the session and let the API
+                    // reject the token if it really is dead.
+                    if (isNoRefreshTokenError(err)) {
+                        logger.debug('Token refresh skipped — no refresh token stored; keeping the session until the API rejects the token', err);
+                        return;
+                    }
+                    // ONLY a current server rejection ends the session. An old timer's
+                    // 401 must not destroy a login that replaced it while it was pending.
+                    if (!operation.isCurrent())
+                        return;
+                    const httpStatus = err.status;
+                    if ((httpStatus === 401 || httpStatus === 403) && operation.isCurrent()) {
+                        logger.warn('Token refresh was rejected, signing out', err);
+                        await client.logout();
+                        return;
+                    }
+                    logger.warn('Token refresh failed; keeping the session and scheduling a retry', err);
+                    scheduleRefresh(true);
                 }
-                logger.warn('Token refresh failed; keeping the session until the API rejects the token', err);
             });
         }, refreshTime);
     };
@@ -336,8 +521,7 @@ export const createJWTAuthClient = (config = {}) => {
         // With `AuthClientConfig<T>` the mapper's answer is already `AuthResult<T>`:
         // the compiler checks its user against the profile this client (and the
         // hook) hands to pages, so no cast may re-label it as `T` after mapping
-        // (xr-molecule-flash-m255: the cast let a mapper drop required fields the
-        // navbar read).
+        // while keeping the custom fields that consumers read.
         if (config.mapAuthResponse) {
             const mapped = config.mapAuthResponse(data);
             try {
@@ -392,7 +576,7 @@ export const createJWTAuthClient = (config = {}) => {
             return fallback;
         }
     };
-    const fetchAPI = async (endpoint, options = {}) => {
+    const fetchAPI = async (endpoint, options = {}) => runAuthOperation(async () => {
         const url = baseURL + endpoint;
         const headers = {
             'Content-Type': 'application/json',
@@ -414,13 +598,13 @@ export const createJWTAuthClient = (config = {}) => {
             headers,
         });
         if (!response.ok) {
-            // The parsed answer, kept WHOLE: the client maps `errorKey`/`error`/
-            // `message` into the I18nError it throws, but every other field — a
-            // RealWorld `{ errors: { credentials: ['is invalid'] } }` map, field
-            // arrays, a top-level array — is preserved on `body` so the app can show
-            // the server's own messages. A non-JSON body
-            // (HTML error page, empty) parses to `{}`, exactly as before.
-            const body = await response.json().catch(() => ({}));
+            // The parsed answer keeps its complete shape: the client maps `errorKey`/`error`/
+            // `message` into the I18nError it throws, and every other field — a structured
+            // `{ errors: { credentials: ['is invalid'] } }` map, field arrays, a top-level array —
+            // remains on `body` so the app can show the server's own messages. Credential values
+            // are redacted in place; non-secret values are unchanged. A non-JSON body (HTML error
+            // page, empty) parses to `{}`, exactly as before.
+            const body = redactCredentials(await response.json().catch(() => ({})));
             const fields = (body ?? {});
             // JSON is untyped: structured validation errors belong on `body`, never
             // in the translation key or its fallback text.
@@ -435,8 +619,31 @@ export const createJWTAuthClient = (config = {}) => {
             // from "the server did not answer" (5xx, network) or "the route does not
             // exist" (404) — `validateSession` clears the session only on the first.
             failure.status = response.status;
-            // The response body, exactly as parsed — see {@link AuthError}.
+            // The response body with credential values redacted — see {@link AuthError}.
             failure.body = body;
+            // Mirror app-http's failed-response view without importing it. Keep the
+            // original auth fields above intact: both documented readings now work on
+            // the SAME rejection, including across duplicated package copies.
+            const headers = {};
+            response.headers.forEach((value, name) => {
+                headers[name] = value;
+            });
+            failure.response = {
+                data: body,
+                status: response.status,
+                statusText: response.statusText,
+                headers: redactCredentials({ headers }).headers,
+                // RequestInit bodies contain passwords and refresh tokens, and its
+                // headers contain bearer/cookie credentials. Method and a credential-
+                // redacted URL are the complete request view an auth rejection may expose.
+                config: {
+                    method: (options.method ?? 'GET').toUpperCase(),
+                    url: redactCredentials(url),
+                },
+            };
+            failure.errorKey = key;
+            failure.aborted = false;
+            Object.defineProperty(failure, HTTP_ERROR_BRAND, { value: true });
             throw failure;
         }
         const data = await response.json();
@@ -448,29 +655,72 @@ export const createJWTAuthClient = (config = {}) => {
             data.user = data.props;
         }
         return data;
+    });
+    /**
+     * A stale credential exchange can set an HttpOnly cookie even when its local
+     * result is ignored. If its sign-out still owns this client, revoke those late
+     * credentials without delaying the caller. Never revoke a replacement session.
+     */
+    const discardLateSession = (operation, result) => {
+        if (operation.isCurrent() ||
+            state.authenticated ||
+            lastSignOutRevision <= operation.revision ||
+            !getSignOutMarker() ||
+            result.twoFactorRequired) {
+            return;
+        }
+        clearSessionHintCookie();
+        if (!logoutEndpoint)
+            return;
+        const accessToken = result.accessToken;
+        void runSessionOperation(async (cleanup) => {
+            try {
+                await fetchAPI(logoutEndpoint, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: accessToken
+                        ? { Authorization: `${config.authScheme ?? 'Bearer'} ${accessToken}` }
+                        : {},
+                });
+            }
+            catch (error) {
+                logger.debug('Late session revocation failed (non-critical)', error);
+            }
+            finally {
+                if (cleanup.isCurrent() && !state.authenticated && getSignOutMarker()) {
+                    clearSessionHintCookie();
+                }
+            }
+        });
     };
-    // [M1-1] Session restore from the httpOnly cookie. The bearer token is held
+    // Session restore from the httpOnly cookie. The bearer token is held
     // in memory (a localStorage copy is XSS-exfiltratable, so it is forbidden)
     // and is therefore lost on a full page load — but the httpOnly session cookie
     // persists. Probe the current-user endpoint with credentials; if the cookie
     // is still valid the server returns the user, and we re-establish the
     // authenticated session WITHOUT the token ever being exposed to JavaScript.
     //
-    // GATE on the non-httpOnly `mol_auth` presence hint (set by the server
-    // alongside the httpOnly token): only probe when a session plausibly exists.
-    // Without this gate, every anonymous caller would fire a guaranteed-401
-    // request (extra API call + console error). A forged hint only costs one
-    // harmless 401.
+    // By default, use the readable `mol_auth=1` hint to avoid probing every anonymous
+    // load. External cookie APIs can opt into `cookieRestore: 'always'`. Once this
+    // client has a candidate, retries do not depend on the hint remaining readable.
     //
     // Shared by initialize() (reload/deep-link restore) and refresh() (see the
     // no-refresh-token fallback there).
-    const restoreFromSessionCookie = async () => {
+    const restoreFromSessionCookie = async () => runSessionOperation(async (operation) => {
+        if (getSignOutMarker()) {
+            clearSessionHintCookie();
+            return { user: null, attempted: false, rejected: false };
+        }
         const hasSessionHint = typeof document !== 'undefined' && /(?:^|;\s*)mol_auth=1(?:;|$)/.test(document.cookie);
-        if (!hasSessionHint)
+        if (!hasSessionHint && !cookieSessionCandidate && cookieRestore !== 'always') {
             return { user: null, attempted: false, rejected: false };
-        const revision = sessionRevision;
+        }
+        cookieSessionCandidate = true;
         const token = tokenStorage.getAccessToken();
-        const isCurrent = () => revision === sessionRevision && token === tokenStorage.getAccessToken();
+        const readProfileRevision = profileRevision;
+        const isCurrent = () => operation.isCurrent() &&
+            token === tokenStorage.getAccessToken() &&
+            readProfileRevision === profileRevision;
         try {
             const result = await fetchAPI(currentUserEndpoint, {
                 method: 'GET',
@@ -479,37 +729,54 @@ export const createJWTAuthClient = (config = {}) => {
             // A sign-out or account switch while this GET was pending owns the new
             // state. Neither an old profile nor an old rejection may replace it.
             if (!isCurrent())
-                return { user: null, attempted: false, rejected: false };
+                return { user: null, attempted: false, rejected: false, stale: true };
             const rawUser = (result?.user ?? null);
             // The same adapter a sign-in's answer goes through — this answer is the
             // wire shape too, and storing it raw dropped the adapted identity.
             const restoredUser = mapCurrentUser(result, rawUser);
-            if (restoredUser && shouldRestoreUser && !shouldRestoreUser(restoredUser)) {
-                // The server DOES have a session (e.g. an anonymous/guest one), but the
-                // app says it must not count as a signed-in client. Stay logged out and
-                // drop the presence hint so later loads skip the probe entirely; the
-                // httpOnly session cookie is untouched and keeps authenticating API
-                // calls (a guest's projects still work).
-                clearSessionHintCookie();
-                return { user: null, attempted: true, rejected: false };
+            // The mapper and restore predicate are caller code and can end or replace
+            // the session synchronously. Re-check ownership after both, before any write.
+            if (!isCurrent())
+                return { user: null, attempted: false, rejected: false, stale: true };
+            if (restoredUser && shouldRestoreUser) {
+                const restore = shouldRestoreUser(restoredUser);
+                if (!isCurrent())
+                    return { user: null, attempted: false, rejected: false, stale: true };
+                if (!restore) {
+                    // The server DOES have a session (e.g. an anonymous/guest one), but the
+                    // app says it must not count as a signed-in client. Stay logged out and
+                    // drop the presence hint so later loads skip the probe entirely; the
+                    // httpOnly session cookie is untouched and keeps authenticating API
+                    // calls (a guest's projects still work).
+                    clearSessionHintCookie();
+                    cookieSessionCandidate = false;
+                    return { user: null, attempted: true, rejected: false, declined: true };
+                }
             }
             if (restoredUser) {
+                clearSignOutMarker();
                 tokenStorage.setUser(restoredUser);
-                setState({ status: 'authenticated', authenticated: true, user: restoredUser });
+                setState({
+                    status: 'authenticated',
+                    authenticated: true,
+                    user: restoredUser,
+                    error: null,
+                });
                 return { user: restoredUser, attempted: true, rejected: false };
             }
             return { user: null, attempted: true, rejected: false };
         }
         catch (error) {
             if (!isCurrent())
-                return { user: null, attempted: false, rejected: false };
+                return { user: null, attempted: false, rejected: false, stale: true };
             const httpStatus = error.status;
             // Only a REJECTED cookie (401/403) proves the hint stale: the session
             // expired server-side, or the database was reset. Drop the hint then, so
             // later loads skip a guaranteed-401 probe; the next login re-sets it.
             if (httpStatus === 401 || httpStatus === 403) {
                 clearSessionHintCookie();
-                return { user: null, attempted: true, rejected: true };
+                cookieSessionCandidate = false;
+                return { user: null, attempted: true, rejected: true, failure: error };
             }
             // Every other failure says nothing about the cookie. A 404 means the
             // configured `currentUserEndpoint` does not exist (a config error the app
@@ -526,6 +793,7 @@ export const createJWTAuthClient = (config = {}) => {
                 user: null,
                 attempted: true,
                 rejected: false,
+                failure: error,
                 error: httpStatus === 404
                     ? 'The current-user endpoint was not found. Serve the route or set currentUserEndpoint to it; the stored session was kept.'
                     : error instanceof Error
@@ -533,12 +801,15 @@ export const createJWTAuthClient = (config = {}) => {
                         : 'The session could not be confirmed',
             };
         }
-    };
+    });
     // The body of `initialize()`, kept separate so the client can record the in-flight
     // promise SYNCHRONOUSLY (see `restoreInFlight`): a caller that awaits `initialize()`
     // still sees a rejection, while `whenRestored()` hands out a promise that resolves.
-    const initializeSession = async () => {
-        const revision = sessionRevision;
+    const initializeSession = async () => runSessionOperation(async (operation) => {
+        if (getSignOutMarker()) {
+            endLocalSession();
+            return;
+        }
         const token = tokenStorage.getAccessToken();
         const user = tokenStorage.getUser();
         if (token && user) {
@@ -548,8 +819,7 @@ export const createJWTAuthClient = (config = {}) => {
             // verification below settles BEHIND that render; only an explicit 401/403
             // ends the session (the same classification `validateSession` uses). A page
             // that waited on its own `/me` call before painting paid a full API round
-            // trip on every navigation (xr-molecule-flash-m177: ~30 page loads in one
-            // pagination spec, its four tests at 15.0–15.9 s of a 15 s budget).
+            // trip on every navigation.
             setState({
                 initialized: true,
                 authenticated: true,
@@ -566,41 +836,34 @@ export const createJWTAuthClient = (config = {}) => {
             if (refreshToken) {
                 try {
                     await client.refresh();
-                    if (revision !== sessionRevision)
+                    if (!operation.isCurrent())
                         return;
                     setState({ initialized: true });
                     return;
                 }
                 catch (error) {
-                    if (revision !== sessionRevision)
+                    if (!operation.isCurrent())
                         return;
                     const httpStatus = error.status;
                     // Only the server REJECTING the refresh token proves the session dead.
                     // A network drop or a 5xx is not about the credential, and it used to
-                    // sign the user out here (the m159 class).
+                    // sign the user out here.
                     if (httpStatus === 401 || httpStatus === 403) {
                         logger.warn('Initial token refresh was rejected; signing out', error);
-                        tokenStorage.clear();
-                        setState({
-                            initialized: true,
-                            authenticated: false,
-                            user: null,
-                            status: 'unauthenticated',
-                        });
+                        endLocalSession();
                         return;
                     }
                     logger.warn('Initial token refresh failed; keeping the stored session until the API rejects it', error);
                 }
             }
-            // [M1-1] Cookie-restore — this is what keeps a refresh / deep-link logged
+            // Cookie-restore — this is what keeps a refresh / deep-link logged
             // in under the in-memory-token model. See restoreFromSessionCookie above.
             const outcome = await restoreFromSessionCookie();
-            if (revision !== sessionRevision)
+            if (!operation.isCurrent())
                 return;
-            if (outcome.rejected) {
+            if (outcome.rejected || outcome.declined) {
                 // The only other proof of this session was rejected by the server.
-                tokenStorage.clear();
-                setState({ initialized: true, authenticated: false, user: null, status: 'unauthenticated' });
+                endLocalSession();
                 return;
             }
             if (outcome.attempted && !outcome.user) {
@@ -623,16 +886,31 @@ export const createJWTAuthClient = (config = {}) => {
         // Reuse its mapping, failure classification and session ownership guards.
         if (token) {
             await client.validateSession();
-            if (revision !== sessionRevision)
+            if (!operation.isCurrent())
                 return;
             setState({ initialized: true });
             return;
         }
-        await restoreFromSessionCookie();
-        if (revision !== sessionRevision)
+        const outcome = await restoreFromSessionCookie();
+        if (!operation.isCurrent())
+            return;
+        if (outcome.rejected || outcome.declined) {
+            endLocalSession();
             return;
+        }
+        if (outcome.error !== undefined) {
+            // A cookie-only candidate is still a session candidate. A transient
+            // failure (including a missing current-user route) leaves it available
+            // for retry; only 401/403 may classify it as signed out.
+            setState({
+                initialized: true,
+                status: 'unavailable',
+                error: outcome.error,
+            });
+            return;
+        }
         setState({ initialized: true });
-    };
+    });
     /**
      * Starts the client's ONE session restore, or returns the one already running.
      *
@@ -690,6 +968,16 @@ export const createJWTAuthClient = (config = {}) => {
         },
         getSessionRevision: () => sessionRevision,
         setUser: (user) => {
+            if (user === null &&
+                (state.authenticated ||
+                    cookieSessionCandidate ||
+                    pendingSessionOperations > 0 ||
+                    state.loading ||
+                    !state.initialized)) {
+                // Settled-looking state can still have a refresh retry in flight.
+                endLocalSession();
+                return;
+            }
             if (user === null)
                 sessionRevision++;
             tokenStorage.setUser(user);
@@ -703,6 +991,8 @@ export const createJWTAuthClient = (config = {}) => {
         },
         setSession: (session) => {
             sessionRevision++;
+            clearSignOutMarker();
+            cookieSessionCandidate = false;
             // NOT passed through `mapAuthResponse`: a seed is not an API answer, it is
             // the profile the caller already built in this client's shape. Mapping it
             // would adapt an adapted profile a second time.
@@ -714,8 +1004,7 @@ export const createJWTAuthClient = (config = {}) => {
             // The COMPLETE state, in one update and one notification: an out-of-band exchange has
             // already proved the session, so `authenticated` must flip with the token. Writing the
             // token and the user with the two field setters leaves the client signed out for every
-            // shared hook (xr-molecule-flash-m178: nine navbar/profile assertions read
-            // `state.authenticated` and timed out after a successful registration).
+            // shared hook, even after a successful registration.
             setState({
                 initialized: true,
                 authenticated: true,
@@ -728,222 +1017,296 @@ export const createJWTAuthClient = (config = {}) => {
         },
         getRefreshToken: () => tokenStorage.getRefreshToken(),
         async login(credentials) {
-            setState({ loading: true, error: null });
-            try {
-                const result = mapResult(await fetchAPI(loginEndpoint, {
-                    method: 'POST',
-                    body: JSON.stringify(shapeBody('login', credentials)),
-                }));
-                // Two-factor gate: the server answered 206 `{ twoFactorRequired: true }`
-                // — no tokens/user issued. Surface the result WITHOUT marking the
-                // session authenticated; the caller re-prompts for the TOTP and retries.
-                if (result.twoFactorRequired) {
-                    setState({ loading: false });
+            return runSessionOperation(async (operation) => {
+                setState({ loading: true, error: null });
+                try {
+                    const result = mapResult(await fetchAPI(loginEndpoint, {
+                        method: 'POST',
+                        body: JSON.stringify(shapeBody('login', credentials)),
+                    }));
+                    // Mapping is caller code too: check after it, immediately before any
+                    // state, credential, event, or timer publication.
+                    if (!operation.isCurrent()) {
+                        discardLateSession(operation, result);
+                        return result;
+                    }
+                    // Two-factor gate: the server answered 206 `{ twoFactorRequired: true }`
+                    // — no tokens/user issued. Surface the result WITHOUT marking the
+                    // session authenticated; the caller re-prompts for the TOTP and retries.
+                    if (result.twoFactorRequired) {
+                        setState({ loading: false });
+                        return result;
+                    }
+                    sessionRevision++;
+                    clearSignOutMarker();
+                    cookieSessionCandidate = !result.accessToken;
+                    tokenStorage.setAccessToken(result.accessToken || null);
+                    tokenStorage.setRefreshToken(result.refreshToken || null);
+                    tokenStorage.setUser(result.user);
+                    setState({
+                        status: 'authenticated',
+                        loading: false,
+                        authenticated: true,
+                        user: result.user,
+                    });
+                    logger.debug('User logged in');
+                    emitEvent({ type: 'login', user: result.user });
+                    scheduleRefresh();
                     return result;
                 }
-                sessionRevision++;
-                tokenStorage.setAccessToken(result.accessToken || null);
-                tokenStorage.setRefreshToken(result.refreshToken || null);
-                tokenStorage.setUser(result.user);
-                setState({
-                    status: 'authenticated',
-                    loading: false,
-                    authenticated: true,
-                    user: result.user,
-                });
-                logger.debug('User logged in');
-                emitEvent({ type: 'login', user: result.user });
-                scheduleRefresh();
-                return result;
-            }
-            catch (err) {
-                const error = err instanceof Error ? err.message : 'Login failed';
-                setState({ loading: false, error });
-                emitEvent({ type: 'error', error });
-                throw err;
-            }
+                catch (err) {
+                    const failure = await snapshotAuthFailure(err);
+                    if (!operation.isCurrent())
+                        throw failure;
+                    setState({ loading: false, error: failure.message });
+                    emitEvent({ type: 'error', error: failure.message });
+                    throw failure;
+                }
+            });
         },
         async logout() {
-            sessionRevision++;
-            setState({ loading: true });
-            try {
-                // [M1-1] The persistent credential is the httpOnly session cookie, not
-                // the in-memory bearer token. The bearer does not survive a page reload
-                // (after a reload `initialize()` restores `authenticated` from the cookie
-                // but cannot repopulate the in-memory token), so guarding the server
-                // logout on `token` alone meant a reloaded session could never log out
-                // server-side and the httpOnly cookie lived on. Call the endpoint
-                // whenever we believe a session exists — token OR restored-authenticated —
-                // and send `credentials` so the cookie authenticates the device
-                // revocation and the server clears the httpOnly cookie.
+            await runSessionOperation(async (operation) => {
+                if (!operation.isCurrent())
+                    return;
+                // Capture revocation authority before local cleanup removes it. The
+                // cookie remains in the request; a bearer-only API gets the old token.
                 const token = tokenStorage.getAccessToken();
-                if (logoutEndpoint && (token || state.authenticated)) {
-                    await fetchAPI(logoutEndpoint, { method: 'POST', credentials: 'include' }).catch((err) => {
-                        logger.debug('Logout endpoint call failed (non-critical)', err);
-                    });
-                }
-            }
-            finally {
-                if (refreshTimer) {
-                    clearTimeout(refreshTimer);
-                    refreshTimer = null;
-                }
-                tokenStorage.clear();
-                // [M1-1] Drop the non-httpOnly session-presence hint so initialize()
-                // won't probe for cookie-restore on the next load even if the server
-                // logout call didn't complete (the server clears it too, on success).
-                clearSessionHintCookie();
-                setState({
-                    initialized: true,
-                    loading: false,
-                    authenticated: false,
-                    user: null,
-                    // An explicit sign-out settles the question, whatever came before.
-                    status: 'unauthenticated',
-                });
+                const revoke = logoutEndpoint && (token || state.authenticated || cookieSessionCandidate);
+                endLocalSession();
                 logger.debug('User logged out');
                 emitEvent({ type: 'logout' });
-            }
+                if (revoke && logoutEndpoint) {
+                    await fetchAPI(logoutEndpoint, {
+                        method: 'POST',
+                        credentials: 'include',
+                        headers: token ? { Authorization: `${config.authScheme ?? 'Bearer'} ${token}` } : {},
+                    }).catch((error) => {
+                        logger.debug('Logout endpoint call failed (non-critical)', error);
+                    });
+                }
+            });
         },
         async register(data) {
-            setState({ loading: true, error: null });
-            try {
-                const result = mapResult(await fetchAPI(registerEndpoint, {
-                    method: 'POST',
-                    body: JSON.stringify(shapeBody('register', data)),
-                }));
-                sessionRevision++;
+            return runSessionOperation(async (operation) => {
+                setState({ loading: true, error: null });
+                try {
+                    const result = mapResult(await fetchAPI(registerEndpoint, {
+                        method: 'POST',
+                        body: JSON.stringify(shapeBody('register', data)),
+                    }));
+                    if (!operation.isCurrent()) {
+                        discardLateSession(operation, result);
+                        return result;
+                    }
+                    sessionRevision++;
+                    clearSignOutMarker();
+                    cookieSessionCandidate = !result.accessToken;
+                    tokenStorage.setAccessToken(result.accessToken || null);
+                    tokenStorage.setRefreshToken(result.refreshToken || null);
+                    tokenStorage.setUser(result.user);
+                    setState({
+                        status: 'authenticated',
+                        loading: false,
+                        authenticated: true,
+                        user: result.user,
+                    });
+                    emitEvent({ type: 'register', user: result.user });
+                    scheduleRefresh();
+                    return result;
+                }
+                catch (err) {
+                    const failure = await snapshotAuthFailure(err);
+                    if (!operation.isCurrent())
+                        throw failure;
+                    setState({ loading: false, error: failure.message });
+                    emitEvent({ type: 'error', error: failure.message });
+                    throw failure;
+                }
+            });
+        },
+        async refresh() {
+            return runSessionOperation(async (operation) => {
+                const refreshToken = tokenStorage.getRefreshToken();
+                if (!refreshToken) {
+                    // Cookie-session APIs (the @molecule/api-resource-user model) issue NO
+                    // refresh token at all — login/register return only { accessToken, user }
+                    // and the durable credential is the httpOnly session cookie. For them,
+                    // "refresh" means re-deriving the session from that cookie, exactly like
+                    // initialize()'s restore. Without this fallback every post-auth refresh
+                    // (the auth modal's finishAuth, the upgrade-tab focus-return) threw
+                    // 'No refresh token available' — which silently aborted the modal's
+                    // signup/login flow right after the account was created.
+                    const outcome = await restoreFromSessionCookie();
+                    if (outcome.user) {
+                        if (operation.isCurrent())
+                            emitEvent({ type: 'refresh' });
+                        return { user: outcome.user };
+                    }
+                    if (outcome.rejected) {
+                        if (operation.isCurrent())
+                            endLocalSession();
+                        throw outcome.failure;
+                    }
+                    if (outcome.error !== undefined) {
+                        if (operation.isCurrent()) {
+                            setState({ initialized: true, status: 'unavailable', error: outcome.error });
+                        }
+                        throw outcome.failure;
+                    }
+                    if (outcome.declined && operation.isCurrent())
+                        endLocalSession();
+                    throw new I18nError('auth.error.noRefreshToken', undefined, 'No refresh token available');
+                }
+                let raw;
+                try {
+                    raw = await fetchAPI(refreshEndpoint, {
+                        method: 'POST',
+                        body: JSON.stringify({ refreshToken }),
+                    });
+                }
+                catch (error) {
+                    if (operation.isCurrent()) {
+                        const status = error.status;
+                        if (status === 401 || status === 403)
+                            endLocalSession();
+                        else {
+                            setState({
+                                status: 'unavailable',
+                                error: error instanceof Error ? error.message : 'The session could not be confirmed',
+                            });
+                        }
+                    }
+                    throw error;
+                }
+                // Normalize credentials and profile together. A mapper for another answer
+                // may not understand this response; preserve the standard wire result then.
+                let result = raw;
+                if (config.mapAuthResponse) {
+                    try {
+                        const mapped = mapResult(raw);
+                        result = {
+                            ...raw,
+                            ...mapped,
+                            accessToken: mapped?.accessToken ?? raw.accessToken,
+                            refreshToken: mapped?.refreshToken ?? raw.refreshToken,
+                            user: mapped?.user ?? raw.user,
+                        };
+                    }
+                    catch (error) {
+                        logger.debug('mapAuthResponse could not read the refresh answer; using it as given', error);
+                    }
+                }
+                const user = result?.user ?? null;
+                if (!operation.isCurrent()) {
+                    discardLateSession(operation, result);
+                    return result;
+                }
+                clearSignOutMarker();
+                cookieSessionCandidate = !result.accessToken;
                 tokenStorage.setAccessToken(result.accessToken || null);
-                tokenStorage.setRefreshToken(result.refreshToken || null);
-                tokenStorage.setUser(result.user);
+                if (result.refreshToken) {
+                    tokenStorage.setRefreshToken(result.refreshToken);
+                }
+                if (user)
+                    tokenStorage.setUser(user);
                 setState({
                     status: 'authenticated',
-                    loading: false,
                     authenticated: true,
-                    user: result.user,
+                    user,
+                    error: null,
                 });
-                emitEvent({ type: 'register', user: result.user });
+                emitEvent({ type: 'refresh' });
                 scheduleRefresh();
                 return result;
-            }
-            catch (err) {
-                const error = err instanceof Error ? err.message : 'Registration failed';
-                setState({ loading: false, error });
-                emitEvent({ type: 'error', error });
-                throw err;
-            }
-        },
-        async refresh() {
-            const refreshToken = tokenStorage.getRefreshToken();
-            if (!refreshToken) {
-                // Cookie-session APIs (the @molecule/api-resource-user model) issue NO
-                // refresh token at all — login/register return only { accessToken, user }
-                // and the durable credential is the httpOnly session cookie. For them,
-                // "refresh" means re-deriving the session from that cookie, exactly like
-                // initialize()'s restore. Without this fallback every post-auth refresh
-                // (the auth modal's finishAuth, the upgrade-tab focus-return) threw
-                // 'No refresh token available' — which silently aborted the modal's
-                // signup/login flow right after the account was created.
-                const outcome = await restoreFromSessionCookie();
-                if (outcome.user) {
-                    emitEvent({ type: 'refresh' });
-                    return { user: outcome.user };
-                }
-                throw new I18nError('auth.error.noRefreshToken', undefined, 'No refresh token available');
-            }
-            const result = await fetchAPI(refreshEndpoint, {
-                method: 'POST',
-                body: JSON.stringify({ refreshToken }),
             });
-            // The refresh answer carries the user too, in the same wire shape a
-            // sign-in's does — route it through the same mapper so a token refresh
-            // cannot replace the adapted profile with the raw one.
-            const user = mapCurrentUser(result, (result?.user ?? null));
-            tokenStorage.setAccessToken(result.accessToken || null);
-            if (result.refreshToken) {
-                tokenStorage.setRefreshToken(result.refreshToken);
-            }
-            if (user)
-                tokenStorage.setUser(user);
-            setState({
-                status: 'authenticated',
-                authenticated: true,
-                user,
-            });
-            emitEvent({ type: 'refresh' });
-            scheduleRefresh();
-            return { ...result, user: user ?? result.user };
         },
         async requestPasswordReset(data) {
-            await fetchAPI(forgotPasswordEndpoint, {
+            await runAuthOperation(() => fetchAPI(forgotPasswordEndpoint, {
                 method: 'POST',
                 body: JSON.stringify(data),
-            });
+            }));
         },
         async confirmPasswordReset(data) {
-            await fetchAPI(resetPasswordEndpoint, {
+            await runAuthOperation(() => fetchAPI(resetPasswordEndpoint, {
                 method: 'POST',
                 body: JSON.stringify(data),
-            });
+            }));
         },
         async updateProfile(data) {
-            const revision = sessionRevision;
-            // The REQUEST transport is configurable (`profileUpdateMethod` /
-            // `profileRequestBody`); everything below — mapping the answer, storing
-            // the user, notifying subscribers — is the same session state for every
-            // transport, so a PUT/enveloped API does not need a hand-written client.
-            // Defaults keep the resource-style PATCH with bare data.
-            const profileUser = state.user;
-            if (typeof profileEndpoint === 'function' && !profileUser)
-                throw new I18nError('auth.error.unauthorized', undefined, 'Sign in before updating a profile');
-            const endpoint = typeof profileEndpoint === 'function' ? profileEndpoint(profileUser) : profileEndpoint;
-            if (typeof profileEndpoint === 'function' &&
-                (typeof endpoint !== 'string' || !endpoint.trim()))
-                throw new TypeError('profileEndpoint must resolve to a nonempty route');
-            const body = profileRequestBody ? profileRequestBody(data) : data;
-            // Body adapters may return custom serializers; finish caller code before
-            // checking which session will authorize the request.
-            const serializedBody = JSON.stringify(body);
-            if (revision !== sessionRevision)
-                throw new I18nError('auth.error.unauthorized', undefined, 'The profile session changed before submission');
-            const answer = await fetchAPI(endpoint, {
-                method: profileUpdateMethod,
-                body: serializedBody,
+            return runAuthOperation(async () => {
+                const revision = sessionRevision;
+                // The REQUEST transport is configurable (`profileUpdateMethod` /
+                // `profileRequestBody`); everything below — mapping the answer, storing
+                // the user, notifying subscribers — is the same session state for every
+                // transport, so a PUT/enveloped API does not need a hand-written client.
+                // Defaults keep the resource-style PATCH with bare data.
+                const profileUser = state.user;
+                if (typeof profileEndpoint === 'function' && !profileUser)
+                    throw new I18nError('auth.error.unauthorized', undefined, 'Sign in before updating a profile');
+                const endpoint = typeof profileEndpoint === 'function' ? profileEndpoint(profileUser) : profileEndpoint;
+                if (typeof profileEndpoint === 'function' &&
+                    (typeof endpoint !== 'string' || !endpoint.trim()))
+                    throw new TypeError('profileEndpoint must resolve to a nonempty route');
+                const body = profileRequestBody ? profileRequestBody(data) : data;
+                // Body adapters may return custom serializers; finish caller code before
+                // checking which session will authorize the request.
+                const serializedBody = JSON.stringify(body);
+                if (revision !== sessionRevision)
+                    throw new I18nError('auth.error.unauthorized', undefined, 'The profile session changed before submission');
+                const answer = await fetchAPI(endpoint, {
+                    method: profileUpdateMethod,
+                    body: serializedBody,
+                });
+                // The profile route answers in one of three shapes: a bare user, `{ user }`, or
+                // the resource envelope `{ props }` (which `fetchAPI` aliases onto `user`).
+                // The profile the app stores is the USER, never the envelope around it —
+                // caching the envelope meant every page reading `user.name` read `undefined`
+                // right after a successful save (the settings-edit class).
+                const unwrapped = answer;
+                const raw = unwrapped.user ?? answer;
+                // The profile route answers the wire shape as well; map it like every
+                // other answer that replaces the cached user.
+                const mapped = mapCurrentUser(answer, raw) ?? raw;
+                // The server may have accepted the old account's update, but that answer
+                // must never replace a signed-out or newly signed-in account's cached
+                // user. Return the request's result, applied to the profile it was sent
+                // for, while leaving the current session (storage and subscribers) untouched.
+                if (revision !== sessionRevision)
+                    return applyProfileAnswer(profileUser, mapped);
+                // A changed-fields answer stored as the user dropped every field the save did not
+                // touch from every `useAuth()` reader, the stored session and the next save's route
+                // (`/users/undefined`). Apply it to the session's CURRENT user — a same-session
+                // refresh that landed during the save is kept — and store and publish the result
+                // once, so no reader ever sees the partial answer.
+                const user = applyProfileAnswer(state.user, mapped);
+                profileRevision++;
+                tokenStorage.setUser(user);
+                setState({ user });
+                return user;
             });
-            // The profile route answers in one of three shapes: a bare user, `{ user }`, or
-            // the resource envelope `{ props }` (which `fetchAPI` aliases onto `user`).
-            // The profile the app stores is the USER, never the envelope around it —
-            // caching the envelope meant every page reading `user.name` read `undefined`
-            // right after a successful save (the settings-edit class).
-            const unwrapped = answer;
-            const raw = unwrapped.user ?? answer;
-            // The profile route answers the wire shape as well; map it like every
-            // other answer that replaces the cached user.
-            const mapped = mapCurrentUser(answer, raw) ?? raw;
-            // The server may have accepted the old account's update, but that answer
-            // must never replace a signed-out or newly signed-in account's cached
-            // user. Return the request's result, applied to the profile it was sent
-            // for, while leaving the current session (storage and subscribers) untouched.
-            if (revision !== sessionRevision)
-                return applyProfileAnswer(profileUser, mapped);
-            // A changed-fields answer stored as the user dropped every field the save did not
-            // touch from every `useAuth()` reader, the stored session and the next save's route
-            // (`/users/undefined`). Apply it to the session's CURRENT user — a same-session
-            // refresh that landed during the save is kept — and store and publish the result
-            // once, so no reader ever sees the partial answer.
-            const user = applyProfileAnswer(state.user, mapped);
-            tokenStorage.setUser(user);
-            setState({ user });
-            return user;
         },
         async changePassword(oldPassword, newPassword) {
             // Server handler (@molecule/api-resource-user `updatePassword`)
             // reads `currentPassword`; legacy callers passed `oldPassword`,
             // so accept either name in the hook signature but translate to
             // the canonical `currentPassword` field when sending.
-            await fetchAPI(changePasswordEndpoint, {
-                method: 'POST',
-                body: JSON.stringify({ currentPassword: oldPassword, newPassword }),
+            await runAuthOperation(async () => {
+                const revision = sessionRevision;
+                const user = state.user;
+                if (typeof changePasswordEndpoint === 'function' && !user)
+                    throw new I18nError('auth.error.unauthorized', undefined, 'Sign in before changing a password');
+                const endpoint = typeof changePasswordEndpoint === 'function'
+                    ? changePasswordEndpoint(user)
+                    : changePasswordEndpoint;
+                if (typeof changePasswordEndpoint === 'function' &&
+                    (typeof endpoint !== 'string' || !endpoint.trim()))
+                    throw new TypeError('changePasswordEndpoint must resolve to a nonempty route');
+                if (revision !== sessionRevision)
+                    throw new I18nError('auth.error.unauthorized', undefined, 'The password session changed before submission');
+                await fetchAPI(endpoint, {
+                    method: changePasswordMethod,
+                    body: JSON.stringify({ currentPassword: oldPassword, newPassword }),
+                });
             });
         },
         async initialize() {
@@ -959,85 +1322,92 @@ export const createJWTAuthClient = (config = {}) => {
             return restoreInFlight ? restoreInFlight.catch(() => undefined) : Promise.resolve();
         },
         async validateSession() {
-            const token = tokenStorage.getAccessToken();
-            if (!token) {
-                setState({
-                    initialized: true,
-                    authenticated: false,
-                    user: null,
-                    status: 'unauthenticated',
-                });
-                return;
-            }
-            const revision = sessionRevision;
-            const isCurrent = () => revision === sessionRevision && token === tokenStorage.getAccessToken();
-            try {
-                // `fetchAPI` sends the stored token, so this asks the server "is this
-                // session still valid?" — the background check `initialize()` does not do
-                // (it restores from storage without a request by design).
-                const result = await fetchAPI(currentUserEndpoint, { method: 'GET' });
-                if (!isCurrent())
+            await runSessionOperation(async (operation) => {
+                const token = tokenStorage.getAccessToken();
+                if (!token) {
+                    const outcome = await restoreFromSessionCookie();
+                    if (!operation.isCurrent() || outcome.stale)
+                        return;
+                    if (outcome.rejected || outcome.declined) {
+                        endLocalSession();
+                    }
+                    else if (outcome.error !== undefined) {
+                        setState({ initialized: true, status: 'unavailable', error: outcome.error });
+                    }
+                    else if (outcome.user) {
+                        setState({ initialized: true });
+                    }
+                    else {
+                        setState({
+                            initialized: true,
+                            authenticated: false,
+                            user: null,
+                            status: 'unauthenticated',
+                        });
+                    }
                     return;
-                // The answer is the wire user, not the app's adapted profile: pass it
-                // through the same `mapAuthResponse` a sign-in uses before storing it
-                // (xr-molecule-flash-m184 — a reload replaced the adapted user with the
-                // raw one and the profile link disappeared).
-                const user = mapCurrentUser(result, (result?.user ?? tokenStorage.getUser()));
-                if (user) {
-                    tokenStorage.setUser(user);
-                    setState({
-                        initialized: true,
-                        authenticated: true,
-                        user,
-                        status: 'authenticated',
-                        error: null,
-                    });
-                }
-                else {
-                    tokenStorage.clear();
-                    setState({
-                        initialized: true,
-                        authenticated: false,
-                        user: null,
-                        status: 'unauthenticated',
-                    });
                 }
-            }
-            catch (error) {
-                if (!isCurrent())
-                    return;
-                const httpStatus = error.status;
-                // ONLY 401 and 403 are the server rejecting this token (revoked, expired,
-                // a reset database): drop the session rather than keep sending a header
-                // the server refuses. Any other status is not about the credential —
-                // most importantly a 404, which means `currentUserEndpoint` does not
-                // exist on this API. A route-not-found neither verifies nor rejects the
-                // token, so clearing it here signed every user out of a working session
-                // over a configuration mistake.
-                if (httpStatus === 401 || httpStatus === 403) {
-                    tokenStorage.clear();
-                    setState({
-                        initialized: true,
-                        authenticated: false,
-                        user: null,
-                        status: 'unauthenticated',
-                    });
-                    return;
+                const readProfileRevision = profileRevision;
+                const isCurrent = () => operation.isCurrent() && token === tokenStorage.getAccessToken();
+                const isCurrentProfileRead = () => isCurrent() && readProfileRevision === profileRevision;
+                try {
+                    // `fetchAPI` sends the stored token, so this asks the server "is this
+                    // session still valid?" — the background check `initialize()` does not do
+                    // (it restores from storage without a request by design).
+                    const result = await fetchAPI(currentUserEndpoint, { method: 'GET' });
+                    if (!isCurrent())
+                        return;
+                    // The answer is the wire user, not the app's adapted profile: pass it
+                    // through the same `mapAuthResponse` a sign-in uses before storing it
+                    // so a reload keeps the adapted identity and its account controls.
+                    const user = mapCurrentUser(result, (result?.user ?? tokenStorage.getUser()));
+                    if (!isCurrentProfileRead())
+                        return;
+                    if (user) {
+                        clearSignOutMarker();
+                        tokenStorage.setUser(user);
+                        setState({
+                            initialized: true,
+                            authenticated: true,
+                            user,
+                            status: 'authenticated',
+                            error: null,
+                        });
+                    }
+                    else {
+                        endLocalSession();
+                    }
                 }
-                // The server could not confirm the session. Keep the token AND the user
-                // so a later reload or a retry can restore them; say so with
-                // `unavailable` instead of signing the user out over a network failure,
-                // a 5xx, or a misplaced current-user route.
-                const message = httpStatus === 404
-                    ? "The current-user endpoint was not found. Set currentUserEndpoint to your API's current-user route; the stored token was kept."
-                    : error instanceof Error
-                        ? error.message
-                        : 'Session could not be confirmed';
-                if (httpStatus === 404) {
-                    logger.warn(`validateSession could not verify the session — the current-user endpoint "${currentUserEndpoint}" was not found. Set currentUserEndpoint to your API's current-user route; the stored token was kept.`, error);
+                catch (error) {
+                    if (!isCurrentProfileRead())
+                        return;
+                    const httpStatus = error.status;
+                    // ONLY 401 and 403 are the server rejecting this token (revoked, expired,
+                    // a reset database): drop the session rather than keep sending a header
+                    // the server refuses. Any other status is not about the credential —
+                    // most importantly a 404, which means `currentUserEndpoint` does not
+                    // exist on this API. A route-not-found neither verifies nor rejects the
+                    // token, so clearing it here signed every user out of a working session
+                    // over a configuration mistake.
+                    if (httpStatus === 401 || httpStatus === 403) {
+                        endLocalSession();
+                        return;
+                    }
+                    // The server could not confirm the session. Keep the token AND the user
+                    // so a later reload or a retry can restore them; say so with
+                    // `unavailable` instead of signing the user out over a network failure,
+                    // a 5xx, or a misplaced current-user route.
+                    const message = httpStatus === 404
+                        ? "The current-user endpoint was not found. Set currentUserEndpoint to your API's current-user route; the stored token was kept."
+                        : error instanceof Error
+                            ? error.message
+                            : 'Session could not be confirmed';
+                    if (httpStatus === 404) {
+                        logger.warn(`validateSession could not verify the session — the current-user endpoint "${currentUserEndpoint}" was not found. Set currentUserEndpoint to your API's current-user route; the stored token was kept.`, error);
+                    }
+                    setState({ status: 'unavailable', error: message });
                 }
-                setState({ status: 'unavailable', error: message });
-            }
+            });
         },
         subscribe(callback) {
             // Subscribing is a read of the state in all but name: a component that only