Add keychain item for biometric registration id

Author: nidal-stytch

Sources/StytchCore/KeychainClient/KeychainClient+Item.swift

@@ -59,7 +59,10 @@ extension KeychainClient {
 }
 
 extension KeychainClient.Item {
+    // The private key registration is central to biometric authentication, and this item should be protected by biometrics unless explicitly specified otherwise by the caller.
     static let privateKeyRegistration: Self = .init(kind: .privateKey, name: "stytch_private_key_registration")
+    // This was introduced in version 0.54.0 to store the biometric registration ID in a keychain item that is not protected by biometrics.
+    static let biometricKeyRegistration: Self = .init(kind: .object, name: "stytch_biometric_key_registration")
 
     static let sessionToken: Self = .init(kind: .token, name: SessionToken.Kind.opaque.name)
     static let sessionJwt: Self = .init(kind: .token, name: SessionToken.Kind.jwt.name)

Sources/StytchCore/Networking/NetworkingRouter.swift

@@ -139,7 +139,9 @@ public extension NetworkingRouter {
                     hostUrl: configuration.hostUrl
                 )
                 userStorage.update(sessionResponse.user)
+                #if !os(tvOS) && !os(watchOS)
                 StytchClient.biometrics.cleanupPotentiallyOrphanedBiometricRegistrations()
+                #endif
             } else if let sessionResponse = dataContainer.data as? B2BAuthenticateResponseType {
                 sessionManager.updateSession(
                     sessionType: .member(sessionResponse.memberSession),

Sources/StytchCore/StytchClient/Biometrics/StytchClient+Biometrics.swift

@@ -9,6 +9,11 @@ public extension StytchClient.Biometrics {
         case availableRegistered
     }
 }
+
+public extension StytchClient {
+    /// The interface for interacting with biometrics products.
+    static var biometrics: Biometrics { .init(router: router.scopedRouter { $0.biometrics }) }
+}
 #endif
 
 public extension StytchClient {
@@ -29,7 +34,7 @@ public extension StytchClient {
 
         /// Indicates if there is an existing biometric registration on device.
         public var registrationAvailable: Bool {
-            keychainClient.valueExistsForItem(.privateKeyRegistration)
+            keychainClient.valueExistsForItem(.biometricKeyRegistration)
         }
 
         #if !os(tvOS) && !os(watchOS)
@@ -51,17 +56,17 @@ public extension StytchClient {
         // sourcery: AsyncVariants, (NOTE: - must use /// doc comment styling)
         /// Removes the current device's existing biometric registration from both the device itself and from the server.
         public func removeRegistration() async throws {
-            guard let queryResult: KeychainClient.QueryResult = try? keychainClient.get(.privateKeyRegistration).first else {
+            guard let queryResult = try? keychainClient.get(.biometricKeyRegistration).first else {
                 return
             }
 
             // Delete registration from backend
-            if let registration = try queryResult.generic.map({ try jsonDecoder.decode(KeychainClient.KeyRegistration.self, from: $0) }) {
-                _ = try await StytchClient.user.deleteFactor(.biometricRegistration(id: registration.registrationId))
+            if let biometricRegistrationId = queryResult.stringValue {
+                _ = try await StytchClient.user.deleteFactor(.biometricRegistration(id: User.BiometricRegistration.ID(stringLiteral: biometricRegistrationId)))
             }
 
-            // Remove local registration
-            try keychainClient.removeItem(.privateKeyRegistration)
+            // Remove local registrations
+            try clearBiometricRegistrations()
         }
 
         // sourcery: AsyncVariants, (NOTE: - must use /// doc comment styling)
@@ -104,23 +109,29 @@ public extension StytchClient {
                 registrationId: finishResponse.biometricRegistrationId
             )
 
+            // Set the .privateKeyRegistration
             try keychainClient.set(
                 key: privateKey,
                 registration: registration,
                 accessPolicy: parameters.accessPolicy.keychainValue
             )
 
+            // Set the .biometricKeyRegistration
+            try keychainClient.set(registration.registrationId.rawValue, for: .biometricKeyRegistration)
+
             return finishResponse
         }
 
         // sourcery: AsyncVariants, (NOTE: - must use /// doc comment styling)
         /// If a valid biometric registration exists, this method confirms the current device owner via the device's built-in biometric reader and returns an updated session object by either starting a new session or adding a the biometric factor to an existing session.
         public func authenticate(parameters: AuthenticateParameters) async throws -> AuthenticateResponse {
-            guard let queryResult: KeychainClient.QueryResult = try keychainClient.get(.privateKeyRegistration).first else {
+            guard let privateKeyRegistrationQueryResult: KeychainClient.QueryResult = try keychainClient.get(.privateKeyRegistration).first else {
                 throw StytchSDKError.noBiometricRegistration
             }
 
-            let privateKey = queryResult.data
+            try copyBiometricRegistrationIDToKeychainIfNeeded(privateKeyRegistrationQueryResult)
+
+            let privateKey = privateKeyRegistrationQueryResult.data
             let publicKey = try cryptoClient.publicKeyForPrivateKey(privateKey)
 
             let startResponse: AuthenticateStartResponse = try await router.post(
@@ -143,45 +154,53 @@ public extension StytchClient {
             return authenticateResponse
         }
 
+        // Clear both the .privateKeyRegistration and the .biometricKeyRegistration
+        func clearBiometricRegistrations() throws {
+            try keychainClient.removeItem(.privateKeyRegistration)
+            try keychainClient.removeItem(.biometricKeyRegistration)
+        }
+
+        // if we have a local biometric registration that doesn't exist on the user object, delete the local
         func cleanupPotentiallyOrphanedBiometricRegistrations() {
             guard let user = StytchClient.user.getSync() else {
                 return
             }
 
-            // if we have a local biometric registration that doesn't exist on the user object, delete the local
             if user.biometricRegistrations.isEmpty {
-                try? keychainClient.removeItem(.privateKeyRegistration)
-            } else if !user.biometricRegistrations.isEmpty {
-                let queryResult = try? keychainClient.get(.privateKeyRegistration).first
-                cleanupBiometricRegistrationIfOrphaned(queryResult: queryResult, user: user)
+                try? clearBiometricRegistrations()
+            } else {
+                let queryResult = try? keychainClient.get(.biometricKeyRegistration).first
+
+                // Check if the user's biometric registrations contain the ID
+                var userBiometricRegistrationIds = [String]()
+                for biometricRegistration in user.biometricRegistrations {
+                    userBiometricRegistrationIds.append(biometricRegistration.biometricRegistrationId.rawValue)
+                }
+
+                if let biometricRegistrationId = queryResult?.stringValue, userBiometricRegistrationIds.contains(biometricRegistrationId) == false {
+                    // Remove the orphaned biometric registration
+                    try? clearBiometricRegistrations()
+                }
             }
         }
 
-        private func cleanupBiometricRegistrationIfOrphaned(
-            queryResult: KeychainClient.QueryResult?,
-            user: User
-        ) {
-            // Decode the biometric registration ID from the query result
-            let biometricRegistrationId = try? queryResult?.generic.map {
-                try jsonDecoder.decode(KeychainClient.KeyRegistration.self, from: $0)
-            }
-
-            // Check if the user's biometric registrations contain the ID
-            if user.biometricRegistrations.map(\.id).contains(biometricRegistrationId?.registrationId) == false {
-                // Remove the orphaned biometric registration
-                try? keychainClient.removeItem(.privateKeyRegistration)
+        /*
+         After introducing the .biometricKeyRegistration keychain item in version 0.54.0, we needed a way for versions prior to 0.54.0
+         to copy the value stored in the biometrically protected .privateKeyRegistration keychain item into the non-biometric
+         .biometricKeyRegistration keychain item without triggering unnecessary Face ID prompts. Since a Face ID prompt is already
+         being shown here for authentication, we decided to use this as an opportunity to perform the migration by copying the
+         registration ID into the .biometricKeyRegistration keychain item. For versions after 0.54.0, this action occurs during
+         registration, and it should only happen here if the .biometricKeyRegistration keychain item is empty.
+         */
+        func copyBiometricRegistrationIDToKeychainIfNeeded(_ queryResult: KeychainClient.QueryResult) throws {
+            let biometricKeyRegistration = try? keychainClient.get(.biometricKeyRegistration).first
+            if biometricKeyRegistration == nil, let registration = try queryResult.generic.map({ try jsonDecoder.decode(KeychainClient.KeyRegistration.self, from: $0) }) {
+                try keychainClient.set(registration.registrationId.rawValue, for: .biometricKeyRegistration)
             }
         }
     }
 }
 
-#if !os(tvOS) && !os(watchOS)
-public extension StytchClient {
-    /// The interface for interacting with biometrics products.
-    static var biometrics: Biometrics { .init(router: router.scopedRouter { $0.biometrics }) }
-}
-#endif
-
 public extension StytchClient.Biometrics {
     typealias RegisterCompleteResponse = Response<RegisterCompleteResponseData>
 

Stytch/DemoApps/StytchBiometrics/Base.lproj/Main.storyboard

@@ -41,7 +41,7 @@
                                 </connections>
                             </button>
                             <button opaque="NO" contentMode="scaleToFill" contentHorizontalAlignment="center" contentVerticalAlignment="center" buttonType="system" lineBreakMode="middleTruncation" translatesAutoresizingMaskIntoConstraints="NO" id="o5j-Hf-UlQ">
-                                <rect key="frame" x="71.666666666666686" y="373" width="250" height="44"/>
+                                <rect key="frame" x="71.666666666666686" y="433" width="250" height="44"/>
                                 <constraints>
                                     <constraint firstAttribute="width" constant="250" id="hIN-Ow-4mf"/>
                                     <constraint firstAttribute="height" constant="44" id="nbd-GJ-kdA"/>
@@ -64,15 +64,29 @@
                                     <action selector="sendAndAuthenticateOTPTapped:" destination="BYZ-38-t0r" eventType="touchUpInside" id="aYn-xv-OWJ"/>
                                 </connections>
                             </button>
+                            <button opaque="NO" contentMode="scaleToFill" contentHorizontalAlignment="center" contentVerticalAlignment="center" buttonType="system" lineBreakMode="middleTruncation" translatesAutoresizingMaskIntoConstraints="NO" id="NSS-yR-4kA">
+                                <rect key="frame" x="71.666666666666686" y="373" width="250" height="44"/>
+                                <constraints>
+                                    <constraint firstAttribute="width" constant="250" id="AYF-4d-BBS"/>
+                                    <constraint firstAttribute="height" constant="44" id="duf-p7-MbL"/>
+                                </constraints>
+                                <state key="normal" title="Button"/>
+                                <buttonConfiguration key="configuration" style="filled" title="Delete Registrations"/>
+                                <connections>
+                                    <action selector="deleteRegistrationsTapped:" destination="BYZ-38-t0r" eventType="touchUpInside" id="HjC-Qh-k2i"/>
+                                </connections>
+                            </button>
                         </subviews>
                         <viewLayoutGuide key="safeArea" id="6Tk-OE-BBY"/>
                         <color key="backgroundColor" systemColor="systemBackgroundColor"/>
                         <constraints>
+                            <constraint firstItem="o5j-Hf-UlQ" firstAttribute="top" secondItem="NSS-yR-4kA" secondAttribute="bottom" constant="16" id="H9h-yE-V0K"/>
+                            <constraint firstItem="NSS-yR-4kA" firstAttribute="centerX" secondItem="8bC-Xf-vdC" secondAttribute="centerX" id="KE2-75-zfD"/>
                             <constraint firstItem="Z8n-4O-9aK" firstAttribute="centerX" secondItem="8bC-Xf-vdC" secondAttribute="centerX" id="TpE-1F-BQX"/>
                             <constraint firstItem="Y0i-2o-kvb" firstAttribute="centerX" secondItem="8bC-Xf-vdC" secondAttribute="centerX" id="Xtd-4b-HJC"/>
+                            <constraint firstItem="NSS-yR-4kA" firstAttribute="top" secondItem="Z8n-4O-9aK" secondAttribute="bottom" constant="16" id="YiG-Oq-E3S"/>
                             <constraint firstItem="2xr-u3-24A" firstAttribute="centerX" secondItem="8bC-Xf-vdC" secondAttribute="centerX" id="bu9-mF-yLw"/>
                             <constraint firstItem="Y0i-2o-kvb" firstAttribute="top" secondItem="2xr-u3-24A" secondAttribute="bottom" constant="50" id="ezs-TN-mbV"/>
-                            <constraint firstItem="o5j-Hf-UlQ" firstAttribute="top" secondItem="Z8n-4O-9aK" secondAttribute="bottom" constant="16" id="gcR-o5-cWl"/>
                             <constraint firstItem="2xr-u3-24A" firstAttribute="top" secondItem="6Tk-OE-BBY" secondAttribute="top" constant="100" id="hWt-qx-X3u"/>
                             <constraint firstItem="Z8n-4O-9aK" firstAttribute="top" secondItem="Y0i-2o-kvb" secondAttribute="bottom" constant="16" id="kLx-k0-BQh"/>
                             <constraint firstItem="o5j-Hf-UlQ" firstAttribute="centerX" secondItem="8bC-Xf-vdC" secondAttribute="centerX" id="y8Z-rQ-8cR"/>

Stytch/DemoApps/StytchBiometrics/ViewController.swift

@@ -68,11 +68,23 @@ class ViewController: UIViewController {
         }
     }
 
+    @IBAction func deleteRegistrationsTapped(_: Any) {
+        clearAllBiometricRegistrations(user: StytchClient.user.getSync())
+        Task {
+            do {
+                let user = try await StytchClient.user.get().wrapped
+                logBiometricRegistrations(user: user, identifier: "delete registrations")
+            } catch {
+                print(error.errorInfo)
+            }
+        }
+    }
+
     func clearAllBiometricRegistrations(user: User?) {
+        guard let user else { return }
         Task {
             do {
-                guard let biometricRegistrations = user?.biometricRegistrations else { return }
-                for registration in biometricRegistrations {
+                for registration in user.biometricRegistrations {
                     _ = try await StytchClient.user.deleteFactor(.biometricRegistration(id: registration.id))
                 }
             } catch {

Tests/StytchCoreTests/BiometricsTestCase.swift

@@ -54,12 +54,16 @@ final class BiometricsTestCase: BaseTestCase {
             .init((0..<challenge.count).map { UInt8($0) })
         }
 
+        // Set the .privateKeyRegistration
         try Current.keychainClient.set(
             key: privateKey.rawRepresentation,
             registration: .init(userId: userId, userLabel: email, registrationId: regId),
             accessPolicy: .deviceOwnerAuthenticationWithBiometrics
         )
 
+        // Set the .biometricKeyRegistration
+        try Current.keychainClient.set(regId.rawValue, for: .biometricKeyRegistration)
+
         XCTAssertTrue(StytchClient.biometrics.registrationAvailable)
 
         networkInterceptor.responses {
@@ -95,12 +99,16 @@ final class BiometricsTestCase: BaseTestCase {
             .init((0..<challenge.count).map { UInt8($0) })
         }
 
+        // Set the .privateKeyRegistration
         try Current.keychainClient.set(
             key: privateKey.rawRepresentation,
             registration: .init(userId: userId, userLabel: email, registrationId: regId),
             accessPolicy: .deviceOwnerAuthenticationWithBiometrics
         )
 
+        // Set the .biometricKeyRegistration
+        try Current.keychainClient.set(regId.rawValue, for: .biometricKeyRegistration)
+
         XCTAssertTrue(StytchClient.biometrics.registrationAvailable)
 
         networkInterceptor.responses {