@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/esphome/esphome.classes.client.ts

@@ -1,10 +1,15 @@
 import * as plugins from '../../plugins.js';
-import type { IEsphomeClientCommand, IEsphomeCommandResult, IEsphomeConfig, IEsphomeEntityDescriptor, IEsphomeEntityState, IEsphomeEvent, IEsphomeSnapshot } from './esphome.types.js';
-import { esphomeDefaultNativeApiPort } from './esphome.types.js';
+import type { IEsphomeClientCommand, IEsphomeCommandResult, IEsphomeConfig, IEsphomeEntityDescriptor, IEsphomeEntityState, IEsphomeEvent, IEsphomeSnapshot, TEsphomeCredentials } from './esphome.types.js';
+import { captureEsphomeConfig, captureEsphomeCredentials, esphomeMac } from './esphome.validation.js';
 
 type TEsphomeEventHandler = (eventArg: IEsphomeEvent) => void;
 type TNativeClient = plugins.esphomeNativeApi.EspHomeClient;
 type TNativeEntity = plugins.esphomeNativeApi.Entity;
+interface IEsphomeCleanup {
+  readonly cleanup: () => void;
+  failed: boolean;
+  promise?: Promise<void>;
+}
 
 const readablePlatforms = new Set(['light', 'switch', 'fan', 'cover', 'climate', 'number', 'select', 'text', 'sensor', 'binary_sensor', 'text_sensor']);
 const writablePlatforms = new Set(['light', 'switch', 'fan', 'cover', 'number', 'select', 'text']);
