Support random setup codes and saved verifiers

[samuelthomas2774]

Adds support for generating random setup codes if one isn't provided, and providing a salt+verifier instead of a setup code, and adds events for pair setup requests to present the setup code to the user. This also rejects pair setup requests if another client is pairing.

import {AccessoryEventTypes, Categories} from 'hap-nodejs';

const bridge = new Bridge('Node Bridge', uuid.generate('Node Bridge'));

bridge.publish({
    username: 'CC:22:3D:E3:CE:30',
    port: 51826,
    category: Categories.BRIDGE,
});

bridge.on(AccessoryEventTypes.PAIR_SETUP_STARTED, (setupcode: string, setupuri: string, session: Session) => {
    // Present the setup code to the user
    // If we had some web interface here we could send a message to it to show the setup code and a QR code with the setup URI
    // Or if we just want to print the code here like this we don't need to listen to the event and could let HAP-NodeJS handle it
    console.log('[%s] Received pair request', bridge.displayName, setupcode, setupuri);
});

bridge.on(AccessoryEventTypes.PAIR_SETUP_FINISHED, (err: Error | null, clientUsername: string | null, session: Session) => {
    // Here we don't have to do anything
    // If we had some web interface here we could send a message to it to hide the setup code/QR code
});

import {AccessoryEventTypes, Categories} from 'hap-nodejs';

const bridge = new Bridge('Node Bridge', uuid.generate('Node Bridge'));

bridge.publish({
    username: 'CC:22:3D:E3:CE:30',
    pincode: {
        // Setup code 809-78-006
        // Generate these using `node dist/scripts/generate-verifier.js`
        salt: Buffer.from('c9196c167e53782a8e3f3f15c5579366', 'hex'),
        verifier: Buffer.from('716c3f88d40f26451ded933f84b0b92dd8b0645b4aad3434dd3deddde91a6d99a12e2ea9c63e5f73a85bdbd7b3bd5322394e53708d3f4b6490b3bc9da268a82694315da7ac7fe0bb62dc9c13d325ee4498b752a68c9a4acd50ce5087abee81a409297e43ccd78d80313ab39019a7ab85b86d45f08a4b4acb834c921cfd247814413886acf5886b321ccd8a7d1680000e4d544d29a23ae3f95962923b4204419b6f14451759ac2840db287c345ca59c54f2a8db28bb98bde430f8218c1bc48e88cc28c422c43e7bde973a977ce6297a05d2f52ec72af428b6e36a8e3dd227be8aeab5e1ee9a3d44f624eb6b6ab1b377e9f75310f851873b0a7d7da52defe4ae4b3cbb474b84828207eab9caf6372de6a2beeba3b98ff629835a4c7988b4c1e51ed657154d6220a38a5d1eb6ce19a5f4e9f6ff8f52f384d45efe1f0ac864d8a3f0b4a9f0d8ba51e59bbb6467f8b35ace45845e94471fa5d09c161161c2bff9054f389f63f133ab7731a360b9872ffbd9908840ff66272345807fd02f0f3e12d4c8', 'hex'),
    },
    port: 51826,
    category: Categories.BRIDGE,
});

[codyc1515]

Does this generate a new setup code on every pairing request?

[samuelthomas2774]

In my example and the updated Core.ts, yes. The function passed to Accessory.publish is called on every pairing request but could provide the same setup code.

[codyc1515]

Ah, okay. That is the correct way to do it. Looks good :)

[Supereg]

Thanks a lot, great PR.
Regarding the API, either you must supply a predefined pincode or you supply a function which needs to generate a random pincode and supply it to the callback. Do I have this right?

