Verification Request: homebridge-mqttthing-ex

[tasict]

Plugin Name

homebridge-mqttthing-ex

Link To GitHub Repo

https://github.com/tasict/homebridge-mqttthing-ex

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

Relationship to homebridge-mqttthing

I want to be upfront about this rather than let the review discover it: this
plugin covers the same problem domain as
homebridge-mqttthing
by David Miller, and it began as a re-implementation of that plugin's
configuration format.

That plugin has been the reference MQTT plugin for Homebridge for years and I
have a great deal of respect for it — this project exists because of it, not
in spite of it. Its most recent npm release is 1.1.49 (January 2026) and its
engines.node range does not yet cover Node 24. Working through the Homebridge
2.0 transition I ran into API-surface issues I could not resolve inside the
existing CommonJS codebase without effectively rewriting it, and upstream has
been quiet for a while. Rather than maintain a divergent fork, I rewrote the
plugin from the ground up in TypeScript / ESM against the modern HAP APIs
(onGet / onSet), with a 327-test suite and CI on Node 20, 22 and 24.
Upstream attribution is in
NOTICE;
the licence is Apache-2.0.

As far as I can tell homebridge-mqttthing is not on the current
verified-plugins.json list, so I don't believe this request displaces a
verified plugin. The verified plugins in adjacent territory
(homebridge-easy-mqtt, homebridge-mqtt-tasmota, homebridge-mqttsmokesensor
and similar) are deliberately narrow — a single device family or a small set of
service types. This plugin is a general MQTT ↔ HomeKit bridge covering roughly
50 accessory types, so I don't believe it duplicates or reduces any of them.

A design decision the review should know about

The plugin registers the accessory alias mqttthing — the same alias upstream
uses. This is deliberate: it lets an existing user migrate by uninstalling the
old plugin, installing this one and restarting, with no config.json changes
and no HomeKit re-pairing, because Homebridge derives the accessory UUID from
the alias plus the configured name. Minimising migration friction for existing
users was the primary design goal.

The trade-off is that the two plugins cannot be installed side by side. This is
handled gracefully rather than by crashing: registration is wrapped in
try/catch and logs an actionable message naming the conflicting plugin
(src/index.ts),
and the behaviour is documented in the README migration section. If the
Homebridge team would prefer the aliases not to collide, I'm happy to rename and
ship a migration path instead — please just say so.

Functionality beyond a like-for-like rewrite

• Platform mode — one config block with a devices[] array, sharing one
  MQTT connection per broker instead of one per accessory (a 40-device setup
  goes from 40 sockets, keepalive timers and broker-side sessions to 1). Devices
  carry a stable id, so renaming is no longer destructive, and cached platform
  accessories keep their HomeKit place (room, scenes, automations) while a
  misconfiguration is fixed. Moving a device into platform mode preserves its
  existing UUID, so this too needs no re-pairing.
• Custom configuration UI (@homebridge/plugin-ui-utils) — searchable
  accessory list built for setups with dozens of devices, a type-aware editor
  with a topic table, editing of apply expressions and of the custom
  multi-service type (which a plain schema form cannot represent), live MQTT
  connection testing and topic probing.
• Outbound publish queue with per-topic coalescing and throttling, so
  HomeKit scene bursts and slider drags cannot overwhelm low-power IoT devices.
• Upstream bugs fixed — spurious colour publishes at start-up, adaptive
  lighting switching lights on, temperature clamping of sensor readings,
  wildcard subscriptions, null-payload crashes, history crashes with multiple
  services. Full list with upstream issue references:
  docs/UpstreamIssues.md.
• Backwards compatible with existing CommonJS codec files and
  { "topic": …, "apply": … } expressions.

Development continues in step with Homebridge releases; further capabilities
will follow as the platform gains them.

Requirement notes

• Dynamic platform — MqttThingPlatform implements DynamicPlatformPlugin
  and is registered with api.registerPlatform(); config.schema.json declares
  "pluginType": "platform". The legacy mqttthing accessory registration is
  retained purely so existing config.json files keep working during migration.
• Does not start unless configured — neither the platform nor the accessory
  is instantiated by Homebridge without a matching config block, and there is no
  ambient work at module load.
• Files on disk — the only writes are the fakegato-history counter files,
  under api.user.storagePath()
  (src/features/history.ts).
  The custom UI server reads codecs from, and writes config.json within, the
  Homebridge storage directory only.
• No analytics — there are no outbound HTTP calls of any kind; the only
  network I/O is to the user's configured MQTT broker.
