homey-lib 2.45.4 → 2.46.1

package/assets/app/schema.d.ts

@@ -80,6 +80,7 @@ export type DriverSettings = (
       [k: string]: unknown;
     }
 )[];
+export type Integrity = string;
 export type AppSettings = (
   | {
       type: "text" | "password" | "textarea" | "label";
@@ -247,6 +248,7 @@ export interface App {
       [k: string]: unknown;
     }[];
     settings?: DriverSettings;
+    firmwareUpdates?: ZigbeeFirmwareUpdates;
     gtin?: string | string[];
     matter?: MatterDevice;
     zwave?: ZwaveDevice;
@@ -373,6 +375,43 @@ export interface ZwaveSetting {
   signed?: boolean;
   [k: string]: unknown;
 }
+export interface ZigbeeFirmwareUpdates {
+  queryNextImageTimeout?: number;
+  minImageBlockPeriod?: number;
+  maxImageBlockSize?: number;
+  imageBlockRequestTimeout?: number;
+  upgradeEndRequestTimeout?: number;
+  upgradeEndDelay?: number;
+  postUpgradeAnnounceTimeout?: number;
+  /**
+   * @minItems 1
+   */
+  updates: [ZigbeeFirmwareUpdate, ...ZigbeeFirmwareUpdate[]];
+}
+export interface ZigbeeFirmwareUpdate {
+  changelog: I18NObject;
+  device: ZigbeeFirmwareUpdateDevice;
+  /**
+   * @minItems 1
+   */
+  files: [ZigbeeFirmwareUpdateFile, ...ZigbeeFirmwareUpdateFile[]];
+}
+export interface ZigbeeFirmwareUpdateDevice {
+  manufacturerName: string | string[];
+  productId: string | string[];
+}
+export interface ZigbeeFirmwareUpdateFile {
+  fileVersion: number;
+  imageType: number;
+  manufacturerCode: number;
+  minFileVersion?: number;
+  maxFileVersion?: number;
+  minHardwareVersion?: number;
+  maxHardwareVersion?: number;
+  size: number;
+  name: string;
+  integrity: Integrity;
+}
 export interface MatterDevice {
   vendorId: number | number[];
   productId: number | number[];

package/assets/app/schema.json

@@ -32,6 +32,135 @@
       },
       "additionalProperties": false
     },
+    "integrity": {
+      "type": "string",
+      "pattern": "^(blake2b512|blake2s256|sha256|sha384|sha512|sha512-256|sha3-256|sha3-384|sha3-512):[0-9a-fA-F]+$"
+    },
+    "zigbee-firmware-update-device": {
+      "type": "object",
+      "required": ["manufacturerName", "productId"],
+      "additionalProperties": false,
+      "properties": {
+        "manufacturerName": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "productId": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        }
+      }
+    },
+    "zigbee-firmware-update-file": {
+      "type": "object",
+      "required": ["fileVersion", "size", "imageType", "manufacturerCode", "name", "integrity"],
+      "additionalProperties": false,
+      "properties": {
+        "fileVersion": {
+          "type": "number"
+        },
+        "imageType": {
+          "type": "number"
+        },
+        "manufacturerCode": {
+          "type": "number"
+        },
+        "minFileVersion": {
+          "type": "number"
+        },
+        "maxFileVersion": {
+          "type": "number"
+        },
+        "minHardwareVersion": {
+          "type": "number"
+        },
+        "maxHardwareVersion": {
+          "type": "number"
+        },
+        "size": {
+          "type": "number"
+        },
+        "name": {
+          "type": "string"
+        },
+        "integrity": {
+          "$ref": "#/definitions/integrity"
+        }
+      }
+    },
+    "zigbee-firmware-update": {
+      "type": "object",
+      "required": ["changelog", "device", "files"],
+      "additionalProperties": false,
+      "properties": {
+        "changelog": {
+          "$ref": "#/definitions/i18nObject"
+        },
+        "device": {
+          "$ref": "#/definitions/zigbee-firmware-update-device"
+        },
+        "files": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/zigbee-firmware-update-file"
+          }
+        }
+      }
+    },
+    "zigbee-firmware-updates": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["updates"],
+      "properties": {
+        "queryNextImageTimeout": {
+          "type": "number"
+        },
+        "minImageBlockPeriod": {
+          "type": "number"
+        },
+        "maxImageBlockSize": {
+          "type": "number"
+        },
+        "imageBlockRequestTimeout": {
+          "type": "number"
+        },
+        "upgradeEndRequestTimeout": {
+          "type": "number"
+        },
+        "upgradeEndDelay": {
+          "type": "number"
+        },
+        "postUpgradeAnnounceTimeout": {
+          "type": "number"
+        },
+        "updates": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/zigbee-firmware-update"
+          }
+        }
+      }
+    },
     "author": {
       "required": ["name"],
       "properties": {
@@ -1316,6 +1445,13 @@
           "settings": {
             "$ref": "#/definitions/driverSettings"
           },
+          "firmwareUpdates": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/zigbee-firmware-updates"
+              }
+            ]
+          },
           "gtin": {
             "oneOf": [
               {

package/helpers/index.js

@@ -38,3 +38,13 @@ try {
   }
 } catch (err) {
 }
+
+function toArray(value) {
+  if (value) {
+    return Array.isArray(value) ? value : [value];
+  }
+
+  return [];
+}
+
+module.exports.toArray = toArray;

package/index.js

@@ -47,3 +47,4 @@ module.exports.getBatteries = Energy.getBatteries.bind(Energy);
 
 /** @typedef {import('./assets/app/schema').App} AppManifest */
 /** @typedef {import('./assets/capability/schema').Capability} CapabilityDefinition */
+/** @typedef {import('./assets/app/schema').ZigbeeFirmwareUpdates} ZigbeeFirmwareUpdates */

package/lib/App/index.js

@@ -14,6 +14,7 @@ const Device = require('../Device');
 const Capability = require('../Capability');
 const Signal = require('../Signal');
 const Energy = require('../Energy');
+const Util = require('../Util');
 
 const {
   openAsync,
@@ -28,6 +29,7 @@ const {
   extname,
   basename,
   dirname,
+  toArray,
 } = require('../../helpers');
 
 /** @typedef {import('../../assets/app/schema').App} AppManifest */
@@ -384,32 +386,29 @@ class App {
         // validate `appJson.drivers[].capabilitiesOptions`
         if (driver.capabilitiesOptions) {
           for (const [capabilityId, capabilityOptions] of Object.entries(driver.capabilitiesOptions)) {
-            // Merge canonical + extra values for target_power_mode - canonical always present, extras appended
-            if (Capability.isInstanceOfId(capabilityId, 'target_power_mode')) {
+            // Validate target_power_mode values - check canonical IDs present, no reserved prefixes
+            if (Capability.isInstanceOfId(capabilityId, 'target_power_mode') && Array.isArray(capabilityOptions.values)) {
               const canonicalValues = Capability.getCapability('target_power_mode').values;
-              const providedValues = Array.isArray(capabilityOptions.values) ? capabilityOptions.values : [];
 
-              const seenIds = new Set(canonicalValues.map(canonical => canonical.id));
-              const extraValues = [];
-
-              for (const value of providedValues) {
-                if (!value || typeof value !== 'object' || typeof value.id !== 'string') continue;
-                if (seenIds.has(value.id)) continue;
-                seenIds.add(value.id);
-                extraValues.push(value);
+              for (const canonical of canonicalValues) {
+                const provided = capabilityOptions.values.find(v => v && typeof v === 'object' && v.id === canonical.id);
+                if (!provided) {
+                  throw new Error(`drivers.${driver.id}.capabilitiesOptions.${capabilityId}.values must include canonical value "${canonical.id}"`);
+                }
               }
 
-              const RESERVED_PREFIXES = ['homey_', 'device_'];
+              const canonicalIds = new Set(canonicalValues.map(v => v.id));
+              const extraValues = capabilityOptions.values.filter(v => v && typeof v === 'object' && typeof v.id === 'string' && !canonicalIds.has(v.id));
+
+              const RESERVED_PREFIXES = ['homey_'];
               const reservedValues = extraValues.filter(value =>
                 RESERVED_PREFIXES.some(prefix => value.id.startsWith(prefix))
               );
 
               if (reservedValues.length) {
                 const ids = reservedValues.map(value => value.id).join(', ');
-                throw new Error(`drivers.${driver.id}.capabilitiesOptions.${capabilityId} custom values cannot use reserved prefixes "homey_" or "device_": ${ids}`);
+                throw new Error(`drivers.${driver.id}.capabilitiesOptions.${capabilityId}.values custom values cannot use reserved prefix "homey_": ${ids}`);
               }
-
-              capabilityOptions.values = [...canonicalValues, ...extraValues];
             }
 
             // validate target_power exclude range must include 0
@@ -644,6 +643,88 @@ class App {
         if (driver.matter && !(driver.connectivity && driver.connectivity.includes('matter'))) {
           throw new Error(`drivers.${driver.id} Matter drivers require 'connectivity' to include 'matter'.`);
         }
+
+        // Validate driver.firmwareUpdates
+        if (driver.firmwareUpdates && Array.isArray(driver.firmwareUpdates.updates)) {
+          // TODO: Remove when we want to roll out firmware updates.
+          if (level !== 'debug') {
+            throw new Error(`drivers.${driver.id} firmwareUpdates can only be included in debug mode validation.`);
+          }
+
+          const isZigbeeDriver = typeof driver.zigbee === 'object' && driver.zigbee !== null;
+
+          if (!isZigbeeDriver) {
+            throw new Error(`drivers.${driver.id} firmwareUpdates are only supported for Zigbee drivers (missing driver.zigbee)`);
+          }
+
+          for (const [updateIndex, update] of Object.entries(driver.firmwareUpdates.updates)) {
+            const hasChangelogString = typeof update.changelog === 'string';
+            const hasChangelogEnString = update.changelog && typeof update.changelog.en === 'string';
+            
+            if (!hasChangelogString && !hasChangelogEnString) {
+              throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] is missing a changelog string`);
+            }
+
+            if (!Array.isArray(update.files) || update.files.length === 0) {
+              throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}].files must include at least one file`);
+            }
+
+            if (isZigbeeDriver) {
+              const driverManufacturerNames = toArray(driver.zigbee.manufacturerName);
+              const driverProductIds = toArray(driver.zigbee.productId);
+
+              const updateManufacturerNames = toArray(update.device.manufacturerName);
+              const updateProductIds = toArray(update.device.productId);
+
+              if (updateManufacturerNames.length === 0 || updateProductIds.length === 0) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] must include at least one manufacturerName and productId`);
+              }
+
+              const hasMismatchedManufacturerName = updateManufacturerNames.some(name => !driverManufacturerNames.includes(name));
+              const hasMismatchedProductId = updateProductIds.some(id => !driverProductIds.includes(id));
+
+              if (hasMismatchedManufacturerName) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] has a manufacturerName that does not match the driver zigbee.manufacturerName`);
+              }
+
+              if (hasMismatchedProductId) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] has a productId that does not match the driver zigbee.productId`);
+              }
+            }
+
+            const seenFiles = new Set();
+
+            for (const [fileIndex, file] of Object.entries(update.files)) {
+              const relativeFilePath = Util.getOTAFilePath({ appPath: '', driverId: driver.id, fileName: file.name });
+              await this._ensureFileExistsCaseSensitive(relativeFilePath);
+              const filePath = join(this._path, relativeFilePath);
+              const isIntegrityValid = await Util.validateIntegrity(filePath, file.integrity);
+
+              if (!isIntegrityValid) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}].files[${fileIndex}] integrity mismatch`);
+              }
+              
+              if (isZigbeeDriver) {
+                try {
+                  await Util.validateZigbeeOTAHeader({
+                    filePath,
+                    manufacturerCode: file.manufacturerCode,
+                    fileVersion: file.fileVersion,
+                    imageType: file.imageType,
+                  });
+                } catch (err) {
+                  throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}].files[${fileIndex}] invalid Zigbee OTA header: ${err.message}`);
+                }
+              }
+
+              const fileId = `${file.manufacturerCode}-${file.imageType}-${file.fileVersion}`;
+              if (seenFiles.has(fileId)) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] has multiple files with the same manufacturerCode, imageType and fileVersion`);
+              }
+              seenFiles.add(fileId);
+            }
+          }
+        }
       }
 
       const allDriversMatter = appJson.drivers.every(driver => driver.connectivity && driver.connectivity.includes('matter'));

