API aesthetic updates (PR #142)

All,

I've produced another pull request in line with the last one, still from
reviewing as a Web API consumer. The PR is here:

https://github.com/w3c/webauthn/pull/142

These changes are also aesthetic, similar to PR #135, but in this case they
are all related to API aesthetics. They are still, for the most part,
editorial in nature. It'd be good to get some care in the review of the
`makeCredential()` updates per the removal of `ScopedCredentialParameters`,
though.

First, per Vijay's comment on issue 60[1], moving the interface from the
global window namespace to the navigator namespace to reduce pollution of
the global namespace. This also makes semantic sense, as the HTML5 `window`
object represents an open window in the browser, whereas the `navigator`
object represents the browser itself. Since authenticators belong to the
whole system, not one window, the object model makes more sense to be a
property attached to `navigator`.

Second, I've renamed the factory object from `navigator.webauthn` to
`navigator.authentication`. In general, web APIs shouldn't use the word
"web" in their name. It's implicit. (I considered "authn" but I feel the
verbosity here is justified -- most of the users will assign the object to
a local variable for ease of use anyway, like our example code does.)

Third, I changed the type of `ScopedCredentialInfo.publicKey` from `any` to
`CryptoKey`, referencing the WebCryptoAPI for the type information. This
feels like a fairly substantial change, but it really isn't: javascript
gets flexibility to ask for the pubkey in a variety of formats (including
JsonWebKey), and we get a tighter (and more expected) type.

Fourth, I've removed the `ScopedCredentialParameters` tuple by unpairing
the `type` and `algorithm` fields. `ScopedCredentialParameters` is used in
the procedure for normalizing algorithms and types, but said procedure
doesn't actually use the types! This changes the makeCredential() method to
instead have a list of supported types and a list of supported algorithms,
and perform its procedure that way.

Keeping these together in an object gives a kind of flexibility, but after
consideration, I don't see much actual purpose in said flexibility. A RP
can either handle an algorithm or not, and is either willing to handle an
authenticator type or not -- particular combinations seem an unnecessary
burden.

Fifth, in response to Vijay's note about extension names[2], I've renamed
the example extensions (correcting a CBOR mismatch in the process). I also
noted in section 7.1, Extension identifiers, that  "Use of dot-separated
notation here does not imply an object hierarchy.", and provided a
counterexample of a differently- separated, versioned id:
`mycompany-myextension_v01`. None of the pre-defined extensions were
modified.

As before, comments here or on the PR are both welcome.

1) https://github.com/w3c/webauthn/issues/60#issuecomment-230693738
2) https://lists.w3.org/Archives/Public /public- webauthn/2016Jul/0046.html

Cheers,
J.C.

Received on Monday, 11 July 2016 21:41:31 UTC