@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/pioneer/pioneer.validation.ts

@@ -0,0 +1,84 @@
+import * as plugins from '../../plugins.js';
+import type { IPioneerConfig, TPioneerControl } from './pioneer.types.js';
+
+export function pioneerRecord(value: unknown, allowed?: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError('Pioneer input must be a plain data object.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== 'string' || (allowed && !allowed.includes(key)) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('Pioneer input contains an unsupported field or accessor.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function pioneerText(value: unknown, label: string, maximum = 256): string {
+  if (typeof value !== 'string' || !value || value.length > maximum || value !== value.trim() || /[\p{Cc}\p{Cs}]/u.test(value)) {
+    throw new TypeError(`Pioneer ${label} must be bounded text without control characters.`);
+  }
+  return value;
+}
+
+export function pioneerHost(value: unknown): string {
+  if (typeof value !== 'string' || plugins.net.isIP(value) !== 4) throw new TypeError('Pioneer requires a selected private IPv4 address.');
+  const [first, second, , last] = value.split('.').map(Number);
+  if (!(first === 10 || first === 127 || (first === 172 && second >= 16 && second <= 31) || (first === 192 && second === 168)) || last === 0 || last === 255) {
+    throw new TypeError('Pioneer requires a selected private or loopback IPv4 host.');
+  }
+  return value;
+}
+
+export function pioneerUdn(value: unknown): string {
+  if (typeof value !== 'string' || !/^uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) throw new TypeError('Pioneer requires an exact UPnP UUID.');
+  return value.toLowerCase();
+}
+
+export function pioneerDescription(value: unknown, host: string): string {
+  const url = new URL(pioneerText(value, 'description URL', 2048));
+  if (url.protocol !== 'http:' || url.hostname !== host || url.username || url.password || url.hash || url.search || url.pathname === '/') {
+    throw new TypeError('Pioneer description must select an HTTP path at the receiver IP without credentials, query or fragment.');
+  }
+  return url.href;
+}
+
+function integer(value: unknown, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new RangeError('Pioneer numeric bound is invalid.');
+  return value;
+}
+
+export function pioneerVolume(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > 185) throw new TypeError('Pioneer volume must be a raw integer from 0 through 185.');
+  return value;
+}
+
+export const pioneerConfigKeys = ['homeId', 'host', 'descriptionUrl', 'expectedUdn', 'model', 'allowUnencryptedLan', 'maximumVolumeRaw', 'name', 'port', 'timeoutMs', 'maxPendingOperations', 'maxDescriptionBytes', 'maxFrameBytes'] as const;
+
+export function normalizePioneerConfig(value: unknown): Readonly<Required<Omit<IPioneerConfig, 'name'>> & Pick<IPioneerConfig, 'name'>> {
+  const config = pioneerRecord(value, pioneerConfigKeys);
+  const host = pioneerHost(config.host);
+  if (config.model !== 'SC-95') throw new TypeError('Pioneer model has no admitted vendor profile.');
+  if (config.allowUnencryptedLan !== true) throw new TypeError('Pioneer requires an explicit plaintext LAN acknowledgement.');
+  return Object.freeze({
+    homeId: pioneerText(config.homeId, 'home ID'), host, descriptionUrl: pioneerDescription(config.descriptionUrl, host),
+    expectedUdn: pioneerUdn(config.expectedUdn), model: config.model, allowUnencryptedLan: config.allowUnencryptedLan,
+    maximumVolumeRaw: pioneerVolume(config.maximumVolumeRaw),
+    ...(config.name === undefined ? {} : { name: pioneerText(config.name, 'name', 128) }),
+    port: integer(config.port, 23, 1, 65535), timeoutMs: integer(config.timeoutMs, 5000, 1, 60000),
+    maxPendingOperations: integer(config.maxPendingOperations, 16, 1, 128),
+    maxDescriptionBytes: integer(config.maxDescriptionBytes, 65536, 256, 1048576), maxFrameBytes: integer(config.maxFrameBytes, 512, 16, 4096),
+  });
+}
+
+export function validatePioneerControl(value: unknown): TPioneerControl {
+  const control = pioneerRecord(value, ['feature', 'value']);
+  if (control.feature === 'power' && typeof control.value === 'boolean') return { feature: 'power', value: control.value };
+  if (control.feature === 'muted' && typeof control.value === 'boolean') return { feature: 'muted', value: control.value };
+  if (control.feature === 'volume_raw') return { feature: 'volume_raw', value: pioneerVolume(control.value) };
+  if (control.feature === 'input' && typeof control.value === 'string' && /^\d{2}$/.test(control.value)) return { feature: 'input', value: control.value };
+  throw new TypeError('Pioneer supports one explicit power, mute, raw volume or observed physical input control.');
+}

package/ts/integrations/roku/readme.md

@@ -0,0 +1,95 @@
+# Roku
+
+Native local Roku ECP queries and controls for `@smarthome.exchange/integrations`. Setup binds one configured endpoint to its reported device UDN. The runtime reads device information, installed apps and the active app from the device.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Setup
+
+Install the parent package using pnpm. Import `RokuIntegration` from its public exports:
+
+```bash
+pnpm add @smarthome.exchange/integrations
+```
+
+```typescript
+import { RokuIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new RokuIntegration();
+const runtime = await integration.setup({
+  host: '192.168.1.60',
+  port: 8060,
+  udn: '015e5108-9000-1046-8035-b0a737964dfb',
+  requestTimeoutMs: 5000,
+}, {});
+
+try {
+  const [device] = await runtime.devices();
+  await runtime.callService?.({
+    domain: 'remote',
+    service: 'send_command',
+    target: { deviceId: device.id },
+    data: { command: 'Home' },
+  });
+} finally {
+  await integration.destroy();
+}
+```
+
+Read `udn` from the device's `GET /query/device-info` response. It is a UUID, distinct from the serial number in Roku's SSDP USN. Configuration requires a literal private or loopback IPv4 address, an integer TCP port, this exact UDN and an optional operation deadline of 1–60000 ms. The default port is 8060 and deadline is 5000 ms. Hostnames, URL credentials, fixture snapshots and additional configuration fields are rejected. Provision configuration through the hub's scoped configuration store; this domain does not persist application data.
+
+Every query reports fresh device state. Device and entity IDs derive from UDN, so renaming the device leaves its identity stable. `power_mode` is a read-only field containing the reported value, or `null` when absent. The active-app feature contains the reported app ID; the entity state contains the reported app name. Neither claims playback activity or an inferred power state.
+
+## Controls
+
+Services require the exact connected `deviceId` or `entityId`. Supplying both requires both to match. Empty targets, foreign targets, extra arguments and accessor properties are rejected before effects.
+
+| Service | Data | Behavior |
+| --- | --- | --- |
+| `remote.send_command` | `{ command: 'Home' }` | One supported ECP keypress. |
+| `media_player.select_source` | `{ source: '837' }` | Launch one currently installed app by its exact ID. |
+
+Feature writes support `remote_key` with a supported key name, or `active_app` with an installed app ID. The runtime checks the caller's device domain and UDN target and uses its canonical writable feature list. It does not trust caller-provided writable flags.
+
+Migrate calls to `media_player.play_pause` to an explicit `remote.send_command` request with `data: { command: 'Play' }` and the same exact device or entity target. The integration reports no authoritative playback state or app-specific playback capability, so it rejects `play_pause` without dispatching a key. Explicit remote `Play` remains available and confirms only that ECP accepted the keypress.
+
+Key names are case-sensitive: `Home`, `Rev`, `Fwd`, `Play`, `Select`, `Left`, `Right`, `Down`, `Up`, `Back`, `InstantReplay`, `Info`, `Backspace`, `Search`, `Enter`, `VolumeUp`, `VolumeDown`, and `VolumeMute`. Volume keys require `is-tv` or `supports-audio-volume-control` in the current device response. `VolumeMute` is a toggle, not a request to set a Boolean mute state. The endpoint identity is rechecked before every control; app launches also refresh the installed-app catalogue. Screensavers cannot be launched through this runtime.
+
+Success confirms an ECP HTTP acceptance with `data.confirmation: 'ecp-http'` and `data.effectOutcome: 'accepted'`. It does not confirm a physical outcome. Controls issue one POST, never retry, and never update state optimistically. A `RokuRequestError` distinguishes `not-sent`, `rejected` and `indeterminate`; callers must not replay an indeterminate effect automatically.
+
+Power controls, absolute volume, semantic play/pause or play-pause services, next/previous track, held keys, command arrays, text entry, app installation, arbitrary deep-link parameters and undocumented media-URL playback are not exposed.
+
+## Discovery and lifecycle
+
+Discovery admits passive `roku:ecp` SSDP records with a canonical Roku USN and a credential-free local HTTP origin on port 8060, or manual entries explicitly marked `integrationDomain: 'roku'`. It copies only allowlisted candidate fields and never follows LOCATION or retains arbitrary metadata. The config flow still requires the verified device-info UDN. Active SSDP probing belongs to the shared device manager and is pending its published LOCATION/lifecycle correction.
+
+The client limits each operation to its configured deadline, at most eight active operations and 256 KiB per response. XML is validated with a bounded parser; DTDs, duplicate required fields and malformed catalogues fail closed. Redirects are rejected. `devices(signal)` and `writeFeature(request, signal)` support cancellation. A setup-context signal owns the connection lifetime. Destroy aborts and joins active operations, closes every runtime owned by the integration and permanently refuses new setup or controls.
+
+ECP uses unauthenticated local HTTP. UDN matching detects endpoint changes but is not cryptographic device authentication. The hub remains responsible for home access, scoped authorization, approvals and audit receipts. Fixture verification uses local HTTP servers only; physical-device and firmware behavior has not been tested.
+
+## Protocol references
+
+[Roku's current ECP documentation](https://developer.roku.com/dev/docs/external-control-api) specifies device-info, keypress, app launch and SSDP. It documents the device setting required for keypress on Roku OS 14.1 and later. Its current command table omits `query/apps` and `query/active-app`; their maintained response contract was checked against [Home Assistant's Roku ECP client source](https://github.com/ctalkington/python-rokuecp/blob/main/src/rokuecp/rokuecp.py). Hardware compatibility for these omitted queries remains unconfirmed.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/integrations/roku/roku.classes.client.ts

@@ -1,165 +1,228 @@
-import type { IRokuApp, IRokuConfig, IRokuDeviceInfo, IRokuSnapshot, TRokuKeypress } from './roku.types.js';
+import * as plugins from '../../plugins.js';
+import type { IRokuActiveApp, IRokuApp, IRokuClientOptions, IRokuConfig, IRokuDeviceInfo, IRokuSnapshot, TRokuEffectOutcome } from './roku.types.js';
+import { normalizeRokuUdn, readRokuRecord, validateRokuAppId, validateRokuConfig, validateRokuKey } from './roku.validation.js';
+
+interface IRokuOperation {
+  signal: AbortSignal;
+  effectSent: boolean;
+}
+
+const isRecord = (inputArg: unknown): inputArg is Record<string, unknown> => typeof inputArg === 'object' && inputArg !== null && !Array.isArray(inputArg);
+const maxResponseBytes = 256 * 1024;
+
+export class RokuRequestError extends Error {
+  constructor(messageArg: string, public readonly effectOutcome: TRokuEffectOutcome) {
+    super(messageArg);
+    this.name = 'RokuRequestError';
+  }
+}
 
 export class RokuClient {
-  constructor(private readonly config: IRokuConfig) {}
+  private readonly config: IRokuConfig;
+  private readonly baseUrl: string;
+  private readonly lifetime = new AbortController();
+  private readonly ownerSignal?: AbortSignal;
+  private readonly operations = new Set<Promise<unknown>>();
+  private closePromise?: Promise<void>;
+  private readonly parser = new plugins.fastXmlParser.XMLParser({
+    ignoreAttributes: false, ignoreDeclaration: true, ignorePiTags: true,
+    parseTagValue: false, parseAttributeValue: false, trimValues: true, maxNestedTags: 8,
+    isArray: (tagArg, pathArg) => tagArg === 'app' && pathArg === 'apps.app',
+  });
+  private readonly onOwnerAbort = (): void => { void this.destroy(); };
+
+  constructor(configArg: IRokuConfig, optionsArg: IRokuClientOptions = {}) {
+    this.config = validateRokuConfig(configArg);
+    this.baseUrl = `http://${this.config.host}:${this.config.port}`;
+    const signal = readRokuRecord(optionsArg, ['abortSignal']).abortSignal;
+    if (signal !== undefined && !(signal instanceof AbortSignal)) throw new Error('Roku owner signal must be an AbortSignal.');
+    this.ownerSignal = signal;
+    this.ownerSignal?.addEventListener('abort', this.onOwnerAbort, { once: true });
+    if (this.ownerSignal?.aborted) this.onOwnerAbort();
+  }
 
-  public async getSnapshot(): Promise<IRokuSnapshot> {
-    const [deviceInfo, apps, activeApp] = await Promise.all([
-      this.getDeviceInfo(),
-      this.getApps(),
-      this.getActiveApp(),
-    ]);
-    return { deviceInfo, apps, activeApp };
+  public get isClosed(): boolean { return this.lifetime.signal.aborted; }
+
+  public getSnapshot(abortSignalArg?: AbortSignal): Promise<IRokuSnapshot> {
+    return this.runOperation(async (operationArg) => {
+      const deviceInfo = await this.readDeviceInfo(operationArg);
+      const apps = await this.readApps(operationArg);
+      const activeApp = await this.readActiveApp(operationArg);
+      return { deviceInfo, apps, activeApp, observedAt: new Date().toISOString() };
+    }, abortSignalArg);
   }
 
-  public async getDeviceInfo(): Promise<IRokuDeviceInfo> {
-    if (this.config.deviceInfo) {
-      return this.config.deviceInfo;
-    }
-    const xml = await this.requestText('/query/device-info');
-    return {
-      serialNumber: this.readXmlTag(xml, 'serial-number'),
-      deviceId: this.readXmlTag(xml, 'device-id'),
-      vendorName: this.readXmlTag(xml, 'vendor-name'),
-      modelName: this.readXmlTag(xml, 'model-name'),
-      modelNumber: this.readXmlTag(xml, 'model-number'),
-      friendlyDeviceName: this.readXmlTag(xml, 'friendly-device-name'),
-      userDeviceName: this.readXmlTag(xml, 'user-device-name'),
-      deviceType: this.readXmlTag(xml, 'device-type'),
-      softwareVersion: this.readXmlTag(xml, 'software-version'),
-      powerMode: this.readXmlTag(xml, 'power-mode'),
-      supportsSuspend: this.readXmlTag(xml, 'supports-suspend') === 'true',
-    };
+  public getDeviceInfo(abortSignalArg?: AbortSignal): Promise<IRokuDeviceInfo> {
+    return this.runOperation((operationArg) => this.readDeviceInfo(operationArg), abortSignalArg);
   }
 
-  public async getApps(): Promise<IRokuApp[]> {
-    if (this.config.apps) {
-      return this.config.apps;
-    }
-    const xml = await this.requestText('/query/apps');
-    return this.readApps(xml);
+  public getApps(abortSignalArg?: AbortSignal): Promise<IRokuApp[]> {
+    return this.runOperation(async (operationArg) => {
+      await this.readDeviceInfo(operationArg);
+      return this.readApps(operationArg);
+    }, abortSignalArg);
   }
 
-  public async getActiveApp(): Promise<IRokuApp | undefined> {
-    if (this.config.activeApp) {
-      return this.config.activeApp;
-    }
-    const xml = await this.requestText('/query/active-app');
-    return this.readApps(xml)[0];
+  public getActiveApp(abortSignalArg?: AbortSignal): Promise<IRokuActiveApp> {
+    return this.runOperation(async (operationArg) => {
+      await this.readDeviceInfo(operationArg);
+      return this.readActiveApp(operationArg);
+    }, abortSignalArg);
   }
 
-  public async keypress(keyArg: TRokuKeypress | string): Promise<void> {
-    await this.requestText(`/keypress/${encodeURIComponent(this.toEcpKey(keyArg))}`, 'POST');
+  public keypress(keyArg: string, abortSignalArg?: AbortSignal): Promise<void> {
+    const key = validateRokuKey(keyArg);
+    return this.runOperation(async (operationArg) => {
+      validateRokuKey(key, await this.readDeviceInfo(operationArg));
+      await this.requestText(`/keypress/${key}`, 'POST', operationArg);
+    }, abortSignalArg);
   }
 
-  public async launch(appIdArg: string, paramsArg: Record<string, string | number | boolean> = {}): Promise<void> {
-    const searchParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(paramsArg)) {
-      searchParams.set(key, String(value));
-    }
-    const suffix = searchParams.size ? `?${searchParams.toString()}` : '';
-    await this.requestText(`/launch/${encodeURIComponent(appIdArg)}${suffix}`, 'POST');
+  public launch(appIdArg: string, abortSignalArg?: AbortSignal): Promise<void> {
+    const appId = validateRokuAppId(appIdArg);
+    return this.runOperation(async (operationArg) => {
+      await this.readDeviceInfo(operationArg);
+      const app = (await this.readApps(operationArg)).find((appArg) => appArg.id === appId && appArg.type !== 'ssvr');
+      if (!app) throw new Error('Roku app id is not in the current installed-app catalogue.');
+      await this.requestText(`/launch/${encodeURIComponent(app.id)}`, 'POST', operationArg);
+    }, abortSignalArg);
   }
 
-  public async playUrl(urlArg: string, mediaTypeArg: 'video' | 'audio' = 'video', titleArg?: string): Promise<void> {
-    const params: Record<string, string> = {
-      u: urlArg,
-      t: mediaTypeArg === 'audio' ? 'a' : 'v',
-    };
-    if (titleArg) {
-      params[mediaTypeArg === 'audio' ? 'songName' : 'videoName'] = titleArg;
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.lifetime.abort(new DOMException('Roku client is closed.', 'AbortError'));
+      this.ownerSignal?.removeEventListener('abort', this.onOwnerAbort);
+      this.closePromise = Promise.allSettled([...this.operations]).then(() => undefined);
     }
-    await this.launch(this.config.playMediaAppId || '15985', params);
+    return this.closePromise;
   }
 
-  public async destroy(): Promise<void> {}
+  private runOperation<TValue>(operationArg: (contextArg: IRokuOperation) => Promise<TValue>, abortSignalArg?: AbortSignal): Promise<TValue> {
+    if (this.isClosed) return Promise.reject(new RokuRequestError('Roku client is closed.', 'not-sent'));
+    if (abortSignalArg?.aborted) return Promise.reject(new RokuRequestError('Roku operation was cancelled.', 'not-sent'));
+    if (this.operations.size >= 8) return Promise.reject(new RokuRequestError('Roku has reached its active-operation limit.', 'not-sent'));
+    const controller = new AbortController();
+    const onAbort = (): void => controller.abort(new DOMException('Roku operation was cancelled.', 'AbortError'));
+    this.lifetime.signal.addEventListener('abort', onAbort, { once: true });
+    abortSignalArg?.addEventListener('abort', onAbort, { once: true });
+    const timeout = setTimeout(() => controller.abort(new DOMException('Roku operation exceeded its deadline.', 'TimeoutError')), this.config.requestTimeoutMs);
+    const context: IRokuOperation = { signal: controller.signal, effectSent: false };
+    const result = Promise.resolve().then(() => operationArg(context)).catch((errorArg: unknown) => {
+      if (errorArg instanceof RokuRequestError) throw errorArg;
+      const reason: unknown = controller.signal.aborted ? controller.signal.reason : errorArg;
+      const message = reason instanceof Error ? reason.message : 'Roku operation failed.';
+      throw new RokuRequestError(message, context.effectSent ? 'indeterminate' : 'not-sent');
+    }).finally(() => {
+      clearTimeout(timeout);
+      this.lifetime.signal.removeEventListener('abort', onAbort);
+      abortSignalArg?.removeEventListener('abort', onAbort);
+      this.operations.delete(result);
+    });
+    this.operations.add(result);
+    return result;
+  }
 
-  private async requestText(pathArg: string, methodArg: 'GET' | 'POST' = 'GET'): Promise<string> {
-    if (!this.config.host) {
-      throw new Error('Roku host is required when fixture data is not provided.');
-    }
-    const response = await globalThis.fetch(`${this.baseUrl()}${pathArg}`, { method: methodArg });
-    const text = await response.text();
+  private async requestText(pathArg: string, methodArg: 'GET' | 'POST', operationArg: IRokuOperation): Promise<string> {
+    operationArg.signal.throwIfAborted();
+    if (methodArg === 'POST') operationArg.effectSent = true;
+    const response = await globalThis.fetch(`${this.baseUrl}${pathArg}`, {
+      method: methodArg, redirect: 'error', signal: operationArg.signal,
+      headers: { accept: 'application/xml, text/xml' },
+    });
     if (!response.ok) {
-      throw new Error(`Roku request ${pathArg} failed with HTTP ${response.status}: ${text}`);
+      await response.body?.cancel();
+      throw new RokuRequestError(`Roku ECP returned HTTP ${response.status}.`, methodArg === 'POST' && response.status >= 400 && response.status < 500 ? 'rejected' : operationArg.effectSent ? 'indeterminate' : 'not-sent');
+    }
+    const reader = response.body?.getReader();
+    if (!reader) return '';
+    const chunks: Uint8Array[] = [];
+    let bytes = 0;
+    let completed = false;
+    try {
+      while (true) {
+        const next = await reader.read();
+        if (next.done) { completed = true; break; }
+        bytes += next.value.byteLength;
+        if (bytes > maxResponseBytes) throw new Error('Roku ECP response exceeds 256 KiB.');
+        chunks.push(next.value);
+      }
+      const decoder = new TextDecoder('utf-8', { fatal: true });
+      return chunks.map((chunkArg) => decoder.decode(chunkArg, { stream: true })).join('') + decoder.decode();
+    } finally {
+      if (!completed) await reader.cancel().catch(() => undefined);
+      reader.releaseLock();
     }
-    return text;
   }
 
-  private readApps(xmlArg: string): IRokuApp[] {
-    const apps: IRokuApp[] = [];
-    const regex = /<app\s+([^>]*)>([\s\S]*?)<\/app>/g;
-    let match: RegExpExecArray | null;
-    while ((match = regex.exec(xmlArg))) {
-      const attrs = this.readAttributes(match[1]);
-      const id = attrs.id;
-      if (!id) {
-        continue;
-      }
-      apps.push({
-        id,
-        name: this.unescapeXml(match[2].trim()),
-        type: attrs.type,
-        version: attrs.version,
-      });
+  private parseRoot(xmlArg: string, rootNameArg: string): unknown {
+    if (/<!\s*(?:DOCTYPE|ENTITY)/i.test(xmlArg) || plugins.fastXmlParser.XMLValidator.validate(xmlArg) !== true) {
+      throw new Error('Roku ECP returned malformed XML.');
     }
-    return apps;
+    const parsed: unknown = this.parser.parse(xmlArg);
+    if (!isRecord(parsed) || Object.keys(parsed).length !== 1 || !(rootNameArg in parsed)) {
+      throw new Error(`Roku ECP response must have one ${rootNameArg} root.`);
+    }
+    return parsed[rootNameArg];
   }
 
-  private readAttributes(valueArg: string): Record<string, string> {
-    const attrs: Record<string, string> = {};
-    const regex = /([a-zA-Z0-9_-]+)="([^"]*)"/g;
-    let match: RegExpExecArray | null;
-    while ((match = regex.exec(valueArg))) {
-      attrs[match[1]] = this.unescapeXml(match[2]);
+  private textField(recordArg: Record<string, unknown>, fieldArg: string): string | undefined {
+    const value = recordArg[fieldArg];
+    if (value === undefined) return undefined;
+    if (typeof value !== 'string' || value.length > 1024 || /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(value)) {
+      throw new Error('Roku ECP returned an invalid text field.');
     }
-    return attrs;
-  }
-
-  private readXmlTag(xmlArg: string, tagArg: string): string | undefined {
-    const escapedTag = tagArg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const regex = new RegExp(`<${escapedTag}>([\\s\\S]*?)<\\/${escapedTag}>`, 'i');
-    const match = regex.exec(xmlArg);
-    return match?.[1] ? this.unescapeXml(match[1].trim()) : undefined;
-  }
-
-  private toEcpKey(keyArg: string): string {
-    const normalized = keyArg.replace(/[_\s-]+/g, '').toLowerCase();
-    const keys: Record<string, TRokuKeypress> = {
-      home: 'Home',
-      rev: 'Rev',
-      reverse: 'Rev',
-      fwd: 'Fwd',
-      forward: 'Fwd',
-      play: 'Play',
-      pause: 'Play',
-      select: 'Select',
-      left: 'Left',
-      right: 'Right',
-      down: 'Down',
-      up: 'Up',
-      back: 'Back',
-      instantreplay: 'InstantReplay',
-      info: 'Info',
-      backspace: 'Backspace',
-      search: 'Search',
-      enter: 'Enter',
-      poweron: 'PowerOn',
-      poweroff: 'PowerOff',
-      power: 'Power',
-      volumeup: 'VolumeUp',
-      volumedown: 'VolumeDown',
-      volumemute: 'VolumeMute',
-      mute: 'VolumeMute',
+    return value;
+  }
+
+  private booleanField(recordArg: Record<string, unknown>, fieldArg: string): boolean | undefined {
+    const value = this.textField(recordArg, fieldArg);
+    if (value === undefined) return undefined;
+    if (value !== 'true' && value !== 'false') throw new Error('Roku ECP returned an invalid boolean field.');
+    return value === 'true';
+  }
+
+  private async readDeviceInfo(operationArg: IRokuOperation): Promise<IRokuDeviceInfo> {
+    const record = this.parseRoot(await this.requestText('/query/device-info', 'GET', operationArg), 'device-info');
+    if (!isRecord(record)) throw new Error('Roku device-info is not an object.');
+    const udn = normalizeRokuUdn(this.textField(record, 'udn'));
+    if (udn !== this.config.udn) throw new Error('Roku endpoint no longer reports the configured UDN.');
+    const vendorName = this.textField(record, 'vendor-name');
+    if (vendorName !== undefined && vendorName !== 'Roku') throw new Error('Roku endpoint reports a different vendor.');
+    return {
+      udn, vendorName, serialNumber: this.textField(record, 'serial-number'), deviceId: this.textField(record, 'device-id'),
+      modelName: this.textField(record, 'model-name'), modelNumber: this.textField(record, 'model-number'),
+      friendlyDeviceName: this.textField(record, 'friendly-device-name'), userDeviceName: this.textField(record, 'user-device-name'),
+      softwareVersion: this.textField(record, 'software-version'), powerMode: this.textField(record, 'power-mode'),
+      isTv: this.booleanField(record, 'is-tv'), supportsAudioVolumeControl: this.booleanField(record, 'supports-audio-volume-control'),
     };
-    return keys[normalized] || keyArg;
   }
 
-  private baseUrl(): string {
-    return `http://${this.config.host}:${this.config.port || 8060}`;
+  private parseApp(inputArg: unknown, requireIdArg: boolean): IRokuActiveApp {
+    if (typeof inputArg === 'string' && !requireIdArg && inputArg.length > 0 && inputArg.length <= 1024) return { name: inputArg };
+    if (!isRecord(inputArg)) throw new Error('Roku ECP returned an invalid app entry.');
+    const name = this.textField(inputArg, '#text');
+    if (!name) throw new Error('Roku app entry has no name.');
+    const id = this.textField(inputArg, '@_id');
+    if (requireIdArg || id !== undefined) validateRokuAppId(id);
+    return { id, name, type: this.textField(inputArg, '@_type'), version: this.textField(inputArg, '@_version') ?? this.textField(inputArg, '@_Version') };
+  }
+
+  private async readApps(operationArg: IRokuOperation): Promise<IRokuApp[]> {
+    const root = this.parseRoot(await this.requestText('/query/apps', 'GET', operationArg), 'apps');
+    if (root === '') return [];
+    if (!isRecord(root) || !Array.isArray(root.app) || root.app.length > 2048) throw new Error('Roku apps catalogue is malformed.');
+    const apps: IRokuApp[] = [];
+    for (const entry of root.app) {
+      const app = this.parseApp(entry, true);
+      if (!app.id || apps.some((existingArg) => existingArg.id === app.id)) throw new Error('Roku apps catalogue has duplicate or missing ids.');
+      apps.push({ id: app.id, name: app.name, type: app.type, version: app.version });
+    }
+    return apps;
   }
 
-  private unescapeXml(valueArg: string): string {
-    return valueArg.replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&gt;/g, '>').replace(/&lt;/g, '<').replace(/&amp;/g, '&');
+  private async readActiveApp(operationArg: IRokuOperation): Promise<IRokuActiveApp> {
+    const root = this.parseRoot(await this.requestText('/query/active-app', 'GET', operationArg), 'active-app');
+    if (!isRecord(root)) throw new Error('Roku active-app response is malformed.');
+    return this.parseApp(root.app, false);
   }
 }

package/ts/integrations/roku/roku.classes.configflow.ts

@@ -1,25 +1,32 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { IRokuConfig } from './roku.types.js';
+import { RokuCandidateValidator } from './roku.discovery.js';
+import { readRokuRecord, validateRokuConfig } from './roku.validation.js';
 
 export class RokuConfigFlow implements IConfigFlow<IRokuConfig> {
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IRokuConfig>> {
     void contextArg;
+    const candidate = await new RokuCandidateValidator().validate(candidateArg);
+    if (!candidate.matched || !candidate.candidate) return { kind: 'error', error: 'Roku setup requires an admitted Roku candidate.' };
+    const host = candidate.candidate.host;
+    const port = candidate.candidate.port;
     return {
-      kind: 'form',
-      title: 'Connect Roku',
-      description: 'Configure the local Roku External Control Protocol endpoint.',
+      kind: 'form', title: 'Connect Roku',
+      description: 'Enter the UDN reported by query/device-info. Setup verifies this identity before exposing the device.',
       fields: [
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'Port', type: 'number' },
+        { name: 'host', label: 'Local IPv4 address', type: 'text', required: true },
+        { name: 'port', label: 'ECP port', type: 'number' },
+        { name: 'udn', label: 'Device UDN', type: 'text', required: true },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'Roku configured',
-        config: {
-          host: String(valuesArg.host || candidateArg.host || ''),
-          port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port || 8060,
-        },
-      }),
+      submit: async (valuesArg) => {
+        try {
+          const values = readRokuRecord(valuesArg, ['host', 'port', 'udn']);
+          const config = validateRokuConfig({ host: values.host ?? host, port: values.port ?? port, udn: values.udn });
+          return { kind: 'done', title: 'Roku configured', config };
+        } catch (errorArg) {
+          return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Invalid Roku configuration.' };
+        }
+      },
     };
   }
 }