@@ -12,12 +17,12 @@ const writablePlatforms = new Set(['light', 'switch', 'fan', 'cover', 'number',
 export class EsphomeClient {
   private readonly connection: EsphomeNativeApiConnection;
 
-  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient) {
-    this.connection = new EsphomeNativeApiConnection(configArg, nativeClientArg);
+  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient, credentialsArg: TEsphomeCredentials = {}) {
+    this.connection = new EsphomeNativeApiConnection(configArg, nativeClientArg, credentialsArg);
   }
 
-  public async connectLive(signalArg?: AbortSignal): Promise<void> {
-    await this.connection.connect(signalArg);
+  public connectLive(signalArg?: AbortSignal): Promise<void> {
+    return this.connection.connect(signalArg);
   }
 
   public isHealthy(): boolean {
@@ -28,16 +33,20 @@ export class EsphomeClient {
     return this.connection.getSnapshot();
   }
 
-  public onEvent(handlerArg: TEsphomeEventHandler): () => void {
-    return this.connection.onEvent(handlerArg);
+  public onEvent(handlerArg: TEsphomeEventHandler, signalArg?: AbortSignal): () => void {
+    return this.connection.onEvent(handlerArg, signalArg);
   }
 
   public async sendCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
     return this.connection.sendCommand(commandArg, signalArg);
   }
 
-  public async destroy(): Promise<void> {
-    await this.connection.destroy();
+  public destroy(): Promise<void> {
+    return this.connection.destroy();
+  }
+
+  public retryCleanup(): Promise<void> {
+    return this.connection.retryCleanup();
   }
 }
 
@@ -48,83 +57,88 @@ export class EsphomeNativeApiConnection {
   private readonly setupTimeoutMs: number;
   private readonly commandTimeoutMs: number;
   private readonly requireEncryption: boolean;
+  private readonly config: IEsphomeConfig;
   private readonly handlers = new Set<TEsphomeEventHandler>();
-  private readonly subscriptions: Disposable[] = [];
+  private readonly cleanup = new Set<IEsphomeCleanup>();
+  private readonly operations = new Set<Promise<unknown>>();
   private readonly pendingCommands = new Set<string>();
   private readonly lifetime = new AbortController();
   private ready = false;
   private connecting = false;
   private destroyed = false;
+  private subscriptionsStarted = false;
+  private identityMismatch = false;
+  private closePromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
 
-  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient) {
-    const manual = configArg.manualEntries?.[0];
-    if (configArg.password || manual?.password) {
-      throw new Error('ESPHome legacy API password authentication is unsupported. Upgrade the device to ESPHome 2025.10 or newer and configure native API encryption.');
-    }
-    if (configArg.snapshot || configArg.entities || configArg.states || configArg.services || configArg.commandExecutor) {
-      throw new Error('ESPHome live setup does not accept injected snapshots, states, services, or command executors.');
-    }
-    if (configArg.manualEntries && configArg.manualEntries.length > 1) {
-      throw new Error('Configure each ESPHome native API device as a separate integration instance.');
-    }
-    this.host = (configArg.host || manual?.host || '').trim();
-    if (!this.host || /\s/.test(this.host)) {
-      throw new Error('ESPHome native API requires a valid host.');
-    }
-    this.port = configArg.port ?? manual?.port ?? esphomeDefaultNativeApiPort;
-    if (!Number.isInteger(this.port) || this.port < 1 || this.port > 65535) {
-      throw new Error('ESPHome native API port must be an integer from 1 through 65535.');
-    }
-    this.setupTimeoutMs = this.timeout(configArg.initialSnapshotTimeoutMs, 15000);
-    this.commandTimeoutMs = this.timeout(configArg.commandTimeoutMs, 5000);
-    const keys = [configArg.encryptionKey, configArg.noisePsk, manual?.encryptionKey, manual?.noisePsk].filter((valueArg): valueArg is string => valueArg !== undefined);
-    if (new Set(keys).size > 1) throw new Error('ESPHome encryption key configuration is conflicting.');
-    const key = keys[0];
-    if (key !== undefined && (!/^[A-Za-z0-9+/]{43}=$/.test(key) || Buffer.from(key, 'base64').length !== 32 || Buffer.from(key, 'base64').toString('base64') !== key)) {
-      throw new Error('ESPHome encryption key must be a canonical base64-encoded 32-byte key.');
-    }
-    this.requireEncryption = key !== undefined;
+  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient, credentialsArg: TEsphomeCredentials = {}) {
+    this.config = captureEsphomeConfig(configArg);
+    const credentials = captureEsphomeCredentials(credentialsArg);
+    this.host = this.config.host;
+    this.port = this.config.port ?? 6053;
+    this.setupTimeoutMs = this.config.initialSnapshotTimeoutMs ?? 15000;
+    this.commandTimeoutMs = this.config.commandTimeoutMs ?? 5000;
+    this.requireEncryption = credentials.psk != null;
     this.native = nativeClientArg ?? new plugins.esphomeNativeApi.EspHomeClient({
       host: this.host,
       port: this.port,
-      psk: key,
-      serverName: configArg.deviceName || manual?.deviceName,
+      psk: credentials.psk,
+      serverName: this.config.deviceName,
       connectTimeoutMs: this.setupTimeoutMs,
     });
-    this.subscriptions.push(
-      this.native.on('telemetry', (eventArg) => {
-        this.refreshReadiness();
-        this.emit({ type: 'state_changed', entityId: this.eventEntityId(eventArg), data: eventArg });
-      }),
-      this.native.onHealthChange((healthArg) => {
-        if (healthArg.state === 'connected' && this.requireEncryption && !healthArg.encrypted) {
-          this.ready = false;
-          this.native.disconnect();
-          this.emit({ type: 'error', data: { message: 'ESPHome encryption is required; the plaintext session was rejected.' } });
-          return;
-        }
-        this.refreshReadiness();
-        this.emit({ type: 'availability_changed', data: { available: this.isHealthy() } });
-      }),
-    );
+    // Construction is inert: own the native client before invoking any subscription callbacks.
+    this.cleanup.add({ cleanup: () => this.native.disconnect(), failed: false });
+  }
+
+  private startSubscriptions(): void {
+    if (this.subscriptionsStarted) return;
+    this.subscriptionsStarted = true;
+    const telemetry = this.native.on('telemetry', (eventArg) => {
+      this.refreshReadiness();
+      if (!this.identityMismatch) this.emit({ type: 'state_changed', entityId: this.eventEntityId(eventArg), data: eventArg });
+    });
+    this.cleanup.add({ cleanup: () => telemetry[Symbol.dispose](), failed: false });
+    this.lifetime.signal.throwIfAborted();
+    const health = this.native.onHealthChange((healthArg) => {
+      if (healthArg.state === 'connected' && this.requireEncryption && !healthArg.encrypted) {
+        this.ready = false;
+        this.native.disconnect();
+        this.emit({ type: 'error', data: { message: 'ESPHome encryption is required; the plaintext session was rejected.' } });
+        return;
+      }
+      this.refreshReadiness();
+      this.emit({ type: 'availability_changed', data: { available: this.isHealthy() } });
+    });
+    this.cleanup.add({ cleanup: () => health[Symbol.dispose](), failed: false });
+    this.lifetime.signal.throwIfAborted();
   }
 
-  public async connect(signalArg?: AbortSignal): Promise<void> {
-    if (this.destroyed || this.connecting || this.isHealthy()) throw new Error('ESPHome connection is destroyed, already connecting, or already connected.');
+  public connect(signalArg?: AbortSignal): Promise<void> {
+    if (this.destroyed || this.connecting || this.isHealthy()) return Promise.reject(new Error('ESPHome connection is destroyed, already connecting, or already connected.'));
     this.connecting = true;
-    const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.setupTimeoutMs), ...(signalArg ? [signalArg] : [])]);
-    try {
-      signal.throwIfAborted();
-      await this.native.connect({ signal });
-      if (this.requireEncryption && !this.native.health().encrypted) throw new Error('ESPHome encryption is required; the plaintext session was rejected.');
-      if (this.native.deviceInfo()?.usesPassword) throw new Error('ESPHome legacy API password authentication is unsupported.');
-      await this.waitForInitialStates(signal);
-    } catch (error) {
-      await this.destroy();
-      throw error;
-    } finally {
-      this.connecting = false;
-    }
+    const operation = this.track(async () => {
+      const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.setupTimeoutMs), ...(signalArg ? [signalArg] : [])]);
+      try {
+        signal.throwIfAborted();
+        this.startSubscriptions();
+        await this.native.connect({ signal });
+        if (this.requireEncryption && !this.native.health().encrypted) throw new Error('ESPHome encryption is required; the plaintext session was rejected.');
+        if (this.native.deviceInfo()?.usesPassword) throw new Error('ESPHome legacy API password authentication is unsupported.');
+        this.assertIdentity();
+        await this.waitForInitialStates(signal);
+      } catch {
+        // SDK diagnostics may contain credentials; do not expose their messages or causes.
+        throw new Error('ESPHome native setup failed or was cancelled.');
+      } finally {
+        this.connecting = false;
+      }
+    });
+    // Join cleanup only after the tracked connect operation settles, so cleanup never awaits itself.
+    return operation.catch(async (errorArg: unknown) => {
+      try { await this.destroy(); }
+      catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'ESPHome setup and owned cleanup failed.'); }
+      throw errorArg;
+    });
   }
 
   public isHealthy(): boolean {
@@ -132,9 +146,11 @@ export class EsphomeNativeApiConnection {
   }
 
   public getSnapshot(): IEsphomeSnapshot {
+    if (this.identityMismatch) throw new Error('ESPHome selected device identity changed; native observations are unavailable.');
     const connected = this.isHealthy();
     const entities = this.native.entitiesByDevice(undefined).filter((entityArg) => readablePlatforms.has(entityArg.type));
     return {
+      homeId: this.config.homeId,
       host: this.host,
       port: this.port,
       connected,
@@ -155,13 +171,31 @@ export class EsphomeNativeApiConnection {
     };
   }
 
-  public onEvent(handlerArg: TEsphomeEventHandler): () => void {
+  public onEvent(handlerArg: TEsphomeEventHandler, signalArg?: AbortSignal): () => void {
     if (this.destroyed) throw new Error('ESPHome connection was destroyed.');
+    signalArg?.throwIfAborted();
+    let active = true;
+    const dispose = (): void => {
+      if (!active) return;
+      signalArg?.removeEventListener('abort', dispose);
+      this.handlers.delete(handlerArg);
+      active = false;
+      this.cleanup.delete(resource);
+    };
+    const resource: IEsphomeCleanup = { cleanup: dispose, failed: false };
+    // Own the handler and caller-signal listener before the foreign registration method.
+    this.cleanup.add(resource);
     this.handlers.add(handlerArg);
-    return () => this.handlers.delete(handlerArg);
+    signalArg?.addEventListener('abort', dispose, { once: true });
+    if (signalArg?.aborted) dispose();
+    return dispose;
   }
 
-  public async sendCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
+  public sendCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
+    return this.track(() => this.executeTrackedCommand(commandArg, signalArg));
+  }
+
+  private async executeTrackedCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
     signalArg?.throwIfAborted();
     if (!this.isHealthy()) return { success: false, error: 'ESPHome is unavailable or has not received its authoritative initial states.' };
     const entity = this.native.entitiesByDevice(undefined).find((entityArg) => entityArg.key === commandArg.key && entityArg.type === commandArg.platform && (entityArg.deviceId ?? 0) === (commandArg.deviceId ?? 0));
@@ -174,22 +208,56 @@ export class EsphomeNativeApiConnection {
     try {
       const state = await this.executeCommand(entity, commandArg.payload, signalArg);
       return { success: true, data: structuredClone(state) };
-    } catch (error) {
-      return { success: false, error: error instanceof Error ? error.message : 'ESPHome command failed.' };
+    } catch {
+      return { success: false, error: 'ESPHome command failed or was cancelled; its physical effect is unknown.' };
     } finally {
       this.pendingCommands.delete(plugins.esphomeNativeApi.entityId(entity.type, entity.objectId));
     }
   }
 
-  public async destroy(): Promise<void> {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    this.ready = false;
-    this.lifetime.abort(new Error('ESPHome connection was destroyed.'));
-    this.native.disconnect();
-    for (const subscription of this.subscriptions) subscription[Symbol.dispose]();
-    this.subscriptions.length = 0;
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.destroyed = true;
+      this.ready = false;
+      this.closePromise = Promise.resolve().then(() => this.drain(false));
+      this.lifetime.abort(new Error('ESPHome connection was destroyed.'));
+    }
+    return this.closePromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.closePromise) throw new Error('ESPHome cleanup retry requires a closed client.');
+    if (!this.retryPromise) {
+      this.retryPromise = Promise.resolve().then(() => this.drain(true));
+      const settled = () => { this.retryPromise = undefined; };
+      void this.retryPromise.then(settled, settled);
+    }
+    return this.retryPromise;
+  }
+
+  private track<T>(workArg: () => Promise<T>): Promise<T> {
+    if (this.destroyed) return Promise.reject(new Error('ESPHome connection was destroyed.'));
+    // Store the actual operation before invoking native or consumer callbacks.
+    const operation = Promise.resolve().then(workArg);
+    this.operations.add(operation);
+    const settled = () => this.operations.delete(operation);
+    void operation.then(settled, settled);
+    return operation;
+  }
+
+  private async drain(retryArg: boolean): Promise<void> {
+    const cleanup = [...this.cleanup].reverse().map((resourceArg) => {
+      if (retryArg && resourceArg.failed) { resourceArg.promise = undefined; resourceArg.failed = false; }
+      resourceArg.promise ??= Promise.resolve().then(() => resourceArg.cleanup()).then(() => undefined, () => {
+        resourceArg.failed = true;
+        throw new Error('ESPHome owned resource cleanup failed.');
+      });
+      return resourceArg.promise;
+    });
+    const [results] = await Promise.all([Promise.allSettled(cleanup), Promise.allSettled([...this.operations])]);
     this.handlers.clear();
+    const failures = results.filter((resultArg) => resultArg.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map(() => new Error('ESPHome owned resource cleanup failed.')), 'ESPHome cleanup failed; resources remain retained for explicit retry.');
   }
 
   private async executeCommand(entityArg: TNativeEntity, payloadArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<unknown> {
@@ -253,14 +321,32 @@ export class EsphomeNativeApiConnection {
 
   private refreshReadiness(): void {
     const health = this.native.health();
-    this.ready = health.state === 'connected' && (!this.requireEncryption || health.encrypted) && this.native.entitiesByDevice(undefined).filter((entityArg) => readablePlatforms.has(entityArg.type)).every((entityArg) => this.native.latest(plugins.esphomeNativeApi.entityId(entityArg.type, entityArg.objectId)) != null);
+    if (health.state === 'connected') {
+      try { this.assertIdentity(); }
+      catch {
+        this.identityMismatch = true;
+        this.ready = false;
+        this.native.disconnect();
+        this.emit({ type: 'error', data: { message: 'ESPHome selected native device identity changed.' } });
+        return;
+      }
+    }
+    this.ready = !this.destroyed && !this.identityMismatch && health.state === 'connected' && (!this.requireEncryption || health.encrypted) && this.native.entitiesByDevice(undefined).filter((entityArg) => readablePlatforms.has(entityArg.type)).every((entityArg) => this.native.latest(plugins.esphomeNativeApi.entityId(entityArg.type, entityArg.objectId)) != null);
+  }
+
+  private assertIdentity(): void {
+    const info = this.native.deviceInfo();
+    if (!info || esphomeMac(info.macAddress) !== this.config.expectedMacAddress || info.name !== this.config.deviceName
+      || (this.config.expectedModel !== undefined && info.model !== this.config.expectedModel)) {
+      throw new Error('ESPHome native device identity does not match the selected endpoint.');
+    }
   }
 
   private entityId(entityArg: TNativeEntity): string {
     const macAddress = this.native.deviceInfo()?.macAddress?.toLowerCase().replace(/[^a-f0-9]/g, '');
     const identity = macAddress?.length === 12 ? macAddress : `${this.host}:${this.port}`;
     const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([identity, entityArg.type, entityArg.key, entityArg.deviceId ?? 0])).digest('hex').slice(0, 24);
-    return `${entityArg.type}.esphome_${digest}`;
+    return `home.${encodeURIComponent(this.config.homeId)}.${entityArg.type}.esphome_${digest}`;
   }
 
   private eventEntityId(eventArg: plugins.esphomeNativeApi.TelemetryEvent): string | undefined {
@@ -285,12 +371,11 @@ export class EsphomeNativeApiConnection {
   }
 
   private emit(eventArg: IEsphomeEvent): void {
-    for (const handler of this.handlers) handler({ ...structuredClone(eventArg), timestamp: Date.now() });
-  }
-
-  private timeout(valueArg: number | undefined, defaultArg: number): number {
-    const value = valueArg ?? defaultArg;
-    if (!Number.isInteger(value) || value < 1 || value > 2147483647) throw new Error('ESPHome timeouts must be integers from 1 through 2147483647.');
-    return value;
+    const failures: unknown[] = [];
+    for (const handler of this.handlers) {
+      try { handler({ ...structuredClone(eventArg), timestamp: Date.now() }); }
+      catch (error) { failures.push(error); }
+    }
+    if (failures.length) throw new AggregateError(failures.map(() => new Error('ESPHome subscriber callback failed.')), 'ESPHome event callbacks failed.');
   }
 }

package/ts/integrations/esphome/esphome.classes.configflow.ts

@@ -1,49 +1,56 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { IEsphomeConfig } from './esphome.types.js';
-import { esphomeDefaultNativeApiPort } from './esphome.types.js';
+import { captureEsphomeConfig, esphomeData } from './esphome.validation.js';
 
 export class EsphomeConfigFlow implements IConfigFlow<IEsphomeConfig> {
+  private readonly scope: NativeIntegrationScope;
+
+  constructor(ownerArg: NativeIntegrationOwner = new NativeIntegrationOwner('esphome')) {
+    this.scope = ownerArg.createFlowScope();
+  }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IEsphomeConfig>> {
-    void contextArg;
+    const context = this.scope.admit(contextArg);
+    // Discovery offers endpoint hints; its metadata, home fields and credentials are never copied.
+    const hints: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    for (const key of ['host', 'port', 'name']) {
+      const field = Object.getOwnPropertyDescriptor(candidateArg, key);
+      if (field && (!field.enumerable || !('value' in field))) throw new TypeError('ESPHome discovery hints must be ordinary data fields.');
+      if (field) hints[key] = field.value as unknown;
+    }
+    const hint = Object.freeze(hints);
     return {
       kind: 'form',
       title: 'Connect ESPHome',
-      description: 'Connect directly to the native API of an ESPHome 2025.10 or newer device. Use its 32-byte base64 encryption key when encryption is configured.',
+      description: 'Confirm the selected native endpoint, node name and MAC address. Provision credentials outside device configuration.',
       fields: [
         { name: 'host', label: 'Host', type: 'text', required: true },
         { name: 'port', label: 'Native API port', type: 'number' },
-        { name: 'encryptionKey', label: 'Encryption key', type: 'password' },
+        { name: 'deviceName', label: 'Selected native node name', type: 'text', required: true },
+        { name: 'expectedMacAddress', label: 'Selected device MAC address', type: 'text', required: true },
+        { name: 'expectedModel', label: 'Selected model (optional)', type: 'text' },
+        { name: 'credentialKey', label: 'Credential reference (optional)', type: 'text' },
+        { name: 'credentialSource', label: 'Credential source', type: 'select', options: [{ label: 'External provider', value: 'provider' }, { label: 'Encrypted store', value: 'store' }] },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'ESPHome configured',
-        config: {
-          host: this.stringValue(valuesArg.host) || candidateArg.host || '',
-          port: this.numberValue(valuesArg.port) || candidateArg.port || esphomeDefaultNativeApiPort,
-          name: candidateArg.name,
-          deviceName: this.stringValue(candidateArg.metadata?.deviceName),
-          encryptionKey: this.stringValue(valuesArg.encryptionKey) || this.stringValue(candidateArg.metadata?.encryptionKey),
-          noisePsk: this.stringValue(candidateArg.metadata?.noisePsk),
-          deviceInfo: {
-            name: this.stringValue(candidateArg.metadata?.deviceName) || candidateArg.name,
-            friendlyName: candidateArg.name,
-            macAddress: candidateArg.macAddress,
-            manufacturer: candidateArg.manufacturer,
-            model: candidateArg.model,
-            host: candidateArg.host,
-            port: candidateArg.port || esphomeDefaultNativeApiPort,
-            apiEncryptionSupported: Boolean(candidateArg.metadata?.encryptionRequired),
-          },
-        },
-      }),
+      submit: async (valuesArg) => {
+        const values = esphomeData(valuesArg, ['homeId', 'host', 'port', 'deviceName', 'expectedMacAddress', 'expectedModel', 'credentialKey', 'credentialSource'], 'ESPHome submitted configuration');
+        if (values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('ESPHome form home does not match the selected host home.');
+        const config = captureEsphomeConfig({
+          homeId: context.homeId, host: (values.host ?? hint.host) as string, port: (values.port ?? hint.port) as number | undefined,
+          name: hint.name as string | undefined, deviceName: values.deviceName as string, expectedMacAddress: values.expectedMacAddress as string,
+          expectedModel: values.expectedModel as string | undefined, credentialKey: values.credentialKey as string | undefined,
+          credentialSource: values.credentialSource as 'provider' | 'store' | undefined,
+        });
+        return this.scope.run(context, config.homeId, async (leaseArg) => {
+          leaseArg.assertOpen();
+          if (config.credentialSource === 'store' && !leaseArg.context.configStore) throw new Error('ESPHome store credential references require a scoped NoSqlConfigStore.');
+          return { kind: 'done', title: 'ESPHome configured', config };
+        });
+      },
     };
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : undefined;
-  }
+  public destroy(): Promise<void> { return this.scope.close(); }
+  public retryCleanup(): Promise<void> { return this.scope.retryCleanup(); }
 }

package/ts/integrations/esphome/esphome.classes.integration.ts

@@ -1,18 +1,20 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { EsphomeClient } from './esphome.classes.client.js';
 import { EsphomeConfigFlow } from './esphome.classes.configflow.js';
 import { createEsphomeDiscoveryDescriptor } from './esphome.discovery.js';
 import { EsphomeMapper } from './esphome.mapper.js';
-import type { IEsphomeConfig } from './esphome.types.js';
+import type { IEsphomeConfig, IEsphomeIntegrationOptions, TEsphomeCredentials } from './esphome.types.js';
+import { captureEsphomeConfig, captureEsphomeCredentials, esphomeData } from './esphome.validation.js';
 
 export class EsphomeIntegration extends BaseIntegration<IEsphomeConfig> {
   public readonly domain = 'esphome';
   public readonly displayName = 'ESPHome';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createEsphomeDiscoveryDescriptor();
-  public readonly configFlow = new EsphomeConfigFlow();
+  public readonly configFlow: EsphomeConfigFlow;
   public readonly metadata = {
     integrationType: 'device',
     iotClass: 'local_push',
@@ -21,35 +23,61 @@ export class EsphomeIntegration extends BaseIntegration<IEsphomeConfig> {
     minimumFirmwareVersion: '2025.10',
     zeroconf: ['_esphomelib._tcp.local.'],
   };
-  private readonly runtimes = new Set<EsphomeRuntime>();
-  private readonly pendingClients = new Set<EsphomeClient>();
-  private destroyed = false;
+  private readonly owner: NativeIntegrationOwner;
+  private readonly resolveCredentials?: IEsphomeIntegrationOptions['resolveCredentials'];
+
+  constructor(optionsArg: IEsphomeIntegrationOptions = {}) {
+    super();
+    const options = esphomeData(optionsArg, ['homeId', 'capacity', 'resolveCredentials'], 'ESPHome integration options');
+    if (options.resolveCredentials !== undefined && typeof options.resolveCredentials !== 'function') throw new TypeError('ESPHome resolveCredentials must be an asynchronous callback.');
+    this.resolveCredentials = options.resolveCredentials as IEsphomeIntegrationOptions['resolveCredentials'];
+    this.owner = new NativeIntegrationOwner(this.domain, { homeId: options.homeId as string | undefined, capacity: options.capacity as number | undefined });
+    this.configFlow = new EsphomeConfigFlow(this.owner);
+  }
 
   public async setup(configArg: IEsphomeConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.destroyed) throw new Error('ESPHome integration was destroyed.');
-    const client = new EsphomeClient(configArg);
-    this.pendingClients.add(client);
-    try {
-      await client.connectLive(contextArg.abortSignal);
-      if (this.destroyed) throw new Error('ESPHome integration was destroyed during setup.');
-      const runtime = new EsphomeRuntime(client, () => this.runtimes.delete(runtime));
-      this.runtimes.add(runtime);
+    const config = captureEsphomeConfig(configArg);
+    return this.owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const timeout = config.initialSnapshotTimeoutMs ?? 15000;
+      const monotonicDeadline = performance.now() + timeout;
+      const signal = AbortSignal.any([leaseArg.signal, AbortSignal.timeout(timeout)]);
+      let credentials: TEsphomeCredentials = {};
+      if (config.credentialKey !== undefined) {
+        const request = Object.freeze({ capturedHomeId: leaseArg.context.homeId, credentialKey: config.credentialKey, signal, monotonicDeadline });
+        // Setup is retained before the deferred callback. Adopt its real completion, never an abort race.
+        const provision = Promise.resolve().then(() => {
+          signal.throwIfAborted();
+          if (config.credentialSource === 'store') {
+            if (!leaseArg.context.configStore) throw new Error('ESPHome store credential references require a scoped NoSqlConfigStore.');
+            return leaseArg.context.configStore.get<TEsphomeCredentials>(request.credentialKey);
+          }
+          if (!this.resolveCredentials) throw new Error('ESPHome provider credential references require resolveCredentials.');
+          return this.resolveCredentials(request);
+        });
+        try { credentials = captureEsphomeCredentials(await provision); }
+        catch { throw new Error('ESPHome credentials could not be resolved.'); }
+      }
+      leaseArg.assertOpen();
+      signal.throwIfAborted();
+      const client = new EsphomeClient(config, undefined, credentials);
+      let cleanupAttempted = false;
+      leaseArg.own(() => {
+        if (cleanupAttempted) return client.retryCleanup();
+        cleanupAttempted = true;
+        return client.destroy();
+      });
+      await client.connectLive(signal);
+      leaseArg.assertOpen();
+      signal.throwIfAborted();
+      const runtime = new EsphomeRuntime(client, leaseArg);
+      leaseArg.promoteToRuntime();
       return runtime;
-    } catch (error) {
-      await client.destroy();
-      throw error;
-    } finally {
-      this.pendingClients.delete(client);
-    }
+    });
   }
 
-  public async destroy(): Promise<void> {
-    this.destroyed = true;
-    await Promise.all([
-      ...[...this.runtimes].map((runtimeArg) => runtimeArg.destroy()),
-      ...[...this.pendingClients].map((clientArg) => clientArg.destroy()),
-    ]);
-  }
+  public destroy(): Promise<void> { return this.owner.close(); }
+
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }
 
 export class HomeAssistantEsphomeIntegration extends EsphomeIntegration {}
