@homebridge-plugins/homebridge-govee 11.32.2-beta.25 → 11.32.2-beta.27

package/CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 
 ### Changed
 
+- fix: stop shipping the test files to npm, since they are only needed in the repository
 - fix: implement the H7107's oscillation toggle, which threw a not-implemented error when tapped (#1334)
 - fix: also send the H7107's oscillation command as the multiSync frame the fan itself uses, since the first shape only turned it off sometimes (#1334)
 - fix: send the H7107's oscillation-off command without the swing-range bytes, matching the zero-tailed frame the fan echoes back (#1334)
@@ -20,7 +21,6 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - feat: add the H7103 and H7112 fans and the H5085 plug, with unknown controls saying so instead of guessing
 - feat: give every appliance type a starting handler, so a new model works for on and off and asks for the rest
 - refactor: point models that behave identically at one shared handler instead of copies of the same file
-- fix: stop shipping the test files to npm, since they are only needed in the repository
 - fix: refuse to send a bluetooth command too long to fit in a packet, rather than sending a longer one the device quietly ignores
 - test: record what every supported model turns into, so a change can be shown to have altered nothing
 - feat: work out what an appliance can do from what the device itself reports, so a model nobody has written down still gets the right controls
@@ -44,6 +44,7 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - feat: recognise eleven more meat thermometers, which report what they send so their readings can be worked out, and stop the one already known printing its whole update as a warning
 - feat: add the H5161 power strip and give the H7184 kitchen composter an on and off switch
 - feat: recognise three more sensors, which report what they send, and say plainly in the log why a sensor has no tile yet
