Improved type safety, local auth support, and better error handling

Sources/KeychainKit/Protocols/KeychainAccountProtocol.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+/// A protocol that defines the required properties for a keychain account descriptor.
+///
+/// Types conforming to this protocol provide metadata for configuring secure storage
+/// and access behavior for keychain items.
+public protocol KeychainAccountProtocol {
+    /// A unique string used to identify the keychain account.
+    var identifier: String { get }
+    
+    /// The keychain data protection level for the account.
+    ///
+    /// Defaults to `kSecAttrAccessibleAfterFirstUnlock`. You may override it to use other
+    /// accessibility levels, such as `kSecAttrAccessibleWhenUnlocked`
+    /// or `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`.
+    var protection: CFString { get }
+    
+    /// The access control flags used to define authentication requirements.
+    ///
+    /// Defaults to `[]` (no additional access control). Can be overridden to specify
+    /// constraints such as `.userPresence`, `.biometryAny`, or `.devicePasscode`.
+    var accessFlags: SecAccessControlCreateFlags { get }
+    
+    /// Whether the item should be marked as synchronizable via iCloud Keychain.
+    ///
+    /// Defaults to `false`. Set to `true` if the item should sync across devices.
+    var synchronizable: Bool { get }
+}
+
+public extension KeychainAccountProtocol {
+    /// Default value for `protection`: accessible after first unlock.
+    var protection: CFString { kSecAttrAccessibleAfterFirstUnlock }
+    
+    /// Default value for `accessFlags`: no access control constraints.
+    var accessFlags: SecAccessControlCreateFlags { [] }
+    
+    /// Default value for `synchronizable`: not synchronized across devices.
+    var synchronizable: Bool { false }
+}
+
+public extension KeychainAccountProtocol where Self: RawRepresentable, Self.RawValue == String {
+    /// Provides a default `identifier` implementation for `RawRepresentable` types
+    /// whose `RawValue` is `String`.
+    ///
+    /// The `identifier` is derived from the raw string value.
+    var identifier: String { rawValue }
+}

Sources/KeychainKit/Protocols/KeychainServiceProtocol.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+/// A protocol that defines the required properties for a keychain service descriptor.
+///
+/// Types conforming to this protocol provide an identifier used to distinguish stored items
+/// and may optionally specify an access group to enable keychain sharing between apps.
+public protocol KeychainServiceProtocol {
+    /// A unique string used to identify the keychain service.
+    var identifier: String { get }
+
+    /// An optional keychain access group identifier to support shared access between apps.
+    ///
+    /// The default implementation returns `nil`, indicating no access group is specified.
+    var accessGroup: String? { get }
+}
+
+public extension KeychainServiceProtocol {
+    /// The default implementation returns `nil`, indicating that no access group is specified.
+    var accessGroup: String? { nil }
+}
+
+public extension KeychainServiceProtocol where Self: RawRepresentable, Self.RawValue == String {
+    /// Provides a default `identifier` implementation for `RawRepresentable` types
+    /// whose `RawValue` is `String`.
+    ///
+    /// The `identifier` is derived from the raw string value.
+    var identifier: String { rawValue }
+}

Sources/KeychainKit/Protocols/KeychainStorageProtocol.swift

