homebridge-bluos 0.1.0

package/dist/api/identity.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Stable player identity.
+ *
+ * Accessory identity must survive a DHCP lease change, so it is built from the
+ * chassis MAC and the zone's control port, never from an address. Verified on
+ * firmware 4.16.6 against a NAD CI-S2, where the primary zone reports
+ * `mac="90:56:82:0A:00:01"` and its secondary zone reports the same NIC with a
+ * port suffix, `mac="90:56:82:0A:00:01:11010"`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMac = parseMac;
+exports.normalizeMac = normalizeMac;
+exports.makePlayerId = makePlayerId;
+exports.makeGeneratedPlayerId = makeGeneratedPlayerId;
+exports.isValidPlayerId = isValidPlayerId;
+exports.formatEndpoint = formatEndpoint;
+exports.accessoryIdentityKey = accessoryIdentityKey;
+exports.hasAccessoryIdentity = hasAccessoryIdentity;
+const node_crypto_1 = require("node:crypto");
+const settings_1 = require("../settings");
+const MAC_OCTET = /^[0-9A-Fa-f]{2}$/;
+const BARE_MAC = /^[0-9A-Fa-f]{12}$/;
+const PLAYER_ID = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}$/;
+/**
+ * Parse a MAC as reported by `/SyncStatus` or an mDNS TXT record.
+ *
+ * Accepts three shapes seen in the field: six colon-separated octets, six
+ * octets plus a numeric zone-port suffix (multi-zone secondaries), and twelve
+ * bare hex digits (mDNS TXT records report `mac=9056820A0002`).
+ *
+ * Returns undefined rather than guessing, so a caller can fall back to a
+ * persisted identity instead of inventing an unstable one.
+ */
+function parseMac(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const cleaned = value.trim();
+    if (cleaned.length === 0) {
+        return undefined;
+    }
+    if (BARE_MAC.test(cleaned)) {
+        const octets = cleaned.toUpperCase().match(/.{2}/g);
+        return octets ? { mac: octets.join(':') } : undefined;
+    }
+    const parts = cleaned.split(':');
+    const octetsOk = parts.length >= 6 && parts.slice(0, 6).every((part) => MAC_OCTET.test(part));
+    if (!octetsOk) {
+        return undefined;
+    }
+    const mac = parts.slice(0, 6).join(':').toUpperCase();
+    if (parts.length === 6) {
+        return { mac };
+    }
+    const suffix = parts[6];
+    if (parts.length === 7 && suffix !== undefined && /^\d+$/.test(suffix)) {
+        const suffixPort = Number(suffix);
+        if (suffixPort >= settings_1.MIN_PORT && suffixPort <= settings_1.MAX_PORT) {
+            return { mac, suffixPort };
+        }
+    }
+    // Extra colon-separated fields we do not recognise: keep the NIC, drop the rest.
+    return { mac };
+}
+/** Normalise a MAC to six upper-case colon-separated octets, dropping any suffix. */
+function normalizeMac(value) {
+    return parseMac(value)?.mac;
+}
+/**
+ * Build a player id from a chassis MAC and the zone's control port.
+ *
+ * The result deliberately matches the shape a multi-zone secondary already
+ * reports for itself (`90:56:82:0A:00:01:11010`), so ids read the same whether
+ * they were derived here or observed on the wire.
+ */
+function makePlayerId(mac, port) {
+    return `${mac.toUpperCase()}:${port}`;
+}
+/**
+ * Generate a persisted identity for a player that reports no usable MAC.
+ *
+ * Deliberately random rather than derived from name or address: both change,
+ * and a changing id silently orphans the accessory. The discovery UI writes
+ * this into configuration once and it is stable from then on.
+ */
+function makeGeneratedPlayerId() {
+    return `gen-${(0, node_crypto_1.randomUUID)()}`;
+}
+/** True when a value is safe to use as a player id and accessory UUID seed. */
+function isValidPlayerId(value) {
+    return typeof value === 'string' && PLAYER_ID.test(value);
+}
+/** Canonical `host:port` string for an endpoint. */
+function formatEndpoint(host, port = settings_1.DEFAULT_BLUOS_PORT) {
+    return `${host}:${port}`;
+}
+/**
+ * The identity of an accessory: what it does, for which player.
+ *
+ * Two accessories with the same key are the same accessory, and one whose key
+ * changes is a different accessory. Contains no address, so re-addressing a
+ * player leaves every UUID untouched.
+ */
+function accessoryIdentityKey(accessory) {
+    const base = `${accessory.deviceId}:${accessory.kind}`;
+    return accessory.kind === 'volumePreset' ? `${base}:${accessory.volume ?? 0}` : base;
+}
+/** True when a cached context describes the same accessory as a resolved one. */
+function hasAccessoryIdentity(context, accessory) {
+    if (context.kind !== accessory.kind || context.deviceId !== accessory.deviceId) {
+        return false;
+    }
+    return accessory.kind !== 'volumePreset' || context.volume === accessory.volume;
+}

