@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/hue/hue.classes.client.ts

@@ -1,29 +1,259 @@
-import type { IHueConfig, IHueLightStatePatch, IHueResourceResponse } from './hue.types.js';
+import * as plugins from '../../plugins.js';
+import type { IHueConfig, IHueEvent, IHueLightStatePatch, IHueResourceResponse } from './hue.types.js';
+import { hueContentType, hueUuid, normalizeHueConfig, parseHueEnvelope, parseHueEvents, parseHueResources, validateHuePatch } from './hue.validation.js';
+
+interface IHueConnection {
+  cancel(): void;
+  closed: Promise<void>;
+}
+
+class HueEventDecoder {
+  readonly #decoder = new TextDecoder('utf-8', { fatal: true });
+  #buffer = '';
+  #data: string[] = [];
+  #frameBytes = 0;
+  #skipLf = false;
+
+  public feed(chunkArg: Buffer): IHueEvent[] {
+    this.#buffer += this.#decoder.decode(chunkArg, { stream: true });
+    const events: IHueEvent[] = [];
+    while (this.#buffer.length) {
+      if (this.#skipLf) {
+        if (this.#buffer.startsWith('\n')) this.#buffer = this.#buffer.slice(1);
+        this.#skipLf = false;
+      }
+      const separator = this.#buffer.search(/[\r\n]/);
+      if (separator === -1) break;
+      const line = this.#buffer.slice(0, separator);
+      this.#skipLf = this.#buffer[separator] === '\r';
+      this.#buffer = this.#buffer.slice(separator + 1);
+      this.#frameBytes += Buffer.byteLength(line);
+      this.assertBounded();
+      if (line === '') {
+        if (this.#data.length) events.push(...parseHueEvents(JSON.parse(this.#data.join('\n')) as unknown));
+        this.#data = [];
+        this.#frameBytes = 0;
+      } else if (line.startsWith('data:')) this.#data.push(line.slice(5).replace(/^ /, ''));
+    }
+    this.assertBounded();
+    return events;
+  }
+
+  private assertBounded(): void {
+    if (this.#frameBytes + Buffer.byteLength(this.#buffer) > 1_048_576) throw new Error('Hue event stream frame exceeds its size limit.');
+  }
+}
 
 export class HueClient {
-  constructor(private readonly config: IHueConfig) {}
-
-  public async getResources(): Promise<IHueResourceResponse> {
-    return this.config.resources ?? {
-      bridge: {
-        id: this.config.bridgeId,
-        productData: {
-          manufacturerName: 'Signify',
-          productName: 'Philips Hue Bridge',
-        },
-        metadata: {
-          name: 'Hue Bridge',
-        },
-      },
-      devices: [],
-      lights: [],
+  readonly #config: ReturnType<typeof normalizeHueConfig>;
+  readonly #agent: plugins.https.Agent;
+  readonly #lifetime = new AbortController();
+  readonly #connections = new Set<IHueConnection>();
+  #destroyPromise?: Promise<void>;
+  #streamCount = 0;
+  #healthy = false;
+  #eventFailure = false;
+
+  constructor(configArg: IHueConfig, private readonly setupSignal?: AbortSignal) {
+    this.#config = normalizeHueConfig(configArg);
+    this.#agent = new plugins.https.Agent({ keepAlive: false, maxSockets: 3, maxTotalSockets: 3 });
+    if (setupSignal?.aborted) this.#lifetime.abort();
+    else setupSignal?.addEventListener('abort', this.abortSetup, { once: true });
+  }
+
+  public isHealthy(): boolean {
+    return !this.#lifetime.signal.aborted && this.#healthy && !this.#eventFailure;
+  }
+
+  public async getResources(abortSignalArg?: AbortSignal): Promise<IHueResourceResponse> {
+    try {
+      const data = parseHueEnvelope(await this.request('GET', '/clip/v2/resource', undefined, abortSignalArg));
+      const resources = parseHueResources(data, this.#config.bridgeId);
+      this.#healthy = true;
+      return resources;
+    } catch (error) { this.#healthy = false; throw error; }
+  }
+
+  public async setLightState(lightIdArg: string, stateArg: IHueLightStatePatch, abortSignalArg?: AbortSignal): Promise<void> {
+    if (!hueUuid(lightIdArg)) throw new Error('Hue light target must be a resource UUID.');
+    validateHuePatch(stateArg);
+    const lightId = lightIdArg.toLowerCase();
+    const state = { ...stateArg };
+    const snapshot = await this.getResources(abortSignalArg);
+    const light = snapshot.lights.find((lightArg) => lightArg.id === lightId);
+    if (!light || !light.available) throw new Error('Hue light target is unknown or unavailable.');
+    if (state.brightness !== undefined && !light.dimming) throw new Error('Hue light does not support brightness.');
+    const body = { ...(state.on === undefined ? {} : { on: { on: state.on } }),
+      ...(state.brightness === undefined ? {} : { dimming: { brightness: state.brightness } }) };
+    const data = parseHueEnvelope(await this.request('PUT', `/clip/v2/resource/light/${lightId}`, body, abortSignalArg));
+    if (data.length !== 1) throw new Error('Hue write acknowledgement does not identify the target light.');
+    const acknowledgement = data[0];
+    if (!acknowledgement || typeof acknowledgement !== 'object' || Array.isArray(acknowledgement)
+      || !('rid' in acknowledgement) || typeof acknowledgement.rid !== 'string' || acknowledgement.rid.toLowerCase() !== lightId
+      || !('rtype' in acknowledgement) || acknowledgement.rtype !== 'light') {
+      throw new Error('Hue write acknowledgement does not identify the target light.');
+    }
+  }
+
+  public async subscribeToEvents(handlerArg: (eventArg: IHueEvent) => void,
+    onErrorArg: (errorArg: Error) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.assertOpen(abortSignalArg);
+    if (this.#streamCount >= 2) throw new Error('Hue event subscription limit reached.');
+    this.#streamCount++;
+    let resolveClosed: () => void = () => {};
+    const closed = new Promise<void>((resolveArg) => { resolveClosed = resolveArg; });
+    const abort = new AbortController();
+    const signal = AbortSignal.any([this.#lifetime.signal, abort.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+    let active = true;
+    signal.addEventListener('abort', () => { active = false; }, { once: true });
+    let established = false;
+    let request: ReturnType<typeof plugins.https.request> | undefined;
+    const connection: IHueConnection = { closed, cancel: () => { active = false; abort.abort(); request?.destroy(); } };
+    this.#connections.add(connection);
+    const decoder = new HueEventDecoder();
+    let failureReported = false;
+    const fail = (errorArg: Error) => {
+      if (!active || failureReported) return;
+      failureReported = true;
+      this.#eventFailure = true;
+      active = false;
+      abort.abort();
+      request?.destroy();
+      if (established) onErrorArg(errorArg);
     };
+    const ready = new Promise<void>((resolveArg, rejectArg) => {
+      const deadline = setTimeout(() => {
+        fail(new Error('Hue event stream connection timed out.'));
+        rejectArg(new Error('Hue event stream connection timed out.'));
+      }, this.#config.requestTimeoutMs);
+      const settleFailure = (errorArg: Error) => {
+        clearTimeout(deadline);
+        if (!established) rejectArg(errorArg);
+        fail(errorArg);
+      };
+      request = plugins.https.request(this.requestOptions('GET', '/eventstream/clip/v2', signal, {
+        accept: 'text/event-stream', 'cache-control': 'no-cache',
+      }), (responseArg) => {
+        if (responseArg.statusCode !== 200 || !hueContentType(responseArg.headers['content-type'], 'text/event-stream')) {
+          responseArg.destroy();
+          settleFailure(new Error('Hue event stream rejected or returned an invalid content type.'));
+          return;
+        }
+        clearTimeout(deadline);
+        established = true;
+        this.#eventFailure = false;
+        resolveArg();
+        responseArg.on('data', (chunkArg: Buffer) => {
+          if (!active) return;
+          try {
+            for (const event of decoder.feed(chunkArg)) {
+              if (active) handlerArg(event);
+            }
+          } catch {
+            settleFailure(new Error('Hue event stream contains invalid or oversized data.'));
+          }
+        });
+        responseArg.once('error', () => settleFailure(new Error('Hue event stream transport failed.')));
+        responseArg.once('end', () => settleFailure(new Error('Hue event stream ended.')));
+        responseArg.once('aborted', () => settleFailure(new Error('Hue event stream was interrupted.')));
+      });
+      request.once('error', () => settleFailure(new Error('Hue event stream transport failed.')));
+      request.once('close', () => {
+        clearTimeout(deadline);
+        this.#connections.delete(connection);
+        this.#streamCount--;
+        resolveClosed();
+        if (!established) rejectArg(new Error('Hue event subscription was cancelled.'));
+      });
+      request.end();
+    });
+    try {
+      await ready;
+    } catch (error) {
+      connection.cancel();
+      if (!request) { this.#connections.delete(connection); this.#streamCount--; resolveClosed(); }
+      await closed;
+      throw error;
+    }
+    return async () => { connection.cancel(); await closed; };
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#destroyPromise) return this.#destroyPromise;
+    this.setupSignal?.removeEventListener('abort', this.abortSetup);
+    this.#lifetime.abort();
+    this.#destroyPromise = this.drain();
+    return this.#destroyPromise;
   }
 
-  public async setLightState(lightIdArg: string, stateArg: IHueLightStatePatch): Promise<void> {
-    void lightIdArg;
-    void stateArg;
+  private readonly abortSetup = (): void => { void this.destroy(); };
+
+  private async drain(): Promise<void> {
+    const connections = [...this.#connections];
+    for (const connection of connections) connection.cancel();
+    this.#agent.destroy();
+    await Promise.all(connections.map((connectionArg) => connectionArg.closed));
+  }
+
+  private assertOpen(abortSignalArg?: AbortSignal): void {
+    if (this.#lifetime.signal.aborted || abortSignalArg?.aborted) throw new Error('Hue client operation was cancelled or the client is closed.');
+    if (this.#connections.size >= 32) throw new Error('Hue concurrent request limit reached.');
   }
 
-  public async destroy(): Promise<void> {}
+  private requestOptions(methodArg: string, pathArg: string, signalArg: AbortSignal, headersArg: Record<string, string> = {}): plugins.https.RequestOptions {
+    return { hostname: this.#config.host, port: this.#config.port, path: pathArg, method: methodArg,
+      servername: this.#config.bridgeId, ca: this.#config.trustedCa, rejectUnauthorized: true,
+      checkServerIdentity: (_hostnameArg, certificateArg) => plugins.tls.checkServerIdentity(this.#config.bridgeId, certificateArg),
+      signal: signalArg, agent: this.#agent,
+      headers: { 'hue-application-key': this.#config.appKey, accept: 'application/json', ...headersArg } };
+  }
+
+  private async request(methodArg: string, pathArg: string, bodyArg?: unknown, abortSignalArg?: AbortSignal): Promise<unknown> {
+    this.assertOpen(abortSignalArg);
+    const abort = new AbortController();
+    const signal = AbortSignal.any([this.#lifetime.signal, abort.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+    const encoded = bodyArg === undefined ? undefined : JSON.stringify(bodyArg);
+    let request: ReturnType<typeof plugins.https.request> | undefined;
+    let resolveClosed: () => void = () => {};
+    const closed = new Promise<void>((resolveArg) => { resolveClosed = resolveArg; });
+    const connection: IHueConnection = { closed, cancel: () => { abort.abort(); request?.destroy(); } };
+    this.#connections.add(connection);
+    const deadline = setTimeout(() => { abort.abort(); request?.destroy(); }, this.#config.requestTimeoutMs);
+    try {
+      return await new Promise<unknown>((resolveArg, rejectArg) => {
+        request = plugins.https.request(this.requestOptions(methodArg, pathArg, signal, encoded === undefined ? {} : {
+          'content-type': 'application/json', 'content-length': String(Buffer.byteLength(encoded)),
+        }), (responseArg) => {
+          if (responseArg.statusCode !== 200 || !hueContentType(responseArg.headers['content-type'], 'application/json')) {
+            responseArg.destroy();
+            rejectArg(new Error(`Hue API request failed with HTTP status ${responseArg.statusCode ?? 0}.`));
+            return;
+          }
+          const chunks: Buffer[] = [];
+          let received = 0;
+          responseArg.on('data', (chunkArg: Buffer) => {
+            received += chunkArg.length;
+            if (received > 4_194_304) {
+              responseArg.destroy();
+              rejectArg(new Error('Hue API response exceeds its size limit.'));
+            } else chunks.push(chunkArg);
+          });
+          responseArg.once('end', () => {
+            try { resolveArg(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))) as unknown); }
+            catch { rejectArg(new Error('Hue API returned invalid JSON.')); }
+          });
+          responseArg.once('aborted', () => rejectArg(new Error('Hue API response was interrupted.')));
+          responseArg.once('error', () => rejectArg(new Error('Hue API response transport failed.')));
+        });
+        request.once('error', () => rejectArg(new Error('Hue HTTPS request failed or was cancelled.')));
+        request.once('close', () => { this.#connections.delete(connection); resolveClosed(); });
+        request.end(encoded);
+      });
+    } finally {
+      clearTimeout(deadline);
+      connection.cancel();
+      if (!request) { this.#connections.delete(connection); resolveClosed(); }
+      await closed;
+    }
+  }
 }

package/ts/integrations/hue/hue.classes.configflow.ts

@@ -1,26 +1,39 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { HueClient } from './hue.classes.client.js';
+import { hueBridgeId, normalizeHueConfig, normalizeHueHost } from './hue.validation.js';
 import type { IHueConfig } from './hue.types.js';
 
 export class HueConfigFlow implements IConfigFlow<IHueConfig> {
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IHueConfig>> {
     void contextArg;
+    const bridgeId = hueBridgeId(candidateArg.id) ? candidateArg.id : undefined;
+    let host: string | undefined;
+    try { host = normalizeHueHost(candidateArg.host); } catch { host = undefined; }
     return {
-      kind: 'form',
-      title: 'Connect Philips Hue Bridge',
-      description: 'Press the bridge button, then provide the generated app key or paste an existing key.',
+      kind: 'form', title: 'Connect Philips Hue Bridge',
+      description: 'Provide a bridge application key created with the physical link button. For Hue private-CA certificates, provide the trusted Hue CA from the developer portal. Setup verifies the TLS identity and live bridge resources.',
       fields: [
+        ...(!bridgeId ? [{ name: 'bridgeId', label: 'Hue bridge ID', type: 'text' as const, required: true }] : []),
+        ...(!host ? [{ name: 'host', label: 'Bridge hostname or IP address', type: 'text' as const, required: true }] : []),
         { name: 'appKey', label: 'Hue app key', type: 'password', required: true },
+        { name: 'trustedCa', label: 'Trusted Hue CA certificate (PEM)', type: 'text' },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'Hue bridge configured',
-        config: {
-          bridgeId: candidateArg.id || 'unknown-hue-bridge',
-          host: candidateArg.host || 'localhost',
-          port: candidateArg.port || 443,
-          appKey: String(valuesArg.appKey || ''),
-        },
-      }),
+      submit: async (valuesArg) => {
+        let client: HueClient | undefined;
+        try {
+          const config = normalizeHueConfig({ bridgeId: bridgeId ?? valuesArg.bridgeId as string,
+            host: host ?? valuesArg.host as string, port: candidateArg.port ?? 443,
+            appKey: valuesArg.appKey as string, trustedCa: valuesArg.trustedCa === '' ? undefined : valuesArg.trustedCa as string | undefined });
+          client = new HueClient(config);
+          await client.getResources();
+          return { kind: 'done', title: 'Hue bridge verified', config };
+        } catch {
+          return { kind: 'error', title: 'Hue bridge could not be verified',
+            error: 'Check the bridge ID, HTTPS endpoint, trusted CA and application key. The bridge must support Hue API v2.' };
+        } finally {
+          await client?.destroy();
+        }
+      },
     };
   }
 }

package/ts/integrations/hue/hue.classes.integration.ts

@@ -1,11 +1,12 @@
 import type * as shxInterfaces from '@smarthome.exchange/interfaces';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { HueClient } from './hue.classes.client.js';
 import { HueConfigFlow } from './hue.classes.configflow.js';
 import { createHueDiscoveryDescriptor } from './hue.discovery.js';
 import { HueMapper } from './hue.mapper.js';
-import type { IHueConfig } from './hue.types.js';
+import { hueRecord } from './hue.validation.js';
+import type { IHueConfig, IHueLightStatePatch, IHueResourceResponse } from './hue.types.js';
 
 export class HueIntegration extends BaseIntegration<IHueConfig> {
   public readonly domain = 'hue';
@@ -13,57 +14,102 @@ export class HueIntegration extends BaseIntegration<IHueConfig> {
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createHueDiscoveryDescriptor();
   public readonly configFlow = new HueConfigFlow();
+  readonly #runtimes = new Set<HueIntegrationRuntime>();
+  #closed = false;
 
   public async setup(configArg: IHueConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    const client = new HueClient(configArg);
-    return new HueIntegrationRuntime(client);
+    if (this.#closed) throw new Error('Hue integration is closed.');
+    const client = new HueClient(configArg, contextArg.abortSignal);
+    const runtime = new HueIntegrationRuntime(client, () => this.#runtimes.delete(runtime));
+    this.#runtimes.add(runtime);
+    try {
+      await client.getResources();
+      if (this.#closed || contextArg.abortSignal?.aborted) throw new Error('Hue setup was cancelled.');
+      return runtime;
+    } catch (error) {
+      await runtime.destroy();
+      throw error;
+    }
   }
 
-  public async destroy(): Promise<void> {}
+  public async destroy(): Promise<void> {
+    this.#closed = true;
+    await Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()));
+  }
 }
 
 class HueIntegrationRuntime implements IIntegrationRuntime {
-  public domain = 'hue';
+  public readonly domain = 'hue';
 
-  constructor(private readonly client: HueClient) {}
+  constructor(private readonly client: HueClient, private readonly released: () => void) {}
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return HueMapper.toDevices(await this.client.getResources());
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+
+  public async devices(abortSignalArg?: AbortSignal): Promise<shxInterfaces.data.IDeviceDefinition[]> {
+    return HueMapper.toDevices(await this.client.getResources(abortSignalArg));
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
     return HueMapper.toEntities(await this.client.getResources());
   }
 
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain !== 'light') {
-      return { success: false, error: `Unsupported Hue service domain: ${requestArg.domain}` };
-    }
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    return this.client.subscribeToEvents((eventArg) => handlerArg(HueMapper.toIntegrationEvent(eventArg)),
+      (errorArg) => handlerArg({ type: 'error', integrationDomain: 'hue', data: { message: errorArg.message }, timestamp: Date.now() }), abortSignalArg);
+  }
 
-    const entityId = requestArg.target.entityId;
-    if (!entityId) {
-      return { success: false, error: 'Hue light service calls require target.entityId.' };
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    if (requestArg.domain !== 'light' || !['turn_on', 'turn_off', 'set_percentage'].includes(requestArg.service)) {
+      return { success: false, error: 'Hue supports only light turn_on, turn_off and set_percentage.' };
     }
-
-    const lightId = entityId.replace(/^light\./, '');
-    if (requestArg.service === 'turn_on') {
-      await this.client.setLightState(lightId, {
-        on: true,
-        brightness: typeof requestArg.data?.brightness === 'number' ? requestArg.data.brightness : undefined,
-      });
-      return { success: true };
+    const target = hueRecord(requestArg.target);
+    if (Reflect.ownKeys(target).some((keyArg) => keyArg !== 'entityId' && keyArg !== 'deviceId')) {
+      return { success: false, error: 'Hue service target contains unsupported fields.' };
     }
-
-    if (requestArg.service === 'turn_off') {
-      await this.client.setLightState(lightId, { on: false });
-      return { success: true };
+    const data = requestArg.data === undefined ? {} : hueRecord(requestArg.data);
+    const allowedKey = requestArg.service === 'set_percentage' ? 'percentage' : requestArg.service === 'turn_on' ? 'brightness' : undefined;
+    if (Reflect.ownKeys(data).some((keyArg) => keyArg !== allowedKey)) return { success: false, error: 'Hue service data contains unsupported fields.' };
+    const state: IHueLightStatePatch = { on: requestArg.service !== 'turn_off' };
+    if (requestArg.service === 'set_percentage' || data.brightness !== undefined) {
+      const brightness = data[requestArg.service === 'set_percentage' ? 'percentage' : 'brightness'];
+      if (typeof brightness !== 'number' || !Number.isFinite(brightness) || brightness < 0 || brightness > 100) {
+        return { success: false, error: 'Hue brightness must be between 0 and 100 percent.' };
+      }
+      state.brightness = brightness;
+      if (requestArg.service === 'set_percentage') state.on = brightness > 0;
     }
+    const snapshot = await this.client.getResources();
+    const lightId = this.resolveLight(snapshot, target.entityId, target.deviceId);
+    if (!lightId) return { success: false, error: 'Hue service requires one known, unambiguous light target.' };
+    await this.client.setLightState(lightId, state);
+    return { success: true };
+  }
 
-    return { success: false, error: `Unsupported Hue light service: ${requestArg.service}` };
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    const snapshot = await this.client.getResources(abortSignalArg);
+    const device = HueMapper.toDevices(snapshot).find((deviceArg) => deviceArg.id === requestArg.device.id);
+    const feature = device?.features.find((featureArg) => featureArg.id === requestArg.feature.id && featureArg.writable);
+    const lightId = this.resolveLight(snapshot, undefined, device?.id);
+    if (!device || !device.online || !feature || !lightId) return { success: false, error: 'Hue feature target is unknown, unavailable or not writable.' };
+    let state: IHueLightStatePatch;
+    if (feature.id === 'on' && typeof requestArg.value === 'boolean') state = { on: requestArg.value };
+    else if (feature.id === 'brightness' && typeof requestArg.value === 'number') state = { brightness: requestArg.value };
+    else return { success: false, error: 'Hue feature value has an invalid type.' };
+    await this.client.setLightState(lightId, state, abortSignalArg);
+    return { success: true };
   }
 
   public async destroy(): Promise<void> {
     await this.client.destroy();
+    this.released();
+  }
+
+  private resolveLight(snapshotArg: IHueResourceResponse, entityIdArg: unknown, deviceIdArg: unknown): string | undefined {
+    if (entityIdArg === undefined && deviceIdArg === undefined) return undefined;
+    const entity = entityIdArg === undefined ? undefined : HueMapper.toEntities(snapshotArg).find((entityArg) => entityArg.id === entityIdArg);
+    const device = deviceIdArg === undefined ? undefined : snapshotArg.lights.find((lightArg) => `hue.light.${lightArg.id}` === deviceIdArg);
+    if (entityIdArg !== undefined && !entity || deviceIdArg !== undefined && !device) return undefined;
+    if (entity && device && entity.deviceId !== `hue.light.${device.id}`) return undefined;
+    return device?.id || (entity ? snapshotArg.lights.find((lightArg) => entity.deviceId === `hue.light.${lightArg.id}`)?.id : undefined);
   }
 }

package/ts/integrations/hue/hue.discovery.ts

@@ -1,3 +1,5 @@
+import * as plugins from '../../plugins.js';
+import { hueBridgeId, hueContentType, normalizeHueHost } from './hue.validation.js';
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type {
   IDiscoveryCandidate,
@@ -16,22 +18,48 @@ export class HueBrokerDiscoveryProbe implements IDiscoveryProbe {
   public description = 'Return Hue bridge candidates from the Hue discovery broker.';
 
   public async probe(contextArg: IDiscoveryContext): Promise<IDiscoveryProbeResult> {
-    if (contextArg.abortSignal?.aborted) {
-      return { candidates: [] };
+    if (contextArg.abortSignal?.aborted) return { candidates: [] };
+    const signal = AbortSignal.any([AbortSignal.timeout(5000), ...(contextArg.abortSignal ? [contextArg.abortSignal] : [])]);
+    const response = await fetch('https://discovery.meethue.com/', { signal, redirect: 'error', cache: 'no-store' });
+    if (!response.ok || !response.body || !hueContentType(response.headers.get('content-type'), 'application/json')) {
+      await response.body?.cancel();
+      throw new Error('Hue discovery broker returned an invalid response.');
     }
-    return {
-      candidates: [
-        {
-          source: 'broker',
-          integrationDomain: 'hue',
-          id: '001788fffe123456',
-          host: '192.168.1.42',
-          port: 443,
-          manufacturer: 'Signify',
-          model: 'Philips Hue Bridge',
-        },
-      ],
-    };
+    const reader = response.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let bytes = 0;
+    try {
+      while (true) {
+        const result = await reader.read();
+        if (result.done) break;
+        bytes += result.value.byteLength;
+        if (bytes > 262144) {
+          await reader.cancel();
+          throw new Error('Hue discovery broker response exceeds its size limit.');
+        }
+        chunks.push(result.value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    let payload: unknown;
+    try { payload = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))) as unknown; }
+    catch { throw new Error('Hue discovery broker returned invalid JSON.'); }
+    if (!Array.isArray(payload) || payload.length > 1024) throw new Error('Hue discovery broker returned invalid bridge metadata.');
+    const candidates: IDiscoveryCandidate[] = [];
+    const ids = new Set<string>();
+    for (const record of payload as unknown[]) {
+      if (!record || typeof record !== 'object' || Array.isArray(record) || !('id' in record) || !hueBridgeId(record.id)
+        || !('internalipaddress' in record) || typeof record.internalipaddress !== 'string' || !plugins.net.isIP(record.internalipaddress)) {
+        throw new Error('Hue discovery broker returned invalid bridge metadata.');
+      }
+      const id = record.id.toLowerCase();
+      if (ids.has(id)) throw new Error('Hue discovery broker returned duplicate bridge identities.');
+      ids.add(id);
+      candidates.push({ source: 'broker', integrationDomain: 'hue', id, host: record.internalipaddress, port: 443,
+        manufacturer: 'Signify', model: 'Philips Hue Bridge' });
+    }
+    return { candidates };
   }
 }
 
@@ -41,8 +69,9 @@ export class HueMdnsMatcher implements IDiscoveryMatcher<IHueMdnsRecord> {
   public description = 'Recognize Hue bridge mDNS records by bridgeid TXT data.';
 
   public async matches(recordArg: IHueMdnsRecord): Promise<IDiscoveryMatch> {
+    if (!recordArg || typeof recordArg !== 'object') return { matched: false, confidence: 'low', reason: 'Hue mDNS record is invalid.' };
     const bridgeId = recordArg.txt?.bridgeid;
-    if (!bridgeId) {
+    if (!hueBridgeId(bridgeId) || !recordArg.host) {
       return {
         matched: false,
         confidence: 'low',
@@ -50,19 +79,22 @@ export class HueMdnsMatcher implements IDiscoveryMatcher<IHueMdnsRecord> {
       };
     }
 
+    let host: string;
+    try { host = normalizeHueHost(recordArg.host); }
+    catch { return { matched: false, confidence: 'low', reason: 'Hue mDNS host is invalid.' }; }
     return {
       matched: true,
-      confidence: 'certain',
+      confidence: 'high',
       reason: 'mDNS record contains Hue bridge ID.',
-      normalizedDeviceId: bridgeId,
+      normalizedDeviceId: bridgeId.toLowerCase(),
       candidate: {
         source: 'mdns',
         integrationDomain: 'hue',
-        id: bridgeId,
-        host: recordArg.host,
-        port: recordArg.port,
+        id: bridgeId.toLowerCase(),
+        host,
+        port: 443,
         manufacturer: 'Signify',
-        model: recordArg.txt?.modelid,
+        model: typeof recordArg.txt?.modelid === 'string' && recordArg.txt.modelid.length <= 128 ? recordArg.txt.modelid : undefined,
       },
     };
   }
@@ -74,19 +106,22 @@ export class HueBridgeValidator implements IDiscoveryValidator {
 
   public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
     const isHue = candidateArg.integrationDomain === 'hue' || candidateArg.manufacturer === 'Signify';
-    if (!isHue || !candidateArg.host) {
+    if (!isHue || !candidateArg.host || !hueBridgeId(candidateArg.id)) {
       return {
         matched: false,
         confidence: 'low',
         reason: 'Candidate lacks Hue metadata or host information.',
       };
     }
+    try { normalizeHueHost(candidateArg.host); }
+    catch { return { matched: false, confidence: 'low', reason: 'Hue candidate host is invalid.' }; }
     return {
       matched: true,
-      confidence: candidateArg.id ? 'certain' : 'high',
+      confidence: 'high',
       reason: 'Candidate can be configured as a Hue bridge.',
-      candidate: candidateArg,
-      normalizedDeviceId: candidateArg.id,
+      candidate: { source: candidateArg.source, integrationDomain: 'hue', id: candidateArg.id.toLowerCase(),
+        host: normalizeHueHost(candidateArg.host), port: 443, manufacturer: 'Signify' },
+      normalizedDeviceId: candidateArg.id.toLowerCase(),
     };
   }
 }