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:

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

The project also includes a watchOS companion app target for watch-specific demos.

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        # Tabbed 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 a StorageKey type.

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
• 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 LegacyMigrationSourceKey to ModernMigrationDestinationKey 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.
• 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.