antaeus.keycloak.react 2.6.4 → 2.7.1

package/README.md

@@ -155,6 +155,27 @@ const { isEnabled, isConfigured, reason } = useKeycloakStatus();
 
 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.
 
+### Silent Renewal Fallback
+
+`oidc-client-ts` always uses a stored refresh token when one is available. To permit iframe renewal only when no refresh token is stored, opt in explicitly:
+
+```tsx
+<KeycloakProvider
+  authority="https://sso.example.com/realms/myrealm"
+  clientId="my-app"
+  config={{
+    silentRenew: {
+      allowIframeFallback: true,
+      transientRetry: { maxAttempts: 3, initialDelayMs: 1000, maxDelayMs: 30000 },
+    },
+  }}
+>
+  <App />
+</KeycloakProvider>
+```
+
+The application must host `silentRenew.silentRedirectUri` (default `/silent-renew.html`), register its exact URL with the identity provider, and allow the identity provider to load in an iframe. Browser privacy settings and third-party-cookie policy can still prevent iframe renewal. `useRefreshToken` remains for source compatibility but cannot force iframe-only renewal.
+
 ## React Hooks
 
 ### useAuth()
@@ -169,6 +190,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

@@ -116,11 +116,23 @@ interface SilentRenewConfig {
      */
     loadingMessage?: string;
     /**
-     * Enable using the refresh token grant instead of iframe silent renew when available.
-     * Keeps long-lived sessions alive even after the app is closed.
+     * Legacy compatibility setting. oidc-client-ts automatically uses a stored
+     * refresh token when one is available.
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Allow oidc-client-ts to use iframe silent renewal when no refresh token is stored.
+     * The application must host the configured silentRedirectUri and permit it in the
+     * identity provider redirect URI allowlist.
+     * @default false
+     */
+    allowIframeFallback?: boolean;
+    /**
+     * Retry policy for transient online silent-renew failures.
+     * Offline renewals wait for the browser's online event instead of using this policy.
+     */
+    transientRetry?: TransientRetryConfig;
     /**
      * Re-check token freshness when a suspended tab/PWA resumes.
      * Useful for mobile browsers and installed PWAs where timers pause in the background.
@@ -128,6 +140,14 @@ interface SilentRenewConfig {
      */
     refreshOnResume?: boolean;
 }
+interface TransientRetryConfig {
+    /** Maximum automatic retries after a transient online failure. @default 3 */
+    maxAttempts?: number;
+    /** Delay before the first retry in milliseconds. @default 1000 */
+    initialDelayMs?: number;
+    /** Maximum exponential backoff delay in milliseconds. @default 30000 */
+    maxDelayMs?: number;
+}
 /**
  * Event callbacks for authentication lifecycle
  */
@@ -1441,6 +1461,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
  */
@@ -1721,4 +1766,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

@@ -116,11 +116,23 @@ interface SilentRenewConfig {
      */
     loadingMessage?: string;
     /**
-     * Enable using the refresh token grant instead of iframe silent renew when available.
-     * Keeps long-lived sessions alive even after the app is closed.
+     * Legacy compatibility setting. oidc-client-ts automatically uses a stored
+     * refresh token when one is available.
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Allow oidc-client-ts to use iframe silent renewal when no refresh token is stored.
+     * The application must host the configured silentRedirectUri and permit it in the
+     * identity provider redirect URI allowlist.
+     * @default false
+     */
+    allowIframeFallback?: boolean;
+    /**
+     * Retry policy for transient online silent-renew failures.
+     * Offline renewals wait for the browser's online event instead of using this policy.
+     */
+    transientRetry?: TransientRetryConfig;
     /**
      * Re-check token freshness when a suspended tab/PWA resumes.
      * Useful for mobile browsers and installed PWAs where timers pause in the background.
@@ -128,6 +140,14 @@ interface SilentRenewConfig {
      */
     refreshOnResume?: boolean;
 }
+interface TransientRetryConfig {
+    /** Maximum automatic retries after a transient online failure. @default 3 */
+    maxAttempts?: number;
+    /** Delay before the first retry in milliseconds. @default 1000 */
+    initialDelayMs?: number;
+    /** Maximum exponential backoff delay in milliseconds. @default 30000 */
+    maxDelayMs?: number;
+}
 /**
  * Event callbacks for authentication lifecycle
  */
@@ -1441,6 +1461,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
  */
@@ -1721,4 +1766,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

