antaeus.keycloak.react 2.6.1 → 2.6.4

package/README.md

@@ -30,6 +30,7 @@ That's it! You now have full authentication with automatic token refresh.
 - Zero-config setup
 - Automatic token lifecycle management
 - Token refresh on app startup
+- Token refresh when suspended mobile/PWA sessions resume
 - Silent token renewal
 - Session monitoring UI
 - Protected routes
@@ -152,6 +153,8 @@ const { isEnabled, isConfigured, reason } = useKeycloakStatus();
 - **on-demand**: Only when API returns 401
 - **both** (recommended): Startup + 401 retry
 
+For mobile browsers and installed PWAs, token freshness is also checked when the app resumes from the background by default. Set `silentRenew.refreshOnResume` to `false` to disable this behavior.
+
 ## React Hooks
 
 ### useAuth()

package/dist/index.d.mts

@@ -121,6 +121,12 @@ interface SilentRenewConfig {
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Re-check token freshness when a suspended tab/PWA resumes.
+     * Useful for mobile browsers and installed PWAs where timers pause in the background.
+     * @default true
+     */
+    refreshOnResume?: boolean;
 }
 /**
  * Event callbacks for authentication lifecycle

package/dist/index.d.ts

@@ -121,6 +121,12 @@ interface SilentRenewConfig {
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Re-check token freshness when a suspended tab/PWA resumes.
+     * Useful for mobile browsers and installed PWAs where timers pause in the background.
+     * @default true
+     */
+    refreshOnResume?: boolean;
 }
 /**
  * Event callbacks for authentication lifecycle

package/dist/index.js

@@ -36,7 +36,8 @@ var defaultConfig = {
     // 30 days in seconds
     showLoadingIndicator: false,
     loadingMessage: "Refreshing session...",
-    useRefreshToken: true
+    useRefreshToken: true,
+    refreshOnResume: true
   },
   advanced: {
     responseType: "code",
@@ -165,6 +166,20 @@ var isTransientNetworkError = (error) => {
   }
   return message.includes("network") || message.includes("failed to fetch") || message.includes("fetch") || message.includes("timeout") || message.includes("temporarily unavailable") || message.includes("dns") || message.includes("offline");
 };
+var isInvalidRefreshTokenError = (error) => {
+  if (error instanceof oidcClientTs.ErrorResponse) {
+    const code = error.error?.toLowerCase?.();
+    if (code === "invalid_grant" || code === "invalid_token") {
+      return true;
+    }
+    const description = error.error_description?.toLowerCase?.();
+    if (description?.includes("refresh token")) {
+      return true;
+    }
+  }
+  const message = error.message?.toLowerCase?.() ?? "";
+  return message.includes("invalid_grant") || message.includes("refresh token") || message.includes("invalid token");
+};
 function useTokenLifecycle(options) {
   const {
     config,
@@ -177,6 +192,7 @@ function useTokenLifecycle(options) {
   const auth = useAuth();
   const [isRefreshing, setIsRefreshing] = react.useState(false);
   const [isRefreshTokenExpired, setIsRefreshTokenExpired] = react.useState(false);
+  const isRefreshingRef = react.useRef(false);
   const hasCheckedOnStartup = react.useRef(false);
   const supportsRefreshTokens = config.silentRenew?.useRefreshToken !== false;
   const [pendingRetry, setPendingRetry] = react.useState(null);
@@ -229,10 +245,11 @@ function useTokenLifecycle(options) {
     return elapsedSeconds >= maxLifetime;
   }, [config.silentRenew?.maxRefreshTokenLifetime, getStorageKey, log, storeFirstLoginTime]);
   const refreshToken = react.useCallback(async () => {
-    if (isRefreshing) {
+    if (isRefreshingRef.current) {
       log("Refresh already in progress, skipping");
       return;
     }
+    isRefreshingRef.current = true;
     setIsRefreshing(true);
     deferredRefreshReasonRef.current = null;
     try {
@@ -255,6 +272,20 @@ function useTokenLifecycle(options) {
       onRefreshSuccess?.();
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
+      if (isInvalidRefreshTokenError(err)) {
+        log("Refresh token rejected by the identity provider, clearing stored session");
+        setIsRefreshTokenExpired(true);
+        onRefreshTokenExpired?.();
+        const key = getStorageKey();
+        localStorage.removeItem(key);
+        try {
+          await auth.removeUser();
+        } catch (removeError) {
+          log("Error removing user after invalid refresh token:", removeError);
+        }
+        onRefreshError?.(err);
+        throw err;
+      }
       if (isTransientNetworkError(err)) {
         const reason = isNavigatorOffline() ? "offline" : "network";
         deferredRefreshReasonRef.current = reason;
@@ -274,10 +305,10 @@ function useTokenLifecycle(options) {
       onRefreshError?.(err);
       throw err;
     } finally {
+      isRefreshingRef.current = false;
       setIsRefreshing(false);
     }
   }, [
-    isRefreshing,
     auth,
     checkRefreshTokenLifetime,
     onRefreshStart,
@@ -285,6 +316,39 @@ function useTokenLifecycle(options) {
     onRefreshError,
     onRefreshTokenExpired,
     enqueueRetry,
+    getStorageKey,
+    log
+  ]);
+  const shouldRefreshOnResume = react.useCallback((reason) => {
+    const silentRenewEnabled = config.silentRenew?.enabled !== false;
+    const refreshOnResume = config.silentRenew?.refreshOnResume !== false;
+    const strategy = config.silentRenew?.refreshStrategy || "both";
+    const strategyAllowsResume = strategy === "startup" || strategy === "both";
+    const hasRefreshToken = Boolean(auth.user?.refresh_token);
+    if (!silentRenewEnabled || !refreshOnResume || !strategyAllowsResume) {
+      return false;
+    }
+    if (auth.isLoading) {
+      return false;
+    }
+    if (!auth.user) {
+      return false;
+    }
+    if (supportsRefreshTokens && !hasRefreshToken) {
+      log("Skipping resume token check because no refresh token is available:", reason);
+      return false;
+    }
+    if (reason !== "online" && typeof document !== "undefined" && document.visibilityState === "hidden") {
+      return false;
+    }
+    return true;
+  }, [
+    auth.isLoading,
+    auth.user,
+    config.silentRenew?.enabled,
+    config.silentRenew?.refreshOnResume,
+    config.silentRenew?.refreshStrategy,
+    supportsRefreshTokens,
     log
   ]);
   const checkAndRefreshTokens = react.useCallback(async () => {
@@ -434,6 +498,38 @@ function useTokenLifecycle(options) {
     checkAndRefreshTokens,
     log
   ]);
+  react.useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+    const runResumeCheck = (reason) => {
+      if (!shouldRefreshOnResume(reason)) {
+        return;
+      }
+      log("Running resume token check after:", reason);
+      checkAndRefreshTokens().catch((error) => {
+        log("Resume token check failed:", error);
+      });
+    };
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "visible") {
+        runResumeCheck("visibilitychange");
+      }
+    };
+    const handlePageShow = () => runResumeCheck("pageshow");
+    const handleFocus = () => runResumeCheck("focus");
+    const handleOnline = () => runResumeCheck("online");
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    window.addEventListener("pageshow", handlePageShow);
+    window.addEventListener("focus", handleFocus);
+    window.addEventListener("online", handleOnline);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("pageshow", handlePageShow);
+      window.removeEventListener("focus", handleFocus);
+      window.removeEventListener("online", handleOnline);
+    };
+  }, [checkAndRefreshTokens, log, shouldRefreshOnResume]);
   react.useEffect(() => {
     if (hasCheckedOnStartup.current) {
       const hasUser = Boolean(auth.user);
@@ -448,6 +544,11 @@ function useTokenLifecycle(options) {
       storeFirstLoginTime();
     }
   }, [auth.user, auth.isLoading, storeFirstLoginTime]);
+  react.useEffect(() => {
+    if (auth.isAuthenticated && isRefreshTokenExpired) {
+      setIsRefreshTokenExpired(false);
+    }
+  }, [auth.isAuthenticated, isRefreshTokenExpired]);
   react.useEffect(() => {
     if (!auth.isAuthenticated || auth.isLoading) {
       return;
@@ -851,7 +952,8 @@ var CONFIG_PRESETS = {
       maxRefreshTokenLifetime: 2592e3,
       // 30 days
       showLoadingIndicator: false,
-      loadingMessage: "Refreshing session..."
+      loadingMessage: "Refreshing session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -887,7 +989,8 @@ var CONFIG_PRESETS = {
       // 30 days
       showLoadingIndicator: true,
       // Show loading for better UX
-      loadingMessage: "Restoring your session..."
+      loadingMessage: "Restoring your session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -924,7 +1027,8 @@ var CONFIG_PRESETS = {
       // 24 hours only
       showLoadingIndicator: false,
       // Silent for security
-      loadingMessage: "Validating session..."
+      loadingMessage: "Validating session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -958,7 +1062,8 @@ var CONFIG_PRESETS = {
       maxRefreshTokenLifetime: 604800,
       // 7 days
       showLoadingIndicator: false,
-      loadingMessage: "Refreshing session..."
+      loadingMessage: "Refreshing session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -995,7 +1100,8 @@ var CONFIG_PRESETS = {
       // No limit (for convenience)
       showLoadingIndicator: true,
       // Show for debugging
-      loadingMessage: "[DEV] Refreshing tokens..."
+      loadingMessage: "[DEV] Refreshing tokens...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",