@@ -57,22 +85,25 @@ export class HomeAssistantEsphomeIntegration extends EsphomeIntegration {}
 export class EsphomeRuntime implements IIntegrationRuntime {
   public readonly domain = 'esphome';
 
-  constructor(private readonly client: EsphomeClient, private readonly onDestroy?: () => void) {}
+  constructor(private readonly client: EsphomeClient, private readonly lease?: INativeSetupLease) {}
 
   public isHealthy(): boolean {
     return this.client.isHealthy();
   }
 
   public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.lease?.assertOpen();
     signalArg?.throwIfAborted();
     return EsphomeMapper.toDevices(await this.client.getSnapshot());
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
+    this.lease?.assertOpen();
     return EsphomeMapper.toEntities(await this.client.getSnapshot());
   }
 
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.lease?.assertOpen();
     signalArg?.throwIfAborted();
     const unsubscribe = this.client.onEvent((eventArg) => {
       handlerArg({
@@ -83,14 +114,12 @@ export class EsphomeRuntime implements IIntegrationRuntime {
         data: eventArg.data,
         timestamp: eventArg.timestamp || Date.now(),
       });
-    });
-    const cleanup = () => { unsubscribe(); signalArg?.removeEventListener('abort', cleanup); };
-    signalArg?.addEventListener('abort', cleanup, { once: true });
-    if (signalArg?.aborted) cleanup();
-    return async () => cleanup();
+    }, signalArg);
+    return async () => unsubscribe();
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    this.lease?.assertOpen();
     if (!requestArg.target.entityId && !requestArg.target.deviceId) return { success: false, error: 'ESPHome service calls require an explicit entity or device target.' };
     const command = EsphomeMapper.commandForService(await this.client.getSnapshot(), requestArg);
     if (!command) return { success: false, error: `ESPHome service ${requestArg.domain}.${requestArg.service} has no unique supported native command target.` };
@@ -98,6 +127,7 @@ export class EsphomeRuntime implements IIntegrationRuntime {
   }
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    this.lease?.assertOpen();
     signalArg?.throwIfAborted();
     if (requestArg.device.integrationDomain !== this.domain) return { success: false, error: 'ESPHome feature writes require an ESPHome device target.' };
     const command = EsphomeMapper.commandForFeature(await this.client.getSnapshot(), requestArg.device.id, requestArg.feature.id, requestArg.value);
@@ -105,8 +135,5 @@ export class EsphomeRuntime implements IIntegrationRuntime {
     return this.client.sendCommand(command, signalArg);
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
-    this.onDestroy?.();
-  }
+  public destroy(): Promise<void> { return this.lease ? this.lease.close() : this.client.destroy(); }
 }