@auth0/auth0-spa-js 2.2.0 → 2.4.0

package/src/Auth0Client.ts

@@ -93,6 +93,12 @@ import {
   patchOpenUrlWithOnRedirect
 } from './Auth0Client.utils';
 import { CustomTokenExchangeOptions } from './TokenExchange';
+import { Dpop } from './dpop/dpop';
+import {
+  Fetcher,
+  type FetcherConfig,
+  type CustomFetchMinimalOutput
+} from './fetcher';
 
 /**
  * @ignore
@@ -119,6 +125,7 @@ export class Auth0Client {
   private readonly tokenIssuer: string;
   private readonly scope: string;
   private readonly cookieStorage: ClientStorage;
+  private readonly dpop: Dpop | undefined;
   private readonly sessionCheckExpiryDays: number;
   private readonly orgHintCookieName: string;
   private readonly isAuthenticatedCookieName: string;
@@ -130,7 +137,6 @@ export class Auth0Client {
   private readonly userCache: ICache = new InMemoryCache().enclosedCache;
 
   private worker?: Worker;
-
   private readonly defaultOptions: Partial<Auth0ClientOptions> = {
     authorizationParams: {
       scope: DEFAULT_SCOPE
@@ -222,6 +228,10 @@ export class Auth0Client {
       this.nowProvider
     );
 
+    this.dpop = this.options.useDpop
+      ? new Dpop(this.options.clientId)
+      : undefined;
+
     this.domainUrl = getDomain(this.options.domain);
     this.tokenIssuer = getTokenIssuer(this.options.issuer, this.domainUrl);
 
@@ -301,6 +311,7 @@ export class Auth0Client {
     const code_verifier = createRandomString();
     const code_challengeBuffer = await sha256(code_verifier);
     const code_challenge = bufferToBase64UrlEncoded(code_challengeBuffer);
+    const thumbprint = await this.dpop?.calculateThumbprint();
 
     const params = getAuthorizeParams(
       this.options,
@@ -312,7 +323,8 @@ export class Auth0Client {
       authorizationParams.redirect_uri ||
         this.options.authorizationParams.redirect_uri ||
         fallbackRedirectUri,
-      authorizeOptions?.response_mode
+      authorizeOptions?.response_mode,
+      thumbprint
     );
 
     const url = this._authorizeUrl(params);
@@ -716,11 +728,17 @@ export class Auth0Client {
           ? await this._getTokenUsingRefreshToken(getTokenOptions)
           : await this._getTokenFromIFrame(getTokenOptions);
 
-        const { id_token, access_token, oauthTokenScope, expires_in } =
-          authResult;
+        const {
+          id_token,
+          token_type,
+          access_token,
+          oauthTokenScope,
+          expires_in
+        } = authResult;
 
         return {
           id_token,
+          token_type,
           access_token,
           ...(oauthTokenScope ? { scope: oauthTokenScope } : null),
           expires_in
@@ -848,6 +866,8 @@ export class Auth0Client {
     });
     this.userCache.remove(CACHE_KEY_ID_TOKEN_SUFFIX);
 
+    await this.dpop?.clear();
+
     const url = this._buildLogoutUrl(logoutOptions);
 
     if (openUrl) {
@@ -901,7 +921,15 @@ export class Auth0Client {
       const authorizeTimeout =
         options.timeoutInSeconds || this.options.authorizeTimeoutInSeconds;
 
-      const codeResult = await runIframe(url, this.domainUrl, authorizeTimeout);
+      // Extract origin from domainUrl, fallback to domainUrl if URL parsing fails
+      let eventOrigin: string;
+      try {
+        eventOrigin = new URL(this.domainUrl).origin;
+      } catch {
+        eventOrigin = this.domainUrl;
+      }
+
+      const codeResult = await runIframe(url, eventOrigin, authorizeTimeout);
 
       if (stateIn !== codeResult.state) {
         throw new GenericError('state_mismatch', 'Invalid state');
@@ -1072,11 +1100,13 @@ export class Auth0Client {
     );
 
     if (entry && entry.access_token) {
-      const { access_token, oauthTokenScope, expires_in } = entry as CacheEntry;
+      const { token_type, access_token, oauthTokenScope, expires_in } =
+        entry as CacheEntry;
       const cache = await this._getIdTokenFromCache();
       return (
         cache && {
           id_token: cache.id_token,
+          token_type: token_type ? token_type : 'Bearer',
           access_token,
           ...(oauthTokenScope ? { scope: oauthTokenScope } : null),
           expires_in
@@ -1112,6 +1142,7 @@ export class Auth0Client {
         auth0Client: this.options.auth0Client,
         useFormData: this.options.useFormData,
         timeout: this.httpTimeoutMs,
+        dpop: this.dpop,
         ...options
       },
       this.worker
@@ -1171,7 +1202,7 @@ export class Auth0Client {
    * - `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, as determined by the SDK's authorization configuration.
+   * - `audience`: The target audience from the options, with fallback to the SDK's authorization configuration.
    *
    * **Example Usage:**
    *
@@ -1180,15 +1211,15 @@ export class Auth0Client {
    * const options: CustomTokenExchangeOptions = {
    *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
    *   subject_token_type: 'urn:acme:legacy-system-token',
-   *   scope: ['openid', 'profile']
+   *   scope: "openid profile"
    * };
    *
    * // Exchange the external token for Auth0 tokens
    * try {
    *   const tokenResponse = await instance.exchangeToken(options);
-   *   console.log('Token response:', tokenResponse);
+   *   // Use tokenResponse.access_token, tokenResponse.id_token, etc.
    * } catch (error) {
-   *   console.error('Token exchange failed:', error);
+   *   // Handle token exchange error
    * }
    * ```
    */
