matterbridge-roborock-vacuum-plugin 1.1.1-rc08 → 1.1.1-rc09

package/dist/platform.js

@@ -1,5 +1,6 @@
 import { MatterbridgeDynamicPlatform } from 'matterbridge';
 import * as axios from 'axios';
+import crypto from 'node:crypto';
 import { debugStringify } from 'matterbridge/logger';
 import RoborockService from './roborockService.js';
 import { PLUGIN_NAME } from './settings.js';
@@ -46,8 +47,8 @@ export class RoborockMatterbridgePlatform extends MatterbridgeDynamicPlatform {
         await this.ready;
         await this.clearSelect();
         await this.persist.init();
-        if (this.config.username === undefined || this.config.password === undefined) {
-            this.log.error('"username" and "password" are required in the config');
+        if (this.config.username === undefined) {
+            this.log.error('"username" (email address) is required in the config');
             return;
         }
         const axiosInstance = axios.default ?? axios;
@@ -59,23 +60,43 @@ export class RoborockMatterbridgePlatform extends MatterbridgeDynamicPlatform {
             this.log.notice(`cleanModeSettings ${debugStringify(this.cleanModeSettings)}`);
         }
         this.platformRunner = new PlatformRunner(this);
-        this.roborockService = new RoborockService(() => new RoborockAuthenticateApi(this.log, axiosInstance), (logger, ud) => new RoborockIoTApi(ud, logger), this.config.refreshInterval ?? 60, this.clientManager, this.log);
+        let deviceId = (await this.persist.getItem('deviceId'));
+        if (!deviceId) {
+            deviceId = crypto.randomUUID();
+            await this.persist.setItem('deviceId', deviceId);
+            this.log.debug('Generated new deviceId:', deviceId);
+        }
+        else {
+            this.log.debug('Using cached deviceId:', deviceId);
+        }
+        this.roborockService = new RoborockService(() => new RoborockAuthenticateApi(this.log, axiosInstance, deviceId), (logger, ud) => new RoborockIoTApi(ud, logger), this.config.refreshInterval ?? 60, this.clientManager, this.log);
         const username = this.config.username;
-        const password = this.config.password;
-        const userData = await this.roborockService.loginWithPassword(username, password, async () => {
-            if (this.enableExperimentalFeature?.enableExperimentalFeature && this.enableExperimentalFeature.advancedFeature?.alwaysExecuteAuthentication) {
-                this.log.debug('Always execute authentication on startup');
-                return undefined;
+        this.log.debug(`config: ${debugStringify(this.config)}`);
+        const authenticationPayload = this.config.authentication;
+        const password = authenticationPayload.password ?? '';
+        const verificationCode = authenticationPayload.verificationCode ?? '';
+        const authenticationMethod = authenticationPayload.authenticationMethod;
+        this.log.debug(`Authentication method: ${authenticationMethod}`);
+        this.log.debug(`Username: ${username}`);
+        this.log.debug(`Password provided: ${password !== ''}`);
+        this.log.debug(`Verification code provided: ${verificationCode !== ''}`);
+        let userData;
+        try {
+            if (authenticationMethod === 'VerificationCode') {
+                this.log.debug('Using verification code from config for authentication');
+                userData = await this.authenticate2FA(username, verificationCode);
             }
-            const savedUserData = (await this.persist.getItem('userData'));
-            if (savedUserData) {
-                this.log.debug('Loading saved userData:', debugStringify(savedUserData));
-                return savedUserData;
+            else {
+                userData = await this.authenticateWithPassword(username, password);
             }
-            return undefined;
-        }, async (userData) => {
-            await this.persist.setItem('userData', userData);
-        });
+        }
+        catch (error) {
+            this.log.error(`Authentication failed: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        if (!userData) {
+            return;
+        }
         this.log.debug('Initializing - userData:', debugStringify(userData));
         const devices = await this.roborockService.listDevices(username);
         this.log.notice('Initializing - devices: ', debugStringify(devices));
@@ -200,4 +221,88 @@ export class RoborockMatterbridgePlatform extends MatterbridgeDynamicPlatform {
         this.log.logLevel = logLevel;
         return Promise.resolve();
     }
+    async authenticateWithPassword(username, password) {
+        if (!this.roborockService) {
+            throw new Error('RoborockService is not initialized');
+        }
+        this.log.notice('Attempting login with password...');
+        const userData = await this.roborockService.loginWithPassword(username, password, async () => {
+            if (this.enableExperimentalFeature?.enableExperimentalFeature && this.enableExperimentalFeature.advancedFeature?.alwaysExecuteAuthentication) {
+                this.log.debug('Always execute authentication on startup');
+                return undefined;
+            }
+            const savedUserData = (await this.persist.getItem('userData'));
+            if (savedUserData) {
+                this.log.debug('Loading saved userData:', debugStringify(savedUserData));
+                return savedUserData;
+            }
+            return undefined;
+        }, async (userData) => {
+            await this.persist.setItem('userData', userData);
+        });
+        this.log.notice('Authentication successful!');
+        return userData;
+    }
+    async authenticate2FA(username, verificationCode) {
+        if (!this.roborockService) {
+            throw new Error('RoborockService is not initialized');
+        }
+        if (!this.enableExperimentalFeature?.advancedFeature?.alwaysExecuteAuthentication) {
+            const savedUserData = (await this.persist.getItem('userData'));
+            if (savedUserData) {
+                this.log.debug('Found saved userData, attempting to use cached token');
+                try {
+                    const userData = await this.roborockService.loginWithCachedToken(username, savedUserData);
+                    this.log.notice('Successfully authenticated with cached token');
+                    return userData;
+                }
+                catch (error) {
+                    this.log.warn(`Cached token invalid or expired: ${error instanceof Error ? error.message : String(error)}`);
+                    await this.persist.removeItem('userData');
+                }
+            }
+        }
+        if (!verificationCode || verificationCode.trim() === '') {
+            const authState = (await this.persist.getItem('authenticateFlowState'));
+            const now = Date.now();
+            const RATE_LIMIT_MS = 60000;
+            if (authState?.codeRequestedAt && now - authState.codeRequestedAt < RATE_LIMIT_MS) {
+                const waitSeconds = Math.ceil((RATE_LIMIT_MS - (now - authState.codeRequestedAt)) / 1000);
+                this.log.warn(`Please wait ${waitSeconds} seconds before requesting another code.`);
+                this.log.notice('============================================');
+                this.log.notice('ACTION REQUIRED: Enter verification code');
+                this.log.notice(`A verification code was previously sent to: ${username}`);
+                this.log.notice('Enter the 6-digit code in the plugin configuration');
+                this.log.notice('under the "verificationCode" field, then restart the plugin.');
+                this.log.notice('============================================');
+                return undefined;
+            }
+            try {
+                this.log.notice(`Requesting verification code for: ${username}`);
+                await this.roborockService.requestVerificationCode(username);
+                await this.persist.setItem('authenticateFlowState', {
+                    email: username,
+                    codeRequestedAt: now,
+                });
+                this.log.notice('============================================');
+                this.log.notice('ACTION REQUIRED: Enter verification code');
+                this.log.notice(`A verification code has been sent to: ${username}`);
+                this.log.notice('Enter the 6-digit code in the plugin configuration');
+                this.log.notice('under the "verificationCode" field, then restart the plugin.');
+                this.log.notice('============================================');
+            }
+            catch (error) {
+                this.log.error(`Failed to request verification code: ${error instanceof Error ? error.message : String(error)}`);
+                throw error;
+            }
+            return undefined;
+        }
+        this.log.notice('Attempting login with verification code...');
+        const userData = await this.roborockService.loginWithVerificationCode(username, verificationCode.trim(), async (data) => {
+            await this.persist.setItem('userData', data);
+            await this.persist.removeItem('authenticateFlowState');
+        });
+        this.log.notice('Authentication successful!');
+        return userData;
+    }
 }

package/dist/roborockCommunication/RESTAPI/roborockAuthenticateApi.js

@@ -1,14 +1,18 @@
 import axios from 'axios';
 import crypto from 'node:crypto';
 import { URLSearchParams } from 'node:url';
+import { AuthenticateResponseCode } from '../Zenum/authenticateResponseCode.js';
 export class RoborockAuthenticateApi {
     logger;
     axiosFactory;
     deviceId;
     username;
     authToken;
-    constructor(logger, axiosFactory = axios) {
-        this.deviceId = crypto.randomUUID();
+    cachedBaseUrl;
+    cachedCountry;
+    cachedCountryCode;
+    constructor(logger, axiosFactory = axios, deviceId) {
+        this.deviceId = deviceId ?? crypto.randomUUID();
         this.axiosFactory = axiosFactory;
         this.logger = logger;
     }
@@ -25,6 +29,53 @@ export class RoborockAuthenticateApi {
         }).toString());
         return this.auth(username, response.data);
     }
+    async requestCodeV4(email) {
+        const api = await this.getAPIFor(email);
+        const response = await api.post('api/v4/email/code/send', new URLSearchParams({
+            email: email,
+            type: 'login',
+            platform: '',
+        }), {
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+        });
+        const apiResponse = response.data;
+        if (apiResponse.code === AuthenticateResponseCode.AccountNotFound) {
+            throw new Error(`Account not found for email: ${email}`);
+        }
+        if (apiResponse.code === AuthenticateResponseCode.RateLimited) {
+            throw new Error('Rate limited. Please wait before requesting another code.');
+        }
+        if (apiResponse.code !== AuthenticateResponseCode.Success && apiResponse.code !== undefined) {
+            throw new Error(`Failed to send verification code: ${apiResponse.msg} (code: ${apiResponse.code})`);
+        }
+        this.logger.debug('Verification code requested successfully');
+    }
+    async loginWithCodeV4(email, code) {
+        const api = await this.getAPIFor(email);
+        const xMercyKs = this.generateRandomString(16);
+        const xMercyK = await this.signKeyV3(api, xMercyKs);
+        const response = await api.post('api/v4/auth/email/login/code', null, {
+            params: {
+                email: email,
+                code: code,
+                country: this.cachedCountry ?? '',
+                countryCode: this.cachedCountryCode ?? '',
+                majorVersion: '14',
+                minorVersion: '0',
+            },
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'x-mercy-ks': xMercyKs,
+                'x-mercy-k': xMercyK,
+                header_appversion: '4.54.02',
+                header_phonesystem: 'iOS',
+                header_phonemodel: 'iPhone16,1',
+            },
+        });
+        return this.authV4(email, response.data);
+    }
     async getHomeDetails() {
         if (!this.username || !this.authToken) {
             return undefined;
@@ -37,11 +88,20 @@ export class RoborockAuthenticateApi {
         }
         return apiResponse.data;
     }
+    getCachedCountryInfo() {
+        return {
+            country: this.cachedCountry,
+            countryCode: this.cachedCountryCode,
+        };
+    }
     async getAPIFor(username) {
         const baseUrl = await this.getBaseUrl(username);
         return this.apiForUser(username, baseUrl);
     }
     async getBaseUrl(username) {
+        if (this.cachedBaseUrl && this.username === username) {
+            return this.cachedBaseUrl;
+        }
         const api = await this.apiForUser(username);
         const response = await api.post('api/v1/getUrlByEmail', new URLSearchParams({
             email: username,
@@ -51,16 +111,41 @@ export class RoborockAuthenticateApi {
         if (!apiResponse.data) {
             throw new Error('Failed to retrieve base URL: ' + apiResponse.msg);
         }
+        this.cachedBaseUrl = apiResponse.data.url;
+        this.cachedCountry = apiResponse.data.country;
+        this.cachedCountryCode = apiResponse.data.countrycode;
+        this.username = username;
         return apiResponse.data.url;
     }
     async apiForUser(username, baseUrl = 'https://usiot.roborock.com') {
-        return this.axiosFactory.create({
+        const instance = this.axiosFactory.create({
             baseURL: baseUrl,
             headers: {
                 header_clientid: crypto.createHash('md5').update(username).update(this.deviceId).digest('base64'),
                 Authorization: this.authToken,
+                header_clientlang: 'en',
             },
         });
+        instance.interceptors.request.use((config) => {
+            this.logger.debug('=== HTTP Request ===');
+            this.logger.debug(`URL: ${config.baseURL}/${config.url}`);
+            this.logger.debug(`Method: ${config.method?.toUpperCase()}`);
+            this.logger.debug(`Params: ${JSON.stringify(config.params)}`);
+            this.logger.debug(`Data: ${JSON.stringify(config.data)}`);
+            this.logger.debug(`Headers: ${JSON.stringify(config.headers)}`);
+            return config;
+        });
+        instance.interceptors.response.use((response) => {
+            this.logger.debug('=== HTTP Response ===');
+            this.logger.debug(`Status: ${response.status}`);
+            this.logger.debug(`Data: ${JSON.stringify(response.data)}`);
+            return response;
+        }, (error) => {
+            this.logger.debug('=== HTTP Error ===');
+            this.logger.debug(`Error: ${JSON.stringify(error.response?.data ?? error.message)}`);
+            return Promise.reject(error);
+        });
+        return instance;
     }
     auth(username, response) {
         const userdata = response.data;
@@ -70,8 +155,41 @@ export class RoborockAuthenticateApi {
         this.loginWithAuthToken(username, userdata.token);
         return userdata;
     }
+    authV4(email, response) {
+        if (response.code === AuthenticateResponseCode.InvalidCode) {
+            throw new Error('Invalid verification code. Please check and try again.');
+        }
+        if (response.code === AuthenticateResponseCode.RateLimited) {
+            throw new Error('Rate limited. Please wait before trying again.');
+        }
+        const userdata = response.data;
+        if (!userdata || !userdata.token) {
+            throw new Error('Authentication failed: ' + response.msg + ' code: ' + response.code);
+        }
+        this.loginWithAuthToken(email, userdata.token);
+        return userdata;
+    }
     loginWithAuthToken(username, token) {
         this.username = username;
         this.authToken = token;
     }
+    generateRandomString(length) {
+        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+        let result = '';
+        const randomBytes = crypto.randomBytes(length);
+        for (let i = 0; i < length; i++) {
+            result += chars[randomBytes[i] % chars.length];
+        }
+        return result;
+    }
+    async signKeyV3(api, s) {
+        const response = await api.post('api/v3/key/sign', null, {
+            params: { s },
+        });
+        const apiResponse = response.data;
+        if (!apiResponse.data?.k) {
+            throw new Error('Failed to sign key: ' + apiResponse.msg);
+        }
+        return apiResponse.data.k;
+    }
 }

package/dist/roborockCommunication/Zenum/authenticateResponseCode.js

@@ -0,0 +1,7 @@
+export var AuthenticateResponseCode;
+(function (AuthenticateResponseCode) {
+    AuthenticateResponseCode[AuthenticateResponseCode["Success"] = 200] = "Success";
+    AuthenticateResponseCode[AuthenticateResponseCode["AccountNotFound"] = 2008] = "AccountNotFound";
+    AuthenticateResponseCode[AuthenticateResponseCode["InvalidCode"] = 2018] = "InvalidCode";
+    AuthenticateResponseCode[AuthenticateResponseCode["RateLimited"] = 9002] = "RateLimited";
+})(AuthenticateResponseCode || (AuthenticateResponseCode = {}));

package/dist/roborockCommunication/Zmodel/authenticateFlowState.js

@@ -0,0 +1 @@
+export {};

package/dist/roborockCommunication/index.js

@@ -9,4 +9,5 @@ export { DeviceStatus } from './Zmodel/deviceStatus.js';
 export { ResponseMessage } from './broadcast/model/responseMessage.js';
 export { MapInfo } from './Zmodel/mapInfo.js';
 export { AdditionalPropCode } from './Zenum/additionalPropCode.js';
+export { AuthenticateResponseCode } from './Zenum/authenticateResponseCode.js';
 export { Scene } from './Zmodel/scene.js';

package/dist/roborockService.js

@@ -44,6 +44,18 @@ export default class RoborockService {
         }
         return this.auth(userdata);
     }
+    async requestVerificationCode(email) {
+        return this.loginApi.requestCodeV4(email);
+    }
+    async loginWithVerificationCode(email, code, savedUserData) {
+        const userdata = await this.loginApi.loginWithCodeV4(email, code);
+        await savedUserData(userdata);
+        return this.auth(userdata);
+    }
+    async loginWithCachedToken(username, userData) {
+        const validatedUserData = await this.loginApi.loginWithUserData(username, userData);
+        return this.auth(validatedUserData);
+    }
     getMessageProcessor(duid) {
         const messageProcessor = this.messageProcessorMap.get(duid);
         if (!messageProcessor) {

package/matterbridge-roborock-vacuum-plugin.config.json

@@ -1,7 +1,7 @@
 {
   "name": "matterbridge-roborock-vacuum-plugin",
   "type": "DynamicPlatform",
-  "version": "1.1.1-rc08",
+  "version": "1.1.1-rc09",
   "whiteList": [],
   "blackList": [],
   "useInterval": true,
@@ -35,6 +35,11 @@
       }
     }
   },
+  "authentication": {
+    "authenticationMethod": "VerificationCode",
+    "verificationCode": "",
+    "password": ""
+  },
   "debug": true,
   "unregisterOnShutdown": false,
   "enableExperimentalFeature": false

package/matterbridge-roborock-vacuum-plugin.schema.json

@@ -1,8 +1,8 @@
 {
   "title": "Matterbridge Roborock Vacuum Plugin",
-  "description": "matterbridge-roborock-vacuum-plugin v. 1.1.1-rc08 by https://github.com/RinDevJunior",
+  "description": "matterbridge-roborock-vacuum-plugin v. 1.1.1-rc09 by https://github.com/RinDevJunior",
   "type": "object",
-  "required": ["username", "password"],
+  "required": ["username"],
   "properties": {
     "name": {
       "description": "Plugin name",
@@ -26,14 +26,51 @@
       "selectFrom": "name"
     },
     "username": {
-      "description": "Roborock username (required for the plugin to work)",
+      "description": "Roborock account email address",
       "type": "string"
     },
-    "password": {
-      "description": "Roborock password (required for the plugin to work)",
-      "type": "string",
-      "ui:widget": "password"
+    "authentication": {
+      "description": "Authentication method to use",
+      "type": "object",
+      "oneOf": [
+        {
+          "title": "Verification Code",
+          "type": "object",
+          "properties": {
+            "authenticationMethod": {
+              "const": "VerificationCode",
+              "type": "string",
+              "default": "VerificationCode",
+              "readOnly": true
+            },
+            "verificationCode": {
+              "description": "6-digit verification code sent to your email. Leave empty to request a new code, then restart the plugin after entering the code.",
+              "type": "string",
+              "maxLength": 6
+            }
+          },
+          "required": ["authenticationMethod", "verificationCode"]
+        },
+        {
+          "title": "Password",
+          "type": "object",
+          "properties": {
+            "authenticationMethod": {
+              "const": "Password",
+              "type": "string",
+              "readOnly": true
+            },
+            "password": {
+              "description": "[DEPRECATED] Password login is no longer supported. Use verification code instead.",
+              "type": "string",
+              "ui:widget": "password"
+            }
+          },
+          "required": ["authenticationMethod", "password"]
+        }
+      ]
     },
+
     "refreshInterval": {
       "description": "Refresh interval in seconds (default: 60)",
       "type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge-roborock-vacuum-plugin",
-  "version": "1.1.1-rc08",
+  "version": "1.1.1-rc09",
   "description": "Matterbridge Roborock Vacuum Plugin",
   "author": "https://github.com/RinDevJunior",
   "license": "MIT",

package/src/model/ExperimentalFeatureSetting.ts

@@ -8,6 +8,12 @@ export interface AdvancedFeature {
   enableMultipleMap: boolean;
 }
 
+export interface AuthenticationPayload {
+  authenticationMethod: 'VerificationCode' | 'Password';
+  verificationCode?: string;
+  password?: string;
+}
+
 export interface ExperimentalFeatureSetting {
   enableExperimentalFeature: boolean;
   advancedFeature: AdvancedFeature;

package/src/platform.ts

@@ -1,5 +1,6 @@
 import { PlatformMatterbridge, MatterbridgeDynamicPlatform, PlatformConfig } from 'matterbridge';
 import * as axios from 'axios';
+import crypto from 'node:crypto';
 import { AnsiLogger, debugStringify, LogLevel } from 'matterbridge/logger';
 import RoborockService from './roborockService.js';
 import { PLUGIN_NAME } from './settings.js';
@@ -9,9 +10,9 @@ import { PlatformRunner } from './platformRunner.js';
 import { RoborockVacuumCleaner } from './rvc.js';
 import { configurateBehavior } from './behaviorFactory.js';
 import { NotifyMessageTypes } from './notifyMessageTypes.js';
-import { Device, RoborockAuthenticateApi, RoborockIoTApi, UserData } from './roborockCommunication/index.js';
+import { Device, RoborockAuthenticateApi, RoborockIoTApi, UserData, AuthenticateFlowState } from './roborockCommunication/index.js';
 import { getSupportedAreas, getSupportedScenes } from './initialData/index.js';
-import { CleanModeSettings, createDefaultExperimentalFeatureSetting, ExperimentalFeatureSetting } from './model/ExperimentalFeatureSetting.js';
+import { AuthenticationPayload, CleanModeSettings, createDefaultExperimentalFeatureSetting, ExperimentalFeatureSetting } from './model/ExperimentalFeatureSetting.js';
 import { ServiceArea } from 'matterbridge/matter/clusters';
 import NodePersist from 'node-persist';
 import Path from 'node:path';
@@ -61,8 +62,8 @@ export class RoborockMatterbridgePlatform extends MatterbridgeDynamicPlatform {
     await this.persist.init();
 
     // Verify that the config is correct
-    if (this.config.username === undefined || this.config.password === undefined) {
-      this.log.error('"username" and "password" are required in the config');
+    if (this.config.username === undefined) {
+      this.log.error('"username" (email address) is required in the config');
       return;
     }
 
@@ -80,8 +81,18 @@ export class RoborockMatterbridgePlatform extends MatterbridgeDynamicPlatform {
 
     this.platformRunner = new PlatformRunner(this);
 
+    // Load or generate deviceId for consistent authentication
+    let deviceId = (await this.persist.getItem('deviceId')) as string | undefined;
+    if (!deviceId) {
+      deviceId = crypto.randomUUID();
+      await this.persist.setItem('deviceId', deviceId);
+      this.log.debug('Generated new deviceId:', deviceId);
+    } else {
+      this.log.debug('Using cached deviceId:', deviceId);
+    }
+
     this.roborockService = new RoborockService(
-      () => new RoborockAuthenticateApi(this.log, axiosInstance),
+      () => new RoborockAuthenticateApi(this.log, axiosInstance, deviceId),
       (logger, ud) => new RoborockIoTApi(ud, logger),
       (this.config.refreshInterval as number) ?? 60,
       this.clientManager,
@@ -89,28 +100,37 @@ export class RoborockMatterbridgePlatform extends MatterbridgeDynamicPlatform {
     );
 
     const username = this.config.username as string;
-    const password = this.config.password as string;
 
-    const userData = await this.roborockService.loginWithPassword(
-      username,
-      password,
-      async () => {
-        if (this.enableExperimentalFeature?.enableExperimentalFeature && this.enableExperimentalFeature.advancedFeature?.alwaysExecuteAuthentication) {
-          this.log.debug('Always execute authentication on startup');
-          return undefined;
-        }
+    this.log.debug(`config: ${debugStringify(this.config)}`);
+
+    const authenticationPayload = this.config.authentication as AuthenticationPayload;
+    const password = authenticationPayload.password ?? '';
+    const verificationCode = authenticationPayload.verificationCode ?? '';
+    const authenticationMethod = authenticationPayload.authenticationMethod as 'VerificationCode' | 'Password';
+
+    this.log.debug(`Authentication method: ${authenticationMethod}`);
+    this.log.debug(`Username: ${username}`);
+    this.log.debug(`Password provided: ${password !== ''}`);
+    this.log.debug(`Verification code provided: ${verificationCode !== ''}`);
+
+    // Authenticate using 2FA flow
+    let userData: UserData | undefined;
+    try {
+      if (authenticationMethod === 'VerificationCode') {
+        this.log.debug('Using verification code from config for authentication');
+        userData = await this.authenticate2FA(username, verificationCode);
+      } else {
+        userData = await this.authenticateWithPassword(username, password);
+      }
+    } catch (error) {
+      this.log.error(`Authentication failed: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
 
-        const savedUserData = (await this.persist.getItem('userData')) as UserData | undefined;
-        if (savedUserData) {
-          this.log.debug('Loading saved userData:', debugStringify(savedUserData));
-          return savedUserData;
-        }
-        return undefined;
-      },
-      async (userData: UserData) => {
-        await this.persist.setItem('userData', userData);
-      },
-    );
+    if (!userData) {
+      // Code was requested, waiting for user to enter it in config
+      return;
+    }
 
     this.log.debug('Initializing - userData:', debugStringify(userData));
     const devices = await this.roborockService.listDevices(username);
@@ -287,4 +307,113 @@ export class RoborockMatterbridgePlatform extends MatterbridgeDynamicPlatform {
     this.log.logLevel = logLevel;
     return Promise.resolve();
   }
+
+  private async authenticateWithPassword(username: string, password: string): Promise<UserData> {
+    if (!this.roborockService) {
+      throw new Error('RoborockService is not initialized');
+    }
+
+    this.log.notice('Attempting login with password...');
+
+    const userData = await this.roborockService.loginWithPassword(
+      username,
+      password,
+      async () => {
+        if (this.enableExperimentalFeature?.enableExperimentalFeature && this.enableExperimentalFeature.advancedFeature?.alwaysExecuteAuthentication) {
+          this.log.debug('Always execute authentication on startup');
+          return undefined;
+        }
+
+        const savedUserData = (await this.persist.getItem('userData')) as UserData | undefined;
+        if (savedUserData) {
+          this.log.debug('Loading saved userData:', debugStringify(savedUserData));
+          return savedUserData;
+        }
+        return undefined;
+      },
+      async (userData: UserData) => {
+        await this.persist.setItem('userData', userData);
+      },
+    );
+    this.log.notice('Authentication successful!');
+    return userData;
+  }
+
+  /**
+   * Authenticate using 2FA verification code flow
+   * @param username - The user's email address
+   * @param verificationCode - The verification code from config (if provided)
+   * @returns UserData on successful authentication, undefined if waiting for code
+   */
+  private async authenticate2FA(username: string, verificationCode: string | undefined): Promise<UserData | undefined> {
+    if (!this.roborockService) {
+      throw new Error('RoborockService is not initialized');
+    }
+
+    if (!this.enableExperimentalFeature?.advancedFeature?.alwaysExecuteAuthentication) {
+      const savedUserData = (await this.persist.getItem('userData')) as UserData | undefined;
+      if (savedUserData) {
+        this.log.debug('Found saved userData, attempting to use cached token');
+        try {
+          const userData = await this.roborockService.loginWithCachedToken(username, savedUserData);
+          this.log.notice('Successfully authenticated with cached token');
+          return userData;
+        } catch (error) {
+          this.log.warn(`Cached token invalid or expired: ${error instanceof Error ? error.message : String(error)}`);
+          await this.persist.removeItem('userData');
+          // Continue to request new code
+        }
+      }
+    }
+
+    if (!verificationCode || verificationCode.trim() === '') {
+      const authState = (await this.persist.getItem('authenticateFlowState')) as AuthenticateFlowState | undefined;
+      const now = Date.now();
+      const RATE_LIMIT_MS = 60000; // 1 minute between code requests
+
+      if (authState?.codeRequestedAt && now - authState.codeRequestedAt < RATE_LIMIT_MS) {
+        const waitSeconds = Math.ceil((RATE_LIMIT_MS - (now - authState.codeRequestedAt)) / 1000);
+        this.log.warn(`Please wait ${waitSeconds} seconds before requesting another code.`);
+        this.log.notice('============================================');
+        this.log.notice('ACTION REQUIRED: Enter verification code');
+        this.log.notice(`A verification code was previously sent to: ${username}`);
+        this.log.notice('Enter the 6-digit code in the plugin configuration');
+        this.log.notice('under the "verificationCode" field, then restart the plugin.');
+        this.log.notice('============================================');
+        return undefined;
+      }
+
+      try {
+        this.log.notice(`Requesting verification code for: ${username}`);
+        await this.roborockService.requestVerificationCode(username);
+
+        await this.persist.setItem('authenticateFlowState', {
+          email: username,
+          codeRequestedAt: now,
+        } as AuthenticateFlowState);
+
+        this.log.notice('============================================');
+        this.log.notice('ACTION REQUIRED: Enter verification code');
+        this.log.notice(`A verification code has been sent to: ${username}`);
+        this.log.notice('Enter the 6-digit code in the plugin configuration');
+        this.log.notice('under the "verificationCode" field, then restart the plugin.');
+        this.log.notice('============================================');
+      } catch (error) {
+        this.log.error(`Failed to request verification code: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+      }
+
+      return undefined;
+    }
+
+    this.log.notice('Attempting login with verification code...');
+
+    const userData = await this.roborockService.loginWithVerificationCode(username, verificationCode.trim(), async (data: UserData) => {
+      await this.persist.setItem('userData', data);
+      await this.persist.removeItem('authenticateFlowState');
+    });
+
+    this.log.notice('Authentication successful!');
+    return userData;
+  }
 }

package/src/roborockCommunication/RESTAPI/roborockAuthenticateApi.ts

@@ -6,6 +6,7 @@ import { AuthenticateResponse } from '../Zmodel/authenticateResponse.js';
 import { BaseUrl } from '../Zmodel/baseURL.js';
 import { HomeInfo } from '../Zmodel/homeInfo.js';
 import { UserData } from '../Zmodel/userData.js';
+import { AuthenticateResponseCode } from '../Zenum/authenticateResponseCode.js';
 
 export class RoborockAuthenticateApi {
   private readonly logger: AnsiLogger;
@@ -13,9 +14,13 @@ export class RoborockAuthenticateApi {
   private deviceId: string;
   private username?: string;
   private authToken?: string;
+  // Cached values from base URL lookup for v4 login
+  private cachedBaseUrl?: string;
+  private cachedCountry?: string;
+  private cachedCountryCode?: string;
 
-  constructor(logger: AnsiLogger, axiosFactory: AxiosStatic = axios) {
-    this.deviceId = crypto.randomUUID();
+  constructor(logger: AnsiLogger, axiosFactory: AxiosStatic = axios, deviceId?: string) {
+    this.deviceId = deviceId ?? crypto.randomUUID();
     this.axiosFactory = axiosFactory;
     this.logger = logger;
   }
@@ -25,6 +30,9 @@ export class RoborockAuthenticateApi {
     return userData;
   }
 
+  /**
+   * @deprecated Use requestCodeV4 and loginWithCodeV4 instead
+   */
   public async loginWithPassword(username: string, password: string): Promise<UserData> {
     const api = await this.getAPIFor(username);
     const response = await api.post(
@@ -38,6 +46,80 @@ export class RoborockAuthenticateApi {
     return this.auth(username, response.data);
   }
 
+  /**
+   * Request a verification code to be sent to the user's email
+   * @param email - The user's email address
+   * @throws Error if the account is not found, rate limited, or other API error
+   */
+  public async requestCodeV4(email: string): Promise<void> {
+    const api = await this.getAPIFor(email);
+    const response = await api.post(
+      'api/v4/email/code/send',
+      new URLSearchParams({
+        email: email,
+        type: 'login',
+        platform: '',
+      }),
+      {
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+      },
+    );
+
+    const apiResponse: AuthenticateResponse<unknown> = response.data;
+
+    if (apiResponse.code === AuthenticateResponseCode.AccountNotFound) {
+      throw new Error(`Account not found for email: ${email}`);
+    }
+    if (apiResponse.code === AuthenticateResponseCode.RateLimited) {
+      throw new Error('Rate limited. Please wait before requesting another code.');
+    }
+    if (apiResponse.code !== AuthenticateResponseCode.Success && apiResponse.code !== undefined) {
+      throw new Error(`Failed to send verification code: ${apiResponse.msg} (code: ${apiResponse.code})`);
+    }
+
+    this.logger.debug('Verification code requested successfully');
+  }
+
+  /**
+   * Login with a verification code received via email
+   * @param email - The user's email address
+   * @param code - The 6-digit verification code
+   * @returns UserData on successful authentication
+   * @throws Error if the code is invalid, rate limited, or other API error
+   */
+  public async loginWithCodeV4(email: string, code: string): Promise<UserData> {
+    const api = await this.getAPIFor(email);
+
+    // Generate x_mercy_ks (random 16-char alphanumeric string)
+    const xMercyKs = this.generateRandomString(16);
+
+    // Get signed key from API
+    const xMercyK = await this.signKeyV3(api, xMercyKs);
+
+    const response = await api.post('api/v4/auth/email/login/code', null, {
+      params: {
+        email: email,
+        code: code,
+        country: this.cachedCountry ?? '',
+        countryCode: this.cachedCountryCode ?? '',
+        majorVersion: '14',
+        minorVersion: '0',
+      },
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'x-mercy-ks': xMercyKs,
+        'x-mercy-k': xMercyK,
+        header_appversion: '4.54.02',
+        header_phonesystem: 'iOS',
+        header_phonemodel: 'iPhone16,1',
+      },
+    });
+
+    return this.authV4(email, response.data);
+  }
+
   public async getHomeDetails(): Promise<HomeInfo | undefined> {
     if (!this.username || !this.authToken) {
       return undefined;
@@ -53,12 +135,26 @@ export class RoborockAuthenticateApi {
     return apiResponse.data;
   }
 
+  /**
+   * Get cached country info from the last base URL lookup
+   */
+  public getCachedCountryInfo(): { country?: string; countryCode?: string } {
+    return {
+      country: this.cachedCountry,
+      countryCode: this.cachedCountryCode,
+    };
+  }
+
   private async getAPIFor(username: string): Promise<AxiosInstance> {
     const baseUrl = await this.getBaseUrl(username);
     return this.apiForUser(username, baseUrl);
   }
 
   private async getBaseUrl(username: string): Promise<string> {
+    if (this.cachedBaseUrl && this.username === username) {
+      return this.cachedBaseUrl;
+    }
+
     const api = await this.apiForUser(username);
     const response = await api.post(
       'api/v1/getUrlByEmail',
@@ -73,17 +169,49 @@ export class RoborockAuthenticateApi {
       throw new Error('Failed to retrieve base URL: ' + apiResponse.msg);
     }
 
+    this.cachedBaseUrl = apiResponse.data.url;
+    this.cachedCountry = apiResponse.data.country;
+    this.cachedCountryCode = apiResponse.data.countrycode;
+    this.username = username;
+
     return apiResponse.data.url;
   }
 
   private async apiForUser(username: string, baseUrl = 'https://usiot.roborock.com'): Promise<AxiosInstance> {
-    return this.axiosFactory.create({
+    const instance = this.axiosFactory.create({
       baseURL: baseUrl,
       headers: {
         header_clientid: crypto.createHash('md5').update(username).update(this.deviceId).digest('base64'),
         Authorization: this.authToken,
+        header_clientlang: 'en',
       },
     });
+
+    instance.interceptors.request.use((config) => {
+      this.logger.debug('=== HTTP Request ===');
+      this.logger.debug(`URL: ${config.baseURL}/${config.url}`);
+      this.logger.debug(`Method: ${config.method?.toUpperCase()}`);
+      this.logger.debug(`Params: ${JSON.stringify(config.params)}`);
+      this.logger.debug(`Data: ${JSON.stringify(config.data)}`);
+      this.logger.debug(`Headers: ${JSON.stringify(config.headers)}`);
+      return config;
+    });
+
+    instance.interceptors.response.use(
+      (response) => {
+        this.logger.debug('=== HTTP Response ===');
+        this.logger.debug(`Status: ${response.status}`);
+        this.logger.debug(`Data: ${JSON.stringify(response.data)}`);
+        return response;
+      },
+      (error) => {
+        this.logger.debug('=== HTTP Error ===');
+        this.logger.debug(`Error: ${JSON.stringify(error.response?.data ?? error.message)}`);
+        return Promise.reject(error);
+      },
+    );
+
+    return instance;
   }
 
   private auth(username: string, response: AuthenticateResponse<UserData>): UserData {
@@ -96,8 +224,57 @@ export class RoborockAuthenticateApi {
     return userdata;
   }
 
+  /**
+   * Handle v4 authentication response with specific error code handling
+   */
+  private authV4(email: string, response: AuthenticateResponse<UserData>): UserData {
+    if (response.code === AuthenticateResponseCode.InvalidCode) {
+      throw new Error('Invalid verification code. Please check and try again.');
+    }
+    if (response.code === AuthenticateResponseCode.RateLimited) {
+      throw new Error('Rate limited. Please wait before trying again.');
+    }
+
+    const userdata = response.data;
+    if (!userdata || !userdata.token) {
+      throw new Error('Authentication failed: ' + response.msg + ' code: ' + response.code);
+    }
+
+    this.loginWithAuthToken(email, userdata.token);
+    return userdata;
+  }
+
   private loginWithAuthToken(username: string, token: string): void {
     this.username = username;
     this.authToken = token;
   }
+
+  /**
+   * Generate a random alphanumeric string of specified length
+   */
+  private generateRandomString(length: number): string {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    const randomBytes = crypto.randomBytes(length);
+    for (let i = 0; i < length; i++) {
+      result += chars[randomBytes[i] % chars.length];
+    }
+    return result;
+  }
+
+  /**
+   * Sign a key using the v3 API endpoint
+   */
+  private async signKeyV3(api: AxiosInstance, s: string): Promise<string> {
+    const response = await api.post('api/v3/key/sign', null, {
+      params: { s },
+    });
+
+    const apiResponse: AuthenticateResponse<{ k: string }> = response.data;
+    if (!apiResponse.data?.k) {
+      throw new Error('Failed to sign key: ' + apiResponse.msg);
+    }
+
+    return apiResponse.data.k;
+  }
 }

package/src/roborockCommunication/Zenum/authenticateResponseCode.ts

@@ -0,0 +1,6 @@
+export enum AuthenticateResponseCode {
+  Success = 200,
+  AccountNotFound = 2008,
+  InvalidCode = 2018,
+  RateLimited = 9002,
+}

package/src/roborockCommunication/Zmodel/authenticateFlowState.ts

@@ -0,0 +1,6 @@
+export interface AuthenticateFlowState {
+  email: string;
+  codeRequestedAt?: number;
+  country?: string;
+  countryCode?: string;
+}

package/src/roborockCommunication/index.ts

@@ -9,6 +9,7 @@ export { DeviceStatus } from './Zmodel/deviceStatus.js';
 export { ResponseMessage } from './broadcast/model/responseMessage.js';
 export { MapInfo } from './Zmodel/mapInfo.js';
 export { AdditionalPropCode } from './Zenum/additionalPropCode.js';
+export { AuthenticateResponseCode } from './Zenum/authenticateResponseCode.js';
 
 export { Scene } from './Zmodel/scene.js';
 
@@ -21,3 +22,4 @@ export type { Client } from './broadcast/client.js';
 export type { SceneParam } from './Zmodel/scene.js';
 export type { BatteryMessage, DeviceErrorMessage, DeviceStatusNotify } from './Zmodel/batteryMessage.js';
 export type { MultipleMap } from './Zmodel/multipleMap.js';
+export type { AuthenticateFlowState } from './Zmodel/authenticateFlowState.js';

package/src/roborockService.ts

@@ -77,6 +77,9 @@ export default class RoborockService {
     this.clientManager = clientManager;
   }
 
+  /**
+   * @deprecated Use requestVerificationCode and loginWithVerificationCode instead
+   */
   public async loginWithPassword(
     username: string,
     password: string,
@@ -97,6 +100,38 @@ export default class RoborockService {
     return this.auth(userdata);
   }
 
+  /**
+   * Request a verification code to be sent to the user's email
+   * @param email - The user's email address
+   */
+  public async requestVerificationCode(email: string): Promise<void> {
+    return this.loginApi.requestCodeV4(email);
+  }
+
+  /**
+   * Login with a verification code received via email
+   * @param email - The user's email address
+   * @param code - The 6-digit verification code
+   * @param savedUserData - Callback to save the user data after successful login
+   * @returns UserData on successful authentication
+   */
+  public async loginWithVerificationCode(email: string, code: string, savedUserData: (userData: UserData) => Promise<void>): Promise<UserData> {
+    const userdata = await this.loginApi.loginWithCodeV4(email, code);
+    await savedUserData(userdata);
+    return this.auth(userdata);
+  }
+
+  /**
+   * Login with cached user data (token reuse)
+   * @param username - The user's email address
+   * @param userData - The cached user data with token
+   * @returns UserData on successful validation
+   */
+  public async loginWithCachedToken(username: string, userData: UserData): Promise<UserData> {
+    const validatedUserData = await this.loginApi.loginWithUserData(username, userData);
+    return this.auth(validatedUserData);
+  }
+
   public getMessageProcessor(duid: string): MessageProcessor | undefined {
     const messageProcessor = this.messageProcessorMap.get(duid);
     if (!messageProcessor) {

package/src/tests/roborockCommunication/RESTAPI/roborockAuthenticateApi.test.ts

@@ -11,6 +11,14 @@ describe('RoborockAuthenticateApi', () => {
     mockAxiosInstance = {
       post: jest.fn(),
       get: jest.fn(),
+      interceptors: {
+        request: {
+          use: jest.fn(),
+        },
+        response: {
+          use: jest.fn(),
+        },
+      },
     };
     mockAxiosFactory = {
       create: jest.fn(() => mockAxiosInstance),