@mp-consulting/homebridge-daikin-cloud 1.5.2 → 1.6.1

package/homebridge-ui/server.js

@@ -1,10 +1,10 @@
-const { HomebridgePluginUiServer } = require('@homebridge/plugin-ui-utils');
 const { resolve, join } = require('path');
 const fs = require('fs');
 const https = require('https');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
 const os = require('os');
+const net = require('net');
 
 // Import from compiled src/api modules (single source of truth)
 // Use path relative to this file, not cwd
@@ -13,6 +13,15 @@ const { DaikinOAuth } = require(join(distPath, 'daikin-oauth'));
 const { DaikinMobileOAuth } = require(join(distPath, 'daikin-mobile-oauth'));
 const { DaikinApi } = require(join(distPath, 'daikin-api'));
 const { configureHttpTransport } = require(join(distPath, 'http-transport'));
+const { loadTokenFromFile, saveTokenToFile, deleteTokenFile } = require(join(distPath, 'token-storage'));
+const {
+  TOKEN_FILES,
+  DEFAULT_CALLBACK_PORT,
+  DEFAULT_CALLBACK_BIND_ADDR,
+  PENDING_AUTH_TTL_MS,
+  RATE_LIMIT_STATUS_FILE,
+} = require(join(__dirname, '..', 'dist', 'src', 'constants'));
+const { validateConfig } = require(join(__dirname, '..', 'dist', 'src', 'config', 'config-manager'));
 
 // =============================================================================
 // Configuration
@@ -20,6 +29,63 @@ const { configureHttpTransport } = require(join(distPath, 'http-transport'));
 
 const CLIMATE_CONTROL_IDS = ['climateControl', 'climateControlMainZone', 'climateControlSecondaryZone'];
 
+/** How long a /devices/list result is reused before calling the Daikin API again */
+const DEVICES_CACHE_TTL_MS = 5 * 60 * 1000;
+
+/** Security headers for the OAuth callback page */
+const CALLBACK_RESPONSE_HEADERS = {
+  'Content-Type': 'text/html; charset=utf-8',
+  'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'",
+  'X-Content-Type-Options': 'nosniff',
+};
+
+// =============================================================================
+// Network Helpers
+// =============================================================================
+
+const NetUtils = {
+  /**
+   * Return the bind address if it is a valid IPv4/IPv6 literal, otherwise the default.
+   */
+  resolveBindAddress(bindAddr) {
+    const value = typeof bindAddr === 'string' ? bindAddr.trim() : '';
+    return value && net.isIP(value) !== 0 ? value : DEFAULT_CALLBACK_BIND_ADDR;
+  },
+
+  /**
+   * True for loopback hosts: 127.0.0.0/8, ::1, IPv4-mapped loopback and "localhost".
+   */
+  isLoopback(host) {
+    if (!host || typeof host !== 'string') {
+      return false;
+    }
+    const value = host.trim().toLowerCase().replace(/^\[|\]$/g, '');
+    if (value === 'localhost' || value.endsWith('.localhost')) {
+      return true;
+    }
+    if (net.isIPv4(value)) {
+      return value.startsWith('127.');
+    }
+    if (net.isIPv6(value)) {
+      return value === '::1' || /^::ffff:127\./.test(value);
+    }
+    return false;
+  },
+};
+
+// =============================================================================
+// HTML Helpers
+// =============================================================================
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
 // =============================================================================
 // SSL Certificate Utilities
 // =============================================================================