@@ -37,6 +37,12 @@ var defaultConfig = {
     showLoadingIndicator: false,
     loadingMessage: "Refreshing session...",
     useRefreshToken: true,
+    allowIframeFallback: false,
+    transientRetry: {
+      maxAttempts: 3,
+      initialDelayMs: 1e3,
+      maxDelayMs: 3e4
+    },
     refreshOnResume: true
   },
   advanced: {
@@ -63,7 +69,6 @@ var KeycloakConfigBuilder = class {
     const config = this.mergeWithDefaults(userConfig);
     const storageType = config.advanced.storageType || "session";
     const storage = storageType === "local" ? window.localStorage : window.sessionStorage;
-    const { useRefreshToken } = config.silentRenew;
     const oidcSettings = {
       authority: config.authority,
       client_id: config.clientId,
@@ -81,9 +86,6 @@ var KeycloakConfigBuilder = class {
         response_mode: "query"
       }
     };
-    if (useRefreshToken !== void 0) {
-      oidcSettings.useRefreshToken = useRefreshToken;
-    }
     return oidcSettings;
   }
   /**
@@ -158,6 +160,9 @@ var useAuth = reactOidcContext.useAuth;
 
 // src/hooks/useTokenLifecycle.ts
 var STORAGE_KEY_PREFIX = "keycloak_first_login_";
+var DEFAULT_MAX_TRANSIENT_RETRIES = 3;
+var DEFAULT_RETRY_INITIAL_DELAY_MS = 1e3;
+var DEFAULT_RETRY_MAX_DELAY_MS = 3e4;
 var isNavigatorOffline = () => typeof navigator !== "undefined" && "onLine" in navigator && navigator.onLine === false;
 var isTransientNetworkError = (error) => {
   const message = error.message?.toLowerCase?.() ?? "";
@@ -193,13 +198,34 @@ function useTokenLifecycle(options) {
   const [isRefreshing, setIsRefreshing] = react.useState(false);
   const [isRefreshTokenExpired, setIsRefreshTokenExpired] = react.useState(false);
   const isRefreshingRef = react.useRef(false);
+  const isMountedRef = react.useRef(true);
   const hasCheckedOnStartup = react.useRef(false);
-  const supportsRefreshTokens = config.silentRenew?.useRefreshToken !== false;
+  const allowIframeFallback = config.silentRenew?.allowIframeFallback === true;
   const [pendingRetry, setPendingRetry] = react.useState(null);
   const deferredRefreshReasonRef = react.useRef(null);
+  const transientRetryAttemptsRef = react.useRef(0);
   const enqueueRetry = react.useCallback((reason) => {
     setPendingRetry((current) => current === reason ? current : reason);
   }, []);
+  const transientRetry = config.silentRenew?.transientRetry;
+  const maxTransientRetries = Math.max(
+    0,
+    transientRetry?.maxAttempts ?? DEFAULT_MAX_TRANSIENT_RETRIES
+  );
+  const retryInitialDelayMs = Math.max(
+    0,
+    transientRetry?.initialDelayMs ?? DEFAULT_RETRY_INITIAL_DELAY_MS
+  );
+  const retryMaxDelayMs = Math.max(
+    retryInitialDelayMs,
+    transientRetry?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS
+  );
+  react.useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
   const log = react.useCallback(
     (message, ...args) => {
       if (debug) {
@@ -269,6 +295,7 @@ function useTokenLifecycle(options) {
       log("Starting token refresh");
       await auth.signinSilent();
       log("Token refresh successful");
+      transientRetryAttemptsRef.current = 0;
       onRefreshSuccess?.();
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
@@ -291,7 +318,15 @@ function useTokenLifecycle(options) {
         deferredRefreshReasonRef.current = reason;
         if (reason === "offline") {
           log("Token refresh deferred because device is offline");
+          transientRetryAttemptsRef.current = 0;
         } else {
+          if (transientRetryAttemptsRef.current >= maxTransientRetries) {
+            deferredRefreshReasonRef.current = null;
+            log("Token refresh retry limit reached:", err.message);
+            onRefreshError?.(err);
+            return;
+          }
+          transientRetryAttemptsRef.current += 1;
           log(
             "Token refresh failed due to transient network issue, will retry automatically:",
             err.message
@@ -317,7 +352,8 @@ function useTokenLifecycle(options) {
     onRefreshTokenExpired,
     enqueueRetry,
     getStorageKey,
-    log
+    log,
+    maxTransientRetries
   ]);
   const shouldRefreshOnResume = react.useCallback((reason) => {
     const silentRenewEnabled = config.silentRenew?.enabled !== false;
@@ -334,7 +370,7 @@ function useTokenLifecycle(options) {
     if (!auth.user) {
       return false;
     }
-    if (supportsRefreshTokens && !hasRefreshToken) {
+    if (!hasRefreshToken && !allowIframeFallback) {
       log("Skipping resume token check because no refresh token is available:", reason);
       return false;
     }
@@ -348,7 +384,7 @@ function useTokenLifecycle(options) {
     config.silentRenew?.enabled,
     config.silentRenew?.refreshOnResume,
     config.silentRenew?.refreshStrategy,
-    supportsRefreshTokens,
+    allowIframeFallback,
     log
   ]);
   const checkAndRefreshTokens = react.useCallback(async () => {
@@ -421,10 +457,10 @@ function useTokenLifecycle(options) {
     }
     let cancelled = false;
     const executeRetry = () => {
-      if (cancelled) {
+      if (!isMountedRef.current) {
         return;
       }
-      if (isRefreshing) {
+      if (isRefreshingRef.current) {
         log("Skipping scheduled token refresh retry because a refresh is already in progress");
         return;
       }
@@ -448,19 +484,23 @@ function useTokenLifecycle(options) {
         window.removeEventListener("online", handleOnline);
       };
     }
+    const retryDelay = Math.min(
+      retryInitialDelayMs * 2 ** Math.max(0, transientRetryAttemptsRef.current - 1),
+      retryMaxDelayMs
+    );
     const timeoutId = window.setTimeout(() => {
       if (cancelled) {
         return;
       }
       log("Retrying token refresh after transient network failure delay");
       setPendingRetry(null);
-      executeRetry();
-    }, 5e3);
+      window.setTimeout(executeRetry, 0);
+    }, retryDelay);
     return () => {
       cancelled = true;
       window.clearTimeout(timeoutId);
     };
-  }, [pendingRetry, refreshToken, isRefreshing, log]);
+  }, [pendingRetry, refreshToken, log, retryInitialDelayMs, retryMaxDelayMs]);
   react.useEffect(() => {
     const strategy = config.silentRenew?.refreshStrategy || "both";
     const shouldCheckOnStartup = strategy === "startup" || strategy === "both";
@@ -472,10 +512,7 @@ function useTokenLifecycle(options) {
       return;
     }
     if (!auth.isAuthenticated) {
-      if (!supportsRefreshTokens) {
-        return;
-      }
-      if (!auth.user || !hasRefreshToken) {
+      if (!auth.user || !hasRefreshToken && !allowIframeFallback) {
         return;
       }
     }
@@ -484,7 +521,7 @@ function useTokenLifecycle(options) {
       "Running startup token check with strategy:",
       strategy,
       "using refresh token:",
-      !auth.isAuthenticated && supportsRefreshTokens
+      !auth.isAuthenticated && hasRefreshToken
     );
     checkAndRefreshTokens().catch((error) => {
       log("Startup token check failed:", error);
@@ -494,7 +531,7 @@ function useTokenLifecycle(options) {
     auth.isLoading,
     auth.user,
     config.silentRenew?.refreshStrategy,
-    supportsRefreshTokens,
+    allowIframeFallback,
     checkAndRefreshTokens,
     log
   ]);
@@ -534,11 +571,11 @@ function useTokenLifecycle(options) {
     if (hasCheckedOnStartup.current) {
       const hasUser = Boolean(auth.user);
       const hasRefreshToken = Boolean(auth.user?.refresh_token);
-      if (!auth.isAuthenticated && (!supportsRefreshTokens || !hasUser || !hasRefreshToken)) {
+      if (!auth.isAuthenticated && (!hasUser || !hasRefreshToken && !allowIframeFallback)) {
         hasCheckedOnStartup.current = false;
       }
     }
-  }, [auth.isAuthenticated, auth.user, supportsRefreshTokens]);
+  }, [auth.isAuthenticated, auth.user, allowIframeFallback]);
   react.useEffect(() => {
     if (auth.user && !auth.isLoading) {
       storeFirstLoginTime();
@@ -1995,6 +2032,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}.
@@ -5052,6 +5142,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;
@@ -5061,6 +5155,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