@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/zigbee2mqtt/readme.md

@@ -1,40 +1,35 @@
-# Zigbee2MQTT
+# Native Zigbee2MQTT
 
-`Zigbee2MqttIntegration` connects directly to a configured MQTT broker and Zigbee2MQTT base topic. It reuses the package's native `MqttClient`; it does not require Home Assistant or connect to the Zigbee coordinator itself.
+The adapter connects to an explicitly selected MQTT broker and Zigbee2MQTT base topic through the existing native MQTT.js transport. SHX home selection is separate from the Zigbee coordinator, network, IEEE address and friendly name. Broker TLS authenticates the selected broker name; Zigbee identity/inventory observations do not prove a unique or cryptographically authenticated physical controller.
 
 ```typescript
-const integration = new Zigbee2MqttIntegration();
+const integration = new Zigbee2MqttIntegration({
+  homeId: hostSelectedHomeId,
+  controls: [{ ieeeAddress: selectedLowercaseIeeeAddress, property: 'state' }],
+  resolveCredentials: async (request) => {
+    // The host resolver owns storage. It validates the admitted home and exact
+    // request.host/port/protocol/baseTopic before returning runtime-only material.
+    return retrieveSelectedBrokerCredentials(request);
+  },
+});
 const runtime = await integration.setup({
-  host: 'broker.example.internal',
-  protocol: 'mqtts',
-  port: 8883,
+  homeId: hostSelectedHomeId,
+  host: 'broker.internal', protocol: 'mqtts', port: 8883,
   baseTopic: 'home/zigbee2mqtt',
-  username: brokerUsername,
-  password: brokerPassword,
-}, { abortSignal: lifetimeController.signal });
-
-const [device] = await runtime.devices();
-const power = device?.features.find((feature) => feature.id === 'state');
-if (device?.online && power?.writable) {
-  await runtime.writeFeature?.({ device, feature: power, value: true });
-}
-await runtime.destroy();
+  authentication: 'provider', credentialKey: 'broker-reference',
+}, { homeId: hostSelectedHomeId, abortSignal: hostLifetime.signal });
 ```
 
-The broker host and base topic are required explicitly. There is no automatic broker selection, injected inventory or fixture configuration in production. `mqtts` validates the broker certificate with Node's trusted certificate authorities; disabling certificate verification is not a supported option. The runtime holds supplied credentials in memory and does not persist them. The application must store and retrieve integration configuration through the public `NoSqlConfigStore` backed by `@lossless.org/client/nosqldb`, using its home scope and external encryption-key provider.
+Every setup and config-flow context requires an independently selected `homeId`; an optional constructor binding does not replace it. Config, form fields, discovery, store scope and network IDs cannot choose home. One instance binds once even if setup later fails. Canonical device IDs are `encodeURIComponent(homeId) + ':zigbee2mqtt.' + lowercaseIeeeAddress`; entity IDs append the exact exposed property. Close is terminal.
 
-Setup waits for received `BASE/bridge/devices` inventory and `BASE/bridge/state`. The inventory contains each device's actual `definition.exposes`; unsupported devices and coordinators cannot be operated. Device IDs use `zigbee2mqtt.0xIEEEADDRESS`, and feature IDs use the exact exposed property, including endpoint suffixes. Entity IDs combine those IDs. A friendly-name change keeps identity stable and discards state and availability learned through the former name.
+`authentication` is required and explicitly selects `anonymous`, `provider` or `config-store`. Anonymous forbids a credential reference. Provider requires both an existing `credentialKey` and constructor-injected `resolveCredentials`; missing provider does not fall back to another source. Config-store requires a borrowed actual scoped `NoSqlConfigStore` and the reference. It reads an encrypted value shaped as `{ version: 1, host, port, protocol, baseTopic, credentials: { username?, password?, ca?, cert?, key?, servername? } }` and verifies exact selected broker/topic binding before use. Configuration and flow output contain references only; passwords, CA/client certificates and private keys are runtime-only strings. No filesystem credential paths are supported. Client cert/key must be supplied together, TLS material requires mqtts, and certificate/hostname verification remains enabled. Plain MQTT requires `allowUnencryptedLan: true`. No-store anonymous and provider paths are legitimate.
 
-Binary, numeric, enum and text exposes are mapped, including primitive features inside advertised light, switch, fan, cover, lock and climate containers. Access bit 1 grants reported state and bit 2 grants writes. Binary features use normalized boolean values, translated into the advertised `value_on` and `value_off`. Numeric writes respect advertised minimum, maximum and step, enum writes accept advertised values only, and text values are limited to 1024 characters. Composite/list values, colors, schedules, numeric presets outside the normal range and binary toggles are unsupported. Their count is included in device metadata. Raw ZCL read/write/command fields are never exposed as controls.
+The resolver request includes captured home, reference, exact broker/topic, an AbortSignal and an absolute performance.now() setup deadline. Provider work is owned before invocation. Deadline/abort prevents late transport allocation; destruction joins the actual foreign promise even if it ignores cancellation. Providers and borrowed store/database/key-provider resources remain caller-owned. Cleanup retry never reruns a provider, setup, subscription or physical command.
 