package/dist/api/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview API barrel.
+ */
+export * from './client';
+export * from './discovery';
+export * from './http';
+export * from './identity';
+export * from './sync-status';
+export * from './xml';

package/dist/api/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview API barrel.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
+__exportStar(require("./discovery"), exports);
+__exportStar(require("./http"), exports);
+__exportStar(require("./identity"), exports);
+__exportStar(require("./sync-status"), exports);
+__exportStar(require("./xml"), exports);

package/dist/api/sync-status.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Readers for `/SyncStatus` and `/Volume` responses.
+ *
+ * `/Status` is intentionally never requested. API v1.7 section 2 says
+ * "/SyncStatus should be polled if only the name, volume and grouping status of
+ * a player is of interest", which is precisely this plugin's scope, and for a
+ * group secondary `/Status` reports the *group's* volume while `/SyncStatus`
+ * reports that player's own. Polling only `/SyncStatus` is therefore both
+ * cheaper and more correct here.
+ */
+import type { PlayerObservation } from '../types';
+/**
+ * Parse a `/SyncStatus` response.
+ *
+ * @param endpoint canonical `host:port` this response came from. Used, alongside
+ * the response's own `id`, to tell a self-referential `<master>` apart from a
+ * real group leader.
+ */
+export declare function parseSyncStatus(body: string, endpoint: string): PlayerObservation;
+/** A parsed `/Volume` response. */
+export interface VolumeResult {
+    /** Level 0..100, or undefined when the player reports fixed volume. */
+    level?: number;
+    fixedVolume: boolean;
+    muted: boolean;
+    /** Pre-mute level, present only while muted. */
+    muteVolume?: number;
+    db?: number;
+}
+/**
+ * Parse a `/Volume` response.
+ *
+ * The level is the element's text content rather than an attribute:
+ * `<volume db="-39.8" mute="0" ...>35</volume>`.
+ */
+export declare function parseVolume(body: string): VolumeResult;
+/**
+ * The level to restore when a muted or zeroed player is switched back on.
+ *
+ * `muteVolume` is preferred because the player itself remembers the pre-mute
+ * level, which makes an unmute lossless without any state of our own. The
+ * remembered level is only a fallback for the other way of reaching silence,
+ * writing `level=0`, which the player cannot undo for us.
+ */
+export declare function restoreLevelFrom(observation: Pick<PlayerObservation, 'muteVolume'>, remembered: number | undefined, fallback: number): number;