If I may propose some modifications:
Since the generation of a new pincode is pretty much always the same, and I think the best implementation is already supplied with your util file, wouldn't it be nicer if the user just flips a boolean to true to indicate that they want random pincodes? Then for every pair request, a random pincode is generated automatically, and also potential error handling is done automatically (currently we need to trust the user that they forward the error to the callback).
And additionally the user has the opportunity to subscribe to an dedicated event on the accessory, whose event handler is called with the generated pincode in order to display the code to the user (and maybe the setupURI to display QR code. I don't really know how HomeKit handles that, and if there is still the opportunity to scan an QR code uri). If there is no listener HAP-NodeJS could maybe print the code to the console.

[samuelthomas2774]

Regarding the API, either you must supply a predefined pincode or you supply a function which needs to generate a random pincode and supply it to the callback. Do I have this right?

Yes.

Since the generation of a new pincode is pretty much always the same, and I think the best implementation is already supplied with your util file, wouldn't it be nicer if the user just flips a boolean to true to indicate that they want random pincodes? Then for every pair request, a random pincode is generated automatically, and also potential error handling is done automatically (currently we need to trust the user that they forward the error to the callback).

That's what I did for Core.ts - if there isn't a pincode property set on the accessory object then a random one is used instead.

And additionally the user has the opportunity to subscribe to an dedicated event on the accessory, whose event handler is called with the generated pincode in order to display the code to the user. If there is no listener HAP-NodeJS could maybe print the code to the console.

The reason I haven't set a default in Accessory.publish is because - unless the user is using Core.ts - we don't know how the setup code/QR code should be displayed. For example, with a web interface for Homebridge a panel somewhere showing the setup code after a pair request has started would be better as the user might not have immediate access to the server output.

I don't really know how HomeKit handles that, and if there is still the opportunity to scan an QR code uri

There's a button to use the camera to scan the setup code/QR code on the setup code entry page. IMG_3345

---

If the helper function to generate a setup code is used by default I'm happy to just emit an event on the Accessory object when a pair request starts/finishes instead as you suggested. That would give us an API like this:

import {AccessoryEventTypes, Categories, generateSetupCode} from 'hap-nodejs';

bridge.publish({
    username: 'CC:22:3D:E3:CE:30',
    port: 51826,
    category: Categories.BRIDGE,
});

bridge.on(AccessoryEventTypes.PAIR_SETUP_STARTED, (setupcode: string, setupuri: string, session: Session) => {
    // Present the setup code to the user
    // If we had some web interface here we could send a message to it to show the setup code and a QR code with the setup URI
    // Or if we just want to print the code here like this we don't need to listen to the event and could let HAP-NodeJS handle it
    console.log('[%s] Received pair request', bridge.displayName, setupcode, setupuri);
});

bridge.on(AccessoryEventTypes.PAIR_SETUP_FINISHED, (err: Error | null, clientUsername: string | null, session: Session) => {
    // Here we don't have to do anything
    // If we had some web interface here we could send a message to it to hide the setup code/QR code
});

[samuelthomas2774]

From f5e303f if a setup code (or a function to generate one) isn't provided then one is generated and either emitted on the Accessory (as in the second example) or printed to the console.

[samuelthomas2774]

I've updated this to merge in the current master branch, and added support for using saved verifiers.

[Supereg]

Would you mind rebasing the PR onto the beta branch? Some major code changes/cleanups were made.
Otherwise I can adapt the PR myself.

Thanks for keeping up with the PR

[samuelthomas2774]

Would you mind rebasing the PR onto the beta branch?

@Supereg I've switched this to the beta branch now.

[Supereg]

Thanks already. I'll check if I have the time to still include that into the latest beta release.
But currently I'm more on the side of ensuring the current beta gets to stable and we can finally ship ciao.

[Supereg]

I'm currently in the process of getting this PR merged.
I'm aiming to rebase this PR onto the latest beta ref and maybe doing some minor changes.
Would you mind enabling the Allow edits from maintainers option on the right, so that I can push those changes into your branch? Otherwise I would need to do those changes outside of this PR. @samuelthomas2774

[samuelthomas2774]

@Supereg I've rebased to the current beta branch and enabled maintainer edits so you can add any changes.

[Supereg]

I have the desire to still change some stuff here and there.
For one, I need to rethink if it makes sense to multiplex string-based pincode, password generating function and SRP verifier into the PublishInfo.pincode property (additionally even a fourth option to leave out that option, for automatically generating passwords).
I will probably refactor the script generating SRP verifiers, for one backing it with a more profound command line parsing, as well as maybe even packaging it as a bin with the hap-nodejs package, such that users can follow a similar "provisioning" workflow like it is the case for the HomeKitADK.
In the end, the goal would even be to move to a SRP verifier based pincode storage for all hap-nodejs and homebridge installations by default.
This probably needs some thoughts around how users running the beta can still properly downgrade (maybe it makes sense to back port the updated AccessoryInfo model to the 0.8.x line).

I also had planned to do some code cleanup to the current pairing logic, maybe moving it out of the HAPServer even. I think (checking against the ADK code) it makes sense to add a pairing timeout (now it is enforced that only a single session is in a pairing session) so that no client can use that as a denial of service.

EDIT: Additionally what this PR is missing, that transient pairings aren't actually allowed to control anything, they really are only allowed to access the \identify route and the secure-message root for software authentication. I already mentioned in #643 that I maybe plan do abuse the transient pairing mechanism to replace the current insecure mode with a new insecure mode providing a secure, encrypted and authenticated way of operating hap-nodejs/homebridge instances from third party software.

EDIT2: We should also definitely find a way to properly and throughly unit test the pairing code.

I still plan to do those changes, though I decided that I don't want to include all that in this PR anymore, I think it makes sense to finally get this merged.
Huge thanks for your contribution 🙏🏽

Quick question to the current split pair-setup. To my knowledge the SRP verifier should be saved for the next pair-setup. Do you know if that verifier should be saved on a global level (and forever?) like you do currently or should this SRP verifier be associated with the HAPConnection (and thus also only live as long as the connection does). The current solution e.g. doesn't allow for multiple connections saving their own verifier?

[samuelthomas2774]

I have the desire to still change some stuff here and there.
For one, I need to rethink if it makes sense to multiplex string-based pincode, password generating function and SRP verifier into the PublishInfo.pincode property (additionally even a fourth option to leave out that option, for automatically generating passwords).
I will probably refactor the script generating SRP verifiers, for one backing it with a more profound command line parsing, as well as maybe even packaging it as a bin with the hap-nodejs package, such that users can follow a similar "provisioning" workflow like it is the case for the HomeKitADK.
In the end, the goal would even be to move to a SRP verifier based pincode storage for all hap-nodejs and homebridge installations by default.
This probably needs some thoughts around how users running the beta can still properly downgrade (maybe it makes sense to back port the updated AccessoryInfo model to the 0.8.x line).

I also had planned to do some code cleanup to the current pairing logic, maybe moving it out of the HAPServer even. I think (checking against the ADK code) it makes sense to add a pairing timeout (now it is enforced that only a single session is in a pairing session) so that no client can use that as a denial of service.

All sound good. The script I included is really just meant as an example of using the generation functions and for generating setup codes for testing; a proper command line tool for this would be great for automatically generating accessories. For users downgrading: the AccessoryInfo.pincode property is always overwritten by Accessory.publish, so it shouldn't really matter what is saved (though I haven't tested that).

