@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.3

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/ios-security/references/file-storage-patterns.md

@@ -1,354 +1,354 @@
-# File Storage Patterns
-
-Guidance on choosing the right directory, applying file protection, managing
-backup exclusions, and handling storage pressure on iOS.
-
-## Contents
-
-- [Directory Selection Guide](#directory-selection-guide)
-- [FileProtectionType Levels](#fileprotectiontype-levels)
-- [Backup Exclusion (isExcludedFromBackup)](#backup-exclusion-isexcludedfrombackup)
-- [Storage Pressure Handling](#storage-pressure-handling)
-
-## Directory Selection Guide
-
-iOS provides four primary directories for app data. Choose based on whether
-the data is user-generated, re-creatable, or temporary.
-
-| Directory | Backed Up | Purged by System | Use For |
-|---|---|---|---|
-| `Documents/` | Yes | No | User-generated content (documents, exports, user files) |
-| `Library/Application Support/` | Yes | No | App-generated supporting files (databases, config, caches that should survive updates) |
-| `Library/Caches/` | No | Yes (low storage) | Re-creatable data (downloaded images, API responses, computed data) |
-| `tmp/` | No | Yes (anytime) | Truly temporary files (in-progress uploads, scratch files) |
-
-### Accessing Standard Directories
-
-Use `FileManager.default.urls(for:in:)` to get the correct path. Never
-hardcode paths.
-
-```swift
-import Foundation
-
-// Documents/ — user-generated content, backed up by iCloud/iTunes
-let documentsURL = FileManager.default.urls(
-    for: .documentDirectory, in: .userDomainMask
-).first!
-
-// Library/Application Support/ — app-generated supporting data, backed up
-let appSupportURL = FileManager.default.urls(
-    for: .applicationSupportDirectory, in: .userDomainMask
-).first!
-// Create if it doesn't exist (not auto-created)
-try FileManager.default.createDirectory(
-    at: appSupportURL, withIntermediateDirectories: true
-)
-
-// Library/Caches/ — re-creatable data, not backed up, may be purged
-let cachesURL = FileManager.default.urls(
-    for: .cachesDirectory, in: .userDomainMask
-).first!
-
-// tmp/ — temporary files, purged by system periodically
-let tmpURL = FileManager.default.temporaryDirectory
-```
-
-### Choosing the Right Directory
-
-```swift
-// User's exported PDF — Documents/
-let exportURL = documentsURL.appendingPathComponent("Report.pdf")
-try pdfData.write(to: exportURL)
-
-// App's SQLite database — Library/Application Support/
-let dbURL = appSupportURL.appendingPathComponent("AppData.sqlite")
-
-// Downloaded thumbnail cache — Library/Caches/
-let thumbURL = cachesURL.appendingPathComponent("thumbnails/\(imageID).jpg")
-
-// In-progress upload — tmp/
-let uploadURL = tmpURL.appendingPathComponent(UUID().uuidString + ".tmp")
-```
-
-## FileProtectionType Levels
-
-iOS encrypts files at rest using Data Protection. The protection level
-determines when the file is accessible relative to the device lock state.
-
-Docs: [FileProtectionType](https://sosumi.ai/documentation/foundation/fileprotectiontype),
-[Encrypting Your App's Files](https://sosumi.ai/documentation/uikit/encrypting-your-app-s-files)
-
-| Level | Constant | When Accessible | Use For |
-|---|---|---|---|
-| Complete | `.complete` | Only when device is unlocked | Sensitive user data (health records, financial data) |
-| Complete Unless Open | `.completeUnlessOpen` | Can finish if opened before lock | Active downloads, recordings in progress |
-| Until First Auth | `.completeUntilFirstUserAuthentication` | After first unlock (default) | Most app data; background-accessible content |
-| None | `.none` | Always, even before first unlock | Non-sensitive system-required data |
-
-### Setting File Protection
-
-```swift
-import Foundation
-
-// Option 1: Set protection when writing data
-try sensitiveData.write(to: fileURL, options: .completeFileProtection)
-
-// Option 2: Set protection via FileManager attributes
-try FileManager.default.setAttributes(
-    [.protectionKey: FileProtectionType.complete],
-    ofItemAtPath: fileURL.path
-)
-
-// Option 3: Set protection on a directory (applies to new files within)
-try FileManager.default.setAttributes(
-    [.protectionKey: FileProtectionType.complete],
-    ofItemAtPath: secureDirectoryURL.path
-)
-```
-
-### Checking Current Protection Level
-
-```swift
-let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
-if let protection = attributes[.protectionKey] as? FileProtectionType {
-    switch protection {
-    case .complete:
-        print("File is fully protected")
-    case .completeUnlessOpen:
-        print("Protected unless already open")
-    case .completeUntilFirstUserAuthentication:
-        print("Protected until first unlock (default)")
-    case .none:
-        print("No encryption")
-    default:
-        break
-    }
-}
-```
-
-### Handling Protected Data Availability
-
-Files with `.complete` protection are inaccessible when the device is locked.
-Check availability before accessing:
-
-```swift
-import UIKit
-
-// Check if protected data is currently available
-if UIApplication.shared.isProtectedDataAvailable {
-    // Safe to read .complete files
-    let data = try Data(contentsOf: protectedFileURL)
-} else {
-    // Wait for device unlock
-}
-
-// Observe availability changes
-NotificationCenter.default.addObserver(
-    forName: UIApplication.protectedDataDidBecomeAvailableNotification,
-    object: nil,
-    queue: .main
-) { _ in
-    // Protected files are now accessible
-}
-
-NotificationCenter.default.addObserver(
-    forName: UIApplication.protectedDataWillBecomeUnavailableNotification,
-    object: nil,
-    queue: .main
-) { _ in
-    // Close file handles to .complete files
-}
-```
-
-## Backup Exclusion (isExcludedFromBackup)
-
-Exclude large re-downloadable content from iCloud/iTunes backup to avoid
-bloating the user's backup. Apple may reject apps that back up excessive
-re-creatable data.
-
-Docs: [URLResourceValues](https://sosumi.ai/documentation/foundation/urlresourcevalues)
-
-### Setting the Exclusion Flag
-
-```swift
-import Foundation
-
-// Exclude a file or directory from backup
-func excludeFromBackup(_ url: URL) throws {
-    var resourceValues = URLResourceValues()
-    resourceValues.isExcludedFromBackup = true
-    var mutableURL = url
-    try mutableURL.setResourceValues(resourceValues)
-}
-
-// Usage
-let largeCache = cachesURL.appendingPathComponent("video-cache")
-try excludeFromBackup(largeCache)
-```
-
-### Checking the Exclusion Flag
-
-```swift
-func isExcludedFromBackup(_ url: URL) throws -> Bool {
-    let values = try url.resourceValues(forKeys: [.isExcludedFromBackupKey])
-    return values.isExcludedFromBackup ?? false
-}
-```
-
-### When to Exclude from Backup
-
-| Exclude | Keep in Backup |
-|---|---|
-| Downloaded media (images, videos, audio) | User-created documents |
-| API response caches | User preferences and settings |
-| Generated thumbnails or previews | App databases with user data |
-| Offline map tiles | In-app purchase receipts |
-| Pre-computed search indexes | User-generated content |
-
-### Common Pattern: Application Support with Exclusion
-
-Store re-downloadable data in Application Support but exclude from backup:
-
-```swift
-let offlineDataURL = appSupportURL.appendingPathComponent("OfflineData")
-try FileManager.default.createDirectory(
-    at: offlineDataURL, withIntermediateDirectories: true
-)
-try excludeFromBackup(offlineDataURL)
-
-// Files in this directory persist across app updates but don't bloat backup
-try downloadedData.write(to: offlineDataURL.appendingPathComponent("map-tiles.db"))
-```
-
-## Storage Pressure Handling
-
-When the device runs low on storage, iOS may purge files in `Library/Caches/`
-and `tmp/`. Apps should proactively manage storage and respond to low-space
-conditions.
-
-### Checking Available Storage
-
-```swift
-import Foundation
-
-func availableDiskSpace() throws -> Int64 {
-    let values = try URL(fileURLWithPath: NSHomeDirectory())
-        .resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
-    return values.volumeAvailableCapacityForImportantUsage ?? 0
-}
-
-// Use .volumeAvailableCapacityForImportantUsageKey for important operations
-// Use .volumeAvailableCapacityForOpportunisticUsageKey for optional operations
-// The opportunistic value is always <= the important value
-
-func hasSpaceForDownload(bytes: Int64) throws -> Bool {
-    let available = try availableDiskSpace()
-    return available > bytes
-}
-```
-
-### Responding to Low Storage Notifications
-
-```swift
-import UIKit
-
-// iOS posts this when storage is critically low (UIKit apps)
-NotificationCenter.default.addObserver(
-    forName: UIApplication.didReceiveMemoryWarningNotification,
-    object: nil,
-    queue: .main
-) { _ in
-    // Clear in-memory caches; consider trimming disk caches too
-    clearImageCache()
-}
-
-// Check storage proactively at app launch or before large operations
-func checkStorageAndCleanup() throws {
-    let availableBytes = try availableDiskSpace()
-    let threshold: Int64 = 100 * 1024 * 1024  // 100 MB
-
-    if availableBytes < threshold {
-        try performCleanup()
-    }
-}
-```
-
-### Implementing Cleanup Strategies
-
-```swift
-import Foundation
-
-struct StorageCleaner {
-    let cachesURL: URL
-    let maxCacheAge: TimeInterval  // e.g., 7 days
-    let maxCacheSize: Int64        // e.g., 500 MB
-
-    /// Remove files older than maxCacheAge
-    func removeExpiredFiles() throws {
-        let contents = try FileManager.default.contentsOfDirectory(
-            at: cachesURL,
-            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
-            options: .skipsHiddenFiles
-        )
-
-        let cutoff = Date.now.addingTimeInterval(-maxCacheAge)
-
-        for fileURL in contents {
-            let values = try fileURL.resourceValues(
-                forKeys: [.contentModificationDateKey]
-            )
-            if let modified = values.contentModificationDate, modified < cutoff {
-                try FileManager.default.removeItem(at: fileURL)
-            }
-        }
-    }
-
-    /// Trim cache to maxCacheSize using LRU eviction
-    func trimToSize() throws {
-        let contents = try FileManager.default.contentsOfDirectory(
-            at: cachesURL,
-            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
-            options: .skipsHiddenFiles
-        )
-
-        // Sort oldest first
-        let sorted = try contents.sorted { a, b in
-            let aDate = try a.resourceValues(forKeys: [.contentModificationDateKey])
-                .contentModificationDate ?? .distantPast
-            let bDate = try b.resourceValues(forKeys: [.contentModificationDateKey])
-                .contentModificationDate ?? .distantPast
-            return aDate < bDate
-        }
-
-        // Calculate total size
-        var totalSize: Int64 = 0
-        for fileURL in sorted {
-            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
-            totalSize += Int64(values.fileSize ?? 0)
-        }
-
-        // Delete oldest files until under budget
-        for fileURL in sorted {
-            guard totalSize > maxCacheSize else { break }
-            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
-            let fileSize = Int64(values.fileSize ?? 0)
-            try FileManager.default.removeItem(at: fileURL)
-            totalSize -= fileSize
-        }
-    }
-
-    /// Full cleanup: expired files first, then trim to size
-    func performCleanup() throws {
-        try removeExpiredFiles()
-        try trimToSize()
-    }
-}
-
-// Usage
-let cleaner = StorageCleaner(
-    cachesURL: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first!,
-    maxCacheAge: 7 * 24 * 60 * 60,   // 7 days
-    maxCacheSize: 500 * 1024 * 1024    // 500 MB
-)
-try cleaner.performCleanup()
-```
+# File Storage Patterns
+
+Guidance on choosing the right directory, applying file protection, managing
+backup exclusions, and handling storage pressure on iOS.
+
+## Contents
+
+- [Directory Selection Guide](#directory-selection-guide)
+- [FileProtectionType Levels](#fileprotectiontype-levels)
+- [Backup Exclusion (isExcludedFromBackup)](#backup-exclusion-isexcludedfrombackup)
+- [Storage Pressure Handling](#storage-pressure-handling)
+
+## Directory Selection Guide
+
+iOS provides four primary directories for app data. Choose based on whether
+the data is user-generated, re-creatable, or temporary.
+
+| Directory | Backed Up | Purged by System | Use For |
+|---|---|---|---|
+| `Documents/` | Yes | No | User-generated content (documents, exports, user files) |
+| `Library/Application Support/` | Yes | No | App-generated supporting files (databases, config, caches that should survive updates) |
+| `Library/Caches/` | No | Yes (low storage) | Re-creatable data (downloaded images, API responses, computed data) |
+| `tmp/` | No | Yes (anytime) | Truly temporary files (in-progress uploads, scratch files) |
+
+### Accessing Standard Directories
+
+Use `FileManager.default.urls(for:in:)` to get the correct path. Never
+hardcode paths.
+
+```swift
+import Foundation
+
+// Documents/ — user-generated content, backed up by iCloud/iTunes
+let documentsURL = FileManager.default.urls(
+    for: .documentDirectory, in: .userDomainMask
+).first!
+
+// Library/Application Support/ — app-generated supporting data, backed up
+let appSupportURL = FileManager.default.urls(
+    for: .applicationSupportDirectory, in: .userDomainMask
+).first!
+// Create if it doesn't exist (not auto-created)
+try FileManager.default.createDirectory(
+    at: appSupportURL, withIntermediateDirectories: true
+)
+
+// Library/Caches/ — re-creatable data, not backed up, may be purged
+let cachesURL = FileManager.default.urls(
+    for: .cachesDirectory, in: .userDomainMask
+).first!
+
+// tmp/ — temporary files, purged by system periodically
+let tmpURL = FileManager.default.temporaryDirectory
+```
+
+### Choosing the Right Directory
+
+```swift
+// User's exported PDF — Documents/
+let exportURL = documentsURL.appendingPathComponent("Report.pdf")
+try pdfData.write(to: exportURL)
+
+// App's SQLite database — Library/Application Support/
+let dbURL = appSupportURL.appendingPathComponent("AppData.sqlite")
+
+// Downloaded thumbnail cache — Library/Caches/
+let thumbURL = cachesURL.appendingPathComponent("thumbnails/\(imageID).jpg")
+
+// In-progress upload — tmp/
+let uploadURL = tmpURL.appendingPathComponent(UUID().uuidString + ".tmp")
+```
+
+## FileProtectionType Levels
+
+iOS encrypts files at rest using Data Protection. The protection level
+determines when the file is accessible relative to the device lock state.
+
+Docs: [FileProtectionType](https://sosumi.ai/documentation/foundation/fileprotectiontype),
+[Encrypting Your App's Files](https://sosumi.ai/documentation/uikit/encrypting-your-app-s-files)
+
+| Level | Constant | When Accessible | Use For |
+|---|---|---|---|
+| Complete | `.complete` | Only when device is unlocked | Sensitive user data (health records, financial data) |
+| Complete Unless Open | `.completeUnlessOpen` | Can finish if opened before lock | Active downloads, recordings in progress |
+| Until First Auth | `.completeUntilFirstUserAuthentication` | After first unlock (default) | Most app data; background-accessible content |
+| None | `.none` | Always, even before first unlock | Non-sensitive system-required data |
+
+### Setting File Protection
+
+```swift
+import Foundation
+
+// Option 1: Set protection when writing data
+try sensitiveData.write(to: fileURL, options: .completeFileProtection)
+
+// Option 2: Set protection via FileManager attributes
+try FileManager.default.setAttributes(
+    [.protectionKey: FileProtectionType.complete],
+    ofItemAtPath: fileURL.path
+)
+
+// Option 3: Set protection on a directory (applies to new files within)
+try FileManager.default.setAttributes(
+    [.protectionKey: FileProtectionType.complete],
+    ofItemAtPath: secureDirectoryURL.path
+)
+```
+
+### Checking Current Protection Level
+
+```swift
+let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
+if let protection = attributes[.protectionKey] as? FileProtectionType {
+    switch protection {
+    case .complete:
+        print("File is fully protected")
+    case .completeUnlessOpen:
+        print("Protected unless already open")
+    case .completeUntilFirstUserAuthentication:
+        print("Protected until first unlock (default)")
+    case .none:
+        print("No encryption")
+    default:
+        break
+    }
+}
+```
+
+### Handling Protected Data Availability
+
+Files with `.complete` protection are inaccessible when the device is locked.
+Check availability before accessing:
+
+```swift
+import UIKit
+
+// Check if protected data is currently available
+if UIApplication.shared.isProtectedDataAvailable {
+    // Safe to read .complete files
+    let data = try Data(contentsOf: protectedFileURL)
+} else {
+    // Wait for device unlock
+}
+
+// Observe availability changes
+NotificationCenter.default.addObserver(
+    forName: UIApplication.protectedDataDidBecomeAvailableNotification,
+    object: nil,
+    queue: .main
+) { _ in
+    // Protected files are now accessible
+}
+
+NotificationCenter.default.addObserver(
+    forName: UIApplication.protectedDataWillBecomeUnavailableNotification,
+    object: nil,
+    queue: .main
+) { _ in
+    // Close file handles to .complete files
+}
+```
+
+## Backup Exclusion (isExcludedFromBackup)
+
+Exclude large re-downloadable content from iCloud/iTunes backup to avoid
+bloating the user's backup. Apple may reject apps that back up excessive
+re-creatable data.
+
+Docs: [URLResourceValues](https://sosumi.ai/documentation/foundation/urlresourcevalues)
+
+### Setting the Exclusion Flag
+
+```swift
+import Foundation
+
+// Exclude a file or directory from backup
+func excludeFromBackup(_ url: URL) throws {
+    var resourceValues = URLResourceValues()
+    resourceValues.isExcludedFromBackup = true
+    var mutableURL = url
+    try mutableURL.setResourceValues(resourceValues)
+}
+
+// Usage
+let largeCache = cachesURL.appendingPathComponent("video-cache")
+try excludeFromBackup(largeCache)
+```
+
+### Checking the Exclusion Flag
+
+```swift
+func isExcludedFromBackup(_ url: URL) throws -> Bool {
+    let values = try url.resourceValues(forKeys: [.isExcludedFromBackupKey])
+    return values.isExcludedFromBackup ?? false
+}
+```
+
+### When to Exclude from Backup
+
+| Exclude | Keep in Backup |
+|---|---|
+| Downloaded media (images, videos, audio) | User-created documents |
+| API response caches | User preferences and settings |
+| Generated thumbnails or previews | App databases with user data |
+| Offline map tiles | In-app purchase receipts |
+| Pre-computed search indexes | User-generated content |
+
+### Common Pattern: Application Support with Exclusion
+
+Store re-downloadable data in Application Support but exclude from backup:
+
+```swift
+let offlineDataURL = appSupportURL.appendingPathComponent("OfflineData")
+try FileManager.default.createDirectory(
+    at: offlineDataURL, withIntermediateDirectories: true
+)
+try excludeFromBackup(offlineDataURL)
+
+// Files in this directory persist across app updates but don't bloat backup
+try downloadedData.write(to: offlineDataURL.appendingPathComponent("map-tiles.db"))
+```
+
+## Storage Pressure Handling
+
+When the device runs low on storage, iOS may purge files in `Library/Caches/`
+and `tmp/`. Apps should proactively manage storage and respond to low-space
+conditions.
+
+### Checking Available Storage
+
+```swift
+import Foundation
+
+func availableDiskSpace() throws -> Int64 {
+    let values = try URL(fileURLWithPath: NSHomeDirectory())
+        .resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
+    return values.volumeAvailableCapacityForImportantUsage ?? 0
+}
+
+// Use .volumeAvailableCapacityForImportantUsageKey for important operations
+// Use .volumeAvailableCapacityForOpportunisticUsageKey for optional operations
+// The opportunistic value is always <= the important value
+
+func hasSpaceForDownload(bytes: Int64) throws -> Bool {
+    let available = try availableDiskSpace()
+    return available > bytes
+}
+```
+
+### Responding to Low Storage Notifications
+
+```swift
+import UIKit
+
+// iOS posts this when storage is critically low (UIKit apps)
+NotificationCenter.default.addObserver(
+    forName: UIApplication.didReceiveMemoryWarningNotification,
+    object: nil,
+    queue: .main
+) { _ in
+    // Clear in-memory caches; consider trimming disk caches too
+    clearImageCache()
+}
+
+// Check storage proactively at app launch or before large operations
+func checkStorageAndCleanup() throws {
+    let availableBytes = try availableDiskSpace()
+    let threshold: Int64 = 100 * 1024 * 1024  // 100 MB
+
+    if availableBytes < threshold {
+        try performCleanup()
+    }
+}
+```
+
+### Implementing Cleanup Strategies
+
+```swift
+import Foundation
+
+struct StorageCleaner {
+    let cachesURL: URL
+    let maxCacheAge: TimeInterval  // e.g., 7 days
+    let maxCacheSize: Int64        // e.g., 500 MB
+
+    /// Remove files older than maxCacheAge
+    func removeExpiredFiles() throws {
+        let contents = try FileManager.default.contentsOfDirectory(
+            at: cachesURL,
+            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
+            options: .skipsHiddenFiles
+        )
+
+        let cutoff = Date.now.addingTimeInterval(-maxCacheAge)
+
+        for fileURL in contents {
+            let values = try fileURL.resourceValues(
+                forKeys: [.contentModificationDateKey]
+            )
+            if let modified = values.contentModificationDate, modified < cutoff {
+                try FileManager.default.removeItem(at: fileURL)
+            }
+        }
+    }
+
+    /// Trim cache to maxCacheSize using LRU eviction
+    func trimToSize() throws {
+        let contents = try FileManager.default.contentsOfDirectory(
+            at: cachesURL,
+            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
+            options: .skipsHiddenFiles
+        )
+
+        // Sort oldest first
+        let sorted = try contents.sorted { a, b in
+            let aDate = try a.resourceValues(forKeys: [.contentModificationDateKey])
+                .contentModificationDate ?? .distantPast
+            let bDate = try b.resourceValues(forKeys: [.contentModificationDateKey])
+                .contentModificationDate ?? .distantPast
+            return aDate < bDate
+        }
+
+        // Calculate total size
+        var totalSize: Int64 = 0
+        for fileURL in sorted {
+            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
+            totalSize += Int64(values.fileSize ?? 0)
+        }
+
+        // Delete oldest files until under budget
+        for fileURL in sorted {
+            guard totalSize > maxCacheSize else { break }
+            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
+            let fileSize = Int64(values.fileSize ?? 0)
+            try FileManager.default.removeItem(at: fileURL)
+            totalSize -= fileSize
+        }
+    }
+
+    /// Full cleanup: expired files first, then trim to size
+    func performCleanup() throws {
+        try removeExpiredFiles()
+        try trimToSize()
+    }
+}
+
+// Usage
+let cleaner = StorageCleaner(
+    cachesURL: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first!,
+    maxCacheAge: 7 * 24 * 60 * 60,   // 7 days
+    maxCacheSize: 500 * 1024 * 1024    // 500 MB
+)
+try cleaner.performCleanup()
+```