@smarthome.exchange/integrations 0.1.0 → 1.0.0

package/ts/integrations/homeassistant/homeassistant.classes.client.ts

@@ -7,8 +7,10 @@ import type {
   IHomeAssistantNormalizedConfig,
   IHomeAssistantServiceCall,
   IHomeAssistantWebsocketApi,
+  IHomeAssistantTargetScope,
   THomeAssistantWebSocketFactory,
 } from './homeassistant.types.js';
+import { homeAssistantRecord, validateHomeAssistantEntity, validateHomeAssistantServices, validateHomeAssistantServiceCall } from './homeassistant.validation.js';
 
 const entityIdPattern = /^[a-z0-9_]+\.[a-z0-9_]+$/;
 const entityDomainPattern = /^[a-z0-9_]+$/;
@@ -34,9 +36,13 @@ const normalizeStringSet = (
   if (valuesArg === undefined) {
     return undefined;
   }
+  if (!Array.isArray(valuesArg) || valuesArg.length > 10_000) {
+    throw new Error(`Home Assistant ${labelArg} allowlist must be a bounded array.`);
+  }
 
   const result = new Set<string>();
   for (const value of valuesArg) {
+    if (typeof value !== 'string') throw new Error(`Home Assistant ${labelArg} entries must be strings.`);
     const normalizedValue = value.trim().toLowerCase();
     if (!patternArg.test(normalizedValue)) {
       throw new Error(`Invalid Home Assistant ${labelArg}: ${value}`);
@@ -49,6 +55,10 @@ const normalizeStringSet = (
 export const normalizeHomeAssistantConfig = (
   configArg: IHomeAssistantHomeassistantConfig
 ): IHomeAssistantNormalizedConfig => {
+  homeAssistantRecord(configArg);
+  if (typeof configArg.homeId !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$/.test(configArg.homeId)) {
+    throw new Error('Home Assistant homeId must be a stable identifier of at most 128 characters.');
+  }
   let parsedUrl: URL;
   try {
     parsedUrl = new URL(configArg.baseUrl);
@@ -68,8 +78,8 @@ export const normalizeHomeAssistantConfig = (
     throw new Error('Home Assistant baseUrl must contain only the scheme, host, and optional port.');
   }
 
-  const accessToken = configArg.accessToken?.trim();
-  if (!accessToken) {
+  const accessToken = typeof configArg.accessToken === 'string' ? configArg.accessToken.trim() : undefined;
+  if (!accessToken || accessToken.length > 8192 || /[\s\x00-\x1f\x7f]/.test(accessToken)) {
     throw new Error('Home Assistant accessToken is required.');
   }
   const entityIds = normalizeStringSet(configArg.entityIds, 'entity ID', entityIdPattern);
@@ -122,6 +132,8 @@ export const normalizeHomeAssistantConfig = (
   }
 
   return {
+    homeId: configArg.homeId,
+    instanceId: plugins.crypto.createHash('sha256').update(parsedUrl.origin).digest('hex').slice(0, 24),
     baseUrl: parsedUrl.origin,
     accessToken,
     entityIds,
@@ -144,6 +156,9 @@ export class HomeAssistantClient implements IHomeAssistantClient {
   private upstreamSnapshot: homeAssistantWebsocket.HassEntities = {};
   private snapshot: homeAssistantWebsocket.HassEntities = {};
   private entityPlatforms: Record<string, string> = {};
+  private services = new Set<string>();
+  private readonly catalogueUnsubscribes = new Set<() => Promise<void>>();
+  private readonly serviceSettlements = new Set<Promise<void>>();
   private connectionReady = false;
   private snapshotReady = false;
   private requiredEntitiesPresent = true;
@@ -169,6 +184,7 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     this.connectionReady = true;
     this.snapshotReady = false;
     this.entityPlatforms = {};
+    this.services.clear();
     this.bufferedStateEvents.clear();
     const generation = this.advanceConnectionGeneration();
     this.emitChange();
@@ -204,6 +220,7 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     this.connectionReady = false;
     this.snapshotReady = false;
     this.entityPlatforms = {};
+    this.services.clear();
     this.bufferedStateEvents.clear();
     this.advanceConnectionGeneration();
     this.emitChange();
@@ -323,6 +340,14 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     return structuredClone(this.entityPlatforms);
   }
 
+  public getServices(): ReadonlySet<string> {
+    return new Set(this.services);
+  }
+
+  public getTargetScope(): IHomeAssistantTargetScope {
+    return { homeId: this.config.homeId, instanceId: this.config.instanceId };
+  }
+
   public subscribe(handlerArg: () => void): () => void {
     if (this.isStopping()) {
       throw new Error('Home Assistant client is destroyed.');
@@ -357,12 +382,20 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     if (!this.requiredEntitiesPresent) {
       throw new Error('Home Assistant snapshot is missing required entities.');
     }
+    const target = homeAssistantRecord(homeAssistantRecord(requestArg).target);
+    const entity = typeof target.entity_id === 'string' ? this.snapshot[target.entity_id] : undefined;
+    if (!entity) throw new Error('Home Assistant service target is outside the selected snapshot.');
+    const request = validateHomeAssistantServiceCall(requestArg, entity, this.services);
     const connection = this.connection;
     const operationAbortController = new AbortController();
     const propagateAbort = (): void => {
       operationAbortController.abort(abortSignalArg?.reason);
     };
     abortSignalArg?.addEventListener('abort', propagateAbort, { once: true });
+    const propagateLifetimeAbort = (): void => {
+      operationAbortController.abort(this.lifetimeAbortController.signal.reason);
+    };
+    this.lifetimeAbortController.signal.addEventListener('abort', propagateLifetimeAbort, { once: true });
     const cancelPendingCommand = (): void => {
       if (this.connection === connection && !this.isStopping()) {
         connection.reconnect(true);
@@ -373,17 +406,21 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     }
     if (operationAbortController.signal.aborted) {
       abortSignalArg?.removeEventListener('abort', propagateAbort);
+      this.lifetimeAbortController.signal.removeEventListener('abort', propagateLifetimeAbort);
       throw abortError(operationAbortController.signal);
     }
     let timeout: ReturnType<typeof setTimeout> | undefined;
+    let resolveSettlement!: () => void;
+    const settlement = new Promise<void>((resolve) => { resolveSettlement = resolve; });
+    this.serviceSettlements.add(settlement);
     this.activeServiceCallCount++;
     try {
       const operationPromise = this.api.callService(
         connection,
-        requestArg.domain,
-        requestArg.service,
-        requestArg.data,
-        requestArg.target
+        request.domain,
+        request.service,
+        request.data,
+        request.target
       );
       operationAbortController.signal.addEventListener('abort', cancelPendingCommand, { once: true });
       if (operationAbortController.signal.aborted) {
@@ -402,6 +439,9 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       }
       abortSignalArg?.removeEventListener('abort', propagateAbort);
       operationAbortController.signal.removeEventListener('abort', cancelPendingCommand);
+      this.lifetimeAbortController.signal.removeEventListener('abort', propagateLifetimeAbort);
+      resolveSettlement();
+      this.serviceSettlements.delete(settlement);
     }
   }
 
@@ -409,7 +449,7 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     if (this.destroyPromise) {
       return this.destroyPromise;
     }
-    if (this.lifecycle === 'destroyed' && !this.stateUnsubscribe) {
+    if (this.lifecycle === 'destroyed' && !this.stateUnsubscribe && this.catalogueUnsubscribes.size === 0 && this.ownedSockets.size === 0) {
       return Promise.resolve();
     }
     this.lifecycle = 'destroying';
@@ -440,6 +480,11 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       connection.removeEventListener('disconnected', this.handleDisconnected);
     }
     try {
+      await Promise.all([...this.serviceSettlements]);
+      for (const unsubscribeCatalogue of [...this.catalogueUnsubscribes]) {
+        await this.settleStateUnsubscribe(unsubscribeCatalogue);
+        this.catalogueUnsubscribes.delete(unsubscribeCatalogue);
+      }
       if (unsubscribe) {
         await this.settleStateUnsubscribe(unsubscribe);
         if (this.stateUnsubscribe === unsubscribe) {
@@ -453,16 +498,20 @@ export class HomeAssistantClient implements IHomeAssistantClient {
         }
         connection.close();
       }
-      this.closeOwnedSockets(connectionSocket);
-      this.advanceConnectionGeneration();
-      this.connectionReady = false;
-      this.snapshotReady = false;
-      this.requiredEntitiesPresent = false;
-      this.bufferedStateEvents.clear();
-      this.upstreamSnapshot = {};
-      this.snapshot = {};
-      this.entityPlatforms = {};
-      this.handlers.clear();
+      try {
+        await this.drainOwnedSockets(connectionSocket);
+      } finally {
+        this.advanceConnectionGeneration();
+        this.connectionReady = false;
+        this.snapshotReady = false;
+        this.requiredEntitiesPresent = false;
+        this.bufferedStateEvents.clear();
+        this.upstreamSnapshot = {};
+        this.snapshot = {};
+        this.entityPlatforms = {};
+        this.services.clear();
+        this.handlers.clear();
+      }
     }
   }
 
@@ -602,7 +651,6 @@ export class HomeAssistantClient implements IHomeAssistantClient {
         }
         settled = true;
         cleanupAuthenticationListeners();
-        this.ownedSockets.delete(socket);
         try {
           socket.close();
         } catch {
@@ -627,13 +675,13 @@ export class HomeAssistantClient implements IHomeAssistantClient {
         })().catch(fail);
       };
       const handleMessage = (eventArg: MessageEvent): void => {
-        if (typeof eventArg.data !== 'string') {
+        if (typeof eventArg.data !== 'string' || eventArg.data.length > 16_384) {
           fail(new Error('Home Assistant authentication returned a non-text message.'));
           return;
         }
         let message: Record<string, unknown>;
         try {
-          message = JSON.parse(eventArg.data) as Record<string, unknown>;
+          message = homeAssistantRecord(JSON.parse(eventArg.data));
         } catch {
           fail(new Error('Home Assistant authentication returned invalid JSON.'));
           return;
@@ -697,10 +745,13 @@ export class HomeAssistantClient implements IHomeAssistantClient {
 
   private closeOwnedSockets(excludedSocketArg?: homeAssistantWebsocket.HaWebSocket): void {
     for (const socket of [...this.ownedSockets]) {
-      this.ownedSockets.delete(socket);
       if (socket === excludedSocketArg) {
         continue;
       }
+      if (socket.readyState === 3) {
+        this.ownedSockets.delete(socket);
+        continue;
+      }
       try {
         socket.close();
       } catch {
@@ -709,6 +760,25 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     }
   }
 
+  private async drainOwnedSockets(connectionSocketArg?: homeAssistantWebsocket.HaWebSocket): Promise<void> {
+    const sockets = new Set(this.ownedSockets);
+    if (connectionSocketArg) sockets.add(connectionSocketArg);
+    await Promise.all([...sockets].map((socket) => new Promise<void>((resolve, reject) => {
+      if (socket.readyState === 3) { this.ownedSockets.delete(socket); resolve(); return; }
+      const finish = (error?: Error): void => {
+        clearTimeout(timeout);
+        socket.removeEventListener('close', handleClose);
+        if (!error) this.ownedSockets.delete(socket);
+        error ? reject(error) : resolve();
+      };
+      const handleClose = (): void => finish();
+      const timeout = setTimeout(() => finish(new Error('Home Assistant socket did not close within 1000 ms.')), 1000);
+      socket.addEventListener('close', handleClose, { once: true });
+      try { if (socket.readyState !== 2) socket.close(); }
+      catch (error) { finish(error instanceof Error ? error : new Error('Home Assistant socket close failed.')); }
+    })));
+  }
+
   private async raceAbort<T>(
     operationArg: Promise<T>,
     abortSignalArg: AbortSignal
@@ -850,6 +920,19 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       throw new Error('Home Assistant client was destroyed during state subscription.');
     }
     this.stateUnsubscribe = unsubscribe;
+    for (const eventType of ['service_registered', 'service_removed', 'entity_registry_updated']) {
+      const unsubscribePromise = connectionArg.subscribeEvents(() => this.handleReady(), eventType);
+      try {
+        const unsubscribeCatalogue = await this.raceAbortWithDeadline(
+          unsubscribePromise, abortSignalArg, initializationDeadlineArg,
+          'Home Assistant did not acknowledge its catalogue subscription before the startup deadline.'
+        );
+        this.catalogueUnsubscribes.add(unsubscribeCatalogue);
+      } catch (errorArg) {
+        void unsubscribePromise.then((lateUnsubscribe) => this.settleStateUnsubscribe(lateUnsubscribe)).catch(() => undefined);
+        throw errorArg;
+      }
+    }
   }
 
   private async refreshCurrentGeneration(
@@ -942,36 +1025,30 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     if (generationArg !== this.connectionGeneration || !this.connectionReady) {
       return false;
     }
+    if (!Array.isArray(statesResult.value) || statesResult.value.length > 10_000) {
+      throw new Error('Home Assistant returned an invalid or oversized entity snapshot.');
+    }
     const entities: homeAssistantWebsocket.HassEntities = {};
-    for (const state of statesResult.value) {
+    for (const rawState of statesResult.value) {
+      const state = validateHomeAssistantEntity(rawState);
       if (this.shouldIncludeEntityId(state.entity_id)) {
+        if (Object.hasOwn(entities, state.entity_id)) throw new Error('Home Assistant returned duplicate entity states.');
         entities[state.entity_id] = state;
       }
     }
-    for (const event of this.bufferedStateEvents.values()) {
-      this.applyStateChangedEvent(entities, event);
-    }
-    this.bufferedStateEvents.clear();
-    const requireEntityRegistry = this.config.requireEntityRegistry;
-    let missingEntityIds = this.commitSnapshot(
-      entities,
-      connectionArg.connected,
-      !requireEntityRegistry
+    const servicesResult = await this.runForConnectionGeneration(
+      () => this.api.getServices(connectionArg), generationArg, abortSignalArg, initializationDeadlineArg,
+      'Home Assistant did not provide its service catalogue before the startup deadline.'
     );
-    if (requireCompleteArg && missingEntityIds.length > 0) {
-      throw new Error(
-        `Home Assistant snapshot is missing required entities: ${missingEntityIds.join(', ')}`
-      );
-    }
-    if (!requireEntityRegistry) {
-      return true;
-    }
+    if (servicesResult.status === 'changed') return false;
+    const services = validateHomeAssistantServices(servicesResult.value);
 
     const entityPlatformsResult = await this.loadEntityPlatforms(
       connectionArg,
       generationArg,
       abortSignalArg,
-      initializationDeadlineArg
+      initializationDeadlineArg,
+      Object.keys(entities)
     );
     if (entityPlatformsResult.status === 'changed') {
       return false;
@@ -979,26 +1056,19 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     if (generationArg !== this.connectionGeneration || !this.connectionReady) {
       return false;
     }
-    if (this.bufferedStateEvents.size > 0) {
-      const refreshedEntities = { ...this.upstreamSnapshot };
-      for (const event of this.bufferedStateEvents.values()) {
-        this.applyStateChangedEvent(refreshedEntities, event);
-      }
-      this.bufferedStateEvents.clear();
-      missingEntityIds = this.commitSnapshot(
-        refreshedEntities,
-        connectionArg.connected,
-        false
-      );
-      if (requireCompleteArg && missingEntityIds.length > 0) {
-        throw new Error(
-          `Home Assistant snapshot is missing required entities: ${missingEntityIds.join(', ')}`
-        );
-      }
+    for (const event of this.bufferedStateEvents.values()) {
+      this.applyStateChangedEvent(entities, event);
+    }
+    if (Object.keys(entities).length > 10_000) throw new Error('Home Assistant entity snapshot exceeds its bounds.');
+    this.bufferedStateEvents.clear();
+    const missingEntityIds = this.config.requireEntityIds
+      ? [...this.config.entityIds!].filter((entityId) => !Object.hasOwn(entities, entityId)) : [];
+    if (requireCompleteArg && missingEntityIds.length > 0) {
+      throw new Error(`Home Assistant snapshot is missing required entities: ${missingEntityIds.join(', ')}`);
     }
     this.entityPlatforms = entityPlatformsResult.value;
-    this.snapshotReady = true;
-    this.emitChange();
+    this.services = services;
+    this.commitSnapshot(entities, connectionArg.connected, true);
     return true;
   }
 
@@ -1008,11 +1078,37 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     if (this.isStopping()) {
       return;
     }
-    const entityId = eventArg.data.entity_id;
+    let entityId: string;
+    try {
+      const data = homeAssistantRecord(homeAssistantRecord(eventArg).data);
+      if (typeof data.entity_id !== 'string' || !entityIdPattern.test(data.entity_id)) {
+        throw new Error('Home Assistant returned an invalid state event target.');
+      }
+      entityId = data.entity_id;
+      if (data.new_state !== null) {
+        const entity = validateHomeAssistantEntity(data.new_state);
+        if (entity.entity_id !== entityId) throw new Error('Home Assistant state event target is inconsistent.');
+      }
+    } catch {
+      this.handleDisconnected();
+      this.connection?.close();
+      return;
+    }
     if (!this.shouldIncludeEntityId(entityId)) {
       return;
     }
+    if (eventArg.data.new_state && !Object.hasOwn(this.upstreamSnapshot, entityId)
+      && Object.keys(this.upstreamSnapshot).length >= 10_000) {
+      this.handleDisconnected();
+      this.connection?.close();
+      return;
+    }
     if (!this.snapshotReady) {
+      if (!this.bufferedStateEvents.has(entityId) && this.bufferedStateEvents.size >= 10_000) {
+        this.handleDisconnected();
+        this.connection?.close();
+        return;
+      }
       this.bufferedStateEvents.set(entityId, structuredClone(eventArg));
       return;
     }
@@ -1087,7 +1183,8 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     connectionArg: homeAssistantWebsocket.Connection,
     generationArg: number,
     abortSignalArg: AbortSignal,
-    initializationDeadlineArg: number
+    initializationDeadlineArg: number,
+    selectedEntityIdsArg: string[]
   ): Promise<TConnectionGenerationResult<Record<string, string>>> {
     const responseResult = await this.runForConnectionGeneration(
       () => connectionArg.sendMessagePromise<IHomeAssistantEntityRegistryForDisplay>({
@@ -1102,25 +1199,31 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       return responseResult;
     }
     const response = responseResult.value;
-    if (!response || !Array.isArray(response.entities)) {
+    if (!response || !Array.isArray(response.entities) || response.entities.length > 10_000) {
       throw new Error('Home Assistant entity registry returned an invalid response.');
     }
 
-    const requiredEntityIds = new Set(this.config.entityIds || Object.keys(this.snapshot));
+    const requiredEntityIds = new Set(this.config.entityIds || selectedEntityIdsArg);
     const entityPlatforms: Record<string, string> = {};
     for (const entry of response.entities) {
+      homeAssistantRecord(entry);
+      if (typeof entry.ei !== 'string' || !entityIdPattern.test(entry.ei)
+        || typeof entry.pl !== 'string' || !entityDomainPattern.test(entry.pl)) {
+        throw new Error('Home Assistant entity registry returned an invalid entry.');
+      }
       if (
         entry
         && typeof entry.ei === 'string'
         && typeof entry.pl === 'string'
         && requiredEntityIds.has(entry.ei)
       ) {
+        if (Object.hasOwn(entityPlatforms, entry.ei)) throw new Error('Home Assistant entity registry returned duplicate entries.');
         entityPlatforms[entry.ei] = entry.pl;
       }
     }
     const missingEntityIds = [...requiredEntityIds]
       .filter((entityIdArg) => !entityPlatforms[entityIdArg]);
-    if (missingEntityIds.length > 0) {
+    if (this.config.requireEntityRegistry && missingEntityIds.length > 0) {
       throw new Error(
         `Home Assistant entity registry is missing required entities: ${missingEntityIds.join(', ')}`
       );

package/ts/integrations/homeassistant/homeassistant.classes.runtime.ts

@@ -7,8 +7,10 @@ import type {
   IServiceCallResult,
 } from '../../core/types.js';
 import { HomeAssistantMapper } from './homeassistant.mapper.js';
+import { homeAssistantRecord } from './homeassistant.validation.js';
 import type {
   IHomeAssistantClient,
+  IHomeAssistantTargetScope,
 } from './homeassistant.types.js';
 
 const abortError = (abortSignalArg: AbortSignal): Error => {
@@ -23,8 +25,11 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
   private destroyed = false;
   private cleanupComplete = false;
   private destroyPromise?: Promise<void>;
+  private readonly targetScope: IHomeAssistantTargetScope;
 
-  constructor(private readonly client: IHomeAssistantClient) {}
+  constructor(private readonly client: IHomeAssistantClient) {
+    this.targetScope = Object.freeze({ ...client.getTargetScope() });
+  }
 
   public isHealthy(): boolean {
     return !this.destroyed && this.client.connected;
@@ -33,24 +38,29 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
   public async devices(
     abortSignalArg?: AbortSignal
   ): Promise<shxInterfaces.data.IDeviceDefinition[]> {
+    this.assertActive();
     if (abortSignalArg?.aborted) {
       throw abortError(abortSignalArg);
     }
     return HomeAssistantMapper.toDevices(
       this.client.getSnapshot(),
       this.client.connected,
-      this.client.getEntityPlatforms()
+      this.client.getEntityPlatforms(),
+      this.client.getServices(),
+      this.targetScope
     );
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
-    return HomeAssistantMapper.toEntities(this.client.getSnapshot(), this.client.connected);
+    this.assertActive();
+    return HomeAssistantMapper.toEntities(this.client.getSnapshot(), this.client.connected, this.targetScope);
   }
 
   public async subscribe(
     handlerArg: (eventArg: IIntegrationEvent) => void,
     abortSignalArg?: AbortSignal
   ): Promise<() => Promise<void>> {
+    this.assertActive();
     if (abortSignalArg?.aborted) {
       throw abortError(abortSignalArg);
     }
@@ -87,9 +97,16 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
     requestArg: IDeviceFeatureWriteRequest,
     abortSignalArg?: AbortSignal
   ): Promise<IServiceCallResult> {
+    this.assertActive();
     if (abortSignalArg?.aborted) {
       throw abortError(abortSignalArg);
     }
+    if (Object.keys(homeAssistantRecord(requestArg)).some((key) => !['device', 'feature', 'value'].includes(key))) {
+      return { success: false, error: 'Home Assistant feature requests contain unsupported fields.' };
+    }
+    homeAssistantRecord(requestArg.device);
+    homeAssistantRecord(requestArg.feature);
+    if (requestArg.device.metadata !== undefined) homeAssistantRecord(requestArg.device.metadata);
     if (requestArg.device.integrationDomain !== this.domain) {
       return {
         success: false,
@@ -106,6 +123,23 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
       return { success: false, error: `Home Assistant entity is no longer available: ${entityId}` };
     }
 
+    if (requestArg.device.id !== HomeAssistantMapper.deviceId(entityId, this.targetScope)
+      || requestArg.device.metadata?.homeId !== this.targetScope.homeId
+      || requestArg.device.metadata?.homeAssistantInstanceId !== this.targetScope.instanceId) {
+      return { success: false, error: 'Home Assistant device target does not belong to this home and endpoint.' };
+    }
+    if (!this.client.connected || entity.state === 'unavailable' || entity.state === 'unknown') {
+      return { success: false, error: 'Home Assistant device is currently unavailable.' };
+    }
+    const currentDevice = HomeAssistantMapper.toDevices(
+      { [entityId]: entity }, true, this.client.getEntityPlatforms(), this.client.getServices(), this.targetScope
+    )[0];
+    const feature = currentDevice.features.find((current) => current.id === requestArg.feature.id);
+    if (!feature?.writable || feature.capability !== requestArg.feature.capability
+      || requestArg.feature.writable !== true || feature.readable !== requestArg.feature.readable) {
+      return { success: false, error: 'Home Assistant feature is outside the advertised writable controls.' };
+    }
+
     const mappedCall = HomeAssistantMapper.createWriteServiceCall(requestArg, entity);
     if (!mappedCall.request) {
       return { success: false, error: mappedCall.error || 'Unsupported Home Assistant write.' };
@@ -124,6 +158,10 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
     };
   }
 
+  private assertActive(): void {
+    if (this.destroyed) throw new Error('Home Assistant runtime is destroyed.');
+  }
+
   public destroy(): Promise<void> {
     if (this.destroyPromise) {
       return this.destroyPromise;