@willieee802/zigbee-herdsman 0.48.2 → 0.49.0

package/src/models/backup.ts

@@ -0,0 +1,37 @@
+import type {ZnpVersion} from "../adapter/z-stack/adapter/tstype";
+import type {NetworkOptions} from "./network-options";
+
+/**
+ * Internal representation of stored backup. Contains all essential network information.
+ *
+ * Additional `znp` object may contain extra information specific to Z-Stack based coordinators.
+ */
+export interface Backup {
+    networkOptions: NetworkOptions;
+    logicalChannel: number;
+    networkKeyInfo: {
+        sequenceNumber: number;
+        frameCounter: number;
+    };
+    securityLevel: number;
+    networkUpdateId: number;
+    coordinatorIeeeAddress: Buffer;
+    devices: {
+        networkAddress: number | null;
+        ieeeAddress: Buffer;
+        isDirectChild: boolean;
+        linkKey?: {
+            key: Buffer;
+            rxCounter: number;
+            txCounter: number;
+        };
+    }[];
+    znp?: {
+        version?: ZnpVersion;
+        trustCenterLinkKeySeed?: Buffer;
+    };
+    ezsp?: {
+        version?: number;
+        hashed_tclk?: Buffer;
+    };
+}

package/src/models/index.ts

@@ -0,0 +1,5 @@
+/* v8 ignore start */
+export * from "./backup";
+export * from "./backup-storage-legacy";
+export * from "./backup-storage-unified";
+export * from "./network-options";

package/src/models/network-options.ts

@@ -0,0 +1,11 @@
+/**
+ * Buffer-oriented structure representing network configuration.
+ */
+export interface NetworkOptions {
+    panId: number;
+    extendedPanId: Buffer;
+    channelList: number[];
+    networkKey: Buffer;
+    networkKeyDistribute: boolean;
+    hasDefaultExtendedPanId?: boolean;
+}

package/src/utils/aes.ts

