@auth0/auth0-spa-js 2.17.1 → 2.18.0

package/dist/typings/Auth0Client.d.ts

@@ -58,6 +58,30 @@ export declare class Auth0Client {
     private _authorizeUrl;
     private _verifyIdToken;
     private _processOrgHint;
+    /**
+     * Extracts the session transfer token from the current URL query parameters
+     * for Native to Web SSO flows.
+     *
+     * @param paramName The query parameter name to extract from the URL
+     * @returns The session transfer token if present, undefined otherwise
+     */
+    private _extractSessionTransferToken;
+    /**
+     * Clears the session transfer token from the current URL using the History API.
+     * This prevents the token from being re-sent on subsequent authentication requests,
+     * which is important since session transfer tokens are typically single-use.
+     *
+     * @param paramName The query parameter name to remove from the URL
+     */
+    private _clearSessionTransferTokenFromUrl;
+    /**
+     * Applies the session transfer token from the URL to the authorization parameters
+     * if configured and not already provided.
+     *
+     * @param authorizationParams The authorization parameters to enhance
+     * @returns The authorization parameters with session_transfer_token added if applicable
+     */
+    private _applySessionTransferToken;
     private _prepareAuthorizeUrl;
     /**
      * ```js

package/dist/typings/global.d.ts

@@ -97,6 +97,14 @@ export interface AuthorizationParams {
      * methods that provide authentication.
      */
     redirect_uri?: string;
+    /**
+     * Session transfer token from a native application for Native to Web SSO.
+     * When `sessionTransferTokenQueryParamName` is set, this is automatically
+     * extracted from the specified URL query parameter if present.
+     *
+     * @see https://auth0.com/docs/authenticate/single-sign-on/native-to-web
+     */
+    session_transfer_token?: string;
     /**
      * If you need to send custom parameters to the Authorization Server,
      * make sure to use the original parameter name.
@@ -288,6 +296,40 @@ export interface Auth0ClientOptions {
      * defined by Auth0 or custom parameters that you define.
     */
     authorizationParams?: ClientAuthorizationParams;
+    /**
+     * Query parameter name to extract the session transfer token from for Native to Web SSO.
+     *
+     * When set, the SDK automatically extracts the token from the specified URL query
+     * parameter and includes it as `session_transfer_token` in authorization requests.
+     * This enables seamless single sign-on when users transition from a native mobile
+     * application to a web application.
+     *
+     * After extraction, the token is automatically removed from the URL using
+     * `window.history.replaceState()` to prevent accidental reuse on subsequent
+     * authentication requests.
+     *
+     * **Default:** `undefined` (feature disabled)
+     *
+     * **Common values:**
+     * - `'session_transfer_token'` - Standard parameter name
+     * - `'stt'` - Shortened version
+     * - Custom parameter name of your choice
+     *
+     * Set to `undefined` to disable automatic extraction if you prefer to handle
+     * session transfer tokens manually.
+     *
+     * @example
+     * ```js
+     * const auth0 = await createAuth0Client({
+     *   domain: '<AUTH0_DOMAIN>',
+     *   clientId: '<AUTH0_CLIENT_ID>',
+     *   sessionTransferTokenQueryParamName: 'session_transfer_token'
+     * });
+     * ```
+     *
+     * @see https://auth0.com/docs/authenticate/single-sign-on/native-to-web
+     */
+    sessionTransferTokenQueryParamName?: string;
 }
 /**
  * Configuration details exposed by the Auth0Client after initialization.

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.17.1";
+declare const _default: "2.18.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": "2.17.1",
+  "version": "2.18.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",

package/src/Auth0Client.ts

@@ -378,6 +378,57 @@ export class Auth0Client {
     }
   }
 
+  /**
+   * Extracts the session transfer token from the current URL query parameters
+   * for Native to Web SSO flows.
+   *
+   * @param paramName The query parameter name to extract from the URL
+   * @returns The session transfer token if present, undefined otherwise
+   */
+  private _extractSessionTransferToken(paramName: string): string | undefined {
+    const params = new URLSearchParams(window.location.search);
+    return params.get(paramName) || undefined;
+  }
+
+  /**
+   * Clears the session transfer token from the current URL using the History API.
+   * This prevents the token from being re-sent on subsequent authentication requests,
+   * which is important since session transfer tokens are typically single-use.
+   *
+   * @param paramName The query parameter name to remove from the URL
+   */
+  private _clearSessionTransferTokenFromUrl(paramName: string): void {
+    try {
+      const url = new URL(window.location.href);
+      if (url.searchParams.has(paramName)) {
+        url.searchParams.delete(paramName);
+        window.history.replaceState({}, '', url.toString());
+      }
+    } catch {
+      // Silently fail if URL manipulation isn't possible
+    }
+  }
+
+  /**
+   * Applies the session transfer token from the URL to the authorization parameters
+   * if configured and not already provided.
+   *
+   * @param authorizationParams The authorization parameters to enhance
+   * @returns The authorization parameters with session_transfer_token added if applicable
+   */
+  private _applySessionTransferToken(
+    authorizationParams: AuthorizationParams
+  ): AuthorizationParams {
+    const paramName = this.options.sessionTransferTokenQueryParamName;
+    if (!paramName || authorizationParams.session_transfer_token) {
+      return authorizationParams;
+    }
+    const token = this._extractSessionTransferToken(paramName);
+    if (!token) return authorizationParams;
+    this._clearSessionTransferTokenFromUrl(paramName);
+    return { ...authorizationParams, session_transfer_token: token };
+  }
+
   private async _prepareAuthorizeUrl(
     authorizationParams: AuthorizationParams,
     authorizeOptions?: Partial<AuthorizeOptions>,
@@ -463,8 +514,10 @@ export class Auth0Client {
       }
     }
 