package/lib/Util/file.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const ALLOWED_INTEGRITY_HASHES = new Set([
+  'blake2b512',
+  'blake2s256',
+  'sha256',
+  'sha384',
+  'sha512',
+  'sha512-256',
+  'sha3-256',
+  'sha3-384',
+  'sha3-512',
+]);
+
+/**
+ * Calculate a hex hash for the contents of a file.
+ * @param {string} filePath - Absolute or relative path to the file.
+ * @param {string} [hashName='sha256'] - Hash algorithm name (e.g. sha256).
+ * @returns {Promise<string>} Resolves with a hex-encoded digest.
+ */
+async function hashFile(filePath, hashName = 'sha256') {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash(hashName);
+    const stream = fs.createReadStream(filePath);
+
+    stream.on('error', reject);
+    stream.on('data', chunk => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+/**
+ * Validate file integrity using a `hashName:hexDigest` string.
+ * @param {string} filePath - Absolute or relative path to the file.
+ * @param {string} integrity - Hash name and hex digest separated by `:`.
+ * @returns {Promise<boolean>} Resolves with true when hashes match.
+ */
+async function validateIntegrity(filePath, integrity) {
+  if (typeof integrity !== 'string') {
+    throw new TypeError('Integrity must be a string');
+  }
+
+  const parts = integrity.split(':');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error('Integrity must be in the format "hashName:hexDigest"');
+  }
+
+  const [hashName, expectedHex] = parts;
+  const actualHex = await hashFile(filePath, hashName);
+
+  return actualHex === expectedHex.toLowerCase();
+}
+
+/**
+ * Create an integrity string for a file using an allowed hash algorithm.
+ * @param {string} filePath - Absolute or relative path to the file.
+ * @param {string} [hashName='sha256'] - Allowed hash algorithm name.
+ * @returns {Promise<string>} Resolves with `hashName:hexDigest`.
+ */
+async function getIntegrity(filePath, hashName = 'sha256') {
+  const normalizedHash = String(hashName || '').toLowerCase();
+
+  if (!ALLOWED_INTEGRITY_HASHES.has(normalizedHash)) {
+    throw new Error('Hash algorithm is not allowed for integrity checks');
+  }
+
+  const digest = await hashFile(filePath, normalizedHash);
+  return `${normalizedHash}:${digest}`;
+}
+
+function getOTAFilePath({ appPath, driverId, fileName }) {
+  return path.join(appPath, 'drivers', driverId, 'assets', 'firmware', fileName);
+}
+
+module.exports = {
+  hashFile,
+  getIntegrity,
+  validateIntegrity,
+  getOTAFilePath,
+};

package/lib/Util/index.js

@@ -1,5 +1,8 @@
 'use strict';
 
+const fileUtils = require('./file');
+const zigbeeUtils = require('./zigbee');
+
 class Util {
 
   /**
@@ -20,6 +23,65 @@ class Util {
     return wantedFeatures.filter(feature => !features.includes(feature));
   }
 
+  /**
+   * Create an integrity string for a file using an allowed hash algorithm.
+   * NOTE: This method is only available in Node.js environments.
+   * @param {string} filePath - Absolute or relative path to the file.
+   * @param {string} hashName - Allowed hash algorithm name.
+   * @returns {Promise<string>} Resolves with `hashName:hexDigest`.
+   */
+  static getIntegrity(filePath, hashName) {
+    return fileUtils.getIntegrity(filePath, hashName);
+  }
+
+  /**
+   * Validate file integrity using a `hashName:hexDigest` string.
+   * NOTE: This method is only available in Node.js environments.
+   * @param {string} filePath - Absolute or relative path to the file.
+   * @param {string} integrity - Hash name and hex digest separated by `:`.
+   * @returns {Promise<boolean>} Resolves with true when hashes match.
+   */
+  static validateIntegrity(filePath, integrity) {
+    return fileUtils.validateIntegrity(filePath, integrity);
+  }
+
+  /**
+   * Parse the Zigbee OTA header from a file.
+   * NOTE: This method is only available in Node.js environments.
+   * @param {string} filePath - Absolute or relative path to the OTA file.
+   * @returns {Promise<import('./zigbee').ZigbeeOTAHeader>} Parsed header values.
+   */
+  static parseZigbeeOTAHeader(filePath) {
+    return zigbeeUtils.parseZigbeeOTAHeader(filePath);
+  }
+
+  /**
+   * Validate a Zigbee OTA header against expected values.
+   * NOTE: This method is only available in Node.js environments.
+   * @param {object} options - Validation options.
+   * @param {string} options.filePath - Absolute or relative path to the OTA file.
+   * @param {number} [options.manufacturerCode] - Expected manufacturer code.
+   * @param {number} [options.fileVersion] - Expected file version.
+   * @param {number} [options.imageType] - Expected image type.
+   * @returns {Promise<import('./zigbee').ZigbeeOTAHeader>} Parsed header values.
+   */
+  static validateZigbeeOTAHeader(options) {
+    return zigbeeUtils.validateZigbeeOTAHeader(options);
+  }
+
+  /**
+   * Returns the expected file path for an OTA file based on app path, driver ID and file name.
+   * NOTE: This method is only available in Node.js environments.
+   * @param {object} options - File path options.
+   * @param {string} options.appPath - Absolute path to the app.
+   * @param {string} options.driverId - Driver ID.
+   * @param {string} options.fileName - OTA file name.
+   * @returns {string} Resolves with the expected file path.
+   */
+  static getOTAFilePath({ appPath, driverId, fileName }) {
+    return fileUtils.getOTAFilePath({ appPath, driverId, fileName });
+  }
+
 }
 
 Util.FEATURE_SPEAKER = 'speaker';