@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/keychain-fundamentals.md

@@ -1,620 +1,500 @@
 # Keychain Fundamentals
 
-> **Scope:** SecItem\* CRUD operations, query dictionary structure, kSecClass types, OSStatus error handling, actor-based wrapper patterns. This is the foundation file  -  all other reference files assume familiarity with these patterns.
->
-> **Key APIs:** `SecItemAdd`, `SecItemCopyMatching`, `SecItemUpdate`, `SecItemDelete`, `kSecClassGenericPassword`, `kSecClassInternetPassword`, `kSecClassKey`, `kSecClassCertificate`, `kSecClassIdentity`
->
-> **Apple Documentation:** [Keychain Services](https://sosumi.ai/documentation/security/keychain_services), [TN3137](https://sosumi.ai/documentation/technotes/tn3137-on-mac-keychains), Quinn "The Eskimo!" DTS posts: "SecItem: Fundamentals" and "SecItem: Pitfalls and Best Practices"
+Every other reference in this skill builds on the material here: how the four
+`SecItem` functions behave, what their dictionaries may contain, how to read
+their status codes, and how to keep them away from the main thread.
 
----
+Primary sources: TN3137 ("On Mac keychain APIs and implementations"), the
+Keychain Services pages in Apple's documentation, and the Apple Developer Forums posts by
+Quinn "The Eskimo!" (DTS) titled "SecItem: Fundamentals" and "SecItem: Pitfalls
+and Best Practices".
 
 ## Contents
 
-- [Architecture Overview](#architecture-overview)
-- [The Four Functions and Their Dictionary Contracts](#the-four-functions-and-their-dictionary-contracts)
-- [Uniqueness and Primary Keys](#uniqueness-and-primary-keys)
-- [The Add-or-Update Pattern](#the-add-or-update-pattern)
-- [Reading from the Keychain: Return Flags and Type Casting](#reading-from-the-keychain-return-flags-and-type-casting)
-  - [Return Type Cheat Sheet](#return-type-cheat-sheet)
-  - [String Keys vs. kSec\* Constants](#string-keys-vs-ksec-constants)
-- [Centralized Query Builder](#centralized-query-builder)
-- [OSStatus Error Handling](#osstatus-error-handling)
-- [Actor-Isolated Keychain Manager (iOS 17+ / macOS 14+)](#actor-isolated-keychain-manager-ios-17-macos-14)
-  - [Why Actors over GCD](#why-actors-over-gcd)
-  - [Legacy GCD Pattern (iOS 13-16 codebases)](#legacy-gcd-pattern-ios-1316-codebases)
-- [Performance Architecture](#performance-architecture)
-  - [Two-Tier Encryption and Query Cost](#two-tier-encryption-and-query-cost)
-  - [Query Specificity](#query-specificity)
-  - [App Launch Performance](#app-launch-performance)
-  - [Batch Operations](#batch-operations)
-- [macOS Keychain Routing (TN3137)](#macos-keychain-routing-tn3137)
-- [Accessibility and Data Protection Classes](#accessibility-and-data-protection-classes)
-- [Cross-References](#cross-references)
-- [Authoritative References](#authoritative-references)
-- [Implementation Notes](#implementation-notes)
-- [Summary Checklist](#summary-checklist)
+- [How the Keychain Is Built](#how-the-keychain-is-built)
+- [Dictionary Contracts](#dictionary-contracts)
+- [Uniqueness](#uniqueness)
+- [Saving: Add, Then Update on Duplicate](#saving-add-then-update-on-duplicate)
+- [Reading](#reading)
+- [One Place That Builds Queries](#one-place-that-builds-queries)
+- [OSStatus Codes](#osstatus-codes)
+- [An Actor Around the Keychain (iOS 17+ / macOS 14+)](#an-actor-around-the-keychain-ios-17--macos-14)
+- [Performance](#performance)
+- [macOS: Two Keychains (TN3137)](#macos-two-keychains-tn3137)
+- [Accessibility at a Glance](#accessibility-at-a-glance)
+- [Checklist](#checklist)
+- [Related Files](#related-files)
 
-## Architecture Overview
+## How the Keychain Is Built
 
-The Keychain Services API exposes four C functions that map to database CRUD operations. Every call is an IPC round-trip to the `securityd` daemon, backed by an encrypted SQLite database. This means every call **blocks the calling thread** and must never execute on `@MainActor`.
+The API is four C functions, one per CRUD verb. None of them touches the
+database directly: each call travels over IPC to `securityd`, the daemon
+that owns an encrypted SQLite store. Because the caller waits for that round
+trip, every call blocks its thread. Keep them off `@MainActor`.
 
-Internally, keychain items use **two-tier AES-256-GCM encryption** (per the Apple Platform Security Guide): a table-level **metadata key** cached in the Application Processor for fast attribute searches, and a **per-row secret key** requiring a Secure Enclave round-trip for `kSecValueData` decryption. This two-tier design has direct performance implications covered in the Performance section below.
+Items are protected in two tiers, both AES-256-GCM:
 
----
+- the searchable attributes sit under a metadata key that is shared by the
+  table and kept cached on the Application Processor;
+- a per-row secret key encrypts `kSecValueData`, and unwrapping it needs a trip
+  to the Secure Enclave.
 
-## The Four Functions and Their Dictionary Contracts
+That split explains most of the performance advice further down.
 
-Each function accepts a specific _type_ of dictionary. Confusing which keys belong in which dictionary is the single most common source of bugs. Quinn (Apple DTS) defines five property groups:
+## Dictionary Contracts
 
-1. **Item class**  -  `kSecClass`
-2. **Item attributes**  -  `kSecAttrAccount`, `kSecAttrService`, etc.
-3. **Search properties**  -  `kSecMatchLimit`
-4. **Return type properties**  -  `kSecReturnData`, `kSecReturnAttributes`, `kSecReturnRef`, `kSecReturnPersistentRef`
-5. **Value type properties**  -  `kSecValueData`, `kSecValueRef`
+Quinn groups the keys you can put in a SecItem dictionary into five kinds:
 
-| Function                    | Dictionary Type                              | Supports Return Keys?   | Default `kSecMatchLimit` | Since   |
-| --------------------------- | -------------------------------------------- | ----------------------- | ------------------------ | ------- |
-| `SecItemAdd(_:_:)`          | Add dictionary (class + attrs + values)      | ✅ Optional             | N/A                      | iOS 2.0 |
-| `SecItemCopyMatching(_:_:)` | Query + return (all 5 groups)                | ✅ Required for results | `kSecMatchLimitOne`      | iOS 2.0 |
-| `SecItemUpdate(_:_:)`       | Pure query (param 1) + update dict (param 2) | ❌                      | **`kSecMatchLimitAll`**  | iOS 2.0 |
-| `SecItemDelete(_:)`         | Pure query                                   | ❌                      | **`kSecMatchLimitAll`**  | iOS 2.0 |
+| Group | Examples |
+| --- | --- |
+| Item class | `kSecClass` |
+| Attributes | `kSecAttrAccount`, `kSecAttrService`, ... |
+| Search | `kSecMatchLimit` |
+| Return type | `kSecReturnData`, `kSecReturnAttributes`, `kSecReturnRef`, `kSecReturnPersistentRef` |
+| Value type | `kSecValueData`, `kSecValueRef` |
 
-**Critical detail:** `kSecMatchLimit` defaults to `kSecMatchLimitOne` for `SecItemCopyMatching` but **`kSecMatchLimitAll` for `SecItemUpdate` and `SecItemDelete`**. An under-specified delete query will wipe every matching item in the keychain.
+Each function accepts a different subset (all available since iOS 2.0):
 
-**Dictionary hygiene:** Use a fresh dictionary for each call. Putting `kSecReturnData` in an add dictionary or `kSecClass` in an update dictionary produces `errSecParam` (-50). Quinn's guidance: "Use a new dictionary for each call. That prevents state from one call accidentally leaking into a subsequent call."
+| Function | Accepts | Return keys | Default match limit |
+| --- | --- | --- | --- |
+| `SecItemAdd(_:_:)` | class, attributes, values | optional | n/a |
+| `SecItemCopyMatching(_:_:)` | all five groups | needed to get anything back | `kSecMatchLimitOne` |
+| `SecItemUpdate(_:_:)` | a query, plus a second dictionary of changes | not allowed | `kSecMatchLimitAll` |
+| `SecItemDelete(_:)` | a query | not allowed | `kSecMatchLimitAll` |
 
----
+The delete default deserves attention: a query that names only the class, or
+only the service, removes every item it matches.
 
-## Uniqueness and Primary Keys
+Give every call its own freshly built dictionary instead of reusing one. Leftover keys break the contract: a `kSecReturnData` inside an add
+dictionary, or a `kSecClass` inside an update dictionary, fails with
+`errSecParam` (-50).
 
-For `kSecClassGenericPassword`, uniqueness is determined by the combination of:
+## Uniqueness
 
-- `kSecAttrAccount` + `kSecAttrService` + `kSecAttrAccessGroup` + `kSecAttrSynchronizable`
+A generic password is identified by the combination of `kSecAttrAccount`,
+`kSecAttrService`, `kSecAttrAccessGroup` and `kSecAttrSynchronizable`.
+`kSecAttrGeneric`, `kSecAttrLabel` and `kSecAttrDescription` play no part in
+that identity.
 
-Other attributes like `kSecAttrGeneric`, `kSecAttrLabel`, or `kSecAttrDescription` **do not participate in uniqueness**. This means a query filtering on non-unique attributes can return `errSecItemNotFound` while a subsequent add still hits `errSecDuplicateItem`.
+This produces a confusing pair of results: a query that filters on a
+non-identifying attribute such as `kSecAttrGeneric` can report
+`errSecItemNotFound`, while an add with the same service and account still
+reports `errSecDuplicateItem`.
 
-For `kSecClassInternetPassword`, the uniqueness set includes: `kSecAttrAccount` + `kSecAttrServer` + `kSecAttrProtocol` + `kSecAttrAuthenticationType` + `kSecAttrPort` + `kSecAttrPath` + `kSecAttrSecurityDomain` + `kSecAttrAccessGroup` + `kSecAttrSynchronizable`.
+Internet passwords are identified by account, server, protocol, authentication
+type, port, path, security domain, access group and synchronizable. See
+[keychain-item-classes.md](keychain-item-classes.md) for every class.
 
-**Immutable attributes:** `kSecAttrAccount` and `kSecClass` cannot be changed via `SecItemUpdate`. To change them, delete and re-add the item (see `keychain-item-classes.md`).
+`SecItemUpdate` cannot change `kSecAttrAccount` or `kSecClass`. To rename an
+account or change class, delete the old item and add a new one.
 
----
+## Saving: Add, Then Update on Duplicate
 
-## The Add-or-Update Pattern
-
-The most common AI-generated keychain bug is calling `SecItemAdd` without handling `errSecDuplicateItem` (-25299).
-
-❌ **Naive add that silently fails on duplicate:**
+The bug that shows up most in generated keychain code is a `SecItemAdd` whose
+result is never read. The first save works; the second returns
+`errSecDuplicateItem` (-25299), nothing is written, and the app keeps running
+with the stale value.
 
 ```swift
-// ❌ WRONG  -  silently fails if item already exists
-func savePassword(_ password: String, account: String) {
-    let query: [CFString: Any] = [
+// Wrong: status ignored, so every save after the first silently does nothing.
+func storeWrong(_ pin: Data) {
+    let item: [CFString: Any] = [
         kSecClass: kSecClassGenericPassword,
-        kSecAttrService: "com.example.app",
-        kSecAttrAccount: account,
-        kSecValueData: Data(password.utf8)
+        kSecAttrService: "com.example.lockbox",
+        kSecAttrAccount: "vault-pin",
+        kSecValueData: pin
     ]
-    SecItemAdd(query as CFDictionary, nil)  // Return value IGNORED!
-    // If item exists → errSecDuplicateItem (-25299)  -  password never saved
+    SecItemAdd(item as CFDictionary, nil)
 }
 ```
 
-✅ **Correct add-or-update with exhaustive OSStatus handling:**
-
 ```swift
-// ✅ CORRECT  -  attempts add, falls back to update on duplicate
-func savePassword(_ password: String, account: String) throws {
-    let baseQuery: [CFString: Any] = [
+func store(_ pin: Data) throws {
+    let identity: [CFString: Any] = [
         kSecClass: kSecClassGenericPassword,
-        kSecAttrService: "com.example.app",
-        kSecAttrAccount: account
+        kSecAttrService: "com.example.lockbox",
+        kSecAttrAccount: "vault-pin"
     ]
+    var insert = identity
+    insert[kSecValueData] = pin
+    insert[kSecAttrAccessible] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
 
-    var addQuery = baseQuery
-    addQuery[kSecValueData] = Data(password.utf8)
-    addQuery[kSecAttrAccessible] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
-
-    let addStatus = SecItemAdd(addQuery as CFDictionary, nil)
-
-    switch addStatus {
+    let added = SecItemAdd(insert as CFDictionary, nil)
+    switch added {
     case errSecSuccess:
         return
-
     case errSecDuplicateItem:
-        // Item exists  -  update it
-        let updates: [CFString: Any] = [kSecValueData: Data(password.utf8)]
-        let updateStatus = SecItemUpdate(
-            baseQuery as CFDictionary,
-            updates as CFDictionary
-        )
-        guard updateStatus == errSecSuccess else {
-            throw KeychainError(status: updateStatus)
-        }
-
+        let changes: [CFString: Any] = [kSecValueData: pin]
+        let updated = SecItemUpdate(identity as CFDictionary, changes as CFDictionary)
+        guard updated == errSecSuccess else { throw KeychainError(status: updated) }
     case errSecInteractionNotAllowed:
-        // Device locked  -  do NOT delete-and-retry!
-        throw KeychainError(status: addStatus)
-
+        throw KeychainError(status: added)
     default:
-        throw KeychainError(status: addStatus)
+        throw KeychainError(status: added)
     }
 }
 ```
 
-Key points in this pattern:
-
-- **Separate dictionaries** for add vs. update  -  the update dictionary contains only the attributes to change, never `kSecClass` or search properties.
-- **`errSecInteractionNotAllowed`** (-25308) means the device is locked and data protection prevents access. Never delete items in response to this error; the item is valid but temporarily inaccessible.
-- **Prefer update over delete-then-add**  -  update preserves persistent references and avoids the race condition window between delete and add.
+Points to carry into any variant:
 
----
+- The changes dictionary lists only what should change. It never contains
+  `kSecClass` or the search attributes.
+- `errSecInteractionNotAllowed` (-25308) tells you the item exists but cannot be
+  opened now: the device is locked, or the item needs UI that cannot appear. The item is fine. Deleting it here destroys
+  good data.
+- Updating in place beats deleting and re-adding: persistent references to the
+  item stay valid, and there is no moment where the item is missing for a
+  concurrent reader. Delete and re-add only when the access control itself has
+  to change (see [keychain-access-control.md](keychain-access-control.md)).
 
-## Reading from the Keychain: Return Flags and Type Casting
+## Reading
 
-The second most common bug is calling `SecItemCopyMatching` without `kSecReturn*` flags. The function may return `errSecSuccess` with a `nil` result  -  this is "success but nil," not a real success.
-
-❌ **Query that returns no data because `kSecReturnData` is missing:**
+Next in frequency: a `SecItemCopyMatching` that sets no `kSecReturn*` key. The call succeeds and the result is empty.
 
 ```swift
-// ❌ WRONG  -  no kSecReturn* flags, result is always nil
-func loadPassword(account: String) -> Data? {
-    let query: [CFString: Any] = [
+// Wrong: no return key, so `out` is nil and the cast always fails.
+func fetchWrong() -> Data? {
+    let lookup: [CFString: Any] = [
         kSecClass: kSecClassGenericPassword,
-        kSecAttrService: "com.example.app",
-        kSecAttrAccount: account,
+        kSecAttrService: "com.example.lockbox",
+        kSecAttrAccount: "vault-pin",
         kSecMatchLimit: kSecMatchLimitOne
-        // BUG: Missing kSecReturnData: true
     ]
-    var result: CFTypeRef?
-    SecItemCopyMatching(query as CFDictionary, &result)
-    return result as? Data  // Always nil  -  no return type was requested
+    var out: CFTypeRef?
+    SecItemCopyMatching(lookup as CFDictionary, &out)
+    return out as? Data
 }
 ```
 
-✅ **Correct query with proper return flags and exhaustive error handling:**
-
 ```swift
-// ✅ CORRECT  -  explicitly requests data, handles all error states
-func loadPassword(account: String) throws -> Data? {
-    let query: [CFString: Any] = [
+func fetch() throws -> Data? {
+    let lookup: [CFString: Any] = [
         kSecClass: kSecClassGenericPassword,
-        kSecAttrService: "com.example.app",
-        kSecAttrAccount: account,
+        kSecAttrService: "com.example.lockbox",
+        kSecAttrAccount: "vault-pin",
         kSecMatchLimit: kSecMatchLimitOne,
-        kSecReturnData: true  // ← REQUIRED to get the secret
+        kSecReturnData: true
     ]
-
-    var result: CFTypeRef?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-
+    var out: CFTypeRef?
+    let status = SecItemCopyMatching(lookup as CFDictionary, &out)
     switch status {
     case errSecSuccess:
-        guard let data = result as? Data else {
-            throw KeychainError(status: errSecParam)
-        }
-        return data
-
+        guard let bytes = out as? Data else { throw KeychainError(status: errSecParam) }
+        return bytes
     case errSecItemNotFound:
-        return nil  // Legitimate "not found"  -  not an error
-
+        return nil
     case errSecInteractionNotAllowed:
         throw KeychainError(status: status)
-
     default:
         throw KeychainError(status: status)
     }
 }
 ```
 
-### Return Type Cheat Sheet
-
-The `CFTypeRef` type depends entirely on which return flags and match limits are set:
-
-```text
-kSecReturnData only      + kSecMatchLimitOne  → Data
-kSecReturnAttributes     + kSecMatchLimitOne  → [String: Any]
-kSecReturnData + Attrs   + kSecMatchLimitOne  → [String: Any]  (data under kSecValueData key)
-kSecReturnRef            + kSecMatchLimitOne  → SecKey / SecCertificate / SecIdentity
-kSecReturnPersistentRef  + kSecMatchLimitOne  → Data (opaque handle)
-Any combination          + kSecMatchLimitAll  → Array of the above type
-```
-
-**Note:** Combining `kSecReturnData` with `kSecMatchLimitAll` may be restricted for password classes on some OS versions. For listing items, prefer `kSecReturnAttributes` or `kSecReturnRef` with `kSecMatchLimitAll`, then fetch data per-item as needed.
-
-### String Keys vs. kSec\* Constants
-
-Never use raw string literals (`"svce"`, `"class"`) instead of `kSec*` constants. The constants are `CFString` values with specific internal representations. Two equally valid dictionary key styles exist:
-
-```swift
-// Style A: CFString keys (fewer casts at definition, cast once at call site)
-let query: [CFString: Any] = [kSecClass: kSecClassGenericPassword]
-SecItemAdd(query as CFDictionary, nil)
+What lands in `out` depends on the return keys and the match limit:
 
-// Style B: String keys (more common in community code)
-let query: [String: Any] = [kSecClass as String: kSecClassGenericPassword]
-SecItemAdd(query as CFDictionary, nil)
-```
+| Return keys | `kSecMatchLimitOne` gives | `kSecMatchLimitAll` gives |
+| --- | --- | --- |
+| Data | `Data` | array of `Data` |
+| Attributes | `[String: Any]` | array of dictionaries |
+| Data + Attributes | dictionary, secret under `kSecValueData` | array of dictionaries |
+| Ref | `SecKey`, `SecCertificate` or `SecIdentity` | array of refs |
+| PersistentRef | opaque `Data` | array of `Data` |
 
-Both are correct. Pick one style and use it consistently across your codebase.
+Some OS versions refuse `kSecReturnData` combined with `kSecMatchLimitAll` for
+password classes. List items with attributes or refs, then fetch data for the
+one you need.
 
----
+Use the `kSec*` constants, never their string values such as `"svce"` or
+`"class"`. Dictionaries typed `[CFString: Any]` work, and so do `[String: Any]` ones
+whose keys are cast with `as String`; pick one style per codebase. This file uses `[CFString: Any]` because it is
+shorter.
 
-## Centralized Query Builder
+## One Place That Builds Queries
 
-Centralize query construction to prevent flag omissions and key typos:
+A small builder keeps every query shape in one auditable spot, so a missing
+return flag or a typo in an attribute shows up in one review instead of twenty.
 
 ```swift
-enum KeychainQueryBuilder {
-    static func buildQuery(
-        forClass secClass: CFString = kSecClassGenericPassword,
-        account: String? = nil,
-        service: String? = nil,
+enum KeychainQuery {
+    static func make(
+        itemClass: CFString = kSecClassGenericPassword,
+        account: String,
+        service: String,
         accessGroup: String? = nil,
-        returnData: Bool = false,
-        returnAttributes: Bool = false,
-        matchLimit: CFString = kSecMatchLimitOne
-    ) -> [String: Any] {
-        var query: [String: Any] = [kSecClass as String: secClass]
-
-        if let account  { query[kSecAttrAccount as String] = account }
-        if let service  { query[kSecAttrService as String] = service }
-        if let group    = accessGroup { query[kSecAttrAccessGroup as String] = group }
-        if returnData   { query[kSecReturnData as String] = kCFBooleanTrue! }
-        if returnAttributes { query[kSecReturnAttributes as String] = kCFBooleanTrue! }
-        query[kSecMatchLimit as String] = matchLimit
-
-        return query
+        wantData: Bool = false,
+        wantAttributes: Bool = false,
+        limit: CFString = kSecMatchLimitOne
+    ) -> [CFString: Any] {
+        var q: [CFString: Any] = [
+            kSecClass: itemClass,
+            kSecAttrAccount: account,
+            kSecAttrService: service,
+            kSecMatchLimit: limit
+        ]
+        if let accessGroup { q[kSecAttrAccessGroup] = accessGroup }
+        if wantData { q[kSecReturnData] = true }
+        if wantAttributes { q[kSecReturnAttributes] = true }
+        return q
     }
 }
 ```
 
-This pattern ensures return flags are set deliberately and provides a single site to audit query construction.
+Drop `kSecMatchLimit` and the return flags before handing a builder result to
+`SecItemAdd`, `SecItemUpdate` or `SecItemDelete`.
 
----
+## OSStatus Codes
 
-## OSStatus Error Handling
+A nonzero status is not automatically a failure to report. Treat each one on
+its merits:
 
-Never treat all non-zero `OSStatus` values as fatal errors. Several codes represent expected operational states:
-
-| OSStatus Code | Constant                      | Meaning                                            | Correct Response                           |
-| ------------- | ----------------------------- | -------------------------------------------------- | ------------------------------------------ |
-| `0`           | `errSecSuccess`               | Operation succeeded                                | Proceed normally                           |
-| `-25299`      | `errSecDuplicateItem`         | Item already exists (on add)                       | Fall back to `SecItemUpdate`               |
-| `-25300`      | `errSecItemNotFound`          | No matching item found                             | Return `nil` / treat as success for delete |
-| `-25308`      | `errSecInteractionNotAllowed` | Device locked, data protection active              | Retry later  -  **never delete**             |
-| `-25293`      | `errSecUserCanceled`          | User cancelled biometric prompt                    | Propagate cancellation to UI               |
-| `-50`         | `errSecParam`                 | Invalid parameter / wrong dictionary keys          | Developer error  -  fix query                |
-| `-25244`      | `errSecNoSuchAttr`            | Attribute not supported (data protection keychain) | Check for unsupported attributes           |
-
-Map raw codes to a domain-specific Swift error:
+| Code | Constant | Response |
+| --- | --- | --- |
+| 0 | `errSecSuccess` | Continue. |
+| -25299 | `errSecDuplicateItem` | Switch to `SecItemUpdate`. |
+| -25300 | `errSecItemNotFound` | Return nil; on delete, count it as success. |
+| -25308 | `errSecInteractionNotAllowed` | Try again later (device locked). Never delete. |
+| -128 | `errSecUserCanceled` | The user dismissed the prompt; tell the UI. |
+| -25293 | `errSecAuthFailed` | Authentication failed or the protected item is no longer usable. |
+| -50 | `errSecParam` | A programming error in the dictionary; fix the query. |
+| -25244 | `errSecNoSuchAttr` | The attribute is not supported (seen on the data protection keychain). |
 
 ```swift
 struct KeychainError: Error, CustomStringConvertible {
     let status: OSStatus
-
     var description: String {
-        let msg = SecCopyErrorMessageString(status, nil) as String? ?? "Unknown"
-        return "KeychainError(\(status)): \(msg)"
+        let text = SecCopyErrorMessageString(status, nil) as String? ?? "unknown"
+        return "Keychain status \(status): \(text)"
     }
 }
 ```
 
-**Logging safety:** Log only the query shape and resulting status code. Never log secret data (`kSecValueData`), tokens, or keys.
+Logs may record the shape of a query (class, service, which flags were set)
+and the status code. They never record `kSecValueData`, tokens or key bytes.
 
----
+## An Actor Around the Keychain (iOS 17+ / macOS 14+)
 
-## Actor-Isolated Keychain Manager (iOS 17+ / macOS 14+)
-
-Every `SecItem*` function blocks the calling thread due to IPC to `securityd` and potential Secure Enclave round-trips. For biometry-protected items, the block can last several seconds during user authentication (WWDC 2014 Session 711).
-
-❌ **`@MainActor` keychain access that blocks the UI:**
+Reads of biometric-protected items wait for the user and can take several
+seconds (WWDC 2014 Session 711). Doing that on the main actor freezes the UI.
 
 ```swift
-// ❌ WRONG  -  blocks main thread, freezes UI during securityd IPC
+// Wrong: the main actor waits on securityd and, for protected items, on the user.
 @MainActor
-class SettingsViewModel: ObservableObject {
-    @Published var token: String = ""
-
-    func loadToken() {
-        let query: [CFString: Any] = [
-            kSecClass: kSecClassGenericPassword,
-            kSecAttrService: "com.example.app",
-            kSecAttrAccount: "authToken",
-            kSecReturnData: true,
-            kSecMatchLimit: kSecMatchLimitOne
-        ]
-        var result: CFTypeRef?
-        let status = SecItemCopyMatching(query as CFDictionary, &result)
-        if status == errSecSuccess, let data = result as? Data {
-            self.token = String(data: data, encoding: .utf8) ?? ""
-        }
-        // UI frozen for entire duration of securityd IPC + potential SE round-trip
+final class ProfileModel: ObservableObject {
+    @Published var apiKey: String?
+    func load() {
+        var out: CFTypeRef?
+        let q: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                  kSecAttrAccount: "api", kSecReturnData: true]
+        _ = SecItemCopyMatching(q as CFDictionary, &out)
+        apiKey = (out as? Data).flatMap { String(decoding: $0, as: UTF8.self) }
     }
 }
 ```
 
-✅ **Actor-isolated keychain manager with full CRUD:**
-
 ```swift
-// ✅ CORRECT  -  dedicated actor keeps all SecItem calls off @MainActor
-actor KeychainManager {
-    static let shared = KeychainManager()
-
+actor SecretStore {
+    static let shared = SecretStore()
     private let service: String
 
-    init(service: String = Bundle.main.bundleIdentifier ?? "default") {
+    init(service: String = Bundle.main.bundleIdentifier ?? "app.secrets") {
         self.service = service
     }
 
-    // MARK: - Save (add-or-update)
-
-    func save(_ data: Data, for key: String,
-              accessibility: CFTypeRef = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
-    ) throws {
-        let baseQuery: [CFString: Any] = [
-            kSecClass: kSecClassGenericPassword,
-            kSecAttrService: service,
-            kSecAttrAccount: key
-        ]
-
-        var addQuery = baseQuery
-        addQuery[kSecValueData] = data
-        addQuery[kSecAttrAccessible] = accessibility
-
-        let addStatus = SecItemAdd(addQuery as CFDictionary, nil)
-
-        switch addStatus {
-        case errSecSuccess:
-            return
-        case errSecDuplicateItem:
-            let updates: [CFString: Any] = [kSecValueData: data]
-            let updateStatus = SecItemUpdate(
-                baseQuery as CFDictionary,
-                updates as CFDictionary
-            )
-            guard updateStatus == errSecSuccess else {
-                throw KeychainError(status: updateStatus)
-            }
-        case errSecInteractionNotAllowed:
-            throw KeychainError(status: addStatus)
-        default:
-            throw KeychainError(status: addStatus)
-        }
+    private func identity(_ account: String) -> [CFString: Any] {
+        [kSecClass: kSecClassGenericPassword,
+         kSecAttrService: service,
+         kSecAttrAccount: account]
     }
 
-    // MARK: - Load
-
-    func load(for key: String) throws -> Data? {
-        let query: [CFString: Any] = [
-            kSecClass: kSecClassGenericPassword,
-            kSecAttrService: service,
-            kSecAttrAccount: key,
-            kSecReturnData: true,
-            kSecMatchLimit: kSecMatchLimitOne
-        ]
-
-        var result: CFTypeRef?
-        let status = SecItemCopyMatching(query as CFDictionary, &result)
-
-        switch status {
-        case errSecSuccess:
-            return result as? Data
-        case errSecItemNotFound:
-            return nil
-        case errSecInteractionNotAllowed:
-            throw KeychainError(status: status)
-        default:
-            throw KeychainError(status: status)
-        }
+    func put(_ value: Data, for account: String,
+             accessible: CFString = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly) throws {
+        var insert = identity(account)
+        insert[kSecValueData] = value
+        insert[kSecAttrAccessible] = accessible
+        let status = SecItemAdd(insert as CFDictionary, nil)
+        if status == errSecSuccess { return }
+        guard status == errSecDuplicateItem else { throw KeychainError(status: status) }
+        let changed = SecItemUpdate(identity(account) as CFDictionary,
+                                    [kSecValueData: value] as CFDictionary)
+        guard changed == errSecSuccess else { throw KeychainError(status: changed) }
     }
 
-    // MARK: - Delete (idempotent)
+    func get(_ account: String) throws -> Data? {
+        var q = identity(account)
+        q[kSecReturnData] = true
+        q[kSecMatchLimit] = kSecMatchLimitOne
+        var out: CFTypeRef?
+        let status = SecItemCopyMatching(q as CFDictionary, &out)
+        if status == errSecItemNotFound { return nil }
+        guard status == errSecSuccess else { throw KeychainError(status: status) }
+        return out as? Data
+    }
 
-    func delete(key: String) throws {
-        let query: [CFString: Any] = [
-            kSecClass: kSecClassGenericPassword,
-            kSecAttrService: service,
-            kSecAttrAccount: key
-        ]
-        let status = SecItemDelete(query as CFDictionary)
+    func remove(_ account: String) throws {
+        let status = SecItemDelete(identity(account) as CFDictionary)
         guard status == errSecSuccess || status == errSecItemNotFound else {
             throw KeychainError(status: status)
         }
     }
 
-    // MARK: - List all accounts (attributes only  -  fast)
-
-    func allAccounts() throws -> [String] {
-        let query: [CFString: Any] = [
-            kSecClass: kSecClassGenericPassword,
-            kSecAttrService: service,
-            kSecMatchLimit: kSecMatchLimitAll,
-            kSecReturnAttributes: true  // No kSecReturnData → skips SE round-trip
-        ]
-
-        var result: CFTypeRef?
-        let status = SecItemCopyMatching(query as CFDictionary, &result)
-
-        switch status {
-        case errSecSuccess:
-            guard let items = result as? [[String: Any]] else { return [] }
-            return items.compactMap { $0[kSecAttrAccount as String] as? String }
-        case errSecItemNotFound:
-            return []
-        default:
+    func accounts() throws -> [String] {
+        let q: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                  kSecAttrService: service,
+                                  kSecMatchLimit: kSecMatchLimitAll,
+                                  kSecReturnAttributes: true]
+        var out: CFTypeRef?
+        let status = SecItemCopyMatching(q as CFDictionary, &out)
+        if status == errSecItemNotFound { return [] }
+        guard status == errSecSuccess, let rows = out as? [[String: Any]] else {
             throw KeychainError(status: status)
         }
+        return rows.compactMap { $0[kSecAttrAccount as String] as? String }
     }
 }
 ```
 
-**Calling from SwiftUI:**
+`remove` is idempotent. `accounts()` asks for attributes only, so it never pays
+for the Secure Enclave unwrap of each secret.
+
+From SwiftUI, the view model awaits the actor and the main actor is free while
+the keychain works:
 
 ```swift
 @MainActor
-class AuthViewModel: ObservableObject {
-    @Published var isAuthenticated = false
-
-    func loadToken() async {
-        do {
-            // Crosses actor boundary  -  suspends, does NOT block MainActor
-            let data = try await KeychainManager.shared.load(for: "authToken")
-            isAuthenticated = data != nil
-        } catch {
-            isAuthenticated = false
-        }
+@Observable
+final class SettingsModel {
+    var hasKey = false
+    func refresh() async {
+        hasKey = (try? await SecretStore.shared.get("api")) != nil
     }
 }
 ```
 
-### Why Actors over GCD
+Why an actor rather than a queue:
 
-| Dimension             | Actor (iOS 17+)                   | GCD Serial Queue                        |
-| --------------------- | --------------------------------- | --------------------------------------- |
-| UI blocking           | Low  -  compiler-enforced isolation | Low (if dispatched correctly)           |
-| Thread safety         | Serialized by actor runtime       | Manual  -  developer discipline           |
-| Readability           | Linear async/await                | Nested completion handlers              |
-| Compiler guarantees   | Enforced `Sendable` + isolation   | None  -  silent data races possible       |
-| Swift 6 compatibility | Native  -  actors are `Sendable`    | Requires manual `@Sendable` annotations |
+| | Actor | GCD serial queue |
+| --- | --- | --- |
+| Isolation | Checked by the compiler | Up to the developer |
+| Serialization | Done by the runtime | Done by the queue, if used consistently |
+| Control flow | Straight-line `async`/`await` | Nested completion handlers |
+| `Sendable` | Enforced | Annotate `@Sendable` by hand |
+| Swift 6 | Native | Needs care to pass strict checking |
 
-### Legacy GCD Pattern (iOS 13-16 codebases)
+For iOS 13 through 16, a private serial queue does the same job:
 
 ```swift
-class LegacyKeychainManager {
-    private let queue = DispatchQueue(label: "com.app.keychain",
-                                      qos: .userInitiated)
-
-    func load(key: String, completion: @escaping (Result<Data?, Error>) -> Void) {
+final class LegacySecretStore {
+    private let queue = DispatchQueue(label: "secrets.io", qos: .userInitiated)
+    func get(_ account: String, completion: @escaping @Sendable (Result<Data?, Error>) -> Void) {
         queue.async {
-            // ... SecItemCopyMatching on background queue ...
+            let result = Result { try readItem(account: account) }
             DispatchQueue.main.async { completion(result) }
         }
     }
 }
 ```
 
----
-
-## Performance Architecture
-
-### Two-Tier Encryption and Query Cost
-
-Because of the two-tier encryption design:
-
-- **`kSecReturnAttributes` only** → uses cached metadata key → **fast** (no Secure Enclave round-trip)
-- **`kSecReturnData`** → requires per-row secret key from Secure Enclave → **slower**
-
-For listing operations, always use `kSecReturnAttributes` or `kSecReturnRef` and fetch secret data only for the specific item the user selects.
-
-### Query Specificity
-
-The underlying SQLite database benefits from narrow constraints. A query specifying only `kSecClass: kSecClassGenericPassword` with `kSecMatchLimitAll` performs a **full table scan**. Adding `kSecAttrService` and `kSecAttrAccount` enables indexed lookup. Always include all relevant uniqueness attributes in production queries.
-
-### App Launch Performance
-
-Keychain access during app launch is a measurable performance risk:
-
-- Each call requires IPC to `securityd` plus potential Secure Enclave latency
-- Items with `kSecAttrAccessibleWhenUnlocked` may be unavailable before first unlock (iOS can launch apps before the user unlocks  -  e.g., background refresh, VoIP pushes)
-- **Best practice:** Defer keychain reads until actually needed. Never call SecItem synchronously in `application(_:didFinishLaunchingWithOptions:)`.
-- Handle `errSecInteractionNotAllowed` gracefully  -  never destructively.
-
-### Batch Operations
-
-There is **no batch API** for SecItem. Each function operates individually with one partial exception: `SecItemAdd` supports `kSecUseItemList` to add multiple certificates or keys (not passwords) in a single call. For batch reads, `SecItemCopyMatching` with `kSecMatchLimitAll` retrieves all matching items at once.
-
----
-
-## macOS Keychain Routing (TN3137)
-
-On macOS, the SecItem API can target two different implementations:
-
-| Implementation                 | Activated By                                                                           | Behavior                                                                                                             |
-| ------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| **Legacy file-based keychain** | Default on macOS (without opt-in)                                                      | Silently ignores unsupported attributes; inconsistent `kSecMatchLimit` defaults; different `SecItemAdd` return types |
-| **Data protection keychain**   | `kSecUseDataProtectionKeychain: true` (macOS 10.15+) or `kSecAttrSynchronizable: true` | Parity with iOS; required for iCloud Keychain sync, biometric protection, and Secure Enclave key storage             |
-
-**Modern apps must always target the data protection keychain.** Mac Catalyst and iOS Apps on Mac use it automatically.
+Here `readItem(account:)` stands for a synchronous read such as `fetch()` in
+the Reading section.
+The completion is `@Sendable` because it crosses two queues; without it Swift 6
+reports sending `completion` as a data race.
+
+## Performance
+
+- Returning attributes only uses the cached metadata key. It is quick and needs
+  no Secure Enclave work.
+- Returning data needs the per-row key from the Secure Enclave, so it costs
+  more.
+- For a list screen, fetch attributes or refs, and fetch data only for the row
+  the user picks.
+- A query with nothing but `kSecClass` and `kSecMatchLimitAll` scans the whole
+  table. Adding service and account lets `securityd` use its index.
+- At launch every read costs IPC plus enclave latency, and items protected with
+  a `WhenUnlocked` class can be unavailable if the app was launched before first
+  unlock (background refresh, VoIP pushes).
+- Do not call SecItem synchronously in
+  `application(_:didFinishLaunchingWithOptions:)`. Read the item when a feature
+  first needs it.
+- Passwords cannot be written in bulk. `SecItemAdd` with `kSecUseItemList` can
+  add several certificates or keys at once, but not password items. Reading in
+  bulk means `kSecMatchLimitAll`.
+
+## macOS: Two Keychains (TN3137)
+
+A Mac has two keychain implementations:
+
+- the legacy **file-based keychain**, which SecItem uses unless told otherwise;
+- the **data protection keychain**, which matches iOS.
+
+The file-based one ignores attributes it does not understand without saying
+so, applies `kSecMatchLimit` defaults inconsistently, and returns different
+types from `SecItemAdd`.
+
+Code opts into the data protection keychain with
+`kSecUseDataProtectionKeychain: true`, available from macOS 10.15, or by setting
+`kSecAttrSynchronizable: true`. It is required for iCloud Keychain sync,
+biometric protection and storing Secure Enclave keys. New code should always
+target it. Mac Catalyst apps and iOS apps running on a Mac use it
+automatically.
 
 ```swift
-// macOS: Always opt into data protection keychain
-var query: [CFString: Any] = [
-    kSecClass: kSecClassGenericPassword,
-    kSecAttrService: "com.example.app",
-    kSecAttrAccount: "token"
-]
-#if os(macOS)
-query[kSecUseDataProtectionKeychain] = true
-#endif
+func macSafe(_ query: [CFString: Any]) -> [CFString: Any] {
+    var q = query
+    #if os(macOS)
+    q[kSecUseDataProtectionKeychain] = true
+    #endif
+    return q
+}
 ```
 
-The file-based keychain's shim layer has documented bugs  -  it silently ignores unsupported attributes where the data protection keychain correctly returns `errSecNoSuchAttr` (-25244). Debugging keychain issues on macOS often starts with confirming which implementation is in use.
-
----
-
-## Accessibility and Data Protection Classes
-
-The `kSecAttrAccessible` attribute controls when a keychain item's secret data can be decrypted. Brief guidance here; see `keychain-access-control.md` for full coverage.
-
-| Constant                                           | Available When                   | Survives Backup? | Use Case                                     |
-| -------------------------------------------------- | -------------------------------- | ---------------- | -------------------------------------------- |
-| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`     | After unlock, until lock         | No (device-only) | Default for most secrets                     |
-| `kSecAttrAccessibleAfterFirstUnlock`               | After first unlock until restart | Yes              | Background processing tokens                 |
-| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`  | Only if passcode set + unlocked  | No               | Highest-sensitivity data (OWASP recommended) |
-| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | After first unlock until restart | No               | Background + device-only                     |
-
-**Deprecated:** `kSecAttrAccessibleAlways`  -  deprecated in iOS 12, unsupported on Apple Silicon Macs. Never use.
-
----
-
-## Cross-References
-
-- **Item class deep dive** (required vs optional attributes per kSecClass) → `keychain-item-classes.md`
-- **Access control flags and SecAccessControl** → `keychain-access-control.md`
-- **Biometric-gated keychain access** (LAContext integration) → `biometric-authentication.md`
-- **Secure Enclave key storage** → `secure-enclave.md`
-- **Credential lifecycle patterns** (OAuth tokens, API keys) → `credential-storage-patterns.md`
-- **Access groups and sharing** → `keychain-sharing.md`
-- **Testing keychain code** (mocks, CI/CD) → `testing-security-code.md`
-- **Common anti-patterns** (comprehensive catalog) → `common-anti-patterns.md`
-
----
-
-## Authoritative References
-
-| Source                                                                                                                          | Relevance                                          |
-| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| [Keychain Services](https://sosumi.ai/documentation/security/keychain_services)                                       | Main API landing page                              |
-| [TN3137: On Mac Keychain APIs and Implementations](https://sosumi.ai/documentation/technotes/tn3137-on-mac-keychains) | macOS data protection vs file-based routing        |
-| Quinn "The Eskimo!"  -  "SecItem: Fundamentals" / "SecItem: Pitfalls and Best Practices"                                          | Most practical DTS reference, updated through 2025 |
-| [Apple Platform Security Guide](https://support.apple.com/guide/security/welcome/web)  -  Keychain Data Protection chapter        | Two-tier encryption architecture                   |
-| WWDC 2014 Session 711  -  "Keychain and Authentication with Touch ID"                                                             | Touch ID/keychain integration patterns             |
-| WWDC 2019 Session 516  -  "What's New in Authentication"                                                                          | Modern credential management                       |
-
----
-
-## Implementation Notes
-
-1. **Dictionary key type convention:** Both `[CFString: Any]` and `[String: Any]` with `kSec* as String` casts are valid. This file uses `[CFString: Any]` for concise examples and shows both styles in the String Keys section.
-
-2. **Default accessibility recommendation:** `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` is strongest for high-security secrets, but items become unavailable if the user removes their passcode. `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` is a safe general foreground-only default. The actor manager example uses `AfterFirstUnlockThisDeviceOnly` for background compatibility while remaining device-bound.
-
-3. **`kSecReturnData` + `kSecMatchLimitAll`:** Some OS versions and keychain implementations have restrictions around returning data for multiple password-class matches. The safer pattern is to use `kSecReturnRef` or `kSecReturnAttributes` with `LimitAll`, then fetch data per item. See the Return Type Cheat Sheet.
-
----
-
-## Summary Checklist
-
-Before shipping keychain code, verify:
-
-1. **OSStatus checked on every call**  -  exhaustive `switch` covering at minimum `errSecSuccess`, `errSecDuplicateItem`, `errSecItemNotFound`, `errSecInteractionNotAllowed`; no ignored return values
-2. **Add-or-update pattern implemented**  -  `SecItemAdd` catches `-25299` and falls back to `SecItemUpdate`; duplicate saves never crash or silently fail
-3. **Return flags explicitly set**  -  every `SecItemCopyMatching` call includes at least one `kSecReturn*` flag; no "success but nil" bugs
-4. **CFTypeRef cast matches flags**  -  cast type corresponds to the combination of return flags and match limit (see Return Type Cheat Sheet)
-5. **Zero SecItem calls on `@MainActor`**  -  all keychain access isolated in a dedicated `actor` (iOS 17+) or serial `DispatchQueue` (iOS 13-16)
-6. **Fresh dictionaries per call**  -  no dictionary reuse across SecItem functions; add dict, query dict, and update dict are separate
-7. **kSec\* constants used**  -  no raw string literals for dictionary keys; using either `[CFString: Any]` or `[String: Any]` with `as String` casts
-8. **Queries are specific**  -  `kSecAttrService` + `kSecAttrAccount` included for GenericPassword; `kSecMatchLimitOne` used unless enumeration is needed
-9. **Delete treats not-found as success**  -  `errSecItemNotFound` on delete is a valid postcondition, not an error
-10. **macOS targets data protection keychain**  -  `kSecUseDataProtectionKeychain: true` set for macOS targets (automatic for Catalyst/iOS-on-Mac)
-11. **errSecInteractionNotAllowed handled non-destructively**  -  device-locked state triggers retry-later logic, never delete-and-recreate
+When a macOS keychain bug appears, first confirm which backend the call went
+to. An attribute the file-based keychain quietly drops will produce
+`errSecNoSuchAttr` (-25244) on the data protection keychain.
+
+## Accessibility at a Glance
+
+| Constant | Readable | In backups | Typical use |
+| --- | --- | --- | --- |
+| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` | while unlocked | no | the default for most secrets |
+| `kSecAttrAccessibleAfterFirstUnlock` | from first unlock until restart | yes | tokens read in the background |
+| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` | unlocked and a passcode is set | no | the most sensitive data (OWASP recommendation) |
+| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | after the first unlock, until reboot | no | device-bound items read in the background |
+
+`kSecAttrAccessibleAlways` was deprecated in iOS 12 and is not supported on
+Apple silicon Macs. Do not use it. The full model is in
+[keychain-access-control.md](keychain-access-control.md).
+
+Choosing among them: `WhenPasscodeSetThisDeviceOnly` is the strongest, but its
+items are deleted if the user removes the passcode. `WhenUnlockedThisDeviceOnly`
+is a safe default for foreground use. The actor above defaults to
+`AfterFirstUnlockThisDeviceOnly` because it assumes background callers.
+
+## Checklist
+
+1. Every SecItem call switches over its status, covering success, duplicate,
+   not found and interaction-not-allowed.
+2. Saves fall back to `SecItemUpdate` on -25299.
+3. Every `SecItemCopyMatching` sets at least one `kSecReturn*` key.
+4. The cast of the `CFTypeRef` result matches the return keys and match limit.
+5. No SecItem call runs on `@MainActor` (actor on iOS 17+, serial queue on
+   iOS 13 to 16).
+6. Add, query and update dictionaries are built fresh for each call.
+7. Keys are `kSec*` constants, not string literals.
+8. Queries are specific: service and account for generic passwords,
+   `kSecMatchLimitOne` unless listing.
+9. Delete treats `errSecItemNotFound` as success.
+10. macOS code sets `kSecUseDataProtectionKeychain: true`.
+11. `errSecInteractionNotAllowed` never leads to deletion.
+
+## Related Files
+
+- [keychain-item-classes.md](keychain-item-classes.md), [keychain-access-control.md](keychain-access-control.md),
+  [biometric-authentication.md](biometric-authentication.md), [secure-enclave.md](secure-enclave.md)
+- [credential-storage-patterns.md](credential-storage-patterns.md), [keychain-sharing.md](keychain-sharing.md),
+  [testing-security-code.md](testing-security-code.md), [common-anti-patterns.md](common-anti-patterns.md)
+
+Further reading: the Keychain Services documentation; TN3137; Quinn's two SecItem
+forum posts; the keychain data protection chapter of the Apple Platform
+Security Guide; WWDC 2014 session 711, titled Keychain and Authentication
+with Touch ID; WWDC 2019 session 516, titled What's New in Authentication.