[Spec] Add output enum for isSecurePaymentConfirmationAvailable and rename API

[stephenmcgruer]

Fixes #284

---

Preview | Diff

[stephenmcgruer]

@rsolomakhin @ianbjacobs - PTAL

cc @pejic

[ianbjacobs]

@stephenmcgruer,

Thanks for this pull request. Some questions:

• What is the relationship between unavailable-no-user-verifying-platform-authenticator and isUserVerifyingPlatformAuthenticatorAvailable() ? Could the latter be called outside of SPC (and thus moot the need for the SPC value)?

• I think the text should explain why there is an enum. At a high level this is meant to help developers without leaking additional information. But what's not clear from the text is the developer needs or use cases driving the move to the enum.

[stephenmcgruer]

Thanks Ian! I'll address your latter bullet shortly, but for the first:

What is the relationship between unavailable-no-user-verifying-platform-authenticator and isUserVerifyingPlatformAuthenticatorAvailable() ? Could the latter be called outside of SPC (and thus moot the need for the SPC value)?

They are identical, but it doesn't feel like it makes sense to me to have spcAvailability == 'available' but then you also have to check isUserVerifyingPlatformAuthenticatorAvailable() and if that returns false SPC will still not work?

Getting into the weeds, I could even see it making more sense to return a set of not-available reasons, since technically you could have SPC not working for multiple reasons. But at some point we start getting into silly territory, when we started with a simple true/false boolean!

[ianbjacobs]

They are identical, but it doesn't feel like it makes sense to me to have spcAvailability == 'available' but then you also have to check isUserVerifyingPlatformAuthenticatorAvailable() and if that returns false SPC will still not work?

I suggest simply calling out the relationship to avoid questions.

[stephenmcgruer]

Ack Ian, sounds good and I'll address that and re-ping.

cc @domenic also, just because I'm curious as to whether you have any "best practice" thoughts on this sort of API. A few things I'm only musing now (whoops; we live and we learn 🤦 ): (1) should it be a set of reasons?, (2) if not, should the spec be explicit about the ordering of priority (e.g., if feature is not enabled return that, else if permission policy not set return that, else if ... ), and (3) should this be called getSecurePaymentConfirmationAvailability() instead of just securePaymentConfirmationAvailability...

EDIT: Edited to add (3)

[domenic]

Easy answers first...

2. if not, should the spec be explicit about the ordering of priority (e.g., if feature is not enabled return that, else if permission policy not set return that, else if ... )

The spec should indeed be explicit about the ordering. Ideally, this would even be true if you did a set of reasons! Since it's possible to imagine web developers doing something like if (reasonSet[0] === "some-reason") { ... } and that code working in only one browser.

(An easy way to order sets is by sorting them, though.)

(3) should this be called getSecurePaymentConfirmationAvailability() instead of just securePaymentConfirmationAvailability...

I like omitting the get prefix, personally.

---

Harder question:

(1) should it be a set of reasons?

This seems like it depends on your use case. What code do you expect developers to write? Is this for reporting to the server, so that they can aggregate all the failures and get insight into statistical patterns? If so, a set is often useful. An example is bfcache blocking reasons.

Or is this for runtime determination of what UI to show? If so, it's a bit harder to imagine how listing all the reasons would help. (But maybe it would; I'm not the domain expert!)