@auth0/auth0-spa-js 2.3.0 → 2.4.0

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

package/src/fetcher.ts

@@ -0,0 +1,224 @@
+import { DPOP_NONCE_HEADER } from './dpop/utils';
+import { UseDpopNonceError } from './errors';
+
+export type ResponseHeaders =
+  | Record<string, string | null | undefined>
+  | [string, string][]
+  | { get(name: string): string | null | undefined };
+
+export type CustomFetchMinimalOutput = {
+  status: number;
+  headers: ResponseHeaders;
+};
+
+export type CustomFetchImpl<TOutput extends CustomFetchMinimalOutput> = (
+  req: Request
+) => Promise<TOutput>;
+
+type AccessTokenFactory = () => Promise<string>;
+
+export type FetcherConfig<TOutput extends CustomFetchMinimalOutput> = {
+  getAccessToken?: AccessTokenFactory;
+  baseUrl?: string;
+  fetch?: CustomFetchImpl<TOutput>;
+  dpopNonceId?: string;
+};
+
+export type FetcherHooks = {
+  isDpopEnabled: () => boolean;
+  getAccessToken: () => Promise<string>;
+  getDpopNonce: () => Promise<string | undefined>;
+  setDpopNonce: (nonce: string) => Promise<void>;
+  generateDpopProof: (params: {
+    url: string;
+    method: string;
+    nonce?: string;
+    accessToken: string;
+  }) => Promise<string>;
+};
+
+export type FetchWithAuthCallbacks<TOutput> = {
+  onUseDpopNonceError?(): Promise<TOutput>;
+};
+
+export class Fetcher<TOutput extends CustomFetchMinimalOutput> {
+  protected readonly config: Omit<FetcherConfig<TOutput>, 'fetch'> &
+    Required<Pick<FetcherConfig<TOutput>, 'fetch'>>;
+
+  protected readonly hooks: FetcherHooks;
+
+  constructor(config: FetcherConfig<TOutput>, hooks: FetcherHooks) {
+    this.hooks = hooks;
+
+    this.config = {
+      ...config,
+      fetch:
+        config.fetch ||
+        // For easier testing and constructor compatibility with SSR.
+        ((typeof window === 'undefined'
+          ? fetch
+          : window.fetch.bind(window)) as () => Promise<any>)
+    };
+  }
+
+  protected isAbsoluteUrl(url: string): boolean {
+    // `http://example.com`, `https://example.com` or `//example.com`
+    return /^(https?:)?\/\//i.test(url);
+  }
+
+  protected buildUrl(
+    baseUrl: string | undefined,
+    url: string | undefined
+  ): string {
+    if (url) {
+      if (this.isAbsoluteUrl(url)) {
+        return url;
+      }
+
+      if (baseUrl) {
+        return `${baseUrl.replace(/\/?\/$/, '')}/${url.replace(/^\/+/, '')}`;
+      }
+    }
+
+    throw new TypeError('`url` must be absolute or `baseUrl` non-empty.');
+  }
+
+  protected getAccessToken(): Promise<string> {
+    return this.config.getAccessToken
+      ? this.config.getAccessToken()
+      : this.hooks.getAccessToken();
+  }
+
+  protected buildBaseRequest(
+    info: RequestInfo | URL,
+    init: RequestInit | undefined
+  ): Request {
+    // In the native `fetch()` behavior, `init` can override `info` and the result
+    // is the merge of both. So let's replicate that behavior by passing those into
+    // a fresh `Request` object.
+    const request = new Request(info, init);
+
+    // No `baseUrl` config, use whatever the URL the `Request` came with.
+    if (!this.config.baseUrl) {
+      return request;
+    }
+
+    return new Request(
+      this.buildUrl(this.config.baseUrl, request.url),
+      request
+    );
+  }
+
+  protected async setAuthorizationHeader(
+    request: Request,
+    accessToken: string
+  ): Promise<void> {
+    request.headers.set(
+      'authorization',
+      `${this.config.dpopNonceId ? 'DPoP' : 'Bearer'} ${accessToken}`
+    );
+  }
+
+  protected async setDpopProofHeader(
+    request: Request,
+    accessToken: string
+  ): Promise<void> {
+    if (!this.config.dpopNonceId) {
+      return;
+    }
+
+    const dpopNonce = await this.hooks.getDpopNonce();
+
+    const dpopProof = await this.hooks.generateDpopProof({
+      accessToken,
+      method: request.method,
+      nonce: dpopNonce,
+      url: request.url
+    });
+
+    request.headers.set('dpop', dpopProof);
+  }
+
+  protected async prepareRequest(request: Request) {
+    const accessToken = await this.getAccessToken();
+
+    this.setAuthorizationHeader(request, accessToken);
+
+    await this.setDpopProofHeader(request, accessToken);
+  }
+
+  protected getHeader(headers: ResponseHeaders, name: string): string {
+    if (Array.isArray(headers)) {
+      return new Headers(headers).get(name) || '';
+    }
+
+    if (typeof headers.get === 'function') {
+      return headers.get(name) || '';
+    }
+
+    return (headers as Record<string, string | null | undefined>)[name] || '';
+  }
+
+  protected hasUseDpopNonceError(response: TOutput): boolean {
+    if (response.status !== 401) {
+      return false;
+    }
+
+    const wwwAuthHeader = this.getHeader(response.headers, 'www-authenticate');
+
+    return wwwAuthHeader.includes('use_dpop_nonce');
+  }
+
+  protected async handleResponse(
+    response: TOutput,
+    callbacks: FetchWithAuthCallbacks<TOutput>
+  ): Promise<TOutput> {
+    const newDpopNonce = this.getHeader(response.headers, DPOP_NONCE_HEADER);
+
+    if (newDpopNonce) {
+      await this.hooks.setDpopNonce(newDpopNonce);
+    }
+
+    if (!this.hasUseDpopNonceError(response)) {
+      return response;
+    }
+
+    // After a `use_dpop_nonce` error, if we didn't get a new DPoP nonce or we
+    // did but it still got rejected for the same reason, we have to give up.
+    if (!newDpopNonce || !callbacks.onUseDpopNonceError) {
+      throw new UseDpopNonceError(newDpopNonce);
+    }
+
+    return callbacks.onUseDpopNonceError();
+  }
+
+  protected async internalFetchWithAuth(
+    info: RequestInfo | URL,
+    init: RequestInit | undefined,
+    callbacks: FetchWithAuthCallbacks<TOutput>
+  ): Promise<TOutput> {
+    const request = this.buildBaseRequest(info, init);
+
+    await this.prepareRequest(request);
+
+    const response = await this.config.fetch(request);
+
+    return this.handleResponse(response, callbacks);
+  }
+
+  public fetchWithAuth(
+    info: RequestInfo | URL,
+    init?: RequestInit
+  ): Promise<TOutput> {
+    const callbacks: FetchWithAuthCallbacks<TOutput> = {
+      onUseDpopNonceError: () =>
+        this.internalFetchWithAuth(info, init, {
+          ...callbacks,
+          // Retry on a `use_dpop_nonce` error, but just once.
+          onUseDpopNonceError: undefined
+        })
+    };
+
+    return this.internalFetchWithAuth(info, init, callbacks);
+  }
+}

