refactor: Update Auth0Provider and related classes to improve client instantiation and session management

subhankarmaiti · subhankarmaiti · commit e5200e212994 · 2025-07-14T03:23:50.000+05:30
diff --git a/src/hooks/Auth0Provider.tsx b/src/hooks/Auth0Provider.tsx
@@ -35,7 +35,8 @@ export const Auth0Provider = ({
   children,
   ...options
 }: PropsWithChildren<Auth0Options>) => {
-  const client = useMemo(() => new Auth0(options), [options]);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const client = useMemo(() => new Auth0(options), []);
   const [state, dispatch] = useReducer(reducer, {
     user: null,
     error: null,
diff --git a/src/platforms/web/adapters/WebAuth0Client.ts b/src/platforms/web/adapters/WebAuth0Client.ts
@@ -1,4 +1,8 @@
-import { Auth0Client, type Auth0ClientOptions } from '@auth0/auth0-spa-js';
+import {
+  Auth0Client,
+  type Auth0ClientOptions,
+  type LogoutOptions,
+} from '@auth0/auth0-spa-js';
 import type { IAuth0Client, IUsersClient } from '../../../core/interfaces';
 import type { WebAuth0Options } from '../../../types/platform-specific';
 import { WebWebAuthProvider } from './WebWebAuthProvider';
@@ -8,102 +12,116 @@ import {
   ManagementApiOrchestrator,
 } from '../../../core/services';
 import { HttpClient } from '../../../core/services/HttpClient';
+import { AuthError } from '../../../core/models';
+
+let spaClient: Auth0Client | null = null;
+let redirectHandled = false;
 
 /**
- * The concrete implementation of IAuth0Client for the Web platform (React Native Web).
+ * Factory function to get a singleton instance of Auth0Client.
+ * This ensures that the client is only created once and reused.
  *
- * This class instantiates the `auth0-spa-js` client and all the necessary
- * web-specific adapters that use it to fulfill their contracts. It also handles
- * the initial redirect callback flow.
+ * @param options - The Auth0ClientOptions to configure the client.
+ * @returns An instance of Auth0Client.
  */
+const getSpaClient = (options: Auth0ClientOptions): Auth0Client => {
+  if (spaClient) {
+    return spaClient;
+  }
+  spaClient = new Auth0Client(options);
+  return spaClient;
+};
+
 export class WebAuth0Client implements IAuth0Client {
   readonly webAuth: WebWebAuthProvider;
   readonly credentialsManager: WebCredentialsManager;
   readonly auth: AuthenticationOrchestrator;
 
-  private readonly client: Auth0Client;
   private readonly httpClient: HttpClient;
+  public readonly client: Auth0Client;
+
+  private logoutInProgress = false;
 
   constructor(options: WebAuth0Options) {
     const baseUrl = `https://${options.domain}`;
 
-    // 1. Create the HttpClient.
     this.httpClient = new HttpClient({
       baseUrl: baseUrl,
       timeout: options.timeout,
       headers: options.headers,
     });
 
-    // 2. Instantiate the AuthenticationOrchestrator.
     this.auth = new AuthenticationOrchestrator({
       clientId: options.clientId,
       httpClient: this.httpClient,
     });
 
-    const { clientId, domain, ...otherOptions } = options;
     const clientOptions: Auth0ClientOptions = {
-      clientId: clientId,
-      domain: domain,
-      cacheLocation: otherOptions.cacheLocation ?? 'memory',
-      useRefreshTokens: otherOptions.useRefreshTokens ?? true,
+      domain: options.domain,
+      clientId: options.clientId,
+      cacheLocation: options.cacheLocation ?? 'memory',
+      useRefreshTokens: options.useRefreshTokens ?? true,
       authorizationParams: {
-        // A default redirect_uri is required by spa-js.
-        // This can be overridden in the `authorize` call.
         redirect_uri:
           typeof window !== 'undefined' ? window.location.origin : '',
+        ...options,
       },
-      ...otherOptions, // Pass through any other spa-js compatible options.
     };
 
-    this.client = new Auth0Client(clientOptions);
+    // Use the singleton factory to get the spa-js client instance.
+    const client = getSpaClient(clientOptions);
+    this.client = client;
 
-    // Automatically handle the redirect from Auth0 when the app loads.
-    // This is a fire-and-forget operation. The hooks layer will update the
-    // UI once the user state is resolved.
-    this.handleRedirect();
+    this.handleRedirect(client);
 
-    // Instantiate our adapters with the configured spa-js client.
-    this.webAuth = new WebWebAuthProvider(this.client);
-    this.credentialsManager = new WebCredentialsManager(this.client);
+    this.webAuth = new WebWebAuthProvider(this);
+    this.credentialsManager = new WebCredentialsManager(this);
   }
 
-  /**
-   * Creates a client for interacting with the Auth0 Management API's user endpoints.
-   *
-   * @param token An access token with the required permissions for the management operations.
-   * @returns An `IUsersClient` instance configured with the provided token.
-   */
   users(token: string): IUsersClient {
-    // Re-use the same HttpClient, but the orchestrator will add its own auth header.
     return new ManagementApiOrchestrator({
       token: token,
       httpClient: this.httpClient,
     });
   }
 
-  /**
-   * Private method to handle the redirect from Auth0 after a login attempt.
-   * This should only run once when the application loads.
-   */
-  private async handleRedirect(): Promise<void> {
+  public async logout(options?: LogoutOptions): Promise<void> {
+    // If a logout process has already started, do nothing.
+    if (this.logoutInProgress) {
+      return;
+    }
+    this.logoutInProgress = true;
+
+    try {
+      await this.client.logout(options);
+    } catch (e: any) {
+      // Reset the flag on error so a retry is possible.
+      this.logoutInProgress = false;
+      throw new AuthError(
+        e.error ?? 'LogoutFailed',
+        e.error_description ?? e.message,
+        { json: e }
+      );
+    }
+  }
+
+  private async handleRedirect(client: Auth0Client): Promise<void> {
+    if (redirectHandled) {
+      return;
+    }
+
     if (
       typeof window !== 'undefined' &&
       window.location.search.includes('code=') &&
       window.location.search.includes('state=')
     ) {
+      redirectHandled = true; // Mark as handled to prevent re-running
+
       try {
-        // This method processes the code and state, exchanges them for tokens,
-        // and caches the result.
-        await this.client.handleRedirectCallback();
+        await client.handleRedirectCallback();
       } catch (e) {
-        // Errors during handleRedirectCallback are often informational
-        // (e.g., user is already logged in). We can log them but
-        // shouldn't crash the app. The developer can get the error
-        // state from the useAuth0 hook if needed.
         console.error('Error during handleRedirectCallback:', e);
       } finally {
-        // Clean the URL to remove the code and state parameters,
-        // preventing the logic from running again on a page refresh.
         window.history.replaceState(
           {},
           document.title,
diff --git a/src/platforms/web/adapters/WebCredentialsManager.ts b/src/platforms/web/adapters/WebCredentialsManager.ts
@@ -1,44 +1,35 @@
-import type { Auth0Client } from '@auth0/auth0-spa-js';
 import type { ICredentialsManager } from '../../../core/interfaces';
 import type { Credentials } from '../../../types';
 import {
   AuthError,
   Credentials as CredentialsModel,
 } from '../../../core/models';
+import type { WebAuth0Client } from './WebAuth0Client';
 
-/**
- * A web platform-specific implementation of the ICredentialsManager.
- * It leverages the internal cache and token management of `auth0-spa-js`.
- */
 export class WebCredentialsManager implements ICredentialsManager {
-  constructor(private client: Auth0Client) {}
+  constructor(private parent: WebAuth0Client) {}
 
   async saveCredentials(_credentials: Credentials): Promise<void> {
-    // In auth0-spa-js, credentials are saved automatically after a successful
-    // login flow. This method is a no-op to maintain API compatibility.
     console.warn(
-      'CredentialsManager.saveCredentials is a no-op on the web. @auth0/auth0-spa-js handles credential storage automatically.'
+      '`saveCredentials` is a no-op on the web. @auth0/auth0-spa-js handles credential storage automatically.'
     );
     return Promise.resolve();
   }
 
   async getCredentials(
     scope?: string,
-    _minTtl?: number, // minTtl is not directly applicable; getTokenSilently handles expiry checks.
+    _minTtl?: number,
     parameters?: Record<string, any>,
     forceRefresh?: boolean
   ): Promise<Credentials> {
     try {
-      const tokenResponse = await this.client.getTokenSilently({
+      const tokenResponse = await this.parent.client.getTokenSilently({
         cacheMode: forceRefresh ? 'off' : 'on',
-        authorizationParams: {
-          ...parameters,
-          scope,
-        },
+        authorizationParams: { ...parameters, scope },
         detailedResponse: true,
       });
 
-      const claims = await this.client.getIdTokenClaims();
+      const claims = await this.parent.client.getIdTokenClaims();
       if (!claims || !claims.exp) {
         throw new AuthError(
           'IdTokenMissing',
@@ -52,10 +43,8 @@ export class WebCredentialsManager implements ICredentialsManager {
         tokenType: 'Bearer',
         expiresAt: claims.exp,
         scope: tokenResponse.scope,
-        // auth0-spa-js does not expose the refresh token directly.
       });
     } catch (e: any) {
-      // Map common spa-js errors to our standard AuthError
       if (e.error === 'login_required' || e.error === 'consent_required') {
         throw new AuthError(
           e.error,
@@ -71,15 +60,11 @@ export class WebCredentialsManager implements ICredentialsManager {
     }
   }
 
-  async hasValidCredentials(_minTtl?: number): Promise<boolean> {
-    // The closest equivalent in auth0-spa-js is isAuthenticated(), which checks
-    // for a valid, non-expired session locally.
-    return this.client.isAuthenticated();
+  async hasValidCredentials(): Promise<boolean> {
+    return this.parent.client.isAuthenticated();
   }
 
   async clearCredentials(): Promise<void> {
-    // This is equivalent to a local-only logout.
-    // It clears the cache in auth0-spa-js without a full redirect.
-    await this.client.logout({ openUrl: false });
+    await this.parent.client.logout({ openUrl: false });
   }
 }
diff --git a/src/platforms/web/adapters/WebWebAuthProvider.ts b/src/platforms/web/adapters/WebWebAuthProvider.ts
@@ -1,84 +1,38 @@
-import type { Auth0Client } from '@auth0/auth0-spa-js';
 import type { IWebAuthProvider } from '../../../core/interfaces';
 import type {
   Credentials,
   WebAuthorizeParameters,
   ClearSessionParameters,
 } from '../../../types';
-import type {
-  WebAuthorizeOptions,
-  WebClearSessionOptions,
-} from '../../../types/platform-specific';
-import {
-  AuthError,
-  Credentials as CredentialsModel,
-} from '../../../core/models';
+import { AuthError } from '../../../core/models';
 import { finalizeScope } from '../../../core/utils';
+import type { WebAuth0Client } from './WebAuth0Client';
 
-/**
- * A web platform-specific implementation of the IWebAuthProvider.
- * This class translates web authentication calls into calls to the `auth0-spa-js` client.
- */
 export class WebWebAuthProvider implements IWebAuthProvider {
-  constructor(private client: Auth0Client) {}
+  constructor(private parent: WebAuth0Client) {}
 
   async authorize(
-    parameters: WebAuthorizeParameters,
-    _options?: WebAuthorizeOptions // options are often included in parameters for SPA-JS
+    parameters: WebAuthorizeParameters = {}
   ): Promise<Credentials> {
-    try {
-      const finalScope = finalizeScope(parameters.scope);
-      // loginWithRedirect does not resolve with credentials; it redirects.
-      // The credentials will be available after the user is redirected back
-      // and handleRedirectCallback is called. The Auth0Provider hook will
-      // manage this state change. For API consistency, we can check if
-      // credentials already exist after a potential redirect.
-      await this.client.loginWithRedirect({
-        authorizationParams: {
-          ...parameters,
-          scope: finalScope,
-          redirect_uri: parameters.redirectUrl,
-        },
-      });
-
-      // After a redirect, the app will re-initialize. We can attempt to
-      // get the token silently upon return. If it succeeds, we have our credentials.
-      const token = await this.client.getTokenSilently();
-      const user = await this.client.getUser();
-
-      if (!token || !user || !user.sub) {
-        throw new AuthError(
-          'LoginIncomplete',
-          'Login flow was initiated, but no user session was found after redirect.'
-        );
-      }
-
-      const claims = await this.client.getIdTokenClaims();
-
-      return new CredentialsModel({
-        idToken: claims?.__raw ?? '',
-        accessToken: token,
-        tokenType: 'Bearer',
-        expiresAt: claims?.exp ?? 0,
-        scope: await this.client
-          .getTokenSilently({ detailedResponse: true })
-          .then((r) => r.scope),
-      });
-    } catch (e: any) {
-      throw new AuthError(
-        e.error ?? 'LoginFailed',
-        e.error_description ?? e.message,
-        { json: e }
-      );
-    }
+    const finalScope = finalizeScope(parameters.scope);
+    await this.parent.client.loginWithRedirect({
+      authorizationParams: {
+        ...parameters,
+        scope: finalScope,
+        redirect_uri: parameters.redirectUrl,
+      },
+    });
+
+    // NOTE: loginWithRedirect does not resolve with a value, as it triggers a full
+    // page navigation. The user session is recovered by `handleRedirectCallback`
+    // when the app reloads. We return a Promise that never resolves to match the
+    // interface, but in practice, the application context will be lost.
+    return new Promise(() => {});
   }
 
-  async clearSession(
-    parameters: ClearSessionParameters,
-    _options?: WebClearSessionOptions
-  ): Promise<void> {
+  async clearSession(parameters: ClearSessionParameters = {}): Promise<void> {
     try {
-      await this.client.logout({
+      await this.parent.client.logout({
         logoutParams: {
           federated: parameters.federated,
           returnTo: parameters.returnToUrl,
@@ -94,8 +48,7 @@ export class WebWebAuthProvider implements IWebAuthProvider {
   }
 
   async cancelWebAuth(): Promise<void> {
-    // Web-based flows cannot be programmatically cancelled in the same way
-    // as the native ASWebAuthenticationSession. This is a no-op for the web.
+    // Web-based flows cannot be programmatically cancelled. This is a no-op.
     return Promise.resolve();
   }
 }
diff --git a/src/types/platform-specific.ts b/src/types/platform-specific.ts
@@ -129,12 +129,20 @@ export interface NativeClearSessionOptions {
 // ========= Web-Specific Options =========
 
 /**
- * Extends the core Auth0Options with web-specific configuration.
+ * Extends the core Auth0Options with web-specific configuration
+ * that is passed down to `@auth0/auth0-spa-js`.
  * @platform web
+ * @see https://auth0.github.io/auth0-spa-js/interfaces/Auth0ClientOptions.html
  */
 export interface WebAuth0Options extends Auth0Options {
+  /** How and where to cache session data. Defaults to `memory`. */
   cacheLocation?: 'memory' | 'localstorage';
+  /** Enables the use of refresh tokens for silent authentication. */
   useRefreshTokens?: boolean;
+  /** A custom audience for the `getTokenSilently` call. */
+  audience?: string;
+  /** A custom scope for the `getTokenSilently` call. */
+  scope?: string;
 }
 
 /**
