antaeus.keycloak.react 2.6.2 → 2.7.0

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()
@@ -166,6 +169,55 @@ auth.signinRedirect()
 auth.signoutRedirect()
 ```
 
+### useStoredOidcSession()
+
+Inspect the OIDC user record stored by `oidc-client-ts` without duplicating the
+library's storage-key format in an application. This is useful when an app wants
+to decide whether to attempt a silent session restore or show a login prompt
+immediately.
+
+```tsx
+import { useAuth, useStoredOidcSession } from 'antaeus.keycloak.react';
+
+function AuthGate() {
+  const auth = useAuth();
+  const storedSession = useStoredOidcSession();
+
+  if (!auth.isAuthenticated && !storedSession.hasRefreshToken) {
+    return <button onClick={() => auth.signinRedirect()}>Sign in</button>;
+  }
+
+  return <App />;
+}
+```
+
+The hook reads from the same storage configured on `KeycloakProvider` via
+`advanced.storageType`. It does not trigger network calls or change provider
+state.
+
+For non-React code or tests, use the exported helpers directly:
+
+```ts
+import {
+  getOidcUserStorageKey,
+  getStoredOidcSession,
+  getStoredOidcUser,
+  hasStoredOidcRefreshToken,
+} from 'antaeus.keycloak.react';
+
+const storageKey = getOidcUserStorageKey(authority, clientId);
+const storedUser = getStoredOidcUser({ authority, clientId, storage: localStorage });
+const session = getStoredOidcSession({ authority, clientId, storage: localStorage });
+const canTrySilentRestore = hasStoredOidcRefreshToken({
+  authority,
+  clientId,
+  storage: localStorage,
+});
+```
+
+These helpers are additive APIs. They do not alter default provider behavior,
+token refresh, silent renew, or session monitoring.
+
 ## Token Bridge (Non-React Consumers)
 
 Expose tokens to plain TypeScript modules (SignalR, fetch helpers, etc.):

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
@@ -1435,6 +1441,31 @@ interface UseTokenLifecycleReturn {
  */
 declare function useTokenLifecycle(options: UseTokenLifecycleOptions): UseTokenLifecycleReturn;
 
+interface StoredOidcSessionUser {
+    access_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+    [key: string]: unknown;
+}
+interface StoredOidcSessionInfo {
+    storageKey: string | null;
+    storedUser: StoredOidcSessionUser | null;
+    hasStoredUser: boolean;
+    hasRefreshToken: boolean;
+}
+interface StoredOidcSessionArgs {
+    authority?: string;
+    clientId?: string;
+    storage?: Pick<Storage, 'getItem'>;
+}
+declare const getOidcUserStorageKey: (authority?: string, clientId?: string) => string | null;
+declare const getStoredOidcUser: ({ authority, clientId, storage, }: StoredOidcSessionArgs) => StoredOidcSessionUser | null;
+declare const hasStoredOidcRefreshToken: (args: StoredOidcSessionArgs) => boolean;
+declare const getStoredOidcSession: (args: StoredOidcSessionArgs) => StoredOidcSessionInfo;
+
+type UseStoredOidcSessionReturn = StoredOidcSessionInfo;
+declare const useStoredOidcSession: () => UseStoredOidcSessionReturn;
+
 /**
  * Options for configuring the SignalR connection
  */
@@ -1715,4 +1746,4 @@ declare function pollForToken(apiBaseUrl: string, deviceCode: string): Promise<T
  */
 declare function fetchUserInfo(apiBaseUrl: string, accessToken: string): Promise<any>;
 
-export { type AdvancedOidcOptions, CONFIG_PRESETS, type ConfigPreset, type DeviceAuthorizationResponse, type DeviceFlowError, DeviceLogin, type DeviceLoginProps, type EventCallbacks, type FeatureFlags, type KeycloakConfig, KeycloakConfigBuilder, type KeycloakDisabledReason, KeycloakProvider, type KeycloakProviderFullConfigProps, type KeycloakProviderProps, type KeycloakProviderZeroConfigProps, type KeycloakStatus, KeycloakStatusProvider, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type PolicyContext, type PolicyFunction, ProtectedRoute, type ProtectedRouteProps, SessionMonitor, type SessionMonitorProps, type SilentRenewConfig, TokenBridge, type TokenBridgeProps, TokenBridgeSync, TokenLifecycleManager, type TokenLifecycleManagerProps, type TokenListener, type TokenResponse, type UseProtectedFetchOptions, type UseProtectedFetchReturn, type UseRolesReturn, type UseScopesReturn, type UseSignalRConnectionOptions, type UseSignalRConnectionReturn, type UseTokenLifecycleOptions, type UseTokenLifecycleReturn, UserProfile, type UserProfileProps, createTokenBridge, defaultConfig, defaultTokenBridge, fetchUserInfo, getConfigFromEnv, getConfigPreset, mergeWithPreset, pollForToken, requestDeviceCode, useAuth, useKeycloakStatus, useProtectedFetch, useRoles, useScopes, useSignalRConnection, useTokenLifecycle };
+export { type AdvancedOidcOptions, CONFIG_PRESETS, type ConfigPreset, type DeviceAuthorizationResponse, type DeviceFlowError, DeviceLogin, type DeviceLoginProps, type EventCallbacks, type FeatureFlags, type KeycloakConfig, KeycloakConfigBuilder, type KeycloakDisabledReason, KeycloakProvider, type KeycloakProviderFullConfigProps, type KeycloakProviderProps, type KeycloakProviderZeroConfigProps, type KeycloakStatus, KeycloakStatusProvider, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type PolicyContext, type PolicyFunction, ProtectedRoute, type ProtectedRouteProps, SessionMonitor, type SessionMonitorProps, type SilentRenewConfig, type StoredOidcSessionArgs, type StoredOidcSessionInfo, type StoredOidcSessionUser, TokenBridge, type TokenBridgeProps, TokenBridgeSync, TokenLifecycleManager, type TokenLifecycleManagerProps, type TokenListener, type TokenResponse, type UseProtectedFetchOptions, type UseProtectedFetchReturn, type UseRolesReturn, type UseScopesReturn, type UseSignalRConnectionOptions, type UseSignalRConnectionReturn, type UseStoredOidcSessionReturn, type UseTokenLifecycleOptions, type UseTokenLifecycleReturn, UserProfile, type UserProfileProps, createTokenBridge, defaultConfig, defaultTokenBridge, fetchUserInfo, getConfigFromEnv, getConfigPreset, getOidcUserStorageKey, getStoredOidcSession, getStoredOidcUser, hasStoredOidcRefreshToken, mergeWithPreset, pollForToken, requestDeviceCode, useAuth, useKeycloakStatus, useProtectedFetch, useRoles, useScopes, useSignalRConnection, useStoredOidcSession, useTokenLifecycle };

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
@@ -1435,6 +1441,31 @@ interface UseTokenLifecycleReturn {
  */
 declare function useTokenLifecycle(options: UseTokenLifecycleOptions): UseTokenLifecycleReturn;
 
+interface StoredOidcSessionUser {
+    access_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+    [key: string]: unknown;
+}
+interface StoredOidcSessionInfo {
+    storageKey: string | null;
+    storedUser: StoredOidcSessionUser | null;
+    hasStoredUser: boolean;
+    hasRefreshToken: boolean;
+}
+interface StoredOidcSessionArgs {
+    authority?: string;
+    clientId?: string;
+    storage?: Pick<Storage, 'getItem'>;
+}
+declare const getOidcUserStorageKey: (authority?: string, clientId?: string) => string | null;
+declare const getStoredOidcUser: ({ authority, clientId, storage, }: StoredOidcSessionArgs) => StoredOidcSessionUser | null;
+declare const hasStoredOidcRefreshToken: (args: StoredOidcSessionArgs) => boolean;
+declare const getStoredOidcSession: (args: StoredOidcSessionArgs) => StoredOidcSessionInfo;
+
+type UseStoredOidcSessionReturn = StoredOidcSessionInfo;
+declare const useStoredOidcSession: () => UseStoredOidcSessionReturn;
+
 /**
  * Options for configuring the SignalR connection
  */
@@ -1715,4 +1746,4 @@ declare function pollForToken(apiBaseUrl: string, deviceCode: string): Promise<T
  */
 declare function fetchUserInfo(apiBaseUrl: string, accessToken: string): Promise<any>;
 
-export { type AdvancedOidcOptions, CONFIG_PRESETS, type ConfigPreset, type DeviceAuthorizationResponse, type DeviceFlowError, DeviceLogin, type DeviceLoginProps, type EventCallbacks, type FeatureFlags, type KeycloakConfig, KeycloakConfigBuilder, type KeycloakDisabledReason, KeycloakProvider, type KeycloakProviderFullConfigProps, type KeycloakProviderProps, type KeycloakProviderZeroConfigProps, type KeycloakStatus, KeycloakStatusProvider, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type PolicyContext, type PolicyFunction, ProtectedRoute, type ProtectedRouteProps, SessionMonitor, type SessionMonitorProps, type SilentRenewConfig, TokenBridge, type TokenBridgeProps, TokenBridgeSync, TokenLifecycleManager, type TokenLifecycleManagerProps, type TokenListener, type TokenResponse, type UseProtectedFetchOptions, type UseProtectedFetchReturn, type UseRolesReturn, type UseScopesReturn, type UseSignalRConnectionOptions, type UseSignalRConnectionReturn, type UseTokenLifecycleOptions, type UseTokenLifecycleReturn, UserProfile, type UserProfileProps, createTokenBridge, defaultConfig, defaultTokenBridge, fetchUserInfo, getConfigFromEnv, getConfigPreset, mergeWithPreset, pollForToken, requestDeviceCode, useAuth, useKeycloakStatus, useProtectedFetch, useRoles, useScopes, useSignalRConnection, useTokenLifecycle };
+export { type AdvancedOidcOptions, CONFIG_PRESETS, type ConfigPreset, type DeviceAuthorizationResponse, type DeviceFlowError, DeviceLogin, type DeviceLoginProps, type EventCallbacks, type FeatureFlags, type KeycloakConfig, KeycloakConfigBuilder, type KeycloakDisabledReason, KeycloakProvider, type KeycloakProviderFullConfigProps, type KeycloakProviderProps, type KeycloakProviderZeroConfigProps, type KeycloakStatus, KeycloakStatusProvider, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type PolicyContext, type PolicyFunction, ProtectedRoute, type ProtectedRouteProps, SessionMonitor, type SessionMonitorProps, type SilentRenewConfig, type StoredOidcSessionArgs, type StoredOidcSessionInfo, type StoredOidcSessionUser, TokenBridge, type TokenBridgeProps, TokenBridgeSync, TokenLifecycleManager, type TokenLifecycleManagerProps, type TokenListener, type TokenResponse, type UseProtectedFetchOptions, type UseProtectedFetchReturn, type UseRolesReturn, type UseScopesReturn, type UseSignalRConnectionOptions, type UseSignalRConnectionReturn, type UseStoredOidcSessionReturn, type UseTokenLifecycleOptions, type UseTokenLifecycleReturn, UserProfile, type UserProfileProps, createTokenBridge, defaultConfig, defaultTokenBridge, fetchUserInfo, getConfigFromEnv, getConfigPreset, getOidcUserStorageKey, getStoredOidcSession, getStoredOidcUser, hasStoredOidcRefreshToken, mergeWithPreset, pollForToken, requestDeviceCode, useAuth, useKeycloakStatus, useProtectedFetch, useRoles, useScopes, useSignalRConnection, useStoredOidcSession, useTokenLifecycle };

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",
@@ -191,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);
@@ -243,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 {
@@ -302,10 +305,10 @@ function useTokenLifecycle(options) {
       onRefreshError?.(err);
       throw err;
     } finally {
+      isRefreshingRef.current = false;
       setIsRefreshing(false);
     }
   }, [
-    isRefreshing,
     auth,
     checkRefreshTokenLifetime,
     onRefreshStart,
@@ -316,6 +319,38 @@ function useTokenLifecycle(options) {
     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 () => {
     if (!auth.user) {
       log("No user session, skipping token check");
@@ -463,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);
@@ -885,7 +952,8 @@ var CONFIG_PRESETS = {
       maxRefreshTokenLifetime: 2592e3,
       // 30 days
       showLoadingIndicator: false,
-      loadingMessage: "Refreshing session..."
+      loadingMessage: "Refreshing session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -921,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",
@@ -958,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",
@@ -992,7 +1062,8 @@ var CONFIG_PRESETS = {
       maxRefreshTokenLifetime: 604800,
       // 7 days
       showLoadingIndicator: false,
-      loadingMessage: "Refreshing session..."
+      loadingMessage: "Refreshing session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -1029,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",
@@ -1923,6 +1995,59 @@ function useProtectedFetch(options = {}) {
   };
 }
 
+// src/utils/storedOidcSession.ts
+var getOidcUserStorageKey = (authority, clientId) => {
+  if (!authority || !clientId) {
+    return null;
+  }
+  return `oidc.user:${authority}:${clientId}`;
+};
+var getStoredOidcUser = ({
+  authority,
+  clientId,
+  storage
+}) => {
+  const storageKey = getOidcUserStorageKey(authority, clientId);
+  if (!storageKey || !storage) {
+    return null;
+  }
+  try {
+    const storedUser = storage.getItem(storageKey);
+    if (!storedUser) {
+      return null;
+    }
+    return JSON.parse(storedUser);
+  } catch {
+    return null;
+  }
+};
+var hasStoredOidcRefreshToken = (args) => {
+  const storedUser = getStoredOidcUser(args);
+  return typeof storedUser?.refresh_token === "string" && storedUser.refresh_token.length > 0;
+};
+var getStoredOidcSession = (args) => {
+  const storageKey = getOidcUserStorageKey(args.authority, args.clientId);
+  const storedUser = getStoredOidcUser(args);
+  return {
+    storageKey,
+    storedUser,
+    hasStoredUser: storedUser !== null,
+    hasRefreshToken: typeof storedUser?.refresh_token === "string" && storedUser.refresh_token.length > 0
+  };
+};
+
+// src/hooks/useStoredOidcSession.ts
+var useStoredOidcSession = () => {
+  const auth = useAuth();
+  const { storage } = useStorageConfig();
+  const authority = auth.settings.authority;
+  const clientId = auth.settings.client_id;
+  return react.useMemo(
+    () => getStoredOidcSession({ authority, clientId, storage }),
+    [authority, clientId, storage]
+  );
+};
+
 // node_modules/@microsoft/signalr/dist/esm/Errors.js
 var HttpError = class extends Error {
   /** Constructs a new instance of {@link @microsoft/signalr.HttpError}.
@@ -4980,6 +5105,10 @@ exports.defaultTokenBridge = defaultTokenBridge;
 exports.fetchUserInfo = fetchUserInfo;
 exports.getConfigFromEnv = getConfigFromEnv;
 exports.getConfigPreset = getConfigPreset;
+exports.getOidcUserStorageKey = getOidcUserStorageKey;
+exports.getStoredOidcSession = getStoredOidcSession;
+exports.getStoredOidcUser = getStoredOidcUser;
+exports.hasStoredOidcRefreshToken = hasStoredOidcRefreshToken;
 exports.mergeWithPreset = mergeWithPreset;
 exports.pollForToken = pollForToken;
 exports.requestDeviceCode = requestDeviceCode;
@@ -4989,6 +5118,7 @@ exports.useProtectedFetch = useProtectedFetch;
 exports.useRoles = useRoles;
 exports.useScopes = useScopes;
 exports.useSignalRConnection = useSignalRConnection;
+exports.useStoredOidcSession = useStoredOidcSession;
 exports.useTokenLifecycle = useTokenLifecycle;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map