fix: trust HA Ingress auth and build proper climate payload for hvac overrides

Two HA add-on fixes:

- Web UI mutations (label edits, .cbz/XML imports) now work on a default
  add-on install with no web_api_key. Requests proxied through Home
  Assistant Ingress are already authenticated by HA, so the
  Supervisor-injected X-Ingress-Path header is trusted, but only when the
  server runs in ingress mode (basePath set) so a spoofed header can't
  bypass auth on a directly-exposed port. A configured web_api_key still
  takes precedence.

- A per-group "hvac" type override now publishes a full climate entity
  (temperature/mode topics) via _createHvacDiscovery instead of a broken
  generic payload, and the climate config topic is tracked for stale
  cleanup. Docs clarify that only Lighting (56) is discovered by default
  and how to reclassify lighting-app groups via type_overrides.

Author: dougrathbone

README.md

@@ -119,13 +119,14 @@ When enabled, `cgateweb` queries the C-Gate network structure (`TREEXML`) and pu
 Supported Device Types:
 
 *   **Lights:** C-Bus Lighting Application groups (typically App ID 56) are discovered as Home Assistant `light` entities, supporting on/off and brightness control.
-*   **Covers:** Devices using the configured `ha_discovery_cover_app_id` (default: `203`) are discovered as `cover` entities (device class `shutter`), supporting:
+*   **Covers:** Devices using the configured `ha_discovery_cover_app_id` (default: `null` — disabled; commonly set to `203` for Enable Control) are discovered as `cover` entities (device class `shutter`), supporting:
     - **Position control:** Set position 0-100% (0=closed, 100=fully open)
     - **Stop:** Stop the cover at its current position
     - **Open/Close:** Basic open/close commands
 *   **Switches:** Devices using the configured `ha_discovery_switch_app_id` (default: `null`) are discovered as `switch` entities.
 *   **Relays:** Devices using the configured `ha_discovery_relay_app_id` (default: `null`) are discovered as `switch` entities with device class `outlet`.
 *   **PIR Motion Sensors:** Devices using the configured `ha_discovery_pir_app_id` (default: `null`) are discovered as `binary_sensor` entities with device class `motion`.
+*   **HVAC / Climate:** Devices using the configured `ha_discovery_hvac_app_id` (default: `null` — disabled; commonly Air Conditioning App `201`) are discovered as `climate` entities.
 
 **Configuration (`settings.js`):**
 
