@auth0/auth0-spa-js 2.5.0 → 2.7.0

package/src/Auth0Client.ts

@@ -31,12 +31,14 @@ import {
   DecodedToken
 } from './cache';
 
-import { TransactionManager } from './transaction-manager';
+import { ConnectAccountTransaction, LoginTransaction, TransactionManager } from './transaction-manager';
 import { verify as verifyIdToken } from './jwt';
 import {
   AuthenticationError,
+  ConnectError,
   GenericError,
   MissingRefreshTokenError,
+  MissingScopesError,
   TimeoutError
 } from './errors';
 
@@ -76,7 +78,11 @@ import {
   User,
   IdToken,
   GetTokenSilentlyVerboseResponse,
-  TokenEndpointResponse
+  TokenEndpointResponse,
+  AuthenticationResult,
+  ConnectAccountRedirectResult,
+  RedirectConnectAccountOptions,
+  ResponseType
 } from './global';
 
 // @ts-ignore
@@ -93,7 +99,8 @@ import {
   patchOpenUrlWithOnRedirect,
   getScopeToRequest,
   allScopesAreIncluded,
-  isRefreshWithMrrt
+  isRefreshWithMrrt,
+  getMissingScopes
 } from './Auth0Client.utils';
 import { CustomTokenExchangeOptions } from './TokenExchange';
 import { Dpop } from './dpop/dpop';
@@ -102,6 +109,7 @@ import {
   type FetcherConfig,
   type CustomFetchMinimalOutput
 } from './fetcher';
