Verification Request: homebridge-roborock-matter

[mathiashornbek]

Plugin Name

homebridge-roborock-matter

Link To GitHub Repo

https://github.com/mathiashornbek/homebridge-roborock-matter

Plugin Icon (Optional)

What this plugin does, and how it differs from existing verified plugins

homebridge-roborock-matter publishes Roborock robot vacuums as native Matter
Robotic Vacuum Cleaner accessories through Homebridge 2's Matter support, using
the Roborock app account (cloud + local TCP transport with automatic
fallback) — no miio token extraction required.

Functionality not offered by any existing verified plugin:

• 2025 Roborock B01/Q7-series support (roborock.vacuum.sc05 and
  compatible). These devices exist only in the Roborock app ecosystem and speak
  a new RPC dialect with an encrypted protobuf map channel; they cannot be
  controlled by miio-based plugins at all. The verified
  homebridge-xiaomi-roborock-matter and homebridge-xiaomi-roborock-vacuum
  target classic miio-speaking vacuums over local LAN — a disjoint device and
  transport set.
• Live room tracking: while the robot is cleaning, its live map position is
  resolved against the per-room boundary outlines and published as the current
  Matter Service Area, so controllers like Apple Home show "cleaning in
  " — including runs started from the Roborock app or the robot's button.
• Matter Service Area room/map selection sourced from the Roborock account's
  named rooms (incl. multi-map homes), capability-gated vacuum/mop/vac+mop
  clean modes, dedicated pause/return-to-dock handling with command
  acknowledgement, per-device connection diagnostics with a redacted
  diagnostics report for bug reports, and Roborock-account 2FA handled entirely
  in the settings UI.

Relationship to other plugins: this is a Matter-only fork of
homebridge-roborock-vacuum2 (not verified, HomeKit/HAP-based), MIT-licensed
with all original attribution preserved. It does not replace any verified
plugin.

Technical notes for review: dynamic platform; aborts cleanly with a logged
error when unconfigured; all persisted state lives under the Homebridge storage
path; config.schema.json plus a custom settings UI; no analytics or tracking;
no post-install scripts; CI runs the 232-test suite and typechecks on Node 22
and 24 against Homebridge 1.11.x and 2.0.0-beta; a GitHub release with
changelog notes is created automatically for every version.

The plugin does not offer the same nor less functionality than that of any existing verified plugin.

🟢 Yes

The plugin successfully installs and does not start unless it is configured.

🟢 Yes

The plugin does not require the user to run Homebridge in a TTY or with non-standard startup parameters, even for initial configuration.

🟢 Yes

The plugin does not contain any analytics or calls that enable you to track the user.

🟢 Yes

If the plugin needs to write files to disk (cache, keys, etc.), it stores them inside the Homebridge storage directory.

🟢 Yes

The plugin does not throw unhandled exceptions, the plugin must catch and log its own errors.

🟢 Yes

More Information

No response

[github-actions]

🔴 Failed Checks

• Config Schema JSON: does not contain a name schema property

🟢 Passed Checks

• Installation: successfully installed
• Package JSON: homepage exists
• Package JSON: bugs.url exists and seems a valid URL
• Package JSON: keywords exist and contain 'homebridge-plugin'
• Package JSON: 'preinstall' in scripts is not present
• Package JSON: 'install' in scripts is not present
• Package JSON: 'postinstall' in scripts is not present
• Package JSON: engines.node property is compatible with Node 22
• Package JSON: engines.node property is compatible with Node 24
• Package JSON: engines.homebridge property is compatible with Homebridge 2.1.1
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v2.4.0) matches NPM version (v2.4.0)
• Config Schema JSON: exists and is valid JSON
• Config Schema JSON: contains valid JSON Schema
• Config Schema JSON: schema has valid type property
• Config Schema JSON: schema has valid properties for object type
• Config Schema JSON: contains a valid pluginAlias
• Config Schema JSON: pluginAlias matches the platform/accessory registered in code
• Config Schema JSON: the pluginType is set to 'platform'
• Dependencies: homebridge is not declared as a runtime/peer/bundled dependency
• Dependencies: hap-nodejs is not declared as a runtime/peer/bundled dependency
• Security: no known vulnerabilities in dependencies
• Security: code patterns flagged for manual review
• Security: no privilege escalation attempts detected
• GitHub Repo: repository is public
• GitHub Repo: repository is not archived
• GitHub Repo: issues are enabled
• GitHub Repo: contains releases

