@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/lifx/lifx.classes.integration.ts

@@ -1,17 +1,152 @@
-import { SimpleLocalIntegration } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { LifxClient } from './lifx.classes.client.js';
 import { LifxConfigFlow } from './lifx.classes.configflow.js';
 import { createLifxDiscoveryDescriptor } from './lifx.discovery.js';
-import type { ILifxConfig } from './lifx.types.js';
-import { lifxDomain, lifxProfile } from './lifx.types.js';
+import { LifxMapper } from './lifx.mapper.js';
+import type { ILifxConfig, ILifxSnapshot } from './lifx.types.js';
+import { lifxProfile } from './lifx.types.js';
+import { assertLifxStoreScope, lifxInteger, lifxKeys, lifxRecord, normalizeLifxConfig, readLifxColor } from './lifx.validation.js';
 
-export class LifxIntegration extends SimpleLocalIntegration<ILifxConfig> {
-  public readonly domain = lifxDomain;
+export class LifxIntegration extends BaseIntegration<ILifxConfig> {
+  public readonly domain = 'lifx';
+  public readonly displayName = 'LIFX';
+  public readonly status = 'control-runtime' as const;
+  public readonly metadata = lifxProfile.metadata;
   public readonly discoveryDescriptor = createLifxDiscoveryDescriptor();
   public readonly configFlow = new LifxConfigFlow();
+  readonly #runtimes = new Set<LifxRuntime>();
+  readonly #pending = new Set<LifxClient>();
+  readonly #setups = new Set<Promise<IIntegrationRuntime>>();
+  #closed = false;
+  #closePromise?: Promise<void>;
 
-  constructor() {
-    super(lifxProfile);
+  public setup(configArg: ILifxConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.#closed) return Promise.reject(new Error('LIFX integration is destroyed.'));
+    const setup = this.#createRuntime(configArg, contextArg).finally(() => this.#setups.delete(setup));
+    this.#setups.add(setup);
+    return setup;
+  }
+
+  async #createRuntime(configArg: ILifxConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const config = normalizeLifxConfig(configArg);
+    assertLifxStoreScope(contextArg.configStore, config.homeId);
+    const client = new LifxClient(config, contextArg.abortSignal);
+    this.#pending.add(client);
+    try {
+      const snapshot = await client.getSnapshot(contextArg.abortSignal);
+      if (this.#closed || contextArg.abortSignal?.aborted) throw new Error('LIFX setup was canceled.');
+      const runtime = new LifxRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
+      this.#runtimes.add(runtime);
+      return runtime;
+    } catch (errorArg) {
+      await client.destroy();
+      throw errorArg;
+    } finally { this.#pending.delete(client); }
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closed = true;
+    this.#closePromise = Promise.resolve().then(async () => {
+      await Promise.all([
+        ...[...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()),
+        ...[...this.#pending].map((clientArg) => clientArg.destroy()),
+      ]);
+      await Promise.allSettled([...this.#setups]);
+    });
+    return this.#closePromise;
   }
 }
 
 export class HomeAssistantLifxIntegration extends LifxIntegration {}
+
+class LifxRuntime implements IIntegrationRuntime {
+  public readonly domain = 'lifx';
+  readonly #deviceId: string;
+  readonly #entityId: string;
+  readonly #hasLight: boolean;
+  #closePromise?: Promise<void>;
+
+  constructor(private readonly client: LifxClient, identityArg: ILifxSnapshot, private readonly released: () => void) {
+    this.#deviceId = LifxMapper.deviceId(identityArg);
+    this.#entityId = LifxMapper.lightEntityId(identityArg);
+    this.#hasLight = identityArg.lightState !== undefined;
+  }
+
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return LifxMapper.toDevices(await this.client.getSnapshot(signalArg));
+  }
+  public async entities(): Promise<IIntegrationEntity[]> { return LifxMapper.toEntities(await this.client.getSnapshot()); }
+
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      const request = lifxRecord(requestArg, 'service request');
+      lifxKeys(request, ['domain', 'service', 'target', 'data']);
+      if (typeof request.domain !== 'string' || typeof request.service !== 'string') throw new TypeError('LIFX service domain and service must be strings.');
+      this.#assertTarget(request.target);
+      const data = request.data === undefined ? {} : lifxRecord(request.data, 'service data');
+      if (request.domain === 'lifx' && ['status', 'snapshot', 'refresh'].includes(request.service)) {
+        lifxKeys(data, []);
+        return { success: true, data: await this.client.getSnapshot() };
+      }
+      if (request.domain === 'light' && ['turn_on', 'turn_off'].includes(request.service)) {
+        lifxKeys(data, ['durationMs']);
+        const duration = lifxInteger(data.durationMs === undefined ? 0 : data.durationMs, 0, 60000, 'durationMs');
+        return accepted(await this.client.setPower(request.service === 'turn_on', duration));
+      }
+      if (request.domain === 'lifx' && request.service === 'set_hsbk') {
+        lifxKeys(data, ['hue', 'saturation', 'brightness', 'kelvin', 'durationMs']);
+        const color = readLifxColor({ hue: data.hue, saturation: data.saturation, brightness: data.brightness, kelvin: data.kelvin });
+        const duration = lifxInteger(data.durationMs === undefined ? 0 : data.durationMs, 0, 60000, 'durationMs');
+        return accepted(await this.client.setHsbk(color, duration));
+      }
+      throw new TypeError('LIFX service is unsupported.');
+    } catch (errorArg) { return failed(errorArg); }
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = lifxRecord(requestArg, 'feature write');
+      lifxKeys(request, ['device', 'feature', 'value']);
+      const device = lifxRecord(request.device, 'feature device');
+      const feature = lifxRecord(request.feature, 'feature');
+      if (device.id !== this.#deviceId || device.integrationDomain !== this.domain) throw new TypeError('LIFX feature device is not owned by this home runtime.');
+      if (feature.id === 'power') {
+        if (typeof request.value !== 'boolean') throw new TypeError('LIFX power feature requires a boolean.');
+        return accepted(await this.client.setPower(request.value, 0, signalArg));
+      }
+      if (feature.id === 'hsbk') return accepted(await this.client.setHsbk(readLifxColor(request.value), 0, signalArg));
+      throw new TypeError('LIFX feature is not writable.');
+    } catch (errorArg) { return failed(errorArg); }
+  }
+
+  public destroy(): Promise<void> {
+    this.#closePromise ??= this.client.destroy().then(() => { this.released(); });
+    return this.#closePromise;
+  }
+
+  #assertTarget(valueArg: unknown): void {
+    const target = lifxRecord(valueArg, 'service target');
+    lifxKeys(target, ['deviceId', 'entityId']);
+    if (target.deviceId === undefined && target.entityId === undefined ||
+      target.deviceId !== undefined && target.deviceId !== this.#deviceId ||
+      target.entityId !== undefined && (target.entityId !== this.#entityId || !this.#hasLight)) {
+      throw new TypeError('LIFX services require one exact owned device or light entity target.');
+    }
+  }
+}
+
+function accepted(resultArg: plugins.ecobridgeDeviceManager.ILifxWriteResult): IServiceCallResult {
+  return { success: true, data: { effectOutcome: resultArg.outcome, observedState: { ...resultArg.observedState }, physicalCompletion: 'unconfirmed' } };
+}
+function failed(errorArg: unknown): IServiceCallResult {
+  return {
+    success: false,
+    error: errorArg instanceof Error ? errorArg.message : 'LIFX operation failed.',
+    data: { effectOutcome: errorArg instanceof plugins.ecobridgeDeviceManager.LifxProtocolError ? errorArg.effectOutcome : 'not-sent',
+      code: errorArg instanceof plugins.ecobridgeDeviceManager.LifxProtocolError ? errorArg.code : 'INVALID_OPERATION' },
+  };
+}

package/ts/integrations/lifx/lifx.discovery.ts

@@ -1,4 +1,27 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { lifxProfile } from './lifx.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch } from '../../core/types.js';
+import { lifxName, lifxRecord, readLifxEndpoint } from './lifx.validation.js';
 
-export const createLifxDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(lifxProfile);
+function matchCandidate(valueArg: unknown): IDiscoveryMatch {
+  try {
+    const input = lifxRecord(valueArg, 'discovery candidate');
+    if (input.source !== 'manual' && input.source !== 'custom' || input.integrationDomain !== 'lifx') {
+      return { matched: false, confidence: 'low', reason: 'An explicit manual/custom LIFX candidate is required.' };
+    }
+    const endpoint = readLifxEndpoint(input.host, input.macAddress, input.port);
+    const candidate: IDiscoveryCandidate = {
+      source: input.source === 'manual' ? 'manual' : 'custom', integrationDomain: 'lifx', ...endpoint,
+      name: input.name === undefined ? undefined : lifxName(input.name, 'candidate name'),
+    };
+    return { matched: true, confidence: 'medium', reason: 'Explicit LIFX endpoint/MAC binding; live identity is checked during setup.', candidate };
+  } catch (errorArg) {
+    return { matched: false, confidence: 'low', reason: errorArg instanceof Error ? errorArg.message : 'Invalid LIFX endpoint candidate.' };
+  }
+}
+
+export function createLifxDiscoveryDescriptor(): DiscoveryDescriptor {
+  return new DiscoveryDescriptor({ integrationDomain: 'lifx', displayName: 'LIFX' })
+    .addMatcher({ id: 'lifx-manual-match', source: 'manual', matches: async (inputArg) => matchCandidate(inputArg) })
+    .addMatcher({ id: 'lifx-custom-match', source: 'custom', matches: async (inputArg) => matchCandidate(inputArg) })
+    .addValidator({ id: 'lifx-explicit-endpoint', validate: async (candidateArg) => matchCandidate(candidateArg) });
+}

package/ts/integrations/lifx/lifx.mapper.ts

@@ -1,26 +1,54 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { ILifxConfig } from './lifx.types.js';
-import { lifxProfile } from './lifx.types.js';
+import type * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { ILifxSnapshot } from './lifx.types.js';
 
 export class LifxMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<ILifxConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: lifxProfile });
