homebridge-tuya-plus 3.14.0-dev.34 → 3.14.0-dev.36

package/AGENTS.md

@@ -144,6 +144,12 @@ optional, off-by-default flags read through `_debugConfig()` and coerced with
   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).
+- `debug.logCloudHttp` — trace every Tuya Cloud HTTP request/response (method,
+  path, headers, body, status, response) at `debug`, with all credentials
+  (token, signature, password, access key/id, uid) redacted. Use it to see
+  exactly what a failing `POST …/commands` sent and how the cloud replied (e.g.
+  the `code`/`value` behind a `2008`). Verbose and per-request — keep it off in
+  normal operation, and remember Homebridge debug logging must be on to see it.
 
 ## Git & PR workflow
 

package/index.js

@@ -402,7 +402,11 @@ class TuyaLan {
       );
     }
 
-    this.cloudApi = new TuyaCloudApi({ ...cloudCfg, log: this.log });
+    this.cloudApi = new TuyaCloudApi({
+      ...cloudCfg,
+      log: this.log,
+      logHttp: coerceBoolean(this._debugConfig().logCloudHttp),
+    });
     this.cloudMessaging = new TuyaCloudMessaging({
       api: this.cloudApi,
       log: this.log,

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/lib/TuyaCloudApi.js

@@ -53,9 +53,18 @@ const REGION_ENDPOINTS = {
 // see one we drop the cached token and retry the call once.
 const TOKEN_INVALID_CODES = new Set([1010, 1011, 1004]);
 
+// Header/body/response field names whose values may be a credential or token.
+// Their values are masked before an HTTP trace is logged (debug.logCloudHttp),
+// so the trace never leaks the access token, signature, account password, uid,
+// or access key/id.
+const SECRET_FIELDS = /^(access_token|refresh_token|password|sign|secret|access_?key|access_?id|client_id|uid|localKey|key)$/i;
+
 class TuyaCloudApi {
-    constructor({accessId, accessKey, region, endpoint, username, password, countryCode, schema, log} = {}) {
+    constructor({accessId, accessKey, region, endpoint, username, password, countryCode, schema, log, logHttp} = {}) {
         this.log = log || console;
+        // Dev/diagnostic switch (debug.logCloudHttp): trace every cloud HTTP
+        // request/response, with credentials redacted. Off by default.
+        this.logHttp = !!logHttp;
         this.accessId = ('' + (accessId || '')).trim();
         this.accessKey = ('' + (accessKey || '')).trim();
 
@@ -280,6 +289,46 @@ class TuyaCloudApi {
 
     /* ------------------------- transport ------------------------------- */
 
+    _maskSecret(value) {
+        const s = '' + value;
+        return s.length <= 8 ? '***' : `${s.slice(0, 4)}…${s.slice(-4)}`;
+    }
+
+    // Deep copy with any credential-looking field masked, so a full HTTP trace
+    // can be logged without leaking the token, signature, account password, or
+    // access key/id (the device `value`s themselves are not secret and stay).
+    _redactForLog(value) {
+        if (Array.isArray(value)) return value.map(v => this._redactForLog(v));
+        if (value && typeof value === 'object') {
+            const out = {};
+            for (const k of Object.keys(value)) {
+                out[k] = SECRET_FIELDS.test(k) ? this._maskSecret(value[k]) : this._redactForLog(value[k]);
+            }
+            return out;
+        }
+        return value;
+    }
+
+    // One redacted request/response trace line, emitted only when the
+    // debug.logCloudHttp switch is set. It's routine, per-request and verbose, so
+    // it goes to debug. Never throws and never leaks a secret (see _redactForLog).
+    _traceHttp(method, urlPath, headers, bodyStr, statusCode, responseBody) {
+        if (!this.logHttp) return;
+        try {
+            let reqBody = '(none)';
+            if (bodyStr) {
+                try { reqBody = JSON.stringify(this._redactForLog(JSON.parse(bodyStr))); }
+                catch (_) { reqBody = ('' + bodyStr).slice(0, 200); }
+            }
+            this.log.debug(
+                `[TuyaCloud HTTP] ${method} ${urlPath} → HTTP ${statusCode}` +
+                ` | req.headers=${JSON.stringify(this._redactForLog(headers))}` +
+                ` | req.body=${reqBody}` +
+                ` | res=${JSON.stringify(this._redactForLog(responseBody))}`
+            );
+        } catch (_) { /* logging must never throw */ }
+    }
+
     _httpsRequest(method, urlPath, headers, bodyStr) {
         return new Promise((resolve, reject) => {
             let url;
@@ -300,15 +349,22 @@ class TuyaCloudApi {
                 resp.setEncoding('utf8');
                 resp.on('data', chunk => { data += chunk; });
                 resp.on('end', () => {
+                    let parsed;
                     try {
-                        resolve(JSON.parse(data));
+                        parsed = JSON.parse(data);
                     } catch (ex) {
-                        reject(new Error(`Tuya Cloud returned non-JSON (HTTP ${resp.statusCode}): ${('' + data).slice(0, 200)}`));
+                        this._traceHttp(method, urlPath, headers, bodyStr, resp.statusCode, data);
+                        return reject(new Error(`Tuya Cloud returned non-JSON (HTTP ${resp.statusCode}): ${('' + data).slice(0, 200)}`));
                     }
+                    this._traceHttp(method, urlPath, headers, bodyStr, resp.statusCode, parsed);
+                    resolve(parsed);
                 });
             });
 
-            req.on('error', reject);
+            req.on('error', err => {
+                if (this.logHttp) { try { this.log.debug(`[TuyaCloud HTTP] ${method} ${urlPath} → error: ${err.message}`); } catch (_) { /* never throw */ } }
+                reject(err);
+            });
             req.setTimeout(20000, () => req.destroy(new Error('request timed out')));
             if (bodyStr) req.write(bodyStr);
             req.end();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.34",
+  "version": "3.14.0-dev.36",
   "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/TuyaCloudApi.test.js

@@ -219,3 +219,58 @@ describe('TuyaCloudApi — endpoints', () => {
         await expect(api.request('GET', '/x')).rejects.toThrow(/no permissions/);
     });
 });
+
+describe('TuyaCloudApi — HTTP trace (debug.logCloudHttp)', () => {
+    const makeLog = () => ({info: () => {}, warn: () => {}, error: () => {}, debug: jest.fn()});
+
+    test('logHttp is off unless explicitly enabled', () => {
+        expect(makeApi().logHttp).toBe(false);
+        expect(makeApi({logHttp: true}).logHttp).toBe(true);
+    });
+
+    test('redaction masks credentials but keeps device data', () => {
+        const api = makeApi();
+        const redacted = api._redactForLog({
+            client_id: 'aid1234567890', access_token: 'tok_abcdef123456', sign: 'SIGNATUREVALUE', t: '1700', nonce: 'n-1',
+            result: {access_token: 'inner-token-xyz', refresh_token: 'refresh-xyz', uid: 'uid-1234567', online: true},
+            commands: [{code: 'switch_1', value: true}]
+        });
+
+        expect(redacted.client_id).not.toBe('aid1234567890');
+        expect(redacted.access_token).not.toBe('tok_abcdef123456');
+        expect(redacted.sign).not.toBe('SIGNATUREVALUE');
+        expect(redacted.result.access_token).not.toBe('inner-token-xyz');
+        expect(redacted.result.refresh_token).not.toBe('refresh-xyz');
+        expect(redacted.result.uid).not.toBe('uid-1234567');
+        // Non-secret fields and the actual device data-points pass through intact.
+        expect(redacted.t).toBe('1700');
+        expect(redacted.nonce).toBe('n-1');
+        expect(redacted.result.online).toBe(true);
+        expect(redacted.commands).toEqual([{code: 'switch_1', value: true}]);
+    });
+
+    test('no trace is logged when the switch is off', () => {
+        const log = makeLog();
+        const api = makeApi({log});
+        api._traceHttp('POST', '/v1.0/devices/dev/commands', {sign: 'X'}, '{"commands":[]}', 200, {success: true});
+        expect(log.debug).not.toHaveBeenCalled();
+    });
+
+    test('a trace carries the request/response but never the raw token or signature', () => {
+        const log = makeLog();
+        const api = makeApi({log, logHttp: true});
+        const headers = {client_id: 'aid', sign: 'SIGN_SECRET_VALUE', access_token: 'TOKEN_SECRET_VALUE', t: '1', nonce: 'n', 'Content-Type': 'application/json'};
+        const body = JSON.stringify({commands: [{code: 'wfh_open', value: true}]});
+
+        api._traceHttp('POST', '/v1.0/devices/dev/commands', headers, body, 200, {success: false, code: 2008, msg: 'command or value not support'});
+
+        expect(log.debug).toHaveBeenCalledTimes(1);
+        const line = log.debug.mock.calls[0][0];
+        expect(line).toContain('POST /v1.0/devices/dev/commands');
+        expect(line).toContain('wfh_open');           // the attempted command is visible
+        expect(line).toContain('2008');                // and the cloud's verdict
+        expect(line).toContain('command or value not support');
+        expect(line).not.toContain('TOKEN_SECRET_VALUE'); // …but secrets are not
+        expect(line).not.toContain('SIGN_SECRET_VALUE');
+    });
+});