@wildo-ai/saas-frontend-lib 1.1.5 → 1.1.6

package/dist/esm/core/security/AuthSessionContext.js

@@ -19,6 +19,7 @@ import { useAnonymousSession } from '../../core/security/AnonymousSessionContext
 import { EMPTY_AUTH_STATE, authFactorLevelForUiLevel, PasskeyAutofillExpiredError, PasskeyAutofillSupersededError, PasskeySignInMediation, } from './security.frontend.schemas.js';
 import { PersistentSessionTokenStorage, } from './session-token-storage.frontend.service.js';
 import { FrontendComponentType, MfaChallengeLabel, UserAuthLabel } from '@wildo-ai/presets-components-models';
+import { SessionEndReason, SessionEstablishment } from '../../core/events/events.frontend.schemas.js';
 const logger = LoggerFrontendService.getLogger();
 const logDebug = logger.debugByType('AuthSessionContext');
 logger.setDebugTypeLogging('AuthSessionContext', false);
@@ -100,6 +101,21 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         // mirrors it into React state — the cookie is the sole source of
         // truth for the rotation channel.
     });
+    /**
+     * How the session this tab holds was established, and why the last one ended (#1977). Read by
+     * `UserOrgsProvider` when it announces `USER_LOGIN` / `USER_LOGOUT`, which happens a render AFTER the
+     * token changes — when the user's context has loaded, or has been cleared — so the facts are kept
+     * here, beside the only code that knows them, and read through `getSessionEstablishment` /
+     * `getSessionEndReason`.
+     *
+     * `RESUMED` is the initial value because the only token a tab can hold before any call here is the one
+     * it found in storage on load. `SESSION_ENDED` is the initial end reason because a session that ends
+     * with nobody recording why was not ended by the person.
+     */
+    const sessionEstablishmentRef = useRef(SessionEstablishment.RESUMED);
+    const sessionEndReasonRef = useRef(SessionEndReason.SESSION_ENDED);
+    const getSessionEstablishment = useCallback(() => sessionEstablishmentRef.current, []);
+    const getSessionEndReason = useCallback(() => sessionEndReasonRef.current, []);
     /**
      * Auth-hardening Slice A Step 3 (2026-04-13) — `storeAuthTokens` now only
      * carries the access token. The refresh token travels via the
@@ -109,11 +125,20 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
      * pre-migration session is wiped on the next call (and `EphemeralSessionTokenStorage`
      * stops accumulating an in-memory value that nothing reads).
      */
