@auth0/auth0-spa-js 2.13.0 → 2.14.0

package/dist/typings/Auth0Client.d.ts

@@ -245,47 +245,71 @@ export declare class Auth0Client {
     private _releaseLockOnPageHide;
     private _requestToken;
     /**
-     * Exchanges an external subject token for an Auth0 token via a token exchange request.
+     * ```js
+     * await auth0.loginWithCustomTokenExchange(options);
+     * ```
+     *
+     * Exchanges an external subject token for Auth0 tokens and logs the user in.
+     * This method implements the Custom Token Exchange grant as specified in RFC 8693.
+     *
+     * The exchanged tokens are automatically cached, establishing an authenticated session.
+     * After calling this method, you can use `getUser()`, `getIdTokenClaims()`, and
+     * `getTokenSilently()` to access the user's information and tokens.
      *
      * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
      *
      * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response,
-     * which contains the issued Auth0 tokens.
+     * which contains the issued Auth0 tokens (access_token, id_token, etc.).
      *
-     * This method implements the token exchange grant as specified in RFC 8693 by first validating
-     * the provided subject token type and then constructing a token request to the /oauth/token endpoint.
      * The request includes the following parameters:
-     *
-     * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange".
-     * - `subject_token`: The external token provided via the options.
-     * - `subject_token_type`: The type of the external token (validated by this function).
-     * - `scope`: A unique set of scopes, generated by merging the scopes supplied in the options
-     *            with the SDK’s default scopes.
-     * - `audience`: The target audience from the options, with fallback to the SDK's authorization configuration.
-     * - `organization`: Optional organization ID or name for authenticating the user in an organization context.
-     *                   When provided, the organization ID will be present in the access token payload.
+     * - `grant_type`: "urn:ietf:params:oauth:grant-type:token-exchange"
+     * - `subject_token`: The external token to exchange
+     * - `subject_token_type`: The type identifier of the external token
+     * - `scope`: Merged scopes from the request and SDK defaults
+     * - `audience`: Target audience (defaults to SDK configuration)
+     * - `organization`: Optional organization ID/name for org-scoped authentication
      *
      * **Example Usage:**
      *
-     * ```
-     * // Define the token exchange options
-     * const options: CustomTokenExchangeOptions = {
+     * ```js
+     * const options = {
      *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
      *   subject_token_type: 'urn:acme:legacy-system-token',
-     *   scope: "openid profile",
-     *   organization: "org_12345"
+     *   scope: 'openid profile email',
+     *   audience: 'https://api.example.com',
+     *   organization: 'org_12345'
      * };
      *
-     * // Exchange the external token for Auth0 tokens
      * try {
-     *   const tokenResponse = await instance.exchangeToken(options);
-     *   // Use tokenResponse.access_token, tokenResponse.id_token, etc.
-     *   // The organization ID will be present in the access token payload
+     *   const tokenResponse = await auth0.loginWithCustomTokenExchange(options);
+     *   console.log('Access token:', tokenResponse.access_token);
+     *
+     *   // User is now logged in - access user info
+     *   const user = await auth0.getUser();
+     *   console.log('Logged in user:', user);
      * } catch (error) {
-     *   // Handle token exchange error
+     *   console.error('Token exchange failed:', error);
      * }
      * ```
      */
+    loginWithCustomTokenExchange(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>;
+    /**
+     * @deprecated Use `loginWithCustomTokenExchange()` instead. This method will be removed in the next major version.
+     *
+     * Exchanges an external subject token for Auth0 tokens.
+     *
+     * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
+     * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response.
+     *
+     * **Example:**
+     * ```js
+     * // Instead of:
+     * const tokens = await auth0.exchangeToken(options);
+     *
+     * // Use:
+     * const tokens = await auth0.loginWithCustomTokenExchange(options);
+     * ```
+     */
     exchangeToken(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>;
     protected _assertDpop(dpop: Dpop | undefined): asserts dpop is Dpop;
     /**

package/dist/typings/constants.d.ts

@@ -29,6 +29,10 @@ export declare const MISSING_REFRESH_TOKEN_ERROR_MESSAGE = "Missing Refresh Toke
  * @ignore
  */
 export declare const INVALID_REFRESH_TOKEN_ERROR_MESSAGE = "invalid refresh token";
+/**
+ * @ignore
+ */
+export declare const USER_BLOCKED_ERROR_MESSAGE = "user is blocked";
 /**
  * @ignore
  */

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.13.0";
+declare const _default: "2.14.0";
 export default _default;

package/package.json

@@ -3,7 +3,7 @@
   "name": "@auth0/auth0-spa-js",
   "description": "Auth0 SDK for Single Page Applications using Authorization Code Grant Flow with PKCE",
   "license": "MIT",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",

package/src/Auth0Client.ts

@@ -61,6 +61,7 @@ import {
   DEFAULT_SESSION_CHECK_EXPIRY_DAYS,
   DEFAULT_AUTH0_CLIENT,
   INVALID_REFRESH_TOKEN_ERROR_MESSAGE,
+  USER_BLOCKED_ERROR_MESSAGE,
   DEFAULT_NOW_PROVIDER,
   DEFAULT_FETCH_TIMEOUT_MS,
   DEFAULT_AUDIENCE
@@ -1297,18 +1298,25 @@ export class Auth0Client {
         audience: options.authorizationParams.audience || DEFAULT_AUDIENCE
       };
     } catch (e) {
-      if (
-        // The web worker didn't have a refresh token in memory so
-        // fallback to an iframe.
-        (e.message.indexOf(MISSING_REFRESH_TOKEN_ERROR_MESSAGE) > -1 ||
-          // A refresh token was found, but is it no longer valid
-          // and useRefreshTokensFallback is explicitly enabled. Fallback to an iframe.
-          (e.message &&
-            e.message.indexOf(INVALID_REFRESH_TOKEN_ERROR_MESSAGE) > -1)) &&
-        this.options.useRefreshTokensFallback
-      ) {
-        return await this._getTokenFromIFrame(options);
+      if (e.message) {
+        // Blocked users should be logged out immediately. No point attempting
+        // iframe fallback as the authorization server will reject the request.
+        if (e.message.includes(USER_BLOCKED_ERROR_MESSAGE)) {
+          await this.logout({ openUrl: false });
+          throw e;
+        }
+
+        // For missing or invalid refresh tokens, attempt iframe fallback if configured.
+        // The iframe may succeed if the user still has a valid session.
+        if (
+          (e.message.includes(MISSING_REFRESH_TOKEN_ERROR_MESSAGE) ||
+            e.message.includes(INVALID_REFRESH_TOKEN_ERROR_MESSAGE)) &&
+          this.options.useRefreshTokensFallback
+        ) {
+          return await this._getTokenFromIFrame(options);
+        }
       }
+
       if (e instanceof MfaRequiredError) {
         this.mfa.setMFAAuthDetails(
           e.mfa_token,
@@ -1496,51 +1504,58 @@ export class Auth0Client {
   */
 
   /**
-   * Exchanges an external subject token for an Auth0 token via a token exchange request.
+   * ```js
+   * await auth0.loginWithCustomTokenExchange(options);
+   * ```
+   *
+   * Exchanges an external subject token for Auth0 tokens and logs the user in.
+   * This method implements the Custom Token Exchange grant as specified in RFC 8693.
+   *
+   * The exchanged tokens are automatically cached, establishing an authenticated session.
+   * After calling this method, you can use `getUser()`, `getIdTokenClaims()`, and
+   * `getTokenSilently()` to access the user's information and tokens.
    *
    * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
    *
    * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response,
-   * which contains the issued Auth0 tokens.
+   * which contains the issued Auth0 tokens (access_token, id_token, etc.).
    *
-   * This method implements the token exchange grant as specified in RFC 8693 by first validating
-   * the provided subject token type and then constructing a token request to the /oauth/token endpoint.
    * The request includes the following parameters:
-   *
-   * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange".
-   * - `subject_token`: The external token provided via the options.
-   * - `subject_token_type`: The type of the external token (validated by this function).
-   * - `scope`: A unique set of scopes, generated by merging the scopes supplied in the options
-   *            with the SDK’s default scopes.
-   * - `audience`: The target audience from the options, with fallback to the SDK's authorization configuration.
-   * - `organization`: Optional organization ID or name for authenticating the user in an organization context.
-   *                   When provided, the organization ID will be present in the access token payload.
+   * - `grant_type`: "urn:ietf:params:oauth:grant-type:token-exchange"
+   * - `subject_token`: The external token to exchange
+   * - `subject_token_type`: The type identifier of the external token
+   * - `scope`: Merged scopes from the request and SDK defaults
+   * - `audience`: Target audience (defaults to SDK configuration)
+   * - `organization`: Optional organization ID/name for org-scoped authentication
    *
    * **Example Usage:**
    *
-   * ```
-   * // Define the token exchange options
-   * const options: CustomTokenExchangeOptions = {
+   * ```js
+   * const options = {
    *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
    *   subject_token_type: 'urn:acme:legacy-system-token',
-   *   scope: "openid profile",
-   *   organization: "org_12345"
+   *   scope: 'openid profile email',
+   *   audience: 'https://api.example.com',
+   *   organization: 'org_12345'
    * };
    *
-   * // Exchange the external token for Auth0 tokens
    * try {
-   *   const tokenResponse = await instance.exchangeToken(options);
-   *   // Use tokenResponse.access_token, tokenResponse.id_token, etc.
-   *   // The organization ID will be present in the access token payload
+   *   const tokenResponse = await auth0.loginWithCustomTokenExchange(options);
+   *   console.log('Access token:', tokenResponse.access_token);
+   *
+   *   // User is now logged in - access user info
+   *   const user = await auth0.getUser();
+   *   console.log('Logged in user:', user);
    * } catch (error) {
-   *   // Handle token exchange error
+   *   console.error('Token exchange failed:', error);
    * }
    * ```
    */
-  async exchangeToken(
+  async loginWithCustomTokenExchange(
     options: CustomTokenExchangeOptions
   ): Promise<TokenEndpointResponse> {
     return this._requestToken({
+      ...options,
       grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
       subject_token: options.subject_token,
       subject_token_type: options.subject_token_type,
@@ -1554,6 +1569,29 @@ export class Auth0Client {
     });
   }
 
+  /**
+   * @deprecated Use `loginWithCustomTokenExchange()` instead. This method will be removed in the next major version.
+   *
+   * Exchanges an external subject token for Auth0 tokens.
+   *
+   * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
+   * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response.
+   *
+   * **Example:**
+   * ```js
+   * // Instead of:
+   * const tokens = await auth0.exchangeToken(options);
+   *
+   * // Use:
+   * const tokens = await auth0.loginWithCustomTokenExchange(options);
+   * ```
+   */
+  async exchangeToken(
+    options: CustomTokenExchangeOptions
+  ): Promise<TokenEndpointResponse> {
+    return this.loginWithCustomTokenExchange(options);
+  }
+
   protected _assertDpop(dpop: Dpop | undefined): asserts dpop is Dpop {
     if (!dpop) {
       throw new Error('`useDpop` option must be enabled before using DPoP.');

package/src/constants.ts

@@ -41,6 +41,11 @@ export const MISSING_REFRESH_TOKEN_ERROR_MESSAGE = 'Missing Refresh Token';
  */
 export const INVALID_REFRESH_TOKEN_ERROR_MESSAGE = 'invalid refresh token';
 
+/**
+ * @ignore
+ */
+export const USER_BLOCKED_ERROR_MESSAGE = 'user is blocked';
+
 /**
  * @ignore
  */

package/src/version.ts

@@ -1 +1 @@
-export default '2.13.0';
+export default '2.14.0';