@auth0/auth0-spa-js 2.1.2 → 2.2.0

package/dist/typings/Auth0Client.d.ts

@@ -1,4 +1,5 @@
-import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse } from './global';
+import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse } from './global';
+import { CustomTokenExchangeOptions } from './TokenExchange';
 /**
  * Auth0 SDK for Single Page Applications using [Authorization Code Grant Flow with PKCE](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce).
  */
@@ -186,4 +187,43 @@ export declare class Auth0Client {
      */
     private _releaseLockOnPageHide;
     private _requestToken;
+    /**
+     * Exchanges an external subject token for an Auth0 token via a token exchange request.
+     *
+     * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
+     *
+     * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response,
+     * which contains the issued Auth0 tokens.
+     *
+     * This method implements the token exchange grant as specified in RFC 8693 by first validating
+     * the provided subject token type and then constructing a token request to the /oauth/token endpoint.
+     * The request includes the following parameters:
+     *
+     * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange".
+     * - `subject_token`: The external token provided via the options.
+     * - `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.
+     *
+     * **Example Usage:**
+     *
+     * ```
+     * // Define the token exchange options
+     * const options: CustomTokenExchangeOptions = {
+     *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
+     *   subject_token_type: 'urn:acme:legacy-system-token',
+     *   scope: ['openid', 'profile']
+     * };
+     *
+     * // Exchange the external token for Auth0 tokens
+     * try {
+     *   const tokenResponse = await instance.exchangeToken(options);
+     *   console.log('Token response:', tokenResponse);
+     * } catch (error) {
+     *   console.error('Token exchange failed:', error);
+     * }
+     * ```
+     */
+    exchangeToken(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>;
 }

package/dist/typings/TokenExchange.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Represents the configuration options required for initiating a Custom Token Exchange request
+ * following RFC 8693 specifications.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 | RFC 8693: OAuth 2.0 Token Exchange}
+ */
+export type CustomTokenExchangeOptions = {
+    /**
+     * The type identifier for the subject token being exchanged
+     *
+     * @pattern
+     * - Must be a namespaced URI under your organization's control
+     * - Forbidden patterns:
+     *   - `^urn:ietf:params:oauth:*` (IETF reserved)
+     *   - `^https:\/\/auth0\.com/*` (Auth0 reserved)
+     *   - `^urn:auth0:*` (Auth0 reserved)
+     *
+     * @example
+     * "urn:acme:legacy-system-token"
+     * "https://api.yourcompany.com/token-type/v1"
+     */
+    subject_token_type: string;
+    /**
+     * The opaque token value being exchanged for Auth0 tokens
+     *
+     * @security
+     * - Must be validated in Auth0 Actions using strong cryptographic verification
+     * - Implement replay attack protection
+     * - Recommended validation libraries: `jose`, `jsonwebtoken`
+     *
+     * @example
+     * "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+     */
+    subject_token: string;
+    /**
+     * The target audience for the requested Auth0 token
+     *
+     * @remarks
+     * Must match exactly with an API identifier configured in your Auth0 tenant
+     *
+     * @example
+     * "https://api.your-service.com/v1"
+     */
+    audience: string;
+    /**
+     * Space-separated list of OAuth 2.0 scopes being requested
+     *
+     * @remarks
+     * Subject to API authorization policies configured in Auth0
+     *
+     * @example
+     * "openid profile email read:data write:data"
+     */
+    scope?: string;
+    /**
+     * Additional custom parameters for Auth0 Action processing
+     *
+     * @remarks
+     * Accessible in Action code via `event.request.body`
+     *
+     * @example
+     * ```typescript
+     * {
+     *   custom_parameter: "session_context",
+     *   device_fingerprint: "a3d8f7...",
+     * }
+     * ```
+     */
+    [key: string]: unknown;
+};

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

@@ -1,7 +1,7 @@
 import { IdToken, User } from '../global';
 export declare const CACHE_KEY_PREFIX = "@@auth0spajs@@";
 export declare const CACHE_KEY_ID_TOKEN_SUFFIX = "@@user@@";
