@smarthome.exchange/integrations 1.0.0 → 3.0.0

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

@@ -1,38 +1,62 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import { ZwaveJsClient } from './zwave_js.classes.client.js';
-import type { IZwaveJsConfig } from './zwave_js.types.js';
-import { validateZwaveJsConfig } from './zwave_js.validation.js';
+import type { IZwaveJsConfig, IZwaveJsIntegrationOptions } from './zwave_js.types.js';
+import { captureZwaveJsData, normalizeZwaveJsOptions, validateZwaveJsConfig } from './zwave_js.validation.js';
 
 export class ZwaveJsConfigFlow implements IConfigFlow<IZwaveJsConfig> {
+  readonly #options: Readonly<IZwaveJsIntegrationOptions>;
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(optionsArg: IZwaveJsIntegrationOptions = {}, scopeArg?: NativeIntegrationScope) {
+    this.#options = normalizeZwaveJsOptions(optionsArg);
+    this.#scope = scopeArg ?? new NativeIntegrationOwner('zwave_js', {
+      homeId: this.#options.homeId, capacity: this.#options.capacity,
+    }).createFlowScope();
+  }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IZwaveJsConfig>> {
-    void candidateArg;
-    void contextArg;
-    return {
-      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 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) => {
-        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(); }
-      },
-    };
+    try {
+      const candidate = captureZwaveJsData(candidateArg);
+      if (candidate.integrationDomain !== undefined && candidate.integrationDomain !== 'zwave_js') throw new Error('Foreign Z-Wave JS candidate.');
+      const admitted = this.#scope.admit(contextArg);
+      return {
+        kind: 'form', title: 'Connect selected Z-Wave JS server',
+        description: 'Select the server and its numeric Z-Wave network ID for the host-selected home. Optional proxy credentials use an explicit reference source and verified TLS. Controls default to read-only.',
+        fields: [
+          { name: 'url', label: 'Server WebSocket URL', type: 'text', required: true },
+          { name: 'expectedHomeId', label: 'Z-Wave network home ID (decimal)', type: 'number', required: true },
+          { name: 'allowControls', label: 'Authorize supported absolute Binary/Multilevel Switch writes', type: 'boolean' },
+          { name: 'credentialRef', label: 'Optional proxy credential reference', type: 'text' },
+          { name: 'credentialSource', label: 'Explicit credential source', type: 'select', options: [
+            { label: 'External provider', value: 'provider' }, { label: 'Borrowed encrypted config store', value: 'config-store' },
+          ] },
+          { name: 'ca', label: 'Additional TLS CA certificate (PEM)', type: 'text' },
+        ],
+        submit: async (inputArg) => {
+          try {
+            const values = captureZwaveJsData(inputArg, ['homeId', 'url', 'expectedHomeId', 'allowControls', 'credentialRef', 'credentialSource', 'ca', 'requestTimeoutMs']);
+            if (values.homeId !== undefined && values.homeId !== admitted.homeId) throw new Error('Submitted home conflicts with selected host home.');
+            const config = validateZwaveJsConfig({ ...values, homeId: admitted.homeId });
+            return await this.#scope.run(admitted, config.homeId, async (lease) => {
+              const client = new ZwaveJsClient(config, { ...lease.context, abortSignal: lease.signal }, this.#options);
+              lease.own(() => client.retryCleanup());
+              await client.start();
+              lease.assertOpen();
+              return { kind: 'done', title: 'Verified selected Z-Wave JS network', config };
+            });
+          } catch (errorArg) {
+            if (errorArg instanceof AggregateError) throw errorArg;
+            return { kind: 'error', title: 'Z-Wave JS verification failed',
+              description: 'Check host home, selected endpoint, network ID, schema, TLS and explicit credential source.' };
+          }
+        },
+      };
+    } catch {
+      return { kind: 'error', title: 'Z-Wave JS admission failed', description: 'Supply the independent host-selected home and matching optional store.' };
+    }
   }
+
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 }

package/ts/integrations/zwave_js/zwave_js.classes.integration.ts

@@ -1,69 +1,83 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { ZwaveJsClient } from './zwave_js.classes.client.js';
 import { ZwaveJsConfigFlow } from './zwave_js.classes.configflow.js';
 import { createZwaveJsDiscoveryDescriptor } from './zwave_js.discovery.js';
 import { ZwaveJsMapper } from './zwave_js.mapper.js';
