@smarthome.exchange/integrations 0.1.0 → 1.0.0

package/ts/integrations/tuya/tuya.types.ts

@@ -1,4 +1,49 @@
+export type TTuyaDatapointAccess = 'read' | 'read-write';
+
+export interface ITuyaDatapointIdentity {
+  readonly id: number;
+  readonly name: string;
+}
+
+export interface ITuyaSwitchDatapoint extends ITuyaDatapointIdentity {
+  readonly kind: 'switch';
+  readonly access: TTuyaDatapointAccess;
+}
+
+export interface ITuyaBrightnessDatapoint extends ITuyaDatapointIdentity {
+  readonly kind: 'brightness';
+  readonly access: TTuyaDatapointAccess;
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+}
+
+export interface ITuyaSensorDatapoint extends ITuyaDatapointIdentity {
+  readonly kind: 'sensor';
+  readonly valueType: 'boolean' | 'integer' | 'string';
+  /** Number of decimal places in a Tuya integer value; sensor display only. */
+  readonly scale?: number;
+  readonly unit?: string;
+}
+
+export type TTuyaDatapointMapping = ITuyaSwitchDatapoint | ITuyaBrightnessDatapoint | ITuyaSensorDatapoint;
+
+/** Non-secret product configuration. Credentials are provisioned into NoSqlConfigStore. */
 export interface IHomeAssistantTuyaConfig {
-  // TODO: replace with the TypeScript-native config for tuya.
-  [key: string]: unknown;
+  readonly homeId: string;
+  readonly deviceId: string;
+  readonly host: string;
+  readonly version: '3.4';
+  readonly port?: number;
+  readonly name?: string;
+  readonly datapoints: readonly TTuyaDatapointMapping[];
+  readonly connectTimeoutMs?: number;
+  readonly requestTimeoutMs?: number;
+  readonly heartbeatIntervalMs?: number;
+}
+
+export interface ITuyaStoredConfiguration {
+  readonly version: 1;
+  readonly config: IHomeAssistantTuyaConfig;
+  readonly localKey: string;
 }

package/ts/integrations/tuya/tuya.validation.ts

