@smarthome.exchange/integrations 2.0.0 → 3.0.0

package/ts/integrations/mqtt/mqtt.classes.configflow.ts

@@ -1,48 +1,61 @@
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { IMqttConfig } from './mqtt.types.js';
+import { mqttRecord, normalizeMqttIntegrationConfig } from './mqtt.validation.js';
 
 export class MqttConfigFlow implements IConfigFlow<IMqttConfig> {
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(ownerArg: NativeIntegrationOwner = new NativeIntegrationOwner('mqtt')) {
+    this.#scope = ownerArg.createFlowScope();
+  }
+
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IMqttConfig>> {
-    void contextArg;
+    if (candidateArg.integrationDomain !== undefined && candidateArg.integrationDomain !== 'mqtt') return { kind: 'error', error: 'MQTT requires an MQTT candidate.' };
+    let context: INativeAdmissionContext;
+    try { context = this.#scope.admit(contextArg); }
+    catch { return { kind: 'error', error: 'MQTT configuration requires the explicit matching host home and an open flow.' }; }
+    const host = typeof candidateArg.host === 'string' ? candidateArg.host : undefined;
     return {
-      kind: 'form',
-      title: 'Connect MQTT broker',
-      description: 'Configure a local MQTT 3.1.1 broker and Home Assistant-style MQTT discovery.',
+      kind: 'form', title: 'Connect selected MQTT broker',
+      description: 'Use a caller-owned credential reference. Selected topic observations are read-only; discovery mode uses the configured MQTT discovery schema.',
       fields: [
-        { name: 'host', label: 'Broker host', type: 'text', required: true },
+        { name: 'host', label: 'Selected broker host', type: 'text', required: true },
         { name: 'port', label: 'Broker port', type: 'number' },
-        { name: 'protocol', label: 'Protocol', type: 'select', options: [{ label: 'MQTT', value: 'mqtt' }, { label: 'MQTTS', value: 'mqtts' }] },
-        { name: 'username', label: 'Username', type: 'text' },
-        { name: 'password', label: 'Password', type: 'password' },
+        { name: 'protocol', label: 'Protocol', type: 'select', options: [{ label: 'MQTTS', value: 'mqtts' }, { label: 'MQTT', value: 'mqtt' }] },
+        { name: 'mode', label: 'Mapping mode', type: 'select', options: [{ label: 'Selected topics', value: 'selected-topics' }, { label: 'MQTT discovery', value: 'discovery' }] },
+        { name: 'mappings', label: 'Explicit observation mappings', type: 'text' },
+        { name: 'credentialKey', label: 'Caller credential reference', type: 'text' },
+        { name: 'allowUnencryptedLan', label: 'Consent to unencrypted local MQTT', type: 'boolean' },
         { name: 'clientId', label: 'Client ID', type: 'text' },
         { name: 'discoveryPrefix', label: 'Discovery prefix', type: 'text' },
       ],
-      submit: async (valuesArg) => {
-        const host = this.stringValue(valuesArg.host) || candidateArg.host;
-        const protocol = valuesArg.protocol === 'mqtts' ? 'mqtts' : 'mqtt';
-        const port = valuesArg.port ?? candidateArg.port ?? (protocol === 'mqtts' ? 8883 : 1883);
-        if (!host || typeof port !== 'number' || !Number.isSafeInteger(port) || port < 1 || port > 65535) {
-          return { kind: 'error', error: 'A broker host and integer port from 1 through 65535 are required.' };
-        }
-        return {
-          kind: 'done',
-          title: 'MQTT configured',
-          config: {
-            host,
-            port,
-            protocol,
-            username: this.stringValue(valuesArg.username),
-            password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
-            clientId: this.stringValue(valuesArg.clientId),
-            discovery: true,
-            discoveryPrefix: this.stringValue(valuesArg.discoveryPrefix) || 'homeassistant',
-          },
-        };
-      },
+      submit: (valuesArg) => this.#submit(valuesArg, context, host),
     };
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
+  async #submit(valuesArg: Record<string, unknown>, contextArg: INativeAdmissionContext, candidateHostArg?: string): Promise<IConfigFlowStep<IMqttConfig>> {
+    let config: IMqttConfig & { homeId: string };
+    try {
+      const values = mqttRecord(valuesArg, ['homeId', 'host', 'port', 'protocol', 'mode', 'mappings', 'credentialKey',
+        'allowUnencryptedLan', 'clientId', 'discoveryPrefix', 'connectTimeoutMs', 'operationTimeoutMs']);
+      if (values.homeId !== undefined && values.homeId !== contextArg.homeId) throw new TypeError('MQTT form home conflicts with the host home.');
+      const mappings = typeof values.mappings === 'string' ? JSON.parse(values.mappings) as unknown : values.mappings;
+      config = normalizeMqttIntegrationConfig({ ...values, mappings, host: values.host ?? candidateHostArg,
+        protocol: values.protocol ?? 'mqtts', mode: values.mode ?? 'discovery', homeId: contextArg.homeId });
+    } catch { return { kind: 'error', error: 'MQTT values, exact topic mappings or host home are invalid. Supply credential references rather than secrets.' }; }
+    try {
+      return await this.#scope.run(contextArg, config.homeId, async (leaseArg): Promise<IConfigFlowStep<IMqttConfig>> => {
+        leaseArg.assertOpen();
+        return { kind: 'done', title: 'MQTT reference configuration prepared', config };
+      });
+    } catch (error) {
+      if (error instanceof AggregateError) throw error;
+      return { kind: 'error', error: 'MQTT configuration flow is closed or cancelled.' };
+    }
   }
 }