+  public static deviceId(snapshotArg: Pick<ILifxSnapshot, 'homeId' | 'deviceInfo'>): string {
+    return `lifx:${encodeURIComponent(snapshotArg.homeId)}:${snapshotArg.deviceInfo.macAddress}`;
   }
-
-  public static toSnapshotFromRaw(configArg: ILifxConfig, rawDataArg: TSimpleLocalRawData): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: lifxProfile, config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
-  }
-
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(lifxProfile, snapshotArg);
+  public static lightEntityId(snapshotArg: Pick<ILifxSnapshot, 'homeId' | 'deviceInfo'>): string {
+    return `${this.deviceId(snapshotArg)}:light`;
   }
 
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(lifxProfile, snapshotArg);
+  public static toDevices(snapshotArg: ILifxSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const info = snapshotArg.deviceInfo;
+    const light = snapshotArg.lightState;
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
+      { id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false },
+      { id: 'product', capability: 'sensor', name: 'Product', readable: true, writable: false },
+      { id: 'firmware', capability: 'sensor', name: 'Firmware', readable: true, writable: false },
+    ];
+    const state: plugins.shxInterfaces.data.IDeviceState[] = [
+      { featureId: 'connectivity', value: 'online', updatedAt: snapshotArg.observedAt },
+      { featureId: 'product', value: info.product, updatedAt: snapshotArg.observedAt },
+      { featureId: 'firmware', value: `${info.firmware.major}.${info.firmware.minor}`, updatedAt: snapshotArg.observedAt },
+    ];
+    if (light) {
+      const singleZone = info.capabilities?.layout === 'single-zone' && info.capabilities.temperatureRange !== undefined;
+      features.push({ id: 'power', capability: 'light', name: 'Power', readable: true, writable: singleZone });
+      state.push({ featureId: 'power', value: light.power > 0, updatedAt: snapshotArg.observedAt });
+      features.push({ id: 'hsbk', capability: 'light', name: 'HSBK (exact uint16 units)', readable: true, writable: singleZone && info.capabilities?.color === true });
+      state.push({ featureId: 'hsbk', value: { hue: light.hue, saturation: light.saturation, brightness: light.brightness, kelvin: light.kelvin }, updatedAt: snapshotArg.observedAt });
+    }
+    return [{
+      id: this.deviceId(snapshotArg), integrationDomain: 'lifx', name: snapshotArg.name,
+      manufacturer: info.vendor === 1 ? 'LIFX' : undefined,
+      model: info.capabilities?.name, protocol: 'udp', online: snapshotArg.online,
+      features, state,
+      metadata: { homeId: snapshotArg.homeId, macAddress: info.macAddress, vendor: info.vendor, product: info.product,
+        firmwareBuild: info.firmware.build, capabilities: info.capabilities, lanAuthenticated: false },
+    }];
   }
 
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
+  public static toEntities(snapshotArg: ILifxSnapshot): IIntegrationEntity[] {
+    const light = snapshotArg.lightState;
+    if (!light) return [];
+    return [{
+      id: this.lightEntityId(snapshotArg), uniqueId: this.lightEntityId(snapshotArg), deviceId: this.deviceId(snapshotArg),
+      integrationDomain: 'lifx', platform: 'light', name: snapshotArg.name, state: light.power > 0 ? 'on' : 'off',
+      available: snapshotArg.online,
+      attributes: { hue: light.hue, saturation: light.saturation, brightness: light.brightness, kelvin: light.kelvin,
+        rawPower: light.power, observedAt: snapshotArg.observedAt, capabilities: snapshotArg.deviceInfo.capabilities },
+    }];
   }
 }

