Allow same mTLS cert for multiple servers (#4603)

<!-- Thank you for submitting a Pull Request and helping to improve Home
Assistant. Please complete the following sections to help the processing
and review of your changes. Please do not delete anything from this
template. -->

## Summary
<!-- Provide a brief summary of the changes you have made and most
importantly what they aim to achieve -->
Fixes mTLS client certificate sharing across multiple servers when the
same .p12 / SecIdentity is assigned to more than one server.

- Store imported client certificate identities using a stable SHA-256
fingerprint of the leaf certificate instead of a server-specific
identifier.
- Update duplicate Keychain identity handling so re-importing the same
certificate migrates the existing item to the stable fingerprint-based
label.
- Avoid deleting a shared Keychain identity when removing or replacing a
certificate on one server if another configured server still references
it.

## Screenshots
<!-- If this is a user-facing change not in the frontend, please include
screenshots in light and dark mode. -->

## Link to pull request in Documentation repository
<!-- Pull requests that add, change or remove functionality must have a
corresponding pull request in the Companion App Documentation repository
(https://github.com/home-assistant/companion.home-assistant). Please add
the number of this pull request after the "#" -->
Documentation: home-assistant/companion.home-assistant#

## Any other notes
<!-- If there is any other information of note, like if this Pull
Request is part of a bigger change, please include it here. -->

Author: bgoncal

Sources/App/Settings/Connection/ConnectionSettingsViewModel.swift

@@ -290,11 +290,18 @@ final class ConnectionSettingsViewModel: ObservableObject {
 
         switch result {
         case let .fulfilled(certificate):
+            let replacedCertificate = server.info.connection.clientCertificate
+
             // Update server connection info
             server.update { info in
                 info.connection.clientCertificate = certificate
             }
 
+            if let replacedCertificate,
+               replacedCertificate.keychainIdentifier != certificate.keychainIdentifier {
+                deleteCertificateIfUnreferenced(replacedCertificate)
+            }
+
             clientCertificate = certificate
             Current.Log.info("Successfully imported client certificate: \(certificate.displayName)")
         case let .rejected(error):
@@ -309,17 +316,32 @@ final class ConnectionSettingsViewModel: ObservableObject {
     func removeCertificate() {
         guard let certificate = clientCertificate else { return }
 
+        server.update { info in
+            info.connection.clientCertificate = nil
+        }
+
+        deleteCertificateIfUnreferenced(certificate)
+
+        clientCertificate = nil
+        Current.Log.info("Removed client certificate")
+    }
+
+    private func deleteCertificateIfUnreferenced(_ certificate: ClientCertificate) {
+        guard !isCertificateReferenced(certificate) else {
+            Current.Log.info("Keeping shared client certificate in Keychain")
+            return
+        }
+
         do {
             try ClientCertificateManager.shared.delete(certificate: certificate)
         } catch {
             Current.Log.error("Failed to delete certificate from Keychain: \(error)")
         }
+    }
 
-        server.update { info in
-            info.connection.clientCertificate = nil
+    private func isCertificateReferenced(_ certificate: ClientCertificate) -> Bool {
+        Current.servers.all.contains { server in
+            server.info.connection.clientCertificate?.keychainIdentifier == certificate.keychainIdentifier
         }
-
-        clientCertificate = nil
-        Current.Log.info("Removed client certificate")
     }
 }

Sources/Shared/API/mTLS/ClientCertificate.swift

@@ -1,3 +1,4 @@
+import CryptoKit
 import Foundation
 import Security
 
@@ -74,7 +75,7 @@ public final class ClientCertificateManager {
     /// - Parameters:
     ///   - p12Data: The raw .p12 file data
     ///   - password: The password to decrypt the .p12 file
-    ///   - identifier: A unique identifier for storing in Keychain
+    ///   - identifier: A fallback identifier for storing in Keychain if the certificate cannot be fingerprinted
     /// - Returns: A ClientCertificate reference
     public func importP12(data p12Data: Data, password: String, identifier: String) throws -> ClientCertificate {
         let options = Self.pkcs12ImportOptions(password: password)
@@ -123,8 +124,10 @@ public final class ClientCertificateManager {
         let certChain = firstItem[kSecImportItemCertChain as String] as? [SecCertificate] ?? []
         let intermediateCerts = Array(certChain.dropFirst())
 
-        // Store identity in Keychain
-        let keychainIdentifier = "com.ha-ios.mtls.\(identifier)"
+        // Store identities by certificate fingerprint rather than by server. The iOS Keychain
+        // treats a certificate/private-key pair as one identity, so labeling the same identity
+        // with different server IDs makes later imports move the item away from older servers.
+        let keychainIdentifier = Self.keychainIdentifier(for: certificate, fallbackIdentifier: identifier)
         try storeIdentity(secIdentity, identifier: keychainIdentifier)
         storeIntermediateCertificates(intermediateCerts, for: keychainIdentifier)
 
@@ -136,6 +139,21 @@ public final class ClientCertificateManager {
         )
     }
 
+    private static func keychainIdentifier(
+        for certificate: SecCertificate?,
+        fallbackIdentifier: String
+    ) -> String {
+        guard let certificate,
+              let certData = SecCertificateCopyData(certificate) as Data? else {
+            return "com.ha-ios.mtls.\(fallbackIdentifier)"
+        }
+
+        let fingerprint = SHA256.hash(data: certData)
+            .map { String(format: "%02x", $0) }
+            .joined()
+        return "com.ha-ios.mtls.identity.\(fingerprint)"
+    }
+
     /// Store a SecIdentity in the Keychain
     private func storeIdentity(_ identity: SecIdentity, identifier: String) throws {
         // First, delete any existing identity with this identifier
@@ -155,9 +173,10 @@ public final class ClientCertificateManager {
 
         let status = SecItemAdd(addQuery as CFDictionary, nil)
 
-        // Handle duplicate - the identity might already exist with different label
+        // Handle duplicate - the same identity might already exist under a legacy server label.
         if status == errSecDuplicateItem {
-            // Try to update instead
+            // Move the existing identity to the certificate-derived label so every server that
+            // imports the same P12 can resolve the same Keychain item.
             let updateQuery: [String: Any] = [
                 kSecValueRef as String: identity,
             ]
@@ -166,9 +185,9 @@ public final class ClientCertificateManager {
                 kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
             ]
             let updateStatus = SecItemUpdate(updateQuery as CFDictionary, updateAttrs as CFDictionary)
-            // If update also fails, the item exists which is fine for our purposes
-            if updateStatus != errSecSuccess, updateStatus != errSecItemNotFound {
-                Current.Log.warning("Keychain update returned \(updateStatus), but certificate may still work")
+            if updateStatus != errSecSuccess {
+                Current.Log.error("Failed to update duplicate client certificate identity label: \(updateStatus)")
+                throw ClientCertificateError.keychainError(updateStatus)
             }
             return
         }