@impact0815/node-red-contrib-home-connect 0.0.0-stage → 0.2.0

package/lib/local-trace.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const SECRET_KEY = /(?:psk|initialization.?vector|iv64|^iv$|secret|token|password|credential|authorization|cookie|nonce|ship.?ski|private.?key|client.?id)/i;
+const IDENTIFIER_KEY = /^(?:deviceID|serialNumber|mac|euiAddress|ssid|ipAddress|ipv4|ipv6)$/i;
+const MAX_TRACE_ENTRIES = 500;
+
+function sanitizeValue(value, key = '', seen = new WeakSet()) {
+  if (SECRET_KEY.test(String(key))) return '[REDACTED]';
+  if (IDENTIFIER_KEY.test(String(key))) return '[REDACTED_IDENTIFIER]';
+  if (value === null || value === undefined) return value;
+  if (Buffer.isBuffer(value)) return `[BUFFER ${value.length} bytes]`;
+  if (typeof value !== 'object') return value;
+  if (seen.has(value)) return '[CIRCULAR]';
+  seen.add(value);
+  if (Array.isArray(value)) return value.slice(0, 200).map(item => sanitizeValue(item, '', seen));
+  const result = {};
+  for (const [name, item] of Object.entries(value).slice(0, 200)) result[name] = sanitizeValue(item, name, seen);
+  return result;
+}
+
+function sanitizeProtocolMessage(message) {
+  const safe = sanitizeValue(message);
+  if (String(message?.resource || '') === '/ci/authentication' && Object.hasOwn(safe || {}, 'data')) {
+    safe.data = '[REDACTED_AUTHENTICATION_DATA]';
+  }
+  return safe;
+}
+
+function resolveTraceFile(configuredPath) {
+  const value = String(configuredPath || '').trim();
+  if (!value) return '';
+  if (!path.isAbsolute(value)) return '';
+  try {
+    const stat = fs.existsSync(value) ? fs.statSync(value) : null;
+    return stat?.isDirectory() ? path.join(value, 'home-connect-local-protocol.jsonl') : value;
+  } catch {
+    return '';
+  }
+}
+
+class LocalProtocolTrace {
+  constructor(options = {}) {
+    this.enabled = options.enabled === true;
+    this.profile = `sha256:${crypto.createHash('sha256').update(String(options.profile || 'local-appliance')).digest('hex').slice(0, 12)}`;
+    this.maxEntries = Math.max(20, Math.min(MAX_TRACE_ENTRIES, Number(options.maxEntries || 250)));
+    this.entries = [];
+    this.file = this.enabled ? resolveTraceFile(options.path) : '';
+    this.writeError = null;
+    if (this.file) {
+      try {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+        const handle = fs.openSync(this.file, 'a', 0o600);
+        fs.closeSync(handle);
+        fs.chmodSync(this.file, 0o600);
+      } catch (error) {
+        this.writeError = { code: error.code || 'TRACE_OPEN_FAILED', message: error.message };
+        this.file = '';
+      }
+    }
+  }
+
+  record(direction, message, metadata = {}) {
+    if (!this.enabled) return;
+    const entry = {
+      timestamp: new Date().toISOString(),
+      direction: String(direction),
+      profile: this.profile,
+      ...sanitizeValue(metadata),
+      message: sanitizeProtocolMessage(message)
+    };
+    this.entries.push(entry);
+    if (this.entries.length > this.maxEntries) this.entries.splice(0, this.entries.length - this.maxEntries);
+    if (this.file) {
+      try { fs.appendFileSync(this.file, `${JSON.stringify(entry)}\n`, { encoding: 'utf8', mode: 0o600 }); }
+      catch (error) { this.writeError = { code: error.code || 'TRACE_WRITE_FAILED', message: error.message }; }
+    }
+  }
+
+  event(type, details = {}) {
+    this.record('internal', { type, details }, { kind: 'lifecycle' });
+  }
+
+  snapshot() {
+    return {
+      enabled: this.enabled,
+      file: this.file || undefined,
+      writeError: this.writeError || undefined,
+      entries: this.entries.map(entry => structuredClone(entry))
+    };
+  }
+}
+
+module.exports = {
+  LocalProtocolTrace,
+  sanitizeProtocolMessage,
+  sanitizeValue,
+  resolveTraceFile,
+  MAX_TRACE_ENTRIES
+};

