Verification Request: homebridge-roborock-vacuum

[tasict]

Plugin Name

homebridge-roborock-vacuum

Link To GitHub Repo

homebridge-roborock-vacuum

Plugin Icon (Optional)

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

Thank you for reviewing this request. Some background on the plugin and how it
differs from existing verified plugins:

Relationship to existing verified plugins

While homebridge-xiaomi-roborock-vacuum (verified) also targets Roborock
vacuums, it works over the Xiaomi miIO protocol and requires the device to be
set up in the Xiaomi ecosystem. This plugin instead signs in with the user's
official Roborock app account and communicates through the Roborock cloud API
plus a direct local (LAN) connection to each vacuum. As a result it covers a
different and growing set of devices and features:

• Supports newer Roborock models that are only available in the Roborock app
  ecosystem and are not exposed via miIO
• Roborock scenes (created in the Roborock app) surfaced as HomeKit switches,
  automatically added/removed as scenes change
• Dock mop-wash control (start/stop) for models with a washing dock, with
  state kept in sync even when a wash is started from the Roborock app
• Optional Matter robotic-vacuum bridging (per device), including per-room
  cleaning through the ServiceArea cluster and clean-mode selection

Verification requirements

• Dynamic platform plugin, registered via the standard Homebridge API
• Configuration is done entirely in the Homebridge UI: config.schema.json plus
  a custom settings page (@homebridge/plugin-ui-utils) with an email/QR-code
  login flow — no token extraction, no TTY, no non-standard startup parameters
• If no platform config is present, the plugin does not start
• The Roborock cloud session token is encrypted at rest; the encryption key
  and session files are written inside the Homebridge storage directory with
  owner-only permissions
• No analytics or user tracking of any kind
• Runs on Node.js v22 and v24 (engines: ^18.20.4 || ^20.15.1 || ^22 || ^24)
• A GitHub release with release notes is published for every version, and
  GitHub issues are enabled for support

[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.1.1) matches NPM version (v2.1.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'
• 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/rsaKeys.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.1.1 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.

[tasict]

/check

[github-actions]

🔴 Failed Checks

Runtime Issues:

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

  {
    "platform": "RoborockVacuumPlatform",
    "name": "Roborock Vacuum",
    "email": "test@example.com",
    "password": "testpassword",
    "encryptedToken": "test-api-key-12345",
    "skipDevices": "test-value",
    "matterDevices": "test-value",
    "matterSceneDevices": "test-value",
    "baseURL": "https://usiot.roborock.com",
    "language": "en",
    "debugMode": false,
    "currentRoomMqtt": {
      "enabled": false,
      "brokerUrl": "mqtt://127.0.0.1:1883",
      "topic": "homebridge/roborock/{duid}/current_room",
      "cleaningPollSeconds": 10
    }
  }

  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 Vacuum",
    "email": "test@example.com",
    "password": "testpassword",
    "encryptedToken": "test-api-key-12345",
    "skipDevices": "test-value",
    "matterDevices": "test-value",
    "matterSceneDevices": "test-value",
    "baseURL": "https://usiot.roborock.com",
    "language": "en",
    "debugMode": false,
    "currentRoomMqtt": {
      "enabled": false,
      "brokerUrl": "mqtt://127.0.0.1:1883",
      "topic": "homebridge/roborock/{duid}/current_room",
      "cleaningPollSeconds": 10
    }
  }

  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.1.2) matches NPM version (v2.1.2)
• 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/rsaKeys.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.1.2 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.

[tasict]

Thanks for the automated review. The failed check has been fixed: v2.1.2 adds the standard name property to config.schema.json and is now published to NPM.

Regarding the items flagged for manual review — all four are false positives; here is the context:

• Accesses private keys in roborockLib/lib/rsaKeys.js: this file generates a fresh, process-local RSA-2048 keypair using Node's built-in crypto.generateKeyPair(). The Roborock photo-transfer protocol requires the client to present an RSA public key so the vacuum can encrypt photos to it. Nothing is read from disk and no user or system keys are ever accessed.
• Function constructor in dist/ui/index.js: this is new Function("specifier", "return import(specifier)") with a fully hard-coded body — the standard pattern for calling native dynamic import() from CommonJS output. It is needed because @homebridge/plugin-ui-utils v2 is ESM-only, and TypeScript would otherwise transpile a plain import() into require(). No user input is involved.
• Accesses environment files in roborockLib/roborockAPI.js: this is a plain process.env.HOMEBRIDGE_STORAGE_PATH read used to locate the Homebridge storage directory. No .env or other environment files are read.
• Dynamic require(): used only to load the bundled i18n catalogs (./i18n/<language>/translations.json). The language value is sanitized first — it must match /^[a-z]{2}(-[a-z]{2})?$/ and correspond to a catalog that ships inside the package — so only bundled translation files can ever be loaded.

[tasict]

/check