@smarthome.exchange/integrations 1.0.0 → 3.0.0

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(); }
 }

package/ts/integrations/esphome/esphome.discovery.ts

@@ -2,6 +2,7 @@ import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { IEsphomeManualEntry, IEsphomeMdnsRecord } from './esphome.types.js';
 import { esphomeDefaultNativeApiPort } from './esphome.types.js';
+import { esphomeMac } from './esphome.validation.js';
 
 const esphomeMdnsTypes = new Set(['_esphomelib._tcp.local', '_esphome._tcp.local']);
 
@@ -37,7 +38,6 @@ export class EsphomeMdnsMatcher implements IDiscoveryMatcher<IEsphomeMdnsRecord>
         metadata: {
           mdnsName: recordArg.name,
           mdnsType: recordArg.type,
-          txt,
           deviceName,
           encryptionRequired: Boolean(this.txt(txt, 'api_encryption')),
         },
@@ -63,13 +63,8 @@ export class EsphomeMdnsMatcher implements IDiscoveryMatcher<IEsphomeMdnsRecord>
   }
 
   private normalizeMac(valueArg?: string): string | undefined {
-    if (!valueArg) {
-      return undefined;
-    }
-    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    if (compact.length !== 12) {
-      return valueArg.toLowerCase();
-    }
+    const compact = esphomeMac(valueArg);
+    if (!compact) return undefined;
     return compact.match(/.{1,2}/g)?.join(':');
   }
 }
@@ -101,11 +96,7 @@ export class EsphomeManualMatcher implements IDiscoveryMatcher<IEsphomeManualEnt
         manufacturer: inputArg.manufacturer || 'ESPHome',
         model: inputArg.model || 'Native API device',
         metadata: {
-          ...inputArg.metadata,
           deviceName: inputArg.deviceName,
-          password: inputArg.password,
-          encryptionKey: inputArg.encryptionKey,
-          noisePsk: inputArg.noisePsk,
         },
       },
     };