-Device availability must be enabled in Zigbee2MQTT. An explicit received `{"state":"online"}` on a device's availability topic, current inventory, an online bridge and a ready MQTT connection are all required for control. Missing availability remains `unknown`; neither a sensor report nor a device announcement implies online status. Bridge shutdown and MQTT disconnect revoke admission and clear cached availability. Reconnect restores the owned subscription and requires freshly received inventory and bridge state before control resumes. Per-device state and availability reports received before the inventory are buffered within the configured limits and applied only to validated inventory members.
+Primitive binary, numeric, enum and text controls are preserved, including advertised primitive children of light/switch/fan/cover/lock/climate. Constructor `controls` is an immutable finite exact lowercase IEEE/property allowlist. Default is no control permission. Expose write access alone does not grant owner permission; editable config cannot grant it. At dispatch, current canonical home/target/capability, expose type/access/range/step/enum, supported/non-disabled membership and authoritative availability must all agree. Complex colors, lists, schedules, arbitrary ZCL, groups, joining, pairing, binding, OTA, bridge configuration and /get are excluded.
 
-`zigbee2mqtt.set` accepts exactly one target, either `deviceId` or `entityId`, and exactly `data: { property, value }`. The entity target must correspond to that property. Feature writes check the target's domain and resolve its current canonical feature, so caller-provided writable flags do not grant capabilities. Every command publishes one JSON property to `BASE/0xIEEEADDRESS/set`, using QoS 0 and `retain: false`. Commands are not retried. Success means the MQTT transport accepted publication and returns `physicalOutcome: 'unconfirmed'`; only subsequent device reports change state. MQTT publication does not prove physical execution.
+Each admitted write publishes exactly one property to BASE/IEEE/set with QoS0 and retain:false. Commands are never retried or optimistically applied. Success preserves `{ confirmation: 'mqtt-publish', physicalOutcome: 'unconfirmed' }`; publication callback loss reports uncertainty. Device state changes only from subsequent observations. Retained and pre-inventory action reports never replay physical events. Current-generation cache seeding and callbacks preserve fresh inventory/availability across reconnects; a stale historical snapshot cannot admit control.
 
-Subscriptions emit added/removed entities and devices, state changes and availability changes. Accepted live action reports are emitted once per report, including repeated identical actions; retained or pre-inventory action state does not replay physical events. Authoritative `device_leave` events remove a device immediately. Subscriber cancellation removes only that listener; a throwing listener is removed and produces an error for remaining subscribers. Runtime destruction and the setup context's lifetime abort cancel pending I/O, stop reconnect, remove callbacks and await socket cleanup.
+The owner shares a default capacity of 16 across pending setup/flow work, live runtimes and retained cleanup failures. Existing device/payload/buffer/deadline/write/subscriber bounds remain. Async foreign subscriber work is additionally bounded at 256 pending callbacks and drained during closure. A failed subscriber is removed and other subscribers receive a sanitized error, preserving established isolation behavior. Integration `destroy()` drains flow/setup/runtime, actual providers, subscriber work, commands and transport; repeated/reentrant calls share a stable promise. `retryCleanup()` retries retained failed cleanup only. Runtime destruction closes its lease. Config-flow destruction is terminal for its scope.
 