-    const storeAuthTokens = (accessToken) => {
+    const storeAuthTokens = (accessToken, establishment) => {
         tokenStorage.storeTokens(accessToken, null);
-        if (accessToken) {
-            clearAnonymousSession();
-        }
+        sessionEstablishmentRef.current = establishment;
+        clearAnonymousSession();
+    };
+    /**
+     * Store a ROTATED access token — a refresh, or a token another tab rotated or minted. Unlike
+     * {@link storeAuthTokens} it says nothing about how the session was established (#1977): a rotation
+     * continues the session it belongs to, so the establishment recorded when that session began stands,
+     * and a signed-out tab that adopts another tab's token has resumed a session rather than signed in.
+     */
+    const storeRotatedAccessToken = (accessToken) => {
+        tokenStorage.storeTokens(accessToken, null);
+        clearAnonymousSession();
     };
     /**
      * An answer parked the account at organization onboarding (#1090): remember the session the onboarding step
@@ -285,7 +310,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 : { ...a, isLoading: false, sessionId: resp.success ? null : sessionId }));
             return;
         }
-        storeAuthTokens(accessToken);
+        storeAuthTokens(accessToken, SessionEstablishment.SIGNED_IN);
         getManualCallsHttpClient().setAuthToken(accessToken);
         setResourcesAuthToken(accessToken);
         if (resp.success) {
@@ -495,7 +520,10 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 throw new Error('The code exchange answered with neither a sign-in nor a parked onboarding session.');
             }
             const { accessToken, returnPath, sourceFrontendServiceName, targetServiceKey } = response;
-            storeAuthTokens(accessToken);
+            // A cross-frontend handoff carries a session the person signed in to on the frontend that issued
+            // it, so here it is RESUMED; an OAuth or SSO callback is the sign-in itself (#1977). `returnPath`
+            // is the discriminator — see the invariant below.
+            storeAuthTokens(accessToken, typeof returnPath === 'string' ? SessionEstablishment.RESUMED : SessionEstablishment.SIGNED_IN);
             getManualCallsHttpClient().setAuthToken(accessToken);
             setResourcesAuthToken(accessToken);
             // Cross-frontend-handoff signal: the issuer (cross-app-jwt-propagation
@@ -563,7 +591,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         try {
             const response = await getManualCallsHttpClient().verifyEmail(token, email);
             if (response.accessToken) {
-                storeAuthTokens(response.accessToken);
+                storeAuthTokens(response.accessToken, SessionEstablishment.SIGNED_IN);
                 getManualCallsHttpClient().setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Email verification successful, tokens stored');
@@ -613,7 +641,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         try {
             const response = await getManualCallsHttpClient().acceptInvitation(params);
             if (response.accessToken) {
-                storeAuthTokens(response.accessToken);
+                storeAuthTokens(response.accessToken, SessionEstablishment.SIGNED_IN);
                 getManualCallsHttpClient().setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Invitation acceptance successful, tokens stored');
@@ -686,7 +714,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         const outcome = classifyRegistrationOutcome(response);
         if (outcome === RegistrationOutcome.SIGNED_IN) {
             const accessToken = response.accessToken;
-            storeAuthTokens(accessToken);
+            storeAuthTokens(accessToken, SessionEstablishment.SIGNED_IN);
             getManualCallsHttpClient().setAuthToken(accessToken);
             setResourcesAuthToken(accessToken);
             logDebug('Registration signed the registrant in, tokens stored', { state: response.state });
@@ -771,7 +799,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             // __wildo_refresh=…` response header (HttpOnly, JS-invisible).
             // Gate on `success && accessToken` only.
             if (response.success && response.accessToken) {
-                storeAuthTokens(response.accessToken);
+                storeAuthTokens(response.accessToken, SessionEstablishment.SIGNED_IN);
                 getManualCallsHttpClient().setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Magic link verification successful, tokens stored');
@@ -824,7 +852,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             // Auth-hardening Slice A Step 6 (2026-04-13): cookie-only contract
             // — see the magic-link gate above for the full rationale.
             if (response.success && response.accessToken) {
-                storeAuthTokens(response.accessToken);
+                storeAuthTokens(response.accessToken, SessionEstablishment.SIGNED_IN);
                 client.setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('MFA verification successful, tokens stored');
@@ -903,7 +931,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             return false;
         }
         const client = getManualCallsHttpClient();
-        storeAuthTokens(settlement.accessToken);
+        storeAuthTokens(settlement.accessToken, SessionEstablishment.SIGNED_IN);
         client.setAuthToken(settlement.accessToken);
         setResourcesAuthToken(settlement.accessToken);
         logDebug('Enrollment completed the registration session, tokens stored');
@@ -952,7 +980,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 logDebug('Onboarding obligation completed; the session stays parked on the rest', { pendingObligations: response.pendingObligations });
                 return { signedIn: false, pendingObligations: response.pendingObligations ?? [] };
             }
-            storeAuthTokens(response.accessToken);
+            storeAuthTokens(response.accessToken, SessionEstablishment.SIGNED_IN);
             client.setAuthToken(response.accessToken);
             setResourcesAuthToken(response.accessToken);
             logDebug('Onboarding completed, tokens stored', { organizationId: response.organizationId });
@@ -1129,7 +1157,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             // Auth-hardening Slice A Step 6 (2026-04-13): cookie-only contract
             // — see the magic-link gate above for the full rationale.
             if (response.success && response.accessToken) {
-                storeAuthTokens(response.accessToken);
+                storeAuthTokens(response.accessToken, SessionEstablishment.SIGNED_IN);
                 client.setAuthToken(response.accessToken);
                 setResourcesAuthToken(response.accessToken);
                 logDebug('Passkey authentication successful, tokens stored');
@@ -1198,7 +1226,9 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             const client = getManualCallsHttpClient();
             const response = await client.exchangeOneOffToken(token);
             const { accessToken, consumableTokenValue, tokenExpiresAt, context } = response;
-            storeAuthTokens(accessToken);
+            // A one-off session is scoped to one task and time-limited: it identifies the person but is not a
+            // sign-in to the application, so it is not counted as one (#1977) — see `SessionEstablishment.ONE_OFF`.
+            storeAuthTokens(accessToken, SessionEstablishment.ONE_OFF);
             client.setAuthToken(accessToken);
             setResourcesAuthToken(accessToken);
             if (consumableTokenValue) {
@@ -1261,9 +1291,17 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             rememberedPendingMfaSessionIdRef.current = null;
         }
     }, [auth.mfaRequired, auth.mfaSessionId, auth.accessToken, auth.identification?.email]);
-    const logout = useCallback(() => {
-        logDebug('Logging out user');
+    /**
+     * End this tab's session, recording WHY (#1977): `UserOrgsProvider` reads the reason when it announces
+     * `USER_LOGOUT`, and a listener that counts sign-outs must not count a session the backend ended.
+     * `logout` is the person's own sign-out; the refresh handler, session restore and the forced-logout
+     * error path end the session with {@link SessionEndReason.SESSION_ENDED}.
+     */
+    const endSession = useCallback((reason) => {
+        logDebug('Ending session', { reason });
         identificationGenerationRef.current += 1;
+        sessionEndReasonRef.current = reason;
+        sessionEstablishmentRef.current = SessionEstablishment.RESUMED;
         // Auth-hardening Slice A Step 3 (2026-04-13) — refresh token now travels
         // via the `__wildo_refresh` `HttpOnly` cookie. JS can't read it (and
         // doesn't need to): the cookie auto-attaches via `withCredentials: true`
@@ -1293,6 +1331,8 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         hasInitializedRef.current = false;
         logger.info('User logged out successfully');
     }, [disconnect, tokenStorage, setResourcesAuthToken, setResourcesConsumableToken]);
+    /** The person signs out of this tab. */
+    const logout = useCallback(() => endSession(SessionEndReason.SIGNED_OUT), [endSession]);
     /**
      * Single-use clear for the cross-frontend-handoff context.
      *
@@ -1375,7 +1415,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             // Persist the rotated access token. The rotated refresh token landed in
             // the `__wildo_refresh` cookie via `Set-Cookie` on the same response —
             // the browser cookie store updated automatically; no JS plumbing needed.
-            storeAuthTokens(result.accessToken);
+            storeRotatedAccessToken(result.accessToken);
             getManualCallsHttpClient().setAuthToken(result.accessToken);
             setResourcesAuthToken(result.accessToken);
             // Update React state — only the access token surfaces here.
@@ -1443,7 +1483,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                         ? error.customMessageReference
                         : (error instanceof Error ? error.message : 'Unknown error'),
                 });
-                logout();
+                endSession(SessionEndReason.SESSION_ENDED);
             }
             else {
                 logger.warn('Auth token renewal failed but session is preserved (will retry on the next request)', {
@@ -1456,7 +1496,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             }
             throw error;
         }
-    }, [setResourcesAuthToken, logout, refreshWebSocketAuth, tokenStorage]);
+    }, [setResourcesAuthToken, endSession, refreshWebSocketAuth, tokenStorage]);
     // Register the token renewal handler on both HTTP clients + expose it via ref
     // so the WebSocket `onAuthenticationError` callback (wired in `connectWebSocket`
     // above) always invokes the current handler.
@@ -1485,7 +1525,7 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
                 // long since aged out (A-Step 6 ships well after the dual-read
                 // window closed); the destructuring above doesn't pick it up.
                 logger.debug('Auth token renewal received from another tab; frontend clients updated');
-                storeAuthTokens(accessToken);
+                storeRotatedAccessToken(accessToken);
                 getManualCallsHttpClient().setAuthToken(accessToken);
                 setResourcesAuthToken(accessToken);
                 setAuth(a => ({ ...a, accessToken }));
@@ -1494,11 +1534,13 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
             if (type === 'LOGOUT') {
                 logDebug('Received logout signal from another tab');
                 identificationGenerationRef.current += 1;
+                sessionEndReasonRef.current = SessionEndReason.SIGNED_OUT_IN_ANOTHER_TAB;
+                sessionEstablishmentRef.current = SessionEstablishment.RESUMED;
                 disconnect();
                 tokenStorage.clear();
                 getManualCallsHttpClient().setConsumableToken(null);
                 setResourcesConsumableToken(null);
-                storeAuthTokens(null);
+                tokenStorage.storeTokens(null, null);
                 getManualCallsHttpClient().setAuthToken(null);
                 setResourcesAuthToken(null);
                 setAuth(EMPTY_AUTH_STATE);
@@ -1548,6 +1590,9 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         getSessionState,
         isAuthenticated,
         logout,
+        endSession,
+        getSessionEstablishment,
+        getSessionEndReason,
         // OAuth2 + cross-frontend-handoff (shared AUTH_CODE_EXCHANGE primitive)
         initiateOAuth2Login,
         handleAuthCodeExchange,
@@ -1580,6 +1625,9 @@ export const AuthSessionProvider = ({ children, tokenStorage: tokenStorageProp }
         auth,
         tokenStorage,
         logout,
+        endSession,
+        getSessionEstablishment,
+        getSessionEndReason,
         initiateOAuth2Login,
         handleAuthCodeExchange,
         handleEmailVerification,