antaeus.keycloak.react 2.6.4 → 2.7.0

package/README.md

@@ -169,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

@@ -1441,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
  */
@@ -1721,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

@@ -1441,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
  */
@@ -1721,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

@@ -1995,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}.
@@ -5052,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;
@@ -5061,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