@@ -0,0 +1,118 @@
+import * as plugins from '../../plugins.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
+import type { IHomeAssistantTuyaConfig, TTuyaDatapointMapping } from './tuya.types.js';
+
+export const tuyaRecord = (valueArg: unknown, labelArg: string): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' ||
+    (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new TypeError(`Tuya ${labelArg} must be a plain object.`);
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+      throw new TypeError(`Tuya ${labelArg} may not contain accessors, symbols or hidden properties.`);
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+};
+
+export const tuyaKeys = (recordArg: Record<string, unknown>, allowedArg: readonly string[]): void => {
+  if (Object.keys(recordArg).some((keyArg) => !allowedArg.includes(keyArg))) {
+    throw new TypeError('Tuya input contains unsupported properties.');
+  }
+};
+
+const text = (valueArg: unknown, labelArg: string, maximumArg: number): string => {
+  if (typeof valueArg !== 'string' || valueArg.trim().length === 0 || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`Tuya ${labelArg} must be a non-empty bounded string without control characters.`);
+  }
+  return valueArg;
+};
+
+const integer = (valueArg: unknown, labelArg: string, minimumArg: number, maximumArg: number): number => {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError(`Tuya ${labelArg} is outside its integer range.`);
+  }
+  return valueArg;
+};
+
+const mapping = (valueArg: unknown): TTuyaDatapointMapping => {
+  const record = tuyaRecord(valueArg, 'datapoint mapping');
+  const identity = { id: integer(record.id, 'datapoint ID', 1, 255), name: text(record.name, 'datapoint name', 128) };
+  if (record.kind === 'switch' || record.kind === 'brightness') {
+    if (record.access !== 'read' && record.access !== 'read-write') throw new TypeError('Tuya switch/brightness access must be explicit.');
+    if (record.kind === 'switch') {
+      tuyaKeys(record, ['id', 'name', 'kind', 'access']);
+      return Object.freeze({ ...identity, kind: 'switch', access: record.access });
+    }
+    tuyaKeys(record, ['id', 'name', 'kind', 'access', 'min', 'max', 'step']);
+    const min = integer(record.min, 'brightness minimum', 0, 2147483647);
+    const max = integer(record.max, 'brightness maximum', 1, 2147483647);
+    const step = integer(record.step, 'brightness step', 1, 2147483647);
+    if (max <= min || (max - min) % step !== 0) throw new TypeError('Tuya brightness bounds must form an exact stepped interval.');
+    return Object.freeze({ ...identity, kind: 'brightness', access: record.access, min, max, step });
+  }
+  if (record.kind !== 'sensor') throw new TypeError('Tuya supports only switch, brightness and read-only sensor mappings.');
+  tuyaKeys(record, ['id', 'name', 'kind', 'valueType', 'scale', 'unit']);
+  if (record.valueType !== 'boolean' && record.valueType !== 'integer' && record.valueType !== 'string') throw new TypeError('Tuya sensor type is unsupported.');
+  if (record.scale !== undefined && record.valueType !== 'integer') throw new TypeError('Tuya scaling is supported only for integer sensors.');
+  const scale = record.scale === undefined ? undefined : integer(record.scale, 'sensor scale', 0, 9);
+  const unit = record.unit === undefined ? undefined : text(record.unit, 'sensor unit', 32);
+  return Object.freeze({ ...identity, kind: 'sensor', valueType: record.valueType, ...(scale === undefined ? {} : { scale }), ...(unit === undefined ? {} : { unit }) });
+};
+
+export const normalizeTuyaConfig = (valueArg: unknown): IHomeAssistantTuyaConfig => {
+  const record = tuyaRecord(valueArg, 'configuration');
+  tuyaKeys(record, ['homeId', 'deviceId', 'host', 'version', 'port', 'name', 'datapoints', 'connectTimeoutMs', 'requestTimeoutMs', 'heartbeatIntervalMs']);
+  const homeId = text(record.homeId, 'home ID', 256);
+  const deviceId = text(record.deviceId, 'device ID', 64);
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(deviceId)) throw new TypeError('Tuya device ID is malformed.');
+  const host = text(record.host, 'literal local address', 64);
+  const address = host.split('.').map(Number);
+  if (plugins.net.isIP(host) !== 4 || !(address[0] === 10 || address[0] === 127 ||
+    address[0] === 172 && address[1] >= 16 && address[1] <= 31 ||
+    address[0] === 192 && address[1] === 168 || address[0] === 169 && address[1] === 254)) {
+    throw new TypeError('Tuya host must be a literal private, link-local or loopback IPv4 address.');
+  }
+  if (record.version !== '3.4') throw new TypeError('Tuya supports local protocol 3.4 only.');
+  if (!Array.isArray(record.datapoints) || record.datapoints.length < 1 || record.datapoints.length > 255 ||
+    Object.keys(record.datapoints).length !== record.datapoints.length ||
+    Reflect.ownKeys(record.datapoints).some((keyArg) => keyArg !== 'length' &&
+      (typeof keyArg !== 'string' || !/^(0|[1-9]\d*)$/.test(keyArg) ||
+        !('value' in Object.getOwnPropertyDescriptor(record.datapoints as object, keyArg)!)))) {
+    throw new TypeError('Tuya datapoint mappings must be a bounded dense array of data properties.');
+  }
+  const datapoints = Object.freeze(record.datapoints.map(mapping));
+  if (new Set(datapoints.map((mappingArg) => mappingArg.id)).size !== datapoints.length) throw new TypeError('Tuya datapoint IDs must be unique.');
+  return Object.freeze({ homeId, deviceId, host, version: '3.4',
+    port: integer(record.port ?? 6668, 'port', 1, 65535),
+    name: record.name === undefined ? `Tuya ${deviceId}` : text(record.name, 'device name', 128),
+    datapoints,
+    connectTimeoutMs: integer(record.connectTimeoutMs ?? 5000, 'connect timeout', 1, 120000),
+    requestTimeoutMs: integer(record.requestTimeoutMs ?? 5000, 'request timeout', 1, 120000),
+    heartbeatIntervalMs: integer(record.heartbeatIntervalMs ?? 10000, 'heartbeat interval', 10, 120000),
+  });
+};
+
+export const scopedTuyaStore = (configArg: IHomeAssistantTuyaConfig, contextArg: IIntegrationSetupContext): NoSqlConfigStore => {
+  const context = tuyaRecord(contextArg, 'setup context');
+  tuyaKeys(context, ['configStore', 'abortSignal', 'logger']);
+  const store = context.configStore;
+  if (!(store instanceof NoSqlConfigStore)) throw new TypeError('Tuya requires an encrypted NoSqlConfigStore and caller-owned encryption key provider.');
+  const scope = store.getScope();
+  if (scope.homeId !== configArg.homeId || scope.integrationDomain !== 'tuya') throw new TypeError('Tuya encrypted store must belong to the exact configured home and integration.');
+  if (context.abortSignal !== undefined && !(context.abortSignal instanceof AbortSignal)) throw new TypeError('Tuya setup cancellation must be an AbortSignal.');
+  return store;
+};
+
+export const tuyaCredentialId = (deviceIdArg: string): string => `device:${deviceIdArg}`;
+
+export const tuyaValueMatches = (mappingArg: TTuyaDatapointMapping, valueArg: unknown): valueArg is plugins.ecobridgeDeviceManager.TTuyaDatapointValue => {
+  if (mappingArg.kind === 'switch' || mappingArg.kind === 'sensor' && mappingArg.valueType === 'boolean') return typeof valueArg === 'boolean';
+  if (mappingArg.kind === 'sensor' && mappingArg.valueType === 'string') return typeof valueArg === 'string' && Buffer.byteLength(valueArg, 'utf8') <= 255;
+  if (typeof valueArg !== 'number' || !Number.isInteger(valueArg) || valueArg < -2147483648 || valueArg > 2147483647) return false;
+  return mappingArg.kind !== 'brightness' || valueArg >= mappingArg.min && valueArg <= mappingArg.max && (valueArg - mappingArg.min) % mappingArg.step === 0;
+};

package/ts/integrations/unifi/unifi.mapper.ts

