@smarthome.exchange/integrations 3.0.0 → 4.0.0

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

@@ -1,6 +1,10 @@
 import * as plugins from '../../plugins.js';
-import type { IHueConfig, IHueEvent, IHueLightStatePatch, IHueResourceResponse } from './hue.types.js';
-import { hueContentType, hueRecord, hueUuid, normalizeHueConfig, parseHueEnvelope, parseHueEvents, parseHueResources, validateHuePatch } from './hue.validation.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import { NativeIntegrationOwner, type INativeOperationLease } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
+import type { IHueConfig, IHueEvent, IHueLightStatePatch, IHueResourceResponse, IHueCredentialRequest, IHueIntegrationOptions } from './hue.types.js';
+import { captureHueOptions, hueContentType, hueData, hueKey, hueOrigin, hueRecord, hueUuid, normalizeHueConfig, parseHueEnvelope, parseHueEvents, parseHueResources, validateHuePatch } from './hue.validation.js';
 
 interface IHueConnection {
   cancel(): void;
@@ -44,8 +48,30 @@ class HueEventDecoder {
   }
 }
 
+export class HuePairingError extends Error {
+  constructor(public readonly linkButtonRequired = false) { super(linkButtonRequired ? 'Press the Hue bridge link button, then retry.' : 'Hue pairing or credential creation was dispatched; do not replay it.'); }
+}
+
+interface IHueOperation {
+  readonly lease: INativeOperationLease;
+  readonly signal: AbortSignal;
+  readonly deadline: number;
+  readonly actual: Set<Promise<unknown>>;
+}
+
+export interface IHueClientOperation {
+  getResources(signalArg?: AbortSignal): Promise<IHueResourceResponse>;
+  setLightState(idArg: string, stateArg: IHueLightStatePatch, signalArg?: AbortSignal): Promise<void>;
+}
+
 export class HueClient {
   readonly #config: ReturnType<typeof normalizeHueConfig>;
+  readonly #context: INativeAdmissionContext;
+  readonly #options: Readonly<IHueIntegrationOptions>;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #ownsOwner: boolean;
+  readonly #store?: NoSqlConfigStore;
+  readonly #ownsStore: boolean;
   readonly #agent: plugins.https.Agent;
   readonly #lifetime = new AbortController();
   readonly #connections = new Set<IHueConnection>();
@@ -58,69 +84,162 @@ export class HueClient {
   #healthy = false;
   #eventFailure = false;
 
-  constructor(configArg: IHueConfig, private readonly setupSignal?: AbortSignal) {
+  constructor(configArg: IHueConfig, contextArg: IIntegrationSetupContext, optionsArg: IHueIntegrationOptions = {}, ownerArg?: NativeIntegrationOwner) {
     this.#config = normalizeHueConfig(configArg);
+    this.#options = captureHueOptions(optionsArg);
+    this.#ownsOwner = !ownerArg;
+    this.#owner = ownerArg ?? new NativeIntegrationOwner('hue', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.#context = this.#owner.admission.admit(contextArg, this.#config.homeId);
+    if (this.#options.homeId !== undefined && this.#options.homeId !== this.#context.homeId) throw new Error('Hue constructor home does not match the host home.');
+    if (this.#context.configStore && this.#options.db) throw new Error('Hue requires one selected credential store.');
+    if (this.#options.db && !(this.#options.db instanceof plugins.nosqldb.SmartdataDb)) throw new TypeError('Hue requires an actual caller-owned database.');
+    this.#ownsStore = !this.#context.configStore && Boolean(this.#options.db);
+    this.#store = this.#context.configStore ?? (this.#options.db && this.#options.keyProvider ? new NoSqlConfigStore({ db: this.#options.db, keyProvider: this.#options.keyProvider, homeId: this.#context.homeId, integrationDomain: 'hue', timeoutMs: this.#config.requestTimeoutMs }) : undefined);
+    if (!this.#options.credentialProvider && !this.#store) throw new Error('Hue requires an explicit credential provider or an actual encrypted config store.');
     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 });
+    this.#context.abortSignal?.addEventListener('abort', this.abortSetup, { once: true });
   }
 
+  public get canCreateCredential(): boolean { return Boolean(this.#options.credentialProvider?.create || !this.#options.credentialProvider && this.#store); }
+
   public isHealthy(): boolean {
-    return !this.#lifetime.signal.aborted && this.#healthy && !this.#eventFailure && this.#callbackFailures.size === 0;
+    return !this.#destroyPromise && !this.#lifetime.signal.aborted && !this.#owner.signal.aborted && !this.#context.abortSignal?.aborted && this.#healthy && !this.#eventFailure && this.#callbackFailures.size === 0;
   }
 
   public getResources(abortSignalArg?: AbortSignal): Promise<IHueResourceResponse> {
-    return this.run(() => this.readResources(abortSignalArg), abortSignalArg);
+    return this.run((operation) => this.readResources(operation), abortSignalArg);
   }
 
-  private async readResources(abortSignalArg?: AbortSignal): Promise<IHueResourceResponse> {
+  private async readResources(operationArg: IHueOperation, keyArg?: string): Promise<IHueResourceResponse> {
     try {
-      const data = parseHueEnvelope(await this.request('GET', '/clip/v2/resource', undefined, abortSignalArg));
-      const resources = parseHueResources(data, this.#config.bridgeId);
+      const key = keyArg ?? await this.credential(operationArg);
+      const data = parseHueEnvelope(await this.request('GET', '/clip/v2/resource', undefined, operationArg.signal, key));
+      this.active(operationArg);
+      const resources = parseHueResources(data, this.#config.bridgeId, this.#context.homeId);
       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.');
-    const captured = hueRecord(stateArg);
-    const state = { on: captured.on, brightness: captured.brightness } as IHueLightStatePatch;
+  public setLightState(lightIdArg: string, stateArg: IHueLightStatePatch, abortSignalArg?: AbortSignal): Promise<void> {
+    const { lightId, state } = this.captureWrite(lightIdArg, stateArg);
+    return this.run((operation) => this.write(operation, lightId, state), abortSignalArg);
+  }
+
+  /** A captured runtime command shares one operation lease, provider deadline and one write attempt. */
+  public execute<TResult>(workArg: (clientArg: IHueClientOperation) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    return this.run(async (operation) => {
+      let open = true;
+      let written = false;
+      const check = (signal?: AbortSignal): void => { if (!open) throw new Error('Hue command session is closed.'); signal?.throwIfAborted(); this.active(operation); };
+      const session: IHueClientOperation = Object.freeze({
+        getResources: async (signal?: AbortSignal) => { check(signal); return this.readResources(operation); },
+        setLightState: async (id: string, patch: IHueLightStatePatch, signal?: AbortSignal) => {
+          check(signal);
+          if (written) throw new Error('Hue command permits one write attempt.');
+          const { lightId, state } = this.captureWrite(id, patch);
+          written = true;
+          await this.write(operation, lightId, state);
+        },
+      });
+      try { return await this.foreign(operation, () => workArg(session)); }
+      finally { open = false; }
+    }, signalArg);
+  }
+
+  private captureWrite(idArg: string, patchArg: IHueLightStatePatch): { lightId: string; state: IHueLightStatePatch } {
+    if (!hueUuid(idArg)) throw new Error('Hue light target must be a resource UUID.');
+    const captured = hueRecord(patchArg);
     validateHuePatch(captured as IHueLightStatePatch);
-    const lightId = lightIdArg.toLowerCase();
-    return this.run(async () => {
-      const snapshot = await this.readResources(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.');
-      }
-    }, abortSignalArg);
+    return { lightId: idArg.toLowerCase(), state: { ...(captured.on === undefined ? {} : { on: captured.on as boolean }), ...(captured.brightness === undefined ? {} : { brightness: captured.brightness as number }) } };
+  }
+
+  private async write(operationArg: IHueOperation, lightId: string, state: IHueLightStatePatch): Promise<void> {
+    this.permission('lights', lightId, Object.keys(state));
+    const key = await this.credential(operationArg);
+    const snapshot = await this.readResources(operationArg, key);
+    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 } }) };
+    this.active(operationArg);
+    const data = parseHueEnvelope(await this.request('PUT', `/clip/v2/resource/light/${lightId}`, body, operationArg.signal, key));
+    if (data.length !== 1) throw new Error('Hue write acknowledgement does not identify the target light.');
+    const acknowledgement = hueRecord(data[0]);
+    if (typeof acknowledgement.rid !== 'string' || acknowledgement.rid.toLowerCase() !== lightId || acknowledgement.rtype !== 'light') throw new Error('Hue write acknowledgement does not identify the target light.');
+  }
+
+  public acquireAppKey(deviceTypeArg = 'smarthome.exchange', signalArg?: AbortSignal): Promise<string> {
+    if (typeof deviceTypeArg !== 'string' || !/^[a-z0-9_.#-]{1,40}$/i.test(deviceTypeArg)) throw new Error('Invalid Hue pairing client name.');
+    return this.run(async (operation) => {
+      this.permission('config', this.#config.bridgeId, ['pair', 'credentials:create']);
+      if (!this.canCreateCredential) throw new Error('Hue pairing requires credential creation by the selected provider or encrypted store.');
+      let dispatched = false;
+      try {
+        const result = await this.request('POST', '/api', { devicetype: deviceTypeArg }, operation.signal, undefined, () => { dispatched = true; });
+        if (!Array.isArray(result) || result.length !== 1) throw new Error('Invalid Hue pairing acknowledgement.');
+        const entry = hueRecord(result[0]);
+        if (entry.error !== undefined && hueRecord(entry.error).type === 101) throw new HuePairingError(true);
+        return hueKey(hueRecord(entry.success).username);
+      } catch (error) { if (error instanceof HuePairingError && error.linkButtonRequired) throw error; if (dispatched) throw new HuePairingError(); throw error; }
+    }, signalArg);
+  }
+
+  public createCredential(appKeyArg: string, signalArg?: AbortSignal): Promise<void> {
+    const key = hueKey(appKeyArg);
+    return this.run(async (operation) => {
+      this.permission('config', this.#config.bridgeId, ['credentials:create']);
+      if (!this.canCreateCredential) throw new Error('Hue credential creation is unavailable.');
+      await this.readResources(operation, key);
+      const request = this.credentialRequest(operation);
+      let dispatched = false;
+      try {
+        if (this.#options.credentialProvider?.create) await this.foreign(operation, () => { dispatched = true; return this.#options.credentialProvider!.create!(request, key); });
+        else {
+          await this.foreign(operation, () => this.#store!.initialize({ signal: operation.signal }));
+          await this.foreign(operation, () => { dispatched = true; return this.#store!.create(this.storeKey(), { version: 1, homeId: request.homeId, origin: request.origin, bridgeId: request.bridgeId, credentialReference: request.credentialReference, appKey: key }); });
+        }
+        this.active(operation);
+      } catch (error) { if (dispatched) throw new HuePairingError(); throw error; }
+    }, signalArg);
   }
 
   public subscribeToEvents(handlerArg: (eventArg: IHueEvent) => unknown,
     onErrorArg: (errorArg: Error) => unknown, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
     if (typeof handlerArg !== 'function' || typeof onErrorArg !== 'function') throw new TypeError('Hue subscribers must be functions.');
-    return this.run(() => this.subscribe(handlerArg, onErrorArg, abortSignalArg), abortSignalArg);
+    let resolveSubscription: (closeArg: () => Promise<void>) => void = () => {};
+    let rejectSubscription: (errorArg: unknown) => void = () => {};
+    let issued = false;
+    const subscribed = new Promise<() => Promise<void>>((resolve, reject) => { resolveSubscription = resolve; rejectSubscription = reject; });
+    let admitted: Promise<void>;
+    try {
+      admitted = this.run(async (operation) => {
+        const key = await this.credential(operation);
+        const close = await this.subscribe(operation, key, handlerArg, onErrorArg, abortSignalArg);
+        this.active(operation);
+        issued = true;
+        let closing: Promise<void> | undefined;
+        resolveSubscription(() => closing ??= close().then(() => admitted));
+      }, abortSignalArg);
+    } catch (error) { rejectSubscription(error); return subscribed; }
+    void admitted.then(() => { if (!issued) rejectSubscription(new Error('Hue subscription failed.')); }, (error: unknown) => {
+      if (!issued) rejectSubscription(error);
+      else { this.#callbackFailures.add(new Error('Hue subscription lifecycle failed.')); this.#eventFailure = true; }
+    });
+    return subscribed;
   }
 
-  private async subscribe(handlerArg: (eventArg: IHueEvent) => unknown,
+  private async subscribe(operationArg: IHueOperation, keyArg: string, handlerArg: (eventArg: IHueEvent) => unknown,
     onErrorArg: (errorArg: Error) => unknown, 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; });
+    operationArg.actual.add(closed);
+    void closed.then(() => operationArg.actual.delete(closed));
     const abort = new AbortController();
-    const signal = AbortSignal.any([this.#lifetime.signal, abort.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+    const signal = AbortSignal.any([this.#lifetime.signal, this.#owner.signal, abort.signal, ...(this.#context.abortSignal ? [this.#context.abortSignal] : []), ...(abortSignalArg ? [abortSignalArg] : [])]);
     let active = true;
     signal.addEventListener('abort', () => { active = false; }, { once: true });
     const callbacks = new Set<Promise<void>>();
@@ -161,7 +280,7 @@ export class HueClient {
       };
       request = plugins.https.request(this.requestOptions('GET', '/eventstream/clip/v2', signal, {
         accept: 'text/event-stream', 'cache-control': 'no-cache',
-      }), (responseArg) => {
+      }, keyArg), (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.'));
@@ -203,7 +322,7 @@ export class HueClient {
       request.end();
     });
     try {
-      await ready;
+      await this.foreign(operationArg, () => ready);
     } catch (error) {
       connection.cancel();
       if (!request) { this.#connections.delete(connection); this.#streamCount--; resolveClosed(); }
@@ -220,7 +339,7 @@ export class HueClient {
   public destroy(): Promise<void> {
     if (!this.#destroyPromise) {
       this.#destroyPromise = Promise.resolve().then(() => this.drain());
-      this.setupSignal?.removeEventListener('abort', this.abortSetup);
+      this.#context.abortSignal?.removeEventListener('abort', this.abortSetup);
       this.#lifetime.abort();
     }
     return this.#destroyPromise;
@@ -233,7 +352,7 @@ export class HueClient {
       this.#retryPromise = Promise.resolve().then(async () => {
         await this.#destroyPromise!.catch(() => undefined);
         this.#callbackFailures.clear();
-        await this.drain();
+        await this.drain(true);
       });
       const settled = (): void => { this.#retryPromise = undefined; };
       void this.#retryPromise.then(settled, settled);
@@ -243,7 +362,7 @@ export class HueClient {
 
   private readonly abortSetup = (): void => { void this.destroy().catch(() => undefined); };
 
-  private async drain(): Promise<void> {
+  private async drain(retryArg = false): Promise<void> {
     const results = await Promise.allSettled([
       ...[...this.#connections].map(async (connectionArg) => { connectionArg.cancel(); await connectionArg.closed; }),
       Promise.resolve().then(() => { if (!this.#agentClosed) { this.#agent.destroy(); this.#agentClosed = true; } }),
@@ -251,36 +370,80 @@ export class HueClient {
     await Promise.allSettled([...this.#operations]);
     const failures = results.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected')
       .map(() => new Error('Hue transport cleanup failed.'));
-    failures.push(...this.#callbackFailures);
+    const other = await Promise.allSettled([
+      ...(this.#ownsStore && this.#store ? [retryArg ? this.#store.retryCleanup() : this.#store.close()] : []),
+      ...(this.#ownsOwner ? [retryArg ? this.#owner.retryCleanup() : this.#owner.close()] : []),
+    ]);
+    failures.push(...other.filter((result) => result.status === 'rejected').map(() => new Error('Hue owned cleanup failed.')), ...this.#callbackFailures);
     if (failures.length) throw new AggregateError(failures, 'Hue cleanup failed; explicit cleanup retry is required.');
   }
 
-  private run<TResult>(workArg: () => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+  private run<TResult>(workArg: (operationArg: IHueOperation) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
     this.assertOpen(signalArg);
-    if (this.#operations.size >= 32) throw new Error('Hue concurrent operation limit reached.');
-    const operation = Promise.resolve().then(() => { this.assertOpen(signalArg); return workArg(); });
+    const operation = this.#owner.runOperation(this.#context, this.#config.homeId, async (lease) => {
+      const deadlineAbort = new AbortController();
+      const deadline = performance.now() + this.#config.requestTimeoutMs;
+      const signal = AbortSignal.any([lease.signal, this.#lifetime.signal, deadlineAbort.signal, ...(signalArg ? [signalArg] : [])]);
+      const actual = new Set<Promise<unknown>>();
+      lease.own(async () => { while (actual.size) await Promise.allSettled([...actual]); });
+      const timer = setTimeout(() => deadlineAbort.abort(new Error('Hue request timed out.')), this.#config.requestTimeoutMs);
+      try { return await workArg({ lease, signal, deadline, actual }); }
+      finally { clearTimeout(timer); }
+    });
     this.#operations.add(operation);
     void operation.then(() => this.#operations.delete(operation), () => this.#operations.delete(operation));
     return operation;
   }
 
+  private async foreign<TResult>(operationArg: IHueOperation, workArg: () => Promise<TResult>): Promise<TResult> {
+    this.active(operationArg);
+    if (operationArg.actual.size >= 16) throw new Error('Hue actual callback capacity reached.');
+    const actual = Promise.resolve().then(() => { this.active(operationArg); return workArg(); });
+    operationArg.actual.add(actual);
+    void actual.then(() => operationArg.actual.delete(actual), () => operationArg.actual.delete(actual));
+    let abort: () => void = () => {};
+    const cancelled = new Promise<never>((_resolve, reject) => { abort = () => reject(this.cancelled(operationArg)); operationArg.signal.addEventListener('abort', abort, { once: true }); if (operationArg.signal.aborted) abort(); });
+    try { const value = await Promise.race([actual, cancelled]); this.active(operationArg); return value; }
+    catch { if (operationArg.signal.aborted || performance.now() >= operationArg.deadline) throw this.cancelled(operationArg); throw new Error('Hue operation failed.'); }
+    finally { operationArg.signal.removeEventListener('abort', abort); }
+  }
+
+  private active(operationArg: IHueOperation): void {
+    if (operationArg.signal.aborted || performance.now() >= operationArg.deadline || this.#destroyPromise) throw this.cancelled(operationArg);
+    operationArg.lease.assertOpen();
+  }
+  private cancelled(operationArg: IHueOperation): Error { return new Error(performance.now() >= operationArg.deadline || operationArg.signal.reason instanceof Error && operationArg.signal.reason.message === 'Hue request timed out.' ? 'Hue request timed out.' : 'Hue request cancelled.'); }
+  private credentialRequest(operationArg: IHueOperation): IHueCredentialRequest { return Object.freeze({ homeId: this.#context.homeId, origin: hueOrigin(this.#config), bridgeId: this.#config.bridgeId, credentialReference: this.#config.credentialReference, signal: operationArg.signal, deadline: operationArg.deadline }); }
+  private storeKey(): string { return `hue.credential.${encodeURIComponent(this.#config.credentialReference)}`; }
+  private async credential(operationArg: IHueOperation): Promise<string> {
+    const request = this.credentialRequest(operationArg);
+    if (this.#options.credentialProvider) return hueKey(await this.foreign(operationArg, () => this.#options.credentialProvider!.resolve(request)));
+    await this.foreign(operationArg, () => this.#store!.initialize({ signal: operationArg.signal }));
+    const envelope = hueData(await this.foreign(operationArg, () => this.#store!.get(this.storeKey())), ['version', 'homeId', 'origin', 'bridgeId', 'credentialReference', 'appKey']);
+    if (envelope.version !== 1 || envelope.homeId !== request.homeId || envelope.origin !== request.origin || envelope.bridgeId !== request.bridgeId || envelope.credentialReference !== request.credentialReference) throw new Error('Hue credential reference does not match the selected home and bridge.');
+    return hueKey(envelope.appKey);
+  }
+  private permission(resourceArg: 'config' | 'lights', idArg: string, fieldsArg: readonly string[]): void {
+    if (!this.#options.controlPermissions?.some((permission) => permission.resource === resourceArg && permission.resourceId === idArg && fieldsArg.every((field) => permission.fields.includes(field)))) throw new Error('Hue control requires exact owner authorization.');
+  }
+
   private assertOpen(abortSignalArg?: AbortSignal): void {
-    if (this.#destroyPromise || this.#lifetime.signal.aborted || abortSignalArg?.aborted) throw new Error('Hue client operation was cancelled or the client is closed.');
+    if (this.#destroyPromise || this.#lifetime.signal.aborted || this.#owner.signal.aborted || this.#context.abortSignal?.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.');
   }
 
-  private requestOptions(methodArg: string, pathArg: string, signalArg: AbortSignal, headersArg: Record<string, string> = {}): plugins.https.RequestOptions {
+  private requestOptions(methodArg: string, pathArg: string, signalArg: AbortSignal, headersArg: Record<string, string> = {}, keyArg?: 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 } };
+      headers: { ...(keyArg === undefined ? {} : { 'hue-application-key': keyArg }), accept: 'application/json', ...headersArg } };
   }
 
-  private async request(methodArg: string, pathArg: string, bodyArg?: unknown, abortSignalArg?: AbortSignal): Promise<unknown> {
+  private async request(methodArg: string, pathArg: string, bodyArg?: unknown, abortSignalArg?: AbortSignal, keyArg?: string, dispatchArg?: () => void): Promise<unknown> {
     this.assertOpen(abortSignalArg);
     const abort = new AbortController();
-    const signal = AbortSignal.any([this.#lifetime.signal, abort.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+    const signal = AbortSignal.any([this.#lifetime.signal, this.#owner.signal, abort.signal, ...(this.#context.abortSignal ? [this.#context.abortSignal] : []), ...(abortSignalArg ? [abortSignalArg] : [])]);
     const encoded = bodyArg === undefined ? undefined : JSON.stringify(bodyArg);
     let request: ReturnType<typeof plugins.https.request> | undefined;
     let resolveClosed: () => void = () => {};
@@ -292,7 +455,7 @@ export class HueClient {
       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) => {
+        }, keyArg), (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}.`));
@@ -316,6 +479,7 @@ export class HueClient {
         });
         request.once('error', () => rejectArg(new Error('Hue HTTPS request failed or was cancelled.')));
         request.once('close', () => { this.#connections.delete(connection); resolveClosed(); });
+        dispatchArg?.();
         request.end(encoded);
       });
     } finally {

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

@@ -1,45 +1,82 @@
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import { HueClient } from './hue.classes.client.js';
-import { hueBridgeId, hueRecord, normalizeHueConfig, normalizeHueHost } from './hue.validation.js';
-import type { IHueConfig } from './hue.types.js';
+import { HueClient, HuePairingError } from './hue.classes.client.js';
+import { captureHueOptions, hueBridgeId, hueData, hueKey, normalizeHueConfig, normalizeHueHost } from './hue.validation.js';
+import type { IHueConfig, IHueIntegrationOptions } from './hue.types.js';
 
 export class HueConfigFlow implements IConfigFlow<IHueConfig> {
+  readonly #options: Readonly<IHueIntegrationOptions>;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #scope: NativeIntegrationScope;
+  readonly #ownsOwner: boolean;
+  #terminal = false;
+  #submitted = false;
+
+  constructor(optionsArg: IHueIntegrationOptions = {}, ownerArg?: NativeIntegrationOwner) {
+    this.#options = captureHueOptions(optionsArg);
+    this.#ownsOwner = !ownerArg;
+    this.#owner = ownerArg ?? new NativeIntegrationOwner('hue', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.#scope = this.#owner.createFlowScope();
+  }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IHueConfig>> {
-    void contextArg;
-    const candidate = hueRecord(candidateArg);
+    const context = this.#scope.admit(contextArg);
+    if (this.#terminal) throw new Error('Hue config flow is closed.');
+    const candidate = hueData(candidateArg, ['id', 'source', 'host', 'port', 'name', 'integrationDomain', 'manufacturer', 'model', 'serialNumber', 'macAddress', 'metadata']);
     if (candidate.integrationDomain !== 'hue') throw new Error('Hue flow requires a Hue candidate.');
     const bridgeId = hueBridgeId(candidate.id) ? candidate.id : undefined;
     const port = candidate.port;
-    if (port !== undefined && typeof port !== 'number') throw new Error('Hue discovered port is invalid.');
+    if (port !== undefined && (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('Hue discovered port is invalid.');
     let host: string | undefined;
     try { host = normalizeHueHost(candidate.host); } catch { host = undefined; }
+    const submit = async (valuesArg: Record<string, unknown>): Promise<IConfigFlowStep<IHueConfig>> => {
+      if (this.#terminal || this.#submitted) return { kind: 'error', title: 'Hue flow closed', error: 'Hue config flow is closed or already submitting.' };
+      this.#submitted = true;
+      let paired = false;
+      let capturedValues: Record<string, unknown> | undefined;
+      try {
+        const values = hueData(valuesArg, ['homeId', 'bridgeId', 'host', 'credentialReference', 'appKey', 'trustedCa']);
+        if (values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('Hue form home does not match the host home.');
+        capturedValues = Object.freeze(values);
+        const config = normalizeHueConfig({ homeId: context.homeId, bridgeId: bridgeId ?? values.bridgeId as string,
+          host: host ?? values.host as string, port: port as number | undefined,
+          credentialReference: values.credentialReference as string, trustedCa: values.trustedCa === '' ? undefined : values.trustedCa as string | undefined });
+        const suppliedKey = values.appKey === undefined || values.appKey === '' ? undefined : hueKey(values.appKey);
+        const result = await this.#scope.run(context, 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(); });
+          if (!client.canCreateCredential) throw new Error('Hue flow requires credential creation by the selected provider or encrypted store.');
+          const key = suppliedKey ?? await client.acquireAppKey(undefined, lease.signal);
+          paired = !suppliedKey;
+          await client.createCredential(key, lease.signal);
+          lease.assertOpen();
+          return { kind: 'done', title: 'Hue bridge verified', config } as IConfigFlowStep<IHueConfig>;
+        });
+        this.#terminal = true;
+        await this.#scope.close();
+        return result;
+      } catch (error) {
+        if (error instanceof HuePairingError && error.linkButtonRequired && !paired) {
+          return { kind: 'wait', title: 'Press the Hue link button', description: 'Press the physical link button on the selected bridge, then retry.', submit: () => submit(capturedValues!) };
+        }
+        if (paired || error instanceof HuePairingError) { this.#terminal = true; await this.#scope.close(); }
+        return { kind: 'error', title: 'Hue bridge could not be verified', error: paired || error instanceof HuePairingError ? 'Hue pairing or credential creation was dispatched; do not replay it.' : 'Check the host home, bridge ID, HTTPS endpoint, trusted CA, credential reference and permissions. The bridge must support Hue API v2.' };
+      } finally { this.#submitted = false; }
+    };
     return {
       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.',
+      description: 'Select a credential reference. Press the physical link button to pair, or supply an existing application key for one-time insertion into the host credential store. Setup verifies TLS identity and live 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: 'credentialReference', label: 'Credential reference', type: 'text', required: true },
+        { name: 'appKey', label: 'Existing Hue app key (optional)', type: 'password' },
         { name: 'trustedCa', label: 'Trusted Hue CA certificate (PEM)', type: 'text' },
-      ],
-      submit: async (valuesArg) => {
-        let client: HueClient | undefined;
-        try {
-          const values = hueRecord(valuesArg);
-          if (Reflect.ownKeys(values).some((keyArg) => !['bridgeId', 'host', 'appKey', 'trustedCa'].includes(String(keyArg)))) throw new Error('Hue flow values contain unsupported fields.');
-          const config = normalizeHueConfig({ bridgeId: bridgeId ?? values.bridgeId as string,
-            host: host ?? values.host as string, port: port ?? 443,
-            appKey: values.appKey as string, trustedCa: values.trustedCa === '' ? undefined : values.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();
-        }
-      },
+      ], submit,
     };
   }
+
+  public destroy(): Promise<void> { this.#terminal = true; return this.#ownsOwner ? this.#owner.close() : this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#ownsOwner ? this.#owner.retryCleanup() : this.#scope.retryCleanup(); }
 }