@usehercules/auth 1.0.39 → 1.0.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,8 @@
1
+ import * as react0 from "react";
1
2
  import * as react_oidc_context0 from "react-oidc-context";
2
- import { AuthContextProps, AuthProviderUserManagerProps, hasAuthParams, useAuth } from "react-oidc-context";
3
+ import { AuthContextProps as AuthContextProps$1, AuthProviderUserManagerProps, hasAuthParams } from "react-oidc-context";
3
4
  import * as oidc_client_ts0 from "oidc-client-ts";
4
- import { UserManagerSettings } from "oidc-client-ts";
5
+ import { UserManager, UserManagerSettings } from "oidc-client-ts";
5
6
  import * as react_jsx_runtime0 from "react/jsx-runtime";
6
7
 
7
8
  //#region src/react/auth-callback-hook.d.ts
@@ -29,6 +30,11 @@ type HerculesAuthProviderProps = Omit<AuthProviderUserManagerProps, "userManager
29
30
  authority: string;
30
31
  client_id: string;
31
32
  };
33
+ interface HerculesAuthProviderContext {
34
+ userManager: UserManager;
35
+ }
36
+ declare const HerculesAuthProviderContext: react0.Context<HerculesAuthProviderContext | null>;
37
+ declare function useHerculesAuthProvider(): HerculesAuthProviderContext;
32
38
  declare function HerculesAuthProvider({
33
39
  children,
34
40
  userManagerSettings,
@@ -58,5 +64,11 @@ declare function useUser(): {
58
64
  url_state?: string;
59
65
  };
60
66
  //#endregion
61
- export { AuthCallbackStatus, type AuthContextProps, HerculesAuthProvider, HerculesAuthProviderProps, UseAuthCallbackOptions, UseAuthCallbackResult, hasAuthParams, useAuth, useAuthCallback, useUser };
67
+ //#region src/react/use-auth.d.ts
68
+ interface AuthContextProps extends AuthContextProps$1 {
69
+ signout: () => Promise<void>;
70
+ }
71
+ declare function useAuth(): AuthContextProps;
72
+ //#endregion
73
+ export { AuthCallbackStatus, AuthContextProps, HerculesAuthProvider, HerculesAuthProviderProps, UseAuthCallbackOptions, UseAuthCallbackResult, hasAuthParams, useAuth, useAuthCallback, useHerculesAuthProvider, useUser };
62
74
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../../src/react/auth-callback-hook.tsx","../../src/react/HerculesAuthProvider.tsx","../../src/react/use-user.ts"],"sourcesContent":[],"mappings":";;;;;;;KAiBY,kBAAA;UAWK,sBAAA;;;iBAkBA;;;AA7BjB;AAWiB,UAsCA,qBAAA,CAtCsB;EAsCtB,MAAA,EAEP,kBAF4B;EAqDtB,KAAA,EAAA,MAAA,GAAA,IAAe;;;;EC1GnB,KAAA,EAAA,GAAA,GDsEG,OCtEH,CAAA,IAAA,CAAA;;AAA4B,iBD0GxB,eAAA,CC1GwB,OAAA,CAAA,ED2G7B,sBC3G6B,CAAA,ED4GrC,qBC5GqC;;;KAA5B,yBAAA,GAA4B,KACtC;wBAGsB,QAAQ;;;;ADApB,iBCwBI,oBAAA,CDxBc;EAAA,QAAA;EAAA,mBAAA;EAAA,SAAA;EAAA,SAAA;EAAA,GAAA;AAAA,CAAA,EC8B3B,yBD9B2B,CAAA,EC8BF,kBAAA,CAAA,GAAA,CAAA,OD9BE;;;iBEPd,OAAA,CAAA;;;;;;;EFOJ,KAAA,EEPW,mBAAA,CAAA,YAAA,GFOO,SAAA;EAWb,QAAA,CAAA,EAAA,MAAA;EAsCA,aAAA,CAAA,EAAA,MAAA,GAAqB,IAAA,GAAA,SAE5B;EAmDM,YAAA,CAAA,EAAA,MAAe,GAAA,SACpB;;;;EC3GC,OAAA,CAAA,ECHW,eAAA,CAAA,aAAA,GDGc,SAAA;EACnC,UAAA,CAAA,EAAA,MAAA;EADsC,KAAA,CAAA,EAAA,OAAA;EAIR,SAAA,CAAA,EAAA,MAAA;CAAR"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../../src/react/auth-callback-hook.tsx","../../src/react/HerculesAuthProvider.tsx","../../src/react/use-user.ts","../../src/react/use-auth.ts"],"sourcesContent":[],"mappings":";;;;;;;;KAiBY,kBAAA;UAWK,sBAAA;;;iBAkBA;;;;AA7BL,UAiDK,qBAAA,CAjDa;EAWb,MAAA,EAwCP,kBAxC6B;EAsCtB,KAAA,EAAA,MAAA,GAAA,IAAA;EAqDD,SAAA,EAAA,OAAe;;;eApChB;ACrEf;AACE,iBDwGc,eAAA,CCxGd,OAAA,CAAA,EDyGS,sBCzGT,CAAA,ED0GC,qBC1GD;;;KADU,yBAAA,GAA4B,KACtC;wBAGsB,QAAQ;;;;UAkBtB,2BAAA;EDnBE,WAAA,ECoBG,WDpBe;AAW9B;AAsCA,cC1BM,2BD4BI,EC5BuB,MAAA,CAAA,OD2ClB,CC3CkB,2BD2CX,GAAA,IAAA,CAAA;AAoCN,iBC5EA,uBAAA,CAAA,CD6EL,EC7E4B,2BD8EpC;iBChEa,oBAAA;;;;;;GAMb,4BAAyB,kBAAA,CAAA,GAAA,CAAA;;;iBCrDZ,OAAA,CAAA;;;;;;;SAAO,mBAAA,CAAA,YAAA;EFOX,QAAA,CAAA,EAAA,MAAA;EAWK,aAAA,CAAA,EAAA,MAAA,GAAsB,IAAA,GAAA,SAkBtB;EAoBA,YAAA,CAAA,EAAA,MAAA,GAAqB,SAAA;EAqDtB,aAAA,CAAA,EAAA,MAAe;;;YE7GR,eAAA,CAAA,aAAA;EDIX,UAAA,CAAA,EAAA,MAAA;EACV,KAAA,CAAA,EAAA,OAAA;EADsC,SAAA,CAAA,EAAA,MAAA;CAIR;;;UEXf,gBAAA,SAAyB;iBACzB;;iBAGD,OAAA,CAAA,GAAW"}
@@ -1,5 +1,5 @@
1
- import { useCallback, useEffect, useMemo, useRef, useState } from "react";
2
- import { AuthProvider, hasAuthParams, hasAuthParams as hasAuthParams$1, useAuth, useAuth as useAuth$1 } from "react-oidc-context";
1
+ import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
2
+ import { AuthProvider, hasAuthParams, hasAuthParams as hasAuthParams$1, useAuth as useAuth$1 } from "react-oidc-context";
3
3
  import { ConvexError } from "convex/values";
