Merge pull request #48 from dimitribouniol/dimitri/unreferenced-string-enumeration

Unreferenced String Enumeration

Author: 0xTim

Sources/WebAuthn/Ceremonies/Authentication/AuthenticationCredential.swift

@@ -29,10 +29,10 @@ public struct AuthenticationCredential {
 
     /// Reports the authenticator attachment modality in effect at the time the navigator.credentials.create() or
     /// navigator.credentials.get() methods successfully complete
-    public let authenticatorAttachment: String?
+    public let authenticatorAttachment: AuthenticatorAttachment?
 
-    /// Value will always be "public-key" (for now)
-    public let type: String
+    /// Value will always be ``CredentialType/publicKey`` (for now)
+    public let type: CredentialType
 }
 
 extension AuthenticationCredential: Decodable {
@@ -42,8 +42,8 @@ extension AuthenticationCredential: Decodable {
         id = try container.decode(URLEncodedBase64.self, forKey: .id)
         rawID = try container.decodeBytesFromURLEncodedBase64(forKey: .rawID)
         response = try container.decode(AuthenticatorAssertionResponse.self, forKey: .response)
-        authenticatorAttachment = try container.decodeIfPresent(String.self, forKey: .authenticatorAttachment)
-        type = try container.decode(String.self, forKey: .type)
+        authenticatorAttachment = try container.decodeIfPresent(AuthenticatorAttachment.self, forKey: .authenticatorAttachment)
+        type = try container.decode(CredentialType.self, forKey: .type)
     }
 
     private enum CodingKeys: String, CodingKey {

Sources/WebAuthn/Ceremonies/Authentication/PublicKeyCredentialRequestOptions.swift

@@ -87,8 +87,8 @@ public struct PublicKeyCredentialDescriptor: Equatable, Encodable {
         case `internal`
     }
 
-    /// Will always be 'public-key'
-    public let type: String
+    /// Will always be ``CredentialType/publicKey``
+    public let type: CredentialType
 
     /// The sequence of bytes representing the credential's ID
     ///
@@ -98,7 +98,11 @@ public struct PublicKeyCredentialDescriptor: Equatable, Encodable {
     /// The types of connections to the client/browser the authenticator supports
     public let transports: [AuthenticatorTransport]
 
-    public init(type: String, id: [UInt8], transports: [AuthenticatorTransport] = []) {
+    public init(
+        type: CredentialType = .publicKey,
+        id: [UInt8],
+        transports: [AuthenticatorTransport] = []
+    ) {
         self.type = type
         self.id = id
         self.transports = transports

Sources/WebAuthn/Ceremonies/Registration/Credential.swift

@@ -17,8 +17,8 @@ import Foundation
 /// After a successful registration ceremony we pass this data back to the relying party. It contains all needed
 /// information about a WebAuthn credential for storage in e.g. a database.
 public struct Credential {
-    /// Value will always be "public-key" (for now)
-    public let type: String
+    /// Value will always be ``CredentialType/publicKey`` (for now)
+    public let type: CredentialType
 
     /// base64 encoded String of the credential ID bytes
     public let id: String

Sources/WebAuthn/Ceremonies/Registration/PublicKeyCredentialCreationOptions.swift

@@ -72,19 +72,19 @@ public struct PublicKeyCredentialCreationOptions: Encodable {
 // MARK: - Credential parameters
 /// From §5.3 (https://w3c.github.io/TR/webauthn/#dictionary-credential-params)
 public struct PublicKeyCredentialParameters: Equatable, Encodable {
-    /// The type of credential to be created. At the time of writing always "public-key".
-    public let type: String
+    /// The type of credential to be created. At the time of writing always ``CredentialType/publicKey``.
+    public let type: CredentialType
     /// The cryptographic signature algorithm with which the newly generated credential will be used, and thus also
     /// the type of asymmetric key pair to be generated, e.g., RSA or Elliptic Curve.
     public let alg: COSEAlgorithmIdentifier
 
     /// Creates a new `PublicKeyCredentialParameters` instance.
     ///
     /// - Parameters:
-    ///   - type: The type of credential to be created. At the time of writing always "public-key".
+    ///   - type: The type of credential to be created. At the time of writing always ``CredentialType/publicKey``.
     ///   - alg: The cryptographic signature algorithm to be used with the newly generated credential.
     ///     For example RSA or Elliptic Curve.
-    public init(type: String = "public-key", alg: COSEAlgorithmIdentifier) {
+    public init(type: CredentialType = .publicKey, alg: COSEAlgorithmIdentifier) {
         self.type = type
         self.alg = alg
     }
@@ -94,7 +94,7 @@ extension Array where Element == PublicKeyCredentialParameters {
     /// A list of `PublicKeyCredentialParameters` WebAuthn Swift currently supports.
     public static var supported: [Element] {
         COSEAlgorithmIdentifier.allCases.map {
-            Element.init(type: "public-key", alg: $0)
+            Element.init(type: .publicKey, alg: $0)
         }
     }
 }

Sources/WebAuthn/Ceremonies/Registration/RegistrationCredential.swift

@@ -22,8 +22,8 @@ public struct RegistrationCredential {
     /// The credential ID of the newly created credential.
     public let id: URLEncodedBase64
 
-    /// Value will always be "public-key" (for now)
-    public let type: String
+    /// Value will always be ``CredentialType/publicKey`` (for now)
+    public let type: CredentialType
 
     /// The raw credential ID of the newly created credential.
     public let rawID: [UInt8]
@@ -37,7 +37,7 @@ extension RegistrationCredential: Decodable {
         let container = try decoder.container(keyedBy: CodingKeys.self)
 
         id = try container.decode(URLEncodedBase64.self, forKey: .id)
-        type = try container.decode(String.self, forKey: .type)
+        type = try container.decode(CredentialType.self, forKey: .type)
         guard let rawID = try container.decode(URLEncodedBase64.self, forKey: .rawID).decodedBytes else {
             throw DecodingError.dataCorruptedError(
                 forKey: .rawID,
@@ -61,8 +61,8 @@ extension RegistrationCredential: Decodable {
 struct ParsedCredentialCreationResponse {
     let id: URLEncodedBase64
     let rawID: Data
-    /// Value will always be "public-key" (for now)
-    let type: String
+    /// Value will always be ``CredentialType/publicKey`` (for now)
+    let type: CredentialType
     let raw: AuthenticatorAttestationResponse
     let response: ParsedAuthenticatorAttestationResponse
 
@@ -71,9 +71,8 @@ struct ParsedCredentialCreationResponse {
         id = rawResponse.id
         rawID = Data(rawResponse.rawID)
 
-        guard rawResponse.type == "public-key" else {
-            throw WebAuthnError.invalidCredentialCreationType
-        }
+        guard rawResponse.type == .publicKey 
+        else { throw WebAuthnError.invalidCredentialCreationType }
         type = rawResponse.type
 
         raw = rawResponse.attestationResponse

Sources/WebAuthn/Ceremonies/Shared/AuthenticatorAttachment.swift

@@ -0,0 +1,34 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+/// An authenticators' attachment modalities.
+///
+/// Relying Parties use this to express a preferred authenticator attachment modality when registering a credential, and clients use this to report the authenticator attachment modality used to complete a registration or authentication ceremony.
+/// - SeeAlso: [WebAuthn Level 3 Editor's Draft §5.4.5. Authenticator Attachment Enumeration (enum AuthenticatorAttachment)](https://w3c.github.io/webauthn/#enum-attachment)
+/// - SeeAlso: [WebAuthn Level 3 Editor's Draft §6.2.1. Authenticator Attachment Modality](https://w3c.github.io/webauthn/#sctn-authenticator-attachment-modality)
+///
+public struct AuthenticatorAttachment: UnreferencedStringEnumeration {
+    public var rawValue: String
+    public init(_ rawValue: String) {
+        self.rawValue = rawValue
+    }
+    
+    /// A platform authenticator is attached using a client device-specific transport, called platform attachment, and is usually not removable from the client device. A public key credential bound to a platform authenticator is called a platform credential.
+    /// - SeeAlso: [WebAuthn Level 3 Editor's Draft §6.2.1. Authenticator Attachment Modality](https://w3c.github.io/webauthn/#platform-attachment)
+    public static let platform: Self = "platform"
+    
+    /// A roaming authenticator is attached using cross-platform transports, called cross-platform attachment. Authenticators of this class are removable from, and can "roam" between, client devices. A public key credential bound to a roaming authenticator is called a roaming credential.
+    /// - SeeAlso: [WebAuthn Level 3 Editor's Draft §6.2.1. Authenticator Attachment Modality](https://w3c.github.io/webauthn/#cross-platform-attachment)
+    public static let crossPlatform: Self = "cross-platform"
+}

Sources/WebAuthn/Ceremonies/Shared/CredentialType.swift

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+/// The type of credential being used.
+///
+/// Only ``CredentialType/publicKey`` is supported by WebAuthn.
+/// - SeeAlso: [Credential Management Level 1 Editor's Draft §2.1.2. Credential Type Registry](https://w3c.github.io/webappsec-credential-management/#sctn-cred-type-registry)
+/// - SeeAlso: [WebAuthn Level 3 Editor's Draft §5.1. PublicKeyCredential Interface](https://w3c.github.io/webauthn/#iface-pkcredential)
+public struct CredentialType: UnreferencedStringEnumeration {
+    public var rawValue: String
+    public init(_ rawValue: String) {
+        self.rawValue = rawValue
+    }
+    
+    /// A public key credential.
+    /// - SeeAlso: [WebAuthn Level 3 Editor's Draft §5.1. PublicKeyCredential Interface](https://w3c.github.io/webauthn/#iface-pkcredential)
+    public static let publicKey: Self = "public-key"
+}

Sources/WebAuthn/Helpers/UnreferencedStringEnumeration.swift

@@ -0,0 +1,33 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the WebAuthn Swift open source project
+//
+// Copyright (c) 2022 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
+//
+//===----------------------------------------------------------------------===//
+
+/// An enumeration type that is not referenced by other parts of the Web IDL because that would preclude other values from being used without updating the specification and its implementations.
+/// - SeeAlso: [WebAuthn Level 3 Editor's Draft §2.1.1. Enumerations as DOMString types](https://w3c.github.io/webauthn/#sct-domstring-backwards-compatibility)
+public protocol UnreferencedStringEnumeration: RawRepresentable, Codable, ExpressibleByStringLiteral, Hashable, Comparable where RawValue == String {
+    init(_ rawValue: RawValue)
+}
+
+extension UnreferencedStringEnumeration {
+    public init(rawValue: RawValue) {
+        self.init(rawValue)
+    }
+    
+    public init(stringLiteral value: String) {
+        self.init(value)
+    }
+    
+    public static func < (lhs: Self, rhs: Self) -> Bool {
+        lhs.rawValue < rhs.rawValue
+    }
+}

Sources/WebAuthn/WebAuthnManager.swift

@@ -167,7 +167,8 @@ public struct WebAuthnManager {
         credentialCurrentSignCount: UInt32,
         requireUserVerification: Bool = false
     ) throws -> VerifiedAuthentication {
-        guard credential.type == "public-key" else { throw WebAuthnError.invalidAssertionCredentialType }
+        guard credential.type == .publicKey
+        else { throw WebAuthnError.invalidAssertionCredentialType }
 
         let parsedAssertion = try ParsedAuthenticatorAssertionResponse(from: credential.response)
         try parsedAssertion.verify(

Tests/WebAuthnTests/WebAuthnManagerAuthenticationTests.swift

@@ -35,7 +35,7 @@ final class WebAuthnManagerAuthenticationTests: XCTestCase {
     }
 
     func testBeginAuthentication() async throws {
-        let allowCredentials: [PublicKeyCredentialDescriptor] = [.init(type: "public-key", id: [1, 0, 2, 30])]
+        let allowCredentials: [PublicKeyCredentialDescriptor] = [.init(type: .publicKey, id: [1, 0, 2, 30])]
         let options = try webAuthnManager.beginAuthentication(
             timeout: .seconds(1234),
             allowCredentials: allowCredentials,
@@ -165,8 +165,8 @@ final class WebAuthnManagerAuthenticationTests: XCTestCase {
         signature: [UInt8] = TestECCKeyPair.signature,
         userHandle: [UInt8]? = "36323638424436452d303831452d344331312d413743332d334444304146333345433134".hexadecimal!,
         attestationObject: [UInt8]? = nil,
-        authenticatorAttachment: String? = "platform",
-        type: String = "public-key",
+        authenticatorAttachment: AuthenticatorAttachment? = .platform,
+        type: CredentialType = .publicKey,
         expectedChallenge: [UInt8] = TestConstants.mockChallenge,
         credentialPublicKey: [UInt8] = TestCredentialPublicKeyBuilder().validMock().buildAsByteArray(),
         credentialCurrentSignCount: UInt32 = 0,