homebridge-dyson-solarcycle-morph 0.1.0

package/dist/dyson/crypto.js

@@ -0,0 +1,98 @@
+/**
+ * Cryptography for the Dyson LTK re-authentication handshake.
+ *
+ * Despite what Dyson's own protocol notes claim, this is not AES-GCM: the app
+ * derives an AES-128 key from the long-term key via HKDF-SHA256 and then uses
+ * unpadded AES-CBC with a separate HMAC-SHA256 over the ciphertext
+ * (encrypt-then-MAC), with the same key serving both roles.
+ */
+import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+/** HKDF `info` string, matching `g20/b.d` in the MyDyson Android app. */
+const HKDF_INFO = Buffer.from('USER_AUTH_AES\x00\x00\x00', 'binary');
+/** Every encrypted block in this protocol is exactly one AES block. */
+const BLOCK = 16;
+/**
+ * Derive the 16-byte AES key from the long-term key.
+ *
+ * HKDF-SHA256 with an empty salt, truncated to the first expansion block.
+ */
+export function deriveAesKey(ltk) {
+    const prk = createHmac('sha256', Buffer.alloc(0)).update(ltk).digest();
+    const block1 = createHmac('sha256', prk)
+        .update(Buffer.concat([HKDF_INFO, Buffer.from([0x01])]))
+        .digest();
+    return block1.subarray(0, BLOCK);
+}
+/**
+ * Encrypt-then-MAC one or more AES blocks.
+ *
+ * @returns `IV(16) || ciphertext || HMAC-SHA256(ciphertext)(32)` — 64 bytes for
+ * the single-block plaintexts this protocol uses.
+ */
+export function sealBlock(key, plaintext, iv = randomBytes(BLOCK)) {
+    if (plaintext.length % BLOCK !== 0) {
+        throw new Error(`plaintext must be a multiple of ${BLOCK} bytes, got ${plaintext.length}`);
+    }
+    const cipher = createCipheriv('aes-128-cbc', key, iv);
+    cipher.setAutoPadding(false);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const mac = createHmac('sha256', key).update(ct).digest();
+    return Buffer.concat([iv, ct, mac]);
+}
+/** Unpadded AES-128-CBC decryption. */
+function openBlock(key, iv, ciphertext) {
+    const decipher = createDecipheriv('aes-128-cbc', key, iv);
+    decipher.setAutoPadding(false);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/**
+ * Build the 82-byte re-auth PayloadA (message type 0x06).
+ *
+ * Layout: `account GUID(16) || 0x00 0x00 || sealBlock(nonce)(64)`.
+ */
+export function buildReauthPayloadA(accountUuid, key, nonce = randomBytes(BLOCK)) {
+    return Buffer.concat([uuidToBytes(accountUuid), Buffer.from([0x00, 0x00]), sealBlock(key, nonce)]);
+}
+/**
+ * Build the 66-byte re-auth PayloadC (message type 0x08).
+ *
+ * Layout: `0x00 0x00 || sealBlock(challenge)(64)`.
+ */
+export function buildReauthPayloadC(key, challenge) {
+    return Buffer.concat([Buffer.from([0x00, 0x00]), sealBlock(key, challenge)]);
+}
+/**
+ * Recover the lamp's challenge from PayloadB (message type 0x07).
+ *
+ * Layout: `0x00 0x00 || IV(16) || ciphertext(32) || MAC(32)?`. The MAC is
+ * absent on some firmware; when present we verify it, since a mismatch is the
+ * earliest and clearest signal that the stored LTK is wrong.
+ *
+ * @param payload The reassembled PayloadB, type byte already stripped.
+ * @returns The 16-byte challenge to echo back in PayloadC.
+ */
+export function parseReauthPayloadB(key, payload) {
+    if (payload.length < 50) {
+        throw new Error(`PayloadB too short (${payload.length} bytes, need >= 50) — the lamp likely rejected the handshake`);
+    }
+    const iv = payload.subarray(2, 18);
+    const ct = payload.subarray(18, 50);
+    const mac = payload.subarray(50, 82);
+    if (mac.length === 32) {
+        const expected = createHmac('sha256', key).update(ct).digest();
+        if (!timingSafeEqual(mac, expected)) {
+            throw new Error('PayloadB failed HMAC verification — the stored LTK is wrong or corrupted');
+        }
+    }
+    // Plaintext is our echoed nonce followed by the lamp's own challenge.
+    return openBlock(key, iv, ct).subarray(BLOCK, 2 * BLOCK);
+}
+/** Dyson sends account GUIDs in big-endian (RFC 4122) byte order. */
+export function uuidToBytes(uuid) {
+    const hex = uuid.replace(/-/g, '');
+    if (!/^[0-9a-fA-F]{32}$/.test(hex)) {
+        throw new Error(`invalid account UUID: ${uuid}`);
+    }
+    return Buffer.from(hex, 'hex');
+}
+//# sourceMappingURL=crypto.js.map

package/dist/dyson/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/dyson/crypto.ts"],"names":[],"mappings":"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"}

package/dist/dyson/debounce.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Coalesces rapid updates so only the value a control settles on is acted on.
+ */
+export declare class Debouncer {
+    private readonly pending;
+    private readonly delayMs;
+    private readonly run;
+    /**
+     * @param delayMs How long a key must stay unchanged before its task runs.
+     * @param run Executes the winning task, typically through a serialising
+     * queue. The key is passed on so the queue can apply the same grouping.
+     */
+    constructor(delayMs: number, run: (task: () => Promise<void>, key: string) => Promise<unknown>);
+    /**
+     * Schedule `task` for `key`, replacing anything already waiting under it.
+     *
+     * A superseded call resolves immediately instead of waiting for the task that
+     * replaced it. Callers here are HomeKit characteristic handlers, which have a
+     * ten-second budget; holding every intermediate slider position open until the
+     * final write lands would spend that budget to report a value that is already
+     * stale. Callers update their own state optimistically, so nothing is lost.
+     */
+    schedule(key: string, task: () => Promise<void>): Promise<void>;
+    /**
+     * Whether a task is waiting under this key.
+     *
+     * Lets a running task notice that its own result is already obsolete, so it
+     * can stop rather than act on a value the caller has moved past.
+     */
+    isPending(key: string): boolean;
+    /** Drop everything waiting, resolving the callers. Nothing is executed. */
+    cancelAll(): void;
+}

package/dist/dyson/debounce.js

@@ -0,0 +1,59 @@
+/**
+ * Coalesces rapid updates so only the value a control settles on is acted on.
+ */
+export class Debouncer {
+    pending = new Map();
+    delayMs;
+    run;
+    /**
+     * @param delayMs How long a key must stay unchanged before its task runs.
+     * @param run Executes the winning task, typically through a serialising
+     * queue. The key is passed on so the queue can apply the same grouping.
+     */
+    constructor(delayMs, run) {
+        this.delayMs = delayMs;
+        this.run = run;
+    }
+    /**
+     * Schedule `task` for `key`, replacing anything already waiting under it.
+     *
+     * A superseded call resolves immediately instead of waiting for the task that
+     * replaced it. Callers here are HomeKit characteristic handlers, which have a
+     * ten-second budget; holding every intermediate slider position open until the
+     * final write lands would spend that budget to report a value that is already
+     * stale. Callers update their own state optimistically, so nothing is lost.
+     */
+    schedule(key, task) {
+        this.pending.get(key)?.supersede();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(key);
+                this.run(task, key).then(() => resolve(), reject);
+            }, this.delayMs);
+            this.pending.set(key, {
+                timer,
+                supersede: () => {
+                    clearTimeout(timer);
+                    this.pending.delete(key);
+                    resolve();
+                },
+            });
+        });
+    }
+    /**
+     * Whether a task is waiting under this key.
+     *
+     * Lets a running task notice that its own result is already obsolete, so it
+     * can stop rather than act on a value the caller has moved past.
+     */
+    isPending(key) {
+        return this.pending.has(key);
+    }
+    /** Drop everything waiting, resolving the callers. Nothing is executed. */
+    cancelAll() {
+        for (const { supersede } of [...this.pending.values()]) {
+            supersede();
+        }
+    }
+}
+//# sourceMappingURL=debounce.js.map

