Added start of WebAuthn client registration implementation

Author: dimitribouniol

Sources/WebAuthn/Authenticators/KeyPairAuthenticator.swift

@@ -22,6 +22,11 @@ public struct KeyPairAuthenticator: AuthenticatorProtocol, Sendable {
     public let canPerformUserVerification: Bool = true
     public let canStoreCredentialSourceClientSide: Bool = true
 
+    /// The specific subset the client fully supports, in case more are added over time.
+    static let implementedPublicKeyCredentialParameterSubset: Set<PublicKeyCredentialParameters> = [
+        PublicKeyCredentialParameters(alg: .algES256),
+    ]
+    
     /// Initialize a key-pair based authenticator with a globally unique ID representing your application.
     /// - Note: To generate an AAGUID, run `% uuidgen` in your terminal. This value should generally not change across installations or versions of your app, and should be the same for every user.
     /// - Parameter attestationGloballyUniqueID: The AAGUID associated with the authenticator.
@@ -34,7 +39,7 @@ public struct KeyPairAuthenticator: AuthenticatorProtocol, Sendable {
     ) {
         self.attestationGloballyUniqueID = attestationGloballyUniqueID
         self.attachmentModality = attachmentModality
-        self.supportedPublicKeyCredentialParameters = supportedPublicKeyCredentialParameters
+        self.supportedPublicKeyCredentialParameters = supportedPublicKeyCredentialParameters.intersection(Self.implementedPublicKeyCredentialParameterSubset)
     }
 
     public func generateCredentialSource(

Sources/WebAuthn/Authenticators/Protocol/AuthenticatorProtocol.swift

@@ -124,6 +124,9 @@ extension AuthenticatorProtocol {
     public func makeCredentials(
         with registration: AttestationRegistrationRequest
     ) async throws -> CredentialSource {
+        guard let chosenCredentialParameters = registration.publicKeyCredentialParameters.first(where: supportedPublicKeyCredentialParameters.contains(_:))
+        else { throw WebAuthnError.noSupportedCredentialParameters }
+        
         throw WebAuthnError.unsupported
     }
 }

Sources/WebAuthn/WebAuthnClient.swift

@@ -0,0 +1,235 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the WebAuthn Swift open source project
+//
+// Copyright (c) 2024 the WebAuthn Swift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of WebAuthn Swift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import Crypto
+
+/// A client implementation capable of interfacing between an ``AuthenticatorProtocol`` authenticator and the Web Authentication API.
+///
+/// - Important: Unless you specifically need to implement a custom WebAuthn client, it is vastly preferable to reach for the built-in [AuthenticationServices](https://developer.apple.com/documentation/authenticationservices) framework instead, which provides out-of-the-box support for a user's [Passkey](https://developer.apple.com/documentation/authenticationservices/public-private_key_authentication/supporting_passkeys). However, this is not always possible or preferrable to use this credential, especially when you want to implement silent account creation, and wish to build it off of WebAuthn. For those cases, `WebAuthnClient` is available.
+///
+/// Registration: To create a registration credential, first ask the relying party (aka the server) for ``PublicKeyCredentialCreationOptions``, then pass those to ``createRegistrationCredential(options:minTimeout:maxTimeout:origin:supportedPublicKeyCredentialParameters:attestRegistration:)`` along with a closure that can generate credentials from configured ``AuthenticatorProtocol`` types such as ``KeyPairAuthenticator`` by passing the provided ``AttestationRegistration`` to ``AuthenticatorProtocol/makeCredentials(with:)``, making sure to persist the resulting ``AuthenticatorProtocol/CredentialSource`` in some way. Finally, pass the resulting ``RegistrationCredential`` back to the relying party to finish registration.
+public struct WebAuthnClient {
+    public init() {}
+    
+    public func createRegistrationCredential(
+        options: PublicKeyCredentialCreationOptions,
+        /// Recommended Range: https://w3c.github.io/webauthn/#recommended-range-and-default-for-a-webauthn-ceremony-timeout
+        minTimeout: Duration = .seconds(300),
+        maxTimeout: Duration = .seconds(600),
+        origin: String,
+        supportedPublicKeyCredentialParameters: Set<PublicKeyCredentialParameters> = .supported,
+        attestRegistration: (_ registration: AttestationRegistrationRequest) async throws -> ()
+    ) async throws -> RegistrationCredential {
+        /// Steps: https://w3c.github.io/webauthn/#sctn-createCredential
+        
+        /// Step 1. Assert: options.publicKey is present.
+        // Skip.
+        
+        /// Step 2. If sameOriginWithAncestors is false:
+        ///     1. If the relevant global object, as determined by the calling create() implementation, does not have transient activation:
+        ///         1. Throw a "NotAllowedError" DOMException.
+        ///     2. Consume user activation of the relevant global object.
+        // Skip.
+        
+        /// Step 3. Let pkOptions be the value of options.publicKey.
+        // Skip.
+        
+        /// Step 4. If pkOptions.timeout is present, check if its value lies within a reasonable range as defined by the client and if not, correct it to the closest value lying within that range. Set a timer lifetimeTimer to this adjusted value. If pkOptions.timeout is not present, then set lifetimeTimer to a client-specific default.
+        ///
+        ///     See the recommended range and default for a WebAuthn ceremony timeout for guidance on deciding a reasonable range and default for pkOptions.timeout.
+        let proposedTimeout = options.timeout ?? minTimeout
+        let timeout = max(minTimeout, min(proposedTimeout, maxTimeout))
+        
+        /// Step 5. If the length of pkOptions.user.id is not between 1 and 64 bytes (inclusive) then throw a TypeError.
+        guard 1...64 ~= options.user.id.count
+        else { throw WebAuthnError.invalidUserID }
+        
+        /// Step 6. Let callerOrigin be origin. If callerOrigin is an opaque origin, throw a "NotAllowedError" DOMException.
+        let callerOrigin = origin
+        
+        /// Step 7. Let effectiveDomain be the callerOrigin’s effective domain. If effective domain is not a valid domain, then throw a "SecurityError" DOMException.
+        // Skip.
+        
+        /// Step 8. If pkOptions.rp.id
+        ///     → is present
+        ///         If pkOptions.rp.id is not a registrable domain suffix of and is not equal to effectiveDomain, throw a "SecurityError" DOMException.
+        ///     → Is not present
+        ///         Set pkOptions.rp.id to effectiveDomain.
+        // Skip.
+        
+        /// Step 11. Let credTypesAndPubKeyAlgs be a new list whose items are pairs of PublicKeyCredentialType and a COSEAlgorithmIdentifier.
+        var publicKeyCredentialParameters: [PublicKeyCredentialParameters] = []
+        
+        /// Step 12. If pkOptions.pubKeyCredParams’s size
+        ///     → is zero
+        ///         Append the following pairs of PublicKeyCredentialType and COSEAlgorithmIdentifier values to credTypesAndPubKeyAlgs:
+        ///             public-key and -7 ("ES256").
+        ///             public-key and -257 ("RS256").
+        ///     → is non-zero
+        ///         For each current of pkOptions.pubKeyCredParams:
+        ///             1. If current.type does not contain a PublicKeyCredentialType supported by this implementation, then continue.
+        ///             2. Let alg be current.alg.
+        ///             3. Append the pair of current.type and alg to credTypesAndPubKeyAlgs.
+        ///             If credTypesAndPubKeyAlgs is empty, throw a "NotSupportedError" DOMException.
+        if options.publicKeyCredentialParameters.isEmpty {
+            publicKeyCredentialParameters = [
+                PublicKeyCredentialParameters(alg: .algES256),
+//                PublicKeyCredentialParameters(alg: .algRS256),
+            ]
+        } else {
+            for credentialParameter in options.publicKeyCredentialParameters {
+                guard supportedPublicKeyCredentialParameters.contains(credentialParameter)
+                else { continue }
+                publicKeyCredentialParameters.append(credentialParameter)
+            }
+            guard !publicKeyCredentialParameters.isEmpty
+            else { throw WebAuthnError.noSupportedCredentialParameters }
+        }
+        
+        /// Step 15. Let clientExtensions be a new map and let authenticatorExtensions be a new map.
+        // Skip.
+        
+        /// Step 16. If pkOptions.extensions is present, then for each extensionId → clientExtensionInput of pkOptions.extensions:
+        ///     1. If extensionId is not supported by this client platform or is not a registration extension, then continue.
+        ///     2. Set clientExtensions[extensionId] to clientExtensionInput.
+        ///     3. If extensionId is not an authenticator extension, then continue.
+        ///     4. Let authenticatorExtensionInput be the (CBOR) result of running extensionId’s client extension processing algorithm on clientExtensionInput. If the algorithm returned an error, continue.
+        ///     5. Set authenticatorExtensions[extensionId] to the base64url encoding of authenticatorExtensionInput.
+        // Skip.
+        
+        /// Step 17. Let collectedClientData be a new CollectedClientData instance whose fields are:
+        let collectedClientData = CollectedClientData(
+            /// type
+            ///     The string "webauthn.create".
+            type: .create,
+            /// challenge
+            ///     The base64url encoding of pkOptions.challenge.
+            challenge: options.challenge.base64URLEncodedString(),
+            /// origin
+            ///     The serialization of callerOrigin.
+            origin: callerOrigin
+            /// topOrigin
+            ///     The serialization of callerOrigin’s top-level origin if the sameOriginWithAncestors argument passed to this internal method is false, else undefined.
+            // Skip.
+            /// crossOrigin
+            ///     The inverse of the value of the sameOriginWithAncestors argument passed to this internal method.
+            // Skip.
+        )
+        
+        /// Step 18. Let clientDataJSON be the JSON-compatible serialization of client data constructed from collectedClientData.
+        let clientDataJSON = try JSONEncoder().encode(collectedClientData)
+        
+        /// Step 19. Let clientDataHash be the hash of the serialized client data represented by clientDataJSON.
+        let clientDataHash = SHA256.hash(data: clientDataJSON)
+        
+        /// Step 20. If options.signal is present and aborted, throw the options.signal’s abort reason.
+        // Skip.
+        
+        /// Step 21. Let issuedRequests be a new ordered set.
+        // Skip.
+        
+        /// Step 22. Let authenticators represent a value which at any given instant is a set of client platform-specific handles, where each item identifies an authenticator presently available on this client platform at that instant.
+        // Skip.
+        
+        /// Step 23. Consider the value of hints and craft the user interface accordingly, as the user-agent sees fit.
+        // Skip.
+        
+        /// Step 24. Start lifetimeTimer.
+        // Skip.
+        
+        /// Step 25. While lifetimeTimer has not expired, perform the following actions depending upon lifetimeTimer, and the state and response for each authenticator in authenticators:
+        // Skip.
+        
+        throw WebAuthnError.unsupported
+    }
+}
+
+// MARK: Convenience Registration and Authentication
+
+extension WebAuthnClient {
+    @inlinable
+    public func createRegistrationCredential<Authenticator: AuthenticatorProtocol & Sendable>(
+        options: PublicKeyCredentialCreationOptions,
+        /// Recommended Range: https://w3c.github.io/webauthn/#recommended-range-and-default-for-a-webauthn-ceremony-timeout
+        minTimeout: Duration = .seconds(300),
+        maxTimeout: Duration = .seconds(600),
+        origin: String,
+        supportedPublicKeyCredentialParameters: Set<PublicKeyCredentialParameters> = .supported,
+        authenticator: Authenticator
+    ) async throws -> (registrationCredential: RegistrationCredential, credentialSource: Authenticator.CredentialSource) {
+        var credentialSource: Authenticator.CredentialSource?
+        let registrationCredential = try await createRegistrationCredential(
+            options: options,
+            minTimeout: minTimeout,
+            maxTimeout: maxTimeout,
+            origin: origin,
+            supportedPublicKeyCredentialParameters: supportedPublicKeyCredentialParameters
+        ) { registration in
+            credentialSource = try await authenticator.makeCredentials(with: registration)
+        }
+        
+        guard let credentialSource
+        else { throw WebAuthnError.missingCredentialSourceDespiteSuccess }
+        
+        return (registrationCredential, credentialSource)
+    }
+    
+    @inlinable
+    public func createRegistrationCredential<each Authenticator: AuthenticatorProtocol & Sendable>(
+        options: PublicKeyCredentialCreationOptions,
+        /// Recommended Range: https://w3c.github.io/webauthn/#recommended-range-and-default-for-a-webauthn-ceremony-timeout
+        minTimeout: Duration = .seconds(300),
+        maxTimeout: Duration = .seconds(600),
+        origin: String,
+        supportedPublicKeyCredentialParameters: Set<PublicKeyCredentialParameters> = .supported,
+        authenticators: repeat each Authenticator
+    ) async throws -> (
+        registrationCredential: RegistrationCredential,
+        credentialSources: (repeat Result<(each Authenticator).CredentialSource, Error>)
+    ) {
+        /// Wrapper function since `repeat` doesn't currently support complex expressions
+        @Sendable func register<LocalAuthenticator: AuthenticatorProtocol & Sendable>(
+            authenticator: LocalAuthenticator,
+            registration: AttestationRegistrationRequest
+        ) -> Task<LocalAuthenticator.CredentialSource, Error> {
+            Task { try await authenticator.makeCredentials(with: registration) }
+        }
+        
+        var credentialSources: (repeat Result<(each Authenticator).CredentialSource, Error>)?
+        let registrationCredential = try await createRegistrationCredential(
+            options: options,
+            minTimeout: minTimeout,
+            maxTimeout: maxTimeout,
+            origin: origin,
+            supportedPublicKeyCredentialParameters: supportedPublicKeyCredentialParameters
+        ) { registration in
+            /// Run each authenticator in parallel as child tasks, so we can automatically propagate cancellation to each of them should it occur.
+            let tasks = (repeat register(
+                authenticator: each authenticators,
+                registration: registration
+            ))
+            await withTaskCancellationHandler {
+                credentialSources = (repeat await (each tasks).result)
+            } onCancel: {
+                repeat (each tasks).cancel()
+            }
+        }
+        
+        guard let credentialSources
+        else { throw WebAuthnError.missingCredentialSourceDespiteSuccess }
+        
+        return (registrationCredential, credentialSources)
+    }
+}

Sources/WebAuthn/WebAuthnError.swift

@@ -66,6 +66,10 @@ public struct WebAuthnError: Error, Hashable, Sendable {
         case invalidExponent
         case unsupportedCOSEAlgorithmForRSAPublicKey
         case unsupported
+        
+        // MARK: WebAuthnClient
+        case noSupportedCredentialParameters
+        case missingCredentialSourceDespiteSuccess
 
         // MARK: Authenticator
         case unsupportedCredentialPublicKeyType
@@ -130,6 +134,10 @@ public struct WebAuthnError: Error, Hashable, Sendable {
     public static let unsupportedCOSEAlgorithmForRSAPublicKey = Self(reason: .unsupportedCOSEAlgorithmForRSAPublicKey)
     public static let unsupported = Self(reason: .unsupported)
 
+    // MARK: WebAuthnClient
+    public static let noSupportedCredentialParameters = Self(reason: .noSupportedCredentialParameters)
+    public static let missingCredentialSourceDespiteSuccess = Self(reason: .missingCredentialSourceDespiteSuccess)
+
     // MARK: Authenticator
     public static let unsupportedCredentialPublicKeyType = Self(reason: .unsupportedCredentialPublicKeyType)
     public static let authorizationGestureNotAllowed = Self(reason: .authorizationGestureNotAllowed)

Sources/WebAuthn/WebAuthnManager.swift

@@ -14,7 +14,7 @@
 
 import Foundation
 
-/// Main entrypoint for WebAuthn operations.
+/// Main entrypoint for WebAuthn relying party (aka server-based) operations.
 ///
 /// Use this struct to perform registration and authentication ceremonies.
 ///