@smarthome.exchange/integrations 1.0.0 → 3.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).