package/ts/integrations/esphome/esphome.mapper.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../../plugins.js';
 import type { IIntegrationEntity, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
-import type { IEsphomeAreaInfo, IEsphomeClientCommand, IEsphomeConfig, IEsphomeDeviceInfo, IEsphomeEntityDescriptor, IEsphomeEntityState, IEsphomeManualEntry, IEsphomeSnapshot } from './esphome.types.js';
+import type { IEsphomeAreaInfo, IEsphomeClientCommand, IEsphomeMappingConfig, IEsphomeDeviceInfo, IEsphomeEntityDescriptor, IEsphomeEntityState, IEsphomeManualEntry, IEsphomeSnapshot } from './esphome.types.js';
 import { esphomeDefaultNativeApiPort } from './esphome.types.js';
 
 const serviceDataFields = new Map<string, readonly string[]>([
@@ -18,11 +18,12 @@ const serviceDataFields = new Map<string, readonly string[]>([
 ]);
 
 export class EsphomeMapper {
-  public static toSnapshot(configArg: IEsphomeConfig, connectedArg?: boolean, eventsArg: IEsphomeSnapshot['events'] = []): IEsphomeSnapshot {
+  public static toSnapshot(configArg: IEsphomeMappingConfig, connectedArg?: boolean, eventsArg: IEsphomeSnapshot['events'] = []): IEsphomeSnapshot {
     const source = configArg.snapshot;
     const manualEntry = configArg.manualEntries?.[0];
     const deviceInfo = this.deviceInfoFromConfig(configArg, source?.deviceInfo, manualEntry);
     return {
+      homeId: configArg.homeId ?? source?.homeId,
       host: configArg.host || source?.host || manualEntry?.host || deviceInfo.host,
       port: configArg.port || source?.port || manualEntry?.port || deviceInfo.port || esphomeDefaultNativeApiPort,
       connected: connectedArg ?? source?.connected ?? false,
@@ -216,7 +217,7 @@ export class EsphomeMapper {
     return `esphome_${this.slug(`${deviceIdentifier}_${entityArg.platform}_${objectId}_${entityArg.key}_${subDevice ?? 0}`)}`;
   }
 
-  private static deviceInfoFromConfig(configArg: IEsphomeConfig, sourceArg?: IEsphomeDeviceInfo, manualEntryArg?: IEsphomeManualEntry): IEsphomeDeviceInfo {
+  private static deviceInfoFromConfig(configArg: IEsphomeMappingConfig, sourceArg?: IEsphomeDeviceInfo, manualEntryArg?: IEsphomeManualEntry): IEsphomeDeviceInfo {
     return {
       ...sourceArg,
       ...configArg.deviceInfo,
@@ -226,12 +227,12 @@ export class EsphomeMapper {
       model: configArg.deviceInfo?.model || sourceArg?.model || manualEntryArg?.model,
       host: configArg.host || sourceArg?.host || manualEntryArg?.host || configArg.deviceInfo?.host,
       port: configArg.port || sourceArg?.port || manualEntryArg?.port || configArg.deviceInfo?.port || esphomeDefaultNativeApiPort,
-      usesPassword: configArg.deviceInfo?.usesPassword ?? sourceArg?.usesPassword ?? Boolean(configArg.password || manualEntryArg?.password),
-      apiEncryptionSupported: configArg.deviceInfo?.apiEncryptionSupported ?? sourceArg?.apiEncryptionSupported ?? Boolean(configArg.encryptionKey || configArg.noisePsk || manualEntryArg?.encryptionKey || manualEntryArg?.noisePsk),
+      usesPassword: configArg.deviceInfo?.usesPassword ?? sourceArg?.usesPassword,
+      apiEncryptionSupported: configArg.deviceInfo?.apiEncryptionSupported ?? sourceArg?.apiEncryptionSupported,
     };
   }
 
-  private static normalizeStates(statesArg: IEsphomeConfig['states'] | IEsphomeSnapshot['states'] | undefined): IEsphomeEntityState[] {
+  private static normalizeStates(statesArg: IEsphomeMappingConfig['states'] | IEsphomeSnapshot['states'] | undefined): IEsphomeEntityState[] {
     if (!statesArg) {
       return [];
     }
@@ -450,7 +451,8 @@ export class EsphomeMapper {
   }
 
   private static mainDeviceId(snapshotArg: IEsphomeSnapshot): string {
-    return `esphome.device.${this.slug(this.compactDeviceIdentifier(snapshotArg.deviceInfo) || snapshotArg.deviceInfo.name || snapshotArg.host || 'configured')}`;
+    const scope = snapshotArg.homeId ? `home.${encodeURIComponent(snapshotArg.homeId)}.` : '';
+    return `${scope}esphome.device.${this.slug(this.compactDeviceIdentifier(snapshotArg.deviceInfo) || snapshotArg.deviceInfo.name || snapshotArg.host || 'configured')}`;
   }
 
   private static subDeviceId(snapshotArg: IEsphomeSnapshot, subDeviceIdArg: string | number): string {

package/ts/integrations/esphome/esphome.types.ts

@@ -1,4 +1,5 @@
 import type { TEntityPlatform } from '../../core/types.js';
+import type * as plugins from '../../plugins.js';
 
 export const esphomeDefaultNativeApiPort = 6053;
 
@@ -16,13 +17,43 @@ export type TEsphomeEntityPlatform =
   | 'water_heater';
 
 export interface IEsphomeConfig {
+  readonly homeId: string;
+  readonly host: string;
+  readonly port?: number;
+  readonly deviceName: string;
+  readonly expectedMacAddress: string;
+  readonly expectedModel?: string;
+  readonly name?: string;
+  readonly credentialKey?: string;
+  readonly credentialSource?: 'provider' | 'store';
+  readonly initialSnapshotTimeoutMs?: number;
+  readonly commandTimeoutMs?: number;
+}
+
+/** Only the published native client's Noise option is supported; legacy passwords are not. */
+export type TEsphomeCredentials = Readonly<Pick<plugins.esphomeNativeApi.EspHomeClientOptions, 'psk'>>;
+
+export interface IEsphomeCredentialRequest {
+  readonly capturedHomeId: string;
+  readonly credentialKey: string;
+  readonly signal: AbortSignal;
+  /** Absolute milliseconds on performance.now(), including provisioning and native setup. */
+  readonly monotonicDeadline: number;
+}
+
+export interface IEsphomeIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+  readonly resolveCredentials?: (requestArg: IEsphomeCredentialRequest) => Promise<TEsphomeCredentials>;
+}
+
+/** Pure mapper input. This cannot be used for live setup. */
+export interface IEsphomeMappingConfig {
+  homeId?: string;
   host?: string;
   port?: number;
   name?: string;
   deviceName?: string;
-  password?: string;
-  encryptionKey?: string;
-  noisePsk?: string;
   initialSnapshotTimeoutMs?: number;
   commandTimeoutMs?: number;
   snapshot?: IEsphomeSnapshot;
@@ -151,6 +182,7 @@ export interface IEsphomeEntityState {
 }
 
 export interface IEsphomeSnapshot {
+  homeId?: string;
   host?: string;
   port: number;
   connected: boolean;
@@ -236,9 +268,6 @@ export interface IEsphomeManualEntry {
   deviceName?: string;
   model?: string;
   manufacturer?: string;
-  password?: string;
-  encryptionKey?: string;
-  noisePsk?: string;
   metadata?: Record<string, unknown>;
 }
 

package/ts/integrations/esphome/esphome.validation.ts

@@ -0,0 +1,66 @@
+import type { IEsphomeConfig, TEsphomeCredentials } from './esphome.types.js';
+
+export const esphomeData = (valueArg: unknown, fieldsArg: readonly string[], labelArg: string): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new TypeError(`${labelArg} must be a plain data object.`);
+  }
+  const captured: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const field = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !fieldsArg.includes(key) || !field || !field.enumerable || !('value' in field)) {
+      throw new TypeError(`${labelArg} contains an unsupported field or accessor.`);
+    }
+    captured[key] = field.value as unknown;
+  }
+  return captured;
+};
+
+export const esphomeIdentifier = (valueArg: unknown, labelArg: string): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.trim() !== valueArg || valueArg.length > 256 || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`${labelArg} must be a non-empty identifier without surrounding whitespace or control characters.`);
+  }
+  return valueArg;
+};
+
+export const esphomeTimeout = (valueArg: unknown, defaultArg: number): number => {
+  const value = valueArg ?? defaultArg;
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 2147483647) {
+    throw new TypeError('ESPHome timeouts must be integers from 1 through 2147483647.');
+  }
+  return value;
+};
+
+export const esphomeMac = (valueArg: unknown): string | undefined => {
+  if (typeof valueArg !== 'string' || !/^(?:[a-f\d]{12}|(?:[a-f\d]{2}:){5}[a-f\d]{2})$/i.test(valueArg)) return undefined;
+  return valueArg.replace(/:/g, '').toLowerCase();
+};
+
+export const captureEsphomeConfig = (valueArg: IEsphomeConfig): IEsphomeConfig => {
+  const value = esphomeData(valueArg, ['homeId', 'host', 'port', 'name', 'deviceName', 'expectedMacAddress', 'expectedModel', 'credentialKey', 'credentialSource', 'initialSnapshotTimeoutMs', 'commandTimeoutMs'], 'ESPHome configuration');
+  const host = esphomeIdentifier(value.host, 'ESPHome host');
+  if (/\s/.test(host)) throw new TypeError('ESPHome host must not contain whitespace.');
+  const port = value.port ?? 6053;
+  if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) throw new TypeError('ESPHome port must be an integer from 1 through 65535.');
+  const mac = esphomeMac(value.expectedMacAddress);
+  if (!mac) throw new TypeError('ESPHome expectedMacAddress must be a complete MAC address.');
+  if (value.credentialSource !== undefined && value.credentialSource !== 'provider' && value.credentialSource !== 'store') throw new TypeError('ESPHome credential source must be provider or store.');
+  if (value.credentialSource !== undefined && value.credentialKey === undefined) throw new TypeError('ESPHome credential source requires a credential reference.');
+  return Object.freeze({
+    homeId: esphomeIdentifier(value.homeId, 'ESPHome configuration homeId'), host, port,
+    deviceName: esphomeIdentifier(value.deviceName, 'ESPHome selected device name'), expectedMacAddress: mac,
+    expectedModel: value.expectedModel === undefined ? undefined : esphomeIdentifier(value.expectedModel, 'ESPHome selected model'),
+    name: value.name === undefined ? undefined : esphomeIdentifier(value.name, 'ESPHome display name'),
+    credentialKey: value.credentialKey === undefined ? undefined : esphomeIdentifier(value.credentialKey, 'ESPHome credential reference'),
+    credentialSource: value.credentialSource as 'provider' | 'store' | undefined,
+    initialSnapshotTimeoutMs: esphomeTimeout(value.initialSnapshotTimeoutMs, 15000), commandTimeoutMs: esphomeTimeout(value.commandTimeoutMs, 5000),
+  });
+};
+
+export const captureEsphomeCredentials = (valueArg: unknown): TEsphomeCredentials => {
+  const value = esphomeData(valueArg, ['psk'], 'ESPHome credential provider result');
+  const psk = value.psk;
+  if (psk !== undefined && psk !== null && (typeof psk !== 'string' || !/^[A-Za-z0-9+/]{43}=$/.test(psk) || Buffer.from(psk, 'base64').length !== 32 || Buffer.from(psk, 'base64').toString('base64') !== psk)) {
+    throw new TypeError('ESPHome Noise credentials require a canonical base64-encoded 32-byte key.');
+  }
+  return Object.freeze({ psk: psk as string | null | undefined });
+};

package/ts/integrations/esphome/readme.md

@@ -10,15 +10,25 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 Install the parent package with `pnpm add @smarthome.exchange/integrations`. The native client requires Node.js 22.20 or newer and ESPHome 2025.10 or newer. Configure one native API node per integration instance; its advertised logical sub-devices share that connection.
 
-Provide a host and an optional port, which defaults to `6053`. For an encrypted device, supply its canonical base64-encoded 32-byte key as `encryptionKey` or `noisePsk`. Conflicting keys, legacy API passwords, injected snapshots, and command executors are rejected during live setup. When a key is supplied, a plaintext connection is rejected before controls become available.
+Provide `homeId`, a host, the selected native `deviceName`, and `expectedMacAddress`; the optional port defaults to `6053`. An optional `expectedModel` must match the model in the actual native device-info response. Setup checks these observed identity fields before publishing readiness, including after reconnect. Discovery supplies endpoint hints and does not prove identity or select the owning home. Home and device/entity routing identifiers include the independently admitted home. MAC/name checks are selection constraints, not authentication; use Noise encryption for authenticated transport.
+
+The embedding host must independently supply the same `homeId` in setup and config-flow contexts. An optional constructor home constrains this choice and never substitutes for context. The first valid admission binds an otherwise unbound integration, even when setup fails. Construction performs no network or persistence work. Shared ownership defaults to sixteen pending operations, live runtimes and retained cleanup resources.
+
+Configuration contains only an optional `credentialKey` reference. Resolve it through the constructor's borrowed asynchronous `resolveCredentials` callback, which receives the captured home, reference, cancellation signal and an absolute `performance.now()` deadline. Its result supports the published client's `{ psk }` option only: a canonical base64-encoded 32-byte Noise key, or no key for a plaintext endpoint. The entire setup deadline includes credential provisioning. Cancellation joins the actual provider promise and rejects late results before transport construction; an uncooperative provider can therefore delay shutdown. Provider errors are replaced with fixed diagnostics to avoid exposing secrets.
 
 ```typescript
 import { EsphomeIntegration } from '@smarthome.exchange/integrations';
 
-async function inspectNode(host: string, encryptionKey: string) {
-  const integration = new EsphomeIntegration();
+async function inspectNode(homeId: string, host: string, macAddress: string, resolveNoiseKey: (reference: string, signal: AbortSignal) => Promise<string>) {
+  const integration = new EsphomeIntegration({
+    resolveCredentials: async ({ credentialKey, signal }) => ({ psk: await resolveNoiseKey(credentialKey, signal) }),
+  });
   try {
-    const runtime = await integration.setup({ host, encryptionKey }, {
+    const runtime = await integration.setup({
+      homeId, host, deviceName: 'selected_node', expectedMacAddress: macAddress,
+      credentialKey: 'selected-node-noise',
+    }, {
+      homeId,
       abortSignal: AbortSignal.timeout(15_000),
     });
     return await runtime.devices();
@@ -28,7 +38,9 @@ async function inspectNode(host: string, encryptionKey: string) {
 }
 ```
 
-Obtain encryption keys through the application's secret provisioning flow. Discovery metadata does not prove a device's identity or grant authority to control it. The caller remains responsible for home access and tool authorization.
+Obtain encryption keys through the application's secret provisioning flow. Forms accept references, and discovery never copies passwords, keys or arbitrary TXT/manual metadata. Raw `encryptionKey`, `noisePsk`, legacy passwords, injected snapshots and command executors are rejected in live configuration. A provisioned PSK session that negotiates plaintext is rejected before controls become available. The caller remains responsible for authentication, home access and tool authorization.
+
+For an explicitly selected encrypted store reference, set `credentialSource: 'store'` and supply an initialized actual `NoSqlConfigStore` scoped to this home and the `esphome` domain. The caller provisions `{ psk }` under `credentialKey` through the store's public API. The default source is the external provider; neither source falls through to the other on failure. Store reads use the store's configured operation timeout and expose no per-call cancellation option; shutdown joins their actual completion and fences late results. The store, database and encryption-key provider remain caller-owned. No store is needed for an external provider or plaintext setup.
 
 ## State and controls
 
@@ -38,7 +50,9 @@ Readable platforms are lights, switches, fans, covers, climate entities, numbers
 
 Use `runtime.writeFeature` with a device and feature returned by that runtime, or `runtime.callService` with an explicit entity or device target. A device target must select exactly one supported entity. Supplying both targets requires them to name the same device. Foreign integration devices, unrelated service domains, out-of-range cover positions, and unknown service settings are rejected. Service data must contain ordinary values without accessors or symbol fields. The `esphome` service domain can select a supported native entity; platform domains must match the selected entity.
 
-Each entity admits one pending command. Success requires a subsequent matching state report within `commandTimeoutMs`, which defaults to 5 seconds. A matching report confirms the observed state; the protocol does not supply a unique action receipt or exactly-once physical execution guarantee. Timeout or cancellation can follow a physical effect, so failed or interrupted commands must not be retried automatically. Destruction disconnects the node, removes subscriptions, and cancels setup and pending confirmations.
+Each entity admits one pending command. Success requires a subsequent matching state report within `commandTimeoutMs`, which defaults to 5 seconds. A matching report confirms the observed state; the protocol does not supply a unique action receipt or exactly-once physical execution guarantee. Timeout or cancellation can follow a physical effect, so failed or interrupted commands must not be retried automatically. Destruction publishes one stable terminal promise, aborts owned work, disconnects the node, drains pending confirmations and all subscriptions, and retains cleanup failures. `integration.retryCleanup()` retries failed cleanup explicitly without reconnecting or replaying commands. Destruction never closes borrowed credential or persistence resources.
+
+The published SDK's synchronous `disconnect()` cancels reconnection, disposes its owned transport and reports disconnect/health transitions. Fixture peers observe the resulting TCP close for plaintext and Noise sessions. The SDK does not expose an OS socket-close completion promise, and this adapter makes no stronger OS-close or guaranteed memory-zeroization claim.
 
 Verification uses real plaintext and Noise-encrypted local TCP fixtures plus the published native client's encoder/decoder and `MockTransport`. Real hardware behavior has not been verified in this lane.