• No post-install scripts — package.json declares no
  preinstall/postinstall.
• Releases — every npm version has a matching GitHub release with notes;
  publishing runs from a release-triggered workflow with npm provenance.

[github-actions]

🔴 Failed Checks

• Package JSON: keywords must include at least one of 'supports-hap' or 'supports-matter' — see Declaring Supported Transports
• Config Schema JSON: schema is invalid - required should not be a boolean property on individual fields. In JSON Schema, required must be an array at the object level listing required property names. Remove "required": true/false from individual properties and use "required": ["property1", "property2"] at the object level instead.
• Config Schema JSON: the pluginType is not set to 'platform'

🟢 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.2.1
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v1.1.0) matches NPM version (v1.1.0)
• Config Schema JSON: exists and is valid JSON
• Config Schema JSON: contains a valid pluginAlias
• Config Schema JSON: pluginAlias matches the platform/accessory registered in code
• 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 critical vulnerabilities (9 high, 0 moderate, 0 low)
• 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: found 9 high-severity vulnerabilities in dependencies (manual review recommended)
• Security: accesses environment files in dist/mqtt/client.js, dist/platform.js
• Security: uses dynamic require() which could load arbitrary code found in 1 file

ℹ️ Check Details

• These checks were run against v1.1.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.

[tasict]

/check

[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: keywords declare the supported transports ('supports-hap' and/or 'supports-matter')
• 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.2.1
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v1.2.1) matches NPM version (v1.2.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 critical vulnerabilities (9 high, 0 moderate, 0 low)
• 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: 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: found 9 high-severity vulnerabilities in dependencies (manual review recommended)
• Security: accesses environment files in dist/mqtt/client.js, dist/platform.js
• Security: uses dynamic require() which could load arbitrary code found in 1 file

ℹ️ Check Details

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

📋 Next Steps

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

[tasict]

Thanks — glad the automated checks are green. Notes on the three manual-review
items, in case they save the reviewer some time.

Security: 9 high-severity vulnerabilities in dependencies

All are transitive denial-of-service advisories from two roots, and I have
measured rather than assumed the following:

fakegato-history@0.6.7 → googleapis (6 of the 9). fakegato-history
hard-depends on googleapis for its optional Google Drive storage backend.
This plugin only ever configures storage: 'fs'
(src/features/history.ts),
so that backend is never instantiated and the advisories
(gaxios, googleapis-common, rimraf, glob, minimatch,
brace-expansion) are not reachable at runtime. The chain bottoms out at
brace-expansion, which is patched in 5.0.8 — but minimatch caps it at
^2.x, so no version resolution can reach the fix.

jsonpath@1.3.0 → underscore (2 of the 9). jsonpath evaluates JSONPath
expressions that the user writes in their own configuration, against payloads
from their own MQTT broker. underscore is patched in 1.13.8, but jsonpath
pins underscore: 1.13.6 exactly rather than as a range, so again nothing
resolves to the fix. jsonpath has been unmaintained for some time.

An overrides block would not help either: npm applies overrides only at the
root of an install tree, so it is ignored inside a published dependency. I
confirmed this by packing a build with overrides set and auditing it as a
consumer — unchanged.

Both roots are on my list to replace. jsonpath is used in exactly one place
and is the easier of the two, but both back features inherited from
homebridge-mqttthing, so I would rather change them deliberately than as a
rushed edit during review. Happy to prioritise either if the team would prefer
it done before verification.

Security: accesses environment files in dist/mqtt/client.js, dist/platform.js

I believe this is a false positive — no file is read. These are three
process.env lookups used as broker-setting fallbacks: MQTTTHING_URL,
MQTTTHING_USERNAME and MQTTTHING_PASSWORD. They exist for compatibility with
homebridge-mqttthing, which supports the same variables so broker credentials
can be kept out of config.json. Nothing is written, and no .env file is read
or parsed.

Security: uses dynamic require() which could load arbitrary code

Two call sites, both intentional:

• src/codec/loader.ts
  loads a user codec — the documented "codec": "myCodec.js" feature
  inherited from homebridge-mqttthing, which lets a user supply a JavaScript
  file to encode/decode MQTT messages for a non-standard device. The path
  resolves either to the plugin's own bundled codecs/ directory or to a path
  inside the Homebridge storage directory. Nothing is fetched, and the user is
  loading their own file by their own explicit configuration.
• src/settings.ts
  requires the plugin's own package.json to report its version in the
  accessory information service. Constant path.

Happy to answer anything else.

[tasict]

/check