@@ -138,11 +139,14 @@ module.exports = {
     ha_discovery_prefix: 'homeassistant', // Default HA discovery topic prefix
     ha_discovery_networks: ['254'],     // List C-Bus network IDs to scan (e.g., ['254', '200'])
     
-    // Application IDs for specific device types (MUST match your C-Bus project configuration)
-    ha_discovery_cover_app_id: '203',   // App ID for Covers (e.g., Enable Control)
+    // Application IDs for specific device types (MUST match your C-Bus project configuration).
+    // All of these default to `null` (disabled). Only the Lighting application (56) is
+    // discovered out of the box, and every Lighting group is published as a `light`.
+    ha_discovery_cover_app_id: '203',   // App ID for Covers (e.g., Enable Control) - null to disable (default)
     ha_discovery_switch_app_id: null,   // App ID for Switches (e.g., Enable Control, Trigger Control) - null to disable
     ha_discovery_relay_app_id: null,    // App ID for Relays (e.g., Enable Control) - null to disable
-    ha_discovery_pir_app_id: null      // App ID for PIR Motion Sensors (e.g., Trigger Control) - null to disable
+    ha_discovery_pir_app_id: null,     // App ID for PIR Motion Sensors (e.g., Trigger Control) - null to disable
+    ha_discovery_hvac_app_id: null     // App ID for HVAC/climate zones (e.g., Air Conditioning 201) - null to disable
 };
 ```
 
@@ -159,7 +163,8 @@ The crucial step is setting the correct `ha_discovery_*_app_id` values to match
 
 **Important Notes:**
 
-*   Discovery for Switches, Relays, and PIRs is **disabled by default** (`null`). You *must* set the corresponding `ha_discovery_*_app_id` in `settings.js` to the correct C-Bus Application ID to enable discovery for these types.
+*   Discovery for Covers, Switches, Relays, PIRs, and HVAC is **disabled by default** (`null`). Only the Lighting application (56) is discovered automatically, and **every** Lighting group is published as a `light`. You *must* set the corresponding `ha_discovery_*_app_id` in `settings.js` to the correct C-Bus Application ID to enable the other types.
+*   **Devices that live on the Lighting application (56) but are not lights** — e.g. shutter-relay units (blinds use lighting group addresses) or a thermostat exposed on app 56 — will appear as `light` entities because classification is purely by Application ID. To reclassify an individual group, add a per-group `type_overrides` entry in your labels file (`"<net>/<app>/<group>": "cover" | "switch" | "relay" | "pir" | "hvac"`) or via the web UI; this is the only way to change the type of a group that shares the Lighting application with real lights.
 *   If multiple discovery types (e.g., Cover and Switch) are configured with the *same* Application ID, `cgateweb` prioritizes discovery in this order: Cover > Switch > Relay > PIR. Only the first matching type will be discovered for a given C-Bus group using that Application ID.
 *   For more technical details, see `docs/project-homeassistant-discovery.md`.
 

homeassistant-addon/DOCS.md

@@ -158,8 +158,8 @@ Disable auto-discovery (`auto_discover_networks: false`) if:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `web_api_key` | password | (empty) | API key required for write operations (`PUT/PATCH/POST`) on label-management endpoints. |
-| `web_allow_unauthenticated_mutations` | boolean | `false` | Unsafe override to allow write operations without API key authentication. |
+| `web_api_key` | password | (empty) | API key required for write operations (`PUT/PATCH/POST`) on label-management endpoints when accessed **directly** (not via Ingress). Requests through Home Assistant Ingress are already authenticated by HA and do not need this key. |
+| `web_allow_unauthenticated_mutations` | boolean | `false` | Unsafe override to allow write operations without authentication on the **directly-exposed** port. Not needed for the Ingress UI. |
 | `web_allowed_origins` | list | `[]` | Optional CORS allowlist of browser origins (e.g. `https://ha.example.com`). Empty disables cross-origin access. |
 | `web_mutation_rate_limit_per_minute` | integer | `120` | Per-client write rate limit for label mutation endpoints. |
 
