homebridge-tuya-plus 3.14.0-dev.35 → 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/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.35",
+  "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/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');
+    });
+});