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

package/docs/LOCAL-LAN.md

@@ -0,0 +1,150 @@
+# Local LAN connection (read-only)
+
+Back to the [English README](../README.md) · [Deutsch](LOCAL-LAN.de.md)
+
+## Scope and safety boundary
+
+Version 0.2.0 adds an **experimental, unofficial local transport** for Home Connect appliances. Node-RED connects directly to the appliance's private/link-local LAN address. Normal runtime reads and events do not call the Home Connect cloud.
+
+The local protocol is not an official public API. Device firmware may change it without notice. This implementation therefore has a hard boundary:
+
+- local resources are **read-only**;
+- the local client exposes no write method;
+- a Write node connected to a local configuration always returns `LOCAL_READ_ONLY` before validation or network I/O;
+- no program, option, setting, command, pairing, registration, deregistration, firmware, or update request is sent locally.
+
+The existing cloud client is unchanged: confidential OAuth Authorization Code flow, no PKCE, rate-limit protection, SSE, health/warnings, dry-run, and guarded cloud writes remain available in separate cloud configuration nodes.
+
+## Supported transports
+
+The `connectionType` and keys come from the appliance profile:
+
+| Profile | Endpoint | Protection |
+|---|---|---|
+| `AES` plus IV | `ws://<private-host>:80/homeconnect` | persistent AES-256-CBC stream plus chained truncated HMAC-SHA256 |
+| `TLS`/`PSK` | `wss://<private-host>:443/homeconnect` | TLS 1.2 PSK (profile identity or `HCCOM_Local_App`; PSK cipher suites) |
+
+Both variants use RFC 6455 WebSocket framing and the local Home Connect session handshake. The upgrade matches the hcpy/homeconnect-websocket clients: exact `GET /homeconnect HTTP/1.1`, `Upgrade: websocket`, `Connection: Upgrade`, `Host`, URL-derived `Origin`, RFC 6455 key, and version 13. A 20-second ping/pong heartbeat is enabled. A disconnect builds an entirely new session with fresh AES/HMAC state; exponential backoff with jitter grows from about one second to at most 60 seconds. The first HMAC, padding, or UTF-8 failure closes the socket immediately because the stream cannot safely resynchronize.
+
+## Obtain profiles
+
+Use the community [Home Connect Profile Downloader](https://github.com/bruestel/homeconnect-profile-downloader). It performs the required account sign-in and downloads, for each registered appliance:
+
+- `<serial>.json` — host/device metadata and PSK/IV;
+- `<serial>_DeviceDescription.xml`;
+- `<serial>_FeatureMapping.xml`.
+
+The account/cloud step is required only to obtain or refresh those profiles. The Node-RED local runtime does not automate account login, scrape passwords, or download profiles itself.
+
+Treat the resulting files as secrets. Do not commit them, put them in flows, attach them to issues, or copy them into screenshots.
+
+## Configure Node-RED
+
+1. Extract the Profile Downloader archive on the Node-RED host.
+2. Restrict the directory to the Node-RED service account, for example `chmod 700 /data/homeconnect-profiles` and `chmod 600 /data/homeconnect-profiles/*`.
+3. Create a new Home Connect configuration and choose **Local LAN (read-only)**.
+4. Enter the server-side **Profile folder**, then click **Scan profiles / Detect devices**. This is a path seen by the Node-RED process; for Docker it is the path inside the container. The scanner searches subfolders and groups `<base>.json`, `<base>_DeviceDescription.xml`, and `<base>_FeatureMapping.xml`. It also accepts the unprefixed XML names when one appliance JSON is alone in its directory.
+5. Read the result, such as **3 device profiles found**. An incomplete set, invalid JSON/key, orphan companion file, or duplicate profile ID is listed clearly and is not turned into an ambiguous device card. Keep the three files from the same download together and scan again.
+6. For every detected device card, enter exactly one **Host/IP**. Missing/malformed values and public IP literals are marked immediately. A hostname is resolved by the server during the connection test and must resolve exclusively to private/link-local addresses. A host detected inside a profile is only an initial suggestion.
+7. Leave **Connection type** at **Auto (recommended)**. Auto first honors an explicit profile declaration of `AES`, `TLS`, or `PSK`; only when it is absent does an IV select AES and no IV select TLS-PSK. A retained IV in an explicitly TLS profile therefore no longer selects the wrong transport. Use AES/TLS only as a deliberate override.
+8. Click **Test connection** on every card. The test posts the Host/IP and Auto/AES/TLS value currently visible in that card, merges it over any older hidden/deployed mapping, and loads only the selected profile. Its stages are **IP reachable → Profile loaded → Transport detected → WebSocket connected → Session initialized → Services detected → Read-only data received**. It stops at the first root cause, marks later stages skipped, and never adds a misleading `LOCAL_VALUES_UNAVAILABLE` follow-up. Unfilled sibling cards cannot cause a false `LOCAL_MAPPING_HOST_REQUIRED`, and the test cannot call a write method.
+9. Click **Done → Deploy**. Every input change updates `localDeviceMappings`, and Done serializes all cards once more. The same assignments are therefore restored after reopening/deploy; users never edit mapping JSON.
+10. In a Read node, select the configured appliance and the desired read resource. There is no Host/IP field. In an Events node, select one configured appliance or **All configured appliances**.
+
+The profile-to-Host/IP/transport assignment is serialized once as `localDeviceMappings` in the configuration node. Read and Events nodes store only the profile/appliance ID.
+
+All appliance selectors show a descriptive display label in the form `type — friendly name — brand/model — …last four ID characters`. The complete technical ID remains the option value and is never shortened in runtime state or requests.
+
+**Advanced fallback:** **Paste profile JSON manually (optional)** accepts a complete profile only when no folder is active. With a folder set, the section is collapsed/disabled by default and folder data takes precedence. **Generate from detected profiles and assignments** can create the credential JSON after all cards are valid. This prevents beginners from writing mapping/profile JSON and never presents a credential placeholder as sample data.
+
+The **safe protocol trace** is also under **Advanced** and disabled by default. Without a file path, a bounded ring buffer remains in memory and is shown in a collapsible section after a connection test. An absolute server-side path writes JSONL with mode `0600` on POSIX; on Windows, use an account-restricted NTFS ACL because POSIX permission bits are not represented reliably. It records decrypted RX/TX protocol messages and lifecycle events, but removes PSKs, IVs, keys, OAuth data, nonces, and appliance/network identifiers. Enable it only while diagnosing, inspect the file before sharing, then disable it again.
+
+Example central assignment in an exported, anonymized config node (all values fictional; keys remain in the protected profile folder and are not exported):
+
+```json
+"localDeviceMappings": "[{\"profileId\":\"dishwasher-local\",\"host\":\"192.168.x.x\",\"connectionType\":\"auto\"}]"
+```
+
+For Docker, mount the directory read-only and use the path inside the container:
+
+```yaml
+volumes:
+  - ./homeconnect-profiles:/data/homeconnect-profiles:ro
+```
+
+## Read and event mapping
+
+After the session handshake, the client reads only these `ro` resources, in this order and by `GET`:
+
+- `/ro/allMandatoryValues`
+- `/ro/values`
+- `/ro/allDescriptionChanges`
+- `/ro/activeProgram`
+- `/ro/selectedProgram`
+
+Numeric runtime UIDs are resolved against both profile files. `FeatureMapping.xml` supplies semantic feature names and, where present, enum members; `DeviceDescription.xml` supplies hexadecimal `uid` values, categories, access/type/unit metadata, and enum references. The resolver follows direct `enumerationType` attributes, nested `<enumerationType refENID="…"/>` elements, `enid` references, and `subsetOf` inheritance. Some real profiles place the authoritative enum table in `DeviceDescription.xml` as `<enumerationType enid="…">`, with enum/member names in the immediately preceding XML comments. All XML identifiers (`uid`, `refUID`, `enid`, `refENID`, `enumerationType`, and `subsetOf`) are hexadecimal even when they contain digits only: `2100` therefore means decimal UID 8448, not 2100.
+
+No global appliance UID or enum table is used. For example, OperationState raw value `0` is translated only when the selected appliance profile defines that member. A profile enum always takes precedence over scalar handling. Profile-typed Boolean values are normalized for RemoteControlActive, RemoteControlStartAllowed, LocalControlActive, and Boolean options. Every local item keeps `rawValue`; `valueResolved` is true only for an actual enum member, a valid profile Boolean/program, or an explicitly typed scalar. If an enum member is missing, the raw value remains visible with `valueResolved: false`, and no status or event warning is inferred from it. On a local read-only connection without an active control context, `RemoteControlStartAllowed=false` remains neutral status rather than a persistent warning.
+
+Resolved status/event features become `status.items`, settings become `settings.items`, and every received item—including unresolved numeric UIDs—remains in `values.items`. Program definitions come from profile features. `BSH.Common.Root.ActiveProgram` and `BSH.Common.Root.SelectedProgram` values are resolved back to program feature names, and currently received option items are attached to program state. A 404 from the optional `/ro/activeProgram` or `/ro/selectedProgram` path therefore does not erase program/options already present in `/ro/allMandatoryValues`.
+
+Snapshots expose a safe `profileResolution` summary (feature/item/resolved/unresolved/status/setting/program counts and at most 20 unresolved numeric UIDs). It contains no host, appliance identity, PSK, IV, nonce, or credential. A rejected optional read is listed under `refresh`, but data received from another successful response or appliance `NOTIFY` remains authoritative and is not discarded.
+
+The local Events node emits normalized `CONNECTED`, `DISCONNECTED`, and `STATUS` messages through the same health/warning layer used by cloud data. Local outputs include `connection.local: true` and `connection.readOnly: true`.
+
+If a configured host is unreachable, snapshot/capability reads return the appliance with `connected: false`, `connection.state: "offline"`, and only a safe network reason instead of converting the device into an unrelated generic error. Values already held by the session are marked stale and retained. An active Events node keeps reconnecting with bounded backoff and emits recovery updates after the appliance becomes reachable again.
+
+The complete sequence follows hcpy and homeconnect-websocket:
+
+1. The appliance sends `POST /ei/initialValues`. The response uses the same `sID`, the same `msgID`, and the EI-version-specific application structure. The client's next counter starts exactly at `data.edMsgID`.
+2. `/ci/services` is always requested as `GET`, version 1, with **no** `data` member. Device code `0`, `200`, or no code is accepted as success.
+3. Every returned service version is used for its service. For `ci < 3`, `/ci/authentication` first follows hcpy and sends `POST` with a 32-byte nonce; only a concrete rejection triggers the documented `GET` fallback.
+4. `NOTIFY /ei/deviceReady` uses the negotiated EI version and omits an empty `data` array.
+5. Device information is optionally read from `/iz/info` when `iz` is advertised, otherwise `/ci/info`; `/ni/info` is used only when `ni` exists. Rejection of these optional diagnostic paths does not block the read-only session.
+6. The five `/ro/*` GETs use the advertised `ro` version. Not every model supports every resource: an individual code 400 is recorded while the remaining read paths continue.
+
+Unsolicited appliance `NOTIFY` and `RESPONSE` messages are processed immediately. Initial/mandatory/value data already delivered by the appliance counts as successful read-only reception even if a later fallback GET is rejected. Appliance-originated housekeeping `GET`/`POST` requests (for example `/ei/keepAlive`) receive a `RESPONSE` with the same session and appliance `msgID`; this does not advance the client's `edMsgID` counter. WebSocket ping/pong remains separate. The connection remains technically read-only: the nonce, device-ready notification, and protocol responses cannot change settings or programs.
+
+## Network restrictions
+
+Before opening a socket, the configured hostname must resolve **only** to RFC1918, IPv4 link-local, IPv6 unique-local, or IPv6 link-local addresses. Loopback, URLs, paths, credentials in hostnames, and public DNS results are rejected. This prevents the local profile field from becoming an arbitrary Internet socket target.
+
+## Troubleshooting
+
+| Code/symptom | Meaning/action |
+|---|---|
+| `LOCAL_PROFILE_REQUIRED` | Set a profile folder or optional manual profile JSON, then save and deploy. |
+| `LOCAL_PROFILE_FOLDER_REQUIRED` | Automatic discovery needs a directory, not an individual file. |
+| `LOCAL_PROFILE_FILES_INCOMPLETE` | Keep the appliance JSON, `DeviceDescription.xml`, and `FeatureMapping.xml` from the same download together, then scan again. |
+| `LOCAL_PROFILE_ORPHAN_COMPANION` | An XML/JSON companion cannot be paired by folder/base name; restore the original downloader filenames. |
+| `LOCAL_MAPPING_HOST_REQUIRED` | The selected card itself has no Host/IP. Enter it; unfilled sibling cards do not block an individual test. |
+| `LOCAL_MAPPING_DUPLICATE` | Keep exactly one central assignment for each profile ID. |
+| `LOCAL_MAPPING_PROFILE_NOT_FOUND` | The folder changed after mapping; rescan to remove stale assignments. |
+| `LOCAL_PROFILE_KEY_MISSING` / `LOCAL_PROFILE_IV_MISSING` | Re-download the complete profile; do not invent keys. |
+| `LOCAL_HOST_NOT_PRIVATE` | Correct DNS/IP; the appliance must resolve only to a private/link-local address. |
+| `LOCAL_NETWORK_ERROR` / `LOCAL_CONNECT_TIMEOUT` | Check same-LAN reachability, DNS/IP, VLAN/firewall, appliance Wi-Fi, and port 80/443. `EHOSTUNREACH` means there is no network path, commonly because the appliance is off/asleep, the IP is stale, VLAN routing is missing, or a firewall blocks it. |
+| `LOCAL_HANDSHAKE_TIMEOUT` / `LOCAL_REQUEST_TIMEOUT` | The socket opened, but the appliance did not complete the protocol/read response. Check profile, transport, firmware compatibility, and packet loss. |
+| `LOCAL_TRANSPORT_UNSUPPORTED` | Keep Auto, or correct an explicit AES/TLS override; also verify Node.js/OpenSSL PSK support. |
+| `LOCAL_TLS_PSK_UNAVAILABLE` | The Node.js/OpenSSL runtime exposes none of the required TLS 1.2 PSK cipher suites; use a runtime/OpenSSL build with PSK support. |
+| `LOCAL_PROFILE_KEY_REJECTED` / `LOCAL_PROFILE_AUTHENTICATION_FAILED` | The profile/key does not match this appliance or is incomplete. Re-download and assign the correct profile; never guess keys. |
+| `LOCAL_PROTOCOL_REJECTED` | The appliance returned a protocol code (for example 400). Diagnostics identify the exact resource, action, negotiated version, and device code; a completely rejected read sequence lists every attempt. Enable the sanitized trace and compare transport/profile/firmware. |
+| `LOCAL_CONNECT_FAILED` | Connection failed without a more specific network/key/transport classification. Check the preceding items. |
+| `LOCAL_WEBSOCKET_UPGRADE_FAILED` | TCP/TLS succeeded, but the appliance rejected the RFC 6455 upgrade on `/homeconnect`. Verify profile assignment, Auto/AES/TLS, IP, and proxies; a returned HTTP status is reported without exposing headers or keys. |
+| `LOCAL_CRYPTO_AUTH_FAILED` / `LOCAL_CRYPTO_PADDING_INVALID` | PSK/IV mismatch or lost AES-CBC/HMAC stream state; the client closes immediately. Re-download profiles if persistent. |
+| `LOCAL_HEARTBEAT_TIMEOUT` / `LOCAL_DISCONNECTED` | The connection was established but stopped responding. Check appliance power/standby, Wi-Fi, VLAN, and firewall; the client rebuilds the complete session with backoff. |
+| `LOCAL_TRACE_PATH_INVALID` | Use an absolute path inside the Node-RED host/container for file tracing. With no path, only the safe in-memory ring buffer is used. |
+| TLS handshake failure | Confirm the profile says TLS, Node.js/OpenSSL exposes PSK cipher suites, and no TLS-inspecting proxy is present. |
+| raw numeric UIDs | XML mapping was absent or did not match the profile. Keep the three downloader files together. |
+| `LOCAL_READ_ONLY` | Expected security behavior. Use a separate cloud connection only if guarded cloud writes are required. |
+
+## Community protocol references
+
+The implementation was independently written for this Node-RED package using publicly available community protocol observations, especially:
+
+- `chris-mc1/homeconnect_local_hass` and `chris-mc1/homeconnect_websocket`
+- `hcpy2-0/hcpy`
+- `zibous/homeconnect-hcpy`
+- `Asmir1975/homeconnect_local_hass-UI`
+- `SukramJ/go-homeconnect2mqtt` protocol notes
+
+No appliance profile, user credential, serial number, host, PSK, IV, or code copied from those projects is included in this package. See [NOTICE](../NOTICE) for attribution and license reminders.

package/docs/MESSAGE-API.md

@@ -0,0 +1,111 @@
+# Message API
+
+All functional nodes preserve unrelated incoming properties. Output 2 contains a structured error in `msg.payload`. Confirmation values are removed from success and error output.
+
+## Normalized health envelope
+
+Every functional output includes:
+
+```js
+msg.health = 'ok'; // ok | running | info | warning | action_required | offline | error
+msg.warnings = [{
+  source: 'status',       // status | event | connection | api | oauth
+  code: 'HC_...',         // stable integration code
+  severity: 'warning',    // info | warning | error | critical
+  text: { de: '...', en: '...' },
+  transient: false
+}];
+msg.homeConnect.health = msg.health;
+msg.homeConnect.warnings = msg.warnings;
+msg.homeConnect.healthSchema = 'home-connect-health/v1';
+msg.homeConnect.healthAt = '...';
+```
+
+Snapshots and discovery entries also carry `payload.health`, `payload.warnings`, `payload.healthSchema`, and `payload.healthAt`. Raw API status and event values are retained. Transient notices are deduplicated and expire; disconnected/offline state remains until a later connection or snapshot confirms recovery. Errors are assessed for that error output and do not poison later successful messages.
+
+## discover
+
+```js
+msg.haId = '...';   // single mode
+msg.force = true;   // bypass five-minute capability cache
+```
+
+No real appliance ID, name, program or capability is built into the package. The editor's **Load devices** button and discovery output use the appliances returned by the connected account or protected local profiles. For local connections, Host/IP and the optional Auto/AES/TLS choice exist only in `home-connect-config`; Read and Events nodes store only a selected appliance/profile ID.
+
+Documented appliance fields such as `name`, `brand`, `type`, `vib` and `connected` remain available under `appliance`. Firmware version/history/update is not part of the public API and has no message operation.
+
+## read
+
+```js
+msg.haId = '...';
+msg.operation = 'snapshot';
+msg.key = '...';       // resource key, map ID or cleaning-summary counter
+msg.subKey = '...';    // detected object, room or zone ID
+```
+
+Operations:
+
+- `snapshot`, `capabilities`, `appliances`, `appliance`
+- `status`, `status-item`, `settings`, `setting`
+- `all-programs`, `programs`, `program`
+- `active-program`, `active-options`, `active-option`
+- `selected-program`, `selected-options`, `selected-option`
+- `commands`, `images`, `image`
+- `maps`, `map`, `map-occupancy-grid`, `map-layout`, `map-cleaning-status`
+- `map-detected-objects`, `map-detected-object`, `map-rooms`, `map-room`, `map-zones`, `map-zone`
+- `map-robot-position`, `map-config-restrictions`, `map-cleaning-summaries`, `map-cleaning-summary`
+
+`image` returns:
+
+```js
+msg.payload = {
+  contentType: 'image/jpeg',
+  data: Buffer.from(/* JPEG bytes */)
+};
+```
+
+The operation may select only a predefined resource; it cannot provide a URL or HTTP method. Local connections support appliance/snapshot/status/settings/program reads derived from `/ro/*` values. Cloud-only image/map operations return `LOCAL_READ_UNSUPPORTED` locally.
+
+## events
+
+An input message with `msg.haId` restarts the stream for that appliance. Use `*` for all configured appliances. The cloud client reconnects SSE with bounded exponential backoff and sends `Last-Event-ID` when supplied. The local client maintains per-appliance WebSockets and emits `STATUS`. Both emit synthetic `CONNECTED` and `DISCONNECTED` lifecycle events. Local event envelopes include `connection.local: true` and `connection.readOnly: true`.
+
+## write
+
+A request can be supplied in `msg.payload`; top-level `msg.haId`, `msg.action`, `msg.program`, `msg.key`, `msg.value` and `msg.options` take precedence.
+
+### Start a program
+
+```js
+msg.payload = {
+  action: 'start-program',
+  haId: '...',
+  program: 'Cooking.Oven.Program.HeatingMode.HotAir',
+  options: [{ key: 'Cooking.Oven.Option.SetpointTemperature', value: 180 }],
+  confirm: 'CONFIRM'
+};
+```
+
+### Other actions
+
+```js
+msg.payload = { action: 'stop-program', haId: '...', confirm: 'CONFIRM' };
+msg.payload = { action: 'select-program', haId: '...', program: '...', options: [], confirm: 'CONFIRM' };
+msg.payload = { action: 'set-setting', haId: '...', key: 'BSH.Common.Setting.PowerState', value: 'BSH.Common.EnumType.PowerState.Standby', confirm: 'CONFIRM' };
+msg.payload = { action: 'command', haId: '...', key: 'BSH.Common.Command.PauseProgram', value: true, confirm: 'CONFIRM' };
+msg.payload = { action: 'set-active-option', haId: '...', key: 'BSH.Common.Option.Duration', value: 600, confirm: 'CONFIRM' };
+msg.payload = { action: 'set-selected-option', haId: '...', key: '...', value: '...', confirm: 'CONFIRM' };
+```
+
+Options may also be an object shorthand:
+
+```js
+msg.options = {
+  'Cooking.Oven.Option.SetpointTemperature': 180,
+  'BSH.Common.Option.Duration': { value: 1800, unit: 'seconds' }
+};
+```
+
+Arbitrary methods, paths, body envelopes and bulk writes are intentionally unsupported. The confirmation token is stored in Node-RED credentials rather than in the flow JSON.
+
+Local configurations reject every write with `LOCAL_READ_ONLY` before capability validation or network I/O. This cannot be overridden by `msg`, editor fields, or `allowWrite`.

package/docs/RELEASE.md

@@ -0,0 +1,91 @@
+# Release procedure for 0.2.0
+
+The feature set is frozen at build `hc-0.2.0-final`. Only release-blocking corrections are allowed, followed by the complete validation sequence.
+
+## Package identity
+
+- npm package: `@impact0815/node-red-contrib-home-connect`
+- version: `0.2.0`
+- GitHub repository: `impact0815/node-red-contrib-home-connect`
+- npm homepage: `https://www.npmjs.com/package/@impact0815/node-red-contrib-home-connect`
+- npm TGZ filename: `impact0815-node-red-contrib-home-connect-0.2.0.tgz`
+
+## Required local checks
+
+```bash
+npm ci --ignore-scripts
+npm run release:check
+npm run validate
+npm pack --json
+sha256sum impact0815-node-red-contrib-home-connect-0.2.0.tgz
+tar -tzf impact0815-node-red-contrib-home-connect-0.2.0.tgz | sort
+npm publish --dry-run ./impact0815-node-red-contrib-home-connect-0.2.0.tgz --access public --registry https://registry.npmjs.org/
+```
+
+The screenshots in `docs/images/` must remain the reviewed simulated images. The examples and package payload must not contain credentials, account data, real appliance identifiers, or private network data.
+
+## Existing GitHub repository: normal additional commit
+
+Follow [GITHUB-UPDATE.md](GITHUB-UPDATE.md). In summary:
+
+```bash
+git switch main
+git pull --ff-only origin main
+npm ci --ignore-scripts
+npm run release:check
+npm run validate
+git add -A
+git diff --cached --check
+git commit -m "Use scoped npm package and finalize 0.2.0"
+git push origin main
+```
+
+Do not force-push. Wait until GitHub Actions CI succeeds on `main`.
+
+## Tag and GitHub Release
+
+Confirm that `v0.2.0` does not already exist. Then:
+
+```bash
+git tag -a v0.2.0 -m "@impact0815/node-red-contrib-home-connect v0.2.0"
+git push origin v0.2.0
+
+ARTIFACT_DIR="/absolute/path/to/release-files"
+gh release create v0.2.0 \
+  "$ARTIFACT_DIR/impact0815-node-red-contrib-home-connect-0.2.0-source.zip" \
+  "$ARTIFACT_DIR/impact0815-node-red-contrib-home-connect-0.2.0.tgz" \
+  "$ARTIFACT_DIR/SHA256SUMS.txt" \
+  --repo impact0815/node-red-contrib-home-connect \
+  --verify-tag \
+  --title "@impact0815/node-red-contrib-home-connect 0.2.0" \
+  --notes-file ./RELEASE_NOTES.md
+```
+
+## npm publication
+
+```bash
+ARTIFACT_DIR="/absolute/path/to/release-files"
+npm config get registry
+npm whoami --registry https://registry.npmjs.org/
+npm view @impact0815/node-red-contrib-home-connect versions --json --registry https://registry.npmjs.org/ || true
+npm publish "$ARTIFACT_DIR/impact0815-node-red-contrib-home-connect-0.2.0.tgz" --access public --registry https://registry.npmjs.org/
+npm view @impact0815/node-red-contrib-home-connect@0.2.0 name version dist.integrity dist.tarball --registry https://registry.npmjs.org/
+```
+
+If npm requires two-factor authentication, complete its prompt or add a current one-time password with `--otp=<code>`. Never put an npm token or OTP into the repository.
+
+## Post-publication smoke test
+
+```bash
+TMPDIR="$(mktemp -d)"
+cd "$TMPDIR"
+npm init -y
+npm install @impact0815/node-red-contrib-home-connect@0.2.0
+node -p "require('@impact0815/node-red-contrib-home-connect/BUILD-INFO.json')"
+```
+
+The package name must be `@impact0815/node-red-contrib-home-connect`, the version `0.2.0`, and the build ID `hc-0.2.0-final`.
+
+## Node-RED Flow Library
+
+After npm publication, sign in at `https://flows.nodered.org/add/node`, enter the exact package name `@impact0815/node-red-contrib-home-connect`, and submit it. The package must already be public on npm and must retain the `node-red` keyword, README, license, and `node-red.nodes` metadata.

package/docs/TROUBLESHOOTING.de.md

@@ -0,0 +1,230 @@
+# Home Connect: Troubleshooting und FAQ
+
+Zurück zur [deutschen README](../README.de.md).
+
+Diese Anleitung beginnt beim sichtbaren Symptom. Zugangsdaten, Hostnamen, Geräte-IDs und OAuth-Codes gehören nie in Fehlerberichte.
+
+## 1. Vorprüfung in zwei Minuten
+
+1. Läuft wirklich der erwartete Build?
+   ```bash
+   cd ~/.node-red
+   node -p "require('./node_modules/@impact0815/node-red-contrib-home-connect/BUILD-INFO.json')"
+   ```
+   Erwartet: Version `0.2.0`, Build `hc-0.2.0-final`, `pkce: false`.
+2. Ist die richtige Connection ausgewählt und eindeutig benannt?
+3. Wurde nach der letzten Änderung **Fertig → Deploy** ausgeführt?
+4. Sind Redirect URI im Developer Portal und in Node-RED exakt gleich?
+5. Ist die Node-RED-Adresse vom verwendeten Browser erreichbar?
+6. Wurde OAuth bis zur Seite **Home Connect authorized** abgeschlossen?
+7. Enthalten die Scopes mindestens `IdentifyAppliance` und die benötigten gerätespezifischen Rechte?
+
+## 2. Autorisieren ist deaktiviert
+
+Das ist Absicht: Die Config-Node prüft, ob genau diese gespeicherte Konfiguration bereits in der laufenden Node-RED-Runtime existiert.
+
+- **Neue/änderte Verbindung:** Fertig klicken, deployen, Verbindung erneut öffnen.
+- **Integrierter Simulator:** OAuth ist nicht erforderlich.
+- **Weiterhin deaktiviert:** Node-RED vollständig neu starten und Browser hart neu laden. Prüfen, ob eine zweite/alte Paketinstallation existiert.
+
+## 3. `CONFIG_NOT_FOUND`
+
+**Bedeutung:** Die URL enthält die ID einer Config-Node, welche die laufende Runtime nicht kennt.
+
+Typische Ursachen:
+
+- Beispiel- oder Simulator-Config wurde referenziert.
+- Verbindung wurde zwar im Editor angelegt, aber nicht deployt.
+- Alter Browser-Tab enthält eine Autorisierungs-URL einer gelöschten Config.
+- Nach Paket-/Flow-Wechsel läuft noch eine andere Runtime-Instanz.
+
+**Behebung:**
+
+1. Alten Auth-Tab schließen.
+2. Im verwendeten Home-Connect-Node die richtige Connection wählen.
+3. Connection eindeutig benennen.
+4. Fertig → Deploy.
+5. Connection erneut öffnen.
+6. Autorisierung über den dortigen Knopf neu starten.
+
+## 4. Falsche oder irreführende Verbindungsbezeichnung
+
+Technisch steuert das Feld **Umgebung** den API-Host, nicht der Name. Ein Name wie `Simulator` bei Umgebung `Production` erhöht aber das Fehlerrisiko. Die Oberfläche zeigt deshalb eine Warnung. Name korrigieren, speichern und deployen.
+
+## 5. Redirect URI: exakter Vergleich
+
+Folgende Teile müssen identisch sein:
+
+| Teil | Häufiger Fehler |
+|---|---|
+| Protokoll | `http` im Portal, `https` in Node-RED |
+| Host | DNS-Name im Portal, IP-Adresse in Node-RED |
+| Port | Port fehlt auf einer Seite |
+| Pfad | Tippfehler in `/home-connect/oauth/callback` |
+| Ende | zusätzlicher Slash `/callback/` |
+| Groß-/Kleinschreibung | abweichende Zeichen im Pfad |
+
+Am sichersten die vollständige URI aus einem Feld kopieren und im anderen einfügen.
+
+## 6. Nach Login: localhost, `ERR_EMPTY_RESPONSE`, Verbindung fehlgeschlagen
+
+`localhost` zeigt aus Sicht des Browsers auf das Browser-Gerät. Läuft Node-RED auf NAS, Server, Raspberry Pi, Home Assistant, ioBroker oder in einem anderen Rechner/Container, erreicht der Browser dort nicht Node-RED.
+
+1. Einen vom Browser erreichbaren Hostnamen oder eine erreichbare IP-Adresse für Node-RED wählen.
+2. Callback-Pfad anhängen: `/home-connect/oauth/callback`.
+3. URI im Developer Portal ändern.
+4. Dieselbe URI in Node-RED eintragen.
+5. Fertig → Deploy.
+6. OAuth neu starten.
+
+## 7. `unauthorized_client` / `client or redirection URI not authorized`
+
+Prüfreihenfolge:
+
+1. Wurde Client ID aus der richtigen Developer-Portal-Application kopiert?
+2. Stimmt die Redirect URI Zeichen für Zeichen?
+3. Verwendet die Application den Authorization Code Grant?
+4. Ist PKCE in dieser Application deaktiviert?
+5. Läuft der Build `hc-0.2.0-final`?
+6. Wurde nach jeder Änderung eine neue Autorisierung gestartet?
+
+Wurde das Client Secret sichtbar, nicht weiter testen: Secret regenerieren, in Node-RED ersetzen, deployen und neu autorisieren.
+
+## 8. Nach Update läuft alter Code
+
+Ein Flow-Deploy lädt keinen neuen Node.js-Runtime-Code. Zusätzlich zur npm-Version BUILD-INFO prüfen, um doppelte Installationen zu erkennen.
+
+```bash
+cd ~/.node-red
+npm uninstall @impact0815/node-red-contrib-home-connect
+rm -rf node_modules/@impact0815/node-red-contrib-home-connect
+npm install --force /absoluter/pfad/impact0815-node-red-contrib-home-connect-0.2.0.tgz
+node -p "require('./node_modules/@impact0815/node-red-contrib-home-connect/BUILD-INFO.json')"
+```
+
+Danach Node-RED/Container vollständig neu starten, Browser hart neu laden und OAuth neu beginnen. Authorization Codes und State-Links sind kurzlebig/einmalig und dürfen nicht wiederverwendet werden.
+
+## 9. `No refresh token is stored. Complete OAuth authorization first.`
+
+Der Refresh Token wird erst beim erfolgreichen Callback gespeichert.
+
+- Autorisierung aus der deployten Connection starten.
+- Login und Zustimmung abschließen.
+- Auf **Home Connect authorized** warten.
+- Erst dann Test/Discover/Read/Events ausführen.
+
+Bleibt der Fehler, den Fehler auf der Callback-Seite notieren, aber keine Codes/Tokens veröffentlichen.
+
+## 10. `insufficient_scope`
+
+Der Token darf die angeforderte Ressource nicht lesen oder steuern.
+
+1. `IdentifyAppliance` beibehalten.
+2. Passenden gerätespezifischen Scope ergänzen, etwa `Dishwasher-Monitor`, `Washer-Monitor` oder `Oven-Monitor`.
+3. Für Aktionen zusätzlich nur benötigtes `*-Control` und/oder `*-Settings` ergänzen.
+4. Fertig → Deploy.
+5. Neu autorisieren; ein alter Refresh Token erhält nicht automatisch neue Rechte.
+
+Der allgemeine Scope `Monitor` kann je nach Application/Konto unzureichend sein.
+
+## 11. Events zeigt dauerhaft `reconnecting`
+
+`reconnecting` ist ein Folgezustand, nicht die eigentliche Ursache. Den zweiten Ausgang des Events-Nodes mit Debug verbinden.
+
+Häufig:
+
+- kein Refresh Token
+- fehlender Monitor-Scope
+- abgelaufene/entzogene Autorisierung
+- Netzwerk-/Proxy-Unterbrechung des SSE-Streams
+- zu viele parallele Event-Streams
+
+Zuerst Geräteliste/Test reparieren, dann einen einzigen Events-Node mit Appliance ID `*` verwenden.
+
+## 12. Erfolgsbild
+
+Die Einrichtung ist abgeschlossen, wenn:
+
+1. die Browserseite **Home Connect authorized** anzeigt,
+2. Test ohne Fehler eine Geräteanzahl meldet,
+3. **Geräte laden** die Auswahl befüllt,
+4. der Events-Node nach Verbindung Events ausgibt statt dauerhaft zu reconnecten.
+
+## 13. Sicheres Fehlerreporting
+
+Erlaubt:
+
+- Paketversion und Build-ID
+- Node.js- und Node-RED-Version
+- Umgebungstyp (Production/Simulator), ohne privaten Hostnamen
+- Fehlercode und bereinigte Fehlermeldung
+- Schritte zur Reproduktion mit Simulator
+
+Nicht veröffentlichen:
+
+- Client ID oder Client Secret
+- Access-/Refresh-Token
+- Authorization Code oder OAuth-State
+- echte Redirect-URI/Hostname/IP
+- echte `haId`, Serien-/Gerätenummern
+- vollständige Events oder Debug-Ausgaben mit persönlichen Daten
+
+
+## 14. Health- und Warning-Codes verstehen
+
+Jede funktionale Ausgabe enthält das Schema `home-connect-health/v1`:
+
+- `ok`: keine aktuelle Auffälligkeit
+- `running`: Programm läuft
+- `info`: nützlicher, nicht dringender Hinweis
+- `warning`: Einschränkung oder pausierter/abbrechender Zustand
+- `action_required`: Eingriff oder neue Autorisierung erforderlich
+- `offline`: Gerät, Event-Stream oder Netzwerk nicht erreichbar
+- `error`: Geräte-/API-Fehler
+
+`warnings` ist dedupliziert. Jeder Eintrag enthält mindestens `source`, `code`, `severity`, `text.de`, `text.en` und `transient`. Kurzlebige Hinweise besitzen zusätzlich Zeitfelder und verschwinden nach Ablauf. Statusbedingungen bleiben nur so lange bestehen, wie der aktuelle Status sie bestätigt.
+
+Wichtige Codes:
+
+| Code | Bedeutung | Maßnahme |
+|---|---|---|
+| `HC_OPERATION_ACTION_REQUIRED` | Gerät fordert lokalen Eingriff | Gerätedisplay/Tür/Vorräte prüfen |
+| `HC_STREAM_DISCONNECTED` | SSE-Verbindung getrennt | Reconnect abwarten; bei Dauerfehler Ausgang 2 prüfen |
+| `HC_OAUTH_INSUFFICIENT_SCOPE` | Token hat zu wenige Rechte | Scope korrigieren, deployen, neu autorisieren |
+| `HC_OAUTH_AUTHORIZATION_EXPIRED` | Autorisierung fehlt/abgelaufen/widerrufen | neu autorisieren |
+| `HC_API_RATE_LIMITED` | HTTP 429/API-Limit | Polling reduzieren, `retryAfter` beachten |
+| `HC_NETWORK_ERROR` | Netzwerk/Timeout | DNS, Proxy, TLS und Erreichbarkeit prüfen |
+
+Der Events-Node erzeugt zusätzlich synthetische `CONNECTED`-/`DISCONNECTED`-Lebenszyklusereignisse für den tatsächlichen SSE-Stream. Sie enthalten keine Zugangsdaten.
+
+## 15. HTTP 429 / `1000 calls in 1 day`
+
+Der lokale Limiter verhindert standardmäßig, dass dieses Paket mehr als 900 API-Versuche in einem rollierenden 24-Stunden-Fenster sendet. In der Verbindung werden der aktuelle Verbrauch und eine eventuelle Sperrzeit angezeigt. Bei ausgeschöpftem Budget erscheint `LOCAL_RATE_LIMITED`; `retryAfter` und `resetAt` geben die verbleibende Wartezeit an.
+
+Wenn Home Connect bereits HTTP 429 mit einer Meldung wie `remaining period of 75502 seconds` zurückgegeben hat, übernimmt das Paket diese Sperrzeit und sendet bis dahin keine weiteren API-Aufrufe. Der Zustand bleibt über Deploys und Neustarts erhalten. Nicht wiederholt auf **Test** oder Inject-Nodes klicken. Polling deutlich reduzieren, nach Möglichkeit einen All-Appliance-Event-Stream verwenden und Snapshots nicht alle 15 Sekunden abrufen. Andere Rechner oder Programme mit derselben Developer-Portal-Application separat prüfen, da sie nicht vom lokalen Zähler erfasst werden.
+
+## 16. Firmwareversion oder Firmwareupdate fehlt
+
+Das ist kein Konfigurationsfehler. Die öffentlich dokumentierte Home-Connect-API stellt Firmwareversion, Firmwarehistorie und Firmwareupdate nicht bereit. Das Paket verwendet keine undokumentierten Endpunkte und bietet absichtlich keinen Firmware-Button. Sichtbar sind nur dokumentierte Geräteinformationen wie Name, Marke, Typ, `vib`/E-Nummer und Verbindungsstatus, sofern geliefert. Firmware ausschließlich über offizielle Hersteller-/Home-Connect-Kanäle prüfen.
+
+## 17. Lokale LAN-Profile und Verbindungsfehler
+
+Bei lokalen Konfigurationen sind OAuth-, Autorisierungs-, Refresh-Token- und Cloud-Tagesbudget-Bereiche absichtlich ausgeblendet. Erfolgreich ist die Einrichtung, wenn **Verbindung testen** in jeder Gerätekarte eine lokale Read-only-Verbindung meldet und Discover/Read/Events `local: true` sowie `readOnly: true` liefern.
+
+In dieser Reihenfolge prüfen:
+
+1. Prüfen, ob der Profilordner im Node-RED-Host/-Container wirklich unter dem eingetragenen Pfad gemountet und für das Servicekonto lesbar ist. Dann ausdrücklich **Profile suchen / Geräte erkennen** anklicken.
+2. Geräte-JSON, `DeviceDescription.xml` und `FeatureMapping.xml` desselben Profile-Downloader-Exports zusammenlassen. `LOCAL_PROFILE_FILES_INCOMPLETE` nennt die fehlende Datei; `LOCAL_PROFILE_ORPHAN_COMPANION` weist auf unpassende Ordner/Dateinamen hin.
+3. Bei einer doppelten Profil-ID nennt der Scanner die betroffenen Dateien. Keine Zuordnung raten: doppelten/alten Export entfernen und erneut suchen.
+4. Nach erfolgreicher Suche muss zum Beispiel **3 Geräteprofile gefunden** erscheinen. Für jedes vollständige Profil gibt es genau eine Karte. Fehlt eine Karte, die Hinweise direkt unter dem Suchergebnis lesen.
+5. In jeder Karte Host/IP eintragen. Fehlende, formal falsche oder öffentliche IPs werden rot markiert. Hostnamen werden beim Test serverseitig aufgelöst. Nur private/link-lokale Ziele sind erlaubt; Loopback und öffentliche Ziele werden mit `LOCAL_HOST_NOT_PRIVATE` abgewiesen. Ein Einzeltest verwendet sofort die aktuellen Felder genau dieser Karte, benötigt noch kein Fertig/Deploy und wird nicht von leeren Nachbarkarten blockiert.
+6. **Verbindungsart: Auto (empfohlen)** beibehalten. Eine ausdrückliche Profilangabe AES/TLS/PSK hat Vorrang; IV-Anwesenheit ist nur der Fallback. `LOCAL_PROFILE_IV_MISSING` bei AES-Override bedeutet, dass das Original-IV fehlt.
+7. Pro Karte **Verbindung testen** anklicken und die sieben Stufen lesen. `LOCAL_NETWORK_ERROR`/Timeout stoppt bei **IP erreichbar**. `EHOSTUNREACH` ist ein fehlender Netzwerkpfad und kein Protokollfehler: Gerät aus/Standby, IP, WLAN, VLAN-Routing und Firewall prüfen. `LOCAL_TLS_PSK_UNAVAILABLE`/`LOCAL_TRANSPORT_UNSUPPORTED` stoppt bei **Transport erkannt**. `LOCAL_WEBSOCKET_UPGRADE_FAILED` bedeutet: TCP beziehungsweise TLS war erfolgreich, aber das Gerät lehnte den Upgrade auf `/homeconnect` ab. Der Test liest nur lokale Ressourcen.
+8. Erst wenn alle Karten gültig sind: **Fertig → Deployen**. Dabei wird `localDeviceMappings` nochmals gespeichert und nach Deploy wiederhergestellt. Host/IP nie in Read-/Events-Nodes eintragen; dort die verständliche Bezeichnung wählen, während intern die volle ID erhalten bleibt.
+9. `LOCAL_CRYPTO_AUTH_FAILED`, `LOCAL_PROFILE_KEY_REJECTED` oder `LOCAL_PROFILE_AUTHENTICATION_FAILED` bedeutet falsches/unvollständiges Profil; PSK/IV weder bearbeiten noch raten. `LOCAL_PROTOCOL_REJECTED` ist davon getrennt und nennt Ressource, Aktion, ausgehandelte Version und Gerätecode. Einzelne nicht unterstützte `/ro/*`-Pfade sind zulässig, sobald ein anderer Read oder ein Geräte-`NOTIFY` Werte geliefert hat. Werden alle fünf Pfade abgelehnt, enthält `rejectedResources` die komplette Folge. `/ci/services` muss Version 1 ohne leeres `data`-Array verwenden.
+10. Werden nur numerische UIDs angezeigt, die XML-Dateien desselben Downloads wiederherstellen und neu suchen.
+11. Manuelles Profil-JSON ist nur der optionale Bereich **Erweitert**. Bei gesetztem Ordner ist es deaktiviert/ignoriert. Bei Bedarf mit der Schaltfläche aus erkannten Profilen und Zuordnungen erzeugen statt selbst schreiben.
+12. Für reale Firmwareabweichungen unter **Erweitert** den sicheren Protokoll-Mitschnitt kurz aktivieren. Ohne Pfad erscheint nur der begrenzte, bereinigte Speicherpuffer beim Test; ein absoluter Pfad schreibt unter POSIX JSONL mit `0600`. Unter Windows den Mitschnittpfad per NTFS-ACL auf das Node-RED-Dienstkonto beschränken, weil POSIX-Rechte dort nicht zuverlässig sind. PSK, IV, Schlüssel, Nonces sowie Geräte-/Netzwerkkennungen werden entfernt. Vor Weitergabe trotzdem prüfen, danach ausschalten und Datei löschen.
+13. `LOCAL_HEARTBEAT_TIMEOUT` oder `LOCAL_DISCONNECTED` nach zunächst erfolgreicher Verbindung deutet auf Strom/Standby, WLAN-Roaming, VLAN/Firewall oder Paketverlust. Die Runtime baut Transport, Kryptozustand, `sID`, `msgID`, Services und Read-Session mit Backoff vollständig neu auf.
+
+`LOCAL_READ_ONLY` ist kein Verbindungsfehler, sondern die erfolgreiche lokale Schreibsperre. Für abgesicherte Schreibzugriffe eine separate Cloud-Konfiguration verwenden. Siehe [Lokale LAN-Verbindung](LOCAL-LAN.de.md).