homebridge-bluos 0.1.0

package/dist/utils/errors.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Error description helpers.
+ *
+ * Node wraps low-level network failures in `cause` chains, so a bare
+ * `error.message` frequently reads "fetch failed" while the useful detail
+ * (ECONNREFUSED, ETIMEDOUT) sits one level down.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionError = exports.ProtocolError = exports.ConfigValidationError = void 0;
+exports.describeError = describeError;
+exports.describeErrorStack = describeErrorStack;
+/** Longest description produced, so a hostile endpoint cannot flood the log. */
+const MAX_DESCRIPTION_LENGTH = 300;
+function messageOf(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        return typeof code === 'string' && code.length > 0
+            ? `${error.message} (${code})`
+            : error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        return JSON.stringify(error) ?? String(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+/**
+ * Describe an error, including any `cause` chain, for a single log line.
+ *
+ * Control characters are stripped: an error message can contain remote input,
+ * and a newline inside a log line lets an attacker forge log entries.
+ */
+function describeError(error) {
+    const parts = [];
+    let current = error;
+    const seen = new Set();
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const text = messageOf(current);
+        if (text.length > 0 && !parts.includes(text)) {
+            parts.push(text);
+        }
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    const joined = parts.length > 0 ? parts.join(': ') : 'unknown error';
+    const sanitized = joined.replace(/[\u0000-\u001F\u007F]/g, '\uFFFD');
+    return sanitized.length > MAX_DESCRIPTION_LENGTH
+        ? `${sanitized.slice(0, MAX_DESCRIPTION_LENGTH)}\u2026`
+        : sanitized;
+}
+/** Describe an error and append its stack, for `log.debug` only. */
+function describeErrorStack(error) {
+    const description = describeError(error);
+    if (error instanceof Error && typeof error.stack === 'string') {
+        return `${description}\n${error.stack}`;
+    }
+    return description;
+}
+/** Raised when configuration cannot produce a usable accessory set. */
+class ConfigValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigValidationError';
+    }
+}
+exports.ConfigValidationError = ConfigValidationError;
+/** Raised when a player answers, but not with something we can parse. */
+class ProtocolError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ProtocolError';
+    }
+}
+exports.ProtocolError = ProtocolError;
+/** Raised when a player cannot be reached at all. */
+class ConnectionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ConnectionError';
+    }
+}
+exports.ConnectionError = ConnectionError;

package/dist/utils/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Utility barrel.
+ */
+export * from './context';
+export * from './errors';
+export * from './serial';
+export * from './timing';
+export * from './validators';

