homebridge-cync-app 0.1.6 → 0.1.8

package/src/cync/config-client.ts

@@ -64,6 +64,11 @@ export interface CyncCloudConfig {
 	meshes: CyncDeviceMesh[];
 }
 
+export interface CyncRefreshResponse {
+	accessToken: string;
+	refreshToken?: string;
+	expiresAt?: number;
+}
 
 export interface CyncLogger {
 	debug(message: string, ...args: unknown[]): void;
@@ -219,6 +224,193 @@ export class ConfigClient {
 		};
 	}
 
+	/**
+	 * Password-only login for background refresh.
+	 *
+	 * This uses the /user_auth endpoint (no two_factor) and is intended
+	 * for automatic re-auth when the access token has expired, after an
+	 * initial 2FA bootstrap has already been completed.
+	 */
+	public async loginWithPassword(
+		email: string,
+		password: string,
+	): Promise<CyncLoginSession & { refreshToken?: string; expiresAt?: number }> {
+		const url = `${CYNC_API_BASE}user_auth`;
+		this.log.debug('Logging into Cync with password-only auth for %s…', email);
+
+		const body = {
+			corp_id: CORP_ID,
+			email,
+			password,
+			resource: ConfigClient.randomLoginResource(),
+		};
+
+		const res = (await fetch(url, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+			},
+			body: JSON.stringify(body),
+		})) as HttpResponse;
+
+		const json: unknown = await res.json().catch(async () => {
+			const text = await res.text().catch(() => '');
+			throw new Error(`Cync password login returned non-JSON payload: ${text}`);
+		});
+
+		if (!res.ok) {
+			this.log.error(
+				'Cync password login failed: HTTP %d %s %o',
+				res.status,
+				res.statusText,
+				json,
+			);
+			const errBody = json as CyncErrorBody;
+			throw new Error(
+				errBody.error?.msg ??
+				`Cync password login failed with status ${res.status} ${res.statusText}`,
+			);
+		}
+
+		const obj = json as Record<string, unknown>;
+		this.log.debug('Cync password login response: keys=%o', Object.keys(obj));
+
+		const accessTokenRaw = obj.access_token ?? obj.accessToken;
+		const userIdRaw = obj.user_id ?? obj.userId;
+		const authorizeRaw = obj.authorize;
+		const refreshTokenRaw = obj.refresh_token ?? obj.refreshToken;
+		const expiresAtRaw = obj.expires_at ?? obj.expiresAt;
+
+		const accessToken =
+			typeof accessTokenRaw === 'string' && accessTokenRaw.length > 0
+				? accessTokenRaw
+				: undefined;
+
+		const userId =
+			userIdRaw !== undefined && userIdRaw !== null
+				? String(userIdRaw)
+				: undefined;
+
+		const authorize =
+			typeof authorizeRaw === 'string' && authorizeRaw.length > 0
+				? authorizeRaw
+				: undefined;
+
+		if (!accessToken || !userId) {
+			this.log.error(
+				'Cync password login missing access_token or user_id: %o',
+				json,
+			);
+			throw new Error(
+				'Cync password login response missing access_token or user_id',
+			);
+		}
+
+		let refreshToken: string | undefined;
+		if (typeof refreshTokenRaw === 'string' && refreshTokenRaw.length > 0) {
+			refreshToken = refreshTokenRaw;
+		}
+
+		let expiresAt: number | undefined;
+		if (typeof expiresAtRaw === 'number') {
+			expiresAt = expiresAtRaw;
+		}
+
+		this.accessToken = accessToken;
+		this.userId = userId;
+		this.authorize = authorize ?? null;
+
+		this.log.info('Cync password login successful; userId=%s', userId);
+
+		return {
+			accessToken,
+			userId,
+			authorize,
+			raw: {
+				...obj,
+				refreshToken,
+				expiresAt,
+			},
+			refreshToken,
+			expiresAt,
+		};
+	}
+
+	/**
+	 * Refresh the access token using a stored refresh token.
+	 *
+	 * This mirrors the 2FA login flow in shape, but only exchanges the
+	 * refresh_token for a new access_token (and possibly a new refresh_token).
+	 */
+	public async refreshAccessToken(refreshToken: string): Promise<CyncRefreshResponse> {
+		const url = `${CYNC_API_BASE}user_auth/refresh`;
+		this.log.debug('Refreshing Cync access token…');
+
+		const body = {
+			corp_id: CORP_ID,
+			refresh_token: refreshToken,
+			resource: ConfigClient.randomLoginResource(),
+		};
+
+		const res = (await fetch(url, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+			},
+			body: JSON.stringify(body),
+		})) as HttpResponse;
+
+		const json: unknown = await res.json().catch(async () => {
+			const text = await res.text().catch(() => '');
+			throw new Error(`Cync refresh returned non-JSON payload: ${text}`);
+		});
+
+		if (!res.ok) {
+			this.log.error(
+				'Cync refresh failed: HTTP %d %s %o',
+				res.status,
+				res.statusText,
+				json,
+			);
+			const errBody = json as CyncErrorBody;
+			const msg =
+				errBody.error?.msg ??
+				`Cync refresh failed with status ${res.status} ${res.statusText}`;
+			throw new Error(msg);
+		}
+
+		const obj = json as Record<string, unknown>;
+		this.log.debug('Cync refresh response: keys=%o', Object.keys(obj));
+
+		const accessTokenRaw = obj.access_token ?? obj.accessToken;
+		const refreshTokenRaw = obj.refresh_token ?? obj.refreshToken;
+		const expiresAtRaw = obj.expires_at ?? obj.expiresAt;
+
+		const accessToken =
+			typeof accessTokenRaw === 'string' && accessTokenRaw.length > 0
+				? accessTokenRaw
+				: undefined;
+
+		if (!accessToken) {
+			this.log.error('Cync refresh missing access_token: %o', json);
+			throw new Error('Cync refresh response missing access_token');
+		}
+
+		const next: CyncRefreshResponse = {
+			accessToken,
+		};
+
+		if (typeof refreshTokenRaw === 'string' && refreshTokenRaw.length > 0) {
+			next.refreshToken = refreshTokenRaw;
+		}
+
+		if (typeof expiresAtRaw === 'number') {
+			next.expiresAt = expiresAtRaw;
+		}
+
+		return next;
+	}
+
 	/**
 	 * Fetch the list of meshes/devices for the current user from the cloud.
 	 *

package/src/cync/cync-accessory-helpers.ts

@@ -0,0 +1,233 @@
+// src/cync/cync-accessory-helpers.ts
+import type {
+	API,
+	Logger,
+	PlatformAccessory,
+} from 'homebridge';
+
+import type { CyncDevice } from './config-client.js';
+import type { TcpClient } from './tcp-client.js';
+import { lookupDeviceModel } from './device-catalog.js';
+
+// Narrowed view of the Cync device properties returned by getDeviceProperties()
+type CyncDeviceRaw = {
+  displayName?: string;
+  firmwareVersion?: string;
+  mac?: string;
+  wifiMac?: string;
+  deviceType?: number;
+  deviceID?: number;
+  [key: string]: unknown;
+};
+
+// CyncDevice as seen by the platform, possibly enriched with a `raw` block
+type CyncDeviceWithRaw = CyncDevice & {
+  raw?: CyncDeviceRaw;
+};
+
+// Context stored on the accessory
+export interface CyncAccessoryContext {
+  cync?: {
+    meshId: string;
+    deviceId: string;
+    productId?: string;
+
+    on?: boolean;
+    brightness?: number; // 0–100 (LAN "level")
+
+    // Color state (local cache, not yet read from LAN frames)
+    hue?: number;          // 0–360
+    saturation?: number;   // 0–100
+    rgb?: { r: number; g: number; b: number };
+    colorActive?: boolean; // true if we last set RGB color
+  };
+  [key: string]: unknown;
+}
+
+// Minimal runtime “env” that accessory modules need from the platform
+export interface CyncAccessoryEnv {
+  log: Logger;
+  api: API;
+  tcpClient: TcpClient;
+
+  isDeviceProbablyOffline(deviceId: string): boolean;
+  markDeviceSeen(deviceId: string): void;
+  startPollingDevice(deviceId: string): void;
+  registerAccessoryForDevice(deviceId: string, accessory: PlatformAccessory): void;
+}
+
+/**
+ * HSV (HomeKit style) → RGB helper used by color lights.
+ */
+export function hsvToRgb(hue: number, saturation: number, value: number): { r: number; g: number; b: number } {
+	const h = ((hue % 360) + 360) % 360;
+	const s = Math.max(0, Math.min(100, saturation)) / 100;
+	const v = Math.max(0, Math.min(100, value)) / 100;
+
+	if (s === 0) {
+		const grey = Math.round(v * 255);
+		return { r: grey, g: grey, b: grey };
+	}
+
+	const sector = h / 60;
+	const i = Math.floor(sector);
+	const f = sector - i;
+
+	const p = v * (1 - s);
+	const q = v * (1 - s * f);
+	const t = v * (1 - s * (1 - f));
+
+	let r = 0;
+	let g = 0;
+	let b = 0;
+
+	switch (i) {
+	case 0:
+		r = v;
+		g = t;
+		b = p;
+		break;
+	case 1:
+		r = q;
+		g = v;
+		b = p;
+		break;
+	case 2:
+		r = p;
+		g = v;
+		b = t;
+		break;
+	case 3:
+		r = p;
+		g = q;
+		b = v;
+		break;
+	case 4:
+		r = t;
+		g = p;
+		b = v;
+		break;
+	default:
+		r = v;
+		g = p;
+		b = q;
+		break;
+	}
+
+	return {
+		r: Math.round(r * 255),
+		g: Math.round(g * 255),
+		b: Math.round(b * 255),
+	};
+}
+
+/**
+ * Resolve the numeric device type from cloud + raw device shape.
+ */
+export function resolveDeviceType(device: CyncDevice): number | undefined {
+	const typedDevice = device as unknown as {
+    device_type?: number;
+    raw?: { deviceType?: number | string };
+  };
+
+	if (typeof typedDevice.device_type === 'number') {
+		return typedDevice.device_type;
+	}
+
+	const rawType = typedDevice.raw?.deviceType;
+	if (typeof rawType === 'number') {
+		return rawType;
+	}
+
+	if (typeof rawType === 'string' && rawType.trim() !== '') {
+		const parsed = Number(rawType.trim());
+		if (!Number.isNaN(parsed)) {
+			return parsed;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Populate the standard Accessory Information service with Cync metadata.
+ */
+export function applyAccessoryInformationFromCyncDevice(
+	api: API,
+	accessory: PlatformAccessory,
+	device: CyncDevice,
+	deviceName: string,
+	deviceId: string,
+): void {
+	const infoService = accessory.getService(api.hap.Service.AccessoryInformation);
+	if (!infoService) {
+		return;
+	}
+
+	const Characteristic = api.hap.Characteristic;
+	const deviceWithRaw = device as CyncDeviceWithRaw;
+	const rawDevice = deviceWithRaw.raw ?? {};
+
+	// Name: keep in sync with how we present the accessory
+	const name = deviceName || accessory.displayName;
+	infoService.updateCharacteristic(Characteristic.Name, name);
+
+	// Manufacturer: fixed for all Cync devices
+	infoService.updateCharacteristic(Characteristic.Manufacturer, 'GE Lighting');
+
+	// Model: prefer catalog entry (Cync app-style model name), fall back to raw info
+	const resolvedType = resolveDeviceType(device);
+	const catalogEntry = typeof resolvedType === 'number'
+		? lookupDeviceModel(resolvedType)
+		: undefined;
+
+	let model: string;
+
+	if (catalogEntry) {
+		// Use the Cync app-style model name
+		model = catalogEntry.modelName;
+
+		// Persist for debugging / future use
+		const ctx = accessory.context as Record<string, unknown>;
+		ctx.deviceType = resolvedType;
+		ctx.modelName = catalogEntry.modelName;
+		if (catalogEntry.marketingName) {
+			ctx.marketingName = catalogEntry.marketingName;
+		}
+	} else {
+		// Fallback: use device displayName + type
+		const modelBase =
+      typeof rawDevice.displayName === 'string' && rawDevice.displayName.trim().length > 0
+      	? rawDevice.displayName.trim()
+      	: 'Cync Device';
+
+		const modelSuffix =
+      typeof resolvedType === 'number'
+      	? ` (Type ${resolvedType})`
+      	: '';
+
+		model = modelBase + modelSuffix;
+	}
+
+	infoService.updateCharacteristic(Characteristic.Model, model);
+
+	// Serial: prefer wifiMac, then mac, then deviceID, then the string deviceId
+	const serial =
+    (typeof rawDevice.wifiMac === 'string' && rawDevice.wifiMac.trim().length > 0)
+    	? rawDevice.wifiMac.trim()
+    	: (typeof rawDevice.mac === 'string' && rawDevice.mac.trim().length > 0)
+    		? rawDevice.mac.trim()
+    		: (rawDevice.deviceID !== undefined
+    			? String(rawDevice.deviceID)
+    			: deviceId);
+
+	infoService.updateCharacteristic(Characteristic.SerialNumber, serial);
+
+	// Firmware revision, if present
+	if (typeof rawDevice.firmwareVersion === 'string' && rawDevice.firmwareVersion.trim().length > 0) {
+		infoService.updateCharacteristic(
+			Characteristic.FirmwareRevision,
+			rawDevice.firmwareVersion.trim(),
+		);
+	}
+}

package/src/cync/cync-client.ts

@@ -52,6 +52,93 @@ export class CyncClient {
 	// Optional LAN update hook for the platform
 	private lanUpdateHandler: ((update: unknown) => void) | null = null;
 
+	// ### 🧩 Password Login Helper: background username/password login for new tokens
+	private async loginWithPasswordForToken(): Promise<CyncTokenData | null> {
+		const { username, password } = this.loginConfig;
+
+		if (!username || !password) {
+			this.log.error(
+				'CyncClient: cannot perform password login; username or password is missing from config.',
+			);
+			return null;
+		}
+
+		try {
+			this.log.warn(
+				'CyncClient: performing background username/password login (no OTP) to obtain a fresh token…',
+			);
+
+			const session = await this.configClient.loginWithPassword(
+				username.trim(),
+				password,
+			);
+
+			const raw = session.raw as Record<string, unknown>;
+			const authorize =
+				typeof raw.authorize === 'string' ? raw.authorize : undefined;
+
+			const s = session as unknown as SessionWithPossibleTokens;
+			const access = s.accessToken ?? s.jwt;
+
+			if (!access) {
+				this.log.error(
+					'CyncClient: password login session did not return an access token.',
+				);
+				return null;
+			}
+
+			const refresh = s.refreshToken ?? s.refreshJwt;
+			const expiresAt = s.expiresAt;
+
+			let lanLoginCode: string | undefined;
+			if (authorize) {
+				const userIdNum = Number.parseInt(session.userId, 10);
+				if (Number.isFinite(userIdNum) && userIdNum >= 0) {
+					const lanBlob = this.buildLanLoginCode(authorize, userIdNum);
+					lanLoginCode = Buffer.from(lanBlob).toString('base64');
+				} else {
+					this.log.warn(
+						'CyncClient: password login returned non-numeric userId=%s; LAN login code not generated.',
+						session.userId,
+					);
+				}
+			} else {
+				this.log.warn(
+					'CyncClient: password login response missing "authorize"; LAN login may be disabled.',
+				);
+			}
+
+			const next: CyncTokenData = {
+				userId: String(session.userId),
+				accessToken: access,
+				refreshToken: refresh,
+				expiresAt,
+				authorize,
+				lanLoginCode,
+			};
+
+			await this.tokenStore.save(next);
+			this.tokenData = next;
+			this.applyAccessToken(next);
+
+			this.log.info(
+				'CyncClient: obtained new token via password login; userId=%s expiresAt=%s',
+				next.userId,
+				next.expiresAt
+					? new Date(next.expiresAt).toISOString()
+					: 'unknown',
+			);
+
+			return next;
+		} catch (err) {
+			this.log.error(
+				'CyncClient: password-based background login failed: %o',
+				err,
+			);
+			return null;
+		}
+	}
+
 	// ### 🧩 LAN Update Bridge: allow platform to handle device updates
 	public onLanDeviceUpdate(handler: (update: unknown) => void): void {
 		this.lanUpdateHandler = handler;
@@ -321,6 +408,155 @@ export class CyncClient {
 	 *   // user reads email, gets code…
 	 *   await client.submitTwoFactor(username, password, code); // completes login
 	 */
+	// ### 🧩 Refresh Error Detector: identifies "Access-Token Expired" responses
+	private isAccessTokenExpiredError(err: unknown): boolean {
+		if (!err) {
+			return false;
+		}
+
+		// Most common case: ConfigClient throws a plain Error('Access-Token Expired')
+		if (err instanceof Error) {
+			if (
+				err.message === 'Access-Token Expired' ||
+				err.message.includes('Access-Token Expired')
+			) {
+				return true;
+			}
+		}
+
+		type ErrorWithShape = {
+			status?: number;
+			message?: string;
+			error?: {
+				msg?: string;
+				code?: number;
+			};
+		};
+
+		const e = err as ErrorWithShape;
+
+		// Shape we see in raw HTTP JSON:
+		// { error: { msg: 'Access-Token Expired', code: 4031021 } }
+		if (
+			e.error &&
+			(e.error.msg === 'Access-Token Expired' || e.error.code === 4031021)
+		) {
+			return true;
+		}
+
+		// Fallback: generic 403 plus message text
+		if (
+			e.status === 403 &&
+			e.message &&
+			e.message.includes('Access-Token Expired')
+		) {
+			return true;
+		}
+
+		return false;
+	}
+
+	// ### 🧩 Token Refresh Helper: exchanges refreshToken for a new accessToken, or falls back to password login
+	private async refreshAccessToken(
+		stored: CyncTokenData,
+	): Promise<CyncTokenData | null> {
+		// First, try refresh_token if we have one
+		if (stored.refreshToken) {
+			try {
+				const resp = await this.configClient.refreshAccessToken(
+					stored.refreshToken,
+				);
+
+				const next: CyncTokenData = {
+					...stored,
+					accessToken: resp.accessToken,
+					refreshToken: resp.refreshToken ?? stored.refreshToken,
+					expiresAt: resp.expiresAt ?? stored.expiresAt,
+				};
+
+				await this.tokenStore.save(next);
+				this.tokenData = next;
+				this.applyAccessToken(next);
+
+				this.log.info(
+					'CyncClient: refreshed access token for userId=%s; expiresAt=%s',
+					next.userId,
+					next.expiresAt
+						? new Date(next.expiresAt).toISOString()
+						: 'unknown',
+				);
+
+				return next;
+			} catch (err) {
+				this.log.error('CyncClient: token refresh failed: %o', err);
+				// fall through to password-based login below
+			}
+		} else {
+			this.log.warn(
+				'CyncClient: refreshAccessToken() called but no refreshToken is stored; will attempt password-based login.',
+			);
+		}
+
+		// If we get here, either we had no refreshToken or refresh failed.
+		// Attempt a background username/password login to obtain a fresh token.
+		const viaPassword = await this.loginWithPasswordForToken();
+		if (!viaPassword) {
+			this.log.error(
+				'CyncClient: password-based background login failed; cannot refresh Cync token automatically.',
+			);
+			return null;
+		}
+
+		return viaPassword;
+	}
+
+	// ### 🧩 Cloud Config Wrapper: auto-refreshes access token
+	private async getCloudConfigWithRefresh(): Promise<CyncCloudConfig> {
+		try {
+			return await this.configClient.getCloudConfig();
+		} catch (err) {
+			if (this.isAccessTokenExpiredError(err) && this.tokenData) {
+				this.log.warn(
+					'CyncClient: access token expired when calling getCloudConfig(); refreshing and retrying once.',
+				);
+
+				const refreshed = await this.refreshAccessToken(this.tokenData);
+				if (refreshed) {
+					return await this.configClient.getCloudConfig();
+				}
+			}
+
+			throw err;
+		}
+	}
+
+	// ### 🧩 Device Properties Wrapper: auto-refresh on Access-Token Expired for mesh calls
+	private async getDevicePropertiesWithRefresh(
+		productId: string | number,
+		meshId: string | number,
+	): Promise<Record<string, unknown>> {
+		// Normalise to strings for ConfigClient
+		const productIdStr = String(productId);
+		const meshIdStr = String(meshId);
+
+		try {
+			return await this.configClient.getDeviceProperties(productIdStr, meshIdStr);
+		} catch (err) {
+			if (this.isAccessTokenExpiredError(err) && this.tokenData) {
+				this.log.warn(
+					'CyncClient: access token expired when calling getDeviceProperties(); refreshing and retrying once.',
+				);
+
+				const refreshed = await this.refreshAccessToken(this.tokenData);
+				if (refreshed) {
+					return await this.configClient.getDeviceProperties(productIdStr, meshIdStr);
+				}
+			}
+
+			throw err;
+		}
+	}
+
 	public async authenticate(username: string): Promise<void> {
 		const email = username.trim();
 
@@ -381,7 +617,7 @@ export class CyncClient {
 		this.ensureSession();
 
 		this.log.info('CyncClient: loading Cync cloud configuration…');
-		const cfg = await this.configClient.getCloudConfig();
+		const cfg = await this.getCloudConfigWithRefresh();
 
 		// Reset LAN topology caches on each reload
 		this.homeDevices = {};
@@ -405,7 +641,7 @@ export class CyncClient {
 			const homeControllers: number[] = [];
 
 			try {
-				const props = await this.configClient.getDeviceProperties(
+				const props = await this.getDevicePropertiesWithRefresh(
 					mesh.product_id,
 					mesh.id,
 				);