@webex/plugin-authorization-browser-first-party 3.8.1 → 3.9.0-multiple-llm.1

package/dist/authorization.js

@@ -25,11 +25,16 @@ var _lodash = require("lodash");
 var _uuid = _interopRequireDefault(require("uuid"));
 var _encBase64url = _interopRequireDefault(require("crypto-js/enc-base64url"));
 var _cryptoJs = _interopRequireDefault(require("crypto-js"));
-var _dec, _dec2, _obj;
+var _dec, _dec2, _obj; // @ts-nocheck
+/* eslint-disable */
 /*!
  * Copyright (c) 2015-2020 Cisco Systems, Inc. See LICENSE file.
  */
 /* eslint camelcase: [0] */
+/**
+ * TS checking disabled: file uses legacy decorator syntax inside an object literal
+ * transformed by Babel. Safe to ignore for now.
+ */
 // Necessary to require lodash this way in order to stub
 // methods in the unit test
 var lodash = require('lodash');
@@ -47,11 +52,29 @@ var Events = exports.Events = {
 };
 
 /**
- * Browser support for OAuth2. Automatically parses the URL query for an
- * authorization code
+ * Browser support for OAuth2 for first-party (Webex Web Client) usage.
+ *
+ * High-level flow handled by this module:
+ * 1. initiateLogin() constructs authorization request (adds CSRF + PKCE).
+ * 2. Browser navigates to IdBroker (login).
+ * 3. IdBroker redirects back with ?code=... (&state=...).
+ * 4. initialize() detects code, validates state/CSRF, cleans URL, optionally
+ *    pre-fetches a preauth catalog, then exchanges the code via
+ *    requestAuthorizationCodeGrant().
+ * 5. Sets resulting supertoken (access/refresh token bundle) on credentials.
+ *
+ * Additional supported flow:
+ * - Device Authorization (QR Code login):
+ *   initQRCodeLogin() obtains device + user codes and begins polling
+ *   _startQRCodePolling() until tokens are issued or timeout/cancel occurs.
+ *
+ * Security considerations implemented:
+ * - CSRF token (state.csrf_token) generation + verification.
+ * - PKCE (S256) code verifier + challenge generation and consumption.
+ * - URL cleanup after redirect (removes code & CSRF to prevent leakage).
+ *
+ * Use of this plugin for anything other than the Webex Web Client is discouraged.
  *
- * Use of this plugin for anything other than the Webex Web Client is strongly
- * discouraged and may be broken at any time
  * @class
  * @name AuthorizationBrowserFirstParty
  * @private
@@ -82,6 +105,10 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       default: false,
       type: 'boolean'
     },
+    /**
+     * Indicates that the plugin has finished any automatic startup
+     * processing (e.g., exchanging a returned authorization code)
+     */
     ready: {
       default: false,
       type: 'boolean'
@@ -89,7 +116,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
   },
   namespace: 'Credentials',
   /**
-   * EventEmitter for authorization events
+   * EventEmitter for authorization events such as QR code login progress
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @type {EventEmitter}
@@ -97,7 +124,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    */
   eventEmitter: new _events.EventEmitter(),
   /**
-   * Stores the timer ID for QR code polling
+   * Stores the timer ID for QR code polling (device authorization)
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @type {?number}
@@ -105,7 +132,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    */
   pollingTimer: null,
   /**
-   * Stores the expiration timer ID for QR code polling
+   * Stores the expiration timer ID for QR code polling (overall timeout)
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @type {?number}
@@ -113,7 +140,8 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    */
   pollingExpirationTimer: null,
   /**
-   * Monotonically increasing id to identify the current polling request
+   * Monotonically increasing id to identify the current polling request.
+   * Used to safely ignore late poll responses after a cancel/reset.
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @type {number}
@@ -121,7 +149,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    */
   pollingId: 0,
   /**
-   * Identifier for the current polling request
+   * Identifier for the current polling request (snapshot of pollingId)
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @type {?number}
@@ -129,11 +157,34 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    */
   currentPollingId: null,
   /**
-   * Initializer
-   * @instance
-   * @memberof AuthorizationBrowserFirstParty
-   * @private
-   * @returns {Authorization}
+   * Auto executes during Webex.init() – you do NOT call this yourself.
+   *
+   * Purpose: Seamless "redirect completion" of the OAuth Authorization Code (+ PKCE) flow.
+   *
+   * Simple summary:
+   * - You call initiateLogin() which redirects user to IdBroker.
+   * - User signs in; IdBroker redirects back to your redirect_uri with ?code=... (&state=...).
+   * - During SDK startup this initialize() runs automatically, sees the code, and
+   *   silently finishes the login (validates state/CSRF + PKCE, scrubs URL, exchanges code).
+   * - When done, webex.credentials.supertoken holds access+refresh and ready=true.
+   *
+   * Step-by-step:
+   * 1. Inspect current window.location for ?code= (& state=).
+   * 2. If no code: set ready=true immediately (nothing to complete).
+   * 3. If code present:
+   *    - Decode base64 state JSON.
+   *    - Verify CSRF token matches sessionStorage value.
+   *    - Retrieve then delete PKCE code_verifier (single use).
+   *    - Optionally derive preauth hint (emailhash in state OR orgId parsed from code).
+   *    - Clean the URL (history.replaceState) to remove code & csrf token data.
+   *    - nextTick:
+   *        a. Best‑effort preauth catalog fetch (non-blocking).
+   *        b. Exchange authorization code (with code_verifier if any) for supertoken
+   *           and store on webex.credentials.
+   * 4. Set ready=true after the async sequence finishes (or immediately if step 2).
+   *
+   * Result: If the redirect included a valid code the token exchange is completed
+   * automatically—no extra API call needed after Webex.init().
    */
   // eslint-disable-next-line complexity
   initialize: function initialize() {
@@ -143,23 +194,37 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     }
     var ret = (0, _apply.default)(_webexCore.WebexPlugin.prototype.initialize, this, attrs);
     var location = _url.default.parse(this.webex.getWindow().location.href, true);
