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

package/README.md

@@ -1,3 +1,326 @@
-# Temporary Holding Version
+# node-red-contrib-home-connect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English · [Deutsch](README.de.md)**
+
+[![CI](https://github.com/impact0815/node-red-contrib-home-connect/actions/workflows/ci.yml/badge.svg)](https://github.com/impact0815/node-red-contrib-home-connect/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](CHANGELOG.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Node-RED nodes for Home Connect: direct, read-only LAN access to appliance profiles plus the existing official cloud API with OAuth, discovery, SSE, rate-limit protection, health/warnings, and guarded writes. The project conceptually follows the discovery-first and safe-write approach of [`impact0815/node-red-contrib-viessmann`](https://github.com/impact0815/node-red-contrib-viessmann), but is an independent Home Connect implementation.
+
+> **Unofficial community project.** This package is not affiliated with, endorsed by, or supported by Home Connect GmbH, BSH Hausgeräte GmbH, Bosch, Siemens, Neff, Gaggenau, or any other brand. Use it at your own risk. Appliance control can create heat, motion, water use, and other hazards. Test with the simulator and dry-run first.
+
+## Read this first
+
+- **Client ID and Client Secret come from your own Application in the Home Connect Developer Portal**, not from the Home Connect mobile app.
+- This build uses the **OAuth 2.0 Authorization Code Grant with a client secret and without PKCE**.
+- The **Client Secret is confidential**. Never publish it in screenshots, forums, issues, flows, or Git repositories. If exposed, regenerate it in the Developer Portal and authorize again.
+- The Redirect URI in the Developer Portal and Node-RED must match **character for character**.
+- Always **save and deploy** a connection before reopening it and starting authorization.
+- The experimental local protocol is undocumented and can change with firmware. Local access is **hard read-only**; profile PSK/IV values are secrets.
+
+## Features
+
+- confidential OAuth 2.0 Authorization Code flow, CSRF state, and refresh-token rotation
+- Client Secret and refresh token in the Node-RED credential store, not exported flows
+- Production, China, official Home Connect simulator, and built-in offline simulator
+- recursive discovery and grouping of Profile Downloader JSON/XML sets, with one central profile-to-Host/IP assignment in the configuration node
+- direct local WebSocket reads/events over AES-CBC/HMAC or TLS-PSK; transport defaults to **Auto** from the profile and can be overridden centrally
+- service-version-driven handshake/read sequencing, unsolicited appliance values, housekeeping responses, and complete session rebuilds
+- optional sanitized in-memory or protected JSONL protocol trace with no PSK, IV, keys, nonces, or appliance/network identifiers
+- selectors show `type — friendly name — brand/model — …ID suffix`; the complete technical ID remains unchanged internally
+- strict local-only host validation, credential-backed profile JSON, and an unconditional `LOCAL_READ_ONLY` write barrier
+- profile-based resolution of hexadecimal XML `uid`/`refUID` values and referenced enums into semantic Home Connect keys, followed by automatic status/setting/value/program classification
+- Server-Sent Events (SSE) with automatic reconnect
+- normalized health model: `ok`, `running`, `info`, `warning`, `action_required`, `offline`, `error`
+- deduplicated warnings carrying German and English text from appliance status, event `level`/`handling`, connection, API, and OAuth; the Dashboard displays only the selected language
+- separate data and structured-error outputs
+- persistent, configurable 24-hour request budget shared by equal Client IDs, with an HTTP 429 circuit breaker
+- guarded writes with global enable, appliance-type allowlist, confirmation token, dry-run, and live capability checks
+- no automatic retries of write requests
+- English and German README, help, troubleshooting, and examples
+- Dashboard 2.0 example with saved DE/EN selection, localized UI/appliance/enum/program/option names, initial snapshots, partial-event merging, offline/reconnect, and cloud plus local read-only paths
+- separate fully simulated, credential-free screenshot flow for reproducible GitHub/npm documentation images
+- zero runtime dependencies; Node.js 18+ and Node-RED 3+
+
+## Installation
+
+### Local TGZ file
+
+```bash
+cd ~/.node-red
+npm install /absolute/path/node-red-contrib-home-connect-0.2.0.tgz
+```
+
+Restart Node-RED completely and reload the browser with **Ctrl+F5**.
+
+### Docker example
+
+```bash
+docker cp node-red-contrib-home-connect-0.2.0.tgz node-red:/tmp/
+docker exec node-red npm install --prefix /data /tmp/node-red-contrib-home-connect-0.2.0.tgz
+docker restart node-red
+```
+
+### Upgrade from 0.1.0
+
+Replace the old package cleanly so Node-RED cannot load a stale copy:
+
+```bash
+cd ~/.node-red
+npm uninstall node-red-contrib-home-connect
+rm -rf node_modules/node-red-contrib-home-connect
+npm install --force /absolute/path/node-red-contrib-home-connect-0.2.0.tgz
+node -p "require('./node_modules/node-red-contrib-home-connect/BUILD-INFO.json')"
+```
+
+Expect `hc-0.2.0-final` and `pkce: false`. Restart the container when applicable. Existing cloud configuration remains compatible; do not reuse incomplete or old authorization links/codes.
+
+## Step-by-step setup for non-technical users
+
+### A. Try it without an account
+
+1. In Node-RED choose **Menu → Import → Examples → node-red-contrib-home-connect → 01-first-steps-device-list**.
+2. Deploy.
+3. Click the Inject button on the left.
+4. The Debug sidebar shows three local test appliances.
+5. The built-in simulator makes no external Home Connect connection and needs no credentials.
+
+### B. Connect real appliances locally (read-only)
+
+1. Use the community [Home Connect Profile Downloader](https://github.com/bruestel/homeconnect-profile-downloader) to export the appliance JSON/XML files.
+2. Store the extracted directory on the Node-RED host with restrictive filesystem permissions. In Docker, mount it read-only, for example at `/data/homeconnect-profiles`. The path must be the path **inside the Node-RED container**, not a path on your laptop.
+3. Create a Home Connect configuration and choose **Local LAN (read-only)**.
+4. Enter the server-side profile directory and click **Scan profiles / Detect devices**. The recursive scanner groups each appliance JSON with its matching `DeviceDescription.xml` and `FeatureMapping.xml`. The result says, for example, **3 device profiles found**. Incomplete sets and duplicate profile IDs are listed separately and must be fixed in the folder.
+5. A card appears for every complete device profile. Enter one Host/IP in each card. Missing, malformed, public, and non-local addresses are marked. Leave **Connection type** at **Auto (recommended)**; Auto honors the profile's declared AES/TLS/PSK transport first and uses IV presence only as a fallback.
+6. Click **Test connection** in every device card. Even before Done/Deploy, it uses the visible Host/IP and transport and shows separate stages for IP reachability, profile, transport, WebSocket, session, services, and read-only data. Rejected protocol resources identify action, version, and device code while network failures remain a separate class. It never sends a write request.
+7. Click **Done → Deploy**. The editor serializes `localDeviceMappings` on every card change and once more on Done, so the exact assignments persist after deploy; do not create mapping JSON yourself.
+8. In a Read node select only the configured appliance and read resource. In an Events node select one configured appliance or **All configured appliances**. Neither node contains a Host/IP field.
+9. Do not attach a Write node: local writes are always rejected with `LOCAL_READ_ONLY` before local network I/O.
+
+Under **Advanced**, **Paste profile JSON manually (optional)** is a fallback. Use either the folder or manual JSON. When a folder is set, the manual editor is collapsed/disabled and ignored. A button can generate the optional credential JSON from the detected profiles and completed mappings; no placeholder, sample key, or hand-written mapping is required. The same section can temporarily enable the safe protocol trace: with no path it is a bounded test display; with an absolute path it is JSONL mode `0600` on POSIX, with sensitive fields removed. On Windows, restrict the path with an account-specific NTFS ACL because POSIX mode bits are not reliable there.
+
+The runtime connects only to private/link-local targets at `ws://host:80/homeconnect` (AES/HMAC) or `wss://host:443/homeconnect` (TLS-PSK). PSK/IV are never emitted. Full setup, Docker, protocol boundary, and troubleshooting: **[Local LAN guide](docs/LOCAL-LAN.md)**.
+
+Appliance selectors use concise labels such as `Dishwasher — Geschirrspüler — Siemens SX678X36TE — …4576`. The shortened suffix is display-only; flows and runtime calls continue to use the full unmodified technical ID.
+
+### C. Create your own Developer Portal Application
+
+1. Sign in to the [Home Connect Developer Portal](https://developer.home-connect.com/).
+2. Create your **own Application**.
+3. Select the **Authorization Code Grant Flow**.
+4. Generate a Client Secret.
+5. Keep **PKCE disabled**, because this package build sends no PKCE parameters.
+6. Register the Redirect URI that Node-RED will use.
+7. Store the Client ID and Client Secret securely.
+
+These values do **not** come from the Home Connect mobile app.
+
+### D. Choose the correct Redirect URI
+
+Pattern:
+
+```text
+https://<node-red-host-reachable-from-your-browser>:<port>/home-connect/oauth/callback
+```
+
+Example using a deliberately fictional hostname:
+
+```text
+https://nodered.example.net/home-connect/oauth/callback
+```
+
+The string must be identical in both places:
+
+- same `http` or `https`
+- same hostname
+- same port
+- path ends exactly with `/home-connect/oauth/callback`
+- **no** trailing slash
+
+**About localhost:** `localhost` always means the computer running the browser. Use it only when the browser and Node-RED run on the same computer. For Node-RED on a NAS, Raspberry Pi, server, or container, use a Node-RED hostname or IP address that the browser can reach.
+
+### E. Create the cloud Node-RED connection
+
+1. Add a Home Connect node to the workspace.
+2. Create a new `home-connect-config` under **Connection**.
+3. Use a clear name such as `Home Connect Production – Home`. Do not name a Production connection `Simulator`.
+4. Select the environment.
+5. Enter the Client ID, Client Secret, and exact Redirect URI.
+6. Start with the smallest practical scopes.
+7. Initially keep the local budget at **900 API calls per 24 hours** and the minimum interval at **250 ms**.
+8. Leave **Allow write access** off initially.
+9. Click **Done**.
+10. **Deploy**.
+11. Reopen the connection. Only now is **Authorize** enabled.
+12. Click **Authorize**, sign in to Home Connect, and grant access.
+13. Authorization has finished when the browser displays **Home Connect authorized**.
+14. Close that window and click **Test** in Node-RED. Appliances then appear automatically in the appliance selectors.
+
+## Scopes in plain language
+
+`IdentifyAppliance` is required for the appliance list. Add appliance-specific permissions when possible.
+
+| Purpose | Example |
+|---|---|
+| Discover appliances only | `IdentifyAppliance` |
+| Monitor dishwasher, washer, and oven | `IdentifyAppliance Dishwasher-Monitor Washer-Monitor Oven-Monitor` |
+| Read and control the example dashboard | `IdentifyAppliance Dishwasher-Monitor Dishwasher-Control Dishwasher-Settings Washer-Monitor Washer-Control Washer-Settings Oven-Monitor Oven-Control Oven-Settings` |
+
+The generic `Monitor` scope is not sufficient for every Application/account. After changing scopes, authorize again so a new refresh token receives the changed permissions.
+
+## Normalized health and warning model
+
+Every Discover, Read, Events, Write, and error output contains `msg.health`, `msg.warnings`, and the same information under `msg.homeConnect`. Snapshots and discovery entries additionally carry `payload.health`, `payload.warnings`, `payload.healthSchema`, and `payload.healthAt`. Dashboard flows therefore do not need to interpret Home Connect enums themselves.
+
+```js
+msg.health = 'action_required';
+msg.warnings = [{
+  source: 'status',
+  code: 'HC_OPERATION_ACTION_REQUIRED',
+  severity: 'critical',
+  text: {
+    de: 'Das Gerät benötigt eine Aktion vor Ort.',
+    en: 'The appliance requires an action on site.'
+  },
+  transient: false
+}];
+```
+
+The model covers `OperationState`, `DoorState`, `RemoteControlActive`, `RemoteControlStartAllowed`, `LocalControlActive`, appliance/SSE connectivity, event `level` and `handling`, OAuth state, API errors, and rate limits. Short-lived notices such as `Finished`, ordinary appliance events, and `CONNECTED` are deduplicated and expire automatically. `DISCONNECTED`/offline remains until a connection or snapshot signal confirms recovery. Raw values are preserved so future enum values are not lost.
+
+## Included nodes
+
+| Node | Purpose |
+|---|---|
+| **Home Connect API** | shared local read-only or cloud OAuth configuration, scopes, and cloud write enable |
+| **Home Connect discover** | dynamically load the user's appliances and capabilities |
+| **Home Connect read** | read status, settings, programs, options, images, and supported map resources |
+| **Home Connect events** | receive local WebSocket or cloud SSE events for all appliances or one appliance |
+| **Home Connect write** | send cloud programs, settings, and commands through safety checks; local is always rejected |
+
+Every functional node has two outputs: **data/result/event** and **structured error**.
+
+## Example flows
+
+Find these under **Import → Examples → node-red-contrib-home-connect**:
+
+| File | Content |
+|---|---|
+| `01-first-steps-device-list.json` | simplest start: built-in simulator and appliance list |
+| `02-events.json` | one all-appliance event stream, filtering, and Debug output |
+| `03-safe-read-write.json` | read a snapshot and validate a write as dry-run only |
+| `04-local-read-only.json` | anonymized local Discover/Read/Events flow with no Write node |
+| `dashboard-dishwasher-washer-oven.json` | Dashboard 2.0: automatic/saved DE/EN display, initial snapshot plus local/cloud event merging, retained last-known state, offline/reconnect handling, compact overview, and detail cards |
+| `dashboard-screenshot-simulated.json` | credential-free deterministic screenshot demo with three clearly simulated appliances; requires only Node-RED Dashboard 2 |
+| `demo-home-connect-flowfuse-1.34.1-scriptless.json` | isolated, scriptless-template Demo flow supplied for FlowFuse Dashboard 1.34.1; deterministic, credential-free, and network-free |
+
+The dashboard also requires `@flowfuse/node-red-dashboard`:
+
+```bash
+cd ~/.node-red
+npm install @flowfuse/node-red-dashboard
+```
+
+The examples start with the built-in simulator. For real appliances, either use a local read-only connection or authorize a Production cloud connection, load the appliance list, and replace the connection in the Home Connect nodes. The shared reducer accepts complete snapshots and partial `STATUS`/`NOTIFY` events without clearing fields that were not part of the update. Offline events retain the last known values, and reconnect events resume live updates. Local controls are disabled by `readOnly`; cloud write nodes must stay in dry-run first. Technical keys remain unchanged internally; localization affects display only. See the [Dashboard guide](docs/DASHBOARD.md) for language selection and screenshot-flow instructions.
+
+## Documentation screenshots
+
+The release documentation uses only the isolated simulated Demo and includes two reviewed captures:
+
+![English Home Connect Demo overview](docs/images/dashboard-overview-en.png)
+
+![English Home Connect Demo appliance details](docs/images/dashboard-details-en.png)
+
+Both reviewed images use the English UI and show only `SIMULATED` Demo data. `npm run release:check` refuses publication if either file is missing, structurally invalid, or differs from the reviewed user-provided PNG. The completed visual review found no browser profiles, hostnames, addresses, account names, real appliance identifiers, tokens, QR codes, profiles, or unrelated tabs/windows.
+
+## Appliance information and firmware — an important boundary
+
+The publicly documented Home Connect API exposes appliance information such as name, brand, appliance type, `vib`/E-number, and connection state when supplied by the appliance/account. Discovery and the Dashboard display these values where available.
+
+**Firmware version, firmware history, and firmware update are not provided by the publicly documented API.** This package does not pretend to implement firmware features, does not call undocumented firmware endpoints, and does not attempt to trigger updates. Check firmware and updates only through official manufacturer/Home Connect channels.
+
+## Troubleshooting / FAQ
+
+### `CONFIG_NOT_FOUND` when authorization starts
+
+The button or an imported flow refers to a configuration node that is not present in the running Node-RED runtime. A simulator/example configuration may have been referenced, or the new configuration was not deployed.
+
+**Fix:** select the correct connection → **Done** → **Deploy** → reopen the connection → start a new authorization. Do not continue in an old browser tab.
+
+### Connection name and environment do not match
+
+A name such as `Simulator` with the Production environment is technically possible but easy to misuse. The editor now warns about this. Rename it clearly and deploy again.
+
+### The browser shows `ERR_EMPTY_RESPONSE` or connection failed on localhost after sign-in
+
+Home Connect redirected the browser to `localhost`, but Node-RED runs on another computer. Change the Redirect URI in both the Developer Portal and Node-RED to a Node-RED host reachable from the browser, match it exactly, deploy, and start OAuth again.
+
+### `unauthorized_client` / `client or redirection URI not authorized`
+
+Usually the Redirect URI does not match exactly. Check protocol, host, port, path, and trailing slash. Also confirm that PKCE is disabled for the Developer Portal Application. This build sends no PKCE parameters.
+
+### Old code still runs after a package update
+
+Node-RED loads runtime code only at startup. Uninstall the old package, install the new TGZ with `--force`, restart Node-RED or its container completely, and hard-reload the browser. Verify the build information. Then restart OAuth completely; old authorization URLs and one-time codes are invalid.
+
+### `No refresh token is stored. Complete OAuth authorization first.`
+
+OAuth did not complete. Start authorization again and wait for **Home Connect authorized**. Only then use Test, Discover, Read, or Events.
+
+### `insufficient_scope`
+
+The stored token lacks the required permission. Enter `IdentifyAppliance` plus suitable appliance-specific scopes, save, deploy, and authorize again. Merely editing the scope text does not update an existing token.
+
+### Events node remains on `reconnecting`
+
+Authorization or monitor/event scopes are usually missing. First confirm that **Test** or the appliance-list example can load appliances. Inspect the Events node's error output, correct scopes, and authorize again. Prefer one all-appliance stream because the API limits concurrent streams.
+
+### `health`, `warnings`, and rate limits
+
+`health` is the summarized state; `warnings` provides stable codes and German/English text. By default, the configuration node permits **900 API attempts in every rolling 24-hour window**, leaving 100 calls in reserve below the vendor limit of 1000. The configurable range is 1–1000; equal Client IDs use the strictest active configuration inside one Node-RED process. REST requests, retries, and SSE connection attempts each count separately. State is persisted below the Node-RED `userDir` in `.home-connect`, so deploys and restarts do not reset the budget.
+
+When the local budget is exhausted, a structured `LOCAL_RATE_LIMITED` error with `retryAfter` and `resetAt` is returned **before network access**. If Home Connect returns HTTP 429, a remaining period embedded in the error text, such as `75502 seconds`, is also recognized and persisted as a circuit breaker; this package sends no further Home Connect API requests during that period. A 429 response is not retried automatically. Other hosts or applications that use the same Home Connect Application cannot be coordinated, so do not raise the reserve to 1000 without a reason and use one config node per Client ID.
+
+For `HC_API_RATE_LIMITED`, reduce polling and observe `retryAfter`. For `HC_OAUTH_INSUFFICIENT_SCOPE` or `HC_OAUTH_AUTHORIZATION_EXPIRED`, correct scopes or authorization and then authorize again. The example Dashboard disables start actions while offline, in error, requiring action, or blocked from remote control.
+
+### How do I know authorization worked?
+
+The callback page displays **Home Connect authorized**. **Test** then reports an appliance count, and **Load appliances** populates the selectors automatically.
+
+See [Troubleshooting (EN)](docs/TROUBLESHOOTING.md) for the complete decision tree.
+
+## Security
+
+- Set a strong `credentialSecret` in `settings.js` before storing credentials.
+- Protect the editor, Dashboard, and callback with HTTPS, authentication, and network controls.
+- Never publish Client Secrets, tokens, real hostnames, appliance IDs, or OAuth codes in issues or screenshots.
+- If a secret is exposed, regenerate it in the Developer Portal and authorize again immediately.
+- Request minimum scopes.
+- Keep `allowWrite` off by default; test every new write with dry-run.
+- Use a deployment-specific confirmation token and appliance-type allowlist for write nodes.
+- Follow manufacturer safety instructions and Home Connect terms.
+
+More details: [SECURITY.md](SECURITY.md).
+
+## Development and validation
+
+```bash
+npm run validate
+```
+
+Validation covers syntax, JSON/flow files, unit and simulator integration tests, and `npm pack --dry-run`. GitHub Actions tests Node.js 18, 20, and 22.
+
+## More documentation
+
+- [Troubleshooting (EN)](docs/TROUBLESHOOTING.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Message API](docs/MESSAGE-API.md)
+- [API coverage](docs/API-COVERAGE.md)
+- [Dashboard](docs/DASHBOARD.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/SECURITY.md

@@ -0,0 +1,47 @@
+# Security policy
+
+## Local appliance profiles
+
+Local profile PSKs and IVs are equivalent to device credentials. Prefer a server-side profile directory readable only by the Node-RED service account, or use the optional credential-backed manual profile JSON field under **Advanced** with a strong `credentialSecret` in `settings.js`. The configuration node stores the non-secret profile-to-Host/IP assignment once; exported flows can therefore expose private addresses even though they never contain folder-based PSK/IV values. Sanitize both before sharing. Never export profiles in flows, logs, screenshots, support bundles, or bug reports.
+
+The local transport rejects public network targets and is hard read-only. Do not weaken these controls. If a profile is exposed, remove the copy, obtain a fresh profile where the appliance/account supports it, and review LAN access.
+
+The optional local protocol trace is disabled by default. It records decrypted protocol messages only after recursive redaction and never records PSK, IV, derived keys, ciphertext, OAuth data, authentication nonces, appliance IDs, serial numbers, MAC addresses, SSIDs, or IP fields. On POSIX, a configured JSONL trace file is created and enforced with mode `0600`; Windows does not expose equivalent POSIX mode bits reliably, so protect the trace path with an account-restricted NTFS ACL. Without a path, entries remain in a bounded memory buffer. Treat even sanitized traces as private operational data, inspect them before sharing, and disable/delete them after diagnosis.
+
+## Supported version
+
+During the 0.x development phase, security fixes are applied to the latest published release.
+
+## Deployment checklist
+
+- Set a strong `credentialSecret` in Node-RED settings before entering OAuth credentials.
+- Serve the editor, Dashboard and OAuth callback over HTTPS.
+- Protect the editor and Dashboard with authentication and network controls.
+- Expose only the callback path needed by Home Connect; do not expose the Node-RED editor anonymously.
+- Request the minimum appliance-specific scopes.
+- Keep `allowWrite` off unless a flow needs it.
+- Keep every new write node in dry-run until its exact request has been inspected.
+- Use a unique confirmation token and an appliance-type allowlist.
+- Never place client secret, refresh token, confirmation token or access token in a Function node, flow, Git repository or debug output.
+- Never place local profile PSK/IV values or profile archives in a Function node, flow, Git repository or debug output.
+- Keep local protocol tracing disabled except during diagnosis; inspect sanitized JSONL before sharing and delete it afterward.
+- Never publish a real redirect URI, hostname, appliance ID, serial number, authorization code or OAuth state in screenshots or issues.
+- If a client secret is exposed, regenerate it in the Home Connect Developer Portal, replace it in Node-RED and complete a new authorization.
+- Review Home Connect Developer Program terms and appliance manufacturer safety instructions.
+
+## Design properties
+
+- OAuth state is random, memory-only, single-use and expires after ten minutes. This confidential-client flow deliberately sends no PKCE parameters.
+- Client secrets, refresh tokens and per-writer confirmation tokens use Node-RED credentials; they are not exported with a flow.
+- No arbitrary URL/method writer exists.
+- Write payloads are checked against refreshed device capabilities, data types, `readWrite` access, ranges and allowed values.
+- Program starts check remote-control/start/local-control/operation status.
+- Write requests are not automatically retried.
+- Normal API requests have a configurable timeout. A persisted sliding-window limiter counts REST and SSE connection attempts before network access; the default is 900 per 24 hours. HTTP 429 opens a local circuit breaker for the reported remaining period instead of being retried.
+- OAuth success/error pages disable caching and set restrictive browser headers.
+- Built-in simulator performs no external I/O.
+- Local transports accept only private/link-local targets and expose only read resources; local writes are rejected before network I/O.
+
+## Reporting a vulnerability
+
+Do not open a public issue containing credentials, private infrastructure data or exploit details. Contact the package maintainer privately and include the affected version, impact, sanitized reproduction and suggested remediation. Revoke affected Home Connect credentials immediately in the Developer Program, deploy the replacement secret and restart Node-RED after rotating secrets.

package/docs/API-COVERAGE.md

@@ -0,0 +1,59 @@
+# Official API contract and coverage
+
+The cloud client in version 0.2.0 remains checked against the two official Swagger 2.0 files supplied for the 0.1.0 revision:
+
+| Specification | SHA-256 | Host | Operations |
+| --- | --- | --- | ---: |
+| `hcsdk-simulation.yaml` | `5942f5ca450a46fa9a6f53ff6d13627972040f105dcd786efddcf9a44ce376a3` | `simulator.home-connect.com` | 28 |
+| `hcsdk-production.yaml` | `a0704118d429eb1a7becf9d624068a2c48ce8d7c0a2250128be2487ff0758c57` | `api.home-connect.com` | 46 |
+
+The generated, machine-readable inventory is `official-api-contract.json`. The original YAML files are not redistributed in the npm package.
+
+## Contract decisions
+
+- API paths use the documented `/api` base path.
+- JSON reads and writes use `application/vnd.bsh.sdk.v1+json`.
+- OAuth uses the documented `accessCode` flow and the `/security/oauth/authorize` and `/security/oauth/token` endpoints on the selected environment host. The private-application implementation uses a client secret and deliberately omits PKCE parameters.
+- Request bodies retain the documented `{ "data": ... }` envelope.
+- JPEG image reads return `{ contentType, data }`, where `data` is a Node.js `Buffer`.
+- Production-only command and cleaning-robot map resources are not queried during generic official-simulator discovery.
+- HTTP 204 write responses become an empty object.
+
+## Read coverage
+
+The read node exposes a finite operation list rather than accepting arbitrary URLs:
+
+- appliances and one appliance
+- complete and single status values
+- complete and single settings
+- all, available, active and selected programs
+- complete and single active/selected program options
+- production command discovery
+- image metadata and JPEG image data
+- all production cleaning-robot map GET resources: maps, occupancy grid, layout, cleaning status, detected objects, rooms, zones, robot position, restrictions and cleaning summaries
+- capability discovery and combined snapshots
+
+The appliance object is passed through, including documented fields such as name, brand, type, `vib` and connected state when returned by the API.
+
+## Firmware is outside the public contract
+
+Neither the checked public production/simulation contracts nor the documented operation set provides firmware version, firmware history, or firmware update. Version 0.2.0 therefore exposes no firmware operation, does not synthesize firmware data, and does not call undocumented firmware endpoints. Its separate experimental local transport is read-only and limited to the documented-in-project `/ro/*` inventory in [LOCAL-LAN.md](LOCAL-LAN.md).
+
+Map operations use `msg.key` for the map ID or cleaning-summary counter. Operations for one detected object, room or zone additionally use `msg.subKey`.
+
+## Write coverage and intentional restrictions
+
+The writer supports the documented singular endpoints for:
+
+- start and stop program
+- select program
+- set one setting
+- execute one command
+- set one option of the active program
+- set one option of the selected program
+
+Bulk setting, command and option writes are intentionally not exposed. Singular writes permit tighter per-value validation and avoid partial-success ambiguity. Arbitrary HTTP methods, paths and body envelopes are intentionally unsupported.
+
+## Simulator differences
+
+The supplied simulation contract does not define command or map endpoints, while the production contract does. The client records this difference explicitly: command discovery is skipped for the official simulator, and map operations remain production-only. The built-in offline simulator implements the common high-level interface and returns structured `404` errors for image/map content it does not model.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,95 @@
+# Architecture
+
+## Components
+
+```text
+Node-RED editor/runtime
+  ├─ Home Connect API configuration
+  │    ├─ OAuth state (confidential client, no PKCE)
+  │    ├─ access-token memory cache
+  │    ├─ refresh token in Node-RED credentials
+  │    ├─ shared API/simulator client
+  │    └─ per-appliance HealthMonitor
+  ├─ discover ── capability cache (5 minutes)
+  ├─ read ────── finite operation router
+  ├─ events ──── SSE parser + Last-Event-ID reconnect loop
+  └─ write ───── security gates + live validation
+
+Client abstraction
+  ├─ HomeConnectClient (production, China, official simulator)
+  ├─ LocalHomeConnectClient (LAN profiles, hard read-only)
+  │    └─ LocalApplianceSession
+  │         ├─ RFC 6455 transport (private/link-local targets only)
+  │         ├─ AES-CBC + chained HMAC or TLS 1.2 PSK
+  │         ├─ negotiated /ei, /ci, /iz, /ni and /ro versions
+  │         ├─ sanitized optional protocol trace
+  │         └─ /ro/* values + full-session reconnect/heartbeat
+  └─ BuiltinSimulator (offline, deterministic, event-capable)
+```
+
+## OAuth lifecycle
+
+1. An authenticated Node-RED editor user starts authorization through an admin route.
+2. A random, short-lived `state` is generated in memory. No PKCE parameters are created or sent.
+3. The browser is redirected to the selected Home Connect authorization endpoint.
+4. The public callback validates state and its ten-minute lifetime.
+5. The authorization code is exchanged for tokens. `client_id`, `client_secret`, the unchanged `redirect_uri` and the code are form-encoded only in the token request.
+6. The refresh token is saved with `RED.nodes.addCredentials`; the access token remains in memory. Client ID and client secret are never added to the browser authorization URL beyond the required client ID.
+7. Access tokens refresh before use when expired and once after an HTTP 401.
+
+No password grant, automated login or credential scraping is used.
+
+## Local LAN lifecycle and read-only boundary
+
+The local profile scanner recursively loads Profile Downloader appliance JSON and groups matching DeviceDescription/FeatureMapping XML files by base name within the same directory. It returns only non-secret profile metadata to the editor. The configuration node owns the single `profileId` → Host/IP/connection assignment; Read and Events nodes store only a profile/appliance ID. Legacy encrypted profile JSON remains in the Node-RED credential store. PSK and IV never enter messages, diagnostics, logs, examples, or exported flows.
+
+Before a socket is opened, DNS must resolve exclusively to private RFC1918, IPv4 link-local, IPv6 unique-local, or IPv6 link-local addresses. `Auto` first honors an explicit profile declaration of AES, TLS, or PSK and uses IV presence only as a fallback; a per-profile override is possible only in the central mapping. The editor posts the current card value to the test route and re-serializes all mappings on Done, so testing before deploy and runtime after deploy use the same Host/IP/transport assignment. The transport performs a direct RFC 6455 upgrade on the exact `/homeconnect` path with websocket-client-compatible `Host`, URL-derived `Origin`, `Upgrade`, `Connection`, key, and version headers; it sends no subprotocol, cookie, or authorization header. AES profiles use port 80 and persistent AES-256-CBC/HMAC state. TLS profiles use port 443 with TLS 1.2 PSK and a profile identity or `HCCOM_Local_App`. The first AES integrity/padding/decode error closes the connection; reconnect creates fresh cipher and HMAC chains. The editor test exposes seven deterministic stages and stops on the first root cause, so a transport/handshake failure cannot be followed by a synthetic values-unavailable error.
+
+The appliance sends `/ei/initialValues`; the session responds with the same session/message IDs and the EI-version-specific application structure, then starts its own message counter at the advertised `edMsgID`. It requests `/ci/services` at version 1 **without a `data` member**, parses flat or nested service lists, negotiates legacy `/ci/authentication` (`POST` first, documented `GET` fallback) when `ci < 3`, and announces `/ei/deviceReady` at the negotiated EI version, also without `data`. Optional identity/network reads select `/iz/info` versus `/ci/info` and `/ni/info` from the service inventory. It then sends only `GET`, using the advertised `ro` version, in this order: `/ro/allMandatoryValues`, `/ro/values`, `/ro/allDescriptionChanges`, `/ro/activeProgram`, and `/ro/selectedProgram`.
+
+Incoming unsolicited `NOTIFY`/`RESPONSE` messages are applied before matching pending requests. Successful or device-pushed initial/mandatory/value payloads count as read-only evidence, so one unsupported fallback resource does not invalidate data already delivered by the appliance. Device-originated housekeeping `GET`/`POST` messages receive `RESPONSE` with the same appliance `msgID` and do not advance the client counter. Non-zero/non-200 response codes retain resource, action, version, and device code; if every read path is rejected, all attempts are returned in sanitized diagnostics.
+
+The optional local protocol trace records decrypted, sanitized protocol envelopes and lifecycle events in a bounded memory buffer and, when an absolute path is configured, JSONL mode `0600` on POSIX. Windows must protect the path with an account-restricted NTFS ACL because it does not report equivalent POSIX mode bits reliably. Recursive redaction removes PSK/IV/key/authentication/OAuth material, nonces, and device/network identifiers. It never records ciphertext or transport headers. Trace I/O failure cannot weaken the read-only boundary or crash the session.
+
+Read-only is enforced at three levels: the local client has no write route, its `write()` always throws `LOCAL_READ_ONLY`, and the Write node rejects a local configuration before cloud capability validation or network I/O. `allowWrite` is forced false for local configurations.
+
+## Discovery model
+
+Discovery starts with `/api/homeappliances`. For each appliance it reads status, settings, available/active/selected programs and, where the supplied contract defines it, commands. Every available program is then opened individually so its actual options and constraints are captured. Unsupported endpoints and failed program details become resource-labelled `discoveryErrors`; they do not erase the rest of the snapshot. Successful discovery is cached for five minutes and invalidated after every write.
+
+## Write threat model and gates
+
+A request must pass all applicable gates:
+
+1. **Configuration gate** – `allowWrite` is enabled.
+2. **Node action gate** – only seven named actions can reach the client; no arbitrary HTTP path or method is accepted.
+3. **Confirmation gate** – optional exact token on each message; the configured token is a Node-RED credential.
+4. **Type gate** – optional appliance-type allowlist.
+5. **Fresh capability gate** – programs, options, settings and commands are reloaded.
+6. **Constraint gate** – value type, access (`readWrite`), allowed values, min, max, step size and duplicate options.
+7. **Operational gate** – connected, remote control active, remote start allowed, local control inactive and ready state for program starts.
+8. **Retry gate** – writes are sent once and never retried automatically.
+
+Dry-run performs gates 1–7 without sending the request. If dry-run is selected in the editor, an input message cannot turn it off.
+
+## SSE lifecycle
+
+The event node opens an all-appliance or per-appliance stream. The parser supports comments/keep-alive, event, data, id and retry fields and arbitrary chunk boundaries. The latest event ID is sent as `Last-Event-ID` after reconnect. The client emits synthetic `CONNECTED`/`DISCONNECTED` lifecycle events and promotes an all-appliance event's `data.haId` to the normalized event envelope. Network/API errors go to output 2. The node reconnects from one to thirty seconds and aborts immediately when removed, redeployed or when the shared configuration closes.
+
+For local configurations, the same node subscribes to per-appliance WebSocket sessions instead. Sessions emit `CONNECTED`, `DISCONNECTED`, and normalized `STATUS`; ping/pong runs every 20 seconds. Reconnect uses jittered exponential backoff from about one to at most 60 seconds and rebuilds the transport, crypto state, session ID, message counter, services, authentication, device-ready notification, optional info reads, and read-only snapshot.
+
+## Health normalization
+
+One `HealthMonitor` belongs to each configuration node, so Discover, Read, Events and Write nodes sharing that connection also share current appliance state. It maps known operation, door, remote/local-control and connection signals to seven stable health values. Event `level`/`handling`, API/OAuth errors and rate limits become bilingual warning records. Current status conditions replace previous conditions; transient event/Finished/Connected notices are deduplicated and time-bounded. Error-output assessments are not retained, preventing one failed request from poisoning later successful output. Unknown enum values remain in the raw payload and produce at most one informational warning.
+
+## Transport controls
+
+Cloud JSON requests use the vendor media type from the supplied Swagger contracts. API reads have a configurable timeout and bounded retries for network errors and temporary 5xx responses. Writes and HTTP 429 responses are never automatically retried. Binary image reads return a `Buffer`; SSE intentionally uses a long-lived connection instead of the normal request timeout.
+
+Every REST attempt and SSE connection attempt first acquires a permit from a persisted sliding-window limiter. The default is 900 permits per rolling 24 hours and a 250 ms minimum spacing; both are configurable within safety bounds, and config nodes with the same environment and Client ID share the strictest active settings. The state file below the Node-RED `userDir` contains only timestamps and a blocked-until value. When the local budget is exhausted, the request fails locally. A vendor HTTP 429 opens a persistent circuit breaker using `Retry-After` or a remaining-seconds value extracted from the API error description; if neither exists, the limiter conservatively blocks for one configured window.
+
+Direct LAN sessions do not consume the cloud limiter. Their controls are private-address validation, request/handshake timeouts, WebSocket heartbeat, bounded reconnect, strict message parsing, per-direction serialized cipher state, and fail-closed integrity handling.
+
+## Simulator
+
+The built-in simulator implements the same high-level client interface. It includes a dishwasher, washer and oven, validates the same constraints, changes active program state, emits SSE-like events, counts down time and simulates oven temperature. It performs no external I/O.