@smarthome.exchange/integrations 0.1.0 → 1.0.0

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

@@ -0,0 +1,65 @@
+import { validateMqttTopic } from '../mqtt/mqtt.classes.client.js';
+import type { IZigbee2MqttConfig, TZigbee2MqttPrimitive } from './zigbee2mqtt.types.js';
+
+export const zigbee2MqttRecord = (valueArg: unknown): Record<string, unknown> | undefined => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return undefined;
+  const prototype = Object.getPrototypeOf(valueArg);
+  if (prototype !== Object.prototype && prototype !== null) return undefined;
+  if (Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string')) return undefined;
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  if (Object.values(descriptors).some((descriptorArg) => !('value' in descriptorArg) || !descriptorArg.enumerable)) return undefined;
+  return valueArg as Record<string, unknown>;
+};
+
+export const zigbee2MqttPrimitive = (valueArg: unknown): valueArg is TZigbee2MqttPrimitive =>
+  typeof valueArg === 'boolean' || typeof valueArg === 'string' && valueArg.length <= 1024 ||
+  typeof valueArg === 'number' && Number.isFinite(valueArg);
+
+export const zigbee2MqttInteger = (valueArg: unknown, defaultArg: number, maximumArg: number): number => {
+  const value = valueArg ?? defaultArg;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1 || value > maximumArg) {
+    throw new Error('Zigbee2MQTT limit must be a positive bounded integer.');
+  }
+  return value;
+};
+
+export const zigbee2MqttConfig = (configArg: IZigbee2MqttConfig): IZigbee2MqttConfig => {
+  const config = zigbee2MqttRecord(configArg);
+  const allowed = new Set(['host', 'baseTopic', 'port', 'protocol', 'username', 'password', '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.');
+  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.');
+  }
+  if (typeof config.baseTopic !== 'string' || !config.baseTopic || config.baseTopic.startsWith('$') ||
+    config.baseTopic.split('/').some((levelArg) => !levelArg) || Buffer.byteLength(config.baseTopic) > 256) {
+    throw new Error('An explicit non-empty Zigbee2MQTT base topic is required.');
+  }
+  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[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.');
+    }
+  }
+  const reconnect = config.reconnectPeriodMs ?? 1000;
+  if (typeof reconnect !== 'number' || !Number.isSafeInteger(reconnect) || reconnect < 0 || reconnect > 60000) {
+    throw new Error('Invalid Zigbee2MQTT reconnect interval.');
+  }
+  return {
+    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),
+    inventoryTimeoutMs: zigbee2MqttInteger(config.inventoryTimeoutMs, 7000, 60000),
+    reconnectPeriodMs: reconnect,
+    maxDevices: zigbee2MqttInteger(config.maxDevices, 2048, 10000),
+    maxPayloadBytes: zigbee2MqttInteger(config.maxPayloadBytes, 8388608, 16777216),
+    maxBufferedBytes: zigbee2MqttInteger(config.maxBufferedBytes, 33554432, 67108864),
+  };
+};

package/ts/integrations/zwave_js/readme.md

