@webex/webex-core 3.12.0-task-refactor.1 → 3.12.0-webex-services-ready.1

package/test/unit/spec/services/services.js

@@ -34,6 +34,53 @@ describe('webex-core', () => {
     });
 
     describe('#initialize', () => {
+      it('listens for "loaded" event instead of "ready" to avoid deadlock', () => {
+        services.listenToOnce = sinon.stub();
+        services.initialize();
+
+        // Second listenToOnce call should be for 'loaded' event
+        assert.equal(services.listenToOnce.getCall(1).args[1], 'loaded');
+      });
+
+      it('services.ready starts as false', () => {
+        assert.isFalse(services.ready);
+      });
+
+      it('sets ready to true and triggers services:initialized when initialization succeeds with credentials', async () => {
+        services.listenToOnce = sinon.stub();
+        services.initServiceCatalogs = sinon.stub().returns(Promise.resolve());
+        services.trigger = sinon.stub();
+        services.webex.credentials = {
+          supertoken: {
+            access_token: 'token',
+          },
+        };
+
+        services.initialize();
+
+        // call the onLoaded callback
+        services.listenToOnce.getCall(1).args[2]();
+        await waitForAsync();
+
+        assert.isTrue(services.ready);
+        sinon.assert.calledWith(services.trigger, 'services:initialized');
+      });
+
+      it('sets ready to true and triggers services:initialized when initialization succeeds without credentials', async () => {
+        services.listenToOnce = sinon.stub();
+        services.collectPreauthCatalog = sinon.stub().returns(Promise.resolve());
+        services.trigger = sinon.stub();
+
+        services.initialize();
+
+        // call the onLoaded callback
+        services.listenToOnce.getCall(1).args[2]();
+        await waitForAsync();
+
+        assert.isTrue(services.ready);
+        sinon.assert.calledWith(services.trigger, 'services:initialized');
+      });
+
       it('initFailed is false when initialization succeeds and credentials are available', async () => {
         services.listenToOnce = sinon.stub();
         services.initServiceCatalogs = sinon.stub().returns(Promise.resolve());
@@ -45,7 +92,7 @@ describe('webex-core', () => {
 
         services.initialize();
 
-        // call the onReady callback
+        // call the onLoaded callback
         services.listenToOnce.getCall(1).args[2]();
         await waitForAsync();
 
@@ -58,7 +105,7 @@ describe('webex-core', () => {
 
         services.initialize();
 
-        // call the onReady callback
+        // call the onLoaded callback
         services.listenToOnce.getCall(1).args[2]();
         await waitForAsync();
 
@@ -67,9 +114,9 @@ describe('webex-core', () => {
 
       it.each([
         {error: new Error('failed'), expectedMessage: 'failed'},
-        {error: undefined, expectedMessage: undefined}
+        {error: undefined, expectedMessage: undefined},
       ])(
-        'sets initFailed to true when collectPreauthCatalog errors',
+        'sets initFailed to true when collectPreauthCatalog errors but still sets ready to true',
         async ({error, expectedMessage}) => {
           services.collectPreauthCatalog = sinon.stub().callsFake(() => {
             return Promise.reject(error);
@@ -77,15 +124,18 @@ describe('webex-core', () => {
 
           services.listenToOnce = sinon.stub();
           services.logger.error = sinon.stub();
+          services.trigger = sinon.stub();
 
           services.initialize();
 
-          // call the onReady callback
+          // call the onLoaded callback
           services.listenToOnce.getCall(1).args[2]();
 
           await waitForAsync();
 
           assert.isTrue(services.initFailed);
+          assert.isTrue(services.ready);
+          sinon.assert.calledWith(services.trigger, 'services:initialized');
           sinon.assert.calledWith(
             services.logger.error,
             `services: failed to init initial services when no credentials available, ${expectedMessage}`
@@ -95,32 +145,132 @@ describe('webex-core', () => {
 
       it.each([
         {error: new Error('failed'), expectedMessage: 'failed'},
-        {error: undefined, expectedMessage: undefined}
-      ])('sets initFailed to true when initServiceCatalogs errors', async ({error, expectedMessage}) => {
-        services.initServiceCatalogs = sinon.stub().callsFake(() => {
-          return Promise.reject(error);
-        });
-        services.webex.credentials = {
-          supertoken: {
-            access_token: 'token'
-          }
+        {error: undefined, expectedMessage: undefined},
+      ])(
+        'sets initFailed to true when initServiceCatalogs errors but still sets ready to true',
+        async ({error, expectedMessage}) => {
+          services.initServiceCatalogs = sinon.stub().callsFake(() => {
+            return Promise.reject(error);
+          });
+          services.webex.credentials = {
+            supertoken: {
+              access_token: 'token',
+            },
+          };
+
+          services.listenToOnce = sinon.stub();
+          services.logger.error = sinon.stub();
+          services.trigger = sinon.stub();
+
+          services.initialize();
+
+          // call the onLoaded callback
+          services.listenToOnce.getCall(1).args[2]();
+
+          await waitForAsync();
+
+          assert.isTrue(services.initFailed);
+          assert.isTrue(services.ready);
+          sinon.assert.calledWith(services.trigger, 'services:initialized');
+          sinon.assert.calledWith(
+            services.logger.error,
+            `services: failed to init initial services when credentials available, ${expectedMessage}`
+          );
         }
+      );
 
-        services.listenToOnce = sinon.stub();
-        services.logger.error = sinon.stub();
+      describe('when change:canAuthorize fires', () => {
+        it('calls initServiceCatalogs when canAuthorize becomes true and postauth catalog is not ready', async () => {
+          services.listenToOnce = sinon.stub();
+          services._loadCatalogFromCache = sinon.stub().returns(Promise.resolve(false));
+          services.collectPreauthCatalog = sinon.stub().returns(Promise.resolve());
+          services.initServiceCatalogs = sinon.stub().returns(Promise.resolve());
+          services.trigger = sinon.stub();
+          // Ensure no credentials so we go to the preauth path
+          services.webex.credentials = {};
 
-        services.initialize();
+          services.initialize();
 
-        // call the onReady callback
-        services.listenToOnce.getCall(1).args[2]();
+          // Get the catalog after initialize creates it
+          const testCatalog = services._getCatalog();
+          testCatalog.status.postauth.ready = false;
 
-        await waitForAsync();
+          // call the onLoaded callback (preauth path)
+          services.listenToOnce.getCall(1).args[2]();
+          await waitForAsync();
 
-        assert.isTrue(services.initFailed);
-        sinon.assert.calledWith(
-          services.logger.error,
-          `services: failed to init initial services when credentials available, ${expectedMessage}`
-        );
+          // Now set canAuthorize to true to simulate auth completing
+          services.webex.canAuthorize = true;
+
+          // call the change:canAuthorize callback (should be call 2)
+          services.listenToOnce.getCall(2).args[2]();
+          await waitForAsync();
+
+          sinon.assert.calledOnce(services.initServiceCatalogs);
+          assert.isTrue(testCatalog.isReady);
+        });
+
+        it('does not call initServiceCatalogs when postauth catalog is already ready', async () => {
+          services.listenToOnce = sinon.stub();
+          services._loadCatalogFromCache = sinon.stub().returns(Promise.resolve(false));
+          services.collectPreauthCatalog = sinon.stub().returns(Promise.resolve());
+          services.initServiceCatalogs = sinon.stub().returns(Promise.resolve());
+          services.trigger = sinon.stub();
+          // Ensure no credentials so we go to the preauth path
+          services.webex.credentials = {};
+
+          services.initialize();
+
+          // Get the catalog after initialize creates it
+          const testCatalog = services._getCatalog();
+
+          // call the onLoaded callback (preauth path)
+          services.listenToOnce.getCall(1).args[2]();
+          await waitForAsync();
+
+          // Set canAuthorize to true and postauth as ready BEFORE calling the callback
+          services.webex.canAuthorize = true;
+          testCatalog.status.postauth.ready = true;
+
+          // call the change:canAuthorize callback (should be call 2)
+          services.listenToOnce.getCall(2).args[2]();
+          await waitForAsync();
+
+          sinon.assert.notCalled(services.initServiceCatalogs);
+        });
+
+        it('logs an error when initServiceCatalogs fails after auth', async () => {
+          services.listenToOnce = sinon.stub();
+          services._loadCatalogFromCache = sinon.stub().returns(Promise.resolve(false));
+          services.collectPreauthCatalog = sinon.stub().returns(Promise.resolve());
+          services.initServiceCatalogs = sinon.stub().rejects(new Error('auth failed'));
+          services.logger.error = sinon.stub();
+          services.trigger = sinon.stub();
+          // Ensure no credentials so we go to the preauth path
+          services.webex.credentials = {};
+
+          services.initialize();
+
+          // Get the catalog after initialize creates it
+          const testCatalog = services._getCatalog();
+          testCatalog.status.postauth.ready = false;
+
+          // call the onLoaded callback (preauth path)
+          services.listenToOnce.getCall(1).args[2]();
+          await waitForAsync();
+
+          // Now set canAuthorize to true to simulate auth completing
+          services.webex.canAuthorize = true;
+
+          // call the change:canAuthorize callback (should be call 2)
+          services.listenToOnce.getCall(2).args[2]();
+          await waitForAsync();
+
+          sinon.assert.calledWith(
+            services.logger.error,
+            'services: failed to init service catalogs after auth, auth failed'
+          );
+        });
       });
     });
 
@@ -159,7 +309,7 @@ describe('webex-core', () => {
 
         services.collectPreauthCatalog = sinon.stub().callsFake(() => {
           return Promise.resolve();
-        })
+        });
 
         services.updateServices = sinon.stub().callsFake(() => {
           return Promise.reject(error);
@@ -254,7 +404,7 @@ describe('webex-core', () => {
             discovery: {
               sqdiscovery: 'https://test.ciscospark.com/v1/region',
             },
-          }
+          },
         };
       });
 
@@ -274,8 +424,8 @@ describe('webex-core', () => {
           assert.calledWith(webex.request, {
             uri: 'https://test.ciscospark.com/v1/region',
             addAuthHeader: false,
-            headers: { 'spark-user-agent': null },
-            timeout: 5000
+            headers: {'spark-user-agent': null},
+            timeout: 5000,
           });
         });
       });
@@ -332,7 +482,6 @@ describe('webex-core', () => {
     });
 
     describe('#_fetchNewServiceHostmap()', () => {
-
       beforeEach(() => {
         sinon.spy(webex.internal.newMetrics.callDiagnosticLatencies, 'measureLatency');
       });
@@ -346,19 +495,20 @@ describe('webex-core', () => {
 
         sinon.stub(services, '_formatReceivedHostmap').resolves(mapResponse);
         sinon.stub(services, 'request').resolves({});
-        
-        const mapResult = await services._fetchNewServiceHostmap({from: 'limited'});
 
-        assert.deepEqual(mapResult, mapResponse);
+        const mapResult = await services._fetchNewServiceHostmap({from: 'limited'});
 
         assert.calledOnceWithExactly(services.request, {
           method: 'GET',
           service: 'u2c',
           resource: '/limited/catalog',
-          qs: {format: 'hostmap'}
-        }
+          qs: {format: 'hostmap'},
+        });
+        assert.calledOnceWithExactly(
+          webex.internal.newMetrics.callDiagnosticLatencies.measureLatency,
+          sinon.match.func,
+          'internal.get.u2c.time'
         );
-        assert.calledOnceWithExactly(webex.internal.newMetrics.callDiagnosticLatencies.measureLatency, sinon.match.func, 'internal.get.u2c.time');
       });
 
       it('checks service request rejects', async () => {
@@ -366,7 +516,7 @@ describe('webex-core', () => {
 
         sinon.spy(services, '_formatReceivedHostmap');
         sinon.stub(services, 'request').rejects(error);
-        
+
         const promise = services._fetchNewServiceHostmap({from: 'limited'});
         const rejectedValue = await assert.isRejected(promise);
 
@@ -378,10 +528,13 @@ describe('webex-core', () => {
           method: 'GET',
           service: 'u2c',
           resource: '/limited/catalog',
-          qs: {format: 'hostmap'}
-        }
+          qs: {format: 'hostmap'},
+        });
+        assert.calledOnceWithExactly(
+          webex.internal.newMetrics.callDiagnosticLatencies.measureLatency,
+          sinon.match.func,
+          'internal.get.u2c.time'
         );
-        assert.calledOnceWithExactly(webex.internal.newMetrics.callDiagnosticLatencies.measureLatency, sinon.match.func, 'internal.get.u2c.time');
       });
     });
 
@@ -412,7 +565,6 @@ describe('webex-core', () => {
       });
 
       it('returns the original uri if the hostmap has no hosts for the host', () => {
-
         services._hostCatalog = {
           'example.com': [],
         };
@@ -576,8 +728,7 @@ describe('webex-core', () => {
                 id: '0:0:0:different-e-x',
               },
             ],
-            'example-f.com': [
-            ],
+            'example-f.com': [],
           },
           format: 'hostmap',
         };
@@ -785,7 +936,7 @@ describe('webex-core', () => {
             defaultUrl: 'https://example-g.com/api/v1',
             hosts: [],
             name: 'example-g',
-          }
+          },
         ]);
       });
 
@@ -839,63 +990,92 @@ describe('webex-core', () => {
         assert.equal(webex.config.credentials.authorizeUrl, authUrl);
       });
     });
-    
+
     describe('#getMobiusClusters', () => {
       it('returns unique mobius host entries from hostCatalog', () => {
         // Arrange: two hostCatalog keys, with duplicate mobius host across keys
         services._hostCatalog = {
-          'mobius-a.webex.com': [
-            {host: 'mobius-a.webex.com', ttl: -1, priority: 5, id: 'urn:TEAM:xyz:mobius'},
-            {host: 'mobius-b.webex.com', ttl: -1, priority: 10, id: 'urn:TEAM:xyz:mobius'},
-            {host: 'ignore.webex.com', ttl: -1, priority: 1, id: 'urn:TEAM:abc:wdm'}, // not mobius
+          'mobius-us-east-2.prod.infra.webex.com': [
+            {
+              host: 'mobius-us-east-2.prod.infra.webex.com',
+              ttl: -1,
+              priority: 5,
+              id: 'urn:TEAM:xyz:mobius',
+            },
+            {
+              host: 'mobius-eu-central-1.prod.infra.webex.com',
+              ttl: -1,
+              priority: 10,
+              id: 'urn:TEAM:xyz:mobius',
+            },
           ],
-          'dup-entry-key': [
-            {host: 'mobius-a.webex.com', ttl: -1, priority: 7, id: 'urn:TEAM:xyz:mobius'}, // duplicate host
+
+          'mobius-eu-central-1.prod.infra.webex.com': [
+            {
+              host: 'mobius-us-east-2.prod.infra.webex.com',
+              ttl: -1,
+              priority: 7,
+              id: 'urn:TEAM:xyz:mobius',
+            }, // duplicate host
+          ],
+          'wdm-a.webex.com': [
+            {host: 'wdm-a.webex.com', ttl: -1, priority: 5, id: 'urn:TEAM:xyz:wdm'},
           ],
         };
-    
+
         // Act
         const clusters = services.getMobiusClusters();
-    
+
         // Assert
         // deduped; only mobius entries; keeps first seen mobius-a, then mobius-b
         assert.deepEqual(
           clusters.map(({host, id, ttl, priority}) => ({host, id, ttl, priority})),
           [
-            {host: 'mobius-a.webex.com', id: 'urn:TEAM:xyz:mobius', ttl: -1, priority: 5},
-            {host: 'mobius-b.webex.com', id: 'urn:TEAM:xyz:mobius', ttl: -1, priority: 10},
+            {
+              host: 'mobius-us-east-2.prod.infra.webex.com',
+              id: 'urn:TEAM:xyz:mobius',
+              ttl: -1,
+              priority: 5,
+            },
+            {
+              host: 'mobius-eu-central-1.prod.infra.webex.com',
+              id: 'urn:TEAM:xyz:mobius',
+              ttl: -1,
+              priority: 10,
+            },
           ]
         );
       });
     });
+
     describe('#isValidHost', () => {
       beforeEach(() => {
         // Setting up a mock host catalog
-          services._hostCatalog = {
-            "audit-ci-m.wbx2.com": [
-              {
-                  "host": "audit-ci-m.wbx2.com",
-                  "ttl": -1,
-                  "priority": 5,
-                  "id": "urn:IDENTITY:PA61:adminAudit"
-              },
-              {
-                  "host": "audit-ci-m.wbx2.com",
-                  "ttl": -1,
-                  "priority": 5,
-                  "id": "urn:IDENTITY:PA61:adminAuditV2"
-              }
-            ],
-            "mercury-connection-partition0-r.wbx2.com": [
-                {
-                    "host": "mercury-connection-partition0-r.wbx2.com",
-                    "ttl": -1,
-                    "priority": 5,
-                    "id": "urn:TEAM:us-west-2_r:mercuryConnectionPartition0"
-                }
-            ],
-            "empty.com": []
-          };
+        services._hostCatalog = {
+          'audit-ci-m.wbx2.com': [
+            {
+              host: 'audit-ci-m.wbx2.com',
+              ttl: -1,
+              priority: 5,
+              id: 'urn:IDENTITY:PA61:adminAudit',
+            },
+            {
+              host: 'audit-ci-m.wbx2.com',
+              ttl: -1,
+              priority: 5,
+              id: 'urn:IDENTITY:PA61:adminAuditV2',
+            },
+          ],
+          'mercury-connection-partition0-r.wbx2.com': [
+            {
+              host: 'mercury-connection-partition0-r.wbx2.com',
+              ttl: -1,
+              priority: 5,
+              id: 'urn:TEAM:us-west-2_r:mercuryConnectionPartition0',
+            },
+          ],
+          'empty.com': [],
+        };
       });
       afterAll(() => {
         // Clean up the mock host catalog
@@ -919,6 +1099,426 @@ describe('webex-core', () => {
         assert.isFalse(services.isValidHost([]));
       });
     });
+
+    describe('#isIntegrationEnvironment', () => {
+      it('returns true when u2c URL contains "intb"', () => {
+        services.webex.config = {
+          services: {
+            discovery: {
+              u2c: 'https://u2c-intb.ciscospark.com/u2c/api/v1',
+            },
+          },
+        };
+        assert.isTrue(services.isIntegrationEnvironment());
+      });
+
+      it('returns false when u2c URL does not contain "intb" (production)', () => {
+        services.webex.config = {
+          services: {
+            discovery: {
+              u2c: 'https://u2c.wbx2.com/u2c/api/v1',
+            },
+          },
+        };
+        assert.isFalse(services.isIntegrationEnvironment());
+      });
+
+      it('returns false when u2c URL is for FedRAMP', () => {
+        services.webex.config = {
+          services: {
+            discovery: {
+              u2c: 'https://u2c.gov.ciscospark.com/u2c/api/v1',
+            },
+          },
+        };
+        assert.isFalse(services.isIntegrationEnvironment());
+      });
+
+      it('returns false when u2c URL is undefined', () => {
+        services.webex.config = {
+          services: {
+            discovery: {
+              u2c: undefined,
+            },
+          },
+        };
+        assert.isFalse(services.isIntegrationEnvironment());
+      });
+
+      it('returns false when config is not available', () => {
+        services.webex.config = undefined;
+        assert.isFalse(services.isIntegrationEnvironment());
+      });
+    });
+
+    describe('U2C catalog cache behavior', () => {
+      let webex;
+      let services;
+      let catalog;
+      let localStorageBackup;
+      let windowBackup;
+
+      const makeLocalStorageShim = () => {
+        const store = new Map();
+        return {
+          getItem: (k) => (store.has(k) ? store.get(k) : null),
+          setItem: (k, v) => store.set(k, v),
+          removeItem: (k) => store.delete(k),
+          _store: store,
+        };
+      };
+
+      beforeEach(() => {
+        // Build a fresh webex instance
+        webex = new MockWebex({
+          children: {services: Services},
+          config: {credentials: {federation: true}},
+        });
+        services = webex.internal.services;
+        catalog = services._getCatalog();
+
+        // enable U2C caching feature flag in tests that rely on localStorage writes/reads
+        services.webex.config = services.webex.config || {};
+        services.webex.config.calling = {...(services.webex.config.calling || {}), cacheU2C: true};
+
+        // stub window.localStorage
+        windowBackup = global.window;
+        if (!global.window) global.window = {};
+        localStorageBackup = global.window.localStorage;
+        global.window.localStorage = makeLocalStorageShim();
+        // Ensure code under test uses our shim via util method
+        sinon.stub(services, '_getLocalStorageSafe').returns(global.window.localStorage);
+
+        // Stub the formatter so we don't need a full hostmap payload in tests
+        sinon
+          .stub(services, '_formatReceivedHostmap')
+          .callsFake(() => [
+            {name: 'hydra', defaultUrl: 'https://api.ciscospark.com/v1', hosts: []},
+          ]);
+      });
+
+      afterEach(() => {
+        global.window.localStorage = localStorageBackup || undefined;
+        if (!windowBackup) {
+          delete global.window;
+        } else {
+          global.window = windowBackup;
+        }
+        // Restore util stub if present
+        if (services._getLocalStorageSafe && services._getLocalStorageSafe.restore) {
+          services._getLocalStorageSafe.restore();
+        }
+      });
+
+      it('invokes initServiceCatalogs on ready, caches catalog, and stores in localStorage', async () => {
+        // Arrange: authenticated credentials and spies
+        services.webex.credentials = {
+          getOrgId: sinon.stub().returns('urn:EXAMPLE:org'),
+          canAuthorize: true,
+          supertoken: {access_token: 'token'},
+        };
+        const initSpy = sinon.spy(services, 'initServiceCatalogs');
+        const cacheSpy = sinon.spy(services, '_cacheCatalog');
+        const setItemSpy = sinon.spy(global.window.localStorage, 'setItem');
+        // Make fetch return a hostmap object and allow formatter to reduce it
+        sinon
+          .stub(services, 'request')
+          .resolves({
+            body: {
+              services: [],
+              activeServices: {},
+              timestamp: Date.now().toString(),
+              orgId: 'urn:EXAMPLE:org',
+              format: 'U2CV2',
+            },
+          });
+        // Cause loaded callback to run immediately
+        services.listenToOnce = sinon.stub().callsFake((ctx, event, cb) => {
+          if (event === 'loaded') cb();
+        });
+
+        // Act
+        services.initialize();
+        await waitForAsync();
+
+        // Assert: initServiceCatalogs was called because there was no cache
+        assert.isTrue(initSpy.called, 'expected initServiceCatalogs to be invoked on ready');
+        // _cacheCatalog is called at least once (preauth/postauth flows)
+        assert.isTrue(cacheSpy.called, 'expected _cacheCatalog to be called');
+        assert.isTrue(setItemSpy.called, 'expected localStorage.setItem to be called');
+
+        // Cleanup spies
+        services.request.restore();
+        initSpy.restore();
+        cacheSpy.restore();
+        setItemSpy.restore();
+      });
+
+      it('does not invoke initServiceCatalogs on ready when cache exists and uses cached catalog', async () => {
+        // Arrange: put a valid cache
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        const cached = {
+          orgId: 'urn:EXAMPLE:org',
+          cachedAt: Date.now(),
+          preauth: {serviceLinks: {}, hostCatalog: {}},
+          postauth: {serviceLinks: {}, hostCatalog: {}},
+        };
+        global.window.localStorage.setItem(CATALOG_CACHE_KEY_V1, JSON.stringify(cached));
+
+        // authenticated credentials
+        services.webex.credentials = {
+          getOrgId: sinon.stub().returns('urn:EXAMPLE:org'),
+          canAuthorize: true,
+          supertoken: {access_token: 'token'},
+        };
+
+        const initSpy = sinon.spy(services, 'initServiceCatalogs');
+        const cacheSpy = sinon.spy(services, '_cacheCatalog');
+        // Cause loaded callback to run immediately
+        services.listenToOnce = sinon.stub().callsFake((ctx, event, cb) => {
+          if (event === 'loaded') cb();
+        });
+
+        // Act
+        services.initialize();
+        await waitForAsync();
+
+        // Assert: ready path found cache and skipped initServiceCatalogs
+        assert.isFalse(
+          initSpy.called,
+          'expected initServiceCatalogs to be skipped with cache present'
+        );
+        assert.isTrue(
+          services._getCatalog().status.preauth.ready,
+          'preauth should be ready from cache'
+        );
+        assert.isTrue(
+          services._getCatalog().status.postauth.ready,
+          'postauth should be ready from cache'
+        );
+        assert.isFalse(cacheSpy.called, 'should not write cache during warm-up-only path');
+
+        // Cleanup
+        initSpy.restore();
+        cacheSpy.restore();
+      });
+
+      it('expires cached catalog after TTL and clears the entry', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        const staleCached = {
+          orgId: 'urn:EXAMPLE:org',
+          cachedAt: Date.now() - (24 * 60 * 60 * 1000 + 1000), // past TTL
+          preauth: {serviceLinks: {}, hostCatalog: {}},
+          postauth: {serviceLinks: {}, hostCatalog: {}},
+        };
+
+        window.localStorage.setItem(CATALOG_CACHE_KEY_V1, JSON.stringify(staleCached));
+
+        const warmed = await services._loadCatalogFromCache();
+
+        assert.isFalse(warmed, 'stale cache must not warm');
+        assert.isNull(
+          window.localStorage.getItem(CATALOG_CACHE_KEY_V1),
+          'expired cache must be cleared'
+        );
+        assert.isFalse(catalog.status.preauth.ready);
+        assert.isFalse(catalog.status.postauth.ready);
+      });
+
+      it('clearCatalogCache() removes the cached entry', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        window.localStorage.setItem(CATALOG_CACHE_KEY_V1, JSON.stringify({cachedAt: Date.now()}));
+
+        await services.clearCatalogCache();
+
+        assert.isNull(window.localStorage.getItem(CATALOG_CACHE_KEY_V1), 'cache should be cleared');
+      });
+
+      it('still fetches when forceRefresh=true even if ready', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        window.localStorage.setItem(
+          CATALOG_CACHE_KEY_V1,
+          JSON.stringify({
+            orgId: 'urn:EXAMPLE:org',
+            cachedAt: Date.now(),
+            preauth: {serviceLinks: {}, hostCatalog: {}},
+            postauth: {serviceLinks: {}, hostCatalog: {}},
+          })
+        );
+
+        // warm from cache
+        const warmed = await services._loadCatalogFromCache();
+        assert.isTrue(warmed);
+        assert.isTrue(catalog.status.preauth.ready);
+        assert.isTrue(catalog.status.postauth.ready);
+
+        const fetchSpy = sinon.spy(services, '_fetchNewServiceHostmap');
+
+        // with forceRefresh we should fetch despite ready=true
+        await services.updateServices({
+          from: 'limited',
+          query: {orgId: 'urn:EXAMPLE:org'},
+          forceRefresh: true,
+        });
+        // pass an empty query to avoid spreading undefined in qs construction
+        await services.updateServices({forceRefresh: true});
+
+        assert.isTrue(fetchSpy.called, 'forceRefresh should bypass cache short-circuit');
+        fetchSpy.restore();
+      });
+
+      it('stores selection metadata and env on cache write for preauth', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        // arrange config for env fingerprint
+        services.webex.config = services.webex.config || {};
+        services.webex.config.services = services.webex.config.services || {discovery: {}};
+        services.webex.config.services.discovery.u2c = 'https://u2c.wbx2.com/u2c/api/v1';
+        services.webex.config.fedramp = false;
+
+        // write cache with meta
+        await services._cacheCatalog(
+          'preauth',
+          {serviceLinks: {}, hostCatalog: {}},
+          {selectionType: 'orgId', selectionValue: 'urn:EXAMPLE:org'}
+        );
+
+        const raw = window.localStorage.getItem(CATALOG_CACHE_KEY_V1);
+        assert.isString(raw);
+        const parsed = JSON.parse(raw);
+        assert.equal(parsed.orgId, undefined, 'orgId not set without credentials');
+        assert.deepEqual(parsed.env, {
+          fedramp: false,
+          u2cDiscoveryUrl: 'https://u2c.wbx2.com/u2c/api/v1',
+        });
+        assert.isObject(parsed.preauth);
+        assert.deepEqual(parsed.preauth.meta, {
+          selectionType: 'orgId',
+          selectionValue: 'urn:EXAMPLE:org',
+        });
+      });
+
+      it('warms preauth from cache when selection meta matches intended orgId', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        // stub credentials
+        services.webex.credentials = {
+          canAuthorize: true,
+          getOrgId: sinon.stub().returns('urn:EXAMPLE:org'),
+        };
+        // set current env to match cached env
+        services.webex.config = services.webex.config || {};
+        services.webex.config.services = services.webex.config.services || {discovery: {}};
+        services.webex.config.services.discovery.u2c = 'https://u2c.wbx2.com/u2c/api/v1';
+        services.webex.config.fedramp = false;
+        // cache with matching orgId selection
+        window.localStorage.setItem(
+          CATALOG_CACHE_KEY_V1,
+          JSON.stringify({
+            cachedAt: Date.now(),
+            env: {fedramp: false, u2cDiscoveryUrl: 'https://u2c.wbx2.com/u2c/api/v1'},
+            preauth: {
+              hostMap: {serviceLinks: {}, hostCatalog: {}},
+              meta: {selectionType: 'orgId', selectionValue: 'urn:EXAMPLE:org'},
+            },
+          })
+        );
+        // formatter returns at least one entry to mark ready
+        services._formatReceivedHostmap.restore && services._formatReceivedHostmap.restore();
+        sinon
+          .stub(services, '_formatReceivedHostmap')
+          .callsFake(() => [
+            {name: 'hydra', defaultUrl: 'https://api.ciscospark.com/v1', hosts: []},
+          ]);
+
+        const warmed = await services._loadCatalogFromCache();
+        assert.isTrue(warmed);
+        assert.isTrue(catalog.status.preauth.ready, 'preauth should be warmed on match');
+      });
+
+      it('does not warm preauth when selection meta is proximity mode', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        // cache with proximity mode selection
+        window.localStorage.setItem(
+          CATALOG_CACHE_KEY_V1,
+          JSON.stringify({
+            cachedAt: Date.now(),
+            env: {fedramp: false, u2cDiscoveryUrl: 'https://u2c.wbx2.com/u2c/api/v1'},
+            preauth: {
+              hostMap: {serviceLinks: {}, hostCatalog: {}},
+              meta: {selectionType: 'mode', selectionValue: 'DEFAULT_BY_PROXIMITY'},
+            },
+          })
+        );
+        services._formatReceivedHostmap.restore && services._formatReceivedHostmap.restore();
+        sinon
+          .stub(services, '_formatReceivedHostmap')
+          .callsFake(() => [
+            {name: 'hydra', defaultUrl: 'https://api.ciscospark.com/v1', hosts: []},
+          ]);
+
+        const warmed = await services._loadCatalogFromCache();
+        // function returns true if overall cache path succeeded; we only verify group readiness
+        assert.isFalse(catalog.status.preauth.ready, 'preauth should not warm for proximity mode');
+      });
+
+      it('does not warm preauth when selection meta mismatches intended selection', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        // authorized with org X
+        services.webex.credentials = {
+          canAuthorize: true,
+          getOrgId: sinon.stub().returns('urn:EXAMPLE:org'),
+        };
+        // cache points to a different org
+        window.localStorage.setItem(
+          CATALOG_CACHE_KEY_V1,
+          JSON.stringify({
+            cachedAt: Date.now(),
+            env: {fedramp: false, u2cDiscoveryUrl: 'https://u2c.wbx2.com/u2c/api/v1'},
+            preauth: {
+              hostMap: {serviceLinks: {}, hostCatalog: {}},
+              meta: {selectionType: 'orgId', selectionValue: 'urn:DIFF:org'},
+            },
+          })
+        );
+        services._formatReceivedHostmap.restore && services._formatReceivedHostmap.restore();
+        sinon
+          .stub(services, '_formatReceivedHostmap')
+          .callsFake(() => [
+            {name: 'hydra', defaultUrl: 'https://api.ciscospark.com/v1', hosts: []},
+          ]);
+
+        await services._loadCatalogFromCache();
+        assert.isFalse(
+          catalog.status.preauth.ready,
+          'preauth should not warm on selection mismatch'
+        );
+      });
+
+      it('skips warming when environment fingerprint mismatches', async () => {
+        const CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+        // cached env differs from current env (different U2C URL)
+        window.localStorage.setItem(
+          CATALOG_CACHE_KEY_V1,
+          JSON.stringify({
+            cachedAt: Date.now(),
+            env: {fedramp: false, u2cDiscoveryUrl: 'https://u2c.other.com/u2c/api/v1'},
+            preauth: {
+              hostMap: {serviceLinks: {}, hostCatalog: {}},
+              meta: {selectionType: 'mode', selectionValue: 'DEFAULT_BY_PROXIMITY'},
+            },
+          })
+        );
+        // current env
+        services.webex.config = services.webex.config || {};
+        services.webex.config.services = services.webex.config.services || {discovery: {}};
+        services.webex.config.services.discovery.u2c = 'https://u2c.wbx2.com/u2c/api/v1';
+        services.webex.config.fedramp = false;
+
+        const warmed = await services._loadCatalogFromCache();
+        assert.isFalse(warmed, 'env mismatch should skip warm and return false');
+        assert.isFalse(catalog.status.preauth.ready);
+        assert.isFalse(catalog.status.postauth.ready);
+      });
+    });
   });
 });
 /* eslint-enable no-underscore-dangle */