package/ts/integrations/lifx/lifx.types.ts

@@ -1,132 +1,58 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+export const lifxDomain = 'lifx';
+export const lifxDefaultName = 'LIFX';
 
-export const lifxDomain = "lifx";
-export const lifxDefaultName = "LIFX";
-
-export type TLifxRawData = TSimpleLocalRawData;
-export interface ILifxSnapshot extends ISimpleLocalSnapshot {}
-export interface ILifxConfig extends ISimpleLocalConfig {
-  url?: string;
-  macAddress?: string;
-  deviceId?: string;
+export interface ILifxConfig {
+  homeId: string;
+  host: string;
+  macAddress: string;
+  /** Endpoint/MAC binding does not authenticate the LAN peer cryptographically. */
+  allowUnencryptedLan: true;
+  port?: number;
+  name?: string;
+  requestTimeoutMs?: number;
+  maxPendingOperations?: number;
 }
 export interface IHomeAssistantLifxConfig extends ILifxConfig {}
 
-export const lifxProfile: ISimpleLocalIntegrationProfile = {
-  domain: lifxDomain,
-  displayName: "LIFX",
-  manufacturer: "LIFX",
-  model: "LIFX local integration",
-  defaultName: lifxDefaultName,
-  defaultProtocol: 'local',
-  status: "control-runtime",
-  platforms: [
-    "binary_sensor",
-    "button",
-    "light",
-    "select",
-    "sensor",
-  ],
-  serviceDomains: [
-    "button",
-    "light",
-    "select",
-  ],
-  controlServices: [
-    "effect_colorloop",
-    "effect_flame",
-    "effect_morph",
-    "effect_move",
-    "effect_pulse",
-    "effect_sky",
-    "effect_stop",
-    "paint_theme",
-    "press",
-    "select_option",
-    "set_hev_cycle_state",
-    "set_state",
-    "toggle",
-    "turn_off",
-    "turn_on",
-  ],
-  discoverySources: [
-    'manual',
-    'custom',
-  ],
-  discoveryKeywords: [
-    "lifx",
-    "LIFX",
-    "Lifx",
-  ],
+export interface ILifxColor {
+  hue: number;
+  saturation: number;
+  brightness: number;
+  kelvin: number;
+}
+export interface ILifxLightState extends ILifxColor { power: number; label: string; }
+
+export interface ILifxDeviceIdentity {
+  macAddress: string;
+  vendor: number;
+  product: number;
+  firmware: { build: string; major: number; minor: number };
+  capabilities?: {
+    name: string;
+    color: boolean;
+    layout: 'single-zone' | 'linear' | 'matrix' | 'chain' | 'relay' | 'unsupported';
+    temperatureRange?: readonly [number, number];
+  };
+}
+/** JSON-safe observations, never an injectable production data source. */
+export interface ILifxSnapshot {
+  homeId: string;
+  name: string;
+  deviceInfo: ILifxDeviceIdentity;
+  lightState?: ILifxLightState;
+  observedAt: string;
+  online: true;
+}
+export type TLifxRawData = ILifxSnapshot;
+
+export const lifxProfile = {
+  domain: lifxDomain, displayName: lifxDefaultName, status: 'control-runtime',
   metadata: {
-    "source": "home-assistant/core",
-    "upstreamPath": "homeassistant/components/lifx",
-    "upstreamDomain": "lifx",
-    "integrationType": "device",
-    "iotClass": "local_polling",
-    "requirements": [
-      "aiolifx==1.2.1",
-      "aiolifx-effects==0.3.2",
-      "aiolifx-themes==1.0.2",
-    ],
-    "dependencies": [
-      "network",
-    ],
-    "codeowners": [
-      "@Djelibeybi",
-    ],
-    "configFlow": true,
-    "documentation": "https://www.home-assistant.io/integrations/lifx",
-    "loggers": [
-      "aiolifx",
-      "aiolifx_effects",
-      "bitstring",
-    ],
-    "runtime": {
-      "type": "control-runtime",
-      "services": [
-        "snapshot",
-        "status",
-        "refresh",
-        "effect_colorloop",
-        "effect_flame",
-        "effect_morph",
-        "effect_move",
-        "effect_pulse",
-        "effect_sky",
-        "effect_stop",
-        "paint_theme",
-        "press",
-        "select_option",
-        "set_hev_cycle_state",
-        "set_state",
-        "toggle",
-        "turn_off",
-        "turn_on",
-      ],
-      "platforms": [
-        "binary_sensor",
-        "button",
-        "light",
-        "select",
-        "sensor",
-      ],
-      "controls": "delegated only to an injected client.execute or commandExecutor; native live LIFX LAN control is blocked by the aiolifx UDP binary protocol/effects stack",
-    },
-    "localApi": {
-      "status": "snapshot/injected-client only: Home Assistant uses aiolifx over the LIFX LAN UDP binary protocol on port 56700 plus aiolifx-effects/aiolifx-themes; no HTTP/TCP/TLS/file protocol is available to implement with the allowed runtime helpers",
-      "implemented": [
-        "manual local setup for LIFX snapshots, rawData, snapshotProvider, and injected native clients",
-        "runtime mapping for LIFX device snapshots and Home Assistant platform metadata",
-        "safe command delegation to injected client.execute or commandExecutor only",
-      ],
-      "explicitUnsupported": [
-        "native live LIFX LAN polling/control: requires aiolifx UDP binary protocol implementation and effect/theme libraries, not an HTTP/TCP/TLS/file protocol available through existing helpers",
-        "LIFX UDP broadcast discovery and HomeKit/DHCP confirmation flows that depend on aiolifx LIFXConnection",
-        "claiming live LIFX polling, pairing, subscription, or write success without an injected native client or snapshotProvider",
-        "Home Assistant entity registry migrations and repair flows",
-        "claiming command success without injected client.execute or commandExecutor",
-      ],
+    source: 'home-assistant/core', upstreamDomain: lifxDomain, configFlow: true,
+    localApi: {
+      status: 'Native explicit-unicast LIFX LAN UDP binary protocol through devicemanager.',
+      implemented: ['home-scoped device identity', 'firmware-derived single-zone capability admission', 'power and full exact-wire HSBK control', 'one-shot acceptance and independent state observation'],
+      explicitUnsupported: ['broadcast discovery', 'cloud access', 'injected clients and snapshots', 'partial HSBK patches', 'white-product HSBK writes', 'multizone/matrix/chain/relay control', 'effects/themes/HEV/infrared', 'toggle and automatic effect retries', 'cryptographic LAN peer authentication'],
     },
   },
-};
+} as const;

package/ts/integrations/lifx/lifx.validation.ts

@@ -0,0 +1,86 @@
+import * as plugins from '../../plugins.js';
+import type { IConfigStore } from '../../core/types.js';
+import type { ILifxColor, ILifxConfig } from './lifx.types.js';
+
+export function lifxRecord(valueArg: unknown, nameArg: string): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError(`LIFX ${nameArg} 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' || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError(`LIFX ${nameArg} may not contain symbols, accessors or hidden fields.`);
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function lifxKeys(recordArg: Record<string, unknown>, keysArg: readonly string[]): void {
+  if (Object.keys(recordArg).some((keyArg) => !keysArg.includes(keyArg))) throw new TypeError('LIFX data contains unsupported fields.');
+}
+
+export function lifxInteger(valueArg: unknown, minimumArg: number, maximumArg: number, nameArg: string): number {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new RangeError(`LIFX ${nameArg} must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return valueArg;
+}
+
+export function lifxName(valueArg: unknown, nameArg: string, maximumArg = 256): string {
+  if (typeof valueArg !== 'string' || !valueArg.trim() || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`LIFX ${nameArg} must be a non-empty string without control characters, at most ${maximumArg} characters.`);
+  }
+  return valueArg;
+}
+
+export function readLifxEndpoint(hostArg: unknown, macArg: unknown, portArg?: unknown): Pick<ILifxConfig, 'host' | 'macAddress' | 'port'> {
+  const host = hostArg;
+  if (typeof host !== 'string' || plugins.net.isIP(host) !== 4) throw new TypeError('LIFX host must be an explicit local unicast IPv4 address.');
+  const octets = host.split('.').map(Number);
+  const local = octets[0] === 10 || octets[0] === 127 || octets[0] === 192 && octets[1] === 168 ||
+    octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31 || octets[0] === 169 && octets[1] === 254;
+  if (!local || octets[3] === 255) throw new TypeError('LIFX host must be a private, loopback or link-local unicast IPv4 address.');
+  const mac = macArg;
+  if (typeof mac !== 'string' || !/^(?:[0-9a-fA-F]{12}|(?:[0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2})$/.test(mac)) {
+    throw new TypeError('LIFX macAddress must contain exactly six hexadecimal bytes.');
+  }
+  const macAddress = mac.replaceAll(':', '').toLowerCase();
+  if (macAddress === '000000000000' || (parseInt(macAddress.slice(0, 2), 16) & 1) !== 0) throw new TypeError('LIFX MAC must identify one unicast device.');
+  return { host, macAddress, port: lifxInteger(portArg === undefined ? 56700 : portArg, 1, 65535, 'port') };
+}
+
+export function normalizeLifxConfig(valueArg: unknown): Readonly<ILifxConfig> {
+  const config = lifxRecord(valueArg, 'configuration');
+  lifxKeys(config, ['homeId', 'host', 'macAddress', 'allowUnencryptedLan', 'port', 'name', 'requestTimeoutMs', 'maxPendingOperations']);
+  const homeId = lifxName(config.homeId, 'homeId');
+  const endpoint = readLifxEndpoint(config.host, config.macAddress, config.port);
+  if (config.allowUnencryptedLan !== true) throw new TypeError('LIFX requires an explicit allowUnencryptedLan: true acknowledgement.');
+  return Object.freeze({
+    homeId, ...endpoint, allowUnencryptedLan: true,
+    name: config.name === undefined ? undefined : lifxName(config.name, 'name'),
+    requestTimeoutMs: lifxInteger(config.requestTimeoutMs === undefined ? 5000 : config.requestTimeoutMs, 1, 60000, 'requestTimeoutMs'),
+    maxPendingOperations: lifxInteger(config.maxPendingOperations === undefined ? 32 : config.maxPendingOperations, 1, 128, 'maxPendingOperations'),
+  });
+}
+
+export function assertLifxStoreScope(storeArg: IConfigStore | undefined, homeIdArg: string): void {
+  if (storeArg === undefined) return;
+  const scope = storeArg.getScope?.();
+  if (!scope || scope.homeId !== homeIdArg || scope.integrationDomain !== 'lifx') {
+    throw new TypeError('LIFX config-store scope must match the configured home and lifx domain.');
+  }
+}
+
+export function readLifxColor(valueArg: unknown): ILifxColor {
+  const color = lifxRecord(valueArg, 'HSBK color');
+  lifxKeys(color, ['hue', 'saturation', 'brightness', 'kelvin']);
+  return {
+    hue: lifxInteger(color.hue, 0, 65535, 'hue'),
+    saturation: lifxInteger(color.saturation, 0, 65535, 'saturation'),
+    brightness: lifxInteger(color.brightness, 0, 65535, 'brightness'),
+    kelvin: lifxInteger(color.kelvin, 1, 65535, 'kelvin'),
+  };
+}

package/ts/integrations/lifx/readme.md

@@ -0,0 +1,55 @@
+# Native LIFX LAN integration
+
+The integration binds one explicit local IPv4 endpoint and six-byte MAC through
+the published `@ecobridge.xyz/devicemanager` `LifxProtocol`. It sends unicast UDP
+only. The LAN protocol has no cryptographic peer authentication; matching the
+sender and MAC is a binding check. Select the endpoint from trusted home context.
+
+```typescript
+const integration = new LifxIntegration();
+const runtime = await integration.setup({
+  homeId: 'home-1', host: '192.168.1.42', macAddress: 'd073d5001337',
+  allowUnencryptedLan: true,
+}, { configStore: homeScopedEncryptedStore });
+```
+
+`homeId`, `host`, `macAddress` and the cleartext acknowledgement are required.
+The caller owns any encrypted `NoSqlConfigStore`; a supplied store must expose a
+matching immutable home/domain scope before traffic. This integration does not
+persist credentials or runtime observations. IDs include the exact home and MAC.
+An integration scope does not grant a caller home access; the hub enforces access.
+Optional `port` defaults to 56700, `requestTimeoutMs` to 5000 and
+`maxPendingOperations` to 32. `name` overrides the observed device label.
+
+Known single-zone product/firmware records expose power and light observations.
+Known color products also expose full HSBK control in exact LAN integer units;
+hue, saturation and brightness use 0–65535, and kelvin must fit the observed
+firmware's documented range. White products have read-only HSBK. Unknown products
+and other layouts expose identity inventory without writable light features.
+Firmware build is a decimal string so snapshots remain JSON-safe.
+
+Every service requires one exact owned device or light entity target. Supported
+services are `lifx.status`, `lifx.snapshot`, `lifx.refresh`, `light.turn_on`,
+`light.turn_off` and `lifx.set_hsbk`. Power services accept only optional
+`durationMs`; `set_hsbk` requires all four HSBK fields and accepts optional
+`durationMs`. Duration is an integer from 0 through 60000 milliseconds. Feature
+writes accept a boolean `power` or complete `hsbk` value.
+
+An accepted write reports device receipt and a separately queried observation.
+The observation may precede transition completion or reflect a concurrent writer;
+it is not a physical completion guarantee. Error results preserve the owning
+protocol's `effectOutcome`: `not-sent`, `rejected`, `indeterminate`, or `accepted`
+when observation fails after ACK. Effects are never retried automatically.
+Cancellation reaches pending protocol operations. Destroy is terminal, idempotent
+and joins setup, operations and UDP socket cleanup.
+
+Migration: injected `client`, `commandExecutor`, `rawData`, `snapshotProvider`,
+URL-only setup and generated effect/theme services are removed. Supply the explicit
+native configuration above and use the bounded services. Broadcast discovery,
+cloud access, partial color patches, toggle, white-color writes, multizone/matrix/
+chain/relay control, effects, themes, HEV and infrared are unsupported.
+
+Sources: [LAN messages](https://lan.developer.lifx.com/docs/changing-a-device),
+[device information](https://lan.developer.lifx.com/docs/information-messages),
+[official product registry](https://github.com/LIFX/products).
+Verification uses real loopback UDP fixtures. Real hardware has not been tested.