@spidy092/auth-client 2.1.3 → 2.1.6

package/config.js

@@ -1,10 +1,37 @@
 // auth-client/config.js
+
+// ========== SESSION SECURITY CONFIGURATION ==========
+// These settings control how the auth-client handles token refresh and session validation
+// to ensure deleted sessions in Keycloak are detected quickly.
+
 let config = {
   clientKey: null,
   authBaseUrl: null,
   redirectUri: null,
   accountUiUrl: null,
   isRouter: false, // ✅ Add router flag
+
+  // ========== SESSION SECURITY SETTINGS ==========
+  // Buffer time (in seconds) before token expiry to trigger proactive refresh
+  // With 5-minute access tokens, refreshing 60s before expiry ensures seamless UX
+  tokenRefreshBuffer: 60,
+
+  // Interval (in milliseconds) for periodic session validation
+  // Validates that the session still exists in Keycloak (not deleted by admin)
+  // Default: 2 minutes (120000ms) - balances responsiveness vs server load
+  sessionValidationInterval: 2 * 60 * 1000,
+
+  // Enable/disable periodic session validation
+  // When enabled, the client will ping the server to verify session is still active
+  enableSessionValidation: true,
+
+  // Enable/disable proactive token refresh
+  // When enabled, tokens are refreshed before they expire (using tokenRefreshBuffer)
+  enableProactiveRefresh: true,
+
+  // Validate session when browser tab becomes visible again
+  // Catches session deletions that happened while the tab was inactive
+  validateOnVisibility: true,
 };
 
 export function setConfig(customConfig = {}) {

package/core.js

@@ -15,7 +15,7 @@ let callbackProcessed = false;
 export function login(clientKeyArg, redirectUriArg) {
   // ✅ Reset callback state when starting new login
   resetCallbackState();
-  
+
   const {
     clientKey: defaultClientKey,
     authBaseUrl,
@@ -51,14 +51,14 @@ export function login(clientKeyArg, redirectUriArg) {
 // ✅ Router mode: Direct backend call
 function routerLogin(clientKey, redirectUri) {
   const { authBaseUrl } = getConfig();
-  
+
   const params = new URLSearchParams();
   if (redirectUri) {
     params.append('redirect_uri', redirectUri);
   }
   const query = params.toString();
   const backendLoginUrl = `${authBaseUrl}/login/${clientKey}${query ? `?${query}` : ''}`;
-  
+
   console.log('🏭 Router Login: Direct backend authentication', {
     clientKey,
     redirectUri,
@@ -71,7 +71,7 @@ function routerLogin(clientKey, redirectUri) {
 // ✅ Client mode: Centralized login
 function clientLogin(clientKey, redirectUri) {
   const { accountUiUrl } = getConfig();
-  
+
   const params = new URLSearchParams({
     client: clientKey
   });
@@ -79,7 +79,7 @@ function clientLogin(clientKey, redirectUri) {
     params.append('redirect_uri', redirectUri);
   }
   const centralizedLoginUrl = `${accountUiUrl}/login?${params.toString()}`;
-  
+
   console.log('🔄 Client Login: Redirecting to centralized login', {
     clientKey,
     redirectUri,
@@ -91,7 +91,7 @@ function clientLogin(clientKey, redirectUri) {
 
 export function logout() {
   resetCallbackState();
-  
+
   const { clientKey, authBaseUrl, accountUiUrl } = getConfig();
   const token = getToken();
 
@@ -188,24 +188,28 @@ export function handleCallback() {
 
   if (accessToken) {
     setToken(accessToken);
-    
-    // ✅ Refresh token should NOT be in URL - it's in httpOnly cookie
-    // If refresh token is in URL, log warning but don't store it client-side
+
+    // ✅ For HTTP development, store refresh token from URL
+    // In HTTPS production, refresh token is in httpOnly cookie (more secure)
     const refreshTokenInUrl = params.get('refresh_token');
     if (refreshTokenInUrl) {
-      console.warn('⚠️ SECURITY WARNING: Refresh token found in URL - this should not happen!');
-      // DO NOT store refresh token from URL - it should only be in httpOnly cookie
+      const isHttpDev = typeof window !== 'undefined' && window.location?.protocol === 'http:';
+      if (isHttpDev) {
+        console.log('📦 HTTP dev mode: Storing refresh token from callback URL');
+        setRefreshToken(refreshTokenInUrl);
+      } else {
+        console.log('🔒 HTTPS mode: Refresh token is in httpOnly cookie (ignoring URL param)');
+      }
     }
-    
+
     const url = new URL(window.location);
     url.searchParams.delete('access_token');
     url.searchParams.delete('refresh_token');
-    url.searchParams.delete('refresh_token');
     url.searchParams.delete('state');
     url.searchParams.delete('error');
     url.searchParams.delete('error_description');
     window.history.replaceState({}, '', url);
-    
+
     console.log('✅ Callback processed successfully, token stored');
     return accessToken;
   }
@@ -223,25 +227,25 @@ let refreshPromise = null;
 
 export async function refreshToken() {
   const { clientKey, authBaseUrl } = getConfig();
-  
+
   // ✅ Prevent concurrent refresh calls
   if (refreshInProgress && refreshPromise) {
     console.log('🔄 Token refresh already in progress, waiting...');
     return refreshPromise;
   }
-  
+
   refreshInProgress = true;
   refreshPromise = (async () => {
     try {
       // Get stored refresh token (for HTTP development)
       const storedRefreshToken = getRefreshToken();
-      
-      console.log('🔄 Refreshing token:', { 
-        clientKey, 
+
+      console.log('🔄 Refreshing token:', {
+        clientKey,
         mode: isRouterMode() ? 'ROUTER' : 'CLIENT',
         hasStoredRefreshToken: !!storedRefreshToken
       });
-      
+
       // Build request options - send refresh token in body and header for HTTP dev
       const requestOptions = {
         method: 'POST',
@@ -250,13 +254,13 @@ export async function refreshToken() {
           'Content-Type': 'application/json'
         }
       };
-      
+
       // For HTTP development, send refresh token in body and header
       if (storedRefreshToken) {
         requestOptions.headers['X-Refresh-Token'] = storedRefreshToken;
         requestOptions.body = JSON.stringify({ refreshToken: storedRefreshToken });
       }
-      
+
       const response = await fetch(`${authBaseUrl}/refresh/${clientKey}`, requestOptions);
 
       if (!response.ok) {
@@ -267,20 +271,20 @@ export async function refreshToken() {
 
       const data = await response.json();
       const { access_token, refresh_token: new_refresh_token } = data;
-      
+
       if (!access_token) {
         throw new Error('No access token in refresh response');
       }
-      
+
       // ✅ This will trigger token listeners
       setToken(access_token);
-      
+
       // ✅ Store new refresh token if provided (token rotation)
       if (new_refresh_token) {
         setRefreshToken(new_refresh_token);
         console.log('🔄 New refresh token stored from rotation');
       }
-      
+
       console.log('✅ Token refresh successful, listeners notified');
       return access_token;
     } catch (err) {
@@ -294,7 +298,7 @@ export async function refreshToken() {
       refreshPromise = null;
     }
   })();
-  
+
   return refreshPromise;
 }
 
@@ -302,7 +306,7 @@ export async function validateCurrentSession() {
   try {
     const { authBaseUrl } = getConfig();
     const token = getToken();
-    
+
     if (!token || !authBaseUrl) {
       return false;
     }
@@ -334,30 +338,218 @@ export async function validateCurrentSession() {
   }
 }
 
+// ========== SESSION SECURITY: PROACTIVE REFRESH & VALIDATION ==========
+// These functions ensure that:
+// 1. Tokens are refreshed before they expire (proactive refresh)
+// 2. Sessions deleted in Keycloak Admin UI are detected quickly (periodic validation)
+
+let proactiveRefreshTimer = null;
+let sessionValidationTimer = null;
+let visibilityHandler = null;
+let sessionInvalidCallbacks = new Set();
+
+// Register a callback to be called when session is invalidated
+export function onSessionInvalid(callback) {
+  if (typeof callback === 'function') {
+    sessionInvalidCallbacks.add(callback);
+  }
+  return () => sessionInvalidCallbacks.delete(callback);
+}
+
+// Notify all registered callbacks that session is invalid
+function notifySessionInvalid(reason = 'session_deleted') {
+  console.log('🚨 Session invalidated:', reason);
+  sessionInvalidCallbacks.forEach(callback => {
+    try {
+      callback(reason);
+    } catch (err) {
+      console.error('Session invalid callback error:', err);
+    }
+  });
+}
+
+// ========== PROACTIVE TOKEN REFRESH ==========
+// Schedules token refresh before expiry to ensure seamless UX
+
+export function startProactiveRefresh() {
+  const { enableProactiveRefresh, tokenRefreshBuffer } = getConfig();
+
+  if (!enableProactiveRefresh) {
+    console.log('⏸️ Proactive refresh disabled by config');
+    return null;
+  }
+
+  // Clear any existing timer
+  stopProactiveRefresh();
+
+  const token = getToken();
+  if (!token) {
+    console.log('⏸️ No token, skipping proactive refresh setup');
+    return null;
+  }
+
+  const { getTimeUntilExpiry } = require('./token');
+  const timeUntilExpiry = getTimeUntilExpiry(token);
+
+  if (timeUntilExpiry <= 0) {
+    console.log('⚠️ Token already expired, attempting immediate refresh');
+    refreshToken().catch(err => {
+      console.error('❌ Immediate refresh failed:', err);
+      notifySessionInvalid('token_expired');
+    });
+    return null;
+  }
+
+  // Schedule refresh for (expiry - buffer) seconds from now
+  const refreshIn = Math.max(0, (timeUntilExpiry - tokenRefreshBuffer)) * 1000;
+
+  console.log(`🔄 Scheduling proactive refresh in ${Math.round(refreshIn / 1000)}s (token expires in ${timeUntilExpiry}s)`);
+
+  proactiveRefreshTimer = setTimeout(async () => {
+    try {
+      console.log('🔄 Proactive token refresh triggered');
+      await refreshToken();
+      console.log('✅ Proactive refresh successful, scheduling next refresh');
+      // Schedule next refresh after successful refresh
+      startProactiveRefresh();
+    } catch (err) {
+      console.error('❌ Proactive refresh failed:', err);
+      // Try again in 30 seconds if refresh fails
+      proactiveRefreshTimer = setTimeout(() => startProactiveRefresh(), 30000);
+    }
+  }, refreshIn);
+
+  return proactiveRefreshTimer;
+}
+
+export function stopProactiveRefresh() {
+  if (proactiveRefreshTimer) {
+    clearTimeout(proactiveRefreshTimer);
+    proactiveRefreshTimer = null;
+    console.log('⏹️ Proactive refresh stopped');
+  }
+}
+
+// ========== PERIODIC SESSION VALIDATION ==========
+// Validates with server that session still exists in Keycloak
+// Catches session deletions from Keycloak Admin UI
 
+export function startSessionMonitor(onInvalid) {
+  const { enableSessionValidation, sessionValidationInterval, validateOnVisibility } = getConfig();
 
+  if (!enableSessionValidation) {
+    console.log('⏸️ Session validation disabled by config');
+    return null;
+  }
 
+  // Register callback if provided
+  if (onInvalid && typeof onInvalid === 'function') {
+    sessionInvalidCallbacks.add(onInvalid);
+  }
 
-// export async function refreshToken() {
-//   const { clientKey, authBaseUrl } = getConfig();
-  
-//   console.log('🔄 Refreshing token:', { clientKey, mode: isRouterMode() ? 'ROUTER' : 'CLIENT' });
-  
-//   try {
-//     const response = await fetch(`${authBaseUrl}/refresh/${clientKey}`, {
-//       method: 'POST',
-//       credentials: 'include',
-//     });
+  // Clear any existing timer
+  stopSessionMonitor();
 
-//     if (!response.ok) {
-//       throw new Error('Refresh failed');
-//     }
+  const token = getToken();
+  if (!token) {
+    console.log('⏸️ No token, skipping session monitor setup');
+    return null;
+  }
+
+  console.log(`👁️ Starting session monitor (interval: ${sessionValidationInterval / 1000}s)`);
+
+  // Periodic validation
+  sessionValidationTimer = setInterval(async () => {
+    try {
+      const currentToken = getToken();
+      if (!currentToken) {
+        console.log('⏸️ No token, stopping session validation');
+        stopSessionMonitor();
+        return;
+      }
+
+      console.log('🔍 Validating session...');
+      const isValid = await validateCurrentSession();
+
+      if (!isValid) {
+        console.log('❌ Session no longer valid on server');
+        stopSessionMonitor();
+        stopProactiveRefresh();
+        clearToken();
+        clearRefreshToken();
+        notifySessionInvalid('session_deleted');
+      } else {
+        console.log('✅ Session still valid');
+      }
+    } catch (error) {
+      console.warn('⚠️ Session validation check failed:', error.message);
+      // Don't invalidate on network errors - wait for next check
+    }
+  }, sessionValidationInterval);
+
+  // Visibility-based validation (when tab becomes visible again)
+  if (validateOnVisibility && typeof document !== 'undefined') {
+    visibilityHandler = async () => {
+      if (document.visibilityState === 'visible') {
+        const currentToken = getToken();
+        if (!currentToken) return;
+
+        console.log('👁️ Tab visible - validating session');
+        try {
+          const isValid = await validateCurrentSession();
+          if (!isValid) {
+            console.log('❌ Session expired while tab was hidden');
+            stopSessionMonitor();
+            stopProactiveRefresh();
+            clearToken();
+            clearRefreshToken();
+            notifySessionInvalid('session_deleted_while_hidden');
+          }
+        } catch (error) {
+          console.warn('⚠️ Visibility check failed:', error.message);
+        }
+      }
+    };
+    document.addEventListener('visibilitychange', visibilityHandler);
+  }
+
+  return sessionValidationTimer;
+}
+
+export function stopSessionMonitor() {
+  if (sessionValidationTimer) {
+    clearInterval(sessionValidationTimer);
+    sessionValidationTimer = null;
+    console.log('⏹️ Session monitor stopped');
+  }
+
+  if (visibilityHandler && typeof document !== 'undefined') {
+    document.removeEventListener('visibilitychange', visibilityHandler);
+    visibilityHandler = null;
+  }
+}
+
+// ========== COMBINED SESSION SECURITY ==========
+// Start both proactive refresh and session monitoring
+
+export function startSessionSecurity(onSessionInvalidCallback) {
+  console.log('🔐 Starting session security (proactive refresh + session monitoring)');
+
+  startProactiveRefresh();
+  startSessionMonitor(onSessionInvalidCallback);
+
+  return {
+    stopAll: () => {
+      stopProactiveRefresh();
+      stopSessionMonitor();
+    }
+  };
+}
+
+export function stopSessionSecurity() {
+  stopProactiveRefresh();
+  stopSessionMonitor();
+  sessionInvalidCallbacks.clear();
+  console.log('🔐 Session security stopped');
+}
 
-//     const { access_token } = await response.json();
-//     setToken(access_token);
-//     return access_token;
-//   } catch (err) {
-//     clearToken();
-//     throw err;
-//   }
-// }

package/index.js

@@ -1,7 +1,36 @@
 // auth-client/index.js
 import { setConfig, getConfig, isRouterMode } from './config';
-import { login, logout, handleCallback, refreshToken, resetCallbackState, validateCurrentSession } from './core';
-import { getToken, setToken, clearToken, setRefreshToken, getRefreshToken, clearRefreshToken, addTokenListener, removeTokenListener, getListenerCount } from './token';
+import {
+  login,
+  logout,
+  handleCallback,
+  refreshToken,
+  resetCallbackState,
+  validateCurrentSession,
+  // Session Security Functions
+  startProactiveRefresh,
+  stopProactiveRefresh,
+  startSessionMonitor,
+  stopSessionMonitor,
+  startSessionSecurity,
+  stopSessionSecurity,
+  onSessionInvalid
+} from './core';
+import {
+  getToken,
+  setToken,
+  clearToken,
+  setRefreshToken,
+  getRefreshToken,
+  clearRefreshToken,
+  addTokenListener,
+  removeTokenListener,
+  getListenerCount,
+  // Token Expiry Utilities
+  getTokenExpiryTime,
+  getTimeUntilExpiry,
+  willExpireSoon
+} from './token';
 import api from './api';
 import { decodeToken, isTokenExpired, isAuthenticated } from './utils/jwt';
 
@@ -38,8 +67,23 @@ export const auth = {
   isTokenExpired,
   isAuthenticated,
 
-  // 🔄 Auto-refresh setup
+  // ⏱️ Token Expiry Utilities (NEW)
+  getTokenExpiryTime,    // Get token expiry as Date object
+  getTimeUntilExpiry,    // Get seconds until token expires
+  willExpireSoon,        // Check if token expires within N seconds
+
+  // 🔐 Session Security (NEW - Short-lived tokens + Periodic validation)
+  startProactiveRefresh,   // Start proactive token refresh before expiry
+  stopProactiveRefresh,    // Stop proactive refresh
+  startSessionMonitor,     // Start periodic session validation
+  stopSessionMonitor,      // Stop session validation
+  startSessionSecurity,    // Start both proactive refresh AND session monitoring
+  stopSessionSecurity,     // Stop all session security
+  onSessionInvalid,        // Register callback for session invalidation
+
+  // 🔄 Legacy auto-refresh (DEPRECATED - use startSessionSecurity instead)
   startTokenRefresh: () => {
+    console.warn('⚠️ startTokenRefresh is deprecated. Use startSessionSecurity() instead for better session management.');
     const interval = setInterval(async () => {
       const token = getToken();
       if (token && isTokenExpired(token, 300)) {
@@ -59,3 +103,4 @@ export const auth = {
 export { AuthProvider } from './react/AuthProvider';
 export { useAuth } from './react/useAuth';
 export { useSessionMonitor } from './react/useSessionMonitor';
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spidy092/auth-client",
-  "version": "2.1.3",
+  "version": "2.1.6",
   "description": "Scalable frontend auth SDK for centralized login using Keycloak + Auth Service.",
   "main": "index.js",
   "module": "index.js",

package/react/AuthProvider.jsx

@@ -1,18 +1,72 @@
 // auth-client/react/AuthProvider.jsx
-import React, { createContext, useState, useEffect } from 'react';
+import React, { createContext, useState, useEffect, useRef } from 'react';
 import { getToken, setToken, clearToken } from '../token';
 import { getConfig } from '../config';
-import { login as coreLogin, logout as coreLogout } from '../core';
+import { 
+  login as coreLogin, 
+  logout as coreLogout,
+  startSessionSecurity,
+  stopSessionSecurity,
+  onSessionInvalid
+} from '../core';
 
 export const AuthContext = createContext();
 
-export function AuthProvider({ children }) {
+export function AuthProvider({ children, onSessionExpired }) {
   const [token, setTokenState] = useState(getToken());
   const [user, setUser] = useState(null);
   const [loading, setLoading] = useState(!!token); // Loading if we have a token to validate
+  const [sessionValid, setSessionValid] = useState(true);
+  const sessionSecurityRef = useRef(null);
 
+  // Handle session invalidation (from Keycloak admin deletion or expiry)
+  const handleSessionInvalid = (reason) => {
+    console.log('🚨 AuthProvider: Session invalidated -', reason);
+    setSessionValid(false);
+    setUser(null);
+    setTokenState(null);
+    
+    // Call custom callback if provided
+    if (onSessionExpired && typeof onSessionExpired === 'function') {
+      onSessionExpired(reason);
+    }
+  };
+
+  // Start session security on mount (when we have a token)
   useEffect(() => {
+    if (token && !sessionSecurityRef.current) {
+      console.log('🔐 AuthProvider: Starting session security');
+      
+      // Register session invalid handler
+      const unsubscribe = onSessionInvalid(handleSessionInvalid);
+      
+      // Start proactive refresh + session monitoring
+      sessionSecurityRef.current = startSessionSecurity(handleSessionInvalid);
+      
+      return () => {
+        unsubscribe();
+        if (sessionSecurityRef.current) {
+          sessionSecurityRef.current.stopAll();
+          sessionSecurityRef.current = null;
+        }
+      };
+    }
+    
+    // Cleanup when token is removed
+    if (!token && sessionSecurityRef.current) {
+      sessionSecurityRef.current.stopAll();
+      sessionSecurityRef.current = null;
+    }
+  }, [token]);
+
+  useEffect(() => {
+    console.log('🔍 AuthProvider useEffect triggered:', { 
+      hasToken: !!token, 
+      tokenLength: token?.length 
+    });
+    
     if (!token) {
+      console.log('⚠️ AuthProvider: No token, setting loading=false');
       setLoading(false);
       return;
     }
@@ -24,20 +78,28 @@ export function AuthProvider({ children }) {
       return;
     }
 
+    console.log('🌐 AuthProvider: Fetching profile with token...', {
+      authBaseUrl,
+      tokenPreview: token.slice(0, 50) + '...'
+    });
+
     fetch(`${authBaseUrl}/account/profile`, {
       headers: { Authorization: `Bearer ${token}` },
       credentials: 'include',
     })
       .then(res => {
+        console.log('📥 Profile response status:', res.status);
         if (!res.ok) throw new Error('Failed to fetch user');
         return res.json();
       })
       .then(userData => {
+        console.log('✅ Profile fetched successfully:', userData.email);
         setUser(userData);
+        setSessionValid(true);
         setLoading(false);
       })
       .catch(err => {
-        console.error('Fetch user error:', err);
+        console.error('❌ Fetch user error:', err);
         clearToken();
         setTokenState(null);
         setUser(null);
@@ -50,9 +112,14 @@ export function AuthProvider({ children }) {
   };
 
   const logout = () => {
+    // Stop session security before logout
+    stopSessionSecurity();
+    sessionSecurityRef.current = null;
+    
     coreLogout();
     setUser(null);
     setTokenState(null);
+    setSessionValid(true);
   };
 
   const value = {
@@ -61,13 +128,17 @@ export function AuthProvider({ children }) {
     loading,
     login,
     logout,
-    isAuthenticated: !!token && !!user,
+    isAuthenticated: !!token && !!user && sessionValid,
+    sessionValid,
     setUser,
     setToken: (newToken) => {
       setToken(newToken);
       setTokenState(newToken);
+      setSessionValid(true);
     },
     clearToken: () => {
+      stopSessionSecurity();
+      sessionSecurityRef.current = null;
       clearToken();
       setTokenState(null);
       setUser(null);

package/react/useSessionMonitor.js

@@ -1,34 +1,78 @@
-// Create: auth-client/react/useSessionMonitor.js
+// auth-client/react/useSessionMonitor.js
+// Enhanced session monitoring hook for detecting Keycloak admin session deletions
 import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useEffect, useCallback } from 'react';
 import { auth } from '../index';
 
+/**
+ * useSessionMonitor - React hook for periodic session validation
+ * 
+ * This hook validates that the user's session still exists in Keycloak.
+ * When an admin deletes a session from Keycloak Admin UI, this hook
+ * will detect it and trigger the onSessionInvalid callback.
+ * 
+ * @param {Object} options Configuration options
+ * @param {boolean} options.enabled - Enable/disable monitoring (default: true)
+ * @param {number} options.refetchInterval - Validation interval in ms (default: 120000 = 2 min)
+ * @param {Function} options.onSessionInvalid - Callback when session is deleted
+ * @param {Function} options.onError - Callback for validation errors
+ * @param {boolean} options.autoLogout - Auto logout on invalid session (default: true)
+ * @param {boolean} options.validateOnMount - Validate session immediately on mount (default: true)
+ */
 export const useSessionMonitor = (options = {}) => {
   const queryClient = useQueryClient();
-  
+
   const {
     enabled = true,
-    refetchInterval = 30 * 1000, // 30 seconds
+    refetchInterval = 2 * 60 * 1000, // 2 minutes (matching config default)
     onSessionInvalid,
-    onError
+    onError,
+    autoLogout = true,
+    validateOnMount = true,
   } = options;
 
-  return useQuery({
+  // Handle session invalidation
+  const handleInvalid = useCallback(() => {
+    console.log('🚨 useSessionMonitor: Session invalid detected');
+
+    // Clear all react-query cache
+    queryClient.clear();
+
+    // Auto logout if enabled
+    if (autoLogout) {
+      auth.clearToken();
+      auth.clearRefreshToken();
+    }
+
+    // Call custom callback
+    if (onSessionInvalid) {
+      onSessionInvalid();
+    }
+  }, [queryClient, autoLogout, onSessionInvalid]);
+
+  // Session validation query
+  const query = useQuery({
     queryKey: ['session-validation'],
     queryFn: async () => {
       try {
+        const token = auth.getToken();
+        if (!token) {
+          return { valid: false, reason: 'no_token' };
+        }
+
+        console.log('🔍 useSessionMonitor: Validating session...');
         const isValid = await auth.validateCurrentSession();
-        
-        if (!isValid && onSessionInvalid) {
-          // Clear all cached data
-          queryClient.clear();
-          // Trigger custom callback
-          onSessionInvalid();
-          return { valid: false };
+
+        if (!isValid) {
+          console.log('❌ useSessionMonitor: Session no longer valid');
+          handleInvalid();
+          return { valid: false, reason: 'session_deleted' };
         }
-        
-        return { valid: isValid };
+
+        console.log('✅ useSessionMonitor: Session still valid');
+        return { valid: true };
       } catch (error) {
-        console.error('Session validation error:', error);
+        console.error('⚠️ useSessionMonitor: Validation error:', error);
         if (onError) {
           onError(error);
         }
@@ -38,12 +82,40 @@ export const useSessionMonitor = (options = {}) => {
     enabled: enabled && !!auth.getToken(),
     refetchInterval,
     refetchIntervalInBackground: true,
-    retry: 1,
-    onError: (error) => {
-      console.error('Session monitor error:', error);
-      if (onError) {
-        onError(error);
+    retry: 2,
+    retryDelay: 5000,
+    staleTime: refetchInterval / 2, // Consider stale at half the interval
+  });
+
+  // Validate on visibility change (when user returns to tab)
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'visible' && auth.getToken()) {
+        console.log('👁️ useSessionMonitor: Tab visible - triggering validation');
+        queryClient.invalidateQueries({ queryKey: ['session-validation'] });
       }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, [enabled, queryClient]);
+
+  // Validate immediately on mount if enabled
+  useEffect(() => {
+    if (validateOnMount && enabled && auth.getToken()) {
+      queryClient.invalidateQueries({ queryKey: ['session-validation'] });
     }
-  });
+  }, [validateOnMount, enabled, queryClient]);
+
+  return {
+    ...query,
+    isSessionValid: query.data?.valid ?? true,
+    invalidationReason: query.data?.reason,
+    manualValidate: () => queryClient.invalidateQueries({ queryKey: ['session-validation'] }),
+  };
 };
+

package/token.js

@@ -102,6 +102,30 @@ function isExpired(token, bufferSeconds = 60) {
   return decoded.exp < now + bufferSeconds;
 }
 
+// ========== TOKEN EXPIRY UTILITIES ==========
+// Get the exact expiry time of a token as a Date object
+export function getTokenExpiryTime(token) {
+  if (!token) return null;
+  const decoded = decode(token);
+  if (!decoded?.exp) return null;
+  return new Date(decoded.exp * 1000);
+}
+
+// Get seconds until token expires (negative if already expired)
+export function getTimeUntilExpiry(token) {
+  if (!token) return -1;
+  const decoded = decode(token);
+  if (!decoded?.exp) return -1;
+  const now = Date.now() / 1000;
+  return Math.floor(decoded.exp - now);
+}
+
+// Check if token will expire within the next N seconds
+export function willExpireSoon(token, withinSeconds = 60) {
+  const timeLeft = getTimeUntilExpiry(token);
+  return timeLeft >= 0 && timeLeft <= withinSeconds;
+}
+
 export function setToken(token) {
   const previousToken = accessToken;
   accessToken = token || null;
@@ -152,8 +176,8 @@ const REFRESH_TOKEN_KEY = 'auth_refresh_token';
 
 function isHttpDevelopment() {
   try {
-    return typeof window !== 'undefined' && 
-           window.location?.protocol === 'http:';
+    return typeof window !== 'undefined' &&
+      window.location?.protocol === 'http:';
   } catch (err) {
     return false;
   }
@@ -190,7 +214,7 @@ export function getRefreshToken() {
       return null;
     }
   }
-  
+
   // In production, refresh token is in httpOnly cookie (not accessible via JS)
   // The refresh endpoint uses credentials: 'include' to send the cookie
   return null;
@@ -203,14 +227,14 @@ export function clearRefreshToken() {
   } catch (err) {
     // Ignore
   }
-  
+
   // Clear cookie (for production)
   try {
     document.cookie = `${REFRESH_COOKIE}=; Path=/; SameSite=Strict${secureAttribute()}; Expires=Thu, 01 Jan 1970 00:00:00 GMT`;
   } catch (err) {
     console.warn('Could not clear refresh token cookie:', err);
   }
-  
+
   // Clear sessionStorage
   try {
     sessionStorage.removeItem(REFRESH_COOKIE);