homebridge-tydom 0.30.1 → 0.31.1

package/README.md

@@ -79,9 +79,59 @@ Then configure the platform, either in the Homebridge UI or directly in `config.
 
 ### Finding your credentials
 
-Your **username** is the MAC address of your gateway: `001A25` followed by the 6-character home ID shown in the mobile app.
+Your **username** is the MAC address of your gateway: `001A25` followed by the 6-character home ID shown in the mobile app. Separators and case do not matter — `00:1a:25:12:34:56` works too.
 
-Your **password** is the one for your Tydom account. Newer setups have it generated by the mobile app and never show it to you; the only known way to recover it is to inspect the app's traffic with an SSL proxy, following [this guide](https://github.com/mgcrea/homebridge-tydom/issues/72#issuecomment-1315036089) from @aure-olivier.
+Your **password** is the gateway's own, which is not the one you sign in to the Tydom app with. Newer setups have it generated by the app and never show it to you.
+
+Rather than extract it, add your account **e-mail** and let the plugin fetch it for you:
+
+```json
+{
+  "platform": "Tydom",
+  "hostname": "mediation.tydom.com",
+  "username": "001A25123456",
+  "email": "you@example.com",
+  "password": "YourDeltaDoreAccountPassw0rd"
+}
+```
+
+With `email` set, `password` is read as your **Delta Dore account** password: at startup the plugin signs in to Delta Dore, looks up the gateway named in `username`, and uses the gateway password it gets back. Nothing else changes, and your account password is never sent to the gateway. Leave `email` out — the default — and `password` keeps its old meaning of the gateway's own password.
+
+The account has to already own that gateway. To check a pair without waiting on Homebridge:
+
+```bash
+pnpm resolve-credentials you@example.com 'YourDeltaDoreAccountPassw0rd' 001A25123456
+```
+
+If you would rather extract the gateway password by hand, you still can, by inspecting the app's traffic with an SSL proxy following [this guide](https://github.com/mgcrea/homebridge-tydom/issues/72#issuecomment-1315036089) from @aure-olivier.
+
+### If your account has several houses
+
+`username` is what picks the house. One Delta Dore account can hold several — a home, a holiday flat, a relative's place — and each is one gateway with its own MAC. Point `username` at the MAC of the house you want this Homebridge instance to expose, and that is the one you get. Adding `email` does not change that: the account lookup is scoped to the MAC you named, and hands back that gateway's password specifically.
+
+To find the MAC of each house, open the Tydom app's home list and read the 6-character home ID next to each one; the MAC is `001A25` followed by that. An account holding three homes gives you three MACs, and each resolves to its own distinct gateway password:
+
+```text
+Maison            ->  001A25 AAAAAA
+Appartement       ->  001A25 BBBBBB
+Chalet            ->  001A25 CCCCCC
+```
+
+Pick the one you want and put it in `username`. Note that the account only ever *confirms* a gateway you name — there is no public Delta Dore API that lists the houses on an account, and the lookup carries no house name either, so the home ID from the app is how you tell them apart.
+
+Being able to *see* a house is not the same as holding its credentials. A house attached to your account but registered by someone else's comes back from the lookup without a password, and the plugin will tell you so rather than pretend the MAC is wrong:
+
+```text
+Delta Dore returned no password for gateway 001A25XXXXXX. The account can see that house
+but does not hold its credentials — sign in with the account that registered the gateway,
+or set "password" to the gateway password directly and leave "email" out.
+```
+
+As that says, the fallback is to drop `email` and give that house's gateway password directly.
+
+Each house gets its own accessory namespace, derived from that home ID, so switching `username` from one house to another retires the first house's accessories and publishes the second's rather than mixing them up. Expect a batch of `Deleting missing accessory` lines in the log the first time you do it — that is the sweep clearing out the house you moved away from.
+
+A platform block is one house at a time; the plugin is declared `singular`, so the Homebridge UI allows a single Tydom block. To expose two houses at once you would need a second Homebridge instance, or a hand-written second platform block run as a child bridge.
 
 Both secrets can be supplied out of band instead, base64-encoded, which is usually what you want in a container:
 
@@ -97,8 +147,9 @@ They take precedence over the corresponding config fields.
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `hostname` | `string` | — | `mediation.tydom.com` for the relay, or your gateway's LAN address (see [Connecting locally](#connecting-locally)). Required. |
-| `username` | `string` | — | Gateway MAC address, e.g. `001A25123456`. Required. |
-| `password` | `string` | — | Tydom account password. Required, unless supplied via the environment. |
+| `username` | `string` | — | Gateway MAC address, e.g. `001A25123456`. This is what selects the house — see [If your account has several houses](#if-your-account-has-several-houses). Required. |
+| `email` | `string` | — | Delta Dore account e-mail. Set it to have the gateway password fetched for you, which also changes what `password` below means. See [Finding your credentials](#finding-your-credentials). |
+| `password` | `string` | — | Your Delta Dore account password if `email` is set, otherwise the gateway's own password. Required, unless supplied via the environment. |
 | `pin` | `string` | — | TYXAL+ alarm PIN. Without it the alarm reports its state but cannot be armed or disarmed. |
 | `locale` | `"fr" \| "en"` | `"fr"` | Language of the labels Delta Dore supplies for zones, detectors and thermostat modes. |
 | `refreshInterval` | `number` | `14400` | Seconds between full state refreshes. The gateway pushes changes as they happen, so this is only a safety net; clamped to a minimum of 60. |
@@ -121,7 +172,8 @@ Environment variables:
 
 | Variable | Description |
 | --- | --- |
-| `HOMEBRIDGE_TYDOM_PASSWORD` | Tydom password, base64-encoded. Overrides `password`. |
+| `HOMEBRIDGE_TYDOM_PASSWORD` | Gateway or account password, base64-encoded. Overrides `password`. |
+| `HOMEBRIDGE_TYDOM_EMAIL` | Delta Dore account e-mail, in plain text. Overrides `email`. |
 | `HOMEBRIDGE_TYDOM_PIN` | TYXAL+ PIN, base64-encoded. Overrides `pin`. |
 | `HOMEBRIDGE_TYDOM_LOCALE` | `fr` or `en`. Overrides `locale`. |
 

package/config.schema.json

@@ -20,12 +20,17 @@
         "required": true,
         "description": "Your gateway's MAC address, uppercase and without separators — e.g. `001A25123456`. It is printed underneath the Tydom box."
       },
+      "email": {
+        "title": "Delta Dore account e-mail",
+        "type": "string",
+        "description": "Optional. The e-mail you sign in to the Tydom app with.\n\nFill it in and the password below is read as your **Delta Dore account** password: the plugin signs in at startup and fetches the gateway's own password for you. Leave it empty — the default — and the password below is the **gateway's** password, used as-is.\n\nThe account has to already own the gateway named above; this looks a password up, it cannot discover which gateways you have. Also accepted as a `HOMEBRIDGE_TYDOM_EMAIL` environment variable."
+      },
       "password": {
         "title": "Password",
         "type": "string",
         "required": true,
         "x-schema-form": { "type": "password" },
-        "description": "The password of your Tydom account. Can be supplied out of band instead, as a base64-encoded `HOMEBRIDGE_TYDOM_PASSWORD` environment variable, which takes precedence over this field."
+        "description": "Your Delta Dore account password if an e-mail is set above, otherwise the gateway's own password. Can be supplied out of band instead, as a base64-encoded `HOMEBRIDGE_TYDOM_PASSWORD` environment variable, which takes precedence over this field."
       },
       "pin": {
         "title": "Alarm PIN",
@@ -121,7 +126,11 @@
     }
   },
   "layout": [
-    { "type": "fieldset", "title": "Connection", "items": ["hostname", "username", "password"] },
+    {
+      "type": "fieldset",
+      "title": "Connection",
+      "items": ["hostname", "username", "email", "password"]
+    },
     {
       "type": "fieldset",
       "title": "Alarm",

package/dist/index.mjs

@@ -409,9 +409,10 @@ const parseConfig = (config, env = process.env) => {
 	const username = asString(config["username"]);
 	const password = env.HOMEBRIDGE_TYDOM_PASSWORD ? decode(env.HOMEBRIDGE_TYDOM_PASSWORD) : asString(config["password"]);
 	const pin = env.HOMEBRIDGE_TYDOM_PIN ? decode(env.HOMEBRIDGE_TYDOM_PIN) : asString(config["pin"]) || void 0;
+	const email = asString(env.HOMEBRIDGE_TYDOM_EMAIL) || asString(config["email"]) || void 0;
 	if (!hostname) throw new ConfigError("Missing \"hostname\" — use \"mediation.tydom.com\" for remote access, or your gateway's local address.");
 	if (!username) throw new ConfigError("Missing \"username\" — this is your Tydom gateway MAC address.");
-	if (!password) throw new ConfigError("Missing \"password\" — set it in the platform config, or as a base64-encoded HOMEBRIDGE_TYDOM_PASSWORD.");
+	if (!password) throw new ConfigError(`Missing "password" — ${email ? `the password of the Delta Dore account ${email}.` : "your gateway's password, or set \"email\" to sign in with your Delta Dore account instead."} Can also be supplied as a base64-encoded HOMEBRIDGE_TYDOM_PASSWORD.`);
 	const locale = (asString(env.HOMEBRIDGE_TYDOM_LOCALE) || asString(config["locale"])) === "en" ? "en" : "fr";
 	const refreshSeconds = Number(config["refreshInterval"] ?? 144e5 / 1e3);
 	const refreshIntervalMs = Number.isFinite(refreshSeconds) ? Math.max(MIN_REFRESH_INTERVAL_MS, refreshSeconds * 1e3) : DEFAULT_REFRESH_INTERVAL_MS;
@@ -422,6 +423,7 @@ const parseConfig = (config, env = process.env) => {
 		hostname,
 		username,
 		password,
+		email,
 		pin,
 		locale,
 		debug: asBoolean(config["debug"], false),
@@ -2901,6 +2903,161 @@ const errorReplacer = (_key, value) => {
 };
 const stringifyError = (err) => JSON.stringify(err, errorReplacer);
 //#endregion
+//#region src/util/deltadore.ts
+/**
+* Delta Dore account API — turns account credentials into gateway credentials.
+*
+* The gateway's own digest handshake (`mediation/client`) authenticates with the
+* gateway MAC as the username and a *gateway* password that is neither the
+* account password nor anything printed on the box. Delta Dore's own apps fetch
+* it at runtime from the account API, which is what this module does.
+*
+* The flow is three hops:
+*
+*   1. OpenID discovery against Delta Dore's Azure AD B2C tenant, to find the
+*      token endpoint. Hard-coding it would break the day they rotate it, and
+*      discovery is the documented way to avoid that.
+*   2. A ROPC (`grant_type=password`) token grant — B2C's non-interactive flow,
+*      the only one usable from a headless plugin.
+*   3. `GET /sites?gateway_mac=…`, which returns the site and its gateway
+*      credentials.
+*
+* Note that step 3 *validates* a MAC rather than enumerating: there is no
+* public endpoint that lists an account's gateways, so the MAC stays a required
+* piece of configuration. Only the password is derived here.
+*/
+const AUTH_CONFIG_URL = "https://deltadoreadb2ciot.b2clogin.com/deltadoreadb2ciot.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_AccountProviderROPC_SignIn";
+/** The Tydom mobile app's public client id. Not a secret. */
+const CLIENT_ID = "8782839f-3264-472a-ab87-4d4e23524da4";
+const SITES_URL = "https://prod.iotdeltadore.com/sitesmanagement/api/v1/sites";
+/**
+* Only the two scopes this actually needs.
+*
+* The app requests twenty-odd (video, metering, orchestration...); asking for
+* scopes we never exercise would hand the token far more authority than reading
+* one gateway password warrants.
+*/
+const SCOPE = [
+	"openid",
+	"profile",
+	"offline_access",
+	"https://deltadoreadb2ciot.onmicrosoft.com/iotapi/sites_management_allowed",
+	"https://deltadoreadb2ciot.onmicrosoft.com/iotapi/sites_management_gateway_credentials"
+].join(" ");
+/** How long any one hop may take before we stop waiting on Delta Dore. */
+const REQUEST_TIMEOUT_MS = 15e3;
+/**
+* A credential problem the user has to fix, as opposed to a transport blip.
+*
+* Kept distinct so the platform can say "your account password is wrong" rather
+* than burning ten connection retries on something no retry will fix.
+*/
+var DeltaDoreAuthError = class extends Error {
+	name = "DeltaDoreAuthError";
+};
+const openIdConfigSchema = z.object({ token_endpoint: z.string() }).loose();
+const tokenResponseSchema = z.object({ access_token: z.string() }).loose();
+const tokenErrorSchema = z.object({
+	error: z.string().optional(),
+	error_description: z.string().optional()
+}).loose();
+const siteSchema = z.object({
+	id: z.string().optional(),
+	gateway: z.object({
+		mac: z.string().optional(),
+		password: z.string().optional()
+	}).loose().optional()
+}).loose();
+const sitesResponseSchema = z.object({ sites: z.array(siteSchema).default([]) }).loose();
+/**
+* Uppercase, separators stripped — the form the sites API matches on.
+*
+* Users copy the MAC off the label underneath the box, which prints it with
+* colons, so accepting only the bare form would reject a correct answer.
+*/
+const normalizeMacAddress = (mac) => mac.replace(/[^0-9a-zA-Z]/g, "").toUpperCase();
+const requestJson = async (fetchImpl, url, init) => {
+	const { what, ...requestInit } = init;
+	let response;
+	try {
+		response = await fetchImpl(url, {
+			...requestInit,
+			signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+		});
+	} catch (err) {
+		throw new Error(`Failed to reach Delta Dore while ${what}: ${String(err)}`, { cause: err });
+	}
+	const text = await response.text();
+	let body;
+	try {
+		body = text ? JSON.parse(text) : {};
+	} catch {
+		throw new Error(`Delta Dore returned a non-JSON response while ${what} (status=${response.status}): ${text.slice(0, 120)}`);
+	}
+	return {
+		status: response.status,
+		body
+	};
+};
+/** Exchange account credentials for a bearer token. */
+const requestAccessToken = async ({ email, password, fetch: fetchImpl = globalThis.fetch }) => {
+	const discovery = await requestJson(fetchImpl, AUTH_CONFIG_URL, { what: "discovering the account API" });
+	const openIdConfig = openIdConfigSchema.safeParse(discovery.body);
+	if (!openIdConfig.success) throw new Error("Delta Dore's OpenID configuration is missing a token endpoint.");
+	const form = new FormData();
+	form.set("username", email);
+	form.set("password", password);
+	form.set("grant_type", "password");
+	form.set("client_id", CLIENT_ID);
+	form.set("scope", SCOPE);
+	form.set("response_type", "token");
+	const { status, body } = await requestJson(fetchImpl, openIdConfig.data.token_endpoint, {
+		method: "POST",
+		body: form,
+		what: "signing in to your Delta Dore account"
+	});
+	const token = tokenResponseSchema.safeParse(body);
+	if (!token.success) {
+		const error = tokenErrorSchema.safeParse(body);
+		const detail = error.success ? error.data.error_description?.split("\n")[0] ?? error.data.error : void 0;
+		throw new DeltaDoreAuthError(`Delta Dore rejected the account credentials (status=${status})${detail ? `: ${detail}` : "."}`);
+	}
+	return token.data.access_token;
+};
+/**
+* Look up the gateway password for `mac` on the signed-in account.
+*
+* Returns the password, or throws if the account does not own that gateway.
+*/
+const fetchGatewayPassword = async ({ accessToken, mac, fetch: fetchImpl = globalThis.fetch }) => {
+	const normalizedMac = normalizeMacAddress(mac);
+	const url = `${SITES_URL}?gateway_mac=${encodeURIComponent(normalizedMac)}`;
+	const { status, body } = await requestJson(fetchImpl, url, {
+		headers: { Authorization: `Bearer ${accessToken}` },
+		what: "looking up your gateway"
+	});
+	if (status === 401 || status === 403) throw new DeltaDoreAuthError(`Your Delta Dore account is not allowed to read the credentials of gateway ${normalizedMac}.`);
+	const parsed = sitesResponseSchema.safeParse(body);
+	if (!parsed.success) throw new Error(`Delta Dore returned an unexpected site list (status=${status}) for gateway ${normalizedMac}.`);
+	const site = parsed.data.sites.find((candidate) => normalizeMacAddress(candidate.gateway?.mac ?? "") === normalizedMac);
+	if (!site) throw new DeltaDoreAuthError(`No gateway with MAC ${normalizedMac} is attached to this Delta Dore account. Check "username" against the MAC printed underneath your Tydom box.`);
+	if (!site.gateway?.password) throw new DeltaDoreAuthError(`Delta Dore returned no password for gateway ${normalizedMac}. The account can see that house but does not hold its credentials — sign in with the account that registered the gateway, or set "password" to the gateway password directly and leave "email" out.`);
+	return site.gateway.password;
+};
+/** Sign in, then read the gateway password. The whole flow, in one call. */
+const resolveGatewayPassword = async ({ email, password, mac, fetch: fetchImpl = globalThis.fetch }) => {
+	const accessToken = await requestAccessToken({
+		email,
+		password,
+		fetch: fetchImpl
+	});
+	return fetchGatewayPassword({
+		accessToken,
+		mac,
+		fetch: fetchImpl
+	});
+};
+//#endregion
 //#region src/controller.ts
 var TydomController = class extends EventEmitter {
 	client;
@@ -2925,6 +3082,14 @@ var TydomController = class extends EventEmitter {
 	emitted = /* @__PURE__ */ new Set();
 	refreshInterval;
 	hasConnectedOnce = false;
+	/**
+	* The gateway password actually in use.
+	*
+	* Empty until `connect` derives it, when the platform was configured with an
+	* account e-mail — in which case `config.password` is the account's, not the
+	* gateway's, and must never reach the gateway.
+	*/
+	gatewayPassword;
 	/** Delta Dore label lookups, bound to the configured locale. */
 	t;
 	constructor(log, config) {
@@ -2932,22 +3097,34 @@ var TydomController = class extends EventEmitter {
 		this.config = config;
 		this.log = log;
 		this.t = createTranslator(config.locale);
-		const { hostname, username, password } = config;
+		const { hostname, username, password, email } = config;
 		this.log.info(`Creating tydom client with username=${styleString(username)} and hostname=${styleString(hostname)}`);
-		this.client = createClient({
+		this.gatewayPassword = email ? "" : password;
+		this.client = this.createClient(this.gatewayPassword);
+	}
+	/**
+	* Build a client for `password` and wire its events up.
+	*
+	* Split out of the constructor because account-derived credentials only
+	* arrive once `connect` has been able to await the account API, and the
+	* client takes its password at construction time.
+	*/
+	createClient(password) {
+		const { hostname, username } = this.config;
+		const client = createClient({
 			username,
 			password,
 			hostname,
 			followUpDebounce: 500
 		});
-		this.client.on("message", (message) => {
+		client.on("message", (message) => {
 			try {
 				this.handleMessage(message);
 			} catch (err) {
 				this.log.error(`Encountered an uncaught error=${stringifyError(err)} while processing message=${styleJson(message)}"`);
 			}
 		});