+
+    // Check if redirect includes error
     this._checkForErrors(location);
     var code = location.query.code;
+
+    // If no authorization code returned, nothing to do
     if (!code) {
       this.ready = true;
       return ret;
     }
+
+    // Decode and parse state object (if present)
     if (location.query.state) {
       location.query.state = JSON.parse(_common.base64.decode(location.query.state));
     } else {
       location.query.state = {};
     }
+
+    // Retrieve PKCE code verifier (if a PKCE flow was initiated)
     var codeVerifier = this.webex.getWindow().sessionStorage.getItem(OAUTH2_CODE_VERIFIER);
+    // Immediately remove code verifier to minimize exposure
     this.webex.getWindow().sessionStorage.removeItem(OAUTH2_CODE_VERIFIER);
     var emailhash = location.query.state.emailhash;
+
+    // Validate CSRF token included in state
     this._verifySecurityToken(location.query);
+    // Remove code + CSRF token remnants from URL (history replace)
     this._cleanUrl(location);
     var preauthCatalogParams;
+
+    // Attempt to extract orgId from structured authorization code (if present)
     var orgId = this._extractOrgIdFromCode(code);
     if (emailhash) {
       preauthCatalogParams = {
@@ -171,11 +236,12 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       };
     }
 
-    // Wait until nextTick in case `credentials` hasn't initialized yet
+    // Defer token exchange until next tick in case credentials plugin not ready yet
     process.nextTick(function () {
       _this.webex.internal.services.collectPreauthCatalog(preauthCatalogParams).catch(function () {
         return _promise.default.resolve();
-      }).then(function () {
+      }) // Non-fatal if catalog collection fails
+      .then(function () {
         return _this.requestAuthorizationCodeGrant({
           code: code,
           codeVerifier: codeVerifier
@@ -183,13 +249,24 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       }).catch(function (error) {
         _this.logger.warn('authorization: failed initial authorization code grant request', error);
       }).then(function () {
+        // Mark plugin ready regardless of success/failure of token exchange
         _this.ready = true;
       });
     });
     return ret;
   },
   /**
-   * Kicks off an oauth flow
+   * Kicks off an OAuth authorization code flow (first party).
+   *
+   * Adds security + PKCE properties:
+   * - SHA256(email) (emailHash & emailhash) for preauth and redirect flows
+   * - state.csrf_token for CSRF protection
+   * - PKCE code_challenge (S256)
+   *
+   * NOTE: This does not itself perform the redirect; it calls
+   * initiateAuthorizationCodeGrant() which changes window location or opens
+   * a separate window as configured.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @param {Object} options
@@ -198,25 +275,38 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
   initiateLogin: function initiateLogin() {
     var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
     options = (0, _lodash.cloneDeep)(options);
+
+    // Optionally compute heuristic email hash for preauth usage
     if (options.email) {
       options.emailHash = _cryptoJs.default.SHA256(options.email).toString();
     }
-    delete options.email;
+    delete options.email; // Ensure raw email not propagated further
+
     options.state = options.state || {};
+    // Embed CSRF token
     options.state.csrf_token = this._generateSecurityToken();
-    // catalog uses emailhash and redirectCI uses emailHash
+    // Provide email hash in lower-case key used by catalog service
+    // (Note: catalog uses emailhash and redirectCI uses emailHash)
     options.state.emailhash = options.emailHash;
+
+    // PKCE - produce code_challenge (S256) and persist code_verifier
     options.code_challenge = this._generateCodeChallenge();
     options.code_challenge_method = 'S256';
     return this.initiateAuthorizationCodeGrant(options);
   },
   /**
-   * Kicks off the Implicit Code grant flow. Typically called via
-   * {@link AuthorizationBrowserFirstParty#initiateLogin}
+   * Performs the navigation step of the Authorization Code flow.
+   * Builds login URL and either:
+   *  - Replaces current window location (default), or
+   *  - Opens a separate window (popup) if options.separateWindow supplied.
+   *
+   * Decorated with whileInFlight('isAuthorizing') to set isAuthorizing=true
+   * during execution to prevent concurrent overlapping attempts.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
-   * @param {Object} options
-   * @returns {Promise}
+   * @param {Object} options - Already augmented with state + PKCE info
+   * @returns {Promise<void>}
    */
   initiateAuthorizationCodeGrant: function initiateAuthorizationCodeGrant(options) {
     this.logger.info('authorization: initiating authorization code grant flow');
@@ -224,15 +314,12 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       response_type: 'code'
     }, options));
     if (options !== null && options !== void 0 && options.separateWindow) {
-      // Default window settings
+      // If a separate popup window is requested, combine user supplied window features
       var defaultWindowSettings = {
         width: 600,
         height: 800
       };
-
-      // Merge user provided settings with defaults
       var windowSettings = (0, _assign.default)(defaultWindowSettings, (0, _typeof2.default)(options.separateWindow) === 'object' ? options.separateWindow : {});
-      // Convert settings object to window.open features string
       var windowFeatures = (0, _entries.default)(windowSettings).map(function (_ref) {
         var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
           key = _ref2[0],
@@ -241,18 +328,21 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       }).join(',');
       this.webex.getWindow().open(loginUrl, '_blank', windowFeatures);
     } else {
-      // Default behavior - open in same window
+      // Normal (in-tab) redirect
       this.webex.getWindow().location = loginUrl;
     }
     return _promise.default.resolve();
   },
   /**
-   * Called by {@link WebexCore#logout()}. Redirects to the logout page
+   * Called by {@link WebexCore#logout()}.
+   * Constructs logout URL and (unless suppressed) navigates away to ensure
+   * server-side session termination.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @param {Object} options
    * @param {boolean} options.noRedirect if true, does not redirect
-   * @returns {Promise}
+   * @returns {Promise<void>}
    */
   logout: function logout() {
     var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -261,11 +351,23 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     }
   },
   /**
-   * Exchanges an authorization code for an access token
+   * Exchanges an authorization code for an access (super) token bundle.
+   *
+   * Decorators:
+   * - @whileInFlight('isAuthorizing'): prevents overlapping exchanges.
+   * - @oneFlight: collapses simultaneous calls into one network request.
+   *
+   * Includes PKCE code_verifier if present from earlier login initiation.
+   *
+   * Error Handling:
+   * - Non-400 responses are propagated.
+   * - 400 responses map to OAuth-specific grantErrors.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @param {Object} options
-   * @param {Object} options.code
+   * @param {string} options.code - Authorization code from redirect
+   * @param {string} [options.codeVerifier] - PKCE code verifier if used
    * @returns {Promise}
    */
   requestAuthorizationCodeGrant: function requestAuthorizationCodeGrant() {
@@ -279,8 +381,9 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       grant_type: 'authorization_code',
       redirect_uri: this.config.redirect_uri,
       code: options.code,
-      self_contained_token: true
+      self_contained_token: true // Request combined access/refresh response
     };