🔍 For Manual Review

The following items were detected and require manual review. We understand that these items may be false positives.

• Security [Critical]: accesses private keys in roborockLib/lib/roborockCrypto.js, roborockLib/lib/roborock_mqtt_connector.js
• Security: uses Function constructor which can be a security risk in dist/ui/index.js
• Security: accesses environment files in roborockLib/roborockAPI.js
• Security: uses dynamic require() which could load arbitrary code found in 2 files

ℹ️ Check Details

• These checks were run against v2.4.0 of the plugin.
• Link to the run workflow: visit →.

📋 Next Steps

• Once you have fixed these failures, comment /check on this issue to run the checks again — your request will not move forward until the checks are re-run.
• If updating your package.json and config.schema.json files, don't forget to publish a new version to NPM.
• Remember this is an automatic script: if you think something has been marked as a failure in error, let us know with a reply.
• Feel free to ask any questions you have by replying to this issue.

[mathiashornbek]

/check

The failed check is fixed in v2.4.1 (published to npm): the config schema now
contains the standard name property.

Notes on the manual-review items — all four are intentional and constrained:

• "Accesses private keys" (roborockCrypto.js, roborock_mqtt_connector.js):
  the Roborock cloud protocol itself requires a locally generated RSA keypair and
  AES session keys to encrypt traffic with Roborock's MQTT broker (same approach
  as the reference implementations, python-roborock and ioBroker.roborock). Keys
  are generated locally, used only for the vendor protocol, and persisted inside
  the Homebridge storage directory. No system or user keys are read.

• "Function constructor" (dist/ui/index.js): a deliberate ESM shim,
  new Function("specifier", "return import(specifier)"), used to dynamically
  import @homebridge/plugin-ui-utils v2+ (a pure ES module) from CommonJS
  output — TypeScript would otherwise transpile import() into require().
  The argument is a fixed string, never user input. The source comment in
  src/ui/index.ts documents this.

• "Accesses environment files" (roborockAPI.js): it reads the
  HOMEBRIDGE_STORAGE_PATH environment variable (set by Homebridge itself) as
  one candidate for locating the Homebridge storage directory. No .env files
  are read or written.

• "Dynamic require()": one is the i18n loader,
  require("./i18n/<language>/translations.json"), constrained to the plugin's
  own bundled translations directory with a fixed allowlist of language codes;
  the other is the documented ESM shim above.

Happy to provide any further detail. Thanks for the review!

Plugin icon attached (100x100 PNG):

[github-actions]

🔴 Failed Checks

Runtime Issues:

• ⚠️ Plugin crashes when started with the following configuration:

  {
    "platform": "RoborockVacuumPlatform",
    "name": "Roborock",
    "email": "test@example.com",
    "password": "testpassword",
    "encryptedToken": "test-api-key-12345",
    "skipDevices": "test-value",
    "baseURL": "https://usiot.roborock.com",
    "debugMode": false,
    "transientWarningThrottleHours": 6,
    "enableMatterServiceArea": true,
    "enableLiveRoomTracking": true,
    "enableMatterPowerSource": true,
    "enableMatterCleanMode": true,
    "enableMatterExtendedOperationalStates": false,
    "enableMatterChargingDockedStates": false,
    "matterChargedBatteryThreshold": 100,
    "cloudOnlyMode": false,
    "preferCloudForMatterCommands": false
  }

  Error:

  expected startup but failed - Plugin initialization error detected
  

  This needs to be fixed so that the plugin does not send Homebridge into a crash-restart loop. The plugin could:

  • Handle missing required configuration gracefully with proper error messages
  • Provide sensible defaults for missing values
  • Validate configuration during startup and log helpful warnings

