homebridge-bluos 0.1.0

package/dist/api/discovery.js

@@ -0,0 +1,402 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview mDNS discovery of BluOS zones.
+ *
+ * Two service types are browsed, because a multi-zone chassis advertises each
+ * zone separately: `_musc._tcp` for primary zones and `_musp._tcp` for the
+ * secondaries of a CI-S2 or CI 580. API v1.7 section 1 is explicit that the port
+ * "should be discovered by use of the MDNS protocol using the services musc.tcp
+ * and musp.tcp", and only the SRV record knows whether a zone is on 11000,
+ * 11010, 11020 or 11030.
+ *
+ * The appendix also describes LSDP, a UDP-broadcast alternative that Lenbrook
+ * says is more reliable than multicast on consumer networks. It is not
+ * implemented: on the network this plugin was developed against, mDNS returned
+ * every zone with full metadata while LSDP returned nothing at all, twice —
+ * first with a global broadcast and then with per-interface subnet broadcasts
+ * and an all-classes query. LSDP also never carries a zone's port, so it could
+ * not replace this path even where it does answer. Manual entry by address
+ * covers networks where multicast is filtered.
+ *
+ * Nothing here is trusted: an endpoint only counts as a player once it has
+ * answered `/SyncStatus`, which is also where authoritative identity comes from.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultMdnsFactory = exports.BluOSDiscovery = void 0;
+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 identity_1 = require("./identity");
+/** Re-query schedule, in milliseconds, to survive dropped multicast packets. */
+const QUERY_SCHEDULE_MS = [0, 400, 1_200];
+/** When to chase missing SRV, TXT and A records for known instances. */
+const FOLLOW_UP_SCHEDULE_MS = [700, 1_600];
+const IPV4 = /^(\d{1,3}\.){3}\d{1,3}$/;
+function isSrv(record) {
+    return record.type === 'SRV';
+}
+function isTxt(record) {
+    return record.type === 'TXT';
+}
+function isPtr(record) {
+    return record.type === 'PTR';
+}
+function isA(record) {
+    return record.type === 'A';
+}
+/**
+ * Decode TXT record data into key/value pairs.
+ *
+ * BluOS primaries advertise `model`, `version`, `mac` and `zs`; secondary zones
+ * omit `mac`, which is why identity is confirmed from `/SyncStatus` instead.
+ */
+function decodeTxt(data) {
+    // Null-prototyped: the keys come from an unauthenticated multicast packet, so
+    // a record of `__proto__=x` must land as an ordinary key rather than reaching
+    // the prototype chain.
+    const entries = Object.create(null);
+    const items = Array.isArray(data) ? data : [data];
+    for (const item of items) {
+        const text = typeof item === 'string' ? item : Buffer.from(item).toString('utf8');
+        const separator = text.indexOf('=');
+        if (separator <= 0) {
+            continue;
+        }
+        entries[text.slice(0, separator).toLowerCase()] = text.slice(separator + 1);
+    }
+    return entries;
+}
+/** Discovers BluOS zones and confirms them against the API. */
+class BluOSDiscovery {
+    log;
+    client;
+    createMdns;
+    /** Live browse windows, so a shutdown does not have to wait one out. */
+    openWindows = new Set();
+    cancelled = false;
+    constructor(options) {
+        this.log = options.log;
+        this.client = options.client;
+        this.createMdns = options.createMdns ?? exports.defaultMdnsFactory;
+    }
+    /**
+     * Abandon every browse in flight and refuse any that start afterwards.
+     *
+     * A browse window is a referenced timer holding a bound multicast socket, so
+     * without this a shutdown during an address re-resolution keeps the Homebridge
+     * process alive for the rest of the window — up to 30 s per unreachable
+     * player. One-way by design: it is only called when the platform is stopping.
+     */
+    cancelAll() {
+        this.cancelled = true;
+        for (const window of this.openWindows) {
+            window.interrupt();
+        }
+        this.openWindows.clear();
+    }
+    /**
+     * Browse for zones and return the ones that answer `/SyncStatus`.
+     *
+     * Failures are logged and skipped rather than thrown: a single unreachable
+     * player must not deny the user the rest of the fleet.
+     */
+    async discover(timeoutSec) {
+        const candidates = await this.browse(timeoutSec);
+        const endpoints = this.toEndpoints(candidates);
+        this.log.debug(`discovery: ${endpoints.length} candidate endpoint(s) to verify`);
+        const verified = await this.verifyAll(endpoints);
+        return verified.sort((left, right) => left.name.localeCompare(right.name));
+    }
+    /**
+     * Verify candidates a few at a time.
+     *
+     * Verification opens a connection and holds it for up to the status timeout,
+     * and nothing throttles distinct endpoints against each other, so verifying
+     * every advertisement at once would let whatever answered the browse decide how
+     * many sockets this plugin opens at one moment.
+     */
+    async verifyAll(entries) {
+        const found = [];
+        let next = 0;
+        const take = () => {
+            const entry = entries[next];
+            next += 1;
+            return entry;
+        };
+        const worker = async () => {
+            for (let entry = take(); entry !== undefined; entry = take()) {
+                if (this.cancelled) {
+                    return;
+                }
+                const player = await this.verify(entry);
+                if (player !== undefined) {
+                    found.push(player);
+                }
+            }
+        };
+        const width = Math.min(settings_1.DISCOVERY_VERIFY_CONCURRENCY, entries.length);
+        await Promise.all(Array.from({ length: width }, async () => worker()));
+        return found;
+    }
+    /**
+     * Find the current address of an already-known player.
+     *
+     * Called at launch and after a player goes silent, so a DHCP lease change does
+     * not require the user to re-save configuration.
+     */
+    async resolveEndpoint(playerId, timeoutSec) {
+        const players = await this.discover(timeoutSec);
+        const match = players.find((player) => player.id === playerId);
+        return match === undefined ? undefined : { host: match.host, port: match.port };
+    }
+    /** Probe one endpoint directly, for the UI's manual-entry path. */
+    async probe(endpoint) {
+        return this.verify({ endpoint, txt: {} });
+    }
+    async verify(entry) {
+        const target = (0, identity_1.formatEndpoint)(entry.endpoint.host, entry.endpoint.port);
+        try {
+            const observation = await this.client.readSyncStatus(entry.endpoint);
+            // A multi-zone secondary reports its chassis NIC with a port suffix, so the
+            // MAC alone is ambiguous; the zone's own port disambiguates it.
+            const mac = (0, identity_1.parseMac)(observation.mac)?.mac ?? (0, identity_1.parseMac)(entry.txt.mac)?.mac;
+            const player = {
+                id: mac === undefined ? '' : (0, identity_1.makePlayerId)(mac, entry.endpoint.port),
+                name: observation.name.length > 0 ? observation.name : target,
+                host: entry.endpoint.host,
+                port: entry.endpoint.port,
+                fixedVolume: observation.fixedVolume,
+                hasBattery: observation.battery !== undefined,
+            };
+            if (observation.brand !== undefined) {
+                player.brand = observation.brand;
+            }
+            if (observation.model !== undefined) {
+                player.model = observation.model;
+            }
+            if (observation.modelName !== undefined) {
+                player.modelName = observation.modelName;
+            }
+            if (observation.firmware !== undefined) {
+                player.firmware = observation.firmware;
+            }
+            if (mac !== undefined) {
+                player.mac = mac;
+            }
+            return player;
+        }
+        catch (error) {
+            this.log.debug(`discovery: ${target} did not answer SyncStatus: ${(0, errors_1.describeError)(error)}`);
+            return undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    toEndpoints(candidates) {
+        const seen = new Set();
+        const results = [];
+        for (const candidate of candidates.instances) {
+            const fromA = candidates.addresses.get(candidate.target.toLowerCase());
+            const host = fromA ?? candidate.responder;
+            if (host === undefined || !IPV4.test(host)) {
+                this.log.debug(`discovery: no IPv4 address for ${candidate.instance} (target ${candidate.target})`);
+                continue;
+            }
+            const key = (0, identity_1.formatEndpoint)(host, candidate.port);
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            if (results.length >= settings_1.MAX_DISCOVERY_CANDIDATES) {
+                this.log.warn(`discovery found more than ${settings_1.MAX_DISCOVERY_CANDIDATES} candidate endpoints; `
+                    + 'verifying the first ones only. Add the player by address in the plugin settings '
+                    + 'if it is missing');
+                break;
+            }
+            results.push({ endpoint: { host, port: candidate.port }, txt: candidate.txt });
+        }
+        return results;
+    }
+    /** Collect mDNS records for the configured window. */
+    async browse(timeoutSec) {
+        const services = [settings_1.MDNS_SERVICE_PRIMARY, settings_1.MDNS_SERVICE_SECONDARY];
+        const instanceService = new Map();
+        const srv = new Map();
+        const txt = new Map();
+        const addresses = new Map();
+        const responders = new Map();
+        if (this.cancelled) {
+            return { instances: [], addresses };
+        }
+        let session;
+        try {
+            session = this.createMdns();
+        }
+        catch (error) {
+            this.log.warn(`discovery unavailable: ${(0, errors_1.describeError)(error)}`);
+            return { instances: [], addresses };
+        }
+        const windowMs = Math.max(1, timeoutSec) * 1_000;
+        const browseWindow = (0, timing_1.interruptibleSleep)(windowMs);
+        this.openWindows.add(browseWindow);
+        /** Belongs to one of the browsed service types, so worth remembering. */
+        const isBrowsedInstance = (name) => services.some((service) => name.endsWith(`.${service}`));
+        let capacityWarned = false;
+        /** Record into a capped map, so a chatty or hostile segment cannot grow the heap. */
+        const remember = (map, key, value) => {
+            if (!map.has(key) && map.size >= settings_1.MAX_DISCOVERY_RECORDS) {
+                if (!capacityWarned) {
+                    capacityWarned = true;
+                    this.log.debug(`discovery: ignoring mDNS records past ${settings_1.MAX_DISCOVERY_RECORDS} of one kind`);
+                }
+                return;
+            }
+            map.set(key, value);
+        };
+        // A dead socket will never answer, so stop waiting on it. Discovery then
+        // returns empty and the caller falls back to configured addresses.
+        session.on('error', (error) => {
+            this.log.warn(`mDNS unavailable, discovery cannot run: ${(0, errors_1.describeError)(error)}`);
+            browseWindow.interrupt();
+        });
+        session.on('warning', (error) => {
+            this.log.debug(`mDNS warning: ${(0, errors_1.describeError)(error)}`);
+        });
+        session.on('response', (packet, remote) => {
+            const records = [...(packet.answers ?? []), ...(packet.additionals ?? [])];
+            for (const record of records) {
+                // SRV and TXT are matched on the service suffix rather than against the
+                // instances seen so far, because a single packet may carry the SRV ahead
+                // of the PTR that introduces it. Records for unrelated services on the
+                // segment are dropped rather than accumulated.
+                if (isPtr(record) && services.includes(record.name)) {
+                    remember(instanceService, record.data, record.name);
+                    remember(responders, record.data, remote.address);
+                }
+                else if (isSrv(record) && isBrowsedInstance(record.name)) {
+                    remember(srv, record.name, { port: record.data.port, target: record.data.target });
+                    remember(responders, record.name, remote.address);
+                }
+                else if (isTxt(record) && isBrowsedInstance(record.name)) {
+                    remember(txt, record.name, decodeTxt(record.data));
+                }
+                else if (isA(record)) {
+                    remember(addresses, record.name.toLowerCase(), record.data);
+                }
+            }
+        });
+        const ask = (questions) => {
+            if (questions.length === 0) {
+                return;
+            }
+            try {
+                session.query({ questions });
+            }
+            catch (error) {
+                this.log.debug(`mDNS query failed: ${(0, errors_1.describeError)(error)}`);
+            }
+        };
+        const timers = [];
+        const schedule = (delayMs, work) => {
+            if (delayMs >= windowMs) {
+                return;
+            }
+            timers.push(setTimeout(work, delayMs));
+        };
+        for (const delay of QUERY_SCHEDULE_MS) {
+            schedule(delay, () => {
+                ask(services.map((service) => ({ name: service, type: 'PTR' })));
+            });
+        }
+        for (const delay of FOLLOW_UP_SCHEDULE_MS) {
+            schedule(delay, () => {
+                const questions = [];
+                for (const instance of instanceService.keys()) {
+                    if (!srv.has(instance)) {
+                        questions.push({ name: instance, type: 'SRV' });
+                    }
+                    if (!txt.has(instance)) {
+                        questions.push({ name: instance, type: 'TXT' });
+                    }
+                }
+                for (const entry of srv.values()) {
+                    if (!addresses.has(entry.target.toLowerCase())) {
+                        questions.push({ name: entry.target, type: 'A' });
+                    }
+                }
+                ask(questions);
+            });
+        }
+        try {
+            await browseWindow.promise;
+        }
+        finally {
+            this.openWindows.delete(browseWindow);
+            browseWindow.interrupt();
+            for (const timer of timers) {
+                clearTimeout(timer);
+            }
+            try {
+                session.destroy();
+            }
+            catch (error) {
+                this.log.debug(`mDNS teardown failed: ${(0, errors_1.describeError)(error)}`);
+            }
+        }
+        const instances = [];
+        for (const [instance, service] of instanceService) {
+            const record = srv.get(instance);
+            if (record === undefined) {
+                this.log.debug(`discovery: no SRV record for ${instance}`);
+                continue;
+            }
+            const candidate = {
+                instance,
+                service,
+                port: record.port > 0 ? record.port : settings_1.DEFAULT_BLUOS_PORT,
+                target: record.target,
+                txt: txt.get(instance) ?? {},
+            };
+            const responder = responders.get(instance);
+            if (responder !== undefined) {
+                candidate.responder = responder;
+            }
+            instances.push(candidate);
+        }
+        return { instances, addresses };
+    }
+}
+exports.BluOSDiscovery = BluOSDiscovery;
+/**
+ * Default mDNS session.
+ *
+ * `loopback: false` stops us from answering our own queries, and the require is
+ * deferred so that importing this module — which the config UI does — cannot
+ * fail merely because a socket could not be bound.
+ *
+ * Interfaces are enumerated up front because `multicast-dns` does the same from
+ * inside its `listening` handler, where a throw would surface as an uncaught
+ * exception instead of a failed call. Doing it here keeps the failure catchable
+ * by {@link BluOSDiscovery.browse}, which degrades to "discovery unavailable".
+ */
+const defaultMdnsFactory = () => {
+    node_os_1.default.networkInterfaces();
+    const makeMdns = require('multicast-dns');
+    return makeMdns({ loopback: false, reuseAddr: true });
+};
+exports.defaultMdnsFactory = defaultMdnsFactory;

package/dist/api/http.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Minimal HTTP GET against a BluOS player.
+ *
+ * Built on `node:http` rather than `fetch` for two reasons.
+ *
+ * Separate connect and total timeouts. A long-poll legitimately takes 100
+ * seconds, but a powered-off player must fail in a couple of seconds rather
+ * than holding a slot for the full poll window. `AbortSignal.timeout` only
+ * expresses one deadline, so `fetch` cannot say "connect fast, then wait".
+ *
+ * No connection reuse, deliberately. Measured on firmware 4.16.6, a control
+ * call to a player completes in ~31 ms while that same endpoint has a
+ * `/SyncStatus` long-poll held open — but only because the two used different
+ * TCP connections. Sharing one keep-alive socket per endpoint would queue the
+ * write behind the held poll, which is the problem other BluOS clients solve
+ * with an explicit "drop the hold before writing" dance. Opening a fresh
+ * connection each time removes the failure mode instead of managing it, and on
+ * a LAN a handshake every hundred seconds costs nothing.
+ */
+/** A completed HTTP response. */
+export interface HttpResponse {
+    status: number;
+    body: string;
+}
+/** Per-request timing and size limits. */
+export interface HttpGetOptions {
+    /** Deadline for establishing the TCP connection. */
+    connectTimeoutMs: number;
+    /** Deadline for the whole exchange, including a long-poll hold. */
+    totalTimeoutMs: number;
+    /** Largest response body accepted, in bytes. */
+    maxBytes: number;
+    /** Cancels the request; used to drop long-polls at shutdown. */
+    signal?: AbortSignal;
+}
+/** Performs one GET. Injectable so tests never touch a socket. */
+export type HttpGet = (url: string, options: HttpGetOptions) => Promise<HttpResponse>;
+/**
+ * GET a URL with independent connect and total deadlines.
+ *
+ * Rejects with {@link ConnectionError} for anything that prevented an answer,
+ * and {@link ProtocolError} when the answer arrived but was unusable (over the
+ * size cap). Redirects are not followed: BluOS control endpoints do not issue
+ * them, and blindly following one would let a compromised player redirect us
+ * at an arbitrary host.
+ */
+export declare const httpGet: HttpGet;

package/dist/api/http.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Minimal HTTP GET against a BluOS player.
+ *
+ * Built on `node:http` rather than `fetch` for two reasons.
+ *
+ * Separate connect and total timeouts. A long-poll legitimately takes 100
+ * seconds, but a powered-off player must fail in a couple of seconds rather
+ * than holding a slot for the full poll window. `AbortSignal.timeout` only
+ * expresses one deadline, so `fetch` cannot say "connect fast, then wait".
+ *
+ * No connection reuse, deliberately. Measured on firmware 4.16.6, a control
+ * call to a player completes in ~31 ms while that same endpoint has a
+ * `/SyncStatus` long-poll held open — but only because the two used different
+ * TCP connections. Sharing one keep-alive socket per endpoint would queue the
+ * write behind the held poll, which is the problem other BluOS clients solve
+ * with an explicit "drop the hold before writing" dance. Opening a fresh
+ * connection each time removes the failure mode instead of managing it, and on
+ * a LAN a handshake every hundred seconds costs nothing.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpGet = void 0;
+const node_http_1 = __importDefault(require("node:http"));
+const errors_1 = require("../utils/errors");
+/**
+ * GET a URL with independent connect and total deadlines.
+ *
+ * Rejects with {@link ConnectionError} for anything that prevented an answer,
+ * and {@link ProtocolError} when the answer arrived but was unusable (over the
+ * size cap). Redirects are not followed: BluOS control endpoints do not issue
+ * them, and blindly following one would let a compromised player redirect us
+ * at an arbitrary host.
+ */
+const httpGet = (url, options) => {
+    const { connectTimeoutMs, totalTimeoutMs, maxBytes, signal } = options;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(new errors_1.ConnectionError('request aborted before it started'));
+            return;
+        }
+        let settled = false;
+        let onAbort;
+        // Held in a container because `cleanup` closes over it before the timer that
+        // fills it in can be created: the timer's callback needs `fail`, and `fail`
+        // needs `cleanup`.
+        const timers = {};
+        // `agent: false` gives this request its own connection and closes it after.
+        const request = node_http_1.default.get(url, { agent: false }, (response) => {
+            const chunks = [];
+            let received = 0;
+            response.on('data', (chunk) => {
+                received += chunk.length;
+                if (received > maxBytes) {
+                    fail(new errors_1.ProtocolError(`response exceeds ${maxBytes} bytes`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on('end', () => {
+                finish({
+                    status: response.statusCode ?? 0,
+                    body: Buffer.concat(chunks).toString('utf8'),
+                });
+            });
+            response.on('error', (error) => {
+                fail(new errors_1.ConnectionError('response stream failed', { cause: error }));
+            });
+        });
+        const cleanup = () => {
+            if (timers.total !== undefined) {
+                clearTimeout(timers.total);
+            }
+            if (onAbort !== undefined) {
+                signal?.removeEventListener('abort', onAbort);
+            }
+        };
+        const finish = (response) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            resolve(response);
+        };
+        const fail = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            request.destroy();
+            reject(error);
+        };
+        // Applies until the socket connects, then swapped for the total deadline.
+        request.setTimeout(connectTimeoutMs, () => {
+            fail(new errors_1.ConnectionError(`connect timed out after ${connectTimeoutMs}ms`));
+        });
+        request.on('socket', (socket) => {
+            const onConnect = () => {
+                // Connected: inactivity is now expected, because a long-poll is idle by
+                // design. The total deadline below is what bounds the request from here.
+                request.setTimeout(0);
+                socket.setNoDelay(true);
+            };
+            if (socket.connecting) {
+                socket.once('connect', onConnect);
+            }
+            else {
+                onConnect();
+            }
+        });
+        request.on('error', (error) => {
+            fail(new errors_1.ConnectionError('request failed', { cause: error }));
+        });
+        // Referenced on purpose, and always cleared in `cleanup`: a caller is
+        // awaiting this request, so the process must not be free to exit under it.
+        timers.total = setTimeout(() => {
+            fail(new errors_1.ConnectionError(`request timed out after ${totalTimeoutMs}ms`));
+        }, totalTimeoutMs);
+        if (signal !== undefined) {
+            onAbort = () => {
+                fail(new errors_1.ConnectionError('request aborted'));
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+};
+exports.httpGet = httpGet;

package/dist/api/identity.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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"`.
+ */
+import type { AccessoryKind, ResolvedAccessory } from '../types';
+/** A MAC split into its chassis part and, when present, a zone-port suffix. */
+export interface ParsedMac {
+    /** Six upper-case octets joined by colons. */
+    mac: string;
+    /** Zone control port carried in the MAC suffix, when the player reported one. */
+    suffixPort?: number;
+}
+/**
+ * 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.
+ */
+export declare function parseMac(value: unknown): ParsedMac | undefined;
+/** Normalise a MAC to six upper-case colon-separated octets, dropping any suffix. */
+export declare function normalizeMac(value: unknown): string | undefined;
+/**
+ * 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.
+ */
+export declare function makePlayerId(mac: string, port: number): string;
+/**
+ * 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.
+ */
+export declare function makeGeneratedPlayerId(): string;
+/** True when a value is safe to use as a player id and accessory UUID seed. */
+export declare function isValidPlayerId(value: unknown): value is string;
+/** Canonical `host:port` string for an endpoint. */
+export declare function formatEndpoint(host: string, port?: number): string;
+/**
+ * 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.
+ */
+export declare function accessoryIdentityKey(accessory: {
+    kind: AccessoryKind;
+    deviceId: string;
+    volume?: number;
+}): string;
+/** True when a cached context describes the same accessory as a resolved one. */
+export declare function hasAccessoryIdentity(context: {
+    kind?: unknown;
+    deviceId?: unknown;
+    volume?: unknown;
+}, accessory: ResolvedAccessory): boolean;