@webex/plugin-authorization-browser-first-party 3.12.0-next.5 → 3.12.0-next.50

package/README.md

@@ -178,13 +178,44 @@ webex.authorization.initQRCodeLogin();
 
 ### Properties
 
-| Property           | Type             | Description                                               |
-| ------------------ | ---------------- | --------------------------------------------------------- |
-| `isAuthorizing`    | boolean          | True while a grant request is in flight                   |
-| `isAuthenticating` | boolean          | Alias of `isAuthorizing`                                  |
-| `ready`            | boolean          | Set true after initial redirect/code processing completes |
-| `eventEmitter`     | EventEmitter     | Emits QR/Device login lifecycle events                    |
-| `Events`           | enum-like object | Accessible names for event types                          |
+| Property                               | Type             | Description                                               |
+| -------------------------------------- | ---------------- | --------------------------------------------------------- |
+| `initialAuthorizationCodeGrantOutcome` | string           | Retained outcome of the automatic initialization exchange |
+| `isAuthorizing`                        | boolean          | True while a grant request is in flight                   |
+| `isAuthenticating`                     | boolean          | Alias of `isAuthorizing`                                  |
+| `ready`                                | boolean          | Set true after initial redirect/code processing completes |
+| `eventEmitter`                         | EventEmitter     | Emits QR/Device login lifecycle events                    |
+| `Events`                               | enum-like object | Accessible names for event types                          |
+
+#### Initial authorization-code grant outcome
+
+```javascript
+import {InitialAuthorizationCodeGrantOutcomes} from '@webex/plugin-authorization-browser-first-party';
+
+const didInitialExchangeSucceed =
+  webex.authorization.initialAuthorizationCodeGrantOutcome ===
+  InitialAuthorizationCodeGrantOutcomes.success;
+```
+
+`initialAuthorizationCodeGrantOutcome` describes only the automatic
+`requestAuthorizationCodeGrant()` call made while this authorization plugin
+instance initializes. Read it after `ready`:
+
+- `not_attempted`: initialization did not invoke the exchange.
+- `success`: the initialization exchange fulfilled.
+- `failure`: the initialization exchange threw or rejected.
+
+The value is a historical result retained for the lifetime of the SDK instance
+and is not reset by logout. It does not represent current authorization state
+or credentials hydrated from storage. It also does not track guest or device
+authentication, token refreshes, or authorization-code exchanges requested
+later on the same SDK instance.
+
+OAuth redirect errors and CSRF validation failures occur before the exchange,
+so the value remains `not_attempted`; these errors can throw before `ready`
+becomes `true`. A non-redirecting logout does not cancel an initialization
+exchange already in flight. If that exchange later settles, it can still update
+credentials and this retained outcome.
 
 ## Security Considerations
 

package/dist/authorization.js

@@ -5,19 +5,20 @@ var _interopRequireDefault = require("@babel/runtime-corejs2/helpers/interopRequ
 _Object$defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = exports.Events = void 0;
+exports.default = exports.InitialAuthorizationCodeGrantOutcomes = exports.Events = void 0;
+var _objectWithoutProperties2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/objectWithoutProperties"));
 var _apply = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/reflect/apply"));
 var _promise = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/promise"));
 var _assign = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/assign"));
 var _entries = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/entries"));
 var _deleteProperty = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/reflect/delete-property"));
-var _stringify = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/json/stringify"));
+var _from = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/array/from"));
 var _getOwnPropertyDescriptor = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/get-own-property-descriptor"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/slicedToArray"));
 var _typeof2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/typeof"));
 var _applyDecoratedDescriptor2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/applyDecoratedDescriptor"));
 var _querystring = _interopRequireDefault(require("querystring"));
-var _url = _interopRequireDefault(require("url"));
+var _url2 = _interopRequireDefault(require("url"));
 var _events = require("events");
 var _common = require("@webex/common");
 var _webexCore = require("@webex/webex-core");
@@ -25,6 +26,7 @@ var _lodash = require("lodash");
 var _uuid = _interopRequireDefault(require("uuid"));
 var _encBase64url = _interopRequireDefault(require("crypto-js/enc-base64url"));
 var _cryptoJs = _interopRequireDefault(require("crypto-js"));