@@ -0,0 +1,23 @@
+# 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.
+
+```typescript
+const runtime = await new ZwaveJsIntegration().setup({
+  url: 'ws://zwave-js.local:3000',
+  expectedHomeId: 123456,
+  requestTimeoutMs: 10000,
+}, { abortSignal });
+```
+
+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.
+
+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.
+
+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 [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.
+
+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.
+
+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.

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

@@ -1,188 +1,308 @@
 import * as plugins from '../../plugins.js';
-import type { IZwaveJsConfig, IZwaveJsServerCommand, IZwaveJsServerEvent, IZwaveJsSnapshot, IZwaveJsState, IZwaveJsVersion } from './zwave_js.types.js';
+import type { IZwaveJsConfig, 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';
 
 type TEventHandler = (eventArg: IZwaveJsServerEvent) => void;
 
 interface IPendingRequest {
   resolve(valueArg: unknown): void;
   reject(errorArg: Error): void;
-  timer: ReturnType<typeof setTimeout>;
+  effect?: (valueArg: unknown) => void;
+  cleanup(): void;
 }
 
 export class ZwaveJsClient {
-  private socket?: any;
-  private started = false;
-  private version?: IZwaveJsVersion;
-  private state?: IZwaveJsState;
-  private readonly events: IZwaveJsServerEvent[] = [];
-  private readonly pendingRequests = new Map<string, IPendingRequest>();
-  private readonly eventHandlers = new Set<TEventHandler>();
-
-  constructor(private readonly config: IZwaveJsConfig) {
-    this.version = config.version;
-    this.state = config.state || { controller: config.controller, nodes: config.nodes || [] };
-  }
-
-  public async getSnapshot(): Promise<IZwaveJsSnapshot> {
-    if (this.config.url && !this.started) {
-      await this.start();
-    }
-    return {
-      ...ZwaveJsMapper.toSnapshot({ ...this.config, version: this.version, state: this.state }, Boolean(this.socket && this.socket.readyState === 1), this.events),
-      url: this.config.url,
-    };
+  #config: IZwaveJsConfig;
+  #socket?: plugins.ws.WebSocket;
+  #socketClosed?: Promise<void>;
+  #startPromise?: Promise<void>;
+  #closePromise?: Promise<void>;
+  #version?: IZwaveJsVersion;
+  #state?: IZwaveJsState;
+  #ready = false;
+  #destroyed = false;
+  #failure?: Error;
+  #greeting?: { resolve(): void; reject(errorArg: Error): void };
+  #pending = new Map<string, IPendingRequest>();
+  #handlers = new Set<TEventHandler>();
+  #events: IZwaveJsServerEvent[] = [];
+  #refreshNeeded = false;
+  #snapshotStale = false;
+  #refreshPromise?: Promise<void>;
+  #lifetimeSignal?: AbortSignal;
+  #lifetimeAbort?: () => void;
+
+  constructor(configArg: IZwaveJsConfig, lifetimeSignalArg?: AbortSignal) {
+    this.#config = validateZwaveJsConfig(configArg);
+    this.#lifetimeSignal = lifetimeSignalArg;
   }
 
-  public async start(): Promise<void> {
-    if (this.started || !this.config.url) {
-      this.started = true;
-      return;
-    }
-    const WebSocketCtor = (globalThis as typeof globalThis & { WebSocket?: new (urlArg: string) => any }).WebSocket;
-    if (!WebSocketCtor) {
-      throw new Error('Global WebSocket is not available in this runtime.');
-    }
-    const socket = new WebSocketCtor(this.config.url);
-    this.socket = socket;
-    socket.addEventListener('message', (eventArg: { data: unknown }) => this.handleMessage(eventArg.data));
-    socket.addEventListener('close', () => this.rejectAll(new Error('Z-Wave JS WebSocket closed.')));
-    await new Promise<void>((resolve, reject) => {
-      socket.addEventListener('open', () => resolve(), { once: true });
-      socket.addEventListener('error', () => reject(new Error(`Unable to connect to Z-Wave JS Server at ${this.config.url}.`)), { once: true });
-    });
-    await this.waitForVersion();
-    await this.sendCommand({ command: 'initialize', schemaVersion: this.config.schemaVersion ?? this.version?.maxSchemaVersion ?? 0, additionalUserAgentComponents: { 'smarthome.exchange': '0.1.0' } }).catch(async () => {
-      await this.sendCommand({ command: 'set_api_schema', schemaVersion: this.config.schemaVersion ?? this.version?.maxSchemaVersion ?? 0 });
-    });
-    const result = await this.sendCommand({ command: 'start_listening' });
-    if (this.isRecord(result) && this.isRecord(result.state)) {
-      this.state = result.state as IZwaveJsState;
-    }
-    this.started = true;
+  public isHealthy(): boolean {
+    return this.#ready && !this.#snapshotStale && !this.#failure && !this.#destroyed && this.#socket?.readyState === plugins.ws.WebSocket.OPEN;
+  }
+
+  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();
+    return this.withAbort(this.#startPromise, abortSignalArg);
   }
 
-  public async sendCommand(commandArg: IZwaveJsServerCommand): Promise<unknown> {
-    await this.ensureStarted();
-    if (!this.socket || this.socket.readyState !== 1) {
-      throw new Error('Z-Wave JS WebSocket is not connected.');
+  public async getSnapshot(abortSignalArg?: AbortSignal): Promise<IZwaveJsSnapshot> {
+    if (this.#destroyed) throw new Error('Z-Wave JS client is destroyed.');
+    if (abortSignalArg?.aborted) throw new Error('Z-Wave JS read was aborted.');
+    if (!this.#state) await this.start(abortSignalArg);
+    return this.snapshot();
+  }
+
+  public async sendCommand(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.');
+    const command = ZwaveJsMapper.validateCommand(this.snapshot(), commandArg);
+    const response = await this.request('node.set_value', {
+      nodeId: command.nodeId, valueId: command.valueId, value: command.value,
+    }, abortSignalArg);
+    if (!zwaveJsRecord(response) || !zwaveJsRecord(response.result) ||
+      typeof response.result.status !== 'number' || ![0, 1, 2, 3, 4, 5, 254, 255].includes(response.result.status)) {
+      const error = new Error('Malformed Z-Wave JS control result.');
+      this.fail(error);
+      throw error;
     }
-    const messageId = `shx-${plugins.crypto.randomBytes(6).toString('hex')}`;
-    const payload = { ...commandArg, messageId };
-    const promise = new Promise<unknown>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(messageId);
-        reject(new Error(`Z-Wave JS command ${commandArg.command} timed out.`));
-      }, 10000);
-      this.pendingRequests.set(messageId, { resolve, reject, timer });
-    });
-    this.socket.send(JSON.stringify(payload));
-    return promise;
+    const status = response.result.status;
+    return { status, outcome: status === 255 ? 'confirmed' : status === 1 ? 'working' : status === 254 ? 'unsupervised' : 'rejected' };
   }
 
   public onEvent(handlerArg: TEventHandler): () => void {
-    this.eventHandlers.add(handlerArg);
-    return () => this.eventHandlers.delete(handlerArg);
+    if (this.#destroyed) throw new Error('Z-Wave JS client is destroyed.');
+    this.#handlers.add(handlerArg);
+    return () => { this.#handlers.delete(handlerArg); };
   }
 
-  public async destroy(): Promise<void> {
-    this.rejectAll(new Error('Z-Wave JS client destroyed.'));
-    if (this.socket?.readyState === 1) {
-      this.socket.close();
+  public destroy(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#destroyed = true;
+      this.fail(new Error('Z-Wave JS client is destroyed.'));
+      this.#handlers.clear();
+      this.#closePromise = this.closeOwnedResources();
     }
-    this.socket = undefined;
-    this.started = false;
-    this.eventHandlers.clear();
+    return this.#closePromise;
   }
 
-  private async ensureStarted(): Promise<void> {
-    if (!this.started) {
-      await this.start();
+  private async connect(): Promise<void> {
+    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 });
+    }
+    try {
+      const socket = new plugins.ws.WebSocket(this.#config.url, {
+        headers: this.#config.authorization ? { Authorization: this.#config.authorization } : undefined,
+        ca: this.#config.ca, rejectUnauthorized: true, followRedirects: false,
+        handshakeTimeout: this.#config.requestTimeoutMs,
+        maxPayload: 2 * 1024 * 1024, maxFragments: 128, maxBufferedChunks: 128, perMessageDeflate: false,
+      });
+      this.#socket = socket;
+      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.')));
+      socket.on('message', (dataArg, binaryArg) => this.receive(dataArg, binaryArg));
+      const outcome = await greetingOutcome;
+      if (!outcome.accepted) throw outcome.error;
+      await this.request('initialize', { schemaVersion: zwaveJsSchemaVersion });
+      await this.requestState();
+      if (this.#failure || this.#destroyed) throw this.#failure ?? new Error('Z-Wave JS client is destroyed.');
+      this.#ready = true;
+    } catch (errorArg) {
+      this.fail(errorArg instanceof Error ? errorArg : new Error('Z-Wave JS setup failed.'));
+      throw this.#failure;
+    } finally {
+      clearTimeout(deadline);
+      this.#greeting = undefined;
     }
   }
 
-  private async waitForVersion(): Promise<void> {
-    if (this.version) {
-      return;
+  private request(commandArg: string, fieldsArg: Record<string, unknown> = {}, abortSignalArg?: AbortSignal,
+    effectArg?: (valueArg: unknown) => void): Promise<unknown> {
+    const socket = this.#socket;
+    if (this.#failure || this.#destroyed || socket?.readyState !== plugins.ws.WebSocket.OPEN) {
+      return Promise.reject(this.#failure ?? new Error('Z-Wave JS WebSocket is not connected.'));
     }
-    await new Promise<void>((resolve) => setTimeout(resolve, 100));
+    if (abortSignalArg?.aborted) return Promise.reject(new Error('Z-Wave JS command was aborted before dispatch.'));
+    if (this.#pending.size >= 64) return Promise.reject(new Error('Z-Wave JS pending command limit reached.'));
+    const messageId = plugins.crypto.randomUUID();
+    return new Promise<unknown>((resolveArg, rejectArg) => {
+      const abort = () => {
+        const pending = this.#pending.get(messageId);
+        if (!pending) return;
+        this.#pending.delete(messageId);
+        pending.cleanup();
+        rejectArg(new Error('Z-Wave JS command was aborted; execution may be indeterminate.'));
+      };
+      const timer = setTimeout(() => this.fail(new Error('Z-Wave JS command deadline expired; execution may be indeterminate.')),
+        this.#config.requestTimeoutMs);
+      const cleanup = () => { clearTimeout(timer); abortSignalArg?.removeEventListener('abort', abort); };
+      this.#pending.set(messageId, { resolve: resolveArg, reject: rejectArg, cleanup, effect: effectArg });
+      abortSignalArg?.addEventListener('abort', abort, { once: true });
+      socket.send(JSON.stringify({ command: commandArg, ...fieldsArg, messageId }), (errorArg) => {
+        if (errorArg) this.fail(new Error('Z-Wave JS command transport failed; execution may be indeterminate.'));
+      });
+    });
   }
 
-  private handleMessage(dataArg: unknown): void {
-    const text = typeof dataArg === 'string' ? dataArg : dataArg instanceof Buffer ? dataArg.toString('utf8') : String(dataArg);
-    const message = JSON.parse(text) as Record<string, unknown>;
-    if (message.type === 'version') {
-      this.version = message as IZwaveJsVersion;
-      return;
-    }
-    if (message.type === 'result') {
-      this.handleResult(message);
-      return;
-    }
-    if (message.type === 'event' && this.isRecord(message.event)) {
-      const event = message.event as IZwaveJsServerEvent;
-      this.events.push(event);
-      this.applyEvent(event);
-      for (const handler of this.eventHandlers) {
-        handler(event);
+  private requestState(): Promise<unknown> {
+    return this.request('start_listening', {}, undefined, (resultArg) => {
+      if (!zwaveJsRecord(resultArg)) throw new Error('Malformed Z-Wave JS state result.');
+      this.#state = parseZwaveJsState(resultArg.state, this.#config.expectedHomeId);
+      this.#snapshotStale = false;
+    });
+  }
+
+  private receive(dataArg: plugins.ws.RawData, binaryArg: boolean): void {
+    if (this.#failure || this.#destroyed) return;
+    try {
+      if (binaryArg) throw new Error('Z-Wave JS protocol requires JSON text frames.');
+      const buffer = Array.isArray(dataArg) ? Buffer.concat(dataArg) :
+        dataArg instanceof ArrayBuffer ? Buffer.from(dataArg) : dataArg;
+      let message: unknown;
+      try { message = JSON.parse(buffer.toString('utf8')); }
+      catch { throw new Error('Malformed Z-Wave JS JSON text frame.'); }
+      validateZwaveJsJson(message);
+      if (!zwaveJsRecord(message)) throw new Error('Malformed Z-Wave JS message.');
+      if (message.type === 'version') {
+        if (this.#version) throw new Error('Duplicate Z-Wave JS greeting.');
+        this.#version = parseZwaveJsVersion(message, this.#config.expectedHomeId);
+        this.#greeting?.resolve();
+      } else if (message.type === 'result') {
+        this.receiveResult(message);
+      } else if (message.type === 'event' && zwaveJsRecord(message.event)) {
+        this.receiveEvent(message.event);
+      } else {
+        throw new Error('Unsupported Z-Wave JS message envelope.');
       }
+    } catch (errorArg) {
+      this.fail(errorArg instanceof Error ? errorArg : new Error('Malformed Z-Wave JS message.'));
     }
   }
 
-  private handleResult(messageArg: Record<string, unknown>): void {
-    const messageId = typeof messageArg.messageId === 'string' ? messageArg.messageId : undefined;
-    if (!messageId) {
-      return;
+  private receiveResult(messageArg: Record<string, unknown>): void {
+    if (typeof messageArg.messageId !== 'string' || typeof messageArg.success !== 'boolean') {
+      throw new Error('Malformed Z-Wave JS result envelope.');
     }
-    const pending = this.pendingRequests.get(messageId);
-    if (!pending) {
+    const pending = this.#pending.get(messageArg.messageId);
+    if (!pending) return;
+    this.#pending.delete(messageArg.messageId);
+    pending.cleanup();
+    if (!messageArg.success) {
+      pending.reject(new Error('Z-Wave JS server rejected the command.'));
       return;
     }
-    clearTimeout(pending.timer);
-    this.pendingRequests.delete(messageId);
-    if (messageArg.success === false) {
-      pending.reject(new Error(`Z-Wave JS command failed: ${JSON.stringify(messageArg.error || messageArg)}`));
-      return;
+    try {
+      pending.effect?.(messageArg.result);
+      pending.resolve(messageArg.result);
+    } catch (errorArg) {
+      const error = errorArg instanceof Error ? errorArg : new Error('Malformed Z-Wave JS command result.');
+      pending.reject(error);
+      throw error;
     }
-    pending.resolve(messageArg.result);
   }
 
-  private applyEvent(eventArg: IZwaveJsServerEvent): void {
-    if (eventArg.source !== 'node' || typeof eventArg.nodeId !== 'number') {
-      return;
+  private receiveEvent(eventArg: Record<string, unknown>): void {
+    if (typeof eventArg.source !== 'string' || typeof eventArg.event !== 'string' || !this.#state) {
+      throw new Error('Malformed or premature Z-Wave JS event.');
     }
-    const nodes = this.state?.nodes || [];
-    const node = nodes.find((nodeArg) => nodeArg.nodeId === eventArg.nodeId);
-    if (!node) {
-      return;
-    }
-    if (eventArg.event === 'value updated' && eventArg.valueId) {
-      const value = ZwaveJsMapper.nodeValues(node).find((valueArg) => this.valueIdMatches(valueArg, eventArg.valueId!));
-      if (value) {
-        value.value = eventArg.newValue ?? eventArg.value;
+    if (eventArg.source === 'node' && typeof eventArg.nodeId === 'number') {
+      const node = this.#state.nodes.find((nodeArg) => nodeArg.nodeId === eventArg.nodeId);
+      if (!node) { this.scheduleRefresh(); return; }
+      if (['alive', 'dead', 'sleep', 'wake up'].includes(eventArg.event)) {
+        node.status = eventArg.event === 'sleep' ? 'asleep' : eventArg.event === 'wake up' ? 'awake' : eventArg.event;
+        this.emit({ source: 'node', event: eventArg.event, nodeId: node.nodeId });
+      } else if (eventArg.event === 'value updated' && zwaveJsRecord(eventArg.args)) {
+        if (this.#snapshotStale) return;
+        const id = parseZwaveJsValueId(eventArg.args);
+        const owned = Array.isArray(node.values) ? node.values.find((valueArg) => zwaveJsValueKey(valueArg) === zwaveJsValueKey(id)) : undefined;
+        if (!owned) { this.scheduleRefresh(); return; }
+        if (!Object.hasOwn(eventArg.args, 'newValue')) throw new Error('Malformed Z-Wave JS value update.');
+        if (owned.metadata) validateZwaveJsValueData(owned.metadata, eventArg.args.newValue);
+        owned.value = eventArg.args.newValue;
+        this.emit({ source: 'node', event: 'value updated', nodeId: node.nodeId, valueId: id, newValue: eventArg.args.newValue });
+      } else if (['ready', 'value added', 'value removed', 'metadata updated'].includes(eventArg.event)) {
+        this.scheduleRefresh();
       }
-    }
-    if (eventArg.event === 'node status' && typeof eventArg.status === 'string') {
-      node.status = eventArg.status;
+    } else if (eventArg.source === 'controller' && ['node added', 'node removed'].includes(eventArg.event)) {
+      this.scheduleRefresh();
     }
   }
 
-  private valueIdMatches(valueArg: ReturnType<typeof ZwaveJsMapper.nodeValues>[number], valueIdArg: NonNullable<IZwaveJsServerEvent['valueId']>): boolean {
-    return (valueArg.commandClass || 0) === valueIdArg.commandClass
-      && (valueArg.endpoint || 0) === (valueIdArg.endpoint || 0)
-      && String(valueArg.property ?? valueArg.propertyName ?? '') === String(valueIdArg.property)
-      && String(valueArg.propertyKey ?? '') === String(valueIdArg.propertyKey ?? '');
+  private scheduleRefresh(): void {
+    this.#refreshNeeded = true;
+    this.#snapshotStale = true;
+    if (this.#refreshPromise) return;
+    this.#refreshPromise = (async () => {
+      try {
+        while (this.#refreshNeeded && !this.#failure && !this.#destroyed) {
+          this.#refreshNeeded = false;
+          await this.requestState();
+          this.emit({ source: 'controller', event: 'state refreshed' });
+        }
+      } catch (errorArg) {
+        this.fail(errorArg instanceof Error ? errorArg : new Error('Z-Wave JS state reconciliation failed.'));
+      } finally { this.#refreshPromise = undefined; }
+    })();
   }
 
-  private rejectAll(errorArg: Error): void {
-    for (const [messageId, pending] of this.pendingRequests) {
-      clearTimeout(pending.timer);
-      pending.reject(errorArg);
-      this.pendingRequests.delete(messageId);
+  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.'));
+      }
     }
   }
 
-  private isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  private snapshot(): IZwaveJsSnapshot {
+    return structuredClone({
+      version: this.#version, controller: this.#state?.controller, nodes: this.#state?.nodes ?? [],
+      connected: this.isHealthy(), events: this.#events,
+    });
+  }
+
+  private fail(errorArg: Error): void {
+    if (this.#failure) return;
+    this.#failure = errorArg;
+    this.#ready = false;
+    if (this.#lifetimeAbort) this.#lifetimeSignal?.removeEventListener('abort', this.#lifetimeAbort);
+    this.#greeting?.reject(errorArg);
+    for (const pending of this.#pending.values()) { pending.cleanup(); pending.reject(errorArg); }
+    this.#pending.clear();
+    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));
+    this.#socket?.removeAllListeners();
+    this.#socket = undefined;
+  }
+
+  private withAbort(promiseArg: Promise<void>, abortSignalArg?: AbortSignal): Promise<void> {
+    if (!abortSignalArg) return promiseArg;
+    return new Promise<void>((resolveArg, rejectArg) => {
+      const abort = () => {
+        const error = new Error('Z-Wave JS setup was aborted.');
+        this.fail(error);
+        rejectArg(error);
+      };
+      abortSignalArg.addEventListener('abort', abort, { once: true });
+      promiseArg.then(resolveArg, rejectArg).finally(() => abortSignalArg.removeEventListener('abort', abort));
+    });
   }
 }

package/ts/integrations/zwave_js/zwave_js.classes.configflow.ts

@@ -1,40 +1,38 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { ZwaveJsClient } from './zwave_js.classes.client.js';
 import type { IZwaveJsConfig } from './zwave_js.types.js';
+import { validateZwaveJsConfig } from './zwave_js.validation.js';
 
 export class ZwaveJsConfigFlow implements IConfigFlow<IZwaveJsConfig> {
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IZwaveJsConfig>> {
+    void candidateArg;
     void contextArg;
     return {
-      kind: 'form',
-      title: 'Connect Z-Wave JS',
-      description: 'Configure the local Z-Wave JS Server WebSocket endpoint.',
+      kind: 'form', title: 'Connect Z-Wave JS',
+      description: 'Enter the explicit server endpoint and network home ID shown by Z-Wave JS. Proxy credentials require verified TLS.',
       fields: [
-        { name: 'url', label: 'Server URL', type: 'text', required: true },
-        { name: 'schemaVersion', label: 'API schema version', type: 'number' },
+        { name: 'url', label: 'Server WebSocket URL', type: 'text', required: true },
+        { name: 'expectedHomeId', label: 'Network home ID (decimal)', type: 'number', required: true },
+        { name: 'authorization', label: 'TLS proxy Authorization header', type: 'password' },
+        { name: 'ca', label: 'Additional TLS CA certificate (PEM)', type: 'text' },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'Z-Wave JS configured',
-        config: {
-          url: this.stringValue(valuesArg.url) || this.urlFromCandidate(candidateArg),
-          schemaVersion: this.numberValue(valuesArg.schemaVersion),
-        },
-      }),
+      submit: async (valuesArg) => {
+        let client: ZwaveJsClient | undefined;
+        try {
+          const config = validateZwaveJsConfig({
+            url: typeof valuesArg.url === 'string' ? valuesArg.url : '',
+            expectedHomeId: typeof valuesArg.expectedHomeId === 'number' ? valuesArg.expectedHomeId : 0,
+            authorization: typeof valuesArg.authorization === 'string' && valuesArg.authorization ? valuesArg.authorization : undefined,
+            ca: typeof valuesArg.ca === 'string' && valuesArg.ca ? valuesArg.ca : undefined,
+          });
+          client = new ZwaveJsClient(config);
+          await client.start();
+          return { kind: 'done', title: 'Verified Z-Wave JS network', config };
+        } catch {
+          return { kind: 'error', title: 'Z-Wave JS verification failed',
+            description: 'Check the endpoint, network home ID, supported schema and TLS proxy admission.' };
+        } finally { await client?.destroy(); }
+      },
     };
   }
-
-  private urlFromCandidate(candidateArg: IDiscoveryCandidate): string {
-    if (typeof candidateArg.metadata?.url === 'string') {
-      return candidateArg.metadata.url;
-    }
-    return candidateArg.host ? `ws://${candidateArg.host}:${candidateArg.port || 3000}` : 'ws://localhost:3000';
-  }
-
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : undefined;
-  }
 }