package/dist/dyson/debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.js","sourceRoot":"","sources":["../../src/dyson/debounce.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,SAAS;IACH,OAAO,GAAG,IAAI,GAAG,EAA4D,CAAC;IAE9E,OAAO,CAAS;IAChB,GAAG,CAA+D;IAEnF;;;;OAIG;IACH,YAAY,OAAe,EAAE,GAAiE;QAC5F,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAW,EAAE,IAAyB;QAC7C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,CAAC;QACnC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACzB,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;YACpD,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;gBACpB,KAAK;gBACL,SAAS,EAAE,GAAG,EAAE;oBACd,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACzB,OAAO,EAAE,CAAC;gBACZ,CAAC;aACF,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,2EAA2E;IAC3E,SAAS;QACP,KAAK,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YACvD,SAAS,EAAE,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/dyson/lamp.d.ts

@@ -0,0 +1,193 @@
+import { EventEmitter } from 'node:events';
+export interface LampState {
+    on: boolean;
+    /** HomeKit-style brightness, 0-100 %. */
+    brightness: number;
+    /** Colour temperature in Kelvin, 2700-6500. */
+    kelvin: number;
+}
+export interface LampOptions {
+    /** BLE MAC, e.g. `AA:BB:CC:DD:EE:FF`. */
+    mac: string;
+    /** Long-term key as a hex string, from {@link DysonCloud.fetchLtk}. */
+    ltk: string;
+    /** Dyson account GUID that the LTK was issued to. */
+    accountId: string;
+    /** Optional HCI adapter name, e.g. `hci0`. Defaults to the system default. */
+    adapter?: string;
+    log?: Logger;
+}
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+export declare interface DysonMorphLamp {
+    on(event: 'connected', listener: () => void): this;
+    on(event: 'disconnected', listener: () => void): this;
+    on(event: 'state', listener: (state: LampState) => void): this;
+    on(event: 'motion', listener: (detected: boolean) => void): this;
+}
+export declare class DysonMorphLamp extends EventEmitter {
+    private readonly mac;
+    private readonly aesKey;
+    private readonly accountId;
+    private readonly adapterName;
+    private readonly log;
+    private bluetooth?;
+    private adapter?;
+    private device?;
+    private chars;
+    /** Per-characteristic write mode, derived from the flags the lamp advertises. */
+    private writeTypes;
+    private readonly assembler;
+    private readonly waiters;
+    /** Serialises all GATT access. */
+    private readonly operations;
+    private readonly writes;
+    private readonly reconciles;
+    private readonly settling;
+    /** Whether the running scan is one we started and must clean up. */
+    private discoveryIsOurs;
+    /** So the "try power-cycling" hint is given once, not on every attempt. */
+    private hintedStuck;
+    private running;
+    private connected;
+    private reconnectAttempt;
+    private reconnectTimer?;
+    private manualModeSetAt;
+    private state;
+    /** What the user last asked for. Reconciliation aims at this, not at guesses. */
+    private desired;
+    constructor(options: LampOptions);
+    /** Last known state. Updated by notifications and polling. */
+    getState(): Readonly<LampState>;
+    isConnected(): boolean;
+    /** Begin connecting, and keep reconnecting until {@link stop} is called. */
+    start(): Promise<void>;
+    /** Disconnect and release the D-Bus connection. */
+    stop(): Promise<void>;
+    setPower(on: boolean): Promise<void>;
+    /** @param percent HomeKit brightness, 0-100 %. */
+    setBrightness(percent: number): Promise<void>;
+    setColorTemperature(kelvin: number): Promise<void>;
+    private writeUint16;
+    /**
+     * Check the lamp ended up where it was asked to, once commands stop arriving.
+     *
+     * Control writes are unacknowledged — the characteristics offer no `write`
+     * flag at all — so one can be dropped with nothing to say so. The lamp
+     * notifies on change, but a lost write changes nothing and therefore notifies
+     * nothing, which is exactly the case that leaves HomeKit showing a state the
+     * lamp is not in. Checking once at the end costs one read of each value
+     * instead of one per command, and none of it in the path the user waits on.
+     */
+    private scheduleReconcile;
+    /**
+     * Refuse a command there is no way to deliver.
+     *
+     * Holding it until the link returns sounds helpful and is not: the lamp is
+     * already reported as unreachable, so the user knows it did not happen, and
+     * replaying a handful of presses minutes later switches the lamp around on
+     * its own. Failing plainly leaves them in control.
+     */
+    private requireConnection;
+    private reconcile;
+    private connectLoop;
+    private connectOnce;
+    /**
+     * Connect, with a scan running, retrying briskly.
+     *
+     * Two things came out of measuring this. A scan has to be running and must
+     * stay running through the connect — stopping it first roughly halves the
+     * success rate. And no arrangement is reliable: the best managed two
+     * successes in three, so the answer is repetition rather than a cleverer
+     * sequence.
+     */
+    private connectDevice;
+    /**
+     * Stop the scan we started, now that it has served its purpose.
+     *
+     * Leaving it running makes the radio time-slice between scan windows and
+     * connection events for as long as the session lasts.
+     */
+    private stopOurDiscovery;
+    /**
+     * Ask BlueZ to hold on to this device.
+     *
+     * An untrusted, unbonded device is dropped from the cache once it is neither
+     * connected nor being discovered, and the address then stops resolving at all
+     * — `bluetoothctl` reports it as "not available". Trusting it keeps the
+     * record, so a reconnect does not have to rediscover the lamp first.
+     */
+    private markTrusted;
+    /**
+     * Locate the characteristics we need, wherever the firmware puts them.
+     *
+     * The published protocol notes place everything under one service, but the
+     * Solarcycle Morph spreads them across three (`2dd10010` for auth and RSSI,
+     * `2dd10020` for attribute writes, `2dd1fff0` for the control values). Rather
+     * than hard-coding a layout that varies by model, we sweep every service and
+     * match on characteristic UUID, which is unique regardless of its parent.
+     */
+    private discoverCharacteristics;
+    /** Write using whichever acknowledgement mode the characteristic supports. */
+    private write;
+    /**
+     * LTK re-authentication: prove we hold the key without contacting the cloud.
+     *
+     * We send an encrypted nonce, the lamp returns it alongside a challenge of
+     * its own, and we send that challenge back encrypted. Until the lamp answers
+     * with `CONNECTION_ESTABLISHED` it silently discards every control write.
+     */
+    private authenticate;
+    private handleAuthFragment;
+    private sendMessage;
+    private waitForMessage;
+    /**
+     * Take the lamp out of daylight mode so it accepts explicit values.
+     *
+     * Refreshed on a TTL rather than tracked as state: the lamp offers no way to
+     * read the current mode back, and the physical button can change it.
+     */
+    private ensureManualMode;
+    private refreshState;
+    /** Read what the lamp currently reports. Values it will not give up are absent. */
+    private readState;
+    /**
+     * Put the link quality in the log. A weak signal and a bug in the plugin
+     * produce the same symptom — repeated disconnects — and only the number
+     * distinguishes them.
+     */
+    private reportSignalStrength;
+    /**
+     * Follow the lamp's own state changes instead of polling for them.
+     *
+     * There is no need to poll to hold the link open — a BLE connection is
+     * maintained by the link layer, not by ATT traffic — and polling actively
+     * hurt: a periodic read would eventually come back `ATT error 0x0e` and take
+     * the connection down with it. Notifications also pick up changes made at the
+     * lamp itself, which polling only caught on its next tick.
+     */
+    private subscribeToState;
+    private handleDisconnect;
+    private teardown;
+    private characteristic;
+    /**
+     * Run `task` after every previously queued GATT operation has settled.
+     *
+     * @param key Marks the operation replaceable: queueing another under the same
+     * key drops this one. Used for value writes, where an older value is worthless
+     * once a newer one is waiting, and omitted for power so it always runs.
+     */
+    private enqueue;
+    /**
+     * Publish what the lamp reports, minus the echo of our own commands.
+     *
+     * A value the user just set must stay where they put it; the steps the lamp
+     * takes on its way there are not news, they are the command happening.
+     */
+    private publishFromLamp;
+    private patchState;
+}