-export declare type CacheKeyData = {
+export type CacheKeyData = {
     audience?: string;
     scope?: string;
     clientId: string;
@@ -39,7 +39,7 @@ export interface IdTokenEntry {
     id_token: string;
     decodedToken: DecodedToken;
 }
-export declare type CacheEntry = {
+export type CacheEntry = {
     id_token?: string;
     access_token: string;
     expires_in: number;
@@ -50,15 +50,15 @@ export declare type CacheEntry = {
     refresh_token?: string;
     oauthTokenScope?: string;
 };
-export declare type WrappedCacheEntry = {
+export type WrappedCacheEntry = {
     body: Partial<CacheEntry>;
     expiresAt: number;
 };
-export declare type KeyManifestEntry = {
+export type KeyManifestEntry = {
     keys: string[];
 };
-export declare type Cacheable = WrappedCacheEntry | KeyManifestEntry;
-export declare type MaybePromise<T> = Promise<T> | T;
+export type Cacheable = WrappedCacheEntry | KeyManifestEntry;
+export type MaybePromise<T> = Promise<T> | T;
 export interface ICache {
     set<T = Cacheable>(key: string, entry: T): MaybePromise<void>;
     get<T = Cacheable>(key: string): MaybePromise<T | undefined>;

package/dist/typings/global.d.ts

@@ -231,11 +231,20 @@ export interface Auth0ClientOptions extends BaseLoginOptions {
      * **Note**: Using this improperly can potentially compromise the token validation.
      */
     nowProvider?: () => Promise<number> | number;
+    /**
+     * If provided, the SDK will load the token worker from this URL instead of the integrated `blob`. An example of when this is useful is if you have strict
+     * Content-Security-Policy (CSP) and wish to avoid needing to set `worker-src: blob:`. We recommend either serving the worker, which you can find in the module
+     * at `<module_path>/dist/auth0-spa-js.worker.production.js`, from the same host as your application or using the Auth0 CDN
+     * `https://cdn.auth0.com/js/auth0-spa-js/<version>/auth0-spa-js.worker.production.js`.
+     *
+     * **Note**: The worker is only used when `useRefreshTokens: true`, `cacheLocation: 'memory'`, and the `cache` is not custom.
+     */
+    workerUrl?: string;
 }
 /**
  * The possible locations where tokens can be stored
  */
-export declare type CacheLocation = 'memory' | 'localstorage';
+export type CacheLocation = 'memory' | 'localstorage';
 /**
  * @ignore
  */
@@ -466,7 +475,7 @@ export interface TokenEndpointOptions {
     useFormData?: boolean;
     [key: string]: any;
 }
-export declare type TokenEndpointResponse = {
+export type TokenEndpointResponse = {
     id_token: string;
     access_token: string;
     refresh_token?: string;
@@ -569,12 +578,12 @@ export declare class User {
 /**
  * @ignore
  */
-export declare type FetchOptions = {
+export type FetchOptions = {
     method?: string;
     headers?: Record<string, string>;
     credentials?: 'include' | 'omit';
     body?: string;
     signal?: AbortSignal;
 };
-export declare type GetTokenSilentlyVerboseResponse = Omit<TokenEndpointResponse, 'refresh_token'>;
+export type GetTokenSilentlyVerboseResponse = Omit<TokenEndpointResponse, 'refresh_token'>;
 export {};

package/dist/typings/scope.d.ts

@@ -1,4 +1,10 @@
 /**
  * @ignore
  */
+/**
+ * Returns a string of unique scopes by removing duplicates and unnecessary whitespace.
+ *
+ * @param {...(string | undefined)[]} scopes - A list of scope strings or undefined values.
+ * @returns {string} A string containing unique scopes separated by a single space.
+ */
 export declare const getUniqueScopes: (...scopes: (string | undefined)[]) => string;

package/dist/typings/storage.d.ts

@@ -5,7 +5,7 @@ interface ClientStorageOptions {
 /**
  * Defines a type that handles storage to/from a storage location
  */
-export declare type ClientStorage = {
+export type ClientStorage = {
     get<T extends Object>(key: string): T | undefined;
     save(key: string, value: any, options?: ClientStorageOptions): void;
     remove(key: string, options?: ClientStorageOptions): void;

package/dist/typings/version.d.ts

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

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

@@ -2,7 +2,7 @@ import { FetchOptions } from '../global';
 /**
  * @ts-ignore
  */
-export declare type WorkerRefreshTokenMessage = {
+export type WorkerRefreshTokenMessage = {
     timeout: number;
     fetchUrl: string;
     fetchOptions: FetchOptions;

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.1.2",
+  "version": "2.2.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",
@@ -33,19 +33,16 @@
   },
   "devDependencies": {
     "@auth0/component-cdn-uploader": "github:auth0/component-cdn-uploader#v2.2.2",
-    "@babel/core": "^7.18.13",
-    "@babel/preset-env": "^7.18.10",
     "@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",
-    "babel-jest": "^28.1.3",
     "browser-tabs-lock": "^1.2.15",
-    "browserstack-cypress-cli": "1.8.1",
+    "browserstack-cypress-cli": "1.28.0",
     "cli-table": "^0.3.6",
     "concurrently": "^7.3.0",
-    "cypress": "7.2.0",
+    "cypress": "13.6.1",
     "es-check": "^7.0.1",
     "es-cookie": "~1.3.2",
     "eslint": "^8.22.0",
@@ -59,11 +56,9 @@
     "jest-junit": "^14.0.0",
     "jest-localstorage-mock": "^2.4.22",
     "jsonwebtoken": "^9.0.0",
-    "node-fetch": "^3.2.10",
     "oidc-provider": "^7.14.0",
     "prettier": "^2.7.1",
     "pretty-quick": "^3.1.2",
-    "qss": "^2.0.3",
     "rimraf": "^3.0.2",
     "rollup": "^2.78.0",
     "rollup-plugin-analyzer": "^4.0.0",
@@ -73,15 +68,15 @@
     "rollup-plugin-node-resolve": "^5.2.0",
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-terser": "^7.0.2",
-    "rollup-plugin-typescript2": "^0.32.1",
+    "rollup-plugin-typescript2": "^0.36.0",
     "rollup-plugin-visualizer": "^5.7.1",
     "rollup-plugin-web-worker-loader": "^1.6.1",
     "serve": "^14.0.1",
     "ts-jest": "^28.0.8",
     "tslib": "^2.4.0",
-    "typedoc": "^0.23.10",
+    "typedoc": "^0.25.1",
     "typescript": "^4.7.4",
-    "wait-on": "^6.0.0"
+    "wait-on": "^7.2.0"
   },
   "files": [
     "src",

package/src/Auth0Client.ts

@@ -92,6 +92,7 @@ import {
   OLD_IS_AUTHENTICATED_COOKIE_NAME,
   patchOpenUrlWithOnRedirect
 } from './Auth0Client.utils';
+import { CustomTokenExchangeOptions } from './TokenExchange';
 
 /**
  * @ignore
@@ -231,7 +232,11 @@ export class Auth0Client {
       this.options.useRefreshTokens &&
       cacheLocation === CACHE_LOCATION_MEMORY
     ) {
-      this.worker = new TokenWorker();
+      if (this.options.workerUrl) {
+        this.worker = new Worker(this.options.workerUrl);
+      } else {
+        this.worker = new TokenWorker();
+      }
     }
   }
 
@@ -1093,7 +1098,10 @@ export class Auth0Client {
   };
 
   private async _requestToken(
-    options: PKCERequestTokenOptions | RefreshTokenRequestTokenOptions,
+    options:
+      | PKCERequestTokenOptions
+      | RefreshTokenRequestTokenOptions
+      | TokenExchangeRequestOptions,
     additionalParameters?: RequestTokenAdditionalParameters
   ) {
     const { nonceIn, organization } = additionalParameters || {};
@@ -1133,6 +1141,68 @@ export class Auth0Client {
 
     return { ...authResult, decodedToken };
   }
+
+  /*
+  Custom Token Exchange
+  * **Implementation Notes:**
+  * - Ensure that the `subject_token` provided has been securely obtained and is valid according
+  *   to your external identity provider's policies before invoking this function.
+  * - The function leverages internal helper methods:
+  *   - `validateTokenType` confirms that the `subject_token_type` is supported.
+  *   - `getUniqueScopes` merges and de-duplicates scopes between the provided options and
+  *     the instance's default scopes.
+  *   - `_requestToken` performs the actual HTTP request to the token endpoint.
+  */
+
+  /**
+   * Exchanges an external subject token for an Auth0 token via a token exchange request.
+   *
+   * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
+   *
+   * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response,
+   * which contains the issued Auth0 tokens.
+   *
+   * This method implements the token exchange grant as specified in RFC 8693 by first validating
+   * the provided subject token type and then constructing a token request to the /oauth/token endpoint.
+   * The request includes the following parameters:
+   *
+   * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange".
+   * - `subject_token`: The external token provided via the options.
+   * - `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.
+   *
+   * **Example Usage:**
+   *
+   * ```
+   * // Define the token exchange options
+   * const options: CustomTokenExchangeOptions = {
+   *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
+   *   subject_token_type: 'urn:acme:legacy-system-token',
+   *   scope: ['openid', 'profile']
+   * };
+   *
+   * // Exchange the external token for Auth0 tokens
+   * try {
+   *   const tokenResponse = await instance.exchangeToken(options);
+   *   console.log('Token response:', tokenResponse);
+   * } catch (error) {
+   *   console.error('Token exchange failed:', error);
+   * }
+   * ```
+   */
+  async exchangeToken(
+    options: CustomTokenExchangeOptions
+  ): Promise<TokenEndpointResponse> {
+    return this._requestToken({
+      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+      subject_token: options.subject_token,
+      subject_token_type: options.subject_token_type,
+      scope: getUniqueScopes(options.scope, this.scope),
+      audience: this.options.authorizationParams.audience
+    });
+  }
 }
 
 interface BaseRequestTokenOptions {
@@ -1153,6 +1223,14 @@ interface RefreshTokenRequestTokenOptions extends BaseRequestTokenOptions {
   refresh_token?: string;
 }
 
+interface TokenExchangeRequestOptions extends BaseRequestTokenOptions {
+  grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange';
+  subject_token: string;
+  subject_token_type: string;
+  actor_token?: string;
+  actor_token_type?: string;
+}
+
 interface RequestTokenAdditionalParameters {
   nonceIn?: string;
   organization?: string;

package/src/TokenExchange.ts

@@ -0,0 +1,74 @@
+/**
+ * Represents the configuration options required for initiating a Custom Token Exchange request
+ * following RFC 8693 specifications.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 | RFC 8693: OAuth 2.0 Token Exchange}
+ */
+export type CustomTokenExchangeOptions = {
+  /**
+   * The type identifier for the subject token being exchanged
+   *
+   * @pattern
+   * - Must be a namespaced URI under your organization's control
+   * - Forbidden patterns:
+   *   - `^urn:ietf:params:oauth:*` (IETF reserved)
+   *   - `^https:\/\/auth0\.com/*` (Auth0 reserved)
+   *   - `^urn:auth0:*` (Auth0 reserved)
+   *
+   * @example
+   * "urn:acme:legacy-system-token"
+   * "https://api.yourcompany.com/token-type/v1"
+   */
+  subject_token_type: string;
+
+  /**
+   * The opaque token value being exchanged for Auth0 tokens
+   *
+   * @security
+   * - Must be validated in Auth0 Actions using strong cryptographic verification
+   * - Implement replay attack protection
+   * - Recommended validation libraries: `jose`, `jsonwebtoken`
+   *
+   * @example
+   * "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+   */
+  subject_token: string;
+
+  /**
+   * The target audience for the requested Auth0 token
+   *
+   * @remarks
+   * Must match exactly with an API identifier configured in your Auth0 tenant
+   *
+   * @example
+   * "https://api.your-service.com/v1"
+   */
+  audience: string;
+
+  /**
+   * Space-separated list of OAuth 2.0 scopes being requested
+   *
+   * @remarks
+   * Subject to API authorization policies configured in Auth0
+   *
+   * @example
+   * "openid profile email read:data write:data"
+   */
+  scope?: string;
+
+  /**
+   * Additional custom parameters for Auth0 Action processing
+   *
+   * @remarks
+   * Accessible in Action code via `event.request.body`
+   *
+   * @example
+   * ```typescript
+   * {
+   *   custom_parameter: "session_context",
+   *   device_fingerprint: "a3d8f7...",
+   * }
+   * ```
+   */
+  [key: string]: unknown;
+};

package/src/global.ts

@@ -259,6 +259,16 @@ export interface Auth0ClientOptions extends BaseLoginOptions {
    * **Note**: Using this improperly can potentially compromise the token validation.
    */
   nowProvider?: () => Promise<number> | number;
+
+  /**
+   * If provided, the SDK will load the token worker from this URL instead of the integrated `blob`. An example of when this is useful is if you have strict
+   * Content-Security-Policy (CSP) and wish to avoid needing to set `worker-src: blob:`. We recommend either serving the worker, which you can find in the module 
+   * at `<module_path>/dist/auth0-spa-js.worker.production.js`, from the same host as your application or using the Auth0 CDN 
+   * `https://cdn.auth0.com/js/auth0-spa-js/<version>/auth0-spa-js.worker.production.js`.
+   * 
+   * **Note**: The worker is only used when `useRefreshTokens: true`, `cacheLocation: 'memory'`, and the `cache` is not custom.
+   */
+  workerUrl?: string;
 }
 
 /**

package/src/scope.ts

@@ -6,6 +6,12 @@ const dedupe = (arr: string[]) => Array.from(new Set(arr));
 /**
  * @ignore
  */
+/**
+ * Returns a string of unique scopes by removing duplicates and unnecessary whitespace.
+ *
+ * @param {...(string | undefined)[]} scopes - A list of scope strings or undefined values.
+ * @returns {string} A string containing unique scopes separated by a single space.
+ */
 export const getUniqueScopes = (...scopes: (string | undefined)[]) => {
   return dedupe(scopes.filter(Boolean).join(' ').trim().split(/\s+/)).join(' ');
 };

package/src/utils.ts

@@ -210,7 +210,7 @@ export const validateCrypto = () => {
   }
   if (typeof getCrypto().subtle === 'undefined') {
     throw new Error(`
-      auth0-spa-js must run on a secure origin. See https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md#why-do-i-get-auth0-spa-js-must-run-on-a-secure-origin for more information.
+      auth0-spa-js must run on a secure origin. See https://github.com/auth0/auth0-spa-js/blob/main/FAQ.md#why-do-i-get-auth0-spa-js-must-run-on-a-secure-origin for more information.
     `);
   }
 };

package/src/version.ts

@@ -1 +1 @@
-export default '2.1.2';
+export default '2.2.0';