package/dist/api/sync-status.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Readers for `/SyncStatus` and `/Volume` responses.
+ *
+ * `/Status` is intentionally never requested. API v1.7 section 2 says
+ * "/SyncStatus should be polled if only the name, volume and grouping status of
+ * a player is of interest", which is precisely this plugin's scope, and for a
+ * group secondary `/Status` reports the *group's* volume while `/SyncStatus`
+ * reports that player's own. Polling only `/SyncStatus` is therefore both
+ * cheaper and more correct here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSyncStatus = parseSyncStatus;
+exports.parseVolume = parseVolume;
+exports.restoreLevelFrom = restoreLevelFrom;
+const settings_1 = require("../settings");
+const errors_1 = require("../utils/errors");
+const identity_1 = require("./identity");
+const xml_1 = require("./xml");
+/** Clamp a reported level into the documented 0..100 range. */
+function clampVolume(value) {
+    return Math.min(settings_1.VOLUME_MAX, Math.max(settings_1.VOLUME_MIN, Math.round(value)));
+}
+/**
+ * Work out whether this player leads a group, follows one, or is standalone.
+ *
+ * `<slave>` children mean it is the primary; a `<master>` pointing anywhere
+ * other than itself means it is a secondary. A player can briefly report a
+ * `<master>` equal to its own endpoint while regrouping, which is not a
+ * following state.
+ *
+ * "Itself" is the `id` the player reports, falling back to the address we
+ * dialled. The distinction matters when a player is configured by hostname: its
+ * own `<master>` would then never match the endpoint, and a regrouping player
+ * would look like a follower.
+ */
+function readSyncRole(root, endpoint) {
+    if ((0, xml_1.children)(root, 'slave').length > 0) {
+        return 'primary';
+    }
+    const self = (0, xml_1.attr)(root, 'id') ?? endpoint;
+    const isSelf = (value) => value === self || value === endpoint;
+    const masterElement = (0, xml_1.child)(root, 'master');
+    if (masterElement !== undefined) {
+        const host = masterElement.text.trim();
+        const port = (0, xml_1.attr)(masterElement, 'port');
+        const master = host.includes(':') || port === undefined ? host : `${host}:${port}`;
+        if (master.length > 0 && !isSelf(master)) {
+            return 'secondary';
+        }
+    }
+    const legacyMaster = (0, xml_1.attr)(root, 'master');
+    if (legacyMaster !== undefined && !isSelf(legacyMaster)) {
+        return 'secondary';
+    }
+    return 'standalone';
+}
+/**
+ * Decide whether a player is muted.
+ *
+ * `/Volume` says so outright with `mute="1"`, but `/SyncStatus` carries no mute
+ * attribute at all. Verified against BluOS 4.16.6, where the same zone reports:
+ *
+ * - playing:  `volume="60" db="-32.1"`
+ * - muted:    `volume="0" db="-100" muteVolume="60" muteDb="-32.1"`
+ * - level 0:  `volume="0" db="-100"`
+ *
+ * So `db="-100"` is silence, not mute, and the two ways of reaching silence are
+ * told apart only by the remembered pre-mute level, which the firmware publishes
+ * exclusively while muted. Inferring mute from `db` instead would turn the mute
+ * switch on whenever a user dragged the slider to zero.
+ */
+function readMuted(root) {
+    if ((0, xml_1.attr)(root, 'mute') !== undefined) {
+        return (0, xml_1.boolAttr)(root, 'mute');
+    }
+    return (0, xml_1.attr)(root, 'muteVolume') !== undefined || (0, xml_1.attr)(root, 'muteDb') !== undefined;
+}
+function readBattery(root) {
+    const element = (0, xml_1.child)(root, 'battery');
+    if (element === undefined) {
+        return undefined;
+    }
+    const level = (0, xml_1.intAttr)(element, 'level');
+    if (level === undefined) {
+        return undefined;
+    }
+    return {
+        level: Math.min(100, Math.max(0, level)),
+        charging: (0, xml_1.boolAttr)(element, 'charging'),
+    };
+}
+/**
+ * Parse a `/SyncStatus` response.
+ *
+ * @param endpoint canonical `host:port` this response came from. Used, alongside
+ * the response's own `id`, to tell a self-referential `<master>` apart from a
+ * real group leader.
+ */
+function parseSyncStatus(body, endpoint) {
+    const root = (0, xml_1.parseXml)(body);
+    // Firmware has shipped both `SyncStatus` and lowercase variants; matching
+    // case-insensitively costs nothing and avoids a needless incompatibility.
+    if (root.name.toLowerCase() !== 'syncstatus') {
+        throw new errors_1.ProtocolError(`expected a SyncStatus response, got <${root.name}>`);
+    }
+    const rawVolume = (0, xml_1.intAttr)(root, 'volume');
+    const fixedVolume = rawVolume === settings_1.FIXED_VOLUME_SENTINEL;
+    const muted = readMuted(root);
+    const rawDb = (0, xml_1.floatAttr)(root, 'db');
+    const observation = {
+        name: (0, xml_1.attr)(root, 'name') ?? '',
+        brand: (0, xml_1.attr)(root, 'brand'),
+        model: (0, xml_1.attr)(root, 'model'),
+        modelName: (0, xml_1.attr)(root, 'modelName'),
+        firmware: (0, xml_1.attr)(root, 'version'),
+        mac: (0, identity_1.normalizeMac)((0, xml_1.attr)(root, 'mac')),
+        fixedVolume,
+        muted,
+        syncRole: readSyncRole(root, endpoint),
+        etag: (0, xml_1.attr)(root, 'etag'),
+        syncStat: (0, xml_1.attrOrChildText)(root, 'syncStat'),
+    };
+    if (rawVolume !== undefined && !fixedVolume) {
+        observation.volume = clampVolume(rawVolume);
+    }
+    const muteVolume = (0, xml_1.intAttr)(root, 'muteVolume');
+    if (muteVolume !== undefined) {
+        observation.muteVolume = clampVolume(muteVolume);
+    }
+    // `db="-100"` is the mute sentinel rather than a real output level, so it is
+    // dropped instead of being reported as if the amplifier were at -100 dB.
+    if (rawDb !== undefined && !(muted && rawDb <= settings_1.MUTED_DB_SENTINEL)) {
+        observation.db = rawDb;
+    }
+    const battery = readBattery(root);
+    if (battery !== undefined) {
+        observation.battery = battery;
+    }
+    return observation;
+}
+/**
+ * Parse a `/Volume` response.
+ *
+ * The level is the element's text content rather than an attribute:
+ * `<volume db="-39.8" mute="0" ...>35</volume>`.
+ */
+function parseVolume(body) {
+    const root = (0, xml_1.parseXml)(body);
+    if (root.name.toLowerCase() !== 'volume') {
+        throw new errors_1.ProtocolError(`expected a Volume response, got <${root.name}>`);
+    }
+    const rawLevel = Number.parseInt(root.text, 10);
+    const fixedVolume = rawLevel === settings_1.FIXED_VOLUME_SENTINEL;
+    const muted = (0, xml_1.boolAttr)(root, 'mute');
+    const rawDb = (0, xml_1.floatAttr)(root, 'db');
+    const result = { fixedVolume, muted };
+    if (Number.isInteger(rawLevel) && !fixedVolume) {
+        result.level = clampVolume(rawLevel);
+    }
+    const muteVolume = (0, xml_1.intAttr)(root, 'muteVolume');
+    if (muteVolume !== undefined) {
+        result.muteVolume = clampVolume(muteVolume);
+    }
+    if (rawDb !== undefined && !(muted && rawDb <= settings_1.MUTED_DB_SENTINEL)) {
+        result.db = rawDb;
+    }
+    return result;
+}
+/**
+ * The level to restore when a muted or zeroed player is switched back on.
+ *
+ * `muteVolume` is preferred because the player itself remembers the pre-mute
+ * level, which makes an unmute lossless without any state of our own. The
+ * remembered level is only a fallback for the other way of reaching silence,
+ * writing `level=0`, which the player cannot undo for us.
+ */
+function restoreLevelFrom(observation, remembered, fallback) {
+    const candidates = [observation.muteVolume, remembered, fallback];
+    for (const candidate of candidates) {
+        if (candidate !== undefined && candidate > settings_1.VOLUME_MIN && candidate <= settings_1.VOLUME_MAX) {
+            return candidate;
+        }
+    }
+    return fallback;
+}