@@ -0,0 +1,124 @@
+import Foundation
+
+/// A protocol that defines a type-safe interface for storing and retrieving values
+/// in the system keychain.
+///
+/// This protocol provides generic support for `Data`, `String`, `UUID`, and `Codable` types.
+/// It allows configuring the associated account and service context for each operation.
+///
+/// Types conforming to this protocol must specify concrete types for `Account`
+/// and `Service`, which describe keychain item identity and service grouping.
+///
+/// ## Topics
+///
+/// ### Associated Types
+///
+/// - ``Account``
+/// - ``Service``
+///
+/// ### Instance Properties
+///
+/// - ``service``
+///
+/// ### Retrieving Values
+///
+/// - ``get(_:)-2gcee``
+/// - ``get(_:)-23z7h``
+/// - ``get(_:)-4xbe6``
+/// - ``get(_:decoder:)``
+///
+/// ### Storing Values
+///
+/// - ``set(_:for:)-21dla``
+/// - ``set(_:for:)-6nzkf``
+/// - ``set(_:for:)-2smpc``
+/// - ``set(_:for:encoder:)``
+///
+/// ### Deleting Values
+///
+/// - ``delete(_:)``
+public protocol KeychainStorageProtocol {
+    /// A type that describes a keychain account and its security configuration.
+    associatedtype Account: KeychainAccountProtocol
+    
+    /// A type that identifies a keychain service context (e.g., app or subsystem).
+    associatedtype Service: KeychainServiceProtocol
+    
+    /// The service associated with this keychain storage instance.
+    ///
+    /// This value is used as the `kSecAttrService` when interacting with the keychain.
+    /// If `nil`, the default service behavior is used.
+    var service: Service? { get }
+    
+    /// Retrieves the value stored in the keychain for the specified account as raw `Data`.
+    ///
+    /// - Parameter account: The keychain account whose value should be retrieved.
+    /// - Returns: The data associated with the given account.
+    /// - Throws: An error if the item is not found, access is denied, or another keychain error occurs.
+    func get(_ account: Account) throws(KeychainError) -> Data
+    
+    /// Retrieves the value stored in the keychain for the specified account as a UTF-8 string.
+    ///
+    /// - Parameter account: The keychain account whose value should be retrieved.
+    /// - Returns: A string decoded from the stored data using UTF-8 encoding.
+    /// - Throws: An error if the item is not found, the data is not valid UTF-8,
+    ///   or a keychain access error occurs.
+    func get(_ account: Account) throws(KeychainError) -> String
+    
+    /// Retrieves the value stored in the keychain for the specified account as a `UUID`.
+    ///
+    /// - Parameter account: The keychain account whose value should be retrieved.
+    /// - Returns: A UUID decoded from a 16-byte binary representation stored in the keychain.
+    /// - Throws: An error if the item is not found, the data is not exactly 16 bytes,
+    ///   or a keychain access error occurs.
+    func get(_ account: Account) throws(KeychainError) -> UUID
+    
+    /// Retrieves and decodes a value of type `T` stored in the keychain for the specified account.
+    ///
+    /// - Parameters:
+    ///   - account: The keychain account whose value should be retrieved.
+    ///   - decoder: The `JSONDecoder` instance used to decode the stored data.
+    /// - Returns: A decoded instance of type `T`.
+    /// - Throws: An error if the item is not found, decoding fails, or a keychain access error occurs.
+    func get<T: Decodable>(_ account: Account, decoder: JSONDecoder) throws(KeychainError) -> T
+    
+    /// Stores raw `Data` in the keychain for the specified account.
+    ///
+    /// - Parameters:
+    ///   - value: The data to store in the keychain.
+    ///   - account: The keychain account under which the data will be saved.
+    /// - Throws: An error if storing the data fails.
+    func set(_ value: Data, for account: Account) throws(KeychainError)
+    
+    /// Stores a UTF-8 encoded `String` in the keychain for the specified account.
+    ///
+    /// - Parameters:
+    ///   - value: The string to store in the keychain.
+    ///   - account: The keychain account under which the string will be saved.
+    /// - Throws: An error if storing the string fails.
+    func set(_ value: String, for account: Account) throws(KeychainError)
+    
+    /// Stores a `UUID` in the keychain for the specified account.
+    ///
+    /// - Parameters:
+    ///   - value: The UUID to store in the keychain (stored in 16-byte binary format).
+    ///   - account: The keychain account under which the UUID will be saved.
+    /// - Throws: An error if storing the UUID fails.
+    func set(_ value: UUID, for account: Account) throws(KeychainError)
+    
+    /// Encodes and stores a value of type `T` in the keychain for the specified account.
+    ///
+    /// - Parameters:
+    ///   - value: The value to encode and store.
+    ///   - account: The keychain account under which the encoded data will be saved.
+    ///   - encoder: The `JSONEncoder` used to encode the value.
+    /// - Throws: An error if encoding or storing the value fails.
+    func set<T: Encodable>(_ value: T, for account: Account, encoder: JSONEncoder) throws(KeychainError)
+    
+    /// Deletes the keychain item associated with the specified account.
+    ///
+    /// - Parameter account: The keychain account whose stored value should be deleted.
+    /// - Note: If the item does not exist, the method completes silently without error.
+    /// - Throws: An error only if the item exists but removal fails.
+    func delete(_ account: Account) throws(KeychainError)
+}