@smarthome.exchange/integrations 0.1.0 → 1.0.0

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

@@ -0,0 +1,191 @@
+import type { IZwaveJsConfig, IZwaveJsNode, IZwaveJsState, IZwaveJsValue, IZwaveJsValueId, IZwaveJsValueMetadata, IZwaveJsVersion } from './zwave_js.types.js';
+
+export const zwaveJsSchemaVersion = 32;
+
+export const zwaveJsRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+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) {
+    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.'); }
+  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)) {
+    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 (configArg.ca !== undefined && (url.protocol !== 'wss:' || typeof configArg.ca !== 'string' ||
+    configArg.ca.length > 65536 || !configArg.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;
+  if (!zwaveJsInteger(requestTimeoutMs, 50, 60000)) throw new Error('Invalid Z-Wave JS request deadline.');
+  return { ...configArg, url: url.href, requestTimeoutMs };
+};
+
+export const parseZwaveJsVersion = (valueArg: unknown, expectedHomeIdArg: number): IZwaveJsVersion => {
+  if (!zwaveJsRecord(valueArg) || valueArg.type !== 'version' ||
+    typeof valueArg.driverVersion !== 'string' || typeof valueArg.serverVersion !== 'string' ||
+    !zwaveJsInteger(valueArg.homeId, 1, 0xffffffff) || valueArg.homeId !== expectedHomeIdArg ||
+    !zwaveJsInteger(valueArg.minSchemaVersion, 0, 1024) ||
+    !zwaveJsInteger(valueArg.maxSchemaVersion, 0, 1024) ||
+    valueArg.minSchemaVersion > zwaveJsSchemaVersion || valueArg.maxSchemaVersion < zwaveJsSchemaVersion) {
+    throw new Error('Z-Wave JS version, network identity or API schema is incompatible.');
+  }
+  return {
+    type: 'version', driverVersion: valueArg.driverVersion, serverVersion: valueArg.serverVersion,
+    homeId: valueArg.homeId, minSchemaVersion: valueArg.minSchemaVersion, maxSchemaVersion: valueArg.maxSchemaVersion,
+  };
+};
+
+export const parseZwaveJsValueId = (valueArg: unknown): IZwaveJsValueId => {
+  if (!zwaveJsRecord(valueArg) || !zwaveJsInteger(valueArg.commandClass, 0, 65535) ||
+    !validProperty(valueArg.property) ||
+    valueArg.propertyKey !== undefined && !validProperty(valueArg.propertyKey) ||
+    valueArg.endpoint !== undefined && !zwaveJsInteger(valueArg.endpoint, 0, 127)) {
+    throw new Error('Malformed Z-Wave JS value identity.');
+  }
+  return {
+    commandClass: valueArg.commandClass, endpoint: valueArg.endpoint as number | undefined,
+    property: valueArg.property, propertyKey: valueArg.propertyKey as string | number | undefined,
+  };
+};
+
+const validProperty = (valueArg: unknown): valueArg is string | number =>
+  typeof valueArg === 'string' && valueArg.length > 0 && valueArg.length <= 256 ||
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg);
+
+export const parseZwaveJsMetadata = (valueArg: unknown): IZwaveJsValueMetadata => {
+  if (!zwaveJsRecord(valueArg) || typeof valueArg.type !== 'string' ||
+    typeof valueArg.readable !== 'boolean' || typeof valueArg.writeable !== 'boolean' ||
+    valueArg.secret !== undefined && typeof valueArg.secret !== 'boolean' ||
+    valueArg.stateful !== undefined && typeof valueArg.stateful !== 'boolean' ||
+    valueArg.min !== undefined && (typeof valueArg.min !== 'number' || !Number.isFinite(valueArg.min)) ||
+    valueArg.max !== undefined && (typeof valueArg.max !== 'number' || !Number.isFinite(valueArg.max))) {
+    throw new Error('Malformed Z-Wave JS value metadata.');
+  }
+  const metadata: IZwaveJsValueMetadata = {
+    type: valueArg.type, readable: valueArg.readable, writeable: valueArg.writeable,
+    secret: valueArg.secret === true, stateful: valueArg.stateful !== false,
+  };
+  for (const key of ['label', 'unit'] as const) {
+    if (typeof valueArg[key] === 'string' && valueArg[key].length <= 1024) metadata[key] = valueArg[key];
+  }
+  for (const key of ['min', 'max'] as const) {
+    if (typeof valueArg[key] === 'number' && Number.isFinite(valueArg[key])) metadata[key] = valueArg[key];
+  }
+  if (metadata.min !== undefined && metadata.max !== undefined && metadata.min > metadata.max) {
+    throw new Error('Invalid Z-Wave JS metadata range.');
+  }
+  if (zwaveJsRecord(valueArg.states)) {
+    metadata.states = {};
+    for (const [key, value] of Object.entries(valueArg.states)) {
+      if (typeof value !== 'string' || value.length > 1024) throw new Error('Malformed Z-Wave JS value states.');
+      metadata.states[key] = value;
+    }
+  }
+  return metadata;
+};
+
+export const parseZwaveJsValue = (valueArg: unknown): IZwaveJsValue | undefined => {
+  const id = parseZwaveJsValueId(valueArg);
+  if (!zwaveJsRecord(valueArg)) throw new Error('Malformed Z-Wave JS value.');
+  const metadata = parseZwaveJsMetadata(valueArg.metadata);
+  if (metadata.secret) return undefined;
+  validateZwaveJsValueData(metadata, valueArg.value);
+  return {
+    ...id, metadata, value: valueArg.value,
+    commandClassName: typeof valueArg.commandClassName === 'string' ? valueArg.commandClassName : undefined,
+    propertyName: typeof valueArg.propertyName === 'string' ? valueArg.propertyName : undefined,
+    propertyKeyName: typeof valueArg.propertyKeyName === 'string' ? valueArg.propertyKeyName : undefined,
+  };
+};
+
+export const validateZwaveJsValueData = (metadataArg: IZwaveJsValueMetadata, valueArg: unknown): void => {
+  if (valueArg === undefined || valueArg === null) return;
+  if (metadataArg.type === 'boolean' && typeof valueArg !== 'boolean' ||
+    metadataArg.type === 'number' && (typeof valueArg !== 'number' || !Number.isFinite(valueArg)) ||
+    metadataArg.type === 'string' && typeof valueArg !== 'string') {
+    throw new Error('Z-Wave JS reported value violates its advertised type.');
+  }
+};
+
+export const parseZwaveJsNode = (valueArg: unknown): IZwaveJsNode => {
+  if (!zwaveJsRecord(valueArg) || !zwaveJsInteger(valueArg.nodeId, 1, 4095) ||
+    typeof valueArg.ready !== 'boolean' || !zwaveJsInteger(valueArg.status, 0, 4) ||
+    !Array.isArray(valueArg.values) || valueArg.values.length > 4096) {
+    throw new Error('Malformed Z-Wave JS node state.');
+  }
+  const node: IZwaveJsNode = {
+    nodeId: valueArg.nodeId, status: ['unknown', 'asleep', 'awake', 'dead', 'alive'][valueArg.status], ready: valueArg.ready,
+    values: valueArg.values.map(parseZwaveJsValue).filter((valueArg): valueArg is IZwaveJsValue => valueArg !== undefined),
+  };
+  const values = node.values as IZwaveJsValue[];
+  if (new Set(values.map(zwaveJsValueKey)).size !== values.length) throw new Error('Duplicate Z-Wave JS value identity.');
+  for (const key of ['name', 'location', 'firmwareVersion'] as const) {
+    if (typeof valueArg[key] === 'string' && valueArg[key].length <= 1024) node[key] = valueArg[key];
+  }
+  if (zwaveJsRecord(valueArg.deviceConfig)) {
+    for (const [source, target] of [['manufacturer', 'manufacturer'], ['label', 'productLabel'], ['description', 'productDescription']] as const) {
+      if (typeof valueArg.deviceConfig[source] === 'string') node[target] = valueArg.deviceConfig[source];
+    }
+  }
+  for (const key of ['manufacturerId', 'productId', 'productType'] as const) {
+    if (zwaveJsInteger(valueArg[key], 0, 65535)) node[key] = valueArg[key];
+  }
+  return node;
+};
+
+export const parseZwaveJsState = (valueArg: unknown, expectedHomeIdArg: number): IZwaveJsState => {
+  if (!zwaveJsRecord(valueArg) || !zwaveJsRecord(valueArg.controller) ||
+    valueArg.controller.homeId !== expectedHomeIdArg || !Array.isArray(valueArg.nodes) || valueArg.nodes.length > 4096) {
+    throw new Error('Malformed Z-Wave JS network state.');
+  }
+  const nodes = valueArg.nodes.map(parseZwaveJsNode);
+  if (new Set(nodes.map((nodeArg) => nodeArg.nodeId)).size !== nodes.length ||
+    nodes.reduce((totalArg, nodeArg) => totalArg + (nodeArg.values as IZwaveJsValue[]).length, 0) > 65536) {
+    throw new Error('Duplicate or oversized Z-Wave JS network state.');
+  }
+  return {
+    controller: {
+      homeId: expectedHomeIdArg,
+      ownNodeId: zwaveJsInteger(valueArg.controller.ownNodeId, 1, 4095) ? valueArg.controller.ownNodeId : undefined,
+    },
+    nodes,
+  };
+};
+
+export const zwaveJsValueKey = (valueArg: IZwaveJsValueId | IZwaveJsValue): string =>
+  JSON.stringify([valueArg.commandClass, valueArg.endpoint ?? 0, valueArg.property, valueArg.propertyKey ?? null]);
+
+/** Limit nesting and aggregate work before any schema-specific traversal. */
+export const validateZwaveJsJson = (valueArg: unknown): void => {
+  const queue: Array<{ value: unknown; depth: number }> = [{ value: valueArg, depth: 0 }];
+  let count = 0;
+  while (queue.length) {
+    const item = queue.pop()!;
+    if (++count > 200000 || item.depth > 32) throw new Error('Oversized Z-Wave JS JSON structure.');
+    if (typeof item.value === 'number' && !Number.isFinite(item.value)) throw new Error('Invalid Z-Wave JS JSON number.');
+    if (Array.isArray(item.value) || zwaveJsRecord(item.value)) {
+      for (const value of Object.values(item.value)) {
+        if (count + queue.length >= 200000) throw new Error('Oversized Z-Wave JS JSON structure.');
+        queue.push({ value, depth: item.depth + 1 });
+      }
+    }
+  }
+};

package/ts/plugins.ts

@@ -4,22 +4,31 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import * as net from 'node:net';
 import * as tls from 'node:tls';
-
-export { crypto, fs, net, path, tls };
+import * as https from 'node:https';
+import * as os from 'node:os';
+export { crypto, fs, https, net, path, tls, os };
 
 // Project scope
 import * as shxInterfaces from '@smarthome.exchange/interfaces';
 
 export { shxInterfaces };
 
+import * as nosqldb from '@lossless.org/client/nosqldb';
+
+export { nosqldb };
+
 // Existing lower-level device/protocol helper package.
 import * as ecobridgeDeviceManager from '@ecobridge.xyz/devicemanager';
 
 export { ecobridgeDeviceManager };
 
 // Third-party scope
+import * as mqtt from 'mqtt';
+import * as ws from 'ws';
 import * as homeAssistantWebsocket from 'home-assistant-js-websocket';
+import * as esphomeNativeApi from 'esphome-client';
 import * as homeAssistantWebsocketMessages from 'home-assistant-js-websocket/dist/messages.js';
 import * as homeAssistantWebsocketUtil from 'home-assistant-js-websocket/dist/util.js';
 
-export { homeAssistantWebsocket, homeAssistantWebsocketMessages, homeAssistantWebsocketUtil };
+import * as fastXmlParser from 'fast-xml-parser';
+export { mqtt, homeAssistantWebsocket, homeAssistantWebsocketMessages, homeAssistantWebsocketUtil, esphomeNativeApi, ws, fastXmlParser };

package/ts_migration/001.import-json-config.ts

@@ -0,0 +1,81 @@
+import * as plugins from '../ts/plugins.js';
+import { NoSqlConfigStore, type INoSqlConfigStoreOptions } from '../ts/core/classes.configstore.js';
+
+export interface ILegacyJsonConfigImportOptions extends INoSqlConfigStoreOptions {
+  sourcePath: string;
+}
+
+export interface ILegacyJsonConfigImportResult {
+  applied: boolean;
+  importedKeys: number;
+}
+
+@plugins.nosqldb.managed({ collectionName: 'shx_integration_config_migrations' })
+class LegacyConfigImportRecord extends plugins.nosqldb.SmartDataDbDoc<LegacyConfigImportRecord, LegacyConfigImportRecord> {
+  @plugins.nosqldb.unI() public id!: string;
+  @plugins.nosqldb.svDb() public sourceDigest!: string;
+  @plugins.nosqldb.svDb() public importedKeys!: number;
+}
+
+const readLegacySource = async (sourcePathArg: string): Promise<Buffer> => {
+  const maximumBytes = 1048576;
+  const handle = await plugins.fs.open(sourcePathArg, 'r');
+  try {
+    if (!(await handle.stat()).isFile()) throw new Error('Legacy config source must be a regular file.');
+    const buffer = Buffer.alloc(maximumBytes + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.byteLength) {
+      const result = await handle.read(buffer, bytesRead, buffer.byteLength - bytesRead, bytesRead);
+      if (result.bytesRead === 0) break;
+      bytesRead += result.bytesRead;
+    }
+    if (bytesRead > maximumBytes) throw new RangeError('Legacy config source exceeds the one-megabyte migration limit.');
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+};
+
+/** Explicit one-time legacy read: the source is never written, renamed or removed. */
+export const importLegacyJsonConfig = async (optionsArg: ILegacyJsonConfigImportOptions): Promise<ILegacyJsonConfigImportResult> => {
+  const store = new NoSqlConfigStore(optionsArg);
+  const migrations = plugins.nosqldb.bindDocToManager({ db: optionsArg.db }, LegacyConfigImportRecord);
+  const source = await readLegacySource(optionsArg.sourcePath);
+  let parsed: unknown;
+  let sourceDigest: string;
+  try {
+    sourceDigest = plugins.crypto.createHash('sha256').update(source).digest('hex');
+    parsed = JSON.parse(source.toString('utf8'));
+  } finally {
+    source.fill(0);
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) || Object.getPrototypeOf(parsed) !== Object.prototype) {
+    throw new TypeError('Legacy JSON config root must be a non-null plain object.');
+  }
+  const entries = Object.entries(parsed);
+  await store.initialize();
+  await migrations.ensureInitialized();
+  const id = JSON.stringify([optionsArg.homeId, optionsArg.integrationDomain, '001.import-json-config']);
+  const session = optionsArg.db.createSession();
+  try {
+    const result = await session.withTransaction(async (sessionArg) => {
+      const previous = await migrations.getInstance({ id }, { session: sessionArg });
+      if (previous) {
+        if (typeof previous.sourceDigest !== 'string' || !/^[a-f0-9]{64}$/.test(previous.sourceDigest) ||
+          !Number.isSafeInteger(previous.importedKeys) || previous.importedKeys < 0) {
+          throw new Error('Legacy config import completion record is invalid.');
+        }
+        if (previous.sourceDigest !== sourceDigest) throw new Error('Legacy config source changed after its completed import.');
+        return { applied: false, importedKeys: previous.importedKeys };
+      }
+      const completion = Object.assign(new migrations(), { id, sourceDigest, importedKeys: entries.length });
+      await migrations.insert(completion, { session: sessionArg });
+      for (const [key, value] of entries) await store.create(key, value, { session: sessionArg });
+      return { applied: true, importedKeys: entries.length };
+    }, { timeoutMS: optionsArg.timeoutMs ?? 5000 });
+    if (!result) throw new Error('Legacy config import did not complete a transaction.');
+    return result;
+  } finally {
+    await session.close();
+  }
+};

package/ts_migration/index.ts

@@ -0,0 +1 @@
+export * from './001.import-json-config.js';

package/ts/integrations/tasmota/.generated-by-smarthome-exchange

@@ -1 +0,0 @@
-This folder is generated from Home Assistant component metadata. Replace it with a handwritten TypeScript port when implementing runtime support.

package/ts/integrations/tuya/.generated-by-smarthome-exchange

@@ -1 +0,0 @@
-This folder is generated from Home Assistant component metadata. Replace it with a handwritten TypeScript port when implementing runtime support.