@@ -6,6 +6,7 @@ import type {
   IUnifiConfig,
   IUnifiDevice,
   IUnifiEvent,
+  IUnifiManualEntry,
   IUnifiPort,
   IUnifiSnapshot,
   IUnifiWlan,
@@ -47,18 +48,18 @@ export class UnifiMapper {
       sites: [
         ...(source?.sites || []),
         ...(configArg.sites || []),
-        ...this.manualItems(configArg, 'sites'),
+        ...this.manualItems(configArg, (entryArg) => entryArg.sites),
       ],
       clients: [
         ...(source?.clients || []),
         ...(configArg.clients || []),
-        ...this.manualItems(configArg, 'clients'),
+        ...this.manualItems(configArg, (entryArg) => entryArg.clients),
       ],
       devices,
       wlans: [
         ...(source?.wlans || []),
         ...(configArg.wlans || []),
-        ...this.manualItems(configArg, 'wlans'),
+        ...this.manualItems(configArg, (entryArg) => entryArg.wlans),
       ],
       ports,
       events: [...(source?.events || []), ...(configArg.events || []), ...eventsArg],
@@ -656,8 +657,10 @@ export class UnifiMapper {
     return this.stringValue(target?.attributes?.mac);
   }
 
-  private static manualItems<TKey extends 'sites' | 'clients' | 'wlans'>(configArg: IUnifiConfig, keyArg: TKey): NonNullable<IUnifiConfig[TKey]> {
-    return (configArg.manualEntries || []).flatMap((entryArg) => entryArg.snapshot?.[keyArg] || entryArg[keyArg] || []) as NonNullable<IUnifiConfig[TKey]>;
+  private static manualItems<TItem>(configArg: IUnifiConfig, selectArg: (entryArg: IUnifiManualEntry) => TItem[] | undefined): TItem[] {
+    return (configArg.manualEntries || []).flatMap((entryArg) =>
+      (entryArg.snapshot && selectArg(entryArg.snapshot)) || selectArg(entryArg) || [],
+    );
   }
 
   private static booleanValue(...valuesArg: unknown[]): boolean | undefined {

package/ts/integrations/webostv/readme.md

@@ -0,0 +1,48 @@
+# Native LG webOS TV
+
+`WebostvIntegration` and the exported `HomeAssistantWebostvIntegration` constructor speak the TV's documented SSAP WebSocket protocol. Setup verifies an explicitly configured TV UUID, registers, persists the returned pairing credential encrypted, and obtains complete initial power, volume, mute, foreground-app and input-list subscriptions before exposing a runtime.
+
+```typescript
+const integration = new WebostvIntegration({ db, keyProvider });
+const runtime = await integration.setup({
+  homeId: 'home-one',
+  endpoint: 'wss://verified-tv.example:3001/',
+  expectedDeviceUUID: verifiedDeviceUUID,
+  pairingMode: 'prompt',
+  certificateAuthority: verifiedPemCertificateChain,
+}, {});
+const device = (await runtime.devices())[0];
+await runtime.callService!({
+  domain: 'media_player', service: 'volume_set',
+  target: { deviceId: device.id }, data: { volume: 25 },
+});
+await integration.destroy();
+```
+
+The default registry's no-argument constructor also supports `setup(config, { configStore })`, where `configStore` is an actual `NoSqlConfigStore` whose public `getScope()` exactly matches the configured home and `webostv` domain. Generic stores and other scopes fail before connection; an invalid provided store never falls back to constructor options. A correctly scoped context store takes precedence over constructor persistence options.
+
+The caller owns `db` and the external `keyProvider` (`currentKey(signal)` / `keyForId(id, signal)`, 32-byte keys). The integration constructs the existing `NoSqlConfigStore` in the immutable `homeId` / `webostv` scope. The pairing record also binds the exact endpoint and TV UUID. Accepted keys are durably stored before subscription setup; storage failure closes setup. There is no filesystem or memory-only credential fallback. `existing` mode rejects any prompt response and closes the connection; the TV may briefly display its prompt before that close. It never waits for or accepts fresh pairing in that mode. Explicit `prompt` mode permits a user to approve initial/rejected-key registration on the TV; a valid stored key is still reused. No key appears in device state, events, command receipts or errors.
+
+Use the TV's independently verified UUID and endpoint; discovery supplies no network probes or identity verification by itself. Only explicit manual candidates with `integrationDomain: 'webostv'` and metadata `{ endpoint, expectedDeviceUUID }` are accepted. WSS uses normal certificate-chain and hostname validation, optionally with the supplied PEM CA chain. TLS verification is never disabled. A deliberately selected cleartext local `ws://...:3000/` endpoint requires `allowUnencryptedConnection: true`; its UUID check is a device selection check and provides no cryptographic protection against an attacker on that network. No automatic WS downgrade, redirects or endpoint guessing occur.
+
+Supported exact-target services in `webostv` or `media_player`:
+
+| Service | Exact data | SSAP endpoint |
+| --- | --- | --- |
+| `status`, `snapshot` | none | Last authoritative subscribed state, with current connection availability |
+| `volume_set` | `{ volume: integer 0..100 }` | `audio/setVolume` |
+| `volume_up`, `volume_down` | none | `audio/volumeUp`, `audio/volumeDown` |
+| `volume_mute` | `{ mute: boolean }` | `audio/setMute` |
+| `select_source` | `{ inputId: advertised input id }` | `tv/switchInput` |
+| `media_play`, `media_pause`, `media_stop` | none | `media.controls/play`, `/pause`, `/stop` |
+| `turn_on`, `turn_off` | none | `system/turnOn`, `system/turnOff` |
+
+Calls require the connected home-scoped device id or its exact media-player entity id. Foreign domains/devices/entities, unknown services, extra arguments, accessors, arbitrary input ids and out-of-range volume fail before command I/O. `writeFeature` accepts only the owned `volume` and `muted` features with validated values. Power state and foreground-app features are read only.
+
+Success means a correlated positive TV response, not verified physical completion. State changes only from validated subscription responses. A timeout, cancellation or disconnect after dispatch has an indeterminate effect outcome and is never replayed automatically. TV power-off responses are sometimes absent: that is reported as indeterminate even if the TV turns off. `turn_on` requires an already connected TV that supports that SSAP method; deep standby wake-on-LAN is not implemented. Media commands depend on the current TV application, and vendor rejections fail. Next/previous track, remote pointer sockets, app launching, channels and calibration are outside this runtime.
+
+Connection, pairing and requests have bounded deadlines; frames, pending requests, inputs and subscribers have limits. Heartbeat failure closes the instance. Malformed authoritative responses fail the connection; disconnected snapshots retain their observation timestamp and report unavailable. Caller abort closes setup; `destroy()` rejects pending requests, drains current encrypted-storage work and closes the owned socket. Initialization uses the config store's bounded, cancellable collection preparation. Constructor-created config stores are closed and drained on destroy; injected context stores and the caller's database remain open. Throwing event subscribers are removed without interrupting other subscribers. Reconnection requires a new setup; no command queue survives connection loss.
+
+Breaking migration: `rawData`, `snapshot`, `snapshotProvider`, injected `client` / `commandExecutor`, generic host/transport/path configuration and `WebostvMapper.toSnapshot*` fixture mapping were removed from the production webOS config. Supply the explicit native fields and constructor persistence owner above. Existing fixture-only test data belongs in a local protocol fixture, not application configuration. No existing fixture config is automatically converted because it does not prove a TV's identity or provide durable pairing credentials.
+
+Protocol sources: [LG Connect SDK socket registration and hello](https://github.com/ConnectSDK/Connect-SDK-Android-Core/blob/master/src/com/connectsdk/service/webos/WebOSTVServiceSocketClient.java), [LG SSAP control implementations](https://github.com/ConnectSDK/Connect-SDK-Android-Core/blob/master/src/com/connectsdk/service/WebOSTVService.java), [Home Assistant's maintained SSAP endpoints](https://github.com/home-assistant-libs/aiowebostv/blob/main/aiowebostv/endpoints.py), [pre-registration system-info sequence and state subscriptions](https://github.com/home-assistant-libs/aiowebostv/blob/main/aiowebostv/webos_client.py), [ws transport API](https://github.com/websockets/ws/blob/master/doc/ws.md). Registration uses a neutral unsigned permission manifest, not LG's test identity/signatures. Hardware pairing/firmware behavior was not verified against an owner's TV; local real WebSocket fixtures cover the documented exchange. Setup currently requires the documented pre-registration system-info request and all five state subscriptions; unsupported firmware fails explicitly.

package/ts/integrations/webostv/webostv.classes.client.ts

@@ -1,9 +1,300 @@
-import { SimpleLocalClient } from '../../core/index.js';
-import type { IWebostvConfig } from './webostv.types.js';
-import { webostvProfile } from './webostv.types.js';
+import * as plugins from '../../plugins.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import type { IWebostvConfig, IWebostvInput, IWebostvIntegrationOptions, IWebostvSnapshot, TWebostvClientEvent, TWebostvCommand } from './webostv.types.js';
+import { normalizeWebostvConfig, webostvInteger, webostvObject, webostvString } from './webostv.validation.js';
 
-export class WebostvClient extends SimpleLocalClient<IWebostvConfig> {
-  constructor(configArg: IWebostvConfig) {
-    super(webostvProfile, configArg);
+interface IPendingRequest {
+  resolve(valueArg: Record<string, unknown>): void;
+  reject(errorArg: Error): void;
+  timer: ReturnType<typeof setTimeout>;
+  cleanup(): void;
+  type: 'hello' | 'register' | 'request' | 'subscribe';
+  update?: (payloadArg: Record<string, unknown>) => void;
+}
+interface IStoredPairing { version: 1; endpoint: string; deviceUUID: string; clientKey: string; }
+const endpoints = {
+  power: 'com.webos.service.tvpower/power/getPowerState', volume: 'audio/getVolume', mute: 'audio/getStatus',
+  app: 'com.webos.applicationManager/getForegroundAppInfo', inputs: 'tv/getExternalInputList',
+} as const;
+const commandEndpoints: Record<Exclude<TWebostvCommand, 'volume_set' | 'volume_mute' | 'select_source'>, string> = {
+  turn_on: 'system/turnOn', turn_off: 'system/turnOff', volume_up: 'audio/volumeUp', volume_down: 'audio/volumeDown',
+  media_play: 'media.controls/play', media_pause: 'media.controls/pause', media_stop: 'media.controls/stop',
+};
+const permissions = ['CONTROL_AUDIO', 'CONTROL_POWER', 'CONTROL_INPUT_MEDIA_PLAYBACK', 'CONTROL_INPUT_TV', 'READ_APP_STATUS', 'READ_RUNNING_APPS', 'READ_INPUT_DEVICE_LIST', 'READ_POWER_STATE'];
+
+export class WebostvClient {
+  readonly #config: Readonly<IWebostvConfig>;
+  readonly #store: NoSqlConfigStore;
+  readonly #ownsStore: boolean;
+  readonly #lifetime = new AbortController();
+  readonly #pending = new Map<string, IPendingRequest>();
+  readonly #subscriptions = new Map<string, (payloadArg: Record<string, unknown>) => void>();
+  readonly #handlers = new Set<(eventArg: TWebostvClientEvent) => void>();
+  #socket?: plugins.ws.WebSocket;
+  #snapshot?: IWebostvSnapshot;
+  #sequence = 0;
+  #start?: Promise<IWebostvSnapshot>;
+  #destroy?: Promise<void>;
+  #heartbeat?: ReturnType<typeof setInterval>;
+  #awaitingPong = false;
+  #ready = false;
+  #failure?: Error;
+  #storage?: Promise<unknown>;
+  readonly #handlerCleanups = new Map<(eventArg: TWebostvClientEvent) => void, () => void>();
+  #removeExternalAbort: () => void = () => undefined;
+
+  constructor(configArg: IWebostvConfig, optionsArg?: IWebostvIntegrationOptions | NoSqlConfigStore, signalArg?: AbortSignal) {
+    this.#config = normalizeWebostvConfig(configArg);
+    if (optionsArg instanceof NoSqlConfigStore) {
+      const scope = optionsArg.getScope();
+      if (scope.homeId !== this.#config.homeId || scope.integrationDomain !== 'webostv') throw new TypeError('webOS requires an encrypted config store scoped to the exact configured home and webostv domain.');
+      this.#store = optionsArg;
+      this.#ownsStore = false;
+    } else {
+      if (!optionsArg?.db || !optionsArg.keyProvider) throw new TypeError('webOS requires an owner-supplied database and external encryption key provider.');
+      this.#store = new NoSqlConfigStore({ db: optionsArg.db, keyProvider: optionsArg.keyProvider, homeId: this.#config.homeId, integrationDomain: 'webostv' });
+      this.#ownsStore = true;
+    }
+    if (signalArg) {
+      const abort = (): void => { void this.destroy(); };
+      if (signalArg.aborted) this.#lifetime.abort(new Error('webOS setup was aborted.'));
+      else { signalArg.addEventListener('abort', abort, { once: true }); this.#removeExternalAbort = () => signalArg.removeEventListener('abort', abort); }
+    }
+  }
+
+  public isHealthy(): boolean { return this.#ready && !this.#lifetime.signal.aborted && this.#socket?.readyState === plugins.ws.WebSocket.OPEN; }
+
+  public async getSnapshot(signalArg?: AbortSignal): Promise<IWebostvSnapshot> {
+    if (signalArg?.aborted) throw new Error('webOS snapshot was aborted.');
+    if (!this.#start) this.#start = this.#initialize().catch(async (errorArg: unknown) => { await this.destroy(); throw errorArg; });
+    await this.#start;
+    if (signalArg?.aborted) throw new Error('webOS snapshot was aborted.');
+    if (!this.#snapshot) throw new Error('webOS state is unavailable.');
+    return structuredClone({ ...this.#snapshot, connected: this.isHealthy() });
+  }
+
+  public async execute(commandArg: TWebostvCommand, argumentArg?: unknown, signalArg?: AbortSignal): Promise<void> {
+    if (!this.isHealthy()) throw new Error('webOS is disconnected; command was not sent.');
+    let uri: string;
+    let payload: Record<string, unknown> = {};
+    if (commandArg === 'volume_set') { uri = 'audio/setVolume'; payload = { volume: webostvInteger(argumentArg, 'volume', 0, 100) }; }
+    else if (commandArg === 'volume_mute') {
+      if (typeof argumentArg !== 'boolean') throw new TypeError('webOS mute must be boolean.');
+      uri = 'audio/setMute'; payload = { mute: argumentArg };
+    } else if (commandArg === 'select_source') {
+      const inputId = webostvString(argumentArg, 'inputId');
+      if (!this.#snapshot?.inputs.some((inputArg) => inputArg.id === inputId)) throw new TypeError('webOS input must match an advertised input id.');
+      uri = 'tv/switchInput'; payload = { inputId };
+    } else {
+      if (!Object.hasOwn(commandEndpoints, commandArg) || argumentArg !== undefined) throw new TypeError('Unsupported webOS command or extra arguments.');
+      uri = commandEndpoints[commandArg];
+    }
+    await this.#request('request', uri, payload, undefined, signalArg);
+  }
+
+  public async subscribe(handlerArg: (eventArg: TWebostvClientEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    await this.getSnapshot(signalArg);
+    if (signalArg?.aborted || this.#lifetime.signal.aborted) throw new Error('webOS subscription was aborted.');
+    if (this.#handlers.size >= 128) throw new Error('webOS subscriber capacity reached.');
+    const subscriber = (eventArg: TWebostvClientEvent): void => handlerArg(eventArg);
+    this.#handlers.add(subscriber);
+    const remove = (): void => { this.#handlers.delete(subscriber); this.#handlerCleanups.delete(subscriber); signalArg?.removeEventListener('abort', remove); };
+    this.#handlerCleanups.set(subscriber, remove);
+    signalArg?.addEventListener('abort', remove, { once: true });
+    return async () => remove();
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#destroy) return this.#destroy;
+    this.#destroy = this.#close();
+    return this.#destroy;
+  }
+
+  async #close(): Promise<void> {
+    this.#ready = false;
+    this.#lifetime.abort(new Error('webOS client was closed.'));
+    this.#removeExternalAbort();
+    const closeStore = this.#ownsStore ? this.#store.close() : Promise.resolve();
+    clearInterval(this.#heartbeat);
+    for (const request of this.#pending.values()) { clearTimeout(request.timer); request.cleanup(); request.reject(new Error('webOS connection closed; effects already sent have an indeterminate outcome.')); }
+    this.#pending.clear(); this.#subscriptions.clear();
+    this.#emit({ type: 'availability', available: false });
+    for (const cleanup of [...this.#handlerCleanups.values()]) cleanup();
+    this.#handlers.clear();
+    const socket = this.#socket;
+    if (!socket || socket.readyState === plugins.ws.WebSocket.CLOSED) { await Promise.all([closeStore, this.#storage?.catch(() => undefined)]); return; }
+    await new Promise<void>((resolveArg) => {
+      const timer = setTimeout(() => { socket.terminate(); }, 1000);
+      socket.once('close', () => { clearTimeout(timer); socket.removeAllListeners(); resolveArg(); });
+      if (socket.readyState === plugins.ws.WebSocket.CONNECTING) socket.terminate();
+      else socket.close(1000);
+    });
+    await Promise.all([closeStore, this.#storage?.catch(() => undefined)]);
+  }
+
+  async #persist<TResult>(operationArg: () => Promise<TResult>): Promise<TResult> {
+    if (this.#lifetime.signal.aborted) throw new Error('webOS persistence was aborted.');
+    const operation = operationArg();
+    this.#storage = operation;
+    try { return await operation; }
+    catch { throw new Error(this.#lifetime.signal.aborted ? 'webOS persistence was aborted.' : 'webOS encrypted pairing storage failed.'); }
+    finally { if (this.#storage === operation) this.#storage = undefined; }
+  }
+
+  async #initialize(): Promise<IWebostvSnapshot> {
+    if (this.#lifetime.signal.aborted) throw new Error('webOS client is closed.');
+    await this.#persist(() => this.#store.initialize({ signal: this.#lifetime.signal }));
+    const keyName = `pairing:${this.#config.expectedDeviceUUID}`;
+    const storedValue: unknown = await this.#persist(() => this.#store.get(keyName));
+    let clientKey: string | undefined;
+    if (storedValue !== undefined) {
+      const stored = webostvObject(storedValue, 'stored webOS pairing');
+      if (stored.version !== 1 || stored.endpoint !== this.#config.endpoint || stored.deviceUUID !== this.#config.expectedDeviceUUID) throw new Error('Stored webOS pairing does not match the configured endpoint and device.');
+      clientKey = webostvString(stored.clientKey, 'stored pairing key', 512);
+    }
+    if (!clientKey && this.#config.pairingMode === 'existing') throw new Error('No durable webOS pairing exists; explicit prompt mode is required for initial pairing.');
+    await this.#connect();
+    const hello = await this.#request('hello', undefined, { appId: 'exchange.smarthome', appName: 'smarthome.exchange' });
+    if (hello.deviceUUID !== this.#config.expectedDeviceUUID) throw new Error('webOS hello device UUID does not match the verified TV.');
+    // New webOS requires this request before registration; permission denial fails setup explicitly.
+    await this.#request('request', 'system/getSystemInfo', {});
+    const registered = await this.#request('register', undefined, {
+      pairingType: 'PROMPT', ...(clientKey ? { 'client-key': clientKey } : {}),
+      manifest: { manifestVersion: 1, appVersion: '1.0', permissions },
+    });
+    const acceptedKey = webostvString(registered['client-key'], 'registered pairing key', 512);
+    if (this.#lifetime.signal.aborted) throw new Error('webOS pairing was aborted.');
+    await this.#persist(() => this.#store.set<IStoredPairing>(keyName, { version: 1, endpoint: this.#config.endpoint, deviceUUID: this.#config.expectedDeviceUUID, clientKey: acceptedKey }));
+    if (this.#lifetime.signal.aborted) throw new Error('webOS setup was aborted.');
+    const initial: Partial<IWebostvSnapshot> = {};
+    const update = (fieldArg: 'power' | 'volume' | 'mute' | 'app' | 'inputs', payloadArg: Record<string, unknown>): void => {
+      this.#applyState(initial, fieldArg, payloadArg);
+      if (this.#snapshot) {
+        this.#snapshot = { ...this.#snapshot, ...initial, observedAt: new Date().toISOString() };
+        this.#emit({ type: 'state', snapshot: structuredClone(this.#snapshot) });
+      }
+    };
+    for (const [field, uri] of Object.entries(endpoints)) {
+      await this.#request('subscribe', uri, {}, (payloadArg) => update(field as keyof typeof endpoints, payloadArg));
+    }
+    if (initial.powerState === undefined || initial.volume === undefined || initial.muted === undefined || initial.currentAppId === undefined || initial.inputs === undefined) throw new Error('webOS did not supply a complete initial state.');
+    this.#snapshot = { homeId: this.#config.homeId, deviceUUID: this.#config.expectedDeviceUUID, name: this.#config.name!, connected: true, powerState: initial.powerState, volume: initial.volume, muted: initial.muted, currentAppId: initial.currentAppId, inputs: initial.inputs, observedAt: new Date().toISOString() };
+    if (this.#lifetime.signal.aborted || this.#socket?.readyState !== plugins.ws.WebSocket.OPEN) throw new Error('webOS connection closed during setup.');
+    this.#ready = true;
+    this.#heartbeat = setInterval(() => {
+      if (this.#awaitingPong) { this.#fail(new Error('webOS heartbeat timed out.')); return; }
+      this.#awaitingPong = true; this.#socket?.ping();
+    }, 15000);
+    this.#heartbeat.unref();
+    return structuredClone(this.#snapshot);
+  }
+
+  #applyState(stateArg: Partial<IWebostvSnapshot>, fieldArg: keyof typeof endpoints, payloadArg: Record<string, unknown>): void {
+    if (fieldArg === 'power') stateArg.powerState = webostvString(payloadArg.state, 'power state', 64);
+    else if (fieldArg === 'app') {
+      if (typeof payloadArg.appId !== 'string' || payloadArg.appId.length > 256 || /[\p{Cc}\p{Cs}]/u.test(payloadArg.appId)) throw new Error('webOS foreground app state is invalid.');
+      stateArg.currentAppId = payloadArg.appId;
+    } else if (fieldArg === 'volume') {
+      const volume = payloadArg.volumeStatus === undefined ? payloadArg : webostvObject(payloadArg.volumeStatus, 'volume status');
+      stateArg.volume = webostvInteger(volume.volume, 'reported volume', 0, 100);
+    } else if (fieldArg === 'mute') {
+      if (typeof payloadArg.mute !== 'boolean') throw new Error('webOS mute state is invalid.');
+      stateArg.muted = payloadArg.mute;
+    } else {
+      if (!Array.isArray(payloadArg.devices) || payloadArg.devices.length > 64) throw new Error('webOS input list is invalid.');
+      const inputs: IWebostvInput[] = payloadArg.devices.map((inputArg: unknown) => {
+        const input = webostvObject(inputArg, 'input');
+        if (typeof input.connected !== 'boolean') throw new Error('webOS input connection state is invalid.');
+        return { id: webostvString(input.id, 'input id'), label: webostvString(input.label, 'input label'), appId: webostvString(input.appId, 'input appId'), connected: input.connected };
+      });
+      if (new Set(inputs.map((inputArg) => inputArg.id)).size !== inputs.length) throw new Error('webOS input ids are not unique.');
+      stateArg.inputs = inputs;
+    }
+  }
+
+  async #connect(): Promise<void> {
+    if (this.#lifetime.signal.aborted) throw new Error('webOS client is closed.');
+    const socket = new plugins.ws.WebSocket(this.#config.endpoint, { handshakeTimeout: this.#config.requestTimeoutMs, maxPayload: 524288, perMessageDeflate: false, followRedirects: false, rejectUnauthorized: true, ca: this.#config.certificateAuthority });
+    this.#socket = socket;
+    socket.on('message', (dataArg, binaryArg) => this.#message(dataArg, binaryArg));
+    socket.on('pong', () => { this.#awaitingPong = false; });
+    socket.on('error', () => this.#fail(new Error('webOS WebSocket transport failed.')));
+    socket.on('close', () => this.#fail(new Error('webOS connection closed; effects already sent have an indeterminate outcome.')));
+    await new Promise<void>((resolveArg, rejectArg) => {
+      const cleanup = (): void => { socket.off('open', opened); socket.off('close', closed); this.#lifetime.signal.removeEventListener('abort', aborted); };
+      const opened = (): void => { cleanup(); resolveArg(); };
+      const closed = (): void => { cleanup(); rejectArg(new Error('webOS connection could not open.')); };
+      const aborted = (): void => { cleanup(); rejectArg(this.#failure ?? new Error('webOS connection was aborted.')); };
+      socket.once('open', opened); socket.once('close', closed); this.#lifetime.signal.addEventListener('abort', aborted, { once: true });
+      if (this.#lifetime.signal.aborted) aborted();
+    });
+  }
+
+  #request(typeArg: IPendingRequest['type'], uriArg: string | undefined, payloadArg: Record<string, unknown>, updateArg?: IPendingRequest['update'], signalArg?: AbortSignal): Promise<Record<string, unknown>> {
+    if (this.#lifetime.signal.aborted || signalArg?.aborted || this.#socket?.readyState !== plugins.ws.WebSocket.OPEN) return Promise.reject(new Error('webOS request was aborted or disconnected.'));
+    if (this.#pending.size >= this.#config.maxPendingRequests!) return Promise.reject(new Error('webOS pending request capacity reached.'));
+    const id = `shx-${++this.#sequence}`;
+    return new Promise((resolveArg, rejectArg) => {
+      const reject = (errorArg: Error): void => { const pending = this.#pending.get(id); if (!pending) return; this.#pending.delete(id); clearTimeout(pending.timer); pending.cleanup(); rejectArg(errorArg); };
+      const abort = (): void => reject(new Error('webOS request was aborted; effects already sent have an indeterminate outcome.'));
+      const timer = setTimeout(() => {
+        reject(new Error('webOS response timed out; effects already sent have an indeterminate outcome.'));
+        if (typeArg !== 'request') this.#fail(new Error('webOS handshake or subscription timed out.'));
+      }, typeArg === 'register' ? this.#config.pairingTimeoutMs : this.#config.requestTimeoutMs);
+      const cleanup = (): void => signalArg?.removeEventListener('abort', abort);
+      this.#pending.set(id, { resolve: resolveArg, reject: rejectArg, timer, cleanup, type: typeArg, update: updateArg });
+      signalArg?.addEventListener('abort', abort, { once: true });
+      this.#socket!.send(JSON.stringify({ id, type: typeArg, ...(uriArg ? { uri: `ssap://${uriArg}` } : {}), payload: payloadArg }), (errorArg) => { if (errorArg) reject(new Error('webOS send failed; effect outcome is indeterminate.')); });
+    });
+  }
+
+  #message(dataArg: plugins.ws.RawData, binaryArg: boolean): void {
+    try {
+      if (binaryArg) throw new Error('webOS sent an unsupported binary frame.');
+      const raw: unknown = JSON.parse(dataArg.toString());
+      const message = webostvObject(raw, 'webOS response');
+      if (typeof message.id !== 'string' || typeof message.type !== 'string') throw new Error('webOS response correlation is invalid.');
+      const pending = this.#pending.get(message.id);
+      const subscription = this.#subscriptions.get(message.id);
+      if (!pending && !subscription) return;
+      const payload = webostvObject(message.payload ?? {}, 'webOS payload');
+      if (message.type === 'error' || payload.returnValue === false) {
+        // Vendor errors may echo credentials; expose only a stable local failure.
+        const error = new Error('webOS rejected the request.');
+        if (pending) { this.#pending.delete(message.id); clearTimeout(pending.timer); pending.cleanup(); pending.reject(error); }
+        else this.#fail(error);
+        return;
+      }
+      if (pending?.type === 'register' && message.type === 'response' && payload.pairingType === 'PROMPT') {
+        if (this.#config.pairingMode !== 'prompt') this.#fail(new Error('webOS requires explicit prompt pairing; existing key was not accepted.'));
+        return;
+      }
+      const expected = pending?.type === 'hello' ? 'hello' : pending?.type === 'register' ? 'registered' : 'response';
+      if (message.type !== expected || ((pending?.type === 'request' || pending?.type === 'subscribe' || subscription) && payload.returnValue !== true)) throw new Error('webOS response type or acknowledgement is invalid.');
+      (pending?.update ?? subscription)?.(payload);
+      if (pending) {
+        if (pending.type === 'subscribe' && pending.update) this.#subscriptions.set(message.id, pending.update);
+        this.#pending.delete(message.id); clearTimeout(pending.timer); pending.cleanup(); pending.resolve(payload);
+      }
+    } catch { this.#fail(new Error('webOS response validation failed.')); }
+  }
+
+  #fail(errorArg: Error): void {
+    if (this.#lifetime.signal.aborted) return;
+    this.#failure = errorArg;
+    this.#emit({ type: 'error', error: errorArg });
+    for (const request of this.#pending.values()) {
+      clearTimeout(request.timer); request.cleanup();
+      request.reject(request.type === 'request' ? new Error(`${errorArg.message} Effects already sent have an indeterminate outcome.`) : errorArg);
+    }
+    this.#pending.clear();
+    void this.destroy();
+  }
+
+  #emit(eventArg: TWebostvClientEvent): void {
+    for (const handler of [...this.#handlers]) {
+      try { handler(eventArg.type === 'state' ? { ...eventArg, snapshot: structuredClone(eventArg.snapshot) } : eventArg); }
+      catch { this.#handlerCleanups.get(handler)?.(); }
+    }
   }
 }

package/ts/integrations/webostv/webostv.classes.configflow.ts

@@ -1,9 +1,22 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
+import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { createWebostvDiscoveryDescriptor } from './webostv.discovery.js';
 import type { IWebostvConfig } from './webostv.types.js';
-import { webostvProfile } from './webostv.types.js';
+import { normalizeWebostvConfig, webostvKeys, webostvObject } from './webostv.validation.js';
 
-export class WebostvConfigFlow extends SimpleLocalConfigFlow<IWebostvConfig> {
-  constructor() {
-    super(webostvProfile);
+export class WebostvConfigFlow implements IConfigFlow<IWebostvConfig> {
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IWebostvConfig>> {
+    const result = await createWebostvDiscoveryDescriptor().getValidators()[0].validate(candidateArg, contextArg);
+    if (!result.matched || !result.candidate) return { kind: 'error', error: result.reason };
+    const candidate = result.candidate;
+    return { kind: 'form', title: 'Pair verified LG webOS TV', description: 'The host must supply an encrypted database and external key provider. Prompt mode requires confirmation on the TV.',
+      fields: [{ name: 'homeId', label: 'Home id', type: 'text', required: true }, { name: 'pairingMode', label: 'Pairing mode', type: 'select', required: true, options: [{ label: 'Use durable existing pairing', value: 'existing' }, { label: 'Confirm new pairing on TV', value: 'prompt' }] }, { name: 'allowUnencryptedConnection', label: 'Allow explicit cleartext local endpoint', type: 'boolean' }],
+      submit: async (valuesArg) => {
+        try {
+          const values = webostvObject(valuesArg, 'webOS config flow values'); webostvKeys(values, ['homeId', 'pairingMode', 'allowUnencryptedConnection', 'certificateAuthority']);
+          const config = normalizeWebostvConfig({ ...values, endpoint: candidate.metadata!.endpoint, expectedDeviceUUID: candidate.metadata!.expectedDeviceUUID, name: candidate.name } as IWebostvConfig);
+          return { kind: 'done', config };
+        } catch (errorArg) { return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Invalid webOS config.' }; }
+      },
+    };
   }
 }