@smarthome.exchange/integrations 1.0.0 → 3.0.0

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;

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.validation.ts

@@ -1,5 +1,7 @@
 import { validateMqttTopic } from '../mqtt/mqtt.classes.client.js';
-import type { IZigbee2MqttConfig, TZigbee2MqttPrimitive } from './zigbee2mqtt.types.js';
+import { mqttCredentials } from '../mqtt/mqtt.validation.js';
+import type { IMqttTransportCredentials } from '../mqtt/mqtt.types.js';
+import type { IZigbee2MqttConfig, IZigbee2MqttIntegrationOptions, TZigbee2MqttPrimitive } from './zigbee2mqtt.types.js';
 
 export const zigbee2MqttRecord = (valueArg: unknown): Record<string, unknown> | undefined => {
   if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return undefined;
@@ -25,9 +27,14 @@ export const zigbee2MqttInteger = (valueArg: unknown, defaultArg: number, maximu
 
 export const zigbee2MqttConfig = (configArg: IZigbee2MqttConfig): IZigbee2MqttConfig => {
   const config = zigbee2MqttRecord(configArg);
-  const allowed = new Set(['host', 'baseTopic', 'port', 'protocol', 'username', 'password', 'clientId',
+  const allowed = new Set(['homeId', 'authentication', 'credentialKey', 'allowUnencryptedLan', 'host', 'baseTopic', 'port', 'protocol', 'clientId',
     'connectTimeoutMs', 'operationTimeoutMs', 'inventoryTimeoutMs', 'reconnectPeriodMs', 'maxDevices', 'maxPayloadBytes', 'maxBufferedBytes']);
   if (!config || Object.keys(config).some((keyArg) => !allowed.has(keyArg))) throw new Error('Unsupported Zigbee2MQTT configuration field.');
+  const homeId = zigbee2MqttIdentifier(config.homeId);
+  if (typeof config.authentication !== 'string' || !['anonymous', 'provider', 'config-store'].includes(config.authentication)) throw new Error('Explicit Zigbee2MQTT authentication mode is required.');
+  const authentication = config.authentication as IZigbee2MqttConfig['authentication'];
+  const credentialKey = config.credentialKey === undefined ? undefined : zigbee2MqttIdentifier(config.credentialKey);
+  if ((authentication === 'anonymous') !== (credentialKey === undefined)) throw new Error('Zigbee2MQTT credential reference must agree with the explicit authentication mode.');
   if (typeof config.host !== 'string' || !config.host || config.host.length > 253 || /[\s/@?#\u0000]/.test(config.host)) {
     throw new Error('An explicit Zigbee2MQTT broker hostname or IP address is required.');
   }
@@ -37,7 +44,9 @@ export const zigbee2MqttConfig = (configArg: IZigbee2MqttConfig): IZigbee2MqttCo
   }
   validateMqttTopic(config.baseTopic);
   if (config.protocol !== undefined && config.protocol !== 'mqtt' && config.protocol !== 'mqtts') throw new Error('Unsupported Zigbee2MQTT broker protocol.');
-  for (const key of ['username', 'password', 'clientId']) {
+  if (config.allowUnencryptedLan !== undefined && typeof config.allowUnencryptedLan !== 'boolean') throw new Error('Zigbee2MQTT plaintext LAN consent must be explicit.');
+  if (config.protocol !== 'mqtts' && config.allowUnencryptedLan !== true) throw new Error('Unencrypted Zigbee2MQTT MQTT requires explicit LAN consent.');
+  for (const key of ['clientId']) {
     if (config[key] !== undefined && (typeof config[key] !== 'string' || String(config[key]).length > 1024 || String(config[key]).includes('\u0000'))) {
       throw new Error('Invalid Zigbee2MQTT broker credential or client identifier.');
     }
@@ -46,13 +55,12 @@ export const zigbee2MqttConfig = (configArg: IZigbee2MqttConfig): IZigbee2MqttCo
   if (typeof reconnect !== 'number' || !Number.isSafeInteger(reconnect) || reconnect < 0 || reconnect > 60000) {
     throw new Error('Invalid Zigbee2MQTT reconnect interval.');
   }
-  return {
+  return Object.freeze({
+    homeId, authentication, credentialKey, allowUnencryptedLan: config.allowUnencryptedLan as boolean | undefined,
     host: config.host,
     baseTopic: config.baseTopic,
     protocol: config.protocol ?? 'mqtt',
     port: zigbee2MqttInteger(config.port, config.protocol === 'mqtts' ? 8883 : 1883, 65535),
-    username: config.username as string | undefined,
-    password: config.password as string | undefined,
     clientId: config.clientId as string | undefined,
     connectTimeoutMs: zigbee2MqttInteger(config.connectTimeoutMs, 7000, 60000),
     operationTimeoutMs: zigbee2MqttInteger(config.operationTimeoutMs, 7000, 60000),
@@ -61,5 +69,43 @@ export const zigbee2MqttConfig = (configArg: IZigbee2MqttConfig): IZigbee2MqttCo
     maxDevices: zigbee2MqttInteger(config.maxDevices, 2048, 10000),
     maxPayloadBytes: zigbee2MqttInteger(config.maxPayloadBytes, 8388608, 16777216),
     maxBufferedBytes: zigbee2MqttInteger(config.maxBufferedBytes, 33554432, 67108864),
-  };
+  });
+};
+
+export const zigbee2MqttIdentifier = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.length > 256 || valueArg.trim() !== valueArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError('Zigbee2MQTT identifier must be a bounded non-empty data string.');
+  }
+  return valueArg;
+};
+
+export const zigbee2MqttControlKey = (ieeeAddressArg: string, propertyArg: string): string => JSON.stringify([ieeeAddressArg, propertyArg]);
+
+export const zigbee2MqttCredentials = (configArg: IZigbee2MqttConfig, valueArg: unknown): IMqttTransportCredentials => {
+  const credentials = mqttCredentials(valueArg);
+  if (configArg.protocol !== 'mqtts' && ['ca', 'cert', 'key', 'servername'].some((key) => Object.hasOwn(credentials, key))) {
+    throw new TypeError('Zigbee2MQTT TLS credentials require an explicitly selected mqtts transport.');
+  }
+  return credentials;
+};
+
+export const zigbee2MqttOptions = (optionsArg: IZigbee2MqttIntegrationOptions): { options: IZigbee2MqttIntegrationOptions; controls: ReadonlySet<string> } => {
+  const fields = zigbee2MqttRecord(optionsArg);
+  if (!fields || Object.keys(fields).some((key) => !['homeId', 'capacity', 'controls', 'resolveCredentials'].includes(key))) throw new TypeError('Unsupported Zigbee2MQTT owner options.');
+  if (fields.resolveCredentials !== undefined && typeof fields.resolveCredentials !== 'function') throw new TypeError('Zigbee2MQTT resolver must be a function.');
+  const controls = new Set<string>();
+  if (fields.controls !== undefined) {
+    if (!Array.isArray(fields.controls) || fields.controls.length > 10000 || Reflect.ownKeys(fields.controls).length !== fields.controls.length + 1) throw new TypeError('Zigbee2MQTT owner controls must be a finite data array.');
+    for (let index = 0; index < fields.controls.length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(fields.controls, String(index));
+      const permission = descriptor && 'value' in descriptor && descriptor.enumerable ? zigbee2MqttRecord(descriptor.value) : undefined;
+      if (!permission || Object.keys(permission).length !== 2 || typeof permission.ieeeAddress !== 'string' || !/^0x[0-9a-f]{16}$/.test(permission.ieeeAddress) ||
+        typeof permission.property !== 'string' || !/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/.test(permission.property)) throw new TypeError('Zigbee2MQTT controls require exact lowercase IEEE/property pairs.');
+      const key = zigbee2MqttControlKey(permission.ieeeAddress, permission.property);
+      if (controls.has(key)) throw new TypeError('Duplicate Zigbee2MQTT owner control permission.');
+      controls.add(key);
+    }
+  }
+  return { options: Object.freeze({ homeId: fields.homeId as string | undefined, capacity: fields.capacity as number | undefined,
+    resolveCredentials: fields.resolveCredentials as IZigbee2MqttIntegrationOptions['resolveCredentials'] }), controls };
 };

package/ts/integrations/zwave_js/readme.md

@@ -1,23 +1,56 @@
 # Native Z-Wave JS
 
-This adapter connects directly to the [Z-Wave JS server WebSocket API](https://github.com/zwave-js/zwave-js-server#readme). Home Assistant is not part of the runtime path. It negotiates schema 32, verifies the configured Z-Wave network home ID, and awaits the server's authoritative initial state before setup succeeds.
+This adapter connects to one explicitly selected [Z-Wave JS server WebSocket API](https://github.com/zwave-js/zwave-js-server#readme). It negotiates schema32, available from server1.32.0, verifies the numeric Z-Wave network ID in both greeting and authoritative initial state, and waits for that state before setup succeeds. Home Assistant and serial-controller access are outside this runtime.
 
 ```typescript
-const runtime = await new ZwaveJsIntegration().setup({
+const homeId = 'my-home'; // Independently selected by the embedding host.
+const integration = new ZwaveJsIntegration();
+const runtime = await integration.setup({
+  homeId,
   url: 'ws://zwave-js.local:3000',
   expectedHomeId: 123456,
+  allowControls: true, // Optional; the default is read-only.
   requestTimeoutMs: 10000,
-}, { abortSignal });
+}, { homeId });
+try {
+  const devices = await runtime.devices();
+} finally {
+  await integration.destroy();
+}
 ```
 
-The network home ID is the decimal form of the ID displayed by Z-Wave JS. Device and entity identities include it, the node ID and the exact value ID. Renaming a node does not change its identity. The new network-scoped IDs replace the earlier node-only IDs. Configuration requires an explicit endpoint and expected home ID; injected nodes, state, version and schema overrides are removed.
+`context.homeId` is required separately for setup, direct `ZwaveJsClient(config, context, options?)` and config-flow start. Constructor `{ homeId?, capacity? }` adds an optional consistency constraint; it never substitutes for context. Config, form, discovery and store scope cannot select host home. The first admitted host remains bound even after failed setup. Integration and flow share admission and terminal ownership. The flow captures context before returning its form, has no editable SHX home field, rejects conflicting submitted home, and returns the captured home. This is a trusted embedding-host contract, not a home string used as authentication.
 
-The native server does not implement authentication. Use `ws` only on an explicitly trusted network. For an operator-managed TLS proxy that enforces HTTP authorization, configure `wss` and an `authorization` header. Certificate and hostname verification stay enabled; optional `ca` adds a PEM trust anchor. Credentials in URLs, query strings, plaintext authorization and redirects are rejected. Endpoint discovery supplies a setup hint and never proves authorization or network ownership. The config flow verifies a live connection before completing. Store its resulting configuration through the host's encrypted config store.
+`config.homeId` is the SHX consistency value. `expectedHomeId` is the separate decimal32-bit Z-Wave network ID shown by the server. Device/entity IDs include encoded SHX home, observed network ID, node and exact value tuple. These IDs replace the earlier network-only IDs; saved canonical targets must be refreshed. Node renaming does not change identity. Endpoint, property and optional propertyKey retain their actual number/string distinctions. No persistent authenticated server UUID is exposed by this protocol. Network ID and software versions alone do not prove server ownership or physical controller identity. The server connection record explicitly represents an adapter observation.
 
-The read surface includes server-reported node state and non-secret values. Driver/controller management, inclusion, arbitrary command-class APIs, locks, thermostat actions and configuration writes are excluded. Supported controls are advertised writable `targetValue` entries for Binary Switch (CC 37, boolean) and Multilevel Switch (CC 38, integer 0–99 constrained further by server metadata). Use `writeFeature` with the exact current device and feature, or `switch`/`light` `turn_on`, `turn_off`, `set_value` with an exact entity/device target. Device targets with multiple supported values require `data.featureId`; ambiguous, foreign and missing targets fail. Caller-supplied feature capabilities do not grant access; the verified server snapshot owns eligibility.
+The native server supplies no authentication. Use `ws` on an explicitly trusted selected network. An operator-managed verified TLS proxy can enforce HTTP authorization. URLs cannot contain credentials, query strings or fragments, and redirects are disabled. Certificate and hostname verification remain enabled; optional `ca` adds a PEM trust anchor. Discovery is an endpoint/setup hint and never grants authorization.
 
-The [driver's SetValueResult contract](https://github.com/zwave-js/node-zwave-js/blob/master/packages/cc/src/lib/SetValueResult.ts) distinguishes supervised completion from acceptance. Only status 255 returns `success: true` with `outcome: 'confirmed'`. Working (1) and unsupervised (254) replies return `success: false` with their indeterminate outcome; device rejection retains its status. Command responses never invent device state. Reported changes come from `value updated` events. Metadata and membership changes trigger bounded, coalesced reconciliation from the server.
+Proxy configuration contains only `credentialRef` and explicit `credentialSource`. The two sources have no fallback:
 
-One client owns one socket, at most 64 pending commands, a 2 MiB frame limit, bounded JSON depth/work, and 50–60000 ms deadlines (default 10000 ms). Caller cancellation before dispatch sends nothing; cancellation after dispatch cannot undo a physical command and rejects as indeterminate. Disconnect, protocol failure and deadline expiry stop the client. Reads retain the detached last snapshot with all devices unavailable and never restart the transport. There are no automatic reconnects or uncertain write retries; explicitly replace the runtime after inspecting the operation's outcome. `destroy()` is idempotent, rejects pending work, drains startup/reconciliation, removes subscriptions and waits for the owned socket to close. Setup's abort signal owns the runtime lifetime.
+- `provider`: constructor options supply caller-owned asynchronous `resolveAuthorization({ homeId, credentialRef, signal, deadline })`. The request is immutable; `deadline` uses monotonic `performance.now()` milliseconds and covers resolution plus setup. The host stores/retrieves the header outside the integration.
+- `config-store`: explicit `context.configStore` is an actual encrypted `NoSqlConfigStore` scoped to the same SHX home and `zwave_js`; its public `get<string>(credentialRef)` returns the externally stored header.
 
-Local protocol fixtures cover startup, TLS proxy admission and rejected credentials, certificate verification, network identity, authoritative events, membership reconciliation, controls, execution outcomes, malformed frames, cancellation and cleanup. Physical acceptance against a real controller and representative supervised/unsupervised nodes remains required; the adapter has not been exercised against the owner's hardware.
+Both require `wss`. The adapter never returns, logs or persists the resolved header. The reference is not a credential and never selects a home. No source is required without proxy authorization. An optional genuine store is checked for exact home/domain even on store-free paths, remains borrowed, and is never closed along with its database/key provider. There is no filesystem persistence, raw-driver access, dummy store or implicit source replacement.
+
+```typescript
+const integration = new ZwaveJsIntegration({
+  resolveAuthorization: async ({ homeId, credentialRef, signal, deadline }) =>
+    hostCredentials.resolve({ homeId, credentialRef, signal, deadline }),
+});
+const runtime = await integration.setup({
+  homeId: 'my-home', url: 'wss://zwave-js.example/', expectedHomeId: 123456,
+  credentialRef: 'zwave-proxy', credentialSource: 'provider',
+}, { homeId: 'my-home' });
+```
+
+Read observations are server-reported nodes, readiness/status and non-secret values; no default nodes/capabilities are inferred. Controls require explicit `allowControls: true`, a healthy runtime, an unambiguous canonical target, and a fresh authoritative membership/metadata snapshot before each one-shot dispatch. Supported writes remain advertised writable `targetValue` entries for Binary Switch(CC37, boolean) and Multilevel Switch(CC38, integer0..99 further restricted by actual metadata). Offline/stale/read-only features and entities advertise no writability. Supplied feature flags cannot grant access.
+
+Use `writeFeature` with exact current device/feature, or `switch`/`light`/`zwave_js` `turn_on`, `turn_off`, `set_value` with exact entity/device target. Device targets with multiple supported values require `data.featureId`. Missing, ambiguous, foreign, unadvertised, secret, unavailable and incompatible targets fail. Only the documented absolute value is sent; no toggles, relative commands, inclusion, management, configuration, locks, thermostat, raw command-class APIs or controller operations exist.
+
+Each request has a unique messageId. Correlated [SetValueResult](https://github.com/zwave-js/node-zwave-js/blob/master/packages/cc/src/lib/SetValueResult.ts) status255 retains legacy `outcome: 'confirmed'` and reports supervised device success. Status1 is working,254 is unsupervised/unknown execution, and other supported statuses are rejection/unsupported/invalid. Every result includes `causalityConfirmed: false`: a device-reported result is not independent physical acceptance or causality proof. Commands never invent reported state. Value-update events and authoritative reconciliation supply separate state observations.
+
+Shared native ownership defaults to16 pending admissions, live runtimes and retained failed cleanup handles combined. The client bounds pending requests, admitted controls/subscriber work and subscribers to64 each, with a2MiB frame limit,128 fragments/chunks and bounded JSON depth/work. Request/setup deadline is50..60000ms(default10000). Cancellation before dispatch sends no effect; cancellation after dispatch cannot undo a command and remains indeterminate. Protocol failure, disconnect and deadline expiry are terminal; retained detached observations become unavailable and never reconnect or replay.
+
+`destroy()` installs its stable memo before abort or callbacks, stops admission, joins actual provider/setup/reconciliation/control/subscriber work and socket closure with allSettled, and then reports cleanup errors. A late provider result after cancellation cannot allocate a socket. An unrelated late provider/subscriber rejection is sanitized and retained; cooperative rejection with the admitted signal reason remains cancellation. Providers own retrieval resources and must eventually settle their admitted promises; close intentionally waits for that actual work after request timeout. `retryCleanup()` explicitly retries cleanup/acknowledges settled failures only. It never invokes the resolver, reconnects or repeats a command, and the original destroy promise remains stable. Closing a flow stops its submissions and leaves sibling runtimes usable; integration close joins all scopes.
+
+Local WebSocket/TLS fixtures cover schema/network admission, events and reconciliation, exact controls/correlation, read-only defaults, home/store/provider boundaries, deadlines, late provider work, capacity, callback failures and terminal cleanup. Physical acceptance on the owner's controller and representative nodes remains unverified; no real controller was accessed.

package/ts/integrations/zwave_js/zwave_js.classes.client.ts

@@ -1,9 +1,17 @@
 import * as plugins from '../../plugins.js';
-import type { IZwaveJsConfig, IZwaveJsServerCommand, IZwaveJsServerEvent, IZwaveJsSnapshot, IZwaveJsState, IZwaveJsVersion, IZwaveJsWriteResult } from './zwave_js.types.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
+import type { IZwaveJsConfig, IZwaveJsIntegrationOptions, IZwaveJsServerCommand, IZwaveJsServerEvent, IZwaveJsSnapshot, IZwaveJsState, IZwaveJsVersion, IZwaveJsWriteResult } from './zwave_js.types.js';
 import { ZwaveJsMapper } from './zwave_js.mapper.js';
-import { parseZwaveJsState, parseZwaveJsValueId, parseZwaveJsVersion, validateZwaveJsConfig, validateZwaveJsJson, validateZwaveJsValueData, zwaveJsRecord, zwaveJsSchemaVersion, zwaveJsValueKey } from './zwave_js.validation.js';
+import { normalizeZwaveJsOptions, parseZwaveJsState, parseZwaveJsValueId, parseZwaveJsVersion, validateZwaveJsConfig, validateZwaveJsJson, validateZwaveJsValueData, zwaveJsRecord, zwaveJsSchemaVersion, zwaveJsValueKey } from './zwave_js.validation.js';
 
-type TEventHandler = (eventArg: IZwaveJsServerEvent) => void;
+type TEventHandler = (eventArg: IZwaveJsServerEvent) => void | Promise<void>;
+interface ISubscription {
+  handler: TEventHandler;
+  active: boolean;
+  pending: Set<Promise<void>>;
+  failures: Set<Error>;
+}
 
 interface IPendingRequest {
   resolve(valueArg: unknown): void;
@@ -14,10 +22,16 @@ interface IPendingRequest {
 
 export class ZwaveJsClient {
   #config: IZwaveJsConfig;
+  readonly #context: INativeAdmissionContext;
+  readonly #options: Readonly<IZwaveJsIntegrationOptions>;
+  readonly #lifetime = new AbortController();
+  readonly #operations = new Set<Promise<unknown>>();
+  readonly #cleanupFailures = new Set<Error>();
   #socket?: plugins.ws.WebSocket;
   #socketClosed?: Promise<void>;
   #startPromise?: Promise<void>;
   #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
   #version?: IZwaveJsVersion;
   #state?: IZwaveJsState;
   #ready = false;
@@ -25,7 +39,7 @@ export class ZwaveJsClient {
   #failure?: Error;
   #greeting?: { resolve(): void; reject(errorArg: Error): void };
   #pending = new Map<string, IPendingRequest>();
-  #handlers = new Set<TEventHandler>();
+  #handlers = new Set<ISubscription>();
   #events: IZwaveJsServerEvent[] = [];
   #refreshNeeded = false;
   #snapshotStale = false;
@@ -33,9 +47,18 @@ export class ZwaveJsClient {
   #lifetimeSignal?: AbortSignal;
   #lifetimeAbort?: () => void;
 
-  constructor(configArg: IZwaveJsConfig, lifetimeSignalArg?: AbortSignal) {
+  constructor(configArg: IZwaveJsConfig, contextArg: IIntegrationSetupContext, optionsArg: IZwaveJsIntegrationOptions = {}) {
     this.#config = validateZwaveJsConfig(configArg);
-    this.#lifetimeSignal = lifetimeSignalArg;
+    this.#options = normalizeZwaveJsOptions(optionsArg);
+    this.#context = new NativeHomeAdmission('zwave_js', { homeId: this.#options.homeId }).admit(contextArg, this.#config.homeId);
+    if (this.#config.credentialSource === 'provider' && !this.#options.resolveAuthorization ||
+      this.#config.credentialSource === 'config-store' && !this.#context.configStore) {
+      throw new Error('Z-Wave JS selected credential source is unavailable.');
+    }
+    this.#lifetimeSignal = AbortSignal.any([this.#lifetime.signal,
+      ...(this.#context.abortSignal ? [this.#context.abortSignal] : [])]);
+    this.#lifetimeAbort = () => this.fail(new Error('Z-Wave JS lifetime was aborted.'));
+    this.#lifetimeSignal.addEventListener('abort', this.#lifetimeAbort, { once: true });
   }
 
   public isHealthy(): boolean {
@@ -45,7 +68,7 @@ export class ZwaveJsClient {
   public start(abortSignalArg?: AbortSignal): Promise<void> {
     if (this.#destroyed || this.#failure) return Promise.reject(this.#failure ?? new Error('Z-Wave JS client is destroyed.'));
     if (abortSignalArg?.aborted || this.#lifetimeSignal?.aborted) return Promise.reject(new Error('Z-Wave JS setup was aborted.'));
-    if (!this.#startPromise) this.#startPromise = this.connect();
+    if (!this.#startPromise) this.#startPromise = Promise.resolve().then(() => this.connect());
     return this.withAbort(this.#startPromise, abortSignalArg);
   }
 
@@ -56,9 +79,22 @@ export class ZwaveJsClient {
     return this.snapshot();
   }
 
-  public async sendCommand(commandArg: IZwaveJsServerCommand, abortSignalArg?: AbortSignal): Promise<IZwaveJsWriteResult> {
+  public sendCommand(commandArg: IZwaveJsServerCommand, abortSignalArg?: AbortSignal): Promise<IZwaveJsWriteResult> {
+    if (!this.isHealthy() || !this.#config.allowControls) return Promise.reject(new Error('Z-Wave JS controls require an authorized healthy server.'));
+    if (this.#operations.size >= 64) return Promise.reject(new Error('Z-Wave JS operation capacity reached.'));
+    // Capture the exact identity/value before deferred work or foreign callbacks.
+    let command: IZwaveJsServerCommand;
+    try { command = ZwaveJsMapper.validateCommand(this.snapshot(), commandArg); }
+    catch (errorArg) { return Promise.reject(errorArg); }
+    return this.track(() => this.executeCommand(command, abortSignalArg));
+  }
+
+  private async executeCommand(commandArg: IZwaveJsServerCommand, abortSignalArg?: AbortSignal): Promise<IZwaveJsWriteResult> {
     if (abortSignalArg?.aborted) throw new Error('Z-Wave JS control was aborted before dispatch.');
     if (!this.isHealthy()) throw new Error('Z-Wave JS control requires a healthy verified server.');
+    // Fresh authoritative advertised membership/metadata is required for every effect.
+    await this.requestState(abortSignalArg);
+    if (!this.isHealthy()) throw new Error('Z-Wave JS control metadata is unavailable or stale.');
     const command = ZwaveJsMapper.validateCommand(this.snapshot(), commandArg);
     const response = await this.request('node.set_value', {
       nodeId: command.nodeId, valueId: command.valueId, value: command.value,
@@ -70,44 +106,94 @@ export class ZwaveJsClient {
       throw error;
     }
     const status = response.result.status;
-    return { status, outcome: status === 255 ? 'confirmed' : status === 1 ? 'working' : status === 254 ? 'unsupervised' : 'rejected' };
+    return { status, outcome: status === 255 ? 'confirmed' : status === 1 ? 'working' : status === 254 ? 'unsupervised' : 'rejected', causalityConfirmed: false };
   }
 
-  public onEvent(handlerArg: TEventHandler): () => void {
+  public onEvent(handlerArg: TEventHandler): () => Promise<void> {
     if (this.#destroyed) throw new Error('Z-Wave JS client is destroyed.');
-    this.#handlers.add(handlerArg);
-    return () => { this.#handlers.delete(handlerArg); };
+    if (typeof handlerArg !== 'function') throw new TypeError('Z-Wave JS subscriber must be a function.');
+    if (this.#handlers.size >= 64) throw new Error('Z-Wave JS subscriber capacity reached.');
+    const subscription: ISubscription = { handler: handlerArg, active: true, pending: new Set(), failures: new Set() };
+    this.#handlers.add(subscription);
+    return async () => {
+      subscription.active = false;
+      await Promise.allSettled([...subscription.pending]);
+      if (subscription.failures.size) throw new AggregateError([...subscription.failures], 'Z-Wave JS subscriber cleanup failed.');
+      this.#handlers.delete(subscription);
+    };
   }
 
   public destroy(): Promise<void> {
     if (!this.#closePromise) {
       this.#destroyed = true;
+      // Publish the stable memo before abort/failure emits any foreign callback.
+      this.#closePromise = Promise.resolve().then(() => this.closeOwnedResources());
       this.fail(new Error('Z-Wave JS client is destroyed.'));
-      this.#handlers.clear();
-      this.#closePromise = this.closeOwnedResources();
+      for (const subscription of this.#handlers) subscription.active = false;
     }
     return this.#closePromise;
   }
 
+  /** Retry retained cleanup only. Never reconnect, resolve credentials or repeat commands. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#destroyed) return this.destroy();
+    if (!this.#retryPromise) {
+      this.#retryPromise = Promise.resolve().then(async () => {
+        await Promise.allSettled([this.#closePromise]);
+        this.#cleanupFailures.clear();
+        for (const subscription of this.#handlers) subscription.failures.clear();
+        await this.closeOwnedResources();
+      });
+      void this.#retryPromise.then(() => { this.#retryPromise = undefined; }, () => { this.#retryPromise = undefined; });
+    }
+    return this.#retryPromise;
+  }
+
   private async connect(): Promise<void> {
+    if (this.#failure || this.#destroyed || this.#lifetimeSignal?.aborted) throw new Error('Z-Wave JS setup was stopped.');
+    const deadlineAt = performance.now() + this.#config.requestTimeoutMs!;
+    let authorization: string | undefined;
+    if (this.#config.credentialRef) {
+      const signal = this.#lifetimeSignal!;
+      const request = Object.freeze({ homeId: this.#context.homeId, credentialRef: this.#config.credentialRef, signal, deadline: deadlineAt });
+      // The actual promise is owned before entering the borrowed provider/store callback.
+      const resolution = this.track(async () => {
+        try {
+          return this.#config.credentialSource === 'provider' ? await this.#options.resolveAuthorization!(request) :
+            await this.#context.configStore!.get<string>(request.credentialRef);
+        } catch (errorArg) {
+          const error = new Error('Z-Wave JS credential resolution failed.');
+          if (signal.aborted && errorArg !== signal.reason) this.#cleanupFailures.add(error);
+          throw error;
+        }
+      });
+      try { authorization = await this.waitForCredential(resolution, signal, deadlineAt); }
+      catch { this.fail(new Error('Z-Wave JS credential admission failed.')); throw this.#failure; }
+      if (typeof authorization !== 'string' || !authorization.trim() || authorization.length > 4096 || /[\x00-\x1f\x7f]/.test(authorization)) {
+        this.fail(new Error('Z-Wave JS credential provider returned an invalid authorization header.'));
+        throw this.#failure;
+      }
+    }
+    if (this.#destroyed || this.#failure || this.#lifetimeSignal?.aborted || performance.now() >= deadlineAt) {
+      this.fail(new Error('Z-Wave JS setup was stopped before connection.'));
+      throw this.#failure;
+    }
     const greeting = new Promise<void>((resolveArg, rejectArg) => {
       this.#greeting = { resolve: resolveArg, reject: rejectArg };
     });
     const greetingOutcome = greeting.then(() => ({ accepted: true as const }),
       (errorArg: unknown) => ({ accepted: false as const, error: errorArg }));
-    const deadline = setTimeout(() => this.fail(new Error('Z-Wave JS setup deadline expired.')), this.#config.requestTimeoutMs);
-    if (this.#lifetimeSignal) {
-      this.#lifetimeAbort = () => this.fail(new Error('Z-Wave JS lifetime was aborted.'));
-      this.#lifetimeSignal.addEventListener('abort', this.#lifetimeAbort, { once: true });
-    }
+    const remainingMs = Math.max(1, deadlineAt - performance.now());
+    const deadline = setTimeout(() => this.fail(new Error('Z-Wave JS setup deadline expired.')), remainingMs);
     try {
       const socket = new plugins.ws.WebSocket(this.#config.url, {
-        headers: this.#config.authorization ? { Authorization: this.#config.authorization } : undefined,
+        headers: authorization ? { Authorization: authorization } : undefined,
         ca: this.#config.ca, rejectUnauthorized: true, followRedirects: false,
-        handshakeTimeout: this.#config.requestTimeoutMs,
+        handshakeTimeout: remainingMs,
         maxPayload: 2 * 1024 * 1024, maxFragments: 128, maxBufferedChunks: 128, perMessageDeflate: false,
       });
       this.#socket = socket;
+      authorization = undefined;
       this.#socketClosed = new Promise<void>((resolveArg) => socket.once('close', () => resolveArg()));
       socket.on('error', () => this.fail(new Error('Z-Wave JS WebSocket connection failed.')));
       socket.on('close', () => this.fail(new Error('Z-Wave JS WebSocket connection closed.')));
@@ -155,8 +241,8 @@ export class ZwaveJsClient {
     });
   }
 
-  private requestState(): Promise<unknown> {
-    return this.request('start_listening', {}, undefined, (resultArg) => {
+  private requestState(abortSignalArg?: AbortSignal): Promise<unknown> {
+    return this.request('start_listening', {}, abortSignalArg, (resultArg) => {
       if (!zwaveJsRecord(resultArg)) throw new Error('Malformed Z-Wave JS state result.');
       this.#state = parseZwaveJsState(resultArg.state, this.#config.expectedHomeId);
       this.#snapshotStale = false;
@@ -243,7 +329,7 @@ export class ZwaveJsClient {
     this.#refreshNeeded = true;
     this.#snapshotStale = true;
     if (this.#refreshPromise) return;
-    this.#refreshPromise = (async () => {
+    this.#refreshPromise = Promise.resolve().then(async () => {
       try {
         while (this.#refreshNeeded && !this.#failure && !this.#destroyed) {
           this.#refreshNeeded = false;
@@ -253,22 +339,38 @@ export class ZwaveJsClient {
       } catch (errorArg) {
         this.fail(errorArg instanceof Error ? errorArg : new Error('Z-Wave JS state reconciliation failed.'));
       } finally { this.#refreshPromise = undefined; }
-    })();
+    });
   }
 
   private emit(eventArg: IZwaveJsServerEvent): void {
     this.#events.push(structuredClone(eventArg));
     if (this.#events.length > 64) this.#events.shift();
-    for (const handler of this.#handlers) {
-      try { handler(structuredClone(eventArg)); } catch {
-        this.#handlers.delete(handler);
-        this.fail(new Error('Z-Wave JS subscriber failed; the runtime was stopped.'));
+    for (const subscription of this.#handlers) {
+      if (!subscription.active) continue;
+      if (this.#operations.size >= 64) {
+        this.fail(new Error('Z-Wave JS subscriber operation capacity reached.'));
+        break;
       }
+      const event = structuredClone(eventArg);
+      const notification = this.track(async () => {
+        if (!subscription.active) return;
+        try { await subscription.handler(event); }
+        catch {
+          const error = new Error('Z-Wave JS subscriber failed; the runtime was stopped.');
+          subscription.failures.add(error);
+          this.#cleanupFailures.add(error);
+          subscription.active = false;
+          this.fail(error);
+        }
+      });
+      subscription.pending.add(notification);
+      void notification.then(() => subscription.pending.delete(notification), () => subscription.pending.delete(notification));
     }
   }
 
   private snapshot(): IZwaveJsSnapshot {
     return structuredClone({
+      homeId: this.#context.homeId, allowControls: this.#config.allowControls === true,
       version: this.#version, controller: this.#state?.controller, nodes: this.#state?.nodes ?? [],
       connected: this.isHealthy(), events: this.#events,
     });
@@ -282,15 +384,36 @@ export class ZwaveJsClient {
     this.#greeting?.reject(errorArg);
     for (const pending of this.#pending.values()) { pending.cleanup(); pending.reject(errorArg); }
     this.#pending.clear();
+    this.#lifetime.abort(errorArg);
     this.#socket?.terminate();
     this.emit({ source: 'connection', event: 'closed' });
   }
 
   private async closeOwnedResources(): Promise<void> {
     if (this.#lifetimeAbort) this.#lifetimeSignal?.removeEventListener('abort', this.#lifetimeAbort);
-    await Promise.allSettled([this.#startPromise, this.#refreshPromise, this.#socketClosed].filter((promiseArg) => promiseArg !== undefined));
+    await Promise.allSettled([this.#startPromise, this.#refreshPromise, this.#socketClosed, ...this.#operations].filter((promiseArg) => promiseArg !== undefined));
     this.#socket?.removeAllListeners();
     this.#socket = undefined;
+    if (this.#cleanupFailures.size) throw new AggregateError([...this.#cleanupFailures], 'Z-Wave JS cleanup failed; settled failures remain retained for explicit cleanup retry.');
+    this.#handlers.clear();
+  }
+
+  private track<TResult>(workArg: () => Promise<TResult>): Promise<TResult> {
+    const operation = Promise.resolve().then(workArg);
+    this.#operations.add(operation);
+    void operation.then(() => this.#operations.delete(operation), () => this.#operations.delete(operation));
+    return operation;
+  }
+
+  private waitForCredential(promiseArg: Promise<string | undefined>, signalArg: AbortSignal, deadlineArg: number): Promise<string | undefined> {
+    return new Promise((resolveArg, rejectArg) => {
+      const abort = () => { cleanup(); rejectArg(new Error('Z-Wave JS credential admission was aborted.')); };
+      const timer = setTimeout(() => { cleanup(); rejectArg(new Error('Z-Wave JS credential deadline expired.')); }, Math.max(1, deadlineArg - performance.now()));
+      const cleanup = () => { clearTimeout(timer); signalArg.removeEventListener('abort', abort); };
+      signalArg.addEventListener('abort', abort, { once: true });
+      if (signalArg.aborted) abort();
+      void promiseArg.then((valueArg) => { cleanup(); resolveArg(valueArg); }, () => { cleanup(); rejectArg(new Error('Z-Wave JS credential resolution failed.')); });
+    });
   }
 
   private withAbort(promiseArg: Promise<void>, abortSignalArg?: AbortSignal): Promise<void> {
@@ -302,7 +425,8 @@ export class ZwaveJsClient {
         rejectArg(error);
       };
       abortSignalArg.addEventListener('abort', abort, { once: true });
-      promiseArg.then(resolveArg, rejectArg).finally(() => abortSignalArg.removeEventListener('abort', abort));
+      void promiseArg.then(() => { abortSignalArg.removeEventListener('abort', abort); resolveArg(); },
+        (errorArg: unknown) => { abortSignalArg.removeEventListener('abort', abort); rejectArg(errorArg); });
     });
   }
 }