homebridge-tuya-plus 3.14.0-dev.33 → 3.14.0-dev.35

package/AGENTS.md

@@ -131,6 +131,20 @@ devices already paired in HomeKit; a careless change can break them silently.
   routing.
 - When a change must alter behavior, make it opt-in.
 
+## Debug config block
+
+The platform reads an **undocumented** top-level `debug` object from the config
+(see `_debugConfig()` in `index.js`). It holds dev/test-only switches and is
+deliberately **kept out of `config.schema.json`** so it never appears in the
+Homebridge UI. Treat it as the one place such switches belong; add new ones as
+optional, off-by-default flags read through `_debugConfig()` and coerced with
+`coerceBoolean`.
+
+- `debug.forceCloudFallback` — pretend LAN discovery fails for every device, so
+  the whole platform runs over the Tuya Cloud fallback. Lets the cloud path be
+  exercised end-to-end without taking devices off the LAN (needs a configured
+  `cloud` block to be useful).
+
 ## Git & PR workflow
 
 - Develop on the branch you've been assigned; never push to `main` directly.

package/index.js

@@ -79,6 +79,20 @@ let Characteristic,
   AdaptiveLightingController,
   UUID;
 
+// Lenient boolean coercion for platform-level config flags, mirroring
+// BaseAccessory._coerceBoolean so the same true / 'true' / 1 spellings users
+// already use on device options are accepted on top-level options too.
+function coerceBoolean(value, defaultValue) {
+  const df = defaultValue || false;
+  return typeof value === 'boolean'
+    ? value
+    : typeof value === 'string'
+      ? value.toLowerCase().trim() === 'true'
+      : typeof value === 'number'
+        ? value !== 0
+        : df;
+}
+
 module.exports = function (homebridge) {
   ({
     platformAccessory: PlatformAccessory,
@@ -221,6 +235,37 @@ class TuyaLan {
       return; // cloud-only (or empty) configuration: nothing to discover over the LAN
     }
 
+    // Debug switch: pretend LAN discovery fails for every device so the whole
+    // platform runs over the Tuya Cloud fallback — a way to exercise the cloud
+    // path end-to-end without taking devices off the LAN. We simply never start
+    // discovery (and never attach a LAN backend), leaving the cloud session each
+    // device was already wired with as its only transport. Useless without a
+    // configured cloud session — the affected devices then have no transport at
+    // all, so say so per device rather than failing silently.
+    if (coerceBoolean(this._debugConfig().forceCloudFallback)) {
+      this.log.warn(
+        'debug.forceCloudFallback is set: skipping LAN discovery; every device is forced onto the Tuya Cloud fallback.',
+      );
+      lanDeviceIds.forEach((deviceId) => {
+        const tuyaDevice = this.tuyaDevices.get(deviceId);
+        if (!tuyaDevice) return;
+        if (tuyaDevice.cloud) {
+          this.log.info(
+            'Forcing %s (%s) onto the Tuya Cloud fallback (debug.forceCloudFallback).',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        } else {
+          this.log.error(
+            'debug.forceCloudFallback is set but %s (%s) has no Tuya Cloud session, so it can\'t be reached.',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        }
+      });
+      return;
+    }
+
     this.log.info('Starting discovery...');
 
     TuyaDiscovery.start({ ids: lanDeviceIds, log: this.log }).on(
@@ -279,6 +324,17 @@ class TuyaLan {
     }, this.config.discoverTimeout ?? DEFAULT_DISCOVER_TIMEOUT);
   }
 
+  // The undocumented top-level `debug` block holds switches that only matter
+  // when developing or testing the plugin (e.g. forcing the Tuya Cloud path).
+  // It is intentionally absent from config.schema.json so it never surfaces in
+  // the Homebridge UI. Always returns an object so callers can read a flag
+  // without first guarding for the block's presence.
+  _debugConfig() {
+    return this.config.debug && typeof this.config.debug === 'object'
+      ? this.config.debug
+      : {};
+  }
+
   // A device showed up on the LAN that isn't in the user's config. When the
   // optional cloud session is available we look the device up there first, so
   // the warning can name it (and hint at its product/category) and the user

package/lib/TuyaAccessory.js

@@ -48,6 +48,21 @@ class TuyaAccessory extends EventEmitter {
             this.log.info(`${this.context.name} reports protocol ${this.context.version}, newer than the newest known Tuya LAN protocol (3.5); using the 3.5 (GCM) stack with ${this.context.version} headers.`);
         }
 
+        // A Tuya local key is the AES-128 key used for every LAN frame and must be
+        // exactly 16 bytes. A wrong-length key (mistyped, truncated, or pasted with
+        // stray characters) makes crypto.createCipheriv throw "Invalid key length"
+        // the moment we first talk to the device. That throw originates inside a
+        // socket callback, so it goes unhandled and crashes Homebridge - which then
+        // restarts and crashes again: a boot loop. Refuse to bring the LAN backend
+        // up for such a device and say why; with a Tuya Cloud session configured it
+        // still works as a cloud-only device, and other devices are unaffected.
+        this._invalidKey = !this.context.fake && !TuyaAccessory.isValidLocalKey(this.context.key);
+        if (this._invalidKey && this.log) {
+            const key = this.context.key;
+            const keyLength = typeof key === 'string' ? Buffer.byteLength(key, 'utf8') : (Buffer.isBuffer(key) ? key.length : 0);
+            this.log.error(`${this.context.name} (${this.context.id}) has an invalid local key: a Tuya local key must be exactly 16 characters (this one has ${keyLength}). LAN control is disabled for this device until the key is corrected.`);
+        }
+
         this.state = {};
         this._cachedBuffer = Buffer.allocUnsafe(0);
 
@@ -72,7 +87,19 @@ class TuyaAccessory extends EventEmitter {
         this.session_key = null;
     }
 
+    // A Tuya local key is the AES-128 key for the LAN protocol, so it must be
+    // exactly 16 bytes (createCipheriv rejects any other length). Measure a
+    // string the way createCipheriv does - by its UTF-8 byte length - so a key
+    // that merely looks 16 characters long but isn't (e.g. a stray multibyte
+    // character) is still caught.
+    static isValidLocalKey(key) {
+        if (Buffer.isBuffer(key)) return key.length === 16;
+        if (typeof key === 'string') return Buffer.byteLength(key, 'utf8') === 16;
+        return false;
+    }
+
     _connect() {
+        if (this._invalidKey) return;
         if (this.context.fake) {
             this.connected = true;
             return setTimeout(() => {
@@ -767,6 +794,7 @@ class TuyaAccessory extends EventEmitter {
 
     _send(o) {
         if (this.context.fake) return;
+        if (this._invalidKey) return false;
         if (!this.connected) return false;
 
         if (this._protocolVersion < 3.2) return this._send_3_1(o);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.33",
+  "version": "3.14.0-dev.35",
   "description": "A community-maintained Homebridge plugin for controlling Tuya devices in HomeKit. LAN-first, with an optional Tuya Cloud fallback for any device the LAN can't reach.",
   "main": "index.js",
   "scripts": {

package/test/TuyaAccessory.protocol.test.js

@@ -155,6 +155,78 @@ describe('protocol version normalization', () => {
     });
 });
 
+// A wrong-length local key made crypto.createCipheriv throw "Invalid key length"
+// from inside a socket callback (see _send_3_3), which goes unhandled and crashes
+// Homebridge into a restart loop. An out-of-spec key must be refused clearly,
+// up front, without ever reaching the cipher or taking the process down.
+describe('invalid local key handling', () => {
+    describe('isValidLocalKey', () => {
+        test.each([
+            ['0123456789abcdef', true],    // 16 ASCII chars
+            ['short', false],
+            ['0123456789abcdefXX', false], // 18 chars
+            ['', false],
+            ['012345678901234é', false],   // 16 chars but 17 UTF-8 bytes
+            [Buffer.alloc(16), true],
+            [Buffer.alloc(8), false],
+            [null, false],
+            [undefined, false],
+            [12345678901234567, false],    // not a string/Buffer
+        ])('isValidLocalKey(%p) === %p', (key, expected) => {
+            expect(TuyaAccessory.isValidLocalKey(key)).toBe(expected);
+        });
+    });
+
+    test('a wrong-length key is flagged and logged without throwing', () => {
+        let device;
+        expect(() => { device = makeDevice('3.3', {key: 'too-short'}); }).not.toThrow();
+        expect(device._invalidKey).toBe(true);
+        expect(device.log.error).toHaveBeenCalledWith(expect.stringContaining('16 characters'));
+        const logged = device.log.error.mock.calls.flat().join(' ');
+        expect(logged).toContain('Protocol Test Device');
+    });
+
+    test('a valid 16-character key is accepted and logs no error', () => {
+        const device = makeDevice('3.3');
+        expect(device._invalidKey).toBe(false);
+        expect(device.log.error).not.toHaveBeenCalled();
+    });
+
+    test('_connect() opens no socket for an invalid-key device', () => {
+        const device = makeDevice('3.5', {key: 'bad'});
+        device._connect();
+        expect(device._socket).toBeUndefined();
+        expect(device.connected).toBe(false);
+    });
+
+    // The exact path that used to crash: a connected device whose update() flows
+    // into _send -> _send_3_x -> createCipheriv. It must short-circuit to false.
+    test.each(['3.1', '3.3', '3.4', '3.5'])(
+        'update() never reaches the cipher for an invalid-key %s device, even when connected',
+        version => {
+            const device = makeDevice(version, {key: 'nope'});
+            const written = attachSocketStub(device); // also forces connected = true
+
+            let result;
+            expect(() => { result = device.update({1: true}); }).not.toThrow();
+            expect(result).toBe(false);
+            expect(written).toHaveLength(0);
+        }
+    );
+
+    test('a fake device without a key is never treated as invalid', () => {
+        const device = new TuyaAccessory({
+            id: 'bf1234567890abcdef12',
+            name: 'Fake Device',
+            fake: true,
+            connect: false,
+            log: makeLog(),
+        });
+        expect(device._invalidKey).toBe(false);
+        expect(device.log.error).not.toHaveBeenCalled();
+    });
+});
+
 describe('message handler routing', () => {
     const HANDLERS = ['_msgHandler_3_1', '_msgHandler_3_3', '_msgHandler_3_4', '_msgHandler_3_5'];
 

package/test/index.test.js

@@ -136,6 +136,36 @@ describe('TuyaLan — discovery routing', () => {
     });
 });
 
+describe('TuyaLan — debug.forceCloudFallback', () => {
+    test('skips LAN discovery so a keyed device never attaches a LAN backend', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: true}, devices: [SW()]});
+        expect(TuyaDiscovery.start).not.toHaveBeenCalled();
+        expect(TuyaDiscovery.on).not.toHaveBeenCalled();
+        expect(instanceFor('bf11111111111111').attachLan).not.toHaveBeenCalled();
+    });
+
+    test('the forced device keeps its shared cloud session as its only transport', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: true}, devices: [SW()]});
+        expect(propsFor('bf11111111111111').cloudApi).toBeDefined();
+    });
+
+    test('off (or absent) leaves discovery running as usual', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: false}, devices: [SW()]});
+        expect(TuyaDiscovery.start).toHaveBeenCalledTimes(1);
+    });
+
+    test('lenient boolean spellings are accepted', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: 'true'}, devices: [SW()]});
+        expect(TuyaDiscovery.start).not.toHaveBeenCalled();
+    });
+
+    test('without a cloud session, the unreachable device is reported as an error', () => {
+        const platform = run({debug: {forceCloudFallback: true}, devices: [SW()]});
+        expect(TuyaDiscovery.start).not.toHaveBeenCalled();
+        expect(platform.log.error).toHaveBeenCalled();
+    });
+});
+
 describe('TuyaLan — unconfigured device discovery', () => {
     const UNKNOWN = {id: 'bf99999999999999', ip: '10.0.0.9'};
     const BARE = 'Discovered a device that has not been configured yet (%s@%s).';