package/dist/utils/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Utility 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("./context"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./serial"), exports);
+__exportStar(require("./timing"), exports);
+__exportStar(require("./validators"), exports);

package/dist/utils/serial.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Opaque HomeKit serial numbers.
+ *
+ * The player's MAC address is the obvious candidate and the wrong one. HomeKit
+ * shows SerialNumber in the Home app and it ends up in screenshots and bug
+ * reports, and a MAC is both identifying and, on a multi-zone chassis, shared
+ * between zones. A random value generated once and persisted in accessory
+ * context is stable across restarts without disclosing anything.
+ */
+import type { PlatformAccessory } from 'homebridge';
+/** Generate a fresh opaque serial number. */
+export declare function newAccessorySerialNumber(): string;
+/**
+ * Return this accessory's serial number, generating and persisting one if the
+ * cached accessory predates the field.
+ */
+export declare function ensureAccessorySerialNumber(accessory: PlatformAccessory): string;

package/dist/utils/serial.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Opaque HomeKit serial numbers.
+ *
+ * The player's MAC address is the obvious candidate and the wrong one. HomeKit
+ * shows SerialNumber in the Home app and it ends up in screenshots and bug
+ * reports, and a MAC is both identifying and, on a multi-zone chassis, shared
+ * between zones. A random value generated once and persisted in accessory
+ * context is stable across restarts without disclosing anything.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newAccessorySerialNumber = newAccessorySerialNumber;
+exports.ensureAccessorySerialNumber = ensureAccessorySerialNumber;
+const node_crypto_1 = require("node:crypto");
+/** Generate a fresh opaque serial number. */
+function newAccessorySerialNumber() {
+    return (0, node_crypto_1.randomUUID)();
+}
+/**
+ * Return this accessory's serial number, generating and persisting one if the
+ * cached accessory predates the field.
+ */
+function ensureAccessorySerialNumber(accessory) {
+    const context = accessory.context;
+    const existing = context.serialNumber;
+    if (typeof existing === 'string' && existing.length > 0) {
+        return existing;
+    }
+    const generated = newAccessorySerialNumber();
+    context.serialNumber = generated;
+    return generated;
+}

package/dist/utils/timing.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 Waiting primitives, in one place so the reference semantics are
+ * decided once.
+ *
+ * The distinction matters and is easy to get wrong. A timer inside an operation
+ * somebody is awaiting must keep the event loop alive: an unreferenced timer
+ * there lets Node decide the process has nothing left to do and exit while a
+ * caller is still waiting for an answer. That was a real defect in this plugin —
+ * the API's one-second minimum gap between requests for the same resource was
+ * implemented with an unreferenced timer, so a script that awaited a read could
+ * exit silently mid-request instead of returning a value.
+ *
+ * The opposite applies to a timer nothing is waiting on, such as a retry backoff
+ * inside a loop that can be cancelled. Those are always cleared rather than
+ * merely unreferenced, so shutdown is immediate instead of waiting out a delay
+ * that has been rendered pointless.
+ */
+/**
+ * Wait, keeping the process alive for the duration.
+ *
+ * For use inside an operation a caller is awaiting.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/** A wait that can be abandoned before it elapses. */
+export interface InterruptibleSleep {
+    /** Resolves when the delay elapses or {@link interrupt} is called. */
+    readonly promise: Promise<void>;
+    /** Resolve now and cancel the underlying timer. */
+    interrupt(): void;
+}
+/**
+ * Wait, but allow the wait to be cut short.
+ *
+ * The timer is cleared on interruption, so nothing is left holding the event
+ * loop open once the delay is no longer wanted.
+ */
+export declare function interruptibleSleep(ms: number): InterruptibleSleep;
+/** Returned by {@link raceTimeout} when the deadline came first. */
+export declare const TIMED_OUT: unique symbol;
+/**
+ * Race work against a deadline, without leaving the timer behind.
+ *
+ * The work is not cancelled when the deadline wins — that is the caller's
+ * decision — but the timer is always cleared, so a fast result does not leave a
+ * pending timer holding the process open.
+ */
+export declare function raceTimeout<T>(work: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT>;

package/dist/utils/timing.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Waiting primitives, in one place so the reference semantics are
+ * decided once.
+ *
+ * The distinction matters and is easy to get wrong. A timer inside an operation
+ * somebody is awaiting must keep the event loop alive: an unreferenced timer
+ * there lets Node decide the process has nothing left to do and exit while a
+ * caller is still waiting for an answer. That was a real defect in this plugin —
+ * the API's one-second minimum gap between requests for the same resource was
+ * implemented with an unreferenced timer, so a script that awaited a read could
+ * exit silently mid-request instead of returning a value.
+ *
+ * The opposite applies to a timer nothing is waiting on, such as a retry backoff
+ * inside a loop that can be cancelled. Those are always cleared rather than
+ * merely unreferenced, so shutdown is immediate instead of waiting out a delay
+ * that has been rendered pointless.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIMED_OUT = void 0;
+exports.sleep = sleep;
+exports.interruptibleSleep = interruptibleSleep;
+exports.raceTimeout = raceTimeout;
+/**
+ * Wait, keeping the process alive for the duration.
+ *
+ * For use inside an operation a caller is awaiting.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, Math.max(0, ms));
+    });
+}
+/**
+ * Wait, but allow the wait to be cut short.
+ *
+ * The timer is cleared on interruption, so nothing is left holding the event
+ * loop open once the delay is no longer wanted.
+ */
+function interruptibleSleep(ms) {
+    let cancel = () => { };
+    const promise = new Promise((resolve) => {
+        const timer = setTimeout(resolve, Math.max(0, ms));
+        cancel = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+    });
+    return { promise, interrupt: () => cancel() };
+}
+/** Returned by {@link raceTimeout} when the deadline came first. */
+exports.TIMED_OUT = Symbol('timed out');
+/**
+ * Race work against a deadline, without leaving the timer behind.
+ *
+ * The work is not cancelled when the deadline wins — that is the caller's
+ * decision — but the timer is always cleared, so a fast result does not leave a
+ * pending timer holding the process open.
+ */
+async function raceTimeout(work, ms) {
+    const deadline = interruptibleSleep(ms);
+    const expired = deadline.promise.then(() => exports.TIMED_OUT);
+    try {
+        return await Promise.race([work, expired]);
+    }
+    finally {
+        deadline.interrupt();
+    }
+}

package/dist/utils/validators.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Configuration validation.
+ *
+ * The split between fatal and non-fatal is deliberate. A structural problem —
+ * `devices` present but not an array — means the file does not describe anything
+ * we can act on, so the platform disables itself while leaving cached
+ * accessories registered, and HomeKit shows them as No Response rather than
+ * losing the rooms and automations built on them.
+ *
+ * A problem with one device is different: rejecting the whole fleet because one
+ * entry is malformed would be a worse outcome than skipping that entry. Skipped
+ * devices are warned about by name and reason, because a device that silently
+ * fails to appear is the hardest kind of bug for a user to report.
+ */
+import { type ResolvedAccessory, type ResolvedDevice, type SliderService } from '../types';
+/** Outcome of validating a platform configuration block. */
+export interface ConfigValidationResult {
+    /** Fatal problems. Any entry means the platform must not start polling. */
+    errors: string[];
+    /** Problems worth reporting that do not prevent operation. */
+    warnings: string[];
+    /** Devices that survived validation, in configuration order. */
+    devices: ResolvedDevice[];
+}
+/**
+ * Make an untrusted string safe to interpolate into a log line.
+ *
+ * Device names come from configuration and from the players themselves, so they
+ * are attacker-influenced in the threat model where someone can write to either.
+ * A newline in a log line lets them forge entries; truncation stops one long
+ * name from burying everything else.
+ */
+export declare function forLog(value: unknown): string;
+/**
+ * Make an untrusted string safe to publish to HomeKit.
+ *
+ * Same sanitising as {@link forLog} but capped at HomeKit's name budget rather
+ * than the log field budget, for values that become characteristic values and
+ * are written into the accessory cache. An empty result becomes undefined, so a
+ * caller keeps the value it already had instead of publishing a blank.
+ */
+export declare function forDisplay(value: string): string | undefined;
+/** True for an IPv4 literal whose octets are all in range. */
+export declare function isIpv4(value: string): boolean;
+/** True for something usable as an HTTP host: an IPv4 literal or a hostname. */
+export declare function isValidHost(value: unknown): value is string;
+/**
+ * True for an address outside the ranges treated as local.
+ *
+ * Local here is RFC 1918, RFC 6598 shared address space (CGNAT / Tailscale),
+ * loopback, and link-local. Not blocked in configuration, only warned about:
+ * the BluOS API is unauthenticated and intended for a local network, and a
+ * routable address in the configuration is much more likely to be a typo than
+ * an intention. Hostnames cannot be classified this way and are left alone
+ * in configuration; the settings-page probe uses {@link isProbeableHost}.
+ */
+export declare function isNonPrivateIpv4(value: string): boolean;
+/**
+ * True for a host the settings-page probe is allowed to dial.
+ *
+ * Narrower than {@link isValidHost}: configuration may name a split-DNS
+ * hostname that happens to look public, but the probe is an authenticated
+ * Homebridge administrator asking this host to open a connection, so it must
+ * not become a scanner. Public IPv4 literals and multi-label public names
+ * (`example.com`) are refused. Private IPv4 (including CGNAT) and local
+ * hostnames are accepted.
+ */
+export declare function isProbeableHost(value: unknown): value is string;
+/** Clamp the discovery window into the supported range. */
+export declare function resolveDiscoveryTimeoutSec(value: unknown, warnings?: string[]): number;
+/**
+ * Resolve a slider service, falling back to the platform default then `fan`.
+ *
+ * An empty string counts as absent, because that is what the Homebridge form
+ * writes for the per-device "use the platform setting" option; treating it as a
+ * bad value would make choosing that option override the platform setting.
+ */
+export declare function resolveSliderService(deviceValue: unknown, platformValue: unknown, warnings?: string[], label?: string): SliderService;
+/**
+ * Validate a platform configuration block.
+ *
+ * Never throws: the platform needs the errors and warnings in order to report
+ * them, and a configuration problem should produce a diagnosable log rather than
+ * an exception during Homebridge startup.
+ */
+export declare function validateConfig(config: unknown): ConfigValidationResult;
+/**
+ * Expand validated devices into the accessories to expose.
+ *
+ * Names are derived here rather than at use time so that duplicates can be
+ * detected once: two accessories sharing a name still work, but they make Siri
+ * ambiguous, which is worth a warning.
+ */
+export declare function resolveAccessories(devices: readonly ResolvedDevice[], warnings?: string[]): ResolvedAccessory[];