@smarthome.exchange/integrations 1.0.0 → 3.0.0

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;
+};

package/ts/integrations/tasmota/tasmota.discovery.ts

@@ -1,7 +1,10 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import * as plugins from '../../plugins.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import { normalizeTasmotaConfig } from './tasmota.config.js';
-import type { IHomeAssistantTasmotaConfig } from './tasmota.types.js';
+import type { IHomeAssistantTasmotaConfig, ITasmotaIntegrationOptions } from './tasmota.types.js';
+import { createTasmotaCredential, tasmotaBrokerIdentity, tasmotaCopy, tasmotaCredentialKey, tasmotaData, tasmotaOptions, tasmotaText } from './tasmota.credentials.js';
 
 class TasmotaManualMatcher implements IDiscoveryMatcher<IDiscoveryCandidate> {
   public readonly id = 'tasmota-selected-device';
@@ -35,8 +38,28 @@ export const createTasmotaDiscoveryDescriptor = (): DiscoveryDescriptor => {
 };
 
 export class TasmotaConfigFlow implements IConfigFlow<IHomeAssistantTasmotaConfig> {
+  private readonly scope: NativeIntegrationScope;
+  private readonly hasResolver: boolean;
+
+  constructor(optionsArg: ITasmotaIntegrationOptions = {}, ownerArg?: NativeIntegrationOwner) {
+    const options = tasmotaOptions(optionsArg);
+    const owner = ownerArg ?? new NativeIntegrationOwner('tasmota', { homeId: options.homeId, capacity: options.capacity });
+    this.scope = owner.createFlowScope();
+    this.hasResolver = options.credentialResolver !== undefined;
+  }
+
+  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<IHomeAssistantTasmotaConfig>> {
-    void contextArg;
+    const candidate = tasmotaData(tasmotaCopy(candidateArg), 'Tasmota candidate');
+    const metadata = candidate.metadata === undefined ? undefined : tasmotaData(candidate.metadata, 'Tasmota candidate metadata');
+    const context = this.scope.admit(contextArg);
+    const candidateHost = candidate.host;
+    const candidatePort = candidate.port;
+    const candidateTopic = metadata?.topic;
+    let pending = false;
+    let submitted = false;
     return {
       kind: 'form',
       title: 'Connect a selected Tasmota device',
@@ -45,6 +68,8 @@ export class TasmotaConfigFlow implements IConfigFlow<IHomeAssistantTasmotaConfi
         { name: 'host', label: 'MQTT broker host', type: 'text', required: true },
         { name: 'port', label: 'MQTT broker port', type: 'number' },
         { name: 'useTls', label: 'Use MQTT TLS', type: 'boolean' },
+        { name: 'anonymous', label: 'Use an anonymous broker', type: 'boolean' },
+        { name: 'credentialRef', label: 'Existing broker credential reference', type: 'text' },
         { name: 'username', label: 'Broker username', type: 'text' },
         { name: 'password', label: 'Broker password', type: 'password' },
         { name: 'topic', label: 'Device Topic', type: 'text', required: true },
@@ -53,31 +78,69 @@ export class TasmotaConfigFlow implements IConfigFlow<IHomeAssistantTasmotaConfi
         { name: 'brightness', label: 'Single-channel Dimmer', type: 'boolean' },
       ],
       submit: async (valuesArg) => {
+        if (pending || submitted) return { kind: 'error', error: 'This Tasmota form is already submitting or completed.' };
+        pending = true;
         try {
-          for (const field of ['username', 'password', 'fullTopic']) if (valuesArg[field] !== undefined && typeof valuesArg[field] !== 'string') throw new Error(`${field} must be a string.`);
-          for (const field of ['useTls', 'brightness']) if (valuesArg[field] !== undefined && typeof valuesArg[field] !== 'boolean') throw new Error(`${field} must be boolean.`);
-          const relayCount = valuesArg.relayCount ?? 1;
-          if (typeof relayCount !== 'number' || !Number.isInteger(relayCount) || relayCount < 0 || relayCount > 32) throw new Error('relayCount must be an integer from 0 through 32.');
-          const host = valuesArg.host ?? candidateArg.host;
-          const topic = valuesArg.topic ?? candidateArg.metadata?.topic;
-          if (typeof host !== 'string' || typeof topic !== 'string') throw new Error('Broker host and device topic are required.');
-          const port = valuesArg.port ?? candidateArg.port;
-          if (port !== undefined && (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535)) throw new Error('Broker port must be an integer from 1 through 65535.');
-          const config: IHomeAssistantTasmotaConfig = {
-            broker: {
-              host,
-              port,
-              protocol: valuesArg.useTls === true ? 'mqtts' : 'mqtt',
-              username: typeof valuesArg.username === 'string' ? valuesArg.username : undefined,
-              password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
-            },
-            devices: [{ topic, fullTopic: typeof valuesArg.fullTopic === 'string' && valuesArg.fullTopic ? valuesArg.fullTopic : undefined, relays: Array.from({ length: relayCount }, (_, indexArg) => indexArg + 1), brightness: valuesArg.brightness === true }],
-          };
-          normalizeTasmotaConfig(config);
-          return { kind: 'done', title: 'Selected Tasmota device configured', config };
+          const values = tasmotaData(tasmotaCopy(valuesArg), 'Tasmota form');
+          return await this.scope.run(context, context.homeId, async (leaseArg) => {
+            if (Object.keys(values).some((keyArg) => !['homeId', 'host', 'port', 'useTls', 'anonymous', 'credentialRef', 'username', 'password', 'topic', 'fullTopic', 'relayCount', 'brightness'].includes(keyArg))) throw new Error('Tasmota form contains unsupported fields.');
+            if (values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('Tasmota form home conflicts with the admitted host home.');
+            for (const field of ['username', 'password', 'fullTopic', 'credentialRef']) if (values[field] !== undefined && typeof values[field] !== 'string') throw new Error(`${field} must be a string.`);
+            for (const field of ['useTls', 'brightness', 'anonymous']) if (values[field] !== undefined && typeof values[field] !== 'boolean') throw new Error(`${field} must be boolean.`);
+            const relayCount = values.relayCount ?? 1;
+            if (typeof relayCount !== 'number' || !Number.isInteger(relayCount) || relayCount < 0 || relayCount > 32) throw new Error('relayCount must be an integer from 0 through 32.');
+            const host = values.host ?? candidateHost;
+            const topic = values.topic ?? candidateTopic;
+            if (typeof host !== 'string' || typeof topic !== 'string') throw new Error('Broker host and device topic are required.');
+            const port = values.port ?? candidatePort;
+            if (port !== undefined && (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535)) throw new Error('Broker port must be an integer from 1 through 65535.');
+            const secretInput = values.username !== undefined || values.password !== undefined;
+            const anonymous = values.anonymous === true;
+            if (anonymous && (secretInput || values.credentialRef !== undefined)) throw new Error('Anonymous Tasmota mode cannot contain credentials.');
+            if (!anonymous && !secretInput && values.credentialRef === undefined) throw new Error('Select anonymous mode explicitly or provide broker credentials.');
+            if (secretInput && values.credentialRef !== undefined) throw new Error('Provide transient credentials or an existing reference, not both.');
+            const reference = anonymous ? undefined : secretInput ? plugins.crypto.randomUUID() : tasmotaText(values.credentialRef, 'Credential reference', 512);
+            const config: IHomeAssistantTasmotaConfig = {
+              homeId: context.homeId,
+              authentication: reference === undefined ? { mode: 'anonymous' } : { mode: 'credential-reference', credentialRef: reference },
+              broker: {
+                host,
+                port,
+                protocol: values.useTls === true ? 'mqtts' : 'mqtt',
+              },
+              devices: [{ topic, fullTopic: typeof values.fullTopic === 'string' && values.fullTopic ? values.fullTopic : undefined, relays: Array.from({ length: relayCount }, (_, indexArg) => indexArg + 1), brightness: values.brightness === true }],
+            };
+            const normalized = normalizeTasmotaConfig(config);
+            if (!anonymous) {
+              const store = leaseArg.context.configStore;
+              if (secretInput) {
+                if (!store) throw new Error('Transient Tasmota broker credentials require an admitted encrypted config store.');
+                const credential = createTasmotaCredential(tasmotaBrokerIdentity(normalized),
+                  typeof values.username === 'string' ? values.username : undefined,
+                  typeof values.password === 'string' ? values.password : undefined);
+                const key = tasmotaCredentialKey(reference!);
+                let committed = false;
+                let write: Promise<void> = Promise.resolve();
+                leaseArg.own(async () => {
+                  const result = await Promise.allSettled([write]);
+                  if (result[0].status === 'fulfilled' && !committed) {
+                    try { await store.delete(key); }
+                    catch { throw new Error('Tasmota cancelled credential cleanup failed.'); }
+                  }
+                });
+                write = Promise.resolve().then(() => store.create(key, credential));
+                try { await write; }
+                catch { throw new Error('Tasmota encrypted credential persistence failed.'); }
+                leaseArg.assertOpen();
+                committed = true;
+              } else if (!store && !this.hasResolver) throw new Error('Tasmota credential reference requires an explicit credential source.');
+            }
+            submitted = true;
+            return { kind: 'done', title: 'Selected Tasmota device configured', config };
+          });
         } catch (errorArg) {
           return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Invalid Tasmota configuration.' };
-        }
+        } finally { pending = false; }
       },
     };
   }

package/ts/integrations/tasmota/tasmota.mapper.ts

@@ -50,9 +50,9 @@ export class TasmotaMapper {
     return sensors;
   }
 
-  public static device(deviceArg: ITasmotaSelectedDevice, stateArg: ITasmotaDeviceState, connectedArg: boolean): plugins.shxInterfaces.data.IDeviceDefinition {
-    const features: plugins.shxInterfaces.data.IDeviceFeature[] = deviceArg.relays.map((relayArg) => ({ id: `power_${relayArg}`, capability: 'switch', name: `Relay ${relayArg}`, readable: true, writable: true }));
-    if (deviceArg.brightness) features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' });
+  public static device(deviceArg: ITasmotaSelectedDevice, stateArg: ITasmotaDeviceState, connectedArg: boolean, enableControlsArg = false): plugins.shxInterfaces.data.IDeviceDefinition {
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = deviceArg.relays.map((relayArg) => ({ id: `power_${relayArg}`, capability: 'switch', name: `Relay ${relayArg}`, readable: true, writable: enableControlsArg }));
+    if (deviceArg.brightness) features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: enableControlsArg, unit: '%' });
     for (const id of Object.keys(stateArg.sensors).sort()) features.push({ id, capability: id.startsWith('sensor_ENERGY/') ? 'energy' : 'sensor', name: id.slice('sensor_'.length).split('/').map(decodeURIComponent).join(' '), readable: true, writable: false });
     const values = { ...stateArg.controls, ...stateArg.sensors };
     return {
@@ -69,12 +69,12 @@ export class TasmotaMapper {
     };
   }
 
-  public static entities(deviceArg: plugins.shxInterfaces.data.IDeviceDefinition): IIntegrationEntity[] {
+  public static entities(deviceArg: plugins.shxInterfaces.data.IDeviceDefinition, homeIdArg: string): IIntegrationEntity[] {
     return deviceArg.features.map((featureArg) => {
       const platform = featureArg.capability === 'switch' ? 'switch' : featureArg.capability === 'light' ? 'light' : 'sensor';
       return {
-        id: `${platform}.${encodeURIComponent(deviceArg.id)}.${encodeURIComponent(featureArg.id)}`,
-        uniqueId: `${deviceArg.id}:${featureArg.id}`,
+        id: `${encodeURIComponent(homeIdArg)}:${platform}.${encodeURIComponent(JSON.stringify([deviceArg.id, featureArg.id]))}`,
+        uniqueId: JSON.stringify([homeIdArg, deviceArg.id, featureArg.id]),
         integrationDomain: 'tasmota',
         deviceId: deviceArg.id,
         platform,