@smarthome.exchange/integrations 1.0.0 → 3.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/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;

package/ts/integrations/shelly/readme.md

@@ -1,14 +1,23 @@
 # Shelly Gen2/3
 
-This native port connects to a local Shelly Gen2 or Gen3 HTTP/RPC endpoint. Setup reads and validates the physical device identity, status and configuration before returning a runtime. It maps switch outputs and their power, voltage, current, energy and temperature readings to canonical devices and entities.
+This native port connects to a local Shelly Gen2 or Gen3 HTTP/RPC endpoint. Setup reads and validates the selected endpoint's reported device ID, MAC, model, generation, methods, status and configuration before returning a runtime. These observations do not attest physical hardware identity. It maps switch outputs and their power, voltage, current, energy and temperature readings to canonical devices and entities.
 
 ```typescript
-const integration = new ShellyIntegration();
+const integration = new ShellyIntegration({
+  resolvePassword, // Caller-owned callback; receives homeId, credentialRef, signal and monotonic deadline.
+});
 const runtime = await integration.setup({
   host: '192.168.1.20',
-  password: devicePassword,
+  homeId: selectedHomeId,
+  expectedDeviceId: selectedDeviceId,
+  expectedMacAddress: selectedMacAddress,
+  expectedModel: selectedModel,
+  expectedGeneration: selectedGeneration,
+  credentialRef: selectedCredentialRef,
+  allowUnencryptedLan: true,
+  allowControl: true, // Omit for read-only outputs.
   requestTimeoutMs: 10000,
-}, {});
+}, { homeId: hostSelectedHomeId, abortSignal: callerSignal });
 
 const [device] = await runtime.devices();
 const output = device.features.find((feature) => feature.id === 'switch_0_output');
@@ -21,14 +30,20 @@ await unsubscribe?.();
 await integration.destroy();
 ```
 
-`host` is a hostname or IP address, with the optional port supplied separately. `protocol` defaults to `http`; `https` validates the endpoint certificate through Node's standard transport. Authentication uses the Shelly `admin` username and SHA-256 digest challenges. Credentials and response bodies are excluded from error messages. Request deadlines default to 10 seconds and accept values between 10 ms and 60 seconds.
+`hostSelectedHomeId` comes independently from the embedding host and must match configuration and any optional constructor home binding. Config flow captures that selection before returning a form. An optional actual `NoSqlConfigStore` must match the admitted home/domain and remains borrowed. The integration's construction is inert; setup, flow work, live runtimes and retained cleanup share a default capacity of 16.
+
+`resolvePassword` is an application-owned asynchronous callback. Its immutable request contains admitted `homeId`, captured `credentialRef`, `signal` and an absolute `performance.now()` deadline including queue, authentication and readback. Config accepts references rather than plaintext passwords. The adapter registers actual provider work before callback entry, fences late credentials after cancellation and joins the actual callback during shutdown. Provider errors are sanitized; a provider that never settles keeps cleanup pending.
+
+`host` is a hostname or IP address, with the optional port supplied separately. `protocol` defaults to `http`; `https` validates the endpoint certificate through Node's standard transport. Plain HTTP requires explicit `allowUnencryptedLan: true`. Authentication uses the Shelly `admin` username and SHA-256 digest challenges. Credentials and response bodies are excluded from error messages. Request deadlines default to 10 seconds and accept values between 10 ms and 60 seconds.
 
 `switch.turn_on` and `switch.turn_off` accept an exact mapped switch entity id. A mapped device id is sufficient when the device exposes one switch. Feature writes require the connected device id, a mapped writable `switch_N_output` feature, and a boolean value. Foreign targets, nonexistent components, ambiguous device targets and fabricated writable sensor features are rejected before a write.
 
+Controls are denied unless `allowControl: true` is captured in configuration. Each absolute output write freshly validates identity, current methods and component state before sending one `Switch.Set`; it then revalidates identity and independently reads `Switch.GetStatus`. The vendor's `was_on` acknowledges prior state. Results carry `commandAcknowledged`, `causalityConfirmed: false`, requested/prior values and an observed-target or indeterminate outcome. Lost acknowledgement, failed post-dispatch readback or changed identity leaves an indeterminate result. Setter challenges, cancellation and cleanup never replay the effect. Independent readback does not prove relay position, exclusive causality or an atomic preflight.
+
 Subscriptions share one native WebSocket connection to `/rpc`. The initial `Shelly.GetStatus` request supplies a unique source and authenticates both current and older Gen2 digest challenges. `NotifyStatus` patches merge into the validated baseline, including nested fields and null removals. `NotifyFullStatus` replaces the baseline. `NotifyEvent` carries vendor events, and configuration changes refresh mapped names. Disconnects and malformed or foreign frames emit safe errors and unavailable events; `isHealthy()` reflects the failed stream. A later subscription can establish a new connection.
 
-The last unsubscribe closes the socket; an aborted listener removes only that listener. The setup context's abort signal cancels live requests and the push transport. Runtime and integration destruction cancel outstanding requests, remove subscribers, and await owned socket closure. If the endpoint does not complete the native WebSocket close handshake before the deadline, cleanup reports failure and retains ownership for another cleanup attempt.
+The last unsubscribe closes the socket; an aborted listener removes only that listener. The setup context's abort signal cancels live requests and the push transport. Runtime and integration destruction cancel outstanding requests, remove subscribers, and await owned socket closure. If the endpoint does not complete the native WebSocket close handshake before the deadline, cleanup reports failure and retains ownership. Repeated `destroy()` keeps its original promise and failure; explicit integration, config-flow or client `retryCleanup()` retries cleanup only, without credential-provider or device-effect replay. Async subscriber continuations and all sibling cleanup settle before completion. Terminal objects cannot reopen.
 
-Production configuration requires a real endpoint. The former `deviceInfo`, `status` and `deviceConfig` fixture fields have been removed; use a local fixture server in tests or call `ShellyMapper` directly with a snapshot. Tests under `test/shelly/` exercise local HTTP and WebSocket servers without real devices or credentials.
+Production configuration requires a real endpoint. The former `deviceInfo`, `status` and `deviceConfig` fixture fields have been removed; use a local fixture server in tests or call `ShellyMapper` directly with a snapshot. Tests under `test/shelly/` exercise local HTTP and WebSocket servers without real devices or credentials. Qualified synthetic profiles cover Plus 1PM Gen2 `SNSW-001P16EU`, 1PM Gen3 `S3SW-001P16EU` and Plus 2PM `SNSW-002P16EU` with two switch components; this is not universal model certification.
 
 Protocol references: [RPC channels](https://shelly-api-docs.shelly.cloud/gen2/General/RPCChannels/), [authentication](https://shelly-api-docs.shelly.cloud/gen2/General/Authentication/), [notifications](https://shelly-api-docs.shelly.cloud/gen2/General/Notifications/), [mDNS](https://shelly-api-docs.shelly.cloud/gen2/General/mDNS/), and [switch RPC](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Switch/).