homebridge-bluos 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.0.3](https://github.com/tbaur/homebridge-bluos/compare/v2.0.2...v2.0.3) (2026-09-13)
+
+
+### Bug Fixes
+
+* skip public and loopback addresses in mDNS discovery ([#46](https://github.com/tbaur/homebridge-bluos/issues/46)) ([9010b86](https://github.com/tbaur/homebridge-bluos/commit/9010b861a95f8d11e450c7c3d877f1f243c2f01d))
+
 ## [2.0.2](https://github.com/tbaur/homebridge-bluos/compare/v2.0.1...v2.0.2) (2026-09-10)
 
 

package/README.md

@@ -56,7 +56,7 @@ Nothing needs enabling on the player, because the BluOS LAN API is always on. A
 
 ### 3. Configure
 
-**Homebridge UI** (recommended): open the plugin settings and press **Discover Players**. Every zone that answers is listed. Tick the players and accessories you want, then press the Homebridge Save button.
+**Homebridge UI** (recommended): open the plugin settings and press **Discover Players**. Every zone that answers on a local IPv4 address is listed. Public and loopback advertisements are skipped. Tick the players and accessories you want, then press the Homebridge Save button.
 
 Or in `config.json`:
 

package/SECURITY.md

@@ -16,8 +16,8 @@ Do not open a public issue. Use GitHub's [private vulnerability reporting](https
 - **Input validation:** Config is checked at startup. A missing or non-list `devices` value disables the platform without unregistering accessories. A bad player or preset is skipped. Hosts, ports and timeouts are rejected or clamped.
 - **Log safety:** Values written to logs have control characters stripped and are length-limited.
 - **Bounded I/O:** Connect and total timeouts on every request, responses capped at 128 KiB, and XML parsed with size, depth and element caps.
-- **Discovery:** mDNS errors are caught so they cannot take Homebridge down. Browse results are capped.
-- **Settings probe:** Accepts only a private or local address and a documented BluOS port.
+- **Discovery:** mDNS errors are caught so they cannot take Homebridge down. Browse results are capped. Advertised addresses are verified only when they are local (RFC 1918, CGNAT/Tailscale, link-local). Public IPv4 and loopback are skipped, so an advertisement cannot make Homebridge open `/SyncStatus` on itself or on the public internet. Players already in configuration are unchanged.
+- **Settings probe:** Accepts only a private or local address and a documented BluOS port. Loopback is allowed here because an administrator asked for that probe.
 - **Dependencies:** CI runs `npm audit` on the runtime tree and OSV-Scanner on the full tree.
 
 ## Best Practices for Users

package/dist/api/discovery.d.ts

@@ -112,10 +112,12 @@ export declare class BluOSDiscovery {
     /**
      * Turn service instances into addressable endpoints.
      *
-     * A zone is only usable once its SRV record (for the port) and an IPv4 address
-     * are both known. The address comes from an A record when one was offered, and
-     * otherwise from the responder's own source address, which for a player
-     * advertising its own service is the same machine.
+     * A zone is only usable once its SRV record (for the port) and a local IPv4
+     * address are both known (RFC 1918, CGNAT / Tailscale, link-local). Public
+     * IPv4 and loopback are ignored, so an advertisement cannot point verify at
+     * Homebridge or at an off-network host. The address comes from an A record
+     * when one was offered, and otherwise from the responder's own source
+     * address, which for a player advertising its own service is the same machine.
      */
     private toEndpoints;
     /** Collect mDNS records for the configured window. */

package/dist/api/discovery.js

@@ -35,6 +35,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const settings_1 = require("../settings");
 const errors_1 = require("../utils/errors");
 const timing_1 = require("../utils/timing");
+const validators_1 = require("../utils/validators");
 const identity_1 = require("./identity");
 /** Re-query schedule, in milliseconds, to survive dropped multicast packets. */
 const QUERY_SCHEDULE_MS = [0, 400, 1_200];
@@ -202,10 +203,12 @@ class BluOSDiscovery {
     /**
      * Turn service instances into addressable endpoints.
      *
-     * A zone is only usable once its SRV record (for the port) and an IPv4 address
-     * are both known. The address comes from an A record when one was offered, and
-     * otherwise from the responder's own source address, which for a player
-     * advertising its own service is the same machine.
+     * A zone is only usable once its SRV record (for the port) and a local IPv4
+     * address are both known (RFC 1918, CGNAT / Tailscale, link-local). Public
+     * IPv4 and loopback are ignored, so an advertisement cannot point verify at
+     * Homebridge or at an off-network host. The address comes from an A record
+     * when one was offered, and otherwise from the responder's own source
+     * address, which for a player advertising its own service is the same machine.
      */
     toEndpoints(candidates) {
         const seen = new Set();
@@ -217,6 +220,13 @@ class BluOSDiscovery {
                 this.log.debug(`discovery: no IPv4 address for ${candidate.instance} (target ${candidate.target})`);
                 continue;
             }
+            if (!(0, validators_1.isDiscoveryHost)(host)) {
+                const reason = (0, validators_1.isLoopbackIpv4)(host)
+                    ? 'loopback is not accepted from mDNS'
+                    : 'not a local address';
+                this.log.debug(`discovery: skipping ${host} (${reason})`);
+                continue;
+            }
             const key = (0, identity_1.formatEndpoint)(host, candidate.port);
             if (seen.has(key)) {
                 continue;

package/dist/utils/validators.d.ts

@@ -85,6 +85,17 @@ export declare function isNonPrivateIpv4(value: string): boolean;
  * hostnames are accepted.
  */
 export declare function isProbeableHost(value: unknown): value is string;
+/**
+ * True for an address discovery may dial after an unsolicited mDNS advertisement.
+ *
+ * Narrower than {@link isProbeableHost}. The settings-page probe is an
+ * administrator asking this host to open a connection, so loopback is allowed
+ * there. An advertisement on the LAN is not a request, and a packet that names
+ * 127.0.0.1 would make Homebridge talk to itself.
+ */
+export declare function isDiscoveryHost(value: unknown): value is string;
+/** True for IPv4 loopback (first octet 127). `isProbeableHost` treats this as local; discovery does not. */
+export declare function isLoopbackIpv4(value: string): boolean;
 /** Clamp the discovery window into the supported range. */
 export declare function resolveDiscoveryTimeoutSec(value: unknown, warnings?: string[]): number;
 /**

package/dist/utils/validators.js

@@ -25,6 +25,8 @@ exports.isIpv4 = isIpv4;
 exports.isValidHost = isValidHost;
 exports.isNonPrivateIpv4 = isNonPrivateIpv4;
 exports.isProbeableHost = isProbeableHost;
+exports.isDiscoveryHost = isDiscoveryHost;
+exports.isLoopbackIpv4 = isLoopbackIpv4;
 exports.resolveDiscoveryTimeoutSec = resolveDiscoveryTimeoutSec;
 exports.resolveSliderService = resolveSliderService;
 exports.validateConfig = validateConfig;
@@ -169,6 +171,28 @@ function isProbeableHost(value) {
     }
     return PROBE_LOCAL_SUFFIXES.some((suffix) => lower.endsWith(suffix) && lower.length > suffix.length);
 }
+/**
+ * True for an address discovery may dial after an unsolicited mDNS advertisement.
+ *
+ * Narrower than {@link isProbeableHost}. The settings-page probe is an
+ * administrator asking this host to open a connection, so loopback is allowed
+ * there. An advertisement on the LAN is not a request, and a packet that names
+ * 127.0.0.1 would make Homebridge talk to itself.
+ */
+function isDiscoveryHost(value) {
+    if (!isProbeableHost(value)) {
+        return false;
+    }
+    return !isLoopbackIpv4(value.trim());
+}
+/** True for IPv4 loopback (first octet 127). `isProbeableHost` treats this as local; discovery does not. */
+function isLoopbackIpv4(value) {
+    if (!isIpv4(value)) {
+        return false;
+    }
+    const [firstOctet = 0] = value.split('.').map(Number);
+    return firstOctet === 127;
+}
 /** Clamp the discovery window into the supported range. */
 function resolveDiscoveryTimeoutSec(value, warnings) {
     if (value === undefined) {

package/docs/FEATURES.md

@@ -42,7 +42,7 @@ A checklist of what is built. The plugin aims to cover everything about a BluOS
 - ✅ An unusable configuration disables the platform and keeps every accessory registered. Nothing is deleted
 - ✅ Per-device validation: one bad entry is skipped with a warning instead of stopping the rest
 - ✅ Size-, depth-, element- and attribute-capped XML parsing, sanitised log output, and a length cap on any identity a player reports for itself
-- ✅ Bounded discovery: the records kept from a browse, the candidates verified from it and the verifications in flight are all capped
+- ✅ Bounded discovery: the records kept from a browse, the candidates verified from it and the verifications in flight are all capped. Public IPv4 and loopback advertisements are not verified
 - ✅ Clean shutdown: poll loops, backoff delays and mDNS browses are cancelled, not left to run out
 - ✅ A cached accessory that the plugin cannot drive reports No Response and says what to do about it. It never shows a stale value forever
 - ✅ Custom Homebridge UI settings page, plus a plain `config.schema.json` form

package/docs/PROTOCOL.md

@@ -259,7 +259,7 @@ mDNS, browsing two service types:
 | `_musc._tcp.local` | Primary players |
 | `_musp._tcp.local` | Secondary zones of a multi-zone chassis (spec appendix §13.1, LSDP class `0x0003`) |
 
-A zone is usable once its `SRV` record (for the port) and an IPv4 address are both known; the address comes from an `A` record when one is offered and otherwise from the responder's own source address. `TXT` records carry `model`, `version`, `mac` and `zs`, but secondary zones **omit `mac`**. That is why identity is always confirmed by reading `/SyncStatus`, and never trusted from the advertisement alone.
+A zone is usable once its `SRV` record (for the port) and a **local** IPv4 address are both known; the address comes from an `A` record when one is offered and otherwise from the responder's own source address. Public IPv4 and loopback advertisements are ignored, so a packet on the LAN cannot steer verify at Homebridge itself or at an off-network host. `TXT` records carry `model`, `version`, `mac` and `zs`, but secondary zones **omit `mac`**. That is why identity is always confirmed by reading `/SyncStatus`, and never trusted from the advertisement alone.
 
 **LSDP** (UDP 11430) is documented as an alternative and was tried first: it failed repeatedly against this fleet, while mDNS answered reliably. mDNS is therefore the only discovery path, with manual address entry as the fallback for networks that filter multicast.
 

package/docs/README-DETAILED.md

@@ -60,7 +60,7 @@ Name it with `options.rebootAllName`. It is the one accessory with no room of it
 
 ## Reliability in detail
 
-**Discovery in the settings page.** Finds zones over mDNS and writes the configuration for you, including the stable identity the platform will look for. Manual address entry covers networks where multicast is filtered.
+**Discovery in the settings page.** Finds zones over mDNS and writes the configuration for you, including the stable identity the platform will look for. Only local IPv4 advertisements are verified (private, CGNAT/Tailscale, link-local). Public and loopback addresses are skipped. Manual address entry covers networks where multicast is filtered; the settings probe still allows loopback because you typed it.
 
 **Long-polling, not polling.** `/SyncStatus?timeout=100` with an `etag`, so a change made on the front panel, the remote or the BluOS app reaches HomeKit in about a second, without hammering the player. One poll loop per zone, because the etag is per zone and not per chassis.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-bluos",
   "displayName": "Homebridge BluOS",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Homebridge plugin for BluOS players — per-zone volume, mute, volume-preset and battery accessories over the LAN Custom Integration API. Verified on NAD and Bluesound hardware",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",