@@ -0,0 +1,218 @@
+import * as crypto from 'crypto';
+import { logger } from './logger';
+
+const IV_MAC_PREFIX = '01010101010101010101';
+/**
+ * PKCS7 填充
+ * @param data 需要填充的数据
+ * @param blockSize 块大小，默认 16
+ * @returns 填充后的数据
+ */
+function pkcs7Pad(data: Buffer, blockSize: number = 16): Buffer {
+  const padLen = blockSize - (data.length % blockSize);
+  const padding = Buffer.alloc(padLen, padLen);
+  return Buffer.concat([data as any, padding as any] as any);
+}
+
+/**
+ * PKCS7 去填充
+ * @param data 需要去填充的数据
+ * @returns 去填充后的数据
+ */
+function pkcs7Unpad(data: Buffer): Buffer {
+  if (data.length === 0) {
+    return data;
+  }
+  const padLen = data[data.length - 1];
+  if (padLen < 1 || padLen > 16) {
+    return data;
+  }
+  return data.slice(0, data.length - padLen);
+}
+
+/**
+ * 将 hex 字符串转换为 Buffer
+ * @param hex hex 字符串
+ * @returns Buffer
+ */
+function hexToBuffer(hex: string): Buffer {
+  return Buffer.from(hex, 'hex');
+}
+
+/**
+ * AES CBC 模式加密，返回 base64 字符串
+ * @param plainText 明文（UTF-8 字符串）
+ * @param keyHex 密钥（hex 字符串，32 或 64 位）
+ * @param ivHex IV（hex 字符串）
+ * @returns base64 编码的密文
+ */
+export function aesCbcEncryptBase64(
+  plainText: string,
+  keyHex: string,
+  ivHex: string,
+): string {
+  const key = hexToBuffer(keyHex);
+  const iv = hexToBuffer(IV_MAC_PREFIX + ivHex);
+
+  if (key.length !== 16 && key.length !== 32) {
+    throw new Error('Key length must be 16 or 32 bytes (hex: 32 or 64 chars)');
+  }
+
+  // 根据密钥长度选择算法
+  const algorithm = key.length === 16 ? 'aes-128-cbc' : 'aes-256-cbc';
+
+  // 将明文转换为 UTF-8 字节并填充
+  const data = pkcs7Pad(Buffer.from(plainText, 'utf-8'), 16);
+
+  // 创建加密器
+  const cipher = crypto.createCipheriv(algorithm, key as any, iv as any);
+
+  // 加密：update 处理所有数据，final 应该返回空（因为数据已经是完整块）
+  // 但 Node.js 的 crypto 模块在某些情况下 final() 会返回额外数据，需要特殊处理
+  const encrypted = cipher.update(data as any);
+  const final = cipher.final() as Buffer;
+
+  // 如果 final 返回了数据且 update 已处理完整数据，只使用 update 的结果（与 Python 行为一致）
+  const result =
+    final.length > 0 && encrypted.length === data.length
+      ? encrypted
+      : Buffer.concat([encrypted as Buffer, final] as any);
+
+  // 返回 base64 编码
+  return result.toString('base64');
+}
+
+/**
+ * AES CBC 模式解密，从 base64 字符串解密
+ * @param cipherB64 base64 编码的密文
+ * @param keyHex 密钥（hex 字符串，32 或 64 位）
+ * @param ivHex IV（hex 字符串）
+ * @returns 解密后的 UTF-8 字符串
+ */
+export function aesCbcDecryptBase64(
+  cipherB64: string,
+  keyHex: string,
+  ivHex: string,
+): string {
+  const key = hexToBuffer(keyHex);
+  const iv = hexToBuffer(IV_MAC_PREFIX + ivHex);
+
+  if (key.length !== 16 && key.length !== 32) {
+    throw new Error('Key length must be 16 or 32 bytes (hex: 32 or 64 chars)');
+  }
+
+  // 根据密钥长度选择算法
+  const algorithm = key.length === 16 ? 'aes-128-cbc' : 'aes-256-cbc';
+
+  // 解码 base64
+  const cipherBytes = Buffer.from(cipherB64, 'base64');
+
+  // 创建解密器
+  const decipher = crypto.createDecipheriv(algorithm, key as any, iv as any);
+
+  // 解密
+  const decrypted = Buffer.concat([
+    decipher.update(cipherBytes as any) as Buffer,
+    decipher.final() as Buffer,
+  ] as any);
+
+  // 去填充并转换为 UTF-8 字符串
+  const unpadded = pkcs7Unpad(decrypted);
+  return unpadded.toString('utf-8');
+}
+
+/**
+ * AES CBC 模式加密 hex 字符串，返回 base64
+ * @param plainHex 明文的 hex 字符串（如 'FE00210120'）
+ * @param keyHex 密钥（hex 字符串，32 或 64 位）
+ * @param ivHex IV（hex 字符串）
+ * @returns base64 编码的密文
+ */
+export function aesCbcEncryptBase64Hex(
+  plainHex: string,
+  keyHex: string,
+  ivHex: string,
+): string {
+  const key = hexToBuffer(keyHex);
+  const iv = hexToBuffer(IV_MAC_PREFIX + ivHex);
+
+  if (key.length !== 16 && key.length !== 32) {
+    throw new Error('Key length must be 16 or 32 bytes (hex: 32 or 64 chars)');
+  }
+
+  // 根据密钥长度选择算法
+  const algorithm = 'aes-128-cbc';
+
+  // 将 hex 字符串转换为 Buffer 并填充
+  const data = pkcs7Pad(hexToBuffer(plainHex), 16);
+
+  // 创建加密器
+  const cipher = crypto.createCipheriv(algorithm, key as any, iv as any);
+  // 禁用自动填充，因为我们已经手动进行了 PKCS7 填充
+  cipher.setAutoPadding(false);
+
+  // 加密：update 处理所有数据，final 应该返回空（因为数据已经是完整块）
+  // 但 Node.js 的 crypto 模块在某些情况下 final() 会返回额外数据，需要特殊处理
+  const encrypted = cipher.update(data as any);
+  const final = cipher.final() as Buffer;
+
+  // 如果 final 返回了数据且 update 已处理完整数据，只使用 update 的结果（与 Python 行为一致）
+  const result =
+    final.length > 0 && encrypted.length === data.length
+      ? encrypted
+      : Buffer.concat([encrypted as Buffer, final] as any);
+
+  // 返回 base64 编码
+  return result.toString('base64');
+}
+
+/**
+ * AES CBC 模式解密，从 base64 解密为 hex 字符串
+ * @param cipherB64 base64 编码的密文
+ * @param keyHex 密钥（hex 字符串，32 或 64 位）
+ * @param ivHex IV（hex 字符串）
+ * @returns 解密后的 hex 字符串（大写）
+ */
+/**
+ * AES CBC 模式解密，从 base64 解密为 hex 字符串
+ * @param cipherB64 base64 编码的密文
+ * @param keyHex 密钥（hex 字符串，32 或 64 位）
+ * @param ivHex IV（hex 字符串）
+ * @returns 解密后的 hex 字符串（大写）
+ */
+export function aesCbcDecryptBase64ToHex(
+  cipherB64: string,
+  keyHex: string,
+  ivHex: string,
+): string {
+  logger.debug('解密前' + cipherB64, 'zh:aes');
+  const key = hexToBuffer(keyHex);
+  const iv = hexToBuffer(IV_MAC_PREFIX + ivHex);
+
+  if (key.length !== 16 && key.length !== 32) {
+    throw new Error('Key length must be 16 or 32 bytes (hex: 32 or 64 chars)');
+  }
+
+  // 根据密钥长度选择算法
+  const algorithm = key.length === 16 ? 'aes-128-cbc' : 'aes-256-cbc';
+
+  // 解码 base64
+  const cipherBytes = Buffer.from(cipherB64, 'base64');
+
+  // 创建解密器
+  const decipher = crypto.createDecipheriv(algorithm, key as any, iv as any);
+  // 禁用自动填充，因为我们要手动处理 PKCS7 填充
+  decipher.setAutoPadding(false);
+
+  // 解密
+  const decrypted = Buffer.concat([
+    decipher.update(cipherBytes as any),
+    decipher.final() as any,
+  ]);
+
+  // 去填充并转换为 hex 字符串（大写）
+  const unpadded = pkcs7Unpad(decrypted);
+  const res = unpadded.toString('hex').toUpperCase();
+  logger.debug('解密后:' + res, 'zh:aes');
+  return res;
+}

