@auth0/auth0-spa-js 2.4.1 → 2.6.0

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/api.ts

@@ -12,6 +12,7 @@ export async function oauthToken(
     scope,
     auth0Client,
     useFormData,
+    useMrrt,
     dpop,
     ...options
   }: TokenEndpointOptions,
@@ -20,10 +21,14 @@ export async function oauthToken(
   const isTokenExchange =
     options.grant_type === 'urn:ietf:params:oauth:grant-type:token-exchange';
 
+  const refreshWithMrrt =
+    options.grant_type === 'refresh_token' && useMrrt;
+
   const allParams = {
     ...options,
     ...(isTokenExchange && audience && { audience }),
-    ...(isTokenExchange && scope && { scope })
+    ...(isTokenExchange && scope && { scope }),
+    ...(refreshWithMrrt && { audience, scope })
   };
 
   const body = useFormData
@@ -51,6 +56,7 @@ export async function oauthToken(
     },
     worker,
     useFormData,
+    useMrrt,
     isDpopSupported ? dpop : undefined
   );
 }

package/src/cache/cache-manager.ts

@@ -69,7 +69,9 @@ export class CacheManager {
 
   async get(
     cacheKey: CacheKey,
-    expiryAdjustmentSeconds = DEFAULT_EXPIRY_ADJUSTMENT_SECONDS
+    expiryAdjustmentSeconds = DEFAULT_EXPIRY_ADJUSTMENT_SECONDS,
+    useMrrt = false,
+    cacheMode?: string
   ): Promise<Partial<CacheEntry> | undefined> {
     let wrappedEntry = await this.cache.get<WrappedCacheEntry>(
       cacheKey.toKey()
@@ -85,6 +87,13 @@ export class CacheManager {
       if (matchedKey) {
         wrappedEntry = await this.cache.get<WrappedCacheEntry>(matchedKey);
       }
+
+      // To refresh using MRRT we need to send a request to the server
+      // If cacheMode is 'cache-only', this will make us unable to call the server
+      // so it won't be needed to find a valid refresh token
+      if (!matchedKey && useMrrt && cacheMode !== 'cache-only') {
+        return this.getEntryWithRefreshToken(cacheKey, keys);
+      }
     }
 
     // If we still don't have an entry, exit.
@@ -97,12 +106,7 @@ export class CacheManager {
 
     if (wrappedEntry.expiresAt - expiryAdjustmentSeconds < nowSeconds) {
       if (wrappedEntry.body.refresh_token) {
-        wrappedEntry.body = {
-          refresh_token: wrappedEntry.body.refresh_token
-        };
-
-        await this.cache.set(cacheKey.toKey(), wrappedEntry);
-        return wrappedEntry.body;
+        return this.modifiedCachedEntry(wrappedEntry, cacheKey);
       }
 
       await this.cache.remove(cacheKey.toKey());
@@ -114,6 +118,24 @@ export class CacheManager {
     return wrappedEntry.body;
   }
 
+  private async modifiedCachedEntry(wrappedEntry: WrappedCacheEntry, cacheKey: CacheKey): Promise<Partial<CacheEntry>> {
+    // We need to keep audience and scope in order to check them later when doing refresh
+    // using MRRT. See getScopeToRequest method.
+    wrappedEntry.body = {
+      refresh_token: wrappedEntry.body.refresh_token,
+      audience: wrappedEntry.body.audience,
+      scope: wrappedEntry.body.scope,
+    };
+
+    await this.cache.set(cacheKey.toKey(), wrappedEntry);
+
+    return {
+      refresh_token: wrappedEntry.body.refresh_token,
+      audience: wrappedEntry.body.audience,
+      scope: wrappedEntry.body.scope,
+    };
+  }
+
   async set(entry: CacheEntry): Promise<void> {
     const cacheKey = new CacheKey({
       clientId: entry.client_id,
@@ -207,4 +229,57 @@ export class CacheManager {
       );
     })[0];
   }
+
+  /**
+   * Returns the first entry that contains a refresh_token that satisfies the following conditions
+   * The keys inside the cache are in the format {prefix}::{clientId}::{audience}::{scope}.
+   * - `prefix` is strict equal to Auth0's internally configured `keyPrefix`
+   * - `clientId` is strict equal to the `cacheKey.clientId`
+   * @param keyToMatch The provided cache key
+   * @param allKeys A list of existing cache keys
+   */
+  private async getEntryWithRefreshToken(keyToMatch: CacheKey, allKeys: Array<string>): Promise<Partial<CacheEntry> | undefined> {
+    for (const key of allKeys) {
+      const cacheKey = CacheKey.fromKey(key);
+
+      if (cacheKey.prefix === CACHE_KEY_PREFIX &&
+        cacheKey.clientId === keyToMatch.clientId) {
+        const cachedEntry = await this.cache.get<WrappedCacheEntry>(key);
+
+        if (cachedEntry?.body?.refresh_token) {
+          return this.modifiedCachedEntry(cachedEntry, keyToMatch);
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Updates in the cache all entries that has a match with previous refresh_token with the
+   * new refresh_token obtained from the server
+   * @param oldRefreshToken Old refresh_token used on refresh
+   * @param newRefreshToken New refresh_token obtained from the server after refresh
+  */
+  async updateEntry(
+    oldRefreshToken: string,
+    newRefreshToken: string,
+  ): Promise<void> {
+    const allKeys = await this.getCacheKeys();
+
+    if (!allKeys) return;
+
+    for (const key of allKeys) {
+      const entry = await this.cache.get<WrappedCacheEntry>(key);
+
+      if (entry?.body?.refresh_token === oldRefreshToken) {
+        const cacheEntry = {
+          ...entry.body,
+          refresh_token: newRefreshToken,
+        } as CacheEntry;
+
+        await this.set(cacheEntry);
+      }
+    }
+  }
 }

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.

package/src/fetcher.ts

@@ -15,7 +15,12 @@ export type CustomFetchImpl<TOutput extends CustomFetchMinimalOutput> = (
   req: Request
 ) => Promise<TOutput>;
 
-type AccessTokenFactory = () => Promise<string>;
+export type AuthParams = {
+  scope?: string[];
+  audience?: string;
+};
+
+type AccessTokenFactory = (authParams?: AuthParams) => Promise<string>;
 
 export type FetcherConfig<TOutput extends CustomFetchMinimalOutput> = {
   getAccessToken?: AccessTokenFactory;
@@ -26,7 +31,7 @@ export type FetcherConfig<TOutput extends CustomFetchMinimalOutput> = {
 
 export type FetcherHooks = {
   isDpopEnabled: () => boolean;
-  getAccessToken: () => Promise<string>;
+  getAccessToken: AccessTokenFactory;
   getDpopNonce: () => Promise<string | undefined>;
   setDpopNonce: (nonce: string) => Promise<void>;
   generateDpopProof: (params: {
@@ -83,10 +88,10 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
     throw new TypeError('`url` must be absolute or `baseUrl` non-empty.');
   }
 
-  protected getAccessToken(): Promise<string> {
+  protected getAccessToken(authParams?: AuthParams): Promise<string> {
     return this.config.getAccessToken
-      ? this.config.getAccessToken()
-      : this.hooks.getAccessToken();
+      ? this.config.getAccessToken(authParams)
+      : this.hooks.getAccessToken(authParams);
   }
 
   protected buildBaseRequest(
@@ -109,10 +114,10 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
     );
   }
 
-  protected async setAuthorizationHeader(
+  protected setAuthorizationHeader(
     request: Request,
     accessToken: string
-  ): Promise<void> {
+  ): void {
     request.headers.set(
       'authorization',
       `${this.config.dpopNonceId ? 'DPoP' : 'Bearer'} ${accessToken}`
@@ -139,8 +144,8 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
     request.headers.set('dpop', dpopProof);
   }
 
-  protected async prepareRequest(request: Request) {
-    const accessToken = await this.getAccessToken();
+  protected async prepareRequest(request: Request, authParams?: AuthParams) {
+    const accessToken = await this.getAccessToken(authParams);
 
     this.setAuthorizationHeader(request, accessToken);
 
@@ -195,11 +200,12 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
   protected async internalFetchWithAuth(
     info: RequestInfo | URL,
     init: RequestInit | undefined,
-    callbacks: FetchWithAuthCallbacks<TOutput>
+    callbacks: FetchWithAuthCallbacks<TOutput>,
+    authParams?: AuthParams
   ): Promise<TOutput> {
     const request = this.buildBaseRequest(info, init);
 
-    await this.prepareRequest(request);
+    await this.prepareRequest(request, authParams);
 
     const response = await this.config.fetch(request);
 
@@ -208,17 +214,23 @@ export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
 
   public fetchWithAuth(
     info: RequestInfo | URL,
-    init?: RequestInit
+    init?: RequestInit,
+    authParams?: AuthParams
   ): Promise<TOutput> {
     const callbacks: FetchWithAuthCallbacks<TOutput> = {
       onUseDpopNonceError: () =>
-        this.internalFetchWithAuth(info, init, {
-          ...callbacks,
-          // Retry on a `use_dpop_nonce` error, but just once.
-          onUseDpopNonceError: undefined
-        })
+        this.internalFetchWithAuth(
+          info,
+          init,
+          {
+            ...callbacks,
+            // Retry on a `use_dpop_nonce` error, but just once.
+            onUseDpopNonceError: undefined
+          },
+          authParams
+        )
     };
 
-    return this.internalFetchWithAuth(info, init, callbacks);
+    return this.internalFetchWithAuth(info, init, callbacks, authParams);
   }
 }

package/src/global.ts

@@ -1,5 +1,6 @@
 import { ICache } from './cache';
 import type { Dpop } from './dpop/dpop';
+import { CompleteResponse } from './MyAccountApiClient';
 
 export interface AuthorizationParams {
   /**
@@ -265,14 +266,20 @@ export interface Auth0ClientOptions extends BaseLoginOptions {
 
   /**
    * If provided, the SDK will load the token worker from this URL instead of the integrated `blob`. An example of when this is useful is if you have strict
-   * Content-Security-Policy (CSP) and wish to avoid needing to set `worker-src: blob:`. We recommend either serving the worker, which you can find in the module 
-   * at `<module_path>/dist/auth0-spa-js.worker.production.js`, from the same host as your application or using the Auth0 CDN 
+   * Content-Security-Policy (CSP) and wish to avoid needing to set `worker-src: blob:`. We recommend either serving the worker, which you can find in the module
+   * at `<module_path>/dist/auth0-spa-js.worker.production.js`, from the same host as your application or using the Auth0 CDN
    * `https://cdn.auth0.com/js/auth0-spa-js/<version>/auth0-spa-js.worker.production.js`.
-   * 
+   *
    * **Note**: The worker is only used when `useRefreshTokens: true`, `cacheLocation: 'memory'`, and the `cache` is not custom.
    */
   workerUrl?: string;
 
+
+  /**
+   * If `true`, the SDK will allow the refreshing of tokens using MRRT
+   */
+  useMrrt?: boolean;
+
   /**
    * If `true`, DPoP (OAuth 2.0 Demonstrating Proof of Possession, RFC9449)
    * will be used to cryptographically bind tokens to this specific browser
@@ -347,14 +354,29 @@ export interface RedirectLoginOptions<TAppState = any>
   openUrl?: (url: string) => Promise<void> | void;
 }
 
+/**
+ * The types of responses expected from the authorization server.
+ * - `code`: used for the standard login flow.
+ * - `connect_code`: used for the connect account flow.
+ */
+export enum ResponseType {
+  Code = 'code',
+  ConnectCode = 'connect_code'
+}
+
 export interface RedirectLoginResult<TAppState = any> {
   /**
    * State stored when the redirect request was made
    */
   appState?: TAppState;
+
+  /**
+   * The type of response, for login it will be `code`
+   */
+  response_type: ResponseType.Code;
 }
 
-export interface PopupLoginOptions extends BaseLoginOptions {}
+export interface PopupLoginOptions extends BaseLoginOptions { }
 
 export interface PopupConfigOptions {
   /**
@@ -517,12 +539,98 @@ export interface LogoutOptions extends LogoutUrlOptions {
   openUrl?: false | ((url: string) => Promise<void> | void);
 }
 
+export interface RedirectConnectAccountOptions<TAppState = any> {
+  /**
+   * The name of the connection to link (e.g. 'google-oauth2').
+   */
+  connection: string;
+
+  /**
+   * Additional authorization parameters for the request.
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'google-oauth2',
+   *   authorization_params: {
+   *     scope: 'https://www.googleapis.com/auth/calendar'
+   *     access_type: 'offline'
+   *   }
+   * });
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'github',
+   *   authorization_params: {
+   *     scope: 'repo user',
+   *     audience: 'https://api.github.com'
+   *   }
+   * });
+   */
+  authorization_params?: AuthorizationParams;
+
+  /**
+   * The URI to redirect back to after connecting the account.
+   */
+  redirectUri?: string;
+
+  /**
+   * Optional application state to persist through the transaction.
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'google-oauth2',
+   *   appState: { returnTo: '/settings' }
+   * });
+   */
+  appState?: TAppState;
+
+  /**
+   * Optional function to handle the redirect URL.
+   *
+   * @example
+   * await auth0.connectAccountWithRedirect({
+   *   connection: 'google-oauth2',
+   *   openUrl: async (url) => { myBrowserApi.open(url); }
+   * });
+   */
+  openUrl?: (url: string) => Promise<void>;
+}
+
+/**
+ * The result returned after a successful account connection redirect.
+ *
+ * Combines the redirect login result (including any persisted app state)
+ * with the complete response from the My Account API.
+ *
+ * @template TAppState - The type of application state persisted through the transaction.
+ * @example
+ * const result = await auth0.connectAccountWithRedirect(options);
+ * console.log(result.appState); // Access persisted app state
+ * console.log(result.connection);   // The connection of the account you connected to.
+ * console.log(result.response_type === 'connect_code');   // The response type will be 'connect_code'
+ */
+export type ConnectAccountRedirectResult<TAppState = any> = CompleteResponse & {
+  /**
+   * State stored when the redirect request was made
+   */
+  appState?: TAppState;
+
+  /**
+   * The type of response, for connect account it will be `connect_code`
+   */
+  response_type: ResponseType.ConnectCode;
+};
+
 /**
  * @ignore
  */
 export interface AuthenticationResult {
   state: string;
   code?: string;
+  /**
+   * This is for the redirect from the connect account flow.
+   */
+  connect_code?: string;
   error?: string;
   error_description?: string;
 }

package/src/http.ts

@@ -65,7 +65,8 @@ const fetchWithWorker = async (
   fetchOptions: FetchOptions,
   timeout: number,
   worker: Worker,
-  useFormData?: boolean
+  useFormData?: boolean,
+  useMrrt?: boolean
 ) => {
   return sendMessage(
     {
@@ -76,7 +77,8 @@ const fetchWithWorker = async (
       timeout,
       fetchUrl,
       fetchOptions,
-      useFormData
+      useFormData,
+      useMrrt
     },
     worker
   );
@@ -89,7 +91,8 @@ export const switchFetch = async (
   fetchOptions: FetchOptions,
   worker?: Worker,
   useFormData?: boolean,
-  timeout = DEFAULT_FETCH_TIMEOUT_MS
+  timeout = DEFAULT_FETCH_TIMEOUT_MS,
+  useMrrt?: boolean,
 ): Promise<any> => {
   if (worker) {
     return fetchWithWorker(
@@ -99,7 +102,8 @@ export const switchFetch = async (
       fetchOptions,
       timeout,
       worker,
-      useFormData
+      useFormData,
+      useMrrt
     );
   } else {
     return fetchWithoutWorker(fetchUrl, fetchOptions, timeout);
@@ -114,6 +118,7 @@ export async function getJSON<T>(
   options: FetchOptions,
   worker?: Worker,
   useFormData?: boolean,
+  useMrrt?: boolean,
   dpop?: Pick<Dpop, 'generateProof' | 'getNonce' | 'setNonce'>,
   isDpopRetry?: boolean
 ): Promise<T> {
@@ -139,7 +144,8 @@ export async function getJSON<T>(
         options,
         worker,
         useFormData,
-        timeout
+        timeout,
+        useMrrt,
       );
       fetchError = null;
       break;
@@ -210,6 +216,7 @@ export async function getJSON<T>(
         options,
         worker,
         useFormData,
+        useMrrt,
         dpop,
         true // !
       );

package/src/index.ts

@@ -23,6 +23,7 @@ export async function createAuth0Client(options: Auth0ClientOptions) {
 export { Auth0Client };
 
 export {
+  ConnectError,
   GenericError,
   AuthenticationError,
   TimeoutError,
@@ -48,3 +49,7 @@ export {
 } from './cache';
 
 export { type FetcherConfig } from './fetcher';
+
+export {
+  MyAccountApiError
+} from './MyAccountApiClient';