• ⚠️ Plugin crashes when network requests fail:

  Test scenario: Network resilience test with simulated HTTP failures

  Configuration used:

  {
    "platform": "RoborockVacuumPlatform",
    "name": "Roborock",
    "email": "test@example.com",
    "password": "testpassword",
    "encryptedToken": "test-api-key-12345",
    "skipDevices": "test-value",
    "baseURL": "https://usiot.roborock.com",
    "debugMode": false,
    "transientWarningThrottleHours": 6,
    "enableMatterServiceArea": true,
    "enableLiveRoomTracking": true,
    "enableMatterPowerSource": true,
    "enableMatterCleanMode": true,
    "enableMatterExtendedOperationalStates": false,
    "enableMatterChargingDockedStates": false,
    "matterChargedBatteryThreshold": 100,
    "cloudOnlyMode": false,
    "preferCloudForMatterCommands": false
  }

  Error:

  expected startup but failed - Plugin initialization error detected
  

  This test simulates network failures to verify the plugin handles HTTP errors gracefully. The plugin should:

  • Implement proper error handling for all HTTP requests
  • Use try-catch blocks or .catch() handlers for promises
  • Provide fallback behavior when external services are unavailable
  • Log errors appropriately without crashing Homebridge
  • Consider implementing retry logic with exponential backoff

🟢 Passed Checks

• Installation: successfully installed
• Package JSON: homepage exists
• Package JSON: bugs.url exists and seems a valid URL
• Package JSON: keywords exist and contain 'homebridge-plugin'
• Package JSON: 'preinstall' in scripts is not present
• Package JSON: 'install' in scripts is not present
• Package JSON: 'postinstall' in scripts is not present
• Package JSON: engines.node property is compatible with Node 22
• Package JSON: engines.node property is compatible with Node 24
• Package JSON: engines.homebridge property is compatible with Homebridge 2.1.1
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v2.4.1) matches NPM version (v2.4.1)
• Config Schema JSON: exists and is valid JSON
• Config Schema JSON: contains valid JSON Schema
• Config Schema JSON: schema has valid type property
• Config Schema JSON: schema has valid properties for object type
• Config Schema JSON: contains a valid pluginAlias
• Config Schema JSON: pluginAlias matches the platform/accessory registered in code
• Config Schema JSON: the pluginType is set to 'platform'
• Config Schema JSON: contains a name schema property
• Dependencies: homebridge is not declared as a runtime/peer/bundled dependency
• Dependencies: hap-nodejs is not declared as a runtime/peer/bundled dependency
• Security: no known vulnerabilities in dependencies
• Security: code patterns flagged for manual review
• Security: no privilege escalation attempts detected
• Runtime: homebridge installed successfully
• Runtime: no config - homebridge should start without plugin configuration and plugin should not load
• Runtime: platform only - plugin should start with just platform property
• Runtime: minimal required - plugin should start with minimal required configuration
• Runtime: plugin shuts down cleanly within 12s of SIGTERM
• Runtime: plugin restarts cleanly without port conflicts
• GitHub Repo: repository is public
• GitHub Repo: repository is not archived
• GitHub Repo: issues are enabled
• GitHub Repo: contains releases

🔍 For Manual Review

The following items were detected and require manual review. We understand that these items may be false positives.

• Security [Critical]: accesses private keys in roborockLib/lib/roborockCrypto.js, roborockLib/lib/roborock_mqtt_connector.js
• Security: uses Function constructor which can be a security risk in dist/ui/index.js
• Security: accesses environment files in roborockLib/roborockAPI.js
• Security: uses dynamic require() which could load arbitrary code found in 2 files

ℹ️ Check Details

• These checks were run against v2.4.1 of the plugin.
• Link to the run workflow: visit →.
• External HTTP requests detected:
  • 📡 https://usiot.roborock.com/api/v3/key/sign
    Methods: POST | Count: 2 | Scenarios: full config, network resilience
  • 📡 https://usiot.roborock.com/api/v4/auth/email/login/pwd
    Methods: POST | Count: 1 | Scenarios: full config

📋 Next Steps

• Once you have fixed these failures, comment /check on this issue to run the checks again — your request will not move forward until the checks are re-run.
• If updating your package.json and config.schema.json files, don't forget to publish a new version to NPM.
• Remember this is an automatic script: if you think something has been marked as a failure in error, let us know with a reply.
• Feel free to ask any questions you have by replying to this issue.

[mathiashornbek]

/check

Both runtime failures are fixed and hardened well beyond the reported scenarios — please re-run against v2.5.0 (published to npm).

Runtime fixes (introduced in 2.4.2, verified in 2.5.0):

