passwordless-lib/fido2-net-lib

Add Missing XML Comments for Public Members

joegoldman2 opened this issue · 4 comments

joegoldman2 commented

Currently, the codebase contains public members without corresponding XML comments (CS1591 warning). This issue is created to track and ensure the addition of proper documentation for these elements.

Regenhardt commented
  • PublicKeyCredentialRpEntity needs an actual description

I suggest mostly the one from the WebAuthn spec, even though it doesn't really include the possibility for a FIDO2 implementation in a native app:

[Represents an] entity whose web application utilizes the Web Authentication API to register and authenticate users

Brackets are my amendment.

Regenhardt commented
  • Fido2User needs a description

As the spec only has use case specific descriptions, I suggest something like this:

Represents a user account for usage with the WebAuthn API.

Regenhardt commented
  • AssertionOptions.Create has no description, but it's basically just a static method calling the constructor

This can be changed to just be a normal constructor. Either way this can get a simple description like:

Creates a new AssertionOptions object.

Regenhardt commented
  • AuthenticatorAssertionRawResponse is just a DTO generated by the browser, but I think the members do deserve descriptions

I can't find this in the spec, but I do like the MDN descriptions, even though they have to be adapted for our strict public-key use case.

Id

base64url encoding of RawId

That should be a <see... link to the RawId member.

RawId

Globally unique identifier for this credential. This identifier can be used to look up credentials.

Response

The signed response data from the authenticator.

Really unsure about this one since that could also be the description of the AssertionResponse type itself.

Type

Type of this credential. Always public-key.

ClientExtensionResults

If any extensions were requested, this contains the results of processing those extensions

I did find the AssertionResponse in the spec:

AssertionResponse.AuthenticatorData

Contains the authenticator data returned by the authenticator.

Although maybe that is a bit too redundant, so we could expand it slightly:

Contains the authenticator data returned by the authenticator, describing it to the relying party in order to make trust decisions.

AssertionResponse.Signature

Contains the raw signature returned from the authenticator.

Maybe with a link to https://www.w3.org/TR/webauthn-2/#sctn-op-get-assertion

AssertionResponse.ClientDataJson

Contains the JSON-compatible serialization of client data (see § 5.8.1 Client Data Used in WebAuthn Signatures (dictionary CollectedClientData)) passed to the authenticator by the client in order to generate this assertion. The exact JSON serialization MUST be preserved, as the hash of the serialized client data has been computed over it.

AssertionResponse.UserHandle

Contains the user handle returned from the authenticator, or null if the authenticator did not return a user handle.