TopDogLabs/LocalData
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: TopDogLabs:d95e5660ef181d1ebfea80078c0205d847a1d66a
Branches Tags
TopDogLabs:develop
TopDogLabs:StorageKe—Refactor
..
compare: TopDogLabs:2a42e3dba0e2d1e668145e4a900df5f88fc10827
Branches Tags
TopDogLabs:develop
TopDogLabs:StorageKe—Refactor

No commits in common. "d95e5660ef181d1ebfea80078c0205d847a1d66a" and "2a42e3dba0e2d1e668145e4a900df5f88fc10827" have entirely different histories.
d95e5660ef ... 2a42e3dba0

38 changed files with 755 additions and 36 deletions
Show Stats Expand all files Collapse all files

41
Sources/LocalData/Audit/StorageAuditReport.swift
View File

@ -1,9 +1,16 @@
import Foundation
/// Renders audit reports for storage key catalogs and registries.
///
/// Use this type to build human-readable snapshots of your storage surface area.
/// Reports are useful for security reviews, compliance audits, and debugging
/// catalog registration issues.
public struct StorageAuditReport: Sendable {
/// Returns descriptors for all keys in a catalog.
///
/// This applies the catalog name to each descriptor, so the output can be
/// grouped and traced back to its module.
///
/// - Parameter catalog: Catalog containing keys to describe.
/// - Returns: An array of ``StorageKeyDescriptor`` values.
public static func items(for catalog: some StorageKeyCatalog) -> [StorageKeyDescriptor] {
@ -20,6 +27,9 @@ public struct StorageAuditReport: Sendable {
/// Renders a text report for a list of type-erased keys.
///
/// Use this when you already have `AnyStorageKey` entries, such as from
/// `StorageRouter.allRegisteredEntries()`.
///
/// - Parameter entries: The keys to render.
/// - Returns: A newline-delimited report string.
public static func renderText(_ entries: [AnyStorageKey]) -> String {
@ -36,6 +46,9 @@ public struct StorageAuditReport: Sendable {
/// Renders a text report for the global registry grouped by catalog.
///
/// Each catalog section is prefixed with a header and followed by its
/// contained key descriptors.
///
/// - Returns: A report string grouped by catalog name.
public static func renderGlobalRegistryGrouped() async -> String {
let catalogs = await StorageRouter.shared.allRegisteredCatalogs()
@ -77,6 +90,10 @@ public struct StorageAuditReport: Sendable {
return lines.joined(separator: "\n")
}
/// Formats a storage domain for audit output.
///
/// - Parameter domain: Domain to format.
/// - Returns: A concise, human-readable domain string.
private static func string(for domain: StorageDomain) -> String {
switch domain {
case .userDefaults(let suite):
@ -94,6 +111,10 @@ public struct StorageAuditReport: Sendable {
}
}
/// Formats a file directory for audit output.
///
/// - Parameter directory: Directory to format.
/// - Returns: A concise directory string.
private static func string(for directory: FileDirectory) -> String {
switch directory {
case .documents:
@ -105,6 +126,10 @@ public struct StorageAuditReport: Sendable {
}
}
/// Formats platform availability for audit output.
///
/// - Parameter availability: Availability to format.
/// - Returns: A concise availability string.
private static func string(for availability: PlatformAvailability) -> String {
switch availability {
case .all:
@ -118,6 +143,10 @@ public struct StorageAuditReport: Sendable {
}
}
/// Formats sync policy for audit output.
///
/// - Parameter syncPolicy: Sync policy to format.
/// - Returns: A concise sync policy string.
private static func string(for syncPolicy: SyncPolicy) -> String {
switch syncPolicy {
case .never:
@ -129,6 +158,10 @@ public struct StorageAuditReport: Sendable {
}
}
/// Formats security policy for audit output.
///
/// - Parameter security: Security policy to format.
/// - Returns: A concise security policy string.
private static func string(for security: SecurityPolicy) -> String {
switch security {
case .none:
@ -141,6 +174,10 @@ public struct StorageAuditReport: Sendable {
}
}
/// Formats encryption policy for audit output.
///
/// - Parameter policy: Encryption policy to format.
/// - Returns: A concise encryption policy string.
private static func string(for policy: SecurityPolicy.EncryptionPolicy) -> String {
switch policy {
case .aes256(let derivation):
@ -152,6 +189,10 @@ public struct StorageAuditReport: Sendable {
}
}
/// Formats key derivation for audit output.
///
/// - Parameter derivation: Derivation to format.
/// - Returns: A concise derivation string.
private static func string(for derivation: SecurityPolicy.KeyDerivation) -> String {
switch derivation {
case .pbkdf2(let iterations, _):

14
Sources/LocalData/Configuration/EncryptionConfiguration.swift
View File

@ -1,6 +1,10 @@
import Foundation
/// Configuration for the encryption system.
///
/// These values control how LocalData derives encryption keys and where the
/// master key is stored. Changing them in a shipped app can make previously
/// encrypted data unreadable, so treat updates as migrations.
public struct EncryptionConfiguration: Sendable {
/// Keychain service for the master key.
public let masterKeyService: String
@ -14,6 +18,16 @@ public struct EncryptionConfiguration: Sendable {
public let pbkdf2Iterations: Int
/// Creates an encryption configuration.
///
/// - Parameters:
/// - masterKeyService: Keychain service identifier for the master key.
/// - masterKeyAccount: Keychain account name for the master key.
/// - masterKeyLength: Length of the derived key in bytes.
/// - defaultHKDFInfo: Default HKDF info value used in key derivation.
/// - pbkdf2Iterations: Default PBKDF2 iteration count.
///
/// - Warning: Changing these values after data is encrypted will cause
/// existing encrypted data to become inaccessible unless you migrate it.
public init(
masterKeyService: String = "LocalData",
masterKeyAccount: String = "MasterKey",

14
Sources/LocalData/Configuration/FileStorageConfiguration.swift
View File

@ -1,16 +1,26 @@
import Foundation
/// Configuration for the FileStorageHelper.
/// Configuration for file-based storage.
///
/// Controls where LocalData stores files and how it scopes directories for
/// app sandbox and App Group containers.
public struct FileStorageConfiguration: Sendable {
/// An optional sub-directory to scope all library files within.
/// If provided, files will be stored in `.../Documents/{subDirectory}/` instead of `.../Documents/`.
///
/// If provided, files will be stored in `.../Documents/{subDirectory}/`
/// instead of `.../Documents/`.
public let subDirectory: String?
/// An optional base URL to override the default system directories.
///
/// Primarily used for testing isolation.
public let baseURL: URL?
/// Creates a file storage configuration.
///
/// - Parameters:
/// - subDirectory: Optional subdirectory for all storage.
/// - baseURL: Optional base URL override for testing.
public init(subDirectory: String? = nil, baseURL: URL? = nil) {
self.subDirectory = subDirectory
self.baseURL = baseURL

8
Sources/LocalData/Configuration/StorageConfiguration.swift
View File

@ -1,7 +1,9 @@
import Foundation
/// Global configuration for the storage engine.
/// Allows setting default identifiers for Keychain services and App Groups.
///
/// Allows setting default identifiers for Keychain services and App Groups to
/// reduce repeated configuration in individual keys.
public struct StorageConfiguration: Sendable {
/// The default Keychain service to use if none is specified in a StorageKey.
public let defaultKeychainService: String?
@ -10,6 +12,10 @@ public struct StorageConfiguration: Sendable {
public let defaultAppGroupIdentifier: String?
/// Creates a configuration with optional defaults.
///
/// - Parameters:
/// - defaultKeychainService: Default Keychain service identifier.
/// - defaultAppGroupIdentifier: Default App Group identifier.
public init(
defaultKeychainService: String? = nil,
defaultAppGroupIdentifier: String? = nil

4
Sources/LocalData/Configuration/SyncConfiguration.swift
View File

@ -1,11 +1,15 @@
import Foundation
/// Configuration for WatchConnectivity sync operations.
///
/// Controls payload limits for automatic sync.
public struct SyncConfiguration: Sendable {
/// Maximum data size for automatic sync in bytes.
public let maxAutoSyncSize: Int
/// Creates a sync configuration.
///
/// - Parameter maxAutoSyncSize: Maximum payload size in bytes.
public init(maxAutoSyncSize: Int = 100_000) {
self.maxAutoSyncSize = maxAutoSyncSize
}

123
Sources/LocalData/Helpers/EncryptionHelper.swift
View File

@ -3,14 +3,29 @@ import CryptoKit
/// Actor that handles all encryption and decryption operations.
///
/// Uses AES-GCM or ChaChaPoly for symmetric encryption with derived keys.
/// `EncryptionHelper` provides symmetric encryption using AES-GCM or
/// ChaChaPoly. It derives per-key symmetric keys from a master key stored in
/// Keychain (or from external key material when configured) so encrypted data
/// is deterministic and recoverable across app launches.
actor EncryptionHelper {
/// Shared encryption helper instance.
///
/// Prefer this shared instance in production code. Tests can inject a custom instance
/// with isolated configuration and keychain dependencies.
public static let shared = EncryptionHelper()
/// Current encryption configuration.
///
/// Controls key derivation defaults and master key settings.
private var configuration: EncryptionConfiguration
/// Keychain provider used for master key storage.
///
/// Abstracted to allow test stubs and isolation.
private var keychain: KeychainStoring
/// External key material providers keyed by source identifier.
///
/// Used for ``SecurityPolicy/EncryptionPolicy/external(source:keyDerivation:)``.
private var keyMaterialProviders: [KeyMaterialSource: any KeyMaterialProviding] = [:]
/// Creates an encryption helper with a configuration and keychain provider.
@ -31,6 +46,8 @@ actor EncryptionHelper {
/// Updates the configuration for the actor.
///
/// - Parameter configuration: New encryption configuration.
/// - Warning: Changing these values after data is encrypted may make
/// existing data unreadable unless migrated.
public func updateConfiguration(_ configuration: EncryptionConfiguration) {
self.configuration = configuration
}
@ -38,7 +55,7 @@ actor EncryptionHelper {
/// Updates the keychain helper used for master key storage.
///
/// - Parameter keychain: Keychain provider to use.
/// - Note: Internal for testing isolation.
/// - Note: Intended for testing isolation and dependency injection.
public func updateKeychainHelper(_ keychain: KeychainStoring) {
self.keychain = keychain
}
@ -50,6 +67,7 @@ actor EncryptionHelper {
/// - Parameters:
/// - provider: The provider that supplies key material.
/// - source: Identifier used to look up the provider.
/// - Note: Required when using ``SecurityPolicy/EncryptionPolicy/external(source:keyDerivation:)``.
public func registerKeyMaterialProvider(
_ provider: any KeyMaterialProviding,
for source: KeyMaterialSource
@ -58,12 +76,13 @@ actor EncryptionHelper {
}
/// Encrypts data using AES-GCM or ChaChaPoly.
///
/// - Parameters:
/// - data: The plaintext data to encrypt.
/// - keyName: A unique name used for key derivation salt.
/// - policy: The encryption policy specifying algorithm and key derivation.
/// - Returns: The encrypted data (nonce + ciphertext + tag combined).
/// - Throws: `StorageError.securityApplicationFailed` if encryption fails.
/// - Throws: ``StorageError/securityApplicationFailed`` if encryption fails.
public func encrypt(
_ data: Data,
keyName: String,
@ -74,12 +93,13 @@ actor EncryptionHelper {
}
/// Decrypts data using AES-GCM or ChaChaPoly.
///
/// - Parameters:
/// - data: The encrypted data (nonce + ciphertext + tag combined).
/// - keyName: The same unique name used during encryption.
/// - policy: The same encryption policy used during encryption.
/// - Returns: The decrypted plaintext data.
/// - Throws: `StorageError.securityApplicationFailed` if decryption fails.
/// - Throws: ``StorageError/securityApplicationFailed`` if decryption fails.
public func decrypt(
_ data: Data,
keyName: String,
@ -91,7 +111,13 @@ actor EncryptionHelper {
// MARK: - Key Derivation
/// Derives an encryption key using the specified policy.
/// Derives a symmetric key based on the encryption policy.
///
/// - Parameters:
/// - keyName: Logical key name used to seed derivation.
/// - policy: Encryption policy describing algorithm and derivation.
/// - Returns: A symmetric key for encryption/decryption.
/// - Throws: ``StorageError/securityApplicationFailed`` when derivation fails or no provider exists.
private func deriveKey(
keyName: String,
policy: SecurityPolicy.EncryptionPolicy
@ -118,7 +144,14 @@ actor EncryptionHelper {
}
}
/// Derives key material based on the provided key derivation strategy.
/// Derives key material using HKDF or PBKDF2.
///
/// - Parameters:
/// - keyName: Logical key name used to seed derivation.
/// - derivation: Key derivation strategy.
/// - baseKeyMaterial: Base key material (master key or external).
/// - Returns: A symmetric key derived from the inputs.
/// - Throws: ``StorageError/securityApplicationFailed`` if derivation fails.
private func deriveKeyMaterial(
keyName: String,
derivation: SecurityPolicy.KeyDerivation,
@ -148,7 +181,10 @@ actor EncryptionHelper {
}
}
/// Gets or creates the master key stored in keychain.
/// Retrieves or creates the master key stored in Keychain.
///
/// - Returns: The master key data.
/// - Throws: ``StorageError/securityApplicationFailed`` or keychain errors.
private func getMasterKey() async throws -> Data {
if let existing = try await keychain.get(
service: configuration.masterKeyService,
@ -180,6 +216,14 @@ actor EncryptionHelper {
// MARK: - AES-GCM Operations
/// Encrypts data using the selected algorithm and key.
///
/// - Parameters:
/// - data: Plaintext data to encrypt.
/// - key: Symmetric key to use.
/// - policy: Encryption policy selecting the algorithm.
/// - Returns: Combined ciphertext for storage.
/// - Throws: ``StorageError/securityApplicationFailed`` if encryption fails.
private func encryptWithKey(
_ data: Data,
using key: SymmetricKey,
@ -195,6 +239,13 @@ actor EncryptionHelper {
}
}
/// Encrypts data using AES-GCM.
///
/// - Parameters:
/// - data: Plaintext data to encrypt.
/// - key: Symmetric key to use.
/// - Returns: Combined nonce + ciphertext + tag.
/// - Throws: ``StorageError/securityApplicationFailed`` if encryption fails.
private func encryptWithAESGCM(_ data: Data, using key: SymmetricKey) throws -> Data {
do {
let sealedBox = try AES.GCM.seal(data, using: key)
@ -207,6 +258,14 @@ actor EncryptionHelper {
}
}
/// Decrypts data using the selected algorithm and key.
///
/// - Parameters:
/// - data: Combined nonce + ciphertext + tag.
/// - key: Symmetric key to use.
/// - policy: Encryption policy selecting the algorithm.
/// - Returns: Decrypted plaintext data.
/// - Throws: ``StorageError/securityApplicationFailed`` if decryption fails.
private func decryptWithKey(
_ data: Data,
using key: SymmetricKey,
@ -222,6 +281,13 @@ actor EncryptionHelper {
}
}
/// Decrypts data using AES-GCM.
///
/// - Parameters:
/// - data: Combined nonce + ciphertext + tag.
/// - key: Symmetric key to use.
/// - Returns: Decrypted plaintext data.
/// - Throws: ``StorageError/securityApplicationFailed`` if decryption fails.
private func decryptWithAESGCM(_ data: Data, using key: SymmetricKey) throws -> Data {
do {
let sealedBox = try AES.GCM.SealedBox(combined: data)
@ -231,6 +297,13 @@ actor EncryptionHelper {
}
}
/// Encrypts data using ChaChaPoly.
///
/// - Parameters:
/// - data: Plaintext data to encrypt.
/// - key: Symmetric key to use.
/// - Returns: Combined nonce + ciphertext + tag.
/// - Throws: ``StorageError/securityApplicationFailed`` if encryption fails.
private func encryptWithChaChaPoly(_ data: Data, using key: SymmetricKey) throws -> Data {
do {
let sealedBox = try ChaChaPoly.seal(data, using: key)
@ -240,6 +313,13 @@ actor EncryptionHelper {
}
}
/// Decrypts data using ChaChaPoly.
///
/// - Parameters:
/// - data: Combined nonce + ciphertext + tag.
/// - key: Symmetric key to use.
/// - Returns: Decrypted plaintext data.
/// - Throws: ``StorageError/securityApplicationFailed`` if decryption fails.
private func decryptWithChaChaPoly(_ data: Data, using key: SymmetricKey) throws -> Data {
do {
let sealedBox = try ChaChaPoly.SealedBox(combined: data)
@ -251,6 +331,15 @@ actor EncryptionHelper {
// MARK: - PBKDF2 Implementation
/// Derives key data using PBKDF2-SHA256.
///
/// - Parameters:
/// - password: Base key material used as the PBKDF2 password.
/// - salt: Salt value to strengthen derivation.
/// - iterations: Number of PBKDF2 rounds.
/// - keyLength: Desired output length in bytes.
/// - Returns: Derived key material.
/// - Throws: ``StorageError/securityApplicationFailed`` if iterations are invalid.
private func pbkdf2SHA256(
password: Data,
salt: Data,
@ -286,22 +375,42 @@ actor EncryptionHelper {
return derivedKey.prefix(keyLength)
}
/// Computes HMAC-SHA256 for PBKDF2.
///
/// - Parameters:
/// - key: HMAC key.
/// - data: Data to authenticate.
/// - Returns: HMAC output.
private func hmacSHA256(key: Data, data: Data) -> Data {
let symmetricKey = SymmetricKey(data: key)
let mac = HMAC<SHA256>.authenticationCode(for: data, using: symmetricKey)
return Data(mac)
}
/// XORs two data buffers for PBKDF2 chaining.
///
/// - Parameters:
/// - left: First buffer.
/// - right: Second buffer.
/// - Returns: XORed data.
private func xor(_ left: Data, _ right: Data) -> Data {
let xored = zip(left, right).map { $0 ^ $1 }
return Data(xored)
}
/// Encodes a UInt32 as big-endian data.
///
/// - Parameter value: Value to encode.
/// - Returns: Big-endian data representation.
private func uint32BigEndian(_ value: UInt32) -> Data {
var bigEndian = value.bigEndian
return Data(bytes: &bigEndian, count: MemoryLayout<UInt32>.size)
}
/// Generates a deterministic salt from a key name.
///
/// - Parameter keyName: Key name used to build the salt.
/// - Returns: Salt data used for key derivation.
private func defaultSalt(for keyName: String) -> Data {
Data(keyName.utf8)
}

46
Sources/LocalData/Helpers/FileStorageHelper.swift
View File

@ -3,12 +3,15 @@ import Foundation
/// Actor that handles all file system operations.
///
/// Provides thread-safe file reading, writing, deletion, and listing for
/// app sandbox and App Group containers.
/// app sandbox and App Group containers, with optional subdirectory scoping.
actor FileStorageHelper {
/// Shared file storage helper instance.
///
/// Prefer this shared instance in production code. Tests can inject a custom instance.
public static let shared = FileStorageHelper()
/// Current file storage configuration.
private var configuration: FileStorageConfiguration
/// Creates a helper with a specific configuration.
@ -241,6 +244,10 @@ actor FileStorageHelper {
// MARK: - Private Helpers
/// Ensures the parent directory exists before writing a file.
///
/// - Parameter url: Directory URL to create if missing.
/// - Throws: ``StorageError/fileError(_:)`` if creation fails.
private func ensureDirectoryExists(at url: URL) throws {
guard !FileManager.default.fileExists(atPath: url.path) else {
return
@ -259,6 +266,13 @@ actor FileStorageHelper {
}
}
/// Writes data to a URL with optional file protection.
///
/// - Parameters:
/// - data: The data to write.
/// - url: Destination URL.
/// - useCompleteFileProtection: Whether to apply complete file protection.
/// - Throws: ``StorageError/fileError(_:)`` if write fails.
private func write(_ data: Data, to url: URL, useCompleteFileProtection: Bool) throws {
var options: Data.WritingOptions = [.atomic]
if useCompleteFileProtection {
@ -274,6 +288,11 @@ actor FileStorageHelper {
}
}
/// Reads data from a URL if it exists.
///
/// - Parameter url: File URL to read.
/// - Returns: File data if present, otherwise `nil`.
/// - Throws: ``StorageError/fileError(_:)`` if read fails.
private func read(from url: URL) throws -> Data? {
guard FileManager.default.fileExists(atPath: url.path) else {
return nil
@ -286,6 +305,10 @@ actor FileStorageHelper {
}
}
/// Deletes a file if it exists.
///
/// - Parameter url: File URL to delete.
/// - Throws: ``StorageError/fileError(_:)`` if deletion fails.
private func delete(file url: URL) throws {
guard FileManager.default.fileExists(atPath: url.path) else {
return
@ -298,6 +321,11 @@ actor FileStorageHelper {
}
}
/// Lists file names in a directory URL.
///
/// - Parameter url: Directory URL to list.
/// - Returns: File names in the directory.
/// - Throws: ``StorageError/fileError(_:)`` if listing fails.
private func list(in url: URL) throws -> [String] {
guard FileManager.default.fileExists(atPath: url.path) else {
return []
@ -310,6 +338,11 @@ actor FileStorageHelper {
}
}
/// Returns the size of a file at a URL.
///
/// - Parameter url: File URL to measure.
/// - Returns: File size in bytes, or `nil` if missing.
/// - Throws: ``StorageError/fileError(_:)`` if attributes fail.
private func size(of url: URL) throws -> Int64? {
guard FileManager.default.fileExists(atPath: url.path) else {
return nil
@ -323,6 +356,11 @@ actor FileStorageHelper {
}
}
/// Resolves the App Group container URL or throws if invalid.
///
/// - Parameter identifier: App Group identifier.
/// - Returns: Container URL for the App Group.
/// - Throws: ``StorageError/invalidAppGroupIdentifier(_:)`` if unresolved.
private func appGroupContainerURL(identifier: String) throws -> URL {
guard let url = FileManager.default.containerURL(
forSecurityApplicationGroupIdentifier: identifier
@ -334,6 +372,12 @@ actor FileStorageHelper {
return url
}
/// Resolves the final directory URL, applying overrides and subdirectory settings.
///
/// - Parameters:
/// - overrideURL: Optional base URL override.
/// - directory: Target file directory.
/// - Returns: Resolved directory URL.
private func resolveDirectoryURL(baseURL overrideURL: URL? = nil, directory: FileDirectory) throws -> URL {
let base: URL
// Priority: 1. Method override, 2. Configuration override, 3. System default

8
Sources/LocalData/Helpers/KeychainHelper.swift
View File

@ -8,6 +8,8 @@ import Security
actor KeychainHelper: KeychainStoring {
/// Shared keychain helper instance.
///
/// Prefer this shared instance in production code. Tests can inject a custom instance.
public static let shared = KeychainHelper()
private init() {}
@ -168,6 +170,12 @@ actor KeychainHelper: KeychainStoring {
// MARK: - Private Helpers
/// Base keychain query for a service/key pair.
///
/// - Parameters:
/// - service: Keychain service identifier.
/// - key: Keychain account name.
/// - Returns: Base query dictionary for Security framework calls.
private func baseQuery(service: String, key: String) -> [String: Any] {
return [
kSecClass as String: kSecClassGenericPassword,

45
Sources/LocalData/Helpers/SyncHelper.swift
View File

@ -3,12 +3,20 @@ import WatchConnectivity
/// Actor that handles WatchConnectivity sync operations.
///
/// Manages data synchronization between iPhone and Apple Watch.
/// `SyncHelper` manages data synchronization between iPhone and Apple Watch.
/// It enforces LocalData's sync policies, validates payload size constraints,
/// and delegates incoming application contexts to ``StorageRouter``.
actor SyncHelper {
/// Shared sync helper instance.
///
/// Prefer this shared instance in production code. Tests can inject a custom instance
/// with isolated configuration and `WCSession` behavior.
public static let shared = SyncHelper()
/// Current sync configuration.
///
/// Controls size thresholds for automatic sync.
private var configuration: SyncConfiguration
/// Creates a helper with a specific configuration.
@ -35,12 +43,18 @@ actor SyncHelper {
// MARK: - Public Interface
/// Syncs data to the paired device if appropriate.
///
/// This method enforces LocalData's eligibility rules:
/// - availability must be `.all` or `.phoneWithWatchSync`
/// - sync policy must be `.manual` or `.automaticSmall`
/// - `.automaticSmall` must be under the configured size threshold
///
/// - Parameters:
/// - data: The data to sync.
/// - keyName: The key name for the application context.
/// - availability: The platform availability setting.
/// - syncPolicy: The sync policy setting.
/// - Throws: `StorageError.dataTooLargeForSync` if data exceeds size limit for automatic sync.
/// - Throws: ``StorageError/dataTooLargeForSync`` if data exceeds size limit for automatic sync.
public func syncIfNeeded(
data: Data,
keyName: String,
@ -68,6 +82,10 @@ actor SyncHelper {
}
/// Manually triggers a sync for the given data.
///
/// This bypasses automatic size gating; callers should ensure payload size
/// is reasonable for application context updates.
///
/// - Parameters:
/// - data: The data to sync.
/// - keyName: The key name for the application context.
@ -107,6 +125,12 @@ actor SyncHelper {
// MARK: - Private Helpers
/// Sends an application context update if WatchConnectivity is ready.
///
/// - Parameters:
/// - data: The data payload to sync.
/// - keyName: The key used in the application context dictionary.
/// - Throws: `WCSession` update errors from `updateApplicationContext`.
private func performSync(data: Data, keyName: String) throws {
guard WCSession.isSupported() else { return }
@ -127,6 +151,10 @@ actor SyncHelper {
Logger.info("<<< [SYNC] Application context updated for key: \(keyName). Keys now: [\(contextKeys)]")
}
/// Lazily configures and activates WCSession.
///
/// LocalData does not own session lifecycle beyond the minimal setup needed
/// to send updates; app-level services should activate WCSession explicitly.
private func setupSession() {
let session = WCSession.default
session.delegate = SessionDelegateProxy.shared
@ -134,7 +162,9 @@ actor SyncHelper {
}
/// Handles received application context from the paired device.
/// This is called by the delegate proxy.
///
/// - Parameter context: Application context dictionary received from WCSession.
/// - Note: This is called by the delegate proxy.
internal func handleReceivedContext(_ context: [String: Any]) async {
Logger.info(">>> [SYNC] Received application context with \(context.count) keys")
for (key, value) in context {
@ -152,11 +182,15 @@ actor SyncHelper {
}
}
/// Internal proxy class that routes WCSessionDelegate callbacks to ``SyncHelper``.
/// Internal proxy class that routes `WCSessionDelegate` callbacks to ``SyncHelper``.
///
/// The proxy bridges delegate callbacks into async code without exposing
/// `WCSessionDelegate` conformance in the public API.
internal final class SessionDelegateProxy: NSObject, WCSessionDelegate {
/// Shared delegate proxy instance.
static let shared = SessionDelegateProxy()
/// Handles WCSession activation completion.
func session(_ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState, error: Error?) {
if let error = error {
Logger.error("WCSession activation failed: \(error.localizedDescription)")
@ -165,6 +199,7 @@ internal final class SessionDelegateProxy: NSObject, WCSessionDelegate {
}
}
/// Receives an updated application context and forwards it to `SyncHelper`.
func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
Task {
await SyncHelper.shared.handleReceivedContext(applicationContext)
@ -172,7 +207,9 @@ internal final class SessionDelegateProxy: NSObject, WCSessionDelegate {
}
#if os(iOS)
/// iOS-only callback when a session becomes inactive.
func sessionDidBecomeInactive(_ session: WCSession) {}
/// iOS-only callback when a session deactivates.
func sessionDidDeactivate(_ session: WCSession) {
session.activate()
}

13
Sources/LocalData/Helpers/UserDefaultsHelper.swift
View File

@ -6,8 +6,11 @@ import Foundation
actor UserDefaultsHelper {
/// Shared helper instance.
///
/// Prefer this shared instance in production code. Tests can inject a custom instance.
public static let shared = UserDefaultsHelper()
/// Underlying defaults instance used when no suite is specified.
private let defaults: UserDefaults
/// Creates a helper with a specific `UserDefaults` instance.
@ -125,6 +128,11 @@ actor UserDefaultsHelper {
// MARK: - Private Helpers
/// Resolves the correct `UserDefaults` instance for a suite.
///
/// - Parameter suite: Suite name, or `nil` to use standard defaults.
/// - Returns: The resolved `UserDefaults` instance.
/// - Throws: ``StorageError/invalidUserDefaultsSuite(_:)`` if the suite is invalid.
private func userDefaults(for suite: String?) throws -> UserDefaults {
if let suite {
guard let suiteDefaults = UserDefaults(suiteName: suite) else {
@ -135,6 +143,11 @@ actor UserDefaultsHelper {
return defaults
}
/// Resolves App Group `UserDefaults` or throws if invalid.
///
/// - Parameter identifier: App Group identifier.
/// - Returns: The resolved App Group defaults.
/// - Throws: ``StorageError/invalidAppGroupIdentifier(_:)`` if invalid.
private func appGroupDefaults(for identifier: String) throws -> UserDefaults {
guard let defaults = UserDefaults(suiteName: identifier) else {
throw StorageError.invalidAppGroupIdentifier(identifier)

10
Sources/LocalData/Migrations/AppVersionConditionalMigration.swift
View File

@ -1,7 +1,10 @@
import Foundation
/// Conditional migration that runs only when the app version is below a threshold.
public struct AppVersionConditionalMigration<Value: Codable & Sendable>: ConditionalMigration {
///
/// Use this wrapper to keep a legacy migration in place for older app versions
/// while allowing newer versions to skip it.
public struct AppVersionConditionalMigration<Value: Codable & Sendable>: StorageMigration {
/// Destination key for the migration.
public let destinationKey: StorageKey<Value>
/// Minimum app version required to skip this migration.
@ -10,6 +13,11 @@ public struct AppVersionConditionalMigration<Value: Codable & Sendable>: Conditi
public let fallbackMigration: AnyStorageMigration
/// Creates a version-gated migration.
///
/// - Parameters:
/// - destinationKey: The key that receives migrated data.
/// - minAppVersion: The minimum app version that should *skip* the migration.
/// - fallbackMigration: The migration to run when the version condition is met.
public init(
destinationKey: StorageKey<Value>,
minAppVersion: String,

20
Sources/LocalData/Migrations/DefaultAggregatingMigration.swift
View File

@ -1,6 +1,10 @@
import Foundation
/// Default migration that aggregates multiple source values into one destination value.
///
/// Use this migration when you need to combine multiple legacy keys into a single
/// destination value (for example, building a new composite model from several
/// old preferences).
public struct DefaultAggregatingMigration<Value: Codable & Sendable>: AggregatingMigration {
/// Destination key for aggregated data.
public let destinationKey: StorageKey<Value>
@ -10,6 +14,11 @@ public struct DefaultAggregatingMigration<Value: Codable & Sendable>: Aggregatin
public let aggregateAction: @Sendable ([AnyCodable]) async throws -> Value
/// Creates an aggregating migration with a custom aggregation closure.
///
/// - Parameters:
/// - destinationKey: The key that receives the aggregated value.
/// - sourceKeys: The legacy keys to read and aggregate.
/// - aggregate: Closure that combines source values into a destination value.
public init(
destinationKey: StorageKey<Value>,
sourceKeys: [AnyStorageKey],
@ -30,6 +39,11 @@ public struct DefaultAggregatingMigration<Value: Codable & Sendable>: Aggregatin
/// Determines whether the migration should run.
///
/// The migration runs when:
/// - the destination is allowed on the current platform
/// - the destination does not already exist
/// - at least one source key contains data
///
/// - Parameters:
/// - router: The storage router used to query state.
/// - context: Migration context for conditional checks.
@ -53,6 +67,12 @@ public struct DefaultAggregatingMigration<Value: Codable & Sendable>: Aggregatin
/// Executes the migration and returns a result.
///
/// The migration:
/// 1. Reads each source descriptor.
/// 2. Applies security to decode the raw data.
/// 3. Aggregates values into a destination value.
/// 4. Writes the destination value and deletes sources.
///
/// - Parameters:
/// - router: The storage router used to read and write values.
/// - context: Migration context for conditional checks.

19
Sources/LocalData/Migrations/DefaultTransformingMigration.swift
View File

@ -1,6 +1,9 @@
import Foundation
/// Default migration that transforms a single source value into a destination value.
///
/// Use this migration when the destination value type differs from the legacy
/// type or when you need to normalize/clean legacy data before storage.
public struct DefaultTransformingMigration<SourceValue: Codable & Sendable, DestinationValue: Codable & Sendable>: TransformingMigration {
/// Destination key for the transformed value.
public let destinationKey: StorageKey<DestinationValue>
@ -10,6 +13,11 @@ public struct DefaultTransformingMigration<SourceValue: Codable & Sendable, Dest
public let transformAction: @Sendable (SourceValue) async throws -> DestinationValue
/// Creates a transforming migration with a custom transform closure.
///
/// - Parameters:
/// - destinationKey: The key that receives the transformed value.
/// - sourceKey: The legacy key providing the source value.
/// - transform: Closure that converts the source value into the destination type.
public init(
destinationKey: StorageKey<DestinationValue>,
sourceKey: StorageKey<SourceValue>,
@ -30,6 +38,11 @@ public struct DefaultTransformingMigration<SourceValue: Codable & Sendable, Dest
/// Determines whether the migration should run.
///
/// The migration runs when:
/// - the destination is allowed on the current platform
/// - the destination does not already exist
/// - the source key contains data
///
/// - Parameters:
/// - router: The storage router used to query state.
/// - context: Migration context for conditional checks.
@ -47,6 +60,12 @@ public struct DefaultTransformingMigration<SourceValue: Codable & Sendable, Dest
/// Executes the migration and returns a result.
///
/// The migration:
/// 1. Reads the source value.
/// 2. Transforms it into the destination type.
/// 3. Writes the destination value.
/// 4. Deletes the source key.
///
/// - Parameters:
/// - router: The storage router used to read and write values.
/// - context: Migration context for conditional checks.

18
Sources/LocalData/Migrations/SimpleLegacyMigration.swift
View File

@ -1,6 +1,9 @@
import Foundation
/// Simple 1:1 legacy migration from a single source key.
///
/// Use this migration when the source and destination value types are identical
/// and no transformation is required.
public struct SimpleLegacyMigration<Value: Codable & Sendable>: StorageMigration {
/// Destination key for migrated data.
public let destinationKey: StorageKey<Value>
@ -8,6 +11,10 @@ public struct SimpleLegacyMigration<Value: Codable & Sendable>: StorageMigration
public let sourceKey: AnyStorageKey
/// Creates a migration from a legacy key to a destination key.
///
/// - Parameters:
/// - destinationKey: The key that receives migrated data.
/// - sourceKey: The legacy key to read and remove.
public init(destinationKey: StorageKey<Value>, sourceKey: AnyStorageKey) {
self.destinationKey = destinationKey
self.sourceKey = sourceKey
@ -15,6 +22,11 @@ public struct SimpleLegacyMigration<Value: Codable & Sendable>: StorageMigration
/// Determines whether the migration should run.
///
/// The migration runs when:
/// - the destination is allowed on the current platform
/// - the destination does not already exist
/// - the source key contains data
///
/// - Parameters:
/// - router: The storage router used to query state.
/// - context: Migration context for conditional checks.
@ -32,6 +44,12 @@ public struct SimpleLegacyMigration<Value: Codable & Sendable>: StorageMigration
/// Executes the migration and returns a result.
///
/// The migration:
/// 1. Reads raw source data.
/// 2. Removes legacy security (if needed).
/// 3. Decodes into the destination value type.
/// 4. Writes to the destination and deletes the source.
///
/// - Parameters:
/// - router: The storage router used to read and write values.
/// - context: Migration context for conditional checks.

19
Sources/LocalData/Models/AnyStorageKey.swift
View File

@ -1,9 +1,15 @@
/// Type-erased wrapper around ``StorageKey`` for catalogs and audits.
///
/// `StorageKey` is generic over its `Value` type, so heterogeneous keys cannot
/// be stored in a single array without type erasure. `AnyStorageKey` captures
/// the descriptor and optional migration, enabling catalog registration and
/// audit reporting.
public struct AnyStorageKey: Sendable {
/// Snapshot of key metadata for auditing and storage operations.
public internal(set) var descriptor: StorageKeyDescriptor
/// Optional migration associated with the key.
public internal(set) var migration: AnyStorageMigration?
/// Migration executor captured from the original key.
private let migrateAction: @Sendable (StorageRouter) async throws -> Void
/// Creates a type-erased key from a typed ``StorageKey``.
@ -17,6 +23,12 @@ public struct AnyStorageKey: Sendable {
}
}
/// Internal initializer for constructing modified wrappers.
///
/// - Parameters:
/// - descriptor: Descriptor describing the key.
/// - migration: Optional migration.
/// - migrateAction: Closure to execute migration for the key.
private init(
descriptor: StorageKeyDescriptor,
migration: AnyStorageMigration?,
@ -30,11 +42,15 @@ public struct AnyStorageKey: Sendable {
/// Convenience factory for creating a type-erased key.
///
/// - Parameter key: The concrete key to erase.
/// - Returns: A type-erased key wrapper.
public static func key<Value>(_ key: StorageKey<Value>) -> AnyStorageKey {
AnyStorageKey(key)
}
/// Internal use: Returns a copy of this key with the catalog name set.
///
/// - Parameter name: Catalog name to assign.
/// - Returns: A new type-erased key with the catalog name applied.
internal func withCatalog(_ name: String) -> AnyStorageKey {
AnyStorageKey(
descriptor: descriptor.withCatalog(name),
@ -44,6 +60,9 @@ public struct AnyStorageKey: Sendable {
}
/// Internal use: Triggers the migration logic for this key.
///
/// - Parameter router: Router used to perform the migration.
/// - Throws: Migration or storage errors.
internal func migrate(on router: StorageRouter) async throws {
try await migrateAction(router)
}

9
Sources/LocalData/Models/AnyStorageMigration.swift
View File

@ -1,11 +1,20 @@
import Foundation
/// Type-erased wrapper for ``StorageMigration`` for use in catalogs and registrations.
///
/// `StorageMigration` is a protocol with an associated type, which makes it
/// difficult to store heterogeneous migrations in a single collection. This
/// wrapper captures the migration's behavior and destination descriptor while
/// preserving sendability.
public struct AnyStorageMigration: Sendable {
/// Descriptor for the migration destination key.
///
/// Useful for auditing and for determining the target of the migration.
public let destinationDescriptor: StorageKeyDescriptor
/// Captured closure that decides whether migration should run.
private let shouldMigrateAction: @Sendable (StorageRouter, MigrationContext) async throws -> Bool
/// Captured closure that executes the migration.
private let migrateAction: @Sendable (StorageRouter, MigrationContext) async throws -> MigrationResult
/// Creates a type-erased migration from a concrete migration.

11
Sources/LocalData/Models/FileDirectory.swift
View File

@ -1,15 +1,26 @@
import Foundation
/// File system directory for file-based storage.
///
/// Use this enum to describe where a file should live within the app sandbox
/// or a custom file URL.
public enum FileDirectory: Sendable, Hashable {
/// App documents directory.
///
/// Best for user-facing or critical data that should be backed up.
case documents
/// App caches directory.
///
/// Best for temporary or re-creatable data that may be purged by the system.
case caches
/// Custom directory URL.
///
/// Use this to scope storage to a custom location (including App Group paths).
case custom(URL)
/// Resolves the directory to a concrete URL.
///
/// - Returns: The resolved directory URL.
public func url() -> URL {
switch self {
case .documents:

7
Sources/LocalData/Models/KeyMaterialSource.swift
View File

@ -1,11 +1,18 @@
import Foundation
/// Identifier for external key material providers.
///
/// Use this type to register and reference external key material when using
/// ``SecurityPolicy/EncryptionPolicy/external(source:keyDerivation:)``.
public struct KeyMaterialSource: Hashable, Sendable {
/// Stable identifier for the provider or key source.
///
/// This should be deterministic and consistent across app launches.
public let id: String
/// Creates a new key material source identifier.
///
/// - Parameter id: Stable identifier for the external key provider.
public init(id: String) {
self.id = id
}

10
Sources/LocalData/Models/MigrationContext.swift
View File

@ -1,6 +1,9 @@
import Foundation
/// Context information available for conditional migrations.
///
/// Migrations use this context to decide whether they should run and to tailor
/// behavior based on app version, device, system state, and historical data.
public struct MigrationContext: Sendable {
/// Current app version string.
public let appVersion: String
@ -14,6 +17,13 @@ public struct MigrationContext: Sendable {
public let systemInfo: SystemInfo
/// Creates a migration context with optional overrides.
///
/// - Parameters:
/// - appVersion: Current app version string. Defaults to the bundle version.
/// - deviceInfo: Device metadata for platform checks.
/// - migrationHistory: Historical migration timestamps by key name.
/// - userPreferences: Optional preferences influencing migration behavior.
/// - systemInfo: System information snapshot.
public init(
appVersion: String = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "Unknown",
deviceInfo: DeviceInfo = .current,

3
Sources/LocalData/Models/MigrationError.swift
View File

@ -1,6 +1,9 @@
import Foundation
/// Migration-specific error types.
///
/// These errors describe why a migration failed or could not run, and are used
/// in ``MigrationResult`` for reporting.
public enum MigrationError: Error, Sendable, Equatable {
/// Validation failed before migration could run.
case validationFailed(String)

33
Sources/LocalData/Models/MigrationResult.swift
View File

@ -1,19 +1,42 @@
import Foundation
/// Result of a migration operation with detailed information.
/// Records the outcome of a migration along with counts, errors, and metadata.
///
/// `MigrationResult` is the canonical payload returned by migrations so callers can
/// surface success/failure, auditing details, and performance data in a consistent way.
/// It is intentionally lightweight and `Sendable` so it can cross concurrency boundaries.
public struct MigrationResult: Sendable {
/// Whether the migration completed successfully.
/// Indicates whether the migration completed without fatal errors.
///
/// A value of `false` does not always mean that no data moved; consult
/// `migratedCount` and `errors` for partial outcomes.
public let success: Bool
/// Number of values migrated.
/// Number of items or records migrated during the operation.
///
/// This count is used for audit logging and metrics. Its meaning depends on the
/// migration type (for example, key-by-key versus batch).
public let migratedCount: Int
/// Errors captured during migration.
/// Errors captured while the migration executed.
///
/// Consumers should surface these to developers and use them to decide on retries.
public let errors: [MigrationError]
/// Additional metadata provided by the migration.
/// Additional metadata emitted by the migration for diagnostics or reporting.
///
/// The dictionary must only contain `AnyCodable` values so results remain portable.
public let metadata: [String: AnyCodable]
/// Duration of the migration in seconds.
///
/// Use this value for instrumentation and to flag unusually slow migrations.
public let duration: TimeInterval
/// Creates a migration result with optional details.
///
/// - Parameters:
/// - success: Whether the migration completed without fatal errors.
/// - migratedCount: Number of items migrated. Defaults to `0`.
/// - errors: Errors captured during the migration. Defaults to an empty array.
/// - metadata: Metadata emitted by the migration. Defaults to an empty dictionary.
/// - duration: Duration in seconds. Defaults to `0`.
public init(
success: Bool,
migratedCount: Int = 0,

19
Sources/LocalData/Models/PlatformAvailability.swift
View File

@ -1,20 +1,35 @@
import Foundation
/// Specifies which platforms a storage key is allowed to run on.
/// Declares which platforms a storage key can be used on.
///
/// `PlatformAvailability` guides the router when enforcing platform-specific usage.
/// For example, watch-only keys prevent accidental reads on iOS, while sync-enabled
/// keys signal that watch-to-phone data flows should be configured.
public enum PlatformAvailability: Sendable {
/// Available on iOS and watchOS (small data only on watch).
///
/// Use this for data that is safe to exist on both devices without explicit sync.
case all
/// Available only on iOS (large or sensitive data).
///
/// Prefer this for data that is too large or too sensitive for watch storage.
case phoneOnly
/// Available only on watchOS.
///
/// Use this for watch-local data that should not be mirrored to iPhone.
case watchOnly
/// Available on iOS and watchOS with explicit sync behavior.
///
/// Use this when your key participates in a defined sync strategy.
case phoneWithWatchSync
}
/// Convenience helpers for platform checks.
public extension PlatformAvailability {
/// Returns `true` if the key should be available on the given platform.
/// Returns `true` when the key is permitted on the supplied platform.
///
/// - Parameter platform: The runtime platform to evaluate.
/// - Returns: `true` if the key can be used on the platform, otherwise `false`.
func isAvailable(on platform: Platform) -> Bool {
switch self {
case .all:

33
Sources/LocalData/Models/SecurityPolicy.swift
View File

@ -2,40 +2,71 @@ import Foundation
import CryptoKit
import Security
/// Security policy for a ``StorageKey``.
/// Describes how a ``StorageKey`` secures its persisted data.
///
/// A `SecurityPolicy` is attached to each key so the storage layer can enforce
/// encryption or Keychain placement consistently across the app.
public enum SecurityPolicy: Equatable, Sendable {
/// Stores data without additional security.
///
/// Use this only for non-sensitive, non-personal data.
case none
/// Encrypts data before storage using the specified policy.
///
/// The encryption policy describes the algorithm and key derivation strategy.
case encrypted(EncryptionPolicy)
/// Stores data directly in the Keychain with accessibility and access control options.
///
/// Use this for credentials or secrets that must remain in Keychain storage.
case keychain(accessibility: KeychainAccessibility, accessControl: KeychainAccessControl?)
/// Recommended security policy for most sensitive data.
///
/// This defaults to the recommended encryption policy to keep data encrypted at rest.
public static let recommended: SecurityPolicy = .encrypted(.recommended)
/// Encryption algorithm and key derivation settings.
///
/// Use these options to align with organizational security requirements.
public enum EncryptionPolicy: Equatable, Sendable {
/// AES-256-GCM encryption.
///
/// Choose when AES is preferred for compliance or interoperability reasons.
case aes256(keyDerivation: KeyDerivation)
/// ChaCha20-Poly1305 encryption.
///
/// This is the recommended default for modern Apple platforms.
case chacha20Poly1305(keyDerivation: KeyDerivation)
/// External key material with key derivation.
///
/// Use this when key material is provided by an HSM, secure enclave, or other source.
case external(source: KeyMaterialSource, keyDerivation: KeyDerivation)
/// Recommended encryption policy for most cases.
///
/// Uses ChaCha20-Poly1305 with HKDF-derived keys.
public static let recommended: EncryptionPolicy = .chacha20Poly1305(keyDerivation: .hkdf())
/// Convenience for external key material with default HKDF.
///
/// - Parameter source: The external key material provider.
/// - Returns: A policy configured with the default HKDF parameters.
public static func external(source: KeyMaterialSource) -> EncryptionPolicy {
.external(source: source, keyDerivation: .hkdf())
}
}
/// Key derivation algorithms for encryption keys.
///
/// These settings allow you to tune how raw key material is transformed into
/// encryption keys used by the selected algorithm.
public enum KeyDerivation: Equatable, Sendable {
/// PBKDF2 with optional iterations and salt.
///
/// Provide `iterations` and `salt` when you need deterministic derivation.
case pbkdf2(iterations: Int? = nil, salt: Data? = nil)
/// HKDF with optional salt and info.
///
/// Supply `info` to domain-separate keys for distinct purposes.
case hkdf(salt: Data? = nil, info: Data? = nil)
}
}

13
Sources/LocalData/Models/Serializer.swift
View File

@ -1,12 +1,21 @@
import Foundation
/// Encodes and decodes values for storage.
///
/// `Serializer` packages paired encode/decode closures with a human-readable name
/// so storage services can serialize values consistently and report the format used.
public struct Serializer<Value: Codable & Sendable>: Sendable, CustomStringConvertible {
/// Encodes a value into `Data`.
///
/// The closure must be `Sendable` so it can execute safely across concurrency contexts.
public let encode: @Sendable (Value) throws -> Data
/// Decodes a value from `Data`.
///
/// The closure must be `Sendable` so it can execute safely across concurrency contexts.
public let decode: @Sendable (Data) throws -> Value
/// Human-readable serializer name used in audit reports.
///
/// Keep names stable so audit output is predictable and searchable.
public let name: String
/// Creates a custom serializer.
@ -26,6 +35,8 @@ public struct Serializer<Value: Codable & Sendable>: Sendable, CustomStringConve
}
/// Description used by `CustomStringConvertible`.
///
/// Mirrors the `name` so logs and debug output show the configured serializer.
public var description: String { name }
/// JSON serializer using `JSONEncoder` and `JSONDecoder`.
@ -70,6 +81,8 @@ public struct Serializer<Value: Codable & Sendable>: Sendable, CustomStringConve
public extension Serializer where Value == Data {
/// Serializer that passes through raw `Data`.
///
/// Use this when the caller already owns the encoding format.
///
/// - Returns: A serializer that returns `Data` unchanged.
static var data: Serializer<Value> {
Serializer<Value>(encode: { $0 }, decode: { $0 }, name: "data")

15
Sources/LocalData/Models/StorageDomain.swift
View File

@ -1,17 +1,32 @@
import Foundation
/// Storage location for a ``StorageKey``.
///
/// `StorageDomain` describes where values are stored and which storage backend is used.
/// The router interprets these cases to route reads and writes to the correct helper.
public enum StorageDomain: Sendable, Equatable {
/// Standard `UserDefaults` using the provided suite name.
///
/// Pass `nil` to target the default `UserDefaults` suite.
case userDefaults(suite: String?)
/// App group `UserDefaults` using the provided group identifier.
///
/// Use this for data shared with extensions on the same device.
case appGroupUserDefaults(identifier: String?)
/// Keychain storage using the provided service identifier.
///
/// Keychain storage is used for sensitive or credential-like data.
case keychain(service: String?)
/// File system storage in the specified directory.
///
/// Suitable for larger values that should not live in defaults or Keychain.
case fileSystem(directory: FileDirectory)
/// Encrypted file system storage in the specified directory.
///
/// Values are encrypted before being written to the file system.
case encryptedFileSystem(directory: FileDirectory)
/// App group file storage using the group identifier and directory.
///
/// Use this for file-backed data that needs to be shared with app extensions.
case appGroupFileSystem(identifier: String?, directory: FileDirectory)
}

35
Sources/LocalData/Models/StorageError.swift
View File

@ -1,37 +1,68 @@
import Foundation
/// Errors thrown by storage operations and migrations.
///
/// `StorageError` standardizes failures across storage helpers so callers can handle
/// issues consistently, whether the underlying storage is defaults, files, or Keychain.
public enum StorageError: Error, Equatable {
/// Failed to encode a value.
///
/// This indicates the serializer could not transform a value into `Data`.
case serializationFailed
/// Failed to decode stored data.
///
/// This typically means the stored payload does not match the expected type.
case deserializationFailed
/// Failed to apply or remove security for stored data.
///
/// This error is used when encryption or decryption fails.
case securityApplicationFailed
/// Underlying Keychain error.
///
/// The associated `OSStatus` comes from Security framework APIs.
case keychainError(OSStatus)
/// File system error description.
///
/// Uses a `String` to preserve a descriptive message while remaining `Equatable`.
case fileError(String) // Changed from Error to String for easier Equatable conformance
/// A phone-only key was accessed on watchOS.
///
/// The associated value is the key name.
case phoneOnlyKeyAccessedOnWatch(String)
/// A watch-only key was accessed on iOS.
///
/// The associated value is the key name.
case watchOnlyKeyAccessedOnPhone(String)
/// Invalid UserDefaults suite name.
///
/// The associated value is the invalid suite identifier.
case invalidUserDefaultsSuite(String)
/// Invalid App Group identifier.
///
/// The associated value is the invalid group identifier.
case invalidAppGroupIdentifier(String)
/// Sync payload exceeded the configured maximum size.
///
/// The key cannot be synced because the payload is too large.
case dataTooLargeForSync
/// No value exists for the requested key.
case notFound
/// The key is not registered in any catalog.
///
/// The associated value is the missing key name.
case unregisteredKey(String)
/// Duplicate key names detected during registration.
///
/// The associated array lists the duplicate key names.
case duplicateRegisteredKeys([String])
/// Missing or empty key description.
///
/// The associated value is the key name missing the description.
case missingDescription(String)
/// Compares two storage errors for equality.
///
/// This custom equality handles associated values, including `OSStatus`.
public static func == (lhs: StorageError, rhs: StorageError) -> Bool {
switch (lhs, rhs) {
case (.serializationFailed, .serializationFailed),
@ -59,4 +90,8 @@ public enum StorageError: Error, Equatable {
}
}
/// `StorageError` includes `OSStatus` values which are not `Sendable` by default.
///
/// The enum is effectively immutable, so we mark it `@unchecked Sendable` to allow
/// it to cross concurrency boundaries.
extension StorageError: @unchecked Sendable {}

26
Sources/LocalData/Models/StorageKeyDescriptor.swift
View File

@ -1,28 +1,54 @@
import Foundation
/// Snapshot of a ``StorageKey`` used for audit and registration.
///
/// `StorageKeyDescriptor` captures the immutable metadata needed for audits, duplicate
/// detection, and catalog reporting without carrying the key's generic type.
public struct StorageKeyDescriptor: Sendable, CustomStringConvertible {
/// Key name within its domain.
///
/// This is the primary identifier used for duplicate detection.
public let name: String
/// Storage domain for the key.
///
/// The router uses this to determine which storage helper should be used.
public let domain: StorageDomain
/// Security policy applied to the key.
///
/// Indicates whether encryption or Keychain placement is required.
public let security: SecurityPolicy
/// Serializer name used for encoding/decoding.
///
/// This is recorded for audit output; the serializer itself remains on the key.
public let serializer: String
/// String representation of the value type.
///
/// Useful for diagnostics when reviewing audit reports.
public let valueType: String
/// Owning module or feature name.
///
/// Use this to identify the feature responsible for the stored data.
public let owner: String
/// Platform availability for the key.
///
/// Governs which runtime platforms are allowed to access the key.
public let availability: PlatformAvailability
/// Sync policy for WatchConnectivity.
///
/// Used when determining sync eligibility and constraints.
public let syncPolicy: SyncPolicy
/// Human-readable description for audit reports.
///
/// Descriptions are required to keep audit results interpretable.
public let description: String
/// Optional catalog name the key belongs to.
///
/// Catalog names aid in grouping keys by feature or module.
public let catalog: String?
/// Internal initializer used by factories and audits.
///
/// Callers should prefer `from(_:)` unless building descriptors manually.
init(
name: String,
domain: StorageDomain,

9
Sources/LocalData/Models/SyncPolicy.swift
View File

@ -1,11 +1,20 @@
import Foundation
/// Defines how a key participates in WatchConnectivity sync.
///
/// `SyncPolicy` is interpreted by sync helpers to decide if and when data should
/// be pushed between iPhone and Apple Watch.
public enum SyncPolicy: Sendable {
/// No sync behavior.
///
/// Use this for keys that should remain device-local.
case never
/// Sync only when the app explicitly requests it.
///
/// Use this when you need full control over sync timing.
case manual
/// Automatically sync when data size is below the configured threshold.
///
/// Use this for small payloads that should stay in sync without manual triggers.
case automaticSmall
}

3
Sources/LocalData/Protocols/AggregatingMigration.swift
View File

@ -1,3 +1,6 @@
/// Defines migrations that aggregate multiple source keys into a single destination.
///
/// Use this protocol when a new storage key is derived from multiple legacy values.
import Foundation
/// Migration protocol that combines multiple sources into a single destination.

4
Sources/LocalData/Protocols/ConditionalMigration.swift
View File

@ -1,4 +0,0 @@
import Foundation
/// Marker protocol for migrations that primarily use conditional checks.
public protocol ConditionalMigration: StorageMigration {}

3
Sources/LocalData/Protocols/KeyMaterialProviding.swift
View File

@ -1,3 +1,6 @@
/// Supplies encryption key material to support external key sources.
///
/// Conformers provide raw bytes used by ``SecurityPolicy.EncryptionPolicy.external``.
import Foundation
/// Supplies external key material for encryption policies.

3
Sources/LocalData/Protocols/KeychainStoring.swift
View File

@ -1,3 +1,6 @@
/// Defines the Keychain operations required by the storage layer.
///
/// This protocol enables swapping concrete Keychain implementations for testing.
import Foundation
/// Protocol defining the interface for Keychain operations.

3
Sources/LocalData/Protocols/StorageKeyCatalog.swift
View File

@ -1,3 +1,6 @@
// Defines catalog types that group storage keys for registration and auditing.
//
// Catalogs are the mechanism used by the router to validate keys and detect duplicates.
/// Collection of storage keys used for registration and auditing.
public protocol StorageKeyCatalog: Sendable {
/// Human-readable catalog name used in audit reports.

3
Sources/LocalData/Protocols/StorageMigration.swift
View File

@ -1,3 +1,6 @@
/// Defines the core migration contract used by the storage router.
///
/// All migration types build on this protocol to move or transform stored data.
import Foundation
/// Core migration protocol for moving data into a destination ``StorageKey``.

3
Sources/LocalData/Protocols/StorageProviding.swift
View File

@ -1,3 +1,6 @@
/// Defines the storage operations required by concrete backends.
///
/// Storage helpers conform to this protocol to provide a common API surface.
import Foundation
/// Abstraction for basic storage operations.

3
Sources/LocalData/Protocols/TransformingMigration.swift
View File

@ -1,3 +1,6 @@
/// Defines migrations that transform a source value into a new destination value.
///
/// Use this protocol when a single legacy key can be mapped to a new schema.
import Foundation
/// Migration protocol that transforms a source value into a destination value.

140
Sources/LocalData/Services/StorageRouter.swift
View File

@ -1,16 +1,23 @@
import Foundation
/// The main storage router that coordinates all storage operations.
/// Uses specialized helper actors for each storage domain.
/// Central coordinator for all LocalData storage operations.
///
/// `StorageRouter` orchestrates serialization, security, storage domain routing,
/// catalog validation, migrations, and WatchConnectivity sync. Use the shared
/// instance for app-wide access and register catalogs at launch to enable
/// auditability and duplicate key detection.
/// `StorageRouter` orchestrates:
/// - serialization and deserialization through ``Serializer``
/// - security policies through ``SecurityPolicy``
/// - storage routing across ``StorageDomain``
/// - catalog validation and audit tracking
/// - migrations and migration history
/// - WatchConnectivity sync coordination
///
/// Use the shared instance for app-wide access and register catalogs at launch
/// to enable auditability and duplicate key detection.
public actor StorageRouter: StorageProviding {
/// Shared router instance for app-wide storage access.
///
/// Prefer this shared instance in production code. For tests, inject a
/// custom instance with isolated helpers.
public static let shared = StorageRouter()
private var catalogRegistries: [String: [AnyStorageKey]] = [:]
@ -25,8 +32,15 @@ public actor StorageRouter: StorageProviding {
/// Initializes a new router with injected helpers.
///
/// - Parameters:
/// - keychain: Keychain helper implementation.
/// - encryption: Encryption helper implementation.
/// - file: File storage helper implementation.
/// - defaults: UserDefaults helper implementation.
/// - sync: Sync helper implementation.
///
/// - Important: Internal for testing isolation via `@testable import`.
/// Production code should use ``StorageRouter/shared``.
/// Production code should use ``StorageRouter/shared``.
internal init(
keychain: KeychainStoring = KeychainHelper.shared,
encryption: EncryptionHelper = .shared,
@ -267,6 +281,12 @@ public actor StorageRouter: StorageProviding {
}
}
/// Checks existence using a descriptor (used by migrations and audits).
/// Checks whether data exists for a descriptor.
///
/// - Parameter descriptor: Descriptor describing the storage location.
/// - Returns: `true` if data exists, otherwise `false`.
/// - Throws: Storage or configuration errors from the underlying helper.
internal func exists(descriptor: StorageKeyDescriptor) async throws -> Bool {
switch descriptor.domain {
case .userDefaults(let suite):
@ -291,6 +311,11 @@ public actor StorageRouter: StorageProviding {
// MARK: - Platform Validation
/// Enforces platform availability rules for a key.
///
/// - Parameter key: The key being accessed.
/// - Throws: ``StorageError/phoneOnlyKeyAccessedOnWatch(_:)`` or
/// ``StorageError/watchOnlyKeyAccessedOnPhone(_:)``.
nonisolated private func validatePlatformAvailability<Value>(for key: StorageKey<Value>) throws {
#if os(watchOS)
if key.availability == .phoneOnly {
@ -303,6 +328,10 @@ public actor StorageRouter: StorageProviding {
#endif
}
/// Validates that a key is present in the registered catalog set.
///
/// - Parameter key: The key being accessed.
/// - Throws: ``StorageError/unregisteredKey(_:)`` when catalogs are registered and the key is missing.
private func validateCatalogRegistration<Value>(for key: StorageKey<Value>) throws {
guard !registeredKeys.isEmpty else { return }
guard registeredKeys[key.name] != nil else {
@ -317,6 +346,9 @@ public actor StorageRouter: StorageProviding {
}
}
/// Detects test environments to avoid noisy assertions in tests.
///
/// This is a best-effort check using environment variables and XCTest classes.
private var isRunningTests: Bool {
// Broad check for any test-related environment variables or classes
if ProcessInfo.processInfo.environment.keys.contains(where: {
@ -327,6 +359,10 @@ public actor StorageRouter: StorageProviding {
return NSClassFromString("XCTestCase") != nil || NSClassFromString("Testing.Test") != nil
}
/// Ensures no duplicate key names exist within a catalog.
///
/// - Parameter entries: The keys being registered.
/// - Throws: ``StorageError/duplicateRegisteredKeys(_:)`` when duplicates are found.
private func validateUniqueKeys(_ entries: [AnyStorageKey]) throws {
var exactNames: [String: Int] = [:]
var duplicates: [String] = []
@ -344,6 +380,10 @@ public actor StorageRouter: StorageProviding {
}
}
/// Ensures all keys have non-empty descriptions for audits.
///
/// - Parameter entries: The keys being registered.
/// - Throws: ``StorageError/missingDescription(_:)`` when descriptions are empty.
private func validateDescription(_ entries: [AnyStorageKey]) throws {
let missing = entries
.map(\.descriptor)
@ -357,6 +397,11 @@ public actor StorageRouter: StorageProviding {
// MARK: - Migration
/// Attempts a migration and returns the migrated value if successful.
///
/// - Parameter key: Destination key for migration.
/// - Returns: The migrated value when migration succeeds.
/// - Throws: ``MigrationError`` if the migration reports an error.
private func attemptMigration<Value>(for key: StorageKey<Value>) async throws -> Value? {
guard let migration = resolveMigration(for: key) else { return nil }
@ -380,18 +425,34 @@ public actor StorageRouter: StorageProviding {
return nil
}
/// Resolves the migration attached to a key, if any.
///
/// - Parameter key: Key that may contain a migration builder.
/// - Returns: The resolved type-erased migration, or `nil`.
private func resolveMigration<Value>(for key: StorageKey<Value>) -> AnyStorageMigration? {
key.migration
}
/// Builds a migration context with the router's current history.
///
/// - Returns: A new ``MigrationContext`` populated with history.
internal func buildMigrationContext() -> MigrationContext {
MigrationContext(migrationHistory: migrationHistory)
}
/// Records a successful migration timestamp for a key.
///
/// - Parameter descriptor: Descriptor of the migrated key.
internal func recordMigration(for descriptor: StorageKeyDescriptor) {
migrationHistory[descriptor.name] = Date()
}
/// Evaluates platform and sync prerequisites for migration.
///
/// - Parameters:
/// - key: Destination key to migrate into.
/// - context: Migration context describing the environment.
/// - Returns: `true` if migration is allowed.
internal func shouldAllowMigration<Value>(
for key: StorageKey<Value>,
context: MigrationContext
@ -409,6 +470,13 @@ public actor StorageRouter: StorageProviding {
// MARK: - Serialization
/// Encodes a value to data using the provided serializer.
///
/// - Parameters:
/// - value: The value to encode.
/// - serializer: Serializer to use.
/// - Returns: Encoded `Data`.
/// - Throws: ``StorageError/serializationFailed``.
private func serialize<Value: Codable & Sendable>(
_ value: Value,
with serializer: Serializer<Value>
@ -420,6 +488,13 @@ public actor StorageRouter: StorageProviding {
}
}
/// Decodes data to a value using the provided serializer.
///
/// - Parameters:
/// - data: The data to decode.
/// - serializer: Serializer to use.
/// - Returns: Decoded value.
/// - Throws: ``StorageError/deserializationFailed``.
nonisolated internal func deserialize<Value: Codable & Sendable>(
_ data: Data,
with serializer: Serializer<Value>
@ -433,6 +508,14 @@ public actor StorageRouter: StorageProviding {
// MARK: - Security
/// Applies encryption or decryption based on the descriptor's policy.
///
/// - Parameters:
/// - data: The data to secure or unsecure.
/// - descriptor: Descriptor describing the security policy.
/// - isEncrypt: `true` to encrypt, `false` to decrypt.
/// - Returns: Secured or unsecured data.
/// - Throws: ``StorageError/securityApplicationFailed`` if crypto fails.
internal func applySecurity(
_ data: Data,
for descriptor: StorageKeyDescriptor,
@ -466,10 +549,21 @@ public actor StorageRouter: StorageProviding {
// MARK: - Storage Operations
/// Stores secured data for a typed key.
///
/// - Parameters:
/// - data: The secured data to store.
/// - key: The destination key.
private func store<Value>(_ data: Data, for key: StorageKey<Value>) async throws {
try await store(data, for: .from(key))
}
/// Stores secured data for a key descriptor.
///
/// - Parameters:
/// - data: The secured data to store.
/// - descriptor: The storage descriptor to use.
/// - Throws: Storage or configuration errors.
private func store(_ data: Data, for descriptor: StorageKeyDescriptor) async throws {
switch descriptor.domain {
case .userDefaults(let suite):
@ -520,6 +614,11 @@ public actor StorageRouter: StorageProviding {
}
}
/// Retrieves secured data for a key descriptor.
///
/// - Parameter descriptor: The storage descriptor to read.
/// - Returns: Secured data if found, otherwise `nil`.
/// - Throws: Storage or configuration errors.
internal func retrieve(for descriptor: StorageKeyDescriptor) async throws -> Data? {
switch descriptor.domain {
case .userDefaults(let suite):
@ -544,6 +643,10 @@ public actor StorageRouter: StorageProviding {
}
}
/// Deletes data for a key descriptor.
///
/// - Parameter descriptor: The storage descriptor to delete.
/// - Throws: Storage or configuration errors.
internal func delete(for descriptor: StorageKeyDescriptor) async throws {
switch descriptor.domain {
case .userDefaults(let suite):
@ -570,6 +673,12 @@ public actor StorageRouter: StorageProviding {
// MARK: - Sync
/// Performs sync if the key's policy and availability allow it.
///
/// - Parameters:
/// - key: The key being synced.
/// - data: The secured data payload.
/// - Throws: ``StorageError/dataTooLargeForSync`` when automatic sync exceeds limits.
private func handleSync<Value>(_ key: StorageKey<Value>, data: Data) async throws {
try await sync.syncIfNeeded(
data: data,
@ -663,7 +772,12 @@ public actor StorageRouter: StorageProviding {
// MARK: - Internal Sync Handling
/// Internal method to update storage from received sync data.
/// This is called by SyncHelper when the paired device sends new context.
///
/// Called by ``SyncHelper`` when the paired device sends new context.
/// - Parameters:
/// - keyName: The storage key name.
/// - data: The secured data payload.
/// - Throws: Storage errors during write.
func updateFromSync(keyName: String, data: Data) async throws {
// Find the registered entry for this key
guard let entry = registeredKeys[keyName] else {
@ -679,6 +793,11 @@ public actor StorageRouter: StorageProviding {
// MARK: - Resolution Helpers
/// Resolves a keychain service using key defaults when needed.
///
/// - Parameter service: Explicit service, or `nil` to use defaults.
/// - Returns: Resolved service identifier.
/// - Throws: ``StorageError/keychainError(_:)`` when no service is available.
private func resolveService(_ service: String?) throws -> String {
guard let resolved = service ?? storageConfiguration.defaultKeychainService else {
Logger.error("No keychain service provided and no default configured")
@ -688,6 +807,11 @@ public actor StorageRouter: StorageProviding {
return resolved
}
/// Resolves an App Group identifier using defaults when needed.
///
/// - Parameter identifier: Explicit identifier, or `nil` to use defaults.
/// - Returns: Resolved App Group identifier.
/// - Throws: ``StorageError/invalidAppGroupIdentifier(_:)`` when no identifier is available.
private func resolveIdentifier(_ identifier: String?) throws -> String {
guard let resolved = identifier ?? storageConfiguration.defaultAppGroupIdentifier else {
Logger.error("No App Group identifier provided and no default configured")

1
Sources/LocalData/Utilities/DeviceInfo.swift
View File

@ -21,6 +21,7 @@ public struct DeviceInfo: Sendable {
/// Current device info derived from the running environment.
public static let current = DeviceInfo()
/// Builds a snapshot of the current device environment.
private init() {
#if os(iOS)
self.platform = .iOS