+var _excluded = ["csrf_token"];
 var _dec, _dec2, _obj; // @ts-nocheck
 /* eslint-disable */
 /*!
@@ -35,9 +37,6 @@ var _dec, _dec2, _obj; // @ts-nocheck
  * 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');
 var OAUTH2_CSRF_TOKEN = 'oauth2-csrf-token';
 var OAUTH2_CODE_VERIFIER = 'oauth2-code-verifier';
 
@@ -52,6 +51,18 @@ var Events = exports.Events = {
   qRCodeLogin: 'qRCodeLogin'
 };
 
+/**
+ * Terminal outcomes for the automatic authorization-code exchange performed
+ * during authorization plugin initialization.
+ *
+ * @enum {string}
+ */
+var InitialAuthorizationCodeGrantOutcomes = exports.InitialAuthorizationCodeGrantOutcomes = {
+  failure: 'failure',
+  notAttempted: 'not_attempted',
+  success: 'success'
+};
+
 /**
  * Browser support for OAuth2 for first-party (Webex Web Client) usage.
  *
@@ -82,6 +93,37 @@ var Events = exports.Events = {
  */
 var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFlight)('isAuthorizing'), _dec2 = (0, _common.whileInFlight)('isAuthorizing'), _obj = {
   derived: {
+    /**
+     * Retains the terminal outcome of the automatic authorization-code exchange
+     * performed during this authorization plugin instance's initialization.
+     *
+     * This historical value does not represent current authorization state,
+     * credentials hydrated from storage, guest authentication, or
+     * authorization-code exchanges requested later on the same SDK instance. It
+     * is not reset by logout. OAuth redirect errors and CSRF validation failures
+     * occur before the exchange, so the value remains not_attempted; these errors
+     * can throw before ready becomes true.
+     *
+     * Calling logout({noRedirect: true}) does not cancel an initialization
+     * exchange already in flight. If that exchange later settles, it can still
+     * update credentials and this retained outcome.
+     *
+     * Interpret only after authorization readiness:
+     * - not_attempted: initialization did not invoke requestAuthorizationCodeGrant()
+     * - success: the initialization exchange fulfilled
+     * - failure: the initialization exchange threw or rejected
+     *
+     * @instance
+     * @memberof AuthorizationBrowserFirstParty
+     * @readonly
+     * @type {string}
+     */
+    initialAuthorizationCodeGrantOutcome: {
+      deps: ['_initialAuthorizationCodeGrantOutcome'],
+      fn: function fn() {
+        return this._initialAuthorizationCodeGrantOutcome;
+      }
+    },
     /**
      * Alias of {@link AuthorizationBrowserFirstParty#isAuthorizing}
      * @instance
@@ -106,6 +148,14 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       default: false,
       type: 'boolean'
     },
+    /**
+     * Internal backing state for the initial authorization-code grant outcome.
+     * @private
+     */
+    _initialAuthorizationCodeGrantOutcome: {
+      default: InitialAuthorizationCodeGrantOutcomes.notAttempted,
+      type: 'string'
+    },
     /**
      * Indicates that the plugin has finished any automatic startup
      * processing (e.g., exchanging a returned authorization code)
@@ -194,7 +244,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       attrs[_key] = arguments[_key];
     }
     var ret = (0, _apply.default)(_webexCore.WebexPlugin.prototype.initialize, this, attrs);
-    var location = _url.default.parse(this.webex.getWindow().location.href, true);
+    var location = _url2.default.parse(this.webex.getWindow().location.href, true);
 
     // Check if redirect includes error
     this._checkForErrors(location);
@@ -208,7 +258,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
 
     // Decode and parse state object (if present)
     if (location.query.state) {
-      location.query.state = JSON.parse(_common.base64.decode(location.query.state));
+      location.query.state = (0, _common.decodeState)(location.query.state);
     } else {
       location.query.state = {};
     }
@@ -247,7 +297,10 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
           code: code,
           codeVerifier: codeVerifier
         });
+      }).then(function () {
+        _this._initialAuthorizationCodeGrantOutcome = InitialAuthorizationCodeGrantOutcomes.success;
       }).catch(function (error) {
+        _this._initialAuthorizationCodeGrantOutcome = InitialAuthorizationCodeGrantOutcomes.failure;
         _this.logger.warn('authorization: failed initial authorization code grant request', error);
       }).then(function () {
         // Mark plugin ready regardless of success/failure of token exchange
@@ -347,6 +400,96 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     }
     return _promise.default.resolve();
   },
+  /**
+   * Initiates third-party (social provider) login. Generates a CSRF token,
+   * embeds it in `options.state.csrf_token`, and delegates to
+   * `initiateThirdPartyLoginRedirect` for navigation.
+   *
+   * @instance
+   * @memberof AuthorizationBrowserFirstParty
+   * @param {Object} options
+   * @param {string} options.oauth2provider
+   * @param {string} options.returnURL
+   * @param {Object} [options.state] - Caller-supplied state object. Merged
+   *   with the generated `csrf_token`.
+   * @returns {Promise<void>}
+   */
+  initiateThirdPartyLogin: function initiateThirdPartyLogin() {
+    var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    options = (0, _lodash.cloneDeep)(options);
+    if (options.state !== undefined && !(0, _lodash.isObject)(options.state)) {
+      throw new Error('if specified, `options.state` must be an object');
+    }
+    options.state = options.state || {};
+    options.state.csrf_token = this._generateSecurityToken();
+    return this.initiateThirdPartyLoginRedirect(options);
+  },
+  /**
+   * Performs the navigation step of the third-party login flow. Builds the
+   * IdBroker URL via `Credentials#buildThirdPartyLoginUrl` and assigns it
+   * to `getWindow().location`.
+   *
+   * Mirrors `initiateAuthorizationCodeGrant` for the `/authorize` flow.
+   * Consumers may override this method for custom navigation handling
+   * (e.g. postMessage in iframed contexts).
+   *
+   * @instance
+   * @memberof AuthorizationBrowserFirstParty
+   * @param {Object} options
+   * @param {string} options.oauth2provider
+   * @param {string} options.returnURL
+   * @returns {Promise<void>}
+   */
+  initiateThirdPartyLoginRedirect: function initiateThirdPartyLoginRedirect() {
+    var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    this.logger.info('authorization: initiating third-party login redirect');
+    try {
+      var _url = this.webex.credentials.buildThirdPartyLoginUrl(options);
+      this.webex.getWindow().location = _url;
+    } catch (err) {
+      return _promise.default.reject(err);
+    }
+    return _promise.default.resolve();
+  },
+  /**
+   * Handles the third-party (social provider) login callback. Reads the
+   * current `window.location`, decodes `state`, validates the CSRF token
+   * (`state.csrf_token`), scrubs sensitive parameters from the URL via
+   * `_cleanUrl`, and returns the parsed payload.
+   *
+   * Mirrors `initialize()` in always operating on the live
+   * `window.location`
+   *
+   * `idToken` is single-use: it is parsed out of the URL exactly once and
+   * the calling client is expected to exchange it (or discard it)
+   * immediately. The returned `state` has `csrf_token` removed.
+   *
+   * @instance
+   * @memberof AuthorizationBrowserFirstParty
+   * @returns {{idToken: string|undefined, email: string|undefined,
+   *   error: string|undefined, state: Object}}
+   */
+  handleThirdPartyCallback: function handleThirdPartyCallback() {
+    var location = _url2.default.parse(this.webex.getWindow().location.href, true);
+    location.query.state = (0, _common.decodeState)(location.query.state || 'e30');
+    this._verifySecurityToken(location.query, {
+      requireMatch: true
+    });
+    this._cleanUrl(location);
+    var _location$query = location.query,
+      idToken = _location$query.id_token,
+      email = _location$query.email,
+      error = _location$query.error,
+      _location$query$state = _location$query.state,
+      csrf_token = _location$query$state.csrf_token,
+      state = (0, _objectWithoutProperties2.default)(_location$query$state, _excluded);
+    return {
+      idToken: idToken,
+      email: email,
+      error: error,
+      state: state
+    };
+  },
   /**
    * Called by {@link WebexCore#logout()}.
    * Constructs logout URL and (unless suppressed) navigates away to ensure
@@ -696,8 +839,9 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    * - HTTP referrer headers to third-party content
    *
    * Approach:
-   * - Remove 'code'.
-   * - Remove 'state' entirely if only contained csrf_token.
+   * - Remove 'code' (OAuth code-grant), 'id_token', and 'email'
+   *   (third-party callback).
+   * - Remove 'state' entirely if it only contained csrf_token.
    * - Else, re-encode remaining state fields (minus csrf_token).
    * - Replace current history entry (no page reload).
    *
@@ -711,14 +855,16 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
     location = (0, _lodash.cloneDeep)(location);
     if (this.webex.getWindow().history && this.webex.getWindow().history.replaceState) {
       (0, _deleteProperty.default)(location.query, 'code');
+      (0, _deleteProperty.default)(location.query, 'id_token');
+      (0, _deleteProperty.default)(location.query, 'email');
       if ((0, _lodash.isEmpty)((0, _lodash.omit)(location.query.state, 'csrf_token'))) {
         (0, _deleteProperty.default)(location.query, 'state');
       } else {
-        location.query.state = _common.base64.encode((0, _stringify.default)((0, _lodash.omit)(location.query.state, 'csrf_token')));
+        location.query.state = (0, _common.encodeState)((0, _lodash.omit)(location.query.state, 'csrf_token'));
       }
       location.search = _querystring.default.stringify(location.query);
       (0, _deleteProperty.default)(location, 'query');
-      this.webex.getWindow().history.replaceState({}, null, _url.default.format(location));
+      this.webex.getWindow().history.replaceState({}, null, _url2.default.format(location));
     }
   },
   /**
@@ -727,7 +873,8 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    * during authorization code exchange; removes it once consumed.
    *
    * Implementation details:
-   * - Creates a 128 character string using base64url safe alphabet.
+   * - Creates a 128 character string using a cryptographically secure random
+   *   source and the base64url safe alphabet.
    * - Computes SHA256 hash, encodes to base64url (no padding).
    *
    * @instance
@@ -740,8 +887,10 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
 
     // eslint-disable-next-line no-underscore-dangle
     var safeCharacterMap = _encBase64url.default._safe_map;
-    var codeVerifier = lodash.times(128, function () {
-      return safeCharacterMap[lodash.random(0, safeCharacterMap.length - 1)];
+    var randomValues = new Uint8Array(128);
+    this.webex.getWindow().crypto.getRandomValues(randomValues);
+    var codeVerifier = (0, _from.default)(randomValues, function (randomValue) {
+      return safeCharacterMap[randomValue & safeCharacterMap.length - 1];
     }).join('');
     var codeChallenge = _cryptoJs.default.SHA256(codeVerifier).toString(_encBase64url.default);
     this.webex.getWindow().sessionStorage.setItem(OAUTH2_CODE_VERIFIER, codeVerifier);
@@ -773,24 +922,31 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
    * - 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.
+   * If no stored token (e.g., user navigated directly), silently returns
+   * unless `options.requireMatch` is `true`, in which case absence of a
+   * stored token is treated as a CSRF failure.
    *
    * @instance
    * @memberof AuthorizationBrowserFirstParty
    * @param {Object} query - Parsed query (location.query)
+   * @param {Object} [options]
+   * @param {boolean} [options.requireMatch=false] - When true, throws if
+   *   no stored sessionToken is present.
    * @private
    * @returns {void}
    */
   _verifySecurityToken: function _verifySecurityToken(query) {
+    var _query$state;
+    var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
     var sessionToken = this.webex.getWindow().sessionStorage.getItem(OAUTH2_CSRF_TOKEN);
     this.webex.getWindow().sessionStorage.removeItem(OAUTH2_CSRF_TOKEN);
     if (!sessionToken) {
+      if (options.requireMatch) {
+        throw new Error('CSRF token missing from session storage');
+      }
       return;
     }
-    if (!query.state) {
-      throw new Error("Expected CSRF token ".concat(sessionToken, ", but not found in redirect query"));
-    }
-    if (!query.state.csrf_token) {
+    if (!((_query$state = query.state) !== null && _query$state !== void 0 && _query$state.csrf_token)) {
       throw new Error("Expected CSRF token ".concat(sessionToken, ", but not found in redirect query"));
     }
     var token = query.state.csrf_token;
@@ -798,7 +954,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.12.0-next.5"
+  version: "3.12.0-next.50"
 }, (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