@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/ios-security/references/cryptokit-advanced.md

@@ -0,0 +1,297 @@
+# CryptoKit Advanced Patterns
+
+Extended CryptoKit usage beyond the basics covered in the main skill. Includes
+digital signatures, key agreement, alternative ciphers, key derivation, and
+post-quantum cryptography.
+
+## Contents
+
+- [ChaChaPoly (Alternative to AES-GCM)](#chachapoly-alternative-to-aes-gcm)
+- [Digital Signatures (P256 / ECDSA)](#digital-signatures-p256-ecdsa)
+- [Key Agreement (Diffie-Hellman)](#key-agreement-diffie-hellman)
+- [Key Derivation with HKDF](#key-derivation-with-hkdf)
+- [Authenticated Encryption with Associated Data (AEAD)](#authenticated-encryption-with-associated-data-aead)
+- [AES Key Wrapping](#aes-key-wrapping)
+- [Secure Enclave Key Agreement](#secure-enclave-key-agreement)
+- [Post-Quantum Cryptography](#post-quantum-cryptography)
+- [Storing CryptoKit Keys in Keychain](#storing-cryptokit-keys-in-keychain)
+- [Jailbreak Detection](#jailbreak-detection)
+
+## ChaChaPoly (Alternative to AES-GCM)
+
+Same sealed-box API as AES-GCM. Use for interoperability with non-Apple systems
+or when AES hardware acceleration is unavailable.
+
+```swift
+import CryptoKit
+
+let key = SymmetricKey(size: .bits256)
+
+// Encrypt
+let sealed = try ChaChaPoly.seal(data, using: key)
+let combined = sealed.combined
+
+// Decrypt
+let box = try ChaChaPoly.SealedBox(combined: combined)
+let decrypted = try ChaChaPoly.open(box, using: key)
+```
+
+## Digital Signatures (P256 / ECDSA)
+
+```swift
+// Generate key pair
+let privateKey = P256.Signing.PrivateKey()
+let publicKey = privateKey.publicKey
+
+// Sign
+let signature = try privateKey.signature(for: data)
+
+// Verify
+let isValid = publicKey.isValidSignature(signature, for: data)
+
+// Export public key (raw, DER, or PEM)
+let rawData = publicKey.rawRepresentation
+let derData = publicKey.derRepresentation
+let pemString = publicKey.pemRepresentation
+
+// Import public key
+let imported = try P256.Signing.PublicKey(rawRepresentation: rawData)
+let importedDER = try P256.Signing.PublicKey(derRepresentation: derData)
+let importedPEM = try P256.Signing.PublicKey(pemRepresentation: pemString)
+```
+
+Also available: `P384.Signing` and `P521.Signing` for stronger curves.
+
+## Key Agreement (Diffie-Hellman)
+
+### Curve25519
+
+```swift
+let myPrivateKey = Curve25519.KeyAgreement.PrivateKey()
+let myPublicKey = myPrivateKey.publicKey
+
+// After exchanging public keys...
+let sharedSecret = try myPrivateKey.sharedSecretFromKeyAgreement(
+    with: theirPublicKey
+)
+
+// Derive symmetric key from shared secret using HKDF
+let symmetricKey = sharedSecret.hkdfDerivedSymmetricKey(
+    using: SHA256.self,
+    salt: salt,
+    sharedInfo: Data("app-encryption".utf8),
+    outputByteCount: 32
+)
+```
+
+### P256 Key Agreement
+
+```swift
+let privateKey = P256.KeyAgreement.PrivateKey()
+let publicKey = privateKey.publicKey
+
+let sharedSecret = try privateKey.sharedSecretFromKeyAgreement(
+    with: theirPublicKey
+)
+```
+
+Also available: `P384.KeyAgreement` and `P521.KeyAgreement`.
+
+## Key Derivation with HKDF
+
+Derive one or more keys from input key material:
+
+```swift
+// Simple derivation
+let derived = HKDF<SHA256>.deriveKey(
+    inputKeyMaterial: inputKey,
+    salt: salt,
+    info: Data("context-string".utf8),
+    outputByteCount: 32
+)
+
+// Two-step: extract then expand (for advanced use)
+let prk = HKDF<SHA256>.extract(inputKeyMaterial: inputKey, salt: salt)
+let key1 = HKDF<SHA256>.expand(
+    pseudoRandomKey: prk,
+    info: Data("key-1".utf8),
+    outputByteCount: 32
+)
+let key2 = HKDF<SHA256>.expand(
+    pseudoRandomKey: prk,
+    info: Data("key-2".utf8),
+    outputByteCount: 32
+)
+```
+
+## Authenticated Encryption with Associated Data (AEAD)
+
+Both AES-GCM and ChaChaPoly support authenticating additional data that is not
+encrypted but is included in the authentication tag:
+
+```swift
+let sealed = try AES.GCM.seal(
+    plaintext,
+    using: key,
+    authenticating: associatedData  // e.g., message headers
+)
+
+let decrypted = try AES.GCM.open(
+    sealed,
+    using: key,
+    authenticating: associatedData
+)
+```
+
+## AES Key Wrapping
+
+Wrap and unwrap symmetric keys for secure transport:
+
+```swift
+let keyToWrap = SymmetricKey(size: .bits256)
+let wrappingKey = SymmetricKey(size: .bits256)
+
+// Wrap
+let wrapped = try AES.KeyWrap.wrap(keyToWrap, using: wrappingKey)
+
+// Unwrap
+let unwrapped = try AES.KeyWrap.unwrap(wrapped, using: wrappingKey)
+```
+
+## Secure Enclave Key Agreement
+
+The Secure Enclave also supports P256 key agreement:
+
+```swift
+let accessControl = SecAccessControlCreateWithFlags(
+    nil,
+    kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
+    [.privateKeyUsage, .biometryCurrentSet],
+    nil
+)!
+
+let sePrivateKey = try SecureEnclave.P256.KeyAgreement.PrivateKey(
+    accessControl: accessControl
+)
+
+let sharedSecret = try sePrivateKey.sharedSecretFromKeyAgreement(
+    with: theirPublicKey
+)
+```
+
+## Post-Quantum Cryptography
+
+CryptoKit includes post-quantum algorithms for future-proofing. These are
+available on newer OS versions.
+
+### ML-KEM (Key Encapsulation)
+
+```swift
+// ML-KEM 768 (128-bit security)
+let privateKey = try MLKEM768.PrivateKey()
+let publicKey = privateKey.publicKey
+
+// Encapsulate (sender side)
+let result = try publicKey.encapsulate()
+let sharedKey = result.sharedSecret      // SymmetricKey
+let encapsulated = result.encapsulated   // Send to key owner
+
+// Decapsulate (receiver side)
+let decapsulatedKey = try privateKey.decapsulate(encapsulated)
+// decapsulatedKey == sharedKey
+```
+
+Also available: `MLKEM1024` for 192-bit security.
+
+### ML-DSA (Digital Signatures)
+
+```swift
+// ML-DSA 65 (128-bit security)
+let signingKey = try MLDSA65.PrivateKey()
+let verifyingKey = signingKey.publicKey
+
+let signature = try signingKey.signature(for: data)
+let isValid = verifyingKey.isValidSignature(signature, for: data)
+```
+
+Also available: `MLDSA87` for 192-bit security.
+
+### Hybrid Post-Quantum (HPKE)
+
+For hybrid classical + post-quantum encryption:
+
+```swift
+let ciphersuite = HPKE.Ciphersuite.XWingMLKEM768X25519_SHA256_AES_GCM_256
+
+let sender = try HPKE.Sender(
+    recipientKey: recipientPublicKey,
+    ciphersuite: ciphersuite,
+    info: Data("app-context".utf8)
+)
+
+let ciphertext = try sender.seal(plaintext)
+// Send sender.encapsulatedKey and ciphertext to recipient
+```
+
+## Storing CryptoKit Keys in Keychain
+
+For non-Secure-Enclave keys that need persistence:
+
+```swift
+let privateKey = P256.Signing.PrivateKey()
+
+// Store
+let keyData = privateKey.rawRepresentation
+let query: [String: Any] = [
+    kSecClass as String: kSecClassKey,
+    kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+    kSecAttrKeySizeInBits as String: 256,
+    kSecAttrApplicationTag as String: "com.app.signing-key".data(using: .utf8)!,
+    kSecValueData as String: keyData,
+    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+]
+SecItemAdd(query as CFDictionary, nil)
+
+// Retrieve
+let searchQuery: [String: Any] = [
+    kSecClass as String: kSecClassKey,
+    kSecAttrApplicationTag as String: "com.app.signing-key".data(using: .utf8)!,
+    kSecReturnData as String: true
+]
+var result: AnyObject?
+SecItemCopyMatching(searchQuery as CFDictionary, &result)
+if let data = result as? Data {
+    let restored = try P256.Signing.PrivateKey(rawRepresentation: data)
+}
+```
+
+## Jailbreak Detection
+
+Use jailbreak detection as one signal, not a security boundary. Check for known jailbreak file paths and sandbox escape:
+
+```swift
+func isDeviceCompromised() -> Bool {
+    let paths = [
+        "/Applications/Cydia.app",
+        "/Library/MobileSubstrate/MobileSubstrate.dylib",
+        "/usr/sbin/sshd",
+        "/etc/apt",
+        "/private/var/lib/apt/"
+    ]
+
+    for path in paths {
+        if FileManager.default.fileExists(atPath: path) { return true }
+    }
+
+    let testPath = "/private/test_jailbreak"
+    do {
+        try "test".write(toFile: testPath, atomically: true, encoding: .utf8)
+        try FileManager.default.removeItem(atPath: testPath)
+        return true
+    } catch {
+        return false
+    }
+}
+```
+
+This is heuristic only. Treat a positive result as higher risk, not proof.

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

@@ -0,0 +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()
+```