Matt Bruce
905cabc542
Summary: - Sources: update Audit, Helpers, Services - Tests: update tests for StorageCatalogTests.swift - Docs: add docs for Design, Migration, Testing Stats: - 10 files changed, 181 insertions(+), 1 deletion(-)
39 lines
2.0 KiB
Markdown
39 lines
2.0 KiB
Markdown
# LocalData Architecture and Design
|
|
|
|
## Overview
|
|
`LocalData` is a typed, discoverable namespace for persisted application data. It provides a consistent API for reading, writing, and removing data across multiple storage domains while enforcing security and serialization policies.
|
|
|
|
## Key Components
|
|
|
|
### StorageRouter
|
|
The central `actor` that coordinates all storage operations. It acts as the primary API surface and handles routing, catalog validation, and migration.
|
|
|
|
### StorageKey
|
|
A protocol that defines the metadata for a single piece of persistent data.
|
|
- **Value**: The type of the data (Codable).
|
|
- **Domain**: Where the data is stored (UserDefaults, Keychain, FileSystem, etc.).
|
|
- **Security**: How the data is secured (None, Keychain-native, or custom Encryption).
|
|
- **Serializer**: How the data is encoded to/from `Data` (JSON, Plist, etc.).
|
|
- **SyncPolicy**: Rules for syncing data between iPhone and Watch.
|
|
|
|
### Helper Actors
|
|
Specialized actors for each storage domain:
|
|
- `KeychainHelper`: Manages Keychain operations.
|
|
- `UserDefaultsHelper`: Manages UserDefaults and App Group defaults.
|
|
- `FileStorageHelper`: Manages local and App Group file storage.
|
|
- `EncryptionHelper`: Provides AES and ChaCha20 encryption.
|
|
- `SyncHelper`: Manages WatchConnectivity synchronization.
|
|
|
|
## Routing Logic
|
|
1. **Validation**: Check if the key is registered in the catalog (if registered) and if it's available on the current platform.
|
|
2. **Serialization**: Convert the value to `Data` using the specified serializer.
|
|
3. **Security (Apply)**: Apply encryption or security policies.
|
|
4. **Storage**: Delegate the write operation to the appropriate helper.
|
|
5. **Sync**: Trigger a sync update if the policy allows.
|
|
|
|
## Security Model
|
|
- **None**: Data is stored as-is (e.g., standard UserDefaults).
|
|
- **Keychain**: Native hardware security using the iOS Keychain.
|
|
- **Encrypted**: Custom encryption (AES-256-GCM or ChaCha20-Poly1305) with key derivation (PBKDF2/HKDF).
|
|
- **File Protection**: Uses iOS "Complete File Protection" for encrypted file system writes.
|