@camstack/addon-provider-bosch 0.1.3 → 0.1.4

package/dist/homecom/addon.mjs

@@ -1,5 +1,387 @@
-import { A as object, E as _enum, F as EventCategory, M as string, O as literal, _ as waterHeaterCapability, b as errMsg, c as deviceAdoptionCapability, n as BaseDeviceProvider, o as climateControlCapability, s as connectionTestCapability, t as BaseDevice, y as DeviceType } from "../dist-BiZi19Lw.mjs";
-import { n as cascadeRemoveDevicesForIntegration, t as setIntegrationDevicesOnline } from "../account-integration-offline-BfoLYzxz.mjs";
+import { A as object, C as defineCustomActions, E as _enum, F as EventCategory, M as string, O as literal, S as customAction, T as isSecretMarkerLike, _ as waterHeaterCapability, b as errMsg, c as deviceAdoptionCapability, n as BaseDeviceProvider, o as climateControlCapability, s as connectionTestCapability, t as BaseDevice, w as isSecretMarker, y as DeviceType } from "../dist-LJMt_ZXW.mjs";
+import { n as cascadeRemoveDevicesForIntegration, r as parseOAuthCallback, t as setIntegrationDevicesOnline } from "../account-integration-offline-DKdrL0V9.mjs";
+import { createHash, randomBytes } from "node:crypto";
+//#region src/homecom/custom-actions.ts
+var homeComActions = defineCustomActions({
+	beginSignIn: customAction(object({}), object({
+		authorizeUrl: string().min(1),
+		verifier: string().min(1),
+		state: string().min(1),
+		summary: string()
+	}), {
+		kind: "mutation",
+		auth: "admin"
+	}),
+	finishSignIn: customAction(object({
+		verifier: string().min(1),
+		callback: string().min(1),
+		state: string().min(1)
+	}), object({
+		token: string().min(1).meta({ secret: true }),
+		refresh: string().min(1).meta({ secret: true }),
+		username: string().meta({ secret: true }),
+		summary: string()
+	}), {
+		kind: "mutation",
+		auth: "admin"
+	})
+});
+//#endregion
+//#region src/homecom/homecom-oauth.ts
+/**
+* Public OAuth client of the HomeCom Easy / PointT mobile app, signed in through SingleKey ID.
+*
+* These are the PUBLIC values the app itself ships (a PKCE client has no secret). They are not
+* derivable from this repository; they come from the community PointT client (`homecom_alt`) and
+* have to be confirmed against a live account — see docs/addons/addon-provider-bosch-homecom.md.
+*/
+var HOMECOM_CLIENT_ID = "762162C0-FA2D-4540-AE66-6489F189FADC";
+var HOMECOM_REDIRECT_URI = "com.bosch.tt.dashtt.pointt://app/login";
+var HOMECOM_AUTHORIZE_URL = "https://singlekey-id.com/auth/connect/authorize";
+var HOMECOM_TOKEN_URL = "https://singlekey-id.com/auth/connect/token";
+var HOMECOM_SCOPE = [
+	"openid",
+	"email",
+	"profile",
+	"offline_access",
+	"pointt.gateway.claiming",
+	"pointt.gateway.removal",
+	"pointt.gateway.list",
+	"pointt.gateway.users",
+	"pointt.gateway.resource.dopair",
+	"pointt.castt.flow.token-exchange",
+	"bacon",
+	"hcc.tariff.read"
+].join(" ");
+//#endregion
+//#region src/homecom/homecom-login.ts
+var MESSAGES = {
+	empty: "Nothing was pasted. Paste the address the browser tried to open after you signed in.",
+	"no-code": "No sign-in code was found in what you pasted. Copy the whole address that starts with com.bosch.tt.dashtt.pointt://, or just the code.",
+	"state-missing": "The pasted address has no state. Copy the complete address, or create the login link again.",
+	"state-mismatch": "This address belongs to a different sign-in attempt. Create the login link again and use the address that follows it.",
+	denied: "Bosch refused the sign-in. Create the login link again and approve the access.",
+	"code-rejected": "The code was already used or has expired. Create the login link again; a code works once and only for a few minutes.",
+	rejected: "Bosch did not accept the sign-in. Create the login link again.",
+	"no-refresh": "Bosch signed you in but returned no long-lived token. Create the login link again."
+};
+/** A failure the operator can act on; `reason` is stable, the message is for the form. */
+var HomeComLoginError = class extends Error {
+	name = "HomeComLoginError";
+	reason;
+	constructor(reason) {
+		super(MESSAGES[reason]);
+		this.reason = reason;
+	}
+};
+function b64url(bytes) {
+	return bytes.toString("base64url");
+}
+function beginHomeComSignIn() {
+	const verifier = b64url(randomBytes(32));
+	const challenge = b64url(createHash("sha256").update(verifier).digest());
+	const state = b64url(randomBytes(16));
+	const url = new URL(HOMECOM_AUTHORIZE_URL);
+	url.searchParams.set("client_id", HOMECOM_CLIENT_ID);
+	url.searchParams.set("redirect_uri", HOMECOM_REDIRECT_URI);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("scope", HOMECOM_SCOPE);
+	url.searchParams.set("code_challenge", challenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	url.searchParams.set("state", state);
+	url.searchParams.set("nonce", b64url(randomBytes(16)));
+	url.searchParams.set("prompt", "login");
+	return {
+		authorizeUrl: url.toString(),
+		verifier,
+		state
+	};
+}
+/**
+* The sign-in code from whatever the operator pasted: the full app address, an address copied
+* from the browser's developer tools, a bare `code=…&state=…` query, or the bare code.
+*/
+function parseHomeComCallback(input, expectedState) {
+	const parsed = parseOAuthCallback(input, expectedState);
+	if (!parsed.ok) throw new HomeComLoginError(parsed.reason);
+	return parsed.code;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function emailFromIdToken(idToken) {
+	if (typeof idToken !== "string") return "";
+	const payload = idToken.split(".")[1];
+	if (!payload) return "";
+	try {
+		const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return isRecord$1(parsed) && typeof parsed["email"] === "string" ? parsed["email"] : "";
+	} catch {
+		return "";
+	}
+}
+async function completeHomeComSignIn(input, fetchFn = globalThis.fetch.bind(globalThis)) {
+	const code = parseHomeComCallback(input.callback, input.state);
+	const res = await fetchFn(HOMECOM_TOKEN_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			grant_type: "authorization_code",
+			client_id: HOMECOM_CLIENT_ID,
+			code,
+			code_verifier: input.verifier,
+			redirect_uri: HOMECOM_REDIRECT_URI
+		}).toString()
+	});
+	const body = await res.json().catch(() => null);
+	if (!res.ok) throw new HomeComLoginError((isRecord$1(body) ? body["error"] : void 0) === "invalid_grant" ? "code-rejected" : "rejected");
+	if (!isRecord$1(body) || typeof body["access_token"] !== "string" || body["access_token"] === "") throw new HomeComLoginError("rejected");
+	const refresh = body["refresh_token"];
+	if (typeof refresh !== "string" || refresh === "") throw new HomeComLoginError("no-refresh");
+	return {
+		token: body["access_token"],
+		refresh,
+		username: emailFromIdToken(body["id_token"])
+	};
+}
+//#endregion
+//#region src/homecom/config.ts
+var HOMECOM_BRANDS = ["bosch", "buderus"];
+var HomeComBrandSchema = _enum(HOMECOM_BRANDS);
+var HOMECOM_REGIONS = ["eu", "us"];
+var HomeComRegionSchema = _enum(HOMECOM_REGIONS);
+var homeComConfigSchema = object({
+	/** Account email; filled by the sign-in, informational only. */
+	username: string().optional().describe("HomeCom / PointT account email").meta({ secret: true }),
+	token: string().min(1).describe("OAuth access token").meta({ secret: true }),
+	refresh: string().min(1).describe("OAuth refresh token").meta({ secret: true }),
+	brand: HomeComBrandSchema.default("bosch"),
+	region: HomeComRegionSchema.default("eu"),
+	/** The gateway this integration controls; chosen once from the account's gateways. */
+	gatewayId: string().min(1).optional()
+});
+function connectionFromSettings(settings) {
+	const parsed = homeComConfigSchema.safeParse(settings);
+	return parsed.success ? parsed.data : null;
+}
+function sameHomeComConnection(a, b) {
+	if (a === null || b === null) return false;
+	return a.username === b.username && a.token === b.token && a.refresh === b.refresh && a.brand === b.brand && a.region === b.region && a.gatewayId === b.gatewayId;
+}
+/**
+* PointT REST origin (matches homecom_alt / HomeCom Easy). US and EU accounts use
+* the same host; `region` is retained for Bacon MQTT (`euc1` / `use1`) when wired.
+*/
+var HOMECOM_POINTT_API_ORIGIN = "https://pointt-api.bosch-thermotechnology.com";
+function homeComApiBase(_region) {
+	return HOMECOM_POINTT_API_ORIGIN;
+}
+var HOMECOM_SECRET_KEYS = [
+	"username",
+	"token",
+	"refresh"
+];
+function buildHomeComFormSchema() {
+	return { sections: [{
+		id: "account",
+		title: "HomeCom account",
+		titleKey: "provider-bosch:homecom.s_account.title",
+		description: "Create the login link and open it in a browser, then sign in with your SingleKey ID. The browser cannot open the app and stops on an address starting with com.bosch.tt.dashtt.pointt://app/login?code=. Paste that whole address below (or only the code) and press Complete sign-in. The address is shown in Chrome and Edge under DevTools (F12) > Network, with Preserve log ticked before you sign in: select the last redirect and copy its Location header. In Firefox use Network > Headers > Location; in Safari use Develop > Show Web Inspector > Network. A code works once and expires within minutes. Tokens can also be pasted by hand in the fields below.",
+		descriptionKey: "provider-bosch:homecom.s_account.description",
+		columns: 1,
+		fields: [
+			{
+				type: "addon-action-button",
+				addonId: "bosch-homecom",
+				key: "__homecom-begin",
+				label: "HomeCom",
+				labelKey: "provider-bosch:homecom.s_account.__homecom-begin.label",
+				buttonLabel: "Create login link",
+				action: "beginSignIn",
+				variant: "primary",
+				assignResult: {
+					authorizeUrl: "authorizeUrl",
+					verifier: "verifier",
+					state: "state"
+				},
+				successMessage: "Open the link in a browser and sign in."
+			},
+			{
+				type: "textarea",
+				key: "authorizeUrl",
+				label: "Login link",
+				labelKey: "provider-bosch:homecom.s_account.authorizeUrl.label",
+				required: false,
+				omitFromSettings: true
+			},
+			{
+				type: "textarea",
+				key: "callback",
+				label: "Redirect address or code",
+				labelKey: "provider-bosch:homecom.s_account.callback.label",
+				required: false,
+				placeholder: "com.bosch.tt.dashtt.pointt://app/login?code=…&state=…",
+				omitFromSettings: true
+			},
+			{
+				type: "password",
+				key: "state",
+				label: "Login state",
+				labelKey: "provider-bosch:homecom.s_account.state.label",
+				required: false,
+				omitFromSettings: true
+			},
+			{
+				type: "password",
+				key: "verifier",
+				label: "Login verifier",
+				labelKey: "provider-bosch:homecom.s_account.verifier.label",
+				required: false,
+				omitFromSettings: true
+			},
+			{
+				type: "addon-action-button",
+				addonId: "bosch-homecom",
+				key: "__homecom-finish",
+				label: "Finish",
+				labelKey: "provider-bosch:homecom.s_account.__homecom-finish.label",
+				buttonLabel: "Complete sign-in",
+				action: "finishSignIn",
+				variant: "primary",
+				paramsFromForm: {
+					verifier: "verifier",
+					callback: "callback",
+					state: "state"
+				},
+				assignResult: {
+					token: "token",
+					refresh: "refresh",
+					username: "username"
+				},
+				successMessage: "{summary}"
+			},
+			{
+				type: "text",
+				key: "username",
+				label: "Account",
+				labelKey: "provider-bosch:homecom.s_account.username.label",
+				required: false
+			},
+			{
+				type: "password",
+				key: "token",
+				label: "Access token (filled by sign-in, or paste one)",
+				labelKey: "provider-bosch:homecom.s_account.token.label",
+				required: true,
+				showToggle: true
+			},
+			{
+				type: "password",
+				key: "refresh",
+				label: "Refresh token (filled by sign-in, or paste one)",
+				labelKey: "provider-bosch:homecom.s_account.refresh.label",
+				required: true,
+				showToggle: true
+			},
+			{
+				type: "text",
+				key: "gatewayId",
+				label: "Gateway id",
+				labelKey: "provider-bosch:homecom.s_account.gatewayId.label",
+				description: "Leave empty to use the first gateway of the account; the chosen one is stored here. For a second gateway add another HomeCom account entry and enter its id.",
+				descriptionKey: "provider-bosch:homecom.s_account.gatewayId.description",
+				required: false
+			},
+			{
+				type: "select",
+				key: "brand",
+				label: "Brand",
+				labelKey: "provider-bosch:homecom.s_account.brand.label",
+				default: "bosch",
+				options: HOMECOM_BRANDS.map((b) => ({
+					value: b,
+					label: b
+				}))
+			},
+			{
+				type: "select",
+				key: "region",
+				label: "Region",
+				labelKey: "provider-bosch:homecom.s_account.region.label",
+				default: "eu",
+				options: HOMECOM_REGIONS.map((r) => ({
+					value: r,
+					label: r.toUpperCase()
+				}))
+			}
+		]
+	}] };
+}
+//#endregion
+//#region src/homecom/homecom-token-persist.ts
+function unreadable(value) {
+	return isSecretMarker(value) || isSecretMarkerLike(value);
+}
+/**
+* Merge `patch` into the integration's stored settings in ONE `setSettings` write, one at a
+* time per integration. Refuses (and says so, without values) when a secret the write
+* touches cannot be read back from the keychain: the hub refuses an overwrite of a secret the
+* addon could not read, so the write would only fail.
+*/
+function buildSerialPatcher(deps) {
+	const tails = /* @__PURE__ */ new Map();
+	return (integrationId, patch) => {
+		const run = async () => {
+			try {
+				const stored = await deps.getSettings(integrationId);
+				const locked = HOMECOM_SECRET_KEYS.filter((key) => unreadable(stored[key]));
+				if (locked.length > 0) {
+					deps.logger.warn(`HomeCom not persisting ${deps.what} — stored secrets are locked`, {
+						tags: { integrationId },
+						meta: { locked }
+					});
+					return;
+				}
+				await deps.setSettings({
+					id: integrationId,
+					settings: {
+						...stored,
+						...patch
+					},
+					secretKeys: [...HOMECOM_SECRET_KEYS]
+				});
+			} catch (err) {
+				deps.logger.warn(`HomeCom failed to persist ${deps.what}`, {
+					tags: { integrationId },
+					meta: { error: errMsg(err) }
+				});
+			}
+		};
+		const next = (tails.get(integrationId) ?? Promise.resolve()).then(run);
+		tails.set(integrationId, next);
+		return next;
+	};
+}
+/** Persist a rotated token pair; never throws, never logs a value. */
+function buildHomeComTokenPersister(deps) {
+	const patch = buildSerialPatcher({
+		...deps,
+		what: "rotated tokens"
+	});
+	return (integrationId, tokens) => patch(integrationId, {
+		token: tokens.token,
+		refresh: tokens.refresh
+	});
+}
+/** Persist the gateway this integration settled on. */
+function buildHomeComGatewayPersister(deps) {
+	const patch = buildSerialPatcher({
+		...deps,
+		what: "chosen gateway"
+	});
+	return (integrationId, gatewayId) => patch(integrationId, { gatewayId });
+}
+//#endregion
 //#region src/homecom/homecom-discovery.ts
 function buildHomeComCandidates(input) {
 	const out = [];
@@ -153,84 +535,6 @@ function buildHomeComAdoptionProvider(deps) {
 	};
 }
 //#endregion
