Credential management for Z-Wave locks

[jlpouffier]

Problem statement

Right now, Home Assistant doesn't have an easy, built-in way to manage things like PINs and user codes for Z-Wave smart locks. This forces people to use third-party app (the vendor's app) instead of a smooth, native system, which makes the whole experience clunky and confusing for new users.

The idea of this bet is to build upon the Matter implementation proposed here #69

In scope

• CRUD (Create, Read, Update, Delete) actions for PINs and user codes.
• Credentials are tied to the lock itself, not to a Home Assistant user.
• Manage everything from the device page and show events in the device activity log.
• Allow codes to be enabled or disabled without having to delete them.

Out of scope

• Create and manage user profiles centrally in Home Assistant, similar to how Apple Home does it, and assign credentials to multiple devices from that profile.
• Link a credential such as a PIN or fingerprint directly to a Home Assistant user so it can be managed across devices.
• Features like scheduling and syncing codes across multiple devices are optional. For now, the focus is on the basics: core create, view, update, and delete actions, plus a device-centered experience.

Foreseen solution

• Same approach as taken for the Matter credentials in a first step Credential management for Matter locks #69
• Implementation split into
  • Support in zwave-js -> feat(cc): implement User Credential CC commands and API zwave-js/zwave-js#8629
  • Support in @zwave-js/server - N/A
  • Support in zwave-js-server-python - N/A
  • Support in HA zwave_js integration - N/A
  • Support in Frontend - N/A (take Matter lock manager home-assistant/frontend#28672 as a reference)
  • In addition to scope defined in 28672 we aim to incorporate support for showing the type of credentials stored, such as biometrics, RFID and NFC but exclude configuring or creating them in this first step.

Community signals

• Native lock code functionality home-assistant/architecture#1000
• [REQUEST] Add full Z-Wave lock management with ability to manage users for locks and their PIN codes via Z-Wave JS to replicate the new Matter lock manager in Home Assistant? zwave-js/zwave-js#8723
• https://github.com/orgs/home-assistant/discussions/2555

Risks & open questions

• Potential deviation from Matter credentials implementation
  • Z-Wave specifically allows multiple credentials of the same type per user/slot/...
• Aim remains to keep it as coherent as possible with user exposed functionality stemming from Matter lock manager home-assistant/frontend#28672

Appetite

• 3-4 weeks

Execution issues

No response

Decision log

Date	Decision	Outcome

[Hedda]

Please also consider creating duplicate roadmap issue for Zigbee lock manager via Home Assistant's ZHA integration) as well, see:

• [REQUEST] Add full Zigbee lock management with ability to manage users for locks and their PIN codes via ZHA to replicate the new Matter lock manager in Home Assistant? zigpy/zha#729

PS: For reference also check out these related discussions and feature requests:

• Leverage a more consistent credential management approach #8

• Native lock code functionality home-assistant/architecture#1000

• https://github.com/orgs/home-assistant/discussions/2555

• [REQUEST] Add full Z-Wave lock management with ability to manage users for locks and their PIN codes via Z-Wave JS to replicate the new Matter lock manager in Home Assistant? zwave-js/zwave-js#8723

[AlCalzone]

Question: Are fingerprints (and other biometric credentials) entirely out of scope, or just linking them to HA users?

[Hedda]

Question: Are fingerprints (and other biometric credentials) entirely out of scope, or just linking them to HA users?

I guess that a similar extended question could be asked about NFC-tags and RFID-tags for NFC-readers / RFID-readers (e.g. NFC/RFID Reader based on Z-Wave?) as both fingerprints and RFID/NFC tags are two-factor authentication (2FA). ? Example:

• https://z-wave.me/products/nfcreader/

ZWave-based products for use with an contactless RFID/NFC-tag (inluding Security cards and PayPass/PayWave or MIFARE) and matching RFID/NFC-reader are very commonly associated with access control panels for both arming/disarming your security alarm system and unlock door locks. Many smart locks and alarm control keypads also have a built-in NFC-reader, so the product does not have to be a standalone NFC-reader. Example the Alfred DB2S Smart Lock features both a built-in RFID reader and Z-Wave Long Range:

• https://z-wavealliance.org/member-news-alfred-international-launches-db2s-smart-lock-with-rfid-card-reader-and-z-wave-long-range-in-the-u-s/

Update: Note that most access control system products seems to be marketed as having "RFID" support or supporting ISO14443 tags (ISO/IEC 14443) instead of "NFC" even though 13.56MHz RFID appars to be the same as NFC.

• https://en.wikipedia.org/wiki/ISO/IEC_14443

Ussually for commercial setups those are almost always configured for two-factor authentication so that a user needs both their own personal NFC-tag in combination with a unique PIN-code programmed that, however for home use it is possible to configure them to only accept the NFC-tag without a PIN-code to unlock doorlocks, so the NFC-tag are in that use case practically used instead of a physical key but for a smart lock (that is at least how we setup an older Yale doorlock was when our kids was much younger to avoid both codes and keys).

PS: For reference, I think that might confuse some users though since non-ZWave NFC/RFID by themselves are already a first-class citizen in Home Assistant, but they is not really related for Z-Wave (nor for Matter or Zigbee) as the credential management is these use cases have the credentials tied to the lock or alarm control panel itself, not to a Home Assistant user as with "Home Assistant Tags" using an ESPHome-based NFC tag reader:

• https://www.home-assistant.io/integrations/tag/

  • https://www.home-assistant.io/blog/2020/09/15/home-assistant-tags/

[mkerstner]

Question: Are fingerprints (and other biometric credentials) entirely out of scope, or just linking them to HA users?

For now we would aim to establish the same foundation like we have for Matter locks.

If you think it made sense to already include fingerprints (and other biometric credentials) in this first step then please propose a path for that, keeping in mind that we aim to attach credentials to the device for now only, not the user.

[mkerstner]

So, we're aiming to support showing the credential type already in a first step. Added this to the description of the scoping above.

[mkerstner]

@AlCalzone Moved it to building fyi