homebridge-navilink 0.1.0

package/dist/api/http.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview JSON over HTTPS against the NaviLink cloud.
+ *
+ * Built on `node:https` rather than `fetch` for three reasons, in ascending
+ * order of how much they matter.
+ *
+ * A response size cap. `fetch` gives you a body you have already committed to
+ * buffering, or a stream you have to cap by hand; a cap applied as bytes
+ * arrive is both simpler and actually enforced. The cloud is not ours and its
+ * responses are not bounded by anything we control.
+ *
+ * Separate connect and total deadlines. `AbortSignal.timeout` expresses one
+ * instant, so it cannot say "reach the host quickly, then allow it time to
+ * answer". An unreachable cloud should fail startup in seconds, not hold a
+ * slot for the whole request budget.
+ *
+ * Control over what is logged. Everything on this path is a credential: the
+ * request body carries the password, and the response body carries a JWT pair
+ * and a set of AWS keys. `fetch` errors quote the URL, and a debug logger
+ * wrapped round it would eventually quote a body. Here, the only thing that
+ * reaches the log is the method and the path.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postJson = void 0;
+exports.parseJsonBody = parseJsonBody;
+const node_https_1 = __importDefault(require("node:https"));
+const errors_1 = require("../utils/errors");
+const redact_1 = require("../utils/redact");
+/** Longest body excerpt put into a parse-failure message. */
+const MAX_BODY_EXCERPT = 80;
+/**
+ * POST a JSON body and read the response as text.
+ *
+ * Rejects with {@link ConnectionError} for anything that prevented an answer
+ * and {@link ProtocolError} when the answer arrived but was unusable. Parsing
+ * is left to the caller: a non-200 from this API still carries a JSON body
+ * explaining why, and throwing on the status here would discard it.
+ *
+ * Redirects are not followed. The cloud does not issue them, and following one
+ * would let a compromised or spoofed endpoint move a request that carries the
+ * user's password to a host of its choosing.
+ */
+const postJson = (url, body, options) => {
+    const { connectTimeoutMs, totalTimeoutMs, maxBytes, headers = {}, signal } = options;
+    const payload = JSON.stringify(body ?? {});
+    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 = {};
+        const request = node_https_1.default.request(url, {
+            method: 'POST',
+            // A connection per request. There is no long-poll to queue behind here,
+            // but sign-in and the device list are a handful of calls per hour and a
+            // pooled socket to a cloud endpoint is one more thing holding state
+            // across a token refresh.
+            agent: false,
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/json',
+                'content-length': String(Buffer.byteLength(payload)),
+                ...headers,
+            },
+        }, (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.connect !== undefined) {
+                clearTimeout(timers.connect);
+            }
+            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);
+        };
+        // Our own timer, not `request.setTimeout`. Node defers that call until
+        // the socket is already connected, then this module immediately clears
+        // it. Without that, a host that blackholes the SYN would sit on the
+        // total deadline instead of failing in seconds, which is the whole
+        // point of having two clocks.
+        timers.connect = setTimeout(() => {
+            fail(new errors_1.ConnectionError(`connect timed out after ${connectTimeoutMs}ms`));
+        }, connectTimeoutMs);
+        request.on('socket', (socket) => {
+            const onReady = () => {
+                if (timers.connect !== undefined) {
+                    clearTimeout(timers.connect);
+                    timers.connect = undefined;
+                }
+                socket.setNoDelay(true);
+            };
+            if (socket.connecting) {
+                // A TLSSocket has `encrypted`. Waiting on TCP `connect` would clear
+                // the timer before the handshake finishes. A plain socket (the test
+                // loopback under an `https:` URL) only emits `connect`.
+                if ('encrypted' in socket) {
+                    socket.once('secureConnect', onReady);
+                }
+                else {
+                    socket.once('connect', onReady);
+                }
+            }
+            else {
+                onReady();
+            }
+        });
+        request.on('error', (error) => {
+            // The message is deliberately generic. Node puts the request URL into
+            // some socket errors, and while this API's URLs carry no secrets, the
+            // rule that nothing from this layer quotes a URL is easier to keep than
+            // an exception list.
+            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 });
+        }
+        request.end(payload);
+    });
+};
+exports.postJson = postJson;
+/**
+ * Parse a response body as JSON, or explain why it could not be.
+ *
+ * The excerpt in the failure message is capped and redacted: a gateway error
+ * page can be a whole HTML document, and a partial JSON body from this API
+ * would otherwise put a token into the log.
+ */
+function parseJsonBody(body) {
+    if (body.length === 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch (error) {
+        throw new errors_1.ProtocolError(`the cloud returned a body that is not JSON (${bodyExcerpt(body)})`, { cause: error });
+    }
+}
+/** A short, redacted look at a body that could not be parsed. */
+function bodyExcerpt(body) {
+    const cleaned = (0, redact_1.redactSecrets)(body).replace(/[\u0000-\u001F\u007F]/g, '\uFFFD');
+    return cleaned.length > MAX_BODY_EXCERPT
+        ? `${cleaned.slice(0, MAX_BODY_EXCERPT)}\u2026`
+        : cleaned;
+}

package/dist/api/identity.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Stable appliance identity.
+ *
+ * Accessory identity has to survive everything that legitimately changes about
+ * an installation: a new router, a re-paired gateway, a firmware update, a
+ * renamed device, a changed account email. What is left is the gateway's MAC
+ * address and the channel the appliance sits on, so that is what identity is.
+ *
+ * The MAC never leaves this layer in the clear. It is the appliance's address
+ * in every MQTT topic, so it is a capability as much as an identifier: it goes
+ * into a device id and into topic construction, and everywhere else (logs,
+ * HomeKit serial numbers, bug reports) it is masked.
+ */
+import type { AccessoryKind, ResolvedAccessory } from '../types';
+/**
+ * Normalise a MAC to the cloud's own spelling: lower-case hex, no separators.
+ *
+ * Accepts the colon-separated form as well, because a hand-edited
+ * configuration is likely to use it and rejecting that would be a puzzle
+ * rather than a help. Returns undefined rather than guessing, so a caller can
+ * skip the entry instead of building an unstable identity from a bad value.
+ */
+export declare function normalizeMac(value: unknown): string | undefined;
+/** Build a device id from a gateway MAC and a channel number. */
+export declare function makeDeviceId(mac: string, channel: number): string;
+/** The MAC and channel inside a device id, or undefined when it is malformed. */
+export declare function parseDeviceId(value: unknown): {
+    mac: string;
+    channel: number;
+} | undefined;
+/**
+ * The identity of an accessory: what it does, for which appliance.
+ *
+ * Two accessories with the same key are the same accessory, and one whose key
+ * changes is a different accessory that takes the old one's rooms, scenes and
+ * automations with it when the old one goes.
+ */
+export declare function accessoryIdentityKey(accessory: {
+    kind: AccessoryKind;
+    deviceId: string;
+}): string;
+/** True when a cached context describes the same accessory as a resolved one. */
+export declare function hasAccessoryIdentity(context: {
+    kind?: unknown;
+    deviceId?: unknown;
+}, accessory: ResolvedAccessory): boolean;

package/dist/api/identity.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Stable appliance identity.
+ *
+ * Accessory identity has to survive everything that legitimately changes about
+ * an installation: a new router, a re-paired gateway, a firmware update, a
+ * renamed device, a changed account email. What is left is the gateway's MAC
+ * address and the channel the appliance sits on, so that is what identity is.
+ *
+ * The MAC never leaves this layer in the clear. It is the appliance's address
+ * in every MQTT topic, so it is a capability as much as an identifier: it goes
+ * into a device id and into topic construction, and everywhere else (logs,
+ * HomeKit serial numbers, bug reports) it is masked.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeMac = normalizeMac;
+exports.makeDeviceId = makeDeviceId;
+exports.parseDeviceId = parseDeviceId;
+exports.accessoryIdentityKey = accessoryIdentityKey;
+exports.hasAccessoryIdentity = hasAccessoryIdentity;
+const settings_1 = require("../settings");
+/** Twelve hex digits, which is how the cloud spells a MAC. */
+const BARE_MAC = /^[0-9a-f]{12}$/;
+/**
+ * Normalise a MAC to the cloud's own spelling: lower-case hex, no separators.
+ *
+ * Accepts the colon-separated form as well, because a hand-edited
+ * configuration is likely to use it and rejecting that would be a puzzle
+ * rather than a help. Returns undefined rather than guessing, so a caller can
+ * skip the entry instead of building an unstable identity from a bad value.
+ */
+function normalizeMac(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const cleaned = value.trim().toLowerCase().replaceAll(/[:-]/g, '');
+    return BARE_MAC.test(cleaned) ? cleaned : undefined;
+}
+/** Build a device id from a gateway MAC and a channel number. */
+function makeDeviceId(mac, channel) {
+    return `${mac.toLowerCase()}:${channel}`;
+}
+/** The MAC and channel inside a device id, or undefined when it is malformed. */
+function parseDeviceId(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const separator = value.lastIndexOf(':');
+    if (separator <= 0) {
+        return undefined;
+    }
+    const mac = normalizeMac(value.slice(0, separator));
+    const channel = Number(value.slice(separator + 1));
+    if (mac === undefined || !Number.isInteger(channel)) {
+        return undefined;
+    }
+    if (channel < settings_1.MIN_CHANNEL || channel > settings_1.MAX_CHANNEL) {
+        return undefined;
+    }
+    return { mac, channel };
+}
+/**
+ * The identity of an accessory: what it does, for which appliance.
+ *
+ * Two accessories with the same key are the same accessory, and one whose key
+ * changes is a different accessory that takes the old one's rooms, scenes and
+ * automations with it when the old one goes.
+ */
+function accessoryIdentityKey(accessory) {
+    return `${accessory.deviceId}:${accessory.kind}`;
+}
+/** True when a cached context describes the same accessory as a resolved one. */
+function hasAccessoryIdentity(context, accessory) {
+    return context.kind === accessory.kind && context.deviceId === accessory.deviceId;
+}

package/dist/api/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview API barrel.
+ */
+export * from './channel';
+export * from './http';
+export * from './identity';
+export * from './mqtt';
+export * from './mqtt-codec';
+export * from './protocol';
+export * from './rest';
+export * from './sigv4';
+export * from './topics';

package/dist/api/index.js

@@ -0,0 +1,33 @@
+"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("./channel"), exports);
+__exportStar(require("./http"), exports);
+__exportStar(require("./identity"), exports);
+__exportStar(require("./mqtt"), exports);
+__exportStar(require("./mqtt-codec"), exports);
+__exportStar(require("./protocol"), exports);
+__exportStar(require("./rest"), exports);
+__exportStar(require("./sigv4"), exports);
+__exportStar(require("./topics"), exports);

package/dist/api/mqtt-codec.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview MQTT 3.1.1 packet encoding and decoding, for the subset AWS
+ * IoT needs.
+ *
+ * Writing this rather than taking a dependency was a deliberate call, and the
+ * reasoning belongs next to the code it justifies.
+ *
+ * `mqtt.js` rebuilds the WebSocket path from its own parsed options, which
+ * discards the SigV4 query string, so the upgrade is rejected or hangs. The
+ * documented way round is `transformWsUrl`, a hook that exists to undo what the
+ * library just did. That is a bad sign for the one part of this plugin where a
+ * subtle failure means a user's heating silently stops responding.
+ *
+ * AWS IoT speaks 3.1.1, this plugin needs seven packet types, and the wire
+ * format is a fixed header, a variable-length integer and length-prefixed
+ * strings. It is a few hundred lines with no I/O in it, which makes it
+ * exhaustively testable without a socket. The family this plugin belongs to
+ * already hand-rolls a capped XML reader for the same reason. The dependency
+ * it replaces brings roughly twenty transitive packages into a plugin that
+ * handles a cloud password, which the security posture would rather not carry.
+ *
+ * What is deliberately absent: QoS 2 (AWS IoT does not support it), retained
+ * message handling beyond the flag, topic aliases and MQTT 5 properties. If a
+ * future NaviLink protocol needs any of them, add it here with a test rather
+ * than reaching back for the library.
+ *
+ * Section references are to the OASIS MQTT 3.1.1 specification.
+ */
+/** Packet type codes (§2.2.1). */
+export declare const PacketType: {
+    readonly CONNECT: 1;
+    readonly CONNACK: 2;
+    readonly PUBLISH: 3;
+    readonly PUBACK: 4;
+    readonly SUBSCRIBE: 8;
+    readonly SUBACK: 9;
+    readonly PINGREQ: 12;
+    readonly PINGRESP: 13;
+    readonly DISCONNECT: 14;
+};
+/**
+ * Largest packet accepted from the broker.
+ *
+ * A status frame is a couple of kilobytes. 256 KiB is generous while keeping a
+ * malfunctioning or hostile broker from growing the heap: the remaining-length
+ * field can encode 256 MB, and a decoder that trusts it will happily buffer
+ * that much before noticing.
+ */
+export declare const MAX_PACKET_BYTES = 262144;
+/** A message the broker delivered to us. */
+export interface PublishPacket {
+    type: typeof PacketType.PUBLISH;
+    topic: string;
+    payload: Uint8Array;
+    qos: 0 | 1;
+    retain: boolean;
+    dup: boolean;
+    /** Present for QoS 1, which must be acknowledged. */
+    packetId?: number;
+}
+/** The broker's answer to our CONNECT. */
+export interface ConnackPacket {
+    type: typeof PacketType.CONNACK;
+    sessionPresent: boolean;
+    returnCode: number;
+}
+/** The broker's acknowledgement of a QoS 1 PUBLISH we sent. */
+export interface PubackPacket {
+    type: typeof PacketType.PUBACK;
+    packetId: number;
+}
+/** The broker's answer to a SUBSCRIBE. */
+export interface SubackPacket {
+    type: typeof PacketType.SUBACK;
+    packetId: number;
+    /** One per requested topic: the granted QoS, or 0x80 for a refusal. */
+    returnCodes: number[];
+}
+/** The broker's answer to a PINGREQ. */
+export interface PingrespPacket {
+    type: typeof PacketType.PINGRESP;
+}
+/** Any packet this decoder produces. */
+export type DecodedPacket = ConnackPacket | PublishPacket | PubackPacket | SubackPacket | PingrespPacket;
+/** A topic filter and the QoS to request for it. */
+export interface Subscription {
+    topic: string;
+    qos: 0 | 1;
+}
+/** A last-will message, published by the broker if we disappear. */
+export interface WillMessage {
+    topic: string;
+    payload: string;
+    qos: 0 | 1;
+    retain: boolean;
+}
+/** Everything CONNECT carries. */
+export interface ConnectOptions {
+    clientId: string;
+    keepaliveSec: number;
+    cleanSession: boolean;
+    username?: string;
+    password?: string;
+    will?: WillMessage;
+}
+/** Human-readable text for a CONNACK return code. */
+export declare function describeConnackReturnCode(code: number): string;
+/** True when a SUBACK return code means the subscription was refused (§3.9.3). */
+export declare function isSubscribeFailure(code: number): boolean;
+/**
+ * Encode the remaining-length field (§2.2.3).
+ *
+ * A base-128 varint, little-endian, with the top bit as the continuation flag
+ * and a hard limit of four bytes.
+ */
+export declare function encodeRemainingLength(length: number): number[];
+/**
+ * Build a CONNECT packet (§3.1).
+ *
+ * AWS IoT authenticates from the SigV4 signature on the WebSocket URL, so the
+ * username and password fields are not credentials here. The username is
+ * optional. The verified US endpoint accepts a CONNECT without one, so this
+ * plugin omits it rather than inventing an SDK marker we have not recorded.
+ */
+export declare function encodeConnect(options: ConnectOptions): Uint8Array;
+/**
+ * Build a PUBLISH packet (§3.3).
+ *
+ * `packetId` is required for QoS 1 and forbidden for QoS 0, which the
+ * specification states and this enforces: a QoS 1 publish with no identifier
+ * cannot be acknowledged, so the caller would wait for a PUBACK that can never
+ * be matched.
+ */
+export declare function encodePublish(input: {
+    topic: string;
+    payload: string;
+    qos: 0 | 1;
+    packetId?: number;
+    retain?: boolean;
+}): Uint8Array;
+/** Build a PUBACK, acknowledging a QoS 1 message the broker sent us (§3.4). */
+export declare function encodePuback(packetId: number): Uint8Array;
+/**
+ * Build a SUBSCRIBE packet (§3.8).
+ *
+ * The fixed-header flags are required to be `0b0010`; a broker must treat
+ * anything else as a protocol violation and close the connection.
+ */
+export declare function encodeSubscribe(packetId: number, subscriptions: readonly Subscription[]): Uint8Array;
+/** Build a PINGREQ (§3.12). */
+export declare function encodePingreq(): Uint8Array;
+/** Build a DISCONNECT (§3.14), which tells the broker not to send our will. */
+export declare function encodeDisconnect(): Uint8Array;
+/**
+ * Reassembles packets from a byte stream.
+ *
+ * Needed because MQTT framing and WebSocket framing are unrelated. One
+ * WebSocket message can carry several MQTT packets, one MQTT packet can be
+ * split across several WebSocket messages, and a split can fall inside the
+ * length field itself. A decoder that assumed one frame is one packet works
+ * perfectly on a quiet connection and corrupts under load, which is the worst
+ * possible failure schedule.
+ */
+export declare class PacketDecoder {
+    private buffer;
+    /**
+     * Add received bytes and return every complete packet now available.
+     *
+     * Throws {@link ProtocolError} on a malformed stream. The caller is expected
+     * to treat that as fatal for the connection: once framing is lost there is no
+     * way to resynchronise, because MQTT has no frame delimiter to scan for.
+     */
+    push(chunk: Uint8Array): DecodedPacket[];
+    /** Bytes held pending the rest of a packet. Exposed for tests and diagnostics. */
+    get pending(): number;
+}