homebridge-tuya-plus 3.14.0-dev.3 → 3.14.0-dev.4

package/lib/TuyaCloudApi.js

@@ -0,0 +1,290 @@
+'use strict';
+
+/*
+ * TuyaCloudApi
+ * ------------
+ * A tiny, dependency-free client for the Tuya Cloud OpenAPI.
+ *
+ * This plugin is, and remains, a LAN-first plugin: almost every Tuya device is
+ * controlled locally over the network. A small class of devices, however,
+ * simply cannot be reached that way — most notably battery-powered "sleepy"
+ * devices (irrigation/faucet timers, door sensors, …). To save battery they
+ * spend nearly all their time asleep and only ever talk to Tuya's cloud (over
+ * MQTT) for a brief moment when they wake. They never keep the local TCP port
+ * (6668) open and never answer LAN discovery, so the cloud is the ONLY way to
+ * reach them. This client exists exclusively for those devices.
+ *
+ * Only the handful of endpoints the plugin needs are implemented:
+ *   - GET  /v1.0/token?grant_type=1        (auth — also yields the account uid)
+ *   - GET  /v1.0/devices/{id}/status       (read all data-points at once)
+ *   - POST /v1.0/devices/{id}/commands     (write data-points)
+ *   - POST /v1.0/iot-03/open-hub/access-config  (optional realtime MQTT config)
+ *
+ * Everything is signed with the Tuya "new" HMAC-SHA256 signature scheme, using
+ * only Node's built-in `https` + `crypto`, so the plugin gains no new runtime
+ * dependency for the core cloud path.
+ *
+ * Docs:
+ *   Signature : https://developer.tuya.com/en/docs/iot/new-singnature
+ *   Control   : https://developer.tuya.com/en/docs/cloud/device-control
+ *   Regions   : https://developer.tuya.com/en/docs/iot/api-request
+ */
+
+const https = require('https');
+const crypto = require('crypto');
+
+// SHA-256 of an empty string — the Content-SHA256 used for GET / empty-body requests.
+const EMPTY_BODY_SHA256 = crypto.createHash('sha256').update('').digest('hex');
+
+// Data-center base URLs. The region MUST match the one the Tuya / Smart Life
+// app account is registered in (App → Me → Settings → Account → Region);
+// cross-region calls are rejected by Tuya.
+const REGION_ENDPOINTS = {
+    cn: 'https://openapi.tuyacn.com',           // China
+    us: 'https://openapi.tuyaus.com',           // Western America (default)
+    'us-e': 'https://openapi-ueaz.tuyaus.com',  // Eastern America (Azure)
+    eu: 'https://openapi.tuyaeu.com',           // Central Europe
+    'eu-w': 'https://openapi-weaz.tuyaeu.com',  // Western Europe (Azure)
+    in: 'https://openapi.tuyain.com',           // India
+    sg: 'https://openapi-sg.iotbing.com'        // Singapore
+};
+
+// Tuya error codes that mean "the access token is no longer usable"; when we
+// see one we drop the cached token and retry the call once.
+const TOKEN_INVALID_CODES = new Set([1010, 1011, 1004]);
+
+class TuyaCloudApi {
+    constructor({accessId, accessKey, region, endpoint, username, password, countryCode, schema, log} = {}) {
+        this.log = log || console;
+        this.accessId = ('' + (accessId || '')).trim();
+        this.accessKey = ('' + (accessKey || '')).trim();
+
+        // Optional "Smart Home" project credentials. When a username/password
+        // are supplied we authenticate as that app account (so the cloud sees
+        // the devices linked to it); otherwise we use the simpler "Custom"
+        // project token flow (grant_type=1).
+        this.username = ('' + (username || '')).trim();
+        this.password = ('' + (password || '')).trim();
+        this.countryCode = ('' + (countryCode || '')).trim();
+        this.schema = (('' + (schema || '')).trim()) || 'tuyaSmart';
+
+        const r = ('' + (region || 'us')).trim().toLowerCase();
+        this.region = r;
+        this.endpoint = (('' + (endpoint || '')).trim()) || REGION_ENDPOINTS[r] || REGION_ENDPOINTS.us;
+        // Strip a trailing slash so path concatenation is predictable.
+        this.endpoint = this.endpoint.replace(/\/+$/, '');
+
+        this._token = null;        // current access_token
+        this.uid = null;           // linked app-account uid (needed for realtime MQTT)
+        this._tokenExpiry = 0;     // ms epoch when the token must be refreshed
+        this._tokenPromise = null; // in-flight token request (de-dupes concurrent callers)
+    }
+
+    isConfigured() {
+        return !!(this.accessId && this.accessKey);
+    }
+
+    // A stable key identifying this credential+region pair, so several devices
+    // that share the same cloud project can share one client (one token, one
+    // realtime connection).
+    static keyFor({accessId, region, endpoint, username} = {}) {
+        const r = ('' + (region || 'us')).trim().toLowerCase();
+        const e = (('' + (endpoint || '')).trim()) || REGION_ENDPOINTS[r] || REGION_ENDPOINTS.us;
+        return `${('' + (accessId || '')).trim()}:${('' + (username || '')).trim()}@${e.replace(/\/+$/, '')}`;
+    }
+
+    /* ----------------------------- signing ----------------------------- */
+
+    _hmac(str) {
+        return crypto.createHmac('sha256', this.accessKey).update(str, 'utf8').digest('hex').toUpperCase();
+    }
+
+    // Build the signed headers for a request. When `withToken` is true the
+    // current access_token is folded into the signature (business calls);
+    // otherwise the token-request variant is used (the token call itself).
+    // `t` and `nonce` are injectable for deterministic testing.
+    _signedHeaders({method, urlPath, bodyStr, withToken, t, nonce} = {}) {
+        t = t || Date.now().toString();
+        nonce = nonce || crypto.randomUUID();
+
+        const contentSha = bodyStr
+            ? crypto.createHash('sha256').update(bodyStr, 'utf8').digest('hex')
+            : EMPTY_BODY_SHA256;
+
+        // stringToSign = METHOD \n Content-SHA256 \n Signature-Headers \n Url
+        // Signature-Headers is intentionally empty (we fold none into the sign).
+        const stringToSign = [method.toUpperCase(), contentSha, '', urlPath].join('\n');
+        const str = (withToken
+            ? this.accessId + this._token + t + nonce
+            : this.accessId + t + nonce) + stringToSign;
+
+        const headers = {
+            'client_id': this.accessId,
+            'sign': this._hmac(str),
+            't': t,
+            'sign_method': 'HMAC-SHA256',
+            'nonce': nonce,
+            'Content-Type': 'application/json'
+        };
+        if (withToken) headers['access_token'] = this._token;
+        return headers;
+    }
+
+    /* ------------------------------ token ------------------------------ */
+
+    async _ensureToken() {
+        if (this._token && Date.now() < this._tokenExpiry) return this._token;
+        if (this._tokenPromise) return this._tokenPromise;
+
+        this._tokenPromise = (async () => {
+            const res = this._useSmartHomeLogin()
+                ? await this._loginSmartHome()
+                : await this._loginCustom();
+            if (!res || res.success !== true || !res.result || !res.result.access_token) {
+                throw new Error(`token request failed: ${this._describeError(res)}`);
+            }
+            this._token = res.result.access_token;
+            this.uid = res.result.uid || this.uid;
+            // Refresh a minute early so a token never expires mid-request.
+            const ttl = (parseInt(res.result.expire_time) || 7200) * 1000;
+            this._tokenExpiry = Date.now() + Math.max(60000, ttl - 60000);
+            return this._token;
+        })();
+
+        try {
+            return await this._tokenPromise;
+        } finally {
+            this._tokenPromise = null;
+        }
+    }
+
+    _useSmartHomeLogin() {
+        return !!(this.username && this.password);
+    }
+
+    // "Custom" project: GET /v1.0/token?grant_type=1 (token-variant signature).
+    _loginCustom() {
+        const urlPath = '/v1.0/token?grant_type=1';
+        const headers = this._signedHeaders({method: 'GET', urlPath, bodyStr: '', withToken: false});
+        return this._httpsRequest('GET', urlPath, headers, null);
+    }
+
+    // "Smart Home" project: authenticate as the linked app account. The password
+    // is sent as a lowercase hex MD5; the request is signed with the token
+    // (no-access-token) variant since we don't hold a token yet.
+    _loginSmartHome() {
+        const urlPath = '/v1.0/iot-01/associated-users/actions/authorized-login';
+        const body = {
+            country_code: this.countryCode,
+            username: this.username,
+            password: crypto.createHash('md5').update('' + this.password).digest('hex'),
+            schema: this.schema
+        };
+        const bodyStr = JSON.stringify(body);
+        const headers = this._signedHeaders({method: 'POST', urlPath, bodyStr, withToken: false});
+        return this._httpsRequest('POST', urlPath, headers, bodyStr);
+    }
+
+    _invalidateToken() {
+        this._token = null;
+        this._tokenExpiry = 0;
+    }
+
+    /* --------------------------- requests ------------------------------ */
+
+    async request(method, urlPath, body, _retried) {
+        await this._ensureToken();
+        const bodyStr = body ? JSON.stringify(body) : '';
+        const headers = this._signedHeaders({method, urlPath, bodyStr, withToken: true});
+        const res = await this._httpsRequest(method, urlPath, headers, bodyStr || null);
+
+        if (res && res.success === false) {
+            if (!_retried && TOKEN_INVALID_CODES.has(res.code)) {
+                this._invalidateToken();
+                return this.request(method, urlPath, body, true);
+            }
+            throw new Error(`${method} ${urlPath} failed: ${this._describeError(res)}`);
+        }
+        return res;
+    }
+
+    // Read every reported data-point in one call → array of {code, value}.
+    async getStatus(deviceId) {
+        const res = await this.request('GET', `/v1.0/devices/${encodeURIComponent(deviceId)}/status`);
+        return (res && Array.isArray(res.result)) ? res.result : [];
+    }
+
+    // Issue one or more commands: [{code, value}, …].
+    async sendCommands(deviceId, commands) {
+        if (!Array.isArray(commands) || !commands.length) return true;
+        const res = await this.request('POST', `/v1.0/devices/${encodeURIComponent(deviceId)}/commands`, {commands});
+        return !!(res && res.result);
+    }
+
+    // Fetch broker credentials for the realtime MQTT message service. Returns
+    // the raw `result` object (url, client_id, username, password, source_topic,
+    // expire_time, …) or throws. Requires the account uid (from the token call)
+    // and that the project has the "Message Service" API authorized.
+    async getMqttConfig(linkId) {
+        await this._ensureToken();
+        if (!this.uid) throw new Error('no account uid available for MQTT config');
+        const body = {
+            uid: this.uid,
+            link_id: linkId,
+            link_type: 'mqtt',
+            topics: 'device',
+            msg_encrypted_version: '2.0'
+        };
+        const res = await this.request('POST', '/v1.0/iot-03/open-hub/access-config', body);
+        if (!res || res.success !== true || !res.result) {
+            throw new Error(`MQTT config request failed: ${this._describeError(res)}`);
+        }
+        return res.result;
+    }
+
+    _describeError(res) {
+        if (!res) return 'no/empty response';
+        if (res.msg || res.code) return `${res.msg || ''} (code ${res.code})`.trim();
+        return 'unexpected response';
+    }
+
+    /* ------------------------- transport ------------------------------- */
+
+    _httpsRequest(method, urlPath, headers, bodyStr) {
+        return new Promise((resolve, reject) => {
+            let url;
+            try {
+                url = new URL(this.endpoint + urlPath);
+            } catch (ex) {
+                return reject(ex);
+            }
+
+            const req = https.request({
+                hostname: url.hostname,
+                port: url.port || 443,
+                path: url.pathname + url.search,
+                method,
+                headers
+            }, resp => {
+                let data = '';
+                resp.setEncoding('utf8');
+                resp.on('data', chunk => { data += chunk; });
+                resp.on('end', () => {
+                    try {
+                        resolve(JSON.parse(data));
+                    } catch (ex) {
+                        reject(new Error(`Tuya Cloud returned non-JSON (HTTP ${resp.statusCode}): ${('' + data).slice(0, 200)}`));
+                    }
+                });
+            });
+
+            req.on('error', reject);
+            req.setTimeout(20000, () => req.destroy(new Error('request timed out')));
+            if (bodyStr) req.write(bodyStr);
+            req.end();
+        });
+    }
+}
+
+TuyaCloudApi.REGION_ENDPOINTS = REGION_ENDPOINTS;
+module.exports = TuyaCloudApi;