@@ -1200,7 +1231,91 @@ export class Auth0Client {
       subject_token: options.subject_token,
       subject_token_type: options.subject_token_type,
       scope: getUniqueScopes(options.scope, this.scope),
-      audience: this.options.authorizationParams.audience
+      audience: options.audience || this.options.authorizationParams.audience
+    });
+  }
+
+  protected _assertDpop(dpop: Dpop | undefined): asserts dpop is Dpop {
+    if (!dpop) {
+      throw new Error('`useDpop` option must be enabled before using 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.
+   */
+  public getDpopNonce(id?: string): Promise<string | undefined> {
+    this._assertDpop(this.dpop);
+
+    return this.dpop.getNonce(id);
+  }
+
+  /**
+   * 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.
+   */
+  public setDpopNonce(nonce: string, id?: string): Promise<void> {
+    this._assertDpop(this.dpop);
+
+    return this.dpop.setNonce(nonce, id);
+  }
+
+  /**
+   * 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.
+   */
+  public generateDpopProof(params: {
+    url: string;
+    method: string;
+    nonce?: string;
+    accessToken: string;
+  }): Promise<string> {
+    this._assertDpop(this.dpop);
+
+    return this.dpop.generateProof(params);
+  }
+
+  /**
+   * 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.
+   */
+  public createFetcher<TOutput extends CustomFetchMinimalOutput = Response>(
+    config: FetcherConfig<TOutput> = {}
+  ): Fetcher<TOutput> {
+    if (this.options.useDpop && !config.dpopNonceId) {
+      throw new TypeError(
+        'When `useDpop` is enabled, `dpopNonceId` must be set when calling `createFetcher()`.'
+      );
+    }
+
+    return new Fetcher(config, {
+      isDpopEnabled: () => !!this.options.useDpop,
+      getAccessToken: () => this.getTokenSilently(),
+      getDpopNonce: () => this.getDpopNonce(config.dpopNonceId),
+      setDpopNonce: nonce => this.setDpopNonce(nonce),
+      generateDpopProof: params => this.generateDpopProof(params)
     });
   }
 }

package/src/Auth0Client.utils.ts

@@ -57,7 +57,8 @@ export const getAuthorizeParams = (
   nonce: string,
   code_challenge: string,
   redirect_uri: string | undefined,
-  response_mode: string | undefined
+  response_mode: string | undefined,
+  thumbprint: string | undefined
 ): AuthorizeOptions => {
   return {
     client_id: clientOptions.clientId,
@@ -71,7 +72,8 @@ export const getAuthorizeParams = (
     redirect_uri:
       redirect_uri || clientOptions.authorizationParams.redirect_uri,
     code_challenge,
-    code_challenge_method: 'S256'
+    code_challenge_method: 'S256',
+    dpop_jkt: thumbprint
   };
 };
 

package/src/TokenExchange.ts

@@ -38,12 +38,13 @@ export type CustomTokenExchangeOptions = {
    * The target audience for the requested Auth0 token
    *
    * @remarks
-   * Must match exactly with an API identifier configured in your Auth0 tenant
+   * Must match exactly with an API identifier configured in your Auth0 tenant.
+   * If not provided, falls back to the client's default audience.
    *
    * @example
    * "https://api.your-service.com/v1"
    */
-  audience: string;
+  audience?: string;
 
   /**
    * Space-separated list of OAuth 2.0 scopes being requested

package/src/api.ts

@@ -1,5 +1,6 @@
 import { TokenEndpointOptions, TokenEndpointResponse } from './global';
 import { DEFAULT_AUTH0_CLIENT } from './constants';
+import * as dpopUtils from './dpop/utils';
 import { getJSON } from './http';
 import { createQueryParams } from './utils';
 
@@ -11,13 +12,25 @@ export async function oauthToken(
     scope,
     auth0Client,
     useFormData,
+    dpop,
     ...options
   }: TokenEndpointOptions,
   worker?: Worker
 ) {
+  const isTokenExchange =
+    options.grant_type === 'urn:ietf:params:oauth:grant-type:token-exchange';
+
+  const allParams = {
+    ...options,
+    ...(isTokenExchange && audience && { audience }),
+    ...(isTokenExchange && scope && { scope })
+  };
+
   const body = useFormData
-    ? createQueryParams(options)
-    : JSON.stringify(options);
+    ? createQueryParams(allParams)
+    : JSON.stringify(allParams);
+
+  const isDpopSupported = dpopUtils.isGrantTypeSupported(options.grant_type);
 
   return await getJSON<TokenEndpointResponse>(
     `${baseUrl}/oauth/token`,
@@ -37,6 +50,7 @@ export async function oauthToken(
       }
     },
     worker,
-    useFormData
+    useFormData,
+    isDpopSupported ? dpop : undefined
   );
 }

package/src/cache/shared.ts

@@ -73,6 +73,7 @@ export interface IdTokenEntry {
 
 export type CacheEntry = {
   id_token?: string;
+  token_type?: string;
   access_token: string;
   expires_in: number;
   decodedToken?: DecodedToken;

package/src/dpop/dpop.ts

@@ -0,0 +1,56 @@
+import { DpopStorage } from './storage';
+import * as dpopUtils from './utils';
+
+export class Dpop {
+  protected readonly storage: DpopStorage;
+
+  public constructor(clientId: string) {
+    this.storage = new DpopStorage(clientId);
+  }
+
+  public getNonce(id?: string): Promise<string | undefined> {
+    return this.storage.findNonce(id);
+  }
+
+  public setNonce(nonce: string, id?: string): Promise<void> {
+    return this.storage.setNonce(nonce, id);
+  }
+
+  protected async getOrGenerateKeyPair(): Promise<dpopUtils.KeyPair> {
+    let keyPair = await this.storage.findKeyPair();
+
+    if (!keyPair) {
+      keyPair = await dpopUtils.generateKeyPair();
+      await this.storage.setKeyPair(keyPair);
+    }
+
+    return keyPair;
+  }
+
+  public async generateProof(params: {
+    url: string;
+    method: string;
+    nonce?: string;
+    accessToken?: string;
+  }): Promise<string> {
+    const keyPair = await this.getOrGenerateKeyPair();
+
+    return dpopUtils.generateProof({
+      keyPair,
+      ...params
+    });
+  }
+
+  public async calculateThumbprint(): Promise<string> {
+    const keyPair = await this.getOrGenerateKeyPair();
+
+    return dpopUtils.calculateThumbprint(keyPair);
+  }
+
+  public async clear(): Promise<void> {
+    await Promise.all([
+      this.storage.clearNonces(),
+      this.storage.clearKeyPairs()
+    ]);
+  }
+}

package/src/dpop/storage.ts

@@ -0,0 +1,134 @@
+import { type KeyPair } from './utils';
+
+const VERSION = 1;
+const NAME = 'auth0-spa-js';
+const TABLES = {
+  NONCE: 'nonce',
+  KEYPAIR: 'keypair'
+} as const;
+
+const AUTH0_NONCE_ID = 'auth0';
+
+type Table = (typeof TABLES)[keyof typeof TABLES];
+
+export class DpopStorage {
+  protected readonly clientId: string;
+  protected dbHandle: IDBDatabase | undefined;
+
+  constructor(clientId: string) {
+    this.clientId = clientId;
+  }
+
+  protected getVersion(): number {
+    return VERSION;
+  }
+
+  protected createDbHandle(): Promise<IDBDatabase> {
+    const req = window.indexedDB.open(NAME, this.getVersion());
+
+    return new Promise((resolve, reject) => {
+      req.onupgradeneeded = () =>
+        Object.values(TABLES).forEach(t => req.result.createObjectStore(t));
+
+      req.onerror = () => reject(req.error);
+      req.onsuccess = () => resolve(req.result);
+    });
+  }
+
+  protected async getDbHandle(): Promise<IDBDatabase> {
+    if (!this.dbHandle) {
+      this.dbHandle = await this.createDbHandle();
+    }
+
+    return this.dbHandle;
+  }
+
+  protected async executeDbRequest<T = unknown>(
+    table: string,
+    mode: IDBTransactionMode,
+    requestFactory: (table: IDBObjectStore) => IDBRequest<T>
+  ): Promise<T> {
+    const db = await this.getDbHandle();
+
+    const txn = db.transaction(table, mode);
+    const store = txn.objectStore(table);
+
+    const request = requestFactory(store);
+
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  protected buildKey(id?: string): string {
+    const finalId = id
+      ? `_${id}` // prefix to avoid collisions
+      : AUTH0_NONCE_ID;
+
+    return `${this.clientId}::${finalId}`;
+  }
+
+  public setNonce(nonce: string, id?: string): Promise<void> {
+    return this.save(TABLES.NONCE, this.buildKey(id), nonce);
+  }
+
+  public setKeyPair(keyPair: KeyPair): Promise<void> {
+    return this.save(TABLES.KEYPAIR, this.buildKey(), keyPair);
+  }
+
+  protected async save(
+    table: Table,
+    key: IDBValidKey,
+    obj: unknown
+  ): Promise<void> {
+    return void await this.executeDbRequest(table, 'readwrite', table =>
+      table.put(obj, key)
+    );
+  }
+
+  public findNonce(id?: string): Promise<string | undefined> {
+    return this.find(TABLES.NONCE, this.buildKey(id));
+  }
+
+  public findKeyPair(): Promise<KeyPair | undefined> {
+    return this.find(TABLES.KEYPAIR, this.buildKey());
+  }
+
+  protected find<T = unknown>(
+    table: Table,
+    key: IDBValidKey
+  ): Promise<T | undefined> {
+    return this.executeDbRequest(table, 'readonly', table => table.get(key));
+  }
+
+  protected async deleteBy(
+    table: Table,
+    predicate: (key: IDBValidKey) => boolean
+  ): Promise<void> {
+    const allKeys = await this.executeDbRequest(table, 'readonly', table =>
+      table.getAllKeys()
+    );
+
+    allKeys
+      ?.filter(predicate)
+      .map(k =>
+        this.executeDbRequest(table, 'readwrite', table => table.delete(k))
+      );
+  }
+
+  protected deleteByClientId(table: Table, clientId: string): Promise<void> {
+    return this.deleteBy(
+      table,
+      k => typeof k === 'string' && k.startsWith(`${clientId}::`)
+    );
+  }
+
+  public clearNonces(): Promise<void> {
+    return this.deleteByClientId(TABLES.NONCE, this.clientId);
+  }
+
+  public clearKeyPairs(): Promise<void> {
+    return this.deleteByClientId(TABLES.KEYPAIR, this.clientId);
+  }
+}

package/src/dpop/utils.ts

@@ -0,0 +1,66 @@
+import * as dpopLib from 'dpop';
+
+export const DPOP_NONCE_HEADER = 'dpop-nonce';
+
+const KEY_PAIR_ALGORITHM: dpopLib.JWSAlgorithm = 'ES256';
+
+const SUPPORTED_GRANT_TYPES = [
+  'authorization_code',
+  'refresh_token',
+  'urn:ietf:params:oauth:grant-type:token-exchange'
+];
+
+export type KeyPair = Readonly<dpopLib.KeyPair>;
+
+type GenerateProofParams = {
+  keyPair: KeyPair;
+  url: string;
+  method: string;
+  nonce?: string;
+  accessToken?: string;
+};
+
+export function generateKeyPair(): Promise<KeyPair> {
+  return dpopLib.generateKeyPair(KEY_PAIR_ALGORITHM, { extractable: false });
+}
+
+export function calculateThumbprint(
+  keyPair: Pick<KeyPair, 'publicKey'>
+): Promise<string> {
+  return dpopLib.calculateThumbprint(keyPair.publicKey);
+}
+
+function normalizeUrl(url: string): string {
+  const parsedUrl = new URL(url);
+
+  /**
+   * "The HTTP target URI (...) without query and fragment parts"
+   * @see {@link https://www.rfc-editor.org/rfc/rfc9449.html#section-4.2-4.6}
+   */
+  parsedUrl.search = '';
+  parsedUrl.hash = '';
+
+  return parsedUrl.href;
+}
+
+export function generateProof({
+  keyPair,
+  url,
+  method,
+  nonce,
+  accessToken
+}: GenerateProofParams): Promise<string> {
+  const normalizedUrl = normalizeUrl(url);
+
+  return dpopLib.generateProof(
+    keyPair,
+    normalizedUrl,
+    method,
+    nonce,
+    accessToken
+  );
+}
+
+export function isGrantTypeSupported(grantType: string): boolean {
+  return SUPPORTED_GRANT_TYPES.includes(grantType);
+}

package/src/errors.ts

@@ -96,6 +96,17 @@ export class MissingRefreshTokenError extends GenericError {
   }
 }
 
+/**
+ * Error thrown when the wrong DPoP nonce is used and a potential subsequent retry wasn't able to fix it.
+ */
+export class UseDpopNonceError extends GenericError {
+  constructor(public newDpopNonce: string | undefined) {
+    super('use_dpop_nonce', 'Server rejected DPoP proof: wrong nonce');
+
+    Object.setPrototypeOf(this, UseDpopNonceError.prototype);
+  }
+}
+
 /**
  * Returns an empty string when value is falsy, or when it's value is included in the exclude argument.
  * @param value The value to check