@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/sonos/sonos.mapper.ts

@@ -8,9 +8,10 @@ export class SonosMapper {
     const deviceId = this.deviceId(snapshotArg);
     const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
       { id: 'playback', capability: 'media', name: 'Playback', readable: true,
-        writable: snapshotArg.group.coordinatorUid === snapshotArg.speakerInfo.uid },
-      { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
-      { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
+        writable: snapshotArg.controlAllowed && snapshotArg.group.coordinatorUid === snapshotArg.speakerInfo.uid
+          && snapshotArg.capabilities.transportActions.some((action) => ['Play', 'Pause', 'Stop'].includes(action) && snapshotArg.capabilities.declaredTransportActions.includes(action)) },
+      { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: snapshotArg.controlAllowed && snapshotArg.capabilities.volumeWritable, unit: '%' },
+      { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: snapshotArg.controlAllowed && snapshotArg.capabilities.muteWritable },
     ];
     const state: plugins.shxInterfaces.data.IDeviceState[] = [
       { featureId: 'playback', value: this.playbackState(snapshotArg), updatedAt },
@@ -33,6 +34,7 @@ export class SonosMapper {
       features,
       state,
       metadata: {
+        homeId: snapshotArg.homeId,
         uid: snapshotArg.speakerInfo.uid,
         serialNumber: snapshotArg.speakerInfo.serialNumber,
         softwareVersion: snapshotArg.speakerInfo.softwareVersion,
@@ -41,20 +43,23 @@ export class SonosMapper {
         coordinatorUid: snapshotArg.group.coordinatorUid,
         groupMemberUids: [...snapshotArg.group.memberUids],
         stateSource: 'local_poll',
+        physicalEffectConfirmed: false,
+        capabilities: structuredClone(snapshotArg.capabilities),
       },
     }];
   }
 
   public static toEntities(snapshotArg: ISonosSnapshot): IIntegrationEntity[] {
     return [{
-      id: this.entityId(snapshotArg.speakerInfo.uid),
-      uniqueId: `sonos_${this.slug(snapshotArg.speakerInfo.uid)}`,
+      id: this.entityId(snapshotArg.homeId, snapshotArg.speakerInfo.uid),
+      uniqueId: this.deviceId(snapshotArg),
       integrationDomain: 'sonos',
       deviceId: this.deviceId(snapshotArg),
       platform: 'media_player',
       name: snapshotArg.speakerInfo.zoneName,
       state: this.playbackState(snapshotArg),
       attributes: {
+        homeId: snapshotArg.homeId,
         volumeLevel: snapshotArg.volume / 100,
         muted: snapshotArg.muted,
         mediaTitle: snapshotArg.positionInfo.title,
@@ -91,11 +96,11 @@ export class SonosMapper {
   }
 
   public static deviceId(snapshotArg: ISonosSnapshot): string {
-    return `sonos.player.${this.slug(snapshotArg.speakerInfo.uid)}`;
+    return `sonos.player.${encodeURIComponent(snapshotArg.homeId)}.${this.slug(snapshotArg.speakerInfo.uid)}`;
   }
 
-  public static entityId(uid: string): string {
-    return `media_player.sonos_${this.slug(uid)}`;
+  public static entityId(homeId: string, uid: string): string {
+    return `media_player.sonos.${encodeURIComponent(homeId)}.${this.slug(uid)}`;
   }
 
   private static slug(valueArg: string): string {

package/ts/integrations/sonos/sonos.matchers.ts

@@ -1,5 +1,5 @@
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
-import { isSonosDataRecord, normalizeSonosConfig, normalizeSonosUid } from './sonos.config.js';
+import { isSonosDataRecord, normalizeSonosEndpoint, normalizeSonosUid } from './sonos.config.js';
 import type { ISonosManualEntry, ISonosMdnsRecord, ISonosSsdpRecord } from './sonos.types.js';
 
 const sonosUpnpSt = 'urn:schemas-upnp-org:device:ZonePlayer:1';
@@ -8,7 +8,7 @@ const noMatch = (reason: string): IDiscoveryMatch => ({ matched: false, confiden
 function candidateMatch(source: IDiscoveryCandidate['source'], host: unknown, port: unknown, uid?: unknown): IDiscoveryMatch {
   try {
     if (typeof host !== 'string' || typeof port !== 'number' || (uid !== undefined && typeof uid !== 'string')) throw new Error('Sonos candidate fields are invalid.');
-    const config = normalizeSonosConfig({ host, port, ...(uid ? { expectedUid: uid } : {}) });
+    const config = normalizeSonosEndpoint({ host, port, ...(uid ? { expectedUid: uid } : {}) });
     return {
       matched: true, confidence: uid ? 'high' : 'medium', reason: 'Candidate identifies a local Sonos endpoint; setup verifies the renderer.',
       normalizedDeviceId: config.expectedUid,

package/ts/integrations/sonos/sonos.types.ts

@@ -1,4 +1,4 @@
-export interface ISonosConfig {
+export interface ISonosEndpointConfig {
   host: string;
   port?: number;
   expectedUid?: string;
@@ -7,6 +7,16 @@ export interface ISonosConfig {
   pollIntervalMs?: number;
 }
 
+export interface ISonosConfig extends ISonosEndpointConfig {
+  homeId: string;
+}
+
+/** Host-owned permission; never accepted from stored config, a form or discovery. */
+export interface ISonosOwnerOptions {
+  readonly homeId?: string;
+  readonly allowControl?: boolean;
+}
+
 export interface ISonosSpeakerInfo {
   uid: string;
   zoneName: string;
@@ -37,6 +47,8 @@ export interface ISonosPositionInfo {
 }
 
 export interface ISonosSnapshot {
+  homeId: string;
+  controlAllowed: boolean;
   speakerInfo: ISonosSpeakerInfo;
   transportInfo: ISonosTransportInfo;
   positionInfo: ISonosPositionInfo;
@@ -44,6 +56,23 @@ export interface ISonosSnapshot {
   muted: boolean;
   group: ISonosGroup;
   observedAt: string;
+  capabilities: ISonosCapabilities;
+}
+
+export interface ISonosCapabilities {
+  readonly transportActions: readonly string[];
+  readonly declaredTransportActions: readonly string[];
+  readonly volumeWritable: boolean;
+  readonly muteWritable: boolean;
+}
+
+export interface ISonosControlResult {
+  readonly acknowledgedActions: readonly string[];
+  readonly snapshot: ISonosSnapshot;
+  readonly outcome: 'observed-target' | 'observed-different' | 'observed-state';
+  readonly requestedValue?: string | number | boolean;
+  readonly observedValue?: string | number | boolean;
+  readonly physicalEffectConfirmed: false;
 }
 
 export interface ISonosGroup {

package/ts/integrations/tasmota/readme.md

@@ -1,25 +1,36 @@
 # Native Tasmota runtime
 
-This integration connects directly to a MQTT broker through the package's shared `MqttClient`. Configure each Tasmota device's broker and unique `Topic` before setup. No Home Assistant connection is required.
+This integration connects directly to a MQTT broker through the package's shared `MqttSession`, which owns credential resolution and its `MqttClient` transport. Configure each Tasmota device's broker and unique `Topic` before setup. No Home Assistant connection is required.
 
 ```typescript
 import { HomeAssistantTasmotaIntegration } from '@smarthome.exchange/integrations';
 
-const runtime = await new HomeAssistantTasmotaIntegration().setup({
-  broker: { host: 'mqtt.home', protocol: 'mqtts', username, password },
+const integration = new HomeAssistantTasmotaIntegration({ enableControls: true });
+const runtime = await integration.setup({
+  homeId: selectedHomeId,
+  authentication: { mode: 'credential-reference', credentialRef: 'broker-main' },
+  broker: { host: 'mqtt.home', protocol: 'mqtts' },
   devices: [{ topic: 'desk', relays: [1], brightness: true }],
   initialSnapshotTimeoutMs: 10_000,
-}, { abortSignal });
+}, { homeId: selectedHomeId, configStore: borrowedEncryptedStore, abortSignal });
 
 try {
   const [device] = await runtime.devices();
   const feature = device.features.find((feature) => feature.id === 'power_1');
   if (feature) await runtime.writeFeature({ device, feature, value: false });
 } finally {
-  await runtime.destroy();
+  await integration.destroy();
 }
 ```
 
+The embedding host must independently supply its selected `homeId` in setup and config-flow context. The configured home must match it. An optional constructor `homeId` adds an immutable constraint; without it, the first admitted setup or flow fixes the instance's home even if setup fails. Discovery metadata, editable values and store scope cannot select the home. Default registry construction remains inert. Entity identifiers include the captured host home. This contract relies on the embedding host's authorization boundary; a home string is not an authentication token.
+
+Authentication is explicit: `authentication: { mode: 'anonymous' }` selects a broker requiring no authentication. Otherwise, a credential reference requires an actual matching borrowed `NoSqlConfigStore` or a runtime-only constructor `credentialResolver`. Legacy plaintext broker username/password configuration fails with an explicit reconfiguration requirement. Flow secret inputs are transient; an admitted encrypted store creates an insert-only reference and the returned configuration contains no secrets. A cancelled late credential write is joined and removed before flow shutdown completes. Anonymous mode never substitutes for a missing or failed credential source.
+
+A constructor resolver receives frozen `{ homeId, credentialRef, broker: { host, port, protocol }, signal, deadlineMonotonicMs }`; the deadline uses `performance.now()`. It returns a plain version1 record containing exactly that broker identity and optional username/password or TLS ca/cert/key/servername. Certificate and private key must be paired; TLS material requires mqtts. A result for another broker is rejected before connecting. Tasmota adapts this broker-bound contract to the shared MQTT session resolver. The session fences startup on cancellation or deadline and retains the actual resolver promise for shutdown, so an ignored cancellation or late result cannot connect. Resolver failures are sanitized and remain observable through session cleanup; explicit `retryCleanup()` acknowledges drained failures without resolving credentials again. The caller owns its resolver, store, database and key provider; the integration closes none of them.
+
+Relay and brightness writes require the embedding owner's runtime-only constructor `enableControls: true`. This permission is not accepted from config forms. Without it, controls remain readable and writes fail before publishing. Every admitted command shares the owner's bounded capacity with pending setups, flows, runtimes and failed cleanup handles (default16, adjustable with constructor `capacity`). Integration destruction is terminal, drains every owned runtime and pending operation, and returns a stable close promise. Runtime destruction releases its owned lease. Failed cleanup remains retained; `integration.retryCleanup()` retries resource cleanup only, never setup, authentication, subscription or control commands.
+
 `relays` defaults to `[1]`; use `[]` for sensor-only devices. `brightness: true` enables the single-channel `Dimmer` command with integer percentage values from 0 through 100. Device identifiers default to `tasmota:<encoded-topic>` and can be assigned explicitly through `id`. `fullTopic` defaults to `%prefix%/%topic%/`; custom patterns must end in `/` and include each token exactly once. Only those two substitution tokens are supported. Custom `prefixes` specify all three command, status and telemetry prefixes. `powerOnPayload` and `powerOffPayload` describe customized `StateText` output; commands still use the standard `ON` and `OFF` arguments.
 
 Setup shares one deadline across the broker connection, subscription acknowledgments, state queries and first fresh snapshots. It requests `State` and `Status 10` for every selected device. A fresh nonretained `STATE`, `STATUS11` or complete `RESULT` state response must report every configured control before that device becomes ready. Retained state can provide an offline snapshot, but cannot establish readiness or overwrite ready state. The protocol does not correlate MQTT 3.1.1 command responses; readiness establishes current nonretained state after a query, rather than proving which request caused the message.

package/ts/integrations/tasmota/tasmota.classes.integration.ts

@@ -1,15 +1,21 @@
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
 import type { IIntegrationSetupContext } from '../../core/types.js';
 import { createTasmotaDiscoveryDescriptor, TasmotaConfigFlow } from './tasmota.discovery.js';
 import { TasmotaRuntime } from './tasmota.classes.runtime.js';
 import type { IHomeAssistantTasmotaConfig } from './tasmota.types.js';
+import type { ITasmotaIntegrationOptions } from './tasmota.types.js';
+import { normalizeTasmotaConfig } from './tasmota.config.js';
+import { tasmotaOptions } from './tasmota.credentials.js';
 
 export class HomeAssistantTasmotaIntegration extends BaseIntegration<IHomeAssistantTasmotaConfig> {
   public readonly domain = 'tasmota';
   public readonly displayName = 'Tasmota';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createTasmotaDiscoveryDescriptor();
-  public readonly configFlow = new TasmotaConfigFlow();
+  public readonly configFlow: TasmotaConfigFlow;
+  private readonly owner: NativeIntegrationOwner;
+  private readonly options: ITasmotaIntegrationOptions;
   public readonly metadata = {
     source: 'home-assistant/core',
     upstreamPath: 'homeassistant/components/tasmota',
@@ -19,12 +25,24 @@ export class HomeAssistantTasmotaIntegration extends BaseIntegration<IHomeAssist
     scope: 'selected-device-relays-brightness-sensors',
   };
 
+  constructor(optionsArg: ITasmotaIntegrationOptions = {}) {
+    super();
+    this.options = tasmotaOptions(optionsArg);
+    this.owner = new NativeIntegrationOwner(this.domain, { homeId: this.options.homeId, capacity: this.options.capacity });
+    this.configFlow = new TasmotaConfigFlow(this.options, this.owner);
+  }
+
   public async setup(configArg: IHomeAssistantTasmotaConfig, contextArg: IIntegrationSetupContext): Promise<TasmotaRuntime> {
-    contextArg.abortSignal?.throwIfAborted();
-    const runtime = new TasmotaRuntime(configArg);
-    await runtime.start(contextArg.abortSignal);
-    return runtime;
+    const config = normalizeTasmotaConfig(configArg);
+    return this.owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const runtime = new TasmotaRuntime(config, leaseArg, this.options, this.owner);
+      leaseArg.own(() => runtime.dispose());
+      await runtime.start(leaseArg.signal);
+      leaseArg.promoteToRuntime();
+      return runtime;
+    });
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> { return this.owner.close(); }
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }

package/ts/integrations/tasmota/tasmota.classes.runtime.ts

@@ -1,32 +1,43 @@
 import * as plugins from '../../plugins.js';
 import { DeviceCommunicationError } from '../../core/errors.js';
+import type { INativeSetupLease, NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IServiceCallResult } from '../../core/types.js';
-import { MqttClient } from '../mqtt/mqtt.classes.client.js';
-import type { IMqttMessage } from '../mqtt/mqtt.types.js';
+import type { MqttClient } from '../mqtt/mqtt.classes.client.js';
+import { MqttSession } from '../mqtt/mqtt.classes.session.js';
+import type { IMqttMessage, TMqttCredentialResolver } from '../mqtt/mqtt.types.js';
 import { parseTasmotaRecord, tasmotaRecord, TasmotaMapper } from './tasmota.mapper.js';
-import { normalizeTasmotaConfig } from './tasmota.config.js';
-import type { IHomeAssistantTasmotaConfig, ITasmotaConfig, ITasmotaDeviceState, ITasmotaSelectedDevice } from './tasmota.types.js';
+import { tasmotaBrokerIdentity, tasmotaCredential, tasmotaCredentialKey } from './tasmota.credentials.js';
+import type { ITasmotaConfig, ITasmotaDeviceState, ITasmotaIntegrationOptions, ITasmotaSelectedDevice } from './tasmota.types.js';
 
 export class TasmotaRuntime implements IIntegrationRuntime {
   public readonly domain = 'tasmota';
-  private readonly config: ITasmotaConfig;
-  private readonly client: MqttClient;
+  public readonly homeId: string;
+  private session?: MqttSession;
+  private client?: MqttClient;
   private readonly lifetime = new AbortController();
   private readonly states = new Map<string, ITasmotaDeviceState>();
   private readonly listeners = new Set<(eventArg: IIntegrationEvent) => void>();
   private readonly changed = new Set<() => void>();
   private readonly subscriptionCleanups = new Set<() => void>();
-  private readonly stopConnectionListener: () => void;
+  private stopConnectionListener?: () => void;
+  private readonly operations = new Set<Promise<unknown>>();
   private initializing = true;
   private started = false;
   private destroyed = false;
   private destroyPromise?: Promise<void>;
+  private disposePromise?: Promise<void>;
+  private cleanupFailed = false;
 
-  constructor(configArg: IHomeAssistantTasmotaConfig) {
-    this.config = normalizeTasmotaConfig(configArg);
-    this.client = new MqttClient(this.config.broker);
+  constructor(private readonly config: ITasmotaConfig, private readonly lease: INativeSetupLease,
+    private readonly options: ITasmotaIntegrationOptions, private readonly owner: NativeIntegrationOwner) {
+    this.homeId = lease.context.homeId;
+    lease.assertOpen();
+    if (config.homeId !== this.homeId) throw new TypeError('Tasmota runtime must match its admitted host home.');
     for (const device of this.config.devices) this.states.set(device.id, { generation: 0, ready: false, online: false, queryPending: false, updatedAt: new Date(0).toISOString(), controls: {}, sensors: {} });
-    this.stopConnectionListener = this.client.onConnectionState((stateArg) => {
+  }
+
+  private observeConnection(clientArg: MqttClient): void {
+    this.stopConnectionListener = clientArg.onConnectionState((stateArg) => {
       if (this.destroyed) return;
       if (!stateArg.connected) {
         for (const device of this.config.devices) this.markOffline(device);
@@ -41,33 +52,50 @@ export class TasmotaRuntime implements IIntegrationRuntime {
     this.checkActive(abortSignalArg);
     if (this.started) throw new DeviceCommunicationError('Tasmota runtime has already started.');
     this.started = true;
-    try {
-      await this.withDeadline(async (signalArg) => {
-        await this.client.start(signalArg);
-        for (const device of this.config.devices) {
-          await this.client.subscribe(`${device.statusBase}#`, (messageArg) => this.receive(device, messageArg), signalArg);
-          await this.client.subscribe(`${device.telemetryBase}#`, (messageArg) => this.receive(device, messageArg), signalArg);
-        }
-        await this.refresh(this.config.devices, signalArg);
-      }, abortSignalArg);
-      this.initializing = false;
-    } catch (errorArg) {
-      await this.destroy();
-      throw errorArg;
-    }
+    const deadlineMonotonicMs = performance.now() + this.config.initialSnapshotTimeoutMs;
+    await this.withDeadline(async (signalArg) => {
+      const broker = tasmotaBrokerIdentity(this.config);
+      const reference = this.config.authentication.mode === 'credential-reference' ? this.config.authentication.credentialRef : undefined;
+      const resolver = this.options.credentialResolver;
+      const store = this.lease.context.configStore;
+      if (reference && !resolver && !store) throw new DeviceCommunicationError('Tasmota credential reference requires an explicit credential source.');
+      const resolveCredentials: TMqttCredentialResolver | undefined = reference ? async (requestArg) => {
+        const request = Object.freeze({ homeId: requestArg.homeId, credentialRef: requestArg.credentialKey, broker,
+          signal: AbortSignal.any([requestArg.signal, signalArg]), deadlineMonotonicMs: Math.min(deadlineMonotonicMs, requestArg.deadline) });
+        const credential = resolver ? await resolver(request) : await store!.get<unknown>(tasmotaCredentialKey(requestArg.credentialKey));
+        return tasmotaCredential(credential, broker);
+      } : undefined;
+      this.checkActive(signalArg);
+      const remaining = Math.floor(deadlineMonotonicMs - performance.now());
+      if (remaining < 1) throw new DeviceCommunicationError('Tasmota fresh state deadline exceeded.');
+      const session = new MqttSession({ ...this.config.broker, homeId: this.homeId, credentialKey: reference,
+        connectTimeoutMs: Math.min(this.config.broker.connectTimeoutMs ?? remaining, remaining) }, this.lease, resolveCredentials);
+      // The runtime's lease owns dispose() before session startup enters the provider or allocates transport.
+      this.session = session;
+      const client = await session.start();
+      this.checkActive(signalArg);
+      this.client = client;
+      this.observeConnection(client);
+      for (const device of this.config.devices) {
+        await client.subscribe(`${device.statusBase}#`, (messageArg) => this.receive(device, messageArg), signalArg);
+        await client.subscribe(`${device.telemetryBase}#`, (messageArg) => this.receive(device, messageArg), signalArg);
+      }
+      await this.refresh(this.config.devices, signalArg);
+    }, abortSignalArg);
+    this.initializing = false;
   }
 
   public isHealthy(): boolean {
-    return !this.destroyed && this.client.isHealthy() && this.config.devices.every((deviceArg) => this.ready(deviceArg));
+    return !this.destroyed && this.client?.isHealthy() === true && this.config.devices.every((deviceArg) => this.ready(deviceArg));
   }
 
   public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
     this.checkActive(abortSignalArg);
-    return this.config.devices.map((deviceArg) => TasmotaMapper.device(deviceArg, this.state(deviceArg), this.client.connected));
+    return this.config.devices.map((deviceArg) => TasmotaMapper.device(deviceArg, this.state(deviceArg), this.client?.connected === true, this.options.enableControls === true));
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
-    return (await this.devices()).flatMap((deviceArg) => TasmotaMapper.entities(deviceArg));
+    return (await this.devices()).flatMap((deviceArg) => TasmotaMapper.entities(deviceArg, this.homeId));
   }
 
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
@@ -86,10 +114,12 @@ export class TasmotaRuntime implements IIntegrationRuntime {
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
     this.checkActive(abortSignalArg);
+    if (this.options.enableControls !== true) return { success: false, error: 'Tasmota controls require explicit embedding-owner enablement.' };
     if (requestArg.device.integrationDomain !== this.domain) return { success: false, error: 'Tasmota device is not selected.' };
     const device = this.config.devices.find((deviceArg) => deviceArg.id === requestArg.device.id);
     if (!device) return { success: false, error: 'Tasmota device is not selected.' };
-    if (!this.client.isHealthy() || !this.ready(device)) return { success: false, error: 'Tasmota device has no fresh online state.' };
+    const client = this.client;
+    if (!client?.isHealthy() || !this.ready(device)) return { success: false, error: 'Tasmota device has no fresh online state.' };
     const featureId = requestArg.feature.id;
     let command: string;
     let payload: string;
@@ -103,22 +133,60 @@ export class TasmotaRuntime implements IIntegrationRuntime {
     } else {
       return { success: false, error: 'Tasmota write requires a selected relay boolean or brightness integer from 0 through 100.' };
     }
-    await this.client.publish({ topic: `${device.commandBase}${command}`, payload, qos: 0, retain: false }, abortSignalArg);
+    const operation = this.owner.runOperation(this.lease.context, this.homeId, async (operationArg) => {
+      const signal = AbortSignal.any([operationArg.signal, this.lease.signal, this.lifetime.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+      this.checkActive(signal);
+      await client.publish({ topic: `${device.commandBase}${command}`, payload, qos: 0, retain: false }, signal);
+    });
+    await this.retain(operation);
     return { success: true, data: { accepted: true } };
   }
 
   public destroy(): Promise<void> {
-    if (this.destroyPromise) return this.destroyPromise;
-    this.destroyed = true;
-    this.stopConnectionListener();
-    this.lifetime.abort(new DeviceCommunicationError('Tasmota runtime destroyed.'));
-    for (const cleanup of [...this.subscriptionCleanups]) cleanup();
-    this.listeners.clear();
-    this.changed.clear();
-    this.destroyPromise = this.client.destroy();
+    if (!this.destroyPromise) {
+      this.destroyed = true;
+      this.destroyPromise = Promise.resolve().then(() => this.lease.close());
+      this.lifetime.abort(new DeviceCommunicationError('Tasmota runtime destroyed.'));
+    }
     return this.destroyPromise;
   }
 
+  /** Resource drain registered on the native lease, separate from its public closure. */
+  public dispose(): Promise<void> {
+    if (!this.disposePromise || this.cleanupFailed) {
+      const retry = this.cleanupFailed;
+      this.cleanupFailed = false;
+      this.destroyed = true;
+      this.disposePromise = Promise.resolve().then(async () => {
+        const cleanup = Promise.allSettled([
+          Promise.resolve().then(() => this.stopConnectionListener?.()),
+          ...[...this.subscriptionCleanups].map((cleanupArg) => Promise.resolve().then(cleanupArg)),
+          ...(this.session ? [Promise.resolve().then(() => retry ? this.session!.retryCleanup() : this.session!.close())] : []),
+        ]);
+        const [results] = await Promise.all([cleanup, Promise.allSettled([...this.operations])]);
+        this.listeners.clear();
+        this.changed.clear();
+        const failures = results.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected')
+          .map((resultArg) => resultArg.reason as unknown);
+        if (failures.length) { this.cleanupFailed = true; throw new AggregateError(failures, 'Tasmota runtime cleanup failed.'); }
+      });
+      this.lifetime.abort(new DeviceCommunicationError('Tasmota runtime destroyed.'));
+    }
+    return this.disposePromise;
+  }
+
+  private track<TValue>(workArg: () => Promise<TValue>): Promise<TValue> {
+    this.checkActive();
+    const operation = Promise.resolve().then(() => { this.checkActive(); return workArg(); });
+    return this.retain(operation);
+  }
+
+  private retain<TValue>(operationArg: Promise<TValue>): Promise<TValue> {
+    this.operations.add(operationArg);
+    void operationArg.then(() => this.operations.delete(operationArg), () => this.operations.delete(operationArg));
+    return operationArg;
+  }
+
   private state(deviceArg: ITasmotaSelectedDevice): ITasmotaDeviceState {
     const state = this.states.get(deviceArg.id);
     if (!state) throw new DeviceCommunicationError('Selected Tasmota device state is missing.');
@@ -133,12 +201,13 @@ export class TasmotaRuntime implements IIntegrationRuntime {
   private checkActive(abortSignalArg?: AbortSignal): void {
     abortSignalArg?.throwIfAborted();
     this.lifetime.signal.throwIfAborted();
+    this.lease.assertOpen();
   }
 
   private async withDeadline<TValue>(operationArg: (signalArg: AbortSignal) => Promise<TValue>, abortSignalArg?: AbortSignal): Promise<TValue> {
     const deadline = new AbortController();
     const timer = setTimeout(() => deadline.abort(new DeviceCommunicationError('Tasmota fresh state deadline exceeded.')), this.config.initialSnapshotTimeoutMs);
-    const signal = AbortSignal.any([this.lifetime.signal, deadline.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+    const signal = AbortSignal.any([this.lifetime.signal, this.lease.signal, deadline.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
     try {
       signal.throwIfAborted();
       return await operationArg(signal);
@@ -160,8 +229,8 @@ export class TasmotaRuntime implements IIntegrationRuntime {
     const fresh = this.waitForFresh(devicesArg, generationsArg, signalArg);
     const queries = async (): Promise<void> => {
       for (const device of devicesArg) {
-        await this.client.publish({ topic: `${device.commandBase}State`, payload: '', qos: 0, retain: false }, signalArg);
-        await this.client.publish({ topic: `${device.commandBase}Status`, payload: '10', qos: 0, retain: false }, signalArg);
+        await this.client!.publish({ topic: `${device.commandBase}State`, payload: '', qos: 0, retain: false }, signalArg);
+        await this.client!.publish({ topic: `${device.commandBase}Status`, payload: '10', qos: 0, retain: false }, signalArg);
       }
     };
     await Promise.all([fresh, queries()]);
@@ -169,7 +238,7 @@ export class TasmotaRuntime implements IIntegrationRuntime {
 
   private refreshInBackground(devicesArg: ITasmotaSelectedDevice[]): void {
     const generations = new Map<string, number>();
-    void this.withDeadline((signalArg) => this.refresh(devicesArg, signalArg, generations)).catch((errorArg: unknown) => {
+    void this.track(() => this.withDeadline((signalArg) => this.refresh(devicesArg, signalArg, generations))).catch((errorArg: unknown) => {
       if (this.destroyed) return;
       const currentDevices = devicesArg.filter((deviceArg) => this.state(deviceArg).generation === generations.get(deviceArg.id));
       if (!currentDevices.length) return;
@@ -190,7 +259,7 @@ export class TasmotaRuntime implements IIntegrationRuntime {
           reject(new DeviceCommunicationError('Tasmota state refresh superseded by a connection or availability change.'));
           return;
         }
-        if (this.client.connected && devicesArg.every((deviceArg) => this.ready(deviceArg))) {
+        if (this.client?.connected && devicesArg.every((deviceArg) => this.ready(deviceArg))) {
           cleanup();
           resolve();
         }

package/ts/integrations/tasmota/tasmota.config.ts

@@ -1,5 +1,6 @@
 import { IntegrationError } from '../../core/errors.js';
 import type { IHomeAssistantTasmotaConfig, ITasmotaConfig, ITasmotaDeviceConfig, ITasmotaSelectedDevice } from './tasmota.types.js';
+import { tasmotaCopy, tasmotaData, tasmotaText } from './tasmota.credentials.js';
 
 const fail = (messageArg: string): never => {
   throw new IntegrationError(messageArg, 'INVALID_TASMOTA_CONFIG');
@@ -51,6 +52,20 @@ const selectedDevice = (deviceArg: ITasmotaDeviceConfig): ITasmotaSelectedDevice
 };
 
 export const normalizeTasmotaConfig = (configArg: IHomeAssistantTasmotaConfig): ITasmotaConfig => {
+  const input = tasmotaData(tasmotaCopy(configArg), 'Tasmota configuration');
+  const broker = tasmotaData(input.broker, 'Tasmota broker');
+  if (['username', 'password', 'token', 'ca', 'cert', 'key'].some((fieldArg) => broker[fieldArg] !== undefined)) {
+    return fail('Legacy plaintext Tasmota broker credentials require explicit reconfiguration with an encrypted credential reference.');
+  }
+  const homeId = tasmotaText(input.homeId, 'Tasmota configuration home');
+  const authentication = tasmotaData(input.authentication, 'Tasmota authentication');
+  if (authentication.mode === 'anonymous') {
+    if (Object.keys(authentication).some((keyArg) => keyArg !== 'mode')) return fail('Anonymous Tasmota authentication must be selected explicitly without credentials.');
+  } else if (authentication.mode === 'credential-reference') {
+    if (Object.keys(authentication).some((keyArg) => !['mode', 'credentialRef'].includes(keyArg))) return fail('Tasmota authentication accepts only a credential reference.');
+    tasmotaText(authentication.credentialRef, 'Tasmota credential reference', 512);
+  } else return fail('Select explicit anonymous authentication or a broker credential reference.');
+  configArg = structuredClone(input) as unknown as IHomeAssistantTasmotaConfig;
   if (!configArg || typeof configArg !== 'object' || !configArg.broker || typeof configArg.broker.host !== 'string' || !configArg.broker.host.trim() || configArg.broker.host !== configArg.broker.host.trim()) return fail('Tasmota requires a real MQTT broker host without surrounding whitespace.');
   if (configArg.broker.port !== undefined && (!Number.isInteger(configArg.broker.port) || configArg.broker.port < 1 || configArg.broker.port > 65_535)) return fail('Tasmota broker port must be an integer from 1 through 65535.');
   if (configArg.broker.protocol !== undefined && configArg.broker.protocol !== 'mqtt' && configArg.broker.protocol !== 'mqtts') return fail('Tasmota broker protocol must be mqtt or mqtts.');
@@ -62,6 +77,8 @@ export const normalizeTasmotaConfig = (configArg: IHomeAssistantTasmotaConfig):
   const initialSnapshotTimeoutMs = configArg.initialSnapshotTimeoutMs ?? 10_000;
   if (!Number.isInteger(initialSnapshotTimeoutMs) || initialSnapshotTimeoutMs < 1 || initialSnapshotTimeoutMs > 2_147_483_647) return fail('initialSnapshotTimeoutMs must be a timer-safe positive integer.');
   return {
+    homeId,
+    authentication: Object.freeze({ ...configArg.authentication }),
     devices,
     initialSnapshotTimeoutMs,
     broker: { ...configArg.broker, discovery: false, birthMessage: false, willMessage: false, subscriptions: [], entities: [], discoveryMessages: [], retainedMessages: [] },

package/ts/integrations/tasmota/tasmota.credentials.ts

@@ -0,0 +1,92 @@
+import type { IMqttTransportCredentials } from '../mqtt/mqtt.types.js';
+import type { ITasmotaBrokerIdentity, ITasmotaConfig, ITasmotaCredential, ITasmotaIntegrationOptions } from './tasmota.types.js';
+
+export const tasmotaData = (valueArg: unknown, nameArg: string): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object'
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new TypeError(`${nameArg} must be a plain data object.`);
+  }
+  const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor?.enumerable || !('value' in descriptor)) {
+      throw new TypeError(`${nameArg} must not contain accessors or hidden fields.`);
+    }
+    result[key] = descriptor.value as unknown;
+  }
+  return result;
+};
+
+/** Capture configuration data without invoking nested user accessors. */
+export const tasmotaCopy = (valueArg: unknown, ancestorsArg = new Set<object>(), depthArg = 0): unknown => {
+  if (valueArg === null || valueArg === undefined || typeof valueArg === 'string' || typeof valueArg === 'boolean'
+    || (typeof valueArg === 'number' && Number.isFinite(valueArg))) return valueArg;
+  if (!valueArg || typeof valueArg !== 'object' || depthArg > 32 || ancestorsArg.has(valueArg)) throw new TypeError('Tasmota configuration must contain bounded plain data.');
+  ancestorsArg.add(valueArg);
+  try {
+    if (Array.isArray(valueArg)) {
+      const items: unknown[] = [];
+      for (let index = 0; index < valueArg.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+        if (!descriptor?.enumerable || !('value' in descriptor)) throw new TypeError('Tasmota configuration arrays must contain data values.');
+        items.push(tasmotaCopy(descriptor.value as unknown, ancestorsArg, depthArg + 1));
+      }
+      if (Reflect.ownKeys(valueArg).length !== items.length + 1) throw new TypeError('Tasmota configuration arrays contain unsupported fields.');
+      return items;
+    }
+    const data = tasmotaData(valueArg, 'Tasmota configuration');
+    return Object.fromEntries(Object.entries(data).map(([keyArg, itemArg]) => [keyArg, tasmotaCopy(itemArg, ancestorsArg, depthArg + 1)]));
+  } finally { ancestorsArg.delete(valueArg); }
+};
+
+export const tasmotaText = (valueArg: unknown, nameArg: string, maximumArg = 256): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.length > maximumArg
+    || valueArg.trim() !== valueArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`${nameArg} must be a bounded nonempty identifier.`);
+  }
+  return valueArg;
+};
+
+export const tasmotaOptions = (valueArg: ITasmotaIntegrationOptions): ITasmotaIntegrationOptions => {
+  const options = tasmotaData(valueArg, 'Tasmota owner options');
+  if (Object.keys(options).some((keyArg) => !['homeId', 'capacity', 'enableControls', 'credentialResolver'].includes(keyArg))) {
+    throw new TypeError('Tasmota owner options contain unsupported fields.');
+  }
+  if (options.enableControls !== undefined && typeof options.enableControls !== 'boolean') throw new TypeError('Tasmota enableControls must be boolean.');
+  if (options.credentialResolver !== undefined && typeof options.credentialResolver !== 'function') throw new TypeError('Tasmota credential resolver must be a function.');
+  return Object.freeze({ ...options }) as ITasmotaIntegrationOptions;
+};
+
+export const tasmotaBrokerIdentity = (configArg: ITasmotaConfig): ITasmotaBrokerIdentity => Object.freeze({
+  host: configArg.broker.host, port: configArg.broker.port ?? (configArg.broker.protocol === 'mqtts' ? 8883 : 1883),
+  protocol: configArg.broker.protocol ?? 'mqtt',
+});
+
+export const tasmotaCredentialKey = (referenceArg: string): string => `tasmota.credential.${encodeURIComponent(tasmotaText(referenceArg, 'Credential reference', 512))}`;
+
+export const tasmotaCredential = (valueArg: unknown, brokerArg: ITasmotaBrokerIdentity): IMqttTransportCredentials => {
+  const value = tasmotaData(valueArg, 'Tasmota credential');
+  if (Object.keys(value).some((keyArg) => !['version', 'host', 'port', 'protocol', 'username', 'password', 'ca', 'cert', 'key', 'servername'].includes(keyArg))
+    || value.version !== 1 || value.host !== brokerArg.host || value.port !== brokerArg.port || value.protocol !== brokerArg.protocol) {
+    throw new TypeError('Tasmota credential does not match the selected broker.');
+  }
+  const credentials: IMqttTransportCredentials = {};
+  for (const field of ['username', 'password', 'ca', 'cert', 'key', 'servername'] as const) {
+    const item = value[field];
+    if (item !== undefined) {
+      if (typeof item !== 'string' || item.length > 1_048_576 || item.includes('\u0000')) throw new TypeError('Tasmota credential fields are invalid.');
+      credentials[field] = item;
+    }
+  }
+  if (!credentials.username && !credentials.password && !credentials.cert) throw new TypeError('Tasmota credential reference must resolve authenticated broker credentials.');
+  if ((credentials.cert === undefined) !== (credentials.key === undefined)) throw new TypeError('Tasmota client certificate and private key must be supplied together.');
+  if ((credentials.ca || credentials.cert || credentials.key || credentials.servername) && brokerArg.protocol !== 'mqtts') throw new TypeError('Tasmota TLS credentials require mqtts.');
+  if (credentials.servername !== undefined) tasmotaText(credentials.servername, 'TLS server name', 253);
+  return Object.freeze(credentials);
+};
+
+export const createTasmotaCredential = (brokerArg: ITasmotaBrokerIdentity, usernameArg?: string, passwordArg?: string): ITasmotaCredential => {
+  const credential: ITasmotaCredential = { version: 1, ...brokerArg, username: usernameArg, password: passwordArg };
+  tasmotaCredential(credential, brokerArg);
+  return credential;
+};