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

package/homebridge-ui/server.js

@@ -1,4 +1,3 @@
-const { HomebridgePluginUiServer } = require('@homebridge/plugin-ui-utils');
 const { resolve, join } = require('path');
 const fs = require('fs');
 const https = require('https');
@@ -504,645 +503,676 @@ 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.devicesCache = new Map();
 
-    this.applyTransportFromConfig();
-    this.registerHandlers();
-    this.ready();
-  }
+      this.applyTransportFromConfig();
+      this.registerHandlers();
+      this.ready();
+    }
 
-  getStoragePath() {
-    return this.homebridgeStoragePath || process.env.UIX_STORAGE_PATH || '';
-  }
+    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;
-  }
+    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 platform = this.readPlatformConfig();
-      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);
+      }
     }
-  }
 
-  /**
+    /**
    * 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;
+    getCallbackBindAddress(payload) {
+      let configured = payload?.oidcCallbackServerBindAddr;
+      if (configured === undefined || configured === null || configured === '') {
+        try {
+          configured = this.readPlatformConfig()?.oidcCallbackServerBindAddr;
+        } catch (e) {
+          configured = undefined;
+        }
       }
-    }
 
-    const bindAddr = NetUtils.resolveBindAddress(configured);
-    if (configured && bindAddr !== String(configured).trim()) {
-      console.warn(`[DaikinCloud] Invalid callback bind address "${configured}", using ${bindAddr}`);
+      const bindAddr = NetUtils.resolveBindAddress(configured);
+      if (configured && bindAddr !== String(configured).trim()) {
+        console.warn(`[DaikinCloud] Invalid callback bind address "${configured}", using ${bindAddr}`);
+      }
+      return bindAddr;
     }
-    return bindAddr;
-  }
 
-  getTokenFilePath() {
-    return resolve(this.getStoragePath(), TOKEN_FILES.developer_portal);
-  }
+    getTokenFilePath() {
+      return resolve(this.getStoragePath(), TOKEN_FILES.developer_portal);
+    }
 
-  getMobileTokenFilePath() {
-    return resolve(this.getStoragePath(), TOKEN_FILES.mobile_app);
-  }
+    getMobileTokenFilePath() {
+      return resolve(this.getStoragePath(), TOKEN_FILES.mobile_app);
+    }
 
-  getCertDir() {
-    return resolve(this.getStoragePath(), 'daikin-cloud-certs');
-  }
+    getCertDir() {
+      return resolve(this.getStoragePath(), 'daikin-cloud-certs');
+    }
 
-  getRateLimitFilePath() {
-    return resolve(this.getStoragePath(), RATE_LIMIT_STATUS_FILE);
-  }
+    getRateLimitFilePath() {
+      return resolve(this.getStoragePath(), RATE_LIMIT_STATUS_FILE);
+    }
 
-  /**
+    /**
    * 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' };
+    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' };
     }
-    return { tokenSet: TokenManager.load(this.getTokenFilePath()), mode: 'developer_portal' };
-  }
 
-  getActiveTokenSet() {
-    return this.getActiveToken().tokenSet;
-  }
+    getActiveTokenSet() {
+      return this.getActiveToken().tokenSet;
+    }
 
-  /**
+    /**
    * 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());
-    }
+    resolveToken(mode) {
+      let tokenSet = null;
+      if (mode === 'mobile_app') {
+        tokenSet = TokenManager.load(this.getMobileTokenFilePath());
+      } else if (mode === 'developer_portal') {
+        tokenSet = TokenManager.load(this.getTokenFilePath());
+      }
 
-    if (tokenSet?.access_token) {
-      return { tokenSet, mode };
+      if (tokenSet?.access_token) {
+        return { tokenSet, mode };
+      }
+      return this.getActiveToken();
     }
-    return this.getActiveToken();
-  }
 
-  invalidateDevicesCache() {
-    this.devicesCache.clear();
-  }
+    invalidateDevicesCache() {
+      this.devicesCache.clear();
+    }
 
-  isPendingAuthExpired() {
-    return !!this.pendingAuth && Date.now() - this.pendingAuth.createdAt > PENDING_AUTH_TTL_MS;
-  }
+    isPendingAuthExpired() {
+      return !!this.pendingAuth && Date.now() - this.pendingAuth.createdAt > PENDING_AUTH_TTL_MS;
+    }
 
-  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));
-  }
+    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));
+    }
 
-  // -------------------------------------------------------------------------
-  // Server Info Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Server Info Handler
+    // -------------------------------------------------------------------------
 
-  async handleGetServerInfo() {
-    const ipAddresses = this.getServerIpAddresses();
-    return {
-      ipAddresses,
-      primaryIp: ipAddresses[0] || null,
-      hostname: os.hostname(),
-    };
-  }
+    async handleGetServerInfo() {
+      const ipAddresses = this.getServerIpAddresses();
+      return {
+        ipAddresses,
+        primaryIp: ipAddresses[0] || null,
+        hostname: os.hostname(),
+      };
+    }
 
-  getServerIpAddresses() {
-    const interfaces = os.networkInterfaces();
-    const addresses = [];
+    getServerIpAddresses() {
+      const interfaces = os.networkInterfaces();
+      const addresses = [];
 
-    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') {
+      for (const nets of Object.values(interfaces)) {
+        if (!nets) {
           continue;
         }
-        addresses.push(net.address);
+        for (const net of nets) {
+        // Skip internal and non-IPv4 addresses
+          if (net.internal || net.family !== 'IPv4') {
+            continue;
+          }
+          addresses.push(net.address);
+        }
       }
-    }
 
-    return addresses;
-  }
+      return addresses;
+    }
 
-  // -------------------------------------------------------------------------
-  // Auth Status Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Auth Status Handler
+    // -------------------------------------------------------------------------
 
-  async handleGetAuthStatus() {
-    try {
+    async handleGetAuthStatus() {
+      try {
       // Check both token files - mobile takes precedence if exists
-      const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
-      const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
+        const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
+        const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
 
-      if (mobileTokenSet?.access_token) {
-        const status = TokenManager.getStatus(mobileTokenSet);
-        status.authMode = 'mobile_app';
-        return status;
-      }
+        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;
-      }
+        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' };
+        return { authenticated: false, message: 'Not authenticated' };
+      } catch (error) {
+        return { authenticated: false, error: error.message, message: 'Error reading token status' };
+      }
     }
-  }
 
-  // -------------------------------------------------------------------------
-  // Start Auth Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Start Auth Handler
+    // -------------------------------------------------------------------------
 
-  async handleStartAuth(payload) {
-    const { clientId, clientSecret, callbackServerExternalAddress, callbackServerPort } = payload;
+    async handleStartAuth(payload) {
+      const { clientId, clientSecret, callbackServerExternalAddress, callbackServerPort } = payload;
 
-    if (!clientId || !clientSecret) {
-      throw new Error('Client ID and Client Secret are required');
-    }
-    if (!callbackServerExternalAddress) {
-      throw new Error('Callback Server Address is required');
-    }
+      if (!clientId || !clientSecret) {
+        throw new Error('Client ID and Client Secret are required');
+      }
+      if (!callbackServerExternalAddress) {
+        throw new Error('Callback Server Address is required');
+      }
 
-    const bindAddr = this.getCallbackBindAddress(payload);
-    if (NetUtils.isLoopback(bindAddr) && !NetUtils.isLoopback(callbackServerExternalAddress)) {
+      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 ` +
+        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.',
-      );
-    }
-
-    const port = parseInt(callbackServerPort || String(DEFAULT_CALLBACK_PORT), 10);
-    const redirectUri = `https://${callbackServerExternalAddress}:${port}`;
-    const state = crypto.randomBytes(32).toString('hex');
-
-    this.pendingAuth = { state, clientId, clientSecret, redirectUri, port, createdAt: Date.now() };
-    this.authResult = null;
-    this.invalidateDevicesCache();
-
-    // Use static method from compiled src/api
-    const authUrl = DaikinOAuth.buildAuthUrlStatic(clientId, redirectUri, state);
-    console.log('[DaikinCloud] Redirect URI:', redirectUri);
-
-    // Try to start callback server for automatic code capture
-    let callbackServerRunning = false;
-    let callbackServerError = null;
+        );
+      }
 
-    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);
-    }
+      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) {
-    let url;
-    try {
-      url = new URL(req.url, 'https://localhost');
-    } catch (e) {
-      this.sendCallbackResponse(res, false, 'Invalid request', 400);
-      return;
-    }
+      // 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);
+      }
 
-    // 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;
+      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 (this.isPendingAuthExpired()) {
-      this.pendingAuth = null;
-      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(() => {});
-      return;
-    }
+    // -------------------------------------------------------------------------
+    // HTTPS Callback Handler
+    // -------------------------------------------------------------------------
 
-    if (error) {
-      this.authResult = { success: false, error: errorDescription || error };
-      this.sendCallbackResponse(res, false, errorDescription || error);
-      return;
-    }
+    handleHttpsCallback(req, res) {
+      let url;
+      try {
+        url = new URL(req.url, 'https://localhost');
+      } catch (e) {
+        this.sendCallbackResponse(res, false, 'Invalid request', 400);
+        return;
+      }
 
-    if (!code) {
-      this.authResult = { success: false, error: 'Missing code parameter' };
-      this.sendCallbackResponse(res, false, 'Missing authorization code', 400);
-      return;
-    }
+      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');
 
-    const { clientId, clientSecret, redirectUri } = this.pendingAuth;
+      // 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;
+      }
 
-    // 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,
-        };
+      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, statusCode = 200) {
-    res.writeHead(statusCode, CALLBACK_RESPONSE_HEADERS);
-    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 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.');
+    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.invalidateDevicesCache();
-      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 {
+          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 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,
-      };
+    // -------------------------------------------------------------------------
+    // Poll Auth Result Handler
+    // -------------------------------------------------------------------------
+
+    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 { pending: true };
     }
-    return { pending: true };
-  }
 
-  // -------------------------------------------------------------------------
-  // Stop Server Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Stop Server Handler
+    // -------------------------------------------------------------------------
 
-  async handleStopServer() {
-    this.pendingAuth = null;
-    this.authResult = null;
-    await this.callbackServer.stop();
-    return { success: true };
-  }
+    async handleStopServer() {
+      this.pendingAuth = null;
+      this.authResult = null;
+      await this.callbackServer.stop();
+      return { success: true };
+    }
 
-  // -------------------------------------------------------------------------
-  // Mobile Auth Test Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Mobile Auth Test Handler
+    // -------------------------------------------------------------------------
 
-  async handleMobileAuthTest(payload) {
-    const { email, password } = payload;
+    async handleMobileAuthTest(payload) {
+      const { email, password } = payload;
 
-    if (!email || !password) {
-      return { success: false, message: 'Email and password are required' };
-    }
+      if (!email || !password) {
+        return { success: false, message: 'Email and password are required' };
+      }
 
-    const tokenFilePath = this.getMobileTokenFilePath();
-    this.invalidateDevicesCache();
+      const tokenFilePath = this.getMobileTokenFilePath();
+      this.invalidateDevicesCache();
 
-    try {
+      try {
       // Create a temporary mobile OAuth client
-      const mobileOAuth = new DaikinMobileOAuth({
-        email,
-        password,
-        tokenFilePath,
-      });
+        const mobileOAuth = new DaikinMobileOAuth({
+          email,
+          password,
+          tokenFilePath,
+        });
 
-      // Perform authentication
-      console.log('[DaikinCloud] Testing mobile app authentication...');
-      const tokenSet = await mobileOAuth.authenticate();
-      console.log('[DaikinCloud] Mobile authentication successful');
+        // Perform authentication
+        console.log('[DaikinCloud] Testing mobile app authentication...');
+        const tokenSet = await mobileOAuth.authenticate();
+        console.log('[DaikinCloud] Mobile authentication successful');
 
-      // Test API access and get device count
-      let deviceCount = 0;
-      let rateLimit = null;
+        // Test API access and get device count
+        let deviceCount = 0;
+        let rateLimit = null;
 
-      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);
-      }
+        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);
+        }
 
-      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',
-      };
+        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',
+        };
+      }
     }
-  }
 
-  // -------------------------------------------------------------------------
-  // Revoke Auth Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Revoke Auth Handler
+    // -------------------------------------------------------------------------
 
-  async handleRevokeAuth(payload) {
-    this.invalidateDevicesCache();
+    async handleRevokeAuth(payload) {
+      this.invalidateDevicesCache();
 
-    const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
-    const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
+      const devPortalTokenSet = TokenManager.load(this.getTokenFilePath());
+      const mobileTokenSet = TokenManager.load(this.getMobileTokenFilePath());
 
-    if (!devPortalTokenSet && !mobileTokenSet) {
-      return { success: true, message: 'No tokens to revoke' };
-    }
+      if (!devPortalTokenSet && !mobileTokenSet) {
+        return { success: true, message: 'No tokens to revoke' };
+      }
 
-    const { clientId, clientSecret } = payload;
+      const { clientId, clientSecret } = payload;
 
-    if (devPortalTokenSet?.refresh_token && clientId && clientSecret) {
-      try {
+      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);
+          await DaikinOAuth.revokeTokenStatic(devPortalTokenSet.refresh_token, clientId, clientSecret);
+        } catch (error) {
+          console.warn('Failed to revoke token at server:', error.message);
+        }
       }
-    }
 
-    // Delete both token files
-    TokenManager.delete(this.getTokenFilePath());
-    TokenManager.delete(this.getMobileTokenFilePath());
-    return { success: true, message: 'Authentication revoked. You will need to re-authenticate.' };
-  }
+      // Delete both token files
+      TokenManager.delete(this.getTokenFilePath());
+      TokenManager.delete(this.getMobileTokenFilePath());
+      return { success: true, message: 'Authentication revoked. You will need to re-authenticate.' };
+    }
 
-  // -------------------------------------------------------------------------
-  // Test Connection Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Test Connection Handler
+    // -------------------------------------------------------------------------
 
-  async handleTestConnection() {
-    const tokenSet = this.getActiveTokenSet();
-    if (!tokenSet?.access_token) {
-      return { success: false, 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 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 };
+        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 };
+      }
     }
-  }
 
-  // -------------------------------------------------------------------------
-  // List Devices Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // List Devices Handler
+    // -------------------------------------------------------------------------
 
-  async handleListDevices(payload) {
+    async handleListDevices(payload) {
     // Token for the requested mode, or fall back to the active token
-    const { tokenSet, mode } = this.resolveToken(payload?.mode);
+      const { tokenSet, mode } = this.resolveToken(payload?.mode);
 
-    if (!tokenSet?.access_token) {
-      return { success: false, devices: [], message: 'Not authenticated. Please authenticate first.' };
-    }
+      if (!tokenSet?.access_token) {
+        return { success: false, devices: [], message: 'Not authenticated. Please authenticate first.' };
+      }
 
-    // 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() };
-    }
+      // 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);
-      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 };
+        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 };
+      }
     }
-  }
 
-  // -------------------------------------------------------------------------
-  // Get Rate Limit Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Get Rate Limit Handler
+    // -------------------------------------------------------------------------
 
-  /**
+    /**
    * 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.',
-        };
+    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}` };
       }
-      return { success: false, message: `Could not read rate limit status: ${error.message}` };
-    }
 
-    if (!status || typeof status !== 'object') {
-      return { success: false, message: 'Could not read rate limit status: invalid file contents' };
-    }
+      if (!status || typeof status !== 'object') {
+        return { success: false, message: 'Could not read rate limit status: invalid file contents' };
+      }
 
-    const { limitMinute, remainingMinute, limitDay, remainingDay, mode, updatedAt } = status;
-    const updatedAtMs = typeof updatedAt === 'number' ? updatedAt : Date.parse(updatedAt);
-    const hasTime = Number.isFinite(updatedAtMs);
+      const { limitMinute, remainingMinute, limitDay, remainingDay, mode, updatedAt } = status;
+      const updatedAtMs = typeof updatedAt === 'number' ? updatedAt : Date.parse(updatedAt);
+      const hasTime = Number.isFinite(updatedAtMs);
 
-    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 {
+        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,
+      };
+    }
 
-  // -------------------------------------------------------------------------
-  // Validate Config Handler
-  // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // 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,
-    });
-  }
+    async handleValidateConfig(payload) {
+      const { clientId, clientSecret, callbackServerExternalAddress, callbackServerPort } = payload || {};
+      return validateConfig({
+        platform: 'DaikinCloud',
+        authMode: 'developer_portal',
+        clientId,
+        clientSecret,
+        callbackServerExternalAddress,
+        callbackServerPort,
+      });
+    }
+  };
 }
 
 // =============================================================================
 // Initialize Server
 // =============================================================================
 
+/**
+ * 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 = {
-  DaikinCloudUiServer,
+  // undefined on runtimes without require(esm); use createDaikinCloudUiServer
+  DaikinCloudUiServer: uiUtils ? createDaikinCloudUiServer(uiUtils.HomebridgePluginUiServer) : undefined,
+  createDaikinCloudUiServer,
+  loadUiUtils,
   CallbackServer,
   SSLUtils,
   NetUtils,
@@ -1156,5 +1186,13 @@ module.exports = {
 // 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) {
-  (() => new DaikinCloudUiServer())();
+  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);
+    });
 }

package/package.json

@@ -2,7 +2,7 @@
   "displayName": "Daikin Cloud",
   "platformname": "daikincloud",
   "name": "@mp-consulting/homebridge-daikin-cloud",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Integrate with the Daikin Cloud to control your Daikin air conditioning via the cloud",
   "license": "(Apache-2.0 AND MIT)",
   "repository": {
@@ -25,6 +25,7 @@
     "test:coverage": "vitest run --coverage",
     "lint": "eslint . --max-warnings=0",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "smoke:ui": "node scripts/smoke-ui-server.js",
     "schema:check": "tsx scripts/check-schema-drift.ts",
     "watch": "npm run build && npm link && nodemon",
     "copy:ui-kit": "mkdir -p homebridge-ui/public/lib && cp node_modules/@mp-consulting/homebridge-ui-kit/dist/kit.css homebridge-ui/public/lib/ && cp node_modules/@mp-consulting/homebridge-ui-kit/dist/kit.js homebridge-ui/public/lib/",