package/dist/api/xml.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview A deliberately small XML reader for BluOS responses.
+ *
+ * BluOS answers with flat documents: attributes on the root element plus a
+ * handful of shallow children. A general-purpose parser would be a new
+ * dependency and a much larger attack surface for input that arrives unattested
+ * over the LAN, so this reads exactly the subset the API uses and refuses
+ * everything else.
+ *
+ * Hardening, in order of importance:
+ *
+ * - Document type declarations and entity declarations are rejected outright.
+ *   No `DOCTYPE` means no external entities (XXE) and no recursive entity
+ *   expansion (the "billion laughs" denial of service).
+ * - Only the five predefined entities and numeric character references are
+ *   decoded, and numeric references are bounded to valid Unicode scalars.
+ * - Byte length, nesting depth, element count and per-element attribute count
+ *   are all capped, so a malfunctioning or hostile endpoint cannot exhaust
+ *   memory.
+ */
+/** A parsed element. Immutable by contract; callers only read. */
+export interface XmlElement {
+    name: string;
+    attributes: Readonly<Record<string, string>>;
+    children: readonly XmlElement[];
+    /** Concatenated direct text content, trimmed. */
+    text: string;
+}
+/** Overridable limits, so tests can exercise the guards cheaply. */
+export interface XmlLimits {
+    maxBytes: number;
+    maxDepth: number;
+    maxElements: number;
+    maxAttributes: number;
+}
+/**
+ * Parse a BluOS XML response.
+ *
+ * @throws ProtocolError when the input breaks a limit, declares a document type
+ * or entity, or is not well-formed enough to read.
+ */
+export declare function parseXml(input: string | Buffer, overrides?: Partial<XmlLimits>): XmlElement;
+/** Read an attribute, or undefined when absent or empty after trimming. */
+export declare function attr(element: XmlElement | undefined, name: string): string | undefined;
+/** First direct child with the given name. */
+export declare function child(element: XmlElement | undefined, name: string): XmlElement | undefined;
+/** All direct children with the given name. */
+export declare function children(element: XmlElement | undefined, name: string): readonly XmlElement[];
+/** Text of the first direct child with the given name, when non-empty. */
+export declare function childText(element: XmlElement | undefined, name: string): string | undefined;
+/**
+ * Read a value that BluOS may report either as a root attribute or as a child
+ * element, preferring the attribute.
+ *
+ * `/SyncStatus` puts `syncStat` on the root while `/Status` makes it a child,
+ * and firmware versions differ on others, so callers should not have to care.
+ */
+export declare function attrOrChildText(element: XmlElement | undefined, name: string): string | undefined;
+/** Parse an integer attribute, returning undefined when absent or unparseable. */
+export declare function intAttr(element: XmlElement | undefined, name: string): number | undefined;
+/** Parse a decimal attribute, returning undefined when absent or unparseable. */
+export declare function floatAttr(element: XmlElement | undefined, name: string): number | undefined;
+/**
+ * Interpret a BluOS boolean.
+ *
+ * The API is inconsistent: `mute` is `0`/`1`, `initialized` and `charging` are
+ * `true`/`false`. Absent means false throughout, so callers that need to tell
+ * "absent" apart from "false" must check the attribute themselves — mute in
+ * `/SyncStatus` being the case that matters, since it is never present there.
+ */
+export declare function boolAttr(element: XmlElement | undefined, name: string): boolean;