package/src/utils/async-mutex.ts

@@ -0,0 +1,31 @@
+export class AsyncMutex {
+    #locked = false;
+    readonly #queue: Array<() => void> = [];
+
+    get count() {
+        return this.#queue.length;
+    }
+
+    async run<T>(fn: () => Promise<T>): Promise<T> {
+        if (this.#locked) {
+            await new Promise<void>((resolve) => this.#queue.push(resolve));
+        }
+
+        this.#locked = true;
+
+        try {
+            return await fn();
+        } finally {
+            this.#locked = false;
+            const next = this.#queue.shift();
+
+            if (next) {
+                next();
+            }
+        }
+    }
+
+    clear() {
+        this.#queue.length = 0;
+    }
+}

package/src/utils/backup.ts

@@ -0,0 +1,152 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import * as ZStackStructs from "../adapter/z-stack/structs";
+import * as ZStackUtils from "../adapter/z-stack/utils";
+import type * as Models from "../models";
+
+/**
+ * Converts internal backup format to unified backup storage format as described by
+ * [zigpy/open-coordinator-backup](https://github.com/zigpy/open-coordinator-backup).
+ *
+ * @param backup Backup to create unified backup format from.
+ */
+export const toUnifiedBackup = (backup: Models.Backup): Models.UnifiedBackupStorage => {
+    const packageInfo = JSON.parse(fs.readFileSync(path.join(__dirname, "../../", "package.json")).toString());
+
+    return {
+        metadata: {
+            format: "zigpy/open-coordinator-backup",
+            version: 1,
+            source: `${packageInfo.name}@${packageInfo.version}`,
+            internal: {
+                date: new Date().toISOString(),
+                ...(backup.znp ? {znpVersion: backup.znp?.version ?? undefined} : /* v8 ignore next */ undefined),
+                ...(backup.ezsp ? {ezspVersion: backup.ezsp?.version ?? undefined} : /* v8 ignore next */ undefined),
+            },
+        },
+        stack_specific: {
+            /* v8 ignore next */
+            ...(backup.znp ? {zstack: {tclk_seed: backup.znp?.trustCenterLinkKeySeed?.toString("hex") || undefined}} : undefined),
+            ...(backup.ezsp ? {ezsp: {hashed_tclk: backup.ezsp?.hashed_tclk?.toString("hex") || undefined}} : /* v8 ignore next */ undefined),
+        },
+        coordinator_ieee: backup.coordinatorIeeeAddress.toString("hex"),
+        pan_id: backup.networkOptions.panId.toString(16),
+        extended_pan_id: backup.networkOptions.extendedPanId.toString("hex"),
+        nwk_update_id: backup.networkUpdateId || 0,
+        security_level: backup.securityLevel,
+        channel: backup.logicalChannel,
+        channel_mask: backup.networkOptions.channelList,
+        network_key: {
+            key: backup.networkOptions.networkKey.toString("hex"),
+            sequence_number: backup.networkKeyInfo.sequenceNumber,
+            frame_counter: backup.networkKeyInfo.frameCounter,
+        },
+        devices: backup.devices.map((device) => {
+            return {
+                nwk_address: device.networkAddress !== null ? device.networkAddress.toString(16) : /* v8 ignore next */ null,
+                ieee_address: device.ieeeAddress.toString("hex"),
+                is_child: device.isDirectChild,
+                link_key: device.linkKey
+                    ? {key: device.linkKey.key.toString("hex"), rx_counter: device.linkKey.rxCounter, tx_counter: device.linkKey.txCounter}
+                    : undefined,
+            };
+        }),
+    };
+};
+
+/**
+ * Converts unified backup storage format to internal backup format.
+ *
+ * @param backup Unified format to convert to internal backup format.
+ */
+export const fromUnifiedBackup = (backup: Models.UnifiedBackupStorage): Models.Backup => {
+    const tclkSeedString = backup.stack_specific?.zstack?.tclk_seed || undefined;
+
+    return {
+        networkOptions: {
+            panId: Number.parseInt(backup.pan_id, 16),
+            extendedPanId: Buffer.from(backup.extended_pan_id, "hex"),
+            channelList: backup.channel_mask,
+            networkKey: Buffer.from(backup.network_key.key, "hex"),
+            networkKeyDistribute: false,
+        },
+        logicalChannel: backup.channel,
+        networkKeyInfo: {
+            sequenceNumber: backup.network_key.sequence_number,
+            frameCounter: backup.network_key.frame_counter,
+        },
+        coordinatorIeeeAddress: Buffer.from(backup.coordinator_ieee, "hex"),
+        securityLevel: backup.security_level,
+        networkUpdateId: backup.nwk_update_id,
+        devices: backup.devices.map((device) => ({
+            networkAddress: device.nwk_address ? Number.parseInt(device.nwk_address, 16) : null,
+            ieeeAddress: Buffer.from(device.ieee_address, "hex"),
+            isDirectChild: typeof device.is_child === "boolean" ? device.is_child : true,
+            linkKey: device.link_key
+                ? {key: Buffer.from(device.link_key.key, "hex"), rxCounter: device.link_key.rx_counter, txCounter: device.link_key.tx_counter}
+                : undefined,
+        })),
+        znp: {
+            version: backup.metadata.internal?.znpVersion || undefined,
+            trustCenterLinkKeySeed: tclkSeedString ? Buffer.from(tclkSeedString, "hex") : undefined,
+        },
+        ezsp: {
+            version: backup.metadata.internal?.ezspVersion || undefined,
+            hashed_tclk: backup.stack_specific?.ezsp?.hashed_tclk ? Buffer.from(backup.stack_specific.ezsp.hashed_tclk, "hex") : undefined,
+        },
+    };
+};
+
+/**
+ * Converts legacy Zigbee2MQTT format to internal backup format.
+ *
+ * @param backup Legacy format to convert.
+ */
+export const fromLegacyBackup = (backup: Models.LegacyBackupStorage): Models.Backup => {
+    if (!backup.data.ZCD_NV_NIB) {
+        throw new Error("Backup corrupted - missing NIB");
+    }
+
+    if (!backup.data.ZCD_NV_NWK_ACTIVE_KEY_INFO) {
+        throw new Error("Backup corrupted - missing active key info");
+    }
+
+    if (!backup.data.ZCD_NV_PRECFGKEY_ENABLE) {
+        throw new Error("Backup corrupted - missing pre-configured key enable attribute");
+    }
+
+    if (!backup.data.ZCD_NV_EX_NWK_SEC_MATERIAL_TABLE && !backup.data.ZCD_NV_LEGACY_NWK_SEC_MATERIAL_TABLE_START) {
+        throw new Error("Backup corrupted - missing network security material table");
+    }
+
+    if (!backup.data.ZCD_NV_EXTADDR) {
+        throw new Error("Backup corrupted - missing adapter IEEE address NV entry");
+    }
+
+    const ieeeAddress = Buffer.from(backup.data.ZCD_NV_EXTADDR.value).reverse();
+    const nib = ZStackStructs.nib(Buffer.from(backup.data.ZCD_NV_NIB.value));
+    const activeKeyInfo = ZStackStructs.nwkKeyDescriptor(Buffer.from(backup.data.ZCD_NV_NWK_ACTIVE_KEY_INFO.value));
+    const preconfiguredKeyEnabled = backup.data.ZCD_NV_PRECFGKEY_ENABLE.value[0] !== 0x00;
+    const nwkSecMaterialSource = backup.data.ZCD_NV_EX_NWK_SEC_MATERIAL_TABLE || backup.data.ZCD_NV_LEGACY_NWK_SEC_MATERIAL_TABLE_START;
+    const nwkSecMaterialEntry = ZStackStructs.nwkSecMaterialDescriptorEntry(Buffer.from(nwkSecMaterialSource.value));
+
+    return {
+        networkOptions: {
+            panId: nib.nwkPanId,
+            extendedPanId: nib.extendedPANID,
+            channelList: ZStackUtils.unpackChannelList(nib.channelList),
+            networkKey: activeKeyInfo.key,
+            networkKeyDistribute: preconfiguredKeyEnabled,
+        },
+        logicalChannel: nib.nwkLogicalChannel,
+        networkKeyInfo: {
+            sequenceNumber: activeKeyInfo.keySeqNum,
+            frameCounter: nwkSecMaterialEntry.FrameCounter,
+        },
+        coordinatorIeeeAddress: ieeeAddress,
+        securityLevel: nib.SecurityLevel,
+        networkUpdateId: nib.nwkUpdateId,
+        devices: [],
+    };
+};

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export * as BackupUtils from "./backup";
+export {Queue} from "./queue";
+export * as Utils from "./utils";
+export {wait} from "./wait";
+export {Waitress} from "./waitress";

package/src/utils/logger.ts

@@ -0,0 +1,20 @@
+export interface Logger {
+    debug: (messageOrLambda: string | (() => string), namespace: string) => void;
+    info: (messageOrLambda: string | (() => string), namespace: string) => void;
+    warning: (messageOrLambda: string | (() => string), namespace: string) => void;
+    error: (messageOrLambda: string, namespace: string) => void;
+}
+
+export let logger: Logger = {
+    debug: (messageOrLambda, namespace) =>
+        console.debug(`[${new Date().toISOString()}] ${namespace}: ${typeof messageOrLambda === "function" ? messageOrLambda() : messageOrLambda}`),
+    info: (messageOrLambda, namespace) =>
+        console.info(`[${new Date().toISOString()}] ${namespace}: ${typeof messageOrLambda === "function" ? messageOrLambda() : messageOrLambda}`),
+    warning: (messageOrLambda, namespace) =>
+        console.warn(`[${new Date().toISOString()}] ${namespace}: ${typeof messageOrLambda === "function" ? messageOrLambda() : messageOrLambda}`),
+    error: (message, namespace) => console.error(`[${new Date().toISOString()}] ${namespace}: ${message}`),
+};
+
+export function setLogger(l: Logger): void {
+    logger = l;
+}

package/src/utils/patchBigIntSerialization.ts

@@ -0,0 +1,8 @@
+// Patch BigInt serialization which is used in e.g. Zcl payloads.
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json
+// biome-ignore lint/suspicious/noExplicitAny: API
+(BigInt.prototype as any).toJSON = function (): string {
+    return this.toString();
+};
+
+export {};

package/src/utils/queue.ts

@@ -0,0 +1,79 @@
+interface Job {
+    key?: string | number;
+    running: boolean;
+    start?: () => void;
+}
+
+export class Queue {
+    readonly #concurrent: number;
+    readonly #jobs: Job[] = [];
+    #running = 0;
+
+    constructor(concurrent = 1) {
+        this.#concurrent = concurrent;
+    }
+
+    public async execute<T>(func: () => Promise<T>, key?: string | number): Promise<T> {
+        const job: Job = {key, running: false};
+        this.#jobs.push(job);
+
+        // Minor optimization/workaround: various tests like the idea that a job that is immediately runnable is run without an event loop spin.
+        // This also helps with stack traces in some cases, so avoid an `await` if we can help it.
+        if (this.#getNext() !== job) {
+            await new Promise<void>((resolve): void => {
+                job.start = (): void => {
+                    job.running = true;
+                    this.#running += 1;
+                    resolve();
+                };
+
+                this.#executeNext();
+            });
+        } else {
+            job.running = true;
+            this.#running += 1;
+        }
+
+        try {
+            return await func();
+        } finally {
+            this.#jobs.splice(this.#jobs.indexOf(job), 1);
+            this.#running = Math.max(this.#running - 1, 0);
+            this.#executeNext();
+        }
+    }
+
+    #executeNext(): void {
+        const job = this.#getNext();
+
+        if (job) {
+            // biome-ignore lint/style/noNonNullAssertion: if we get here, start is always defined for job
+            job.start!();
+        }
+    }
+
+    #getNext(): Job | undefined {
+        if (this.#running > this.#concurrent - 1) {
+            return undefined;
+        }
+
+        for (let i = 0; i < this.#jobs.length; i++) {
+            const job = this.#jobs[i];
+
+            if (!job.running && (!job.key || !this.#jobs.find((j) => j.key === job.key && j.running))) {
+                return job;
+            }
+        }
+
+        return undefined;
+    }
+
+    public clear(): void {
+        this.#running = 0;
+        this.#jobs.length = 0;
+    }
+
+    public count(): number {
+        return this.#jobs.length;
+    }
+}