-import type { IZwaveJsConfig, IZwaveJsServerCommand, IZwaveJsWriteResult } from './zwave_js.types.js';
+import type { IZwaveJsConfig, IZwaveJsIntegrationOptions, IZwaveJsServerCommand, IZwaveJsWriteResult } from './zwave_js.types.js';
+import { normalizeZwaveJsOptions, validateZwaveJsConfig } from './zwave_js.validation.js';
 
 export class ZwaveJsIntegration extends BaseIntegration<IZwaveJsConfig> {
   public readonly domain = 'zwave_js';
   public readonly displayName = 'Z-Wave';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createZwaveJsDiscoveryDescriptor();
-  public readonly configFlow = new ZwaveJsConfigFlow();
+  public readonly configFlow: ZwaveJsConfigFlow;
   public readonly metadata = {
     source: 'zwave-js/zwave-js-server', upstreamPath: 'src/lib', upstreamDomain: 'zwave_js',
     integrationType: 'hub', iotClass: 'local_push', qualityScale: 'unknown',
   };
-  #clients = new Set<ZwaveJsClient>();
-  #destroyed = false;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: Readonly<IZwaveJsIntegrationOptions>;
 
-  public async setup(configArg: IZwaveJsConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.#destroyed) throw new Error('Z-Wave JS integration is destroyed.');
-    const client = new ZwaveJsClient(configArg, contextArg.abortSignal);
-    this.#clients.add(client);
-    try {
-      await client.start();
-      if (this.#destroyed) throw new Error('Z-Wave JS integration is destroyed.');
-      return new ZwaveJsRuntime(client, () => { this.#clients.delete(client); });
-    } catch (errorArg) {
-      await client.destroy();
-      this.#clients.delete(client);
-      throw errorArg;
-    }
+  constructor(optionsArg: IZwaveJsIntegrationOptions = {}) {
+    super();
+    this.#options = normalizeZwaveJsOptions(optionsArg);
+    this.#owner = new NativeIntegrationOwner('zwave_js', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.configFlow = new ZwaveJsConfigFlow(this.#options, this.#owner.createFlowScope());
   }
 
-  public async destroy(): Promise<void> {
-    this.#destroyed = true;
-    await Promise.all([...this.#clients].map((clientArg) => clientArg.destroy()));
-    this.#clients.clear();
+  public setup(configArg: IZwaveJsConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const config = validateZwaveJsConfig(configArg);
+      return this.#owner.runSetup(contextArg, config.homeId, async (lease) => {
+        const client = new ZwaveJsClient(config, { ...lease.context, abortSignal: lease.signal }, this.#options);
+        let runtime: ZwaveJsRuntime | undefined;
+        lease.own(async () => {
+          const results = await Promise.allSettled([Promise.resolve().then(() => client.retryCleanup()),
+            ...(runtime ? [Promise.resolve().then(() => runtime!.closeSubscriptions())] : [])]);
+          const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+          if (failures.length) throw new AggregateError(failures.map((result) => result.reason as unknown), 'Z-Wave JS owned cleanup failed.');
+        });
+        await client.start();
+        lease.assertOpen();
+        runtime = new ZwaveJsRuntime(client, lease);
+        lease.promoteToRuntime();
+        return runtime;
+      });
+    } catch (errorArg) { return Promise.reject(errorArg); }
   }
+
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantZwaveJsIntegration extends ZwaveJsIntegration {}
 
 class ZwaveJsRuntime implements IIntegrationRuntime {
   public readonly domain = 'zwave_js';
-  #subscriptions = new Set<() => void>();
+  #subscriptions = new Set<() => Promise<void>>();
   #destroyPromise?: Promise<void>;
 
-  constructor(private readonly client: ZwaveJsClient, private readonly released: () => void) {}
+  constructor(private readonly client: ZwaveJsClient, private readonly lease: INativeSetupLease) {}
 
   public isHealthy(): boolean { return this.client.isHealthy(); }
 
   public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.lease.assertOpen();
     return ZwaveJsMapper.toDevices(await this.client.getSnapshot(abortSignalArg));
   }
 
-  public async entities(): Promise<IIntegrationEntity[]> { return ZwaveJsMapper.toEntities(await this.client.getSnapshot()); }
+  public async entities(): Promise<IIntegrationEntity[]> { this.lease.assertOpen(); return ZwaveJsMapper.toEntities(await this.client.getSnapshot()); }
 
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.lease.assertOpen();
     if (abortSignalArg?.aborted) throw new Error('Z-Wave JS subscription was aborted.');
     const snapshot = await this.client.getSnapshot(abortSignalArg);
     const unsubscribe = this.client.onEvent((eventArg) => {
-      handlerArg({
+      return handlerArg({
         type: eventArg.source === 'connection' || ['alive', 'dead', 'sleep', 'wake up'].includes(eventArg.event) ?
           'availability_changed' : 'state_changed',
         integrationDomain: this.domain,
@@ -71,36 +85,44 @@ class ZwaveJsRuntime implements IIntegrationRuntime {
         data: eventArg, timestamp: Date.now(),
       });
     });
-    const release = () => {
-      unsubscribe();
-      abortSignalArg?.removeEventListener('abort', release);
+    const abort = () => { void release().catch(() => undefined); };
+    const release = async () => {
+      abortSignalArg?.removeEventListener('abort', abort);
+      await unsubscribe();
       this.#subscriptions.delete(release);
     };
     this.#subscriptions.add(release);
-    abortSignalArg?.addEventListener('abort', release, { once: true });
-    if (abortSignalArg?.aborted) release();
-    return async () => { release(); };
+    abortSignalArg?.addEventListener('abort', abort, { once: true });
+    if (abortSignalArg?.aborted) await release();
+    this.lease.assertOpen();
+    return release;
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    this.lease.assertOpen();
     const command = ZwaveJsMapper.commandForService(await this.client.getSnapshot(), requestArg);
     if (!command) return { success: false, error: 'Unsupported, missing or ambiguous Z-Wave JS control target.' };
     return this.execute(command);
   }
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    this.lease.assertOpen();
     const command = ZwaveJsMapper.commandForFeature(await this.client.getSnapshot(abortSignalArg), requestArg);
     return this.execute(command, abortSignalArg);
   }
 
   public destroy(): Promise<void> {
-    if (!this.#destroyPromise) {
-      for (const release of this.#subscriptions) release();
-      this.#destroyPromise = this.client.destroy().finally(() => this.released());
-    }
+    if (!this.#destroyPromise) this.#destroyPromise = this.lease.close();
     return this.#destroyPromise;
   }
 
+  public async closeSubscriptions(): Promise<void> {
+    const results = await Promise.allSettled([...this.#subscriptions].map((release) => Promise.resolve().then(release)));
+    this.#subscriptions.clear(); // Callback work/failures remain owned by the client ledger.
+    const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map((result) => result.reason as unknown), 'Z-Wave JS subscription cleanup failed.');
+  }
+
   private async execute(commandArg: IZwaveJsServerCommand, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
     const data: IZwaveJsWriteResult = await this.client.sendCommand(commandArg, abortSignalArg);
     return { success: data.outcome === 'confirmed', data,

package/ts/integrations/zwave_js/zwave_js.discovery.ts

@@ -1,7 +1,7 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { IZwaveJsManualEntry, IZwaveJsMdnsRecord, IZwaveJsUsbRecord } from './zwave_js.types.js';
-import { validateZwaveJsConfig, zwaveJsRecord } from './zwave_js.validation.js';
+import { validateZwaveJsEndpoint, zwaveJsRecord } from './zwave_js.validation.js';
 
 const knownUsbIds = new Set(['0658:0200', '10c4:8a2a', '303a:4001', '10c4:ea60']);
 
@@ -133,7 +133,7 @@ export const createZwaveJsDiscoveryDescriptor = (): DiscoveryDescriptor => {
 };
 
 const safeUrl = (urlArg: string): string | undefined => {
-  try { return validateZwaveJsConfig({ url: urlArg, expectedHomeId: 1 }).url.replace(/\/$/, ''); }
+  try { return validateZwaveJsEndpoint(urlArg).replace(/\/$/, ''); }
   catch { return undefined; }
 };
 

package/ts/integrations/zwave_js/zwave_js.mapper.ts

@@ -1,7 +1,7 @@
 import * as plugins from '../../plugins.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
 import type { IZwaveJsNode, IZwaveJsServerCommand, IZwaveJsSnapshot, IZwaveJsValue, IZwaveJsValueId, TZwaveJsControlValue } from './zwave_js.types.js';
-import { parseZwaveJsValueId, zwaveJsRecord, zwaveJsValueKey } from './zwave_js.validation.js';
+import { captureZwaveJsData, parseZwaveJsValueId, zwaveJsRecord, zwaveJsValueKey } from './zwave_js.validation.js';
 
 interface IControlTarget { node: IZwaveJsNode; value: IZwaveJsValue }
 
@@ -9,14 +9,16 @@ export class ZwaveJsMapper {
   /** Pure mapping helper; runtime setup always obtains its state from the server. */
   public static toSnapshot(snapshotArg: Partial<IZwaveJsSnapshot>, connectedArg = false,
     eventsArg: IZwaveJsSnapshot['events'] = []): IZwaveJsSnapshot {
-    return structuredClone({ ...snapshotArg, nodes: snapshotArg.nodes ?? [], events: eventsArg, connected: connectedArg });
+    if (typeof snapshotArg.homeId !== 'string' || !snapshotArg.homeId) throw new Error('Z-Wave JS snapshot requires its admitted SHX home.');
+    return structuredClone({ ...snapshotArg, homeId: snapshotArg.homeId, allowControls: snapshotArg.allowControls === true,
+      nodes: snapshotArg.nodes ?? [], events: eventsArg, connected: connectedArg });
   }
 
   public static toDevices(snapshotArg: IZwaveJsSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
     const updatedAt = new Date().toISOString();
     const devices: plugins.shxInterfaces.data.IDeviceDefinition[] = [{
-      id: this.controllerDeviceId(snapshotArg), integrationDomain: 'zwave_js', name: 'Z-Wave controller',
-      protocol: 'zwave', manufacturer: 'Z-Wave JS', model: 'Controller', online: snapshotArg.connected,
+      id: this.controllerDeviceId(snapshotArg), integrationDomain: 'zwave_js', name: 'Z-Wave JS server connection',
+      protocol: 'zwave', online: snapshotArg.connected,
       features: [
         { id: 'connection', capability: 'sensor', name: 'Connection', readable: true, writable: false },
         { id: 'node_count', capability: 'sensor', name: 'Node count', readable: true, writable: false },
@@ -25,7 +27,8 @@ export class ZwaveJsMapper {
         { featureId: 'connection', value: snapshotArg.connected ? 'connected' : 'disconnected', updatedAt },
         { featureId: 'node_count', value: snapshotArg.nodes.length, updatedAt },
       ],
-      metadata: { homeId: this.homeId(snapshotArg), serverVersion: snapshotArg.version?.serverVersion, driverVersion: snapshotArg.version?.driverVersion },
+      metadata: { homeId: snapshotArg.homeId, zwaveHomeId: this.homeId(snapshotArg), ownNodeId: snapshotArg.controller?.ownNodeId,
+        serverVersion: snapshotArg.version?.serverVersion, driverVersion: snapshotArg.version?.driverVersion, adapterObservation: true },
     }];
     for (const node of snapshotArg.nodes) {
       const values = this.nodeValues(node).filter((valueArg) => valueArg.metadata?.secret !== true);
@@ -40,7 +43,7 @@ export class ZwaveJsMapper {
             id: this.featureId(valueArg), capability: this.platformForValue(valueArg) === 'light' ? 'light' :
               this.platformForValue(valueArg) === 'switch' ? 'switch' : 'sensor',
             name: this.valueLabel(valueArg), readable: valueArg.metadata?.readable === true,
-            writable: this.valueWritable(valueArg), unit: valueArg.metadata?.unit,
+            writable: snapshotArg.allowControls && this.nodeAvailable(snapshotArg, node) && this.valueWritable(valueArg), unit: valueArg.metadata?.unit,
           })),
         ],
         state: [
@@ -49,7 +52,7 @@ export class ZwaveJsMapper {
             featureId: this.featureId(valueArg), value: this.stateValue(valueArg.value), updatedAt,
           })),
         ],
-        metadata: { homeId: this.homeId(snapshotArg), nodeId: node.nodeId, manufacturerId: node.manufacturerId,
+        metadata: { homeId: snapshotArg.homeId, zwaveHomeId: this.homeId(snapshotArg), nodeId: node.nodeId, manufacturerId: node.manufacturerId,
           productId: node.productId, productType: node.productType, firmwareVersion: node.firmwareVersion },
       });
     }
@@ -66,14 +69,24 @@ export class ZwaveJsMapper {
           id: `${platform}.${identity}`, uniqueId: identity, integrationDomain: 'zwave_js',
           deviceId: this.nodeDeviceId(snapshotArg, nodeArg.nodeId), platform, name: this.valueLabel(valueArg),
           state: valueArg.metadata?.readable === true ? this.entityState(valueArg, platform) : 'unknown',
-          attributes: { homeId: this.homeId(snapshotArg), nodeId: nodeArg.nodeId, valueId: this.valueId(valueArg),
-            featureId: this.featureId(valueArg), unit: valueArg.metadata?.unit, writable: this.valueWritable(valueArg) },
+          attributes: { homeId: snapshotArg.homeId, zwaveHomeId: this.homeId(snapshotArg), nodeId: nodeArg.nodeId, valueId: this.valueId(valueArg),
+            featureId: this.featureId(valueArg), unit: valueArg.metadata?.unit,
+            writable: snapshotArg.allowControls && this.nodeAvailable(snapshotArg, nodeArg) && this.valueWritable(valueArg) },
           available: this.nodeAvailable(snapshotArg, nodeArg),
         };
       }));
   }
 
   public static commandForService(snapshotArg: IZwaveJsSnapshot, requestArg: IServiceCallRequest): IZwaveJsServerCommand | undefined {
+    const data = captureZwaveJsData(requestArg, ['domain', 'service', 'target', 'data']);
+    const targetData = captureZwaveJsData(data.target, ['entityId', 'deviceId']);
+    const serviceData = data.data === undefined ? undefined : captureZwaveJsData(data.data, ['featureId', 'value']);
+    if (typeof data.domain !== 'string' || typeof data.service !== 'string' ||
+      targetData.deviceId !== undefined && typeof targetData.deviceId !== 'string' ||
+      targetData.entityId !== undefined && typeof targetData.entityId !== 'string' ||
+      serviceData?.featureId !== undefined && typeof serviceData.featureId !== 'string' ||
+      data.service !== 'set_value' && serviceData?.value !== undefined) return undefined;
+    requestArg = { domain: data.domain, service: data.service, target: targetData, data: serviceData } as IServiceCallRequest;
     if (!['switch', 'light', 'zwave_js'].includes(requestArg.domain) ||
       !['turn_on', 'turn_off', 'set_value'].includes(requestArg.service)) return undefined;
     const target = this.findTargetValue(snapshotArg, requestArg);
@@ -86,25 +99,26 @@ export class ZwaveJsMapper {
   }
 
   public static commandForFeature(snapshotArg: IZwaveJsSnapshot, requestArg: IDeviceFeatureWriteRequest): IZwaveJsServerCommand {
-    const node = snapshotArg.nodes.find((nodeArg) => this.nodeDeviceId(snapshotArg, nodeArg.nodeId) === requestArg.device.id);
-    const value = node && this.nodeValues(node).find((valueArg) => this.featureId(valueArg) === requestArg.feature.id);
+    const request = captureZwaveJsData(requestArg, ['device', 'feature', 'value']);
+    const device = captureZwaveJsData(request.device);
+    const feature = captureZwaveJsData(request.feature);
+    if (device.integrationDomain !== 'zwave_js') throw new Error('Z-Wave JS device target belongs to another integration.');
+    const node = snapshotArg.nodes.find((nodeArg) => this.nodeDeviceId(snapshotArg, nodeArg.nodeId) === device.id);
+    const value = node && this.nodeValues(node).find((valueArg) => this.featureId(valueArg) === feature.id);
     if (!node || !value) throw new Error('Z-Wave JS feature target is not in the verified network.');
-    return this.createCommand(snapshotArg, { node, value }, requestArg.value);
+    return this.createCommand(snapshotArg, { node, value }, request.value);
   }
 
   public static validateCommand(snapshotArg: IZwaveJsSnapshot, commandArg: IZwaveJsServerCommand): IZwaveJsServerCommand {
-    if (!zwaveJsRecord(commandArg) || commandArg.command !== 'node.set_value' ||
-      Object.keys(commandArg).some((keyArg) => !['command', 'nodeId', 'valueId', 'value'].includes(keyArg))) {
+    const command = captureZwaveJsData(commandArg, ['command', 'nodeId', 'valueId', 'value']);
+    if (command.command !== 'node.set_value') {
       throw new Error('Unsupported Z-Wave JS command.');
     }
-    const id = parseZwaveJsValueId(commandArg.valueId);
-    if (Object.keys(commandArg.valueId).some((keyArg) => !['commandClass', 'endpoint', 'property', 'propertyKey'].includes(keyArg))) {
-      throw new Error('Invalid Z-Wave JS control identity fields.');
-    }
-    const node = snapshotArg.nodes.find((nodeArg) => nodeArg.nodeId === commandArg.nodeId);
+    const id = parseZwaveJsValueId(captureZwaveJsData(command.valueId, ['commandClass', 'endpoint', 'property', 'propertyKey']));
+    const node = snapshotArg.nodes.find((nodeArg) => nodeArg.nodeId === command.nodeId);
     const value = node && this.nodeValues(node).find((valueArg) => zwaveJsValueKey(valueArg) === zwaveJsValueKey(id));
     if (!node || !value) throw new Error('Z-Wave JS command target is not in the verified network.');
-    return this.createCommand(snapshotArg, { node, value }, commandArg.value);
+    return this.createCommand(snapshotArg, { node, value }, command.value);
   }
 
   public static valueId(valueArg: IZwaveJsValue): IZwaveJsValueId {
@@ -120,11 +134,11 @@ export class ZwaveJsMapper {
   }
 
   public static nodeDeviceId(snapshotArg: IZwaveJsSnapshot, nodeIdArg: number): string {
-    return `zwave_js.${this.homeId(snapshotArg).toString(16)}.node.${nodeIdArg}`;
+    return `zwave_js.${encodeURIComponent(snapshotArg.homeId)}.${this.homeId(snapshotArg).toString(16)}.node.${nodeIdArg}`;
   }
 
   private static createCommand(snapshotArg: IZwaveJsSnapshot, targetArg: IControlTarget, valueArg: unknown): IZwaveJsServerCommand {
-    if (!this.nodeAvailable(snapshotArg, targetArg.node) || !this.valueWritable(targetArg.value)) {
+    if (!snapshotArg.allowControls || !this.nodeAvailable(snapshotArg, targetArg.node) || !this.valueWritable(targetArg.value)) {
       throw new Error('Z-Wave JS target is unavailable or is not a supported writable value.');
     }
     const metadata = targetArg.value.metadata!;
@@ -188,7 +202,7 @@ export class ZwaveJsMapper {
     return homeId;
   }
 
-  private static controllerDeviceId(snapshotArg: IZwaveJsSnapshot): string { return `zwave_js.${this.homeId(snapshotArg).toString(16)}.controller`; }
+  private static controllerDeviceId(snapshotArg: IZwaveJsSnapshot): string { return `zwave_js.${encodeURIComponent(snapshotArg.homeId)}.${this.homeId(snapshotArg).toString(16)}.server`; }
   private static nodeName(nodeArg: IZwaveJsNode): string { return nodeArg.name || nodeArg.productLabel || `Z-Wave node ${nodeArg.nodeId}`; }
   private static valueLabel(valueArg: IZwaveJsValue): string { return valueArg.metadata?.label || valueArg.propertyName || String(valueArg.property); }
 }

package/ts/integrations/zwave_js/zwave_js.types.ts

@@ -1,13 +1,33 @@
 export interface IZwaveJsConfig {
+  /** Consistency with the independent home selected by the embedding host. */
+  homeId: string;
   url: string;
   expectedHomeId: number;
-  /** Authorization enforced by the operator's TLS reverse proxy, not by Z-Wave JS. */
-  authorization?: string;
+  /** Controls are disabled unless the owning host explicitly enables them. */
+  allowControls?: boolean;
+  credentialRef?: string;
+  /** Explicit alternatives; neither source falls back to the other. */
+  credentialSource?: 'provider' | 'config-store';
   /** Additional TLS trust anchor. Certificate and hostname verification stay enabled. */
   ca?: string;
   requestTimeoutMs?: number;
 }
 
+export interface IZwaveJsCredentialRequest {
+  readonly homeId: string;
+  readonly credentialRef: string;
+  readonly signal: AbortSignal;
+  /** Monotonic performance.now() deadline in milliseconds. */
+  readonly deadline: number;
+}
+export type TZwaveJsAuthorizationResolver = (requestArg: IZwaveJsCredentialRequest) => Promise<string>;
+export interface IZwaveJsIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+  /** Caller-owned; never persisted or closed by the integration. */
+  readonly resolveAuthorization?: TZwaveJsAuthorizationResolver;
+}
+
 export interface IZwaveJsVersion {
   type: 'version';
   driverVersion: string;
@@ -89,6 +109,8 @@ export interface IZwaveJsValue {
 }
 
 export interface IZwaveJsSnapshot {
+  homeId: string;
+  allowControls: boolean;
   version?: IZwaveJsVersion;
   controller?: IZwaveJsController;
   nodes: IZwaveJsNode[];
@@ -107,9 +129,10 @@ export interface IZwaveJsServerCommand {
 }
 
 export interface IZwaveJsWriteResult {
-  /** Only supervised status 255 proves completion. Status 1/254 remain indeterminate. */
+  /** Supervised status is a device report, not independent proof of physical causality. */
   outcome: 'confirmed' | 'working' | 'unsupervised' | 'rejected';
   status: number;
+  causalityConfirmed: false;
 }
 
 export interface IZwaveJsServerEvent {

package/ts/integrations/zwave_js/zwave_js.validation.ts

@@ -1,4 +1,4 @@
-import type { IZwaveJsConfig, IZwaveJsNode, IZwaveJsState, IZwaveJsValue, IZwaveJsValueId, IZwaveJsValueMetadata, IZwaveJsVersion } from './zwave_js.types.js';
+import type { IZwaveJsConfig, IZwaveJsIntegrationOptions, IZwaveJsNode, IZwaveJsState, IZwaveJsValue, IZwaveJsValueId, IZwaveJsValueMetadata, IZwaveJsVersion } from './zwave_js.types.js';
 
 export const zwaveJsSchemaVersion = 32;
 
@@ -8,34 +8,68 @@ export const zwaveJsRecord = (valueArg: unknown): valueArg is Record<string, unk
 export const zwaveJsInteger = (valueArg: unknown, minArg: number, maxArg: number): valueArg is number =>
   typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= minArg && valueArg <= maxArg;
 
-export const validateZwaveJsConfig = (configArg: IZwaveJsConfig): IZwaveJsConfig => {
-  if (!zwaveJsRecord(configArg) || Object.keys(configArg).some((keyArg) =>
-    !['url', 'expectedHomeId', 'authorization', 'ca', 'requestTimeoutMs'].includes(keyArg))) {
-    throw new Error('Invalid Z-Wave JS configuration fields.');
-  }
-  if (typeof configArg.url !== 'string' || configArg.url.length > 2048) {
+/** Capture foreign data without executing getters or accepting hidden/symbol fields. */
+export const captureZwaveJsData = (valueArg: unknown, fieldsArg?: readonly string[]): Record<string, unknown> => {
+  if (!zwaveJsRecord(valueArg) || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError('Z-Wave JS input must be a plain data object.');
+  }
+  const captured: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || fieldsArg && !fieldsArg.includes(key) || !descriptor ||
+      !descriptor.enumerable || !('value' in descriptor)) throw new TypeError('Unsupported Z-Wave JS data field or accessor.');
+    Object.defineProperty(captured, key, { value: descriptor.value as unknown, enumerable: true, writable: true });
+  }
+  return captured;
+};
+
+export const validateZwaveJsEndpoint = (urlArg: unknown): string => {
+  if (typeof urlArg !== 'string' || urlArg.length > 2048) {
     throw new Error('Z-Wave JS requires an explicit WebSocket URL.');
   }
   let url: URL;
-  try { url = new URL(configArg.url); } catch { throw new Error('Invalid Z-Wave JS WebSocket URL.'); }
+  try { url = new URL(urlArg); } catch { throw new Error('Invalid Z-Wave JS WebSocket URL.'); }
   if (!['ws:', 'wss:'].includes(url.protocol) || !url.hostname || url.username || url.password || url.search || url.hash) {
     throw new Error('Z-Wave JS URL must use ws/wss without credentials, query or fragment.');
   }
-  if (!zwaveJsInteger(configArg.expectedHomeId, 1, 0xffffffff)) {
+  return url.href;
+};
+
+export const normalizeZwaveJsOptions = (optionsArg: IZwaveJsIntegrationOptions = {}): Readonly<IZwaveJsIntegrationOptions> => {
+  const options = captureZwaveJsData(optionsArg, ['homeId', 'capacity', 'resolveAuthorization']);
+  if (options.resolveAuthorization !== undefined && typeof options.resolveAuthorization !== 'function') {
+    throw new TypeError('Z-Wave JS authorization resolver must be a caller-owned function.');
+  }
+  return Object.freeze(options) as Readonly<IZwaveJsIntegrationOptions>;
+};
+
+export const validateZwaveJsConfig = (inputArg: IZwaveJsConfig | Record<string, unknown>): IZwaveJsConfig => {
+  const config = captureZwaveJsData(inputArg, ['homeId', 'url', 'expectedHomeId', 'allowControls', 'credentialRef', 'credentialSource', 'ca', 'requestTimeoutMs']);
+  if (typeof config.homeId !== 'string' || !config.homeId || config.homeId.length > 256 ||
+    config.homeId.trim() !== config.homeId || /[\p{Cc}\p{Cs}]/u.test(config.homeId)) throw new Error('Z-Wave JS configuration requires host home consistency.');
+  const url = validateZwaveJsEndpoint(config.url);
+  if (!zwaveJsInteger(config.expectedHomeId, 1, 0xffffffff)) {
     throw new Error('Z-Wave JS requires the expected network home ID.');
   }
-  if (configArg.authorization !== undefined && (url.protocol !== 'wss:' ||
-    typeof configArg.authorization !== 'string' || !configArg.authorization.trim() ||
-    configArg.authorization.length > 4096 || /[\x00-\x1f\x7f]/.test(configArg.authorization))) {
-    throw new Error('Z-Wave JS proxy authorization requires verified TLS and a valid header.');
+  if (config.allowControls !== undefined && typeof config.allowControls !== 'boolean') throw new Error('Invalid Z-Wave JS control authorization.');
+  if (config.credentialRef !== undefined && (typeof config.credentialRef !== 'string' || !config.credentialRef ||
+    config.credentialRef.length > 1024 || config.credentialRef.trim() !== config.credentialRef || /[\p{Cc}\p{Cs}]/u.test(config.credentialRef))) {
+    throw new Error('Invalid Z-Wave JS credential reference.');
+  }
+  if (config.credentialSource !== undefined && config.credentialSource !== 'provider' && config.credentialSource !== 'config-store' ||
+    (config.credentialRef === undefined) !== (config.credentialSource === undefined) || config.credentialRef !== undefined && !url.startsWith('wss:')) {
+    throw new Error('Z-Wave JS credentials require an explicit source, reference and verified TLS.');
   }
-  if (configArg.ca !== undefined && (url.protocol !== 'wss:' || typeof configArg.ca !== 'string' ||
-    configArg.ca.length > 65536 || !configArg.ca.includes('-----BEGIN CERTIFICATE-----'))) {
+  if (config.ca !== undefined && (!url.startsWith('wss:') || typeof config.ca !== 'string' ||
+    config.ca.length > 65536 || !config.ca.includes('-----BEGIN CERTIFICATE-----'))) {
     throw new Error('Z-Wave JS CA must be a PEM certificate for a wss endpoint.');
   }
-  const requestTimeoutMs = configArg.requestTimeoutMs ?? 10000;
+  const requestTimeoutMs = config.requestTimeoutMs ?? 10000;
   if (!zwaveJsInteger(requestTimeoutMs, 50, 60000)) throw new Error('Invalid Z-Wave JS request deadline.');
-  return { ...configArg, url: url.href, requestTimeoutMs };
+  return Object.freeze({ homeId: config.homeId, url, expectedHomeId: config.expectedHomeId,
+    allowControls: config.allowControls === true, requestTimeoutMs,
+    credentialRef: config.credentialRef as string | undefined,
+    credentialSource: config.credentialSource as IZwaveJsConfig['credentialSource'], ca: config.ca as string | undefined });
 };
 
 export const parseZwaveJsVersion = (valueArg: unknown, expectedHomeIdArg: number): IZwaveJsVersion => {
@@ -81,7 +115,7 @@ export const parseZwaveJsMetadata = (valueArg: unknown): IZwaveJsValueMetadata =
   }
   const metadata: IZwaveJsValueMetadata = {
     type: valueArg.type, readable: valueArg.readable, writeable: valueArg.writeable,
-    secret: valueArg.secret === true, stateful: valueArg.stateful !== false,
+    secret: valueArg.secret as boolean | undefined, stateful: valueArg.stateful as boolean | undefined,
   };
   for (const key of ['label', 'unit'] as const) {
     if (typeof valueArg[key] === 'string' && valueArg[key].length <= 1024) metadata[key] = valueArg[key];

package/ts/plugins.ts

@@ -4,9 +4,10 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import * as net from 'node:net';
 import * as tls from 'node:tls';
+import * as http from 'node:http';
 import * as https from 'node:https';
 import * as os from 'node:os';
-export { crypto, fs, https, net, path, tls, os };
+export { crypto, fs, http, https, net, path, tls, os };
 
 // Project scope
 import * as shxInterfaces from '@smarthome.exchange/interfaces';