-//#region src/homecom/config.ts
-var HOMECOM_BRANDS = ["bosch", "buderus"];
-var HomeComBrandSchema = _enum(HOMECOM_BRANDS);
-var HOMECOM_REGIONS = ["eu", "us"];
-var HomeComRegionSchema = _enum(HOMECOM_REGIONS);
-var homeComConfigSchema = object({
-	username: string().min(1).describe("HomeCom / PointT account email").meta({ secret: true }),
-	token: string().min(1).describe("OAuth access token").meta({ secret: true }),
-	refresh: string().min(1).describe("OAuth refresh token").meta({ secret: true }),
-	brand: HomeComBrandSchema.default("bosch"),
-	region: HomeComRegionSchema.default("eu")
-});
-function connectionFromSettings(settings) {
-	const parsed = homeComConfigSchema.safeParse(settings);
-	return parsed.success ? parsed.data : null;
-}
-function sameHomeComConnection(a, b) {
-	if (a === null || b === null) return false;
-	return a.username === b.username && a.token === b.token && a.refresh === b.refresh && a.brand === b.brand && a.region === b.region;
-}
-/**
-* PointT REST origin (matches homecom_alt / HomeCom Easy). US and EU accounts use
-* the same host; `region` is retained for Bacon MQTT (`euc1` / `use1`) when wired.
-*/
-var HOMECOM_POINTT_API_ORIGIN = "https://pointt-api.bosch-thermotechnology.com";
-function homeComApiBase(_region) {
-	return HOMECOM_POINTT_API_ORIGIN;
-}
-function buildHomeComFormSchema() {
-	return { sections: [{
-		id: "account",
-		title: "HomeCom account",
-		columns: 1,
-		fields: [
-			{
-				type: "text",
-				key: "username",
-				label: "Username",
-				required: true
-			},
-			{
-				type: "password",
-				key: "token",
-				label: "Access token",
-				required: true,
-				showToggle: true
-			},
-			{
-				type: "password",
-				key: "refresh",
-				label: "Refresh token",
-				required: true,
-				showToggle: true
-			},
-			{
-				type: "select",
-				key: "brand",
-				label: "Brand",
-				default: "bosch",
-				options: HOMECOM_BRANDS.map((b) => ({
-					value: b,
-					label: b
-				}))
-			},
-			{
-				type: "select",
-				key: "region",
-				label: "Region",
-				default: "eu",
-				options: HOMECOM_REGIONS.map((r) => ({
-					value: r,
-					label: r.toUpperCase()
-				}))
-			}
-		]
-	}] };
-}
-//#endregion
 //#region src/homecom/homecom-gateway.ts
 var HomeComConnectionResolver = class {
 	#surfaces = /* @__PURE__ */ new Map();
@@ -397,6 +701,38 @@ function readNum(raw) {
 var HomeComAuthError = class extends Error {
 	name = "HomeComAuthError";
 };
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rowId(row) {
+	for (const key of [
+		"deviceId",
+		"gatewayId",
+		"id"
+	]) {
+		const value = row[key];
+		if (typeof value === "string" && value.length > 0) return value;
+		if (typeof value === "number") return String(value);
+	}
+	return null;
+}
+/** Gateways from the account listing: a bare array or `{ gateways: [...] }`. */
+function parseHomeComGatewayList(payload) {
+	const rows = isRecord(payload) ? payload["gateways"] : payload;
+	if (!Array.isArray(rows)) return [];
+	const out = [];
+	for (const row of rows) {
+		if (!isRecord(row)) continue;
+		const gatewayId = rowId(row);
+		if (gatewayId === null) continue;
+		const name = row["name"];
+		out.push({
+			gatewayId,
+			name: typeof name === "string" && name.length > 0 ? name : gatewayId
+		});
+	}
+	return out;
+}
 function createHomeComApiClient(config, gatewayId, deps = {}) {
 	const fetchFn = deps.fetchFn ?? globalThis.fetch.bind(globalThis);
 	let token = config.token;
@@ -421,10 +757,14 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 	}
 	return {
 		async refreshTokens() {
-			const res = await fetchFn(`${base}/token/oauth2`, {
+			const res = await fetchFn(HOMECOM_TOKEN_URL, {
 				method: "POST",
 				headers: { "Content-Type": "application/x-www-form-urlencoded" },
-				body: `grant_type=refresh_token&refresh_token=${encodeURIComponent(refresh)}&client_id=homecom`
+				body: new URLSearchParams({
+					grant_type: "refresh_token",
+					refresh_token: refresh,
+					client_id: HOMECOM_CLIENT_ID
+				}).toString()
 			});
 			if (!res.ok) {
 				if (res.status === 401 || res.status === 403) throw new HomeComAuthError("refresh refused");
@@ -438,11 +778,18 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 			if (typeof newToken !== "string" || typeof newRefresh !== "string") throw new Error("HomeCom token refresh: missing tokens");
 			token = newToken;
 			refresh = newRefresh;
+			await deps.onTokensRotated?.({
+				token,
+				refresh
+			});
 			return {
 				token,
 				refresh
 			};
 		},
+		async listGateways() {
+			return parseHomeComGatewayList(await request("/v2/gateways"));
+		},
 		async fetchSystem() {
 			const parsed = parseHomeComSystemPayload(await request(`/v2/gateways/${gatewayId}/system`));
 			return {
@@ -493,6 +840,8 @@ var HomeComIntegrationManager = class {
 	#surfaceSink;
 	#makeClient;
 	#pollIntervalMs;
+	#onGatewayChosen;
+	#gateways = [];
 	#client = null;
 	#gatewayId = null;
 	#pollTimer = null;
@@ -508,7 +857,26 @@ var HomeComIntegrationManager = class {
 		this.#onDisconnected = options.onDisconnected;
 		this.#surfaceSink = options.surfaceSink;
 		const fetchFn = options.fetchFn;
-		this.#makeClient = options.makeClient ?? ((config, gatewayId) => createHomeComApiClient(config, gatewayId, { fetchFn }));
+		this.#onGatewayChosen = options.onGatewayChosen ?? (() => void 0);
+		const onTokensRotated = async (tokens) => {
+			this.#connection = {
+				...this.#connection,
+				token: tokens.token,
+				refresh: tokens.refresh
+			};
+			try {
+				await options.onTokensRotated?.(tokens);
+			} catch (err) {
+				this.#logger.warn("HomeCom could not store the rotated tokens", {
+					tags: { integrationId: this.#id },
+					meta: { error: errMsg(err) }
+				});
+			}
+		};
+		this.#makeClient = options.makeClient ?? ((config, gatewayId) => createHomeComApiClient(config, gatewayId, {
+			fetchFn,
+			onTokensRotated
+		}));
 		this.#pollIntervalMs = options.pollIntervalMs ?? 6e4;
 	}
 	getConnection() {
@@ -521,8 +889,9 @@ var HomeComIntegrationManager = class {
 			kind: "homecom",
 			status: this.#status,
 			info: {
-				username: this.#connection.username,
-				gatewayId: this.#gatewayId
+				username: this.#connection.username ?? "",
+				gatewayId: this.#gatewayId,
+				gateways: this.#gateways
 			},
 			lastCheckedAt: this.#lastCheckedAt,
 			error: this.#error
@@ -532,14 +901,15 @@ var HomeComIntegrationManager = class {
 		if (this.#client !== null) return;
 		this.#status = "connecting";
 		this.#error = null;
-		const gatewayId = await this.resolveGatewayId(this.#connection);
-		this.#gatewayId = gatewayId;
-		const client = this.#makeClient(this.#connection, gatewayId);
-		this.#client = client;
+		let client = null;
 		try {
+			const gatewayId = await this.resolveGatewayId();
+			this.#gatewayId = gatewayId;
+			client = this.#makeClient(this.#connection, gatewayId);
+			this.#client = client;
 			const snapshot = await this.fetchWithTokenRefresh(client);
 			const surface = {
-				gatewayId,
+				gatewayId: this.#gatewayId ?? "",
 				client,
 				snapshot,
 				discoverables: buildDiscoverables(snapshot)
@@ -553,7 +923,8 @@ var HomeComIntegrationManager = class {
 			}, this.#pollIntervalMs);
 		} catch (err) {
 			this.#status = "error";
-			this.#error = err instanceof HomeComAuthError ? "authentication failed — check tokens" : errMsg(err);
+			this.#error = err instanceof HomeComAuthError ? "authentication failed — sign in again" : errMsg(err);
+			this.#client = null;
 			this.#surfaceSink.set(this.#id, null);
 			this.#onDisconnected(this.#id);
 			throw err;
@@ -566,6 +937,7 @@ var HomeComIntegrationManager = class {
 		}
 		this.#client = null;
 		this.#gatewayId = null;
+		this.#gateways = [];
 		this.#status = "disconnected";
 		this.#surfaceSink.set(this.#id, null);
 		this.#onDisconnected(this.#id);
@@ -590,17 +962,34 @@ var HomeComIntegrationManager = class {
 		}
 	}
 	async fetchWithTokenRefresh(client) {
+		return this.withTokenRefresh(client, () => client.fetchSystem());
+	}
+	async withTokenRefresh(client, call) {
 		try {
-			return await client.fetchSystem();
+			return await call();
 		} catch (err) {
 			if (!(err instanceof HomeComAuthError)) throw err;
 			await client.refreshTokens();
-			return client.fetchSystem();
+			return call();
 		}
 	}
-	/** Discover K40 gateway id via account listing (simplified: username hash stub). */
-	async resolveGatewayId(config) {
-		return "gateway-k40";
+	/**
+	* The gateway to poll: the stored choice when the account still has it, otherwise the
+	* account's first gateway, which is then stored. A stored choice that vanished is an error —
+	* silently switching to another gateway would control a different house.
+	*/
+	async resolveGatewayId() {
+		const lister = this.#makeClient(this.#connection, "");
+		this.#gateways = await this.withTokenRefresh(lister, () => lister.listGateways());
+		const stored = this.#connection.gatewayId;
+		if (stored !== void 0) {
+			if (!this.#gateways.some((g) => g.gatewayId === stored)) throw new Error(`HomeCom gateway ${stored} is no longer on this account`);
+			return stored;
+		}
+		const first = this.#gateways[0];
+		if (first === void 0) throw new Error("HomeCom account has no gateway");
+		this.#onGatewayChosen(first.gatewayId);
+		return first.gatewayId;
 	}
 };
 //#endregion
@@ -610,11 +999,15 @@ var HomeComClientRegistry = class {
 	#onConnected;
 	#onDisconnected;
 	#makeManager;
+	#onTokensRotated;
+	#onGatewayChosen;
 	#entries = /* @__PURE__ */ new Map();
 	constructor(logger, deps = {}) {
 		this.#logger = logger;
 		this.#onConnected = deps.onConnected ?? (() => void 0);
 		this.#onDisconnected = deps.onDisconnected ?? (() => void 0);
+		this.#onTokensRotated = deps.onTokensRotated ?? (async () => void 0);
+		this.#onGatewayChosen = deps.onGatewayChosen ?? (() => void 0);
 		const fetchFn = deps.fetchFn;
 		const makeClient = deps.makeClient;
 		this.#makeManager = deps.makeManager ?? ((opts) => new HomeComIntegrationManager({
@@ -624,6 +1017,8 @@ var HomeComClientRegistry = class {
 			logger: opts.logger,
 			onConnected: opts.onConnected,
 			onDisconnected: opts.onDisconnected,
+			onTokensRotated: opts.onTokensRotated,
+			onGatewayChosen: opts.onGatewayChosen,
 			surfaceSink: homeComConnections,
 			fetchFn,
 			makeClient,
@@ -639,7 +1034,7 @@ var HomeComClientRegistry = class {
 	async upsert(integrationId, name, connection) {
 		const existing = this.#entries.get(integrationId);
 		if (existing) {
-			if (sameHomeComConnection(existing.connection, connection)) return;
+			if (sameHomeComConnection(existing.connection, connection) || sameHomeComConnection(existing.manager.getConnection(), connection)) return;
 			try {
 				await existing.manager.applyConnection(connection);
 				this.#entries.set(integrationId, {
@@ -660,7 +1055,9 @@ var HomeComClientRegistry = class {
 			connection,
 			logger: this.#logger,
 			onConnected: (id) => this.#onConnected(id),
-			onDisconnected: (id) => this.#onDisconnected(id)
+			onDisconnected: (id) => this.#onDisconnected(id),
+			onTokensRotated: (tokens) => this.#onTokensRotated(integrationId, tokens),
+			onGatewayChosen: (gatewayId) => this.#onGatewayChosen(integrationId, gatewayId)
 		});
 		this.#entries.set(integrationId, {
 			manager,
@@ -718,14 +1115,10 @@ var HomeComClientRegistry = class {
 };
 //#endregion
 //#region src/homecom/homecom-connection-test.ts
-async function defaultResolveGatewayId(_config) {
-	return "gateway-k40";
-}
-var TEST_LABEL = "Refreshes HomeCom OAuth tokens and reads the heat-pump system snapshot";
+var TEST_LABEL = "Lists the account gateways and reads the heat-pump system snapshot";
 function buildHomeComConnectionTestProvider(deps) {
 	const { logger } = deps;
 	const makeClient = deps.makeClient ?? ((config, gatewayId) => createHomeComApiClient(config, gatewayId));
-	const resolveGatewayId = deps.resolveGatewayId ?? defaultResolveGatewayId;
 	return {
 		describeTest: async () => ({ label: TEST_LABEL }),
 		testSettings: async ({ settings }) => {
@@ -735,11 +1128,18 @@ function buildHomeComConnectionTestProvider(deps) {
 				error: `HomeCom settings incomplete: ${parsed.error.issues.map((i) => i.path.join(".") || "(root)").join(", ")}`
 			};
 			const startedAt = Date.now();
-			const gatewayId = await resolveGatewayId(parsed.data);
-			const client = makeClient(parsed.data, gatewayId);
 			try {
-				await client.refreshTokens();
-				await client.fetchSystem();
+				const gateways = await makeClient(parsed.data, "").listGateways();
+				const gatewayId = parsed.data.gatewayId ?? gateways[0]?.gatewayId;
+				if (gatewayId === void 0) return {
+					outcome: "rejected",
+					error: "This HomeCom account has no gateway."
+				};
+				if (!gateways.some((g) => g.gatewayId === gatewayId)) return {
+					outcome: "rejected",
+					error: `Gateway ${gatewayId} is not on this account.`
+				};
+				await makeClient(parsed.data, gatewayId).fetchSystem();
 				return {
 					outcome: "validated",
 					latencyMs: Date.now() - startedAt
@@ -747,12 +1147,9 @@ function buildHomeComConnectionTestProvider(deps) {
 			} catch (err) {
 				if (err instanceof HomeComAuthError) return {
 					outcome: "rejected",
-					error: "HomeCom refused these tokens — re-authenticate the PointT account."
+					error: "HomeCom refused the access token — sign in again to get a fresh one."
 				};
-				logger.warn("HomeCom connection test inconclusive", { meta: {
-					username: parsed.data.username,
-					error: errMsg(err)
-				} });
+				logger.warn("HomeCom connection test inconclusive", { meta: { error: errMsg(err) } });
 				return {
 					outcome: "inconclusive",
 					error: "Could not reach the HomeCom cloud API."
@@ -958,7 +1355,17 @@ var BoschHomeComProviderAddon = class extends BaseDeviceProvider {
 	}
 	async onInitialize() {
 		const regs = this.providerRegistrationsFromSuper(await super.onInitialize());
-		this.clients = new HomeComClientRegistry(this.ctx.logger);
+		const persistDeps = {
+			getSettings: (id) => this.ctx.api.integrations.getSettings.query({ id }),
+			setSettings: (input) => this.ctx.api.integrations.setSettings.mutate(input),
+			logger: this.ctx.logger
+		};
+		const persistTokens = buildHomeComTokenPersister(persistDeps);
+		const persistGateway = buildHomeComGatewayPersister(persistDeps);
+		this.clients = new HomeComClientRegistry(this.ctx.logger, {
+			onTokensRotated: (integrationId, tokens) => persistTokens(integrationId, tokens),
+			onGatewayChosen: (integrationId, gatewayId) => void persistGateway(integrationId, gatewayId)
+		});
 		this.clients.setOnConnected((integrationId) => {
 			this.setIntegrationDevicesOnline(integrationId, true);
 		});
@@ -967,17 +1374,33 @@ var BoschHomeComProviderAddon = class extends BaseDeviceProvider {
 		});
 		await this.reconcileIntegrations();
 		this.subscribeIntegrationLifecycle();
-		return [
-			...regs,
-			{
-				capability: deviceAdoptionCapability,
-				provider: this.buildAdoptionProvider()
-			},
-			{
-				capability: connectionTestCapability,
-				provider: this.buildConnectionTestProvider()
+		return {
+			providers: [
+				...regs,
+				{
+					capability: deviceAdoptionCapability,
+					provider: this.buildAdoptionProvider()
+				},
+				{
+					capability: connectionTestCapability,
+					provider: this.buildConnectionTestProvider()
+				}
+			],
+			customActions: homeComActions,
+			actionHandlers: {
+				beginSignIn: async () => ({
+					...beginHomeComSignIn(),
+					summary: "Open the link in a browser and sign in."
+				}),
+				finishSignIn: async (input) => {
+					const tokens = await completeHomeComSignIn(input);
+					return {
+						...tokens,
+						summary: tokens.username.length > 0 ? `Signed in as ${tokens.username}. Save to connect.` : "Signed in. Save to connect."
+					};
+				}
 			}
-		];
+		};
 	}
 	async onShutdown() {
 		try {