• A rejected Roborock login no longer escapes as an unhandled promise
  rejection. Invalid credentials (the harness's test@example.com) now stop
  cleanly with a logged, actionable message and the plugin stays idle;
  Homebridge keeps running.
• Network failures at startup (unreachable Roborock cloud) are caught and
  retried with increasing backoff (1-10 minutes, max 10 attempts) — covering
  both the simulated-HTTP-failure scenario and the real-world case of
  Homebridge booting before the network is up. A belt-and-braces .catch()
  at the platform call site guarantees nothing can escape.
• Both scenarios were reproduced and verified locally with the exact
  configuration from the harness, under Homebridge 1.8.3 and 2.1.2-beta.3:
  clean logs, no unhandled rejections, no crash-restart loop.

Additional hardening in 2.5.0 (supply-chain review feedback):

• The custom UI server now loads the pure-ESM @homebridge/plugin-ui-utils
  via native ESM (homebridge-ui is "type": "module"); the
  Function-constructor import shim flagged earlier is gone entirely.
• Removed a dead, never-called ioBroker-era ZIP/image downloader and its
  jszip dependency, plus node-forge (RSA keys now come from Node's
  built-in OpenSSL-backed generator). Production tree: 0 npm audit
  vulnerabilities.
• 241 passing tests, typecheck clean, CI green on Node 22/24 against
  Homebridge 1.11.x and 2.0.0-beta.

[github-actions]

🟢 Passed Checks

• Installation: successfully installed
• Package JSON: homepage exists
• Package JSON: bugs.url exists and seems a valid URL
• Package JSON: keywords exist and contain 'homebridge-plugin'
• Package JSON: 'preinstall' in scripts is not present
• Package JSON: 'install' in scripts is not present
• Package JSON: 'postinstall' in scripts is not present
• Package JSON: engines.node property is compatible with Node 22
• Package JSON: engines.node property is compatible with Node 24
• Package JSON: engines.homebridge property is compatible with Homebridge 2.1.1
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v2.5.0) matches NPM version (v2.5.0)
• Config Schema JSON: exists and is valid JSON
• Config Schema JSON: contains valid JSON Schema
• Config Schema JSON: schema has valid type property
• Config Schema JSON: schema has valid properties for object type
• Config Schema JSON: contains a valid pluginAlias
• Config Schema JSON: pluginAlias matches the platform/accessory registered in code
• Config Schema JSON: the pluginType is set to 'platform'
• Config Schema JSON: contains a name schema property
• Dependencies: homebridge is not declared as a runtime/peer/bundled dependency
• Dependencies: hap-nodejs is not declared as a runtime/peer/bundled dependency
• Security: no known vulnerabilities in dependencies
• Security: code patterns flagged for manual review
• Security: no privilege escalation attempts detected
• Runtime: homebridge installed successfully
• Runtime: no config - homebridge should start without plugin configuration and plugin should not load
• Runtime: platform only - plugin should start with just platform property
• Runtime: minimal required - plugin should start with minimal required configuration
• Runtime: full config - plugin should start with comprehensive configuration
• Runtime: network resilience - plugin should handle network failures without crashing
• Runtime: plugin shuts down cleanly within 12s of SIGTERM
• Runtime: plugin restarts cleanly without port conflicts
• GitHub Repo: repository is public
• GitHub Repo: repository is not archived
• GitHub Repo: issues are enabled
• GitHub Repo: contains releases

🔍 For Manual Review

The following items were detected and require manual review. We understand that these items may be false positives.

• Security [Critical]: accesses private keys in roborockLib/lib/roborockCrypto.js, roborockLib/lib/roborock_mqtt_connector.js
• Security: accesses environment files in roborockLib/roborockAPI.js
• Security: uses dynamic require() which could load arbitrary code found in 1 file

ℹ️ Check Details

• These checks were run against v2.5.0 of the plugin.
• Link to the run workflow: visit →.
• External HTTP requests detected:
  • 📡 https://usiot.roborock.com/api/v3/key/sign
    Methods: POST | Count: 2 | Scenarios: full config, network resilience
  • 📡 https://usiot.roborock.com/api/v4/auth/email/login/pwd
    Methods: POST | Count: 1 | Scenarios: full config

📋 Next Steps

All checks passed successfully, nice work! Your plugin and/or icon will now be manually reviewed by the Homebridge team.