@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swift-security/references/credential-storage-patterns.md

@@ -1,752 +1,754 @@
 # Credential Storage Patterns
 
-> Scope: Secure lifecycle patterns for client-side credentials on Apple platforms, including storage, refresh, rotation, migration, and logout cleanup.
-
-The iOS Keychain is the only Apple-sanctioned storage mechanism for OAuth tokens, API keys, passwords, and other credentials. Cybernews found in 2025 that 71% of iOS apps leak at least one hardcoded secret  -  primarily through `UserDefaults`, `Info.plist`, or `.xcconfig` files that produce plaintext artifacts trivially extractable from device backups or IPA bundles. This reference covers the complete credential lifecycle: secure storage via Keychain Services, OAuth2/OIDC authentication flows, atomic token refresh with rotation, runtime secret fetching, key rotation strategies, and comprehensive logout cleanup.
-
-Authoritative sources: Apple Developer Documentation (Keychain Services, Authentication Services), Apple Platform Security Guide (December 2024), WWDC 2019 Session 516 "What's New in Authentication", WWDC 2021 Session 10105 "Secure login with iCloud Keychain verification codes", WWDC 2024 Session 10125 "Streamline sign-in with passkey upgrades and credential managers", OWASP Mobile Top 10 2024, MASVS v2.1.0 (January 2024), MASTG v2, CISA/FBI "Product Security Bad Practices" advisory v2.0 (January 2025), and the Cybernews iOS app security research (March 2025).
-
----
+OAuth tokens, API keys and passwords have exactly one place Apple sanctions for
+them on the device: the Keychain. When a 2025 study pulled apart App Store
+binaries, 71% of the iOS apps it examined exposed one or more embedded secrets, most
+often through `UserDefaults`,
+`Info.plist` or `.xcconfig` values, all of which can be read out of a backup or an
+unzipped IPA.
+
+This file covers the storage lifecycle: where credentials go, how they are written
+and refreshed, how they are cleared, rotated and migrated. The sign-in UI itself
+(Sign in with Apple, passkeys, `ASAuthorizationController`) belongs to the
+`authentication` skill, and App Attest belongs to `device-integrity`; both appear
+here only as far as token storage depends on them.
+
+Grounding: Apple's Keychain Services and Authentication Services documentation; the
+December 2024 edition of the Platform Security Guide; WWDC sessions 516 (2019), 10105
+(2021) and 10125 (2024); on the OWASP side the 2024 Mobile Top 10, the January 2024
+MASVS release 2.1.0 and MASTG version 2; version 2.0 of the joint CISA and FBI list of
+product security bad practices, published January 2025; and a March 2025 industry
+survey of secrets in iOS apps.
 
 ## Contents
 
