@webex/webex-core 3.12.0-next.5 → 3.12.0-next.50

package/src/lib/credentials/credentials.js

@@ -6,7 +6,7 @@ import querystring from 'querystring';
 import url from 'url';
 
 import jwt from 'jsonwebtoken';
-import {base64, makeStateDataType, oneFlight, tap, whileInFlight} from '@webex/common';
+import {base64, encodeState, makeStateDataType, oneFlight, tap, whileInFlight} from '@webex/common';
 import {safeSetTimeout} from '@webex/common-timers';
 import {clone, cloneDeep, isObject, isEmpty} from 'lodash';
 
@@ -109,7 +109,7 @@ const Credentials = WebexPlugin.extend({
    */
   buildLoginUrl(options = {clientType: 'public'}) {
     /* eslint-disable camelcase */
-    if (options.state && !isObject(options.state)) {
+    if (options.state !== undefined && !isObject(options.state)) {
       throw new Error('if specified, `options.state` must be an object');
     }
 
@@ -126,7 +126,7 @@ const Credentials = WebexPlugin.extend({
 
     if (options.state) {
       if (!isEmpty(options.state)) {
-        options.state = base64.toBase64Url(JSON.stringify(options.state));
+        options.state = encodeState(options.state);
       } else {
         delete options.state;
       }
@@ -212,6 +212,96 @@ const Credentials = WebexPlugin.extend({
     return fields[2];
   },
 
+  /**
+   * Extract the CI user ID [cis_uuid] from a provided token.
+   *
+   * @private
+   * @param {string} token - The access token to extract the user ID from.
+   * @throws {Error} - If the token cannot be parsed or does not contain a user ID.
+   * @returns {string} - The CI user ID.
+   */
+  extractUserIdFromToken(token = '') {
+    // User tokens are JWT-like; the middle section holds a base64-encoded JSON payload.
+    const payload = JSON.parse(base64.decode(token.split('.')[1]));
+
+    if (!payload.cis_uuid) {
+      throw new Error('the provided token does not contain a user ID');
+    }
+
+    return payload.cis_uuid;
+  },
+
+  /**
+   * Get the CI user ID [cis_uuid] of the currently authenticated user.
+   *
+   * Checks the supertoken first, then falls back to any stored user tokens.
+   *
+   * @throws {Error} - If the user ID could not be determined from any token.
+   * @returns {string} - The CI user ID.
+   */
+  getUserId() {
+    const tokens = [this.supertoken, ...this.userTokens.models];
+
+    for (const token of tokens) {
+      if (token && token.access_token) {
+        try {
+          return this.extractUserIdFromToken(token.access_token);
+        } catch {
+          // token wasn't parseable or lacked a user ID; try the next one
+        }
+      }
+    }
+
+    throw new Error('could not extract the user ID from any available token');
+  },
+
+  /**
+   * Generates a Third-Party Login URL pointing at IdBroker's
+   * `/idb/ThirdPartyLogin` endpoint. Used by the social-provider sign-in
+   * flow (Google / Microsoft / Apple / ...).
+   *
+   * Mirrors `buildLoginUrl` / `buildLogoutUrl` — pure URL construction,
+   * no navigation side effects. Reads from `this.config.thirdPartyLoginUrl`,
+   * which is derived from `idbroker.url` in `credentials-config.js`.
+   *
+   * @instance
+   * @memberof Credentials
+   * @param {Object} options
+   * @param {string} options.oauth2provider - Provider name (`google`,
+   *   `microsoft`, `apple`, ...). Required.
+   * @param {string} options.returnURL - URL IdBroker should send the user
+   *   back to after the third-party hand-off. Required.
+   * @param {Object} [options.state] - Optional state object. When non-empty
+   *   it is JSON-stringified and base64url-encoded, then emitted as the
+   *   top-level `state` query param so IdBroker can echo it back unchanged
+   *   on the callback (mirrors `buildLoginUrl`).
+   * @returns {string}
+   */
+  buildThirdPartyLoginUrl(options = {}) {
+    const {oauth2provider, returnURL, state} = options;
+
+    if (!oauth2provider) {
+      throw new Error('`options.oauth2provider` is required');
+    }
+    if (!returnURL) {
+      throw new Error('`options.returnURL` is required');
+    }
+    if (state !== undefined && !isObject(state)) {
+      throw new Error('if specified, `options.state` must be an object');
+    }
+
+    const query = {
+      oauth2provider,
+      returnURL,
+    };
+
+    if (state && !isEmpty(state)) {
+      query.state = encodeState(state);
+    }
+
+    return `${this.config.thirdPartyLoginUrl}?${querystring.stringify(query)}`;
+  },
+
   /**
    * Generates a Logout URL
    * @instance

package/src/lib/domains.ts

@@ -0,0 +1,94 @@
+import Url from 'url';
+
+import {uniq} from 'lodash';
+
+// Canonicalise a hostname for comparison: lowercase, drop the brackets around
+// an IPv6 literal, and drop leading/trailing dots. DNS treats `Example.com`,
+// `example.com.` and `example.com` as the same name.
+//
+// Node's `url.domainToASCII` looks like the standard way to do this, but the
+// `url` polyfill this package bundles for the browser does not implement it,
+// so it cannot be used here. It also leaves trailing dots in place.
+const normalizeHostname = (value: string): string =>
+  typeof value === 'string'
+    ? value
+        .toLowerCase()
+        .replace(/^\[|\]$/g, '')
+        .replace(/^\.+/, '')
+        .replace(/\.+$/, '')
+    : '';
+
+/**
+ * Canonicalise a list of configured allowed domains, discarding any entry that
+ * is not a usable hostname. Callers normalise on the way in so the stored list
+ * is already canonical, rather than re-deriving it on every request.
+ *
+ * @param {Array<string>} allowedDomains - The configured allowed domains.
+ * @returns {Array<string>} - Normalized, de-duplicated, non-empty entries.
+ */
+export const normalizeAllowedDomains = (allowedDomains: Array<string>): Array<string> =>
+  uniq(
+    (Array.isArray(allowedDomains) ? allowedDomains : []).map(normalizeHostname).filter(Boolean)
+  );
+
+/**
+ * Determine if a hostname is covered by an allowed domain, matching only on DNS
+ * label boundaries, so that a hostname is allowed only when it is the domain
+ * itself or a subdomain of it. Matching on a substring instead would treat
+ * unrelated hostnames that merely contain the domain as allowed.
+ *
+ * @param {string} hostname - Hostname to test. Must not include a port.
+ * @param {string} allowedDomain - The configured allowed domain.
+ * @returns {boolean} - True when the hostname is the domain or a subdomain of it.
+ */
+const hostnameMatchesDomain = (hostname: string, allowedDomain: string): boolean => {
+  // The stored list is normalized on write, but `allowedDomains` is a public
+  // property, so normalize again here rather than trust it.
+  const host = normalizeHostname(hostname);
+  const domain = normalizeHostname(allowedDomain);
+
+  return !!host && !!domain && (host === domain || host.endsWith(`.${domain}`));
+};
+
+/**
+ * Find the allowed domain covering a url, or `undefined` if there is none.
+ *
+ * Parsing lives here rather than in the callers, and deliberately uses both url
+ * parsers, because this check gates an `Authorization` header. The two
+ * transports behind `@webex/http-core` do not use the same url parser: the
+ * browser transport parses per WHATWG, the node transport uses Node's legacy
+ * `Url.parse`, and for some inputs the two resolve different hosts.
+ *
+ * Rather than picking one, require both to agree and fail closed when they do
+ * not, so this check can never authorize a host that differs from the one a
+ * transport would actually connect to. Do not narrow this to a single parser.
+ *
+ * @param {string} url - The url to match the allowed domains against.
+ * @param {Array<string>} allowedDomains - The configured allowed domains.
+ * @returns {string} - The matching allowed domain, or undefined if there is none.
+ */
+export const matchAllowedDomain = (
+  url: string,
+  allowedDomains: Array<string>
+): string | undefined => {
+  let hostname: string;
+  let legacyHostname: string;
+
+  try {
+    ({hostname} = new URL(url));
+    ({hostname: legacyHostname} = Url.parse(url));
+  } catch {
+    // Not a parsable absolute url, so it cannot belong to an allowed domain.
+    return undefined;
+  }
+
+  if (normalizeHostname(hostname) !== normalizeHostname(legacyHostname)) {
+    return undefined;
+  }
+
+  return (allowedDomains || []).find((allowedDomain) =>
+    hostnameMatchesDomain(hostname, allowedDomain)
+  );
+};
+
+export default matchAllowedDomain;

package/src/lib/services/service-catalog.js

@@ -4,6 +4,100 @@ import AmpState from 'ampersand-state';
 
 import {union} from 'lodash';
 import ServiceUrl from './service-url';
+import {matchAllowedDomain, normalizeAllowedDomains} from '../domains';
+
+// Catalog base URLs are a small, stable set, so their parsed origin/path is
+// memoized to avoid repeated `new URL()` work when scanning the catalog on the
+// request hot path.
+const catalogUrlCache = new Map();
+
+/**
+ * Parse a catalog URL into the origin and normalized path used for matching,
+ * memoizing the result. Returns null when the URL is unparsable.
+ *
+ * @param {string} catalogUrlString - The catalog URL to parse
+ * @returns {{origin: string, path: string} | null} - Parsed catalog URL, or null
+ */
+export function parseCatalogUrl(catalogUrlString) {
+  if (catalogUrlCache.has(catalogUrlString)) {
+    return catalogUrlCache.get(catalogUrlString);
+  }
+
+  let parsed = null;
+
+  try {
+    const catalogUrl = new URL(catalogUrlString);
+
+    // Normalize paths by removing trailing slashes (except root "/")
+    parsed = {origin: catalogUrl.origin, path: catalogUrl.pathname.replace(/\/$/, '') || '/'};
+  } catch {
+    parsed = null;
+  }
+
+  catalogUrlCache.set(catalogUrlString, parsed);
+
+  return parsed;
+}
+
+/**
+ * Check if an already-parsed candidate URL matches a parsed catalog URL with
+ * proper origin validation. Allocates nothing, so it is safe to call in a tight
+ * loop over the whole catalog.
+ *
+ * @param {URL} candidateUrl - The parsed candidate URL to validate
+ * @param {{origin: string, path: string} | null} parsedCatalogUrl - The parsed catalog URL
+ * @returns {boolean} - True if the candidate URL is under the catalog URL's origin and path
+ */
+export function matchesParsedCatalogUrl(candidateUrl, parsedCatalogUrl) {
+  if (!candidateUrl || !parsedCatalogUrl) {
+    return false;
+  }
+
+  // Origins must match exactly (scheme + host + port)
+  if (candidateUrl.origin !== parsedCatalogUrl.origin) {
+    return false;
+  }
+
+  const catalogPath = parsedCatalogUrl.path;
+
+  if (catalogPath === '/') {
+    // Root path matches everything under this origin
+    return true;
+  }
+
+  const candidatePath = candidateUrl.pathname;
+
+  if (candidatePath.startsWith(catalogPath)) {
+    // Ensure we're at a path boundary, not mid-segment
+    // e.g., /api/v1 should match /api/v1/foo but not /api/v1extra
+    // nextChar is undefined for exact match, '/' for valid extension
+    const nextChar = candidatePath[catalogPath.length];
+
+    return nextChar === '/' || nextChar === undefined;
+  }
+
+  return false;
+}
+
+/**
+ * Check if a candidate URL matches a catalog URL with proper origin validation.
+ * This prevents bypasses like https://trusted.example.attacker.com matching https://trusted.example
+ *
+ * @param {string} candidateUrlString - The URL to validate
+ * @param {string} catalogUrlString - The catalog URL to compare against
+ * @returns {boolean} - True if the candidate URL is under the catalog URL's origin and path
+ */
+export function matchesCatalogUrl(candidateUrlString, catalogUrlString) {
+  let candidateUrl;
+
+  try {
+    candidateUrl = new URL(candidateUrlString);
+  } catch {
+    return false;
+  }
+
+  return matchesParsedCatalogUrl(candidateUrl, parseCatalogUrl(catalogUrlString));
+}
 
 /* eslint-disable no-underscore-dangle */
 /**
@@ -245,20 +339,27 @@ const ServiceCatalog = AmpState.extend({
       ...this.serviceGroups.override,
     ];
 
+    // Invalid URLs cannot match any service
+    let candidateUrl;
+
+    try {
+      candidateUrl = new URL(url);
+    } catch {
+      return undefined;
+    }
+
     return serviceUrls.find((serviceUrl) => {
-      // Check to see if the URL we are checking starts with the default URL
-      if (url.startsWith(serviceUrl.defaultUrl)) {
+      // Check if the URL matches the default URL with proper origin validation
+      if (matchesParsedCatalogUrl(candidateUrl, parseCatalogUrl(serviceUrl.defaultUrl))) {
         return true;
       }
 
-      // If not, we check to see if the alternate URLs match
-      // These are made by swapping the host of the default URL
-      // with that of an alternate host
+      // Check alternate URLs (built by swapping host with alternate hosts)
       for (const host of serviceUrl.hosts) {
         const alternateUrl = new URL(serviceUrl.defaultUrl);
         alternateUrl.host = host.host;
 
-        if (url.startsWith(alternateUrl.toString())) {
+        if (matchesParsedCatalogUrl(candidateUrl, parseCatalogUrl(alternateUrl.toString()))) {
           return true;
         }
       }
@@ -268,19 +369,14 @@ const ServiceCatalog = AmpState.extend({
   },
 
   /**
-   * Finds an allowed domain that matches a specific url.
+   * Finds an allowed domain that matches a specific url. The url's hostname
+   * must be the allowed domain itself or a subdomain of it.
    *
    * @param {string} url - The url to match the allowed domains against.
    * @returns {string} - The matching allowed domain.
    */
   findAllowedDomain(url) {
-    const urlObj = Url.parse(url);
-
-    if (!urlObj.host) {
-      return undefined;
-    }
-
-    return this.allowedDomains.find((allowedDomain) => urlObj.host.includes(allowedDomain));
+    return matchAllowedDomain(url, this.allowedDomains);
   },
 
   /**
@@ -367,7 +463,7 @@ const ServiceCatalog = AmpState.extend({
    * @returns {void}
    */
   setAllowedDomains(allowedDomains) {
-    this.allowedDomains = [...allowedDomains];
+    this.allowedDomains = normalizeAllowedDomains(allowedDomains);
   },
 
   /**
@@ -376,7 +472,7 @@ const ServiceCatalog = AmpState.extend({
    * @returns {void}
    */
   addAllowedDomains(newAllowedDomains) {
-    this.allowedDomains = union(this.allowedDomains, newAllowedDomains);
+    this.allowedDomains = union(this.allowedDomains, normalizeAllowedDomains(newAllowedDomains));
   },
 
   /**

package/src/lib/services/services.js

@@ -57,6 +57,22 @@ const Services = WebexPlugin.extend({
     initFailed: ['boolean', false, false],
   },
 
+  session: {
+    /**
+     * Becomes `true` once the initial catalog collection has completed
+     * (successfully or otherwise) and any in-flight credentials refresh has
+     * settled. Blocks `webex.ready` so consumers can rely on `webex.ready`
+     * implying "catalogs populated AND credential state stable".
+     * @instance
+     * @memberof Services
+     * @type {boolean}
+     */
+    ready: {
+      default: false,
+      type: 'boolean',
+    },
+  },
+
   _catalogs: new WeakMap(),
 
   _serviceUrls: null,
@@ -1087,9 +1103,16 @@ const Services = WebexPlugin.extend({
       requestObject.headers = {authorization: token};
     }
 
-    return this.webex.internal.newMetrics.callDiagnosticLatencies
-      .measureLatency(() => this.request(requestObject), 'internal.get.u2c.time')
-      .then(({body}) => body);
+    const sendRequest = () => this.request(requestObject);
+
+    const responsePromise = this.webex.internal.newMetrics
+      ? this.webex.internal.newMetrics.callDiagnosticLatencies.measureLatency(
+          sendRequest,
+          'internal.get.u2c.time'
+        )
+      : sendRequest();
+
+    return responsePromise.then(({body}) => body);
   },
 
   /**
@@ -1346,6 +1369,7 @@ const Services = WebexPlugin.extend({
 
     // Destructure the credentials plugin.
     const {credentials} = this.webex;
+    const catalog = this._getCatalog();
 
     // Init a promise chain. Must be done as a Promise.resolve() to allow
     // credentials#getOrgId() to properly throw.
@@ -1358,12 +1382,18 @@ const Services = WebexPlugin.extend({
         .then(() => {
           // Validate if the token is authorized.
           if (credentials.canAuthorize) {
-            // Attempt to collect the postauth catalog.
-
-            return this.updateServices().catch(() => {
-              this.initFailed = true;
-              this.logger.warn('services: cannot retrieve postauth catalog');
-            });
+            // Attempt to collect the postauth catalog, then mark the catalog
+            // ready. Setting `isReady` here - rather than only in the init
+            // callers - means a slow postauth fetch that loses the gated-init
+            // timeout race still marks the catalog ready once it completes.
+            return this.updateServices()
+              .then(() => {
+                catalog.isReady = true;
+              })
+              .catch(() => {
+                this.initFailed = true;
+                this.logger.warn('services: cannot retrieve postauth catalog');
+              });
           }
 
           // Return a resolved promise for consistent return value.
@@ -1372,6 +1402,51 @@ const Services = WebexPlugin.extend({
     );
   },
 
+  /**
+   * Await any in-flight credentials refresh, then flip `services.ready` so
+   * `webex.ready` can fire. Closes the parallel-refresh window: if a credential
+   * refresh is in flight when initial catalog collection settles, we must not
+   * signal ready until the refresh has resolved - otherwise downstream
+   * consumers may observe `canAuthorize`/token state that is about to change
+   * under them.
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  async _finalizeReady() {
+    const {credentials} = this.webex;
+
+    if (credentials && credentials.isRefreshing) {
+      await new Promise((resolve) => {
+        credentials.once('change:isRefreshing', resolve);
+      });
+    }
+
+    this.ready = true;
+  },
+
+  /**
+   * Build a promise that rejects once the catalog init timeout elapses. Race
+   * this against catalog collection so a hung request never leaves
+   * `services.ready` false forever - that would stall `webex.ready` and leave
+   * consumers waiting on it indefinitely. Timeout is configurable via
+   * `config.services.catalogInitTimeout` (defaults to 15s in config). Created
+   * lazily so paths that skip catalog collection never schedule a stray timer.
+   *
+   * @private
+   * @returns {Promise<never>}
+   */
+  _makeInitTimeout() {
+    const initTimeoutMs = this.webex.config?.services?.catalogInitTimeout;
+
+    return new Promise((_, reject) => {
+      setTimeout(
+        () => reject(new Error(`services: init timed out after ${initTimeoutMs}ms`)),
+        initTimeoutMs
+      );
+    });
+  },
+
   /**
    * Initializer
    *
@@ -1388,11 +1463,39 @@ const Services = WebexPlugin.extend({
     this.registries.set(this.webex, registry);
     this.states.set(this.webex, state);
 
-    // Listen for configuration changes once.
+    // Listen for configuration changes once. The config is not populated on the
+    // webex instance until the `change:config` event fires, so any decision that
+    // depends on config values (such as the gated-vs-ungated init below) must be
+    // made from within this handler rather than synchronously in `initialize()`.
     this.listenToOnce(this.webex, 'change:config', () => {
       this.initConfig();
+
+      // Feature flag: when enabled, `webex.ready` is blocked until the initial
+      // catalog collection has settled AND any in-flight credentials refresh has
+      // completed. When disabled (the default), preserves the pre-existing
+      // behavior where `webex.ready` fires as soon as `webex.loaded` does and
+      // the catalog is collected out-of-band.
+      const waitForCatalogInit = this.webex.config?.services?.waitForCatalogInit === true;
+
+      if (waitForCatalogInit) {
+        this._initializeCatalogsGated(catalog);
+      } else {
+        // Not gating - immediately mark ready so we do not block webex.ready.
+        this.ready = true;
+        this._initializeCatalogsUngated(catalog);
+      }
     });
+  },
 
+  /**
+   * Original (pre-verified-ready) initialization path. Runs on `webex.ready`
+   * and collects catalogs opportunistically without blocking anything.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsUngated(catalog) {
     // wait for webex instance to be ready before attempting
     // to update the service catalogs
     // this can cause a race condition because credentials may
@@ -1407,19 +1510,25 @@ const Services = WebexPlugin.extend({
       const {supertoken} = this.webex.credentials;
       // Validate if the supertoken exists.
       if (supertoken && supertoken.access_token) {
-        this.initServiceCatalogs()
-          .then(() => {
-            catalog.isReady = true;
-          })
-          .catch((error) => {
-            this.initFailed = true;
-            this.logger.error(
-              `services: failed to init initial services when credentials available, ${error?.message}`
-            );
-          });
+        // `initServiceCatalogs` marks the catalog ready internally once the
+        // postauth catalog is collected.
+        this.initServiceCatalogs().catch((error) => {
+          this.initFailed = true;
+          this.logger.error(
+            `services: failed to init initial services when credentials available, ${error?.message}`
+          );
+        });
       } else {
         const {email} = this.webex.config;
 
+        if (this.webex.config?.services?.skipPreauthCatalogOnUnauthenticated === true) {
+          this.logger.info(
+            'services: skipping preauth catalog collection while unauthenticated as per the config'
+          );
+
+          return;
+        }
+
         this.collectPreauthCatalog(email ? {email} : undefined).catch((error) => {
           this.initFailed = true;
           this.logger.error(
@@ -1429,6 +1538,85 @@ const Services = WebexPlugin.extend({
       }
     });
   },
+
+  /**
+   * Verified-ready initialization path. Blocks `webex.ready` until the initial
+   * catalog fetch has settled (or timed out) AND any in-flight credentials
+   * refresh has completed. Also handles the fresh-login case where OAuth
+   * completes after `loaded` fires.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsGated(catalog) {
+    // Wait for storage to be loaded before attempting to update the service
+    // catalogs. We listen for 'loaded' instead of 'ready' because `services.ready`
+    // now blocks `webex.ready` - listening to 'ready' would deadlock.
+    this.listenToOnce(this.webex, 'loaded', async () => {
+      const cachedCatalog = await this._loadCatalogFromCache();
+      if (cachedCatalog) {
+        catalog.isReady = true;
+        await this._finalizeReady();
+
+        return; // skip initServiceCatalogs() on reload when cache exists
+      }
+      const {supertoken} = this.webex.credentials;
+
+      // Validate if the supertoken exists.
+      if (supertoken && supertoken.access_token) {
+        // `initServiceCatalogs` marks the catalog ready internally once the
+        // postauth catalog is collected - even if it loses the timeout race
+        // below, so a slow fetch still eventually flips `catalog.isReady`.
+        Promise.race([this.initServiceCatalogs(), this._makeInitTimeout()])
+          .catch((error) => {
+            this.initFailed = true;
+            this.logger.error(
+              `services: failed to init initial services when credentials available, ${error?.message}`
+            );
+          })
+          .finally(() => this._finalizeReady());
+      } else {
+        const {email} = this.webex.config;
+
+        // Handle fresh login: 'loaded' fires before OAuth completes, so listen
+        // for `canAuthorize` flipping true and then collect the postauth catalog.
+        this.listenToOnce(this.webex, 'change:canAuthorize', () => {
+          if (this.webex.canAuthorize && !catalog.status.postauth.ready) {
+            // `initServiceCatalogs` marks the catalog ready internally.
+            this.initServiceCatalogs().catch((error) => {
+              this.logger.error(
+                `services: failed to init service catalogs after auth, ${error?.message}`
+              );
+            });
+          }
+        });
+
+        if (this.webex.config?.services?.skipPreauthCatalogOnUnauthenticated === true) {
+          // Skip the preauth catalog fetch (it will be collected manually
+          // later), but still finalize `services.ready` so `webex.ready` is not
+          // stalled while unauthenticated. No timeout is created here so there
+          // is no stray timer or unhandled rejection.
+          this.logger.info(
+            'services: skipping preauth catalog collection while unauthenticated as per the config'
+          );
+          this._finalizeReady();
+        } else {
+          Promise.race([
+            this.collectPreauthCatalog(email ? {email} : undefined),
+            this._makeInitTimeout(),
+          ])
+            .catch((error) => {
+              this.initFailed = true;
+              this.logger.error(
+                `services: failed to init initial services when no credentials available, ${error?.message}`
+              );
+            })
+            .finally(() => this._finalizeReady());
+        }
+      }
+    });
+  },
 });
 /* eslint-enable no-underscore-dangle */