@smarthome.exchange/integrations 2.0.0 → 4.0.0

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

@@ -1,51 +1,57 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import type * as plugins from '../../plugins.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.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 { hueRecord } from './hue.validation.js';
-import type { IHueConfig, IHueLightStatePatch, IHueResourceResponse } from './hue.types.js';
+import { captureHueOptions, hueRecord, normalizeHueConfig } from './hue.validation.js';
+import type { IHueConfig, IHueLightStatePatch, IHueResourceResponse, IHueIntegrationOptions } from './hue.types.js';
 
 export class HueIntegration extends BaseIntegration<IHueConfig> {
   public readonly domain = 'hue';
   public readonly displayName = 'Philips Hue';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createHueDiscoveryDescriptor();
-  public readonly configFlow = new HueConfigFlow();
-  readonly #runtimes = new Set<HueIntegrationRuntime>();
-  #closed = false;
+  public readonly configFlow: HueConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: Readonly<IHueIntegrationOptions>;
+
+  constructor(optionsArg: IHueIntegrationOptions = {}) {
+    super();
+    this.#options = captureHueOptions(optionsArg);
+    this.#owner = new NativeIntegrationOwner('hue', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.configFlow = new HueConfigFlow(this.#options, this.#owner);
+  }
 
   public async setup(configArg: IHueConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    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 {
+    const config = normalizeHueConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (lease) => {
+      const client = new HueClient(config, { ...lease.context, abortSignal: lease.signal }, this.#options, this.#owner);
+      let cleanupStarted = false;
+      lease.own(() => { if (cleanupStarted) return client.retryCleanup(); cleanupStarted = true; return client.destroy(); });
       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;
-    }
+      lease.assertOpen();
+      if (!client.isHealthy()) throw new Error('Hue setup cancelled.');
+      lease.promoteToRuntime();
+      return new HueIntegrationRuntime(client, lease);
+    });
   }
 
-  public async destroy(): Promise<void> {
-    this.#closed = true;
-    await Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()));
-  }
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
+
 }
 
 class HueIntegrationRuntime implements IIntegrationRuntime {
   public readonly domain = 'hue';
 
-  constructor(private readonly client: HueClient, private readonly released: () => void) {}
+  constructor(private readonly client: HueClient, private readonly lease: INativeSetupLease) {}
 
   public isHealthy(): boolean { return this.client.isHealthy(); }
 
-  public async devices(abortSignalArg?: AbortSignal): Promise<shxInterfaces.data.IDeviceDefinition[]> {
+  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
     return HueMapper.toDevices(await this.client.getResources(abortSignalArg));
   }
 
@@ -59,57 +65,72 @@ class HueIntegrationRuntime implements IIntegrationRuntime {
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain !== 'light' || !['turn_on', 'turn_off', 'set_percentage'].includes(requestArg.service)) {
+    const request = hueRecord(requestArg);
+    if (Reflect.ownKeys(request).some((keyArg) => !['domain', 'service', 'target', 'data'].includes(String(keyArg)))) return { success: false, error: 'Hue service contains unsupported fields.' };
+    if (request.domain !== 'light' || typeof request.service !== 'string' || !['turn_on', 'turn_off', 'set_percentage'].includes(request.service)) {
       return { success: false, error: 'Hue supports only light turn_on, turn_off and set_percentage.' };
     }
-    const target = hueRecord(requestArg.target);
+    const target = hueRecord(request.target);
     if (Reflect.ownKeys(target).some((keyArg) => keyArg !== 'entityId' && keyArg !== 'deviceId')) {
       return { success: false, error: 'Hue service target contains unsupported fields.' };
     }
-    const data = requestArg.data === undefined ? {} : hueRecord(requestArg.data);
-    const allowedKey = requestArg.service === 'set_percentage' ? 'percentage' : requestArg.service === 'turn_on' ? 'brightness' : undefined;
+    if (Object.values(target).some((valueArg) => typeof valueArg !== 'string' || !valueArg)) return { success: false, error: 'Hue service targets must be identifiers.' };
+    const data = request.data === undefined ? {} : hueRecord(request.data);
+    const allowedKey = request.service === 'set_percentage' ? 'percentage' : request.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'];
+    const state: IHueLightStatePatch = { on: request.service !== 'turn_off' };
+    if (request.service === 'set_percentage' || data.brightness !== undefined) {
+      const brightness = data[request.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;
+      if (request.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 this.client.execute(async (session) => {
+      const snapshot = await session.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 session.setLightState(lightId, state);
+      return { success: true };
+    });
   }
 
   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 };
+    const request = hueRecord(requestArg);
+    if (Reflect.ownKeys(request).some((keyArg) => !['device', 'feature', 'value'].includes(String(keyArg)))) return { success: false, error: 'Hue feature request contains unsupported fields.' };
+    const selectedDevice = hueRecord(request.device);
+    const selectedFeature = hueRecord(request.feature);
+    const deviceId = selectedDevice.id;
+    const featureId = selectedFeature.id;
+    const capability = selectedFeature.capability;
+    const value = request.value;
+    if (selectedDevice.integrationDomain !== this.domain || typeof deviceId !== 'string' || typeof featureId !== 'string') {
+      return { success: false, error: 'Hue feature requires one exact Hue device and feature.' };
+    }
+    return this.client.execute(async (session) => {
+      const snapshot = await session.getResources(abortSignalArg);
+      const device = HueMapper.toDevices(snapshot).find((deviceArg) => deviceArg.id === deviceId);
+      const feature = device?.features.find((featureArg) => featureArg.id === featureId && featureArg.capability === capability && 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 value === 'boolean') state = { on: value };
+      else if (feature.id === 'brightness' && typeof value === 'number') state = { brightness: value };
+      else return { success: false, error: 'Hue feature value has an invalid type.' };
+      await session.setLightState(lightId, state, abortSignalArg);
+      return { success: true };
+    }, abortSignalArg);
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
-    this.released();
-  }
+  public destroy(): Promise<void> { return this.lease.close(); }
 
   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);
+    const device = deviceIdArg === undefined ? undefined : snapshotArg.lights.find((lightArg) => HueMapper.lightDeviceId(snapshotArg.homeId, 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);
+    if (entity && device && entity.deviceId !== HueMapper.lightDeviceId(snapshotArg.homeId, device.id)) return undefined;
+    return device?.id || (entity ? snapshotArg.lights.find((lightArg) => entity.deviceId === HueMapper.lightDeviceId(snapshotArg.homeId, lightArg.id))?.id : undefined);
   }
 }