-- [The Six Anti-Patterns AI Code Generators Reproduce](#the-six-anti-patterns-ai-code-generators-reproduce)
-  - [Anti-Pattern 1  -  Tokens in UserDefaults](#anti-pattern-1-tokens-in-userdefaults)
-  - [Anti-Pattern 2  -  Hardcoded API Keys in Source Code](#anti-pattern-2-hardcoded-api-keys-in-source-code)
-  - [Anti-Pattern 3  -  Production Secrets in .xcconfig](#anti-pattern-3-production-secrets-in-xcconfig)
-  - [Anti-Pattern 4  -  Missing kSecAttrAccessible Specification](#anti-pattern-4-missing-ksecattraccessible-specification)
-  - [Anti-Pattern 5  -  Non-Atomic Token Refresh](#anti-pattern-5-non-atomic-token-refresh)
-  - [Anti-Pattern 6  -  Incomplete Credential Clearing on Logout](#anti-pattern-6-incomplete-credential-clearing-on-logout)
-  - [Correct Baseline for Credential Storage](#correct-baseline-for-credential-storage)
-- [Data Protection Class Selection for Credentials](#data-protection-class-selection-for-credentials)
-- [Actor-Based KeychainManager  -  Thread-Safe Credential Storage](#actor-based-keychainmanager-thread-safe-credential-storage)
-- [OAuth2 Token Storage and Retrieval Cycle](#oauth2-token-storage-and-retrieval-cycle)
-  - [Token Model](#token-model)
-  - [ASWebAuthenticationSession + PKCE Flow](#aswebauthenticationsession-pkce-flow)
-- [Atomic Token Refresh with Rotation Support](#atomic-token-refresh-with-rotation-support)
-  - [Refresh Coordinator with Promise Coalescing](#refresh-coordinator-with-promise-coalescing)
-- [Runtime API Key Fetching with Keychain Cache and TTL](#runtime-api-key-fetching-with-keychain-cache-and-ttl)
-- [Comprehensive Credential Clearing on Logout](#comprehensive-credential-clearing-on-logout)
-- [Key Rotation and Versioned Migration](#key-rotation-and-versioned-migration)
-  - [Rotation Strategies by Secret Type](#rotation-strategies-by-secret-type)
-  - [Versioned Keychain Items for Migration](#versioned-keychain-items-for-migration)
-  - [Detecting Compromised Credentials](#detecting-compromised-credentials)
-- [Device Binding and Backup Implications](#device-binding-and-backup-implications)
-- [Biometric Protection for High-Value Credentials](#biometric-protection-for-high-value-credentials)
-- [iOS 17+ and 18+ Modernizations](#ios-17-and-18-modernizations)
-- [Static Analysis and CI/CD Guardrails](#static-analysis-and-cicd-guardrails)
-- [OWASP MASTG Compliance Mapping](#owasp-mastg-compliance-mapping)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## The Six Anti-Patterns AI Code Generators Reproduce
-
-AI coding assistants routinely generate insecure credential handling. Each anti-pattern below is documented with evidence, an incorrect code sample, and the correct alternative.
-
-### Anti-Pattern 1  -  Tokens in UserDefaults
-
-`UserDefaults` writes an unencrypted XML plist at `/var/mobile/Containers/Data/Application/{APP_ID}/Library/Preferences/{BUNDLE_ID}.plist`. This file is included in iTunes/Finder device backups, readable with iMazing or iExplorer on non-jailbroken devices, and trivially extractable on jailbroken devices via `objection`'s `ios nsuserdefaults get` command. Apple's documentation is explicit: the defaults system stores information on disk in an unencrypted format and must not be used for personal or sensitive information.
-
-```swift
-// ❌ INCORRECT  -  AI-generated token storage in UserDefaults
-// Tokens are written as plaintext XML plist, readable from device backups
-func saveTokens(accessToken: String, refreshToken: String) {
-    UserDefaults.standard.set(accessToken, forKey: "access_token")
-    UserDefaults.standard.set(refreshToken, forKey: "refresh_token")
-}
-```
-
-**OWASP mapping:** Violates M9 (Insecure Data Storage), MASVS-STORAGE-1, MASWE-0002, and fails MASTG-TEST-0300/0301.
-
-> For the canonical ❌/✅ code samples, objection detection commands, and full remediation checklist for this pattern, see `common-anti-patterns.md` section Anti-Pattern #1  -  Storing Secrets in UserDefaults.
-
-### Anti-Pattern 2  -  Hardcoded API Keys in Source Code
-
-CISA and the FBI classify hardcoded credentials as a formal "bad security practice" (CWE-798, ranked in 2024 CWE Top 25). The Cybernews research team found 815,000+ hardcoded secrets across 156,080 iOS apps simply by unzipping IPA files and scanning plaintext  -  no decompilation required.
-
-```swift
-// ❌ INCORRECT  -  Hardcoded API key discoverable via `strings` on the Mach-O binary
-struct APIConfig {
-    static let stripeSecretKey = "sk_live_51ABC123DEF456..."
-    static let firebaseAPIKey = "AIzaSyB1234567890abcdefg"
-}
-// Attacker runs: strings MyApp.app/MyApp | grep "sk_live"
-```
-
-**OWASP mapping:** Violates M1 (Improper Credential Usage), MASWE-0005, and CISA/FBI advisory item #8.
-
-### Anti-Pattern 3  -  Production Secrets in .xcconfig
-
-The `.xcconfig` pattern solves only the git-commit problem. When you reference `$(MY_API_KEY)` in Info.plist, Xcode resolves the variable at build time and embeds the literal plaintext value in the compiled Info.plist inside the `.app` bundle. Extraction takes seconds: rename `.ipa` to `.zip`, unzip, open Info.plist.
+- [Six ways credentials leak](#six-ways-credentials-leak)
+- [Choosing the protection class](#choosing-the-protection-class)
+- [One actor in front of the Keychain](#one-actor-in-front-of-the-keychain)
+- [OAuth tokens: from sign-in to Keychain](#oauth-tokens-from-sign-in-to-keychain)
+- [Refresh that survives crashes and races](#refresh-that-survives-crashes-and-races)
+- [API keys fetched at runtime](#api-keys-fetched-at-runtime)
+- [Logout clears everything](#logout-clears-everything)
+- [Rotation and versioned storage](#rotation-and-versioned-storage)
+- [Device binding and restores](#device-binding-and-restores)
+- [Biometrics on high-value credentials](#biometrics-on-high-value-credentials)
+- [What iOS 17 and 18 changed](#what-ios-17-and-18-changed)
+- [Guardrails in CI](#guardrails-in-ci)
+- [OWASP mapping](#owasp-mapping)
+- [The three decisions that matter](#the-three-decisions-that-matter)
+- [Checklist](#checklist)
+
+## Six ways credentials leak
+
+**1. UserDefaults.** Values are written as plain XML into the app container's
+`Library/Preferences` folder, in a plist named after the bundle identifier
+(under `/var/mobile/Containers/Data/Application/` on the device).
+That file is part of Finder and iTunes backups and desktop backup browsers read it
+from a non-jailbroken phone; on a jailbroken one, `objection` reads it with
+`ios nsuserdefaults get`. Apple's documentation says not to keep sensitive data
+there. OWASP mapping: Top 10 M9, control MASVS-STORAGE-1, weakness MASWE-0002; it
+fails MASTG-TEST-0300 and MASTG-TEST-0301. Code
+samples are in [common-anti-patterns.md](common-anti-patterns.md) (#1).
+
+**2. Keys in source.** CISA and the FBI list hardcoded credentials as a bad practice
+(item 8 of their list), and CWE-798 sits in the 2024 CWE Top 25. The 2025 study pulled
+more than 815,000 secrets from 156,080 iOS apps just by unzipping IPAs; payment and
+backend API keys fall out of `strings MyApp | grep sk_live`. Maps to M1 and
+MASWE-0005.
+
+**3. `.xcconfig` as a hiding place.** It keeps a secret out of git, nothing more. A
+`$(API_TOKEN)` reference in `Info.plist` is substituted at build time, so the
+plaintext value ships in the bundle; `unzip` the IPA and run `plutil -p` on
+`Info.plist` to see it.
+
+**4. No explicit accessibility.** Without `kSecAttrAccessible` the item gets
+`kSecAttrAccessibleWhenUnlocked` (the default since iOS 4). That class migrates to a
+new device through an encrypted backup, and on a device without a passcode it is
+effectively always unlocked. Set `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` to
+keep the item on this hardware.
+
+**5. Non-atomic refresh.** Deleting the old tokens, then crashing before the new ones
+are stored, leaves the user signed out or half signed in. Two refreshes racing can
+store a refresh token the server already rotated away; with refresh token rotation
+(RTR) replaying it can revoke the whole token family.
+
+**6. Partial logout.** Removing the access token but leaving the refresh token behind
+keeps a longer-lived credential on the device that can mint new access tokens.
 
 ```swift
-// ❌ INCORRECT  -  .xcconfig value compiled into Info.plist as plaintext
-// In Secrets.xcconfig:  MAPS_API_KEY = gm_pk_a1b2c3d4e5f6g7h8i9
-// In Info.plist:         <key>MapsAPIKey</key><string>$(MAPS_API_KEY)</string>
-
-let apiKey = Bundle.main.infoDictionary?["MapsAPIKey"] as? String
-// Attacker: unzip App.ipa && plutil -p Payload/App.app/Info.plist | grep Maps
-```
-
-### Anti-Pattern 4  -  Missing kSecAttrAccessible Specification
-
-When you add a Keychain item without specifying `kSecAttrAccessible`, the system applies the default: `kSecAttrAccessibleWhenUnlocked` (iOS 4.0+). While reasonable, this default allows Keychain items to migrate to new devices via encrypted backups and treats devices without a passcode as "always unlocked." Explicitly setting `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` prevents backup migration and confines the credential to the original hardware.
-
-### Anti-Pattern 5  -  Non-Atomic Token Refresh
-
-When an access token expires, the app must delete the old token and store the new one. If the app crashes between these operations, the Keychain enters an inconsistent state. Concurrent refresh attempts compound the problem: two threads can both detect expiry, both call the refresh endpoint, and one writes a stale or already-rotated refresh token. With Refresh Token Rotation (RTR), this race can invalidate the entire token family.
-
-### Anti-Pattern 6  -  Incomplete Credential Clearing on Logout
-
-The most common partial-cleanup bug is deleting the access token while leaving the refresh token in the Keychain. A refresh token is often longer-lived and more powerful  -  it can silently generate new access tokens.
-
-```swift
-// ❌ INCORRECT  -  Partial cleanup leaves refresh token behind
-func logout() {
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: "com.myapp.auth",
-        kSecAttrAccount as String: "access_token"
-    ]
-    SecItemDelete(query as CFDictionary)
-    // BUG: refresh_token, user_profile, cached API keys all remain
-}
+// Broken logout: only one of two credentials removed
+let query: [String: Any] = [
+    kSecClass as String: kSecClassGenericPassword,
+    kSecAttrService as String: "com.example.bank.auth",
+    kSecAttrAccount as String: "access_token"
+]
+SecItemDelete(query as CFDictionary)
 ```
 
-### Correct Baseline for Credential Storage
-
-✅ Store credentials in Keychain, not `UserDefaults`/plist/source literals.
-✅ Set `kSecAttrAccessible` explicitly for each item based on access pattern.
-✅ Use add-or-update semantics and handle all `OSStatus` outcomes.
-✅ Delete all credential artifacts (access token, refresh token, derived caches) on logout.
+The baseline that avoids all six: Keychain only, an explicit accessibility class on
+every item, add-then-update-on-duplicate writes that check every `OSStatus`, and a
+logout that removes every credential artifact.
 
----
+## Choosing the protection class
 
-## Data Protection Class Selection for Credentials
+Every Keychain row is protected twice with AES-256-GCM. Its attributes use a key the
+system keeps cached; its secret value uses a key specific to that row, and unwrapping
+that one means asking the Secure Enclave (details in [keychain-fundamentals.md](keychain-fundamentals.md)).
+Accessibility decides when that unwrap is allowed.
 
-Choosing the correct `kSecAttrAccessible` value is the highest-ROI decision for credential confidentiality. The Keychain encrypts items using dual AES-256-GCM keys: a metadata key (cached for fast searches) and a per-row secret key that always requires a Secure Enclave round trip (Apple Platform Security Guide, December 2024; full architecture: `keychain-fundamentals.md` section Two-Tier Encryption and Query Cost).
+| Class | Behaviour | Use for |
+| --- | --- | --- |
+| `WhenUnlockedThisDeviceOnly` | Device-bound, unavailable while locked | Recommended default: OAuth tokens, API keys |
+| `WhenPasscodeSetThisDeviceOnly` | Highest assurance; destroyed if the passcode is removed | High-value secrets |
+| `AfterFirstUnlockThisDeviceOnly` | Readable in the background after first unlock; longer exposure | Only when background work needs it, such as a silent push handler |
+| `AfterFirstUnlock` | Not device-bound; moves through backups | Avoid for sensitive tokens |
 
-| Accessibility Class                                | Device-Bound | Background Access       | Primary Use Case              | Risk Note                                                           |
-| -------------------------------------------------- | ------------ | ----------------------- | ----------------------------- | ------------------------------------------------------------------- |
-| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`     | Yes          | No                      | OAuth tokens, API keys        | **Recommended default**  -  strongest for credentials                 |
-| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`  | Yes          | No                      | Highest-assurance secrets     | Item permanently destroyed if user removes passcode                 |
-| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | Yes          | Yes (post-first unlock) | Background token refresh      | Larger exposure window; use only when background access is required |
-| `kSecAttrAccessibleAfterFirstUnlock`               | No           | Yes                     | Background + backup migration | Transfers via encrypted backup; avoid for sensitive tokens          |
+Do not set `kSecAttrSynchronizable` on session tokens. Syncing through iCloud
+Keychain is meant for passwords the user sees and manages, not for credentials an app
+minted for itself.
 
-**Rule of thumb:** Default to `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` for all OAuth tokens and API keys. Use `AfterFirstUnlockThisDeviceOnly` only when background refresh is required (e.g., silent push notification handling). Never use `kSecAttrSynchronizable` for app tokens  -  iCloud Keychain sync is designed for website passwords, not application secrets.
+More detail on classes and flags: [keychain-access-control.md](keychain-access-control.md).
 
-> For complete accessibility constant selection criteria, data protection tier explanations, and `SecAccessControl` interaction rules, see `keychain-access-control.md` section The "When" Layer: Seven Accessibility Constants.
+## One actor in front of the Keychain
 
----
-
-## Actor-Based KeychainManager  -  Thread-Safe Credential Storage
-
-The `SecItemAdd`, `SecItemCopyMatching`, `SecItemUpdate`, and `SecItemDelete` functions (all iOS 2.0+) are synchronous C functions performing IPC to the `securityd` daemon. They are thread-safe for independent items, but concurrent modifications to the same item produce race conditions  -  notably `errSecDuplicateItem` (-25299) when two threads both try to add a missing item simultaneously. A Swift actor (iOS 13+, idiomatic from iOS 17+ with mature concurrency) provides a serial executor that eliminates these races.
+The `SecItem*` functions (present since iOS 2.0) can be called from any thread when
+each call touches a different item. Two calls aimed at one item, however, race: two simultaneous adds end with one
+`errSecDuplicateItem`, and a read between a delete and an add sees nothing. An actor
+(iOS 13+, and the idiomatic choice in code targeting iOS 17 and later) serializes
+every operation.
 
 ```swift
-// ✅ CORRECT  -  Actor-based KeychainManager with proper kSecAttrAccessible
-// Requires: iOS 13+ (actors), recommended iOS 17+ for mature concurrency
 import Foundation
 import Security
 
-public actor KeychainManager {
-
-    public enum KeychainError: Error {
-        case unexpectedStatus(OSStatus), itemNotFound, encodingFailed, decodingFailed
+public actor CredentialVault {
+    public enum Failure: Error {
+        case status(OSStatus)
+        case missing
+        case encoding
+        case decoding
     }
 
-    let service: String
+    private let service: String
     private let accessGroup: String?
     private let accessibility: CFString
 
-    public init(service: String, accessGroup: String? = nil,
+    public init(service: String,
+                accessGroup: String? = nil,
                 accessibility: CFString = kSecAttrAccessibleWhenUnlockedThisDeviceOnly) {
-        self.service = service; self.accessGroup = accessGroup; self.accessibility = accessibility
+        self.service = service
+        self.accessGroup = accessGroup
+        self.accessibility = accessibility
     }
 
-    func baseQuery(account: String) -> [CFString: Any] {
-        var q: [CFString: Any] = [
-            kSecClass: kSecClassGenericPassword, kSecAttrService: service,
-            kSecAttrAccount: account, kSecAttrAccessible: accessibility
+    private func identity(for account: String) -> [String: Any] {
+        var query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account
         ]
-        if let accessGroup { q[kSecAttrAccessGroup] = accessGroup }
+        if let accessGroup { query[kSecAttrAccessGroup as String] = accessGroup }
         #if os(macOS)
-        q[kSecUseDataProtectionKeychain] = true   // iOS-style data protection on macOS
+        query[kSecUseDataProtectionKeychain as String] = true
         #endif
-        return q
+        return query
     }
 
-    /// Add-or-update semantics: try update first, fall back to add.
-    public func save(account: String, data: Data) throws {
-        var searchQ = baseQuery(account: account)
-        searchQ.removeValue(forKey: kSecAttrAccessible)
-        let attrs: [CFString: Any] = [kSecValueData: data, kSecAttrAccessible: accessibility]
-        var status = SecItemUpdate(searchQ as CFDictionary, attrs as CFDictionary)
-        if status == errSecItemNotFound {
-            var addQ = baseQuery(account: account); addQ[kSecValueData] = data
-            status = SecItemAdd(addQ as CFDictionary, nil)
-        }
-        guard status == errSecSuccess else { throw KeychainError.unexpectedStatus(status) }
+    public func store(_ secret: Data, account: String) throws {
+        var insert = identity(for: account)
+        insert[kSecValueData as String] = secret
+        insert[kSecAttrAccessible as String] = accessibility
+
+        let added = SecItemAdd(insert as CFDictionary, nil)
+        if added == errSecSuccess { return }
+        guard added == errSecDuplicateItem else { throw Failure.status(added) }
+
+        let changes: [String: Any] = [
+            kSecValueData as String: secret,
+            kSecAttrAccessible as String: accessibility
+        ]
+        let updated = SecItemUpdate(identity(for: account) as CFDictionary,
+                                    changes as CFDictionary)
+        guard updated == errSecSuccess else { throw Failure.status(updated) }
     }
 
-    public func load(account: String) throws -> Data {
-        var q = baseQuery(account: account)
-        q.removeValue(forKey: kSecAttrAccessible)
-        q[kSecReturnData] = kCFBooleanTrue; q[kSecMatchLimit] = kSecMatchLimitOne
-        var result: AnyObject?
-        let status = SecItemCopyMatching(q as CFDictionary, &result)
-        switch status {
-        case errSecSuccess: guard let d = result as? Data else { throw KeychainError.decodingFailed }; return d
-        case errSecItemNotFound: throw KeychainError.itemNotFound
-        default: throw KeychainError.unexpectedStatus(status)
-        }
+    public func read(account: String) throws -> Data {
+        var query = identity(for: account)
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+        var output: CFTypeRef?
+        let outcome = SecItemCopyMatching(query as CFDictionary, &output)
+        if outcome == errSecItemNotFound { throw Failure.missing }
+        guard outcome == errSecSuccess else { throw Failure.status(outcome) }
+        guard let payload = output as? Data else { throw Failure.decoding }
+        return payload
     }
 
-    public func delete(account: String) throws {
-        var q = baseQuery(account: account); q.removeValue(forKey: kSecAttrAccessible)
-        let s = SecItemDelete(q as CFDictionary)
-        guard s == errSecSuccess || s == errSecItemNotFound else { throw KeychainError.unexpectedStatus(s) }
+    public func remove(account: String) throws {
+        try Self.acceptingAbsence(SecItemDelete(identity(for: account) as CFDictionary))
     }
 
-    /// Delete ALL items for this service  -  used during logout.
-    public func deleteAll() throws {
-        var q: [CFString: Any] = [kSecClass: kSecClassGenericPassword, kSecAttrService: service as CFString]
-        if let accessGroup { q[kSecAttrAccessGroup] = accessGroup as CFString }
+    private static func acceptingAbsence(_ outcome: OSStatus) throws {
+        if outcome != errSecSuccess && outcome != errSecItemNotFound {
+            throw Failure.status(outcome)
+        }
+    }
+
+    public func removeEverything() throws {
+        var query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service
+        ]
+        if let accessGroup { query[kSecAttrAccessGroup as String] = accessGroup }
         #if os(macOS)
-        q[kSecUseDataProtectionKeychain] = true
+        query[kSecUseDataProtectionKeychain as String] = true
         #endif
-        let s = SecItemDelete(q as CFDictionary)
-        guard s == errSecSuccess || s == errSecItemNotFound else { throw KeychainError.unexpectedStatus(s) }
+        try Self.acceptingAbsence(SecItemDelete(query as CFDictionary))
     }
 }
 ```
 
-**Why an actor?** The actor's serial executor guarantees that `save`, `load`, `delete`, and `deleteAll` never interleave. Two concurrent callers hitting `save` for the same account queue instead of racing. The synchronous `SecItem*` C calls execute safely within the actor  -  callers `await` access, suspending rather than blocking the cooperative thread pool.
+Notes on the shape:
+
+- `store` adds first and updates only on `errSecDuplicateItem`. The update query is
+  the item's identity (class, service, account, group) and carries no accessibility
+  or data; the new data and accessibility go in the attributes dictionary. Any other
+  status throws. Deleting and re-adding is reserved for changing an item's
+  `kSecAttrAccessControl`, which cannot be updated in place.
+- `read` asks for data with a match limit of one and turns not-found into a typed
+  error. `remove` treats not-found as success. `removeEverything` deletes by class
+  and service (plus group) and is what logout calls.
+- Because this is an actor, none of these can interleave, and callers suspend
+  instead of blocking a thread in the cooperative pool.
 
-**Global actor alternative**  -  when Keychain serialization must span multiple modules:
+When the same serialization has to span several types or modules, a global actor
+does the job:
 
 ```swift
-// ✅ Pattern: Global actor for cross-module Keychain serialization
-// Requires: iOS 13.0+ (global actors via Swift 5.5+)
 @globalActor
-actor KeychainActor {
-    static let shared = KeychainActor()
+actor KeychainIsolation {
+    static let shared = KeychainIsolation()
 }
 
-@KeychainActor
-func saveCredential(_ data: Data, account: String) throws {
-    let query: [CFString: Any] = [
-        kSecClass: kSecClassGenericPassword,
-        kSecAttrService: "com.myapp.auth" as CFString,
-        kSecAttrAccount: account as CFString,
-        kSecAttrAccessible: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
-        kSecValueData: data
-    ]
-    let status = SecItemAdd(query as CFDictionary, nil)
-    guard status == errSecSuccess else {
-        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
-    }
+@KeychainIsolation
+func rotateDeviceSecret(using vault: CredentialVault) async throws {
+    let fresh = Data(UUID().uuidString.utf8)
+    try await vault.store(fresh, account: "device_secret")
 }
 ```
 
----
+### Storing CryptoKit keys with the same vault
+
+Apple's sample code for keeping CryptoKit keys in the Keychain defines a small protocol for
+keys that have no `SecKey` form (Curve25519, post-quantum keys, Secure Enclave
+blobs), so they can be kept as generic passwords:
+
+```swift
+import CryptoKit
+
+protocol GenericPasswordConvertible {
+    init<Bytes: ContiguousBytes>(rawRepresentation: Bytes) throws
+    var rawRepresentation: Data { get }
+}
+
+extension Curve25519.Signing.PrivateKey: GenericPasswordConvertible {}
 
-## OAuth2 Token Storage and Retrieval Cycle
+extension CredentialVault {
+    func storeKey<K: GenericPasswordConvertible>(_ key: K, account: String) throws {
+        try store(key.rawRepresentation, account: account)
+    }
+
+    func loadKey<K: GenericPasswordConvertible>(_ type: K.Type, account: String) throws -> K {
+        try K(rawRepresentation: read(account: account))
+    }
+}
+```
 
-`ASWebAuthenticationSession` (iOS 12.0+) is the mandatory standard for secure web-based login flows. Using legacy web views like `WKWebView` or `SFSafariViewController` for OAuth is a significant anti-pattern  -  they allow the host app to inspect web content or steal credentials. WWDC 2019 "What's New in Authentication" formally recommended migrating from the deprecated `SFAuthenticationSession` to `ASWebAuthenticationSession`.
+The write goes through the same add-then-update-on-duplicate `store`. Which key
+types need this and which go in as `kSecClassKey` is covered in
+[cryptokit-public-key.md](cryptokit-public-key.md).
 
-### Token Model
+## OAuth tokens: from sign-in to Keychain
+
+Web-based sign-in uses `ASWebAuthenticationSession` (iOS 12+). Running OAuth inside a
+`WKWebView` or `SFSafariViewController` is an anti-pattern: the hosting app can read
+or script the page and capture the password. WWDC 2019 also told apps to leave the
+deprecated `SFAuthenticationSession`. The UI side is the `authentication` skill's
+territory; what matters here is what gets stored.
 
 ```swift
-// ✅ CORRECT  -  Codable token model with expiry tracking
-struct OAuthTokens: Codable {
+struct SessionTokens: Codable {
     let accessToken: String
     let refreshToken: String
     let expiresAt: Date
     let tokenType: String
 
-    var isExpired: Bool {
-        Date() >= expiresAt
-    }
-
-    /// Proactive refresh before expiry.
-    /// Both providers agree: refresh at 75-90% of lifetime or with a fixed
-    /// buffer (e.g., 60 seconds) to account for network latency and clock skew.
-    var shouldRefresh: Bool {
-        let buffer: TimeInterval = 60
-        return Date() >= expiresAt.addingTimeInterval(-buffer)
-    }
+    var isExpired: Bool { Date() >= expiresAt }
+    var needsRefresh: Bool { Date().addingTimeInterval(60) >= expiresAt }
 }
 ```
 
-### ASWebAuthenticationSession + PKCE Flow
+Refresh before expiry, either with a fixed buffer (60 seconds above) or at 75-90% of
+the token lifetime, to absorb network latency and clock skew.
+
+The authorization-code flow with PKCE (RFC 7636) for a public client (no client
+secret on the device):
 
 ```swift
-// ✅ CORRECT  -  ASWebAuthenticationSession + PKCE + Keychain storage
-// Requires: iOS 13.0+ (for prefersEphemeralWebBrowserSession)
 import AuthenticationServices
 import CryptoKit
 
-final class OAuthManager: NSObject, ASWebAuthenticationPresentationContextProviding {
-
-    private let keychain = KeychainManager(
-        service: "com.myapp.auth",
-        accessibility: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
-    )
-    private let clientID = "mobile-app-client" // public client, no secret needed
-    private let redirectScheme = "com.myapp.auth"
-
-    func startAuthentication() async throws -> OAuthTokens {
-        let codeVerifier = generateCodeVerifier()  // RFC 7636 PKCE
-        let codeChallenge = generateCodeChallenge(from: codeVerifier)
-
-        var components = URLComponents(string: "https://auth.example.com/authorize")!
-        components.queryItems = [
-            URLQueryItem(name: "response_type", value: "code"),
-            URLQueryItem(name: "client_id", value: clientID),
-            URLQueryItem(name: "redirect_uri", value: "\(redirectScheme)://callback"),
-            URLQueryItem(name: "scope", value: "openid profile offline_access"),
-            URLQueryItem(name: "code_challenge", value: codeChallenge),
-            URLQueryItem(name: "code_challenge_method", value: "S256"),
-            URLQueryItem(name: "state", value: UUID().uuidString)
+func base64URL(_ data: Data) -> String {
+    data.base64EncodedString()
+        .replacingOccurrences(of: "+", with: "-")
+        .replacingOccurrences(of: "/", with: "_")
+        .replacingOccurrences(of: "=", with: "")
+}
+
+func makeVerifier() throws -> String {
+    var entropy = Data(count: 32)
+    let rc = entropy.withUnsafeMutableBytes { buffer in
+        buffer.baseAddress.map { SecRandomCopyBytes(kSecRandomDefault, 32, $0) } ?? errSecAllocate
+    }
+    guard rc == errSecSuccess else { throw CredentialVault.Failure.status(rc) }
+    return base64URL(entropy)
+}
+
+@MainActor
+final class SignInCoordinator: NSObject, ASWebAuthenticationPresentationContextProviding {
+    private let vault: CredentialVault
+    private let anchor: ASPresentationAnchor
+
+    init(vault: CredentialVault, anchor: ASPresentationAnchor) {
+        self.vault = vault
+        self.anchor = anchor
+    }
+
+    func presentationAnchor(for _: ASWebAuthenticationSession) -> ASPresentationAnchor { anchor }
+
+    func signIn() async throws {
+        let verifier = try makeVerifier()
+        let digest = SHA256.hash(data: Data(verifier.utf8))
+        let challenge = base64URL(Data(digest))
+        let state = UUID().uuidString
+
+        guard var parts = URLComponents(string: "https://login.example.com/authorize") else { return }
+        parts.queryItems = [
+            .init(name: "response_type", value: "code"),
+            .init(name: "client_id", value: "ios-reader"),
+            .init(name: "redirect_uri", value: "exampleapp://oauth"),
+            .init(name: "scope", value: ["openid", "profile", "offline_access"].joined(separator: " ")),
+            .init(name: "code_challenge", value: challenge),
+            .init(name: "code_challenge_method", value: "S256"),
+            .init(name: "state", value: state)
         ]
+        guard let authorizeURL = parts.url else { return }
 
-        let callbackURL: URL = try await withCheckedThrowingContinuation { continuation in
+        let callback: URL = try await withCheckedThrowingContinuation { waiter in
             let session = ASWebAuthenticationSession(
-                url: components.url!, callbackURLScheme: redirectScheme
-            ) { url, error in
-                if let error { continuation.resume(throwing: error) }
-                else if let url { continuation.resume(returning: url) }
+                url: authorizeURL, callbackURLScheme: "exampleapp"
+            ) { redirect, failure in
+                guard let redirect else {
+                    waiter.resume(throwing: failure ?? URLError(.cancelled))
+                    return
+                }
+                waiter.resume(returning: redirect)
             }
-            session.prefersEphemeralWebBrowserSession = true  // iOS 13+: no cookie sharing
+            session.prefersEphemeralWebBrowserSession = true
             session.presentationContextProvider = self
             session.start()
         }
 
-        guard let code = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)?
-            .queryItems?.first(where: { $0.name == "code" })?.value else {
-            throw OAuthError.missingAuthorizationCode
+        let returned = Dictionary(
+            (URLComponents(url: callback, resolvingAgainstBaseURL: false)?.queryItems ?? [])
+                .map { ($0.name, $0.value ?? "") },
+            uniquingKeysWith: { first, _ in first }
+        )
+        guard returned["state"] == state, let code = returned["code"] else {
+            throw URLError(.badServerResponse)
         }
 
-        let tokens = try await exchangeCodeForTokens(code: code, codeVerifier: codeVerifier)
-        try await keychain.save(account: "oauth_tokens", data: JSONEncoder().encode(tokens))
-        return tokens
+        let tokens = try await exchange(code: code, verifier: verifier)
+        try await vault.store(try JSONEncoder().encode(tokens), account: "oauth_tokens_v2")
     }
 
-    // MARK: - PKCE helpers (RFC 7636)
-
-    private func generateCodeVerifier() -> String {
-        var buffer = [UInt8](repeating: 0, count: 32)
-        _ = SecRandomCopyBytes(kSecRandomDefault, buffer.count, &buffer)
-        return Data(buffer).base64EncodedString()
-            .replacingOccurrences(of: "+", with: "-")
-            .replacingOccurrences(of: "/", with: "_")
-            .replacingOccurrences(of: "=", with: "")
-    }
-
-    private func generateCodeChallenge(from verifier: String) -> String {
-        // CryptoKit SHA256 (iOS 13.0+)  -  replaces legacy CC_SHA256
-        let hash = SHA256.hash(data: Data(verifier.utf8))
-        return Data(hash).base64EncodedString()
-            .replacingOccurrences(of: "+", with: "-")
-            .replacingOccurrences(of: "/", with: "_")
-            .replacingOccurrences(of: "=", with: "")
-    }
-
-    private func exchangeCodeForTokens(code: String, codeVerifier: String) async throws -> OAuthTokens {
-        // Standard OAuth2 token exchange  -  implement with your authorization server
-        fatalError("Implement token exchange")
+    private func exchange(code: String, verifier: String) async throws -> SessionTokens {
+        throw URLError(.unsupportedURL) // POST code + code_verifier to the token endpoint here
     }
-
-    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor { ASPresentationAnchor() }
-    enum OAuthError: Error { case missingAuthorizationCode }
 }
 ```
 
-**iOS 17.4+ improvement:** `ASWebAuthenticationSession.Callback` enables HTTPS universal link callbacks instead of custom URL schemes. Universal links provide a cryptographic guarantee of domain ownership, making them significantly less susceptible to interception (RFC 8252, OAuth 2.0 for Native Apps).
-
-**Privacy vs SSO trade-off:** Setting `prefersEphemeralWebBrowserSession = true` maximizes privacy and session isolation but breaks Single Sign-On. Toggle based on whether your app prioritizes strict isolation or seamless SSO.
+The verifier is 32 random bytes from `SecRandomCopyBytes`, base64url-encoded without
+padding; the challenge is base64url of its SHA-256, sent with method `S256`. The state
+value is checked on return. `prefersEphemeralWebBrowserSession = true` (iOS 13+) shares
+no cookies with Safari, which gives the strongest isolation at the cost of single
+sign-on; decide per product.
 
----
+From iOS 17.4, `ASWebAuthenticationSession.Callback` can use an HTTPS universal link
+as the redirect. That proves domain ownership and is much harder for another app to
+intercept than a custom scheme (RFC 8252).
 
-## Atomic Token Refresh with Rotation Support
+## Refresh that survives crashes and races
 
-When a server implements Refresh Token Rotation (RTR)  -  as Okta, Auth0, and others do  -  each refresh response includes a new refresh token and the old one is immediately invalidated. If the app stores the new access token but crashes before persisting the new refresh token, the user is locked out. The solution: update both tokens atomically within the actor's serial execution context.
+Identity providers that implement refresh token rotation issue a new refresh token
+on every refresh and invalidate the old one. If the app persists the new access token
+and the process dies before the matching refresh token reaches storage, the next
+launch has nothing valid to refresh with and the user must sign in again. Many
+providers keep the previous refresh token valid for a short grace period (often
+configurable from 0 to 60 seconds, 30 is common) so a retried request still works;
+presenting it after the grace period revokes the entire family, which the server
+treats as a sign of theft.
 
-Servers typically provide a short grace period (e.g., 30 seconds per Okta's configuration) during which the previous refresh token remains valid to handle network retries. If a previously invalidated token is reused outside the grace period, the server invalidates the entire token family  -  a strong signal of credential compromise.
+Store both tokens as one encoded item so that a single write replaces them together,
+encode before touching the Keychain, and route the write through the actor:
 
 ```swift
-// ✅ CORRECT  -  Atomic token refresh with rotation support
-// Requires: iOS 13.0+ (actor serialization guarantees no interleaving)
-extension KeychainManager {
-    func atomicTokenUpdate(oldAccount: String = "oauth_tokens", newTokens: OAuthTokens) throws {
-        let newData = try JSONEncoder().encode(newTokens) // Encode BEFORE mutation
-
-        var delQ: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
-                                      kSecAttrService: self.service as CFString,
-                                      kSecAttrAccount: oldAccount as CFString]
-        #if os(macOS)
-        delQ[kSecUseDataProtectionKeychain] = true
-        #endif
-        let delStatus = SecItemDelete(delQ as CFDictionary)
-        guard delStatus == errSecSuccess || delStatus == errSecItemNotFound else {
-            throw KeychainError.unexpectedStatus(delStatus)
-        }
-
-        var addQ = baseQuery(account: oldAccount); addQ[kSecValueData] = newData
-        let addStatus = SecItemAdd(addQ as CFDictionary, nil)
-        guard addStatus == errSecSuccess else { throw KeychainError.unexpectedStatus(addStatus) }
+extension CredentialVault {
+    func replaceTokens(_ tokens: SessionTokens) throws {
+        guard let encoded = try? JSONEncoder().encode(tokens) else { throw Failure.encoding }
+        try store(encoded, account: "oauth_tokens_v2")
     }
 }
 ```
 
-### Refresh Coordinator with Promise Coalescing
+There is no delete step. `store` adds, and on `errSecDuplicateItem` updates the
+existing row in place, so at no point is the item absent.
 
-If multiple concurrent callers detect an expired token, only one refresh request should fire and all callers share the result:
+Concurrent callers must share one refresh:
 
 ```swift
-// ✅ CORRECT  -  Single-flight refresh coordinator
-// Requires: iOS 13.0+
-actor TokenRefreshCoordinator {
-
-    private let keychain: KeychainManager
+actor RefreshGate {
+    private let vault: CredentialVault
     private let tokenEndpoint: URL
-    private var refreshTask: Task<OAuthTokens, Error>?
+    private var inFlight: Task<SessionTokens, Error>?
 
-    init(keychain: KeychainManager, tokenEndpoint: URL) {
-        self.keychain = keychain; self.tokenEndpoint = tokenEndpoint
+    init(vault: CredentialVault, tokenEndpoint: URL) {
+        self.vault = vault
+        self.tokenEndpoint = tokenEndpoint
     }
 
-    /// Returns a valid access token, refreshing if necessary.
-    func validAccessToken() async throws -> String {
-        guard let data = try? await keychain.load(account: "oauth_tokens"),
-              let tokens = try? JSONDecoder().decode(OAuthTokens.self, from: data) else {
-            throw TokenError.notAuthenticated
-        }
-        guard tokens.shouldRefresh else { return tokens.accessToken }
-
-        // Coalesce: reuse in-flight refresh if one exists
-        if let existing = refreshTask { return try await existing.value.accessToken }
+    func validTokens(current: SessionTokens) async throws -> SessionTokens {
+        if !current.needsRefresh { return current }
+        if let inFlight { return try await inFlight.value }
 
-        let task = Task<OAuthTokens, Error> {
-            defer { refreshTask = nil }
-            return try await performRefresh(currentRefreshToken: tokens.refreshToken)
-        }
-        refreshTask = task
-        return try await task.value.accessToken
+        let task = Task { try await self.refresh(using: current) }
+        inFlight = task
+        defer { inFlight = nil }
+        return try await task.value
     }
 
-    private func performRefresh(currentRefreshToken: String) async throws -> OAuthTokens {
+    private func refresh(using old: SessionTokens) async throws -> SessionTokens {
         var request = URLRequest(url: tokenEndpoint)
         request.httpMethod = "POST"
-        request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
-        request.httpBody = "grant_type=refresh_token&refresh_token=\(currentRefreshToken)".data(using: .utf8)
+        request.addValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
+        request.httpBody = Data("grant_type=refresh_token&refresh_token=\(old.refreshToken)".utf8)
 
-        let (data, response) = try await URLSession.shared.data(for: request)
-        guard let http = response as? HTTPURLResponse else { throw TokenError.networkError }
+        let reply = try await URLSession.shared.data(for: request)
+        let body = reply.0
+        let code = (reply.1 as? HTTPURLResponse)?.statusCode ?? 0
 
-        switch http.statusCode {
+        switch code {
         case 200:
-            // Decode server response (access_token, refresh_token?, expires_in, token_type)
-            let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
-            let newTokens = OAuthTokens(
-                accessToken: json["access_token"] as! String,
-                refreshToken: (json["refresh_token"] as? String) ?? currentRefreshToken,
-                expiresAt: Date().addingTimeInterval(json["expires_in"] as! TimeInterval),
-                tokenType: json["token_type"] as! String
+            let decoder = JSONDecoder()
+            decoder.keyDecodingStrategy = .convertFromSnakeCase
+            let payload = try decoder.decode(RefreshPayload.self, from: body)
+            let next = SessionTokens(
+                accessToken: payload.accessToken,
+                refreshToken: payload.refreshToken ?? old.refreshToken,
+                expiresAt: Date().addingTimeInterval(payload.expiresIn),
+                tokenType: payload.tokenType
             )
-            try await keychain.atomicTokenUpdate(newTokens: newTokens)
-            return newTokens
+            try await vault.replaceTokens(next)
+            return next
         case 400, 401:
-            try? await keychain.deleteAll()  // Refresh token revoked  -  force re-auth
-            throw TokenError.refreshTokenExpired
+            try await vault.removeEverything()
+            throw SessionError.refreshExpired
         default:
-            throw TokenError.serverError(http.statusCode)
+            throw SessionError.server(code)
         }
     }
+}
 
-    enum TokenError: Error {
-        case notAuthenticated, refreshTokenExpired, networkError, serverError(Int)
-    }
+struct RefreshPayload: Decodable {
+    let accessToken: String
+    let refreshToken: String?
+    let expiresIn: TimeInterval
+    let tokenType: String
+}
+
+enum SessionError: Error {
+    case refreshExpired
+    case server(Int)
 }
 ```
 
----
+A token that is not near expiry is returned as is; a refresh already running is
+awaited instead of started again; the task slot clears itself when done. If the
+server does not return a new refresh token, the old one is kept. A 400 or 401 means
+the refresh token is dead, so everything is wiped and the user signs in again.
 
-## Runtime API Key Fetching with Keychain Cache and TTL
+## API keys fetched at runtime
 
-The most secure pattern for API keys is a backend proxy  -  the key never reaches the device. When that is not feasible, fetch the key from a secure backend at runtime and cache it in the Keychain with a time-to-live. The Keychain has no native TTL mechanism, so store expiry metadata alongside the secret.
+The best design keeps third-party API keys off the device entirely behind your own
+backend proxy. If the device really must hold the key, download it when needed and keep
+a Keychain copy stamped with its own expiry, since Keychain items never expire by
+themselves.
 
-Use App Attest (`DCAppAttestService`, iOS 14.0+) to prove app integrity before the backend issues secrets. The app generates a hardware-backed key pair in the Secure Enclave and requests an attestation object from Apple. The backend validates this object, ensuring the app is untampered and running on a genuine device, before delivering short-lived API keys.
+Before the backend hands out a secret, have the app prove it is genuine with App
+Attest (`DCAppAttestService`, iOS 14+): the app creates a Secure Enclave key pair,
+Apple vouches for it, and only after checking that attestation on the server does
+your backend hand out keys, and short-lived ones at that. The attestation mechanics belong to `device-integrity`.
 
 ```swift
-// ✅ CORRECT  -  Runtime secret fetching with TTL-based Keychain cache
-// Requires: iOS 13.0+
-actor RuntimeSecretManager {
-
-    private struct CachedSecret: Codable {
-        let value: String; let fetchedAt: Date; let ttlSeconds: TimeInterval
-        var isExpired: Bool { Date().timeIntervalSince(fetchedAt) >= ttlSeconds }
-    }
+struct CachedSecret: Codable {
+    let value: String
+    let fetchedAt: Date
+    let lifetime: TimeInterval
+    var isExpired: Bool { fetchedAt.addingTimeInterval(lifetime) < Date() }
+}
 
-    private let keychain: KeychainManager
-    private let secretsEndpoint: URL
-    private let defaultTTL: TimeInterval
-    private var memoryCache: [String: CachedSecret] = [:]
+actor RemoteSecretStore {
+    private let vault: CredentialVault
+    private let fetch: @Sendable (String) async throws -> String
+    private var memory: [String: CachedSecret] = [:]
 
-    init(keychain: KeychainManager, secretsEndpoint: URL, defaultTTL: TimeInterval = 3600) {
-        self.keychain = keychain; self.secretsEndpoint = secretsEndpoint; self.defaultTTL = defaultTTL
+    init(vault: CredentialVault, fetch: @escaping @Sendable (String) async throws -> String) {
+        self.vault = vault
+        self.fetch = fetch
     }
 
-    /// Three-tier lookup: memory → Keychain → network
-    func secret(forKey key: String) async throws -> String {
-        if let c = memoryCache[key], !c.isExpired { return c.value }
+    func secret(named name: String, lifetime: TimeInterval = 3600) async throws -> String {
+        if let hit = memory[name], !hit.isExpired { return hit.value }
 
-        if let data = try? await keychain.load(account: "secret_\(key)"),
-           let c = try? JSONDecoder().decode(CachedSecret.self, from: data), !c.isExpired {
-            memoryCache[key] = c; return c.value
+        let account = "secret_\(name)"
+        let fromDisk = (try? await vault.read(account: account))
+            .flatMap { try? JSONDecoder().decode(CachedSecret.self, from: $0) }
+        if let stored = fromDisk, !stored.isExpired {
+            memory[name] = stored
+            return stored.value
         }
 
-        let freshValue = try await fetchFromBackend(key: key)
-        let cached = CachedSecret(value: freshValue, fetchedAt: Date(), ttlSeconds: defaultTTL)
-        try await keychain.save(account: "secret_\(key)", data: JSONEncoder().encode(cached))
-        memoryCache[key] = cached
-        return freshValue
-    }
-
-    private func fetchFromBackend(key: String) async throws -> String {
-        var request = URLRequest(url: secretsEndpoint.appendingPathComponent(key))
-        // Authenticate with App Attest (iOS 14.0+) before backend issues secret
-        let (data, response) = try await URLSession.shared.data(for: request)
-        guard let http = response as? HTTPURLResponse, http.statusCode == 200,
-              let json = try? JSONDecoder().decode([String: String].self, from: data),
-              let value = json["value"] else { throw SecretFetchError.serverError }
-        return value
+        let fresh = CachedSecret(value: try await fetch(name), fetchedAt: Date(), lifetime: lifetime)
+        try await vault.store(try JSONEncoder().encode(fresh), account: account)
+        memory[name] = fresh
+        return fresh.value
     }
-
-    enum SecretFetchError: Error { case serverError }
 }
 ```
 
----
+Lookup order is memory, then Keychain, then network, with a one-hour default
+lifetime.
 
-## Comprehensive Credential Clearing on Logout
+## Logout clears everything
 
-A secure logout must clear every credential artifact: access token, refresh token, cached secrets, user profile data, and in-memory caches. It must also revoke tokens server-side when possible. Group all auth-related Keychain items under a single `kSecAttrService` value so `SecItemDelete` can wipe them in one call  -  no forgotten refresh tokens, no orphaned API keys.
+Logout removes the access token, the refresh token, cached secrets, stored profile
+data and in-memory caches, and revokes the tokens on the server when it can. Keeping
+every auth item under one `kSecAttrService` means one `SecItemDelete` clears them.
 
 ```swift
-// ✅ CORRECT  -  Complete credential clearing on logout
-// OWASP MASVS-STORAGE-1, MASVS-STORAGE-2 compliant | iOS 13.0+
-actor SessionManager {
-
-    private let keychain = KeychainManager(service: "com.myapp.auth",
-                                            accessibility: kSecAttrAccessibleWhenUnlockedThisDeviceOnly)
-
-    func logout() async {
-        // 1. Server-side revocation (best-effort)
-        if let data = try? await keychain.load(account: "oauth_tokens"),
-           let tokens = try? JSONDecoder().decode(OAuthTokens.self, from: data) {
-            try? await revoke(token: tokens.refreshToken)
-            try? await revoke(token: tokens.accessToken)
+struct SignOutService {
+    let vault: CredentialVault
+    let revokeEndpoint: URL
+    let authHost: String
+
+    // Covers storage controls 1 and 2 of MASVS
+    func signOut(tokens: SessionTokens?) async {
+        if let tokens {
+            for token in [tokens.refreshToken, tokens.accessToken] {
+                var request = URLRequest(url: revokeEndpoint)
+                request.httpMethod = "POST"
+                _ = try? await URLSession.shared.upload(for: request, from: Data("token=\(token)".utf8))
+            }
         }
-        // 2. Nuclear Keychain cleanup  -  ALL items for this service
-        try? await keychain.deleteAll()
-        // 3. Clear cookies for auth domain
-        HTTPCookieStorage.shared.cookies(for: URL(string: "https://auth.example.com")!)?
-            .forEach { HTTPCookieStorage.shared.deleteCookie($0) }
-        // 4. Clear URL cache
-        URLCache.shared.removeAllCachedResponses()
-    }
+        try? await vault.removeEverything()
 
-    private func revoke(token: String) async throws {
-        var req = URLRequest(url: URL(string: "https://auth.example.com/oauth/revoke")!)
-        req.httpMethod = "POST"
-        req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
-        req.httpBody = "token=\(token)".data(using: .utf8)
-        _ = try await URLSession.shared.data(for: req)
+        let jar = HTTPCookieStorage.shared
+        jar.cookies?.filter { $0.domain.hasSuffix(authHost) }.forEach(jar.deleteCookie)
+        URLCache.shared.removeAllCachedResponses()
     }
 }
 ```
 
-**Server-driven revocation signals:** Backends can signal revocation via HTTP 401/403 with custom reason codes (e.g., `token_revoked`) or via silent push notifications (APNs) to trigger background logout and Keychain clearing.
-
----
-
-## Key Rotation and Versioned Migration
-
-### Rotation Strategies by Secret Type
-
-**OAuth refresh tokens**  -  rely on server-driven RTR. Okta's model issues a new refresh token on every use with a configurable grace period (0-60 seconds). If a previously invalidated token is reused outside the grace period, the server invalidates the entire token family.
-
-**Long-lived API keys**  -  rotation is a planned event: generate a new least-privilege key, deploy it, verify operation, then revoke the old one. Maintain emergency playbooks for compromise scenarios.
+Revocation is best effort and happens first (refresh token, then access token); local
+cleanup happens regardless. The server can also force a logout: return 401 or 403
+with a reason such as `token_revoked`, or send a silent push that triggers the same
+cleanup in the background.
 
-### Versioned Keychain Items for Migration
+## Rotation and versioned storage
 
-Version Keychain items using the `kSecAttrAccount` key to enable backward-compatible migration during rotation:
+- Refresh tokens rotate on the server's schedule (RTR); grace periods are typically
+  configurable between 0 and 60 seconds.
+- Long-lived API keys need a planned rotation (issue a new least-privilege key,
+  ship, verify traffic, revoke the old one) and a written emergency procedure for a
+  leak.
+- Version the storage layout through the account name, for example
+  `oauth_tokens_v2`, so a format change can be migrated and rolled back.
 
 ```swift
-// ✅ CORRECT  -  Versioned Keychain migration during rotation
-// Requires: iOS 13.0+
-actor TokenMigrationManager {
-
-    private let keychain: KeychainManager
-    private static let currentVersion = 2
-
-    init(keychain: KeychainManager) { self.keychain = keychain }
-
-    /// Call on app launch to migrate old token formats.
-    func migrateIfNeeded() async throws {
-        if let _ = try? await keychain.load(account: "oauth_tokens_v2") {
-            return // Already current
-        }
-        if let oldData = try? await keychain.load(account: "oauth_tokens") {
-            let migrated = try migrateV1ToV2(oldData)
-            try await keychain.save(account: "oauth_tokens_v2", data: migrated)
-            try await keychain.delete(account: "oauth_tokens") // Clean up old
-        }
+extension CredentialVault {
+    func upgradeTokenLayout() throws {
+        if (try? read(account: "oauth_tokens_v2")) != nil { return }
+        guard let legacy = try? read(account: "oauth_tokens_v1") else { return }
+
+        let converted = try convertV1ToV2(legacy)
+        try store(converted, account: "oauth_tokens_v2")
+        guard (try? read(account: "oauth_tokens_v2")) == converted else { return }
+        try remove(account: "oauth_tokens_v1")
     }
 
-    private func migrateV1ToV2(_ data: Data) throws -> Data {
-        // Implement format conversion between versions
-        return data
-    }
+    private func convertV1ToV2(_ data: Data) throws -> Data { data }
 }
 ```
 
-### Detecting Compromised Credentials
-
-Four strategies: (1) **Token reuse detection**  -  server invalidates the entire token family when an already-rotated refresh token is presented. (2) **Anomaly monitoring**  -  geographic or temporal anomalies in token usage patterns. (3) **Proactive refresh**  -  refresh tokens at 75-90% of their lifetime rather than waiting for expiry. (4) **Breach database checks**  -  services like AWS Cognito check credentials against known breach databases during authentication.
+The old item is removed as soon as the new one has been written and read back.
+Keeping the old copy around "for rollback" only doubles the number of places a
+credential can leak from; the same rule applies with more force to plaintext copies
+in UserDefaults or files, which are deleted in the same step that verifies the
+Keychain write (see [migration-legacy-stores.md](migration-legacy-stores.md)).
 
----
+Signals of compromise: a rotated refresh token being replayed (revoke the family),
+unusual location or time patterns, and leaked-password checks some identity
+providers run against breach corpora. Refresh proactively at 75-90% of lifetime.
 
-## Device Binding and Backup Implications
+## Device binding and restores
 
-Using `ThisDeviceOnly` variants prevents credential cloning but introduces friction during device upgrades. Because `ThisDeviceOnly` secrets are non-migratory, they will not transfer when a user restores an iCloud backup to a new device. The application must detect missing credentials on first launch and gracefully route the user through re-authentication.
+`ThisDeviceOnly` items cannot be copied to another device, which also means they do
+not come back after restoring an iCloud backup onto a new phone. Detect that on first
+launch and send the user to sign in:
 
 ```swift
-// ✅ Pattern: Detect missing credentials after device restore
-func handleAppLaunch() async {
+func routeAtLaunch(vault: CredentialVault) async -> LaunchDestination {
     do {
-        let _ = try await keychain.load(account: "oauth_tokens_v2")
-        // Tokens present  -  proceed normally
-    } catch KeychainManager.KeychainError.itemNotFound {
-        // Likely a fresh install or device restore
-        // Route to authentication flow
-        await presentLoginScreen()
+        let raw = try await vault.read(account: "oauth_tokens_v2")
+        _ = try JSONDecoder().decode(SessionTokens.self, from: raw)
+        return .home
+    } catch CredentialVault.Failure.missing {
+        return .signIn
     } catch {
-        // Unexpected error  -  log and route to auth
-        logger.error("Keychain load failed: \(error)")
-        await presentLoginScreen()
+        // log the failure without the token contents
+        return .signIn
     }
 }
-```
 
-**Why not `kSecAttrSynchronizable` for app tokens?** Setting it to `true` syncs the item across all trusted Apple devices via iCloud Keychain. While appropriate for website passwords managed by the Passwords app, this significantly increases the attack surface for OAuth tokens and API keys. Omit this attribute to keep secrets local.
+enum LaunchDestination { case home, signIn }
+```
 
----
+`kSecAttrSynchronizable: true` copies an item to every device on the user's iCloud
+account. That suits website passwords and widens the attack surface for session
+tokens, so leave it out. The two cannot be combined anyway: Apple documents that a
+synchronizable item may not use a `ThisDeviceOnly` accessibility value, and
+`SecItemAdd` rejects that combination with `errSecParam` (-50).
 
-## Biometric Protection for High-Value Credentials
+## Biometrics on high-value credentials
 
-For user-initiated, high-value operations (e.g., payment authorization, viewing sensitive data), add `SecAccessControl` with biometric gating. Avoid biometric protection for refresh tokens that require headless background renewal.
+A biometric `SecAccessControl` fits secrets used in a user-initiated moment, such as
+authorizing a payment or revealing sensitive data. It does not fit a refresh token
+that must renew silently in the background.
 
 ```swift
-// ✅ CORRECT  -  Maximum OWASP MASTG L2 compliance configuration
-// Requires: iOS 11.3+ (for .or compound constraint)
-func createHighSecurityKeychainItem(account: String, secret: Data) throws {
-    var error: Unmanaged<CFError>?
-    guard let accessControl = SecAccessControlCreateWithFlags(
-        kCFAllocatorDefault,
+func protectPaymentPIN(_ pin: Data) throws {
+    guard let gate = SecAccessControlCreateWithFlags(
+        nil,
         kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
         [.biometryCurrentSet, .or, .devicePasscode],
-        &error
-    ) else {
-        throw error!.takeRetainedValue() as Error
-    }
+        nil
+    ) else { throw CredentialVault.Failure.encoding }
 
-    let query: [CFString: Any] = [
-        kSecClass: kSecClassGenericPassword,
-        kSecAttrService: "com.myapp.auth" as CFString,
-        kSecAttrAccount: account as CFString,
-        kSecValueData: secret,
-        kSecAttrAccessControl: accessControl,
-        kSecUseDataProtectionKeychain: true
+    let identity: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: "com.example.bank.auth",
+        kSecAttrAccount as String: "payment_pin",
+        kSecUseDataProtectionKeychain as String: true
     ]
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    guard status == errSecSuccess else {
-        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
+    var insert = identity
+    insert[kSecValueData as String] = pin
+    insert[kSecAttrAccessControl as String] = gate
+
+    var status = SecItemAdd(insert as CFDictionary, nil)
+    if status == errSecDuplicateItem {
+        SecItemDelete(identity as CFDictionary)
+        status = SecItemAdd(insert as CFDictionary, nil)
     }
+    guard status == errSecSuccess else { throw CredentialVault.Failure.status(status) }
 }
 ```
 
-**Cross-reference:** See `biometric-authentication.md` for detailed `LAContext` integration patterns and the LAContext-only bypass vulnerability. See `keychain-access-control.md` for the full accessibility class decision tree.
-
----
-
-## iOS 17+ and 18+ Modernizations
-
-**iOS 17** introduced `ASWebAuthenticationSession.Callback` (iOS 17.4+), enabling HTTPS universal link callbacks instead of custom URL schemes  -  more secure redirect handling that verifies domain ownership. Shared password groups let teams share credentials via end-to-end encrypted iCloud Keychain. Third-party credential provider extensions can now supply passkeys alongside passwords.
-
-**iOS 18** brought the standalone Passwords app (replacing Keychain Access for end users), automatic passkey upgrades via `.conditional` registration style, and expanded credential provider extensions to support verification codes. No new `SecItem*` APIs were introduced, but the ecosystem shift toward passkeys means the Keychain's role is evolving from storing passwords to storing cryptographic keys for WebAuthn-based authentication.
-
-**WWDC 2024** Session 10125 "Streamline sign-in with passkey upgrades and credential managers" detailed the automatic passkey upgrade flow. WWDC 2021 Session 10105 introduced on-device TOTP verification code generation synced via iCloud Keychain, reducing dependence on SMS-based 2FA.
-
-**Swift 6 strict concurrency direction:** The community `swift-keychain-kit` library introduces `SecretData` as a non-copyable type (`~Copyable`) that uses `mlock` to prevent swapping to disk and zeroes memory on deallocation. While not yet an Apple framework, this pattern points toward where Keychain APIs are heading: consumed secrets that cannot accidentally be copied into insecure memory.
-
----
-
-## Static Analysis and CI/CD Guardrails
-
-Catch credential anti-patterns before they reach production:
-
-| Tool                         | Purpose                                                | Integration Point        |
-| ---------------------------- | ------------------------------------------------------ | ------------------------ |
-| **truffleHog / gitleaks**    | Scan for hardcoded secrets in source code              | PR/commit hooks          |
-| **strings / class-dump**     | Verify no secrets in compiled binary                   | Post-build CI step       |
-| **SwiftLint** (custom rules) | Flag `UserDefaults` usage for token-like keys          | Local + CI               |
-| **Frida / Objection**        | Verify `kSecAttrAccessible` values at runtime          | QA / penetration testing |
-| **MobSF**                    | Automated network traffic and storage leakage analysis | Dynamic regression gate  |
-
-**Rule:** Fail the build if static analysis detects secrets in the codebase or compiled binary.
-
----
-
-## OWASP MASTG Compliance Mapping
-
-The OWASP Mobile Top 10 (2024) places M1 (Improper Credential Usage) as the number-one mobile security risk. The MASVS v2.1.0 restructured requirements with MASWE (Mobile App Security Weakness Enumeration) bridging controls to specific tests.
-
-| Pattern                                    | OWASP Controls          | MASWE Weaknesses                   | MASTG Tests                           |
-| ------------------------------------------ | ----------------------- | ---------------------------------- | ------------------------------------- |
-| Keychain with `WhenUnlockedThisDeviceOnly` | M1, M9, MASVS-STORAGE-1 | MASWE-0002, MASWE-0004, MASWE-0036 | MASTG-TEST-0299, 0300, 0301, 0302     |
-| Actor-based thread-safe access             | M9, MASVS-STORAGE-1     | MASWE-0002                         | MASTG-TEST-0300                       |
-| ASWebAuthenticationSession (ephemeral)     | M1, MASVS-AUTH-1        | MASWE-0032                         | MASTG-TEST-0064                       |
-| Atomic token refresh                       | M1, MASVS-AUTH-1        | MASWE-0038                         |  -                                      |
-| Runtime secret fetching                    | M1, MASVS-STORAGE-1     | MASWE-0005                         |  -                                      |
-| Comprehensive logout cleanup               | M9, MASVS-STORAGE-2     | MASWE-0004                         | MASTG-TEST-0298                       |
-| Biometric + `ThisDeviceOnly`               | M9, MASVS-STORAGE-2     | MASWE-0046                         | MASTG-TEST-0298, MASTG-DEMO-0043-0047 |
-
-The legacy test identifiers MSTG-STORAGE-1 and MSTG-STORAGE-2 map to the deprecated MASTG-TEST-0052 and MASTG-TEST-0053, now replaced by the granular suite MASTG-TEST-0296 through MASTG-TEST-0314.
-
----
-
-## Conclusion
-
-The Keychain is not optional  -  it is the only mechanism Apple provides that encrypts credentials via the Secure Enclave and enforces data protection classes tied to device lock state. Three architectural decisions eliminate the majority of credential vulnerabilities: (1) use a Swift actor as the single Keychain access point to eliminate race conditions in token refresh; (2) fetch secrets at runtime from a backend proxy using App Attest for app attestation rather than embedding them in the binary; (3) group all auth-related Keychain items under a single `kSecAttrService` so logout can clear everything in one call.
-
-The future trajectory  -  passkeys, non-copyable secret types, HTTPS callbacks  -  reinforces rather than replaces these fundamentals.
-
----
-
-## Summary Checklist
-
-1. **Keychain-only storage**  -  all tokens, API keys, and credentials stored exclusively in the Keychain with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`; never in `UserDefaults`, `Info.plist`, `.xcconfig`, or hardcoded in source
-2. **Actor-serialized access**  -  all Keychain operations routed through a Swift `actor` (or `@globalActor`) to prevent race conditions and `errSecDuplicateItem` errors from concurrent access
-3. **ASWebAuthenticationSession + PKCE**  -  OAuth2 flows use `ASWebAuthenticationSession` with `prefersEphemeralWebBrowserSession = true` and PKCE (RFC 7636); never `WKWebView` or `SFSafariViewController`
-4. **Atomic token refresh**  -  refresh token rotation handled atomically within the actor: encode new tokens before any mutation, delete old, store new; promise coalescing prevents duplicate refresh requests
-5. **Runtime secret fetching**  -  API keys fetched from an attested backend (App Attest / DeviceCheck, iOS 14.0+) and cached in Keychain with application-layer TTL; three-tier lookup: memory → Keychain → network
-6. **Comprehensive logout**  -  `deleteAll()` by `kSecAttrService` clears all credential items in one call; also revokes tokens server-side, clears cookies, and clears `URLCache`
-7. **No `kSecAttrSynchronizable` for app tokens**  -  iCloud Keychain sync is for website passwords, not application secrets; `ThisDeviceOnly` variants prevent backup exfiltration
-8. **Device restore detection**  -  app detects missing `ThisDeviceOnly` credentials after device restore and gracefully routes to re-authentication
-9. **Versioned migration**  -  Keychain items versioned via `kSecAttrAccount` naming (e.g., `oauth_tokens_v2`) to support format changes and rollback during rotation
-10. **CI/CD secret scanning**  -  static analysis (truffleHog, gitleaks, `strings`) integrated into build pipeline to catch hardcoded secrets before deployment; fail the build on detection
-11. **OWASP MASTG compliance**  -  patterns satisfy M1, M9, MASVS-STORAGE-1, MASVS-AUTH-1 controls; validate with MASTG-TEST-0298 through 0302 and dynamic analysis (Frida/Objection) confirming protection classes at runtime
+`.or` needs iOS 11.3+. This is the MASTG L2 configuration: device-bound, passcode
+required, current biometric set or passcode on every read. It is also the one case
+where a duplicate is handled by delete-and-re-add, because access control cannot be
+changed with `SecItemUpdate`. Reads that the user cancels fail with
+`errSecUserCanceled` (-128). See
+[biometric-authentication.md](biometric-authentication.md).
+
+## What iOS 17 and 18 changed
+
+- iOS 17: HTTPS callbacks through `ASWebAuthenticationSession.Callback` (17.4+);
+  shared password groups synced end-to-end encrypted through iCloud Keychain;
+  credential provider extensions can offer passkeys.
+- iOS 18: the Passwords app; automatic passkey upgrades using the `.conditional`
+  request style; credential providers can fill verification codes. No new `SecItem*`
+  API.
+- WWDC 2024 session 10125 covers automatic passkey upgrades; WWDC 2021 session 10105
+  covers on-device verification codes synced through iCloud Keychain.
+- The community package `swift-keychain-kit` experiments with a `~Copyable`
+  `SecretData` that `mlock`s its buffer and zeroes it on deallocation. It is not an
+  Apple framework, but it shows where secret handling in Swift is heading.
+
+## Guardrails in CI
+
+| Tool | Stage | Checks |
+| --- | --- | --- |
+| truffleHog, gitleaks | Pre-commit hook, PR | Secrets in source |
+| `strings`, class-dump | After build | Secrets in the binary |
+| SwiftLint custom rule | Lint | `UserDefaults` writes with token-like keys |
+| Frida, Objection | QA, pentest | Actual `kSecAttrAccessible` values at runtime |
+| MobSF | Dynamic scan | Storage and network leakage |
+
+A secret found in code or in the binary fails the build.
+
+## OWASP mapping
+
+OWASP Mobile Top 10 (2024) puts M1, Improper Credential Usage, first. MASVS v2.1.0
+adds MASWE, the weakness list that links controls to MASTG tests.
+
+| Control | Top 10 | MASVS | MASWE | MASTG |
+| --- | --- | --- | --- | --- |
+| Keychain, WhenUnlockedThisDeviceOnly | M1, M9 | STORAGE-1 | 0002, 0004, 0036 | TEST-0299, 0300, 0301, 0302 |
+| Actor-serialized access | M9 | STORAGE-1 | 0002 | TEST-0300 |
+| Ephemeral `ASWebAuthenticationSession` | M1 | AUTH-1 | 0032 | TEST-0064 |
+| Atomic refresh | M1 | AUTH-1 | 0038 | |
+| Runtime secret fetch | M1 | STORAGE-1 | 0005 | |
+| Logout cleanup | M9 | STORAGE-2 | 0004 | TEST-0298 |
+| Biometrics plus ThisDeviceOnly | M9 | STORAGE-2 | 0046 | TEST-0298, DEMO-0043 to 0047 |
+
+The legacy MSTG-STORAGE-1 and -2 tests (MASTG-TEST-0052 and 0053) are deprecated and
+replaced by MASTG-TEST-0296 through 0314. More in
+[compliance-owasp-mapping.md](compliance-owasp-mapping.md).
+
+## The three decisions that matter
+
+One actor is the only door to the Keychain. Runtime secrets come from your own
+backend, gated by App Attest. Every auth item shares one `kSecAttrService` so logout
+is a single call.
+
+## Checklist
+
+- [ ] Credentials only in the Keychain with WhenUnlockedThisDeviceOnly; never
+      UserDefaults, `Info.plist`, `.xcconfig` or source.
+- [ ] All Keychain access through one actor or a `@globalActor`.
+- [ ] Sign-in via `ASWebAuthenticationSession`, ephemeral, with PKCE (RFC 7636);
+      never `WKWebView` or `SFSafariViewController`.
+- [ ] Saves are add-then-update-on-duplicate; delete-and-re-add only when access
+      control changes.
+- [ ] Refresh encodes first, writes both tokens in one item, and coalesces concurrent
+      refreshes.
+- [ ] Runtime API keys handed out only after the backend checks an App Attest (or
+      DeviceCheck) proof, iOS 14+, and cached with an app-managed expiry; memory, then Keychain, then network.
+- [ ] Logout: delete by service, revoke on the server, clear cookies and `URLCache`.
+- [ ] No `kSecAttrSynchronizable` on app tokens.
+- [ ] Missing ThisDeviceOnly credentials after a restore route to sign-in.
+- [ ] Versioned account names; old versions deleted once the new write is verified.
+- [ ] CI secret scanning (truffleHog, gitleaks, `strings`) fails the build.
+- [ ] M1, M9, MASVS-STORAGE-1 and MASVS-AUTH-1 checked against MASTG-TEST-0298 to
+      0302 and with Frida or Objection.