@auth0/auth0-spa-js 2.18.3 → 2.19.0

package/dist/typings/Auth0Client.d.ts

@@ -1,4 +1,4 @@
-import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse, ConnectAccountRedirectResult, RedirectConnectAccountOptions, ClientConfiguration } from './global';
+import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse, ConnectAccountRedirectResult, RedirectConnectAccountOptions, ClientConfiguration, RevokeRefreshTokenOptions } from './global';
 import { CustomTokenExchangeOptions } from './TokenExchange';
 import { Dpop } from './dpop/dpop';
 import { Fetcher, type FetcherConfig, type CustomFetchMinimalOutput } from './fetcher';
@@ -262,6 +262,43 @@ export declare class Auth0Client {
      * @param options
      */
     private _buildLogoutUrl;
+    /**
+     * ```js
+     * await auth0.revokeRefreshToken();
+     * ```
+     *
+     * Revokes the refresh token using the `/oauth/revoke` endpoint.
+     * This invalidates the refresh token so it can no longer be used to obtain new access tokens.
+     *
+     * The method works with both memory and localStorage cache modes:
+     * - For memory storage with worker: The refresh token never leaves the worker thread,
+     *   maintaining security isolation
+     * - For localStorage: The token is retrieved from cache and revoked
+     *
+     * If `useRefreshTokens` is disabled, this method does nothing.
+     *
+     * **Important:** This method revokes the refresh token for a single audience. If your
+     * application requests tokens for multiple audiences, each audience may have its own
+     * refresh token. To fully revoke all refresh tokens, call this method once per audience.
+     * If you want to terminate the user's session entirely, use `logout()` instead.
+     *
+     * When using Multi-Resource Refresh Tokens (MRRT), a single refresh token may cover
+     * multiple audiences. In that case, revoking it will affect all cache entries that
+     * share the same token.
+     *
+     * @param options - Optional parameters to identify which refresh token to revoke.
+     *   Defaults to the audience configured in `authorizationParams`.
+     *
+     * @example
+     * // Revoke the default refresh token
+     * await auth0.revokeRefreshToken();
+     *
+     * @example
+     * // Revoke refresh tokens for each audience individually
+     * await auth0.revokeRefreshToken({ audience: 'https://api.example.com' });
+     * await auth0.revokeRefreshToken({ audience: 'https://api2.example.com' });
+     */
+    revokeRefreshToken(options?: RevokeRefreshTokenOptions): Promise<void>;
     /**
      * ```js
      * await auth0.logout(options);

package/dist/typings/api.d.ts

@@ -1,2 +1,33 @@
 import { TokenEndpointOptions, TokenEndpointResponse } from './global';
+/**
+ * @ignore
+ * Internal options for the revokeToken API call.
+ * Kept in api.ts (not global.ts) so it is not part of the public type surface.
+ */
+interface RevokeTokenOptions {
+    baseUrl: string;
+    /** Maps directly to the OAuth `client_id` parameter. */
+    client_id: string;
+    /** Tokens to revoke. Empty for the worker path — the worker holds its own store. */
+    refreshTokens: string[];
+    audience?: string;
+    timeout?: number;
+    auth0Client?: any;
+    useFormData?: boolean;
+    onRefreshTokenRevoked?: (refreshToken: string) => Promise<void> | void;
+}
 export declare function oauthToken({ baseUrl, timeout, audience, scope, auth0Client, useFormData, useMrrt, dpop, ...options }: TokenEndpointOptions, worker?: Worker): Promise<TokenEndpointResponse>;
+/**
+ * Revokes refresh tokens using the /oauth/revoke endpoint.
+ *
+ * Mirrors the oauthToken pattern: the worker/non-worker dispatch lives here,
+ * keeping Auth0Client free of transport concerns.
+ *
+ * - Worker path: sends a single message; the worker holds its own RT store and
+ *   loops internally. refreshTokens is empty (worker ignores it).
+ * - Non-worker path: loops over refreshTokens and issues one request per token.
+ *
+ * @throws {GenericError} If any revoke request fails
+ */
+export declare function revokeToken({ baseUrl, timeout, auth0Client, useFormData, refreshTokens, audience, client_id, onRefreshTokenRevoked }: RevokeTokenOptions, worker?: Worker): Promise<void>;
+export {};

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

@@ -11,6 +11,7 @@ export declare class CacheManager {
     private modifiedCachedEntry;
     set(entry: CacheEntry): Promise<void>;
     remove(client_id: string, audience?: string, scope?: string): Promise<void>;
+    stripRefreshToken(refreshToken: string): Promise<void>;
     clear(clientId?: string): Promise<void>;
     private wrapCacheEntry;
     private getCacheKeys;
@@ -42,6 +43,18 @@ export declare class CacheManager {
      * @param allKeys A list of existing cache keys
      */
     private getEntryWithRefreshToken;
+    /**
+     * Returns all distinct refresh tokens stored for a given audience and client.
+     *
+     * Multiple cache entries may exist for the same audience when different scope
+     * combinations were obtained via separate authorization flows, each potentially
+     * carrying a different refresh token. A Set is used to deduplicate tokens that
+     * are shared across entries (e.g. MRRT).
+     *
+     * @param audience The audience to look up
+     * @param clientId The client id to scope the lookup
+     */
+    getRefreshTokensByAudience(audience: string, clientId: string): Promise<string[]>;
     /**
      * Updates the refresh token in all cache entries that contain the old refresh token.
      *

package/dist/typings/global.d.ts

@@ -816,4 +816,11 @@ export type FetchResponse = {
     json: any;
 };
 export type GetTokenSilentlyVerboseResponse = Omit<TokenEndpointResponse, 'refresh_token'>;
+/**
+ * Options for revoking a refresh token
+ */
+export interface RevokeRefreshTokenOptions {
+    /** Audience to identify which refresh token to revoke. Omit for default audience. */
+    audience?: string;
+}
 export type { Authenticator, AuthenticatorType, OobChannel, MfaFactorType, EnrollParams, EnrollOtpParams, EnrollSmsParams, EnrollVoiceParams, EnrollEmailParams, EnrollPushParams, EnrollmentResponse, OtpEnrollmentResponse, OobEnrollmentResponse, ChallengeAuthenticatorParams, ChallengeResponse, VerifyParams, MfaGrantType, EnrollmentFactor } from './mfa/types';

package/dist/typings/http.d.ts

@@ -1,5 +1,11 @@
 import { FetchOptions } from './global';
 import { Dpop } from './dpop/dpop';
 export declare const createAbortController: () => AbortController;
+/**
+ * Wraps a single `fetch` call with an AbortController-based timeout and
+ * returns the raw `Response`. Shared by the JSON token path and the revoke
+ * path to avoid duplicating abort/timeout orchestration.
+ */
+export declare const fetchWithTimeout: (fetchUrl: string, fetchOptions: FetchOptions, timeout: number) => Promise<Response>;
 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/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.18.3";
+declare const _default: "2.19.0";
 export default _default;

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

@@ -1,20 +1,27 @@
 import { FetchOptions } from '../global';
-/**
- * @ts-ignore
- */
 export type WorkerInitMessage = {
     type: 'init';
     allowedBaseUrl: string;
 };
-export type WorkerRefreshTokenMessage = {
+type WorkerTokenMessage = {
     timeout: number;
     fetchUrl: string;
     fetchOptions: FetchOptions;
     useFormData?: boolean;
-    useMrrt?: boolean;
     auth: {
         audience: string;
         scope: string;
     };
 };
-export type WorkerMessage = WorkerInitMessage | WorkerRefreshTokenMessage;
+export type WorkerRefreshTokenMessage = WorkerTokenMessage & {
+    type: 'refresh';
+    useMrrt?: boolean;
+};
+export type WorkerRevokeTokenMessage = Omit<WorkerTokenMessage, 'auth'> & {
+    type: 'revoke';
+    auth: {
+        audience: string;
+    };
+};
+export type WorkerMessage = WorkerInitMessage | WorkerRefreshTokenMessage | WorkerRevokeTokenMessage;
+export {};

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

@@ -1,7 +1,13 @@
-import { WorkerRefreshTokenMessage } from './worker.types';
+import { WorkerRefreshTokenMessage, WorkerRevokeTokenMessage } from './worker.types';
 /**
- * Sends the specified message to the web worker
- * @param message The message to send
- * @param to The worker to send the message to
+ * Sends a message to a Web Worker and returns a Promise that resolves with
+ * the worker's response, or rejects if the worker replies with an error.
+ *
+ * Uses a {@link MessageChannel} so each call gets its own private reply port,
+ * making concurrent calls safe without shared state.
+ *
+ * @param message - The typed message to send (`refresh` or `revoke`).
+ * @param to      - The target {@link Worker} instance.
+ * @returns A Promise that resolves with the worker's response payload.
  */
-export declare const sendMessage: (message: WorkerRefreshTokenMessage, to: Worker) => Promise<unknown>;
+export declare const sendMessage: <T = any>(message: WorkerRefreshTokenMessage | WorkerRevokeTokenMessage, to: Worker) => Promise<T>;

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.18.3",
+  "version": "2.19.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",
@@ -93,7 +93,7 @@
     "rollup-plugin-livereload": "^2.0.5",
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-terser": "^7.0.2",
-    "rollup-plugin-typescript2": "^0.36.0",
+    "rollup-plugin-typescript2": "^0.37.0",
     "rollup-plugin-visualizer": "^5.7.1",
     "rollup-plugin-web-worker-loader": "~1.6.1",
     "serve": "^14.0.1",

package/src/Auth0Client.ts

@@ -17,7 +17,7 @@ import {
 
 import { getLockManager, type ILockManager } from './lock';
 
-import { oauthToken } from './api';
+import { oauthToken, revokeToken } from './api';
 
 import { injectDefaultScopes, scopesToRequest } from './scope';
 
@@ -90,7 +90,8 @@ import {
   RedirectConnectAccountOptions,
   ResponseType,
   ClientAuthorizationParams,
-  ClientConfiguration
+  ClientConfiguration,
+  RevokeRefreshTokenOptions
 } from './global';
 
 // @ts-ignore
@@ -1144,6 +1145,76 @@ export class Auth0Client {
     return url + federatedQuery;
   }
 
+  /**
+   * ```js
+   * await auth0.revokeRefreshToken();
+   * ```
+   *
+   * Revokes the refresh token using the `/oauth/revoke` endpoint.
+   * This invalidates the refresh token so it can no longer be used to obtain new access tokens.
+   *
+   * The method works with both memory and localStorage cache modes:
+   * - For memory storage with worker: The refresh token never leaves the worker thread,
+   *   maintaining security isolation
+   * - For localStorage: The token is retrieved from cache and revoked
+   *
+   * If `useRefreshTokens` is disabled, this method does nothing.
+   *
+   * **Important:** This method revokes the refresh token for a single audience. If your
+   * application requests tokens for multiple audiences, each audience may have its own
+   * refresh token. To fully revoke all refresh tokens, call this method once per audience.
+   * If you want to terminate the user's session entirely, use `logout()` instead.
+   *
+   * When using Multi-Resource Refresh Tokens (MRRT), a single refresh token may cover
+   * multiple audiences. In that case, revoking it will affect all cache entries that
+   * share the same token.
+   *
+   * @param options - Optional parameters to identify which refresh token to revoke.
+   *   Defaults to the audience configured in `authorizationParams`.
+   *
+   * @example
+   * // Revoke the default refresh token
+   * await auth0.revokeRefreshToken();
+   *
+   * @example
+   * // Revoke refresh tokens for each audience individually
+   * await auth0.revokeRefreshToken({ audience: 'https://api.example.com' });
+   * await auth0.revokeRefreshToken({ audience: 'https://api2.example.com' });
+   */
+  public async revokeRefreshToken(options: RevokeRefreshTokenOptions = {}): Promise<void> {
+    if (!this.options.useRefreshTokens) {
+      return;
+    }
+
+    const audience =
+      options.audience || this.options.authorizationParams.audience;
+
+    const resolvedAudience = audience || DEFAULT_AUDIENCE;
+
+    // For the non-worker path the main-thread cache holds the refresh tokens.
+    // For the worker path the worker holds its own RT store — the cache returns
+    // [] and revokeToken sends a single message; the worker loops internally.
+    const refreshTokens = await this.cacheManager.getRefreshTokensByAudience(
+      resolvedAudience,
+      this.options.clientId
+    );
+
+    await revokeToken(
+      {
+        baseUrl: this.domainUrl,
+        timeout: this.httpTimeoutMs,
+        auth0Client: this.options.auth0Client,
+        useFormData: this.options.useFormData,
+        client_id: this.options.clientId,
+        refreshTokens,
+        audience: resolvedAudience,
+        onRefreshTokenRevoked: refreshToken =>
+          this.cacheManager.stripRefreshToken(refreshToken)
+      },
+      this.worker
+    );
+  }
+
   /**
    * ```js
    * await auth0.logout(options);

package/src/api.ts

@@ -1,7 +1,31 @@
 import { TokenEndpointOptions, TokenEndpointResponse } from './global';
-import { DEFAULT_AUTH0_CLIENT, DEFAULT_AUDIENCE } from './constants';
+import {
+  DEFAULT_AUTH0_CLIENT,
+  DEFAULT_AUDIENCE,
+  DEFAULT_FETCH_TIMEOUT_MS
+} from './constants';
+
+/**
+ * @ignore
+ * Internal options for the revokeToken API call.
+ * Kept in api.ts (not global.ts) so it is not part of the public type surface.
+ */
+interface RevokeTokenOptions {
+  baseUrl: string;
+  /** Maps directly to the OAuth `client_id` parameter. */
+  client_id: string;
+  /** Tokens to revoke. Empty for the worker path — the worker holds its own store. */
+  refreshTokens: string[];
+  audience?: string;
+  timeout?: number;
+  auth0Client?: any;
+  useFormData?: boolean;
+  onRefreshTokenRevoked?: (refreshToken: string) => Promise<void> | void;
+}
 import * as dpopUtils from './dpop/utils';
-import { getJSON } from './http';
+import { GenericError } from './errors';
+import { getJSON, fetchWithTimeout } from './http';
+import { sendMessage } from './worker/worker.utils';
 import { createQueryParams, stripAuth0Client } from './utils';
 
 export async function oauthToken(
@@ -59,3 +83,89 @@ export async function oauthToken(
     isDpopSupported ? dpop : undefined
   );
 }
+
+/**
+ * Revokes refresh tokens using the /oauth/revoke endpoint.
+ *
+ * Mirrors the oauthToken pattern: the worker/non-worker dispatch lives here,
+ * keeping Auth0Client free of transport concerns.
+ *
+ * - Worker path: sends a single message; the worker holds its own RT store and
+ *   loops internally. refreshTokens is empty (worker ignores it).
+ * - Non-worker path: loops over refreshTokens and issues one request per token.
+ *
+ * @throws {GenericError} If any revoke request fails
+ */
+export async function revokeToken(
+  {
+    baseUrl,
+    timeout,
+    auth0Client,
+    useFormData,
+    refreshTokens,
+    audience,
+    client_id,
+    onRefreshTokenRevoked
+  }: RevokeTokenOptions,
+  worker?: Worker
+): Promise<void> {
+  const resolvedTimeout = timeout || DEFAULT_FETCH_TIMEOUT_MS;
+  // token_type_hint is a SHOULD per RFC 7009 §2.1; used in both paths below.
+  const token_type_hint = 'refresh_token' as const;
+  const fetchUrl = `${baseUrl}/oauth/revoke`;
+  const headers = {
+    'Content-Type': useFormData
+      ? 'application/x-www-form-urlencoded'
+      : 'application/json',
+    'Auth0-Client': btoa(
+      JSON.stringify(stripAuth0Client(auth0Client || DEFAULT_AUTH0_CLIENT))
+    )
+  };
+
+  if (worker) {
+    // Worker holds its own RT store and injects each token into the request.
+    // Send the base body (without token) so the worker can loop over its tokens.
+    const baseParams = { client_id, token_type_hint };
+    const body = useFormData
+      ? createQueryParams(baseParams)
+      : JSON.stringify(baseParams);
+
+    return sendMessage(
+      {
+        type: 'revoke',
+        timeout: resolvedTimeout,
+        fetchUrl,
+        fetchOptions: { method: 'POST', body, headers },
+        useFormData,
+        auth: { audience: audience ?? DEFAULT_AUDIENCE }
+      },
+      worker
+    );
+  }
+
+  for (const refreshToken of refreshTokens) {
+    const params = { client_id, token_type_hint, token: refreshToken };
+    const body = useFormData
+      ? createQueryParams(params)
+      : JSON.stringify(params);
+
+    const response = await fetchWithTimeout(
+      fetchUrl,
+      { method: 'POST', body, headers },
+      resolvedTimeout
+    );
+
+    if (!response.ok) {
+      let error: string | undefined;
+      let errorDescription: string | undefined;
+      try {
+        ({ error, error_description: errorDescription } = JSON.parse(await response.text()));
+      } catch {
+        // body absent or not valid JSON
+      }
+      throw new GenericError(error || 'revoke_error', errorDescription || `HTTP error ${response.status}`);
+    }
+
+    await onRefreshTokenRevoked?.(refreshToken);
+  }
+}

package/src/cache/cache-manager.ts

@@ -163,6 +163,23 @@ export class CacheManager {
     await this.cache.remove(cacheKey.toKey());
   }
 
+  async stripRefreshToken(refreshToken: string): Promise<void> {
+    const keys = await this.getCacheKeys();
+
+    /* c8 ignore next */
+    if (!keys) return;
+
+    // Find all cache entries that have this refresh token and strip only the refresh token,
+    // leaving the access token intact (it remains valid until it expires)
+    for (const key of keys) {
+      const entry = await this.cache.get<WrappedCacheEntry>(key);
+      if (entry?.body?.refresh_token === refreshToken) {
+        delete entry.body.refresh_token;
+        await this.cache.set(key, entry);
+      }
+    }
+  }
+
   async clear(clientId?: string): Promise<void> {
     const keys = await this.getCacheKeys();
 
@@ -269,6 +286,46 @@ export class CacheManager {
     return undefined;
   }
 
+  /**
+   * Returns all distinct refresh tokens stored for a given audience and client.
+   *
+   * Multiple cache entries may exist for the same audience when different scope
+   * combinations were obtained via separate authorization flows, each potentially
+   * carrying a different refresh token. A Set is used to deduplicate tokens that
+   * are shared across entries (e.g. MRRT).
+   *
+   * @param audience The audience to look up
+   * @param clientId The client id to scope the lookup
+   */
+  async getRefreshTokensByAudience(
+    audience: string,
+    clientId: string
+  ): Promise<string[]> {
+    const keys = await this.getCacheKeys();
+
+    if (!keys) return [];
+
+    const tokens = new Set<string>();
+
+    for (const key of keys) {
+      const cacheKey = CacheKey.fromKey(key);
+
+      if (
+        cacheKey.prefix === CACHE_KEY_PREFIX &&
+        cacheKey.clientId === clientId &&
+        cacheKey.audience === audience
+      ) {
+        const entry = await this.cache.get<WrappedCacheEntry>(key);
+
+        if (entry?.body?.refresh_token) {
+          tokens.add(entry.body.refresh_token);
+        }
+      }
+    }
+
+    return Array.from(tokens);
+  }
+
   /**
    * Updates the refresh token in all cache entries that contain the old refresh token.
    *

package/src/global.ts

@@ -903,6 +903,14 @@ export type GetTokenSilentlyVerboseResponse = Omit<
   'refresh_token'
 >;
 
+/**
+ * Options for revoking a refresh token
+ */
+export interface RevokeRefreshTokenOptions {
+  /** Audience to identify which refresh token to revoke. Omit for default audience. */
+  audience?: string;
+}
+
 // MFA API types
 export type {
   Authenticator,

package/src/http.ts

@@ -17,27 +17,16 @@ import { DPOP_NONCE_HEADER } from './dpop/utils';
 
 export const createAbortController = () => new AbortController();
 
-const dofetch = async (fetchUrl: string, fetchOptions: FetchOptions) => {
-  const response = await fetch(fetchUrl, fetchOptions);
-
-  return {
-    ok: response.ok,
-    json: await response.json(),
-
-    /**
-     * This is not needed, but do it anyway so the object shape is the
-     * same as when using a Web Worker (which *does* need this, see
-     * src/worker/token.worker.ts).
-     */
-    headers: fromEntries(response.headers)
-  };
-};
-
-const fetchWithoutWorker = async (
+/**
+ * Wraps a single `fetch` call with an AbortController-based timeout and
+ * returns the raw `Response`. Shared by the JSON token path and the revoke
+ * path to avoid duplicating abort/timeout orchestration.
+ */
+export const fetchWithTimeout = (
   fetchUrl: string,
   fetchOptions: FetchOptions,
   timeout: number
-) => {
+): Promise<Response> => {
   const controller = createAbortController();
   fetchOptions.signal = controller.signal;
 
@@ -45,9 +34,8 @@ const fetchWithoutWorker = async (
 
   // The promise will resolve with one of these two promises (the fetch or the timeout), whichever completes first.
   return Promise.race([
-    dofetch(fetchUrl, fetchOptions),
-
-    new Promise((_, reject) => {
+    fetch(fetchUrl, fetchOptions),
+    new Promise<never>((_, reject) => {
       timeoutId = setTimeout(() => {
         controller.abort();
         reject(new Error("Timeout when executing 'fetch'"));
@@ -58,6 +46,24 @@ const fetchWithoutWorker = async (
   });
 };
 
+const fetchWithoutWorker = async (
+  fetchUrl: string,
+  fetchOptions: FetchOptions,
+  timeout: number
+) => {
+  const response = await fetchWithTimeout(fetchUrl, fetchOptions, timeout);
+  return {
+    ok: response.ok,
+    json: await response.json(),
+    /**
+     * This is not needed, but do it anyway so the object shape is the
+     * same as when using a Web Worker (which *does* need this, see
+     * src/worker/token.worker.ts).
+     */
+    headers: fromEntries(response.headers)
+  };
+};
+
 const fetchWithWorker = async (
   fetchUrl: string,
   audience: string,
@@ -70,6 +76,7 @@ const fetchWithWorker = async (
 ) => {
   return sendMessage(
     {
+      type: 'refresh',
       auth: {
         audience,
         scope

package/src/version.ts

@@ -1 +1 @@
-export default '2.18.3';
+export default '2.19.0';