@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/homeassistant/homeassistant.mapper.ts

@@ -8,28 +8,11 @@ import type {
 import type {
   IHomeAssistantServiceCall,
   THomeAssistantVacuumCommand,
+  IHomeAssistantTargetScope,
 } from './homeassistant.types.js';
-
-const vacuumFeatureBits: Record<THomeAssistantVacuumCommand, number> = {
-  start: 8192,
-  pause: 4,
-  stop: 8,
-  return_to_base: 16,
-  locate: 512,
-  clean_spot: 1024,
-};
+import { homeAssistantBrightnessColorModes, homeAssistantSupportsPower, homeAssistantVacuumFeatureBits } from './homeassistant.validation.js';
 
 const unavailableStates = new Set(['unavailable']);
-const brightnessColorModes = new Set([
-  'brightness',
-  'color_temp',
-  'hs',
-  'rgb',
-  'rgbw',
-  'rgbww',
-  'white',
-  'xy',
-]);
 
 const attributesOf = (
   entityArg: homeAssistantWebsocket.HassEntity
@@ -95,7 +78,7 @@ const supportsBrightness = (
   const supportedColorModes = attributesOf(entityArg).supported_color_modes;
   return Array.isArray(supportedColorModes)
     && supportedColorModes.some((modeArg) => (
-      typeof modeArg === 'string' && brightnessColorModes.has(modeArg)
+      typeof modeArg === 'string' && homeAssistantBrightnessColorModes.has(modeArg)
     ));
 };
 
@@ -106,7 +89,7 @@ const supportedVacuumCommands = (
   if (typeof supportedFeatures !== 'number' || !Number.isInteger(supportedFeatures)) {
     return [];
   }
-  return (Object.entries(vacuumFeatureBits) as Array<[THomeAssistantVacuumCommand, number]>)
+  return (Object.entries(homeAssistantVacuumFeatureBits) as Array<[THomeAssistantVacuumCommand, number]>)
     .filter(([, bitArg]) => (supportedFeatures & bitArg) === bitArg)
     .map(([commandArg]) => commandArg);
 };
@@ -125,28 +108,33 @@ export class HomeAssistantMapper {
   public static toDevices(
     entitiesArg: homeAssistantWebsocket.HassEntities,
     connectedArg: boolean,
-    entityPlatformsArg: Readonly<Record<string, string>> = {}
+    entityPlatformsArg: Readonly<Record<string, string>> = {},
+    servicesArg?: ReadonlySet<string>,
+    targetScopeArg?: IHomeAssistantTargetScope
   ): shxInterfaces.data.IDeviceDefinition[] {
     return Object.values(entitiesArg)
       .sort((leftArg, rightArg) => leftArg.entity_id.localeCompare(rightArg.entity_id))
       .map((entityArg) => this.toDevice(
         entityArg,
         connectedArg,
-        entityPlatformsArg[entityArg.entity_id]
+        entityPlatformsArg[entityArg.entity_id],
+        servicesArg,
+        targetScopeArg
       ));
   }
 
   public static toEntities(
     entitiesArg: homeAssistantWebsocket.HassEntities,
-    connectedArg: boolean
+    connectedArg: boolean,
+    targetScopeArg?: IHomeAssistantTargetScope
   ): IIntegrationEntity[] {
     return Object.values(entitiesArg)
       .sort((leftArg, rightArg) => leftArg.entity_id.localeCompare(rightArg.entity_id))
       .map((entityArg) => ({
-        id: entityArg.entity_id,
-        uniqueId: entityArg.entity_id,
+        id: targetScopeArg ? this.deviceId(entityArg.entity_id, targetScopeArg) : entityArg.entity_id,
+        uniqueId: targetScopeArg ? this.deviceId(entityArg.entity_id, targetScopeArg) : entityArg.entity_id,
         integrationDomain: 'homeassistant',
-        deviceId: this.deviceId(entityArg.entity_id),
+        deviceId: this.deviceId(entityArg.entity_id, targetScopeArg),
         platform: platformOf(entityArg),
         name: nameOf(entityArg),
         state: entityArg.state,
@@ -208,7 +196,7 @@ export class HomeAssistantMapper {
         return { error: `Home Assistant vacuum commands require a supported string value for ${entityId}.` };
       }
       const command = requestArg.value as THomeAssistantVacuumCommand;
-      if (!Object.prototype.hasOwnProperty.call(vacuumFeatureBits, command)) {
+      if (!Object.prototype.hasOwnProperty.call(homeAssistantVacuumFeatureBits, command)) {
         return { error: `Unsupported Home Assistant vacuum command for ${entityId}: ${requestArg.value}` };
       }
       if (!supportedVacuumCommands(entityArg).includes(command)) {
@@ -235,18 +223,24 @@ export class HomeAssistantMapper {
     return typeof entityId === 'string' ? entityId : undefined;
   }
 
-  private static deviceId(entityIdArg: string): string {
-    return `homeassistant:${entityIdArg}`;
+  public static deviceId(entityIdArg: string, targetScopeArg?: IHomeAssistantTargetScope): string {
+    return targetScopeArg
+      ? `homeassistant:${targetScopeArg.homeId}:${targetScopeArg.instanceId}:${entityIdArg}`
+      : `homeassistant:${entityIdArg}`;
   }
 
   private static toDevice(
     entityArg: homeAssistantWebsocket.HassEntity,
     connectedArg: boolean,
-    entityPlatformArg?: string
+    entityPlatformArg?: string,
+    servicesArg?: ReadonlySet<string>,
+    targetScopeArg?: IHomeAssistantTargetScope
   ): shxInterfaces.data.IDeviceDefinition {
     const domain = domainOf(entityArg.entity_id);
     const capability = capabilityOf(entityArg);
     const attributes = attributesOf(entityArg);
+    const controlsAvailable = !servicesArg || (connectedArg
+      && entityArg.state !== 'unavailable' && entityArg.state !== 'unknown');
     const features: shxInterfaces.data.IDeviceFeature[] = [{
       id: 'state',
       capability,
@@ -269,7 +263,7 @@ export class HomeAssistantMapper {
         capability,
         name: 'Power',
         readable: true,
-        writable: true,
+        writable: controlsAvailable && (!servicesArg || homeAssistantSupportsPower(domain, servicesArg)),
       });
       state.push({
         featureId: 'power',
@@ -288,7 +282,7 @@ export class HomeAssistantMapper {
         capability: 'light',
         name: 'Brightness',
         readable: true,
-        writable: true,
+        writable: controlsAvailable && (!servicesArg || servicesArg.has('light.turn_on')),
         unit: '%',
       });
       state.push({
@@ -298,19 +292,20 @@ export class HomeAssistantMapper {
       });
     }
 
-    const vacuumCommands = domain === 'vacuum' ? supportedVacuumCommands(entityArg) : [];
+    const vacuumCommands = domain === 'vacuum' ? supportedVacuumCommands(entityArg)
+      .filter((command) => !servicesArg || servicesArg.has(`vacuum.${command}`)) : [];
     if (vacuumCommands.length > 0) {
       features.push({
         id: 'command',
         capability: 'vacuum',
         name: 'Command',
         readable: false,
-        writable: true,
+        writable: controlsAvailable,
       });
     }
 
     return {
-      id: this.deviceId(entityArg.entity_id),
+      id: this.deviceId(entityArg.entity_id, targetScopeArg),
       integrationDomain: 'homeassistant',
       name: nameOf(entityArg),
       protocol: 'homeassistant',
@@ -318,6 +313,7 @@ export class HomeAssistantMapper {
       features,
       state,
       metadata: {
+        ...(targetScopeArg ? { homeId: targetScopeArg.homeId, homeAssistantInstanceId: targetScopeArg.instanceId } : {}),
         homeAssistantEntityId: entityArg.entity_id,
         homeAssistantDomain: domain,
         homeAssistantPlatform: entityPlatformArg,

package/ts/integrations/homeassistant/homeassistant.types.ts

@@ -9,6 +9,7 @@ export type THomeAssistantVacuumCommand =
   | 'clean_spot';
 
 export interface IHomeAssistantHomeassistantConfig {
+  homeId: string;
   baseUrl: string;
   accessToken: string;
   entityIds?: string[];
@@ -21,6 +22,8 @@ export interface IHomeAssistantHomeassistantConfig {
 }
 
 export interface IHomeAssistantNormalizedConfig {
+  homeId: string;
+  instanceId: string;
   baseUrl: string;
   accessToken: string;
   entityIds?: Set<string>;
@@ -58,6 +61,7 @@ export interface IHomeAssistantWebsocketApi {
   createConnection: typeof homeAssistantWebsocket.createConnection;
   subscribeEntities: typeof homeAssistantWebsocket.subscribeEntities;
   getStates: typeof homeAssistantWebsocket.getStates;
+  getServices: typeof homeAssistantWebsocket.getServices;
   callService: typeof homeAssistantWebsocket.callService;
 }
 
@@ -66,6 +70,8 @@ export interface IHomeAssistantClient {
   init(abortSignalArg?: AbortSignal): Promise<void>;
   getSnapshot(): homeAssistantWebsocket.HassEntities;
   getEntityPlatforms(): Record<string, string>;
+  getServices(): ReadonlySet<string>;
+  getTargetScope(): IHomeAssistantTargetScope;
   subscribe(handlerArg: () => void): () => void;
   callService(
     requestArg: IHomeAssistantServiceCall,
@@ -73,3 +79,8 @@ export interface IHomeAssistantClient {
   ): Promise<unknown>;
   destroy(): Promise<void>;
 }
+
+export interface IHomeAssistantTargetScope {
+  readonly homeId: string;
+  readonly instanceId: string;
+}

package/ts/integrations/homeassistant/homeassistant.validation.ts

@@ -0,0 +1,139 @@
+import type * as homeAssistantWebsocket from 'home-assistant-js-websocket';
+import type { IHomeAssistantServiceCall, THomeAssistantVacuumCommand } from './homeassistant.types.js';
+
+const entityIdPattern = /^[a-z0-9_]+\.[a-z0-9_]+$/;
+const actionNamePattern = /^[a-z0-9_]+$/;
+
+export const homeAssistantVacuumFeatureBits: Record<THomeAssistantVacuumCommand, number> = {
+  start: 8192, pause: 4, stop: 8, return_to_base: 16, locate: 512, clean_spot: 1024,
+};
+export const homeAssistantBrightnessColorModes = new Set([
+  'brightness', 'color_temp', 'hs', 'rgb', 'rgbw', 'rgbww', 'white', 'xy',
+]);
+
+export const homeAssistantSupportsPower = (domainArg: string, servicesArg: ReadonlySet<string>): boolean => (
+  ['turn_on', 'turn_off'].every((service) => servicesArg.has(`${domainArg}.${service}`))
+);
+
+export const homeAssistantRecord = (valueArg: unknown): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new Error('Home Assistant requires a plain data object.');
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  if (Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string'
+    || !descriptors[keyArg]?.enumerable || !('value' in descriptors[keyArg]))) {
+    throw new Error('Home Assistant requires own enumerable data properties.');
+  }
+  return valueArg as Record<string, unknown>;
+};
+
+export const validateHomeAssistantEntity = (valueArg: unknown): homeAssistantWebsocket.HassEntity => {
+  const entity = homeAssistantRecord(valueArg);
+  if (typeof entity.entity_id !== 'string' || entity.entity_id.length > 255
+    || !entityIdPattern.test(entity.entity_id) || typeof entity.state !== 'string'
+    || entity.state.length > 4096 || typeof entity.last_changed !== 'string'
+    || !Number.isFinite(Date.parse(entity.last_changed)) || typeof entity.last_updated !== 'string'
+    || !Number.isFinite(Date.parse(entity.last_updated))) {
+    throw new Error('Home Assistant returned an invalid entity state.');
+  }
+  homeAssistantRecord(entity.attributes);
+  let nodes = 0;
+  const validateJson = (value: unknown, depth: number): void => {
+    if (++nodes > 4096 || depth > 16) throw new Error('Home Assistant entity attributes exceed their bounds.');
+    if (value === null || typeof value === 'boolean') return;
+    if (typeof value === 'string' && value.length <= 16_384) return;
+    if (typeof value === 'number' && Number.isFinite(value)) return;
+    if (Array.isArray(value)) {
+      if (value.length > 4096) throw new Error('Home Assistant entity attributes exceed their bounds.');
+      value.forEach((entry) => validateJson(entry, depth + 1));
+      return;
+    }
+    Object.values(homeAssistantRecord(value)).forEach((entry) => validateJson(entry, depth + 1));
+  };
+  validateJson(entity.attributes, 0);
+  const context = homeAssistantRecord(entity.context);
+  if (typeof context.id !== 'string'
+    || !(context.user_id === null || typeof context.user_id === 'string')
+    || !(context.parent_id === null || typeof context.parent_id === 'string')) {
+    throw new Error('Home Assistant returned invalid entity context.');
+  }
+  return structuredClone(entity) as homeAssistantWebsocket.HassEntity;
+};
+
+export const validateHomeAssistantServices = (valueArg: unknown): Set<string> => {
+  const result = new Set<string>();
+  const domains = homeAssistantRecord(valueArg);
+  let serviceCount = 0;
+  if (Object.keys(domains).length > 1000) throw new Error('Home Assistant service catalogue exceeds its bounds.');
+  for (const [domain, services] of Object.entries(domains)) {
+    if (!actionNamePattern.test(domain)) throw new Error('Home Assistant returned an invalid service domain.');
+    for (const [service, description] of Object.entries(homeAssistantRecord(services))) {
+      if (++serviceCount > 10_000) throw new Error('Home Assistant service catalogue exceeds its bounds.');
+      if (!actionNamePattern.test(service)) throw new Error('Home Assistant returned an invalid service action.');
+      const descriptor = homeAssistantRecord(description);
+      const fields = homeAssistantRecord(descriptor.fields);
+      if (Object.keys(fields).length > 1000) throw new Error('Home Assistant service fields exceed their bounds.');
+      const needsUnsupportedFields = Object.entries(fields).some(([name, field]) => {
+        const required = homeAssistantRecord(field).required;
+        if (required !== undefined && typeof required !== 'boolean') throw new Error('Home Assistant returned invalid service field requirements.');
+        return required === true && name !== 'entity_id';
+      });
+      const needsResponse = descriptor.response !== undefined && homeAssistantRecord(descriptor.response).optional === false;
+      if (needsUnsupportedFields || needsResponse) continue;
+      result.add(`${domain}.${service}`);
+    }
+  }
+  return result;
+};
+
+export const validateHomeAssistantServiceCall = (
+  valueArg: IHomeAssistantServiceCall,
+  entityArg: homeAssistantWebsocket.HassEntity,
+  servicesArg: ReadonlySet<string>
+): IHomeAssistantServiceCall => {
+  const request = homeAssistantRecord(valueArg);
+  const keys = Object.keys(request);
+  if (keys.some((key) => !['domain', 'service', 'data', 'target'].includes(key))) {
+    throw new Error('Home Assistant service calls contain unsupported fields.');
+  }
+  const target = homeAssistantRecord(request.target);
+  const domain = entityArg.entity_id.split('.')[0];
+  if (Object.keys(target).length !== 1 || target.entity_id !== entityArg.entity_id
+    || request.domain !== domain || typeof request.service !== 'string'
+    || !servicesArg.has(`${domain}.${request.service}`)) {
+    throw new Error('Home Assistant service target or advertised action is invalid.');
+  }
+  if (entityArg.state === 'unavailable' || entityArg.state === 'unknown') {
+    throw new Error('Home Assistant cannot control an unavailable entity.');
+  }
+  const data = request.data === undefined ? {} : homeAssistantRecord(request.data);
+  const hasBrightness = Object.keys(data).length === 1 && Object.hasOwn(data, 'brightness');
+  if (['light', 'switch', 'input_boolean'].includes(domain)
+    && ['turn_on', 'turn_off'].includes(request.service)) {
+    if (Object.keys(data).length === 0 && !homeAssistantSupportsPower(domain, servicesArg)) {
+      throw new Error('Home Assistant entity does not advertise complete power controls.');
+    }
+    if (Object.keys(data).length > 0 && !(domain === 'light' && request.service === 'turn_on'
+      && hasBrightness && typeof data.brightness === 'number' && Number.isInteger(data.brightness)
+      && data.brightness >= 1 && data.brightness <= 255
+      && Array.isArray(entityArg.attributes.supported_color_modes)
+      && entityArg.attributes.supported_color_modes.some((mode: unknown) =>
+        typeof mode === 'string' && homeAssistantBrightnessColorModes.has(mode)))) {
+      throw new Error('Home Assistant service data is outside the supported control contract.');
+    }
+  } else {
+    const features: unknown = entityArg.attributes.supported_features;
+    const bit = homeAssistantVacuumFeatureBits[request.service as THomeAssistantVacuumCommand];
+    if (domain !== 'vacuum' || !Object.hasOwn(homeAssistantVacuumFeatureBits, request.service)
+      || typeof features !== 'number' || !Number.isInteger(features)
+      || (features & bit) !== bit
+      || Object.keys(data).length > 0) {
+      throw new Error('Home Assistant service is outside the supported control contract.');
+    }
+  }
+  return {
+    domain, service: request.service, target: { entity_id: entityArg.entity_id },
+    ...(hasBrightness ? { data: { brightness: data.brightness } } : {}),
+  };
+};

package/ts/integrations/homeassistant/readme.md

@@ -0,0 +1,40 @@
+# Home Assistant runtime
+
+`HomeAssistantHomeassistantIntegration` connects directly to Home Assistant's authenticated `/api/websocket` endpoint through the installed official `home-assistant-js-websocket` client and Node's native WebSocket. Its existing optional WebSocket-factory constructor remains available. Production contains no fixture entities or credentials.
+
+```typescript
+const integration = new HomeAssistantHomeassistantIntegration();
+const runtime = await integration.setup({
+  homeId: 'house-a',
+  baseUrl: 'https://ha.example.test:8123',
+  accessToken: configuredHomeAssistantToken,
+  entityIds: ['light.kitchen', 'switch.office', 'vacuum.downstairs'],
+  requireEntityIds: true,
+  requireEntityRegistry: true,
+  setupRetry: 0,
+  initialSnapshotTimeoutMs: 10_000,
+  serviceCallTimeoutMs: 15_000,
+}, { abortSignal });
+try {
+  const devices = await runtime.devices();
+  // Send selected advertised features through the hub's scoped tool boundary.
+} finally {
+  await runtime.destroy();
+}
+```
+
+`homeId`, an HTTP(S) origin without user information, path, query or fragment, and a nonempty configured access token are required. Home IDs contain 1–128 alphanumeric, underscore, period, colon or hyphen characters and begin with an alphanumeric character. The exact configured ID is preserved, including case and colons in IDs such as `home:studio` and `home:unconfigured`; it is never trimmed or renamed. Optional entity IDs and domains form intersecting allowlists. Credentials stay in runtime configuration; a caller that persists configuration must use the core encrypted NoSql config store and its external key provider. This integration writes no application data to the filesystem.
+
+Setup uses one deadline for authentication, subscription acknowledgements, an authoritative `get_states` snapshot, `get_services`, and `config/entity_registry/list_for_display`. Registry provenance is fetched for selected entities even when strict registry enforcement is disabled. Strict enforcement additionally requires every explicitly configured entity to exist in the state and registry snapshots. Home Assistant must support these documented commands; an unsupported or malformed response rejects setup.
+
+Device and entity IDs include the configured home ID and a stable hash of the endpoint origin. Changing a returned snapshot, its entity metadata or its feature list cannot redirect writes. A runtime admits only its own home, endpoint, integration domain, canonical device ID and currently advertised writable feature. The caller's device state and writable claims confer no authority; home access and approvals remain owned by the hub.
+
+Supported writes are exact light/switch/input-boolean `turn_on` and `turn_off`, integer light brightness percentages 1–100 mapped to HA brightness 1–255, and the vacuum commands advertised by its supported-feature bits. A service must also exist in the current live service catalogue. Services requiring fields outside this contract or mandatory response handling are excluded. Power remains readable when its complete pair of control actions is absent. Direct client calls enforce the same selected-entity, action, value and target restrictions; area, label, device-group, wildcard and arbitrary service-data targeting are rejected.
+
+`state_changed` updates are authoritative. Service acknowledgements never synthesize state. `service_registered`, `service_removed` and `entity_registry_updated` events revoke snapshot readiness until fresh state, service and registry snapshots complete. Reconnects do the same before health or writes recover. Missing required entities, offline entities, malformed states or inconsistent event targets block controls. A malformed state event closes its connection and leaves retained devices offline.
+
+Snapshots and buffered events are bounded at 10,000 entities, services at 10,000 actions and 1,000 domains, and entity attributes at depth 16 and 4,096 values. Caller aborts and write deadlines cancel the pending command through the owning connection; commands are never retried or replayed by this adapter. Cancellation after dispatch leaves the physical effect uncertain. Destroy aborts pending callers, releases all subscriptions, closes sockets, waits for physical closure up to one second, clears retained data and makes the runtime terminal. Failed cleanup remains retryable through `destroy()`.
+
+The local test fixtures use real HTTP upgrades and native WebSockets with test-only tokens. They verify exact request bytes, catalogue changes, registry refresh, reconnect readiness, authoritative state, malformed inputs, cross-home and mutated-target rejection, cancellation and physical closure. Hardware acceptance against the owner's Home Assistant remains outside this lane.
+
+API references: [Home Assistant WebSocket API](https://developers.home-assistant.io/docs/api/websocket/), [REST API](https://developers.home-assistant.io/docs/api/rest/), and [official JavaScript client](https://github.com/home-assistant/home-assistant-js-websocket).