Added AssertionAuthenticationRequest to assist with authentication assertions

Author: dimitribouniol

Sources/WebAuthn/Authenticators/Protocol/AssertionAuthenticationRequest.swift

@@ -0,0 +1,69 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 Crypto
+
+public struct AssertionAuthenticationRequest {
+    public var options: PublicKeyCredentialRequestOptions
+    public var clientDataHash: SHA256Digest
+    public var attemptAuthentication: Callback
+    
+    init(
+        options: PublicKeyCredentialRequestOptions,
+        clientDataHash: SHA256Digest,
+        attemptAuthentication: @escaping (_ assertionResults: Results) async throws -> ()
+    ) {
+        self.options = options
+        self.clientDataHash = clientDataHash
+        self.attemptAuthentication = Callback(callback: attemptAuthentication)
+    }
+}
+
+extension AssertionAuthenticationRequest {
+    public struct Callback {
+        /// The internal callback the attestation should call.
+        var callback: (_ assertionResults: Results) async throws -> ()
+        
+        /// Submit the results of asserting a user's authentication request.
+        ///
+        /// Authenticators should call this to submit a successful authentication and cancel any other pending authenticators.
+        ///
+        /// - SeeAlso: https://w3c.github.io/webauthn/#sctn-generating-an-attestation-object
+        public func submitAssertionResults(
+            credentialID: [UInt8],
+            authenticatorData: [UInt8],
+            signature: [UInt8],
+            userHandle: [UInt8]?,
+            authenticatorAttachment: AuthenticatorAttachment
+        ) async throws {
+            try await callback(Results(
+                credentialID: credentialID,
+                authenticatorData: authenticatorData,
+                signature: signature,
+                userHandle: userHandle,
+                authenticatorAttachment: authenticatorAttachment
+            ))
+        }
+    }
+}
+
+extension AssertionAuthenticationRequest {
+    struct Results {
+        var credentialID: [UInt8]
+        var authenticatorData: [UInt8]
+        var signature: [UInt8]
+        var userHandle: [UInt8]?
+        var authenticatorAttachment: AuthenticatorAttachment
+    }
+}

Sources/WebAuthn/Authenticators/Protocol/AuthenticatorProtocol.swift

@@ -15,6 +15,8 @@
 import Crypto
 import SwiftCBOR
 
+public typealias CredentialStore<A: AuthenticatorProtocol> = [A.CredentialSource.ID : A.CredentialSource]
+
 public protocol AuthenticatorProtocol<CredentialSource> {
     associatedtype CredentialSource: AuthenticatorCredentialSourceProtocol
 
@@ -90,6 +92,21 @@ public protocol AuthenticatorProtocol<CredentialSource> {
         requiresUserPresence: Bool,
         credentialOptions: [CredentialSource]
     ) async throws -> CredentialSource
+    
+    /// Request that an authenticator assert one of the specified credentials.
+    ///
+    /// - Note: If the authenticator fails, other authenticators should continue until either one succeeds, or the parent task is cancelled.
+    ///
+    /// - SeeAlso: [WebAuthn Level 3 Editor's Draft §5.1.4.2. Issuing a Credential Request to an Authenticator](https://w3c.github.io/webauthn/#sctn-issuing-cred-request-to-authenticator)
+    /// - SeeAlso: [WebAuthn Level 3 Editor's Draft §6.3.3. The authenticatorGetAssertion Operation](https://w3c.github.io/webauthn/#authenticatorgetassertion)
+    /// - Parameters:
+    ///   - authenticationRequest: The authentication request from the relying party.
+    ///   - credentials: The set of credentials the authenticator should match against.
+    /// - Returns: An updated credential source upon successful authentication.
+    func assertCredentials(
+        authenticationRequest: AssertionAuthenticationRequest,
+        credentials: CredentialStore<Self>
+    ) async throws -> CredentialSource
 }
 
 // MARK: - Default Implementations
@@ -320,3 +337,14 @@ extension AuthenticatorProtocol {
         return credentialSource
     }
 }
+
+// MARK: Authentication
+
+extension AuthenticatorProtocol {
+    public func assertCredentials(
+        authenticationRequest: AssertionAuthenticationRequest,
+        credentials: CredentialStore<Self>
+    ) async throws -> CredentialSource {
+        throw WebAuthnError.unsupported
+    }
+}