-		this.client.on("connect", () => {
+		client.on("connect", () => {
 			this.log.info(`Successfully connected to Tydom hostname=${styleString(hostname)} with username=${styleString(username)}`);
 			if (this.hasConnectedOnce) {
 				this.log.warn(`Reconnected to Tydom hostname=${styleString(hostname)}, re-syncing state...`);
@@ -2957,7 +3134,7 @@ var TydomController = class extends EventEmitter {
 			}
 			this.emit("connect");
 		});
-		this.client.on("disconnect", () => {
+		client.on("disconnect", () => {
 			this.log.warn(`Disconnected from Tydom hostname=${styleString(hostname)}"`);
 			if (this.refreshInterval) {
 				clearInterval(this.refreshInterval);
@@ -2965,6 +3142,29 @@ var TydomController = class extends EventEmitter {
 			}
 			this.emit("disconnect");
 		});
+		return client;
+	}
+	/**
+	* Fetch the gateway password from the Delta Dore account, once.
+	*
+	* No-op unless an account e-mail was configured. The result is kept for the
+	* process lifetime: the gateway password is stable, and `connect` is retried
+	* with backoff on startup — re-running the whole OAuth flow on every attempt
+	* would turn a flaky socket into repeated sign-ins.
+	*/
+	async resolveGatewayPassword() {
+		const { email, password: accountPassword, username } = this.config;
+		if (this.gatewayPassword || !email) return;
+		this.log.info(`Resolving the gateway password from the Delta Dore account of ${styleString(email)}...`);
+		const password = await resolveGatewayPassword({
+			email,
+			password: accountPassword,
+			mac: username
+		});
+		this.gatewayPassword = password;
+		this.client.removeAllListeners();
+		this.client = this.createClient(password);
+		this.log.info(`Resolved the gateway password for username=${styleString(username)}`);
 	}
 	getUniqueId(deviceId, endpointId) {
 		return deviceId === endpointId ? `${deviceId}` : `${deviceId}:${endpointId}`;
@@ -2977,6 +3177,7 @@ var TydomController = class extends EventEmitter {
 		const { hostname, username } = this.config;
 		debug(`Connecting to hostname=${styleString(hostname)}...`);
 		try {
+			await this.resolveGatewayPassword();
 			await this.client.connect();
 			await asyncWait(250);
 			await this.client.get("/ping");
@@ -4947,8 +5148,14 @@ var TydomPlatform = class {
 		this.t = createTranslator(this.config.locale);
 		this.pluginLog = createPluginLogger(log, this.config.debug);
 		this.controller = new TydomController(log, this.config);
+		const controller = this.controller;
 		this.apiClient = new TydomApiClient({
-			transport: this.controller.client,
+			transport: {
+				get: (uri) => controller.client.get(uri),
+				put: (uri, body) => controller.client.put(uri, body),
+				post: (uri, body) => controller.client.post(uri, body),
+				command: (uri) => controller.client.command(uri)
+			},
 			logger: this.pluginLog
 		});
 		this.api.on("didFinishLaunching", () => {