@smarthome.exchange/integrations 2.0.0 → 3.0.0

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.