@auth0/auth0-spa-js 2.2.0 → 2.4.0

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 {
   /**
@@ -84,6 +85,8 @@ export interface AuthorizationParams {
    *
    * - If you provide an Organization ID (a string with the prefix `org_`), it will be validated against the `org_id` claim of your user's ID Token. The validation is case-sensitive.
    * - If you provide an Organization Name (a string *without* the prefix `org_`), it will be validated against the `org_name` claim of your user's ID Token. The validation is case-insensitive.
+   *   To use an Organization Name you must have "Allow Organization Names in Authentication API" switched on in your Auth0 settings dashboard.
+   *   More information is available on the [Auth0 documentation portal](https://auth0.com/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api)
    *
    */
   organization?: string;
@@ -269,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;
 }
 
 /**
@@ -525,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;
@@ -645,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.2.0';
+export default '2.4.0';

package/src/worker/token.worker.ts

@@ -1,5 +1,6 @@
 import { MissingRefreshTokenError } from '../errors';
-import { createQueryParams } from '../utils';
+import { FetchResponse } from '../global';
+import { createQueryParams, fromEntries } from '../utils';
 import { WorkerRefreshTokenMessage } from './worker.types';
 
 let refreshTokens: Record<string, string> = {};
@@ -19,7 +20,7 @@ const deleteRefreshToken = (audience: string, scope: string) =>
   delete refreshTokens[cacheKey(audience, scope)];
 
 const wait = (time: number) =>
-  new Promise(resolve => setTimeout(resolve, time));
+  new Promise<void>(resolve => setTimeout(resolve, time));
 
 const formDataToObject = (formData: string): Record<string, any> => {
   const queryParams = new URLSearchParams(formData);
@@ -36,6 +37,8 @@ const messageHandler = async ({
   data: { timeout, auth, fetchUrl, fetchOptions, useFormData },
   ports: [port]
 }: MessageEvent<WorkerRefreshTokenMessage>) => {
+  let headers: FetchResponse['headers'] = {};
+
   let json: {
     refresh_token?: string;
   };
@@ -72,7 +75,7 @@ const messageHandler = async ({
       fetchOptions.signal = abortController.signal;
     }
 
-    let response: any;
+    let response: void | Response;
 
     try {
       response = await Promise.race([
@@ -99,6 +102,7 @@ const messageHandler = async ({
       return;
     }
 
+    headers = fromEntries(response.headers);
     json = await response.json();
 
     if (json.refresh_token) {
@@ -110,7 +114,8 @@ const messageHandler = async ({
 
     port.postMessage({
       ok: response.ok,
-      json
+      json,
+      headers
     });
   } catch (error) {
     port.postMessage({
@@ -118,7 +123,8 @@ const messageHandler = async ({
       json: {
         error: error.error,
         error_description: error.message
-      }
+      },
+      headers
     });
   }
 };