package/lib/oauth.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+function base64url(input) {
+  return Buffer.from(input).toString('base64url');
+}
+
+function createState() {
+  return base64url(crypto.randomBytes(32));
+}
+
+function buildAuthorizationUrl(options) {
+  const url = new URL('/security/oauth/authorize', options.baseUrl);
+  url.searchParams.set('client_id', options.clientId);
+  url.searchParams.set('redirect_uri', options.redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('scope', options.scope);
+  url.searchParams.set('state', options.state);
+  return url.toString();
+}
+
+module.exports = { base64url, createState, buildAuthorizationUrl };

package/lib/rate-limiter.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { HomeConnectError, retryAfterSeconds } = require('./errors');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_REQUESTS = 900;
+const DEFAULT_MINIMUM_INTERVAL = 250;
+
+const sleep = ms => new Promise(resolve => {
+  const timer = setTimeout(resolve, ms);
+  timer.unref?.();
+});
+
+function integerInRange(value, fallback, minimum, maximum) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(maximum, Math.max(minimum, Math.floor(number)));
+}
+
+function createFileRateLimitStore(directory, key) {
+  if (!directory || !key) return undefined;
+  const digest = crypto.createHash('sha256').update(String(key)).digest('hex').slice(0, 24);
+  const file = path.join(directory, `rate-limit-${digest}.json`);
+  return {
+    file,
+    async load() {
+      try {
+        return JSON.parse(await fs.readFile(file, 'utf8'));
+      } catch (error) {
+        if (error.code === 'ENOENT' || error.name === 'SyntaxError') return undefined;
+        throw error;
+      }
+    },
+    async save(state) {
+      await fs.mkdir(directory, { recursive: true });
+      const temporary = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+      await fs.writeFile(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+      await fs.rename(temporary, file);
+    }
+  };
+}
+
+class SlidingWindowRateLimiter {
+  constructor(options = {}) {
+    this.windowMs = integerInRange(options.windowMs, DAY_MS, 1000, DAY_MS);
+    this.configure(options);
+    this.store = options.store;
+    this.now = options.now || Date.now;
+    this.wait = options.wait || sleep;
+    this.state = { version: 1, timestamps: [], blockedUntil: 0 };
+    this.lastRequestAt = 0;
+    this.queue = Promise.resolve();
+    this.ready = this._load();
+  }
+
+  configure(options = {}) {
+    this.maxRequests = integerInRange(options.maxRequests, this.maxRequests || DEFAULT_MAX_REQUESTS, 1, 1000);
+    this.minimumIntervalMs = integerInRange(
+      options.minimumIntervalMs,
+      this.minimumIntervalMs || DEFAULT_MINIMUM_INTERVAL,
+      100,
+      60000
+    );
+  }
+
+  async _load() {
+    if (!this.store?.load) return;
+    const saved = await this.store.load();
+    if (!saved || typeof saved !== 'object') return;
+    this.state.timestamps = Array.isArray(saved.timestamps)
+      ? saved.timestamps.map(Number).filter(Number.isFinite).sort((a, b) => a - b)
+      : [];
+    this.state.blockedUntil = Number.isFinite(Number(saved.blockedUntil)) ? Number(saved.blockedUntil) : 0;
+    this._prune(this.now());
+  }
+
+  _prune(now) {
+    const threshold = now - this.windowMs;
+    this.state.timestamps = this.state.timestamps.filter(timestamp => timestamp > threshold);
+    if (this.state.blockedUntil <= now) this.state.blockedUntil = 0;
+  }
+
+  async _save() {
+    if (this.store?.save) await this.store.save(this.state);
+  }
+
+  _limitError(now, blockedUntil, source) {
+    const retryAfter = Math.max(1, Math.ceil((blockedUntil - now) / 1000));
+    return new HomeConnectError(
+      `Home Connect request blocked by the local rate limiter. Retry in ${retryAfter} seconds.`,
+      {
+        code: 'LOCAL_RATE_LIMITED',
+        status: 429,
+        retryAfter: String(retryAfter),
+        details: {
+          source,
+          maxRequests: this.maxRequests,
+          periodSeconds: Math.ceil(this.windowMs / 1000),
+          usedRequests: this.state.timestamps.length,
+          remainingRequests: Math.max(0, this.maxRequests - this.state.timestamps.length),
+          resetAt: new Date(blockedUntil).toISOString()
+        }
+      }
+    );
+  }
+
+  async _acquire() {
+    await this.ready;
+    let now = this.now();
+    this._prune(now);
+    if (this.state.blockedUntil > now) {
+      throw this._limitError(now, this.state.blockedUntil, 'server');
+    }
+    if (this.state.timestamps.length >= this.maxRequests) {
+      this.state.blockedUntil = this.state.timestamps[0] + this.windowMs;
+      await this._save();
+      throw this._limitError(now, this.state.blockedUntil, 'local-budget');
+    }
+
+    const delay = Math.max(0, this.minimumIntervalMs - (now - this.lastRequestAt));
+    if (delay) await this.wait(delay);
+    now = this.now();
+    this._prune(now);
+    if (this.state.blockedUntil > now) {
+      throw this._limitError(now, this.state.blockedUntil, 'server');
+    }
+    if (this.state.timestamps.length >= this.maxRequests) {
+      this.state.blockedUntil = this.state.timestamps[0] + this.windowMs;
+      await this._save();
+      throw this._limitError(now, this.state.blockedUntil, 'local-budget');
+    }
+
+    this.state.timestamps.push(now);
+    this.lastRequestAt = now;
+    await this._save();
+    return this.status();
+  }
+
+  acquire() {
+    const run = this.queue.then(() => this._acquire(), () => this._acquire());
+    this.queue = run;
+    return run;
+  }
+
+  async recordServerLimit(value) {
+    await this.ready;
+    const now = this.now();
+    this._prune(now);
+    const seconds = retryAfterSeconds(value, now) || Math.ceil(this.windowMs / 1000);
+    this.state.blockedUntil = Math.max(this.state.blockedUntil, now + seconds * 1000);
+    await this._save();
+    return this.status();
+  }
+
+  async status() {
+    await this.ready;
+    const now = this.now();
+    this._prune(now);
+    const localReset = this.state.timestamps.length >= this.maxRequests
+      ? this.state.timestamps[0] + this.windowMs
+      : 0;
+    const resetAt = Math.max(localReset, this.state.blockedUntil);
+    return {
+      maxRequests: this.maxRequests,
+      periodSeconds: Math.ceil(this.windowMs / 1000),
+      minimumIntervalMs: this.minimumIntervalMs,
+      usedRequests: this.state.timestamps.length,
+      remainingRequests: Math.max(0, this.maxRequests - this.state.timestamps.length),
+      blocked: resetAt > now,
+      retryAfter: resetAt > now ? String(Math.max(1, Math.ceil((resetAt - now) / 1000))) : undefined,
+      resetAt: resetAt > now ? new Date(resetAt).toISOString() : undefined
+    };
+  }
+}
+
+module.exports = {
+  DAY_MS,
+  DEFAULT_MAX_REQUESTS,
+  DEFAULT_MINIMUM_INTERVAL,
+  SlidingWindowRateLimiter,
+  createFileRateLimitStore,
+  integerInRange
+};

package/lib/simulator.js

@@ -0,0 +1,290 @@
+'use strict';
+
+const { EventEmitter } = require('node:events');
+const { validateWrite } = require('./validation');
+const { HomeConnectError } = require('./errors');
+
+const clone = value => value == null ? value : structuredClone(value);
+const item = (key, value, extra = {}) => ({ key, value, ...extra });
+const bool = allowed => ({ type: 'Boolean', constraints: { allowedvalues: allowed } });
+
+function makeDevices() {
+  return [
+    {
+      appliance: { haId: 'dishwasher-001', name: 'Geschirrspülmaschine', type: 'Dishwasher', brand: 'Bosch', vib: 'SIM-DW-001', connected: true },
+      status: { items: [
+        item('BSH.Common.Status.RemoteControlActive', true),
+        item('BSH.Common.Status.RemoteControlStartAllowed', true),
+        item('BSH.Common.Status.LocalControlActive', false),
+        item('BSH.Common.Status.OperationState', 'BSH.Common.EnumType.OperationState.Ready'),
+        item('BSH.Common.Status.DoorState', 'BSH.Common.EnumType.DoorState.Closed')
+      ] },
+      settings: { items: [item('BSH.Common.Setting.PowerState', 'BSH.Common.EnumType.PowerState.On', { constraints: { allowedvalues: ['BSH.Common.EnumType.PowerState.On', 'BSH.Common.EnumType.PowerState.Standby'] } })] },
+      programs: { available: [
+        { key: 'Dishcare.Dishwasher.Program.Eco50', name: 'Eco 50 °C', options: [
+          item('BSH.Common.Option.StartInRelative', 0, { unit: 'seconds', constraints: { min: 0, max: 86400, stepsize: 60, default: 0 } }),
+          item('Dishcare.Dishwasher.Option.VarioSpeedPlus', false, bool([true, false])),
+          item('Dishcare.Dishwasher.Option.IntensivZone', false, bool([true, false]))
+        ] },
+        { key: 'Dishcare.Dishwasher.Program.Auto2', name: 'Auto 45–65 °C', options: [item('Dishcare.Dishwasher.Option.VarioSpeedPlus', false, bool([true, false]))] },
+        { key: 'Dishcare.Dishwasher.Program.Intensiv70', name: 'Intensiv 70 °C', options: [item('Dishcare.Dishwasher.Option.IntensivZone', true, bool([true, false]))] }
+      ], active: null, selected: null },
+      commands: { items: [
+        item('BSH.Common.Command.PauseProgram', true, bool([true])),
+        item('BSH.Common.Command.ResumeProgram', true, bool([true]))
+      ] }
+    },
+    {
+      appliance: { haId: 'washer-001', name: 'Waschmaschine', type: 'Washer', brand: 'Siemens', vib: 'SIM-WM-001', connected: true },
+      status: { items: [
+        item('BSH.Common.Status.RemoteControlActive', true), item('BSH.Common.Status.RemoteControlStartAllowed', true),
+        item('BSH.Common.Status.LocalControlActive', false), item('BSH.Common.Status.OperationState', 'BSH.Common.EnumType.OperationState.Ready'),
+        item('BSH.Common.Status.DoorState', 'BSH.Common.EnumType.DoorState.Closed')
+      ] },
+      settings: { items: [item('BSH.Common.Setting.PowerState', 'BSH.Common.EnumType.PowerState.On', { constraints: { allowedvalues: ['BSH.Common.EnumType.PowerState.On', 'BSH.Common.EnumType.PowerState.Standby'] } })] },
+      programs: { available: [
+        { key: 'LaundryCare.Washer.Program.Cotton', name: 'Baumwolle', options: [
+          item('LaundryCare.Washer.Option.Temperature', 'LaundryCare.Washer.EnumType.Temperature.GC40', { constraints: { allowedvalues: ['LaundryCare.Washer.EnumType.Temperature.GC30', 'LaundryCare.Washer.EnumType.Temperature.GC40', 'LaundryCare.Washer.EnumType.Temperature.GC60'] } }),
+          item('LaundryCare.Washer.Option.SpinSpeed', 'LaundryCare.Washer.EnumType.SpinSpeed.RPM1400', { constraints: { allowedvalues: ['LaundryCare.Washer.EnumType.SpinSpeed.RPM800', 'LaundryCare.Washer.EnumType.SpinSpeed.RPM1200', 'LaundryCare.Washer.EnumType.SpinSpeed.RPM1400'] } })
+        ] },
+        { key: 'LaundryCare.Washer.Program.EasyCare', name: 'Pflegeleicht', options: [] },
+        { key: 'LaundryCare.Washer.Program.Mix', name: 'Mix', options: [] }
+      ], active: null, selected: null },
+      commands: { items: [item('BSH.Common.Command.PauseProgram', true, bool([true])), item('BSH.Common.Command.ResumeProgram', true, bool([true]))] }
+    },
+    {
+      appliance: { haId: 'oven-001', name: 'Backofen', type: 'Oven', brand: 'Neff', vib: 'SIM-OV-001', connected: true },
+      status: { items: [
+        item('BSH.Common.Status.RemoteControlActive', true), item('BSH.Common.Status.RemoteControlStartAllowed', true),
+        item('BSH.Common.Status.LocalControlActive', false), item('BSH.Common.Status.OperationState', 'BSH.Common.EnumType.OperationState.Ready'),
+        item('BSH.Common.Status.DoorState', 'BSH.Common.EnumType.DoorState.Closed'),
+        item('Cooking.Oven.Status.CurrentCavityTemperature', 22, { unit: '°C' })
+      ] },
+      settings: { items: [item('BSH.Common.Setting.PowerState', 'BSH.Common.EnumType.PowerState.On', { constraints: { allowedvalues: ['BSH.Common.EnumType.PowerState.On', 'BSH.Common.EnumType.PowerState.Standby'] } })] },
+      programs: { available: [
+        { key: 'Cooking.Oven.Program.HeatingMode.HotAir', name: 'Heißluft', options: [
+          item('Cooking.Oven.Option.SetpointTemperature', 180, { unit: '°C', constraints: { min: 30, max: 250, stepsize: 5, default: 180 } }),
+          item('BSH.Common.Option.Duration', 1800, { unit: 'seconds', constraints: { min: 60, max: 10800, stepsize: 60, default: 1800 } }),
+          item('Cooking.Oven.Option.FastPreHeat', false, bool([true, false]))
+        ] },
+        { key: 'Cooking.Oven.Program.HeatingMode.TopBottomHeating', name: 'Ober-/Unterhitze', options: [item('Cooking.Oven.Option.SetpointTemperature', 180, { unit: '°C', constraints: { min: 30, max: 275, stepsize: 5, default: 180 } })] },
+        { key: 'Cooking.Oven.Program.HeatingMode.PreHeating', name: 'Vorheizen', options: [item('Cooking.Oven.Option.SetpointTemperature', 200, { unit: '°C', constraints: { min: 50, max: 250, stepsize: 5, default: 200 } })] }
+      ], active: null, selected: null },
+      commands: { items: [item('BSH.Common.Command.PauseProgram', true, bool([true])), item('BSH.Common.Command.ResumeProgram', true, bool([true]))] }
+    }
+  ];
+}
+
+class BuiltinSimulator extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.language = options.language || 'de-DE';
+    this.devices = new Map(makeDevices().map(device => [device.appliance.haId, device]));
+    this.timers = new Map();
+  }
+
+  get environment() { return 'builtin-simulator'; }
+  get requiresOAuth() { return false; }
+
+  _device(haId) {
+    const device = this.devices.get(haId);
+    if (!device) throw new HomeConnectError(`Unknown simulated appliance: ${haId}`, { code: 'APPLIANCE_NOT_FOUND', status: 404 });
+    return device;
+  }
+
+  _emit(haId, event, items) {
+    const payload = { haId, event, data: { items: clone(items) }, simulated: true, timestamp: new Date().toISOString() };
+    this.emit(`event:${haId}`, payload);
+    this.emit('event:*', payload);
+  }
+
+  _setStatus(device, key, value, extra = {}) {
+    const existing = device.status.items.find(entry => entry.key === key);
+    if (existing) Object.assign(existing, { value, ...extra });
+    else device.status.items.push(item(key, value, extra));
+    this._emit(device.appliance.haId, 'STATUS', [item(key, value, extra)]);
+  }
+
+  async listHomeAppliances() { return clone(Array.from(this.devices.values(), device => device.appliance)); }
+  async getHomeAppliance(haId) { return clone(this._device(haId).appliance); }
+  async getStatus(haId) { return clone(this._device(haId).status); }
+  async getStatusValue(haId, key) {
+    const value = this._device(haId).status.items.find(entry => entry.key === key);
+    if (!value) throw new HomeConnectError(`Status not found: ${key}`, { code: 'STATUS_NOT_AVAILABLE', status: 404 });
+    return clone(value);
+  }
+  async getSettings(haId) { return clone(this._device(haId).settings); }
+  async getSetting(haId, key) {
+    const value = this._device(haId).settings.items.find(entry => entry.key === key);
+    if (!value) throw new HomeConnectError(`Setting not found: ${key}`, { code: 'SETTING_NOT_AVAILABLE', status: 404 });
+    return clone(value);
+  }
+  async getAllPrograms(haId) {
+    const programs = this._device(haId).programs;
+    return clone({ programs: programs.available, active: programs.active, selected: programs.selected });
+  }
+  async getAvailablePrograms(haId) { return { programs: clone(this._device(haId).programs.available.map(({ key, name }) => ({ key, name }))) }; }
+  async getAvailableProgram(haId, key) {
+    const program = this._device(haId).programs.available.find(entry => entry.key === key);
+    if (!program) throw new HomeConnectError(`Program not found: ${key}`, { code: 'PROGRAM_NOT_AVAILABLE', status: 404 });
+    return clone(program);
+  }
+  async getActiveProgram(haId) { return clone(this._device(haId).programs.active); }
+  async getSelectedProgram(haId) { return clone(this._device(haId).programs.selected); }
+  async getProgramOptions(haId, kind) {
+    const program = this._device(haId).programs[kind];
+    if (!program) throw new HomeConnectError(`No ${kind} program is available.`, { code: kind === 'active' ? 'NO_ACTIVE_PROGRAM' : 'NO_SELECTED_PROGRAM', status: 409 });
+    return { options: clone(program.options || []) };
+  }
+  async getProgramOption(haId, kind, key) {
+    const options = await this.getProgramOptions(haId, kind);
+    const option = options.options.find(entry => entry.key === key);
+    if (!option) throw new HomeConnectError(`Option not found: ${key}`, { code: 'OPTION_NOT_AVAILABLE', status: 404 });
+    return clone(option);
+  }
+  async getCommands(haId) { return clone(this._device(haId).commands); }
+  async getImages(haId) { this._device(haId); return { images: [] }; }
+  async getImage(haId, imageKey) { this._device(haId); throw new HomeConnectError(`Image not found: ${imageKey}`, { code: 'IMAGE_NOT_AVAILABLE', status: 404 }); }
+  async getMaps(haId) { this._device(haId); return []; }
+  async getMap(haId, mapId) { this._device(haId); throw new HomeConnectError(`Map not found: ${mapId}`, { code: 'MAP_NOT_AVAILABLE', status: 404 }); }
+  async getMapResource(haId, mapId) { return this.getMap(haId, mapId); }
+  async getMapGlobalResource(haId, resource) { this._device(haId); throw new HomeConnectError(`Map resource not found: ${resource}`, { code: 'MAP_RESOURCE_NOT_AVAILABLE', status: 404 }); }
+
+  async discoverAppliance(haId) {
+    const device = this._device(haId);
+    return clone({ ...device, discoveredAt: new Date().toISOString(), simulated: true });
+  }
+
+  async discoverAll() {
+    return Promise.all(Array.from(this.devices.keys(), id => this.discoverAppliance(id)));
+  }
+
+  async read(haId, operation = 'snapshot', key, subKey) {
+    if (operation === 'appliances') return this.listHomeAppliances();
+    if (operation === 'snapshot' || operation === 'capabilities') return this.discoverAppliance(haId);
+    if (operation === 'appliance') return this.getHomeAppliance(haId);
+    if (operation === 'status') return this.getStatus(haId);
+    if (operation === 'status-item') return this.getStatusValue(haId, key);
+    if (operation === 'settings') return this.getSettings(haId);
+    if (operation === 'setting') return this.getSetting(haId, key);
+    if (operation === 'all-programs') return this.getAllPrograms(haId);
+    if (operation === 'programs') return this.getAvailablePrograms(haId);
+    if (operation === 'program') return this.getAvailableProgram(haId, key);
+    if (operation === 'active-program') return this.getActiveProgram(haId);
+    if (operation === 'active-options') return this.getProgramOptions(haId, 'active');
+    if (operation === 'active-option') return this.getProgramOption(haId, 'active', key);
+    if (operation === 'selected-program') return this.getSelectedProgram(haId);
+    if (operation === 'selected-options') return this.getProgramOptions(haId, 'selected');
+    if (operation === 'selected-option') return this.getProgramOption(haId, 'selected', key);
+    if (operation === 'commands') return this.getCommands(haId);
+    if (operation === 'images') return this.getImages(haId);
+    if (operation === 'image') return this.getImage(haId, key);
+    if (operation === 'maps') return this.getMaps(haId);
+    if (operation === 'map') return this.getMap(haId, key);
+    if (operation === 'map-occupancy-grid') return this.getMapResource(haId, key, 'occupancyGrid');
+    if (operation === 'map-layout') return this.getMapResource(haId, key, 'layout');
+    if (operation === 'map-cleaning-status') return this.getMapResource(haId, key, 'cleaningStatus');
+    if (operation === 'map-detected-objects') return this.getMapResource(haId, key, 'cleaningStatus/objects');
+    if (operation === 'map-detected-object') return this.getMapResource(haId, key, 'cleaningStatus/objects', subKey);
+    if (operation === 'map-rooms') return this.getMapResource(haId, key, 'rooms');
+    if (operation === 'map-room') return this.getMapResource(haId, key, 'rooms', subKey);
+    if (operation === 'map-zones') return this.getMapResource(haId, key, 'zones');
+    if (operation === 'map-zone') return this.getMapResource(haId, key, 'zones', subKey);
+    if (operation === 'map-robot-position') return this.getMapGlobalResource(haId, 'robot/position');
+    if (operation === 'map-config-restrictions') return this.getMapGlobalResource(haId, 'config/restrictions');
+    if (operation === 'map-cleaning-summaries') return this.getMapGlobalResource(haId, 'cleaningSummary');
+    if (operation === 'map-cleaning-summary') return this.getMapGlobalResource(haId, 'cleaningSummary', key);
+    throw new HomeConnectError(`Unsupported read operation: ${operation}`, { code: 'READ_ACTION_NOT_ALLOWED' });
+  }
+
+  async write(request, capability) {
+    const device = this._device(request.haId);
+    const cap = capability || await this.discoverAppliance(request.haId);
+    validateWrite(cap, request);
+    if (request.action === 'set-setting') {
+      const target = device.settings.items.find(entry => entry.key === request.key);
+      target.value = request.value;
+      this._emit(request.haId, 'NOTIFY', [clone(target)]);
+    } else if (request.action === 'select-program') {
+      const program = device.programs.available.find(entry => entry.key === request.program);
+      const supplied = new Map((request.options || []).map(option => [option.key, option]));
+      const options = (program.options || []).map(option => ({
+        ...clone(option),
+        value: supplied.get(option.key)?.value ?? option.constraints?.default ?? option.value
+      }));
+      device.programs.selected = { key: program.key, name: program.name, options };
+      this._emit(request.haId, 'NOTIFY', [item('BSH.Common.Root.SelectedProgram', program.key)]);
+    } else if (request.action === 'start-program') {
+      const program = device.programs.available.find(entry => entry.key === request.program);
+      const defaults = (program.options || []).map(option => ({
+        ...clone(option), value: option.constraints?.default ?? option.value
+      }));
+      const supplied = new Map((request.options || []).map(option => [option.key, option]));
+      const options = defaults.map(option => supplied.has(option.key)
+        ? { ...option, value: supplied.get(option.key).value }
+        : option);
+      for (const option of request.options || []) if (!options.some(entry => entry.key === option.key)) options.push(option);
+      device.programs.active = { key: program.key, name: program.name, options };
+      device.programs.selected = clone(device.programs.active);
+      this._setStatus(device, 'BSH.Common.Status.OperationState', 'BSH.Common.EnumType.OperationState.Run');
+      const duration = options.find(option => option.key === 'BSH.Common.Option.Duration')?.value || 5400;
+      this._startTimer(device, duration);
+    } else if (request.action === 'stop-program') {
+      this._stopTimer(request.haId);
+      device.programs.active = null;
+      this._setStatus(device, 'BSH.Common.Status.OperationState', 'BSH.Common.EnumType.OperationState.Ready');
+    } else if (request.action === 'command') {
+      this._emit(request.haId, 'EVENT', [item(request.key, request.value)]);
+    } else if (request.action === 'set-active-option' || request.action === 'set-selected-option') {
+      const kind = request.action === 'set-active-option' ? 'active' : 'selected';
+      const program = device.programs[kind];
+      const target = program.options.find(entry => entry.key === request.key);
+      target.value = request.value;
+      this._emit(request.haId, 'NOTIFY', [clone(target)]);
+    }
+    return { accepted: true, simulated: true, request: clone(request), at: new Date().toISOString() };
+  }
+
+  _startTimer(device, seconds) {
+    this._stopTimer(device.appliance.haId);
+    let remaining = seconds;
+    this._setStatus(device, 'BSH.Common.Option.RemainingProgramTime', remaining, { unit: 'seconds' });
+    const timer = setInterval(() => {
+      remaining = Math.max(0, remaining - 60);
+      this._setStatus(device, 'BSH.Common.Option.RemainingProgramTime', remaining, { unit: 'seconds' });
+      if (device.appliance.type === 'Oven') {
+        const target = device.programs.active?.options?.find(option => option.key === 'Cooking.Oven.Option.SetpointTemperature')?.value || 180;
+        const current = device.status.items.find(entry => entry.key === 'Cooking.Oven.Status.CurrentCavityTemperature');
+        const next = Math.min(target, (current?.value || 22) + 10);
+        this._setStatus(device, 'Cooking.Oven.Status.CurrentCavityTemperature', next, { unit: '°C' });
+        if (next === target) this._emit(device.appliance.haId, 'EVENT', [item('Cooking.Oven.Event.PreheatFinished', true)]);
+      }
+      if (remaining === 0) {
+        this._stopTimer(device.appliance.haId);
+        device.programs.active = null;
+        this._setStatus(device, 'BSH.Common.Status.OperationState', 'BSH.Common.EnumType.OperationState.Finished');
+      }
+    }, 5000);
+    timer.unref?.();
+    this.timers.set(device.appliance.haId, timer);
+  }
+
+  _stopTimer(haId) {
+    if (this.timers.has(haId)) clearInterval(this.timers.get(haId));
+    this.timers.delete(haId);
+  }
+
+  openEvents(haId, onEvent) {
+    const channel = `event:${haId || '*'}`;
+    this.on(channel, onEvent);
+    queueMicrotask(() => onEvent({ haId: haId || '*', event: 'CONNECTED', data: { items: [] }, simulated: true, timestamp: new Date().toISOString() }));
+    return () => this.off(channel, onEvent);
+  }
+
+  close() {
+    for (const id of this.timers.keys()) this._stopTimer(id);
+    this.removeAllListeners();
+  }
+}
+
+module.exports = { BuiltinSimulator, makeDevices };