@@ -360,11 +360,11 @@ Set `ha_discovery_hvac_app_id: 201` to enable HVAC discovery. Use `ha_hvac_tempe
 
 This add-on runs with `host_network: false`.
 
-- Ingress is enabled and routes the label editor UI through Home Assistant.
+- Ingress is enabled and routes the label editor UI through Home Assistant. Requests arriving via Ingress are already authenticated by Home Assistant (the Supervisor injects an `X-Ingress-Path` header), so label edits and `.cbz`/XML imports work out of the box with no `web_api_key`.
 - Port `8080/tcp` is exposed by the add-on for direct access if needed.
 - Outbound connections to remote C-Gate and MQTT still work normally from the add-on container.
 
-If you expose `8080`, set `web_api_key` and keep `web_allow_unauthenticated_mutations: false`.
+If you expose `8080` for direct (non-Ingress) access, set `web_api_key` and keep `web_allow_unauthenticated_mutations: false`. Direct requests never carry the Ingress header, so they always require the key.
 
 ## Stale Device Detection
 

src/haDiscovery.js

@@ -675,7 +675,14 @@ class HaDiscovery {
                 const config = getDiscoveryConfig(typeOverride);
                 if (config) {
                     this.logger.debug(`Type override: ${labelKey} -> ${typeOverride}`);
-                    this._createDiscovery(networkId, appId, groupId, group.Label, config);
+                    if (config.isHvac) {
+                        // HVAC needs the dedicated climate payload (temperature/mode
+                        // topics); the generic builder would publish a broken
+                        // climate entity with no thermostat controls.
+                        this._createHvacDiscovery(networkId, appId, groupId, group.Label);
+                    } else {
+                        this._createDiscovery(networkId, appId, groupId, group.Label, config);
+                    }
                     // Remove any stale retained light config for this group.
                     // This covers the case where the type changes within the same session
                     // (e.g. first run saw it as a light; this run sees the type override).
@@ -857,6 +864,7 @@ class HaDiscovery {
         };
 
         this._publish(discoveryTopic, JSON.stringify(payload), MQTT_RETAINED_STATE_OPTIONS);
+        if (this._currentRunTopics) this._currentRunTopics.add(discoveryTopic);
         this.discoveryCount++;
     }
 

src/webServer.js

@@ -648,6 +648,16 @@ class WebServer {
 
     _isAuthorizedMutation(req) {
         if (!this.apiKey) {
+            // Requests proxied through Home Assistant Ingress have already been
+            // authenticated by HA (only logged-in HA users can reach the ingress
+            // URL). The Supervisor injects an X-Ingress-Path header on every such
+            // request, which the directly-exposed port never carries. Trusting it
+            // lets the bundled label UI import/edit on a default add-on install
+            // (no web_api_key) without opening up the raw port. A configured
+            // web_api_key still takes precedence below.
+            if (this._isIngressRequest(req)) {
+                return true;
+            }
             return this.allowUnauthenticatedMutations;
         }
 
@@ -665,6 +675,16 @@ class WebServer {
         return crypto.timingSafeEqual(providedBuf, expectedBuf);
     }
 
+    _isIngressRequest(req) {
+        // Only trust the ingress marker when the server was actually started in
+        // ingress mode (INGRESS_ENTRY -> basePath). This prevents a spoofed
+        // X-Ingress-Path header from bypassing auth on a standalone deployment
+        // that is not fronted by the Supervisor proxy.
+        if (!this.basePath) return false;
+        const ingressPath = req.headers['x-ingress-path'];
+        return typeof ingressPath === 'string' && ingressPath.length > 0;
+    }
+
     _setCorsHeaders(req, res) {
         const requestOrigin = req.headers.origin;
         if (this.allowedOrigins && this.allowedOrigins.length > 0) {

tests/haDiscovery.test.js

@@ -1152,6 +1152,41 @@ describe('HaDiscovery', () => {
             expect(payload.device.name).toBe('Pond Pump');
         });
 
+        it('should override a lighting group to hvac (climate) type with a full climate payload', () => {
+            // A thermostat wired on the lighting application (app 56) can only be
+            // reclassified via a per-group type override. The resulting entity must
+            // be a real HA climate device with temperature/mode topics — not a
+            // generic payload published to the climate component (which renders as a
+            // broken thermostat in HA).
+            const labelData = {
+                labels: new Map([['254/56/12', 'Hallway Thermostat']]),
+                typeOverrides: new Map([['254/56/12', 'hvac']]),
+                entityIds: new Map(),
+                exclude: new Set()
+            };
+            const ha = new HaDiscovery(mockSettings, mockPublishFn, mockSendCommandFn, labelData);
+            ha._publishDiscoveryFromTree('254', MOCK_TREEXML_RESULT_NET254);
+
+            // The stale light config for this group should be cleared.
+            const lightCall = mockPublishFn.mock.calls.find(
+                c => c[0] === 'testhomeassistant/light/cgateweb_254_56_12/config'
+            );
+            expect(lightCall).toBeDefined();
+            expect(lightCall[1]).toBe('');
+
+            const climateCall = mockPublishFn.mock.calls.find(
+                c => c[0] === 'testhomeassistant/climate/cgateweb_254_56_12/config'
+            );
+            expect(climateCall).toBeDefined();
+            const payload = JSON.parse(climateCall[1]);
+            expect(payload.device.name).toBe('Hallway Thermostat');
+            expect(payload.current_temperature_topic).toBe('cbus/read/254/56/12/current_temperature');
+            expect(payload.temperature_command_topic).toBe('cbus/write/254/56/12/setpoint');
+            expect(payload.temperature_state_topic).toBe('cbus/read/254/56/12/setpoint');
+            expect(payload.mode_command_topic).toBe('cbus/write/254/56/12/hvacmode');
+            expect(payload.modes).toEqual(expect.arrayContaining(['off', 'auto', 'cool', 'heat', 'fan_only']));
+        });
+
         it('should inject default_entity_id with domain prefix when entity_ids has an entry', () => {
             const labelData = {
                 labels: new Map([['254/56/10', 'Kitchen']]),

tests/webServer.test.js

@@ -541,6 +541,120 @@ describe('WebServer', () => {
         });
     });
 
+    describe('Ingress authentication (HA-authenticated requests)', () => {
+        let ingressServer;
+        let ingressPort;
+        const BASE = '/api/hassio_ingress/abc123';
+
+        afterEach(async () => {
+            if (ingressServer) await ingressServer.close();
+            ingressServer = null;
+        });
+
+        const patchThroughIngress = (port, headers = {}) => new Promise((resolve, reject) => {
+            const req = http.request({
+                hostname: '127.0.0.1',
+                port,
+                path: `${BASE}/api/labels`,
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json', ...headers }
+            }, (res) => {
+                let data = '';
+                res.on('data', (chunk) => { data += chunk; });
+                res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(data) }));
+            });
+            req.on('error', reject);
+            req.write(JSON.stringify({ '254/56/10': 'Patched' }));
+            req.end();
+        });
+
+        it('allows a mutation that arrives via HA Ingress when no API key is set (default add-on install)', async () => {
+            // Reproduces the user bug: a default HA add-on install has no
+            // web_api_key and web_allow_unauthenticated_mutations=false. The
+            // bundled UI is served through ingress, which HA has already
+            // authenticated, so the Supervisor-injected X-Ingress-Path header
+            // must be trusted. Previously this returned 401 "Unauthorized".
+            ingressServer = new WebServer({
+                port: 0,
+                basePath: BASE,
+                labelLoader,
+                getStatus: () => ({})
+            });
+            await ingressServer.start();
+            ingressPort = ingressServer._server.address().port;
+
+            const res = await patchThroughIngress(ingressPort, { 'X-Ingress-Path': BASE });
+            expect(res.status).toBe(200);
+        });
+
+        it('still rejects a non-ingress unauthenticated mutation when no API key is set', async () => {
+            // A direct request (no X-Ingress-Path) must remain blocked so an
+            // exposed port is not opened up by the ingress trust.
+            ingressServer = new WebServer({
+                port: 0,
+                basePath: BASE,
+                labelLoader,
+                getStatus: () => ({})
+            });
+            await ingressServer.start();
+            ingressPort = ingressServer._server.address().port;
+
+            const res = await patchThroughIngress(ingressPort);
+            expect(res.status).toBe(401);
+        });
+
+        it('ignores X-Ingress-Path when the server is not running in ingress mode', async () => {
+            // Without basePath the server is not behind ingress; a spoofed
+            // X-Ingress-Path header must not grant access.
+            ingressServer = new WebServer({
+                port: 0,
+                labelLoader,
+                getStatus: () => ({})
+            });
+            await ingressServer.start();
+            ingressPort = ingressServer._server.address().port;
+
+            const res = await new Promise((resolve, reject) => {
+                const req = http.request({
+                    hostname: '127.0.0.1',
+                    port: ingressPort,
+                    path: '/api/labels',
+                    method: 'PATCH',
+                    headers: { 'Content-Type': 'application/json', 'X-Ingress-Path': '/spoofed' }
+                }, (response) => {
+                    let data = '';
+                    response.on('data', (chunk) => { data += chunk; });
+                    response.on('end', () => resolve({ status: response.statusCode, body: JSON.parse(data) }));
+                });
+                req.on('error', reject);
+                req.write(JSON.stringify({ '254/56/10': 'Patched' }));
+                req.end();
+            });
+
+            expect(res.status).toBe(401);
+        });
+
+        it('still enforces a configured API key even for ingress requests', async () => {
+            // When an operator has explicitly set web_api_key (e.g. to harden an
+            // exposed port), it must always win over ingress trust.
+            ingressServer = new WebServer({
+                port: 0,
+                basePath: BASE,
+                labelLoader,
+                apiKey: 'secret-key',
+                getStatus: () => ({})
+            });
+            await ingressServer.start();
+            ingressPort = ingressServer._server.address().port;
+
+            const res = await patchThroughIngress(ingressPort, { 'X-Ingress-Path': BASE });
+            expect(res.status).toBe(401);
+
+            const ok = await patchThroughIngress(ingressPort, { 'X-Ingress-Path': BASE, 'X-API-Key': 'secret-key' });
+            expect(ok.status).toBe(200);
+        });
+    });
+
     describe('Mutation rate limiting', () => {
         let limitedServer;
         let limitedPort;