package/ts/integrations/hue/hue.mapper.ts

@@ -3,10 +3,13 @@ import type { IIntegrationEntity, IIntegrationEvent } from '../../core/types.js'
 import type { IHueEvent, IHueResourceResponse } from './hue.types.js';
 
 export class HueMapper {
+  public static lightDeviceId(homeIdArg: string, lightIdArg: string): string { return `hue.light.${encodeURIComponent(homeIdArg)}.${lightIdArg}`; }
+  public static lightEntityId(homeIdArg: string, lightIdArg: string): string { return `light.hue.${encodeURIComponent(homeIdArg)}.${lightIdArg}`; }
+
   public static toDevices(resourcesArg: IHueResourceResponse): plugins.shxInterfaces.data.IDeviceDefinition[] {
     const timestamp = new Date().toISOString();
     const devices: plugins.shxInterfaces.data.IDeviceDefinition[] = [{
-      id: `hue.bridge.${resourcesArg.bridge.id}`,
+      id: `hue.bridge.${encodeURIComponent(resourcesArg.homeId)}.${resourcesArg.bridge.id}`,
       integrationDomain: 'hue', name: resourcesArg.bridge.metadata?.name || 'Hue Bridge', protocol: 'hue',
       manufacturer: resourcesArg.bridge.productData?.manufacturerName,
       model: resourcesArg.bridge.productData?.productName || resourcesArg.bridge.productData?.modelId,
@@ -17,7 +20,7 @@ export class HueMapper {
     for (const light of resourcesArg.lights) {
       const owner = resourcesArg.devices.find((deviceArg) => deviceArg.id === light.owner.rid);
       devices.push({
-        id: `hue.light.${light.id}`, integrationDomain: 'hue',
+        id: HueMapper.lightDeviceId(resourcesArg.homeId, light.id), integrationDomain: 'hue',
         name: light.metadata?.name || owner?.metadata?.name || `Hue Light ${light.id}`, protocol: 'hue',
         manufacturer: owner?.productData?.manufacturerName,
         model: owner?.productData?.productName || owner?.productData?.modelId,
@@ -26,7 +29,7 @@ export class HueMapper {
           ...(light.dimming ? [{ id: 'brightness', capability: 'light' as const, name: 'Brightness', readable: true, writable: true, unit: '%' }] : [])],
         state: [{ featureId: 'on', value: light.on.on, updatedAt: timestamp },
           ...(light.dimming ? [{ featureId: 'brightness', value: light.dimming.brightness, updatedAt: timestamp }] : [])],
-        metadata: { hueOwnerRid: light.owner.rid },
+        metadata: { homeId: resourcesArg.homeId, hueOwnerRid: light.owner.rid },
       });
     }
     return devices;
@@ -34,8 +37,8 @@ export class HueMapper {
 
   public static toEntities(resourcesArg: IHueResourceResponse): IIntegrationEntity[] {
     return resourcesArg.lights.map((lightArg) => ({
-      id: `light.${lightArg.id}`, uniqueId: `hue_light_${lightArg.id}`, integrationDomain: 'hue',
-      deviceId: `hue.light.${lightArg.id}`, platform: 'light',
+      id: HueMapper.lightEntityId(resourcesArg.homeId, lightArg.id), uniqueId: `hue_light_${encodeURIComponent(resourcesArg.homeId)}_${lightArg.id}`, integrationDomain: 'hue',
+      deviceId: HueMapper.lightDeviceId(resourcesArg.homeId, lightArg.id), platform: 'light',
       name: lightArg.metadata?.name || resourcesArg.devices.find((deviceArg) => deviceArg.id === lightArg.owner.rid)?.metadata?.name || `Hue Light ${lightArg.id}`,
       state: lightArg.on.on ? 'on' : 'off',
       attributes: lightArg.dimming ? { brightness: lightArg.dimming.brightness } : {}, available: lightArg.available,

package/ts/integrations/hue/hue.types.ts

@@ -1,13 +1,48 @@
+import type * as plugins from '../../plugins.js';
+import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
+
 export interface IHueConfig {
+  homeId: string;
   bridgeId: string;
   host: string;
-  appKey: string;
+  credentialReference: string;
   port?: number;
   /** PEM CA supplied by the operator from a trusted source. */
   trustedCa?: string;
   requestTimeoutMs?: number;
 }
 
+export interface IHueCredentialRequest {
+  readonly homeId: string;
+  readonly origin: string;
+  readonly bridgeId: string;
+  readonly credentialReference: string;
+  readonly signal: AbortSignal;
+  /** Monotonic deadline shared by provider work and HTTPS dispatch. */
+  readonly deadline: number;
+}
+
+export interface IHueCredentialProvider {
+  resolve(requestArg: IHueCredentialRequest): Promise<string>;
+  /** Creates a reference without replacing an existing credential. */
+  create?(requestArg: IHueCredentialRequest, appKeyArg: string): Promise<void>;
+}
+
+export interface IHueControlPermission {
+  readonly resource: 'config' | 'lights';
+  readonly resourceId: string;
+  readonly fields: readonly string[];
+}
+
+export interface IHueIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+  readonly credentialProvider?: IHueCredentialProvider;
+  readonly controlPermissions?: readonly IHueControlPermission[];
+  readonly db?: plugins.nosqldb.SmartdataDb;
+  readonly keyProvider?: IConfigEncryptionKeyProvider;
+}
+
 export interface IHueLightStatePatch {
   on?: boolean;
   /** Hue v2 brightness is a percentage, from 0 through 100. */
@@ -40,6 +75,7 @@ export interface IHueLightResource {
 }
 
 export interface IHueResourceResponse {
+  homeId: string;
   bridge: IHueDeviceResource;
   devices: IHueDeviceResource[];
   lights: IHueLightResource[];

package/ts/integrations/hue/hue.validation.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../../plugins.js';
-import type { IHueConfig, IHueDeviceResource, IHueEvent, IHueLightResource, IHueLightStatePatch, IHueResourceResponse } from './hue.types.js';
+import type { IHueConfig, IHueDeviceResource, IHueEvent, IHueLightResource, IHueLightStatePatch, IHueResourceResponse, IHueIntegrationOptions } from './hue.types.js';
 
 export const hueContentType = (valueArg: unknown, expectedArg: string): boolean =>
   typeof valueArg === 'string' && valueArg.split(';', 1)[0].trim().toLowerCase() === expectedArg;
@@ -10,13 +10,101 @@ export const hueUuid = (valueArg: unknown): valueArg is string =>
 export const hueBridgeId = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && /^[0-9a-f]{16}$/i.test(valueArg);
 
+/** Capture plain data fields without invoking caller accessors or retaining mutable objects. */
 export const hueRecord = (valueArg: unknown): Record<string, unknown> => {
-  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
-    throw new Error('Hue returned an invalid object.');
+  if (!valueArg || typeof valueArg !== 'object'
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new Error('Hue requires a plain data object.');
   }
-  return valueArg as Record<string, unknown>;
+  const record: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+      throw new Error('Hue data contains an unsupported field or accessor.');
+    }
+    record[key] = descriptor.value as unknown;
+  }
+  return record;
+};
+
+
+export const hueData = (valueArg: unknown, allowedArg: readonly string[]): Record<string, unknown> => {
+  const value = hueRecord(valueArg);
+  if (Object.keys(value).some((key) => !allowedArg.includes(key))) throw new TypeError('Hue data contains unsupported fields.');
+  return value;
+};
+
+export const hueText = (valueArg: unknown, nameArg: string, maximumArg = 256): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.length > maximumArg || valueArg.trim() !== valueArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) throw new TypeError(`Invalid Hue ${nameArg}.`);
+  return valueArg;
+};
+
+export const hueKey = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || !/^[a-z0-9_-]{1,256}$/i.test(valueArg)) throw new TypeError('Invalid Hue application credential.');
+  return valueArg;
 };
 
+export const hueOrigin = (configArg: IHueConfig): string => new URL(`https://${plugins.net.isIP(configArg.host) === 6 ? `[${configArg.host}]` : configArg.host}:${configArg.port ?? 443}`).origin;
+
+function method(valueArg: unknown, keyArg: string): ((...argsArg: never[]) => unknown) | undefined {
+  if (!valueArg || typeof valueArg !== 'object') throw new TypeError('Invalid Hue credential provider.');
+  let target: object | null = valueArg;
+  for (let depth = 0; target && depth < 16; depth++) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, keyArg);
+    if (descriptor) {
+      if (!('value' in descriptor) || typeof descriptor.value !== 'function') throw new TypeError('Hue provider requires data methods.');
+      return Function.prototype.bind.call(descriptor.value, valueArg) as (...argsArg: never[]) => unknown;
+    }
+    target = Object.getPrototypeOf(target) as object | null;
+  }
+  return undefined;
+}
+
+export function captureHueOptions(valueArg: IHueIntegrationOptions = {}): Readonly<IHueIntegrationOptions> {
+  const value = hueData(valueArg, ['homeId', 'capacity', 'credentialProvider', 'controlPermissions', 'db', 'keyProvider']);
+  const result: IHueIntegrationOptions = {};
+  if (value.homeId !== undefined) Object.assign(result, { homeId: hueText(value.homeId, 'constructor home') });
+  if (value.capacity !== undefined) {
+    if (typeof value.capacity !== 'number' || !Number.isSafeInteger(value.capacity) || value.capacity < 1 || value.capacity > 16) throw new TypeError('Hue capacity must be from 1 through 16.');
+    Object.assign(result, { capacity: value.capacity });
+  }
+  if (value.credentialProvider !== undefined) {
+    const resolve = method(value.credentialProvider, 'resolve');
+    const create = method(value.credentialProvider, 'create');
+    if (!resolve) throw new TypeError('Hue credential provider must resolve references.');
+    Object.assign(result, { credentialProvider: Object.freeze({ resolve, ...(create ? { create } : {}) }) });
+  }
+  if (value.controlPermissions !== undefined) {
+    if (!Array.isArray(value.controlPermissions) || value.controlPermissions.length > 128) throw new TypeError('Invalid Hue control permissions.');
+    const permissions = dataArray(value.controlPermissions).map((permissionArg: unknown) => {
+      const permission = hueData(permissionArg, ['resource', 'resourceId', 'fields']);
+      if (typeof permission.resource !== 'string' || !['config', 'lights'].includes(permission.resource)) throw new TypeError('Invalid Hue permission resource.');
+      const resourceId = hueText(permission.resourceId, 'permission resource', 128).toLowerCase();
+      if (permission.resource === 'lights' ? !hueUuid(resourceId) : !hueBridgeId(resourceId)) throw new TypeError('Invalid Hue permission identity.');
+      if (!Array.isArray(permission.fields) || !permission.fields.length || permission.fields.length > 32) throw new TypeError('Invalid Hue permission fields.');
+      const fields = dataArray(permission.fields).map((fieldArg: unknown) => hueText(fieldArg, 'permission field', 64));
+      const supported = permission.resource === 'lights' ? ['on', 'brightness'] : ['pair', 'credentials:create'];
+      if (fields.some((field) => !supported.includes(field))) throw new TypeError('Invalid Hue permission field.');
+      return Object.freeze({ resource: permission.resource, resourceId, fields: Object.freeze(fields) });
+    });
+    Object.assign(result, { controlPermissions: Object.freeze(permissions) });
+  }
+  if (value.db !== undefined) Object.assign(result, { db: value.db });
+  if (value.keyProvider !== undefined) {
+    const currentKey = method(value.keyProvider, 'currentKey');
+    const keyForId = method(value.keyProvider, 'keyForId');
+    if (!currentKey || !keyForId) throw new TypeError('Hue encrypted storage requires data-method key providers.');
+    Object.assign(result, { keyProvider: Object.freeze({ currentKey, keyForId }) });
+  }
+  if (Boolean(value.db) !== Boolean(value.keyProvider)) throw new TypeError('Hue owned encrypted storage requires both database and key provider.');
+  return Object.freeze(result);
+}
+
+function dataArray(valueArg: unknown[]): unknown[] {
+  if (Reflect.ownKeys(valueArg).some((key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= valueArg.length))) throw new TypeError('Hue arrays require dense data fields.');
+  return Array.from({ length: valueArg.length }, (_, index) => { const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index)); if (!descriptor?.enumerable || !('value' in descriptor)) throw new TypeError('Hue arrays require dense data fields.'); return descriptor.value as unknown; });
+}
+
 export const normalizeHueHost = (valueArg: unknown): string => {
   if (typeof valueArg !== 'string' || valueArg.length > 253 || valueArg !== valueArg.trim()) {
     throw new Error('Hue host must be a hostname or IP address.');
@@ -30,16 +118,17 @@ export const normalizeHueHost = (valueArg: unknown): string => {
   return host;
 };
 
-export const normalizeHueConfig = (configArg: IHueConfig): Required<Pick<IHueConfig, 'bridgeId' | 'host' | 'appKey' | 'port' | 'requestTimeoutMs'>> & Pick<IHueConfig, 'trustedCa'> => {
+export const normalizeHueConfig = (configArg: IHueConfig): Readonly<Required<Omit<IHueConfig, 'trustedCa'>> & Pick<IHueConfig, 'trustedCa'>> => {
   const record = hueRecord(configArg);
-  const allowed = new Set(['bridgeId', 'host', 'appKey', 'port', 'trustedCa', 'requestTimeoutMs']);
+  if (Object.hasOwn(record, 'appKey')) throw new Error('Hue raw appKey configuration is no longer supported. Migrate the key to a home-bound credential reference.');
+  const allowed = new Set(['homeId', 'bridgeId', 'host', 'credentialReference', 'port', 'trustedCa', 'requestTimeoutMs']);
   if (Reflect.ownKeys(record).some((keyArg) => typeof keyArg !== 'string' || !allowed.has(keyArg))) {
     throw new Error('Hue configuration contains unsupported fields.');
   }
   if (!hueBridgeId(record.bridgeId)) throw new Error('Hue bridgeId must contain 16 hexadecimal characters.');
-  if (typeof record.appKey !== 'string' || !/^[a-z0-9_-]{1,256}$/i.test(record.appKey)) {
-    throw new Error('Hue appKey must be a nonempty application key.');
-  }
+  const homeId = hueText(record.homeId, 'configuration home');
+  const credentialReference = hueText(record.credentialReference, 'credential reference');
+  if (encodeURIComponent(credentialReference).length > 900) throw new Error('Hue credential reference is too long.');
   const port = record.port ?? 443;
   const requestTimeoutMs = record.requestTimeoutMs ?? 10_000;
   if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535) throw new Error('Hue port is invalid.');
@@ -48,8 +137,8 @@ export const normalizeHueConfig = (configArg: IHueConfig): Required<Pick<IHueCon
   }
   if (record.trustedCa !== undefined && (typeof record.trustedCa !== 'string' || record.trustedCa.length > 65_536
     || !record.trustedCa.includes('-----BEGIN CERTIFICATE-----'))) throw new Error('Hue trustedCa must contain a PEM certificate.');
-  return { bridgeId: record.bridgeId.toLowerCase(), host: normalizeHueHost(record.host), appKey: record.appKey, port, requestTimeoutMs,
-    trustedCa: typeof record.trustedCa === 'string' ? record.trustedCa : undefined };
+  return Object.freeze({ homeId, credentialReference, bridgeId: record.bridgeId.toLowerCase(), host: normalizeHueHost(record.host), port, requestTimeoutMs,
+    trustedCa: typeof record.trustedCa === 'string' ? record.trustedCa : undefined });
 };
 
 export const validateHuePatch = (patchArg: IHueLightStatePatch): void => {
@@ -86,7 +175,7 @@ const deviceResource = (resourceArg: Record<string, unknown>): IHueDeviceResourc
       productName: optionalString(product.product_name), softwareVersion: optionalString(product.software_version) } : undefined };
 };
 