+    const authorizationParams = this._applySessionTransferToken(options.authorizationParams || {});
+
     const params = await this._prepareAuthorizeUrl(
-      options.authorizationParams || {},
+      authorizationParams,
       { response_mode: 'web_message' },
       window.location.origin
     );
@@ -553,8 +606,10 @@ export class Auth0Client {
       urlOptions.authorizationParams?.organization ||
       this.options.authorizationParams.organization;
 
+    const authorizationParams = this._applySessionTransferToken(urlOptions.authorizationParams || {});
+
     const { url, ...transaction } = await this._prepareAuthorizeUrl(
-      urlOptions.authorizationParams || {}
+      authorizationParams
     );
 
     this.transactionManager.create<LoginTransaction>({

package/src/global.ts

@@ -113,6 +113,15 @@ export interface AuthorizationParams {
    */
   redirect_uri?: string;
 
+  /**
+   * Session transfer token from a native application for Native to Web SSO.
+   * When `sessionTransferTokenQueryParamName` is set, this is automatically
+   * extracted from the specified URL query parameter if present.
+   *
+   * @see https://auth0.com/docs/authenticate/single-sign-on/native-to-web
+   */
+  session_transfer_token?: string;
+
   /**
    * If you need to send custom parameters to the Authorization Server,
    * make sure to use the original parameter name.
@@ -324,6 +333,41 @@ export interface Auth0ClientOptions {
    * defined by Auth0 or custom parameters that you define.
   */
   authorizationParams?: ClientAuthorizationParams;
+
+  /**
+   * Query parameter name to extract the session transfer token from for Native to Web SSO.
+   *
+   * When set, the SDK automatically extracts the token from the specified URL query
+   * parameter and includes it as `session_transfer_token` in authorization requests.
+   * This enables seamless single sign-on when users transition from a native mobile
+   * application to a web application.
+   *
+   * After extraction, the token is automatically removed from the URL using
+   * `window.history.replaceState()` to prevent accidental reuse on subsequent
+   * authentication requests.
+   *
+   * **Default:** `undefined` (feature disabled)
+   *
+   * **Common values:**
+   * - `'session_transfer_token'` - Standard parameter name
+   * - `'stt'` - Shortened version
+   * - Custom parameter name of your choice
+   *
+   * Set to `undefined` to disable automatic extraction if you prefer to handle
+   * session transfer tokens manually.
+   *
+   * @example
+   * ```js
+   * const auth0 = await createAuth0Client({
+   *   domain: '<AUTH0_DOMAIN>',
+   *   clientId: '<AUTH0_CLIENT_ID>',
+   *   sessionTransferTokenQueryParamName: 'session_transfer_token'
+   * });
+   * ```
+   *
+   * @see https://auth0.com/docs/authenticate/single-sign-on/native-to-web
+   */
+  sessionTransferTokenQueryParamName?: string;
 }
 
 /**

package/src/utils.ts

@@ -149,11 +149,16 @@ export const getCrypto = () => {
 export const createRandomString = () => {
   const charset =
     '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_~.';
+  const validMax = 256 - (256 % charset.length);
   let random = '';
-  const randomValues = Array.from(
-    getCrypto().getRandomValues(new Uint8Array(43))
-  );
-  randomValues.forEach(v => (random += charset[v % charset.length]));
+  while (random.length < 43) {
+    const bytes = getCrypto().getRandomValues(new Uint8Array(43 - random.length));
+    for (const byte of bytes) {
+      if (random.length < 43 && byte < validMax) {
+        random += charset[byte % charset.length];
+      }
+    }
+  }
   return random;
 };
 

package/src/version.ts

@@ -1 +1 @@
-export default '2.17.1';
+export default '2.18.0';