@auth0/auth0-spa-js/dist/typings/Auth0Client.d.ts

Auth0 SDK for Single Page Applications using Authorization Code Grant Flow with PKCE

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';
/**
 * Auth0 SDK for Single Page Applications using [Authorization Code Grant Flow with PKCE](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce).
 */
export declare class Auth0Client {
    private readonly transactionManager;
    private readonly cacheManager;
    private readonly domainUrl;
    private readonly tokenIssuer;
    private readonly scope;
    private readonly cookieStorage;
    private readonly dpop;
    private readonly sessionCheckExpiryDays;
    private readonly orgHintCookieName;
    private readonly isAuthenticatedCookieName;
    private readonly nowProvider;
    private readonly httpTimeoutMs;
    private readonly options;
    private readonly userCache;
    private readonly myAccountApi;
    private worker?;
    private readonly activeLockKeys;
    private readonly defaultOptions;
    constructor(options: Auth0ClientOptions);
    private _url;
    private _authorizeUrl;
    private _verifyIdToken;
    private _processOrgHint;
    private _prepareAuthorizeUrl;
    /**
     * ```js
     * try {
     *  await auth0.loginWithPopup(options);
     * } catch(e) {
     *  if (e instanceof PopupCancelledError) {
     *    // Popup was closed before login completed
     *  }
     * }
     * ```
     *
     * Opens a popup with the `/authorize` URL using the parameters
     * provided as arguments. Random and secure `state` and `nonce`
     * parameters will be auto-generated. If the response is successful,
     * results will be valid according to their expiration times.
     *
     * IMPORTANT: This method has to be called from an event handler
     * that was started by the user like a button click, for example,
     * otherwise the popup will be blocked in most browsers.
     *
     * @param options
     * @param config
     */
    loginWithPopup(options?: PopupLoginOptions, config?: PopupConfigOptions): Promise<void>;
    /**
     * ```js
     * const user = await auth0.getUser();
     * ```
     *
     * Returns the user information if available (decoded
     * from the `id_token`).
     *
     * @typeparam TUser The type to return, has to extend {@link User}.
     */
    getUser<TUser extends User>(): Promise<TUser | undefined>;
    /**
     * ```js
     * const claims = await auth0.getIdTokenClaims();
     * ```
     *
     * Returns all claims from the id_token if available.
     */
    getIdTokenClaims(): Promise<IdToken | undefined>;
    /**
     * ```js
     * await auth0.loginWithRedirect(options);
     * ```
     *
     * Performs a redirect to `/authorize` using the parameters
     * provided as arguments. Random and secure `state` and `nonce`
     * parameters will be auto-generated.
     *
     * @param options
     */
    loginWithRedirect<TAppState = any>(options?: RedirectLoginOptions<TAppState>): Promise<void>;
    /**
     * After the browser redirects back to the callback page,
     * call `handleRedirectCallback` to handle success and error
     * 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> | 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();
     * ```
     *
     * Check if the user is logged in using `getTokenSilently`. The difference
     * with `getTokenSilently` is that this doesn't return a token, but it will
     * pre-fill the token cache.
     *
     * This method also heeds the `auth0.{clientId}.is.authenticated` cookie, as an optimization
     *  to prevent calling Auth0 unnecessarily. If the cookie is not present because
     * there was no previous login (or it has expired) then tokens will not be refreshed.
     *
     * It should be used for silently logging in the user when you instantiate the
     * `Auth0Client` constructor. You should not need this if you are using the
     * `createAuth0Client` factory.
     *
     * **Note:** the cookie **may not** be present if running an app using a private tab, as some
     * browsers clear JS cookie data and local storage when the tab or page is closed, or on page reload. This effectively
     * means that `checkSession` could silently return without authenticating the user on page refresh when
     * using a private tab, despite having previously logged in. As a workaround, use `getTokenSilently` instead
     * and handle the possible `login_required` error [as shown in the readme](https://github.com/auth0/auth0-spa-js#creating-the-client).
     *
     * @param options
     */
    checkSession(options?: GetTokenSilentlyOptions): Promise<void>;
    /**
     * Fetches a new access token and returns the response from the /oauth/token endpoint, omitting the refresh token.
     *
     * @param options
     */
    getTokenSilently(options: GetTokenSilentlyOptions & {
        detailedResponse: true;
    }): Promise<GetTokenSilentlyVerboseResponse>;
    /**
     * Fetches a new access token and returns it.
     *
     * @param options
     */
    getTokenSilently(options?: GetTokenSilentlyOptions): Promise<string>;
    private _getTokenSilently;
    /**
     * ```js
     * const token = await auth0.getTokenWithPopup(options);
     * ```
     * Opens a popup with the `/authorize` URL using the parameters
     * provided as arguments. Random and secure `state` and `nonce`
     * parameters will be auto-generated. If the response is successful,
     * results will be valid according to their expiration times.
     *
     * @param options
     * @param config
     */
    getTokenWithPopup(options?: GetTokenWithPopupOptions, config?: PopupConfigOptions): Promise<string | undefined>;
    /**
     * ```js
     * const isAuthenticated = await auth0.isAuthenticated();
     * ```
     *
     * Returns `true` if there's valid information stored,
     * otherwise returns `false`.
     *
     */
    isAuthenticated(): Promise<boolean>;
    /**
     * ```js
     * await auth0.buildLogoutUrl(options);
     * ```
     *
     * Builds a URL to the logout endpoint using the parameters provided as arguments.
     * @param options
     */
    private _buildLogoutUrl;
    /**
     * ```js
     * await auth0.logout(options);
     * ```
     *
     * Clears the application session and performs a redirect to `/v2/logout`, using
     * the parameters provided as arguments, to clear the Auth0 session.
     *
     * If the `federated` option is specified it also clears the Identity Provider session.
     * [Read more about how Logout works at Auth0](https://auth0.com/docs/logout).
     *
     * @param options
     */
    logout(options?: LogoutOptions): Promise<void>;
    private _getTokenFromIFrame;
    private _getTokenUsingRefreshToken;
    private _saveEntryInCache;
    private _getIdTokenFromCache;
    private _getEntryFromCache;
    /**
     * Releases any locks acquired by the current page that are not released yet
     *
     * Get's called on the `pagehide` event.
     * https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event
     */
    private _releaseLockOnPageHide;
    private _requestToken;
    /**
     * Exchanges an external subject token for an Auth0 token via a token exchange request.
     *
     * @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.
     *
     * 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.
     *
     * **Example Usage:**
     *
     * ```
     * // Define the token exchange options
     * const options: CustomTokenExchangeOptions = {
     *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
     *   subject_token_type: 'urn:acme:legacy-system-token',
     *   scope: "openid profile"
     * };
     *
     * // Exchange the external token for Auth0 tokens
     * try {
     *   const tokenResponse = await instance.exchangeToken(options);
     *   // Use tokenResponse.access_token, tokenResponse.id_token, etc.
     * } catch (error) {
     *   // Handle token exchange error
     * }
     * ```
     */
    exchangeToken(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>;
    protected _assertDpop(dpop: Dpop | undefined): asserts dpop is Dpop;
    /**
     * Returns the current DPoP nonce used for making requests to Auth0.
     *
     * It can return `undefined` because when starting fresh it will not
     * be populated until after the first response from the server.
     *
     * It requires enabling the {@link Auth0ClientOptions.useDpop} option.
     *
     * @param nonce The nonce value.
     * @param id    The identifier of a nonce: if absent, it will get the nonce
     *              used for requests to Auth0. Otherwise, it will be used to
     *              select a specific non-Auth0 nonce.
     */
    getDpopNonce(id?: string): Promise<string | undefined>;
    /**
     * Sets the current DPoP nonce used for making requests to Auth0.
     *
     * It requires enabling the {@link Auth0ClientOptions.useDpop} option.
     *
     * @param nonce The nonce value.
     * @param id    The identifier of a nonce: if absent, it will set the nonce
     *              used for requests to Auth0. Otherwise, it will be used to
     *              select a specific non-Auth0 nonce.
     */
    setDpopNonce(nonce: string, id?: string): Promise<void>;
    /**
     * Returns a string to be used to demonstrate possession of the private
     * key used to cryptographically bind access tokens with DPoP.
     *
     * It requires enabling the {@link Auth0ClientOptions.useDpop} option.
     */
    generateDpopProof(params: {
        url: string;
        method: string;
        nonce?: string;
        accessToken: string;
    }): Promise<string>;
    /**
     * Returns a new `Fetcher` class that will contain a `fetchWithAuth()` method.
     * This is a drop-in replacement for the Fetch API's `fetch()` method, but will
     * handle certain authentication logic for you, like building the proper auth
     * headers or managing DPoP nonces and retries automatically.
     *
     * 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>;
}