@smarthome.exchange/integrations 3.0.0 → 4.0.0

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

@@ -1,89 +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>();
-  readonly #setups = new Set<Promise<IIntegrationRuntime>>();
-  #closed = false;
-  #destroyPromise?: Promise<void>;
-  #retryPromise?: Promise<void>;
+  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 context = hueRecord(contextArg);
-    const signal = context.abortSignal;
-    if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError('Hue abortSignal must be an AbortSignal.');
-    const client = new HueClient(configArg, signal);
-    const runtime = new HueIntegrationRuntime(client, () => this.#runtimes.delete(runtime));
-    this.#runtimes.add(runtime);
-    const setup = Promise.resolve().then(async () => {
-      try {
-        await client.getResources();
-        if (this.#closed || signal?.aborted) throw new Error('Hue setup was cancelled.');
-        return runtime;
-      } catch (error) {
-        try { await runtime.destroy(); }
-        catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Hue setup and cleanup failed.'); }
-        throw error;
-      }
+    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();
+      lease.assertOpen();
+      if (!client.isHealthy()) throw new Error('Hue setup cancelled.');
+      lease.promoteToRuntime();
+      return new HueIntegrationRuntime(client, lease);
     });
-    this.#setups.add(setup);
-    void setup.then(() => this.#setups.delete(setup), () => this.#setups.delete(setup));
-    return setup;
-  }
-
-  public destroy(): Promise<void> {
-    if (!this.#destroyPromise) {
-      this.#closed = true;
-      this.#destroyPromise = Promise.resolve().then(() => this.drain(false));
-    }
-    return this.#destroyPromise;
-  }
-
-  public retryCleanup(): Promise<void> {
-    if (!this.#destroyPromise) throw new Error('Hue cleanup retry requires a terminal integration.');
-    if (!this.#retryPromise) {
-      this.#retryPromise = Promise.resolve().then(async () => {
-        await this.#destroyPromise!.catch(() => undefined);
-        await this.drain(true);
-      });
-      const settled = (): void => { this.#retryPromise = undefined; };
-      void this.#retryPromise.then(settled, settled);
-    }
-    return this.#retryPromise;
   }
 
-  private async drain(retryArg: boolean): Promise<void> {
-    const cleanup = Promise.allSettled([...this.#runtimes].map((runtimeArg) => retryArg ? runtimeArg.retryCleanup() : runtimeArg.destroy()));
-    const [results] = await Promise.all([cleanup, Promise.allSettled([...this.#setups])]);
-    const errors = results.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected').map((resultArg) => resultArg.reason as unknown);
-    if (errors.length) throw new AggregateError(errors, 'Hue integration cleanup failed; resources remain retained for explicit retry.');
-  }
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 
 }
 
 class HueIntegrationRuntime implements IIntegrationRuntime {
   public readonly domain = 'hue';
 
-  #destroyPromise?: Promise<void>;
-  #retryPromise?: Promise<void>;
-  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));
   }
 
@@ -119,11 +87,13 @@ class HueIntegrationRuntime implements IIntegrationRuntime {
       state.brightness = brightness;
       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> {
@@ -138,44 +108,29 @@ class HueIntegrationRuntime implements IIntegrationRuntime {
     if (selectedDevice.integrationDomain !== this.domain || typeof deviceId !== 'string' || typeof featureId !== 'string') {
       return { success: false, error: 'Hue feature requires one exact Hue device and feature.' };
     }
-    const snapshot = await this.client.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 this.client.setLightState(lightId, state, abortSignalArg);
-    return { success: true };
+    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 destroy(): Promise<void> {
-    this.#destroyPromise ??= Promise.resolve().then(async () => { await this.client.destroy(); this.released(); });
-    return this.#destroyPromise;
-  }
-
-  public retryCleanup(): Promise<void> {
-    if (!this.#destroyPromise) throw new Error('Hue cleanup retry requires a terminal runtime.');
-    if (!this.#retryPromise) {
-      this.#retryPromise = Promise.resolve().then(async () => {
-        await this.#destroyPromise!.catch(() => undefined);
-        await this.client.retryCleanup();
-        this.released();
-      });
-      const settled = (): void => { this.#retryPromise = undefined; };
-      void this.#retryPromise.then(settled, settled);
-    }
-    return this.#retryPromise;
-  }
+  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;
@@ -27,6 +27,84 @@ export const hueRecord = (valueArg: unknown): Record<string, 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.');
@@ -40,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.');
@@ -58,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 => {
@@ -96,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>[] = [];
@@ -143,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,12 +35,37 @@ 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.
 
+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 and all admitted request/subscriber continuations to settle. Subscriber callbacks may return promises. Unsubscribe has stable promise identity and joins admitted callbacks; later events are fenced. Each stream permits at most 32 pending callbacks. Synchronous throws and async rejections are observed, mark the stream unhealthy, and use a redacted subscriber error rather than being relabelled as malformed stream data. Callback failures remain visible on terminal client cleanup until explicit `HueClient.retryCleanup()` or `HueIntegration.retryCleanup()` acknowledges them. Failed transport cleanup is retained for the same retry. Retry performs cleanup only; it never replays GETs, PUTs, subscriptions, or callbacks. `destroy()` publishes a stable terminal promise before aborting and continues to return that promise after a retry. Integration and runtime destroy also have stable terminal promise identity. Integration shutdown joins pending setups and all sibling runtimes before surfacing cleanup failures, retaining failed runtime handles for explicit cleanup-only retry. Shared native home/resource admission, flow ownership, and home-qualified IDs are pending a separate breaking config/identity decision. Raw `appKey` configuration remains the current contract; home-bound credential references and existing-config migration require a separate public-contract decision.
+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, plain-data/accessor validation, blocked async subscribers, sibling drainage, reentrant close, retained cleanup failures and cleanup-only retry without HTTPS replay. 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