+import { MyAccountApiClient } from './MyAccountApiClient';
 
 /**
  * @ignore
@@ -138,6 +146,7 @@ export class Auth0Client {
     authorizationParams: AuthorizationParams;
   };
   private readonly userCache: ICache = new InMemoryCache().enclosedCache;
+  private readonly myAccountApi: MyAccountApiClient;
 
   private worker?: Worker;
   private readonly defaultOptions: Partial<Auth0ClientOptions> = {
@@ -238,6 +247,23 @@ export class Auth0Client {
     this.domainUrl = getDomain(this.options.domain);
     this.tokenIssuer = getTokenIssuer(this.options.issuer, this.domainUrl);
 
+    const myAccountApiIdentifier = `${this.domainUrl}/me/`;
+    const myAccountFetcher = this.createFetcher({
+      ...(this.options.useDpop && { dpopNonceId: '__auth0_my_account_api__' }),
+      getAccessToken: () =>
+        this.getTokenSilently({
+          authorizationParams: {
+            scope: 'create:me:connected_accounts',
+            audience: myAccountApiIdentifier
+          },
+          detailedResponse: true
+        })
+    });
+    this.myAccountApi = new MyAccountApiClient(
+      myAccountFetcher,
+      myAccountApiIdentifier
+    );
+
     // Don't use web workers unless using refresh tokens in memory
     if (
       typeof window !== 'undefined' &&
@@ -477,9 +503,10 @@ export class Auth0Client {
       urlOptions.authorizationParams || {}
     );
 
-    this.transactionManager.create({
+    this.transactionManager.create<LoginTransaction>({
       ...transaction,
       appState,
+      response_type: ResponseType.Code,
       ...(organization && { organization })
     });
 
@@ -500,18 +527,18 @@ export class Auth0Client {
    */
   public async handleRedirectCallback<TAppState = any>(
     url: string = window.location.href
-  ): Promise<RedirectLoginResult<TAppState>> {
+  ): Promise<
+    RedirectLoginResult<TAppState> | ConnectAccountRedirectResult<TAppState>
+  > {
     const queryStringFragments = url.split('?').slice(1);
 
     if (queryStringFragments.length === 0) {
       throw new Error('There are no query params available for parsing.');
     }
 
-    const { state, code, error, error_description } = parseAuthenticationResult(
-      queryStringFragments.join('')
-    );
-
-    const transaction = this.transactionManager.get();
+    const transaction = this.transactionManager.get<
+      LoginTransaction | ConnectAccountTransaction
+    >();
 
     if (!transaction) {
       throw new GenericError('missing_transaction', 'Invalid state');
@@ -519,6 +546,38 @@ export class Auth0Client {
 
     this.transactionManager.remove();
 
+    const authenticationResult = parseAuthenticationResult(
+      queryStringFragments.join('')
+    );
+
+    if (transaction.response_type === ResponseType.ConnectCode) {
+      return this._handleConnectAccountRedirectCallback<TAppState>(
+        authenticationResult,
+        transaction
+      );
+    }
+    return this._handleLoginRedirectCallback<TAppState>(
+      authenticationResult,
+      transaction
+    );
+  }
+
+  /**
+   * Handles the redirect callback from the login flow.
+   *
+   * @template AppState - The application state persisted from the /authorize redirect.
+   * @param {string} authenticationResult - The parsed authentication result from the URL.
+   * @param {string} transaction - The login transaction.
+   *
+   * @returns {RedirectLoginResult} Resolves with the persisted app state.
+   * @throws {GenericError | Error} If the transaction is missing, invalid, or the code exchange fails.
+   */
+  private async _handleLoginRedirectCallback<TAppState>(
+    authenticationResult: AuthenticationResult,
+    transaction: LoginTransaction
+  ): Promise<RedirectLoginResult<TAppState>> {
+    const { code, state, error, error_description } = authenticationResult;
+
     if (error) {
       throw new AuthenticationError(
         error,
@@ -553,7 +612,63 @@ export class Auth0Client {
     );
 
     return {
-      appState: transaction.appState
+      appState: transaction.appState,
+      response_type: ResponseType.Code
+    };
+  }
+
+  /**
+   * Handles the redirect callback from the connect account flow.
+   * This works the same as the redirect from the login flow expect it verifies the `connect_code`
+   * with the My Account API rather than the `code` with the Authorization Server.
+   *
+   * @template AppState - The application state persisted from the connect redirect.
+   * @param {string} connectResult - The parsed connect accounts result from the URL.
+   * @param {string} transaction - The login transaction.
+   * @returns {Promise<ConnectAccountRedirectResult>} The result of the My Account API, including any persisted app state.
+   * @throws {GenericError | MyAccountApiError} If the transaction is missing, invalid, or an error is returned from the My Account API.
+   */
+  private async _handleConnectAccountRedirectCallback<TAppState>(
+    connectResult: AuthenticationResult,
+    transaction: ConnectAccountTransaction
+  ): Promise<ConnectAccountRedirectResult<TAppState>> {
+    const { connect_code, state, error, error_description } = connectResult;
+
+    if (error) {
+      throw new ConnectError(
+        error,
+        error_description || error,
+        transaction.connection,
+        state,
+        transaction.appState
+      );
+    }
+
+    if (!connect_code) {
+      throw new GenericError('missing_connect_code', 'Missing connect code');
+    }
+
+    if (
+      !transaction.code_verifier ||
+      !transaction.state ||
+      !transaction.auth_session ||
+      !transaction.redirect_uri ||
+      transaction.state !== state
+    ) {
+      throw new GenericError('state_mismatch', 'Invalid state');
+    }
+
+    const data = await this.myAccountApi.completeAccount({
+      auth_session: transaction.auth_session,
+      connect_code,
+      redirect_uri: transaction.redirect_uri,
+      code_verifier: transaction.code_verifier
+    });
+
+    return {
+      ...data,
+      appState: transaction.appState,
+      response_type: ResponseType.ConnectCode,
     };
   }
 
@@ -1032,7 +1147,7 @@ export class Auth0Client {
         }
       );
 
-      // If is refreshed with MRRT, we update all entries that have the old 
+      // If is refreshed with MRRT, we update all entries that have the old
       // refresh_token with the new one if the server responded with one
       if (tokenResult.refresh_token && this.options.useMrrt && cache?.refresh_token) {
         await this.cacheManager.updateEntry(
@@ -1064,9 +1179,14 @@ export class Auth0Client {
               return await this._getTokenFromIFrame(options);
             }
 
-            throw new MissingRefreshTokenError(
+            const missingScopes = getMissingScopes(
+              scopesToRequest,
+              tokenResult.scope,
+            );
+
+            throw new MissingScopesError(
               options.authorizationParams.audience || 'default',
-              options.authorizationParams.scope,
+              missingScopes,
             );
           }
         }
@@ -1369,12 +1489,6 @@ export class Auth0Client {
   public createFetcher<TOutput extends CustomFetchMinimalOutput = Response>(
     config: FetcherConfig<TOutput> = {}
   ): Fetcher<TOutput> {
-    if (this.options.useDpop && !config.dpopNonceId) {
-      throw new TypeError(
-        'When `useDpop` is enabled, `dpopNonceId` must be set when calling `createFetcher()`.'
-      );
-    }
-
     return new Fetcher(config, {
       isDpopEnabled: () => !!this.options.useDpop,
       getAccessToken: authParams =>
@@ -1382,13 +1496,79 @@ export class Auth0Client {
           authorizationParams: {
             scope: authParams?.scope?.join(' '),
             audience: authParams?.audience
-          }
+          },
+          detailedResponse: true
         }),
       getDpopNonce: () => this.getDpopNonce(config.dpopNonceId),
-      setDpopNonce: nonce => this.setDpopNonce(nonce),
+      setDpopNonce: nonce => this.setDpopNonce(nonce, config.dpopNonceId),
       generateDpopProof: params => this.generateDpopProof(params)
     });
   }
+
+  /**
+   * Initiates a redirect to connect the user's account with a specified connection.
+   * This method generates PKCE parameters, creates a transaction, and redirects to the /connect endpoint.
+   *
+   * @template TAppState - The application state to persist through the transaction.
+   * @param {RedirectConnectAccountOptions<TAppState>} options - Options for the connect account redirect flow.
+   * @param   {string} options.connection - The name of the connection to link (e.g. 'google-oauth2').
+   * @param   {AuthorizationParams} [options.authorization_params] - Additional authorization parameters for the request to the upstream IdP.
+   * @param   {string} [options.redirectUri] - The URI to redirect back to after connecting the account.
+   * @param   {TAppState} [options.appState] - Application state to persist through the transaction.
+   * @param   {(url: string) => Promise<void>} [options.openUrl] - Custom function to open the URL.
+   *
+   * @returns {Promise<void>} Resolves when the redirect is initiated.
+   * @throws {MyAccountApiError} If the connect request to the My Account API fails.
+   */
+  public async connectAccountWithRedirect<TAppState = any>(
+    options: RedirectConnectAccountOptions<TAppState>
+  ) {
+    const {
+      openUrl,
+      appState,
+      connection,
+      authorization_params,
+      redirectUri = this.options.authorizationParams.redirect_uri ||
+      window.location.origin
+    } = options;
+
+    if (!connection) {
+      throw new Error('connection is required');
+    }
+
+    const state = encode(createRandomString());
+    const code_verifier = createRandomString();
+    const code_challengeBuffer = await sha256(code_verifier);
+    const code_challenge = bufferToBase64UrlEncoded(code_challengeBuffer);
+
+    const { connect_uri, connect_params, auth_session } =
+      await this.myAccountApi.connectAccount({
+        connection,
+        redirect_uri: redirectUri,
+        state,
+        code_challenge,
+        code_challenge_method: 'S256',
+        authorization_params
+      });
+
+    this.transactionManager.create<ConnectAccountTransaction>({
+      state,
+      code_verifier,
+      auth_session,
+      redirect_uri: redirectUri,
+      appState,
+      connection,
+      response_type: ResponseType.ConnectCode
+    });
+
+    const url = new URL(connect_uri);
+    url.searchParams.set('ticket', connect_params.ticket);
+    if (openUrl) {
+      await openUrl(url.toString());
+    } else {
+      window.location.assign(url);
+    }
+  }
 }
 
 interface BaseRequestTokenOptions {

package/src/Auth0Client.utils.ts

@@ -108,6 +108,20 @@ export const allScopesAreIncluded = (scopeToInclude?: string, scopes?: string):
   return scopesToInclude.every((key) => scopeGroup.includes(key));
 }
 
+/**
+ * @ignore
+ * 
+ * Returns the scopes that are missing after a refresh
+ */
+export const getMissingScopes = (requestedScope?: string, respondedScope?: string): string => {
+  const requestedScopes = requestedScope?.split(" ") || [];
+  const respondedScopes = respondedScope?.split(" ") || [];
+
+  const missingScopes = requestedScopes.filter((scope) => respondedScopes.indexOf(scope) == -1);
+
+  return missingScopes.join(",");
+}
+
 /**
  * @ignore
  *

package/src/MyAccountApiClient.ts

@@ -0,0 +1,158 @@
+import { AuthorizationParams } from './global';
+import { Fetcher } from './fetcher';
+
+interface ConnectRequest {
+  /** The name of the connection to link the account with (e.g., 'google-oauth2', 'facebook'). */
+  connection: string;
+  /** The URI to redirect to after the connection process completes. */
+  redirect_uri: string;
+  /** An opaque value used to maintain state between the request and callback. */
+  state?: string;
+  /** A string value used to associate a Client session with an ID Token, and to mitigate replay attacks. */
+  nonce?: string;
+  /** The PKCE code challenge derived from the code verifier. */
+  code_challenge?: string;
+  /** The method used to derive the code challenge. Required when code_challenge is provided. */
+  code_challenge_method?: 'S256';
+  authorization_params?: AuthorizationParams;
+}
+
+interface ConnectResponse {
+  /** The base URI to initiate the account connection flow. */
+  connect_uri: string;
+  /** The authentication session identifier. */
+  auth_session: string;
+  /** Parameters to be used with the connect URI. */
+  connect_params: {
+    /** The ticket identifier to be used with the connection URI. */
+    ticket: string;
+  };
+  /** The number of seconds until the ticket expires. */
+  expires_in: number;
+}
+
+interface CompleteRequest {
+  /** The authentication session identifier */
+  auth_session: string;
+  /** The authorization code returned from the connect flow */
+  connect_code: string;
+  /** The redirect URI used in the original request */
+  redirect_uri: string;
+  /** The PKCE code verifier */
+  code_verifier?: string;
+}
+
+export interface CompleteResponse {
+  /** The unique identifier of the connected account */
+  id: string;
+  /** The connection name */
+  connection: string;
+  /** The access type, always 'offline' */
+  access_type: 'offline';
+  /** Array of scopes granted */
+  scopes?: string[];
+  /** ISO date string of when the connected account was created */
+  created_at: string;
+  /** ISO date string of when the refresh token expires (optional) */
+  expires_at?: string;
+}
+
+// Validation error returned from MyAccount API
+export interface ErrorResponse {
+  type: string;
+  status: number;
+  title: string;
+  detail: string;
+  validation_errors?: {
+    detail: string;
+    field?: string;
+    pointer?: string;
+    source?: string;
+  }[];
+}
+
+/**
+ * Subset of the MyAccount API that handles the connect accounts flow.
+ */
+export class MyAccountApiClient {
+  constructor(
+    private myAccountFetcher: Fetcher<Response>,
+    private apiBase: string
+  ) {}
+
+  /**
+   * Get a ticket for the connect account flow.
+   */
+  async connectAccount(params: ConnectRequest): Promise<ConnectResponse> {
+    const res = await this.myAccountFetcher.fetchWithAuth(
+      `${this.apiBase}v1/connected-accounts/connect`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(params)
+      }
+    );
+    return this._handleResponse(res);
+  }
+
+  /**
+   * Verify the redirect from the connect account flow and complete the connecting of the account.
+   */
+  async completeAccount(params: CompleteRequest): Promise<CompleteResponse> {
+    const res = await this.myAccountFetcher.fetchWithAuth(
+      `${this.apiBase}v1/connected-accounts/complete`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(params)
+      }
+    );
+    return this._handleResponse(res);
+  }
+
+  private async _handleResponse(res: Response) {
+    let body: any;
+    try {
+      body = await res.text();
+      body = JSON.parse(body);
+    } catch (err) {
+      throw new MyAccountApiError({
+        type: 'invalid_json',
+        status: res.status,
+        title: 'Invalid JSON response',
+        detail: body || String(err)
+      });
+    }
+
+    if (res.ok) {
+      return body;
+    } else {
+      throw new MyAccountApiError(body);
+    }
+  }
+}
+
+export class MyAccountApiError extends Error {
+  public readonly type: string;
+  public readonly status: number;
+  public readonly title: string;
+  public readonly detail: string;
+  public readonly validation_errors?: ErrorResponse['validation_errors'];
+
+  constructor({
+    type,
+    status,
+    title,
+    detail,
+    validation_errors
+  }: ErrorResponse) {
+    super(detail);
+    this.name = 'MyAccountApiError';
+    this.type = type;
+    this.status = status;
+    this.title = title;
+    this.detail = detail;
+    this.validation_errors = validation_errors;
+    Object.setPrototypeOf(this, MyAccountApiError.prototype);
+  }
+}