EDIT: Additionally what this PR is missing, that transient pairings aren't actually allowed to control anything, they really are only allowed to access the \identify route and the secure-message root for software authentication. I already mentioned in #643 that I maybe plan do abuse the transient pairing mechanism to replace the current insecure mode with a new insecure mode providing a secure, encrypted and authenticated way of operating hap-nodejs/homebridge instances from third party software.

I remember reading your comments there. The transient pairing mode doesn't really have any use at the moment but it made sense to me to implement it in this PR as it's really just properly implementing the pair-setup modes, and then leave any actual use for it to be added separately. I am certainly all for a better way of accessing the HAP server from third-party software, as encouraging users to enable an "insecure mode" for normal operation of certain Homebridge plugins is really a bad idea.

(As well as handling instances where there is no setup code as introduced by this PR...) Something maybe for @oznu to consider is that homebridge-config-ui-x allows controlling other Homebridge servers - any secure replacement would require the user to configure this (although in my opinion this should be manually enabled for each HAP server).

Also how this would work with child bridges/external accessories in Homebridge, as from hap-nodejs' perspective they are completely separate HAP servers.

EDIT2: We should also definitely find a way to properly and throughly unit test the pairing code.

I still plan to do those changes, though I decided that I don't want to include all that in this PR anymore, I think it makes sense to finally get this merged.
Huge thanks for your contribution 🙏🏽

Thank you! I'm very happy this has finally been merged.

Quick question to the current split pair-setup. To my knowledge the SRP verifier should be saved for the next pair-setup. Do you know if that verifier should be saved on a global level (and forever?) like you do currently or should this SRP verifier be associated with the HAPConnection (and thus also only live as long as the connection does). The current solution e.g. doesn't allow for multiple connections saving their own verifier?

The HAP spec. just says "save the SRP verifier for the Setup Code and use it for the next Pair-Setup with kPairingFlag_Split" (nothing about who for or if it should expire). I think the issue with saving the verifier per-connection is that the client could disconnect between the pair attempts, and I guess multiple connections saving their own verifier would already be disallowed anyway as only one can be attempting a pair-setup at a time.