homebridge-nuheat2 1.2.15 → 1.2.16

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project should be documented in this file
 
 ## [Unreleased]
 
+## [1.2.16] - 2026-04-29
+
+### Changed
+
+- Switch the built-in Nuheat OAuth client to Authorization Code with PKCE using the public `homebridge-nuheat2_260421` client ID
+- Keep legacy confidential-client OAuth overrides available when a custom `clientSecret` is explicitly configured
+
 ## [1.2.15] - 2026-04-27
 
 ### Fixed

package/README.md

@@ -15,6 +15,7 @@ This project builds on the original [`senorshaun/homebridge-nuheat`](https://git
 - Optionally creates HomeKit switches for Nuheat group away mode
 - Supports permanent, scheduled, and timed holds
 - Uses Nuheat's OAuth-based API instead of legacy site scraping
+- Uses the official Nuheat PKCE public client by default, with no distributable client secret
 - Includes compatibility improvements for Homebridge 1.8+ and 2.0 betas
 - Can optionally expose a schedule switch for each thermostat
 - Allows advanced OAuth overrides for long-term API stability
@@ -89,8 +90,8 @@ The equivalent JSON looks like this:
 - `refresh`: Poll interval in seconds, default `60`. Values lower than `30` are raised to `30` to reduce API traffic
 - `enableNotifications`: Enables Nuheat SignalR notifications for faster updates. Defaults to `true`; set to `false` only while troubleshooting
 - `debug`: Enables verbose Nuheat API, notification, and accessory logging. Defaults to `false`
-- `clientId`: Optional advanced override for the Nuheat OAuth client ID. Current releases require this to be paired with `clientSecret`; PKCE public-client support is planned but is not active yet
-- `clientSecret`: Optional legacy OAuth client secret override for confidential-client credentials. Required with a custom `clientId` until PKCE support ships. Do not publish or share this value
+- `clientId`: Optional advanced override for the Nuheat OAuth client ID. Leave blank to use the built-in PKCE public client ID, `homebridge-nuheat2_260421`
+- `clientSecret`: Optional legacy OAuth client secret override for confidential-client credentials. Leave blank for the PKCE public-client flow. Do not publish or share this value
 - `redirectUri`: Optional advanced override for the Nuheat OAuth redirect URI, default `http://localhost`
 
 ### Hold Length Behavior
@@ -114,7 +115,9 @@ Nuheat's public OpenAPI documentation indicates that third-party developers shou
 - [Nuheat OpenAPI docs](https://api.mynuheat.com/)
 - [Nuheat API access request page](https://www.nuheat.com/openapi)
 
-This fork still supports the legacy built-in OAuth client settings as a fallback. Nuheat is expected to issue a PKCE-based public client for this integration so the plugin can eventually ship with a public `clientId` without distributing a client secret. Until that migration is complete, keep any issued `clientSecret` out of GitHub, npm, screenshots, and shared logs.
+This fork uses Nuheat's PKCE-based public client for normal authentication. The built-in public `clientId` is `homebridge-nuheat2_260421`; there is no distributable client secret.
+
+Legacy confidential-client credentials can still be supplied with `clientId` and `clientSecret` for testing alternate Nuheat-issued clients. Keep any `clientSecret` out of GitHub, npm, screenshots, and shared logs.
 
 ## What's New In This Fork
 
@@ -173,7 +176,6 @@ After that, bump the version in `package.json`, push to `master`, and GitHub Act
 
 ## Future Work
 
-- Validate the plugin against the official Nuheat API credentials requested for this integration.
-- Move the normal OAuth path to Nuheat's PKCE-based public client once the new client details are issued.
+- Validate the PKCE public-client flow against more real-world Nuheat accounts.
 - Verify group and away-mode behavior against current live API responses.
 - Evaluate whether SignalR notifications can reduce polling further in real-world deployments.

package/config.schema.json

@@ -125,13 +125,13 @@
       "clientId": {
         "title": "Nuheat Client ID",
         "type": "string",
-        "description": "Advanced OAuth override. Current releases require this to be paired with a clientSecret; PKCE public-client support is planned but not active yet."
+        "description": "Advanced OAuth override. Leave blank to use the built-in PKCE public client ID."
       },
       "clientSecret": {
         "title": "Nuheat Client Secret (Legacy)",
         "type": "string",
         "format": "password",
-        "description": "Advanced OAuth override for confidential-client credentials. Required with a custom clientId until PKCE support ships. Do not publish or share this value."
+        "description": "Legacy OAuth override for confidential-client credentials. Leave blank for the PKCE public-client flow. Do not publish or share this value."
       },
       "redirectUri": {
         "title": "Nuheat Redirect URI",
@@ -177,7 +177,7 @@
       "title": "Advanced OAuth",
       "expandable": true,
       "expanded": false,
-      "description": "Only change these fields when testing Nuheat-issued API credentials.",
+      "description": "Only change these fields when testing alternate Nuheat-issued API credentials.",
       "items": [
         "clientId",
         "clientSecret",

package/homebridge-ui/public/index.html

@@ -173,19 +173,21 @@
       <div>
         <h2>Advanced OAuth</h2>
         <p class="help">
-          Leave these fields blank unless Nuheat has issued confidential-client
-          credentials for testing. PKCE public-client support is planned but is
-          not active yet.
+          Leave these fields blank to use the built-in Nuheat PKCE public
+          client. Only change them when testing alternate Nuheat-issued API
+          credentials.
         </p>
       </div>
-      <span id="oauth-status" class="status-pill warn">Built-in fallback</span>
+      <span id="oauth-status" class="status-pill good">Built-in PKCE</span>
     </div>
 
     <div class="settings-grid">
       <label class="field">
         <span>Nuheat Client ID</span>
         <input id="client-id" type="text" placeholder="Optional client ID" />
-        <small>Advanced override for a Nuheat-issued OAuth client ID.</small>
+        <small>
+          Advanced override. Blank uses homebridge-nuheat2_260421.
+        </small>
       </label>
 
       <label id="client-secret-row" class="field">
@@ -196,8 +198,8 @@
           placeholder="Leave blank to keep existing"
         />
         <small>
-          Required with a custom client ID until PKCE support ships. Do not
-          publish or share this value.
+          Leave blank for PKCE public-client auth. Only use this for legacy
+          confidential-client credentials.
         </small>
       </label>
 

package/homebridge-ui/public/index.js

@@ -320,15 +320,6 @@ async function saveOauth() {
     return;
   }
 
-  if (clientId && !hasUsableClientSecret(clientId) && !clientSecret) {
-    showToast(
-      "error",
-      "Current OAuth overrides require a matching client ID and client secret.",
-    );
-    elements.clientSecret.focus();
-    return;
-  }
-
   const patch = {
     clientId: clientId || undefined,
     redirectUri: redirectUri && redirectUri !== "http://localhost" ? redirectUri : undefined,
@@ -336,7 +327,7 @@ async function saveOauth() {
 
   if (clientSecret) {
     patch.clientSecret = clientSecret;
-  } else if (!clientId) {
+  } else if (!clientId || clientId !== (state.config?.clientId || "")) {
     patch.clientSecret = undefined;
   }
 
@@ -450,10 +441,10 @@ function updateOauthStatus() {
   const hasClientSecret = hasUsableClientSecret(elements.clientId.value.trim());
   const text = hasClientId
     ? hasClientSecret
-      ? "Custom OAuth"
-      : "Secret needed"
-    : "Built-in fallback";
-  setStatus(elements.oauthStatus, hasClientId && hasClientSecret, text);
+      ? "Custom legacy OAuth"
+      : "Custom PKCE"
+    : "Built-in PKCE";
+  setStatus(elements.oauthStatus, true, text);
 }
 
 function hasUsableClientSecret(clientId) {
@@ -590,9 +581,9 @@ function getOauthMode(config) {
     return "configured confidential client";
   }
   if (config.clientId) {
-    return "incomplete custom client";
+    return "configured PKCE public client";
   }
-  return "built-in fallback credentials";
+  return "built-in PKCE public client";
 }
 
 function normalizeHoldLength(value) {

package/lib/NuHeatAPI.js

@@ -6,6 +6,7 @@ const FetchError = fetchModule.FetchError;
 const HeadersCtor = fetchModule.Headers;
 const isRedirect = fetchModule.isRedirect;
 const { parse } = htmlParser;
+const node_crypto_1 = require("node:crypto");
 const settings_1 = require("./settings");
 const NuHeatModels_1 = require("./NuHeatModels");
 const OAUTH_SCOPES = ["openapi", "openid", "profile", "offline_access"];
@@ -16,7 +17,9 @@ class NuHeatAPI {
     oauthClientId;
     oauthClientSecret;
     oauthRedirectUri;
-    usingFallbackCredentials;
+    usingBuiltInClient;
+    usePkce;
+    pkceCodeVerifier;
     headers;
     accessToken;
     accessTokenTimestamp;
@@ -28,23 +31,19 @@ class NuHeatAPI {
         this.email = email;
         this.password = password;
         this.log = log;
-        this.oauthClientId =
-            options.clientId ||
-                process.env.NUHEAT_API_CLIENT_ID ||
-                settings_1.NUHEAT_API_CLIENT_ID;
-        this.oauthClientSecret =
-            options.clientSecret ||
-                process.env.NUHEAT_API_CLIENT_SECRET ||
-                settings_1.NUHEAT_API_CLIENT_SECRET;
+        const configuredClientId = options.clientId || process.env.NUHEAT_API_CLIENT_ID || "";
+        const configuredClientSecret = options.clientSecret || process.env.NUHEAT_API_CLIENT_SECRET || "";
+        this.oauthClientId = configuredClientId || settings_1.NUHEAT_API_CLIENT_ID;
+        this.oauthClientSecret = configuredClientId
+            ? configuredClientSecret || settings_1.NUHEAT_API_CLIENT_SECRET
+            : "";
         this.oauthRedirectUri =
             options.redirectUri ||
                 process.env.NUHEAT_API_REDIRECT_URI ||
                 settings_1.NUHEAT_API_REDIRECT_URI;
-        this.usingFallbackCredentials =
-            !options.clientId &&
-                !process.env.NUHEAT_API_CLIENT_ID &&
-                !options.clientSecret &&
-                !process.env.NUHEAT_API_CLIENT_SECRET;
+        this.usingBuiltInClient = !configuredClientId;
+        this.usePkce = !this.oauthClientSecret;
+        this.pkceCodeVerifier = "";
         this.headers = new HeadersCtor();
         this.headers.set("Content-Type", "application/json");
         this.headers.set("Accept", "application/json");
@@ -54,8 +53,10 @@ class NuHeatAPI {
         this.refreshToken = "";
         this.tokenScope = "";
         this.tokenType = "Bearer";
-        if (this.usingFallbackCredentials) {
-            this.log.warn("NuHeatAPI: Using built-in OAuth client credentials. Request your own Nuheat API client for long-term reliability.");
+        if (this.usingBuiltInClient) {
+            this.log.info("NuHeatAPI: Using built-in Nuheat PKCE public client ID " +
+                this.oauthClientId +
+                ".");
         }
         else {
             this.log.info("NuHeatAPI: Using configured OAuth client ID " + this.oauthClientId + ".");
@@ -63,11 +64,48 @@ class NuHeatAPI {
         this.log.debug("NuHeatAPI: OAuth redirect URI " +
             this.oauthRedirectUri +
             ". Requested scopes: " +
-            this.getRequestedScope());
+            this.getRequestedScope() +
+            ". OAuth flow: " +
+            (this.usePkce ? "authorization_code_pkce" : "authorization_code_secret"));
     }
     getRequestedScope() {
         return OAUTH_SCOPES.join(" ");
     }
+    generatePkceCodeVerifier() {
+        return (0, node_crypto_1.randomBytes)(64).toString("base64url");
+    }
+    getPkceCodeChallenge(codeVerifier) {
+        return (0, node_crypto_1.createHash)("sha256").update(codeVerifier).digest("base64url");
+    }
+    buildAuthorizationCodeTokenRequest(redirectUrl) {
+        const requestBody = new URLSearchParams({
+            client_id: this.oauthClientId,
+            code: redirectUrl.searchParams.get("code") || "",
+            grant_type: "authorization_code",
+            redirect_uri: this.oauthRedirectUri,
+            scope: redirectUrl.searchParams.get("scope") || "",
+        });
+        if (this.usePkce) {
+            requestBody.set("code_verifier", this.pkceCodeVerifier);
+        }
+        else {
+            requestBody.set("client_secret", this.oauthClientSecret);
+        }
+        return requestBody;
+    }
+    buildRefreshTokenRequest() {
+        const requestBody = new URLSearchParams({
+            client_id: this.oauthClientId,
+            grant_type: "refresh_token",
+            refresh_token: this.refreshToken,
+            scope: this.tokenScope,
+        });
+        if (!this.usePkce) {
+            requestBody.set("client_secret", this.oauthClientSecret);
+            requestBody.set("redirect_uri", this.oauthRedirectUri);
+        }
+        return requestBody;
+    }
     async setAwayMode(groupId, awayMode) {
         const callURL = "https://api.mynuheat.com/api/v1/Group";
         const callOptions = {
@@ -248,8 +286,14 @@ class NuHeatAPI {
         authEndpoint.searchParams.set("client_id", this.oauthClientId);
         authEndpoint.searchParams.set("redirect_uri", this.oauthRedirectUri);
         authEndpoint.searchParams.set("scope", this.getRequestedScope());
+        if (this.usePkce) {
+            this.pkceCodeVerifier = this.generatePkceCodeVerifier();
+            authEndpoint.searchParams.set("code_challenge", this.getPkceCodeChallenge(this.pkceCodeVerifier));
+            authEndpoint.searchParams.set("code_challenge_method", "S256");
+        }
         this.log.debug("NuHeatAPI: Requesting OAuth authorization page with scopes: " +
-            this.getRequestedScope());
+            this.getRequestedScope() +
+            (this.usePkce ? " using PKCE." : "."));
         const response = await this.fetch(authEndpoint.toString(), {
             redirect: "follow",
         });
@@ -396,14 +440,7 @@ class NuHeatAPI {
                 return null;
             }
             const redirectUrl = new URL(response.headers.get("location") || "");
-            const requestBody = new URLSearchParams({
-                client_id: this.oauthClientId,
-                client_secret: this.oauthClientSecret,
-                code: redirectUrl.searchParams.get("code") || "",
-                grant_type: "authorization_code",
-                redirect_uri: this.oauthRedirectUri,
-                scope: redirectUrl.searchParams.get("scope") || "",
-            });
+            const requestBody = this.buildAuthorizationCodeTokenRequest(redirectUrl);
             response = await this.fetch(settings_1.NUHEAT_API_TOKEN_URI, {
                 body: requestBody.toString(),
                 headers: {
@@ -426,14 +463,7 @@ class NuHeatAPI {
         return null;
     }
     async getRefreshedAccessToken() {
-        const requestBody = new URLSearchParams({
-            client_id: this.oauthClientId,
-            client_secret: this.oauthClientSecret,
-            grant_type: "refresh_token",
-            redirect_uri: this.oauthRedirectUri,
-            refresh_token: this.refreshToken,
-            scope: this.tokenScope,
-        });
+        const requestBody = this.buildRefreshTokenRequest();
         const response = await this.fetch(settings_1.NUHEAT_API_TOKEN_URI, {
             body: requestBody.toString(),
             headers: {

package/lib/settings.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NUHEAT_API_CONSENT_URI = exports.NUHEAT_API_TOKEN_URI = exports.NUHEAT_API_AUTHORIZE_URI = exports.NUHEAT_API_REDIRECT_URI = exports.NUHEAT_API_CLIENT_SECRET = exports.NUHEAT_API_CLIENT_ID = void 0;
-exports.NUHEAT_API_CLIENT_ID = "homebridge-nuheat";
-exports.NUHEAT_API_CLIENT_SECRET = "PkYnj7yq6b3r1H4PN/gehP7NPvSMCzTIXerRx0ZZpsE=";
+exports.NUHEAT_API_CLIENT_ID = "homebridge-nuheat2_260421";
+exports.NUHEAT_API_CLIENT_SECRET = "";
 exports.NUHEAT_API_REDIRECT_URI = "http://localhost";
 exports.NUHEAT_API_AUTHORIZE_URI = "https://identity.mynuheat.com/connect/authorize";
 exports.NUHEAT_API_TOKEN_URI = "https://identity.mynuheat.com/connect/token";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-nuheat2",
-  "version": "1.2.15",
+  "version": "1.2.16",
   "description": "Homebridge Platform for NuHeat Signature Thermostats",
   "main": "index.js",
   "scripts": {