package/lib/TuyaCloudDevice.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const EventEmitter = require('events');
+
+/*
+ * TuyaCloudDevice
+ * ---------------
+ * A drop-in replacement for TuyaAccessory (the LAN device class) that talks to
+ * a device through the Tuya Cloud instead of the local network. It deliberately
+ * exposes the exact same minimal contract every accessory relies on, so the
+ * existing accessories (IrrigationSystemAccessory, …) work unchanged on top:
+ *
+ *   - `context`            device config (name, id, type, …)
+ *   - `state`              current data-points  { <code>: value, … }
+ *   - `connected`          boolean
+ *   - `_connect()`         start talking to the device
+ *   - `update(dps)`        write data-points
+ *   - 'connect' / 'change' events  (change → (changes, state))
+ *
+ * The one meaningful difference from the LAN class is the data-point KEY. The
+ * LAN protocol addresses data-points by numeric id (1, 2, …); the cloud speaks
+ * string "codes" (e.g. `switch_1`, `battery_percentage`). So `state` here is
+ * keyed by code, and accessories used over the cloud are configured with codes.
+ * The device logs its codes on connect to make that configuration obvious.
+ *
+ * Updates are delivered by Tuya's realtime MQTT message service (see
+ * TuyaCloudMessaging) — there is no periodic polling. Two REST calls are still
+ * inherent to the cloud, because MQTT only carries *changes* and is
+ * *receive-only*:
+ *   - one `GET /status` to learn the initial state on connect (and again as a
+ *     catch-up whenever the realtime stream (re)connects), and
+ *   - `POST /commands` to actually control the device.
+ */
+
+class TuyaCloudDevice extends EventEmitter {
+    constructor(props = {}) {
+        super();
+        this.log = props.log || console;
+        this.api = props.cloudApi;
+        this.messaging = props.messaging || null; // shared realtime stream
+
+        // Keep a plain config object on `context`, mirroring TuyaAccessory, but
+        // without the live helper objects we were handed.
+        this.context = {...props};
+        delete this.context.cloudApi;
+        delete this.context.messaging;
+        delete this.context.log;
+
+        this.state = {};
+        this.connected = false;
+        this._stopped = false;
+        this._retryTimer = null;
+
+        if (props.connect !== false) this._connect();
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  Connect: read initial state, announce, then let realtime keep it fresh.
+     * ------------------------------------------------------------------ */
+
+    async _connect() {
+        if (!this.api || !this.api.isConfigured()) {
+            return this.log.error(`${this.context.name}: Tuya Cloud is not configured (missing accessId/accessKey).`);
+        }
+
+        try {
+            const status = await this.api.getStatus(this.context.id);
+            this.state = this._statusToState(status);
+            this.connected = true;
+
+            this._logDiscoveredCodes(status);
+
+            this.emit('connect');
+            // Accessories register their characteristics off the first 'change'.
+            this.emit('change', {...this.state}, this.state);
+
+            this._subscribeRealtime();
+        } catch (ex) {
+            this.log.error(`${this.context.name}: failed to connect to Tuya Cloud: ${ex.message}`);
+            // Retry later — credentials/permissions/network may recover.
+            if (!this._stopped) {
+                this._retryTimer = setTimeout(() => this._connect(), 30000);
+            }
+        }
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  Realtime (shared MQTT stream)
+     * ------------------------------------------------------------------ */
+
+    _subscribeRealtime() {
+        if (!this.messaging) {
+            return this.log.warn(`${this.context.name}: realtime updates are unavailable (no MQTT). Control still works, but external changes (physical buttons, the device's own timers) won't be reflected until restart. Ensure the "mqtt" package is installed and realtime isn't disabled in the cloud config.`);
+        }
+        // Register the reconnect catch-up handler before starting, so the very
+        // first 'online' is caught. On any (re)connect we re-read the full state
+        // to recover anything missed while the stream was down.
+        this.messaging.on('online', () => this._refreshState());
+        this.messaging.subscribeDevice(this.context.id, status => this._applyStatus(status));
+    }
+
+    async _refreshState() {
+        if (this._stopped) return;
+        try {
+            const status = await this.api.getStatus(this.context.id);
+            this._applyStatus(status);
+        } catch (ex) {
+            this.log.debug(`${this.context.name}: cloud state refresh failed: ${ex.message}`);
+        }
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  State helpers
+     * ------------------------------------------------------------------ */
+
+    // Convert a Tuya `[{code, value}]` status array into a flat { code: value }.
+    _statusToState(status) {
+        const state = {};
+        (status || []).forEach(item => {
+            if (item && typeof item.code === 'string') state[item.code] = item.value;
+        });
+        return state;
+    }
+
+    // Apply a fresh snapshot (initial / catch-up) or a realtime delta, diff it
+    // against what we hold, and emit only what changed — exactly mirroring
+    // TuyaAccessory._change so accessories behave identically.
+    _applyStatus(status) {
+        const incoming = this._statusToState(status);
+        const changes = {};
+        Object.keys(incoming).forEach(code => {
+            if (incoming[code] !== this.state[code]) changes[code] = incoming[code];
+        });
+        if (Object.keys(changes).length) {
+            this.state = {...this.state, ...incoming};
+            this.emit('change', changes, this.state);
+        }
+        return changes;
+    }
+
+    _logDiscoveredCodes(status) {
+        try {
+            const list = (status || []).map(i => `${i.code}=${JSON.stringify(i.value)}`).join(', ');
+            this.log.info(`${this.context.name}: Tuya Cloud data-point codes → ${list || '(none reported)'}`);
+        } catch (_) { /* logging must never throw */ }
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  Writes
+     * ------------------------------------------------------------------ */
+
+    // Write data-points. `dps` is keyed by code → value (the accessory was
+    // configured with codes). We deliberately do NOT optimistically mutate
+    // `this.state`: the accessory already reflects the user's intent in HomeKit
+    // immediately, and leaving `state` untouched lets the realtime stream
+    // confirm the real device state without a spurious "revert" while a sleepy
+    // device catches up. Returns truthy like TuyaAccessory.update().
+    update(dps) {
+        if (!dps || typeof dps !== 'object') return true;
+
+        const commands = Object.keys(dps).map(code => ({code, value: dps[code]}));
+        if (!commands.length) return true;
+
+        if (!this.connected) {
+            this.log.debug(`${this.context.name}: skipping cloud write, not connected`);
+            return false;
+        }
+
+        this.api.sendCommands(this.context.id, commands)
+            .then(ok => {
+                if (!ok) this.log.warn(`${this.context.name}: Tuya Cloud rejected command ${JSON.stringify(commands)}`);
+            })
+            .catch(ex => this.log.error(`${this.context.name}: cloud command failed: ${ex.message}`));
+
+        return true;
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  Teardown (tidy; Homebridge doesn't strictly require it)
+     * ------------------------------------------------------------------ */
+
+    stop() {
+        this._stopped = true;
+        if (this._retryTimer) { clearTimeout(this._retryTimer); this._retryTimer = null; }
+    }
+}
+
+module.exports = TuyaCloudDevice;