@auth0/auth0-spa-js 2.4.1 → 2.6.0

package/dist/typings/Auth0Client.d.ts

@@ -1,4 +1,4 @@
-import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse } from './global';
+import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse, ConnectAccountRedirectResult, RedirectConnectAccountOptions } from './global';
 import { CustomTokenExchangeOptions } from './TokenExchange';
 import { Dpop } from './dpop/dpop';
 import { Fetcher, type FetcherConfig, type CustomFetchMinimalOutput } from './fetcher';
@@ -20,6 +20,7 @@ export declare class Auth0Client {
     private readonly httpTimeoutMs;
     private readonly options;
     private readonly userCache;
+    private readonly myAccountApi;
     private worker?;
     private readonly defaultOptions;
     constructor(options: Auth0ClientOptions);
@@ -89,7 +90,30 @@ export declare class Auth0Client {
      * responses from Auth0. If the response is successful, results
      * will be valid according to their expiration times.
      */
-    handleRedirectCallback<TAppState = any>(url?: string): Promise<RedirectLoginResult<TAppState>>;
+    handleRedirectCallback<TAppState = any>(url?: string): Promise<RedirectLoginResult<TAppState> | ConnectAccountRedirectResult<TAppState>>;
+    /**
+     * 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 _handleLoginRedirectCallback;
+    /**
+     * 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 _handleConnectAccountRedirectCallback;
     /**
      * ```js
      * await auth0.checkSession();
@@ -276,4 +300,20 @@ export declare class Auth0Client {
      * Check the `EXAMPLES.md` file for a deeper look into this method.
      */
     createFetcher<TOutput extends CustomFetchMinimalOutput = Response>(config?: FetcherConfig<TOutput>): Fetcher<TOutput>;
+    /**
+     * 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.
+     */
+    connectAccountWithRedirect<TAppState = any>(options: RedirectConnectAccountOptions<TAppState>): Promise<void>;
 }

package/dist/typings/Auth0Client.utils.d.ts

@@ -32,3 +32,35 @@ export declare const getAuthorizeParams: (clientOptions: Auth0ClientOptions & {
  * Function used to provide support for the deprecated onRedirect through openUrl.
  */
 export declare const patchOpenUrlWithOnRedirect: <T extends Pick<LogoutOptions, "openUrl" | "onRedirect">>(options: T) => T;
+/**
+ * @ignore
+ *
+ * Checks if all scopes are included inside other array of scopes
+ */
+export declare const allScopesAreIncluded: (scopeToInclude?: string, scopes?: string) => boolean;
+/**
+ * @ignore
+ *
+ * For backward compatibility we are going to check if we are going to downscope while doing a refresh request
+ * while MRRT is allowed. If the audience is the same for the refresh_token we are going to use and it has
+ * lower scopes than the ones originally in the token, we are going to return the scopes that were stored
+ * with the refresh_token in the tokenset.
+ * @param useMrrt Setting that the user can activate to use MRRT in their requests
+ * @param authorizationParams Contains the audience and scope that the user requested to obtain a token
+ * @param cachedAudience Audience stored with the refresh_token wich we are going to use in the request
+ * @param cachedScope Scope stored with the refresh_token wich we are going to use in the request
+ */
+export declare const getScopeToRequest: (useMrrt: boolean | undefined, authorizationParams: {
+    audience?: string;
+    scope: string;
+}, cachedAudience?: string, cachedScope?: string) => string;
+/**
+ * @ignore
+ *
+ * Checks if the refresh request has been done using MRRT
+ * @param cachedAudience Audience from the refresh token used to refresh
+ * @param cachedScope Scopes from the refresh token used to refresh
+ * @param requestAudience Audience sent to the server
+ * @param requestScope Scopes sent to the server
+ */
+export declare const isRefreshWithMrrt: (cachedAudience: string | undefined, cachedScope: string | undefined, requestAudience: string | undefined, requestScope: string) => boolean;

package/dist/typings/MyAccountApiClient.d.ts

@@ -0,0 +1,92 @@
+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;
+}
+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 declare class MyAccountApiClient {
+    private myAccountFetcher;
+    private apiBase;
+    constructor(myAccountFetcher: Fetcher<Response>, apiBase: string);
+    /**
+     * Get a ticket for the connect account flow.
+     */
+    connectAccount(params: ConnectRequest): Promise<ConnectResponse>;
+    /**
+     * Verify the redirect from the connect account flow and complete the connecting of the account.
+     */
+    completeAccount(params: CompleteRequest): Promise<CompleteResponse>;
+    private _handleResponse;
+}
+export declare class MyAccountApiError extends Error {
+    readonly type: string;
+    readonly status: number;
+    readonly title: string;
+    readonly detail: string;
+    readonly validation_errors?: ErrorResponse['validation_errors'];
+    constructor({ type, status, title, detail, validation_errors }: ErrorResponse);
+}
+export {};

package/dist/typings/api.d.ts

@@ -1,2 +1,2 @@
 import { TokenEndpointOptions, TokenEndpointResponse } from './global';
-export declare function oauthToken({ baseUrl, timeout, audience, scope, auth0Client, useFormData, dpop, ...options }: TokenEndpointOptions, worker?: Worker): Promise<TokenEndpointResponse>;
+export declare function oauthToken({ baseUrl, timeout, audience, scope, auth0Client, useFormData, useMrrt, dpop, ...options }: TokenEndpointOptions, worker?: Worker): Promise<TokenEndpointResponse>;

package/dist/typings/cache/cache-manager.d.ts

@@ -7,7 +7,8 @@ export declare class CacheManager {
     constructor(cache: ICache, keyManifest?: CacheKeyManifest | undefined, nowProvider?: () => number | Promise<number>);
     setIdToken(clientId: string, idToken: string, decodedToken: DecodedToken): Promise<void>;
     getIdToken(cacheKey: CacheKey): Promise<IdTokenEntry | undefined>;
-    get(cacheKey: CacheKey, expiryAdjustmentSeconds?: number): Promise<Partial<CacheEntry> | undefined>;
+    get(cacheKey: CacheKey, expiryAdjustmentSeconds?: number, useMrrt?: boolean, cacheMode?: string): Promise<Partial<CacheEntry> | undefined>;
+    private modifiedCachedEntry;
     set(entry: CacheEntry): Promise<void>;
     clear(clientId?: string): Promise<void>;
     private wrapCacheEntry;
@@ -31,4 +32,20 @@ export declare class CacheManager {
      * @param allKeys A list of existing cache keys
      */
     private matchExistingCacheKey;
+    /**
+     * 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 getEntryWithRefreshToken;
+    /**
+     * 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
+    */
+    updateEntry(oldRefreshToken: string, newRefreshToken: string): Promise<void>;
 }

package/dist/typings/errors.d.ts

@@ -19,6 +19,16 @@ export declare class AuthenticationError extends GenericError {
     appState: any;
     constructor(error: string, error_description: string, state: string, appState?: any);
 }
+/**
+ * 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 declare class ConnectError extends GenericError {
+    connection: string;
+    state: string;
+    appState: any;
+    constructor(error: string, error_description: string, connection: string, state: string, appState?: any);
+}
 /**
  * Thrown when silent auth times out (usually due to a configuration issue) or
  * when network requests to the Auth server timeout.

package/dist/typings/fetcher.d.ts

@@ -6,7 +6,11 @@ export type CustomFetchMinimalOutput = {
     headers: ResponseHeaders;
 };
 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;
     baseUrl?: string;
@@ -15,7 +19,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: {
@@ -34,15 +38,15 @@ export declare class Fetcher<TOutput extends CustomFetchMinimalOutput> {
     constructor(config: FetcherConfig<TOutput>, hooks: FetcherHooks);
     protected isAbsoluteUrl(url: string): boolean;
     protected buildUrl(baseUrl: string | undefined, url: string | undefined): string;
-    protected getAccessToken(): Promise<string>;
+    protected getAccessToken(authParams?: AuthParams): Promise<string>;
     protected buildBaseRequest(info: RequestInfo | URL, init: RequestInit | undefined): Request;
-    protected setAuthorizationHeader(request: Request, accessToken: string): Promise<void>;
+    protected setAuthorizationHeader(request: Request, accessToken: string): void;
     protected setDpopProofHeader(request: Request, accessToken: string): Promise<void>;
-    protected prepareRequest(request: Request): Promise<void>;
+    protected prepareRequest(request: Request, authParams?: AuthParams): Promise<void>;
     protected getHeader(headers: ResponseHeaders, name: string): string;
     protected hasUseDpopNonceError(response: TOutput): boolean;
     protected handleResponse(response: TOutput, callbacks: FetchWithAuthCallbacks<TOutput>): Promise<TOutput>;
-    protected internalFetchWithAuth(info: RequestInfo | URL, init: RequestInit | undefined, callbacks: FetchWithAuthCallbacks<TOutput>): Promise<TOutput>;
-    fetchWithAuth(info: RequestInfo | URL, init?: RequestInit): Promise<TOutput>;
+    protected internalFetchWithAuth(info: RequestInfo | URL, init: RequestInit | undefined, callbacks: FetchWithAuthCallbacks<TOutput>, authParams?: AuthParams): Promise<TOutput>;
+    fetchWithAuth(info: RequestInfo | URL, init?: RequestInit, authParams?: AuthParams): Promise<TOutput>;
 }
 export {};

package/dist/typings/global.d.ts

@@ -1,5 +1,6 @@
 import { ICache } from './cache';
 import type { Dpop } from './dpop/dpop';
+import { CompleteResponse } from './MyAccountApiClient';
 export interface AuthorizationParams {
     /**
      * - `'page'`: displays the UI with a full page view
@@ -243,6 +244,10 @@ export interface Auth0ClientOptions extends BaseLoginOptions {
      * **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
@@ -311,11 +316,24 @@ export interface RedirectLoginOptions<TAppState = any> extends BaseLoginOptions
      */
     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 declare 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 {
 }
@@ -465,12 +483,91 @@ 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/dist/typings/http.d.ts

@@ -1,5 +1,5 @@
 import { FetchOptions } from './global';
 import { Dpop } from './dpop/dpop';
 export declare const createAbortController: () => AbortController;
-export declare const switchFetch: (fetchUrl: string, audience: string, scope: string, fetchOptions: FetchOptions, worker?: Worker, useFormData?: boolean, timeout?: number) => Promise<any>;
-export declare function getJSON<T>(url: string, timeout: number | undefined, audience: string, scope: string, options: FetchOptions, worker?: Worker, useFormData?: boolean, dpop?: Pick<Dpop, 'generateProof' | 'getNonce' | 'setNonce'>, isDpopRetry?: boolean): Promise<T>;
+export declare const switchFetch: (fetchUrl: string, audience: string, scope: string, fetchOptions: FetchOptions, worker?: Worker, useFormData?: boolean, timeout?: number, useMrrt?: boolean) => Promise<any>;
+export declare function getJSON<T>(url: string, timeout: number | undefined, audience: string, scope: string, options: FetchOptions, worker?: Worker, useFormData?: boolean, useMrrt?: boolean, dpop?: Pick<Dpop, 'generateProof' | 'getNonce' | 'setNonce'>, isDpopRetry?: boolean): Promise<T>;

package/dist/typings/index.d.ts

@@ -13,6 +13,7 @@ export * from './global';
  */
 export declare function createAuth0Client(options: Auth0ClientOptions): Promise<Auth0Client>;
 export { Auth0Client };
-export { GenericError, AuthenticationError, TimeoutError, PopupTimeoutError, PopupCancelledError, MfaRequiredError, MissingRefreshTokenError, UseDpopNonceError } from './errors';
+export { ConnectError, GenericError, AuthenticationError, TimeoutError, PopupTimeoutError, PopupCancelledError, MfaRequiredError, MissingRefreshTokenError, UseDpopNonceError } from './errors';
 export { ICache, LocalStorageCache, InMemoryCache, Cacheable, DecodedToken, CacheEntry, WrappedCacheEntry, KeyManifestEntry, MaybePromise, CacheKey, CacheKeyData } from './cache';
 export { type FetcherConfig } from './fetcher';
+export { MyAccountApiError } from './MyAccountApiClient';

package/dist/typings/transaction-manager.d.ts

@@ -1,5 +1,5 @@
 import { ClientStorage } from './storage';
-interface Transaction {
+export interface LoginTransaction {
     nonce: string;
     scope: string;
     audience: string;
@@ -8,6 +8,18 @@ interface Transaction {
     redirect_uri?: string;
     organization?: string;
     state?: string;
+    response_type: 'code';
+}
+export interface ConnectAccountTransaction {
+    appState?: any;
+    audience?: string;
+    auth_session: string;
+    code_verifier: string;
+    redirect_uri: string;
+    scope?: string;
+    state: string;
+    connection: string;
+    response_type: 'connect_code';
 }
 export declare class TransactionManager {
     private storage;
@@ -15,8 +27,7 @@ export declare class TransactionManager {
     private cookieDomain?;
     private storageKey;
     constructor(storage: ClientStorage, clientId: string, cookieDomain?: string | undefined);
-    create(transaction: Transaction): void;
-    get(): Transaction | undefined;
+    create<T extends Object = LoginTransaction>(transaction: T): void;
+    get<T extends Object = LoginTransaction>(): T | undefined;
     remove(): void;
 }
-export {};

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.4.1";
+declare const _default: "2.6.0";
 export default _default;

package/dist/typings/worker/worker.types.d.ts

@@ -7,6 +7,7 @@ export type WorkerRefreshTokenMessage = {
     fetchUrl: string;
     fetchOptions: FetchOptions;
     useFormData?: boolean;
+    useMrrt?: boolean;
     auth: {
         audience: string;
         scope: string;

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.4.1",
+  "version": "2.6.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",