package/lib/sse.js

@@ -0,0 +1,58 @@
+'use strict';
+
+function parseSSEBlock(block) {
+  const message = { event: 'message', data: '', id: undefined, retry: undefined, comment: undefined };
+  const comments = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (!line) continue;
+    if (line.startsWith(':')) { comments.push(line.slice(1).trim()); continue; }
+    const separator = line.indexOf(':');
+    const field = separator === -1 ? line : line.slice(0, separator);
+    let value = separator === -1 ? '' : line.slice(separator + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+    if (field === 'event') message.event = value;
+    if (field === 'data') message.data += `${value}\n`;
+    if (field === 'id') message.id = value;
+    if (field === 'retry' && /^\d+$/.test(value)) message.retry = Number(value);
+  }
+  if (message.data.endsWith('\n')) message.data = message.data.slice(0, -1);
+  if (comments.length) message.comment = comments.join('\n');
+  if (comments.length && message.event === 'message' && !message.data) message.event = 'KEEP-ALIVE';
+  return message;
+}
+
+async function* streamChunks(body) {
+  if (body && typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield value;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    return;
+  }
+  for await (const chunk of body) yield chunk;
+}
+
+async function* parseSSE(body) {
+  const decoder = new TextDecoder();
+  let buffer = '';
+  for await (const chunk of streamChunks(body)) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let boundary;
+    while ((boundary = buffer.search(/\r?\n\r?\n/)) !== -1) {
+      const block = buffer.slice(0, boundary);
+      const match = buffer.slice(boundary).match(/^\r?\n\r?\n/);
+      buffer = buffer.slice(boundary + match[0].length);
+      if (block.trim()) yield parseSSEBlock(block);
+    }
+  }
+  buffer += decoder.decode();
+  if (buffer.trim()) yield parseSSEBlock(buffer);
+}
+
+module.exports = { parseSSE, parseSSEBlock };