package/ts/integrations/mqtt/mqtt.classes.integration.ts

@@ -1,18 +1,23 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { MqttClient } from './mqtt.classes.client.js';
 import { MqttConfigFlow } from './mqtt.classes.configflow.js';
 import { createMqttDiscoveryDescriptor } from './mqtt.discovery.js';
 import { MqttMapper } from './mqtt.mapper.js';
-import type { IMqttConfig, IMqttPublishOptions } from './mqtt.types.js';
+import { MqttSession } from './mqtt.classes.session.js';
+import { normalizeMqttIntegrationConfig } from './mqtt.validation.js';
+import type { IMqttConfig, IMqttIntegrationOptions, IMqttPublishOptions } from './mqtt.types.js';
 
 export class MqttIntegration extends BaseIntegration<IMqttConfig> {
   public readonly domain = 'mqtt';
   public readonly displayName = 'MQTT';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createMqttDiscoveryDescriptor();
-  public readonly configFlow = new MqttConfigFlow();
+  public readonly configFlow: MqttConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: IMqttIntegrationOptions;
   public readonly metadata = {
     source: 'home-assistant/core',
     upstreamPath: 'homeassistant/components/mqtt',
@@ -22,20 +27,31 @@ export class MqttIntegration extends BaseIntegration<IMqttConfig> {
     qualityScale: 'platinum',
   };
 
+  constructor(optionsArg: IMqttIntegrationOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner('mqtt', { homeId: optionsArg.homeId, capacity: optionsArg.capacity });
+    this.#options = Object.freeze({ resolveCredentials: optionsArg.resolveCredentials });
+    this.configFlow = new MqttConfigFlow(this.#owner);
+  }
+
   public async setup(configArg: IMqttConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    const client = new MqttClient(configArg);
-    const runtime = new MqttRuntime(client);
-    try {
-      await client.start(contextArg.abortSignal);
+    const config = normalizeMqttIntegrationConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const session = new MqttSession(config, leaseArg, this.#options.resolveCredentials);
+      let runtime: MqttRuntime | undefined;
+      let cleanupAttempts = 0;
+      const closeSession = (): Promise<void> => cleanupAttempts++ === 0 ? session.close() : session.retryCleanup();
+      leaseArg.own(() => runtime ? runtime.cleanup() : closeSession());
+      const client = await session.start();
+      leaseArg.assertOpen();
+      runtime = new MqttRuntime(client, config, leaseArg, closeSession);
+      leaseArg.promoteToRuntime();
       return runtime;
-    } catch (error) {
-      try { await runtime.destroy(); }
-      catch (cleanupError) { throw new AggregateError([error, cleanupError], 'MQTT setup and cleanup failed.'); }
-      throw error;
-    }
+    });
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantMqttIntegration extends MqttIntegration {}
@@ -51,25 +67,30 @@ class MqttRuntime implements IIntegrationRuntime {
   private updateRequested = false;
   private updating = false;
   private destroyed = false;
+  private readonly operations = new Set<Promise<unknown>>();
+  private readonly failures = new Set<unknown>();
+  private readonly ownerAbort = (): void => { this.destroyed = true; };
 
-  constructor(private readonly client: MqttClient) {
+  constructor(private readonly client: MqttClient, private readonly config: IMqttConfig,
+    private readonly lease: INativeSetupLease, private readonly closeSession: () => Promise<void>) {
     this.removeMessageHandler = client.onMessage(() => this.queueUpdate());
     this.removeConnectionHandler = client.onConnectionState((stateArg) => {
       if (stateArg.error) this.emit({ type: 'error', integrationDomain: this.domain, data: { message: stateArg.error.message }, timestamp: Date.now() });
       this.queueUpdate();
     });
+    lease.signal.addEventListener('abort', this.ownerAbort, { once: true });
   }
 
   public isHealthy(): boolean {
-    return this.client.isHealthy();
+    return !this.destroyed && this.client.isHealthy();
   }
 
   public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
-    return MqttMapper.toDevices(await this.client.getSnapshot(abortSignalArg));
+    return this.operation(async () => MqttMapper.toDevices(await this.client.getSnapshot(this.signal(abortSignalArg))));
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
-    return MqttMapper.toEntities(await this.client.getSnapshot());
+    return this.operation(async () => MqttMapper.toEntities(await this.client.getSnapshot(this.signal())));
   }
 
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
@@ -92,35 +113,64 @@ class MqttRuntime implements IIntegrationRuntime {
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    try {
-      let command: IMqttPublishOptions | undefined;
-      if (requestArg.domain === 'mqtt') {
-        if (requestArg.service !== 'publish') return { success: false, error: 'Unsupported MQTT broker service.' };
-        command = this.publishOptionsFromRequest(requestArg);
-      } else command = MqttMapper.commandForService(await this.client.getSnapshot(), requestArg);
-      if (!command) return { success: false, error: 'MQTT service requires an available, unambiguous supported target and valid input.' };
-      await this.client.publish(command);
-      return { success: true };
-    } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (this.config.mode === 'selected-topics') return { success: false, error: 'Selected MQTT topic mappings are read-only.' };
+    return this.operation(async () => {
+      try {
+        let command: IMqttPublishOptions | undefined;
+        if (requestArg.domain === 'mqtt') {
+          if (requestArg.service !== 'publish') return { success: false, error: 'Unsupported MQTT broker service.' };
+          command = this.publishOptionsFromRequest(requestArg);
+        } else command = MqttMapper.commandForService(await this.client.getSnapshot(), requestArg);
+        if (!command) return { success: false, error: 'MQTT service requires an available, unambiguous supported target and valid input.' };
+        await this.client.publish(command, this.signal());
+        return { success: true, data: { transportAccepted: true, brokerAcknowledged: command.qos === 1 || command.qos === 2, physicalOutcomeConfirmed: false } };
+      } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    });
   }
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
-    try {
-      const command = MqttMapper.commandForFeature(await this.client.getSnapshot(abortSignalArg), requestArg);
-      if (!command) return { success: false, error: 'MQTT feature requires an available, unambiguous supported target and valid value.' };
-      await this.client.publish(command, abortSignalArg);
-      return { success: true };
-    } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (this.config.mode === 'selected-topics') return { success: false, error: 'Selected MQTT topic mappings are read-only.' };
+    return this.operation(async () => {
+      try {
+        const signal = this.signal(abortSignalArg);
+        const command = MqttMapper.commandForFeature(await this.client.getSnapshot(signal), requestArg);
+        if (!command) return { success: false, error: 'MQTT feature requires an available, unambiguous supported target and valid value.' };
+        await this.client.publish(command, signal);
+        return { success: true, data: { transportAccepted: true, brokerAcknowledged: command.qos === 1 || command.qos === 2, physicalOutcomeConfirmed: false } };
+      } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    });
   }
 
-  public async destroy(): Promise<void> {
+  public destroy(): Promise<void> { return this.lease.close(); }
+
+  public async cleanup(): Promise<void> {
     this.destroyed = true;
     this.removeMessageHandler();
     this.removeConnectionHandler();
-    for (const cleanup of [...this.subscriptionCleanups]) await cleanup();
+    const cleanups = [...this.subscriptionCleanups];
     this.handlers.clear();
-    await this.client.destroy();
-    await this.updatePromise;
+    this.lease.signal.removeEventListener('abort', this.ownerAbort);
+    const results = await Promise.allSettled([
+      ...cleanups.map((cleanup) => Promise.resolve().then(cleanup)), this.closeSession(), this.updatePromise,
+      ...[...this.operations].map((operation) => operation.then(() => undefined, () => undefined)),
+    ]);
+    const failures = [...this.failures, ...results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : [])];
+    this.failures.clear();
+    if (failures.length) throw new AggregateError(failures, 'MQTT runtime cleanup failed; retry cleanup explicitly.');
+  }
+
+  private signal(signalArg?: AbortSignal): AbortSignal {
+    this.lease.assertOpen();
+    if (this.destroyed) throw new Error('MQTT runtime has been destroyed.');
+    return signalArg ? AbortSignal.any([this.lease.signal, signalArg]) : this.lease.signal;
+  }
+
+  private operation<TValue>(workArg: () => Promise<TValue>): Promise<TValue> {
+    this.signal();
+    const work = Promise.resolve().then(workArg);
+    this.operations.add(work);
+    void work.then(() => { this.operations.delete(work); }, () => { this.operations.delete(work); });
+    return work;
   }
 
   private queueUpdate(): void {
@@ -129,7 +179,16 @@ class MqttRuntime implements IIntegrationRuntime {
     if (this.updating) return;
     this.updating = true;
     this.updatePromise = this.updateSnapshots().catch((error: unknown) => {
-      if (!this.destroyed) this.emit({ type: 'error', integrationDomain: this.domain, data: { message: error instanceof Error ? error.message : String(error) }, timestamp: Date.now() });
+      if (!this.destroyed || error instanceof AggregateError) this.failures.add(error);
+      if (!this.destroyed) {
+        try { this.emit({ type: 'error', integrationDomain: this.domain, data: { message: error instanceof Error ? error.message : String(error) }, timestamp: Date.now() }); }
+        catch (callbackError) { this.failures.add(callbackError); }
+      }
+      if (this.failures.size) {
+        this.destroyed = true;
+        // Stop admitting updates after a delivery failure; the retained lease owns reporting/retry.
+        void this.lease.close().catch(() => undefined);
+      }
     }).finally(() => {
       this.updating = false;
       if (this.updateRequested && !this.destroyed) this.queueUpdate();
@@ -158,7 +217,9 @@ class MqttRuntime implements IIntegrationRuntime {
   }
 
   private emit(eventArg: IIntegrationEvent): void {
-    for (const handler of this.handlers) handler(eventArg);
+    const failures: unknown[] = [];
+    for (const handler of this.handlers) { try { handler(eventArg); } catch (error) { failures.push(error); } }
+    if (failures.length) throw new AggregateError(failures, 'MQTT event callbacks failed.');
   }
 
   private publishOptionsFromRequest(requestArg: IServiceCallRequest): IMqttPublishOptions | undefined {

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 {