homey-lib 2.45.3 → 2.46.0

package/lib/Media/index.js

@@ -2,6 +2,9 @@
 
 class Media {
 
+  /**
+   * @returns {Record<string, Record<string, unknown>>}
+   */
   static getCodecs() {
     // eslint-disable-next-line global-require
     return require('../../assets/media/codecs.json');

package/lib/Signal/index.js

@@ -11,8 +11,16 @@ const {
   prontoValidator,
 } = require('./validators');
 
+/**
+ * @typedef {'433' | '868' | 'ir'} SignalFrequency
+ */
+
 class Signal {
 
+  /**
+   * @param {Record<string, unknown>} signal
+   * @param {{ frequency?: SignalFrequency }} [options]
+   */
   constructor(signal, { frequency = undefined } = {}) {
     this._signal = signal;
     this._frequency = frequency;
@@ -20,6 +28,10 @@ class Signal {
     this._check = this._check.bind(this);
   }
 
+  /**
+   * @param {...unknown} args
+   * @returns {void}
+   */
   debug(...args) {
     if (!this._debug) return;
 
@@ -27,12 +39,21 @@ class Signal {
     console.log('[dbg]', ...args);
   }
 
+  /**
+   * @param {string} message
+   * @param {boolean} result
+   * @returns {void}
+   */
   _check(message, result) {
     if (result !== true) {
       throw new Error(message);
     }
   }
 
+  /**
+   * @param {{ debug?: boolean }} [options]
+   * @returns {Promise<void>}
+   */
   async validate({
     debug = false,
   } = {}) {
@@ -65,6 +86,10 @@ class Signal {
     this.debug('Validated successfully');
   }
 
+  /**
+   * @param {Record<string, (value: unknown, signal: Record<string, unknown>) => { result: boolean, msg: string }>} validatorEngine
+   * @returns {void}
+   */
   _validateWithEngine(validatorEngine) {
     return validate(validatorEngine, this._check, this._signal);
   }

package/lib/Signal/validators.js

@@ -2,7 +2,21 @@
 
 'use strict';
 
+/**
+ * @typedef {Record<string, unknown>} SignalDefinition
+ * @typedef {{ result: boolean, msg: string }} ValidationResult
+ * @typedef {(value: unknown, signal: SignalDefinition) => ValidationResult} Validator
+ * @typedef {Record<string, Validator>} ValidatorEngine
+ * @typedef {(message: string, result: boolean) => void} CheckFn
+ */
+
 /* static functions */
+/**
+ * @param {ValidatorEngine} validator
+ * @param {CheckFn} check
+ * @param {SignalDefinition} signal
+ * @returns {void}
+ */
 function validate(validator, check, signal) {
   for (const propName in signal) {
     const property = signal[propName];
@@ -70,6 +84,7 @@ function _validateGenericData(data, signal) {
   return res;
 }
 
+/** @type {ValidatorEngine} */
 const genericValidator = {
   words(words, signal) {
     const res = { result: true, msg: 'invalid_words' };
@@ -166,6 +181,7 @@ const rfBounds = {
   repetitions: { min: 1, max: 255 },
 };
 
+/** @type {ValidatorEngine} */
 const rfValidator = {
 
   words(words, signal) {
@@ -222,6 +238,7 @@ const modulationBounds = {
   channelDeviation: { min: 5000, max: 50000 },
 };
 
+/** @type {ValidatorEngine} */
 const modulationValidator = {
   modulation(modulation, signal) {
     // replace by default modulation props in homey-microcontroller?
@@ -256,6 +273,7 @@ const modulationValidator = {
   },
 };
 
+/** @type {ValidatorEngine} */
 const prontoValidator = {
   cmds(cmds, signal) {
     const res = !Object.keys(cmds).some(cmd => {
@@ -279,6 +297,7 @@ const rf433Bounds = {
   carrier: { min: 433000000, max: 433990000 },
 };
 
+/** @type {ValidatorEngine} */
 const rf433Validator = {
   carrier(carrier, signal) {
     const res = _valid_bounds(carrier, 433000000, 433990000);
@@ -290,6 +309,7 @@ const rf868Bounds = {
   carrier: { min: 868000000, max: 868900000 },
 };
 
+/** @type {ValidatorEngine} */
 const rf868Validator = {
   carrier(carrier, signal) {
     const res = _valid_bounds(carrier, rf868Bounds.carrier.min, rf868Bounds.carrier.max);
@@ -302,6 +322,7 @@ const irBounds = {
   dutyCycle: { min: 30, max: 70 },
 };
 
+/** @type {ValidatorEngine} */
 const irValidator = {
   carrier(carrier, signal) {
     const res = _valid_bounds(carrier, irBounds.carrier.min, irBounds.carrier.max);

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,16 +1,87 @@
 'use strict';
 
+const fileUtils = require('./file');
+const zigbeeUtils = require('./zigbee');
+
 class Util {
 
+  /**
+   * @param {string} modelId
+   * @returns {string[]}
+   */
   static getPlatformLocalFeatures(modelId) {
     return Util._platformLocalFeatures[modelId] || [];
   }
 
+  /**
+   * @param {string} modelId
+   * @param {string[]} wantedFeatures
+   * @returns {string[]}
+   */
   static getMissingPlatformLocalFeatures(modelId, wantedFeatures) {
     const features = Util.getPlatformLocalFeatures(modelId);
     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';
@@ -18,6 +89,7 @@ Util.FEATURE_LED_RING = 'ledring';
 Util.FEATURE_NFC = 'nfc';
 Util.FEATURE_MATTER = 'matter';
 Util.FEATURE_CAMERA_STREAMING = 'camera-streaming';
+/** @type {Record<string, string[]>} */
 Util._platformLocalFeatures = {
   homey1s: [Util.FEATURE_SPEAKER, Util.FEATURE_LED_RING, Util.FEATURE_NFC],
   homey1d: [Util.FEATURE_SPEAKER, Util.FEATURE_LED_RING, Util.FEATURE_NFC],

package/lib/Util/zigbee.js

@@ -0,0 +1,225 @@
+'use strict';
+
+const fs = require('fs');
+
+const OTA_FILE_IDENTIFIER = 0x0BEEF11E;
+const OTA_HEADER_VERSION = 0x0100;
+const OTA_MIN_HEADER_LENGTH = 56;
+
+const FIELD_CONTROL_BITS = {
+  securityCredentialVersion: 1 << 0,
+  deviceSpecificFile: 1 << 1,
+  hardwareVersionsPresent: 1 << 2,
+};
+
+/**
+ * @typedef {object} ZigbeeOTAHeader
+ * @property {number} fileSize - File size in bytes.
+ * @property {number} fileIdentifier - OTA file identifier.
+ * @property {number} headerVersion - OTA header version.
+ * @property {number} headerLength - OTA header length in bytes.
+ * @property {number} fieldControl - Field control bitmask.
+ * @property {number} manufacturerCode - Manufacturer code.
+ * @property {number} imageType - Image type.
+ * @property {number} fileVersion - File version.
+ * @property {number} zigbeeStackVersion - Zigbee stack version.
+ * @property {string} headerString - Header string (ASCII).
+ * @property {number} totalImageSize - Total image size in bytes.
+ * @property {number} [securityCredentialVersion] - Security credential version.
+ * @property {string} [upgradeFileDestination] - Destination EUI64 hex string.
+ * @property {number} [minimumHardwareVersion] - Minimum hardware version.
+ * @property {number} [maximumHardwareVersion] - Maximum hardware version.
+ * @property {number} remainingHeaderBytes - Unparsed header bytes.
+ */
+
+/**
+ * Read a fixed-length slice from the start of a file.
+ * @param {string} filePath - Absolute or relative path to the OTA file.
+ * @param {number} length - Number of bytes to read.
+ * @returns {Promise<Buffer>} Buffer with the requested bytes.
+ */
+async function readFileSlice(filePath, length) {
+  const fileHandle = await fs.promises.open(filePath, 'r');
+  try {
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await fileHandle.read(buffer, 0, length, 0);
+    if (bytesRead < length) {
+      throw new Error('Unexpected end of file while reading Zigbee OTA header');
+    }
+    return buffer;
+  } finally {
+    await fileHandle.close();
+  }
+}
+
+/**
+ * Parse the Zigbee OTA header from a file.
+ * @param {string} filePath - Absolute or relative path to the OTA file.
+ * @returns {Promise<ZigbeeOTAHeader>} Parsed header values.
+ */
+async function parseZigbeeOTAHeader(filePath) {
+  if (typeof filePath !== 'string' || filePath.length === 0) {
+    throw new TypeError('filePath must be a non-empty string');
+  }
+
+  const stats = await fs.promises.stat(filePath);
+  if (stats.size < OTA_MIN_HEADER_LENGTH) {
+    throw new Error('File is too small to contain a Zigbee OTA header');
+  }
+
+  const baseHeader = await readFileSlice(filePath, OTA_MIN_HEADER_LENGTH);
+  const baseFileIdentifier = baseHeader.readUInt32LE(0);
+
+  if (baseFileIdentifier !== OTA_FILE_IDENTIFIER) {
+    throw new Error('Invalid Zigbee OTA header identifier');
+  }
+
+  const headerLength = baseHeader.readUInt16LE(6);
+
+  if (headerLength < OTA_MIN_HEADER_LENGTH) {
+    throw new Error('Zigbee OTA header length is shorter than the mandatory header size');
+  }
+  if (headerLength > stats.size) {
+    throw new Error('Zigbee OTA header length exceeds file size');
+  }
+
+  const headerBuffer = headerLength === OTA_MIN_HEADER_LENGTH
+    ? baseHeader
+    : await readFileSlice(filePath, headerLength);
+
+  let offset = 0;
+  const fileIdentifier = headerBuffer.readUInt32LE(offset);
+  offset += 4;
+  if (fileIdentifier !== OTA_FILE_IDENTIFIER) {
+    throw new Error('Invalid Zigbee OTA header identifier');
+  }
+  const headerVersion = headerBuffer.readUInt16LE(offset);
+  offset += 2;
+  const parsedHeaderLength = headerBuffer.readUInt16LE(offset);
+  offset += 2;
+  const fieldControl = headerBuffer.readUInt16LE(offset);
+  offset += 2;
+  const manufacturerCode = headerBuffer.readUInt16LE(offset);
+  offset += 2;
+  const imageType = headerBuffer.readUInt16LE(offset);
+  offset += 2;
+  const fileVersion = headerBuffer.readUInt32LE(offset);
+  offset += 4;
+  const zigbeeStackVersion = headerBuffer.readUInt16LE(offset);
+  offset += 2;
+  const headerString = headerBuffer
+    .toString('ascii', offset, offset + 32)
+    .replace(/\0+$/, '');
+  offset += 32;
+  const totalImageSize = headerBuffer.readUInt32LE(offset);
+  offset += 4;
+
+  const header = {
+    fileSize: stats.size,
+    fileIdentifier,
+    headerVersion,
+    headerLength: parsedHeaderLength,
+    fieldControl,
+    manufacturerCode,
+    imageType,
+    fileVersion,
+    zigbeeStackVersion,
+    headerString,
+    totalImageSize,
+  };
+
+  if (fieldControl & FIELD_CONTROL_BITS.securityCredentialVersion) {
+    header.securityCredentialVersion = headerBuffer.readUInt8(offset);
+    offset += 1;
+  }
+
+  if (fieldControl & FIELD_CONTROL_BITS.deviceSpecificFile) {
+    header.upgradeFileDestination = headerBuffer
+      .slice(offset, offset + 8)
+      .toString('hex');
+    offset += 8;
+  }
+
+  if (fieldControl & FIELD_CONTROL_BITS.hardwareVersionsPresent) {
+    header.minimumHardwareVersion = headerBuffer.readUInt16LE(offset);
+    offset += 2;
+    header.maximumHardwareVersion = headerBuffer.readUInt16LE(offset);
+    offset += 2;
+  }
+
+  if (parsedHeaderLength < offset) {
+    throw new Error('Zigbee OTA header length is shorter than parsed fields');
+  }
+
+  header.remainingHeaderBytes = parsedHeaderLength - offset;
+
+  return header;
+}
+
+/**
+ * Validate a Zigbee OTA header against expected values.
+ * @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<ZigbeeOTAHeader>} Parsed header values.
+ */
+async function validateZigbeeOTAHeader({
+  filePath,
+  manufacturerCode,
+  fileVersion,
+  imageType,
+} = {}) {
+  const header = await parseZigbeeOTAHeader(filePath);
+
+  if (header.fileIdentifier !== OTA_FILE_IDENTIFIER) {
+    throw new Error('Invalid Zigbee OTA header identifier');
+  }
+
+  if (header.headerVersion !== OTA_HEADER_VERSION) {
+    throw new Error('Unsupported Zigbee OTA header version');
+  }
+
+  if (header.headerLength > header.totalImageSize) {
+    throw new Error('Zigbee OTA header length exceeds total image size');
+  }
+
+  if (header.totalImageSize !== header.fileSize) {
+    throw new Error('Zigbee OTA total image size does not match file size');
+  }
+
+  if (manufacturerCode !== undefined) {
+    if (typeof manufacturerCode !== 'number') {
+      throw new TypeError('manufacturerCode must be a number');
+    }
+    if (header.manufacturerCode !== manufacturerCode) {
+      throw new Error('Zigbee OTA manufacturer code does not match');
+    }
+  }
+
+  if (imageType !== undefined) {
+    if (typeof imageType !== 'number') {
+      throw new TypeError('imageType must be a number');
+    }
+    if (header.imageType !== imageType) {
+      throw new Error('Zigbee OTA image type does not match');
+    }
+  }
+
+  if (fileVersion !== undefined) {
+    if (typeof fileVersion !== 'number') {
+      throw new TypeError('fileVersion must be a number');
+    }
+    if (header.fileVersion !== fileVersion) {
+      throw new Error('Zigbee OTA file version does not match');
+    }
+  }
+
+  return header;
+}
+
+module.exports = {
+  parseZigbeeOTAHeader,
+  validateZigbeeOTAHeader,
+};

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "homey-lib",
-  "version": "2.45.3",
+  "version": "2.46.0",
   "description": "Shared Library for Homey",
+  "types": "types/index.d.ts",
   "main": "index.js",
   "scripts": {
-    "build": "npm ci; npm run pack",
+    "build": "npm ci; npm run types:generate; npm run schema:generate; npm run schema:copy; npm run pack",
     "pack": "webpack",
     "lint": "eslint .",
     "test": "mocha --parallel",
     "locales:apply": "node scripts/apply-locale-files.js",
-    "locales:generate": "node scripts/generate-locale-files.js"
+    "locales:generate": "node scripts/generate-locale-files.js",
+    "types:generate": "tsc --project tsconfig.types.json",
+    "schema:generate": "npm run capability-schema:generate && npm run app-schema:generate",
+    "schema:copy": "mkdir -p types/assets/app types/assets/capability && cp assets/app/schema.d.ts types/assets/app/schema.d.ts && cp assets/capability/schema.d.ts types/assets/capability/schema.d.ts",
+    "capability-schema:generate": "json2ts -i assets/capability/schema.json -o assets/capability/schema.d.ts --unknownAny",
+    "app-schema:generate": "json2ts -i assets/app/schema.json -o assets/app/schema.d.ts --unknownAny"
   },
   "engines": {
     "node": ">=12.13.0"
@@ -34,10 +40,12 @@
   "devDependencies": {
     "eslint": "^7.31.0",
     "eslint-config-athom": "^2.1.1",
+    "json-schema-to-typescript": "^15.0.4",
     "mocha": "^9.1.3",
     "mock-fs": "^5.1.2",
     "object-path": "^0.11.8",
     "set-value": "^4.1.0",
+    "typescript": "^5.9.3",
     "webpack": "^5.98.0",
     "webpack-cli": "^5.1.4"
   }

package/tsconfig.types.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true,
+    "outDir": "./types",
+    "module": "commonjs",
+    "target": "ES2020",
+    "strict": false
+  },
+  "include": ["index.js", "lib/**/*.js"],
+  "exclude": ["test/**", "node_modules/**"]
+}