package/src/global.ts

@@ -1,4 +1,5 @@
 import { ICache } from './cache';
+import type { Dpop } from './dpop/dpop';
 
 export interface AuthorizationParams {
   /**
@@ -271,6 +272,15 @@ 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`, DPoP (OAuth 2.0 Demonstrating Proof of Possession, RFC9449)
+   * will be used to cryptographically bind tokens to this specific browser
+   * so they can't be used from a different device in case of a leak.
+   *
+   * The default setting is `false`.
+   */
+  useDpop?: boolean;
 }
 
 /**
@@ -527,11 +537,13 @@ export interface TokenEndpointOptions {
   timeout?: number;
   auth0Client: any;
   useFormData?: boolean;
+  dpop?: Pick<Dpop, 'generateProof' | 'getNonce' | 'setNonce'>;
   [key: string]: any;
 }
 
 export type TokenEndpointResponse = {
   id_token: string;
+  token_type: string;
   access_token: string;
   refresh_token?: string;
   expires_in: number;
@@ -647,6 +659,15 @@ export type FetchOptions = {
   signal?: AbortSignal;
 };
 
+/**
+ * @ignore
+ */
+export type FetchResponse = {
+  ok: boolean;
+  headers: Record<string, string | undefined>;
+  json: any;
+};
+
 export type GetTokenSilentlyVerboseResponse = Omit<
   TokenEndpointResponse,
   'refresh_token'

package/src/http.ts

@@ -3,13 +3,17 @@ import {
   DEFAULT_SILENT_TOKEN_RETRY_COUNT
 } from './constants';
 
