LocalData/README.md

# LocalData

LocalData provides a typed, discoverable namespace for persisted app data across UserDefaults, Keychain, and file storage with optional encryption.

## Architecture

The package uses a clean, modular architecture with isolated actors for thread safety:

```
StorageRouter (main entry point)
    ├── UserDefaultsHelper
    ├── KeychainHelper
    ├── FileStorageHelper
    ├── EncryptionHelper
    └── SyncHelper
```

## What Ships in the Package

### Protocols
- **StorageKey** - Define storage configuration for each data type
- **StorageProviding** - Abstraction for storage operations
- **KeyMaterialProviding** - Supplies external key material for encryption

### Services (Actors)
- **StorageRouter** - Main entry point for all storage operations
- **KeychainHelper** - Secure keychain storage
- **EncryptionHelper** - AES-256-GCM or ChaCha20-Poly1305 with PBKDF2/HKDF
- **FileStorageHelper** - File system operations
- **UserDefaultsHelper** - UserDefaults with suite support
- **SyncHelper** - WatchConnectivity sync

### Models
- **StorageDomain** - userDefaults, keychain, fileSystem, encryptedFileSystem
- **SecurityPolicy** - none, keychain, encrypted (AES-256 or ChaCha20-Poly1305)
- **Serializer** - JSON, plist, Data, or custom
- **PlatformAvailability** - all, phoneOnly, watchOnly, phoneWithWatchSync
- **SyncPolicy** - never, manual, automaticSmall
- **KeychainAccessibility** - All 7 iOS accessibility options
- **KeychainAccessControl** - All 6 access control options (biometry, passcode, etc.)
- **FileDirectory** - documents, caches, custom URL
- **StorageError** - Comprehensive error types
- **AnyCodable** - Type-erased Codable for mixed-type payloads

## Usage

### 1. Define Keys
Extend `StorageKeys` with your own key types:

```swift
import LocalData

extension StorageKeys {
    struct UserTokenKey: StorageKey {
        typealias Value = String
        
        let name = "user_token"
        let domain: StorageDomain = .keychain(service: "com.myapp")
        let security: SecurityPolicy = .keychain(
            accessibility: .afterFirstUnlock,
            accessControl: .biometryAny
        )
        let serializer: Serializer<String> = .json
        let owner = "AuthService"
        let availability: PlatformAvailability = .phoneOnly
        let syncPolicy: SyncPolicy = .never
    }
}
```
If you omit `security`, it defaults to `SecurityPolicy.recommended`.

### 2. Use StorageRouter
```swift
// Save
let key = StorageKeys.UserTokenKey()
try await StorageRouter.shared.set("token123", for: key)

// Retrieve
let token = try await StorageRouter.shared.get(key)

// Remove
try await StorageRouter.shared.remove(key)
```

## Storage Domains

| Domain | Use Case |
|--------|----------|
| `userDefaults` | Preferences, small settings |
| `keychain` | Credentials, tokens, sensitive data |
| `fileSystem` | Documents, cached data, large files |
| `encryptedFileSystem` | Sensitive files with encryption policies |

## Security Options

### Keychain Accessibility
- `whenUnlocked` - Only when device unlocked
- `afterFirstUnlock` - After first unlock until restart
- `whenUnlockedThisDeviceOnly` - No migration to new device
- `afterFirstUnlockThisDeviceOnly` - No migration
- `always` - Always accessible (least secure)
- `alwaysThisDeviceOnly` - Always, no migration
- `whenPasscodeSetThisDeviceOnly` - Requires passcode

### Access Control
- `userPresence` - Any authentication
- `biometryAny` - Face ID or Touch ID
- `biometryCurrentSet` - Current enrolled biometric only
- `devicePasscode` - Passcode only
- `biometryAnyOrDevicePasscode` - Biometric preferred, passcode fallback
- `biometryCurrentSetOrDevicePasscode` - Current biometric or passcode

### Encryption
- AES-256-GCM or ChaCha20-Poly1305
- PBKDF2-SHA256 or HKDF-SHA256 key derivation
- Configurable PBKDF2 iteration count
- Master key stored securely in keychain
- Default security policy: `SecurityPolicy.recommended` (ChaCha20-Poly1305 + HKDF)
- External key material providers can be registered via `EncryptionHelper`

```swift
struct RemoteKeyProvider: KeyMaterialProviding {
    func keyMaterial(for keyName: String) async throws -> Data {
        // Example only: fetch from service or keychain
        Data(repeating: 1, count: 32)
    }
}

let source = KeyMaterialSource(id: "remote.key")
await EncryptionHelper.shared.registerKeyMaterialProvider(RemoteKeyProvider(), for: source)

let policy: SecurityPolicy.EncryptionPolicy = .external(
    source: source,
    keyDerivation: .hkdf()
)
```

## Sync Behavior

StorageRouter can sync data to Apple Watch via WCSession when:
- `availability` is `.all` or `.phoneWithWatchSync`
- `syncPolicy` is `.manual` or `.automaticSmall` (≤100KB)
- WCSession is activated and watch is paired

The app owns WCSession activation and handling incoming updates.

## Platforms
- iOS 17+
- watchOS 10+

## Testing
- Unit tests use Swift Testing (`Testing` package)

## Storage Audit

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.

1) Define a catalog in your app that lists all keys:

```swift
struct AppStorageCatalog: StorageKeyCatalog {
    static var allKeys: [StorageKeyDescriptor] {
        [
            .from(StorageKeys.AppVersionKey(), serializer: "json"),
            .from(StorageKeys.UserPreferencesKey(), serializer: "json")
        ]
    }
}
```

2) Generate a report:

```swift
let report = StorageAuditReport.renderText(for: AppStorageCatalog.self)
print(report)
```

For dynamic key names, use a placeholder name and a note to describe how it is generated.

## Sample App
See `SecureStorgageSample` for working examples of all storage domains and security options.