@auth0/auth0-spa-js 2.2.0 → 2.4.0

package/dist/typings/Auth0Client.d.ts

@@ -1,5 +1,7 @@
 import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse } 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).
  */
@@ -10,6 +12,7 @@ export declare class Auth0Client {
     private readonly tokenIssuer;
     private readonly scope;
     private readonly cookieStorage;
+    private readonly dpop;
     private readonly sessionCheckExpiryDays;
     private readonly orgHintCookieName;
     private readonly isAuthenticatedCookieName;
@@ -204,7 +207,7 @@ export declare 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:**
      *
@@ -213,17 +216,64 @@ export declare 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
      * }
      * ```
      */
     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>;
 }

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

@@ -25,7 +25,7 @@ export declare const cacheFactory: (location: string) => () => ICache;
  */
 export declare const getAuthorizeParams: (clientOptions: Auth0ClientOptions & {
     authorizationParams: AuthorizationParams;
-}, scope: string, authorizationParams: AuthorizationParams, state: string, nonce: string, code_challenge: string, redirect_uri: string | undefined, response_mode: string | undefined) => AuthorizeOptions;
+}, scope: string, authorizationParams: AuthorizationParams, state: string, nonce: string, code_challenge: string, redirect_uri: string | undefined, response_mode: string | undefined, thumbprint: string | undefined) => AuthorizeOptions;
 /**
  * @ignore
  *

package/dist/typings/TokenExchange.d.ts

@@ -36,12 +36,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/dist/typings/api.d.ts

@@ -1,2 +1,2 @@
 import { TokenEndpointOptions, TokenEndpointResponse } from './global';
-export declare function oauthToken({ baseUrl, timeout, audience, scope, auth0Client, useFormData, ...options }: TokenEndpointOptions, worker?: Worker): Promise<TokenEndpointResponse>;
+export declare function oauthToken({ baseUrl, timeout, audience, scope, auth0Client, useFormData, dpop, ...options }: TokenEndpointOptions, worker?: Worker): Promise<TokenEndpointResponse>;

package/dist/typings/cache/shared.d.ts

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

package/dist/typings/dpop/dpop.d.ts

@@ -0,0 +1,17 @@
+import { DpopStorage } from './storage';
+import * as dpopUtils from './utils';
+export declare class Dpop {
+    protected readonly storage: DpopStorage;
+    constructor(clientId: string);
+    getNonce(id?: string): Promise<string | undefined>;
+    setNonce(nonce: string, id?: string): Promise<void>;
+    protected getOrGenerateKeyPair(): Promise<dpopUtils.KeyPair>;
+    generateProof(params: {
+        url: string;
+        method: string;
+        nonce?: string;
+        accessToken?: string;
+    }): Promise<string>;
+    calculateThumbprint(): Promise<string>;
+    clear(): Promise<void>;
+}

package/dist/typings/dpop/storage.d.ts

@@ -0,0 +1,27 @@
+import { type KeyPair } from './utils';
+declare const TABLES: {
+    readonly NONCE: "nonce";
+    readonly KEYPAIR: "keypair";
+};
+type Table = (typeof TABLES)[keyof typeof TABLES];
+export declare class DpopStorage {
+    protected readonly clientId: string;
+    protected dbHandle: IDBDatabase | undefined;
+    constructor(clientId: string);
+    protected getVersion(): number;
+    protected createDbHandle(): Promise<IDBDatabase>;
+    protected getDbHandle(): Promise<IDBDatabase>;
+    protected executeDbRequest<T = unknown>(table: string, mode: IDBTransactionMode, requestFactory: (table: IDBObjectStore) => IDBRequest<T>): Promise<T>;
+    protected buildKey(id?: string): string;
+    setNonce(nonce: string, id?: string): Promise<void>;
+    setKeyPair(keyPair: KeyPair): Promise<void>;
+    protected save(table: Table, key: IDBValidKey, obj: unknown): Promise<void>;
+    findNonce(id?: string): Promise<string | undefined>;
+    findKeyPair(): Promise<KeyPair | undefined>;
+    protected find<T = unknown>(table: Table, key: IDBValidKey): Promise<T | undefined>;
+    protected deleteBy(table: Table, predicate: (key: IDBValidKey) => boolean): Promise<void>;
+    protected deleteByClientId(table: Table, clientId: string): Promise<void>;
+    clearNonces(): Promise<void>;
+    clearKeyPairs(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,15 @@
+import * as dpopLib from 'dpop';
+export declare const DPOP_NONCE_HEADER = "dpop-nonce";
+export type KeyPair = Readonly<dpopLib.KeyPair>;
+type GenerateProofParams = {
+    keyPair: KeyPair;
+    url: string;
+    method: string;
+    nonce?: string;
+    accessToken?: string;
+};
+export declare function generateKeyPair(): Promise<KeyPair>;
+export declare function calculateThumbprint(keyPair: Pick<KeyPair, 'publicKey'>): Promise<string>;
+export declare function generateProof({ keyPair, url, method, nonce, accessToken }: GenerateProofParams): Promise<string>;
+export declare function isGrantTypeSupported(grantType: string): boolean;
+export {};

package/dist/typings/errors.d.ts

@@ -52,3 +52,10 @@ export declare class MissingRefreshTokenError extends GenericError {
     scope: string;
     constructor(audience: string, scope: string);
 }
+/**
+ * Error thrown when the wrong DPoP nonce is used and a potential subsequent retry wasn't able to fix it.
+ */
+export declare class UseDpopNonceError extends GenericError {
+    newDpopNonce: string | undefined;
+    constructor(newDpopNonce: string | undefined);
+}

package/dist/typings/fetcher.d.ts

@@ -0,0 +1,48 @@
+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 declare 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);
+    protected isAbsoluteUrl(url: string): boolean;
+    protected buildUrl(baseUrl: string | undefined, url: string | undefined): string;
+    protected getAccessToken(): Promise<string>;
+    protected buildBaseRequest(info: RequestInfo | URL, init: RequestInit | undefined): Request;
+    protected setAuthorizationHeader(request: Request, accessToken: string): Promise<void>;
+    protected setDpopProofHeader(request: Request, accessToken: string): Promise<void>;
+    protected prepareRequest(request: Request): Promise<void>;
+    protected getHeader(headers: ResponseHeaders, name: string): string;
+    protected hasUseDpopNonceError(response: TOutput): boolean;
+    protected handleResponse(response: TOutput, callbacks: FetchWithAuthCallbacks<TOutput>): Promise<TOutput>;
+    protected internalFetchWithAuth(info: RequestInfo | URL, init: RequestInit | undefined, callbacks: FetchWithAuthCallbacks<TOutput>): Promise<TOutput>;
+    fetchWithAuth(info: RequestInfo | URL, init?: RequestInit): Promise<TOutput>;
+}
+export {};

package/dist/typings/global.d.ts

@@ -1,4 +1,5 @@
 import { ICache } from './cache';
+import type { Dpop } from './dpop/dpop';
 export interface AuthorizationParams {
     /**
      * - `'page'`: displays the UI with a full page view
@@ -72,6 +73,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;
@@ -240,6 +243,14 @@ 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;
 }
 /**
  * The possible locations where tokens can be stored
@@ -473,10 +484,12 @@ 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;
@@ -585,5 +598,13 @@ export type FetchOptions = {
     body?: string;
     signal?: AbortSignal;
 };
+/**
+ * @ignore
+ */
+export type FetchResponse = {
+    ok: boolean;
+    headers: Record<string, string | undefined>;
+    json: any;
+};
 export type GetTokenSilentlyVerboseResponse = Omit<TokenEndpointResponse, 'refresh_token'>;
 export {};

package/dist/typings/http.d.ts

@@ -1,4 +1,5 @@
 import { FetchOptions } from './global';
+import { Dpop } from './dpop/dpop';
 export declare const createAbortController: () => AbortController;
 export declare const switchFetch: (fetchUrl: string, audience: string, scope: string, fetchOptions: FetchOptions, worker?: Worker, useFormData?: boolean, timeout?: number) => Promise<any>;
-export declare function getJSON<T>(url: string, timeout: number | undefined, audience: string, scope: string, options: FetchOptions, worker?: Worker, useFormData?: boolean): Promise<T>;
+export declare function getJSON<T>(url: string, timeout: number | undefined, audience: string, scope: string, options: FetchOptions, worker?: Worker, useFormData?: boolean, dpop?: Pick<Dpop, 'generateProof' | 'getNonce' | 'setNonce'>, isDpopRetry?: boolean): Promise<T>;

package/dist/typings/index.d.ts

@@ -13,5 +13,6 @@ export * from './global';
  */
 export declare function createAuth0Client(options: Auth0ClientOptions): Promise<Auth0Client>;
 export { Auth0Client };
-export { GenericError, AuthenticationError, TimeoutError, PopupTimeoutError, PopupCancelledError, MfaRequiredError, MissingRefreshTokenError } from './errors';
+export { GenericError, AuthenticationError, TimeoutError, PopupTimeoutError, PopupCancelledError, MfaRequiredError, MissingRefreshTokenError, UseDpopNonceError } from './errors';
 export { ICache, LocalStorageCache, InMemoryCache, Cacheable, DecodedToken, CacheEntry, WrappedCacheEntry, KeyManifestEntry, MaybePromise, CacheKey, CacheKeyData } from './cache';
+export { type FetcherConfig } from './fetcher';

package/dist/typings/utils.d.ts

@@ -21,3 +21,9 @@ export declare const getDomain: (domainUrl: string) => string;
  */
 export declare const getTokenIssuer: (issuer: string | undefined, domainUrl: string) => string;
 export declare const parseNumber: (value: any) => number | undefined;
+/**
+ * Ponyfill for `Object.fromEntries()`, which is not available until ES2020.
+ *
+ * When the target of this project reaches ES2020, this can be removed.
+ */
+export declare const fromEntries: <T = any>(iterable: Iterable<[PropertyKey, T]>) => Record<PropertyKey, T>;

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.2.0";
+declare const _default: "2.4.0";
 export default _default;

package/package.json

@@ -3,16 +3,32 @@
   "name": "@auth0/auth0-spa-js",
   "description": "Auth0 SDK for Single Page Applications using Authorization Code Grant Flow with PKCE",
   "license": "MIT",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",
+  "ccu": {
+    "name": "auth0-spa-js",
+    "cdn": "https://cdn.auth0.com",
+    "bucket": "assets.us.auth0.com",
+    "localPath": "dist",
+    "mainBundleFile": "auth0-spa-js.production.js",
+    "digest": {
+      "hashes": [
+        "sha384"
+      ],
+      "extensions": [
+        ".js"
+      ]
+    }
+  },
   "scripts": {
     "dev": "rimraf dist && rollup -c --watch",
     "start": "npm run dev",
     "docs": "typedoc --options ./typedoc.js src",
     "build": "rimraf dist && rollup -m -c --environment NODE_ENV:production && npm run test:es-check",
     "build:stats": "rimraf dist && rollup -m -c --environment NODE_ENV:production --environment WITH_STATS:true && npm run test:es-check && open bundle-stats/index.html",
+    "lint": "eslint --ext .jsx,.js src/",
     "lint:security": "eslint ./src --ext ts --no-eslintrc --config ./.eslintrc.security",
     "test": "jest --coverage --silent",
     "test:watch": "jest --coverage --watch",
@@ -32,21 +48,23 @@
     "publish:cdn": "ccu --trace"
   },
   "devDependencies": {
-    "@auth0/component-cdn-uploader": "github:auth0/component-cdn-uploader#v2.2.2",
+    "@auth0/component-cdn-uploader": "^2.2.2",
     "@rollup/plugin-replace": "^4.0.0",
     "@types/cypress": "^1.1.3",
     "@types/jest": "^28.1.7",
     "@typescript-eslint/eslint-plugin-tslint": "^5.33.1",
     "@typescript-eslint/parser": "^5.33.1",
     "browser-tabs-lock": "^1.2.15",
-    "browserstack-cypress-cli": "1.28.0",
+    "browserstack-cypress-cli": "1.32.8",
     "cli-table": "^0.3.6",
     "concurrently": "^7.3.0",
-    "cypress": "13.6.1",
+    "dpop": "^2.1.1",
+    "cypress": "13.17.0",
     "es-check": "^7.0.1",
     "es-cookie": "~1.3.2",
     "eslint": "^8.22.0",
     "eslint-plugin-security": "^1.5.0",
+    "fake-indexeddb": "^6.0.1",
     "gzip-size": "^7.0.0",
     "husky": "^7.0.4",
     "idtoken-verifier": "^2.2.2",
@@ -98,21 +116,6 @@
     "Single Page Application authentication",
     "SPA authentication"
   ],
-  "ccu": {
-    "name": "auth0-spa-js",
-    "cdn": "https://cdn.auth0.com",
-    "mainBundleFile": "auth0-spa-js.production.js",
-    "bucket": "assets.us.auth0.com",
-    "localPath": "dist",
-    "digest": {
-      "hashes": [
-        "sha384"
-      ],
-      "extensions": [
-        ".js"
-      ]
-    }
-  },
   "husky": {
     "hooks": {
       "pre-commit": "pretty-quick --staged"