meross-iot 0.1.0

package/lib/controller/features/encryption-feature.js

@@ -0,0 +1,259 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Default initialization vector (IV) for AES encryption.
+ *
+ * Meross devices require a zero-filled IV rather than a random IV. This is a
+ * protocol requirement that must be followed for compatibility with Meross firmware.
+ *
+ * @constant {Buffer}
+ * @private
+ */
+const DEFAULT_IV = Buffer.from('0000000000000000', 'utf8');
+
+/**
+ * Derives the encryption key from device UUID, Meross key, and MAC address.
+ *
+ * The Meross protocol requires a specific key derivation algorithm that combines
+ * portions of the device UUID, Meross cloud key, and MAC address. The specific
+ * substring ranges used here match the Meross firmware implementation.
+ *
+ * MD5 is used because it's part of the Meross protocol specification, despite
+ * being cryptographically weak. The hex digest is encoded as UTF-8 bytes to
+ * produce a 32-byte key suitable for AES-256-CBC encryption.
+ *
+ * @param {string} uuid - Device UUID (full UUID string)
+ * @param {string} mrskey - Meross cloud key (from device configuration)
+ * @param {string} mac - Device MAC address
+ * @returns {Buffer} 32-byte encryption key (MD5 hex string encoded as UTF-8 bytes) for AES-256-CBC
+ * @private
+ */
+function _deriveEncryptionKey(uuid, mrskey, mac) {
+    const strtohash = uuid.substring(3, 22) +
+                     mrskey.substring(1, 9) +
+                     mac +
+                     mrskey.substring(10, 28);
+    const hash = crypto.createHash('md5').update(strtohash).digest('hex');
+    return Buffer.from(hash, 'utf8');
+}
+
+/**
+ * Pads data to 16-byte blocks with zero bytes.
+ *
+ * AES encryption requires data to be aligned to 16-byte block boundaries.
+ * Meross devices use zero padding rather than standard PKCS7 padding, so
+ * zero bytes are appended until the data length is a multiple of 16.
+ *
+ * @param {Buffer} data - Data to pad
+ * @returns {Buffer} Padded data aligned to 16-byte blocks
+ * @private
+ */
+function _padTo16Bytes(data) {
+    const blockSize = 16;
+    const padLength = blockSize - (data.length % blockSize);
+    const padding = Buffer.alloc(padLength, 0);
+    return Buffer.concat([data, padding]);
+}
+
+/**
+ * Encrypts message data using AES-256-CBC encryption.
+ *
+ * Encrypts message data for communication with Meross devices. The data is padded
+ * to 16-byte blocks using zero padding, then encrypted with AES-256-CBC using a
+ * zero-filled IV. Auto-padding is disabled because manual zero padding is used
+ * instead of the default PKCS7 padding.
+ *
+ * @param {Buffer|string} messageData - Message data to encrypt. Can be a Buffer or a JSON string.
+ * @param {Buffer} key - 32-byte encryption key (MD5 hex string encoded as UTF-8).
+ * @returns {string} Base64-encoded encrypted message
+ * @private
+ */
+function _encrypt(messageData, key) {
+    let dataBuffer;
+    if (typeof messageData === 'string') {
+        dataBuffer = Buffer.from(messageData, 'utf8');
+    } else {
+        dataBuffer = messageData;
+    }
+
+    const paddedData = _padTo16Bytes(dataBuffer);
+
+    const cipher = crypto.createCipheriv('aes-256-cbc', key, DEFAULT_IV);
+    cipher.setAutoPadding(false);
+
+    let encrypted = cipher.update(paddedData);
+    encrypted = Buffer.concat([encrypted, cipher.final()]);
+
+    return encrypted.toString('base64');
+}
+
+/**
+ * Decrypts encrypted message data using AES-256-CBC decryption.
+ *
+ * Decrypts message data received from Meross devices. The data is decoded from
+ * base64, decrypted using AES-256-CBC with a zero-filled IV, and zero padding
+ * is removed from the result. Auto-padding is disabled because manual zero padding
+ * removal is required instead of standard PKCS7 unpadding.
+ *
+ * @param {string|Buffer} encryptedData - Base64-encoded encrypted data (as string) or encrypted Buffer
+ * @param {Buffer} key - 32-byte encryption key (MD5 hex string encoded as UTF-8).
+ * @returns {Buffer} Decrypted data as Buffer
+ * @private
+ */
+function _decrypt(encryptedData, key) {
+    let encryptedBuffer;
+    if (typeof encryptedData === 'string') {
+        encryptedBuffer = Buffer.from(encryptedData, 'base64');
+    } else {
+        encryptedBuffer = encryptedData;
+    }
+
+    const decipher = crypto.createDecipheriv('aes-256-cbc', key, DEFAULT_IV);
+    decipher.setAutoPadding(false);
+
+    let decrypted = decipher.update(encryptedBuffer);
+    decrypted = Buffer.concat([decrypted, decipher.final()]);
+
+    // Remove zero padding by finding the last non-zero byte
+    let result = decrypted;
+    let lastNonZero = result.length - 1;
+    while (lastNonZero >= 0 && result[lastNonZero] === 0) {
+        lastNonZero--;
+    }
+    if (lastNonZero < result.length - 1) {
+        result = result.slice(0, lastNonZero + 1);
+    }
+
+    return result;
+}
+
+/**
+ * Encryption feature module.
+ * Handles encryption key management and message encryption/decryption for devices that support it.
+ */
+module.exports = {
+    /**
+     * Initializes encryption support state.
+     *
+     * Called during device construction or when abilities are updated to ensure encryption
+     * state variables are properly initialized.
+     *
+     * @private
+     */
+    _initializeEncryption() {
+        if (this._encryptionKey === undefined) {
+            this._encryptionKey = null;
+        }
+        if (this._supportsEncryption === undefined) {
+            this._supportsEncryption = false;
+        }
+    },
+
+    /**
+     * Checks if the device supports encryption.
+     *
+     * Encryption support is automatically detected from device abilities when abilities are updated.
+     *
+     * @returns {boolean} True if device supports encryption, false otherwise
+     */
+    supportEncryption() {
+        this._initializeEncryption();
+        return this._supportsEncryption;
+    },
+
+    /**
+     * Checks if the encryption key has been set for this device.
+     *
+     * @returns {boolean} True if encryption key is set, false otherwise
+     * @see setEncryptionKey
+     */
+    isEncryptionKeySet() {
+        this._initializeEncryption();
+        return this._encryptionKey !== null;
+    },
+
+    /**
+     * Sets the encryption key for this device.
+     *
+     * The encryption key is derived from the device UUID, Meross key, and MAC address using
+     * a device-specific algorithm. This is typically called automatically when encryption
+     * support is detected and all required data is available.
+     *
+     * @param {string} uuid - Device UUID
+     * @param {string} mrskey - Meross key from cloud instance
+     * @param {string} mac - Device MAC address
+     */
+    setEncryptionKey(uuid, mrskey, mac) {
+        this._initializeEncryption();
+        this._encryptionKey = _deriveEncryptionKey(uuid, mrskey, mac);
+        this._macAddress = mac;
+    },
+
+    /**
+     * Encrypts a message using the device's encryption key.
+     *
+     * @param {Object|string|Buffer} messageData - Message data to encrypt
+     * @returns {string} Base64-encoded encrypted message
+     * @throws {import('../../model/exception').CommandError} If encryption key is not set
+     * @see decryptMessage
+     * @see isEncryptionKeySet
+     */
+    encryptMessage(messageData) {
+        if (!this.isEncryptionKeySet()) {
+            const { CommandError } = require('../../model/exception');
+            throw new CommandError('Encryption key is not set! Please invoke setEncryptionKey first.', null, this.uuid);
+        }
+        return _encrypt(messageData, this._encryptionKey);
+    },
+
+    /**
+     * Decrypts an encrypted message using the device's encryption key.
+     *
+     * @param {string|Buffer} encryptedData - Encrypted message data to decrypt
+     * @returns {Buffer} Decrypted message data
+     * @throws {import('../../model/exception').CommandError} If encryption key is not set
+     * @see encryptMessage
+     * @see isEncryptionKeySet
+     */
+    decryptMessage(encryptedData) {
+        if (!this.isEncryptionKeySet()) {
+            const { CommandError } = require('../../model/exception');
+            throw new CommandError('Encryption key is not set! Please invoke setEncryptionKey first.', null, this.uuid);
+        }
+        return _decrypt(encryptedData, this._encryptionKey);
+    },
+
+    /**
+     * Updates device abilities and detects encryption support.
+     *
+     * Checks for the Appliance.Encrypt.ECDHE namespace in abilities to determine if
+     * the device supports encryption.
+     *
+     * @param {Object} abilities - Device abilities object
+     * @private
+     */
+    _updateAbilitiesWithEncryption(abilities) {
+        this._initializeEncryption();
+        this._abilities = abilities;
+        this._supportsEncryption = abilities && typeof abilities === 'object' &&
+                                   'Appliance.Encrypt.ECDHE' in abilities;
+    },
+
+    /**
+     * Updates MAC address and automatically sets encryption key if conditions are met.
+     *
+     * If encryption is supported, the key is not yet set, and all required data (MAC address,
+     * cloud instance key) is available, the encryption key is automatically derived and set.
+     *
+     * @param {string} mac - Device MAC address
+     * @private
+     */
+    _updateMacAddressWithEncryption(mac) {
+        this._macAddress = mac;
+        if (this._supportsEncryption && !this.isEncryptionKeySet() && this._macAddress && this.cloudInst && this.cloudInst.key) {
+            this.setEncryptionKey(this.uuid, this.cloudInst.key, this._macAddress);
+        }
+    }
+};