+import { fromEntries } from './utils';
 import { sendMessage } from './worker/worker.utils';
-import { FetchOptions } from './global';
+import { FetchOptions, FetchResponse } from './global';
 import {
   GenericError,
   MfaRequiredError,
-  MissingRefreshTokenError
+  MissingRefreshTokenError,
+  UseDpopNonceError
 } from './errors';
+import { Dpop } from './dpop/dpop';
+import { DPOP_NONCE_HEADER } from './dpop/utils';
 
 export const createAbortController = () => new AbortController();
 
@@ -18,7 +22,14 @@ const dofetch = async (fetchUrl: string, fetchOptions: FetchOptions) => {
 
   return {
     ok: response.ok,
-    json: await response.json()
+    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)
   };
 };
 
@@ -102,10 +113,22 @@ export async function getJSON<T>(
   scope: string,
   options: FetchOptions,
   worker?: Worker,
-  useFormData?: boolean
+  useFormData?: boolean,
+  dpop?: Pick<Dpop, 'generateProof' | 'getNonce' | 'setNonce'>,
+  isDpopRetry?: boolean
 ): Promise<T> {
+  if (dpop) {
+    const dpopProof = await dpop.generateProof({
+      url,
+      method: options.method || 'GET',
+      nonce: await dpop.getNonce()
+    });
+
+    options.headers = { ...options.headers, dpop: dpopProof };
+  }
+
   let fetchError: null | Error = null;
-  let response: any;
+  let response!: FetchResponse;
 
   for (let i = 0; i < DEFAULT_SILENT_TOKEN_RETRY_COUNT; i++) {
     try {
@@ -135,9 +158,25 @@ export async function getJSON<T>(
 
   const {
     json: { error, error_description, ...data },
+    headers,
     ok
   } = response;
 
+  let newDpopNonce: string | undefined;
+
+  if (dpop) {
+    /**
+     * Note that a new DPoP nonce can appear in both error and success responses!
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc9449.html#section-8.2-3}
+     */
+    newDpopNonce = headers[DPOP_NONCE_HEADER];
+
+    if (newDpopNonce) {
+      await dpop.setNonce(newDpopNonce);
+    }
+  }
+
   if (!ok) {
     const errorMessage =
       error_description || `HTTP error. Unable to fetch ${url}`;
@@ -150,6 +189,32 @@ export async function getJSON<T>(
       throw new MissingRefreshTokenError(audience, scope);
     }
 
+    /**
+     * When DPoP is used and we get a `use_dpop_nonce` error from the server,
+     * we must retry ONCE with any new nonce received in the rejected request.
+     *
+     * If a new nonce was not received or the retry fails again, we give up and
+     * throw the error as is.
+     */
+    if (error === 'use_dpop_nonce') {
+      if (!dpop || !newDpopNonce || isDpopRetry) {
+        throw new UseDpopNonceError(newDpopNonce);
+      }
+
+      // repeat the call but with isDpopRetry=true to avoid any more retries
+      return getJSON(
+        url,
+        timeout,
+        audience,
+        scope,
+        options,
+        worker,
+        useFormData,
+        dpop,
+        true // !
+      );
+    }
+
     throw new GenericError(error || 'request_error', errorMessage);
   }
 

package/src/index.ts

@@ -29,7 +29,8 @@ export {
   PopupTimeoutError,
   PopupCancelledError,
   MfaRequiredError,
-  MissingRefreshTokenError
+  MissingRefreshTokenError,
+  UseDpopNonceError
 } from './errors';
 
 export {
@@ -45,3 +46,5 @@ export {
   CacheKey,
   CacheKeyData
 } from './cache';
+
+export { type FetcherConfig } from './fetcher';

package/src/utils.ts

@@ -246,3 +246,18 @@ export const parseNumber = (value: any): number | undefined => {
   }
   return parseInt(value, 10) || undefined;
 };
+
+/**
+ * Ponyfill for `Object.fromEntries()`, which is not available until ES2020.
+ *
+ * When the target of this project reaches ES2020, this can be removed.
+ */
+export const fromEntries = <T = any>(
+  iterable: Iterable<[PropertyKey, T]>
+): Record<PropertyKey, T> => {
+  return [...iterable].reduce((obj, [key, val]) => {
+    obj[key] = val;
+
+    return obj;
+  }, {} as Record<PropertyKey, T>);
+};

package/src/version.ts

@@ -1 +1 @@
-export default '2.3.0';
+export default '2.4.0';