@auth0/auth0-spa-js 1.21.1 → 1.22.0

package/dist/typings/Auth0Client.d.ts

@@ -17,6 +17,7 @@ export default class Auth0Client {
     private readonly isAuthenticatedCookieName;
     private readonly nowProvider;
     private readonly httpTimeoutMs;
+    private readonly useRefreshTokensFallback;
     cacheLocation: CacheLocation;
     private worker;
     constructor(options: Auth0ClientOptions);

package/dist/typings/constants.d.ts

@@ -24,7 +24,7 @@ export declare const CACHE_LOCATION_LOCAL_STORAGE = "localstorage";
 /**
  * @ignore
  */
-export declare const MISSING_REFRESH_TOKEN_ERROR_MESSAGE = "The web worker is missing the refresh token";
+export declare const MISSING_REFRESH_TOKEN_ERROR_MESSAGE = "Missing Refresh Token";
 /**
  * @ignore
  */

package/dist/typings/errors.d.ts

@@ -48,3 +48,8 @@ export declare class MfaRequiredError extends GenericError {
     mfa_token: string;
     constructor(error: string, error_description: string, mfa_token: string);
 }
+export declare class MissingRefreshTokenError extends GenericError {
+    audience: string;
+    scope: string;
+    constructor(audience: string, scope: string);
+}

package/dist/typings/global.d.ts

@@ -138,6 +138,26 @@ export interface Auth0ClientOptions extends BaseLoginOptions {
      * **Note**: Use of refresh tokens must be enabled by an administrator on your Auth0 client application.
      */
     useRefreshTokens?: boolean;
+    /**
+     * If true, fallback to the technique of using a hidden iframe and the `authorization_code` grant with `prompt=none` when unable to use refresh tokens.
+     * The default setting is `true`.
+     *
+     * **Note**: There might be situations where doing silent auth with a Web Message response from an iframe is not possible,
+     * like when you're serving your application from the file system or a custom protocol (like in a Desktop or Native app).
+     * In situations like this you can disable the iframe fallback and handle the failed Refresh Grant and prompt the user to login interactively with `loginWithRedirect` or `loginWithPopup`."
+     *
+     * E.g. Using the `file:` protocol in an Electron application does not support that legacy technique.
+     *
+     *  let token: string;
+     *  try {
+     *    token = await auth0.getTokenSilently();
+     *  } catch (e) {
+     *  if (e.error === 'missing_refresh_token' || e.error === 'invalid_grant') {
+     *      auth0.loginWithRedirect();
+     *    }
+     *  }
+     */
+    useRefreshTokensFallback?: boolean;
     /**
      * A maximum number of seconds to wait before declaring background calls to /authorize as failed for timeout
      * Defaults to 60s.

package/dist/typings/utils.d.ts

@@ -13,3 +13,10 @@ export declare const sha256: (s: string) => Promise<any>;
 export declare const urlDecodeB64: (input: string) => string;
 export declare const bufferToBase64UrlEncoded: (input: number[] | Uint8Array) => string;
 export declare const validateCrypto: () => void;
+/**
+ * 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
+ * @param exclude An array of values that should result in an empty string.
+ * @returns The value, or an empty string when falsy or included in the exclude argument.
+ */
+export declare function valueOrEmptyString(value: string, exclude?: string[]): string;

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.21.1";
+declare const _default: "1.22.0";
 export default _default;

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": "1.21.1",
+  "version": "1.22.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",
@@ -81,7 +81,7 @@
   "dependencies": {
     "abortcontroller-polyfill": "^1.7.3",
     "browser-tabs-lock": "^1.2.15",
-    "core-js": "^3.22.0",
+    "core-js": "^3.22.4",
     "es-cookie": "^1.3.2",
     "fast-text-encoding": "^1.0.3",
     "promise-polyfill": "^8.2.3",

package/src/Auth0Client.ts

@@ -27,7 +27,12 @@ import {
 
 import TransactionManager from './transaction-manager';
 import { verify as verifyIdToken } from './jwt';
-import { AuthenticationError, GenericError, TimeoutError } from './errors';
+import {
+  AuthenticationError,
+  GenericError,
+  MissingRefreshTokenError,
+  TimeoutError
+} from './errors';
 
 import {
   ClientStorage,
@@ -202,6 +207,7 @@ export default class Auth0Client {
   private readonly isAuthenticatedCookieName: string;
   private readonly nowProvider: () => number | Promise<number>;
   private readonly httpTimeoutMs: number;
+  private readonly useRefreshTokensFallback: boolean;
 
   cacheLocation: CacheLocation;
   private worker: Worker;
@@ -299,6 +305,9 @@ export default class Auth0Client {
     }
 
     this.customOptions = getCustomInitialOptions(options);
+
+    this.useRefreshTokensFallback =
+      this.options.useRefreshTokensFallback !== false;
   }
 
   private _url(path: string) {
@@ -1183,7 +1192,14 @@ export default class Auth0Client {
     // and you don't have a refresh token in web worker memory
     // fallback to an iframe.
     if ((!cache || !cache.refresh_token) && !this.worker) {
-      return await this._getTokenFromIFrame(options);
+      if (this.useRefreshTokensFallback) {
+        return await this._getTokenFromIFrame(options);
+      }
+
+      throw new MissingRefreshTokenError(
+        options.audience || 'default',
+        options.scope
+      );
     }
 
     const redirect_uri =
@@ -1230,11 +1246,12 @@ export default class Auth0Client {
       if (
         // The web worker didn't have a refresh token in memory so
         // fallback to an iframe.
-        e.message === MISSING_REFRESH_TOKEN_ERROR_MESSAGE ||
-        // A refresh token was found, but is it no longer valid.
-        // Fallback to an iframe.
-        (e.message &&
-          e.message.indexOf(INVALID_REFRESH_TOKEN_ERROR_MESSAGE) > -1)
+        (e.message.indexOf(MISSING_REFRESH_TOKEN_ERROR_MESSAGE) > -1 ||
+          // A refresh token was found, but is it no longer valid.
+          // Fallback to an iframe.
+          (e.message &&
+            e.message.indexOf(INVALID_REFRESH_TOKEN_ERROR_MESSAGE) > -1)) &&
+        this.useRefreshTokensFallback
       ) {
         return await this._getTokenFromIFrame(options);
       }

package/src/constants.ts

@@ -34,8 +34,7 @@ export const CACHE_LOCATION_LOCAL_STORAGE = 'localstorage';
 /**
  * @ignore
  */
-export const MISSING_REFRESH_TOKEN_ERROR_MESSAGE =
-  'The web worker is missing the refresh token';
+export const MISSING_REFRESH_TOKEN_ERROR_MESSAGE = 'Missing Refresh Token';
 
 /**
  * @ignore

package/src/errors.ts

@@ -3,6 +3,8 @@
  * https://github.com/gotwarlost/istanbul/issues/690
  */
 
+import { valueOrEmptyString } from './utils';
+
 /**
  * Thrown when network requests to the Auth server fail.
  */
@@ -91,3 +93,16 @@ export class MfaRequiredError extends GenericError {
     Object.setPrototypeOf(this, MfaRequiredError.prototype);
   }
 }
+
+export class MissingRefreshTokenError extends GenericError {
+  /* istanbul ignore next */
+  constructor(public audience: string, public scope: string) {
+    super(
+      'missing_refresh_token',
+      `Missing Refresh Token (audience: '${valueOrEmptyString(audience, [
+        'default'
+      ])}', scope: '${valueOrEmptyString(scope)}')`
+    );
+    Object.setPrototypeOf(this, MissingRefreshTokenError.prototype);
+  }
+}

package/src/global.ts

@@ -158,6 +158,27 @@ export interface Auth0ClientOptions extends BaseLoginOptions {
    */
   useRefreshTokens?: boolean;
 
+  /**
+   * If true, fallback to the technique of using a hidden iframe and the `authorization_code` grant with `prompt=none` when unable to use refresh tokens.
+   * The default setting is `true`.
+   *
+   * **Note**: There might be situations where doing silent auth with a Web Message response from an iframe is not possible,
+   * like when you're serving your application from the file system or a custom protocol (like in a Desktop or Native app).
+   * In situations like this you can disable the iframe fallback and handle the failed Refresh Grant and prompt the user to login interactively with `loginWithRedirect` or `loginWithPopup`."
+   *
+   * E.g. Using the `file:` protocol in an Electron application does not support that legacy technique.
+   *
+   *  let token: string;
+   *  try {
+   *    token = await auth0.getTokenSilently();
+   *  } catch (e) {
+   *  if (e.error === 'missing_refresh_token' || e.error === 'invalid_grant') {
+   *      auth0.loginWithRedirect();
+   *    }
+   *  }
+   */
+  useRefreshTokensFallback?: boolean;
+
   /**
    * A maximum number of seconds to wait before declaring background calls to /authorize as failed for timeout
    * Defaults to 60s.

package/src/utils.ts

@@ -241,3 +241,13 @@ export const validateCrypto = () => {
     `);
   }
 };
+
+/**
+ * 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
+ * @param exclude An array of values that should result in an empty string.
+ * @returns The value, or an empty string when falsy or included in the exclude argument.
+ */
+export function valueOrEmptyString(value: string, exclude: string[] = []) {
+  return value && !exclude.includes(value) ? value : '';
+}

package/src/version.ts

@@ -1 +1 @@
-export default '1.21.1';
+export default '1.22.0';

package/src/worker/token.worker.ts

@@ -1,4 +1,4 @@
-import { MISSING_REFRESH_TOKEN_ERROR_MESSAGE } from '../constants';
+import { MissingRefreshTokenError } from '../errors';
 import { WorkerRefreshTokenMessage } from './worker.types';
 
 let refreshTokens: Record<string, string> = {};
@@ -50,7 +50,7 @@ const messageHandler = async ({
       const refreshToken = getRefreshToken(audience, scope);
 
       if (!refreshToken) {
-        throw new Error(MISSING_REFRESH_TOKEN_ERROR_MESSAGE);
+        throw new MissingRefreshTokenError(audience, scope);
       }
 
       fetchOptions.body = useFormData