+- feat: add ble encryption for the H3001 solar string lights, which silently ignore unencrypted frames (#1328)
 
 ## v11.32.1 (2026-08-02)
 

package/lib/connection/ble.js

@@ -3,8 +3,10 @@ import process from 'node:process'
 
 import btClient from '@stoprocent/noble'
 
+import { buildHandshake, isHandshakeFrame, parseHandshakeResponse, V2Session } from '../utils/ble-crypto.js'
 import { BLE_STAGE_TIMEOUTS, UUID } from '../utils/ble-protocol.js'
 import { decodeAny } from '../utils/decode.js'
+import { getDeviceCapabilities } from '../utils/device-capabilities.js'
 import { base64ToHex, generateCodeFromHexValues, hexToTwoItems, sleep } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
 import { isFirstReport } from '../utils/report-unknown.js'
@@ -20,6 +22,7 @@ const H5101_UUID = '0001'
 const POWER_ON_TIMEOUT = BLE_STAGE_TIMEOUTS.powerOn
 const CONNECTION_TIMEOUT = BLE_STAGE_TIMEOUTS.connect
 const WRITE_TIMEOUT = BLE_STAGE_TIMEOUTS.write
+const HANDSHAKE_TIMEOUT = BLE_STAGE_TIMEOUTS.handshake
 const SETTLE_DELAY = BLE_STAGE_TIMEOUTS.settle
 
 /*
@@ -265,8 +268,19 @@ export default class BLEConnection {
       const finalBuffer = this.prepareCommandBuffer(params)
       accessory.logDebug(`sending command: ${finalBuffer.toString('hex')}`)
 
+      // Encrypted models refuse the plain frame. Because writes are
+      // unacknowledged, they refuse it silently, so the handshake has to happen
+      // here rather than being discovered by a failed write. It is per
+      // connection: the frame counter resets with the link.
+      let payload = finalBuffer
+      if (getDeviceCapabilities(accessory.context.gvModel).bleEncryption === 'v2') {
+        const session = await this.negotiateSession(accessory, characteristic, characteristics)
+        payload = session.seal(finalBuffer)
+        accessory.logDebug(`encrypted as: ${payload.toString('hex')}`)
+      }
+
       // Write without response then allow time for the BLE controller to transmit before disconnecting
-      await this.writeWithTimeout(characteristic, finalBuffer, WRITE_TIMEOUT)
+      await this.writeWithTimeout(characteristic, payload, WRITE_TIMEOUT)
       accessory.logDebug('command sent successfully')
       await sleep(SETTLE_DELAY)
     } catch (err) {
@@ -299,6 +313,70 @@ export default class BLEConnection {
     }
   }
 
+  /**
+   * Exchange a session key with an encrypted model.
+   *
+   * Unlike every other path in this client we need a reply, which arrives as a
+   * notification on UUID.NOTIFY. Note that we deliberately do NOT subscribe:
+   * these lights push notifications without the client ever writing the client
+   * characteristic configuration descriptor, exactly as the official app does.
+   * Calling subscribeAsync() here makes the descriptor write hang and the light
+   * then drops the connection, so listening is both sufficient and required.
+   *
+   * The reply is authenticated - parseHandshakeResponse throws if the GCM tag
+   * does not verify - which turns a wrong key into a real error rather than a
+   * light that silently ignores every command.
+   *
+   * Returns a V2Session that wraps outgoing frames.
+   */
+  async negotiateSession(accessory, writeCharacteristic, characteristics) {
+    const notifyCharacteristic = Object.values(characteristics).find(
+      char => char.uuid.replace(HYPHEN_REGEX, '') === UUID.NOTIFY,
+    )
+    if (!notifyCharacteristic) {
+      throw new Error('Notify characteristic not found, cannot negotiate encryption')
+    }
+
+    let resolveReply
+    let rejectReply
+    const reply = new Promise((resolve, reject) => {
+      resolveReply = resolve
+      rejectReply = reject
+    })
+    // Attach a handler immediately: if the write below throws, the timeout would
+    // otherwise reject an unawaited promise and crash the process.
+    reply.catch(() => {})
+
+    const onData = (data) => {
+      // The light also pushes state frames here; take only the handshake.
+      if (isHandshakeFrame(data)) {
+        resolveReply(data)
+      }
+    }
+    notifyCharacteristic.on('data', onData)
+    const timer = setTimeout(
+      () => rejectReply(new Error('Encryption handshake timeout')),
+      HANDSHAKE_TIMEOUT,
+    )
+
+    try {
+      const { frame, txIvKey } = buildHandshake()
+      accessory.logDebug(`sending handshake: ${frame.toString('hex')}`)
+      await this.writeWithTimeout(writeCharacteristic, frame, WRITE_TIMEOUT)
+
+      const response = await reply
+      accessory.logDebug(`handshake reply: ${response.toString('hex')}`)
+
+      const { devInfo, sku, mac } = parseHandshakeResponse(response)
+      accessory.logDebug(`handshake verified for ${sku} at ${mac}`)
+
+      return new V2Session({ txIvKey, devInfo })
+    } finally {
+      clearTimeout(timer)
+      notifyCharacteristic.removeListener('data', onData)
+    }
+  }
+
   async connectWithTimeout(address, timeout) {
     let timeoutId
     try {

package/lib/utils/ble-crypto.js

@@ -0,0 +1,130 @@
+/**
+ * Govee "V2" BLE encryption (EncryptionManagerV2 in the Govee Home app).
+ *
+ * Used by newer Bluetooth-only devices such as the H3001 solar string lights.
+ * Older devices take the plain 20-byte frame; these wrap it in AES-128-GCM and
+ * silently ignore anything that is not wrapped.
+ *
+ * Wire format on 00010203-0405-0607-0809-0a0b0c0d2b11 (write) and ...2b10 (notify):
+ *
+ *   handshake request   e7 11 01 | iv(12) | tagLen(1) | GCM{ txIvKey(8) }
+ *                       AAD = frame[0..15]                     key = KEY_HANDSHAKE
+ *   handshake response  e7 11 00 | iv(12) |            GCM{ rxIvKey(8) ++ devInfo(11) }
+ *                       AAD = frame[0..14]                     key = KEY_HANDSHAKE
+ *
+ *   deviceKey = AES-128-ECB-encrypt(KEY_DEVICE, devInfo ++ 00*5)
+ *
+ *   data frame          counter(4, big endian) | GCM{ 20-byte Govee frame }
+ *                       nonce = txIvKey(8) ++ counter(4)
+ *                       AAD   = counter(4)
+ *                       key   = deviceKey
+ *                       tag   = 12 bytes appended
+ *
+ * devInfo is the ASCII SKU (5 bytes, e.g. "H3001") followed by the MAC address
+ * in reverse byte order, so the per-device key needs no cloud lookup.
+ *
+ * Counters are per-direction, start at 1, and increment by one per frame. They
+ * reset on every connection, so a handshake is required per connection.
+ *
+ * No new dependencies: node:crypto provides aes-128-gcm and aes-128-ecb.
+ */
+import { Buffer } from 'node:buffer'
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+
+// Application-wide constants, recovered from the Govee Home app's string
+// resources (LibTools KEY_COMMUNICATION_X / _Y).
+const KEY_HANDSHAKE = Buffer.from('fc03783c7c42cb83e202a1643648aff6', 'hex')
+const KEY_DEVICE = Buffer.from('ae028b630bae6ecc4bff1b249e22f955', 'hex')
+
+const TAG_LEN = 12 // 96-bit tag; the app falls back to 128-bit
+const HDR = { MAGIC0: 0xE7, MAGIC1: 0x11, SUB_REQUEST: 0x01, STATUS_OK: 0x00 }
+
+/** True if `data` is an e711 handshake frame rather than a data frame. */
+export function isHandshakeFrame(data) {
+  return data.length >= 3 && data[0] === HDR.MAGIC0 && data[1] === HDR.MAGIC1
+}
+
+function gcmSeal(key, iv, aad, plaintext) {
+  const c = createCipheriv('aes-128-gcm', key, iv, { authTagLength: TAG_LEN })
+  c.setAAD(aad)
+  return Buffer.concat([c.update(plaintext), c.final(), c.getAuthTag()])
+}
+
+function gcmOpen(key, iv, blob, aad) {
+  const d = createDecipheriv('aes-128-gcm', key, iv, { authTagLength: TAG_LEN })
+  d.setAAD(aad)
+  d.setAuthTag(blob.subarray(blob.length - TAG_LEN))
+  return Buffer.concat([d.update(blob.subarray(0, blob.length - TAG_LEN)), d.final()]) // throws on a bad tag
+}
+
+/**
+ * Build the handshake to write first on every new connection.
+ * Returns { frame, txIvKey } -- keep txIvKey, it seeds the nonce for writes.
+ */
+export function buildHandshake(txIvKey = randomBytes(8), iv = randomBytes(12)) {
+  const frame = Buffer.alloc(36)
+  frame[0] = HDR.MAGIC0
+  frame[1] = HDR.MAGIC1
+  frame[2] = HDR.SUB_REQUEST
+  iv.copy(frame, 3)
+  frame[15] = TAG_LEN
+  gcmSeal(KEY_HANDSHAKE, iv, frame.subarray(0, 16), txIvKey).copy(frame, 16)
+  return { frame, txIvKey }
+}
+
+/**
+ * Parse the light's handshake reply. Returns { rxIvKey, devInfo, sku, mac }.
+ * Throws if the GCM tag does not verify or the device reports an error status.
+ */
+export function parseHandshakeResponse(frame) {
+  if (!isHandshakeFrame(frame)) {
+    throw new Error(`not an e711 response: ${frame.subarray(0, 4).toString('hex')}`)
+  }
+  if (frame[2] !== HDR.STATUS_OK) {
+    throw new Error(`handshake rejected, status 0x${frame[2].toString(16)}`)
+  }
+  // Note the AAD here is 15 bytes: the reply carries no tag-length byte.
+  const blob = gcmOpen(KEY_HANDSHAKE, frame.subarray(3, 15), frame.subarray(15), frame.subarray(0, 15))
+  if (blob.length !== 19) {
+    throw new Error(`expected a 19-byte handshake blob, got ${blob.length}`)
+  }
+  const devInfo = blob.subarray(8, 19)
+  return {
+    rxIvKey: blob.subarray(0, 8),
+    devInfo,
+    sku: devInfo.subarray(0, 5).toString('ascii'),
+    mac: Buffer.from(devInfo.subarray(5, 11)).reverse().toString('hex').replace(/(..)(?=.)/g, '$1:'),
+  }
+}
+
+/** deviceKey = AES-128-ECB-encrypt(KEY_DEVICE, devInfo padded to 16 with zeros). */
+function deriveDeviceKey(devInfo) {
+  const block = Buffer.alloc(16)
+  devInfo.copy(block)
+  const c = createCipheriv('aes-128-ecb', KEY_DEVICE, null)
+  c.setAutoPadding(false)
+  return Buffer.concat([c.update(block), c.final()])
+}
+
+/** Per-connection session, wrapping outgoing 20-byte frames. */
+export class V2Session {
+  constructor({ txIvKey, devInfo }) {
+    this.txIvKey = txIvKey
+    this.deviceKey = deriveDeviceKey(devInfo)
+    this.txCounter = 1
+  }
+
+  /** Wrap a plain 20-byte Govee frame for writing. */
+  seal(frame20, counter = this.txCounter) {
+    const ctr = Buffer.alloc(4)
+    ctr.writeUInt32BE(counter >>> 0, 0)
+    const out = Buffer.concat([
+      ctr,
+      gcmSeal(this.deviceKey, Buffer.concat([this.txIvKey, ctr]), ctr, frame20),
+    ])
+    if (counter === this.txCounter) {
+      this.txCounter += 1
+    }
+    return out
+  }
+}

package/lib/utils/ble-protocol.js

@@ -57,6 +57,9 @@ export const UUID = {
   SERVICE: '00010203-0405-0607-0809-0a0b0c0d1910',
   WRITE_DEFAULT: '000102030405060708090a0b0c0d2b11',
   WRITE_ALT: '000102030405060708090a0b0c0d2b10', // H615B
+  // The same attribute as WRITE_ALT, named for the role it plays on encrypted
+  // models: they answer the key handshake here.
+  NOTIFY: '000102030405060708090a0b0c0d2b10',
 }
 
 // Total BLE packet size
@@ -70,6 +73,11 @@ export const BLE_STAGE_TIMEOUTS = {
   powerOn: 5000,
   connect: 10000,
   write: 5000,
+  // Encrypted models exchange a session key before the first real command (see
+  // ble-crypto.js). Captures of the official app show the light replying in
+  // about 30ms, so this is a generous ceiling rather than an expected cost.
+  // Models that need no handshake never spend any of it.
+  handshake: 5000,
   settle: 100, // let the controller transmit before disconnecting
 
   // Discovering services, and the disconnect on the way out, have no timeout of

package/lib/utils/device-capabilities.js

@@ -54,6 +54,21 @@ const modelOverrides = {
   // H615B uses alternate BLE write characteristic UUID
   H615B: { bleWriteUuid: UUID.WRITE_ALT },
 
+  // Bluetooth-only solar string lights (#1328). Every frame is wrapped in
+  // AES-128-GCM, so this model needs the key handshake in ble-crypto.js before
+  // any command is accepted. Its colour and brightness formats were read off a
+  // capture of the official app:
+  //   colour     33 05 15 01 RR GG BB 00 00 00 00 00 FF  (then zero padding)
+  //   brightness 33 04 <0-100>          e.g. 0x1e for 30%, 0x64 for 100%
+  // Writes are unacknowledged, so without the wrapper the light silently
+  // ignores everything and the plugin cannot tell.
+  H3001: {
+    bleEncryption: 'v2',
+    bleColorCmd: COLOR_SUB.RGB_EXTENDED,
+    bleColorCmdSuffix: [0x00, 0x00, 0x00, 0x00, 0x00, 0xFF],
+    bleBrightnessScale: 0x64,
+  },
+
   // H6121 requires cmdVersion 1 for status requests
   H6121: { awsStatusCmdVersion: 1 },
 
@@ -116,6 +131,9 @@ const defaults = {
   awsBrightnessNoScale: false,
   readsSwingStatus: true,
   iceSizeAscending: false,
+  // false for the great majority of models, which take the plain 20-byte frame.
+  // 'v2' selects the AES-128-GCM transport in ble-crypto.js.
+  bleEncryption: false,
 }
 
 export function getDeviceCapabilities(model, firmware) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@homebridge-plugins/homebridge-govee",
   "alias": "Govee",
   "type": "module",
-  "version": "11.32.2-beta.25",
+  "version": "11.32.2-beta.27",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",