@@ -95,30 +161,10 @@ const SSLUtils = {
 // =============================================================================
 
 const TokenManager = {
-  load(filePath) {
-    try {
-      if (fs.existsSync(filePath)) {
-        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-      }
-    } catch (error) {
-      console.error('Error loading token set:', error.message);
-    }
-    return null;
-  },
-
-  save(filePath, tokenSet) {
-    fs.writeFileSync(filePath, JSON.stringify(tokenSet, null, 2), { encoding: 'utf8', mode: 0o600 });
-  },
-
-  delete(filePath) {
-    try {
-      fs.unlinkSync(filePath);
-    } catch (error) {
-      if (error.code !== 'ENOENT') {
-        throw error;
-      }
-    }
-  },
+  // File access is shared with the plugin (Zod-validated reads, 0600 writes)
+  load: (filePath) => loadTokenFromFile(filePath),
+  save: (filePath, tokenSet) => saveTokenToFile(filePath, tokenSet),
+  delete: (filePath) => deleteTokenFile(filePath),
 
   getStatus(tokenSet) {
     if (!tokenSet || !tokenSet.access_token) {
@@ -273,11 +319,24 @@ class CallbackServer {
     this.server = null;
     this.port = null;
     this.connections = new Set();
+    this.ttlTimer = null;
   }
 
-  async start(port, hostname, certDir, requestHandler) {
+  /**
+   * Start the HTTPS callback server.
+   * @param {object} options
+   * @param {number} options.port - Port to listen on
+   * @param {string} options.hostname - External hostname/IP used for the certificate
+   * @param {string} [options.bindAddr] - Interface to bind (validated IP literal)
+   * @param {string} options.certDir - Directory for the self-signed certificate
+   * @param {Function} options.requestHandler - HTTPS request handler
+   * @param {number} [options.ttlMs] - Auto-stop delay (defaults to the pending auth lifetime)
+   */
+  async start({ port, hostname, bindAddr, certDir, requestHandler, ttlMs = PENDING_AUTH_TTL_MS }) {
     await this.stop();
 
+    const host = NetUtils.resolveBindAddress(bindAddr);
+
     return new Promise((resolve, reject) => {
       const tryStart = (attempt = 1) => {
         try {
@@ -296,14 +355,16 @@ class CallbackServer {
               setTimeout(() => tryStart(attempt + 1), 1000);
             } else {
               console.error('Callback server error:', err.message);
+              this.server = null;
               reject(err);
             }
           });
 
-          this.server.listen(port, '0.0.0.0', () => {
-            console.log(`HTTPS callback server listening on port ${port}`);
+          this.server.listen(port, host, () => {
+            console.log(`HTTPS callback server listening on ${host}:${port}`);
             this.port = port;
-            resolve({ success: true, port });
+            this.scheduleAutoStop(ttlMs);
+            resolve({ success: true, port, host });
           });
         } catch (error) {
           reject(error);
@@ -314,7 +375,28 @@ class CallbackServer {
     });
   }
 
+  scheduleAutoStop(ttlMs) {
+    this.clearAutoStop();
+    this.ttlTimer = setTimeout(() => {
+      this.ttlTimer = null;
+      console.log('[DaikinCloud] Authorization window expired, stopping callback server');
+      this.stop().catch(() => {});
+    }, ttlMs);
+    if (typeof this.ttlTimer.unref === 'function') {
+      this.ttlTimer.unref();
+    }
+  }
+
+  clearAutoStop() {
+    if (this.ttlTimer) {
+      clearTimeout(this.ttlTimer);
+      this.ttlTimer = null;
+    }
+  }
+
   async stop() {
+    this.clearAutoStop();
+
     return new Promise((resolve) => {
       if (!this.server) {
         resolve({ success: true });
@@ -409,7 +491,7 @@ const HtmlTemplates = {
     <div class="container">
         <div class="icon">${icon}</div>
         <h1>${success ? 'Success!' : 'Error'}</h1>
-        <p class="message">${message}</p>
+        <p class="message">${escapeHtml(message)}</p>
         <p class="hint">You can close this window and return to Homebridge.</p>
     </div>
 </body>
@@ -421,544 +503,696 @@ const HtmlTemplates = {
 // Main Server Class
 // =============================================================================
 
-class DaikinCloudUiServer extends HomebridgePluginUiServer {
-  constructor() {
-    super();
+/**
+ * Build the UI server class on top of HomebridgePluginUiServer. The base is
+ * passed in because @homebridge/plugin-ui-utils is ESM-only: require() loads it
+ * on Node >= 20.19 / 22.12, older runtimes need import() (see loadUiUtils).
+ */
+function createDaikinCloudUiServer(HomebridgePluginUiServer) {
+  return class DaikinCloudUiServer extends HomebridgePluginUiServer {
+    constructor() {
+      super();
+
+      this.pendingAuth = null;
+      this.authResult = null;
+      this.callbackServer = new CallbackServer();
+      this.devicesCache = new Map();
 
-    this.pendingAuth = null;
-    this.authResult = null;
-    this.callbackServer = new CallbackServer();
+      this.applyTransportFromConfig();
+      this.registerHandlers();
+      this.ready();
+    }
 
-    this.applyTransportFromConfig();
-    this.registerHandlers();
-    this.ready();
-  }
+    getStoragePath() {
+      return this.homebridgeStoragePath || process.env.UIX_STORAGE_PATH || '';
+    }
 
-  /**
+    /**
+   * Read the DaikinCloud platform block from the Homebridge config.json.
+   * Throws if the config file cannot be read or parsed.
+   */
+    readPlatformConfig() {
+      const configPath = this.homebridgeConfigPath || resolve(this.getStoragePath(), 'config.json');
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      return (config.platforms || []).find((p) => p.platform === 'DaikinCloud') || null;
+    }
+
+    /**
    * Honour the plugin's httpTransport setting in the setup wizard too, so a
    * network that blocks Node's TLS fingerprint (issue #6) can still complete
    * authentication from the UI. Env var DAIKIN_HTTP_TRANSPORT wins.
    */
-  applyTransportFromConfig() {
-    try {
-      const configPath = resolve(this.homebridgeStoragePath || process.env.UIX_STORAGE_PATH || '', 'config.json');
-      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-      const platform = (config.platforms || []).find((p) => p.platform === 'DaikinCloud');
-      configureHttpTransport(platform && platform.httpTransport);
-    } catch (e) {
-      console.log('[DaikinCloud] Could not read httpTransport from config, using default:', e.message);
+    applyTransportFromConfig() {
+      try {
+        const platform = this.readPlatformConfig();
+        configureHttpTransport(platform && platform.httpTransport);
+      } catch (e) {
+        console.log('[DaikinCloud] Could not read httpTransport from config, using default:', e.message);
+      }
     }
-  }
 
-  getTokenFilePath() {
-    return resolve(this.homebridgeStoragePath || process.env.UIX_STORAGE_PATH || '', '.daikin-controller-cloud-tokenset');
-  }
+    /**
+   * Resolve the callback server bind address from the request payload, then the
+   * saved platform config, falling back to DEFAULT_CALLBACK_BIND_ADDR when the
+   * value is missing or not an IPv4/IPv6 literal.
+   */
+    getCallbackBindAddress(payload) {
+      let configured = payload?.oidcCallbackServerBindAddr;
+      if (configured === undefined || configured === null || configured === '') {
+        try {
+          configured = this.readPlatformConfig()?.oidcCallbackServerBindAddr;
+        } catch (e) {
+          configured = undefined;
+        }
+      }
 
-  getMobileTokenFilePath() {
-    return resolve(this.homebridgeStoragePath || process.env.UIX_STORAGE_PATH || '', '.daikin-mobile-tokenset');
-  }
+      const bindAddr = NetUtils.resolveBindAddress(configured);
+      if (configured && bindAddr !== String(configured).trim()) {
+        console.warn(`[DaikinCloud] Invalid callback bind address "${configured}", using ${bindAddr}`);
+      }
+      return bindAddr;
+    }
 
-  getCertDir() {
-    return resolve(this.homebridgeStoragePath || process.env.UIX_STORAGE_PATH || '', 'daikin-cloud-certs');
-  }
+    getTokenFilePath() {
+      return resolve(this.getStoragePath(), TOKEN_FILES.developer_portal);
+    }
 
-  getActiveTokenSet() {
-    // Check mobile token first (takes precedence)
-    const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
-    if (mobileTokenSet?.access_token) {
-      return mobileTokenSet;
+    getMobileTokenFilePath() {
+      return resolve(this.getStoragePath(), TOKEN_FILES.mobile_app);
     }
-    // Fall back to developer portal token
-    return TokenManager.load(this.getTokenFilePath());
-  }
 
-  registerHandlers() {
-    this.onRequest('/auth/status', this.handleGetAuthStatus.bind(this));
-    this.onRequest('/auth/start', this.handleStartAuth.bind(this));
-    this.onRequest('/auth/', this.handleCallback.bind(this));
-    this.onRequest('/auth/revoke', this.handleRevokeAuth.bind(this));
-    this.onRequest('/auth/test', this.handleTestConnection.bind(this));
-    this.onRequest('/auth/poll', this.handlePollAuthResult.bind(this));
-    this.onRequest('/auth/stop-server', this.handleStopServer.bind(this));
-    this.onRequest('/auth/mobile-test', this.handleMobileAuthTest.bind(this));
-    this.onRequest('/config/validate', this.handleValidateConfig.bind(this));
-    this.onRequest('/devices/list', this.handleListDevices.bind(this));
-    this.onRequest('/api/rate-limit', this.handleGetRateLimit.bind(this));
-    this.onRequest('/server/info', this.handleGetServerInfo.bind(this));
-  }
+    getCertDir() {
+      return resolve(this.getStoragePath(), 'daikin-cloud-certs');
+    }
 
-  // -------------------------------------------------------------------------
-  // Server Info Handler
-  // -------------------------------------------------------------------------
+    getRateLimitFilePath() {
+      return resolve(this.getStoragePath(), RATE_LIMIT_STATUS_FILE);
+    }
 
-  async handleGetServerInfo() {
-    const ipAddresses = this.getServerIpAddresses();
-    return {
-      ipAddresses,
-      primaryIp: ipAddresses[0] || null,
-      hostname: os.hostname(),
-    };
-  }
+    /**
+   * Active token set and the auth mode it belongs to (mobile takes precedence).
+   */
+    getActiveToken() {
+      const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
+      if (mobileTokenSet?.access_token) {
+        return { tokenSet: mobileTokenSet, mode: 'mobile_app' };
+      }
+      return { tokenSet: TokenManager.load(this.getTokenFilePath()), mode: 'developer_portal' };
+    }
 
-  getServerIpAddresses() {
-    const interfaces = os.networkInterfaces();
-    const addresses = [];
+    getActiveTokenSet() {
+      return this.getActiveToken().tokenSet;
+    }
 
-    for (const nets of Object.values(interfaces)) {
-      if (!nets) {
-        continue;
+    /**
+   * Token set for the requested mode, falling back to the active token set.
+   */
+    resolveToken(mode) {
+      let tokenSet = null;
+      if (mode === 'mobile_app') {
+        tokenSet = TokenManager.load(this.getMobileTokenFilePath());
+      } else if (mode === 'developer_portal') {
+        tokenSet = TokenManager.load(this.getTokenFilePath());
       }
-      for (const net of nets) {
-        // Skip internal and non-IPv4 addresses
-        if (net.internal || net.family !== 'IPv4') {
-          continue;
-        }
-        addresses.push(net.address);
+
+      if (tokenSet?.access_token) {
+        return { tokenSet, mode };
       }
+      return this.getActiveToken();
     }
 
-    return addresses;
-  }
+    invalidateDevicesCache() {
+      this.devicesCache.clear();
+    }
 
-  // -------------------------------------------------------------------------
-  // Auth Status Handler
-  // -------------------------------------------------------------------------
+    isPendingAuthExpired() {
+      return !!this.pendingAuth && Date.now() - this.pendingAuth.createdAt > PENDING_AUTH_TTL_MS;
+    }
 
-  async handleGetAuthStatus() {
-    try {
-      // Check both token files - mobile takes precedence if exists
-      const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
-      const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
+    registerHandlers() {
+      this.onRequest('/auth/status', this.handleGetAuthStatus.bind(this));
+      this.onRequest('/auth/start', this.handleStartAuth.bind(this));
+      this.onRequest('/auth/', this.handleCallback.bind(this));
+      this.onRequest('/auth/revoke', this.handleRevokeAuth.bind(this));
+      this.onRequest('/auth/test', this.handleTestConnection.bind(this));
+      this.onRequest('/auth/poll', this.handlePollAuthResult.bind(this));
+      this.onRequest('/auth/stop-server', this.handleStopServer.bind(this));
+      this.onRequest('/auth/mobile-test', this.handleMobileAuthTest.bind(this));
+      this.onRequest('/config/validate', this.handleValidateConfig.bind(this));
+      this.onRequest('/devices/list', this.handleListDevices.bind(this));
+      this.onRequest('/api/rate-limit', this.handleGetRateLimit.bind(this));
+      this.onRequest('/server/info', this.handleGetServerInfo.bind(this));
+    }
 
-      if (mobileTokenSet?.access_token) {
-        const status = TokenManager.getStatus(mobileTokenSet);
-        status.authMode = 'mobile_app';
-        return status;
-      }
+    // -------------------------------------------------------------------------
+    // Server Info Handler
+    // -------------------------------------------------------------------------
+
+    async handleGetServerInfo() {
+      const ipAddresses = this.getServerIpAddresses();
+      return {
+        ipAddresses,
+        primaryIp: ipAddresses[0] || null,
+        hostname: os.hostname(),
+      };
+    }
+
+    getServerIpAddresses() {
+      const interfaces = os.networkInterfaces();
+      const addresses = [];
 
-      if (devPortalTokenSet?.access_token) {
-        const status = TokenManager.getStatus(devPortalTokenSet);
-        status.authMode = 'developer_portal';
-        return status;
+      for (const nets of Object.values(interfaces)) {
+        if (!nets) {
+          continue;
+        }
+        for (const net of nets) {
+        // Skip internal and non-IPv4 addresses
+          if (net.internal || net.family !== 'IPv4') {
+            continue;
+          }
+          addresses.push(net.address);
+        }
       }
 
-      return { authenticated: false, message: 'Not authenticated' };
-    } catch (error) {
-      return { authenticated: false, error: error.message, message: 'Error reading token status' };
+      return addresses;
     }
-  }
 
-  // -------------------------------------------------------------------------
-  // Start Auth Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Auth Status Handler
+    // -------------------------------------------------------------------------
 
-  async handleStartAuth(payload) {
-    const { clientId, clientSecret, callbackServerExternalAddress, callbackServerPort } = payload;
+    async handleGetAuthStatus() {
+      try {
+      // Check both token files - mobile takes precedence if exists
+        const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
+        const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
 
-    if (!clientId || !clientSecret) {
-      throw new Error('Client ID and Client Secret are required');
-    }
-    if (!callbackServerExternalAddress) {
-      throw new Error('Callback Server Address is required');
+        if (mobileTokenSet?.access_token) {
+          const status = TokenManager.getStatus(mobileTokenSet);
+          status.authMode = 'mobile_app';
+          return status;
+        }
+
+        if (devPortalTokenSet?.access_token) {
+          const status = TokenManager.getStatus(devPortalTokenSet);
+          status.authMode = 'developer_portal';
+          return status;
+        }
+
+        return { authenticated: false, message: 'Not authenticated' };
+      } catch (error) {
+        return { authenticated: false, error: error.message, message: 'Error reading token status' };
+      }
     }
 
-    const port = parseInt(callbackServerPort || '8582', 10);
-    const redirectUri = `https://${callbackServerExternalAddress}:${port}`;
-    const state = crypto.randomBytes(32).toString('hex');
+    // -------------------------------------------------------------------------
+    // Start Auth Handler
+    // -------------------------------------------------------------------------
 
-    this.pendingAuth = { state, clientId, clientSecret, redirectUri, port, createdAt: Date.now() };
-    this.authResult = null;
+    async handleStartAuth(payload) {
+      const { clientId, clientSecret, callbackServerExternalAddress, callbackServerPort } = payload;
 
-    // Use static method from compiled src/api
-    const authUrl = DaikinOAuth.buildAuthUrlStatic(clientId, redirectUri, state);
-    console.log('[DaikinCloud] Generated auth URL:', authUrl);
-    console.log('[DaikinCloud] Redirect URI:', redirectUri);
+      if (!clientId || !clientSecret) {
+        throw new Error('Client ID and Client Secret are required');
+      }
+      if (!callbackServerExternalAddress) {
+        throw new Error('Callback Server Address is required');
+      }
 
-    // Try to start callback server for automatic code capture
-    let callbackServerRunning = false;
-    let callbackServerError = null;
+      const bindAddr = this.getCallbackBindAddress(payload);
+      if (NetUtils.isLoopback(bindAddr) && !NetUtils.isLoopback(callbackServerExternalAddress)) {
+      // The browser is redirected to the external address, which can never reach a loopback-only server
+        throw new Error(
+          `The callback server bind address is ${bindAddr} (this machine only), but the callback address is ` +
+        `${callbackServerExternalAddress}, so Daikin's redirect could never reach it. Set "Callback Server Bind Address" ` +
+        'to 0.0.0.0 (or this host\'s LAN IP) in Settings > Network, then start authentication again.',
+        );
+      }
 
-    try {
-      await this.callbackServer.start(
-        port,
-        callbackServerExternalAddress,
-        this.getCertDir(),
-        this.handleHttpsCallback.bind(this),
-      );
-      callbackServerRunning = true;
-      console.log('[DaikinCloud] Callback server started successfully');
-    } catch (error) {
-      callbackServerError = error.message;
-      console.warn('[DaikinCloud] Failed to start callback server:', error.message);
-    }
+      const port = parseInt(callbackServerPort || String(DEFAULT_CALLBACK_PORT), 10);
+      const redirectUri = `https://${callbackServerExternalAddress}:${port}`;
+      const state = crypto.randomBytes(32).toString('hex');
 
-    return {
-      authUrl,
-      state,
-      redirectUri,
-      callbackServerRunning,
-      callbackServerError,
-      message: callbackServerRunning
-        ? 'Callback server is running. Authentication will complete automatically.'
-        : 'Could not start callback server. After authenticating, copy the full callback URL and paste it below.',
-    };
-  }
+      this.pendingAuth = { state, clientId, clientSecret, redirectUri, port, createdAt: Date.now() };
+      this.authResult = null;
+      this.invalidateDevicesCache();
 
-  // -------------------------------------------------------------------------
-  // HTTPS Callback Handler
-  // -------------------------------------------------------------------------
+      // Use static method from compiled src/api
+      const authUrl = DaikinOAuth.buildAuthUrlStatic(clientId, redirectUri, state);
+      console.log('[DaikinCloud] Redirect URI:', redirectUri);
 
-  handleHttpsCallback(req, res) {
-    const url = new URL(req.url, `https://${req.headers.host}`);
+      // Try to start callback server for automatic code capture
+      let callbackServerRunning = false;
+      let callbackServerError = null;
 
-    const code = url.searchParams.get('code');
-    const state = url.searchParams.get('state');
-    const error = url.searchParams.get('error');
-    const errorDescription = url.searchParams.get('error_description');
+      try {
+        await this.callbackServer.start({
+          port,
+          hostname: callbackServerExternalAddress,
+          bindAddr,
+          certDir: this.getCertDir(),
+          requestHandler: this.handleHttpsCallback.bind(this),
+        });
+        callbackServerRunning = true;
+        console.log('[DaikinCloud] Callback server started successfully');
+      } catch (error) {
+        callbackServerError = error.message;
+        console.warn('[DaikinCloud] Failed to start callback server:', error.message);
+      }
 
-    if (error) {
-      this.authResult = { success: false, error: errorDescription || error };
-      this.sendCallbackResponse(res, false, errorDescription || error);
-      return;
+      return {
+        authUrl,
+        state,
+        redirectUri,
+        callbackServerRunning,
+        callbackServerError,
+        message: callbackServerRunning
+          ? 'Callback server is running. Authentication will complete automatically.'
+          : 'Could not start callback server. After authenticating, copy the full callback URL and paste it below.',
+      };
     }
 
-    if (!code || !state) {
-      this.authResult = { success: false, error: 'Missing code or state parameter' };
-      this.sendCallbackResponse(res, false, 'Missing authorization code');
-      return;
-    }
+    // -------------------------------------------------------------------------
+    // HTTPS Callback Handler
+    // -------------------------------------------------------------------------
 
-    if (!this.pendingAuth || state !== this.pendingAuth.state) {
-      this.authResult = { success: false, error: 'Invalid state parameter' };
-      this.sendCallbackResponse(res, false, 'Invalid state parameter');
-      return;
-    }
+    handleHttpsCallback(req, res) {
+      let url;
+      try {
+        url = new URL(req.url, 'https://localhost');
+      } catch (e) {
+        this.sendCallbackResponse(res, false, 'Invalid request', 400);
+        return;
+      }
 
-    const { clientId, clientSecret, redirectUri } = this.pendingAuth;
+      const code = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+      const error = url.searchParams.get('error');
+      const errorDescription = url.searchParams.get('error_description');
 
-    // Use static method from compiled src/api
-    DaikinOAuth.exchangeCodeStatic(code, clientId, clientSecret, redirectUri)
-      .then((tokenSet) => {
-        TokenManager.save(this.getTokenFilePath(), tokenSet);
-        this.authResult = {
-          success: true,
-          message: 'Authentication successful!',
-          expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
-        };
+      // Requests that do not carry the pending state are not ours: reject them
+      // without touching authResult so they cannot disrupt a running login.
+      if (!this.pendingAuth || !state || state !== this.pendingAuth.state) {
+        this.sendCallbackResponse(res, false, 'Invalid or missing state parameter', 400);
+        return;
+      }
+
+      if (this.isPendingAuthExpired()) {
         this.pendingAuth = null;
-        this.sendCallbackResponse(res, true, 'Authentication successful! You can close this window.');
+        this.authResult = { success: false, error: 'Authorization request expired. Please try again.' };
+        this.sendCallbackResponse(res, false, 'Authorization request expired. Please start again from Homebridge.', 400);
         this.callbackServer.stop().catch(() => {});
-      })
-      .catch((err) => {
-        this.authResult = { success: false, error: err.message };
-        this.sendCallbackResponse(res, false, `Token exchange failed: ${err.message}`);
-      });
-  }
+        return;
+      }
 
-  sendCallbackResponse(res, success, message) {
-    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-    res.end(HtmlTemplates.callbackResponse(success, message));
-  }
+      if (error) {
+        this.authResult = { success: false, error: errorDescription || error };
+        this.sendCallbackResponse(res, false, errorDescription || error);
+        return;
+      }
 
-  // -------------------------------------------------------------------------
-  // Manual Callback Handler
-  // -------------------------------------------------------------------------
+      if (!code) {
+        this.authResult = { success: false, error: 'Missing code parameter' };
+        this.sendCallbackResponse(res, false, 'Missing authorization code', 400);
+        return;
+      }
 
-  async handleCallback(payload) {
-    let { code, state, callbackUrl } = payload;
+      const { clientId, clientSecret, redirectUri } = this.pendingAuth;
 
-    if (callbackUrl) {
-      try {
-        const url = new URL(callbackUrl);
-        code = url.searchParams.get('code');
-        state = url.searchParams.get('state');
-      } catch (e) {
-        throw new Error('Invalid callback URL format', { cause: e });
-      }
+      // Use static method from compiled src/api
+      return DaikinOAuth.exchangeCodeStatic(code, clientId, clientSecret, redirectUri)
+        .then((tokenSet) => {
+          TokenManager.save(this.getTokenFilePath(), tokenSet);
+          this.invalidateDevicesCache();
+          this.authResult = {
+            success: true,
+            message: 'Authentication successful!',
+            expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
+          };
+          this.pendingAuth = null;
+          this.sendCallbackResponse(res, true, 'Authentication successful! You can close this window.');
+          this.callbackServer.stop().catch(() => {});
+        })
+        .catch((err) => {
+          this.authResult = { success: false, error: err.message };
+          this.sendCallbackResponse(res, false, `Token exchange failed: ${err.message}`);
+        });
     }
 
-    if (!code) {
-      throw new Error('Authorization code is required');
-    }
-    if (!this.pendingAuth) {
-      throw new Error('No pending authorization. Please start the auth flow again.');
-    }
-    if (state && state !== this.pendingAuth.state) {
-      throw new Error('Invalid state parameter. Please try again.');
-    }
-    if (Date.now() - this.pendingAuth.createdAt > 10 * 60 * 1000) {
-      this.pendingAuth = null;
-      throw new Error('Authorization request expired. Please try again.');
+    sendCallbackResponse(res, success, message, statusCode = 200) {
+      res.writeHead(statusCode, CALLBACK_RESPONSE_HEADERS);
+      res.end(HtmlTemplates.callbackResponse(success, message));
     }
 
-    const { clientId, clientSecret, redirectUri } = this.pendingAuth;
+    // -------------------------------------------------------------------------
+    // Manual Callback Handler
+    // -------------------------------------------------------------------------
 
-    try {
-      // Use static method from compiled src/api
-      const tokenSet = await DaikinOAuth.exchangeCodeStatic(code, clientId, clientSecret, redirectUri);
-      TokenManager.save(this.getTokenFilePath(), tokenSet);
-      this.pendingAuth = null;
+    async handleCallback(payload) {
+      let { code, state, callbackUrl } = payload;
 
-      await this.callbackServer.stop();
+      if (callbackUrl) {
+        try {
+          const url = new URL(callbackUrl);
+          code = url.searchParams.get('code');
+          state = url.searchParams.get('state');
+        } catch (e) {
+          throw new Error('Invalid callback URL format', { cause: e });
+        }
+      }
 
-      return {
-        success: true,
-        message: 'Authentication successful! Restart Homebridge to apply.',
-        expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
-      };
-    } catch (error) {
-      throw new Error(`Token exchange failed: ${error.message}`, { cause: error });
-    }
-  }
+      if (!code) {
+        throw new Error('Authorization code is required');
+      }
+      if (!this.pendingAuth) {
+        throw new Error('No pending authorization. Please start the auth flow again.');
+      }
+      if (!state || state !== this.pendingAuth.state) {
+        throw new Error('Invalid or missing state parameter. Please paste the full callback URL or start again.');
+      }
+      if (this.isPendingAuthExpired()) {
+        this.pendingAuth = null;
+        throw new Error('Authorization request expired. Please try again.');
+      }
 
-  // -------------------------------------------------------------------------
-  // Poll Auth Result Handler
-  // -------------------------------------------------------------------------
+      const { clientId, clientSecret, redirectUri } = this.pendingAuth;
+
+      try {
+      // Use static method from compiled src/api
+        const tokenSet = await DaikinOAuth.exchangeCodeStatic(code, clientId, clientSecret, redirectUri);
+        TokenManager.save(this.getTokenFilePath(), tokenSet);
+        this.invalidateDevicesCache();
+        this.pendingAuth = null;
 
-  async handlePollAuthResult() {
-    if (this.authResult) {
-      const result = { ...this.authResult };
-      if (result.success) {
-        this.authResult = null;
         await this.callbackServer.stop();
-      }
-      return result;
-    }
 
-    const tokenSet = TokenManager.load(this.getTokenFilePath());
-    if (tokenSet && tokenSet.access_token) {
-      return {
-        success: true,
-        message: 'Authentication successful!',
-        expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
-      };
+        return {
+          success: true,
+          message: 'Authentication successful! Restart Homebridge to apply.',
+          expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
+        };
+      } catch (error) {
+        throw new Error(`Token exchange failed: ${error.message}`, { cause: error });
+      }
     }
-    return { pending: true };
-  }
-
-  // -------------------------------------------------------------------------
-  // Stop Server Handler
-  // -------------------------------------------------------------------------
-
-  async handleStopServer() {
-    this.pendingAuth = null;
-    this.authResult = null;
-    await this.callbackServer.stop();
-    return { success: true };
-  }
 
-  // -------------------------------------------------------------------------
-  // Mobile Auth Test Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Poll Auth Result Handler
+    // -------------------------------------------------------------------------
 
-  async handleMobileAuthTest(payload) {
-    const { email, password } = payload;
+    async handlePollAuthResult() {
+      if (this.authResult) {
+        const result = { ...this.authResult };
+        if (result.success) {
+          this.authResult = null;
+          await this.callbackServer.stop();
+        }
+        return result;
+      }
 
-    if (!email || !password) {
-      return { success: false, message: 'Email and password are required' };
+      const tokenSet = TokenManager.load(this.getTokenFilePath());
+      if (tokenSet && tokenSet.access_token) {
+        return {
+          success: true,
+          message: 'Authentication successful!',
+          expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
+        };
+      }
+      return { pending: true };
     }
 
-    const tokenFilePath = this.getMobileTokenFilePath();
+    // -------------------------------------------------------------------------
+    // Stop Server Handler
+    // -------------------------------------------------------------------------
 
-    try {
-      // Create a temporary mobile OAuth client
-      const mobileOAuth = new DaikinMobileOAuth({
-        email,
-        password,
-        tokenFilePath,
-      });
+    async handleStopServer() {
+      this.pendingAuth = null;
+      this.authResult = null;
+      await this.callbackServer.stop();
+      return { success: true };
+    }
 
-      // Perform authentication
-      console.log('[DaikinCloud] Testing mobile app authentication...');
-      const tokenSet = await mobileOAuth.authenticate();
-      console.log('[DaikinCloud] Mobile authentication successful');
+    // -------------------------------------------------------------------------
+    // Mobile Auth Test Handler
+    // -------------------------------------------------------------------------
 
-      // Test API access and get device count
-      let deviceCount = 0;
-      let rateLimit = null;
+    async handleMobileAuthTest(payload) {
+      const { email, password } = payload;
 
-      try {
-        const result = await DaikinApi.requestStatic('/v1/gateway-devices', tokenSet.access_token);
-        deviceCount = Array.isArray(result.data) ? result.data.length : 0;
-        rateLimit = result.rateLimit;
-      } catch (apiError) {
-        console.warn('[DaikinCloud] API test failed:', apiError.message);
+      if (!email || !password) {
+        return { success: false, message: 'Email and password are required' };
       }
 
-      return {
-        success: true,
-        message: 'Authentication successful!',
-        deviceCount,
-        rateLimit,
-        expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
-      };
-    } catch (error) {
-      console.error('[DaikinCloud] Mobile auth test failed:', error.message);
-      return {
-        success: false,
-        message: error.message || 'Authentication failed',
-      };
-    }
-  }
+      const tokenFilePath = this.getMobileTokenFilePath();
+      this.invalidateDevicesCache();
 
-  // -------------------------------------------------------------------------
-  // Revoke Auth Handler
-  // -------------------------------------------------------------------------
+      try {
+      // Create a temporary mobile OAuth client
+        const mobileOAuth = new DaikinMobileOAuth({
+          email,
+          password,
+          tokenFilePath,
+        });
 
-  async handleRevokeAuth(payload) {
-    const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
-    const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
+        // Perform authentication
+        console.log('[DaikinCloud] Testing mobile app authentication...');
+        const tokenSet = await mobileOAuth.authenticate();
+        console.log('[DaikinCloud] Mobile authentication successful');
 
-    if (!devPortalTokenSet && !mobileTokenSet) {
-      return { success: true, message: 'No tokens to revoke' };
-    }
+        // Test API access and get device count
+        let deviceCount = 0;
+        let rateLimit = null;
 
-    const { clientId, clientSecret } = payload;
+        try {
+          const result = await DaikinApi.requestStatic('/v1/gateway-devices', tokenSet.access_token);
+          deviceCount = Array.isArray(result.data) ? result.data.length : 0;
+          rateLimit = result.rateLimit;
+        } catch (apiError) {
+          console.warn('[DaikinCloud] API test failed:', apiError.message);
+        }
 
-    if (devPortalTokenSet?.refresh_token && clientId && clientSecret) {
-      try {
-        // Use static method from compiled src/api
-        await DaikinOAuth.revokeTokenStatic(devPortalTokenSet.refresh_token, clientId, clientSecret);
+        return {
+          success: true,
+          message: 'Authentication successful!',
+          deviceCount,
+          rateLimit,
+          expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000).toISOString() : null,
+        };
       } catch (error) {
-        console.warn('Failed to revoke token at server:', error.message);
+        console.error('[DaikinCloud] Mobile auth test failed:', error.message);
+        return {
+          success: false,
+          message: error.message || 'Authentication failed',
+        };
       }
     }
 
-    // Delete both token files
-    TokenManager.delete(this.getTokenFilePath());
-    TokenManager.delete(this.getMobileTokenFilePath());
-    return { success: true, message: 'Authentication revoked. You will need to re-authenticate.' };
-  }
+    // -------------------------------------------------------------------------
+    // Revoke Auth Handler
+    // -------------------------------------------------------------------------
 
-  // -------------------------------------------------------------------------
-  // Test Connection Handler
-  // -------------------------------------------------------------------------
+    async handleRevokeAuth(payload) {
+      this.invalidateDevicesCache();
 
-  async handleTestConnection() {
-    const tokenSet = this.getActiveTokenSet();
-    if (!tokenSet?.access_token) {
-      return { success: false, message: 'Not authenticated. Please authenticate first.' };
-    }
+      const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
+      const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
 
-    try {
-      // Use static method from compiled src/api
-      const result = await DaikinApi.requestStatic('/v1/gateway-devices', tokenSet.access_token);
-      const devices = result.data;
-      return {
-        success: true,
-        message: `Connection successful! Found ${Array.isArray(devices) ? devices.length : 0} device(s).`,
-        deviceCount: Array.isArray(devices) ? devices.length : 0,
-      };
-    } catch (error) {
-      return { success: false, message: `Connection failed: ${error.message}`, error: error.message };
-    }
-  }
+      if (!devPortalTokenSet && !mobileTokenSet) {
+        return { success: true, message: 'No tokens to revoke' };
+      }
 
-  // -------------------------------------------------------------------------
-  // List Devices Handler
-  // -------------------------------------------------------------------------
+      const { clientId, clientSecret } = payload;
 
-  async handleListDevices(payload) {
-    const mode = payload?.mode;
+      if (devPortalTokenSet?.refresh_token && clientId && clientSecret) {
+        try {
+        // Use static method from compiled src/api
+          await DaikinOAuth.revokeTokenStatic(devPortalTokenSet.refresh_token, clientId, clientSecret);
+        } catch (error) {
+          console.warn('Failed to revoke token at server:', error.message);
+        }
+      }
 
-    // Get token based on mode parameter, or fall back to active token
-    let tokenSet;
-    if (mode === 'mobile_app') {
-      tokenSet = TokenManager.load(this.getMobileTokenFilePath());
-    } else if (mode === 'developer_portal') {
-      tokenSet = TokenManager.load(this.getTokenFilePath());
-    } else {
-      tokenSet = this.getActiveTokenSet();
+      // Delete both token files
+      TokenManager.delete(this.getTokenFilePath());
+      TokenManager.delete(this.getMobileTokenFilePath());
+      return { success: true, message: 'Authentication revoked. You will need to re-authenticate.' };
     }
 
-    // If the requested mode's token doesn't exist or is invalid, fall back to active token
-    if (!tokenSet?.access_token) {
-      tokenSet = this.getActiveTokenSet();
-    }
+    // -------------------------------------------------------------------------
+    // Test Connection Handler
+    // -------------------------------------------------------------------------
 
-    if (!tokenSet?.access_token) {
-      return { success: false, devices: [], message: 'Not authenticated. Please authenticate first.' };
-    }
+    async handleTestConnection() {
+      const tokenSet = this.getActiveTokenSet();
+      if (!tokenSet?.access_token) {
+        return { success: false, message: 'Not authenticated. Please authenticate first.' };
+      }
 
-    try {
+      try {
       // Use static method from compiled src/api
-      const result = await DaikinApi.requestStatic('/v1/gateway-devices', tokenSet.access_token);
-      const gatewayDevices = result.data;
-      const devices = Array.isArray(gatewayDevices)
-        ? gatewayDevices.map(device => DeviceExtractor.extractAll(device))
-        : [];
-
-      return { success: true, devices, message: `Found ${devices.length} device(s).` };
-    } catch (error) {
-      return { success: false, devices: [], message: `Failed to fetch devices: ${error.message}`, error: error.message };
+        const result = await DaikinApi.requestStatic('/v1/gateway-devices', tokenSet.access_token);
+        const devices = result.data;
+        return {
+          success: true,
+          message: `Connection successful! Found ${Array.isArray(devices) ? devices.length : 0} device(s).`,
+          deviceCount: Array.isArray(devices) ? devices.length : 0,
+        };
+      } catch (error) {
+        return { success: false, message: `Connection failed: ${error.message}`, error: error.message };
+      }
     }
-  }
 
-  // -------------------------------------------------------------------------
-  // Get Rate Limit Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // List Devices Handler
+    // -------------------------------------------------------------------------
 
-  async handleGetRateLimit(payload) {
-    const mode = payload?.mode;
+    async handleListDevices(payload) {
+    // Token for the requested mode, or fall back to the active token
+      const { tokenSet, mode } = this.resolveToken(payload?.mode);
 
-    // Get token based on mode parameter, or fall back to active token
-    let tokenSet;
-    if (mode === 'mobile_app') {
-      tokenSet = TokenManager.load(this.getMobileTokenFilePath());
-    } else if (mode === 'developer_portal') {
-      tokenSet = TokenManager.load(this.getTokenFilePath());
-    } else {
-      tokenSet = this.getActiveTokenSet();
-    }
+      if (!tokenSet?.access_token) {
+        return { success: false, devices: [], message: 'Not authenticated. Please authenticate first.' };
+      }
 
-    if (!tokenSet?.access_token) {
-      return { success: false, message: 'Not authenticated' };
-    }
+      // Reuse a recent result to spare the daily API quota (explicit refresh bypasses it)
+      if (payload?.refresh) {
+        this.devicesCache.delete(mode);
+      }
+      const cached = this.devicesCache.get(mode);
+      if (cached && Date.now() - cached.fetchedAt < DEVICES_CACHE_TTL_MS) {
+        return { ...cached.result, cached: true, fetchedAt: new Date(cached.fetchedAt).toISOString() };
+      }
 
-    try {
+      try {
       // Use static method from compiled src/api
-      const result = await DaikinApi.requestStatic('/v1/gateway-devices', tokenSet.access_token);
-      return { success: true, rateLimit: result.rateLimit };
-    } catch (error) {
-      return { success: false, message: error.message };
+        const result = await DaikinApi.requestStatic('/v1/gateway-devices', tokenSet.access_token);
+        const gatewayDevices = result.data;
+        const devices = Array.isArray(gatewayDevices)
+          ? gatewayDevices.map(device => DeviceExtractor.extractAll(device))
+          : [];
+
+        const response = { success: true, devices, message: `Found ${devices.length} device(s).` };
+        const fetchedAt = Date.now();
+        this.devicesCache.set(mode, { result: response, fetchedAt });
+        return { ...response, cached: false, fetchedAt: new Date(fetchedAt).toISOString() };
+      } catch (error) {
+        return { success: false, devices: [], message: `Failed to fetch devices: ${error.message}`, error: error.message };
+      }
     }
-  }
 
-  // -------------------------------------------------------------------------
-  // Validate Config Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Get Rate Limit Handler
+    // -------------------------------------------------------------------------
 
-  async handleValidateConfig(payload) {
-    const errors = [];
-    const warnings = [];
-    const { clientId, clientSecret, callbackServerExternalAddress, callbackServerPort } = payload;
+    /**
+   * Report the rate limit status the running plugin records after each API
+   * response, instead of spending an API call just to read the headers.
+   */
+    async handleGetRateLimit() {
+      let status;
+      try {
+        status = JSON.parse(fs.readFileSync(this.getRateLimitFilePath(), 'utf8'));
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          return {
+            success: false,
+            noData: true,
+            message: 'No data yet — the plugin records this after its next API call.',
+          };
+        }
+        return { success: false, message: `Could not read rate limit status: ${error.message}` };
+      }
 
-    if (!clientId) {
-      errors.push('Client ID is required. Get it from the Daikin Developer Portal.');
-    }
-    if (!clientSecret) {
-      errors.push('Client Secret is required. Get it from the Daikin Developer Portal.');
-    }
+      if (!status || typeof status !== 'object') {
+        return { success: false, message: 'Could not read rate limit status: invalid file contents' };
+      }
 
-    if (!callbackServerExternalAddress) {
-      errors.push('Callback Server External Address is required.');
-    } else if (callbackServerExternalAddress === 'localhost' || callbackServerExternalAddress === '127.0.0.1') {
-      errors.push('Callback address cannot be localhost. Use your external IP or domain.');
-    }
+      const { limitMinute, remainingMinute, limitDay, remainingDay, mode, updatedAt } = status;
+      const updatedAtMs = typeof updatedAt === 'number' ? updatedAt : Date.parse(updatedAt);
+      const hasTime = Number.isFinite(updatedAtMs);
 
-    const port = parseInt(callbackServerPort || '8582', 10);
-    if (isNaN(port) || port < 1 || port > 65535) {
-      errors.push('Invalid port number. Must be between 1 and 65535.');
-    } else if (port < 1024) {
-      warnings.push('Using a privileged port (< 1024) may require root permissions.');
+      return {
+        success: true,
+        rateLimit: { limitMinute, remainingMinute, limitDay, remainingDay },
+        mode: mode || null,
+        updatedAt: hasTime ? new Date(updatedAtMs).toISOString() : null,
+        ageMs: hasTime ? Math.max(0, Date.now() - updatedAtMs) : null,
+      };
     }
 
-    return { valid: errors.length === 0, errors, warnings };
-  }
+    // -------------------------------------------------------------------------
+    // Validate Config Handler
+    // -------------------------------------------------------------------------
+
+    /**
+   * Validate the Developer Portal wizard fields with the plugin's own rules
+   * (ConfigManager), so the UI and the plugin can never disagree.
+   * Response: { valid, errors, warnings }.
+   */
+    async handleValidateConfig(payload) {
+      const { clientId, clientSecret, callbackServerExternalAddress, callbackServerPort } = payload || {};
+      return validateConfig({
+        platform: 'DaikinCloud',
+        authMode: 'developer_portal',
+        clientId,
+        clientSecret,
+        callbackServerExternalAddress,
+        callbackServerPort,
+      });
+    }
+  };
 }
 
 // =============================================================================
 // Initialize Server
 // =============================================================================
 
-(() => new DaikinCloudUiServer())();
+/**
+ * Load @homebridge/plugin-ui-utils synchronously when the runtime supports
+ * require() of ES modules, otherwise return null so the caller uses import().
+ */
+function loadUiUtilsSync() {
+  try {
+    return require('@homebridge/plugin-ui-utils');
+  } catch (error) {
+    if (error.code === 'ERR_REQUIRE_ESM') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function loadUiUtils() {
+  return loadUiUtilsSync() || import('@homebridge/plugin-ui-utils');
+}
+
+const uiUtils = loadUiUtilsSync();
+
+module.exports = {
+  // undefined on runtimes without require(esm); use createDaikinCloudUiServer
+  DaikinCloudUiServer: uiUtils ? createDaikinCloudUiServer(uiUtils.HomebridgePluginUiServer) : undefined,
+  createDaikinCloudUiServer,
+  loadUiUtils,
+  CallbackServer,
+  SSLUtils,
+  NetUtils,
+  TokenManager,
+  DeviceExtractor,
+  HtmlTemplates,
+  escapeHtml,
+  DEVICES_CACHE_TTL_MS,
+};
+
+// Homebridge UI forks this file as a child process; only start the server then,
+// so tests can require it without side effects.
+if (require.main === module) {
+  loadUiUtils()
+    .then(({ HomebridgePluginUiServer }) => {
+      const DaikinCloudUiServer = createDaikinCloudUiServer(HomebridgePluginUiServer);
+      return new DaikinCloudUiServer();
+    })
+    .catch((error) => {
+      console.error('Failed to start the Daikin Cloud UI server:', error);
+      process.exit(1);
+    });
+}