Added guiding documentation to the new public initializers

Closes #74

Author: dimitribouniol

Sources/WebAuthn/Ceremonies/Authentication/PublicKeyCredentialRequestOptions.swift

@@ -19,7 +19,7 @@ import Foundation
 ///
 /// - SeeAlso: https://www.w3.org/TR/webauthn-2/#dictionary-assertion-options
 public struct PublicKeyCredentialRequestOptions: Sendable {
-    /// A challenge that the authenticator signs, along with other data, when producing an authentication assertion
+    /// A challenge that the authenticator signs, along with other data, when producing an authentication assertion.
     ///
     /// When encoding using `Encodable` this is encoded as base64url.
     public var challenge: [UInt8]
@@ -45,6 +45,16 @@ public struct PublicKeyCredentialRequestOptions: Sendable {
 
     // let extensions: [String: Any]
 
+    /// Initialize a credential request options dictionary directly.
+    ///
+    /// - Warning: Manually initializing options dictionaries can easily lead to insecure implementations of the WebAuthn protocol. Whenever possible, create an options dictionary using ``WebAuthnManager/beginAuthentication(timeout:allowCredentials:userVerification:)`` instead.
+    ///
+    /// - Parameters:
+    ///   - challenge: A challenge that the authenticator signs, along with other data, when producing an authentication assertion.
+    ///   - timeout: A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a hint, and may be overridden by the client.
+    ///   - relyingPartyID: The ID of the Relying Party making the request.
+    ///   - allowCredentials: Optionally used by the client to find authenticators eligible for this authentication ceremony.
+    ///   - userVerification: Specifies whether the user should be verified during the authentication ceremony.
     public init(
         challenge: [UInt8],
         timeout: Duration?,

Sources/WebAuthn/Ceremonies/Registration/PublicKeyCredentialCreationOptions.swift

@@ -27,26 +27,34 @@ public struct PublicKeyCredentialCreationOptions: Sendable {
     /// encoding using `Encodable`, the challenge is base64url encoded.
     public let challenge: [UInt8]
 
-    /// Contains names and an identifier for the user account performing the registration
+    /// Contains names and an identifier for the user account performing the registration.
     public var user: PublicKeyCredentialUserEntity
 
-    /// Contains a name and an identifier for the Relying Party responsible for the request
+    /// Contains a name and an identifier for the Relying Party responsible for the request.
     public var relyingParty: PublicKeyCredentialRelyingPartyEntity
 
-    /// A list of key types and signature algorithms the Relying Party supports. Ordered from most preferred to least
-    /// preferred.
+    /// A list of key types and signature algorithms the Relying Party supports. Ordered from most preferred to least preferred.
     public var publicKeyCredentialParameters: [PublicKeyCredentialParameters]
 
-    /// A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a
-    /// hint, and may be overridden by the client.
+    /// A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a hint, and may be overridden by the client.
     ///
     /// - Note: When encoded, this value is represented in milleseconds as a ``UInt32``.
     public var timeout: Duration?
 
-    /// Sets the Relying Party's preference for attestation conveyance. At the time of writing only `none` is
-    /// supported.
+    /// Sets the Relying Party's preference for attestation conveyance. At the time of writing only ``AttestationConveyancePreference/none`` is supported.
     public var attestation: AttestationConveyancePreference
 
+    /// Initialize a credential creation options dictionary directly.
+    ///
+    /// - Warning: Manually initializing options dictionaries can easily lead to insecure implementations of the WebAuthn protocol. Whenever possible, create an options dictionary using ``WebAuthnManager/beginRegistration(user:timeout:attestation:publicKeyCredentialParameters:)`` instead.
+    ///
+    /// - Parameters:
+    ///   - challenge: A byte array randomly generated by the Relying Party. Should be at least 16 bytes long to ensure sufficient entropy.
+    ///   - user: Contains names and an identifier for the user account performing the registration.
+    ///   - relyingParty: Contains a name and an identifier for the Relying Party responsible for the request.
+    ///   - publicKeyCredentialParameters: A list of key types and signature algorithms the Relying Party supports. Ordered from most preferred to least preferred.
+    ///   - timeout: A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a hint, and may be overridden by the client.
+    ///   - attestation: Sets the Relying Party's preference for attestation conveyance. At the time of writing only `none` is supported.
     public init(
         challenge: [UInt8],
         user: PublicKeyCredentialUserEntity,

Sources/WebAuthn/WebAuthnManager.swift

@@ -46,7 +46,10 @@ public struct WebAuthnManager: Sendable {
 
     /// Generate a new set of registration data to be sent to the client.
     ///
-    /// This method will use the Relying Party information from the WebAuthnManager's configuration  to create ``PublicKeyCredentialCreationOptions``
+    /// This method will use the Relying Party information from the WebAuthnManager's configuration  to create a ready-to-consume ``PublicKeyCredentialCreationOptions`` on the client.
+    ///
+    /// - Important: You must store the ``PublicKeyCredentialCreationOptions/challenge`` value returned by this method and validate against it during the ``finishRegistration(challenge:credentialCreationData:requireUserVerification:supportedPublicKeyAlgorithms:pemRootCertificatesByFormat:confirmCredentialIDNotRegisteredYet:)`` phase of registration.
+    ///
     /// - Parameters:
     ///   - user: The user to register.
     ///   - timeout: How long the browser should give the user to choose an authenticator. This value
@@ -126,7 +129,9 @@ public struct WebAuthnManager: Sendable {
         )
     }
 
-    /// Generate options for retrieving a credential via navigator.credentials.get()
+    /// Generate options for retrieving a credential via `navigator.credentials.get()`.
+    ///
+    /// - Important: You must store the ``PublicKeyCredentialRequestOptions/challenge`` value returned by this method and validate against it during the ``finishAuthentication(credential:expectedChallenge:credentialPublicKey:credentialCurrentSignCount:requireUserVerification:)`` phase of authentication.
     ///
     /// - Parameters:
     ///   - timeout: How long the browser should give the user to choose an authenticator. This value