package/src/errors.ts

@@ -35,6 +35,24 @@ export class AuthenticationError extends GenericError {
   }
 }
 
+/**
+ * Thrown when handling the redirect callback for the connect flow fails, will be one of Auth0's
+ * Authentication API's Standard Error Responses: https://auth0.com/docs/api/authentication?javascript#standard-error-responses
+ */
+export class ConnectError extends GenericError {
+  constructor(
+    error: string,
+    error_description: string,
+    public connection: string,
+    public state: string,
+    public appState: any = null
+  ) {
+    super(error, error_description);
+    //https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
+    Object.setPrototypeOf(this, ConnectError.prototype);
+  }
+}
+
 /**
  * Thrown when silent auth times out (usually due to a configuration issue) or
  * when network requests to the Auth server timeout.
@@ -96,6 +114,21 @@ export class MissingRefreshTokenError extends GenericError {
   }
 }
 
+/**
+ * Error thrown when there are missing scopes after refreshing a token
+ */
+export class MissingScopesError extends GenericError {
+  constructor(public audience: string, public scope: string) {
+    super(
+      'missing_scopes',
+      `Missing requested scopes after refresh (audience: '${valueOrEmptyString(audience, [
+        'default'
+      ])}', missing scope: '${valueOrEmptyString(scope)}')`
+    );
+    Object.setPrototypeOf(this, MissingScopesError.prototype);
+  }
+}
+
 /**
  * Error thrown when the wrong DPoP nonce is used and a potential subsequent retry wasn't able to fix it.
  */