4
4
  import * as z from "zod";
5
5
  import { UserManager, WebStorageStateStore } from "oidc-client-ts";
@@ -50,6 +50,8 @@ function useAuthCallback(options = {}) {
50
50
  const hadAuthParams = useRef(hasAuthParams$1());
51
51
  const syncStarted = useRef(false);
52
52
  useEffect(() => {
53
+ mountedRef.current = true;
54
+ syncStarted.current = false;
53
55
  return () => {
54
56
  mountedRef.current = false;
55
57
  };
@@ -159,6 +161,12 @@ const DEFAULT_AUTH_CONFIG = {
159
161
  onSignoutCallback,
160
162
  onSigninCallback
161
163
  };
164
+ const HerculesAuthProviderContext = createContext(null);
165
+ function useHerculesAuthProvider() {
166
+ const context = useContext(HerculesAuthProviderContext);
167
+ if (!context) throw new Error("HerculesAuthProviderContext not found");
168
+ return context;
169
+ }
162
170
  /**
163
171
  * A wrapper React component which provides a {@link ReactAuthProvider}
164
172
  * configured with Hercules Auth.
@@ -177,11 +185,14 @@ function HerculesAuthProvider({ children, userManagerSettings, authority, client
177
185
  post_logout_redirect_uri: userManagerSettings?.post_logout_redirect_uri ?? window.location.origin,
178
186
  userStore: userManagerSettings?.userStore ?? new WebStorageStateStore({ store: window.localStorage })
179
187
  }));
180
- return /* @__PURE__ */ jsx(AuthProvider, {
181
- userManager,
182
- ...DEFAULT_AUTH_CONFIG,
183
- ...props,
184
- children
188
+ return /* @__PURE__ */ jsx(HerculesAuthProviderContext.Provider, {
189
+ value: { userManager },
190
+ children: /* @__PURE__ */ jsx(AuthProvider, {
191
+ userManager,
192
+ ...DEFAULT_AUTH_CONFIG,
193
+ ...props,
194
+ children
195
+ })
185
196
  });
186
197
  }
187
198
 
@@ -218,5 +229,27 @@ function useUser() {
218
229
  }
219
230
 
220
231
  //#endregion
221
- export { HerculesAuthProvider, hasAuthParams, useAuth, useAuthCallback, useUser };
232
+ //#region src/react/use-auth.ts
233
+ function useAuth() {
234
+ const { userManager } = useHerculesAuthProvider();
235
+ const auth = useAuth$1();
236
+ const { signoutRedirect, removeUser } = auth;
237
+ const signout = useCallback(async () => {
238
+ if (await userManager.metadataService.getEndSessionEndpoint() != null) await signoutRedirect();
239
+ else await removeUser();
240
+ }, [
241
+ userManager,
242
+ signoutRedirect,
243
+ removeUser
244
+ ]);
245
+ return useMemo(() => {
246
+ return {
247
+ ...auth,
248
+ signout
249
+ };
250
+ }, [auth, signout]);
251
+ }
252
+
253
+ //#endregion
254
+ export { HerculesAuthProvider, hasAuthParams, useAuth, useAuthCallback, useHerculesAuthProvider, useUser };
222
255
  //# sourceMappingURL=index.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":["useAuth","hasAuthParams","DEFAULT_AUTH_CONFIG: Partial<HerculesAuthProviderProps>","ReactAuthProvider","useAuth"],"sources":["../../src/react/auth-callback-hook.tsx","../../src/react/HerculesAuthProvider.tsx","../../src/react/use-user.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useState, useRef, useCallback } from \"react\";\nimport { useAuth, hasAuthParams } from \"react-oidc-context\";\nimport { ConvexError } from \"convex/values\";\nimport * as z from \"zod\";\n\nconst DEFAULT_TIMEOUT_MS = 20000; // 20 second timeout\n\nconst convexErrorSchema = z.object({\n message: z.string(),\n});\n\n/**\n * Authentication callback status states\n * @public\n */\nexport type AuthCallbackStatus =\n | \"processing-oauth\" // OIDC is processing the callback\n | \"waiting-backend\" // OIDC authenticated, waiting for backend\n | \"syncing\" // Syncing user with backend (e.g., creating user record)\n | \"success\" // All done\n | \"error\"; // Something went wrong\n\n/**\n * Options for the useAuthCallback hook\n * @public\n */\nexport interface UseAuthCallbackOptions {\n /**\n * Timeout in milliseconds before the callback is considered failed.\n * @default 20000\n */\n timeoutMs?: number;\n\n /**\n * Whether the backend (e.g., Convex) is authenticated.\n * The hook will wait for this to be true before calling onSync.\n */\n isBackendAuthenticated?: boolean;\n\n /**\n * Called when the backend is authenticated and ready to sync.\n * Use this to create/update the user in your backend.\n * Return a promise that resolves when sync is complete.\n */\n onSync?: () => Promise<void>;\n\n /**\n * Called when authentication is successful and sync is complete.\n * Use this to redirect the user.\n */\n onSuccess?: () => void;\n\n /**\n * Called when OIDC is not authenticated and there are no auth params.\n * This typically means the user navigated directly to the callback page.\n * Use this to redirect them away.\n */\n onNoAuthParams?: () => void;\n}\n\n/**\n * Return type for the useAuthCallback hook\n * @public\n */\nexport interface UseAuthCallbackResult {\n /** Current status of the auth callback flow */\n status: AuthCallbackStatus;\n\n /** Error message if status is \"error\" */\n error: string | null;\n\n /** Whether the auth callback is still in progress */\n isLoading: boolean;\n\n /** Whether the auth callback completed successfully */\n isSuccess: boolean;\n\n /** Whether there was an error */\n isError: boolean;\n\n /** Retry the authentication flow by redirecting to the auth provider */\n retry: () => Promise<void>;\n}\n\n/**\n * A hook for handling OAuth/OIDC callback flows.\n *\n * This hook manages the complete authentication callback lifecycle:\n * 1. Processing the OAuth callback from the identity provider\n * 2. Waiting for backend authentication (e.g., Convex)\n * 3. Syncing user data with your backend\n * 4. Handling success and error states\n *\n * @example\n * ```tsx\n * function AuthCallback() {\n * const navigate = useNavigate();\n * const { isAuthenticated } = useConvexAuth();\n * const updateUser = useMutation(api.users.updateCurrentUser);\n *\n * const { status, error, retry } = useAuthCallback({\n * isBackendAuthenticated: isAuthenticated,\n * onSync: () => updateUser(),\n * onSuccess: () => navigate(\"/\", { replace: true }),\n * onNoAuthParams: () => navigate(\"/\", { replace: true }),\n * });\n *\n * if (status === \"error\") {\n * return <ErrorState message={error} onRetry={retry} />;\n * }\n *\n * return <LoadingSpinner />;\n * }\n * ```\n *\n * @public\n */\nexport function useAuthCallback(\n options: UseAuthCallbackOptions = {},\n): UseAuthCallbackResult {\n const {\n timeoutMs = DEFAULT_TIMEOUT_MS,\n isBackendAuthenticated = true,\n onSync,\n onSuccess,\n onNoAuthParams,\n } = options;\n\n const {\n isLoading: isAuthLoading,\n isAuthenticated: isOidcAuthenticated,\n error: oidcError,\n signinRedirect,\n } = useAuth();\n\n const [status, setStatus] = useState<AuthCallbackStatus>(\"processing-oauth\");\n const [error, setError] = useState<string | null>(null);\n\n // Track mount state to prevent state updates after unmount\n const mountedRef = useRef(true);\n // Track if we had auth params on mount (won't change during lifecycle)\n const hadAuthParams = useRef(hasAuthParams());\n // Track if we've already started sync to prevent double execution\n const syncStarted = useRef(false);\n\n // Cleanup on unmount\n useEffect(() => {\n return () => {\n mountedRef.current = false;\n };\n }, []);\n\n // Timeout protection with state awareness\n useEffect(() => {\n if (status === \"success\" || status === \"error\") return;\n\n const timeout = setTimeout(() => {\n if (mountedRef.current) {\n setStatus(\"error\");\n setError(\"Authentication timed out. Please try again.\");\n }\n }, timeoutMs);\n\n return () => clearTimeout(timeout);\n }, [status, timeoutMs]);\n\n // Track OIDC authentication progression\n useEffect(() => {\n // Don't update if we're already past processing or in an error state\n if (status !== \"processing-oauth\" && status !== \"waiting-backend\") return;\n\n // Handle OIDC errors\n if (oidcError) {\n setStatus(\"error\");\n setError(oidcError.message || \"Authentication failed\");\n return;\n }\n\n // No auth params and not authenticated - navigated here directly\n if (!hadAuthParams.current && !isAuthLoading && !isOidcAuthenticated) {\n onNoAuthParams?.();\n return;\n }\n\n // OIDC is done loading and authenticated - move to waiting for backend\n if (\n !isAuthLoading &&\n isOidcAuthenticated &&\n status === \"processing-oauth\"\n ) {\n setStatus(\"waiting-backend\");\n return;\n }\n\n // OIDC finished but not authenticated (and we had auth params)\n // Wait a bit before declaring failure to avoid race conditions\n if (\n hadAuthParams.current &&\n !isAuthLoading &&\n !isOidcAuthenticated &&\n !oidcError &&\n status === \"processing-oauth\"\n ) {\n // Use a small delay to avoid race condition during OIDC state transitions\n const failureTimeout = setTimeout(() => {\n if (mountedRef.current && !isOidcAuthenticated) {\n setStatus(\"error\");\n setError(\"Authentication was cancelled or failed. Please try again.\");\n }\n }, 500);\n\n return () => clearTimeout(failureTimeout);\n }\n\n return;\n }, [isAuthLoading, isOidcAuthenticated, oidcError, status, onNoAuthParams]);\n\n // Sync with backend once backend is authenticated\n useEffect(() => {\n if (status !== \"waiting-backend\" || !isBackendAuthenticated) return;\n if (syncStarted.current) return;\n\n syncStarted.current = true;\n\n async function performSync() {\n if (!mountedRef.current) return;\n\n setStatus(\"syncing\");\n\n try {\n if (onSync) {\n await onSync();\n }\n\n if (mountedRef.current) {\n setStatus(\"success\");\n }\n } catch (err) {\n console.error(\"Auth callback sync failed:\", err);\n\n if (!mountedRef.current) return;\n\n if (err instanceof ConvexError) {\n // try to extract the error message from the convex error\n const parseResult = convexErrorSchema.safeParse(err.data);\n if (parseResult.success) {\n setStatus(\"error\");\n setError(parseResult.data.message);\n return;\n }\n }\n\n // Check if it's an authentication error\n const errorMessage =\n err instanceof Error\n ? err.message\n : \"Failed to complete authentication. Please try again.\";\n\n setStatus(\"error\");\n setError(errorMessage);\n }\n }\n\n performSync();\n }, [status, isBackendAuthenticated, onSync]);\n\n // Handle successful completion\n useEffect(() => {\n if (status === \"success\") {\n onSuccess?.();\n }\n }, [status, onSuccess]);\n\n // Retry handler\n const retry = useCallback(async () => {\n try {\n await signinRedirect();\n } catch (err) {\n console.error(\"Failed to restart auth:\", err);\n }\n }, [signinRedirect]);\n\n return {\n status,\n error,\n isLoading: status !== \"success\" && status !== \"error\",\n isSuccess: status === \"success\",\n isError: status === \"error\",\n retry,\n };\n}\n","\"use client\";\n\nimport { useState } from \"react\";\nimport {\n AuthProvider as ReactAuthProvider,\n type AuthProviderUserManagerProps,\n} from \"react-oidc-context\";\nimport {\n UserManager,\n WebStorageStateStore,\n type UserManagerSettings,\n} from \"oidc-client-ts\";\n\nexport type HerculesAuthProviderProps = Omit<\n AuthProviderUserManagerProps,\n \"userManager\"\n> & {\n userManagerSettings?: Partial<UserManagerSettings>;\n authority: string;\n client_id: string;\n};\n\nfunction onSigninCallback() {\n window.history.replaceState({}, document.title, window.location.pathname);\n}\n\nfunction onSignoutCallback() {\n window.location.pathname = \"\";\n}\n\nconst DEFAULT_AUTH_CONFIG: Partial<HerculesAuthProviderProps> = {\n onSignoutCallback,\n onSigninCallback,\n};\n\n/**\n * A wrapper React component which provides a {@link ReactAuthProvider}\n * configured with Hercules Auth.\n *\n * @public\n */\nexport function HerculesAuthProvider({\n children,\n userManagerSettings,\n authority,\n client_id,\n ...props\n}: HerculesAuthProviderProps) {\n const [userManager] = useState(\n () =>\n new UserManager({\n ...userManagerSettings,\n authority: userManagerSettings?.authority ?? authority,\n client_id: userManagerSettings?.client_id ?? client_id,\n prompt: userManagerSettings?.prompt ?? \"select_account\",\n response_type: userManagerSettings?.response_type ?? \"code\",\n scope:\n userManagerSettings?.scope ?? \"openid profile email offline_access\",\n redirect_uri:\n userManagerSettings?.redirect_uri ??\n `${window.location.origin}/auth/callback`,\n post_logout_redirect_uri:\n userManagerSettings?.post_logout_redirect_uri ??\n window.location.origin,\n userStore:\n userManagerSettings?.userStore ??\n new WebStorageStateStore({ store: window.localStorage }),\n }),\n );\n\n return (\n <ReactAuthProvider\n userManager={userManager}\n {...DEFAULT_AUTH_CONFIG}\n {...props}\n >\n {children}\n </ReactAuthProvider>\n );\n}\n","\"use client\";\n\nimport { useMemo } from \"react\";\nimport { useAuth } from \"react-oidc-context\";\n\n/**\n * A hook that returns the current user if authenticated\n *\n * @public\n */\nexport function useUser() {\n const { user, isLoading, error, isAuthenticated } = useAuth();\n\n return useMemo(() => {\n const id = user?.profile.sub;\n const name = user?.profile.name;\n const email = user?.profile.email;\n const avatar = user?.profile.picture;\n return {\n ...(user ?? {}),\n id,\n name,\n email,\n avatar,\n isAuthenticated,\n isLoading,\n error,\n };\n }, [user, isAuthenticated, isLoading, error]);\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"index.mjs","names":["useAuth","hasAuthParams","DEFAULT_AUTH_CONFIG: Partial<HerculesAuthProviderProps>","ReactAuthProvider","useAuth","useOidcAuth"],"sources":["../../src/react/auth-callback-hook.tsx","../../src/react/HerculesAuthProvider.tsx","../../src/react/use-user.ts","../../src/react/use-auth.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useState, useRef, useCallback } from \"react\";\nimport { useAuth, hasAuthParams } from \"react-oidc-context\";\nimport { ConvexError } from \"convex/values\";\nimport * as z from \"zod\";\n\nconst DEFAULT_TIMEOUT_MS = 20000; // 20 second timeout\n\nconst convexErrorSchema = z.object({\n message: z.string(),\n});\n\n/**\n * Authentication callback status states\n * @public\n */\nexport type AuthCallbackStatus =\n | \"processing-oauth\" // OIDC is processing the callback\n | \"waiting-backend\" // OIDC authenticated, waiting for backend\n | \"syncing\" // Syncing user with backend (e.g., creating user record)\n | \"success\" // All done\n | \"error\"; // Something went wrong\n\n/**\n * Options for the useAuthCallback hook\n * @public\n */\nexport interface UseAuthCallbackOptions {\n /**\n * Timeout in milliseconds before the callback is considered failed.\n * @default 20000\n */\n timeoutMs?: number;\n\n /**\n * Whether the backend (e.g., Convex) is authenticated.\n * The hook will wait for this to be true before calling onSync.\n */\n isBackendAuthenticated?: boolean;\n\n /**\n * Called when the backend is authenticated and ready to sync.\n * Use this to create/update the user in your backend.\n * Return a promise that resolves when sync is complete.\n */\n onSync?: () => Promise<void>;\n\n /**\n * Called when authentication is successful and sync is complete.\n * Use this to redirect the user.\n */\n onSuccess?: () => void;\n\n /**\n * Called when OIDC is not authenticated and there are no auth params.\n * This typically means the user navigated directly to the callback page.\n * Use this to redirect them away.\n */\n onNoAuthParams?: () => void;\n}\n\n/**\n * Return type for the useAuthCallback hook\n * @public\n */\nexport interface UseAuthCallbackResult {\n /** Current status of the auth callback flow */\n status: AuthCallbackStatus;\n\n /** Error message if status is \"error\" */\n error: string | null;\n\n /** Whether the auth callback is still in progress */\n isLoading: boolean;\n\n /** Whether the auth callback completed successfully */\n isSuccess: boolean;\n\n /** Whether there was an error */\n isError: boolean;\n\n /** Retry the authentication flow by redirecting to the auth provider */\n retry: () => Promise<void>;\n}\n\n/**\n * A hook for handling OAuth/OIDC callback flows.\n *\n * This hook manages the complete authentication callback lifecycle:\n * 1. Processing the OAuth callback from the identity provider\n * 2. Waiting for backend authentication (e.g., Convex)\n * 3. Syncing user data with your backend\n * 4. Handling success and error states\n *\n * @example\n * ```tsx\n * function AuthCallback() {\n * const navigate = useNavigate();\n * const { isAuthenticated } = useConvexAuth();\n * const updateUser = useMutation(api.users.updateCurrentUser);\n *\n * const { status, error, retry } = useAuthCallback({\n * isBackendAuthenticated: isAuthenticated,\n * onSync: () => updateUser(),\n * onSuccess: () => navigate(\"/\", { replace: true }),\n * onNoAuthParams: () => navigate(\"/\", { replace: true }),\n * });\n *\n * if (status === \"error\") {\n * return <ErrorState message={error} onRetry={retry} />;\n * }\n *\n * return <LoadingSpinner />;\n * }\n * ```\n *\n * @public\n */\nexport function useAuthCallback(\n options: UseAuthCallbackOptions = {},\n): UseAuthCallbackResult {\n const {\n timeoutMs = DEFAULT_TIMEOUT_MS,\n isBackendAuthenticated = true,\n onSync,\n onSuccess,\n onNoAuthParams,\n } = options;\n\n const {\n isLoading: isAuthLoading,\n isAuthenticated: isOidcAuthenticated,\n error: oidcError,\n signinRedirect,\n } = useAuth();\n\n const [status, setStatus] = useState<AuthCallbackStatus>(\"processing-oauth\");\n const [error, setError] = useState<string | null>(null);\n\n // Track mount state to prevent state updates after unmount\n const mountedRef = useRef(true);\n // Track if we had auth params on mount (won't change during lifecycle)\n const hadAuthParams = useRef(hasAuthParams());\n // Track if we've already started sync to prevent double execution\n const syncStarted = useRef(false);\n\n // Reset on mount, cleanup on unmount\n useEffect(() => {\n mountedRef.current = true;\n syncStarted.current = false;\n return () => {\n mountedRef.current = false;\n };\n }, []);\n\n // Timeout protection with state awareness\n useEffect(() => {\n if (status === \"success\" || status === \"error\") return;\n\n const timeout = setTimeout(() => {\n if (mountedRef.current) {\n setStatus(\"error\");\n setError(\"Authentication timed out. Please try again.\");\n }\n }, timeoutMs);\n\n return () => clearTimeout(timeout);\n }, [status, timeoutMs]);\n\n // Track OIDC authentication progression\n useEffect(() => {\n // Don't update if we're already past processing or in an error state\n if (status !== \"processing-oauth\" && status !== \"waiting-backend\") return;\n\n // Handle OIDC errors\n if (oidcError) {\n setStatus(\"error\");\n setError(oidcError.message || \"Authentication failed\");\n return;\n }\n\n // No auth params and not authenticated - navigated here directly\n if (!hadAuthParams.current && !isAuthLoading && !isOidcAuthenticated) {\n onNoAuthParams?.();\n return;\n }\n\n // OIDC is done loading and authenticated - move to waiting for backend\n if (\n !isAuthLoading &&\n isOidcAuthenticated &&\n status === \"processing-oauth\"\n ) {\n setStatus(\"waiting-backend\");\n return;\n }\n\n // OIDC finished but not authenticated (and we had auth params)\n // Wait a bit before declaring failure to avoid race conditions\n if (\n hadAuthParams.current &&\n !isAuthLoading &&\n !isOidcAuthenticated &&\n !oidcError &&\n status === \"processing-oauth\"\n ) {\n // Use a small delay to avoid race condition during OIDC state transitions\n const failureTimeout = setTimeout(() => {\n if (mountedRef.current && !isOidcAuthenticated) {\n setStatus(\"error\");\n setError(\"Authentication was cancelled or failed. Please try again.\");\n }\n }, 500);\n\n return () => clearTimeout(failureTimeout);\n }\n\n return;\n }, [isAuthLoading, isOidcAuthenticated, oidcError, status, onNoAuthParams]);\n\n // Sync with backend once backend is authenticated\n useEffect(() => {\n if (status !== \"waiting-backend\" || !isBackendAuthenticated) return;\n if (syncStarted.current) return;\n\n syncStarted.current = true;\n\n async function performSync() {\n if (!mountedRef.current) return;\n\n setStatus(\"syncing\");\n\n try {\n if (onSync) {\n await onSync();\n }\n\n if (mountedRef.current) {\n setStatus(\"success\");\n }\n } catch (err) {\n console.error(\"Auth callback sync failed:\", err);\n\n if (!mountedRef.current) return;\n\n if (err instanceof ConvexError) {\n // try to extract the error message from the convex error\n const parseResult = convexErrorSchema.safeParse(err.data);\n if (parseResult.success) {\n setStatus(\"error\");\n setError(parseResult.data.message);\n return;\n }\n }\n\n // Check if it's an authentication error\n const errorMessage =\n err instanceof Error\n ? err.message\n : \"Failed to complete authentication. Please try again.\";\n\n setStatus(\"error\");\n setError(errorMessage);\n }\n }\n\n performSync();\n }, [status, isBackendAuthenticated, onSync]);\n\n // Handle successful completion\n useEffect(() => {\n if (status === \"success\") {\n onSuccess?.();\n }\n }, [status, onSuccess]);\n\n // Retry handler\n const retry = useCallback(async () => {\n try {\n await signinRedirect();\n } catch (err) {\n console.error(\"Failed to restart auth:\", err);\n }\n }, [signinRedirect]);\n\n return {\n status,\n error,\n isLoading: status !== \"success\" && status !== \"error\",\n isSuccess: status === \"success\",\n isError: status === \"error\",\n retry,\n };\n}\n","\"use client\";\n\nimport { useState } from \"react\";\nimport {\n AuthProvider as ReactAuthProvider,\n type AuthProviderUserManagerProps,\n} from \"react-oidc-context\";\nimport {\n UserManager,\n WebStorageStateStore,\n type UserManagerSettings,\n} from \"oidc-client-ts\";\nimport { createContext, useContext } from \"react\";\n\nexport type HerculesAuthProviderProps = Omit<\n AuthProviderUserManagerProps,\n \"userManager\"\n> & {\n userManagerSettings?: Partial<UserManagerSettings>;\n authority: string;\n client_id: string;\n};\n\nfunction onSigninCallback() {\n window.history.replaceState({}, document.title, window.location.pathname);\n}\n\nfunction onSignoutCallback() {\n window.location.pathname = \"\";\n}\n\nconst DEFAULT_AUTH_CONFIG: Partial<HerculesAuthProviderProps> = {\n onSignoutCallback,\n onSigninCallback,\n};\n\ninterface HerculesAuthProviderContext {\n userManager: UserManager;\n}\n\nconst HerculesAuthProviderContext =\n createContext<HerculesAuthProviderContext | null>(null);\n\nexport function useHerculesAuthProvider() {\n const context = useContext(HerculesAuthProviderContext);\n if (!context) {\n throw new Error(\"HerculesAuthProviderContext not found\");\n }\n return context;\n}\n\n/**\n * A wrapper React component which provides a {@link ReactAuthProvider}\n * configured with Hercules Auth.\n *\n * @public\n */\nexport function HerculesAuthProvider({\n children,\n userManagerSettings,\n authority,\n client_id,\n ...props\n}: HerculesAuthProviderProps) {\n const [userManager] = useState(\n () =>\n new UserManager({\n ...userManagerSettings,\n authority: userManagerSettings?.authority ?? authority,\n client_id: userManagerSettings?.client_id ?? client_id,\n prompt: userManagerSettings?.prompt ?? \"select_account\",\n response_type: userManagerSettings?.response_type ?? \"code\",\n scope:\n userManagerSettings?.scope ?? \"openid profile email offline_access\",\n redirect_uri:\n userManagerSettings?.redirect_uri ??\n `${window.location.origin}/auth/callback`,\n post_logout_redirect_uri:\n userManagerSettings?.post_logout_redirect_uri ??\n window.location.origin,\n userStore:\n userManagerSettings?.userStore ??\n new WebStorageStateStore({ store: window.localStorage }),\n }),\n );\n\n return (\n <HerculesAuthProviderContext.Provider value={{ userManager }}>\n <ReactAuthProvider\n userManager={userManager}\n {...DEFAULT_AUTH_CONFIG}\n {...props}\n >\n {children}\n </ReactAuthProvider>\n </HerculesAuthProviderContext.Provider>\n );\n}\n","\"use client\";\n\nimport { useMemo } from \"react\";\nimport { useAuth } from \"react-oidc-context\";\n\n/**\n * A hook that returns the current user if authenticated\n *\n * @public\n */\nexport function useUser() {\n const { user, isLoading, error, isAuthenticated } = useAuth();\n\n return useMemo(() => {\n const id = user?.profile.sub;\n const name = user?.profile.name;\n const email = user?.profile.email;\n const avatar = user?.profile.picture;\n return {\n ...(user ?? {}),\n id,\n name,\n email,\n avatar,\n isAuthenticated,\n isLoading,\n error,\n };\n }, [user, isAuthenticated, isLoading, error]);\n}\n","import {\n useAuth as useOidcAuth,\n type AuthContextProps as OidcAuthContextProps,\n} from \"react-oidc-context\";\nimport { useHerculesAuthProvider } from \"./HerculesAuthProvider\";\nimport { useCallback, useMemo } from \"react\";\n\nexport interface AuthContextProps extends OidcAuthContextProps {\n signout: () => Promise<void>;\n}\n\nexport function useAuth(): AuthContextProps {\n const { userManager } = useHerculesAuthProvider();\n const auth = useOidcAuth();\n\n const { signoutRedirect, removeUser } = auth;\n const signout = useCallback(async () => {\n const endpoint = await userManager.metadataService.getEndSessionEndpoint();\n if (endpoint != null) {\n await signoutRedirect();\n } else {\n await removeUser();\n }\n }, [userManager, signoutRedirect, removeUser]);\n\n return useMemo(() => {\n return {\n ...auth,\n signout,\n } satisfies AuthContextProps;\n }, [auth, signout]);\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usehercules/auth",
3
- "version": "1.0.39",
3
+ "version": "1.0.41",
4
4
  "description": "Authentication utilities for Hercules applications using OIDC",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -28,22 +28,28 @@
28
28
  "dependencies": {
29
29
  "oidc-client-ts": "^3.4.1",
30
30
  "react-oidc-context": "^3.3.0",
31
- "zod": "^4.1.12"
31
+ "zod": "^4.3.6"
32
32
  },
33
33
  "peerDependencies": {
34
- "convex": "^1.29.3",
34
+ "convex": "^1.29.0",
35
35
  "react": "^18.0.0 || ^19.0.0"
36
36
  },
37
37
  "devDependencies": {
38
- "@types/react": "^19.2.6",
39
- "convex": "^1.29.3",
40
- "react": "^19.2.0",
41
- "tsdown": "^0.16.6",
42
- "typescript": "^5.9.3"
38
+ "@testing-library/jest-dom": "^6.9.1",
39
+ "@testing-library/react": "^16.3.2",
40
+ "@types/react": "^19.2.14",
41
+ "@types/react-dom": "^19.2.3",
42
+ "convex": "^1.32.0",
43
+ "jsdom": "^28.1.0",
44
+ "react": "^19.2.4",
45
+ "react-dom": "^19.2.4",
46
+ "tsdown": "^0.18.4",
47
+ "typescript": "^5.9.3",
48
+ "vitest": "^4.0.18"
43
49
  },
44
50
  "scripts": {
45
51
  "build": "tsdown",
46
52
  "dev": "tsdown --watch",
47
- "test": "exit 0"
53
+ "test": "vitest --run"
48
54
  }
49
55
  }
@@ -10,6 +10,7 @@ import {
10
10
  WebStorageStateStore,
11
11
  type UserManagerSettings,
12
12
  } from "oidc-client-ts";
13
+ import { createContext, useContext } from "react";
13
14
 
14
15
  export type HerculesAuthProviderProps = Omit<
15
16
  AuthProviderUserManagerProps,
@@ -33,6 +34,21 @@ const DEFAULT_AUTH_CONFIG: Partial<HerculesAuthProviderProps> = {
33
34
  onSigninCallback,
34
35
  };
35
36
 
37
+ interface HerculesAuthProviderContext {
38
+ userManager: UserManager;
39
+ }
40
+
41
+ const HerculesAuthProviderContext =
42
+ createContext<HerculesAuthProviderContext | null>(null);
43
+
44
+ export function useHerculesAuthProvider() {
45
+ const context = useContext(HerculesAuthProviderContext);
46
+ if (!context) {
47
+ throw new Error("HerculesAuthProviderContext not found");
48
+ }
49
+ return context;
50
+ }
51
+
36
52
  /**
37
53
  * A wrapper React component which provides a {@link ReactAuthProvider}
38
54
  * configured with Hercules Auth.
@@ -69,12 +85,14 @@ export function HerculesAuthProvider({
69
85
  );
70
86
 
71
87
  return (
72
- <ReactAuthProvider
73
- userManager={userManager}
74
- {...DEFAULT_AUTH_CONFIG}
75
- {...props}
76
- >
77
- {children}
78
- </ReactAuthProvider>
88
+ <HerculesAuthProviderContext.Provider value={{ userManager }}>
89
+ <ReactAuthProvider
90
+ userManager={userManager}
91
+ {...DEFAULT_AUTH_CONFIG}
92
+ {...props}
93
+ >
94
+ {children}
95
+ </ReactAuthProvider>
96
+ </HerculesAuthProviderContext.Provider>
79
97
  );
80
98
  }
@@ -0,0 +1,281 @@
1
+ import { describe, it, expect, vi, beforeEach } from "vitest";
2
+ import { renderHook, act, waitFor, configure } from "@testing-library/react";
3
+ import { useAuthCallback } from "./auth-callback-hook.js";
4
+
5
+ // Run every test under StrictMode so the double-mount cycle
6
+ // (mount → unmount → remount) is always exercised.
7
+ configure({ reactStrictMode: true });
8
+
9
+ // ---- Mocks ----
10
+
11
+ const mockSigninRedirect = vi.fn();
12
+
13
+ let mockAuthState = {
14
+ isLoading: true,
15
+ isAuthenticated: false,
16
+ error: undefined as Error | undefined,
17
+ signinRedirect: mockSigninRedirect,
18
+ };
19
+
20
+ let mockHasAuthParams = true;
21
+
22
+ vi.mock("react-oidc-context", () => ({
23
+ useAuth: () => mockAuthState,
24
+ hasAuthParams: () => mockHasAuthParams,
25
+ }));
26
+
27
+ vi.mock("convex/values", () => ({
28
+ ConvexError: class ConvexError extends Error {
29
+ data: unknown;
30
+ constructor(data: unknown) {
31
+ super("ConvexError");
32
+ this.data = data;
33
+ }
34
+ },
35
+ }));
36
+
37
+ // ---- Helpers ----
38
+
39
+ function setAuthState(overrides: Partial<typeof mockAuthState>) {
40
+ mockAuthState = { ...mockAuthState, ...overrides };
41
+ }
42
+
43
+ // ---- Tests ----
44
+
45
+ beforeEach(() => {
46
+ mockAuthState = {
47
+ isLoading: true,
48
+ isAuthenticated: false,
49
+ error: undefined,
50
+ signinRedirect: mockSigninRedirect,
51
+ };
52
+ mockHasAuthParams = true;
53
+ mockSigninRedirect.mockReset();
54
+ });
55
+
56
+ describe("useAuthCallback", () => {
57
+ describe("initial state", () => {
58
+ it("starts in processing-oauth status", () => {
59
+ const { result } = renderHook(() => useAuthCallback());
60
+ expect(result.current.status).toBe("processing-oauth");
61
+ expect(result.current.isLoading).toBe(true);
62
+ expect(result.current.isSuccess).toBe(false);
63
+ expect(result.current.isError).toBe(false);
64
+ expect(result.current.error).toBeNull();
65
+ });
66
+ });
67
+
68
+ describe("happy path (full flow)", () => {
69
+ it("reaches success when OIDC authenticates and backend is ready", async () => {
70
+ const onSync = vi.fn().mockResolvedValue(undefined);
71
+ const onSuccess = vi.fn();
72
+
73
+ setAuthState({ isLoading: false, isAuthenticated: true });
74
+
75
+ const { result } = renderHook(() =>
76
+ useAuthCallback({
77
+ isBackendAuthenticated: true,
78
+ onSync,
79
+ onSuccess,
80
+ }),
81
+ );
82
+
83
+ await waitFor(() => {
84
+ expect(result.current.status).toBe("success");
85
+ });
86
+
87
+ expect(onSync).toHaveBeenCalledOnce();
88
+ expect(onSuccess).toHaveBeenCalledOnce();
89
+ expect(result.current.isLoading).toBe(false);
90
+ expect(result.current.isSuccess).toBe(true);
91
+ });
92
+
93
+ it("transitions through waiting-backend when OIDC finishes after mount", async () => {
94
+ const onSync = vi.fn().mockResolvedValue(undefined);
95
+
96
+ // Start with OIDC still loading
97
+ const { result, rerender } = renderHook(() =>
98
+ useAuthCallback({
99
+ isBackendAuthenticated: true,
100
+ onSync,
101
+ }),
102
+ );
103
+
104
+ expect(result.current.status).toBe("processing-oauth");
105
+
106
+ // OIDC finishes
107
+ setAuthState({ isLoading: false, isAuthenticated: true });
108
+ rerender();
109
+
110
+ await waitFor(() => {
111
+ expect(result.current.status).toBe("success");
112
+ });
113
+
114
+ expect(onSync).toHaveBeenCalledOnce();
115
+ });
116
+ });
117
+
118
+ describe("timeout", () => {
119
+ it("errors after timeout when stuck", () => {
120
+ vi.useFakeTimers();
121
+
122
+ try {
123
+ const { result } = renderHook(() =>
124
+ useAuthCallback({ timeoutMs: 5000 }),
125
+ );
126
+
127
+ expect(result.current.status).toBe("processing-oauth");
128
+
129
+ act(() => {
130
+ vi.advanceTimersByTime(5000);
131
+ });
132
+
133
+ expect(result.current.status).toBe("error");
134
+ expect(result.current.error).toBe(
135
+ "Authentication timed out. Please try again.",
136
+ );
137
+ expect(result.current.isError).toBe(true);
138
+ expect(result.current.isLoading).toBe(false);
139
+ } finally {
140
+ vi.useRealTimers();
141
+ }
142
+ });
143
+
144
+ it("does not timeout after reaching success", async () => {
145
+ vi.useFakeTimers();
146
+
147
+ try {
148
+ const onSync = vi.fn().mockResolvedValue(undefined);
149
+
150
+ setAuthState({ isLoading: false, isAuthenticated: true });
151
+
152
+ const { result } = renderHook(() =>
153
+ useAuthCallback({
154
+ isBackendAuthenticated: true,
155
+ onSync,
156
+ timeoutMs: 5000,
157
+ }),
158
+ );
159
+
160
+ // Flush microtasks for async sync to complete
161
+ await act(async () => {
162
+ await vi.advanceTimersByTimeAsync(100);
163
+ });
164
+
165
+ expect(result.current.status).toBe("success");
166
+
167
+ // Advance past timeout — should still be success, not error
168
+ act(() => {
169
+ vi.advanceTimersByTime(10000);
170
+ });
171
+
172
+ expect(result.current.status).toBe("success");
173
+ } finally {
174
+ vi.useRealTimers();
175
+ }
176
+ });
177
+ });
178
+
179
+ describe("OIDC errors", () => {
180
+ it("transitions to error when OIDC reports an error", () => {
181
+ setAuthState({ error: new Error("OIDC failed") });
182
+
183
+ const { result } = renderHook(() => useAuthCallback());
184
+
185
+ expect(result.current.status).toBe("error");
186
+ expect(result.current.error).toBe("OIDC failed");
187
+ });
188
+ });
189
+
190
+ describe("no auth params", () => {
191
+ it("calls onNoAuthParams when no auth params and not authenticated", () => {
192
+ mockHasAuthParams = false;
193
+ setAuthState({ isLoading: false, isAuthenticated: false });
194
+
195
+ const onNoAuthParams = vi.fn();
196
+
197
+ renderHook(() => useAuthCallback({ onNoAuthParams }));
198
+
199
+ expect(onNoAuthParams).toHaveBeenCalled();
200
+ });
201
+ });
202
+
203
+ describe("sync errors", () => {
204
+ it("transitions to error when onSync throws", async () => {
205
+ const onSync = vi.fn().mockRejectedValue(new Error("Sync boom"));
206
+
207
+ setAuthState({ isLoading: false, isAuthenticated: true });
208
+
209
+ const { result } = renderHook(() =>
210
+ useAuthCallback({
211
+ isBackendAuthenticated: true,
212
+ onSync,
213
+ }),
214
+ );
215
+
216
+ await waitFor(() => {
217
+ expect(result.current.status).toBe("error");
218
+ });
219
+
220
+ expect(result.current.error).toBe("Sync boom");
221
+ });
222
+ });
223
+
224
+ describe("waiting for backend", () => {
225
+ it("stays in waiting-backend until isBackendAuthenticated is true", async () => {
226
+ const onSync = vi.fn().mockResolvedValue(undefined);
227
+
228
+ setAuthState({ isLoading: false, isAuthenticated: true });
229
+
230
+ const { result, rerender } = renderHook(
231
+ ({ backendAuth }: { backendAuth: boolean }) =>
232
+ useAuthCallback({
233
+ isBackendAuthenticated: backendAuth,
234
+ onSync,
235
+ }),
236
+ { initialProps: { backendAuth: false } },
237
+ );
238
+
239
+ // Should be in waiting-backend (OIDC done, but backend not ready)
240
+ expect(result.current.status).toBe("waiting-backend");
241
+ expect(onSync).not.toHaveBeenCalled();
242
+
243
+ // Backend becomes authenticated
244
+ rerender({ backendAuth: true });
245
+
246
+ await waitFor(() => {
247
+ expect(result.current.status).toBe("success");
248
+ });
249
+
250
+ expect(onSync).toHaveBeenCalledOnce();
251
+ });
252
+ });
253
+
254
+ describe("retry", () => {
255
+ it("calls signinRedirect on retry", async () => {
256
+ mockSigninRedirect.mockResolvedValue(undefined);
257
+
258
+ const { result } = renderHook(() => useAuthCallback());
259
+
260
+ await act(async () => {
261
+ await result.current.retry();
262
+ });
263
+
264
+ expect(mockSigninRedirect).toHaveBeenCalledOnce();
265
+ });
266
+ });
267
+
268
+ describe("no onSync provided", () => {
269
+ it("goes straight to success when onSync is omitted", async () => {
270
+ setAuthState({ isLoading: false, isAuthenticated: true });
271
+
272
+ const { result } = renderHook(() =>
273
+ useAuthCallback({ isBackendAuthenticated: true }),
274
+ );
275
+
276
+ await waitFor(() => {
277
+ expect(result.current.status).toBe("success");
278
+ });
279
+ });
280
+ });
281
+ });
@@ -145,8 +145,10 @@ export function useAuthCallback(
145
145
  // Track if we've already started sync to prevent double execution
146
146
  const syncStarted = useRef(false);
147
147
 
148
- // Cleanup on unmount
148
+ // Reset on mount, cleanup on unmount
149
149
  useEffect(() => {
150
+ mountedRef.current = true;
151
+ syncStarted.current = false;
150
152
  return () => {
151
153
  mountedRef.current = false;
152
154
  };
@@ -1,10 +1,7 @@
1
1
  export * from "./auth-callback-hook";
2
2
  export * from "./HerculesAuthProvider";
3
3
  export * from "./use-user";
4
+ export * from "./use-auth";
4
5
 
5
6
  // rexports of react-oidc-context
6
- export {
7
- type AuthContextProps,
8
- hasAuthParams,
9
- useAuth,
10
- } from "react-oidc-context";
7
+ export { hasAuthParams } from "react-oidc-context";
@@ -0,0 +1,125 @@
1
+ import { describe, it, expect, vi, beforeEach } from "vitest";
2
+ import { renderHook, act, configure } from "@testing-library/react";
3
+ import { useAuth } from "./use-auth.js";
4
+
5
+ configure({ reactStrictMode: true });
6
+
7
+ // ---- Mocks ----
8
+
9
+ const mockSignoutRedirect = vi.fn();
10
+ const mockRemoveUser = vi.fn();
11
+ const mockGetEndSessionEndpoint = vi.fn();
12
+
13
+ const mockUserManager = {
14
+ metadataService: {
15
+ getEndSessionEndpoint: mockGetEndSessionEndpoint,
16
+ },
17
+ };
18
+
19
+ let mockAuthState: Record<string, unknown> = {};
20
+
21
+ vi.mock("react-oidc-context", () => ({
22
+ useAuth: () => mockAuthState,
23
+ }));
24
+
25
+ vi.mock("./HerculesAuthProvider", () => ({
26
+ useHerculesAuthProvider: () => ({ userManager: mockUserManager }),
27
+ }));
28
+
29
+ // ---- Helpers ----
30
+
31
+ function setAuthState(overrides: Record<string, unknown>) {
32
+ mockAuthState = {
33
+ isLoading: false,
34
+ isAuthenticated: true,
35
+ signoutRedirect: mockSignoutRedirect,
36
+ removeUser: mockRemoveUser,
37
+ ...overrides,
38
+ };
39
+ }
40
+
41
+ // ---- Tests ----
42
+
43
+ beforeEach(() => {
44
+ setAuthState({});
45
+ mockSignoutRedirect.mockReset();
46
+ mockRemoveUser.mockReset();
47
+ mockGetEndSessionEndpoint.mockReset();
48
+ });
49
+
50
+ describe("useAuth", () => {
51
+ it("returns the underlying auth state with a signout method", () => {
52
+ const { result } = renderHook(() => useAuth());
53
+
54
+ expect(result.current.isAuthenticated).toBe(true);
55
+ expect(result.current.isLoading).toBe(false);
56
+ expect(typeof result.current.signout).toBe("function");
57
+ });
58
+
59
+ it("spreads all properties from the oidc auth context", () => {
60
+ setAuthState({ isAuthenticated: false, isLoading: true });
61
+
62
+ const { result } = renderHook(() => useAuth());
63
+
64
+ expect(result.current.isAuthenticated).toBe(false);
65
+ expect(result.current.isLoading).toBe(true);
66
+ });
67
+
68
+ describe("signout", () => {
69
+ it("calls signoutRedirect when end session endpoint exists", async () => {
70
+ mockGetEndSessionEndpoint.mockResolvedValue(
71
+ "https://auth.example.com/logout",
72
+ );
73
+ mockSignoutRedirect.mockResolvedValue(undefined);
74
+
75
+ const { result } = renderHook(() => useAuth());
76
+
77
+ await act(async () => {
78
+ await result.current.signout();
79
+ });
80
+
81
+ expect(mockGetEndSessionEndpoint).toHaveBeenCalled();
82
+ expect(mockSignoutRedirect).toHaveBeenCalledOnce();
83
+ expect(mockRemoveUser).not.toHaveBeenCalled();
84
+ });
85
+
86
+ it("calls removeUser when end session endpoint is null", async () => {
87
+ mockGetEndSessionEndpoint.mockResolvedValue(null);
88
+
89
+ const { result } = renderHook(() => useAuth());
90
+
91
+ await act(async () => {
92
+ await result.current.signout();
93
+ });
94
+
95
+ expect(mockGetEndSessionEndpoint).toHaveBeenCalled();
96
+ expect(mockSignoutRedirect).not.toHaveBeenCalled();
97
+ expect(mockRemoveUser).toHaveBeenCalledOnce();
98
+ });
99
+
100
+ it("calls removeUser when end session endpoint is undefined", async () => {
101
+ mockGetEndSessionEndpoint.mockResolvedValue(undefined);
102
+
103
+ const { result } = renderHook(() => useAuth());
104
+
105
+ await act(async () => {
106
+ await result.current.signout();
107
+ });
108
+
109
+ expect(mockSignoutRedirect).not.toHaveBeenCalled();
110
+ expect(mockRemoveUser).toHaveBeenCalledOnce();
111
+ });
112
+ });
113
+
114
+ describe("memoization", () => {
115
+ it("returns a stable signout reference across rerenders with same deps", () => {
116
+ const { result, rerender } = renderHook(() => useAuth());
117
+
118
+ const firstSignout = result.current.signout;
119
+ rerender();
120
+ const secondSignout = result.current.signout;
121
+
122
+ expect(firstSignout).toBe(secondSignout);
123
+ });
124
+ });
125
+ });
@@ -0,0 +1,32 @@
1
+ import {
2
+ useAuth as useOidcAuth,
3
+ type AuthContextProps as OidcAuthContextProps,
4
+ } from "react-oidc-context";
5
+ import { useHerculesAuthProvider } from "./HerculesAuthProvider";
6
+ import { useCallback, useMemo } from "react";
7
+
8
+ export interface AuthContextProps extends OidcAuthContextProps {
9
+ signout: () => Promise<void>;
10
+ }
11
+
12
+ export function useAuth(): AuthContextProps {
13
+ const { userManager } = useHerculesAuthProvider();
14
+ const auth = useOidcAuth();
15
+
16
+ const { signoutRedirect, removeUser } = auth;
17
+ const signout = useCallback(async () => {
18
+ const endpoint = await userManager.metadataService.getEndSessionEndpoint();
19
+ if (endpoint != null) {
20
+ await signoutRedirect();
21
+ } else {
22
+ await removeUser();
23
+ }
24
+ }, [userManager, signoutRedirect, removeUser]);
25
+
26
+ return useMemo(() => {
27
+ return {
28
+ ...auth,
29
+ signout,
30
+ } satisfies AuthContextProps;
31
+ }, [auth, signout]);
32
+ }
package/tsdown.config.ts CHANGED
@@ -4,7 +4,6 @@ export default defineConfig((options) => [
4
4
  {
5
5
  ...options,
6
6
  entry: ["src/react/index.ts", "src/convex-react/index.ts"],
7
- external: ["react", "react/jsx-runtime", "convex"],
8
7
  dts: true,
9
8
  sourcemap: true,
10
9
  exports: true,