SecureStorageSample

A sample iOS app demonstrating the LocalData package capabilities for secure, typed storage across multiple domains.

Features

This app provides interactive demos for all LocalData storage options:

Screen	Demo	Storage Domain
UserDefaults	Save/load/remove values	UserDefaults
Keychain	Secure credentials with biometrics	Keychain
File Storage	User profiles with Codable models	File System
Encrypted Storage	Encrypted logs (AES or ChaCha20)	Encrypted File System
Platform Sync Lab	Platform availability & sync policies	Multiple

The project also includes a watchOS companion app target for watch-specific demos. The watch app displays the synced user profile and the syncable setting from the Platform Sync Lab. On iPhone launch and when the watch becomes available, the app re-sends any syncable keys so the watch updates without manual re-entry. The watch app also requests a sync on launch when the iPhone is reachable.

Watch Sync Handshake

This sample uses a launch-order-safe handshake so either app can start first:

1. Watch app launches → sends a request_sync message (or queues it if the iPhone is unreachable).
2. iOS app receives the request → replies with a snapshot of current syncable keys and updates applicationContext.
3. Watch app applies the snapshot → UI updates immediately.

This avoids requiring users to remember which app to open first.

Where the Logic Lives

• iOS WCSession + handshake: SecureStorageSample/SecureStorageSample/Services/WatchConnectivityService.swift
• Bootstrap on launch: SecureStorageSample/SecureStorageSample/SecureStorageSampleApp.swift
• Sync policy UI lab: SecureStorageSample/SecureStorageSample/Views/PlatformSyncDemo.swift
• Watch WCSession + request: SecureStorageSample/SecureStorageSample Watch App/Services/WatchConnectivityService.swift
• Watch payload handlers: SecureStorageSample/SecureStorageSample Watch App/Services/Handlers/

Requirements

• iOS 17.0+
• watchOS 10.0+ (companion app target)
• Xcode 15+

Getting Started

1. Open SecureStorageSample.xcodeproj
2. Select an iOS simulator or device
3. Build and run (⌘R)
4. To use App Group demos, enable the App Group entitlement for each target that should share data. The identifier is derived from the bundle ID via SharedKit constants.

Project Structure

SharedPackage/
├── Package.swift
└── Sources/
    └── SharedKit/
        ├── Constants/
        │   ├── StorageKeyNames.swift
        │   └── StorageServiceIdentifiers.swift
        └── Models/
            └── UserProfile.swift
SecureStorageSample/
├── ContentView.swift        # List-based navigation
├── Models/
│   ├── Credential.swift
│   └── SampleLocationData.swift
├── StorageKeys/
│   ├── UserDefaults/
│   ├── Keychain/
│   ├── FileSystem/
│   ├── EncryptedFileSystem/
│   ├── AppGroup/
│   └── Platform/
├── WatchOptimized.swift     # Watch data models
├── Services/
│   ├── AppStorageCatalog.swift
│   ├── ExternalKeyMaterialProvider.swift
│   └── WatchConnectivityService.swift
└── Views/
    ├── UserDefaultsDemo.swift
    ├── KeychainDemo.swift
    ├── FileSystemDemo.swift
    ├── EncryptedStorageDemo.swift
    └── PlatformSyncDemo.swift
SecureStorageSample Watch App/
├── SecureStorageSampleApp.swift
├── ContentView.swift
├── Protocols/
│   └── WatchDataHandling.swift
├── State/
│   └── WatchProfileStore.swift
└── Services/
    ├── WatchConnectivityService.swift
    └── Handlers/
        └── UserProfileWatchHandler.swift

Storage Design Philosophy

This app intentionally uses a Type-Safe Storage Design. Unlike standard iOS development which uses string keys (e.g., UserDefaults.standard.string(forKey: "user_name")), this library requires you to define StorageKey values.

Why types instead of strings?