-export const parseHueResources = (dataArg: unknown[], bridgeIdArg: string): IHueResourceResponse => {
+export const parseHueResources = (dataArg: unknown[], bridgeIdArg: string, homeIdArg: string): IHueResourceResponse => {
   const devices = new Map<string, IHueDeviceResource>();
   const connectivity = new Map<string, boolean>();
   const lightResources: Record<string, unknown>[] = [];
@@ -133,7 +222,7 @@ export const parseHueResources = (dataArg: unknown[], bridgeIdArg: string): IHue
       on: { on: power.on }, dimming: dimming ? { brightness: dimming.brightness as number } : undefined,
       available: connectivity.get(owner.rid.toLowerCase()) === true };
   });
-  return { bridge, devices: [...devices.values()], lights };
+  return { homeId: hueText(homeIdArg, 'resource home'), bridge, devices: [...devices.values()], lights };
 };
 
 export const parseHueEvents = (valueArg: unknown): IHueEvent[] => {

package/ts/integrations/hue/readme.md

@@ -6,19 +6,27 @@ Native TypeScript integration for Philips Hue API v2 bridges. It discovers bridg
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## Configuration and TLS
+## Configuration, credentials and TLS
 
-`IHueConfig` requires `bridgeId` (the bridge's 16-character hexadecimal ID), `host` (an IP address or hostname), and `appKey`. Optional fields are `port` (443 by default), `trustedCa` (a PEM CA certificate), and `requestTimeoutMs` (10000 by default, permitted range 50–60000).
+`IHueConfig` requires `homeId`, `bridgeId` (16 hexadecimal characters), `host` and `credentialReference`. Optional fields are `port` (443), `trustedCa` (operator-supplied PEM CA) and `requestTimeoutMs` (10000, permitted range 50–60000). Setup, config flows and the public `HueClient(config, context, options)` require an independently selected `context.homeId`. Configuration and discovery cannot choose that authority. Constructor `options.homeId`, configuration home, and any supplied store must match it. The first admitted home remains bound even when readiness fails.
 
-Create an application key using the bridge's physical link button and the [Hue developer setup procedure](https://developers.meethue.com/develop/get-started-2/). This integration accepts that key; it does not generate or print credentials. Its config flow verifies a live resource read before returning a completed configuration. The application key travels only in the `hue-application-key` request header. Inject the host's encrypted `IConfigStore` into the normal integration setup flow when storing the resulting configuration.
+Supply an `IHueCredentialProvider` in owner options or an actual `NoSqlConfigStore` scoped to that home and the `hue` domain in the context. A structural store is rejected. A provider receives a frozen request containing `homeId`, HTTPS `origin`, `bridgeId`, `credentialReference`, `signal` and a monotonic `deadline`; it must resolve the exact selected credential and honor its own non-replacing `create` contract. Provider methods and control permissions are captured at construction. Resolution is joined even if cancellation wins, and a late result cannot open HTTPS. Provider errors are redacted. Keys are resolved per operation and never retained in configuration.
 
-Certificate-chain verification remains enabled. The certificate must identify the configured bridge ID, even when the connection uses an IP address. Hue bridges using the Signify private CA require the operator to supply the appropriate trusted CA from the [Hue HTTPS guidance](https://developers.meethue.com/develop/application-design-guidance/using-https/). The system trust store is used when `trustedCa` is absent. No trust-on-first-use, HTTP downgrade, disabled verification or caller-supplied resource snapshots are supported. Discovery metadata does not establish a trusted bridge identity.
+The encrypted-store reference key is `hue.credential.<encodeURIComponent(credentialReference)>`. Its encrypted value is `{ version: 1, homeId, origin, bridgeId, credentialReference, appKey }`; every scope field must match before the key is used. Creation uses insert-only `NoSqlConfigStore.create`, after TLS and live bridge-resource validation. `options.db` plus `options.keyProvider` can instead create an owned store wrapper at the admitted home/domain. The wrapper is closed with the client; a supplied store, database and key provider remain caller-owned. Normal persistence uses the public document-client APIs.
 
-Use `HueIntegration` from `@smarthome.exchange/integrations` with operator-supplied configuration:
+The config flow accepts an existing key only for one-time credential insertion. Without a supplied key, it uses HTTPS `POST /api` with the physical link button, validates the resulting key against API v2 resources and passes it to the provider/store. Error type 101 offers an explicit link-button retry. An indeterminate dispatched pairing or credential creation is terminal; shutdown and cleanup never replay it. Completed config and flow output contain only the reference, and events/errors never expose the application key. Pairing requires exact `config` permission for the selected bridge ID with both `pair` and `credentials:create`; insertion of an existing key requires `credentials:create`. The application key is sent in the `hue-application-key` header for authenticated requests.
+
+Certificate-chain verification stays enabled. The certificate must identify the configured bridge ID even when connecting by IP. Hue bridges using the Signify private CA require the trusted CA from the [Hue HTTPS guidance](https://developers.meethue.com/develop/application-design-guidance/using-https/). The system trust store is used when `trustedCa` is absent. Discovery metadata is a selection hint; setup verifies TLS identity and the live `bridge_id`.
 
 ```typescript
-const integration = new HueIntegration();
-const runtime = await integration.setup({ bridgeId, host, appKey, trustedCa }, { configStore });
+import { HueIntegration } from '@smarthome.exchange/integrations';
+
+// homeId and the actual home/domain-scoped configStore are selected by the host.
+const integration = new HueIntegration({
+  homeId,
+  controlPermissions: [{ resource: 'lights', resourceId: selectedLightUuid, fields: ['on', 'brightness'] }],
+});
+const runtime = await integration.setup({ homeId, bridgeId, host, credentialReference, trustedCa }, { homeId, configStore });
 try {
   const lights = (await runtime.devices()).filter((device) => device.id.startsWith('hue.light.'));
   console.log(lights.map((device) => ({ id: device.id, name: device.name, online: device.online })));
@@ -27,13 +35,38 @@ try {
 }
 ```
 
+## Migration from raw appKey configurations
+
+Raw `appKey` configurations are refused with a migration error, including when a reference is also supplied. Migrate explicitly by inserting the existing key into the selected host store and saving only the completed configuration. `configStore` must be an actual encrypted store scoped to `homeId` and `hue`:
+
+```typescript
+const integration = new HueIntegration({
+  homeId,
+  controlPermissions: [{ resource: 'config', resourceId: bridgeId, fields: ['credentials:create'] }],
+});
+try {
+  const form = await integration.configFlow.start({
+    source: 'manual', integrationDomain: 'hue', id: bridgeId, host, port,
+  }, { homeId, configStore });
+  const result = await form.submit!({ credentialReference, appKey: existingAppKey, trustedCa });
+  if (result.kind !== 'done' || !result.config) throw new Error('Hue credential migration failed.');
+  // Persist result.config through the host config store; retire the old raw-key config.
+} finally {
+  await integration.destroy();
+}
+```
+
+Use a new reference if the selected reference already exists; insertion never replaces it. Update stored entity/device targets to the home-qualified identities below. Construct a runtime owner with the desired light grants after migration; pairing permissions do not grant light controls.
+
 ## Reads and controls
 
-Setup checks both the TLS identity and the `bridge_id` returned by `/clip/v2/resource`. Device/light IDs are validated UUIDs. Entities use `light.<resource UUID>` and devices use `hue.light.<resource UUID>`; changing a display name preserves identity. This replaces the previous display-name entity IDs. The `resources` configuration fixture field has been removed.
+Setup checks both the TLS identity and the `bridge_id` returned by `/clip/v2/resource`. Device/light IDs are validated UUIDs. Entities use `light.hue.<encoded home>.<resource UUID>`, light devices use `hue.light.<encoded home>.<resource UUID>`, and bridge devices use `hue.bridge.<encoded home>.<bridge-device UUID>`; changing a display name preserves identity. Entity unique IDs also include the admitted home. Two homes cannot share a routing identity. The `resources` configuration fixture field has been removed.
 
 Lights advertise brightness only when the bridge reports the `dimming` capability. Availability follows the owning device's Zigbee connectivity resource; missing or disconnected connectivity is unavailable. Manufacturer and model come from the owning device, including supported third-party Hue lights.
 
-Light services are `turn_on`, `turn_off` and `set_percentage`. `turn_on` accepts optional `brightness` from 0 to 100; `set_percentage` requires `percentage` in that same range. A target must match the current entity/device exactly; supplying both requires them to identify the same light. `writeFeature` supports boolean `on` and numeric `brightness` only for an available light's declared writable capabilities. Unsupported fields, unknown targets and values outside the protocol range are rejected.
+Controls default to denied. Each write requires one immutable `lights` permission matching the raw light UUID and every selected field (`on`, `brightness`). No wildcard grant is accepted. The public client enforces the same permission boundary as the runtime.
+
+Light services are `turn_on`, `turn_off` and `set_percentage`. `turn_on` accepts optional `brightness` from 0 to 100; `set_percentage` requires `percentage` in that same range. A target must match the current entity/device exactly; supplying both requires them to identify the same light. `writeFeature` supports boolean `on` and numeric `brightness` only for an available light's declared writable capabilities. Unsupported fields, unknown targets and values outside the protocol range are rejected. Controls capture plain-data target IDs, domain, capability and value before awaiting a fresh read; later caller mutation cannot retarget a write. Accessors, symbols, hidden fields and class instances are rejected without invoking getters. Setup cancellation and config-flow discovery endpoint hints are also captured before awaiting readiness or displaying a form.
 
 Writes use `PUT /clip/v2/resource/light/<UUID>` and require the bridge's matching resource acknowledgement. Success means the bridge accepted the write; it does not guarantee physical delivery. Accepted writes never change local read state. Each `devices()` or `entities()` call reads current authoritative resources, and writes are not automatically retried.
 
@@ -41,13 +74,17 @@ Writes use `PUT /clip/v2/resource/light/<UUID>` and require the bridge's matchin
 
 `subscribe()` opens authenticated HTTPS `/eventstream/clip/v2` and returns an asynchronous, idempotent unsubscribe function. Change notifications contain only relevant resource IDs/types; consumers reread authoritative state. Unknown resource payloads are omitted because they may contain credentials. Invalid frames, stream termination and transport failures produce an error event and mark the runtime unhealthy. Reads do not silently restart a failed subscription; the host may explicitly establish a new one or replace the runtime.
 
-Requests have whole-response deadlines and a 4 MiB body limit. Discovery uses the fixed documented `https://discovery.meethue.com/` broker with a five-second deadline and 256 KiB body limit. SSE frames are limited to 1 MiB and batches to 256 events. A client permits at most 32 outstanding connections, two event subscriptions, and three simultaneous HTTPS sockets. Caller cancellation and `destroy()` close owned requests/streams; destroy waits for them to close. The integration also owns pending setups and destroys their clients on failure or shutdown.
+One shared `NativeIntegrationOwner` bounds pending setups, promoted runtimes, subscriptions, finite operations and retained cleanup resources (default capacity 16). A setup lease owns the client before readiness and promotes to a runtime only after validation. Config flows use terminal child scopes on that same owner. Previously returned forms cannot submit after flow/integration shutdown; candidate endpoint and host context are captured before any await. A runtime command holds one operation lease and permits one PUT attempt. Setup/submission also occupy a lease while their client operation runs, so capacity must leave room for both.
+
+Requests share a whole-operation deadline with credential resolution and have a 4 MiB body limit. Discovery uses the fixed documented `https://discovery.meethue.com/` broker with a five-second deadline and 256 KiB body limit. SSE frames are limited to 1 MiB and batches to 256 events. A client permits at most 32 outstanding connections, two event subscriptions, three simultaneous HTTPS sockets and 32 pending callbacks per stream. An established stream retains shared capacity until its transport and callbacks settle; its connection deadline does not expire a live subscription.
+
+Caller cancellation and `destroy()` close owned requests/streams and join actual provider, request and subscriber continuations. Subscriber callbacks may return promises. Unsubscribe and destroy have stable promise identity; later callbacks are fenced. Synchronous throws and async rejections are observed and use redacted subscriber errors. Failed transport/store cleanup and callback failures remain retained until explicit cleanup-only retry. `HueClient.retryCleanup()`, `HueConfigFlow.retryCleanup()` and `HueIntegration.retryCleanup()` never replay GETs, PUTs, pairing, credential creation, subscriptions or callbacks. Integration shutdown drains sibling runtimes and pending submissions before reporting cleanup failure. Runtime `destroy()` closes its promoted lease.
 
 ## Verification and limits
 
-Tests use disposable CA-signed local TLS bridges, including untrusted issuers, a wrong bridge certificate, resource identity mismatch, exact PUT payloads, non-optimistic reads, unsupported controls, unavailable devices, malformed/oversized bodies, cancellation and event-stream cleanup. No physical bridge or owner's home was accessed.
+Tests preserve the existing 46 cases and use disposable CA-signed local TLS bridges, including untrusted issuers, a wrong bridge certificate, resource identity mismatch, exact PUT payloads, non-optimistic reads, unsupported controls, unavailable devices, malformed/oversized bodies, cancellation, plain-data/accessor validation, blocked async subscribers, sibling drainage, reentrant close, retained cleanup failures and cleanup-only retry without HTTPS replay. Ownership regressions additionally cover home-qualified routing, default-deny exact grants, shared capacity, scoped encrypted references, late provider drainage, flow shutdown, link-button pairing and secret-free completion. No physical bridge or owner's home was accessed.
 
-The public [Hue API announcement](https://developers.meethue.com/new-hue-api/) establishes API v2 HTTPS, local proactive events and the supported discovery methods. Detailed Hue API and HTTPS pages require a developer login and returned login/403 here. Implemented wire resource models and event paths were cross-checked against [aiohue's upstream v2 implementation](https://github.com/home-assistant-libs/aiohue/tree/main/aiohue/v2). Aiohue's disabled-TLS and geofence keepalive workaround are not used. Physical bridge firmware compatibility, operator CA provisioning and physical command delivery remain acceptance checks. Color, color temperature, scenes, entertainment streaming, grouped lights and accessory sensors are not exposed by this runtime.
+The public [Hue API announcement](https://developers.meethue.com/new-hue-api/) establishes API v2 HTTPS, local proactive events and the supported discovery methods. Detailed Hue API and HTTPS pages require a developer login and returned login/403 here. The pairing wire shape (`POST /api`, `devicetype`, `success.username`) was checked against [aiohue util.py](https://github.com/home-assistant-libs/aiohue/blob/main/aiohue/util.py). Its HTTP fallback and disabled TLS are not used. Implemented wire resource models and event paths were cross-checked against [aiohue's upstream v2 implementation](https://github.com/home-assistant-libs/aiohue/tree/main/aiohue/v2). Aiohue's disabled-TLS and geofence keepalive workaround are not used. Physical bridge firmware compatibility, operator CA provisioning and physical command delivery remain acceptance checks. Color, color temperature, scenes, entertainment streaming, grouped lights and accessory sensors are not exposed by this runtime.
 
 ## License and Legal Information