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

Docs README

Browse Source 
Summary:
- Docs: README

Stats:
- 1 file changed, 20 insertions(+), 7 deletions(-)
This commit is contained in:
Matt Bruce 2026-01-14 11:41:37 -06:00
parent 3f6856f124
commit 28ab0bf475
1 changed files with 20 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@ -24,22 +24,29 @@ StorageRouter (main entry point)
### Services (Actors) ### Services (Actors)
- **StorageRouter** - Main entry point for all storage operations - **StorageRouter** - Main entry point for all storage operations
- **KeychainHelper** - Secure keychain storage
- **EncryptionHelper** - AES-256-GCM or ChaCha20-Poly1305 with PBKDF2/HKDF ### Internal Helpers (Not Public API)
- **FileStorageHelper** - File system operations These helpers are internal implementation details used by `StorageRouter`. They are not part of the public API and should not be used directly.
- **UserDefaultsHelper** - UserDefaults with suite support
- **SyncHelper** - WatchConnectivity sync - **KeychainHelper** - Reads/writes secure items with Keychain APIs.
- **EncryptionHelper** - Handles encryption/decryption and key derivation.
- **FileStorageHelper** - Reads/writes files with appropriate protection.
- **UserDefaultsHelper** - Wraps UserDefaults and suites safely.
- **SyncHelper** - Manages WatchConnectivity sync.
### Models ### Models
- **StorageDomain** - userDefaults, keychain, fileSystem, encryptedFileSystem - **StorageDomain** - userDefaults, keychain, fileSystem, encryptedFileSystem
- **SecurityPolicy** - none, keychain, encrypted (AES-256 or ChaCha20-Poly1305) - **SecurityPolicy** - none, keychain, encrypted (AES-256 or ChaCha20-Poly1305)
- **Serializer** - JSON, plist, Data, or custom - **Serializer** - JSON, plist, Data, or custom
- **KeyMaterialSource** - Identifier for external key material providers
- **PlatformAvailability** - all, phoneOnly, watchOnly, phoneWithWatchSync - **PlatformAvailability** - all, phoneOnly, watchOnly, phoneWithWatchSync
- **SyncPolicy** - never, manual, automaticSmall - **SyncPolicy** - never, manual, automaticSmall
- **KeychainAccessibility** - All 7 iOS accessibility options - **KeychainAccessibility** - All 7 iOS accessibility options
- **KeychainAccessControl** - All 6 access control options (biometry, passcode, etc.) - **KeychainAccessControl** - All 6 access control options (biometry, passcode, etc.)
- **FileDirectory** - documents, caches, custom URL - **FileDirectory** - documents, caches, custom URL
- **StorageError** - Comprehensive error types - **StorageError** - Comprehensive error types
- **StorageKeyDescriptor** - Audit snapshot of a key’s storage metadata
- **AnyStorageKey** - Type-erased storage key for catalogs
- **AnyCodable** - Type-erased Codable for mixed-type payloads - **AnyCodable** - Type-erased Codable for mixed-type payloads
## Usage ## Usage
@ -62,6 +69,7 @@ extension StorageKeys {
) )
let serializer: Serializer<String> = .json let serializer: Serializer<String> = .json
let owner = "AuthService" let owner = "AuthService"
let description = "Stores the current user auth token."
let availability: PlatformAvailability = .phoneOnly let availability: PlatformAvailability = .phoneOnly
let syncPolicy: SyncPolicy = .never let syncPolicy: SyncPolicy = .never
} }
@ -116,7 +124,7 @@ try await StorageRouter.shared.remove(key)
- Configurable PBKDF2 iteration count - Configurable PBKDF2 iteration count
- Master key stored securely in keychain - Master key stored securely in keychain
- Default security policy: `SecurityPolicy.recommended` (ChaCha20-Poly1305 + HKDF) - Default security policy: `SecurityPolicy.recommended` (ChaCha20-Poly1305 + HKDF)
- External key material providers can be registered via `EncryptionHelper` - External key material providers can be registered via `StorageRouter`
```swift ```swift
struct RemoteKeyProvider: KeyMaterialProviding { struct RemoteKeyProvider: KeyMaterialProviding {
@ -127,7 +135,7 @@ struct RemoteKeyProvider: KeyMaterialProviding {
} }
let source = KeyMaterialSource(id: "remote.key") let source = KeyMaterialSource(id: "remote.key")
await EncryptionHelper.shared.registerKeyMaterialProvider(RemoteKeyProvider(), for: source) await StorageRouter.shared.registerKeyMaterialProvider(RemoteKeyProvider(), for: source)
let policy: SecurityPolicy.EncryptionPolicy = .external( let policy: SecurityPolicy.EncryptionPolicy = .external(
source: source, source: source,
@ -155,6 +163,10 @@ The app owns WCSession activation and handling incoming updates.
LocalData can generate a catalog of all configured storage keys, even if no data has been written yet. This is useful for security reviews and compliance. LocalData can generate a catalog of all configured storage keys, even if no data has been written yet. This is useful for security reviews and compliance.
### Why `AnyStorageKey`?
`StorageKey` has an associated type (`Value`), which means you cannot store different keys in a single array using `[StorageKey]` or `some StorageKey`. Swift requires type erasure for heterogeneous protocol values, so the catalog uses `[AnyStorageKey]` and builds descriptors behind the scenes.
1) Define a catalog in your app that lists all keys: 1) Define a catalog in your app that lists all keys:
```swift ```swift
@ -185,6 +197,7 @@ do {
} }
``` ```
Each `StorageKey` must provide a human-readable `description` used in audit reports.
Dynamic key names are intentionally not supported in the core API to keep storage auditing strict and predictable. Dynamic key names are intentionally not supported in the core API to keep storage auditing strict and predictable.
If you need this later, see `FutureEnhancements.md` for a proposed design. If you need this later, see `FutureEnhancements.md` for a proposed design.