package/lib/controller/features/garage-feature.js

@@ -0,0 +1,337 @@
+'use strict';
+
+const GarageDoorState = require('../../model/states/garage-door-state');
+const { normalizeChannel } = require('../../utilities/options');
+
+/**
+ * Garage door feature module.
+ * Provides control over garage door open/close state and configuration settings.
+ */
+module.exports = {
+    /**
+     * Controls the garage door state (open/close).
+     *
+     * Automatically includes the device UUID in the payload.
+     *
+     * @param {Object} options - Garage door options
+     * @param {number} [options.channel=0] - Channel to control (default: 0)
+     * @param {boolean} options.open - True to open, false to close
+     * @returns {Promise<Object>} Response from the device containing the updated state
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setGarageDoor(options = {}) {
+        if (options.open === undefined) {
+            throw new Error('open is required');
+        }
+        const channel = normalizeChannel(options);
+        const payload = { 'state': { channel, 'open': options.open ? 1 : 0, 'uuid': this.uuid } };
+        const response = await this.publishMessage('SET', 'Appliance.GarageDoor.State', payload);
+
+        if (response && response.state) {
+            this._updateGarageDoorState(response.state, 'response');
+            this._lastFullUpdateTimestamp = Date.now();
+        } else {
+            this._updateGarageDoorState([{ channel, open: options.open ? 1 : 0 }], 'response');
+            this._lastFullUpdateTimestamp = Date.now();
+        }
+
+        return response;
+    },
+
+    /**
+     * Gets the current garage door state from the device.
+     *
+     * Use {@link getCachedGarageDoorState} to get cached state without making a request.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to get state for (default: 0, use 0xffff for all channels)
+     * @returns {Promise<Object>} Response containing garage door state with `state` array
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getGarageDoorState(options = {}) {
+        const channel = normalizeChannel(options);
+        const payload = { 'state': { channel } };
+        const response = await this.publishMessage('GET', 'Appliance.GarageDoor.State', payload);
+        if (response && response.state) {
+            this._updateGarageDoorState(response.state, 'response');
+            this._lastFullUpdateTimestamp = Date.now();
+        }
+        return response;
+    },
+
+    /**
+     * Gets the garage door multiple configuration state.
+     *
+     * Retrieves configuration for all channels. Use {@link getGarageDoorConfig} (getter) to get
+     * cached configuration for a specific channel.
+     * @param {Object} [options={}] - Get options
+     * @returns {Promise<Object>} Response containing garage door config with `config` array
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getGarageDoorMultipleState(_options = {}) {
+        const response = await this.publishMessage('GET', 'Appliance.GarageDoor.MultipleConfig', {});
+        if (response && response.config) {
+            this._updateGarageDoorConfig(response.config);
+            this._lastFullUpdateTimestamp = Date.now();
+        }
+        return response;
+    },
+
+    /**
+     * Gets the garage door multiple configuration (alias for getGarageDoorMultipleState).
+     *
+     * @param {Object} [options={}] - Get options
+     * @see getGarageDoorMultipleState
+     * @returns {Promise<Object>} Response containing garage door config with `config` array
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getGarageDoorMultipleConfig(_options = {}) {
+        return await this.getGarageDoorMultipleState(_options);
+    },
+
+    /**
+     * Gets the garage door configuration from the device.
+     *
+     * Note: This method name conflicts with the getter method {@link getGarageDoorConfig} that
+     * returns cached config. Use {@link getGarageDoorMultipleState} to get config from device.
+     * @param {Object} [options={}] - Get options
+     * @returns {Promise<Object>} Response containing garage door configuration
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getGarageDoorConfig(_options = {}) {
+        return await this.publishMessage('GET', 'Appliance.GarageDoor.Config', {});
+    },
+
+    /**
+     * Controls the garage door configuration.
+     *
+     * @param {Object} options - Garage door config options
+     * @param {Object} [options.configData] - Configuration data object (if provided, used directly)
+     * @param {number} [options.signalDuration] - Signal duration in milliseconds
+     * @param {boolean} [options.buzzerEnable] - Enable/disable buzzer
+     * @param {number} [options.doorOpenDuration] - Door open duration in milliseconds
+     * @param {number} [options.doorCloseDuration] - Door close duration in milliseconds
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setGarageDoorConfig(options = {}) {
+        let configData;
+        if (options.configData) {
+            configData = options.configData;
+        } else {
+            configData = {
+                signalDuration: options.signalDuration,
+                buzzerEnable: options.buzzerEnable,
+                doorOpenDuration: options.doorOpenDuration,
+                doorCloseDuration: options.doorCloseDuration
+            };
+            // Remove undefined values
+            Object.keys(configData).forEach(key => {
+                if (configData[key] === undefined) {
+                    delete configData[key];
+                }
+            });
+        }
+        const payload = { config: configData };
+        return await this.publishMessage('SET', 'Appliance.GarageDoor.Config', payload);
+    },
+
+    /**
+     * Gets the cached garage door state for the specified channel.
+     *
+     * Returns cached state without making a request. Use {@link getGarageDoorState} to fetch
+     * fresh state from the device. State is automatically updated when commands are sent or
+     * push notifications are received.
+     *
+     * @param {number} [channel=0] - Channel to get state for (default: 0)
+     * @returns {import('../lib/model/states/garage-door-state').GarageDoorState|undefined} Cached garage door state or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     */
+    getCachedGarageDoorState(channel = 0) {
+        this.validateState();
+        return this._garageDoorStateByChannel.get(channel);
+    },
+
+    /**
+     * Checks if the garage door is opened for the specified channel.
+     *
+     * Uses cached state. Ensure state is initialized with {@link refreshState} first.
+     *
+     * @param {number} [channel=0] - Channel to check (default: 0)
+     * @returns {boolean|undefined} True if open, false if closed, undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     * @see isGarageDoorClosed
+     */
+    isGarageDoorOpened(channel = 0) {
+        this.validateState();
+        const state = this._garageDoorStateByChannel.get(channel);
+        if (state) {
+            return state.isOpen;
+        }
+        return undefined;
+    },
+
+    /**
+     * Checks if the garage door is closed for the specified channel.
+     *
+     * Uses cached state. Ensure state is initialized with {@link refreshState} first.
+     *
+     * @param {number} [channel=0] - Channel to check (default: 0)
+     * @returns {boolean|undefined} True if closed, false if open, undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     * @see isGarageDoorOpened
+     */
+    isGarageDoorClosed(channel = 0) {
+        this.validateState();
+        const isOpen = this.isGarageDoorOpened(channel);
+        if (isOpen === undefined) {
+            return undefined;
+        }
+        return !isOpen;
+    },
+
+    /**
+     * Gets the garage door configuration for the specified channel (cached).
+     *
+     * Returns cached configuration without making a request. Use {@link getGarageDoorMultipleState}
+     * to fetch fresh configuration from the device.
+     *
+     * @param {number} [channel=0] - Channel to get config for (default: 0)
+     * @returns {Object|undefined} Garage door config or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     */
+    getGarageDoorConfig(channel = 0) {
+        this.validateState();
+        return this._garageDoorConfigByChannel.get(channel);
+    },
+
+    /**
+     * Opens the garage door for the specified channel.
+     *
+     * Convenience method that calls {@link setGarageDoor} with `open = true`.
+     *
+     * @param {Object} [options={}] - Open options
+     * @param {number} [options.channel=0] - Channel to control (default: 0)
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     * @see closeGarageDoor
+     * @see toggleGarageDoor
+     */
+    async openGarageDoor(options = {}) {
+        return await this.setGarageDoor({ ...options, open: true });
+    },
+
+    /**
+     * Closes the garage door for the specified channel.
+     *
+     * Convenience method that calls {@link setGarageDoor} with `open = false`.
+     *
+     * @param {Object} [options={}] - Close options
+     * @param {number} [options.channel=0] - Channel to control (default: 0)
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     * @see openGarageDoor
+     * @see toggleGarageDoor
+     */
+    async closeGarageDoor(options = {}) {
+        return await this.setGarageDoor({ ...options, open: false });
+    },
+
+    /**
+     * Toggles the garage door state for the specified channel.
+     *
+     * Opens if closed, closes if open. Uses cached state to determine current state.
+     *
+     * @param {Object} [options={}] - Toggle options
+     * @param {number} [options.channel=0] - Channel to control (default: 0)
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     * @see openGarageDoor
+     * @see closeGarageDoor
+     */
+    async toggleGarageDoor(options = {}) {
+        const channel = normalizeChannel(options);
+        const isOpen = this.isGarageDoorOpened(channel);
+        const newState = isOpen === true ? false : true;
+        return await this.setGarageDoor({ channel, open: newState });
+    },
+
+    /**
+     * Updates the cached garage door state from state data.
+     *
+     * Called automatically when garage door push notifications are received or commands complete.
+     * Handles both single objects and arrays of state data.
+     *
+     * @param {Object|Array} stateData - State data (single object or array)
+     * @param {string} [source='response'] - Source of the update ('push' | 'poll' | 'response')
+     * @private
+     */
+    _updateGarageDoorState(stateData, source = 'response') {
+        if (!stateData) {return;}
+
+        const stateArray = Array.isArray(stateData) ? stateData : [stateData];
+
+        for (const stateItem of stateArray) {
+            const channelIndex = stateItem.channel;
+            if (channelIndex === undefined || channelIndex === null) {continue;}
+
+            const oldState = this._garageDoorStateByChannel.get(channelIndex);
+            const oldValue = oldState ? {
+                isOpen: oldState.isOpen
+            } : undefined;
+
+            let state = this._garageDoorStateByChannel.get(channelIndex);
+            if (!state) {
+                state = new GarageDoorState(stateItem);
+                this._garageDoorStateByChannel.set(channelIndex, state);
+            } else {
+                state.update(stateItem);
+            }
+
+            const newValue = { isOpen: state.isOpen };
+            if (oldValue === undefined || oldValue.isOpen !== state.isOpen) {
+                this.emit('stateChange', {
+                    type: 'garageDoor',
+                    channel: channelIndex,
+                    value: newValue,
+                    oldValue,
+                    source,
+                    timestamp: Date.now()
+                });
+            }
+        }
+    },
+
+    /**
+     * Updates the cached garage door configuration from config data.
+     *
+     * Called automatically when garage door configuration responses are received.
+     * Handles both single objects and arrays of config data.
+     *
+     * @param {Object|Array} configData - Config data (single object or array)
+     * @private
+     */
+    _updateGarageDoorConfig(configData) {
+        if (!configData) {return;}
+
+        const configArray = Array.isArray(configData) ? configData : [configData];
+
+        for (const configItem of configArray) {
+            const channelIndex = configItem.channel;
+            if (channelIndex === undefined || channelIndex === null) {continue;}
+
+            this._garageDoorConfigByChannel.set(channelIndex, configItem);
+        }
+    }
+};
+