@smarthome.exchange/integrations 2.0.0 → 3.0.0

package/ts/integrations/mqtt/mqtt.validation.ts

@@ -0,0 +1,157 @@
+import { validateMqttTopic } from './mqtt.classes.client.js';
+import type { IMqttConfig, IMqttTopicMapping, IMqttTransportCredentials } from './mqtt.types.js';
+
+export const mqttRecord = (valueArg: unknown, allowedArg: readonly string[]): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object'
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new TypeError('MQTT configuration must be a plain data object.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !allowedArg.includes(key) || !descriptor?.enumerable || !('value' in descriptor)) {
+      throw new TypeError('MQTT configuration contains an unsupported field or accessor.');
+    }
+    result[key] = descriptor.value as unknown;
+  }
+  return result;
+};
+
+export const mqttText = (valueArg: unknown, maximumArg = 256): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.trim() !== valueArg
+    || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError('MQTT identifier must be a bounded non-empty string without whitespace or control characters.');
+  }
+  return valueArg;
+};
+
+const integer = (valueArg: unknown, maximumArg: number, minimumArg = 1): number | undefined => {
+  if (valueArg === undefined) return undefined;
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError('MQTT numeric configuration is out of range.');
+  }
+  return valueArg;
+};
+
+const mapping = (valueArg: unknown): IMqttTopicMapping => {
+  const value = mqttRecord(valueArg, ['deviceId', 'entityId', 'featureId', 'name', 'deviceName', 'stateTopic', 'availabilityTopic', 'payloadAvailable']);
+  const stateTopic = mqttText(value.stateTopic, 65535);
+  const availabilityTopic = value.availabilityTopic === undefined ? undefined : mqttText(value.availabilityTopic, 65535);
+  validateMqttTopic(stateTopic);
+  if (availabilityTopic) validateMqttTopic(availabilityTopic);
+  if (value.payloadAvailable !== undefined && (typeof value.payloadAvailable !== 'string' || Buffer.byteLength(value.payloadAvailable) > 4096)) {
+    throw new TypeError('MQTT availability payload must be a bounded UTF-8 string.');
+  }
+  const payloadAvailable = typeof value.payloadAvailable === 'string' ? value.payloadAvailable : undefined;
+  if (payloadAvailable !== undefined && availabilityTopic === undefined) throw new TypeError('MQTT availability payload requires its exact topic.');
+  return Object.freeze({ deviceId: mqttText(value.deviceId), entityId: mqttText(value.entityId), featureId: mqttText(value.featureId),
+    name: mqttText(value.name), deviceName: mqttText(value.deviceName), stateTopic, availabilityTopic, payloadAvailable });
+};
+
+/** Capture data without invoking nested accessors before host admission. */
+const mqttData = (valueArg: unknown): unknown => {
+  const seen = new Set<object>();
+  let entries = 0;
+  const copy = (value: unknown, depth: number): unknown => {
+    if (++entries > 200000 || depth > 32) throw new TypeError('MQTT configuration data exceeds its bounds.');
+    if (value === null || value === undefined || typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value !== 'object' || seen.has(value)) throw new TypeError('MQTT configuration requires finite acyclic data.');
+    seen.add(value);
+    try {
+      if (Array.isArray(value)) {
+        if (Reflect.ownKeys(value).length !== value.length + 1) throw new TypeError('MQTT configuration arrays require exact data entries.');
+        const result: unknown[] = [];
+        for (let index = 0; index < value.length; index++) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+          if (!descriptor?.enumerable || !('value' in descriptor)) throw new TypeError('MQTT configuration arrays cannot contain accessors or holes.');
+          result.push(copy(descriptor.value as unknown, depth + 1));
+        }
+        return result;
+      }
+      if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        throw new TypeError('MQTT configuration requires plain data objects.');
+      }
+      const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+      for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key !== 'string' || !descriptor?.enumerable || !('value' in descriptor)) throw new TypeError('MQTT configuration cannot contain accessors.');
+        result[key] = copy(descriptor.value as unknown, depth + 1);
+      }
+      return result;
+    } finally { seen.delete(value); }
+  };
+  return copy(valueArg, 0);
+};
+
+export const normalizeMqttIntegrationConfig = (valueArg: unknown): IMqttConfig & { homeId: string } => {
+  const fields = mqttRecord(valueArg, ['homeId', 'mode', 'host', 'port', 'protocol', 'credentialKey', 'allowUnencryptedLan', 'mappings',
+    'clientId', 'keepalive', 'clean', 'discovery', 'discoveryPrefix', 'birthMessage', 'willMessage', 'subscriptions',
+    'discoveryMessages', 'retainedMessages', 'entities', 'connectTimeoutMs', 'operationTimeoutMs', 'reconnectPeriodMs',
+    'maxMessageTopics', 'maxPayloadBytes', 'maxBufferedBytes']);
+  const value = mqttData(fields) as Record<string, unknown>;
+  const homeId = mqttText(value.homeId);
+  if (value.mode !== undefined && value.mode !== 'discovery' && value.mode !== 'selected-topics') throw new TypeError('Unsupported MQTT mapping mode.');
+  if (value.protocol !== undefined && value.protocol !== 'mqtt' && value.protocol !== 'mqtts') throw new TypeError('Unsupported MQTT transport.');
+  const protocol = value.protocol === 'mqtts' ? 'mqtts' : 'mqtt';
+  const host = value.host === undefined ? undefined : mqttText(value.host, 253);
+  if (host && (/[\s/@?#\\:]/u.test(host) || host === '.')) throw new TypeError('MQTT host must be a selected hostname or IPv4 address, without URL or credentials.');
+  if (value.allowUnencryptedLan !== undefined && typeof value.allowUnencryptedLan !== 'boolean') throw new TypeError('MQTT LAN consent must be explicit.');
+  if (host && protocol === 'mqtt' && value.allowUnencryptedLan !== true) throw new TypeError('Unencrypted MQTT requires explicit LAN consent.');
+  const credentialKey = value.credentialKey === undefined ? undefined : mqttText(value.credentialKey);
+  const port = integer(value.port, 65535) ?? (protocol === 'mqtts' ? 8883 : 1883);
+  integer(value.connectTimeoutMs, 2147483647);
+  integer(value.operationTimeoutMs, 2147483647);
+  integer(value.reconnectPeriodMs, 2147483647, 0);
+  integer(value.keepalive, 65535, 0);
+  const topicLimit = integer(value.maxMessageTopics, 100000) ?? 4096;
+  integer(value.maxPayloadBytes, 16777216);
+  integer(value.maxBufferedBytes, 1073741824);
+  if (value.clean !== undefined && typeof value.clean !== 'boolean') throw new TypeError('MQTT clean session must be a boolean.');
+  if (value.discovery !== undefined && typeof value.discovery !== 'boolean') throw new TypeError('MQTT discovery must be a boolean.');
+  if (value.clientId !== undefined) mqttText(value.clientId);
+  if (value.clean === false && value.clientId === undefined) throw new TypeError('Persistent MQTT sessions require an explicit client ID.');
+  if (value.mode === 'selected-topics') {
+    if (!host || !Array.isArray(value.mappings) || !value.mappings.length || value.mappings.length > topicLimit) {
+      throw new TypeError('Selected MQTT requires a broker and bounded explicit mappings.');
+    }
+    if (value.discovery === true || value.birthMessage !== undefined && value.birthMessage !== false
+      || value.willMessage !== undefined && value.willMessage !== false || value.clean === false
+      || value.reconnectPeriodMs !== undefined && value.reconnectPeriodMs !== 0
+      || ['subscriptions', 'discoveryMessages', 'retainedMessages', 'entities', 'discoveryPrefix'].some((key) => value[key] !== undefined)) {
+      throw new TypeError('Selected MQTT mappings cannot enable discovery, broker effects, fixtures or persistent sessions.');
+    }
+    const mappings = value.mappings.map((itemArg: unknown) => mapping(itemArg));
+    const entities = new Set<string>();
+    const features = new Set<string>();
+    const devices = new Map<string, string>();
+    for (const item of mappings) {
+      const feature = JSON.stringify([item.deviceId, item.featureId]);
+      if (entities.has(item.entityId) || features.has(feature) || devices.has(item.deviceId) && devices.get(item.deviceId) !== item.deviceName) {
+        throw new TypeError('Selected MQTT mappings require unique entities/features and consistent device names.');
+      }
+      entities.add(item.entityId); features.add(feature); devices.set(item.deviceId, item.deviceName);
+    }
+    const subscriptions = [...new Set(mappings.flatMap((item) => [item.stateTopic, ...(item.availabilityTopic ? [item.availabilityTopic] : [])]))];
+    if (subscriptions.length > topicLimit) throw new TypeError('Selected MQTT topic limit exceeded.');
+    return Object.freeze({ ...structuredClone(value) as IMqttConfig, homeId, host, port, protocol, credentialKey,
+      mode: 'selected-topics', mappings, discovery: false, birthMessage: false, willMessage: false,
+      clean: true, reconnectPeriodMs: 0 });
+  }
+  if (value.mappings !== undefined) throw new TypeError('MQTT mappings require selected-topics mode.');
+  return Object.freeze({ ...structuredClone(value) as IMqttConfig, homeId, host, port, protocol, credentialKey, mode: 'discovery' });
+};
+
+export const mqttCredentials = (valueArg: unknown): IMqttTransportCredentials => {
+  const value = mqttRecord(valueArg, ['username', 'password', 'ca', 'cert', 'key', 'servername']);
+  const result: IMqttTransportCredentials = {};
+  for (const key of ['username', 'password', 'ca', 'cert', 'key', 'servername'] as const) {
+    const item = value[key];
+    if (item === undefined) continue;
+    if (typeof item !== 'string' || item.length > 1048576 || item.includes('\u0000')) throw new TypeError('MQTT caller credentials are invalid.');
+    result[key] = item;
+  }
+  if ((result.cert === undefined) !== (result.key === undefined)) throw new TypeError('MQTT client certificate and key must be supplied together.');
+  if (result.servername !== undefined) mqttText(result.servername, 253);
+  return result;
+};

package/ts/integrations/mqtt/readme.md

@@ -2,7 +2,9 @@
 
 `MqttIntegration` connects directly to a broker over MQTT 3.1.1 TCP or TLS through MQTT.js. No Home Assistant server or access token is involved. Setup completes after broker connection and owned subscription acknowledgements. MQTT has no end marker for retained discovery replay; newly received discovery produces normalized events and later snapshots.
 
-Configuration accepts `host`, `port`, `protocol: 'mqtt' | 'mqtts'`, `username`, `password`, `clientId`, `clean`, and `keepalive`. TLS verifies certificates by default. Persistent sessions require an explicit client ID. Credentials remain in runtime configuration; this integration does not persist them.
+Construct `MqttIntegration` with an optional host-home consistency binding. A selected `credentialKey` requires an explicit constructor `resolveCredentials` callback; a connection without credentials needs neither resolver nor store. Setup and config-flow start require an independently selected `context.homeId`; configuration `homeId` must match it. Configuration accepts endpoint, `credentialKey`, mapping and transport limits, with an explicit `allowUnencryptedLan: true` acknowledgment for plain MQTT. MQTTS is the flow default. Persist credential references rather than usernames, passwords, private CA or client key material. The borrowed resolver receives immutable `{ homeId, credentialKey, signal, deadline }`, with an absolute `performance.now()` deadline, and returns runtime-only `{ username?, password?, ca?, cert?, key?, servername? }` strings. Certificate and key must be supplied together. The caller resolver can retrieve an encrypted credential record through its own actual `NoSqlConfigStore` public API. Any store supplied in native context must match the admitted home and MQTT domain. The integration does not read credentials from context storage automatically or substitute it for a missing resolver. TLS verifies the certificate and hostname. No secret files are read, and provider, database and store remain caller-owned.
+
+Construction is inert. Setup, config-flow work, live runtimes and failed cleanup share the native owner capacity, default 16. Terminal destruction publishes a stable promise before abort and joins actual provider callbacks even after caller cancellation or deadline. A provider that never settles keeps cleanup pending; a late unrelated rejection remains observable through sanitized cleanup. Explicit `retryCleanup()` retries cleanup only, without resolving credentials, reconnecting, subscribing or publishing again.
 
 Discovery defaults to `homeassistant/#`. Both single-component and device discovery messages are supported, including abbreviations and topic bases. The latest configuration for each discovery topic replaces its predecessor; an empty payload removes it. State, availability, and attribute topics are subscribed dynamically and removed when no longer referenced. Availability lists support `all`, `any`, and `latest`. A disconnected broker marks its devices unavailable immediately.
 
@@ -12,17 +14,24 @@ The adapter reads supported canonical platforms. Writes support default-schema p
 
 Snapshots retain one latest message per topic, bounded by `maxMessageTopics` (4096), `maxPayloadBytes` (262144), and `maxBufferedBytes` (8388608). A limit violation closes the owned connection. These settings bound application snapshots, not broker retention or the protocol library's frame parser.
 
+The reusable low-level `MqttClient` preserves its first-argument username/password configuration API. Its optional second argument accepts runtime-only `IMqttTransportCredentials` for CA/mTLS use; the integration configuration migration above does not remove that raw-client API.
+
 `MqttClient` is reusable by native integrations:
 
 - `start(signal?)`, `publish(options, signal?)`, and `subscribe(filter, handler?, signal?)` are bounded operations.
 - `subscribe` callbacks receive only matching topics. Its returned asynchronous cleanup sends UNSUBSCRIBE after the final owner releases the filter.
 - `connected`, `isHealthy()`, and `onConnectionState(handler)` expose subscription readiness and connection loss.
 - `onMessage(handler)` observes messages on owned subscriptions without subscribing to the entire broker.
-- `getSnapshot(signal?)` returns current discovery and state.
-- `destroy()` closes resources and is terminal and idempotent.
+- `getSnapshot(signal?)` preserves historical discovery and state metadata.
+- Synchronous `getCurrentSnapshot()` clones only observations from the current live broker connection. Register state/message handlers before seeding readiness from it; fixtures and earlier connections are excluded, while current retained packets received before SUBACK are included. Eligibility clears before disconnect/error callbacks.
+- `destroy()` closes resources and keeps its terminal promise, including its original failure. Explicit `retryCleanup()` retries retained transport cleanup without replaying connection setup, subscriptions or publishes.
 
 Abort or timeout closes the physical connection that owns the operation before rejection; an explicit subsequent `start()` can establish a fresh connection. A stale operation cannot close a later connection generation. Subscriber cleanup is independent of transport destruction.
 
 For an ecosystem that owns its own MQTT topics, set `discovery: false`, `birthMessage: false`, and `willMessage: false`, then subscribe only its selected topics. Fixture snapshots remain supported through `entities`, `discoveryMessages`, and `retainedMessages`; they do not claim a healthy broker connection.
 
+Selected-topic mode uses `mode: 'selected-topics'` and explicit non-empty mappings with owner-selected device, entity and feature IDs, names and one exact `stateTopic`; optional exact `availabilityTopic` uses `payloadAvailable`, default `online`. Payloads remain raw UTF-8 strings and all mapped features are read-only sensors. Only the mapping topic union is subscribed. Wildcards, caller subscription arrays, discovery, birth/will, fixture snapshots, persistent sessions, reconnect and generic publish are refused in this mode. Unselected messages are ignored before caching. Disconnect immediately marks observations unavailable and requires a newly admitted setup. Mapping IDs and broker observations do not attest physical device identity.
+
+Discovery mode remains the default and preserves the existing discovery/control surface. Connection loss during an admitted publish closes that owning connection generation before MQTT.js can replay an unacknowledged effect. Subscription-only reconnection remains supported; old-generation cancellation and cleanup cannot close a successor. No broker acknowledgment proves physical execution or application-level deduplication.
+
 References: [MQTT.js 5.16.0](https://github.com/mqttjs/MQTT.js/tree/v5.16.0), [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/), and [MQTT 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html).

package/ts/integrations/samsungtv/readme.md

@@ -1,11 +1,11 @@
 # Samsung Smart TV
 
-The native integration consumes `SamsungTvProtocol` from published `@ecobridge.xyz/devicemanager`. It owns configuration, encrypted pairing and smarthome mapping; the dependency owns HTTP/TLS/WebSocket parsing, identity verification, operation deadlines and transport cleanup.
+The native integration consumes `SamsungTvProtocol` from published `@ecobridge.xyz/devicemanager` 4.11.1. It owns configuration, encrypted pairing, home admission and smarthome mapping; the dependency owns HTTP/TLS/WebSocket parsing, identity verification, operation deadlines and transport cleanup.
 
 Configure an exact `homeId`, the UUID reported by the TV, explicit `httpOrigin` and `websocketOrigin`, and `pairingMode: 'prompt' | 'existing'`. WSS certificate and hostname verification are mandatory. `certificateAuthority` adds an explicitly trusted PEM CA chain; it never disables verification. REST and WSS must use the same host. Local HTTP discovery requires `allowUnencryptedLocalDiscovery: true` and is restricted by the protocol to literal private/link-local/loopback IPv4 or ULA/loopback IPv6. HTTP carries no token or credentials and follows no redirects.
 
 ```typescript
-const integration = new SamsungtvIntegration({ db, keyProvider });
+const integration = new SamsungtvIntegration({ homeId: 'home-one', db, keyProvider });
 const runtime = await integration.setup({
   homeId: 'home-one',
   expectedDeviceId: '2ff68485-c4cb-48c7-a6ac-9c50e44d7084',
@@ -14,14 +14,20 @@ const runtime = await integration.setup({
   certificateAuthority: trustedTvCa,
   allowUnencryptedLocalDiscovery: true,
   pairingMode: 'prompt',
-}, {});
+}, { homeId: 'home-one' });
 ```
 
-The database and external encryption key provider are caller-owned. The default registry constructor instead accepts a context `NoSqlConfigStore` scoped to the exact configured home and `samsungtv` domain. Generic stores and incorrect scopes are rejected. Pairing credentials never appear in config flow results, snapshots, entities or logs. Confirmed tokens are saved through encrypted document models before controls become ready, and are bound to the exact UUID and WSS origin. Existing mode requires prior pairing in the same home. Runtime destroy leaves caller-owned stores/databases open, drains accepted persistence and transports, clears the protocol reference and is terminal. No filesystem application state is written. Clearing JavaScript references does not guarantee physical string zeroization.
+Every setup and config flow requires an independently host-selected context `homeId`. Configuration must match that selection. An optional constructor `homeId` prebinds the integration; otherwise the first valid admission binds it for its lifetime. Another home requires another integration instance. Constructor options, configuration, context, discovery hints and controls are captured as data fields before asynchronous work; accessors cannot supply authority. Config forms derive their home from the captured host context, and integration or flow destruction invalidates outstanding forms.
+
+The standalone `SamsungtvClient` accepts `ISamsungtvClientOptions` containing `{ db, keyProvider }`, or an actual scoped `NoSqlConfigStore`. The integration's `homeId` and `capacity` options belong to `ISamsungtvIntegrationOptions`.
+
+The database and external encryption key provider are caller-owned. The default registry constructor instead accepts a context `NoSqlConfigStore` scoped to the exact configured home and `samsungtv` domain. Generic stores, incorrect scopes and overridden scope claims are rejected. Pairing credentials never appear in config flow results, snapshots, entities or logs. Confirmed tokens are saved through encrypted document models before controls become ready, and are bound to the exact UUID and WSS origin. Existing mode requires prior pairing in the same home. Runtime destroy leaves caller-owned stores/databases open, drains accepted persistence and transports, clears the protocol reference after successful cleanup and is terminal. No filesystem application state is written. Clearing JavaScript references does not guarantee physical string zeroization.
+
+The native owner tracks accepted setup operations, runtimes and failed cleanup under one `capacity` limit (default 16). Cleanup is registered before startup and transferred to the runtime only after successful setup. Integration destruction joins pending setups and every runtime; a failed cleanup retains its handle and capacity until explicit `integration.retryCleanup()`. Client and protocol close promises are published before synchronous abort callbacks and preserve their original result. A late pairing-persistence failure becomes a safe `PERSISTENCE_FAILED` cleanup error. The client also drains its owned encrypted store even when protocol cleanup fails. `client.retryCleanup()` requires terminal destruction and acknowledges settled cleanup through the published protocol/store APIs. Neither cleanup API repeats pairing, token persistence, startup or commands, and neither reopens a destroyed owner. A failed setup can free retained capacity through the integration's cleanup API while an otherwise open integration remains available for an explicitly requested new setup.
 
 Every snapshot reads the current device information and observed power. Failed reads propagate; no manual fallback, guessed playback/source/volume, optimistic state or synthetic availability is produced. Device and entity IDs include the escaped home and exact TV UUID. `power` is read-only; `remote_key` admits one exact currently supported `KEY_` code. Directional keys additionally require the TV's current capability declaration.
 
-Services require the exact owned `deviceId` or `entityId`. Supported media-player services are `turn_off`, `media_play`, `media_pause`, `media_stop`, `volume_up` and `volume_down`. `remote.send_command` accepts exactly `{ command: 'KEY_HOME' }`; `samsungtv.send_key` accepts exactly `{ key: 'KEY_HOME' }`. `samsungtv.snapshot` accepts no data fields. Commands return `{ key, transport: 'sent', effectOutcome: 'indeterminate' }`: Samsung's remote channel does not acknowledge physical effects. Errors retain the protocol's safe code and effect outcome. No command is retried, repeated or replayed and concurrent effects are rejected.
+Services require the exact owned `deviceId` or `entityId`; when both are present, both must match. Feature writes require the exact owned device and writable `remote_key` media feature, with current key capability rechecked by the protocol. Destruction permanently refuses observations and controls. Supported media-player services are `turn_off`, `media_play`, `media_pause`, `media_stop`, `volume_up` and `volume_down`. `remote.send_command` accepts exactly `{ command: 'KEY_HOME' }`; `samsungtv.send_key` accepts exactly `{ key: 'KEY_HOME' }`. `samsungtv.snapshot` accepts no data fields. Commands return `{ key, transport: 'sent', effectOutcome: 'indeterminate' }`: Samsung's remote channel does not acknowledge physical effects. Errors retain the protocol's safe code and effect outcome. No command is retried, repeated or replayed and concurrent effects are rejected.
 
 The previous fixture config, plaintext token/host/port config, arbitrary WebSocket command, repeated keys and optimistic media fields have been removed. Reconfigure using the explicit native config above. `play_pause`, absolute mute/volume assignment, source/app selection, channel keys as track controls, power-on/Wake-on-LAN, press/hold/release, legacy TCP/PIN and Frame Art Mode remain unsupported. An explicit `KEY_MUTE` command is a toggle and is never presented as a boolean mute assignment.
 

package/ts/integrations/samsungtv/samsungtv.classes.client.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../../plugins.js';
 import { NoSqlConfigStore } from '../../core/classes.configstore.js';
-import type { ISamsungtvConfig, ISamsungtvIntegrationOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
+import type { ISamsungtvConfig, ISamsungtvClientOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
 import { normalizeSamsungtvConfig, samsungtvKeys, samsungtvObject, samsungtvString } from './samsungtv.validation.js';
 
 interface IStoredPairing {
@@ -18,24 +18,27 @@ export class SamsungtvClient {
   #protocol?: plugins.ecobridgeDeviceManager.SamsungTvProtocol;
   #start?: Promise<void>;
   #destroy?: Promise<void>;
+  #retryCleanup?: Promise<void>;
   #removeAbort: () => void = () => undefined;
 
-  constructor(configArg: ISamsungtvConfig, optionsArg?: ISamsungtvIntegrationOptions | NoSqlConfigStore, signalArg?: AbortSignal) {
+  constructor(configArg: ISamsungtvConfig, optionsArg?: ISamsungtvClientOptions | NoSqlConfigStore, signalArg?: AbortSignal) {
     this.#config = normalizeSamsungtvConfig(configArg);
     if (optionsArg instanceof NoSqlConfigStore) {
-      const scope = optionsArg.getScope();
+      const scope = NoSqlConfigStore.prototype.getScope.call(optionsArg);
       if (scope.homeId !== this.#config.homeId || scope.integrationDomain !== 'samsungtv') {
         throw new TypeError('Samsung TV requires an encrypted NoSqlConfigStore scoped to the exact configured home and samsungtv domain.');
       }
       this.#store = optionsArg;
       this.#ownsStore = false;
     } else {
-      if (!optionsArg?.db || !optionsArg.keyProvider) throw new TypeError('Samsung TV 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: 'samsungtv' });
+      const options = samsungtvObject(optionsArg ?? {}, 'Samsung TV client persistence options');
+      samsungtvKeys(options, ['db', 'keyProvider']);
+      if (!options.db || !options.keyProvider) throw new TypeError('Samsung TV requires an owner-supplied database and external encryption key provider.');
+      this.#store = new NoSqlConfigStore({ db: options.db as ISamsungtvClientOptions['db'], keyProvider: options.keyProvider as ISamsungtvClientOptions['keyProvider'], homeId: this.#config.homeId, integrationDomain: 'samsungtv' });
       this.#ownsStore = true;
     }
     if (signalArg) {
-      const aborted = (): void => { void this.destroy(); };
+      const aborted = (): void => { void this.destroy().catch(() => undefined); };
       if (signalArg.aborted) this.#lifetime.abort(new Error('Samsung TV setup was cancelled.'));
       else {
         signalArg.addEventListener('abort', aborted, { once: true });
@@ -48,7 +51,7 @@ export class SamsungtvClient {
 
   public async start(signalArg?: AbortSignal): Promise<void> {
     this.#assertOpen(signalArg);
-    if (!this.#start) this.#start = this.#initialize(signalArg);
+    if (!this.#start) this.#start = Promise.resolve().then(() => this.#initialize(signalArg));
     await this.#start;
     this.#assertOpen(signalArg);
   }
@@ -67,20 +70,42 @@ export class SamsungtvClient {
 
   public destroy(): Promise<void> {
     if (!this.#destroy) {
+      // Publish before aborting foreign callbacks; retain failed cleanup for explicit acknowledgement.
+      this.#destroy = Promise.resolve().then(() => this.#drain(false));
       this.#lifetime.abort(new Error('Samsung TV client is destroyed.'));
       this.#removeAbort();
-      this.#destroy = (async () => {
-        await this.#protocol?.close();
-        if (this.#start) await Promise.allSettled([this.#start]);
-        await this.#protocol?.close();
-        this.#protocol = undefined;
-        if (this.#ownsStore) await this.#store?.close();
-        this.#store = undefined;
-      })();
+      this.#removeAbort = () => undefined;
     }
     return this.#destroy;
   }
 
+  /** Terminal cleanup only; never repeats pairing persistence, startup or commands. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#destroy) return Promise.reject(new Error('Samsung TV cleanup requires terminal destroy.'));
+    this.#retryCleanup ??= Promise.resolve().then(async () => {
+      await this.#destroy!.catch(() => undefined);
+      await this.#drain(true);
+    });
+    return this.#retryCleanup;
+  }
+
+  async #drain(retryArg: boolean): Promise<void> {
+    const protocol = this.#protocol;
+    const store = this.#store;
+    // Close both owners before joining either: persistence providers may await store cancellation.
+    const cleanup = Promise.allSettled([
+      Promise.resolve().then(() => retryArg ? protocol?.retryCleanup() : protocol?.close()),
+      Promise.resolve().then(() => this.#ownsStore ? (retryArg ? store?.retryCleanup() : store?.close()) : undefined),
+    ]);
+    // Startup errors belong to the start caller; protocol close owns late persistence failures.
+    const [results] = await Promise.all([cleanup, Promise.allSettled(this.#start ? [this.#start] : [])]);
+    if (results[0].status === 'fulfilled') this.#protocol = undefined;
+    if (results[1].status === 'fulfilled') this.#store = undefined;
+    const errors = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+    if (errors.length) throw new AggregateError(errors, 'Samsung TV client cleanup failed; resources remain retained.');
+    this.#start = undefined;
+  }
+
   async #initialize(signalArg?: AbortSignal): Promise<void> {
     const signal = this.#signal(signalArg);
     const store = this.#store;

package/ts/integrations/samsungtv/samsungtv.classes.configflow.ts

@@ -1,20 +1,28 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { ISamsungtvConfig } from './samsungtv.types.js';
 import { normalizeSamsungtvConfig, samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
 
 export class SamsungtvConfigFlow implements IConfigFlow<ISamsungtvConfig> {
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(ownerArg: NativeIntegrationOwner = new NativeIntegrationOwner('samsungtv')) {
+    this.#scope = ownerArg.createFlowScope();
+  }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ISamsungtvConfig>> {
-    void contextArg;
-    const metadata = candidateArg.metadata === undefined ? {} : samsungtvObject(candidateArg.metadata, 'Samsung TV candidate metadata');
+    const context = this.#scope.admit(contextArg);
+    const candidate = samsungtvObject(candidateArg, 'Samsung TV discovery candidate');
+    const metadata = candidate.metadata === undefined ? {} : samsungtvObject(candidate.metadata, 'Samsung TV candidate metadata');
     const hints: Record<string, unknown> = {};
     for (const field of ['httpOrigin', 'websocketOrigin', 'expectedDeviceId']) {
       if (typeof metadata[field] === 'string') hints[field] = metadata[field];
     }
+    Object.freeze(hints);
     return {
       kind: 'form', title: 'Pair Samsung Smart TV',
-      description: 'Confirm this home, the exact TV UUID, explicit REST/WSS origins and trusted TV CA. Confirm the TV pairing prompt when using prompt mode. Pairing credentials are stored only in encrypted home-scoped persistence.',
+      description: 'Confirm the exact TV UUID, explicit REST/WSS origins and trusted TV CA for the selected home. Confirm the TV pairing prompt when using prompt mode. Pairing credentials are stored only in encrypted home-scoped persistence.',
       fields: [
-        { name: 'homeId', label: 'Home ID', type: 'text', required: true },
         { name: 'expectedDeviceId', label: 'Exact TV UUID', type: 'text', required: true },
         { name: 'httpOrigin', label: 'REST origin', type: 'text', required: true },
         { name: 'websocketOrigin', label: 'Verified WSS origin', type: 'text', required: true },
@@ -27,17 +35,24 @@ export class SamsungtvConfigFlow implements IConfigFlow<ISamsungtvConfig> {
         try {
           const values = samsungtvObject(valuesArg, 'Samsung TV config form');
           samsungtvKeys(values, ['homeId', 'expectedDeviceId', 'httpOrigin', 'websocketOrigin', 'pairingMode', 'certificateAuthority', 'allowUnencryptedLocalDiscovery']);
+          if (values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('Samsung TV form home does not match the selected host home.');
           const config = normalizeSamsungtvConfig({
-            homeId: values.homeId, expectedDeviceId: values.expectedDeviceId ?? hints.expectedDeviceId,
+            homeId: context.homeId, expectedDeviceId: values.expectedDeviceId ?? hints.expectedDeviceId,
             httpOrigin: values.httpOrigin ?? hints.httpOrigin, websocketOrigin: values.websocketOrigin ?? hints.websocketOrigin,
             pairingMode: values.pairingMode, certificateAuthority: values.certificateAuthority,
             allowUnencryptedLocalDiscovery: values.allowUnencryptedLocalDiscovery,
           });
-          return { kind: 'done', title: 'Samsung Smart TV configuration accepted', config };
+          return await this.#scope.run(context, config.homeId, async (leaseArg) => {
+            leaseArg.assertOpen();
+            return { kind: 'done', title: 'Samsung Smart TV configuration accepted', config };
+          });
         } catch (errorArg) {
           return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Samsung TV configuration is invalid.' };
         }
       },
     };
   }
+
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 }

package/ts/integrations/samsungtv/samsungtv.classes.integration.ts

@@ -1,13 +1,13 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { SamsungtvClient } from './samsungtv.classes.client.js';
 import { SamsungtvConfigFlow } from './samsungtv.classes.configflow.js';
 import { createSamsungtvDiscoveryDescriptor } from './samsungtv.discovery.js';
 import { SamsungtvMapper } from './samsungtv.mapper.js';
-import type { ISamsungtvConfig, ISamsungtvIntegrationOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
-import { samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
+import type { ISamsungtvConfig, ISamsungtvClientOptions, ISamsungtvIntegrationOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
+import { normalizeSamsungtvConfig, samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
 
 const serviceKeys = {
   turn_off: 'KEY_POWEROFF', media_play: 'KEY_PLAY', media_pause: 'KEY_PAUSE', media_stop: 'KEY_STOP',
@@ -32,65 +32,77 @@ export class SamsungtvIntegration extends BaseIntegration<ISamsungtvConfig> {
   public readonly displayName = 'Samsung Smart TV';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createSamsungtvDiscoveryDescriptor();
-  public readonly configFlow = new SamsungtvConfigFlow();
+  public readonly configFlow: SamsungtvConfigFlow;
   public readonly metadata = {
     source: 'home-assistant/core', upstreamDomain: 'samsungtv', integrationType: 'device', iotClass: 'local_poll',
     localApi: { implemented: ['verified UUID and WSS pairing', 'encrypted home-scoped pairing', 'fresh REST observations', 'single supported remote Click'],
       explicitUnsupported: ['optimistic state', 'automatic retries or replay', 'legacy TCP/PIN', 'play_pause', 'app launch', 'absolute volume/mute assignment', 'wake-on-LAN', 'hold/release/repeated keys'] },
   };
-  readonly #runtimes = new Set<SamsungtvRuntime>();
-  readonly #pending = new Set<SamsungtvClient>();
-  #options?: ISamsungtvIntegrationOptions;
-  #destroyed = false;
-  #destroy?: Promise<void>;
+  readonly #owner: NativeIntegrationOwner;
+  #options?: ISamsungtvClientOptions;
 
-  constructor(optionsArg?: ISamsungtvIntegrationOptions) {
+  constructor(optionsArg: ISamsungtvIntegrationOptions = {}) {
     super();
-    this.#options = optionsArg ? { db: optionsArg.db, keyProvider: optionsArg.keyProvider } : undefined;
+    const options = samsungtvObject(optionsArg, 'Samsung TV integration options');
+    samsungtvKeys(options, ['homeId', 'capacity', 'db', 'keyProvider']);
+    if ((options.db === undefined) !== (options.keyProvider === undefined)) {
+      throw new TypeError('Samsung TV database and key provider must be supplied together.');
+    }
+    this.#options = options.db === undefined ? undefined : {
+      db: options.db as ISamsungtvClientOptions['db'], keyProvider: options.keyProvider as ISamsungtvClientOptions['keyProvider'],
+    };
+    this.#owner = new NativeIntegrationOwner(this.domain, { homeId: options.homeId as string | undefined, capacity: options.capacity as number | undefined });
+    this.configFlow = new SamsungtvConfigFlow(this.#owner);
   }
 
   public async setup(configArg: ISamsungtvConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.#destroyed) throw new Error('Samsung TV integration is destroyed.');
-    if (contextArg.configStore !== undefined && !(contextArg.configStore instanceof NoSqlConfigStore)) {
-      throw new TypeError('Samsung TV runtime requires an encrypted NoSqlConfigStore.');
-    }
-    const client = new SamsungtvClient(configArg, contextArg.configStore ?? this.#options, contextArg.abortSignal);
-    this.#pending.add(client);
-    try {
-      const snapshot = await client.getSnapshot(contextArg.abortSignal);
-      if (this.#destroyed) throw new Error('Samsung TV integration was destroyed during setup.');
-      const runtime = new SamsungtvRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
-      this.#runtimes.add(runtime);
+    const config = normalizeSamsungtvConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new SamsungtvClient(config, leaseArg.context.configStore ?? this.#options, leaseArg.signal);
+      let cleanupAttempted = false;
+      leaseArg.own(() => {
+        if (cleanupAttempted) return client.retryCleanup();
+        cleanupAttempted = true;
+        return client.destroy();
+      });
+      const snapshot = await client.getSnapshot(leaseArg.signal);
+      leaseArg.assertOpen();
+      const runtime = new SamsungtvRuntime(client, snapshot, leaseArg);
+      leaseArg.promoteToRuntime();
       return runtime;
-    } catch (errorArg) { await client.destroy(); throw errorArg; }
-    finally { this.#pending.delete(client); }
+    });
   }
 
   public destroy(): Promise<void> {
-    if (!this.#destroy) {
-      this.#destroyed = true;
-      this.#destroy = Promise.all([
-        ...[...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()),
-        ...[...this.#pending].map((clientArg) => clientArg.destroy()),
-      ]).then(() => { this.#options = undefined; });
-    }
-    return this.#destroy;
+    const closed = this.#owner.close();
+    this.#options = undefined;
+    return closed;
   }
+
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantSamsungtvIntegration extends SamsungtvIntegration {}
 
 class SamsungtvRuntime implements IIntegrationRuntime {
   public readonly domain = 'samsungtv';
-  constructor(private readonly client: SamsungtvClient, private readonly identity: ISamsungtvSnapshot, private readonly onDestroyed: () => void) {}
+  readonly #deviceId: string;
+  constructor(private readonly client: SamsungtvClient, identityArg: ISamsungtvSnapshot, private readonly lease: INativeSetupLease) {
+    this.#deviceId = SamsungtvMapper.deviceId(identityArg);
+  }
   public isHealthy(): boolean { return this.client.isHealthy(); }
   public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.lease.assertOpen();
     return SamsungtvMapper.toDevices(await this.client.getSnapshot(signalArg));
   }
-  public async entities(): Promise<IIntegrationEntity[]> { return SamsungtvMapper.toEntities(await this.client.getSnapshot()); }
+  public async entities(): Promise<IIntegrationEntity[]> {
+    this.lease.assertOpen();
+    return SamsungtvMapper.toEntities(await this.client.getSnapshot());
+  }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
     try {
+      this.lease.assertOpen();
       const request = samsungtvObject(requestArg, 'Samsung TV service request');
       samsungtvKeys(request, ['domain', 'service', 'target', 'data']);
       this.#assertTarget(request.target);
@@ -117,24 +129,27 @@ class SamsungtvRuntime implements IIntegrationRuntime {
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
     try {
+      this.lease.assertOpen();
       const request = samsungtvObject(requestArg, 'Samsung TV feature write');
       samsungtvKeys(request, ['device', 'feature', 'value']);
       const device = samsungtvObject(request.device, 'Samsung TV feature device');
       const feature = samsungtvObject(request.feature, 'Samsung TV feature');
-      if (device.id !== SamsungtvMapper.deviceId(this.identity) || device.integrationDomain !== this.domain) {
+      if (device.id !== this.#deviceId || device.integrationDomain !== this.domain) {
         throw new TypeError('Samsung TV feature device is not owned by this runtime.');
       }
-      if (feature.id !== 'remote_key') throw new TypeError('Samsung TV feature is not writable.');
+      if (feature.id !== 'remote_key' || feature.capability !== 'media' || feature.readable !== false || feature.writable !== true) {
+        throw new TypeError('Samsung TV feature is not the owned writable remote key.');
+      }
       return { success: true, data: await this.client.sendKey(remoteKey(request.value), signalArg) };
     } catch (errorArg) { return failure(errorArg); }
   }
 
-  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
+  public destroy(): Promise<void> { return this.lease.close(); }
 
   #assertTarget(valueArg: unknown): void {
     const target = samsungtvObject(valueArg, 'Samsung TV service target');
     samsungtvKeys(target, ['deviceId', 'entityId']);
-    const deviceId = SamsungtvMapper.deviceId(this.identity);
+    const deviceId = this.#deviceId;
     if ((target.deviceId === undefined && target.entityId === undefined) ||
       (target.deviceId !== undefined && target.deviceId !== deviceId) ||
       (target.entityId !== undefined && target.entityId !== `${deviceId}:media_player`)) {

package/ts/integrations/samsungtv/samsungtv.types.ts

@@ -1,5 +1,6 @@
 import type * as plugins from '../../plugins.js';
 import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 
 export interface ISamsungtvConfig {
   homeId: string;
@@ -16,11 +17,13 @@ export interface ISamsungtvConfig {
 
 export interface IHomeAssistantSamsungtvConfig extends ISamsungtvConfig {}
 
-export interface ISamsungtvIntegrationOptions {
+export interface ISamsungtvClientOptions {
   db: plugins.nosqldb.SmartdataDb;
   keyProvider: IConfigEncryptionKeyProvider;
 }
 
+export interface ISamsungtvIntegrationOptions extends INativeIntegrationOwnerOptions, Partial<ISamsungtvClientOptions> {}
+
 export interface ISamsungtvSnapshot {
   readonly homeId: string;
   readonly device: plugins.ecobridgeDeviceManager.ISamsungTvDeviceInfo;