+
     if (options.codeVerifier) {
       form.code_verifier = options.codeVerifier;
     }
@@ -293,8 +396,9 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
         pass: this.config.client_secret,
         sendImmediately: true
       },
-      shouldRefreshAccessToken: false
+      shouldRefreshAccessToken: false // This is the token acquisition call itself
     }).then(function (res) {
+      // Store supertoken into credentials (includes refresh token)
       _this2.webex.credentials.set({
         supertoken: res.body
       });
@@ -302,16 +406,22 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       if (res.statusCode !== 400) {
         return _promise.default.reject(res);
       }
+
+      // Map standard OAuth error to strongly typed error class
       var ErrorConstructor = _webexCore.grantErrors.select(res.body.error);
       return _promise.default.reject(new ErrorConstructor(res._res || res));
     });
   },
   /**
-   * Generate a QR code URL to launch the Webex app when scanning with the camera
+   * Generate a QR code verification URL for device authorization flow.
+   * When a user scans the QR code with a mobile device, this deep-links into
+   * Webex (web) to continue login, including passing along userCode and the
+   * helper service base URL.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
-   * @param {String} verificationUrl
-   * @returns {String}
+   * @param {String} verificationUrl - Original verification URI (complete)
+   * @returns {String} Possibly rewritten verification URL
    */
   _generateQRCodeVerificationUrl: function _generateQRCodeVerificationUrl(verificationUrl) {
     var baseUrl = 'https://web.webex.com/deviceAuth';
@@ -329,7 +439,15 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     }
   },
   /**
-   * Get an OAuth Login URL for QRCode. Generate QR code based on the returned URL.
+   * Initiates Device Authorization (QR Code) flow.
+   *
+   * Steps:
+   * 1. Obtain device_code, user_code, verification URLs from oauth-helper.
+   * 2. Emit getUserCodeSuccess (provides data for generating QR code).
+   * 3. Start polling token endpoint with device_code.
+   *
+   * Emits qRCodeLogin events for UI to react (success, failure, pending, etc.).
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @emits #qRCodeLogin
@@ -337,6 +455,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
   initQRCodeLogin: function initQRCodeLogin() {
     var _this3 = this;
     if (this.pollingTimer) {
+      // Prevent concurrent device authorization attempts
       this.eventEmitter.emit(Events.qRCodeLogin, {
         eventType: 'getUserCodeFailure',
         data: {
@@ -372,7 +491,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
           verificationUriComplete: verificationUriComplete
         }
       });
-      // if device authorization success, then start to poll server to check whether the user has completed authorization
+      // Begin polling for authorization completion
       _this3._startQRCodePolling(res.body);
     }).catch(function (res) {
       _this3.eventEmitter.emit(Events.qRCodeLogin, {
@@ -382,10 +501,21 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     });
   },
   /**
-   * Polling the server to check whether the user has completed authorization
+   * Poll the device token endpoint until user authorizes, an error occurs,
+   * or timeout happens.
+   *
+   * Polling behavior:
+   * - Interval provided by server (default 2s). 'slow_down' doubles interval once.
+   * - 428 status => pending (continue).
+   * - Success => set credentials + emit authorizationSuccess + stop polling.
+   * - Any other error => emit authorizationFailure + stop polling.
+   *
+   * Cancellation:
+   * - cancelQRCodePolling() resets timers and polling ids so late responses are ignored.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
-   * @param {Object} options
+   * @param {Object} options - Must include device_code, may include interval/expires_in
    * @emits #qRCodeLogin
    */
   _startQRCodePolling: function _startQRCodePolling() {
@@ -402,6 +532,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       return;
     }
     if (this.pollingTimer) {
+      // Already polling; avoid starting a duplicate cycle
       this.eventEmitter.emit(Events.qRCodeLogin, {
         eventType: 'authorizationFailure',
         data: {
@@ -413,7 +544,10 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     var deviceCode = options.device_code,
       _options$expires_in = options.expires_in,
       expiresIn = _options$expires_in === void 0 ? 300 : _options$expires_in;
+    // Server recommended polling interval (seconds)
     var interval = (_options$interval = options.interval) !== null && _options$interval !== void 0 ? _options$interval : 2;
+
+    // Global timeout for entire device authorization attempt
     this.pollingExpirationTimer = setTimeout(function () {
       _this4.cancelQRCodePolling(false);
       _this4.eventEmitter.emit(Events.qRCodeLogin, {
@@ -424,6 +558,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       });
     }, expiresIn * 1000);
     var polling = function polling() {
+      // Increment id so any previous poll loops can be invalidated
       _this4.pollingId += 1;
       _this4.currentPollingId = _this4.pollingId;
       _this4.webex.request({
@@ -441,7 +576,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
           sendImmediately: true
         }
       }).then(function (res) {
-        // if the pollingId has changed, it means that the polling request has been canceled
+        // If polling canceled (id changed), ignore this response
         if (_this4.currentPollingId !== _this4.pollingId) return;
         _this4.eventEmitter.emit(Events.qRCodeLogin, {
           eventType: 'authorizationSuccess',
@@ -452,18 +587,15 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
         });
         _this4.cancelQRCodePolling();
       }).catch(function (res) {
-        // if the pollingId has changed, it means that the polling request has been canceled
         if (_this4.currentPollingId !== _this4.pollingId) return;
 
-        // When server sends 400 status code with message 'slow_down', it means that last request happened too soon.
-        // So, skip one interval and then poll again.
+        // Backoff signal from server; increase interval just once for next cycle
         if (res.statusCode === 400 && res.body.message === 'slow_down') {
           schedulePolling(interval * 2);
           return;
         }
 
-        // if the statusCode is 428 which means that the authorization request is still pending
-        // as the end user hasn't yet completed the user-interaction steps. So keep polling.
+        // Pending: keep polling
         if (res.statusCode === 428) {
           _this4.eventEmitter.emit(Events.qRCodeLogin, {
             eventType: 'authorizationPending',
@@ -472,6 +604,8 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
           schedulePolling(interval);
           return;
         }
+
+        // Terminal error
         _this4.cancelQRCodePolling();
         _this4.eventEmitter.emit(Events.qRCodeLogin, {
           eventType: 'authorizationFailure',
@@ -479,13 +613,17 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
         });
       });
     };
+
+    // Schedules next poll invocation
     var schedulePolling = function schedulePolling(interval) {
       return _this4.pollingTimer = setTimeout(polling, interval * 1000);
     };
     schedulePolling(interval);
   },
   /**
-   * cancel polling request
+   * Cancel active device authorization polling loop.
+   *
+   * @param {boolean} withCancelEvent emit a pollingCanceled event (default true)
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @returns {void}
@@ -504,25 +642,31 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     this.pollingTimer = null;
   },
   /**
-   * Extracts the orgId from the returned code from idbroker
-   * Description of how to parse the code can be found here:
-   * https://wiki.cisco.com/display/IDENTITY/Federated+Token+Validation
+   * Extracts the orgId from the returned code from idbroker.
+   *
+   * Certain authorization codes encode organization info in a structured
+   * underscore-delimited format. This method parses out the 3rd segment.
+   *
+   * For undocumented formats or unexpected code shapes, returns undefined.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @param {String} code
    * @private
-   * @returns {String}
+   * @returns {String|undefined}
    */
   _extractOrgIdFromCode: function _extractOrgIdFromCode(code) {
     return (code === null || code === void 0 ? void 0 : code.split('_')[2]) || undefined;
   },
   /**
-   * Checks if the result of the login redirect contains an error string
+   * Checks if the result of the login redirect contains an OAuth error.
+   * Throws a mapped grant error if encountered.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @param {Object} location
    * @private
-   * @returns {Promise}
+   * @returns {void}
    */
   _checkForErrors: function _checkForErrors(location) {
     var query = location.query;
@@ -532,12 +676,23 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     }
   },
   /**
-   * Removes no-longer needed values from the url (access token, csrf token, etc)
+   * Removes no-longer needed values from the URL (authorization code, CSRF token).
+   * This is important to avoid leaking sensitive parameters via:
+   * - Browser history
+   * - Copy/paste of URL
+   * - HTTP referrer headers to third-party content
+   *
+   * Approach:
+   * - Remove 'code'.
+   * - Remove 'state' entirely if only contained csrf_token.
+   * - Else, re-encode remaining state fields (minus csrf_token).
+   * - Replace current history entry (no page reload).
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @param {Object} location
    * @private
-   * @returns {Promise}
+   * @returns {void}
    */
   _cleanUrl: function _cleanUrl(location) {
     location = (0, _lodash.cloneDeep)(location);
@@ -554,11 +709,18 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     }
   },
   /**
-   * Generates PKCE code verifier and code challenge and sets the the code verifier in sessionStorage
+   * Generates a PKCE (RFC 7636) code verifier and corresponding S256 code challenge.
+   * Persists the verifier in sessionStorage (single-use) for later retrieval
+   * during authorization code exchange; removes it once consumed.
+   *
+   * Implementation details:
+   * - Creates a 128 character string using base64url safe alphabet.
+   * - Computes SHA256 hash, encodes to base64url (no padding).
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @private
-   * @returns {string}
+   * @returns {string} code_challenge
    */
   _generateCodeChallenge: function _generateCodeChallenge() {
     this.logger.info('authorization: generating PKCE code challenge');
@@ -573,11 +735,15 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     return codeChallenge;
   },
   /**
-   * Generates a CSRF token and sticks in in sessionStorage
+   * Generates a CSRF token and stores it in sessionStorage.
+   * Token is embedded in 'state' and validated upon redirect return.
+   *
+   * Uses UUID v4 for randomness.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @private
-   * @returns {Promise}
+   * @returns {string} token
    */
   _generateSecurityToken: function _generateSecurityToken() {
     this.logger.info('authorization: generating csrf token');
@@ -586,13 +752,21 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     return token;
   },
   /**
-   * Checks if the CSRF token in sessionStorage is the same as the one returned
-   * in the url.
+   * Verifies that the CSRF token returned in the 'state' matches the one
+   * previously stored in sessionStorage.
+   *
+   * Steps:
+   * - Retrieve and immediately remove stored token (one-time use).
+   * - Ensure state + state.csrf_token exist.
+   * - Compare values; throw descriptive errors on mismatch / absence.
+   *
+   * If no stored token (e.g., user navigated directly), silently returns.
+   *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
-   * @param {Object} query
+   * @param {Object} query - Parsed query (location.query)
    * @private
-   * @returns {Promise}
+   * @returns {void}
    */
   _verifySecurityToken: function _verifySecurityToken(query) {
     var sessionToken = this.webex.getWindow().sessionStorage.getItem(OAUTH2_CSRF_TOKEN);
@@ -611,7 +785,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       throw new Error("CSRF token ".concat(token, " does not match stored token ").concat(sessionToken));
     }
   },
-  version: "3.8.1"
+  version: "3.9.0-multiple-llm.1"
 }, ((0, _applyDecoratedDescriptor2.default)(_obj, "initiateAuthorizationCodeGrant", [_dec], (0, _getOwnPropertyDescriptor.default)(_obj, "initiateAuthorizationCodeGrant"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "requestAuthorizationCodeGrant", [_dec2, _common.oneFlight], (0, _getOwnPropertyDescriptor.default)(_obj, "requestAuthorizationCodeGrant"), _obj)), _obj)));
 var _default = exports.default = Authorization;
 //# sourceMappingURL=authorization.js.map