@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/common-anti-patterns.md

@@ -1,708 +1,438 @@
-# Common Anti-Patterns
+# Insecure Patterns in Generated iOS Code
 
-> **Scope:** The 10 most dangerous security anti-patterns that AI coding assistants generate for iOS apps. Each entry includes the vulnerability explanation, realistic ❌ insecure code, ✅ correct replacement, detection heuristic, and OWASP risk mapping. This is the skill's backbone  -  the single most important file for correcting AI-generated security code.
->
-> **Cross-references:** `biometric-authentication.md` (anti-pattern #3 deep dive), `keychain-fundamentals.md` (anti-pattern #4 CRUD patterns), `keychain-access-control.md` (anti-pattern #5 protection classes), `cryptokit-symmetric.md` (anti-patterns #6-7), `credential-storage-patterns.md` (anti-patterns #1-2 token lifecycle), `migration-legacy-stores.md` (anti-pattern #9 first-launch cleanup), `compliance-owasp-mapping.md` (full OWASP/MASVS mapping).
+This is the review backbone of the skill. It lists the ten security mistakes that code generators produce most often on Apple platforms. Every entry gives the reason it is dangerous, an insecure sample, a corrected sample, a way to detect it, and its OWASP mapping.
 
----
+Deeper material per entry: [credential-storage-patterns.md](credential-storage-patterns.md) (1 and 2), [biometric-authentication.md](biometric-authentication.md) (3), [keychain-fundamentals.md](keychain-fundamentals.md) (4), [keychain-access-control.md](keychain-access-control.md) (5), [cryptokit-symmetric.md](cryptokit-symmetric.md) (6 and 7), [migration-legacy-stores.md](migration-legacy-stores.md) (9), and [compliance-owasp-mapping.md](compliance-owasp-mapping.md) for the complete standards mapping.
 
 ## Contents
 
-- [Why AI Generates Insecure iOS Code](#why-ai-generates-insecure-ios-code)
-- [Anti-Pattern #1  -  Storing Secrets in UserDefaults](#anti-pattern-1-storing-secrets-in-userdefaults)
-- [Anti-Pattern #2  -  Hardcoded API Keys](#anti-pattern-2-hardcoded-api-keys)
-- [Anti-Pattern #3  -  LAContext-Only Biometric Authentication](#anti-pattern-3-lacontext-only-biometric-authentication)
-- [Anti-Pattern #4  -  Ignoring SecItem Error Codes](#anti-pattern-4-ignoring-secitem-error-codes)
-- [Anti-Pattern #5  -  Wrong or Missing Data Protection Class](#anti-pattern-5-wrong-or-missing-data-protection-class)
-- [Anti-Pattern #6  -  Nonce Reuse in AES-GCM](#anti-pattern-6-nonce-reuse-in-aes-gcm)
-- [Anti-Pattern #7  -  MD5/SHA-1 for Security Purposes](#anti-pattern-7-md5sha-1-for-security-purposes)
-- [Anti-Pattern #8  -  Logging Sensitive Data](#anti-pattern-8-logging-sensitive-data)
-- [Anti-Pattern #9  -  Not Clearing Keychain on First Launch](#anti-pattern-9-not-clearing-keychain-on-first-launch)
-- [Anti-Pattern #10  -  Non-Cryptographic RNG for Security Operations](#anti-pattern-10-non-cryptographic-rng-for-security-operations)
-- [Quick Reference Matrix](#quick-reference-matrix)
-- [CI/CD Detection Strategy](#cicd-detection-strategy)
-- [iOS 26 / WWDC 2025 Implications](#ios-26-wwdc-2025-implications)
-- [Summary Checklist](#summary-checklist)
+- [Why generated code drifts toward insecure defaults](#why-generated-code-drifts-toward-insecure-defaults)
+- [1. Secrets in UserDefaults](#1-secrets-in-userdefaults)
+- [2. Hardcoded API keys](#2-hardcoded-api-keys)
+- [3. Biometric check that only returns a Boolean](#3-biometric-check-that-only-returns-a-boolean)
+- [4. Ignoring SecItem status codes](#4-ignoring-secitem-status-codes)
+- [5. Missing or weak data protection class](#5-missing-or-weak-data-protection-class)
+- [6. Reusing an AES-GCM nonce](#6-reusing-an-aes-gcm-nonce)
+- [7. MD5 or SHA-1 where security matters](#7-md5-or-sha-1-where-security-matters)
+- [8. Secrets in logs](#8-secrets-in-logs)
+- [9. No keychain cleanup after reinstall](#9-no-keychain-cleanup-after-reinstall)
+- [10. Weak randomness for security values](#10-weak-randomness-for-security-values)
+- [Quick reference](#quick-reference)
+- [Automating detection in CI](#automating-detection-in-ci)
+- [What iOS 26 changes](#what-ios-26-changes)
+- [Checklist](#checklist)
 
-## Why AI Generates Insecure iOS Code
+## Why generated code drifts toward insecure defaults
 
-AI assistants optimize for functional correctness, not security  -  reproducing the most common patterns from training data, which are overwhelmingly insecure-by-default. Veracode's 2025 analysis: 45% of AI-generated code fails security tests. Cybernews: 815,000+ hardcoded secrets across 156,000 iOS apps (71% leaking ≥1 credential). Stanford: developers using AI write less secure code yet feel more confident.
+Generators are rewarded for code that compiles and works, and their training data is full of tutorials that store tokens in `UserDefaults` or gate screens on a biometric Boolean. The insecure version is usually the shortest one, so it wins.
 
-Apple's security primitives (Keychain, CryptoKit, Secure Enclave) are excellent but AI consistently bypasses them. CISA/FBI classified hardcoded credentials as elevating "risk to national security" in their January 2025 Bad Practices v2.0 (CWE-798).
+Published numbers point the same way. A 2025 industry study found that 45% of AI-produced code failed security tests. A 2025 scan of about 156,000 iOS apps found more than 815,000 hardcoded secrets, with 71% of apps leaking at least one. An academic user study found that developers with an AI assistant wrote less secure code while feeling more confident in it. The CISA and FBI "Product Security Bad Practices" guidance (version 2.0, January 2025) names hardcoded credentials (CWE-798) as a practice that raises risk to national security.
 
-**OWASP standard:** Mobile Top 10 (2024) with MASTG v2 test IDs. Legacy MSTG-\* identifiers noted where commonly referenced.
+Mappings below use the OWASP Mobile Top 10 (2024) and MASTG v2 test identifiers, with legacy MSTG identifiers in parentheses where auditors still quote them.
 
----
+The samples share two small error types: `KeychainFailure(status)` wraps an `OSStatus`, and `VaultError` carries app-level cases such as `deviceLocked` and `authenticationFailed`.
 
-## Anti-Pattern #1  -  Storing Secrets in UserDefaults
+## 1. Secrets in UserDefaults
 
-**Severity:** CRITICAL | **OWASP:** M9 (Insecure Data Storage) | **Fix effort:** Medium
+Severity: Critical. OWASP: M9. Fix effort: Medium.
 
-UserDefaults writes to an unencrypted XML plist at `~/Library/Preferences/{BUNDLE_ID}.plist`. Apple's documentation: "Don't store personal or sensitive information as settings." Readable from unencrypted backups, jailbroken devices (Objection `ios nsuserdefaults get`), and third-party SDKs. **SwiftUI's `@AppStorage` is a wrapper over `UserDefaults`**  -  it has identical security properties and must never be used for tokens, keys, or credentials.
+`UserDefaults` writes an unencrypted property list to `Library/Preferences/<bundle id>.plist` inside the container, and Apple's documentation says not to keep sensitive data there. The file shows up in unencrypted backups, on jailbroken devices (`objection` reads it with `ios nsuserdefaults get`), and to any third-party SDK in the process. SwiftUI's `@AppStorage` is the same store with a property wrapper around it, so it is equally unsuitable for tokens, keys or credentials.
 
-**❌ Insecure  -  AI-generated pattern:**
+Insecure:
 
 ```swift
-// Plaintext on disk, readable from backups
-func saveAuthToken(_ token: String) {
-    UserDefaults.standard.set(token, forKey: "userAuthToken")
-    UserDefaults.standard.set(refreshToken, forKey: "refreshToken")
-    UserDefaults.standard.synchronize()
-}
-
-let token = UserDefaults.standard.string(forKey: "userAuthToken")
+let prefs = UserDefaults.standard
+prefs.set(session.accessToken, forKey: "access_token")
+prefs.set(session.refreshToken, forKey: "refresh_token")
+prefs.synchronize()
 ```
 
-**✅ Secure  -  Keychain with add-or-update:**
+Secure:
 
 ```swift
-func saveTokenToKeychain(_ token: Data, account: String) throws {
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: "com.myapp.auth",
-        kSecAttrAccount as String: account,
-        kSecValueData as String: token,
-        kSecAttrAccessible as String:
-            kSecAttrAccessibleWhenUnlockedThisDeviceOnly
-    ]
-    let status = SecItemAdd(query as CFDictionary, nil)
+func storeAccessToken(_ token: String) throws {
+    let identity: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                     kSecAttrService: "com.example.courier",
+                                     kSecAttrAccount: "access_token"]
+    var insert = identity
+    insert[kSecValueData] = Data(token.utf8)
+    insert[kSecAttrAccessible] = kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+    var status = SecItemAdd(insert as CFDictionary, nil)
     if status == errSecDuplicateItem {
-        // Full add-or-update pattern → see anti-pattern #4
-        let search: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrService as String: "com.myapp.auth",
-            kSecAttrAccount as String: account
-        ]
-        let updateStatus = SecItemUpdate(
-            search as CFDictionary,
-            [kSecValueData as String: token] as CFDictionary)
-        guard updateStatus == errSecSuccess else {
-            throw KeychainError.unexpectedStatus(updateStatus)
-        }
-    } else if status != errSecSuccess {
-        throw KeychainError.unexpectedStatus(status)
+        let changes: [CFString: Any] = [kSecValueData: Data(token.utf8)]
+        status = SecItemUpdate(identity as CFDictionary, changes as CFDictionary)
     }
+    guard status == errSecSuccess else { throw KeychainFailure(status) }
 }
 ```
 
-**MASTG tests:** MASTG-TEST-0300, MASTG-TEST-0302. **MASWE:** MASWE-0006. **Legacy:** MSTG-STORAGE-1.
+Standards: MASTG-TEST-0300, MASTG-TEST-0302, MASWE-0006 (legacy MSTG-STORAGE-1).
 
-**Detection heuristic:**
+Detection: case-insensitive search of `.swift` files for lines containing `UserDefaults` together with token, password, secret, credential, auth, session, api key, jwt or bearer.
 
-```bash
-grep -rn "UserDefaults" --include="*.swift" | \
-  grep -iE "token|password|secret|credential|auth|session|api.?key|jwt|bearer"
+```sh
+grep -rniE 'UserDefaults.*(token|password|secret|credential|auth|session|api_?key|jwt|bearer)' --include='*.swift' .
 ```
 
----
-
-## Anti-Pattern #2  -  Hardcoded API Keys
+## 2. Hardcoded API keys
 
-**Severity:** CRITICAL | **OWASP:** M1 (Improper Credential Usage) | **Fix effort:** High
+Severity: Critical. OWASP: M1. Fix effort: High.
 
-API keys compiled into Swift appear in the binary's `__TEXT.__cstring` segment  -  `strings MyApp.app/MyApp` extracts them instantly. Even `.xcconfig` or `Info.plist` values ship inside the IPA. Cybernews found 78,800 Google API keys across 156,000 iOS apps.
+A Swift string literal ends up in the binary's `__TEXT.__cstring` section, where `strings` prints it in seconds. Values in `.xcconfig` files or `Info.plist` ship inside the IPA just the same. The 2025 scan mentioned above found about 78,800 keys for a single cloud provider's APIs alone.
 
-**❌ Insecure  -  AI-generated pattern:**
+Insecure:
 
 ```swift
-class PaymentService {
-    private let stripeKey = "sk_live_51H7bK2E..."   // In binary
-    private let firebaseKey = "AIzaSyB..."            // In binary
-
-    func charge(amount: Int) async throws {
-        var request = URLRequest(
-            url: URL(string: "https://api.stripe.com/v1/charges")!)
-        request.setValue("Bearer \(stripeKey)",
-                        forHTTPHeaderField: "Authorization")
-        let (data, _) = try await URLSession.shared.data(for: request)
-    }
+enum Secrets {
+    static let paymentsKey = "sk_live_EXAMPLEONLY000000000000"
+    static let backendKey = "AIzaEXAMPLEONLY00000000000000000"
 }
-
-// Also dangerous: key in Info.plist or .xcconfig bundled in app
-let key = Bundle.main.infoDictionary?["API_KEY"] as? String
+request.setValue("Bearer \(Secrets.paymentsKey)", forHTTPHeaderField: "Authorization")
+let plistKey = Bundle.main.infoDictionary?["API_KEY"] as? String
 ```
 
-**✅ Secure  -  server proxy + Keychain cache:**
+Secure, in order of preference:
 
-```swift
-class SecureAPIKeyManager {
-    static let shared = SecureAPIKeyManager()
-
-    /// Best: proxy through your server (key never on device)
-    func secureRequest(endpoint: String, params: [String: Any]) async throws -> Data {
-        var request = URLRequest(
-            url: URL(string: "https://api.myserver.com/proxy/\(endpoint)")!)
-        request.httpMethod = "POST"
-        request.httpBody = try JSONSerialization.data(withJSONObject: params)
-        let (data, _) = try await URLSession.shared.data(for: request)
-        return data
-    }
+1. A server-side proxy holds the key and the app calls the proxy, so the key never reaches the device.
+2. If the device genuinely needs a key, fetch it at runtime from your server after the user or device is authenticated and cache it in the keychain.
 
-    /// If client must hold key: fetch at runtime, cache in Keychain
-    func getAPIKey() async throws -> String {
-        if let cached = try? readFromKeychain(service: "api-keys", account: "primary") {
-            return String(data: cached, encoding: .utf8)!
-        }
-        let (data, _) = try await URLSession.shared.data(
-            from: URL(string: "https://api.myserver.com/config/key")!)
-        try saveToKeychain(data, service: "api-keys", account: "primary")
-        return String(data: data, encoding: .utf8)!
-    }
+```swift
+func quoteShipment(_ order: ShipmentRequest) async throws -> Quote {
+    var request = URLRequest(url: quotesEndpoint)
+    request.httpMethod = "POST"
+    request.httpBody = try JSONEncoder().encode(order)
+    request.setValue("Bearer \(try await session.userAccessToken())", forHTTPHeaderField: "Authorization")
+    let (body, _) = try await URLSession.shared.data(for: request)
+    return try JSONDecoder().decode(Quote.self, from: body)
 }
 ```
 
-Apple's DeviceCheck and App Attest frameworks provide server-side device verification without embedding secrets. WWDC 2019-709 advises storing credentials in Keychain, not in code.
+DeviceCheck and App Attest let the server verify a genuine app instance without shipping any secret (details in the `device-integrity` skill). WWDC 2019 session 709 states the rule plainly: credentials belong in the keychain.
 
-**MASTG tests:** MASTG-TEST-0213, MASTG-TEST-0214. **MASWE:** MASWE-0005. **Legacy:** MSTG-STORAGE-12. **CISA/FBI:** CWE-798  -  Product Security Bad Practices v2.0 (January 2025).
+Standards: MASTG-TEST-0213, MASTG-TEST-0214, MASWE-0005 (legacy MSTG-STORAGE-12); CWE-798 per the CISA/FBI guidance.
 
-**Detection heuristic:**
+Detection: in `.swift`, `.plist` and `.xcconfig` files, look for `let` constants whose name contains "key" assigned a literal of 20 or more alphanumeric characters, and for the prefixes `"sk_live_`, `"pk_live_`, `"AIza` and `"AKIA`.
 
-```bash
-grep -rn 'let.*[Kk]ey.*=.*"[A-Za-z0-9_\-]\{20,\}"' --include="*.swift"
-grep -rn '"sk_live_\|"pk_live_\|"AIza[A-Za-z0-9]\|"AKIA[A-Z0-9]' \
-  --include="*.swift" --include="*.plist" --include="*.xcconfig"
+```sh
+grep -rnE 'let [A-Za-z]*[Kk]ey[A-Za-z]* *= *"[A-Za-z0-9_-]{20,}"' --include='*.swift' .
+grep -rnE '"(sk_live_|pk_live_|AIza|AKIA)' --include='*.swift' --include='*.plist' --include='*.xcconfig' .
 ```
 
----
+## 3. Biometric check that only returns a Boolean
 
-## Anti-Pattern #3  -  LAContext-Only Biometric Authentication
+Severity: Critical. OWASP: M3. Fix effort: Medium.
 
-**Severity:** CRITICAL | **OWASP:** M3 (Insecure Authentication) | **Fix effort:** Medium
+This is the insecure pattern generators reproduce most. `evaluatePolicy` hands back a `Bool` in the app's own process, and one Frida command or `objection`'s `ios ui biometrics_bypass` flips it. MASTG's position is that biometric authentication must unlock something in the keychain, not just a screen.
 
-Using `LAContext.evaluatePolicy()` alone is the single most reproduced insecure pattern across iOS tutorials. The method returns a simple boolean callback in user-space  -  no cryptographic binding. Frida forces `success = true` in one command; Objection packages this as `ios ui biometrics_bypass`. OWASP MASTG: "Biometric authentication must be based on unlocking the keychain." Full deep dive: see `biometric-authentication.md`.
-
-**❌ Insecure  -  AI-generated pattern:**
+Insecure:
 
 ```swift
-func authenticateUser(completion: @escaping (Bool) -> Void) {
-    let context = LAContext()
-    context.evaluatePolicy(
-        .deviceOwnerAuthenticationWithBiometrics,
-        localizedReason: "Authenticate to access your account"
-    ) { success, authError in
-        DispatchQueue.main.async {
-            if success {
-                self.showSensitiveData()  // Gated on a hookable boolean
-            }
-            completion(success)
-        }
-    }
+LAContext().evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics,
+                           localizedReason: "Show your balance") { granted, _ in
+    if granted { DispatchQueue.main.async { self.revealBalance() } }
 }
 ```
 
-**✅ Secure  -  Keychain + SecAccessControl hardware binding:**
+Secure: bind the secret to a keychain item whose access control demands biometrics, and read it with an `LAContext` attached.
 
 ```swift
-// STORE: biometric-protected via Secure Enclave
-func storeWithBiometric(secret: Data, account: String) throws {
-    let access = SecAccessControlCreateWithFlags(
-        nil,
-        kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
-        .biometryCurrentSet, nil)!
-
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: "com.myapp.biometric",
-        kSecAttrAccount as String: account,
-        kSecAttrAccessControl as String: access,
-        kSecValueData as String: secret
-    ]
-    let status = SecItemAdd(query as CFDictionary, nil)
-    guard status == errSecSuccess || status == errSecDuplicateItem else {
-        throw KeychainError.unexpectedStatus(status)
+func sealBalanceKey(_ secret: Data) throws {
+    guard let gate = SecAccessControlCreateWithFlags(nil,
+            kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly, .biometryCurrentSet, nil) else {
+        throw KeychainFailure(errSecParam)
+    }
+    let identity: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                     kSecAttrService: "com.example.courier",
+                                     kSecAttrAccount: "balance-key"]
+    var insert = identity
+    insert[kSecValueData] = secret
+    insert[kSecAttrAccessControl] = gate
+    var status = SecItemAdd(insert as CFDictionary, nil)
+    if status == errSecDuplicateItem {
+        status = SecItemUpdate(identity as CFDictionary, [kSecValueData: secret] as CFDictionary)
     }
+    guard status == errSecSuccess else { throw KeychainFailure(status) }
 }
 
-// READ: Secure Enclave enforces biometric before releasing data
-func readWithBiometric(account: String) throws -> Data {
+func openBalanceKey() throws -> Data {
     let context = LAContext()
-    context.localizedReason = "Access your secure data"
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: "com.myapp.biometric",
-        kSecAttrAccount as String: account,
-        kSecReturnData as String: true,
-        kSecMatchLimit as String: kSecMatchLimitOne,
-        kSecUseAuthenticationContext as String: context
-    ]
-    var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-    guard status == errSecSuccess, let data = result as? Data else {
-        throw KeychainError.unexpectedStatus(status)
-    }
-    return data  // Only returned after hardware biometric validation
+    context.localizedReason = "Show your balance"
+    let lookup: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                   kSecAttrService: "com.example.courier",
+                                   kSecAttrAccount: "balance-key",
+                                   kSecReturnData: true,
+                                   kSecUseAuthenticationContext: context]
+    var out: CFTypeRef?
+    let status = SecItemCopyMatching(lookup as CFDictionary, &out)
+    guard status == errSecSuccess, let secret = out as? Data else { throw KeychainFailure(status) }
+    return secret
 }
 ```
 
-The `.biometryCurrentSet` flag invalidates the item if biometrics change, preventing an attacker with physical access from enrolling their own biometric. Objection's documentation confirms this bypass "will NOT work" with keychain-bound biometric items.
-
-**MASTG tests:** MASTG-TEST-0266, MASTG-TEST-0267. **MASWE:** MASWE-0044. **Legacy:** MSTG-AUTH-8. **WWDC:** 2014-711 introduced `SecAccessControlCreateWithFlags`.
+A duplicate is updated, never silently accepted. If the item needs a different access control than the one it was created with, delete it and add it again, because that is the one case where add-or-update does not apply.
 
-**Detection heuristic:**
+`.biometryCurrentSet` invalidates the item when the enrolled biometrics change, so an attacker who adds their own face or finger to a stolen, unlocked device gets nothing. `objection`'s own documentation notes that its bypass does not work against keychain-bound items.
 
-```bash
-# evaluatePolicy without SecAccessControl → insecure
-grep -rn "evaluatePolicy" --include="*.swift" -l | \
-  xargs grep -L "SecAccessControlCreateWithFlags"
-# Verify secure pattern exists
-grep -rn "\.biometryCurrentSet\|\.biometryAny" --include="*.swift"
-```
+Standards: MASTG-TEST-0266, MASTG-TEST-0267, MASWE-0044 (legacy MSTG-AUTH-8). `SecAccessControlCreateWithFlags` arrived with WWDC 2014 session 711.
 
----
+Detection: files that call `evaluatePolicy` but never `SecAccessControlCreateWithFlags`; also confirm whether `.biometryCurrentSet` or `.biometryAny` appears at all.
 
-## Anti-Pattern #4  -  Ignoring SecItem Error Codes
+```sh
+grep -rl 'evaluatePolicy' --include='*.swift' . | xargs grep -L 'SecAccessControlCreateWithFlags'
+```
 
-**Severity:** HIGH | **OWASP:** M8 (Security Misconfiguration) | **Fix effort:** Low
+## 4. Ignoring SecItem status codes
 
-`errSecDuplicateItem` (OSStatus -25299) is the most common Keychain failure. When `SecItemAdd` hits a duplicate, it silently discards the new value. Password updates never persist, refreshed tokens are lost, and auth breaks in hard-to-debug ways. Other critical codes: `errSecItemNotFound` (-25300), `errSecAuthFailed` (-25293), `errSecInteractionNotAllowed` (-25308).
+Severity: High. OWASP: M8 (Security Misconfiguration). Fix effort: Low.
 
-Full CRUD patterns: see `keychain-fundamentals.md`.
+The usual casualty is `errSecDuplicateItem` (-25299): the add fails, nobody looks, and the new value is dropped while the old one stays. Other statuses that must be handled: `errSecItemNotFound` (-25300), `errSecAuthFailed` (-25293), `errSecInteractionNotAllowed` (-25308). A cancelled authentication prompt surfaces as `errSecUserCanceled` (-128).
 
-**❌ Insecure  -  AI-generated pattern:**
+Insecure:
 
 ```swift
-func saveToken(_ token: Data) {
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: "com.app.auth",
-        kSecAttrAccount as String: "accessToken",
-        kSecValueData as String: token
-    ]
-    SecItemAdd(query as CFDictionary, nil)  // Return value ignored!
-}
+SecItemAdd(insert as CFDictionary, nil)
 ```
 
-**✅ Secure  -  OSStatus switch with add-or-update:**
+Secure:
 
 ```swift
-func saveToKeychain(value: Data, service: String, account: String) throws {
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: service,
-        kSecAttrAccount as String: account,
-        kSecValueData as String: value,
-        kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
-    ]
-    let status = SecItemAdd(query as CFDictionary, nil)
-    switch status {
-    case errSecSuccess: return
-    case errSecDuplicateItem:
-        let search: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrService as String: service,
-            kSecAttrAccount as String: account
-        ]
-        let updateStatus = SecItemUpdate(
-            search as CFDictionary, [kSecValueData as String: value] as CFDictionary)
-        guard updateStatus == errSecSuccess else { throw KeychainError.updateFailed(updateStatus) }
-    case errSecInteractionNotAllowed: throw KeychainError.deviceLocked
-    case errSecAuthFailed: throw KeychainError.authenticationFailed
-    default: throw KeychainError.unexpectedStatus(status)
-    }
+switch SecItemAdd(insert as CFDictionary, nil) {
+case errSecSuccess:
+    break
+case errSecDuplicateItem:
+    let status = SecItemUpdate(identity as CFDictionary, [kSecValueData: payload] as CFDictionary)
+    guard status == errSecSuccess else { throw KeychainFailure(status) }
+case errSecInteractionNotAllowed:
+    throw VaultError.deviceLocked
+case errSecAuthFailed, errSecUserCanceled:
+    throw VaultError.authenticationFailed
+case let other:
+    throw KeychainFailure(other)
 }
 ```
 
-Critical detail: `SecItemUpdate` takes two dictionaries  -  search query (without `kSecValueData`) and attributes to update. Passing the full query as the search parameter is a common mistake.
+`SecItemUpdate` takes two dictionaries: a search query with no `kSecValueData`, and the attributes to change. Passing the full add dictionary as the search query is a frequent mistake that makes the update match nothing.
 
-**MASTG tests:** MASTG-TEST-0300, MASTG-TEST-0301. **Legacy:** MASVS-STORAGE-2.
+Standards: MASTG-TEST-0300, MASTG-TEST-0301 (legacy MASVS-STORAGE-2).
 
-**Detection heuristic:**
+Detection: files containing `SecItemAdd` with no mention of `errSecDuplicateItem` or -25299, and `SecItemAdd(` calls whose result is neither assigned nor compared.
 
-```bash
-grep -rn "SecItemAdd" --include="*.swift" -l | \
-  xargs grep -L "errSecDuplicateItem\|DuplicateItem\|-25299"
-grep -rn "SecItemAdd(" --include="*.swift" | \
-  grep -v "let\|var\|status\|=\|switch\|if\|guard"
-```
+## 5. Missing or weak data protection class
 
----
+Severity: High. OWASP: M9. Fix effort: Low.
 
-## Anti-Pattern #5  -  Wrong or Missing Data Protection Class
+Leaving `kSecAttrAccessible` out means inheriting a default that may not fit. `kSecAttrAccessibleAlways` (deprecated in iOS 12) keeps the item decryptable while the device is locked. A class without the `ThisDeviceOnly` suffix is included in backups.
 
-**Severity:** HIGH | **OWASP:** M9 (Insecure Data Storage) | **Fix effort:** Low
+Pick deliberately:
 
-Omitting `kSecAttrAccessible` inherits a default that may be insufficient. Using deprecated `kSecAttrAccessibleAlways` (deprecated iOS 12) leaves data decryptable on a locked device. Missing `ThisDeviceOnly` suffix means items are included in backups. Full protection class guide: see `keychain-access-control.md`.
+| Item | Class |
+| --- | --- |
+| Passwords, access tokens used in the foreground | `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` |
+| Highest-sensitivity secrets | `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` |
+| Values background code must read (push tokens, refresh tokens) | `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` |
 
-**❌ Insecure  -  AI-generated patterns:**
+WWDC 2014 session 711's advice still holds: choose the most restrictive option that works for the feature.
 
-```swift
-// Missing kSecAttrAccessible entirely
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrAccount as String: "user_password",
-    kSecValueData as String: passwordData
-]
-SecItemAdd(query as CFDictionary, nil)
-
-// Deprecated  -  accessible when device is locked
-kSecAttrAccessible as String: kSecAttrAccessibleAlways
-```
-
-**✅ Secure  -  selection by use case:**
-
-```swift
-// Passwords, auth tokens (foreground-only)
-kSecAttrAccessible as String:
-    kSecAttrAccessibleWhenUnlockedThisDeviceOnly
-
-// Highest sensitivity  -  requires passcode to exist
-kSecAttrAccessible as String:
-    kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly
+Standards: MASTG-TEST-0299 (legacy MASTG-STORAGE-3).
 
-// Background-access items (push tokens, refresh tokens)
-kSecAttrAccessible as String:
-    kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
-```
-
-WWDC 2014-711: "Always use the most restrictive option that makes sense for your app."
-
-**MASTG test:** MASTG-TEST-0299. **Legacy:** MASTG-STORAGE-3.
-
-**Detection heuristic:**
-
-```bash
-grep -rn "kSecAttrAccessibleAlways\b" --include="*.swift"
-grep -rn "SecItemAdd" --include="*.swift" -l | \
-  xargs grep -L "kSecAttrAccessible\|kSecAttrAccessControl"
-grep -rn "kSecAttrAccessibleWhenUnlocked\b" --include="*.swift" | \
-  grep -v "ThisDeviceOnly"
-```
+Detection: `kSecAttrAccessibleAlways\b`; files with `SecItemAdd` but neither `kSecAttrAccessible` nor `kSecAttrAccessControl`; `kSecAttrAccessibleWhenUnlocked\b` without `ThisDeviceOnly`.
 
----
+## 6. Reusing an AES-GCM nonce
 
-## Anti-Pattern #6  -  Nonce Reuse in AES-GCM
+Severity: Critical. OWASP: M10. Fix effort: Medium.
 
-**Severity:** CRITICAL | **OWASP:** M10 (Insufficient Cryptography) | **Fix effort:** Medium
+Two messages sealed with the same key and nonce share a keystream, so XOR of the ciphertexts equals XOR of the plaintexts, and the GHASH authentication key can be recovered, which lets an attacker forge messages (Joux, 2006). CryptoKit picks a fresh random nonce for you; the break only happens when code builds nonces by hand.
 
-Reusing a nonce with the same key in AES-GCM is a complete cryptographic break. Identical nonces produce identical keystreams, enabling plaintext recovery via `C1 ⊕ C2 = P1 ⊕ P2` and authentication key recovery via polynomial factorization ("forbidden attack," Joux 2006). CryptoKit's `AES.GCM.seal` has a safe default: omitting the `nonce` parameter auto-generates a random 12-byte nonce. Danger occurs when AI explicitly constructs nonces. Full patterns: see `cryptokit-symmetric.md`.
-
-**❌ Insecure  -  AI-generated patterns:**
+Insecure:
 
 ```swift
-import CryptoKit
-
-// Hardcoded nonce  -  identical keystream every encryption
-let fixedNonce = try! AES.GCM.Nonce(data: Data(repeating: 0x00, count: 12))
-
-func encrypt(_ plaintext: Data, using key: SymmetricKey) throws -> Data {
-    let sealedBox = try AES.GCM.seal(
-        plaintext, using: key, nonce: fixedNonce)  // CATASTROPHIC
-    return sealedBox.combined!
-}
-// Also dangerous: counter-based nonce that resets on app restart → collision
+let fixedNonce = try AES.GCM.Nonce(data: Data(repeating: 0, count: 12))
+let box = try AES.GCM.seal(record, using: key, nonce: fixedNonce)
 ```
 
-**✅ Secure  -  let CryptoKit handle nonces:**
+A counter nonce that restarts from zero after each launch fails the same way.
+
+Secure:
 
 ```swift
-import CryptoKit
+let key = SymmetricKey(size: .bits256)
 
-func encrypt(_ plaintext: Data, using key: SymmetricKey) throws -> Data {
-    // Nonce omitted → CryptoKit generates random 12-byte nonce
-    let sealedBox = try AES.GCM.seal(plaintext, using: key)
-    return sealedBox.combined!  // Contains: nonce ‖ ciphertext ‖ tag
+func encrypt(_ record: Data) throws -> Data {
+    guard let wire = try AES.GCM.seal(record, using: key).combined else {
+        throw CryptoKitError.incorrectParameterSize
+    }
+    return wire
 }
 
-func decrypt(_ combined: Data, using key: SymmetricKey) throws -> Data {
-    let sealedBox = try AES.GCM.SealedBox(combined: combined)
-    return try AES.GCM.open(sealedBox, using: key)
+func decrypt(_ wire: Data) throws -> Data {
+    try AES.GCM.open(try AES.GCM.SealedBox(combined: wire), using: key)
 }
-
-let key = SymmetricKey(size: .bits256)  // AES-256 per WWDC 2025 guidance
 ```
 
-WWDC 2019-709 introduced CryptoKit with the design philosophy: "easy to use, hard to misuse."
-
-**MASTG test:** MASTG-TEST-0317. **MASWE:** MASWE-0022. **Legacy:** MASTG-CRYPTO-4.
+`combined` packs nonce, ciphertext and tag together, so nothing needs managing separately. This is the design goal WWDC 2019 session 709 set for CryptoKit: easy to use correctly, hard to use wrongly.
 
-**Detection heuristic:**
-
-```bash
-grep -rn "AES\.GCM\.Nonce(data:" --include="*.swift"
-grep -rn "let.*nonce.*=.*AES\.GCM\.Nonce" --include="*.swift"
-grep -rn "Data(repeating:.*count:\s*12)" --include="*.swift"
-grep -rn "\.seal(.*nonce:" --include="*.swift"
-```
+Standards: MASTG-TEST-0317, MASWE-0022 (legacy MASTG-CRYPTO-4).
 
----
+Detection: `AES.GCM.Nonce(data:`, variables named like `nonce`, `Data(repeating:` with `count: 12`, and `.seal(` calls that pass `nonce:`.
 
-## Anti-Pattern #7  -  MD5/SHA-1 for Security Purposes
+## 7. MD5 or SHA-1 where security matters
 
-**Severity:** HIGH | **OWASP:** M10 (Insufficient Cryptography) | **Fix effort:** Low
+Severity: High. OWASP: M10. Fix effort: Low.
 
-MD5 broken since Wang & Yu (2005); SHA-1 broken by SHAttered (2017). CISA January 2025 lists both as insecure. Apple signals this via CryptoKit's `Insecure.MD5` and `Insecure.SHA1` namespacing.
+MD5 collisions have been practical since 2005 (Wang and Yu); SHA-1 fell publicly with SHAttered in 2017. The January 2025 CISA guidance lists both as insecure, and CryptoKit parks them in the `Insecure` namespace for a reason.
 
-**❌ Insecure  -  AI-generated pattern:**
+Insecure:
 
 ```swift
-import CryptoKit
-func hashPassword(_ password: String) -> String {
-    let hash = Insecure.MD5.hash(data: password.data(using: .utf8)!)
-    return hash.map { String(format: "%02x", $0) }.joined()
-}
-// Also: CC_MD5, CC_SHA1 from CommonCrypto
+let stored = Insecure.MD5.hash(data: Data(password.utf8))
 ```
 
-**✅ Secure  -  SHA-256 minimum, KDF for passwords:**
-
-```swift
-import CryptoKit
-
-// Integrity verification
-func hashData(_ data: Data) -> String {
-    let hash = SHA256.hash(data: data)
-    return hash.map { String(format: "%02x", $0) }.joined()
-}
+Also `CC_MD5` and `CC_SHA1` from CommonCrypto.
 
-// HMAC for message authentication
-func authenticate(_ data: Data, key: SymmetricKey) -> Data {
-    Data(HMAC<SHA256>.authenticationCode(for: data, using: key))
-}
+Secure: use the hash that fits the job.
 
-// Password storage  -  NEVER raw hashes. Use a KDF:
-// Server-side: Argon2id, bcrypt, or scrypt
-// On-device: PBKDF2 with ≥600,000 iterations (OWASP 2023 minimum for HMAC-SHA256)
-// See cryptokit-symmetric.md for full PBKDF2 implementation
+```swift
+let fingerprint = SHA256.hash(data: download)
+let tag = HMAC<SHA256>.authenticationCode(for: message, using: macKey)
 ```
 
-iOS 26 adds SHA-3 family (`SHA3_256`, `SHA3_384`, `SHA3_512`) in CryptoKit. WWDC 2025-314 covers post-quantum additions (ML-KEM, ML-DSA), not SHA-3.
+Passwords are never hashed with a plain digest. Hash them on the server with Argon2id, bcrypt or scrypt. When a key must be derived on the device, use PBKDF2 with at least 600,000 iterations.
 
-**MASTG test:** MASTG-TEST-0211. **MASTG demos:** MASTG-DEMO-0015, MASTG-DEMO-0016. **Legacy:** MSTG-CRYPTO-1.
+iOS 26 adds `SHA3_256`, `SHA3_384` and `SHA3_512`. WWDC 2025 session 314 is about post-quantum cryptography and does not cover SHA-3.
 
-**Detection heuristic:**
+Standards: MASTG-TEST-0211, MASTG-DEMO-0015, MASTG-DEMO-0016 (legacy MSTG-CRYPTO-1).
 
-```bash
-grep -rn "Insecure\.\(MD5\|SHA1\)" --include="*.swift"
-grep -rn "CC_MD5\|CC_SHA1\|CC_MD5_DIGEST_LENGTH\|CC_SHA1_DIGEST_LENGTH" \
-  --include="*.swift" --include="*.m"
-```
+Detection: `Insecure.MD5` or `Insecure.SHA1`, plus `CC_MD5`, `CC_SHA1` and the matching digest-length constants in `.swift` and `.m` files.
 
----
+## 8. Secrets in logs
 
-## Anti-Pattern #8  -  Logging Sensitive Data
+Severity: High. OWASP: M9. Fix effort: Low.
 
-**Severity:** HIGH | **OWASP:** M9 (Insecure Data Storage) | **Fix effort:** Low
+Whatever `print()`, `NSLog()` or `os_log()` emits can persist in the device log, where Xcode's console, `idevicesyslog` or `log collect --device` retrieve it; on a jailbroken device any process can read it.
 
-`print()`, `NSLog()`, and `os_log()` with sensitive values persist in device logs  -  accessible via Xcode Console, `idevicesyslog`, and `log collect --device`. On jailbroken devices, any process reads log storage. Apple's `OSLogPrivacy` (iOS 14+): `.private` redacts in production; `.sensitive` (iOS 15+) always redacted.
+`OSLogPrivacy` (iOS 14 and later) controls redaction: `.private` values are hidden in production logs, and `.sensitive` (iOS 15 and later) is always hidden.
 
-**❌ Insecure  -  AI-generated pattern:**
+Insecure:
 
 ```swift
-func login(username: String, password: String) async throws {
-    print("Logging in with password: \(password)")       // In device logs!
-    let token = try await authService.authenticate(username, password)
-    print("Got auth token: \(token)")                     // In device logs!
-    os_log("API key loaded: %{public}@", apiKey)          // Explicitly public!
-}
+print("login ok, token=\(token)")
+os_log("using key %{public}@", apiKey)
 ```
 
-**✅ Secure  -  OSLogPrivacy with redaction:**
+Secure:
 
 ```swift
-import os
-
-let logger = Logger(subsystem: Bundle.main.bundleIdentifier!, category: "auth")
-
-func login(username: String, password: String) async throws {
-    // Log events, not values  -  .private(mask: .hash) enables correlation
-    logger.info("Login attempt: \(username, privacy: .private(mask: .hash))")
-    let token = try await authService.authenticate(username, password)
-    logger.info("Authentication succeeded")  // No token value
-}
-
-// Legacy os_log
-os_log("Account: %{private}@", log: .default, type: .info, accountNumber)
-
-// Strip debug logging in release builds
-#if DEBUG
-print("Debug: \(sensitiveValue)")
-#endif
+let authLog = Logger(subsystem: "com.example.courier", category: "auth")
+authLog.info("sign-in succeeded")
+authLog.debug("session \(sessionID, privacy: .private(mask: .hash))")
 ```
 
-**MASTG tests:** MASTG-TEST-0296, MASTG-TEST-0297. **MASWE:** MASWE-0001. **Legacy:** MSTG-STORAGE-3.
+Log the event, not the value. `.private(mask: .hash)` still lets you correlate entries for the same session. With the older API, use `%{private}@`. Keep any diagnostic `print` inside `#if DEBUG`.
 
-**Detection heuristic:**
+Standards: MASTG-TEST-0296, MASTG-TEST-0297, MASWE-0001 (legacy MSTG-STORAGE-3).
 
-```bash
-grep -rn "print(.*\\\(" --include="*.swift" | \
-  grep -iE "password|token|secret|key|credential|ssn|credit"
-grep -rn "NSLog(.*%@" --include="*.swift" --include="*.m" | \
-  grep -iE "password|token|secret|key"
-grep -rn 'os_log.*%{public}' --include="*.swift" | \
-  grep -iE "password|token|secret|key"
-```
-
----
+Detection: `print(` with string interpolation, `NSLog(` with `%@`, and `os_log` with `%{public}` near words like password, token, secret or key.
 
-## Anti-Pattern #9  -  Not Clearing Keychain on First Launch
+## 9. No keychain cleanup after reinstall
 
-**Severity:** MEDIUM | **OWASP:** M9 (Insecure Data Storage) | **Fix effort:** Low
+Severity: Medium. OWASP: M9. Fix effort: Low.
 
-Keychain items persist in a system-wide encrypted database managed by `securityd`, outside the app sandbox. App deletion removes the sandbox but keychain items survive. Apple DTS engineer Quinn "The Eskimo!" confirmed this as "currently expected behaviour despite being an obvious privacy concern." Consequences: stale credentials on reinstall, cross-user data leakage on device resale, and Firebase SDK authentication errors on reinstall. Full migration patterns: see `migration-legacy-stores.md`.
+The keychain database lives in `securityd`, outside the app container, so items survive deleting the app. Apple DTS has described this as expected behaviour even though it has privacy consequences. The effects: stale credentials after reinstall, one user's session leaking to the next owner of a resold device, and backend SDKs failing authentication with leftover state.
 
-**❌ The missing pattern  -  AI never generates this:**
+Secure: before any SDK initialises, wait until protected data is readable, then check a marker in `UserDefaults`; if it is unset, delete every item class with `kSecAttrSynchronizable: kSecAttrSynchronizableAny` and set the marker.
 
 ```swift
-@main
-struct MyApp: App {
-    var body: some Scene {
-        WindowGroup { ContentView() }
+@MainActor
+func purgeKeychainOnFreshInstall() async {
+    await ReinstallSweeper.waitUntilProtectedDataIsReadable()
+    guard !UserDefaults.standard.bool(forKey: "vault.installMarker") else { return }
+    for itemClass in [kSecClassGenericPassword, kSecClassInternetPassword,
+                      kSecClassCertificate, kSecClassKey, kSecClassIdentity] {
+        let scope: [CFString: Any] = [kSecClass: itemClass,
+                                      kSecAttrSynchronizable: kSecAttrSynchronizableAny]
+        SecItemDelete(scope as CFDictionary)
     }
-    // Stale keychain items from previous install persist silently
+    UserDefaults.standard.set(true, forKey: "vault.installMarker")
 }
 ```
 
-**✅ Secure  -  first-launch keychain cleanup:**
+The protected-data wait is not optional. A pre-warmed launch before first unlock reads the marker as unset and would erase a signed-in user. The full version, including retry on failed deletes, is in [migration-legacy-stores.md](migration-legacy-stores.md).
 
-```swift
-@main
-struct MyApp: App {
-    init() { clearKeychainIfFirstLaunch() }
+Standards: MASTG-TEST-0300, MASTG-TEST-0301 (legacy MSTG-STORAGE-11).
 
-    var body: some Scene {
-        WindowGroup { ContentView() }
-    }
+Detection: files using `SecItemAdd` or `SecItemCopyMatching` with no first-launch marker anywhere in the project; files with `SecItemDelete` that reference such a marker are the cleanup to review.
 
-    private func clearKeychainIfFirstLaunch() {
-        let defaults = UserDefaults.standard
-        guard !defaults.bool(forKey: "hasLaunchedBefore") else { return }
-
-        // UserDefaults was cleared on uninstall → this is first launch
-        for secClass in [kSecClassGenericPassword, kSecClassInternetPassword,
-                         kSecClassCertificate, kSecClassKey, kSecClassIdentity] {
-            SecItemDelete([
-                kSecClass: secClass,
-                kSecAttrSynchronizable: kSecAttrSynchronizableAny
-            ] as NSDictionary)
-        }
-        defaults.set(true, forKey: "hasLaunchedBefore")
-    }
-}
-```
+## 10. Weak randomness for security values
 
-Place this before initializing any SDKs (Firebase, analytics) that read from Keychain. Including `kSecAttrSynchronizableAny` ensures iCloud Keychain items are also cleared.
+Severity: High. OWASP: M10. Fix effort: Low.
 
-**MASTG tests:** MASTG-TEST-0300, MASTG-TEST-0301. **Legacy:** MSTG-STORAGE-11.
+The generator and the amount of entropy both matter.
 
-**Detection heuristic:**
+- `rand()`, `random()`, `drand48()` and `srand(time(nil))` are predictable and never acceptable. GameplayKit sources such as `GKMersenneTwisterRandomSource` and `GKARC4RandomSource` are built for games and are not for security either.
+- `arc4random`, `arc4random_buf` and `arc4random_uniform` are backed by the system cryptographic generator on Apple platforms, as their manual page states, and so is Swift's `SystemRandomNumberGenerator`, which `randomElement()` and `Int.random(in:)` use by default. The generator is fine; the usual defect is how little of it the code uses. `arc4random()` returns a single 32-bit `UInt32`, `arc4random() % n` adds modulo bias, and `arc4random_uniform(999_999)` produces a token with about 20 bits of entropy. A few `randomElement()` picks from a character set make an equally guessable session identifier. These functions also cannot report failure.
+- For keys, tokens, salts and nonces, prefer `SecRandomCopyBytes`, which draws from the same system generator (corecrypto, seeded from hardware entropy), returns a status you can check, and makes the security intent obvious in review. For key material, use `SymmetricKey(size: .bits256)` directly.
 
-```bash
-grep -rn "SecItemAdd\|SecItemCopyMatching" --include="*.swift" -l | \
-  xargs grep -L "hasLaunchedBefore\|isFirstLaunch\|firstRun"
-grep -rn "SecItemDelete" --include="*.swift" -l | \
-  xargs grep "hasLaunchedBefore\|isFirstLaunch"
-```
-
----
-
-## Anti-Pattern #10  -  Non-Cryptographic RNG for Security Operations
-
-**Severity:** HIGH | **OWASP:** M10 (Insufficient Cryptography) | **Fix effort:** Low
-
-`arc4random()` returns only 32-bit `UInt32`  -  insufficient for cryptographic purposes requiring 128-256 bits. Character-by-character token construction introduces bias. Truly non-cryptographic alternatives (`rand()`, `drand48()`, GameplayKit RNG) must never be used for security operations.
-
-**❌ Insecure  -  AI-generated patterns:**
+Insecure:
 
 ```swift
-func generateToken() -> String {
-    return String(arc4random_uniform(999_999))  // ~20 bits of entropy
-}
-
-func generateSessionId(length: Int = 16) -> String {
-    let chars = "abcdefghijklmnopqrstuvwxyz0123456789"
-    return String((0..<length).map { _ in chars.randomElement()! })  // Bias
-}
-// Also dangerous: srand48/drand48, rand(), GameplayKit RNG
+let resetCode = String(arc4random_uniform(999_999))
+let sessionID = String((0..<6).compactMap { _ in "abcdef0123456789".randomElement() })
 ```
 
-**✅ Secure  -  SecRandomCopyBytes / CryptoKit:**
+Secure:
 
 ```swift
-import Security
-import CryptoKit
-
-// SecRandomCopyBytes  -  canonical iOS crypto RNG
-func generateSecureToken(byteCount: Int = 32) throws -> String {
-    var bytes = [UInt8](repeating: 0, count: byteCount)
+func makeSessionToken() throws -> String {
+    var bytes = [UInt8](repeating: 0, count: 32)
     let status = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
-    guard status == errSecSuccess else {
-        throw CryptoError.randomGenerationFailed(status)
-    }
+    guard status == errSecSuccess else { throw KeychainFailure(status) }
     return bytes.map { String(format: "%02x", $0) }.joined()
 }
 
-// CryptoKit key generation (secure RNG internally)
-let encryptionKey = SymmetricKey(size: .bits256)
+let wrappingKey = SymmetricKey(size: .bits256)
 ```
 
-`SecRandomCopyBytes` sources entropy from the Secure Enclave's hardware TRNG via corecrypto's `ccrng_generate`. It reports errors via return status  -  unlike `arc4random`, which silently cannot fail.
-
-**MASTG test:** MASTG-TEST-0311. **MASTG demos:** MASTG-DEMO-0073, MASTG-DEMO-0074. **Legacy:** MSTG-CRYPTO-6.
-
-**Detection heuristic:**
-
-```bash
-grep -rn "arc4random\|arc4random_uniform\|arc4random_buf" --include="*.swift" | \
-  grep -iE "token|nonce|salt|key|secret|session|iv"
-grep -rn "\bsrand\b\|\brand()\|\brandom()\|\bdrand48\b" --include="*.swift"
-grep -rn "GKARC4RandomSource\|GKMersenneTwisterRandomSource" --include="*.swift"
-```
-
----
-
-## Quick Reference Matrix
-
-| #   | Anti-Pattern             | OWASP 2024 | MASTG Test      | Dangerous API              | Secure API                          | Fix Effort |
-| --- | ------------------------ | ---------- | --------------- | -------------------------- | ----------------------------------- | ---------- |
-| 1   | UserDefaults secrets     | M9         | MASTG-TEST-0302 | `UserDefaults.set`         | `SecItemAdd` + Keychain             | Medium     |
-| 2   | Hardcoded API keys       | M1         | MASTG-TEST-0213 | String literals            | Server proxy + Keychain cache       | High       |
-| 3   | LAContext-only biometric | M3         | MASTG-TEST-0266 | `evaluatePolicy`           | `SecAccessControlCreateWithFlags`   | Medium     |
-| 4   | Ignored SecItem errors   | M8         | MASTG-TEST-0300 | Unchecked `SecItemAdd`     | OSStatus switch + `SecItemUpdate`   | Low        |
-| 5   | Wrong data protection    | M9         | MASTG-TEST-0299 | `kSecAttrAccessibleAlways` | `WhenUnlockedThisDeviceOnly`        | Low        |
-| 6   | Nonce reuse AES-GCM      | M10        | MASTG-TEST-0317 | `AES.GCM.Nonce(data:)`     | Omit nonce (auto-random)            | Medium     |
-| 7   | MD5/SHA-1 for security   | M10        | MASTG-TEST-0211 | `Insecure.MD5/.SHA1`       | `SHA256`+ / KDF for passwords       | Low        |
-| 8   | Logging sensitive data   | M9         | MASTG-TEST-0297 | `print(token)`             | `Logger` + `.private`               | Low        |
-| 9   | No keychain cleanup      | M9         | MASTG-TEST-0300 | Missing cleanup            | UserDefaults flag + `SecItemDelete` | Low        |
-| 10  | Non-crypto RNG           | M10        | MASTG-TEST-0311 | `arc4random()`             | `SecRandomCopyBytes`                | Low        |
-
----
-
-## CI/CD Detection Strategy
-
-**Semgrep** (pre-commit/PR gate): Fast structural pattern matching for `UserDefaults` misuse, missing `errSecDuplicateItem`, `LAContext` booleans. Limited data-flow analysis.
-
-**CodeQL** (nightly/PR gate): Deep semantic taint tracking  -  catches tokens assigned to variables then logged. Slower execution.
+Standards: MASTG-TEST-0311, MASTG-DEMO-0073, MASTG-DEMO-0074 (legacy MSTG-CRYPTO-6).
 
-**Binary scanning** (post-build): `strings`/`class-dump` on compiled binary catches hardcoded keys surviving source-level obfuscation.
+Detection: `srand`, `rand()`, `random()`, `drand48`, `GKARC4RandomSource`, `GKMersenneTwisterRandomSource` are findings. `arc4random` calls near token, nonce, salt, key, secret, session or iv are review prompts: check how many bits the value carries.
 
-Recommended: Semgrep on every PR + post-build binary scanning. CodeQL nightly for deep analysis.
+## Quick reference
 
----
+| # | OWASP | Main MASTG test | Look for | Replace with | Effort |
+| --- | --- | --- | --- | --- | --- |
+| 1 | M9 | 0302 | `UserDefaults.set` of a secret | `SecItemAdd` with update on duplicate | Medium |
+| 2 | M1 | 0213 | Key literals | Server proxy, runtime fetch cached in keychain | High |
+| 3 | M3 | 0266 | `evaluatePolicy` as the gate | `SecAccessControlCreateWithFlags` | Medium |
+| 4 | M8 | 0300 | Unchecked `SecItemAdd` | Status `switch` with update on duplicate | Low |
+| 5 | M9 | 0299 | `Always`, missing class | `WhenUnlockedThisDeviceOnly` or stricter | Low |
+| 6 | M10 | 0317 | `AES.GCM.Nonce(data:)` | Let CryptoKit choose the nonce | Medium |
+| 7 | M10 | 0211 | `Insecure.*` | SHA-256 or stronger, a password KDF | Low |
+| 8 | M9 | 0297 | `print(token)` | `Logger` with `.private` | Low |
+| 9 | M9 | 0300 | No reinstall cleanup | Marker plus `SecItemDelete` after protected data | Low |
+| 10 | M10 | 0311 | Low-entropy or predictable RNG | `SecRandomCopyBytes`, `SymmetricKey` | Low |
 
-## iOS 26 / WWDC 2025 Implications
+## Automating detection in CI
 
-WWDC 2025-314 introduced the most significant CryptoKit expansion since 2019:
+- **Semgrep**: fast structural rules, ideal as a pre-commit hook or pull-request gate for `UserDefaults` secrets, add calls without duplicate handling and Boolean biometric gates. Its data-flow tracking is limited.
+- **CodeQL**: semantic taint analysis, for example a token flowing into a logging call. Slower; run nightly or on pull requests.
+- **Binary scan after the build**: `strings` and `class-dump` over the built product catch keys that survived obfuscation or came in through configuration files.
 
-- **Symmetric keys:** `.bits256` recommended over `.bits128` for quantum resistance (anti-patterns #6, #10)
-- **Hashing:** SHA-3 family (`SHA3_256/384/512`) in CryptoKit on iOS 26+ (anti-pattern #7)
-- **Post-quantum:** ML-KEM 768/1024, ML-DSA 65/87, X-Wing  -  all with Secure Enclave support
-- **TLS:** `X25519MLKEM768` enabled by default for `URLSession` in iOS 26
-- **Secure Enclave:** Hardware post-quantum key creation strengthens anti-patterns #3 and #5 fixes
+A practical setup runs Semgrep on every pull request, a binary scan after each build, and CodeQL nightly.
 
----
+## What iOS 26 changes
 
-## Summary Checklist
+Prefer `.bits256` symmetric keys over `.bits128` for headroom against quantum attacks. The SHA-3 family is available from iOS 26. CryptoKit adds ML-KEM-768 and ML-KEM-1024, ML-DSA-65 and ML-DSA-87, and the X-Wing hybrid KEM, with Secure Enclave support, and `URLSession` negotiates the hybrid `X25519MLKEM768` TLS key exchange by default. Creating post-quantum keys in the Secure Enclave strengthens the fixes for entries 3 and 5.
 
-When reviewing iOS code for security anti-patterns, verify each item:
+## Checklist
 
-1. **No secrets in UserDefaults**  -  tokens, passwords, API keys, JWTs use Keychain with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` or stricter
-1. **No hardcoded keys in source**  -  API keys fetched at runtime via server proxy or authenticated endpoint; no high-entropy string literals, no secrets in `.xcconfig` or `Info.plist`
-1. **Biometrics bound to Keychain**  -  `evaluatePolicy` is never used alone to gate sensitive actions; `SecAccessControlCreateWithFlags` with `.biometryCurrentSet` protects keychain items
-1. **All SecItem calls checked**  -  `SecItemAdd` handles `errSecDuplicateItem` with `SecItemUpdate` fallback; `SecItemCopyMatching` handles `errSecItemNotFound`; no discarded `OSStatus` return values
-1. **Explicit data protection class**  -  every `SecItemAdd` includes `kSecAttrAccessible` or `kSecAttrAccessControl`; no `kSecAttrAccessibleAlways`; `ThisDeviceOnly` variants used for non-syncing items
-1. **No nonce reuse**  -  `AES.GCM.seal` called without explicit `nonce:` parameter (auto-random); no stored/global/counter-based nonce variables
-1. **No broken hashes**  -  no `Insecure.MD5`, `Insecure.SHA1`, `CC_MD5`, `CC_SHA1` for security purposes; passwords use a password KDF such as Argon2id, bcrypt, or PBKDF2-HMAC-SHA256 with at least 600,000 iterations
-1. **No sensitive data in logs**  -  `print()` and `NSLog()` never contain tokens, keys, or credentials; `os_log` uses `%{private}@`; `Logger` uses `.private` or `.private(mask: .hash)`
-1. **First-launch keychain cleanup**  -  `UserDefaults` flag + `SecItemDelete` for all classes runs before SDK initialization at app startup
-1. **Cryptographic RNG only**  -  `SecRandomCopyBytes` or CryptoKit APIs for tokens, nonces, salts, keys; no `arc4random` / `rand()` / `drand48()` / GameplayKit RNG in security contexts
-1. **iOS 26 readiness**  -  symmetric keys use `.bits256`; no deprecated algorithms; aware of post-quantum CryptoKit APIs for forward-looking implementations
+- [ ] No secrets in `UserDefaults` or `@AppStorage`; keychain with `WhenUnlockedThisDeviceOnly` or stricter.
+- [ ] No hardcoded keys or high-entropy literals; nothing secret in `.xcconfig` or `Info.plist`.
+- [ ] Biometrics unlock a keychain item protected with `.biometryCurrentSet`.
+- [ ] Every `SecItem` call checks its status; duplicates are updated, not-found is handled.
+- [ ] Every add sets accessibility or access control; no `Always`; `ThisDeviceOnly` for items that should not sync.
+- [ ] No explicit, global or counter nonces.
+- [ ] No MD5 or SHA-1; passwords go through Argon2id, bcrypt, or PBKDF2-HMAC-SHA256 with at least 600,000 iterations.
+- [ ] No secrets in logs; `%{private}@`, or `Logger` with `.private` or `.private(mask: .hash)`.
+- [ ] Reinstall cleanup runs before SDK setup and after protected data is available.
+- [ ] Security values come from a cryptographic generator with enough bits.
+- [ ] Ready for iOS 26: `.bits256`, no deprecated algorithms, post-quantum APIs on the radar.