v2.3.0

⚠️ Upgrade notes

• For developers importing single files from dist/lib instead of the package itself: dist/lib/Service.js and dist/lib/Characteristic.js no longer attach the definitions (like Service.Lightbulb or Characteristic.On) when they are loaded on their own. Import from @homebridge/hap-nodejs as normal and nothing changes.
• Node.js 22 users need v22.12.0 or newer. Node.js 24 and 26 are unchanged. This is the first Node.js 22 release that can require() an ES module, and the upstream dbus-native package needs it too.
• HAP-NodeJS is now an ES module. Importing it works as before, including import hap from '@homebridge/hap-nodejs'. CommonJS code can still require('@homebridge/hap-nodejs'), on the Node.js versions above.

Changes

• fix: ignore state changes reported while a controller is being restored (#1133) (@seydx)
• perf: use the native crypto of Node.js for Curve25519 and Ed25519 (#1135) (@StefanRiese)
• chore: update hap characteristics and services
• chore(deps): dependency updates
• chore(deps): switch from the @homebridge/dbus-native fork back to upstream dbus-native
• fix: warn only once per address when a connection's local interface can't be found (#1131)
• fix(datastream): stop a stray unidentified frame from crashing the process
• fix(datastream): drop malformed frame payloads instead of crashing the process
• fix(datastream): destroy closed sockets when the remote never closes its side
• fix(camera): reject malformed SetupEndpoints writes before marking the stream busy
• fix(camera): answer SetupEndpoints with an error when the prepared stream response is invalid
• fix(camera): keep RTP proxy sockets open and only log errors after they are bound
• fix(datastream): decode binary data of up to 32 bytes instead of dropping it
• fix(datastream): make back-references follow the OPACK rule so reader and writer agree
• perf(datastream): stop allocating an unused buffer for every received frame
• fix(datastream): answer requests that have no handler instead of leaving them unanswered
• fix(remote): read target configurations from the Map they are stored in
• fix(remote): remove a whole target when the request lists no buttons
• fix(remote): don't crash when a delayed button release fails
• fix(remote): stop the Siri audio producer when the stream is refused
• fix(adaptive-lighting): forget the saved curve position when a new curve arrives
• fix(adaptive-lighting): keep Adaptive Lighting on when a control point request is rejected
• fix(color-utils): stop rounding the shared color temperature lookup table in place
• fix(adaptive-lighting): guard the curve maths against zero-length segments and NaN
• fix(check-name): accept names that are a single letter or number
• docs(uuid): say that unparse reads 16 bytes, not 8
• fix(accessory): unlink controller storage when a bridged accessory is removed
• fix(accessory): report slow and timed out handlers through the bridged accessory
• fix(accessory): track the primary service of a restored accessory
• fix(controller-storage): stop saving restored controller data again after it was cleared
• fix(accessory): drop client event registrations when a bridged accessory is removed
• fix(accessory): answer an Identify write of false instead of letting it time out
• fix(accessory): handle a paired identify without a set listener on the Identify characteristic
• fix(characteristic): reject instead of throwing when a legacy callback supplies an illegal value
• fix(characteristic): recompute the configuration number when setProps is called after publish
• refactor(accessory): share the read and write timeout handling and answer an empty write at once
• fix(server): answer a malformed request URL with 400 instead of crashing
• fix(server): only accept the proxy socket on the internal loopback HTTP server
• fix(server): wait for the whole HTTP response before writing event notifications
• fix(server): cap the size of request bodies, with a lower limit before pair-verify
• fix(crypto): keep a frame whose length header arrived split across two TCP packets
• fix(server): refuse pair-verify on a connection that is already verified
• fix(server): answer /pairings requests with an unexpected state or method
• fix(server): check idle connections again when the first one reaches the idle time
• fix(server): limit the timed write ttl, unref its timer and clear it when the connection closes
• fix(advertiser): warn about a system D-Bus connection error instead of crashing
• fix(tlv): reject a truncated entry in decodeWithLists instead of cutting it short
• fix(server): skip an event notification whose events were all unregistered
• fix(server): log the listener count from before the removal in HAPConnection.off()
• fix(accessory): compare a pairing's public key byte for byte instead of as text
• refactor: load the service and characteristic definitions without an import cycle
• test: migrate from jest to vitest
• chore(lint): switch to the @antfu/eslint-config rules used by homebridge
• chore: raise the minimum Node.js 22 version to 22.12.0
• feat: migrate the package to an ES module
• fix: stop a failed read or write throwing "HAPStatus is not defined" in the ES module build
• docs: regenerate docs for v2.3.0

Homebridge Dependencies

• @homebridge/ciao @ v1.4.0
• bonjour-hap @ v3.11.0

v2.2.3

Changes

• ci: rename the pr-labeler caller job from stale to label
• fix: stop one accessory's invalid permissions taking down the whole bridge (#1129)
• chore(deps): dependency updates

Homebridge Dependencies

• @homebridge/ciao @ v1.3.12
• @homebridge/dbus-native @ v0.7.9
• bonjour-hap @ v3.10.5

v2.2.2

Changes

• feat: log a debug line when the accessory configuration number increments
• fix: hash a canonical form of the configuration so array reordering cannot increment c#
• docs: regenerate docs for v2.2.2

Homebridge Dependencies

• @homebridge/ciao @ v1.3.12
• @homebridge/dbus-native @ v0.7.9
• bonjour-hap @ v3.10.5

v2.2.1

Changes

• refactor: drop the doubled advertiser check in the configuration-update debounce
• fix: close the exists-then-unlink gap when removing a storage key
• chore(deps): dependency updates
• docs: regenerate docs for v2.2.1

Homebridge Dependencies

• @homebridge/ciao @ v1.3.12
• @homebridge/dbus-native @ v0.7.9
• bonjour-hap @ v3.10.5

v2.2.0

⚠️ Goodbye node-persist

• The long-unmaintained node-persist dependency has been replaced with a minimal file storage (#1125, thanks @tim-fin).
• For users: no action needed.
  • The on-disk format is unchanged — existing pairings and accessory data are read exactly as before, nothing is migrated or rewritten
  • Writes are now atomic: an interrupted write (power loss, crash) can no longer leave behind a corrupted file that loses your pairings
  • HAP-NodeJS now also warns at startup if the storage directory is not writable, instead of failing with an obscure error later
• For developers using HAPStorage.storage() directly: the returned object now only implements the methods HAP-NodeJS itself uses — initSync, getItem, setItemSync and removeItemSync. Everything else from the old node-persist API now throws a clear error explaining this change. Also note:
  • initSync({ dir }) now requires an absolute path — node-persist silently redirected relative paths into node_modules, where the data was lost on the next install
  • Keys must be plain filenames — no slashes, no leading dot
• getItem(key, callback) (the legacy callback form) throws — use the plain getItem(key)
  • Full list of removed methods:

    • setOptions
    • init
    • key
    • keys
    • length
    • forEach
    • values
    • valuesWithKeyMatch
    • setItem
    • getItemSync
    • removeItem
    • clear[Sync]
    • persist[Sync]
    • persistKey[Sync]
    • removePersistedKey[Sync]
    • parseString
    • parseTTLDir[Sync]
    • parseDataDir[Sync]
    • parseDir[Sync]
    • parseDataFile[Sync]
    • parseTTLFile[Sync]
    • parseFile[Sync]
    • isExpired
    • resolveDir
    • stopInterval
    • log

Changes

• fix: replace node-persist with minimal in-repo file storage (#1125) (@tim-fin)
• Update for NodeJS 26 (@NorthernMan54)
• feat: warn when the persist directory is not writable, instead of failing obscurely at publish (#1028)
• chore(deps): dependency updates
• docs: regenerate docs for v2.2.0

Homebridge Dependencies

• @homebridge/ciao @ v1.3.10
• @homebridge/dbus-native @ v0.7.7
• bonjour-hap @ v3.10.4

v2.1.9

Changes

• fix: test harness rewritten around a connection-owning HAP client, removing the axios dependency (#1122) (@hjdhjd)
• chore(ci): bump actions/setup-node to v7
• chore: dependency updates
• docs: regenerate docs for v2.1.9

Homebridge Dependencies

• @homebridge/ciao @ v1.3.10
• @homebridge/dbus-native @ v0.7.7
• bonjour-hap @ v3.10.4

v2.1.8

Changes

• test: work around Node free-socket data guard in HAP HTTP client
• chore: dependency updates
• chore: update actions/checkout to v7
• chore: added deprecate-past-pre-releases workflow
• chore: update hap characteristics and services
• docs: regenerate docs for v2.1.8

Homebridge Dependencies

• @homebridge/ciao @ v1.3.10
• @homebridge/dbus-native @ v0.7.7
• bonjour-hap @ v3.10.4

v2.1.7

Changes

• chore: dependency updates
• chore: drop local @types shims, use upstream bonjour-hap types
• chore(ci): bump release workflow action versions
• test: cover encrypted data length validation in pair handlers
• test: cover required TLV field validation in pairing handlers
• test: cover RTP proxy setup rejection handling
• test: cover SEQUENCE_NUM presence check in pair handlers
• test: cover M1 reset prevention in pair-setup
• test: cover safe accessory lookups in slow/timeout warnings
• test: cover aid.iid format validation
• test: cover camera stream start TLV parsing guards
• test: cover error argument in pairing debug logs
• test: cover constant-time pincode comparison
• test: cover characteristic warning message for non-Error throws
• fix: improve HomeKit Name characteristic validation (#1119) (@n0rt0nthec4t)
• docs: regenerate docs for v2.1.7

v2.1.6

Changes

• fix: defer ControllerStorage construction until UUID is set
• chore: route HKSV diagnostics through HAP-NodeJS:HKSV namespace
• chore: dependency updates

Homebridge Dependencies

• @homebridge/ciao @ v1.3.8
• @homebridge/dbus-native @ v0.7.5
• bonjour-hap @ v3.10.2

v2.1.5

Changes

• fix: drop ConfiguredName HIG warning
• chore: dependency updates

Homebridge Dependencies

• @homebridge/ciao @ v1.3.8
• @homebridge/dbus-native @ v0.7.5
• bonjour-hap @ v3.10.2