-Connection, publication and inventory deadlines default to 7 seconds and are capped at 60 seconds. Inventory defaults to at most 2048 devices, 256 expose descriptors per device, 8 MiB per MQTT payload and 32 MiB total buffered MQTT data. Commands are limited to 64 in flight and listeners to 256. Unsupported bridge topics, including bridge configuration and logging, are never forwarded as entity attributes or errors.
-
-Groups, pairing, joining, binding, OTA, bridge configuration, network management, `/get` polling and Home Assistant discovery are outside this adapter. Tests use the real MQTT.js TCP parser against a local test broker; no hardware access is performed.
-
-Protocol references: [MQTT topics and messages](https://www.zigbee2mqtt.io/guide/usage/mqtt_topics_and_messages.html), [exposes and access masks](https://www.zigbee2mqtt.io/guide/usage/exposes.html), and [device availability](https://www.zigbee2mqtt.io/guide/configuration/device-availability.html).
+Verification uses real local MQTT.js TCP/TLS fixtures, including private CA/mutual client authentication and wrong broker-name denial. No hardware/private production broker acceptance has been established.

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.classes.configflow.ts

@@ -1,9 +1,13 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { IZigbee2MqttConfig } from './zigbee2mqtt.types.js';
-import { zigbee2MqttConfig } from './zigbee2mqtt.validation.js';
+import { zigbee2MqttConfig, zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 
 export class Zigbee2MqttConfigFlow implements IConfigFlow<IZigbee2MqttConfig> {
-  public async start(_candidateArg: IDiscoveryCandidate, _contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IZigbee2MqttConfig>> {
+  readonly #scope: NativeIntegrationScope;
+  constructor(ownerArg = new NativeIntegrationOwner('zigbee2mqtt')) { this.#scope = ownerArg.createFlowScope(); }
+  public async start(_candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IZigbee2MqttConfig>> {
+    const context = this.#scope.admit(contextArg);
     return {
       kind: 'form', title: 'Connect Zigbee2MQTT',
       description: 'Enter the broker and exact Zigbee2MQTT base topic. Enable device availability in Zigbee2MQTT before operating devices.',
@@ -12,15 +16,20 @@ export class Zigbee2MqttConfigFlow implements IConfigFlow<IZigbee2MqttConfig> {
         { name: 'baseTopic', label: 'Zigbee2MQTT base topic', 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: 'authentication', label: 'Credential source', type: 'select', required: true, options: [{ label: 'Anonymous', value: 'anonymous' }, { label: 'Caller provider', value: 'provider' }, { label: 'Encrypted config store', value: 'config-store' }] },
+        { name: 'credentialKey', label: 'Existing credential reference', type: 'text' },
+        { name: 'allowUnencryptedLan', label: 'Allow plaintext LAN MQTT', type: 'boolean' },
       ],
-      submit: async (valuesArg) => {
+      submit: (valuesArg) => this.#scope.run(context, undefined, async () => {
         try {
-          const config = zigbee2MqttConfig(valuesArg as unknown as IZigbee2MqttConfig);
+          const values = zigbee2MqttRecord(valuesArg);
+          if (!values || values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('Conflicting home or invalid form data.');
+          const config = zigbee2MqttConfig({ ...values, homeId: context.homeId } as unknown as IZigbee2MqttConfig);
           return { kind: 'done', title: 'Zigbee2MQTT configured', config };
         } catch { return { kind: 'error', error: 'Enter a valid broker, base topic and supported explicit configuration fields.' }; }
-      },
+      }),
     };
   }
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 }

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.classes.integration.ts

@@ -1,23 +1,70 @@
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import { NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
 import type { IIntegrationRuntime, IIntegrationSetupContext } from '../../core/types.js';
 import { Zigbee2MqttConfigFlow } from './zigbee2mqtt.classes.configflow.js';
 import { Zigbee2MqttRuntime } from './zigbee2mqtt.classes.runtime.js';
-import type { IZigbee2MqttConfig } from './zigbee2mqtt.types.js';
+import { MqttSession } from '../mqtt/mqtt.classes.session.js';
+import type { TMqttCredentialResolver } from '../mqtt/mqtt.types.js';
+import type { IZigbee2MqttConfig, IZigbee2MqttIntegrationOptions } from './zigbee2mqtt.types.js';
+import { zigbee2MqttConfig, zigbee2MqttCredentials, zigbee2MqttOptions, zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
 
 export class Zigbee2MqttIntegration extends BaseIntegration<IZigbee2MqttConfig> {
   public readonly domain = 'zigbee2mqtt';
   public readonly displayName = 'Zigbee2MQTT';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = new DiscoveryDescriptor({ integrationDomain: this.domain, displayName: this.displayName });
-  public readonly configFlow = new Zigbee2MqttConfigFlow();
+  public readonly configFlow: Zigbee2MqttConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: IZigbee2MqttIntegrationOptions;
+  readonly #controls: ReadonlySet<string>;
   public readonly metadata = { source: 'zigbee2mqtt', upstreamPath: 'Koenkk/zigbee2mqtt', iotClass: 'local_push' };
 
+  constructor(optionsArg: IZigbee2MqttIntegrationOptions = {}) {
+    super();
+    const { options, controls } = zigbee2MqttOptions(optionsArg);
+    this.#options = options;
+    this.#controls = controls;
+    this.#owner = new NativeIntegrationOwner(this.domain, { homeId: options.homeId, capacity: options.capacity });
+    this.configFlow = new Zigbee2MqttConfigFlow(this.#owner);
+  }
+
   public async setup(configArg: IZigbee2MqttConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    const runtime = new Zigbee2MqttRuntime(configArg);
-    await runtime.start(contextArg.abortSignal);
-    return runtime;
+    const config = zigbee2MqttConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (lease) => {
+      let resolver: TMqttCredentialResolver | undefined;
+      if (config.authentication === 'provider') {
+        const provider = this.#options.resolveCredentials;
+        if (!provider) throw new Error('Zigbee2MQTT provider mode requires an explicit caller resolver.');
+        resolver = async (request) => zigbee2MqttCredentials(config, await provider(Object.freeze({ ...request, host: config.host, port: config.port!, protocol: config.protocol!, baseTopic: config.baseTopic })));
+      } else if (config.authentication === 'config-store') {
+        const store = lease.context.configStore;
+        if (!store) throw new Error('Zigbee2MQTT config-store mode requires an admitted encrypted NoSqlConfigStore.');
+        resolver = async (request) => {
+          const value = zigbee2MqttRecord(await store.get<unknown>(request.credentialKey));
+          if (!value || Object.keys(value).some((key) => !['version', 'host', 'port', 'protocol', 'baseTopic', 'credentials'].includes(key)) ||
+            value.version !== 1 || value.host !== config.host || value.port !== config.port || value.protocol !== config.protocol || value.baseTopic !== config.baseTopic) {
+            throw new Error('Zigbee2MQTT encrypted credentials do not match the selected broker and base topic.');
+          }
+          return zigbee2MqttCredentials(config, value.credentials);
+        };
+      }
+      const session = new MqttSession({ ...config, discovery: false, birthMessage: false, willMessage: false, clean: true,
+        subscriptions: [config.baseTopic + '/#'], maxMessageTopics: (config.maxDevices ?? 2048) * 4 + 16 }, lease, resolver);
+      let runtime: Zigbee2MqttRuntime | undefined;
+      let attempts = 0;
+      const closeSession = (): Promise<void> => attempts++ === 0 ? session.close() : session.retryCleanup();
+      lease.own(() => runtime ? runtime.cleanup() : closeSession());
+      const client = await session.start();
+      lease.assertOpen();
+      runtime = new Zigbee2MqttRuntime(config, client, lease, closeSession, this.#controls);
+      await runtime.start();
+      lease.assertOpen();
+      lease.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/zigbee2mqtt/zigbee2mqtt.classes.runtime.ts

@@ -1,10 +1,11 @@
 import type * as plugins from '../../plugins.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
-import { MqttClient } from '../mqtt/mqtt.classes.client.js';
+import type { MqttClient } from '../mqtt/mqtt.classes.client.js';
 import type { IMqttMessage } from '../mqtt/mqtt.types.js';
 import { Zigbee2MqttMapper } from './zigbee2mqtt.mapper.js';
 import type { IZigbee2MqttConfig, IZigbee2MqttDevice, IZigbee2MqttReportedState, IZigbee2MqttSnapshot } from './zigbee2mqtt.types.js';
-import { zigbee2MqttConfig, zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
+import { zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
+import type { INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 
 interface IZigbee2MqttListener {
   handler: (eventArg: IIntegrationEvent) => void;
@@ -14,7 +15,7 @@ interface IZigbee2MqttListener {
 export class Zigbee2MqttRuntime implements IIntegrationRuntime {
   public readonly domain = 'zigbee2mqtt';
   private readonly config: IZigbee2MqttConfig;
-  private readonly client: MqttClient;
+  readonly #controls: ReadonlySet<string>;
   private readonly removeMessageHandler: () => void;
   private readonly removeConnectionHandler: () => void;
   private readonly handlers = new Set<IZigbee2MqttListener>();
@@ -34,17 +35,18 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
   private inventoryCurrent = false;
   private inventoryError?: Error;
   private destroyed = false;
-  private destroyPromise?: Promise<void>;
   private activeWrites = 0;
-  private removeSetupAbort?: () => void;
+  private readonly pendingHandlers = new Set<Promise<void>>();
+  private readonly callbackFailures = new Set<Error>();
+  private readonly ownerAbort = (): void => { this.destroyed = true; };
 
-  constructor(configArg: IZigbee2MqttConfig) {
-    this.config = zigbee2MqttConfig(configArg);
-    this.client = new MqttClient({
-      ...this.config, discovery: false, birthMessage: false, willMessage: false, clean: true,
-      subscriptions: [this.config.baseTopic + '/#'],
-      maxMessageTopics: (this.config.maxDevices ?? 2048) * 4 + 16,
-    });
+  constructor(configArg: IZigbee2MqttConfig, private readonly client: MqttClient,
+    private readonly lease: INativeSetupLease, private readonly closeSession: () => Promise<void>,
+    controlsArg: ReadonlySet<string>) {
+    this.config = configArg;
+    this.#controls = new Set(controlsArg);
+    this.connected = client.connected;
+    lease.signal.addEventListener('abort', this.ownerAbort, { once: true });
     this.removeMessageHandler = this.client.onMessage((messageArg) => this.receive(messageArg));
     this.removeConnectionHandler = this.client.onConnectionState((stateArg) => {
       const previous = this.snapshot();
@@ -64,24 +66,16 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
     });
   }
 
-  public async start(abortSignalArg?: AbortSignal): Promise<void> {
-    this.assertOpen(abortSignalArg);
+  public async start(): Promise<void> {
+    this.assertOpen();
     if (this.started) throw new Error('Zigbee2MQTT runtime has already started.');
     this.started = true;
-    if (abortSignalArg) {
-      const abort = (): void => { void this.destroy().catch(() => this.emitError('Zigbee2MQTT cancellation cleanup failed.')); };
-      abortSignalArg.addEventListener('abort', abort, { once: true });
-      this.removeSetupAbort = () => abortSignalArg.removeEventListener('abort', abort);
-    }
-    try {
-      await this.client.start(abortSignalArg);
-      this.assertOpen(abortSignalArg);
-      await this.waitForInventory(abortSignalArg);
-    } catch (error) {
-      try { await this.destroy(); }
-      catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Zigbee2MQTT setup and cleanup failed.'); }
-      throw error;
+    // Handlers are installed before this synchronous current-generation snapshot. No await
+    // can let older cached observations overwrite a later callback or a reconnect.
+    for (const message of this.client.getCurrentSnapshot()) {
+      if (message.topic !== this.config.baseTopic + '/bridge/event') this.receive(message, true);
     }
+    await this.waitForInventory(this.lease.signal);
   }
 
   public isHealthy(): boolean {
@@ -128,6 +122,9 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
         !device || device.integrationDomain !== this.domain || typeof device.id !== 'string' || !feature || typeof feature.id !== 'string') {
         throw new Error('Zigbee2MQTT feature request requires a device owned by this domain.');
       }
+      const selected = this.findDevice(device.id);
+      const current = selected?.exposes.find((expose) => expose.property === feature.id);
+      if (!current || feature.capability !== current.capability) throw new Error('Zigbee2MQTT feature capability does not match the current target.');
       return await this.write(device.id, feature.id, request.value, abortSignalArg);
     } catch (error) { return this.failure(error); }
   }
@@ -149,26 +146,23 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
         selected = this.findDevice(target.entityId.slice(0, -(data.property.length + 1)));
       }
       if (!selected) throw new Error('Zigbee2MQTT target is not in the current inventory.');
-      return await this.write(Zigbee2MqttMapper.deviceId(selected.ieeeAddress), data.property, data.value);
+      return await this.write(Zigbee2MqttMapper.deviceId(this.config.homeId, selected.ieeeAddress), data.property, data.value);
     } catch (error) { return this.failure(error); }
   }
 
-  public destroy(): Promise<void> {
-    if (!this.destroyPromise) this.destroyPromise = this.destroyConnection();
-    return this.destroyPromise;
-  }
+  public destroy(): Promise<void> { return this.lease.close(); }
 
   private async write(deviceIdArg: string, propertyArg: string, valueArg: unknown, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
     this.assertOpen(abortSignalArg);
     const device = this.findDevice(deviceIdArg);
     const expose = device?.exposes.find((exposeArg) => exposeArg.property === propertyArg);
-    if (!device || !expose || !Zigbee2MqttMapper.available(this.snapshot([device]), device)) throw new Error('Zigbee2MQTT target is unavailable or not exposed.');
+    if (!device || !expose || !Zigbee2MqttMapper.writable(this.snapshot([device]), device, expose) || !Zigbee2MqttMapper.available(this.snapshot([device]), device)) throw new Error('Zigbee2MQTT target is unavailable or not exposed.');
     const value = Zigbee2MqttMapper.commandValue(expose, valueArg);
     if (value === undefined) throw new Error('Zigbee2MQTT value is not permitted by the advertised expose.');
     if (this.activeWrites >= 64) throw new Error('Zigbee2MQTT command admission limit exceeded.');
     this.activeWrites++;
     try {
-      const publication = this.client.publish({ topic: `${this.config.baseTopic}/${device.ieeeAddress}/set`, payload: { [expose.property]: value }, qos: 0, retain: false }, abortSignalArg);
+      const publication = this.client.publish({ topic: `${this.config.baseTopic}/${device.ieeeAddress}/set`, payload: { [expose.property]: value }, qos: 0, retain: false }, abortSignalArg ? AbortSignal.any([this.lease.signal, abortSignalArg]) : this.lease.signal);
       this.pendingWrites.add(publication);
       try { await publication; }
       catch { throw new Error('Zigbee2MQTT command publication failed; its physical outcome is unconfirmed.'); }
@@ -297,8 +291,8 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
       if (value === undefined) { states.delete(expose.property); this.emitError('Zigbee2MQTT reported a value outside its expose type.'); continue; }
       states.set(expose.property, { value, updatedAt: new Date(timestampArg).toISOString() });
       if (liveEventArg && (expose.property === 'action' || expose.property.startsWith('action_'))) {
-        this.emit({ type: 'state_changed', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(deviceArg.ieeeAddress),
-          entityId: Zigbee2MqttMapper.entityId(deviceArg.ieeeAddress, expose.property), data: { value }, timestamp: timestampArg });
+        this.emit({ type: 'state_changed', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(this.config.homeId, deviceArg.ieeeAddress),
+          entityId: Zigbee2MqttMapper.entityId(this.config.homeId, deviceArg.ieeeAddress, expose.property), data: { value }, timestamp: timestampArg });
       }
     }
   }
@@ -307,10 +301,10 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
     const next = this.snapshot(scopedDevicesArg);
     const previousDevices = new Map(previousArg.devices.map((deviceArg) => [deviceArg.ieeeAddress, deviceArg]));
     for (const device of next.devices) {
-      if (!previousDevices.has(device.ieeeAddress)) this.emit({ type: 'device_added', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(device.ieeeAddress), timestamp: Date.now() });
+      if (!previousDevices.has(device.ieeeAddress)) this.emit({ type: 'device_added', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(this.config.homeId, device.ieeeAddress), timestamp: Date.now() });
     }
     for (const device of previousArg.devices) {
-      if (!this.devicesByIeee.has(device.ieeeAddress)) this.emit({ type: 'device_removed', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(device.ieeeAddress), timestamp: Date.now() });
+      if (!this.devicesByIeee.has(device.ieeeAddress)) this.emit({ type: 'device_removed', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(this.config.homeId, device.ieeeAddress), timestamp: Date.now() });
     }
     const previous = new Map(Zigbee2MqttMapper.toEntities(previousArg).map((entityArg) => [entityArg.id, entityArg]));
     const current = new Map(Zigbee2MqttMapper.toEntities(next).map((entityArg) => [entityArg.id, entityArg]));
@@ -331,7 +325,7 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
   private snapshot(scopedDevicesArg?: IZigbee2MqttDevice[]): IZigbee2MqttSnapshot {
     const devices = scopedDevicesArg ?? [...this.devicesByIeee.values()];
     return {
-      devices, connected: this.connected && !this.destroyed,
+      homeId: this.config.homeId, controls: this.#controls, devices, connected: this.connected && !this.destroyed,
       bridgeOnline: this.bridgeOnline, inventoryCurrent: this.inventoryCurrent,
       availability: new Map(devices.filter((deviceArg) => this.availability.has(deviceArg.ieeeAddress)).map((deviceArg) =>
         [deviceArg.ieeeAddress, this.availability.get(deviceArg.ieeeAddress) === true])),
@@ -340,7 +334,8 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
   }
 
   private findDevice(idArg: string): IZigbee2MqttDevice | undefined {
-    return idArg.startsWith('zigbee2mqtt.') ? this.devicesByIeee.get(idArg.slice('zigbee2mqtt.'.length)) : undefined;
+    const prefix = `${encodeURIComponent(this.config.homeId)}:zigbee2mqtt.`;
+    return idArg.startsWith(prefix) ? this.devicesByIeee.get(idArg.slice(prefix.length)) : undefined;
   }
 
   private deviceForTopic(topicArg: string): IZigbee2MqttDevice | undefined {
@@ -370,37 +365,55 @@ export class Zigbee2MqttRuntime implements IIntegrationRuntime {
     if (this.inventoryReceived && this.bridgeReceived && this.client.connected) for (const waiter of [...this.readyWaiters]) waiter.resolve();
   }
 
-  private async destroyConnection(): Promise<void> {
+  public async cleanup(): Promise<void> {
     this.destroyed = true;
-    this.removeSetupAbort?.();
+    this.lease.signal.removeEventListener('abort', this.ownerAbort);
     this.removeMessageHandler();
     this.removeConnectionHandler();
     for (const waiter of [...this.readyWaiters]) waiter.reject(new Error('Zigbee2MQTT runtime closed.'));
-    for (const cleanup of [...this.subscriptionCleanups]) await cleanup();
+    const cleanups = [...this.subscriptionCleanups];
     this.handlers.clear();
-    await this.client.destroy();
-    await Promise.allSettled([...this.pendingWrites]);
+    const results = await Promise.allSettled([
+      ...cleanups.map((cleanup) => Promise.resolve().then(cleanup)),
+      Promise.resolve().then(this.closeSession),
+      ...[...this.pendingWrites].map((write) => write.then(() => undefined, () => undefined)),
+      ...this.pendingHandlers,
+    ]);
     this.devicesByIeee.clear();
     this.devicesByName.clear();
     this.availability.clear();
     this.state.clear();
     this.pendingMessages.clear();
+    const failures = [...this.callbackFailures, ...results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : [])];
+    this.callbackFailures.clear();
+    if (failures.length) throw new AggregateError(failures, 'Zigbee2MQTT runtime cleanup failed; retry cleanup explicitly.');
   }
 
   private assertOpen(abortSignalArg?: AbortSignal): void {
     if (abortSignalArg?.aborted) throw new DOMException('Zigbee2MQTT operation aborted.', 'AbortError');
     if (this.destroyed) throw new Error('Zigbee2MQTT runtime closed.');
+    this.lease.assertOpen();
   }
 
   private emit(eventArg: IIntegrationEvent): void {
     for (const listener of [...this.handlers]) {
       if (!this.handlers.has(listener)) continue;
-      try { listener.handler(structuredClone(eventArg)); }
-      catch {
-        // A consumer callback must not disconnect the transport shared by other subscribers.
+      if (this.pendingHandlers.size >= 256) {
         void listener.cleanup();
-        this.emitError('Zigbee2MQTT subscriber callback failed.');
+        this.emitError('Zigbee2MQTT subscriber work limit exceeded.');
+        continue;
       }
+      const work = Promise.resolve().then(async () => {
+        if (!this.handlers.has(listener) || this.destroyed) return;
+        try { await listener.handler(structuredClone(eventArg)); }
+        catch {
+          await listener.cleanup();
+          if (this.destroyed) this.callbackFailures.add(new Error('Zigbee2MQTT subscriber callback failed while draining.'));
+          else this.emitError('Zigbee2MQTT subscriber callback failed.');
+        }
+      });
+      this.pendingHandlers.add(work);
+      void work.then(() => this.pendingHandlers.delete(work), () => this.pendingHandlers.delete(work));
     }
   }
 

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.mapper.ts

@@ -1,18 +1,18 @@
 import type * as plugins from '../../plugins.js';
 import type { IIntegrationEntity } from '../../core/types.js';
 import type { IZigbee2MqttDevice, IZigbee2MqttExpose, IZigbee2MqttSnapshot, TZigbee2MqttPrimitive } from './zigbee2mqtt.types.js';
-import { zigbee2MqttPrimitive, zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
+import { zigbee2MqttControlKey, zigbee2MqttPrimitive, zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
 
 const specificTypes = new Set(['light', 'switch', 'fan', 'cover', 'lock', 'climate']);
 const forbiddenProperties = new Set(['__proto__', 'constructor', 'prototype', 'read', 'write', 'command', 'commands', 'get', 'set']);
 
 export class Zigbee2MqttMapper {
-  public static deviceId(ieeeAddressArg: string): string {
-    return `zigbee2mqtt.${ieeeAddressArg}`;
+  public static deviceId(homeIdArg: string, ieeeAddressArg: string): string {
+    return `${encodeURIComponent(homeIdArg)}:zigbee2mqtt.${ieeeAddressArg}`;
   }
 
-  public static entityId(ieeeAddressArg: string, propertyArg: string): string {
-    return `${this.deviceId(ieeeAddressArg)}.${propertyArg}`;
+  public static entityId(homeIdArg: string, ieeeAddressArg: string, propertyArg: string): string {
+    return `${this.deviceId(homeIdArg, ieeeAddressArg)}.${propertyArg}`;
   }
 
   public static parseInventory(payloadArg: unknown, maxDevicesArg: number): IZigbee2MqttDevice[] {
@@ -54,12 +54,12 @@ export class Zigbee2MqttMapper {
 
   public static toDevices(snapshotArg: IZigbee2MqttSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
     return snapshotArg.devices.map((deviceArg) => ({
-      id: this.deviceId(deviceArg.ieeeAddress), integrationDomain: 'zigbee2mqtt', name: deviceArg.friendlyName,
+      id: this.deviceId(snapshotArg.homeId, deviceArg.ieeeAddress), integrationDomain: 'zigbee2mqtt', name: deviceArg.friendlyName,
       manufacturer: deviceArg.manufacturer, model: deviceArg.model, protocol: 'zigbee',
       online: this.available(snapshotArg, deviceArg),
       features: deviceArg.exposes.map((exposeArg) => ({
         id: exposeArg.property, name: exposeArg.name, capability: exposeArg.capability,
-        readable: exposeArg.readable, writable: exposeArg.writable && deviceArg.supported && !deviceArg.disabled,
+        readable: exposeArg.readable, writable: this.writable(snapshotArg, deviceArg, exposeArg),
         unit: exposeArg.unit,
       })),
       state: deviceArg.exposes.filter((exposeArg) => exposeArg.readable).flatMap((exposeArg) => {
@@ -67,6 +67,7 @@ export class Zigbee2MqttMapper {
         return state ? [{ featureId: exposeArg.property, value: state.value, updatedAt: state.updatedAt }] : [];
       }),
       metadata: {
+        homeId: snapshotArg.homeId,
         ieeeAddress: deviceArg.ieeeAddress, supported: deviceArg.supported, disabled: deviceArg.disabled,
         unsupportedExposes: deviceArg.unsupportedExposes,
         availability: snapshotArg.availability.has(deviceArg.ieeeAddress) ? snapshotArg.availability.get(deviceArg.ieeeAddress) ? 'online' : 'offline' : 'unknown',
@@ -76,18 +77,23 @@ export class Zigbee2MqttMapper {
 
   public static toEntities(snapshotArg: IZigbee2MqttSnapshot): IIntegrationEntity[] {
     return snapshotArg.devices.flatMap((deviceArg) => deviceArg.exposes.map((exposeArg) => ({
-      id: this.entityId(deviceArg.ieeeAddress, exposeArg.property),
-      uniqueId: this.entityId(deviceArg.ieeeAddress, exposeArg.property),
-      integrationDomain: 'zigbee2mqtt', deviceId: this.deviceId(deviceArg.ieeeAddress),
+      id: this.entityId(snapshotArg.homeId, deviceArg.ieeeAddress, exposeArg.property),
+      uniqueId: this.entityId(snapshotArg.homeId, deviceArg.ieeeAddress, exposeArg.property),
+      integrationDomain: 'zigbee2mqtt', deviceId: this.deviceId(snapshotArg.homeId, deviceArg.ieeeAddress),
       name: `${deviceArg.friendlyName} ${exposeArg.name}`, platform: exposeArg.platform,
       available: this.available(snapshotArg, deviceArg),
       state: exposeArg.readable ? snapshotArg.state.get(deviceArg.ieeeAddress)?.get(exposeArg.property)?.value ?? null : null,
-      attributes: { property: exposeArg.property, readable: exposeArg.readable, writable: exposeArg.writable && deviceArg.supported && !deviceArg.disabled,
+      attributes: { homeId: snapshotArg.homeId, property: exposeArg.property, readable: exposeArg.readable, writable: this.writable(snapshotArg, deviceArg, exposeArg),
         unit: exposeArg.unit, minimum: exposeArg.minimum, maximum: exposeArg.maximum, step: exposeArg.step,
         values: exposeArg.values ? [...exposeArg.values] : undefined },
     })));
   }
 
+  public static writable(snapshotArg: IZigbee2MqttSnapshot, deviceArg: IZigbee2MqttDevice, exposeArg: IZigbee2MqttExpose): boolean {
+    return snapshotArg.inventoryCurrent && exposeArg.writable && deviceArg.supported && !deviceArg.disabled &&
+      snapshotArg.controls.has(zigbee2MqttControlKey(deviceArg.ieeeAddress, exposeArg.property));
+  }
+
   public static available(snapshotArg: IZigbee2MqttSnapshot, deviceArg: IZigbee2MqttDevice): boolean {
     return snapshotArg.connected && snapshotArg.bridgeOnline && snapshotArg.inventoryCurrent &&
       deviceArg.supported && !deviceArg.disabled && snapshotArg.availability.get(deviceArg.ieeeAddress) === true;

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.types.ts

@@ -1,13 +1,17 @@
 import type { TEntityPlatform } from '../../core/types.js';
 import type * as plugins from '../../plugins.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
+import type { IMqttCredentialRequest, IMqttTransportCredentials } from '../mqtt/mqtt.types.js';
 
 export interface IZigbee2MqttConfig {
+  homeId: string;
+  authentication: 'anonymous' | 'provider' | 'config-store';
+  credentialKey?: string;
+  allowUnencryptedLan?: boolean;
   host: string;
   baseTopic: string;
   port?: number;
   protocol?: 'mqtt' | 'mqtts';
-  username?: string;
-  password?: string;
   clientId?: string;
   connectTimeoutMs?: number;
   operationTimeoutMs?: number;
@@ -18,6 +22,33 @@ export interface IZigbee2MqttConfig {
   maxBufferedBytes?: number;
 }
 
+/** Runtime-only owner permission; it is never learned from MQTT or editable config. */
+export interface IZigbee2MqttControlPermission {
+  readonly ieeeAddress: string;
+  readonly property: string;
+}
+
+export interface IZigbee2MqttCredentialRequest extends IMqttCredentialRequest {
+  readonly host: string;
+  readonly port: number;
+  readonly protocol: 'mqtt' | 'mqtts';
+  readonly baseTopic: string;
+}
+
+export interface IZigbee2MqttStoredCredential {
+  version: 1;
+  host: string;
+  port: number;
+  protocol: 'mqtt' | 'mqtts';
+  baseTopic: string;
+  credentials: IMqttTransportCredentials;
+}
+
+export interface IZigbee2MqttIntegrationOptions extends INativeIntegrationOwnerOptions {
+  readonly controls?: readonly IZigbee2MqttControlPermission[];
+  readonly resolveCredentials?: (requestArg: IZigbee2MqttCredentialRequest) => Promise<IMqttTransportCredentials>;
+}
+
 export type TZigbee2MqttPrimitive = string | number | boolean;
 
 export interface IZigbee2MqttExpose {
@@ -54,6 +85,8 @@ export interface IZigbee2MqttReportedState {
 }
 
 export interface IZigbee2MqttSnapshot {
+  homeId: string;
+  controls: ReadonlySet<string>;
   devices: IZigbee2MqttDevice[];
   connected: boolean;
   bridgeOnline: boolean;