package/src/fetcher.ts

@@ -1,5 +1,6 @@
 import { DPOP_NONCE_HEADER } from './dpop/utils';
 import { UseDpopNonceError } from './errors';
+import { GetTokenSilentlyVerboseResponse } from './global';
 
 export type ResponseHeaders =
   | Record<string, string | null | undefined>
@@ -20,7 +21,12 @@ export type AuthParams = {
   audience?: string;
 };
 
-type AccessTokenFactory = (authParams?: AuthParams) => Promise<string>;
+type AccessTokenFactory = (authParams?: AuthParams) => Promise<string | GetTokenSilentlyVerboseResponse>;
+
+enum TokenType {
+  Bearer = 'Bearer',
+  DPoP = 'DPoP'
+}
 
 export type FetcherConfig<TOutput extends CustomFetchMinimalOutput> = {
   getAccessToken?: AccessTokenFactory;
@@ -88,12 +94,24 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
     throw new TypeError('`url` must be absolute or `baseUrl` non-empty.');
   }
 
-  protected getAccessToken(authParams?: AuthParams): Promise<string> {
+  protected getAccessToken(authParams?: AuthParams): Promise<string | GetTokenSilentlyVerboseResponse> {
     return this.config.getAccessToken
       ? this.config.getAccessToken(authParams)
       : this.hooks.getAccessToken(authParams);
   }
 
+  protected extractUrl(info: RequestInfo | URL): string {
+    if (typeof info === 'string') {
+      return info;
+    }
+
+    if (info instanceof URL) {
+      return info.href;
+    }
+
+    return info.url;
+  }
+
   protected buildBaseRequest(
     info: RequestInfo | URL,
     init: RequestInit | undefined
@@ -101,26 +119,32 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
     // In the native `fetch()` behavior, `init` can override `info` and the result
     // is the merge of both. So let's replicate that behavior by passing those into
     // a fresh `Request` object.
-    const request = new Request(info, init);
 
-    // No `baseUrl` config, use whatever the URL the `Request` came with.
+    // No `baseUrl`? We can use `info` and `init` as is.
     if (!this.config.baseUrl) {
-      return request;
+      return new Request(info, init);
     }
 
-    return new Request(
-      this.buildUrl(this.config.baseUrl, request.url),
-      request
-    );
+    // But if `baseUrl` is present, first we have to build the final URL...
+    const finalUrl = this.buildUrl(this.config.baseUrl, this.extractUrl(info));
+
+    // ... and then overwrite `info`'s URL with it, making sure we keep any other
+    // properties that might be there already (headers, etc).
+    const finalInfo = info instanceof Request
+      ? new Request(finalUrl, info)
+      : finalUrl;
+
+    return new Request(finalInfo, init);
   }
 
-  protected async setAuthorizationHeader(
+  protected setAuthorizationHeader(
     request: Request,
-    accessToken: string
-  ): Promise<void> {
+    accessToken: string,
+    tokenType: string = TokenType.Bearer
+  ): void {
     request.headers.set(
       'authorization',
-      `${this.config.dpopNonceId ? 'DPoP' : 'Bearer'} ${accessToken}`
+      `${tokenType} ${accessToken}`
     );
   }
 
@@ -145,11 +169,22 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
   }
 
   protected async prepareRequest(request: Request, authParams?: AuthParams) {
-    const accessToken = await this.getAccessToken(authParams);
-
-    this.setAuthorizationHeader(request, accessToken);
+    const accessTokenResponse = await this.getAccessToken(authParams);
+
+    let tokenType: string;
+    let accessToken: string;
+    if (typeof accessTokenResponse === 'string') {
+      tokenType = this.config.dpopNonceId ? TokenType.DPoP : TokenType.Bearer;
+      accessToken = accessTokenResponse;
+    } else {
+      tokenType = accessTokenResponse.token_type;
+      accessToken = accessTokenResponse.access_token;
+    }
 
-    await this.setDpopProofHeader(request, accessToken);
+    this.setAuthorizationHeader(request, accessToken, tokenType);
+    if (tokenType === TokenType.DPoP) {
+      await this.setDpopProofHeader(request, accessToken);
+    }
   }
 
   protected getHeader(headers: ResponseHeaders, name: string): string {
@@ -171,7 +206,7 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
 
     const wwwAuthHeader = this.getHeader(response.headers, 'www-authenticate');
 
-    return wwwAuthHeader.includes('use_dpop_nonce');
+    return wwwAuthHeader.includes('invalid_dpop_nonce') || wwwAuthHeader.includes('use_dpop_nonce');
   }
 
   protected async handleResponse(