@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/mqtt/mqtt.types.ts

@@ -18,6 +18,17 @@ export interface IMqttConfig {
   discoveryMessages?: IMqttMessage[];
   retainedMessages?: IMqttMessage[];
   entities?: IMqttEntityConfig[];
+  connectTimeoutMs?: number;
+  operationTimeoutMs?: number;
+  reconnectPeriodMs?: number;
+  maxMessageTopics?: number;
+  maxPayloadBytes?: number;
+  maxBufferedBytes?: number;
+}
+
+export interface IMqttConnectionState {
+  connected: boolean;
+  error?: Error;
 }
 
 export interface IMqttPublishOptions {
@@ -84,6 +95,8 @@ export interface IMqttEntityConfig {
   stateTopic?: string;
   commandTopic?: string;
   availabilityTopic?: string;
+  availability?: IMqttAvailability[];
+  availabilityMode?: 'all' | 'any' | 'latest';
   jsonAttributesTopic?: string;
   valueTemplate?: string;
   stateValueTemplate?: string;
@@ -101,6 +114,12 @@ export interface IMqttEntityConfig {
   rawConfig?: Record<string, unknown>;
 }
 
+export interface IMqttAvailability {
+  topic: string;
+  payloadAvailable?: string;
+  payloadNotAvailable?: string;
+}
+
 export interface IMqttManualEntry {
   host?: string;
   port?: number;

package/ts/integrations/mqtt/readme.md

@@ -0,0 +1,28 @@
+# Native MQTT runtime
+
+`MqttIntegration` connects directly to a broker over MQTT 3.1.1 TCP or TLS through MQTT.js. No Home Assistant server or access token is involved. Setup completes after broker connection and owned subscription acknowledgements. MQTT has no end marker for retained discovery replay; newly received discovery produces normalized events and later snapshots.
+
+Configuration accepts `host`, `port`, `protocol: 'mqtt' | 'mqtts'`, `username`, `password`, `clientId`, `clean`, and `keepalive`. TLS verifies certificates by default. Persistent sessions require an explicit client ID. Credentials remain in runtime configuration; this integration does not persist them.
+
+Discovery defaults to `homeassistant/#`. Both single-component and device discovery messages are supported, including abbreviations and topic bases. The latest configuration for each discovery topic replaces its predecessor; an empty payload removes it. State, availability, and attribute topics are subscribed dynamically and removed when no longer referenced. Availability lists support `all`, `any`, and `latest`. A disconnected broker marks its devices unavailable immediately.
+
+The adapter reads supported canonical platforms. Writes support default-schema power for switches, lights and fans, button press, cover open/close/stop, numeric and text values, and configured select options. JSON-schema lights, command templates, climate setpoints and other specialized control protocols are not advertised as writable. State templates support exactly `{{ value }}` and a single `value_json` property reference; unsupported templates yield an unknown value. Writes require one exact, available target with valid input; they do not modify readable state optimistically.
+
+`connectTimeoutMs` and `operationTimeoutMs` default to 7000; `reconnectPeriodMs` defaults to 1000. MQTT.js handles protocol reconnection and QoS handshakes. Connection readiness is published only after owned subscriptions are restored. QoS 0 completion confirms transport acceptance; QoS 1 and 2 completion confirms the broker protocol acknowledgement. These acknowledgements do not confirm that a physical device performed the action.
+
+Snapshots retain one latest message per topic, bounded by `maxMessageTopics` (4096), `maxPayloadBytes` (262144), and `maxBufferedBytes` (8388608). A limit violation closes the owned connection. These settings bound application snapshots, not broker retention or the protocol library's frame parser.
+
+`MqttClient` is reusable by native integrations:
+
+- `start(signal?)`, `publish(options, signal?)`, and `subscribe(filter, handler?, signal?)` are bounded operations.
+- `subscribe` callbacks receive only matching topics. Its returned asynchronous cleanup sends UNSUBSCRIBE after the final owner releases the filter.
+- `connected`, `isHealthy()`, and `onConnectionState(handler)` expose subscription readiness and connection loss.
+- `onMessage(handler)` observes messages on owned subscriptions without subscribing to the entire broker.
+- `getSnapshot(signal?)` returns current discovery and state.
+- `destroy()` closes resources and is terminal and idempotent.
+
+Abort or timeout closes the physical connection that owns the operation before rejection; an explicit subsequent `start()` can establish a fresh connection. A stale operation cannot close a later connection generation. Subscriber cleanup is independent of transport destruction.
+
+For an ecosystem that owns its own MQTT topics, set `discovery: false`, `birthMessage: false`, and `willMessage: false`, then subscribe only its selected topics. Fixture snapshots remain supported through `entities`, `discoveryMessages`, and `retainedMessages`; they do not claim a healthy broker connection.
+
+References: [MQTT.js 5.16.0](https://github.com/mqttjs/MQTT.js/tree/v5.16.0), [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/), and [MQTT 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html).

package/ts/integrations/nanoleaf/nanoleaf.classes.client.ts

@@ -1,280 +1,146 @@
-import type {
-  INanoleafAuthTokenResult,
-  INanoleafConfig,
-  INanoleafControllerInfo,
-  INanoleafEffects,
-  INanoleafEffectsCommand,
-  INanoleafPanelLayout,
-  INanoleafRhythmInfo,
-  INanoleafSnapshot,
-  INanoleafState,
-  INanoleafStateCommand,
-} from './nanoleaf.types.js';
-
-const DEFAULT_NANOLEAF_PORT = 16021;
+import * as plugins from '../../plugins.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import { createNanoleafCredentialStore, nanoleafCredentialKey, readNanoleafCredential } from './nanoleaf.credentials.js';
+import type { INanoleafConfig, INanoleafIntegrationOptions, INanoleafSnapshot, INanoleafWriteResult } from './nanoleaf.types.js';
+import { normalizeNanoleafConfig } from './nanoleaf.validation.js';
 
 export class NanoleafClient {
-  constructor(private readonly config: INanoleafConfig) {}
-
-  public async getSnapshot(): Promise<INanoleafSnapshot> {
-    if (this.config.snapshot) {
-      return this.normalizeSnapshot(this.config.snapshot);
-    }
-
-    if (this.canRequest()) {
-      const controllerInfo = await this.requestJson<INanoleafControllerInfo>(this.authenticatedPath(''));
-      return this.normalizeSnapshot({
-        controllerInfo,
-        state: controllerInfo.state ?? {},
-        effects: controllerInfo.effects ?? {},
-        panelLayout: controllerInfo.panelLayout,
-        rhythm: controllerInfo.rhythm,
-      });
-    }
-
-    return this.normalizeSnapshot({
-      controllerInfo: this.config.controllerInfo ?? this.defaultControllerInfo(),
-      state: this.config.state ?? this.config.controllerInfo?.state ?? {},
-      effects: this.config.effects ?? this.config.controllerInfo?.effects ?? {},
-      panelLayout: this.config.panelLayout ?? this.config.controllerInfo?.panelLayout,
-      rhythm: this.config.rhythm ?? this.config.controllerInfo?.rhythm,
-    });
-  }
-
-  public async getControllerInfo(): Promise<INanoleafControllerInfo> {
-    return (await this.getSnapshot()).controllerInfo;
-  }
-
-  public async getState(): Promise<INanoleafState> {
-    if (this.config.snapshot || this.config.state || this.config.controllerInfo?.state || !this.canRequest()) {
-      return (await this.getSnapshot()).state;
-    }
-    return this.requestJson<INanoleafState>(this.authenticatedPath('/state'));
-  }
-
-  public async getEffects(): Promise<INanoleafEffects> {
-    if (this.config.snapshot || this.config.effects || this.config.controllerInfo?.effects || !this.canRequest()) {
-      return (await this.getSnapshot()).effects;
-    }
-    return this.requestJson<INanoleafEffects>(this.authenticatedPath('/effects'));
-  }
-
-  public async getPanelLayout(): Promise<INanoleafPanelLayout | undefined> {
-    return (await this.getSnapshot()).panelLayout;
-  }
-
-  public async getRhythm(): Promise<INanoleafRhythmInfo | undefined> {
-    return (await this.getSnapshot()).rhythm;
-  }
-
-  public async turnOn(): Promise<void> {
-    await this.setState({ on: { value: true } });
-  }
-
-  public async turnOff(transitionArg?: number): Promise<void> {
-    if (transitionArg === undefined) {
-      await this.setState({ on: { value: false } });
-      return;
-    }
-    await this.setState({ on: { value: false }, brightness: { value: 0, duration: transitionArg } });
-  }
-
-  public async setBrightness(percentArg: number, transitionArg?: number): Promise<void> {
-    await this.setState({
-      brightness: {
-        value: this.clamp(Math.round(percentArg), 0, 100),
-        duration: transitionArg,
+  readonly #config: Readonly<INanoleafConfig>;
+  readonly #protocol: plugins.ecobridgeDeviceManager.NanoleafProtocol;
+  readonly #ownsStore: boolean;
+  readonly #lifetime = new AbortController();
+  readonly #operations = new Set<Promise<unknown>>();
+  #store?: NoSqlConfigStore;
+  #healthy = false;
+  #closed = false;
+  #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
+  #protocolClosed = false;
+  #removeParentAbort: () => void = () => undefined;
+
+  constructor(configArg: INanoleafConfig, ownerArg?: INanoleafIntegrationOptions | NoSqlConfigStore, signalArg?: AbortSignal, homeIdArg?: string) {
+    this.#config = normalizeNanoleafConfig(configArg);
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Nanoleaf lifetime signal must be an AbortSignal.');
+    if (homeIdArg === undefined) throw new TypeError('Nanoleaf client requires the admitted host home.');
+    const store = createNanoleafCredentialStore(this.#config, homeIdArg, ownerArg);
+    this.#store = store.store;
+    this.#ownsStore = store.owned;
+    this.#protocol = new plugins.ecobridgeDeviceManager.NanoleafProtocol({
+      origin: this.#config.origin, expectedSerialNumber: this.#config.expectedSerialNumber,
+      expectedModel: this.#config.expectedModel, allowUnencryptedHttp: this.#config.allowUnencryptedHttp,
+      ca: this.#config.certificateAuthority, timeoutMs: this.#config.timeoutMs,
+      maxResponseBytes: this.#config.maxResponseBytes, maxPendingOperations: this.#config.maxPendingOperations,
+      getAuthToken: async (signal) => {
+        signal.throwIfAborted();
+        const currentStore = this.#store;
+        if (!currentStore) throw new Error('Nanoleaf client is destroyed.');
+        await currentStore.initialize({ signal });
+        signal.throwIfAborted();
+        const credential: unknown = await currentStore.get(nanoleafCredentialKey(this.#config));
+        signal.throwIfAborted();
+        return readNanoleafCredential(this.#config, credential);
       },
     });
-  }
-
-  public async setHue(hueArg: number): Promise<void> {
-    await this.setState({ hue: { value: this.clamp(Math.round(hueArg), 0, 360) } });
-  }
-
-  public async setSaturation(saturationArg: number): Promise<void> {
-    await this.setState({ sat: { value: this.clamp(Math.round(saturationArg), 0, 100) } });
-  }
-
-  public async setColorTemperature(kelvinArg: number): Promise<void> {
-    await this.setState({ ct: { value: Math.round(kelvinArg) } });
-  }
-
-  public async setState(stateArg: INanoleafStateCommand): Promise<void> {
-    this.applyStatePatch(stateArg);
-    if (this.canRequest()) {
-      await this.requestJson<void>(this.authenticatedPath('/state'), {
-        method: 'PUT',
-        body: stateArg,
-      });
-      return;
-    }
-    this.assertFixtureMode();
-  }
-
-  public async setEffect(effectArg: string): Promise<void> {
-    this.applyEffectsPatch({ select: effectArg });
-    if (this.canRequest()) {
-      await this.requestJson<void>(this.authenticatedPath('/effects'), {
-        method: 'PUT',
-        body: { select: effectArg },
-      });
-      return;
-    }
-    this.assertFixtureMode();
-  }
-
-  public async writeEffectsCommand(commandArg: INanoleafEffectsCommand): Promise<void> {
-    if (this.canRequest()) {
-      await this.requestJson<void>(this.authenticatedPath('/effects'), {
-        method: 'PUT',
-        body: { write: commandArg },
-      });
-      return;
-    }
-    this.assertFixtureMode();
-  }
-
-  public async identify(): Promise<void> {
-    if (this.canRequest()) {
-      await this.requestJson<void>(this.authenticatedPath('/identify'), { method: 'PUT' });
-      return;
+    if (signalArg) {
+      const aborted = (): void => { void this.destroy(); };
+      signalArg.addEventListener('abort', aborted, { once: true });
+      this.#removeParentAbort = () => signalArg.removeEventListener('abort', aborted);
+      if (signalArg.aborted) aborted();
     }
-    this.assertFixtureMode();
-  }
-
-  public async createAuthToken(): Promise<INanoleafAuthTokenResult> {
-    return {
-      success: false,
-      error: 'Nanoleaf pairing/token generation is not implemented. Put the controller in pairing mode and provide an existing authToken.',
-    };
   }
 
-  public async destroy(): Promise<void> {}
+  public isHealthy(): boolean { return this.#healthy && !this.#closed; }
 
-  private normalizeSnapshot(snapshotArg: INanoleafSnapshot): INanoleafSnapshot {
-    const controllerInfo = snapshotArg.controllerInfo;
-    const state = snapshotArg.state ?? controllerInfo.state ?? {};
-    const effects = snapshotArg.effects ?? controllerInfo.effects ?? {};
-    const panelLayout = snapshotArg.panelLayout ?? controllerInfo.panelLayout;
-    const rhythm = snapshotArg.rhythm ?? controllerInfo.rhythm;
-    controllerInfo.state = state;
-    controllerInfo.effects = effects;
-    controllerInfo.panelLayout = panelLayout;
-    controllerInfo.rhythm = rhythm;
-    return { controllerInfo, state, effects, panelLayout, rhythm };
-  }
-
-  private applyStatePatch(stateArg: INanoleafStateCommand): void {
-    const state = this.ensureMutableState();
-    if (stateArg.on) {
-      state.on = { ...state.on, ...stateArg.on };
-    }
-    if (stateArg.brightness) {
-      state.brightness = { ...state.brightness, ...stateArg.brightness };
-    }
-    if (stateArg.hue) {
-      state.hue = { ...state.hue, ...stateArg.hue };
-    }
-    if (stateArg.sat) {
-      state.sat = { ...state.sat, ...stateArg.sat };
-    }
-    if (stateArg.ct) {
-      state.ct = { ...state.ct, ...stateArg.ct };
-    }
+  public getSnapshot(signalArg?: AbortSignal): Promise<INanoleafSnapshot> {
+    return this.#run(async (signal) => this.#snapshot(await this.#protocol.readSnapshot({ signal })), signalArg);
   }
 
-  private applyEffectsPatch(effectsArg: Partial<INanoleafEffects>): void {
-    const effects = this.ensureMutableEffects();
-    Object.assign(effects, effectsArg);
+  public setPower(powerArg: boolean, signalArg?: AbortSignal): Promise<INanoleafWriteResult> {
+    return this.#setState({ power: powerArg }, signalArg);
   }
 
-  private ensureMutableState(): INanoleafState {
-    if (this.config.snapshot) {
-      this.config.snapshot.state ||= {};
-      this.config.snapshot.controllerInfo.state = this.config.snapshot.state;
-      return this.config.snapshot.state;
-    }
-    this.config.state ||= this.config.controllerInfo?.state ?? {};
-    if (this.config.controllerInfo) {
-      this.config.controllerInfo.state = this.config.state;
-    }
-    return this.config.state;
+  public setBrightness(brightnessArg: number, signalArg?: AbortSignal): Promise<INanoleafWriteResult> {
+    return this.#setState({ brightness: brightnessArg }, signalArg);
   }
 
-  private ensureMutableEffects(): INanoleafEffects {
-    if (this.config.snapshot) {
-      this.config.snapshot.effects ||= {};
-      this.config.snapshot.controllerInfo.effects = this.config.snapshot.effects;
-      return this.config.snapshot.effects;
-    }
-    this.config.effects ||= this.config.controllerInfo?.effects ?? {};
-    if (this.config.controllerInfo) {
-      this.config.controllerInfo.effects = this.config.effects;
-    }
-    return this.config.effects;
+  public setColorTemperature(kelvinArg: number, signalArg?: AbortSignal): Promise<INanoleafWriteResult> {
+    return this.#setState({ colorTemperatureKelvin: kelvinArg }, signalArg);
   }
 
-  private assertFixtureMode(): void {
-    if (!this.hasFixtureData()) {
-      throw new Error('Nanoleaf host and authToken are required when snapshot/manual config data is not provided.');
-    }
+  #setState(commandArg: plugins.ecobridgeDeviceManager.INanoleafStateCommand, signalArg?: AbortSignal): Promise<INanoleafWriteResult> {
+    return this.#run(async (signal) => {
+      const result = await this.#protocol.setState(commandArg, { signal });
+      return Object.freeze({ acceptance: result.acceptance, snapshot: this.#snapshot(result.snapshot) });
+    }, signalArg);
   }
 
-  private hasFixtureData(): boolean {
-    return Boolean(this.config.snapshot || this.config.controllerInfo || this.config.state || this.config.effects || this.config.panelLayout || this.config.rhythm);
+  public selectEffect(effectArg: string, signalArg?: AbortSignal): Promise<INanoleafWriteResult> {
+    return this.#run(async (signal) => {
+      const result = await this.#protocol.selectEffect(effectArg, { signal });
+      return Object.freeze({ acceptance: result.acceptance, snapshot: this.#snapshot(result.snapshot) });
+    }, signalArg);
   }
 
-  private canRequest(): boolean {
-    return Boolean(this.config.host && this.authToken());
+  public destroy(): Promise<void> {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closed = true;
+    this.#healthy = false;
+    this.#removeParentAbort();
+    this.#closePromise = Promise.resolve().then(() => this.#drainCleanup());
+    this.#lifetime.abort();
+    return this.#closePromise;
   }
 
-  private authToken(): string | undefined {
-    return this.config.authToken || this.config.token;
+  /** Explicitly retries retained cleanup; no device operation is replayed. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#closePromise) return this.destroy();
+    if (this.#retryPromise) return this.#retryPromise;
+    const retry = this.#closePromise.then(() => undefined, () => this.#drainCleanup(true));
+    this.#retryPromise = retry;
+    void retry.finally(() => { if (this.#retryPromise === retry) this.#retryPromise = undefined; }).catch(() => undefined);
+    return retry;
   }
 
-  private authenticatedPath(pathArg: string): string {
-    const token = this.authToken();
-    if (!token) {
-      throw new Error('Nanoleaf authToken is required for local HTTP requests.');
-    }
-    return `/api/v1/${encodeURIComponent(token)}${pathArg}`;
+  async #drainCleanup(retryArg = false): Promise<void> {
+    const results = await Promise.allSettled([
+      Promise.resolve().then(async () => {
+        if (!this.#protocolClosed) {
+          await this.#protocol.close();
+          this.#protocolClosed = true;
+        }
+      }),
+      Promise.allSettled([...this.#operations]),
+    ]);
+    if (this.#ownsStore && this.#store) {
+      results.push(...await Promise.allSettled([Promise.resolve().then(async () => {
+        if (retryArg) await this.#store?.retryCleanup();
+        else await this.#store?.close();
+        this.#store = undefined;
+      })]));
+    } else if (this.#protocolClosed) this.#store = undefined;
+    const failures = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason as unknown] : []);
+    if (failures.length) throw new AggregateError(failures, 'Nanoleaf client cleanup failed.');
   }
 
-  private async requestJson<TResult>(pathArg: string, optionsArg: { method?: string; body?: unknown } = {}): Promise<TResult> {
-    const response = await globalThis.fetch(`${this.baseUrl()}${pathArg}`, {
-      method: optionsArg.method ?? (optionsArg.body === undefined ? 'GET' : 'POST'),
-      headers: optionsArg.body === undefined ? undefined : { 'content-type': 'application/json' },
-      body: optionsArg.body === undefined ? undefined : JSON.stringify(optionsArg.body),
-    });
-    const text = await response.text();
-    if (!response.ok) {
-      throw new Error(`Nanoleaf request ${pathArg} failed with HTTP ${response.status}: ${text}`);
-    }
-    if (!text) {
-      return undefined as TResult;
-    }
-    return JSON.parse(text) as TResult;
+  #snapshot(snapshotArg: plugins.ecobridgeDeviceManager.INanoleafSnapshot): INanoleafSnapshot {
+    return Object.freeze({ ...snapshotArg, homeId: this.#config.homeId, origin: this.#config.origin });
   }
 
-  private baseUrl(): string {
-    if (!this.config.host) {
-      throw new Error('Nanoleaf host is required for local HTTP requests.');
+  #run<TResult>(workArg: (signalArg: AbortSignal) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    if (this.#closed) return Promise.reject(new plugins.ecobridgeDeviceManager.NanoleafProtocolError('CLOSED', 'Nanoleaf client is destroyed.'));
+    if (this.#operations.size >= (this.#config.maxPendingOperations ?? 32)) {
+      return Promise.reject(new plugins.ecobridgeDeviceManager.NanoleafProtocolError('BUSY', 'Nanoleaf client operation capacity is exhausted.'));
     }
-    const protocol = this.config.protocol ?? 'http';
-    const port = this.config.port ?? DEFAULT_NANOLEAF_PORT;
-    return `${protocol}://${this.config.host}:${port}`;
-  }
-
-  private defaultControllerInfo(): INanoleafControllerInfo {
-    return {
-      name: 'Nanoleaf',
-      manufacturer: 'Nanoleaf',
-      model: 'Nanoleaf Controller',
-    };
-  }
-
-  private clamp(valueArg: number, minArg: number, maxArg: number): number {
-    return Math.max(minArg, Math.min(maxArg, valueArg));
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) return Promise.reject(new TypeError('Nanoleaf operation signal must be an AbortSignal.'));
+    const signal = signalArg ? AbortSignal.any([this.#lifetime.signal, signalArg]) : this.#lifetime.signal;
+    const operation = Promise.resolve().then(async () => {
+      if (signal.aborted) throw new plugins.ecobridgeDeviceManager.NanoleafProtocolError('ABORTED', 'Nanoleaf operation was cancelled before admission.');
+      return workArg(signal);
+    }).then((resultArg) => { this.#healthy = !this.#closed && !signal.aborted; return resultArg; }, (errorArg: unknown) => {
+      this.#healthy = false;
+      throw errorArg;
+    }).finally(() => this.#operations.delete(operation));
+    this.#operations.add(operation);
+    return operation;
   }
 }

package/ts/integrations/nanoleaf/nanoleaf.classes.configflow.ts

@@ -1,29 +1,100 @@
+import * as plugins from '../../plugins.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { INanoleafConfig } from './nanoleaf.types.js';
-
-const DEFAULT_NANOLEAF_PORT = 16021;
+import { createNanoleafCredentialStore, nanoleafCredential, nanoleafCredentialKey } from './nanoleaf.credentials.js';
+import type { INanoleafConfig, INanoleafIntegrationOptions } from './nanoleaf.types.js';
+import { nanoleafKeys, nanoleafRecord, normalizeNanoleafConfig } from './nanoleaf.validation.js';
 
 export class NanoleafConfigFlow implements IConfigFlow<INanoleafConfig> {
+  readonly #scope: NativeIntegrationScope;
+  readonly #credentials?: INanoleafIntegrationOptions;
+
+  constructor(ownerArg?: INanoleafIntegrationOptions, scopeArg?: NativeIntegrationScope) {
+    this.#credentials = ownerArg && Object.freeze({ db: ownerArg.db, keyProvider: ownerArg.keyProvider });
+    this.#scope = scopeArg ?? new NativeIntegrationOwner('nanoleaf', { homeId: ownerArg?.homeId }).createFlowScope();
+  }
+
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<INanoleafConfig>> {
-    void contextArg;
+    if (candidateArg.integrationDomain !== undefined && candidateArg.integrationDomain !== 'nanoleaf') {
+      return { kind: 'error', error: 'Nanoleaf config flow requires a Nanoleaf candidate.' };
+    }
+    let context: INativeAdmissionContext;
+    try { context = this.#scope.admit(contextArg); }
+    catch { return { kind: 'error', error: 'Nanoleaf config flow requires an open instance and the explicit matching host home.' }; }
     return {
-      kind: 'form',
-      title: 'Connect Nanoleaf',
-      description: 'Configure the local Nanoleaf HTTP endpoint with an existing auth token from the controller.',
+      kind: 'form', title: 'Connect selected Nanoleaf controller',
+      description: 'Provide the selected local IPv4 origin, serial and documented model. An existing token is validated and stored encrypted for the host-selected home; plaintext vendor HTTP requires explicit consent.',
       fields: [
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'Port', type: 'number', required: true },
-        { name: 'authToken', label: 'Auth token', type: 'password', required: true },
+        { name: 'origin', label: 'Selected HTTP(S) IPv4 origin', type: 'text', required: true },
+        { name: 'expectedSerialNumber', label: 'Expected serial number', type: 'text', required: true },
+        { name: 'expectedModel', label: 'Expected documented controller model', type: 'text', required: true },
+        { name: 'credentialKey', label: 'New encrypted credential reference', type: 'text', required: true },
+        { name: 'authToken', label: 'Existing controller token', type: 'password', required: true },
+        { name: 'allowUnencryptedHttp', label: 'Consent to plaintext local HTTP', type: 'boolean' },
+        { name: 'certificateAuthority', label: 'Trusted HTTPS controller PEM certificate', type: 'text' },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'Nanoleaf configured',
-        config: {
-          host: String(valuesArg.host || candidateArg.host || ''),
-          port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port || DEFAULT_NANOLEAF_PORT,
-          authToken: String(valuesArg.authToken || ''),
-        },
-      }),
+      submit: (valuesArg) => this.#submit(valuesArg, context),
     };
   }
+
+  async #submit(valuesArg: Record<string, unknown>, contextArg: INativeAdmissionContext): Promise<IConfigFlowStep<INanoleafConfig>> {
+    let config: Readonly<INanoleafConfig>;
+    let credential: ReturnType<typeof nanoleafCredential>;
+    try {
+      const values = nanoleafRecord(valuesArg, 'config flow values');
+      nanoleafKeys(values, ['homeId', 'origin', 'expectedSerialNumber', 'expectedModel', 'credentialKey', 'authToken',
+        'allowUnencryptedHttp', 'certificateAuthority', 'timeoutMs', 'maxResponseBytes', 'maxPendingOperations']);
+      if (values.homeId !== undefined && values.homeId !== contextArg.homeId) throw new TypeError('Nanoleaf form home conflicts with the host home.');
+      const { authToken, ...configuration } = values;
+      config = normalizeNanoleafConfig({ ...configuration, homeId: contextArg.homeId });
+      credential = nanoleafCredential(config, authToken);
+      this.#scope.admit(contextArg, config.homeId);
+    } catch { return { kind: 'error', error: 'Nanoleaf config flow values or host home are invalid, cancelled or closed.' }; }
+    return this.#scope.run(contextArg, config.homeId, async (leaseArg): Promise<IConfigFlowStep<INanoleafConfig>> => {
+      try {
+        const handle = createNanoleafCredentialStore(config, leaseArg.context.homeId, leaseArg.context.configStore ?? this.#credentials);
+        let protocol: plugins.ecobridgeDeviceManager.NanoleafProtocol | undefined;
+        let protocolClosed = false;
+        let storeClosed = !handle.owned;
+        let firstStoreCleanup = true;
+        // One admitted credential-validation operation owns its protocol and optional store.
+        leaseArg.own(async () => {
+          const results = await Promise.allSettled([
+            Promise.resolve().then(async () => {
+              if (protocol && !protocolClosed) { await protocol.close(); protocolClosed = true; }
+            }),
+            Promise.resolve().then(async () => {
+              if (!storeClosed) {
+                // Failed lease callbacks run again only on explicit owner cleanup retry.
+                if (firstStoreCleanup) { firstStoreCleanup = false; await handle.store.close(); }
+                else await handle.store.retryCleanup();
+                storeClosed = true;
+              }
+            }),
+          ]);
+          const failures = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason as unknown] : []);
+          if (failures.length) throw new AggregateError(failures, 'Nanoleaf flow resource cleanup failed.');
+        });
+        await handle.store.initialize({ signal: leaseArg.signal });
+        leaseArg.assertOpen();
+        protocol = new plugins.ecobridgeDeviceManager.NanoleafProtocol({ origin: config.origin,
+          expectedSerialNumber: config.expectedSerialNumber, expectedModel: config.expectedModel,
+          getAuthToken: () => credential.authToken, allowUnencryptedHttp: config.allowUnencryptedHttp,
+          ca: config.certificateAuthority, timeoutMs: config.timeoutMs, maxResponseBytes: config.maxResponseBytes,
+          maxPendingOperations: config.maxPendingOperations });
+        await protocol.readSnapshot({ signal: leaseArg.signal });
+        leaseArg.assertOpen();
+        await handle.store.create(nanoleafCredentialKey(config), credential);
+        leaseArg.assertOpen();
+        return { kind: 'done', title: 'Nanoleaf identity verified and token stored encrypted', config };
+      } catch { return { kind: 'error', error: 'Nanoleaf controller validation or encrypted credential persistence failed.' }; }
+    }).catch((errorArg: unknown): IConfigFlowStep<INanoleafConfig> => {
+      if (errorArg instanceof AggregateError) throw errorArg;
+      return { kind: 'error', error: 'Nanoleaf config flow was cancelled or closed.' };
+    });
+  }
 }