1. Safety: The compiler prevents typos. You can't accidentally load from "user_name" and save to "username".
2. Codable Support: Keys define their own value types. You can store complex Codable structs or classes just as easily as strings, and the library handles the JSON/Plist serialization automatically.
3. Visibility: All data your app stores is discoverable in the StorageKeys/ folder. It serves as a manifest of your app's persistence layer.
4. Migration: You can move a piece of data from UserDefaults to EncryptedFileSystem just by changing the domain in the Key definition. No UI code needs to change.

Storage Key Examples

The app demonstrates various storage configurations:

UserDefaults

• Simple string storage with automatic sync
• App Group UserDefaults support for shared preferences

Keychain

• 7 accessibility options (whenUnlocked, afterFirstUnlock, etc.)
• 6 access control options (biometry, passcode, etc.)

File System

• Documents: Permanent storage, backed up to iCloud. Use for critical user data.
• Caches: Purgeable storage (iOS may delete when low on space), not backed up. Use for temporary data.
• JSON and PropertyList serializers supported.

App Group Storage

• Shared UserDefaults via App Group identifier
• Shared files in the App Group container
• Requires App Group entitlements in all participating targets

Encrypted Storage

• AES-256-GCM or ChaCha20-Poly1305 encryption
• PBKDF2 or HKDF key derivation
• PBKDF2 iteration count must remain consistent or existing data will not decrypt
• Complete file protection
• External key material example via KeyMaterialProviding
• Global encryption configuration (Keychain service/account) in app init

Platform & Sync

• Platform availability (phoneOnly, watchOnly, all)
• Sync policies (never, manual, automaticSmall)
• Global sync configuration (max file size) in app init

Data Migration

• Fallback: Automatically moves data from legacyMigrationSource to modernMigrationDestination on first access using protocol-based migration.
• Transforming: Converts a legacy full-name string into a structured ProfileName.
• Aggregating: Combines legacy notification + theme settings into UnifiedSettings.
• Conditional: Migrates app mode only when the version rule is met.
• Manual Sweep: Explicitly triggers a "drain" of legacy keys to the Keychain using StorageRouter.shared.forceMigration(for:).
• Startup Sweep: Automatically cleanses all registered legacy keys at app launch via registerCatalog(..., migrateImmediately: true).

Global Configuration

The app demonstrates how to configure the LocalData library globally during startup in SecureStorageSampleApp.swift:

• Encryption: Customized Keychain service (SecureStorageSample) and account (AppMasterKey) names to isolate the library's master encryption key from other apps.
• Sync: Set a custom maxAutoSyncSize of 50KB to control which data is automatically synchronized to the Apple Watch, overriding the library's 100KB default.
• File Storage: Scoping all library files into a SecureStorage sub-directory. This ensures that the library's data (whether in the main sandbox or a shared App Group container) is kept neat and isolated within its own folder, rather than cluttering the root directories.
• Storage Defaults: Pre-configuring the default Keychain service and App Group identifier. This allows common keys in the app to omit these identifiers, reducing boilerplate and making the code more maintainable.

This approach centralizes infrastructure settings and avoids hardcoding environment-specific values within individual storage keys.

Dependencies

• LocalData - Local package for typed secure storage
• SharedKit - Local package for shared iOS/watch models and constants

Notes

• Storage keys are now split into one file per key and grouped by domain; platform-focused keys live in StorageKeys/Platform with comments calling out availability/sync focus.
• Keys are declared as StorageKey<Value> static properties via constrained extensions (e.g., extension StorageKey where Value == String).
• The shared model/constants live in SharedPackage (SharedKit) to keep the watch/iOS data contract centralized.
• Keychain service IDs and App Group identifiers are centralized in SharedKit/Constants/StorageServiceIdentifiers.swift to avoid hardcoded strings in keys.
• The watch app uses a handler-based WatchConnectivity layer so new payload types can be added in Services/Handlers without bloating the main service.
• A StorageKeyCatalog sample is included to generate a security audit report of all storage keys.
• Each StorageKey includes a description used in audit reports.
• The catalog is registered at app startup to enforce key registration and catch duplicates.

License

This sample is provided for demonstration purposes.