@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/mqtt/mqtt.classes.session.ts

@@ -0,0 +1,118 @@
+import type { INativeOperationLease } from '../../core/classes.nativeintegrationowner.js';
+import { MqttClient } from './mqtt.classes.client.js';
+import type { IMqttConfig, IMqttTransportCredentials, TMqttCredentialResolver } from './mqtt.types.js';
+import { mqttCredentials } from './mqtt.validation.js';
+
+/** Owns actual caller credential work and the resulting transport, without owning the provider. */
+export class MqttSession {
+  readonly #config: IMqttConfig & { homeId: string };
+  readonly #lease: INativeOperationLease;
+  readonly #resolver?: TMqttCredentialResolver;
+  readonly #lifetime = new AbortController();
+  readonly #signal: AbortSignal;
+  #provider?: Promise<IMqttTransportCredentials>;
+  #work?: Promise<MqttClient>;
+  #client?: MqttClient;
+  #closed = false;
+  #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
+  #providerDrained = false;
+  #transportClosed = false;
+  #transportCloseAttempted = false;
+
+  constructor(configArg: IMqttConfig & { homeId: string }, leaseArg: INativeOperationLease, resolverArg?: TMqttCredentialResolver) {
+    this.#config = configArg; this.#lease = leaseArg; this.#resolver = resolverArg;
+    this.#signal = AbortSignal.any([leaseArg.signal, this.#lifetime.signal]);
+  }
+
+  public start(): Promise<MqttClient> {
+    if (!this.#work) this.#work = Promise.resolve().then(() => this.#start());
+    return this.#work;
+  }
+
+  public close(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#closed = true;
+      this.#closePromise = Promise.resolve().then(() => this.#drain());
+      this.#lifetime.abort(new Error('MQTT session is closed.'));
+    }
+    return this.#closePromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.#closed) return Promise.reject(new Error('MQTT cleanup can only be retried after close.'));
+    if (!this.#retryPromise) {
+      const retry = Promise.resolve().then(() => this.#drain());
+      this.#retryPromise = retry;
+      void retry.then(() => { this.#retryPromise = undefined; }, () => { this.#retryPromise = undefined; });
+    }
+    return this.#retryPromise;
+  }
+
+  #assertOpen(): void {
+    this.#lease.assertOpen();
+    this.#signal.throwIfAborted();
+    if (this.#closed) throw new Error('MQTT session is closed.');
+  }
+
+  async #start(): Promise<MqttClient> {
+    this.#assertOpen();
+    const deadline = performance.now() + (this.#config.connectTimeoutMs ?? 7000);
+    let credentials: IMqttTransportCredentials = {};
+    if (this.#config.credentialKey) {
+      if (!this.#resolver) throw new Error('MQTT credential reference requires a caller resolver.');
+      const resolver = this.#resolver;
+      const request = Object.freeze({ homeId: this.#lease.context.homeId, credentialKey: this.#config.credentialKey,
+        signal: this.#signal, deadline });
+      // The microtask enters foreign code only after its actual promise is retained here.
+      this.#provider = Promise.resolve().then(() => {
+        this.#assertOpen();
+        return resolver(request);
+      }).then((value) => mqttCredentials(value), () => { throw new Error('MQTT caller credential resolution failed.'); });
+      const provider = this.#provider;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let abort: () => void = () => {};
+      const cancellation = new Promise<never>((_resolve, reject) => {
+        abort = () => reject(this.#signal.reason as unknown);
+        timer = setTimeout(() => {
+          const error = new Error('MQTT credential resolution timed out.');
+          reject(error);
+          this.#lifetime.abort(error);
+        }, Math.max(1, deadline - performance.now()));
+        this.#signal.addEventListener('abort', abort, { once: true });
+        if (this.#signal.aborted) abort();
+      });
+      try { credentials = await Promise.race([provider, cancellation]); }
+      finally { if (timer) clearTimeout(timer); this.#signal.removeEventListener('abort', abort); }
+    }
+    this.#assertOpen();
+    const remaining = Math.floor(deadline - performance.now());
+    if (remaining < 1) throw new Error('MQTT setup timed out.');
+    const client = new MqttClient({ ...this.#config, connectTimeoutMs: remaining }, credentials);
+    this.#client = client;
+    // The session is already the lease's owned cleanup before this allocation and start.
+    try { await client.start(this.#signal); }
+    catch (error) { if (this.#signal.aborted) throw this.#signal.reason as unknown; throw error; }
+    this.#assertOpen();
+    return client;
+  }
+
+  async #drain(): Promise<void> {
+    const provider = this.#provider;
+    const client = this.#client;
+    const results = await Promise.allSettled([
+      ...(provider && !this.#providerDrained ? [provider.then(() => { this.#providerDrained = true; }, () => {
+        this.#providerDrained = true;
+        throw new Error('MQTT caller credential work failed while draining.');
+      })] : []),
+      ...(client && !this.#transportClosed ? [Promise.resolve().then(() => {
+        const retry = this.#transportCloseAttempted;
+        this.#transportCloseAttempted = true;
+        return retry ? client.retryCleanup() : client.destroy();
+      }).then(() => { this.#transportClosed = true; })] : []),
+      ...(this.#work ? [this.#work.then(() => undefined, () => undefined)] : []),
+    ]);
+    const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : []);
+    if (failures.length) throw new AggregateError(failures, 'MQTT session cleanup failed; retry cleanup explicitly.');
+  }
+}

package/ts/integrations/mqtt/mqtt.mapper.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../../plugins.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
-import type { IMqttConfig, IMqttDeviceInfo, IMqttEntityConfig, IMqttMessage, IMqttPayload, IMqttPublishOptions, IMqttSnapshot } from './mqtt.types.js';
+import type { IMqttConfig, IMqttDeviceInfo, IMqttEntityConfig, IMqttMessage, IMqttPayload, IMqttPublishOptions, IMqttSnapshot, IMqttTopicMapping } from './mqtt.types.js';
 
 const defaultDiscoveryPrefix = 'homeassistant';
 const defaultPayloadOn = 'ON';
@@ -68,6 +68,8 @@ export class MqttMapper {
       ...(configArg.discovery === false ? [] : this.entitiesFromDiscoveryMessages(messages, configArg.discoveryPrefix || defaultDiscoveryPrefix)),
     ];
     return {
+      homeId: configArg.homeId,
+      selectedMappings: configArg.mode === 'selected-topics' ? structuredClone(configArg.mappings ?? []) : undefined,
       brokerInfo: {
         host: configArg.host,
         port: configArg.port || (configArg.protocol === 'mqtts' ? 8883 : 1883),
@@ -82,6 +84,7 @@ export class MqttMapper {
   }
 
   public static toDevices(snapshotArg: IMqttSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    if (snapshotArg.selectedMappings) return this.selectedDevices(snapshotArg);
     const updatedAt = new Date().toISOString();
     const devices = new Map<string, plugins.shxInterfaces.data.IDeviceDefinition>();
     const brokerId = this.brokerDeviceId(snapshotArg);
@@ -145,6 +148,13 @@ export class MqttMapper {
   }
 
   public static toEntities(snapshotArg: IMqttSnapshot): IIntegrationEntity[] {
+    if (snapshotArg.selectedMappings) return snapshotArg.selectedMappings.map((mappingArg) => ({
+      id: mappingArg.entityId, uniqueId: mappingArg.entityId, integrationDomain: 'mqtt', deviceId: mappingArg.deviceId,
+      platform: 'sensor', name: mappingArg.name, state: this.selectedValue(snapshotArg, mappingArg.stateTopic),
+      attributes: { homeId: snapshotArg.homeId, stateTopic: mappingArg.stateTopic, availabilityTopic: mappingArg.availabilityTopic,
+        observationFormat: 'raw-utf8', identitySource: 'owner-mapping' },
+      available: this.selectedAvailable(snapshotArg, mappingArg),
+    }));
     return snapshotArg.entities.map((entityArg) => ({
       id: entityArg.defaultEntityId || `${this.toEntityPlatform(entityArg.platform)}.${this.slug(entityArg.uniqueId || entityArg.objectId || entityArg.name || 'mqtt')}`,
       uniqueId: this.uniqueId(entityArg),
@@ -168,6 +178,7 @@ export class MqttMapper {
   }
 
   public static commandForService(snapshotArg: IMqttSnapshot, requestArg: IServiceCallRequest): IMqttPublishOptions | undefined {
+    if (snapshotArg.selectedMappings) return undefined;
     const entity = this.findTargetEntity(snapshotArg, requestArg);
     if (entity && requestArg.target.deviceId && this.deviceIdForEntity(entity, snapshotArg) !== requestArg.target.deviceId) return undefined;
     if (!entity?.commandTopic || requestArg.domain !== entity.platform || !this.controlSupported(entity) || !this.entityAvailable(entity, snapshotArg)) {
@@ -209,6 +220,7 @@ export class MqttMapper {
   }
 
   public static commandForFeature(snapshotArg: IMqttSnapshot, requestArg: IDeviceFeatureWriteRequest): IMqttPublishOptions | undefined {
+    if (snapshotArg.selectedMappings) return undefined;
     const entities = snapshotArg.entities.filter((entityArg) =>
       this.deviceIdForEntity(entityArg, snapshotArg) === requestArg.device.id &&
       this.featureForEntity(entityArg).id === requestArg.feature.id
@@ -584,6 +596,36 @@ export class MqttMapper {
     return Array.isArray(valueArg) ? JSON.stringify(valueArg) : valueArg as plugins.shxInterfaces.data.TDeviceStateValue;
   }
 
+  private static selectedValue(snapshotArg: IMqttSnapshot, topicArg: string): string | null {
+    const value = snapshotArg.messages.find((messageArg) => messageArg.topic === topicArg)?.payload;
+    return typeof value === 'string' ? value : null;
+  }
+
+  private static selectedAvailable(snapshotArg: IMqttSnapshot, mappingArg: IMqttTopicMapping): boolean {
+    return snapshotArg.brokerInfo.connected && this.selectedValue(snapshotArg, mappingArg.stateTopic) !== null
+      && (!mappingArg.availabilityTopic
+        || this.selectedValue(snapshotArg, mappingArg.availabilityTopic) === (mappingArg.payloadAvailable ?? 'online'));
+  }
+
+  private static selectedDevices(snapshotArg: IMqttSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const devices = new Map<string, plugins.shxInterfaces.data.IDeviceDefinition>();
+    for (const mapping of snapshotArg.selectedMappings ?? []) {
+      let device = devices.get(mapping.deviceId);
+      if (!device) {
+        device = { id: mapping.deviceId, name: mapping.deviceName, integrationDomain: 'mqtt', protocol: 'mqtt',
+          online: false, features: [], state: [], metadata: { homeId: snapshotArg.homeId, identitySource: 'owner-mapping',
+            brokerHost: snapshotArg.brokerInfo.host, physicalIdentityConfirmed: false } };
+        devices.set(mapping.deviceId, device);
+      }
+      device.online ||= this.selectedAvailable(snapshotArg, mapping);
+      device.features.push({ id: mapping.featureId, name: mapping.name, capability: 'sensor', readable: true, writable: false });
+      const message = snapshotArg.messages.find((itemArg) => itemArg.topic === mapping.stateTopic);
+      device.state.push({ featureId: mapping.featureId, value: this.selectedValue(snapshotArg, mapping.stateTopic),
+        updatedAt: new Date(message?.timestamp ?? Date.now()).toISOString() });
+    }
+    return [...devices.values()];
+  }
+
   private static stringValue(valueArg: unknown): string | undefined {
     return typeof valueArg === 'string' && valueArg ? valueArg : undefined;
   }

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

@@ -1,6 +1,13 @@
 import type { TEntityPlatform } from '../../core/types.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 
 export interface IMqttConfig {
+  /** Required by MqttIntegration; raw MqttClient remains a reusable transport. */
+  homeId?: string;
+  mode?: 'discovery' | 'selected-topics';
+  credentialKey?: string;
+  allowUnencryptedLan?: boolean;
+  mappings?: IMqttTopicMapping[];
   host?: string;
   port?: number;
   protocol?: 'mqtt' | 'mqtts';
@@ -26,6 +33,49 @@ export interface IMqttConfig {
   maxBufferedBytes?: number;
 }
 
+/** Owner-defined identity and exact topics; payloads are opaque UTF-8 observations. */
+export interface IMqttTopicMapping {
+  deviceId: string;
+  entityId: string;
+  featureId: string;
+  name: string;
+  deviceName: string;
+  stateTopic: string;
+  availabilityTopic?: string;
+  payloadAvailable?: string;
+}
+
+export interface IMqttSelectedConfig extends IMqttConfig {
+  homeId: string;
+  mode: 'selected-topics';
+  mappings: IMqttTopicMapping[];
+}
+
+/** Runtime-only subset of the documented MQTT.js TCP/TLS options. No file paths. */
+export interface IMqttTransportCredentials {
+  username?: string;
+  password?: string;
+  ca?: string;
+  cert?: string;
+  key?: string;
+  servername?: string;
+}
+
+export interface IMqttCredentialRequest {
+  readonly homeId: string;
+  readonly credentialKey: string;
+  readonly signal: AbortSignal;
+  /** Absolute performance.now() deadline. */
+  readonly deadline: number;
+}
+
+/** The caller owns retrieval, storage and cancellation of this borrowed provider. */
+export type TMqttCredentialResolver = (requestArg: IMqttCredentialRequest) => Promise<IMqttTransportCredentials>;
+
+export interface IMqttIntegrationOptions extends INativeIntegrationOwnerOptions {
+  readonly resolveCredentials?: TMqttCredentialResolver;
+}
+
 export interface IMqttConnectionState {
   connected: boolean;
   error?: Error;
@@ -61,6 +111,8 @@ export interface IMqttSnapshot {
   brokerInfo: IMqttBrokerInfo;
   entities: IMqttEntityConfig[];
   messages: IMqttMessage[];
+  homeId?: string;
+  selectedMappings?: IMqttTopicMapping[];
 }
 
 export interface IMqttDeviceInfo {

package/ts/integrations/mqtt/mqtt.validation.ts

@@ -0,0 +1,157 @@
+import { validateMqttTopic } from './mqtt.classes.client.js';
+import type { IMqttConfig, IMqttTopicMapping, IMqttTransportCredentials } from './mqtt.types.js';
+
+export const mqttRecord = (valueArg: unknown, allowedArg: readonly string[]): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object'
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new TypeError('MQTT configuration must be a plain data object.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !allowedArg.includes(key) || !descriptor?.enumerable || !('value' in descriptor)) {
+      throw new TypeError('MQTT configuration contains an unsupported field or accessor.');
+    }
+    result[key] = descriptor.value as unknown;
+  }
+  return result;
+};
+
+export const mqttText = (valueArg: unknown, maximumArg = 256): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.trim() !== valueArg
+    || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError('MQTT identifier must be a bounded non-empty string without whitespace or control characters.');
+  }
+  return valueArg;
+};
+
+const integer = (valueArg: unknown, maximumArg: number, minimumArg = 1): number | undefined => {
+  if (valueArg === undefined) return undefined;
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError('MQTT numeric configuration is out of range.');
+  }
+  return valueArg;
+};
+
+const mapping = (valueArg: unknown): IMqttTopicMapping => {
+  const value = mqttRecord(valueArg, ['deviceId', 'entityId', 'featureId', 'name', 'deviceName', 'stateTopic', 'availabilityTopic', 'payloadAvailable']);
+  const stateTopic = mqttText(value.stateTopic, 65535);
+  const availabilityTopic = value.availabilityTopic === undefined ? undefined : mqttText(value.availabilityTopic, 65535);
+  validateMqttTopic(stateTopic);
+  if (availabilityTopic) validateMqttTopic(availabilityTopic);
+  if (value.payloadAvailable !== undefined && (typeof value.payloadAvailable !== 'string' || Buffer.byteLength(value.payloadAvailable) > 4096)) {
+    throw new TypeError('MQTT availability payload must be a bounded UTF-8 string.');
+  }
+  const payloadAvailable = typeof value.payloadAvailable === 'string' ? value.payloadAvailable : undefined;
+  if (payloadAvailable !== undefined && availabilityTopic === undefined) throw new TypeError('MQTT availability payload requires its exact topic.');
+  return Object.freeze({ deviceId: mqttText(value.deviceId), entityId: mqttText(value.entityId), featureId: mqttText(value.featureId),
+    name: mqttText(value.name), deviceName: mqttText(value.deviceName), stateTopic, availabilityTopic, payloadAvailable });
+};
+
+/** Capture data without invoking nested accessors before host admission. */
+const mqttData = (valueArg: unknown): unknown => {
+  const seen = new Set<object>();
+  let entries = 0;
+  const copy = (value: unknown, depth: number): unknown => {
+    if (++entries > 200000 || depth > 32) throw new TypeError('MQTT configuration data exceeds its bounds.');
+    if (value === null || value === undefined || typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value !== 'object' || seen.has(value)) throw new TypeError('MQTT configuration requires finite acyclic data.');
+    seen.add(value);
+    try {
+      if (Array.isArray(value)) {
+        if (Reflect.ownKeys(value).length !== value.length + 1) throw new TypeError('MQTT configuration arrays require exact data entries.');
+        const result: unknown[] = [];
+        for (let index = 0; index < value.length; index++) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+          if (!descriptor?.enumerable || !('value' in descriptor)) throw new TypeError('MQTT configuration arrays cannot contain accessors or holes.');
+          result.push(copy(descriptor.value as unknown, depth + 1));
+        }
+        return result;
+      }
+      if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        throw new TypeError('MQTT configuration requires plain data objects.');
+      }
+      const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+      for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key !== 'string' || !descriptor?.enumerable || !('value' in descriptor)) throw new TypeError('MQTT configuration cannot contain accessors.');
+        result[key] = copy(descriptor.value as unknown, depth + 1);
+      }
+      return result;
+    } finally { seen.delete(value); }
+  };
+  return copy(valueArg, 0);
+};
+
+export const normalizeMqttIntegrationConfig = (valueArg: unknown): IMqttConfig & { homeId: string } => {
+  const fields = mqttRecord(valueArg, ['homeId', 'mode', 'host', 'port', 'protocol', 'credentialKey', 'allowUnencryptedLan', 'mappings',
+    'clientId', 'keepalive', 'clean', 'discovery', 'discoveryPrefix', 'birthMessage', 'willMessage', 'subscriptions',
+    'discoveryMessages', 'retainedMessages', 'entities', 'connectTimeoutMs', 'operationTimeoutMs', 'reconnectPeriodMs',
+    'maxMessageTopics', 'maxPayloadBytes', 'maxBufferedBytes']);
+  const value = mqttData(fields) as Record<string, unknown>;
+  const homeId = mqttText(value.homeId);
+  if (value.mode !== undefined && value.mode !== 'discovery' && value.mode !== 'selected-topics') throw new TypeError('Unsupported MQTT mapping mode.');
+  if (value.protocol !== undefined && value.protocol !== 'mqtt' && value.protocol !== 'mqtts') throw new TypeError('Unsupported MQTT transport.');
+  const protocol = value.protocol === 'mqtts' ? 'mqtts' : 'mqtt';
+  const host = value.host === undefined ? undefined : mqttText(value.host, 253);
+  if (host && (/[\s/@?#\\:]/u.test(host) || host === '.')) throw new TypeError('MQTT host must be a selected hostname or IPv4 address, without URL or credentials.');
+  if (value.allowUnencryptedLan !== undefined && typeof value.allowUnencryptedLan !== 'boolean') throw new TypeError('MQTT LAN consent must be explicit.');
+  if (host && protocol === 'mqtt' && value.allowUnencryptedLan !== true) throw new TypeError('Unencrypted MQTT requires explicit LAN consent.');
+  const credentialKey = value.credentialKey === undefined ? undefined : mqttText(value.credentialKey);
+  const port = integer(value.port, 65535) ?? (protocol === 'mqtts' ? 8883 : 1883);
+  integer(value.connectTimeoutMs, 2147483647);
+  integer(value.operationTimeoutMs, 2147483647);
+  integer(value.reconnectPeriodMs, 2147483647, 0);
+  integer(value.keepalive, 65535, 0);
+  const topicLimit = integer(value.maxMessageTopics, 100000) ?? 4096;
+  integer(value.maxPayloadBytes, 16777216);
+  integer(value.maxBufferedBytes, 1073741824);
+  if (value.clean !== undefined && typeof value.clean !== 'boolean') throw new TypeError('MQTT clean session must be a boolean.');
+  if (value.discovery !== undefined && typeof value.discovery !== 'boolean') throw new TypeError('MQTT discovery must be a boolean.');
+  if (value.clientId !== undefined) mqttText(value.clientId);
+  if (value.clean === false && value.clientId === undefined) throw new TypeError('Persistent MQTT sessions require an explicit client ID.');
+  if (value.mode === 'selected-topics') {
+    if (!host || !Array.isArray(value.mappings) || !value.mappings.length || value.mappings.length > topicLimit) {
+      throw new TypeError('Selected MQTT requires a broker and bounded explicit mappings.');
+    }
+    if (value.discovery === true || value.birthMessage !== undefined && value.birthMessage !== false
+      || value.willMessage !== undefined && value.willMessage !== false || value.clean === false
+      || value.reconnectPeriodMs !== undefined && value.reconnectPeriodMs !== 0
+      || ['subscriptions', 'discoveryMessages', 'retainedMessages', 'entities', 'discoveryPrefix'].some((key) => value[key] !== undefined)) {
+      throw new TypeError('Selected MQTT mappings cannot enable discovery, broker effects, fixtures or persistent sessions.');
+    }
+    const mappings = value.mappings.map((itemArg: unknown) => mapping(itemArg));
+    const entities = new Set<string>();
+    const features = new Set<string>();
+    const devices = new Map<string, string>();
+    for (const item of mappings) {
+      const feature = JSON.stringify([item.deviceId, item.featureId]);
+      if (entities.has(item.entityId) || features.has(feature) || devices.has(item.deviceId) && devices.get(item.deviceId) !== item.deviceName) {
+        throw new TypeError('Selected MQTT mappings require unique entities/features and consistent device names.');
+      }
+      entities.add(item.entityId); features.add(feature); devices.set(item.deviceId, item.deviceName);
+    }
+    const subscriptions = [...new Set(mappings.flatMap((item) => [item.stateTopic, ...(item.availabilityTopic ? [item.availabilityTopic] : [])]))];
+    if (subscriptions.length > topicLimit) throw new TypeError('Selected MQTT topic limit exceeded.');
+    return Object.freeze({ ...structuredClone(value) as IMqttConfig, homeId, host, port, protocol, credentialKey,
+      mode: 'selected-topics', mappings, discovery: false, birthMessage: false, willMessage: false,
+      clean: true, reconnectPeriodMs: 0 });
+  }
+  if (value.mappings !== undefined) throw new TypeError('MQTT mappings require selected-topics mode.');
+  return Object.freeze({ ...structuredClone(value) as IMqttConfig, homeId, host, port, protocol, credentialKey, mode: 'discovery' });
+};
+
+export const mqttCredentials = (valueArg: unknown): IMqttTransportCredentials => {
+  const value = mqttRecord(valueArg, ['username', 'password', 'ca', 'cert', 'key', 'servername']);
+  const result: IMqttTransportCredentials = {};
+  for (const key of ['username', 'password', 'ca', 'cert', 'key', 'servername'] as const) {
+    const item = value[key];
+    if (item === undefined) continue;
+    if (typeof item !== 'string' || item.length > 1048576 || item.includes('\u0000')) throw new TypeError('MQTT caller credentials are invalid.');
+    result[key] = item;
+  }
+  if ((result.cert === undefined) !== (result.key === undefined)) throw new TypeError('MQTT client certificate and key must be supplied together.');
+  if (result.servername !== undefined) mqttText(result.servername, 253);
+  return result;
+};

package/ts/integrations/mqtt/readme.md

@@ -2,7 +2,9 @@
 
 `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.
+Construct `MqttIntegration` with an optional host-home consistency binding. A selected `credentialKey` requires an explicit constructor `resolveCredentials` callback; a connection without credentials needs neither resolver nor store. Setup and config-flow start require an independently selected `context.homeId`; configuration `homeId` must match it. Configuration accepts endpoint, `credentialKey`, mapping and transport limits, with an explicit `allowUnencryptedLan: true` acknowledgment for plain MQTT. MQTTS is the flow default. Persist credential references rather than usernames, passwords, private CA or client key material. The borrowed resolver receives immutable `{ homeId, credentialKey, signal, deadline }`, with an absolute `performance.now()` deadline, and returns runtime-only `{ username?, password?, ca?, cert?, key?, servername? }` strings. Certificate and key must be supplied together. The caller resolver can retrieve an encrypted credential record through its own actual `NoSqlConfigStore` public API. Any store supplied in native context must match the admitted home and MQTT domain. The integration does not read credentials from context storage automatically or substitute it for a missing resolver. TLS verifies the certificate and hostname. No secret files are read, and provider, database and store remain caller-owned.
+
+Construction is inert. Setup, config-flow work, live runtimes and failed cleanup share the native owner capacity, default 16. Terminal destruction publishes a stable promise before abort and joins actual provider callbacks even after caller cancellation or deadline. A provider that never settles keeps cleanup pending; a late unrelated rejection remains observable through sanitized cleanup. Explicit `retryCleanup()` retries cleanup only, without resolving credentials, reconnecting, subscribing or publishing again.
 
 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.
 
@@ -12,17 +14,24 @@ The adapter reads supported canonical platforms. Writes support default-schema p
 
 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.
 
+The reusable low-level `MqttClient` preserves its first-argument username/password configuration API. Its optional second argument accepts runtime-only `IMqttTransportCredentials` for CA/mTLS use; the integration configuration migration above does not remove that raw-client API.
+
 `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.
+- `getSnapshot(signal?)` preserves historical discovery and state metadata.
+- Synchronous `getCurrentSnapshot()` clones only observations from the current live broker connection. Register state/message handlers before seeding readiness from it; fixtures and earlier connections are excluded, while current retained packets received before SUBACK are included. Eligibility clears before disconnect/error callbacks.
+- `destroy()` closes resources and keeps its terminal promise, including its original failure. Explicit `retryCleanup()` retries retained transport cleanup without replaying connection setup, subscriptions or publishes.
 
 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.
 
+Selected-topic mode uses `mode: 'selected-topics'` and explicit non-empty mappings with owner-selected device, entity and feature IDs, names and one exact `stateTopic`; optional exact `availabilityTopic` uses `payloadAvailable`, default `online`. Payloads remain raw UTF-8 strings and all mapped features are read-only sensors. Only the mapping topic union is subscribed. Wildcards, caller subscription arrays, discovery, birth/will, fixture snapshots, persistent sessions, reconnect and generic publish are refused in this mode. Unselected messages are ignored before caching. Disconnect immediately marks observations unavailable and requires a newly admitted setup. Mapping IDs and broker observations do not attest physical device identity.
+
+Discovery mode remains the default and preserves the existing discovery/control surface. Connection loss during an admitted publish closes that owning connection generation before MQTT.js can replay an unacknowledged effect. Subscription-only reconnection remains supported; old-generation cancellation and cleanup cannot close a successor. No broker acknowledgment proves physical execution or application-level deduplication.
+
 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/samsungtv/readme.md

@@ -1,11 +1,11 @@
 # Samsung Smart TV
 
-The native integration consumes `SamsungTvProtocol` from published `@ecobridge.xyz/devicemanager`. It owns configuration, encrypted pairing and smarthome mapping; the dependency owns HTTP/TLS/WebSocket parsing, identity verification, operation deadlines and transport cleanup.
+The native integration consumes `SamsungTvProtocol` from published `@ecobridge.xyz/devicemanager` 4.11.1. It owns configuration, encrypted pairing, home admission and smarthome mapping; the dependency owns HTTP/TLS/WebSocket parsing, identity verification, operation deadlines and transport cleanup.
 
 Configure an exact `homeId`, the UUID reported by the TV, explicit `httpOrigin` and `websocketOrigin`, and `pairingMode: 'prompt' | 'existing'`. WSS certificate and hostname verification are mandatory. `certificateAuthority` adds an explicitly trusted PEM CA chain; it never disables verification. REST and WSS must use the same host. Local HTTP discovery requires `allowUnencryptedLocalDiscovery: true` and is restricted by the protocol to literal private/link-local/loopback IPv4 or ULA/loopback IPv6. HTTP carries no token or credentials and follows no redirects.
 
 ```typescript
-const integration = new SamsungtvIntegration({ db, keyProvider });
+const integration = new SamsungtvIntegration({ homeId: 'home-one', db, keyProvider });
 const runtime = await integration.setup({
   homeId: 'home-one',
   expectedDeviceId: '2ff68485-c4cb-48c7-a6ac-9c50e44d7084',
@@ -14,14 +14,20 @@ const runtime = await integration.setup({
   certificateAuthority: trustedTvCa,
   allowUnencryptedLocalDiscovery: true,
   pairingMode: 'prompt',
-}, {});
+}, { homeId: 'home-one' });
 ```
 
-The database and external encryption key provider are caller-owned. The default registry constructor instead accepts a context `NoSqlConfigStore` scoped to the exact configured home and `samsungtv` domain. Generic stores and incorrect scopes are rejected. Pairing credentials never appear in config flow results, snapshots, entities or logs. Confirmed tokens are saved through encrypted document models before controls become ready, and are bound to the exact UUID and WSS origin. Existing mode requires prior pairing in the same home. Runtime destroy leaves caller-owned stores/databases open, drains accepted persistence and transports, clears the protocol reference and is terminal. No filesystem application state is written. Clearing JavaScript references does not guarantee physical string zeroization.
+Every setup and config flow requires an independently host-selected context `homeId`. Configuration must match that selection. An optional constructor `homeId` prebinds the integration; otherwise the first valid admission binds it for its lifetime. Another home requires another integration instance. Constructor options, configuration, context, discovery hints and controls are captured as data fields before asynchronous work; accessors cannot supply authority. Config forms derive their home from the captured host context, and integration or flow destruction invalidates outstanding forms.
+
+The standalone `SamsungtvClient` accepts `ISamsungtvClientOptions` containing `{ db, keyProvider }`, or an actual scoped `NoSqlConfigStore`. The integration's `homeId` and `capacity` options belong to `ISamsungtvIntegrationOptions`.
+
+The database and external encryption key provider are caller-owned. The default registry constructor instead accepts a context `NoSqlConfigStore` scoped to the exact configured home and `samsungtv` domain. Generic stores, incorrect scopes and overridden scope claims are rejected. Pairing credentials never appear in config flow results, snapshots, entities or logs. Confirmed tokens are saved through encrypted document models before controls become ready, and are bound to the exact UUID and WSS origin. Existing mode requires prior pairing in the same home. Runtime destroy leaves caller-owned stores/databases open, drains accepted persistence and transports, clears the protocol reference after successful cleanup and is terminal. No filesystem application state is written. Clearing JavaScript references does not guarantee physical string zeroization.
+
+The native owner tracks accepted setup operations, runtimes and failed cleanup under one `capacity` limit (default 16). Cleanup is registered before startup and transferred to the runtime only after successful setup. Integration destruction joins pending setups and every runtime; a failed cleanup retains its handle and capacity until explicit `integration.retryCleanup()`. Client and protocol close promises are published before synchronous abort callbacks and preserve their original result. A late pairing-persistence failure becomes a safe `PERSISTENCE_FAILED` cleanup error. The client also drains its owned encrypted store even when protocol cleanup fails. `client.retryCleanup()` requires terminal destruction and acknowledges settled cleanup through the published protocol/store APIs. Neither cleanup API repeats pairing, token persistence, startup or commands, and neither reopens a destroyed owner. A failed setup can free retained capacity through the integration's cleanup API while an otherwise open integration remains available for an explicitly requested new setup.
 
 Every snapshot reads the current device information and observed power. Failed reads propagate; no manual fallback, guessed playback/source/volume, optimistic state or synthetic availability is produced. Device and entity IDs include the escaped home and exact TV UUID. `power` is read-only; `remote_key` admits one exact currently supported `KEY_` code. Directional keys additionally require the TV's current capability declaration.
 
-Services require the exact owned `deviceId` or `entityId`. Supported media-player services are `turn_off`, `media_play`, `media_pause`, `media_stop`, `volume_up` and `volume_down`. `remote.send_command` accepts exactly `{ command: 'KEY_HOME' }`; `samsungtv.send_key` accepts exactly `{ key: 'KEY_HOME' }`. `samsungtv.snapshot` accepts no data fields. Commands return `{ key, transport: 'sent', effectOutcome: 'indeterminate' }`: Samsung's remote channel does not acknowledge physical effects. Errors retain the protocol's safe code and effect outcome. No command is retried, repeated or replayed and concurrent effects are rejected.
+Services require the exact owned `deviceId` or `entityId`; when both are present, both must match. Feature writes require the exact owned device and writable `remote_key` media feature, with current key capability rechecked by the protocol. Destruction permanently refuses observations and controls. Supported media-player services are `turn_off`, `media_play`, `media_pause`, `media_stop`, `volume_up` and `volume_down`. `remote.send_command` accepts exactly `{ command: 'KEY_HOME' }`; `samsungtv.send_key` accepts exactly `{ key: 'KEY_HOME' }`. `samsungtv.snapshot` accepts no data fields. Commands return `{ key, transport: 'sent', effectOutcome: 'indeterminate' }`: Samsung's remote channel does not acknowledge physical effects. Errors retain the protocol's safe code and effect outcome. No command is retried, repeated or replayed and concurrent effects are rejected.
 
 The previous fixture config, plaintext token/host/port config, arbitrary WebSocket command, repeated keys and optimistic media fields have been removed. Reconfigure using the explicit native config above. `play_pause`, absolute mute/volume assignment, source/app selection, channel keys as track controls, power-on/Wake-on-LAN, press/hold/release, legacy TCP/PIN and Frame Art Mode remain unsupported. An explicit `KEY_MUTE` command is a toggle and is never presented as a boolean mute assignment.
 

package/ts/integrations/samsungtv/samsungtv.classes.client.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../../plugins.js';
 import { NoSqlConfigStore } from '../../core/classes.configstore.js';
-import type { ISamsungtvConfig, ISamsungtvIntegrationOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
+import type { ISamsungtvConfig, ISamsungtvClientOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
 import { normalizeSamsungtvConfig, samsungtvKeys, samsungtvObject, samsungtvString } from './samsungtv.validation.js';
 
 interface IStoredPairing {
@@ -18,24 +18,27 @@ export class SamsungtvClient {
   #protocol?: plugins.ecobridgeDeviceManager.SamsungTvProtocol;
   #start?: Promise<void>;
   #destroy?: Promise<void>;
+  #retryCleanup?: Promise<void>;
   #removeAbort: () => void = () => undefined;
 
-  constructor(configArg: ISamsungtvConfig, optionsArg?: ISamsungtvIntegrationOptions | NoSqlConfigStore, signalArg?: AbortSignal) {
+  constructor(configArg: ISamsungtvConfig, optionsArg?: ISamsungtvClientOptions | NoSqlConfigStore, signalArg?: AbortSignal) {
     this.#config = normalizeSamsungtvConfig(configArg);
     if (optionsArg instanceof NoSqlConfigStore) {
-      const scope = optionsArg.getScope();
+      const scope = NoSqlConfigStore.prototype.getScope.call(optionsArg);
       if (scope.homeId !== this.#config.homeId || scope.integrationDomain !== 'samsungtv') {
         throw new TypeError('Samsung TV requires an encrypted NoSqlConfigStore scoped to the exact configured home and samsungtv domain.');
       }
       this.#store = optionsArg;
       this.#ownsStore = false;
     } else {
-      if (!optionsArg?.db || !optionsArg.keyProvider) throw new TypeError('Samsung TV requires an owner-supplied database and external encryption key provider.');
-      this.#store = new NoSqlConfigStore({ db: optionsArg.db, keyProvider: optionsArg.keyProvider, homeId: this.#config.homeId, integrationDomain: 'samsungtv' });
+      const options = samsungtvObject(optionsArg ?? {}, 'Samsung TV client persistence options');
+      samsungtvKeys(options, ['db', 'keyProvider']);
+      if (!options.db || !options.keyProvider) throw new TypeError('Samsung TV requires an owner-supplied database and external encryption key provider.');
+      this.#store = new NoSqlConfigStore({ db: options.db as ISamsungtvClientOptions['db'], keyProvider: options.keyProvider as ISamsungtvClientOptions['keyProvider'], homeId: this.#config.homeId, integrationDomain: 'samsungtv' });
       this.#ownsStore = true;
     }
     if (signalArg) {
-      const aborted = (): void => { void this.destroy(); };
+      const aborted = (): void => { void this.destroy().catch(() => undefined); };
       if (signalArg.aborted) this.#lifetime.abort(new Error('Samsung TV setup was cancelled.'));
       else {
         signalArg.addEventListener('abort', aborted, { once: true });
@@ -48,7 +51,7 @@ export class SamsungtvClient {
 
   public async start(signalArg?: AbortSignal): Promise<void> {
     this.#assertOpen(signalArg);
-    if (!this.#start) this.#start = this.#initialize(signalArg);
+    if (!this.#start) this.#start = Promise.resolve().then(() => this.#initialize(signalArg));
     await this.#start;
     this.#assertOpen(signalArg);
   }
@@ -67,20 +70,42 @@ export class SamsungtvClient {
 
   public destroy(): Promise<void> {
     if (!this.#destroy) {
+      // Publish before aborting foreign callbacks; retain failed cleanup for explicit acknowledgement.
+      this.#destroy = Promise.resolve().then(() => this.#drain(false));
       this.#lifetime.abort(new Error('Samsung TV client is destroyed.'));
       this.#removeAbort();
-      this.#destroy = (async () => {
-        await this.#protocol?.close();
-        if (this.#start) await Promise.allSettled([this.#start]);
-        await this.#protocol?.close();
-        this.#protocol = undefined;
-        if (this.#ownsStore) await this.#store?.close();
-        this.#store = undefined;
-      })();
+      this.#removeAbort = () => undefined;
     }
     return this.#destroy;
   }
 
+  /** Terminal cleanup only; never repeats pairing persistence, startup or commands. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#destroy) return Promise.reject(new Error('Samsung TV cleanup requires terminal destroy.'));
+    this.#retryCleanup ??= Promise.resolve().then(async () => {
+      await this.#destroy!.catch(() => undefined);
+      await this.#drain(true);
+    });
+    return this.#retryCleanup;
+  }
+
+  async #drain(retryArg: boolean): Promise<void> {
+    const protocol = this.#protocol;
+    const store = this.#store;
+    // Close both owners before joining either: persistence providers may await store cancellation.
+    const cleanup = Promise.allSettled([
+      Promise.resolve().then(() => retryArg ? protocol?.retryCleanup() : protocol?.close()),
+      Promise.resolve().then(() => this.#ownsStore ? (retryArg ? store?.retryCleanup() : store?.close()) : undefined),
+    ]);
+    // Startup errors belong to the start caller; protocol close owns late persistence failures.
+    const [results] = await Promise.all([cleanup, Promise.allSettled(this.#start ? [this.#start] : [])]);
+    if (results[0].status === 'fulfilled') this.#protocol = undefined;
+    if (results[1].status === 'fulfilled') this.#store = undefined;
+    const errors = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+    if (errors.length) throw new AggregateError(errors, 'Samsung TV client cleanup failed; resources remain retained.');
+    this.#start = undefined;
+  }
+
   async #initialize(signalArg?: AbortSignal): Promise<void> {
     const signal = this.#signal(signalArg);
     const store = this.#store;