@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,543 +1,421 @@
 # Keychain Access Control
 
-> Scope: Selecting `kSecAttrAccessible` classes and `SecAccessControl` flags to enforce the correct lock-state and user-presence guarantees for keychain items.
+Two independent settings decide whether a read succeeds:
 
-Data protection classes (`kSecAttrAccessible`) and runtime authentication gates (`SecAccessControl`) form the two-layer security model protecting every keychain item. The first controls **when** an item's class key is available in memory based on device state; the second controls **how** the user must authenticate at access time. Both must be satisfied for a read to succeed. Getting this wrong is the single most common cause of production keychain failures  -  background operations that silently return `nil`, items that vanish after device migration, or credentials left decryptable at rest.
+- **When** the item can be decrypted: `kSecAttrAccessible` picks the data
+  protection class, which decides whether the class key is in memory given the
+  device state (locked, unlocked, not yet unlocked since boot).
+- **How** the user must prove presence at the moment of access:
+  `SecAccessControl` adds biometric, passcode or application-password
+  requirements.
 
-Sources: Apple Platform Security Guide (2024-2026 editions), Apple Keychain Services documentation, TN3137, WWDC 2014 Session 711 ("Keychain and Authentication with Touch ID"), WWDC 2015 Session 706, SecAccessControl documentation, OWASP MASTG.
+A read has to satisfy both. Getting either wrong produces the keychain failures
+that reach production most often: background reads that return nothing, items
+that vanish after a device migration, and credentials that are readable at rest
+when they should not be.
 
----
+Sources: Apple Platform Security Guide (2024 to 2026 editions), Keychain
+Services documentation, TN3137, the `SecAccessControl` documentation, WWDC
+2014 Session 711, WWDC 2015 Session 706, and OWASP MASTG.
 
 ## Contents
 
-- [The "When" Layer: Seven Accessibility Constants](#the-when-layer-seven-accessibility-constants)
-  - [The Protection Spectrum](#the-protection-spectrum)
-  - [Quick Reference Table](#quick-reference-table)
-  - [Lock-State Spectrum Explained](#lock-state-spectrum-explained)
-- [The "How" Layer: SecAccessControl Flags](#the-how-layer-secaccesscontrol-flags)
-  - [Available Flags](#available-flags)
-  - [Flag Compatibility Matrix](#flag-compatibility-matrix)
-  - [Composing Constraints](#composing-constraints)
-- [The Cardinal Rule: Never Set Both Attributes](#the-cardinal-rule-never-set-both-attributes)
-- [Decision Matrix: Choosing the Right Accessibility Level](#decision-matrix-choosing-the-right-accessibility-level)
-  - [`WhenPasscodeSetThisDeviceOnly`  -  Data that should self-destruct](#whenpasscodesetthisdeviceonly-data-that-should-self-destruct)
-  - [`WhenUnlockedThisDeviceOnly`  -  Standard device-bound credentials](#whenunlockedthisdeviceonly-standard-device-bound-credentials)
-  - [`AfterFirstUnlockThisDeviceOnly`  -  Background operations (most common for services)](#afterfirstunlockthisdeviceonly-background-operations-most-common-for-services)
-  - [`AfterFirstUnlock`  -  Background + backup migration](#afterfirstunlock-background-backup-migration)
-  - [Dual-Item Strategy for Mixed Contexts](#dual-item-strategy-for-mixed-contexts)
-- [Common AI-Generated Mistakes](#common-ai-generated-mistakes)
-  - [Mistake 1: Omitting `kSecAttrAccessible` (inheriting the wrong default)](#mistake-1-omitting-ksecattraccessible-inheriting-the-wrong-default)
-  - [Mistake 2: Using deprecated `kSecAttrAccessibleAlways`](#mistake-2-using-deprecated-ksecattraccessiblealways)
-  - [Mistake 3: Not handling `ThisDeviceOnly` item loss after device migration](#mistake-3-not-handling-thisdeviceonly-item-loss-after-device-migration)
-  - [Mistake 4: Biometric flags on background-accessible protection levels](#mistake-4-biometric-flags-on-background-accessible-protection-levels)
-  - [Mistake 5: Conflicting flags without logical operator](#mistake-5-conflicting-flags-without-logical-operator)
+- [When: The Accessibility Constants](#when-the-accessibility-constants)
+- [How: SecAccessControl Flags](#how-secaccesscontrol-flags)
+- [Accessibility and Access Control Are Exclusive](#accessibility-and-access-control-are-exclusive)
+- [Choosing a Combination](#choosing-a-combination)
+- [Mistakes in Generated Code](#mistakes-in-generated-code)
 - [Code Patterns](#code-patterns)
-  - [Biometric protection with highest security](#biometric-protection-with-highest-security)
-  - [Background-accessible token (push notifications, VPN, widgets)](#background-accessible-token-push-notifications-vpn-widgets)
-  - [Accessing a `WhenUnlocked` item from a background extension](#accessing-a-whenunlocked-item-from-a-background-extension)
-- [macOS: `kSecUseDataProtectionKeychain`](#macos-ksecusedataprotectionkeychain)
-- [NSFileProtection Sidebar](#nsfileprotection-sidebar)
-- [Error Codes Reference](#error-codes-reference)
-- [iOS Version Timeline](#ios-version-timeline)
-- [Testing Requirements](#testing-requirements)
-- [Cross-References](#cross-references)
-- [Summary Checklist](#summary-checklist)
-
-## The "When" Layer: Seven Accessibility Constants
-
-Every keychain item is encrypted with a class key derived from the device's hardware UID and (for most classes) the user's passcode. The `kSecAttrAccessible` attribute selects which class key protects the item, determining when the system can decrypt it. **If you omit `kSecAttrAccessible`, the default is `kSecAttrAccessibleWhenUnlocked`**  -  confirmed by Apple documentation. This default breaks all background operations.
-
-### The Protection Spectrum
-
-Listed from most restrictive to least:
-
-**`kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`** (iOS 8+)  -  the highest-security class. Items are accessible only while unlocked, and only if a device passcode is currently set. Two unique behaviors: (1) `SecItemAdd` fails on devices without a passcode, (2) **removing the passcode permanently deletes all items in this class**  -  class keys are discarded, data is unrecoverable. No non-`ThisDeviceOnly` variant exists. Items don't sync to iCloud Keychain, aren't backed up, and aren't in escrow keybags.
-
-**`kSecAttrAccessibleWhenUnlockedThisDeviceOnly`**  -  Items decryptable only while unlocked. Device-bound: excluded from backups and device migration.
-
-**`kSecAttrAccessibleWhenUnlocked`** ⭐ (system default)  -  Same lock-state behavior as above, but items migrate with encrypted backups. Maps to `NSFileProtectionComplete`. Class key is discarded from memory shortly after the device locks (~10 seconds with Require Password set to Immediately).
-
-**`kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`**  -  **The correct choice for background operations.** After the user unlocks the device once following a restart, the class key remains in memory until the next restart  -  even while locked. Device-bound.
-
-**`kSecAttrAccessibleAfterFirstUnlock`**  -  Same background accessibility, but items migrate with encrypted backups. Apple uses this for system Wi-Fi passwords, mail accounts, and iCloud tokens. Maps to `NSFileProtectionCompleteUntilFirstUserAuthentication`.
-
-**`kSecAttrAccessibleAlwaysThisDeviceOnly`** ⚠️ DEPRECATED  -  Deprecated in iOS 12 / macOS 10.14. Apple announced intent at WWDC 2015 Session 706.
-
-**`kSecAttrAccessibleAlways`** ⚠️ DEPRECATED  -  Same deprecation. Items encrypted with only the device UID (no passcode involvement), equivalent to `NSFileProtectionNone`.
-
-Deprecated "Always" constants have OS-version-specific behavior and should not be used for new or migrated code. **Migrate to `kSecAttrAccessibleAfterFirstUnlock` or a stricter class**, and block these constants in CI linting rather than relying on runtime behavior across OS versions.
-
-### Quick Reference Table
-
-| Constant                         | Accessible When         | Survives Lock | Migrates in Backup | Special                         |
-| -------------------------------- | ----------------------- | ------------- | ------------------ | ------------------------------- |
-| `WhenPasscodeSetThisDeviceOnly`  | Unlocked + passcode set | No            | No                 | **Deleted on passcode removal** |
-| `WhenUnlockedThisDeviceOnly`     | Unlocked                | No            | No                 |  -                                |
-| `WhenUnlocked` ⭐ default        | Unlocked                | No            | Yes                |  -                                |
-| `AfterFirstUnlockThisDeviceOnly` | After first unlock      | Yes           | No                 | Background-safe                 |
-| `AfterFirstUnlock`               | After first unlock      | Yes           | Yes                | Background-safe + migratable    |
-| `AlwaysThisDeviceOnly` ⚠️        | Always¹                 | Yes           | No                 | Deprecated iOS 12               |
-| `Always` ⚠️                      | Always¹                 | Yes           | Yes                | Deprecated iOS 12               |
-
-¹ Behavior may be remapped to `AfterFirstUnlock` on modern iOS versions.
-
-### Lock-State Spectrum Explained
-
-After a device restart, the system is in **Before First Unlock (BFU)** state. Only items with the deprecated `Always` class are supposed to be accessible. Even `AfterFirstUnlock` items are locked.
-
-Once the user enters their passcode, the device enters **After First Unlock (AFU)** state. `AfterFirstUnlock` class keys load into memory and remain there through subsequent lock/unlock cycles until the next restart. `WhenUnlocked` class keys are available only during active unlocked periods and discarded each time the device locks.
-
-> **iOS 15+ caveat  -  app pre-warming:** iOS can launch your process before first unlock for faster app startup. This means even `AfterFirstUnlock` items may be temporarily unavailable during pre-warm. Check `UIApplication.shared.isProtectedDataAvailable` before accessing keychain items, and defer if it returns `false`.
-
----
-
-## The "How" Layer: SecAccessControl Flags
-
-`SecAccessControl` adds runtime authentication requirements on top of data-at-rest protection. It is created via `SecAccessControlCreateWithFlags`, which embeds the accessibility level inside the control object:
+- [macOS: kSecUseDataProtectionKeychain](#macos-ksecusedataprotectionkeychain)
+- [File Protection Sidebar](#file-protection-sidebar)
+- [Error Codes](#error-codes)
+- [Version Timeline](#version-timeline)
+- [Testing](#testing)
+- [Checklist](#checklist)
+- [Related Files](#related-files)
+
+## When: The Accessibility Constants
+
+Every item is encrypted under a class key. Class keys derive from the device's
+hardware UID and, for most classes, from the passcode as well. If an add leaves
+`kSecAttrAccessible` out, the item gets `kSecAttrAccessibleWhenUnlocked`, which
+means nothing running in the background can read it.
+
+| Constant | Readable when | Leaves the device? | Notes |
+| --- | --- | --- | --- |
+| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` (iOS 8+) | unlocked, and a passcode is currently set | never | `SecItemAdd` fails if there is no passcode. Removing the passcode deletes every such item for good. No backup, no iCloud sync, not in the escrow keybag, and no migratable variant. |
+| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` | unlocked | never | Not in backups, not migrated. |
+| `kSecAttrAccessibleWhenUnlocked` | unlocked | encrypted backups | The default. Corresponds to `NSFileProtectionComplete`. With Require Passcode set to Immediately, the class key is discarded about ten seconds after lock. |
+| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | from the first unlock after boot until restart, including while locked | never | The choice for background work that should stay on this device. |
+| `kSecAttrAccessibleAfterFirstUnlock` | same as above | encrypted backups | Apple uses it for Wi-Fi passwords, mail accounts and iCloud tokens. Corresponds to `NSFileProtectionCompleteUntilFirstUserAuthentication`. |
+| `kSecAttrAccessibleAlwaysThisDeviceOnly` | always | never | Deprecated in iOS 12 and macOS 10.14; the intent was announced at WWDC 2015 Session 706. |
+| `kSecAttrAccessibleAlways` | always | encrypted backups | Deprecated at the same time. Protected by the UID only, the same strength as `NSFileProtectionNone`. |
+
+The two `Always` constants still compile, but what they do depends on the OS
+version (they may be treated as `AfterFirstUnlock`). Move existing items to
+`AfterFirstUnlock` or something stricter, and add a CI lint that rejects the
+constants.
+
+Summary:
+
+- Still readable while locked: the `AfterFirstUnlock` pair (and the deprecated
+  `Always` pair).
+- Carried in backups: `WhenUnlocked`, `AfterFirstUnlock`, `Always`.
+
+### Device states
+
+- After a restart the device is in **Before First Unlock** (BFU). Nothing but
+  the `Always` classes can be read, including `AfterFirstUnlock` items.
+- Once the user enters the passcode the device is **After First Unlock** (AFU).
+  `AfterFirstUnlock` class keys stay loaded through later lock cycles until the
+  next restart. `WhenUnlocked` keys are dropped at every lock.
+- From iOS 15, the system may pre-warm an app, launching its process before the
+  first unlock. Even `AfterFirstUnlock` items can be unreadable then. Check
+  `UIApplication.shared.isProtectedDataAvailable` and postpone the read when it
+  is `false` (or wait for `protectedDataDidBecomeAvailableNotification`).
+
+## How: SecAccessControl Flags
 
 ```swift
 func SecAccessControlCreateWithFlags(
-    _ allocator: CFAllocator?,       // Pass nil
-    _ protection: CFTypeRef,          // A kSecAttrAccessible constant
+    _ allocator: CFAllocator?,
+    _ protection: CFTypeRef,
     _ flags: SecAccessControlCreateFlags,
     _ error: UnsafeMutablePointer<Unmanaged<CFError>?>?
 ) -> SecAccessControl?
 ```
 
-### Available Flags
-
-**Authentication constraints:**
-
-- **`.userPresence`** (iOS 8+)  -  Biometry OR passcode. Does not require biometry enrollment; auto-falls back to passcode. Equivalent to `[.biometryAny, .or, .devicePasscode]` but handles no-biometry gracefully.
-- **`.biometryAny`** (iOS 11.3+, was `.touchIDAny`)  -  Requires biometric authentication. Item **survives** enrollment changes (new fingerprints, Face ID re-enrollment).
-- **`.biometryCurrentSet`** (iOS 11.3+, was `.touchIDCurrentSet`)  -  Requires biometric authentication. Item **invalidated** on enrollment changes. Most secure biometric option  -  blocks an attacker who enrolls their own biometrics.
-- **`.devicePasscode`** (iOS 9+)  -  Requires device passcode entry only.
-
-**Logical combinators:**
-
-- **`.or`**  -  At least one constraint must be satisfied.
-- **`.and`**  -  All constraints must be satisfied.
-
-**Additional:**
+Pass `nil` for the allocator. `protection` is one of the accessibility
+constants above; it becomes part of the access-control object.
 
-- **`.privateKeyUsage`** (iOS 9+)  -  Required for Secure Enclave private key operations (signing, key agreement).
-- **`.applicationPassword`** (iOS 9+)  -  Adds an app-provided password to key derivation. Not a constraint  -  an additional encryption layer.
-
-### Flag Compatibility Matrix
-
-| Flag                   | Works in Background?     | Typical Pairing                           | Failure if Misused                           |
-| ---------------------- | ------------------------ | ----------------------------------------- | -------------------------------------------- |
-| `.userPresence`        | No                       | Foreground + `WhenUnlocked`               | `-25308` in background                       |
-| `.biometryAny`         | No                       | Foreground secrets                        | `errSecAuthFailed` if no biometrics enrolled |
-| `.biometryCurrentSet`  | No                       | `WhenPasscodeSetTDO` for highest security | Auth fails on enrollment change              |
-| `.devicePasscode`      | No                       | Compliance flows                          | `-25308` without UI                          |
-| `.privateKeyUsage`     | Yes (for key ops)        | Secure Enclave keys                       |  -                                             |
-| `.applicationPassword` | Yes (if password cached) | Niche models                              | Password lifecycle management                |
-
-### Composing Constraints
-
-Since `SecAccessControlCreateFlags` is an `OptionSet`, compose with array literal syntax:
-
-```swift
-// Biometry OR passcode  -  most common pattern
-let flags: SecAccessControlCreateFlags = [.biometryCurrentSet, .or, .devicePasscode]
-
-// Biometry AND passcode  -  both required (rare, high security)
-let flags: SecAccessControlCreateFlags = [.biometryAny, .and, .devicePasscode]
-
-// Biometry OR passcode, plus application password encryption
-let flags: SecAccessControlCreateFlags = [.biometryAny, .or, .devicePasscode, .applicationPassword]
-```
+| Flag | Since | Requires | Works in the background |
+| --- | --- | --- | --- |
+| `.userPresence` | iOS 8 | biometry or the passcode; falls back to the passcode by itself and works with nothing enrolled. Close to `[.biometryAny, .or, .devicePasscode]` but tolerant of devices without biometry. | no |
+| `.biometryAny` | iOS 11.3 (was `.touchIDAny`) | any enrolled finger or face; survives enrollment changes | no |
+| `.biometryCurrentSet` | iOS 11.3 (was `.touchIDCurrentSet`) | the enrollment that existed when the item was stored; any change invalidates the item. The strongest choice, since an attacker who adds their own face or finger gains nothing. | no |
+| `.devicePasscode` | iOS 9 | the passcode only | no |
+| `.privateKeyUsage` | iOS 9 | needed for any Secure Enclave private key operation (signing, key agreement) | yes, for key operations |
+| `.applicationPassword` | iOS 9 | a password supplied by the app, mixed into key derivation; an additional encryption layer rather than a gate | yes, if the password is cached |
 
-> **Critical rule: `.or` / `.and` is required between authentication flags.** Combining `.biometryCurrentSet` and `.devicePasscode` without a logical operator causes `SecAccessControlCreateWithFlags` to return `nil` with `errSecParam` (-50). Both sources confirm this behavior.
+`.or` accepts any one of the listed requirements; `.and` demands all of them.
 
----
+What misuse looks like:
 
-## The Cardinal Rule: Never Set Both Attributes
+| Flag | Failure |
+| --- | --- |
+| `.userPresence` | -25308 when read in the background |
+| `.biometryAny` | `errSecAuthFailed` when nothing is enrolled |
+| `.biometryCurrentSet` | authentication fails for good after an enrollment change |
+| `.devicePasscode` | -25308 when no UI can be shown |
 
-`kSecAttrAccessible` and `kSecAttrAccessControl` are **mutually exclusive** in the query dictionary. When you use `SecAccessControlCreateWithFlags`, the accessibility level is embedded inside the `SecAccessControl` object via the `protection` parameter. Setting both in the same `SecItemAdd` query causes **`errSecParam` (-50)**.
+Usual pairings: `.userPresence` with a foreground `WhenUnlocked` item;
+`.biometryCurrentSet` with `WhenPasscodeSetThisDeviceOnly`; `.devicePasscode`
+for flows that a compliance rule requires; `.privateKeyUsage` on Secure
+Enclave keys.
 
-```swift
-// ❌ WRONG  -  sets accessibility twice, causes errSecParam (-50)
-var error: Unmanaged<CFError>?
-let access = SecAccessControlCreateWithFlags(
-    nil,
-    kSecAttrAccessibleWhenUnlockedThisDeviceOnly, // ← accessibility set HERE
-    [.biometryCurrentSet, .or, .devicePasscode],
-    &error
-)!
-
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrAccount as String: "credential",
-    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly, // ❌ CONFLICT
-    kSecAttrAccessControl as String: access, // ← already contains accessibility
-    kSecValueData as String: secretData
-]
-// SecItemAdd returns errSecParam (-50)
-```
+`SecAccessControlCreateFlags` is an `OptionSet`:
 
 ```swift
-// ✅ CORRECT  -  accessibility set only inside SecAccessControl
-var error: Unmanaged<CFError>?
-guard let access = SecAccessControlCreateWithFlags(
-    nil,
-    kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
-    [.biometryCurrentSet, .or, .devicePasscode],
-    &error
-) else { throw KeychainError.accessControlCreationFailed(error?.takeRetainedValue()) }
-
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrAccount as String: "credential",
-    kSecAttrAccessControl as String: access, // Contains accessibility + auth flags
-    kSecValueData as String: secretData
-]
+let strongWithRecovery: SecAccessControlCreateFlags = [.biometryCurrentSet, .or, .devicePasscode]
+let both: SecAccessControlCreateFlags = [.biometryAny, .and, .devicePasscode]
+let layered: SecAccessControlCreateFlags = [.biometryAny, .or, .devicePasscode, .applicationPassword]
 ```
 
----
-
-## Decision Matrix: Choosing the Right Accessibility Level
-
-### `WhenPasscodeSetThisDeviceOnly`  -  Data that should self-destruct
-
-Use for your most sensitive credentials. Pair with `.biometryCurrentSet` via `SecAccessControl`. Accept the tradeoff: items are permanently destroyed on passcode removal and never survive device migration. Your app **must** handle item absence gracefully and guide users through re-authentication.
-
-**Use cases:** Banking session tokens, password manager vault keys, healthcare credentials, E2E encryption private keys.
-
-### `WhenUnlockedThisDeviceOnly`  -  Standard device-bound credentials
-
-Credentials that should be device-bound but don't need passcode-deletion behavior. Re-authenticate after device migration.
-
-**Use cases:** OAuth access tokens (refreshable), app-specific API keys, cached credentials, device registration tokens.
-
-### `AfterFirstUnlockThisDeviceOnly`  -  Background operations (most common for services)
-
-The correct choice for **any keychain item accessed by background code**  -  push notification handlers, WidgetKit timeline providers, background fetch, VPN extensions, notification service extensions. Device-bound.
-
-**Use cases:** Push notification decryption keys, VPN credentials, background sync tokens, watch connectivity tokens.
-
-### `AfterFirstUnlock`  -  Background + backup migration
-
-Same background accessibility, plus items migrate with encrypted backups. Use when background access and device-transfer continuity are both needed.
+Two authentication flags with no `.or` or `.and` between them make
+`SecAccessControlCreateWithFlags` return `nil` with `errSecParam` (-50).
 
-**Use cases:** Enterprise VPN credentials, email account credentials, Wi-Fi configuration passwords.
+Any item whose flags involve biometry makes the system show Face ID on devices
+that have it, so the app's `Info.plist` must contain
+`NSFaceIDUsageDescription`. See
+[biometric-authentication.md](biometric-authentication.md).
 
-### Dual-Item Strategy for Mixed Contexts
+## Accessibility and Access Control Are Exclusive
 
-If a credential needs both background access (no UI) and foreground biometric protection (with UI), **store two separate items**: a background-capable token with `AfterFirstUnlockThisDeviceOnly` (no `SecAccessControl` user-presence flags) and a stronger foreground-only item with `WhenUnlockedThisDeviceOnly` + biometric `SecAccessControl`. This avoids the logical contradiction of biometric flags on background-accessible items.
-
----
-
-## Common AI-Generated Mistakes
-
-### Mistake 1: Omitting `kSecAttrAccessible` (inheriting the wrong default)
-
-The most pervasive error. AI code generators produce keychain wrappers that never set `kSecAttrAccessible`, inheriting `WhenUnlocked`. Works during development (device unlocked while testing), fails in production when background extensions execute while locked  -  `errSecInteractionNotAllowed` (-25308), often silently swallowed.
-
-```swift
-// ❌ WRONG  -  omits kSecAttrAccessible, defaults to WhenUnlocked
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrAccount as String: "authToken",
-    kSecAttrService as String: "com.example.app",
-    kSecValueData as String: tokenData
-    // Missing: kSecAttrAccessible  -  background extensions WILL fail with -25308
-]
-```
+An add dictionary carries `kSecAttrAccessible` or `kSecAttrAccessControl`,
+never both. The pair is rejected with `errSecParam` (-50). With access control,
+the accessibility value lives inside the `SecAccessControl` object.
 
 ```swift
-// ✅ CORRECT  -  explicit accessibility for background use
-let query: [String: Any] = [
+// Wrong: accessibility given twice, and the access control force-unwrapped.
+let acl = SecAccessControlCreateWithFlags(nil, kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+                                          .userPresence, nil)!
+let clash: [String: Any] = [
     kSecClass as String: kSecClassGenericPassword,
-    kSecAttrAccount as String: "authToken",
-    kSecAttrService as String: "com.example.app",
-    kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
-    kSecValueData as String: tokenData
+    kSecAttrAccount as String: "journal-key",
+    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+    kSecAttrAccessControl as String: acl
 ]
 ```
 
-### Mistake 2: Using deprecated `kSecAttrAccessibleAlways`
-
-Compiles with a warning on iOS 12+, runs at runtime  -  arguably worse than a hard failure. No meaningful lock-state protection.
-
-```swift
-// ❌ WRONG  -  deprecated since iOS 12
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrAccessible as String: kSecAttrAccessibleAlways, // ⚠️ Deprecated
-    kSecValueData as String: tokenData
-]
-// Replacement: kSecAttrAccessibleAfterFirstUnlock
-```
-
-### Mistake 3: Not handling `ThisDeviceOnly` item loss after device migration
-
-Items with `ThisDeviceOnly` are cryptographically bound to the hardware UID. They are excluded from all backups, iCloud sync, and Quick Start device-to-device migration. After restoring to a new device, these items silently disappear  -  `errSecItemNotFound` (-25300). AI-generated code rarely implements re-authentication flows for this scenario.
-
-### Mistake 4: Biometric flags on background-accessible protection levels
-
-Setting `.biometryCurrentSet` with `kSecAttrAccessibleAfterFirstUnlock` is technically valid at the API level but creates a **logical contradiction**: `AfterFirstUnlock` implies background access while locked, but biometric auth requires an interactive prompt. Result: `errSecInteractionNotAllowed` in background contexts, defeating the purpose.
-
-### Mistake 5: Conflicting flags without logical operator
-
-Combining `.biometryCurrentSet` and `.devicePasscode` without `.or` or `.and` causes `SecAccessControlCreateWithFlags` to return `nil` / `errSecParam` (-50).
-
-```swift
-// ❌ WRONG  -  missing logical operator
-let access = SecAccessControlCreateWithFlags(
-    nil,
-    kSecAttrAccessibleWhenUnlocked,
-    [.biometryCurrentSet, .devicePasscode], // Missing .or or .and
-    &error
-)
-// Returns nil, error contains errSecParam
-```
-
 ```swift
-// ✅ CORRECT  -  explicit .or between constraints
-let access = SecAccessControlCreateWithFlags(
-    nil,
-    kSecAttrAccessibleWhenUnlocked,
-    [.biometryCurrentSet, .or, .devicePasscode],
-    &error
-)
+func journalKeyEntry(_ bytes: Data) throws -> [String: Any] {
+    var cfError: Unmanaged<CFError>?
+    guard let acl = SecAccessControlCreateWithFlags(
+        nil, kSecAttrAccessibleWhenUnlockedThisDeviceOnly, .userPresence, &cfError) else {
+        throw (cfError?.takeRetainedValue() as Error?) ?? KeychainError(status: errSecParam)
+    }
+    return [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: "com.example.journal",
+        kSecAttrAccount as String: "journal-key",
+        kSecAttrAccessControl as String: acl,
+        kSecValueData as String: bytes
+    ]
+}
 ```
 
----
+## Choosing a Combination
+
+| Setting | For | Consequence to design for | Examples |
+| --- | --- | --- | --- |
+| `WhenPasscodeSetThisDeviceOnly` + `.biometryCurrentSet` | the most sensitive data | Items disappear if the passcode is removed and never move to a new device; the app must cope with the item being gone and re-authenticate. | banking session tokens, password-vault keys, health-record credentials, end-to-end private keys |
+| `WhenUnlockedThisDeviceOnly` | device-bound data that should survive passcode changes | Re-authenticate after migration. | refreshable OAuth access tokens, app API keys, cached credentials, device registration tokens |
+| `AfterFirstUnlockThisDeviceOnly` | anything read by background code: push handlers, WidgetKit timeline providers, background fetch, VPN and notification service extensions | Readable while locked, so weaker at rest. | push payload decryption keys, VPN credentials, background sync tokens, watch connectivity tokens |
+| `AfterFirstUnlock` | background access that should also survive a restore | Travels in encrypted backups. | enterprise VPN credentials, mail credentials, Wi-Fi passwords |
+
+When one credential needs both background access and biometric protection in
+the foreground, keep two items: one `AfterFirstUnlockThisDeviceOnly` with no
+presence flags for background code, and one `WhenUnlockedThisDeviceOnly` with a
+biometric access control for the foreground path.
+
+## Mistakes in Generated Code
+
+1. **No accessibility value.** The item defaults to `WhenUnlocked`. Everything
+   works during development on an unlocked phone; in the background the read
+   returns -25308, which is often swallowed. Background items should say
+   `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` explicitly.
+2. **`kSecAttrAccessibleAlways`.** On iOS 12 and later it compiles with a
+   deprecation warning and runs, offering no protection tied to the lock state.
+   Replace it with `kSecAttrAccessibleAfterFirstUnlock`.
+3. **Forgetting what `ThisDeviceOnly` means.** Such items are tied to the
+   hardware UID and are left out of backups, iCloud Keychain and Quick Start
+   transfers. After a restore onto a new device the read returns
+   `errSecItemNotFound` (-25300). Build the re-authentication path.
+4. **`.biometryCurrentSet` on an `AfterFirstUnlock` item.** The API accepts it,
+   but the two settings contradict each other: the class promises background
+   availability and the flag demands a user. Background reads fail with
+   `errSecInteractionNotAllowed`.
+5. **Two authentication flags with no operator.** `nil` and `errSecParam`.
 
 ## Code Patterns
 
-✅ The first two examples are correct patterns for foreground and background access. The third example is intentionally incorrect.
+### Top-sensitivity secret
 
-### Biometric protection with highest security
+Saving follows add, then update on duplicate. Updating the data of an item that
+has an access control requires the user to authenticate, so pass an
+`LAContext` for the prompt. `SecItemUpdate` cannot change an item's access
+control, so a change of policy is the one case that deletes and re-adds.
 
 ```swift
-func saveBiometricProtectedItem(data: Data, account: String, service: String) throws {
-    var error: Unmanaged<CFError>?
-    guard let accessControl = SecAccessControlCreateWithFlags(
-        nil,
-        kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
-        [.biometryCurrentSet, .or, .devicePasscode],
-        &error
-    ) else {
-        throw KeychainError.accessControlCreationFailed(error?.takeRetainedValue())
-    }
+import LocalAuthentication
 
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: service,
-        kSecAttrAccessControl as String: accessControl,
-        kSecValueData as String: data
-    ]
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    switch status {
-    case errSecSuccess: return
-    case errSecDuplicateItem:
-        // Must delete + re-add: SecItemUpdate cannot change SecAccessControl
-        let searchQuery: [String: Any] = [
+enum VaultKeyStore {
+    static var base: [String: Any] {
+        [
             kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: account,
-            kSecAttrService as String: service
+            kSecAttrService as String: "com.example.vault",
+            kSecAttrAccount as String: "master"
         ]
-        let deleteStatus = SecItemDelete(searchQuery as CFDictionary)
-        guard deleteStatus == errSecSuccess else {
-            throw KeychainError.fromStatus(deleteStatus)
+    }
+
+    static func policy() throws -> SecAccessControl {
+        var cfError: Unmanaged<CFError>?
+        guard let acl = SecAccessControlCreateWithFlags(
+            nil, kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
+            [.biometryCurrentSet, .or, .devicePasscode], &cfError) else {
+            throw (cfError?.takeRetainedValue() as Error?) ?? KeychainError(status: errSecParam)
+        }
+        return acl
+    }
+
+    static func save(_ key: Data, context: LAContext) throws {
+        var insert = base
+        insert[kSecAttrAccessControl as String] = try policy()
+        insert[kSecValueData as String] = key
+        let added = SecItemAdd(insert as CFDictionary, nil)
+        guard added == errSecDuplicateItem else {
+            guard added == errSecSuccess else { throw KeychainError(status: added) }
+            return
         }
-        let readdStatus = SecItemAdd(query as CFDictionary, nil)
-        guard readdStatus == errSecSuccess else {
-            throw KeychainError.fromStatus(readdStatus)
+        var match = base
+        match[kSecUseAuthenticationContext as String] = context
+        let changed = SecItemUpdate(match as CFDictionary,
+                                    [kSecValueData as String: key] as CFDictionary)
+        guard changed == errSecSuccess else { throw KeychainError(status: changed) }
+    }
+
+    static func replacePolicy(keeping key: Data) throws {
+        let removed = SecItemDelete(base as CFDictionary)
+        guard removed == errSecSuccess || removed == errSecItemNotFound else {
+            throw KeychainError(status: removed)
         }
-    default:
-        throw KeychainError.fromStatus(status)
+        var insert = base
+        insert[kSecAttrAccessControl as String] = try policy()
+        insert[kSecValueData as String] = key
+        let added = SecItemAdd(insert as CFDictionary, nil)
+        guard added == errSecSuccess else { throw KeychainError(status: added) }
     }
 }
 ```
 
-> **Important:** `SecItemUpdate` **cannot** change a `SecAccessControl` attribute on an existing item. To change access control, you must delete and re-add. Both sources confirm this.
+`replacePolicy` exists only because access control cannot be updated in place.
+Read the value (with authentication) before calling it, so nothing is lost.
+`base` is computed: a `[String: Any]` is not `Sendable`, so a `static let` of
+it is a Swift 6 error.
 
-### Background-accessible token (push notifications, VPN, widgets)
+### Token read by background code
 
 ```swift
-func saveBackgroundToken(_ token: Data, account: String, service: String) throws {
-    let query: [String: Any] = [
+func saveSyncToken(_ token: Data) throws {
+    let match: [String: Any] = [
         kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: service,
-        kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
-        kSecValueData as String: token
+        kSecAttrService as String: "com.example.sync",
+        kSecAttrAccount as String: "bg-token"
     ]
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    switch status {
-    case errSecSuccess: return
-    case errSecDuplicateItem:
-        let updateAttrs: [String: Any] = [kSecValueData as String: token]
-        let searchQuery: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: account,
-            kSecAttrService as String: service
-        ]
-        let updateStatus = SecItemUpdate(searchQuery as CFDictionary, updateAttrs as CFDictionary)
-        guard updateStatus == errSecSuccess else {
-            throw KeychainError.fromStatus(updateStatus)
-        }
-    default:
-        throw KeychainError.fromStatus(status)
-    }
+    var insert = match
+    insert[kSecValueData as String] = token
+    insert[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+    let added = SecItemAdd(insert as CFDictionary, nil)
+    if added == errSecSuccess { return }
+    guard added == errSecDuplicateItem else { throw KeychainError(status: added) }
+    let changed = SecItemUpdate(match as CFDictionary,
+                                [kSecValueData as String: token] as CFDictionary)
+    guard changed == errSecSuccess else { throw KeychainError(status: changed) }
 }
 ```
 
-### Accessing a `WhenUnlocked` item from a background extension
+### What goes wrong in an extension
 
 ```swift
-// Runs in WidgetKit TimelineProvider or NotificationServiceExtension while locked  -  WILL fail
-func fetchTokenInBackground() -> String? {
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: "authToken",
-        kSecAttrService as String: "com.example.app",
-        kSecReturnData as String: true,
-        kSecMatchLimit as String: kSecMatchLimitOne
-        // Item stored with default WhenUnlocked  -  inaccessible while locked
-    ]
-
-    var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-    // status == errSecInteractionNotAllowed (-25308) when device is locked
-    guard status == errSecSuccess, let data = result as? Data else {
-        return nil // ❌ Silent failure  -  no logging, no error propagation
-    }
-    return String(data: data, encoding: .utf8)
+// Wrong: the item was stored with the default WhenUnlocked class. A widget or
+// notification service extension running while the phone is locked gets -25308,
+// and this code turns that into a silent nil with no log.
+func tokenForWidget() -> Data? {
+    var out: CFTypeRef?
+    let q: [String: Any] = [kSecClass as String: kSecClassGenericPassword,
+                            kSecAttrAccount as String: "widget-token",
+                            kSecReturnData as String: true]
+    guard SecItemCopyMatching(q as CFDictionary, &out) == errSecSuccess else { return nil }
+    return out as? Data
 }
 ```
 
----
-
-## macOS: `kSecUseDataProtectionKeychain`
+## macOS: kSecUseDataProtectionKeychain
 
-macOS has **two keychain implementations** (per TN3137): the legacy file-based keychain (`~/Library/Keychains/login.keychain-db`) and the modern Data Protection keychain. The `SecItem` API defaults to the **legacy** keychain on macOS.
+Unless told otherwise, SecItem on macOS works on the legacy file-based keychain
+at `~/Library/Keychains/login.keychain-db`. Without
+`kSecUseDataProtectionKeychain: true`:
 
-Set `kSecUseDataProtectionKeychain: true` in every macOS keychain query to target the modern keychain. Without it:
-
-- `SecAccessControl` flags fail with `errSecParam` (-50)
-- iCloud Keychain sync doesn't work
-- Secure Enclave integration is unavailable
-- Biometric protection (Touch ID) won't function
+- `SecAccessControl` fails with `errSecParam`;
+- iCloud Keychain sync is unavailable;
+- Secure Enclave keys cannot be stored;
+- Touch ID protection does not apply.
 
 ```swift
-// ✅ macOS: always include kSecUseDataProtectionKeychain
-let query: [String: Any] = [
+let macEntry: [String: Any] = [
     kSecClass as String: kSecClassGenericPassword,
-    kSecAttrAccount as String: account,
-    kSecAttrService as String: service,
-    kSecUseDataProtectionKeychain as String: true, // ← Critical on macOS
-    kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
-    kSecValueData as String: data
+    kSecAttrService as String: "com.example.mac-notes",
+    kSecAttrAccount as String: "sync",
+    kSecValueData as String: Data("v".utf8),
+    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+    kSecUseDataProtectionKeychain as String: true
 ]
 ```
 
-On iOS, tvOS, and watchOS, this flag is ignored (those platforms always use Data Protection). The Data Protection keychain requires a user login context  -  `launchd` daemons running outside a user session must use the legacy keychain. Mac Catalyst and iOS-on-Mac apps automatically use Data Protection.
-
----
-
-## NSFileProtection Sidebar
-
-The keychain and file system share the same Data Protection architecture but expose it through different APIs. Use the keychain for small discrete secrets (passwords, tokens, keys). Use `NSFileProtection` for larger data (documents, databases, images).
-
-**`NSFileProtectionComplete`** (Class A) = `kSecAttrAccessibleWhenUnlocked`. File inaccessible while locked. Class key discarded ~10 seconds after lock.
-
-**`NSFileProtectionCompleteUnlessOpen`** (Class B) = **No keychain equivalent.** Uses asymmetric ECDH (Curve25519) to allow already-opened files to continue being written while locked. Designed for background downloads (e.g., mail attachment download continues writing to an already-open file).
-
-**`NSFileProtectionCompleteUntilFirstUserAuthentication`** (Class C) = `kSecAttrAccessibleAfterFirstUnlock`. The default for third-party app files when no explicit protection is set. Available after first unlock.
-
-**`NSFileProtectionNone`** (Class D) = deprecated `kSecAttrAccessibleAlways`. Protected only by device UID.
-
-**Recommended layered approach:** Store encryption keys in the keychain with `WhenUnlockedThisDeviceOnly`, then use those keys to encrypt larger files on disk with `NSFileProtectionComplete` as an additional layer.
-
----
-
-## Error Codes Reference
-
-| Code       | Constant                      | Meaning                              | Common Root Cause                                                                                                                                   |
-| ---------- | ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **-25308** | `errSecInteractionNotAllowed` | Item not accessible in current state | Device locked + `WhenUnlocked` item; BFU state + `AfterFirstUnlock` item; biometric flag in background                                              |
-| **-50**    | `errSecParam`                 | Invalid parameters                   | Both `kSecAttrAccessible` and `kSecAttrAccessControl` set; conflicting flags without `.or`/`.and`; missing `kSecUseDataProtectionKeychain` on macOS |
-| **-25293** | `errSecAuthFailed`            | Authentication failed                | Biometric auth failed; enrollment changed with `.biometryCurrentSet`; no biometrics enrolled                                                        |
-| **-25300** | `errSecItemNotFound`          | Item not in keychain                 | Item never stored; `ThisDeviceOnly` lost after migration; `WhenPasscodeSet` deleted on passcode removal                                             |
-| **-25299** | `errSecDuplicateItem`         | Item already exists                  | `SecItemAdd` when matching primary keys exist  -  use add-or-update pattern                                                                           |
-| **-128**   | `errSecUserCanceled`          | User canceled prompt                 | User tapped Cancel on biometric/passcode dialog                                                                                                     |
-| **-34018** | `errSecMissingEntitlement`    | Missing entitlement                  | Keychain access group not in entitlements; common on iOS Simulator                                                                                  |
-
-The most insidious is `-25308`  -  it surfaces in production but rarely during development because developers test with unlocked devices. Always handle it by deferring the operation and retrying when `UIApplication.shared.isProtectedDataAvailable` is `true`.
-
----
-
-## iOS Version Timeline
-
-**iOS 8 (2014):** `WhenPasscodeSetThisDeviceOnly` introduced. `SecAccessControlCreateWithFlags` added. `.userPresence` flag.
-
-**iOS 9 (2015):** `.devicePasscode`, `.applicationPassword`, `.privateKeyUsage` flags added. Apple announced intent to deprecate `Always` at WWDC 2015 Session 706.
-
-**iOS 11.3 (2018):** `.touchIDAny` → `.biometryAny`; `.touchIDCurrentSet` → `.biometryCurrentSet` (unified naming for Face ID).
-
-**iOS 12 (2018):** `kSecAttrAccessibleAlways` and `AlwaysThisDeviceOnly` formally deprecated. Both still compile and run for backward compatibility.
-
-**iOS 15 (2021):** MDM-installed keychain items changed default from "always" to "after first unlock, nonmigratory." App pre-warming can launch processes before first unlock, making `AfterFirstUnlock` items temporarily unavailable.
-
-**iOS 16 (2022):** Passkeys launched (FIDO2/WebAuthn key pairs synced via E2E encrypted iCloud Keychain). No changes to access control APIs.
-
-**iOS 17 (2023):** Enterprise passkey support. No `kSecAttrAccessible` or `SecAccessControl` changes.
-
-**iOS 18 (2024):** Standalone Passwords app. No keychain data protection API changes.
-
-**iOS 26 (2025):** Stolen Device Protection enabled by default  -  requires biometric auth (no passcode fallback) for stored passwords when away from familiar locations. Secure passkey import/export via FIDO Alliance standard. No changes to `kSecAttrAccessible` constants.
-
----
-
-## Testing Requirements
-
-All data protection testing **must** use physical devices with passcodes enabled. The iOS Simulator does not enforce `kSecAttrAccessible` or `NSFileProtection`, creating a false sense of security.
-
-**Critical test scenarios:**
-
-1. **Reboot / BFU state:** Reboot device, attempt keychain access before unlocking. `AfterFirstUnlock` items should return `-25308` or `-25300`. Unlock once, lock again, test background access  -  should succeed.
-
-2. **Lock timing:** Store a `WhenUnlocked` item. Lock the device. Attempt read immediately  -  expect `-25308`.
-
-3. **Passcode removal:** Store a `WhenPasscodeSetThisDeviceOnly` item. Remove passcode in Settings. Verify item is deleted (`-25300`).
-
-4. **Biometric enrollment change:** Store an item with `.biometryCurrentSet`. Add a new fingerprint or Face ID appearance. Verify authentication fails (`-25293`).
-
-5. **Backup/restore migration:** Back up device, restore to a different physical device. Verify all `ThisDeviceOnly` items are absent (`-25300`).
-
-6. **Background extension access:** Trigger a notification service extension or widget timeline update while the device is locked. Verify `AfterFirstUnlock` items are readable and `WhenUnlocked` items are not.
-
----
-
-## Cross-References
-
-- `keychain-fundamentals.md`  -  SecItem CRUD patterns, add-or-update, OSStatus handling
-- `biometric-authentication.md`  -  Biometric flag selection (`.biometryCurrentSet`, `.biometryAny`, `.userPresence`) and keychain-bound patterns
-- `secure-enclave.md`  -  Hardware-backed keys with `SecAccessControl` and `.privateKeyUsage`
-- `keychain-item-classes.md`  -  Class-specific accessibility considerations and primary key composition
-- `common-anti-patterns.md`  -  Anti-pattern #5 (missing `kSecAttrAccessible`), #3 (LAContext-only gate)
-- `compliance-owasp-mapping.md`  -  M9 (Insecure Data Storage) accessibility requirements
-
----
-
-## Summary Checklist
-
-1. **Always set `kSecAttrAccessible` explicitly**  -  never rely on the `WhenUnlocked` default; choose the level matching your access context (foreground vs background)
-2. **Never set both `kSecAttrAccessible` and `kSecAttrAccessControl`** in the same query dictionary  -  accessibility belongs inside `SecAccessControlCreateWithFlags`
-3. **Use `AfterFirstUnlockThisDeviceOnly`** for any item accessed by background extensions, widgets, VPN, or push notification handlers
-4. **Pair `WhenPasscodeSetThisDeviceOnly` with `.biometryCurrentSet`** for highest-security items, and handle item deletion on passcode removal gracefully
-5. **Include `.or` or `.and`** when combining multiple authentication flags  -  omitting the operator causes `errSecParam` (-50)
-6. **Set `kSecUseDataProtectionKeychain: true`** on all macOS keychain queries to target the modern Data Protection keychain
-7. **Implement re-authentication flows** for `ThisDeviceOnly` items that will be absent after device migration or backup restore
-8. **Check `isProtectedDataAvailable`** before keychain access in app launch paths  -  iOS 15+ pre-warming can start your process before first unlock
-9. **Delete and re-add** (not update) when changing `SecAccessControl` on an existing item  -  `SecItemUpdate` cannot modify access control attributes
-10. **Test on physical devices** across lock/unlock, reboot, passcode removal, and biometric enrollment change scenarios  -  the Simulator does not enforce data protection
-11. **Block deprecated `kSecAttrAccessibleAlways` constants** in CI/CD linting and migrate existing items to `AfterFirstUnlock` on next foreground authentication
+iOS, tvOS and watchOS ignore the flag. The data protection keychain needs a
+logged-in user context, so a `launchd` daemon running outside any user session
+has to use the legacy keychain.
+
+## File Protection Sidebar
+
+The keychain is for small, discrete secrets. Documents, databases and images
+use `NSFileProtection` instead.
+
+| File class | Keychain counterpart | Behaviour |
+| --- | --- | --- |
+| A: `NSFileProtectionComplete` | `WhenUnlocked` | key discarded about ten seconds after lock |
+| B: `NSFileProtectionCompleteUnlessOpen` | none | uses Curve25519 key agreement so a file opened before lock can still be written while locked (for example an attachment downloading in the background) |
+| C: `NSFileProtectionCompleteUntilFirstUserAuthentication` | `AfterFirstUnlock` | the default for third-party app files |
+| D: `NSFileProtectionNone` | deprecated `Always` | UID protection only |
+
+For layered protection, keep an encryption key in the keychain as
+`WhenUnlockedThisDeviceOnly`, encrypt the file with it, and mark the file
+`NSFileProtectionComplete` as well.
+
+## Error Codes
+
+| Code | Name | Typical cause |
+| --- | --- | --- |
+| -25308 | `errSecInteractionNotAllowed` | a `WhenUnlocked` item read while locked; an `AfterFirstUnlock` item read before first unlock; a biometric flag used in the background |
+| -50 | `errSecParam` | both accessibility attributes present; flags without a combinator; access control on macOS without the data protection flag |
+| -25293 | `errSecAuthFailed` | biometric match failed; enrollment changed under `.biometryCurrentSet`; nothing enrolled |
+| -25300 | `errSecItemNotFound` | never stored; a `ThisDeviceOnly` item lost in migration; a `WhenPasscodeSet` item deleted with the passcode |
+| -25299 | `errSecDuplicateItem` | save with add-or-update |
+| -128 | `errSecUserCanceled` | the user tapped Cancel on the prompt |
+| -34018 | `errSecMissingEntitlement` | the access group is not in the entitlements; frequent in the Simulator |
+
+-25308 is the hardest of these to catch: it happens in production and rarely on
+a developer's unlocked phone. Postpone the work and retry once
+`isProtectedDataAvailable` is `true`.
+
+## Version Timeline
+
+| Release | Change |
+| --- | --- |
+| iOS 8 | `WhenPasscodeSetThisDeviceOnly`, `SecAccessControlCreateWithFlags`, `.userPresence` |
+| iOS 9 | `.devicePasscode`, `.applicationPassword`, `.privateKeyUsage`; plan to retire `Always` announced (WWDC 2015 Session 706) |
+| iOS 11.3 | Touch ID flag names replaced by biometry names |
+| iOS 12 | both `Always` constants deprecated; they still compile and run |
+| iOS 15 | keychain items installed by MDM default to after-first-unlock and non-migratory instead of always; pre-warming can run the app before first unlock |
+| iOS 16 | passkeys (FIDO2 / WebAuthn, synced end to end encrypted through iCloud Keychain); no access control API change |
+| iOS 17 | passkeys for managed Apple Accounts; no change to accessibility or `SecAccessControl` |
+| iOS 18 | the standalone Passwords app; no data protection API change |
+| iOS 26 | Stolen Device Protection on by default (biometrics without passcode fallback for saved passwords away from familiar places; confirm against current release notes); passkey import and export using the FIDO Alliance format; no new accessibility constants |
+
+## Testing
+
+The Simulator enforces neither `kSecAttrAccessible` nor `NSFileProtection`.
+Data protection behaviour can only be tested on a physical device with a
+passcode set.
+
+| Scenario | Expected |
+| --- | --- |
+| Reboot, then read an `AfterFirstUnlock` item before unlocking | -25308 or -25300; after one unlock and a relock, a background read succeeds |
+| Lock, then immediately read a `WhenUnlocked` item | -25308 |
+| Remove the passcode | `WhenPasscodeSet` item gone (-25300) |
+| Enroll a new finger or face | `.biometryCurrentSet` item fails (-25293) |
+| Restore a backup onto another device | `ThisDeviceOnly` items absent (-25300) |
+| Notification extension or widget while locked | `AfterFirstUnlock` readable, `WhenUnlocked` not |
+
+More on test structure: [testing-security-code.md](testing-security-code.md).
+
+## Checklist
+
+- Every add states its accessibility, chosen for foreground or background use.
+- Never both attributes; with access control, the accessibility goes inside it.
+- Extensions, widgets, VPN code and push handlers read
+  `AfterFirstUnlockThisDeviceOnly` items.
+- Top secrets use `WhenPasscodeSetThisDeviceOnly` with `.biometryCurrentSet`,
+  and the app handles deletion when the passcode is removed.
+- Multiple authentication flags are joined by `.or` or `.and`.
+- macOS queries all set `kSecUseDataProtectionKeychain: true`.
+- `ThisDeviceOnly` items have a re-authentication path after migration or
+  restore.
+- Launch paths check `isProtectedDataAvailable` (iOS 15 pre-warming).
+- Saves are add, then update; only an access-control change deletes and
+  re-adds.
+- Biometric flags come with `NSFaceIDUsageDescription` in `Info.plist`.
+- Lock, reboot, passcode removal and enrollment change are tested on hardware.
+- CI rejects the deprecated `Always` constants, and existing items move to
+  `AfterFirstUnlock` the next time the user authenticates in the foreground.
+
+## Related Files
+
+[keychain-fundamentals.md](keychain-fundamentals.md),
+[biometric-authentication.md](biometric-authentication.md),
+[secure-enclave.md](secure-enclave.md),
+[keychain-item-classes.md](keychain-item-classes.md),
+[common-anti-patterns.md](common-anti-patterns.md) (items on missing
+accessibility and on `LAContext`-only gates), and
+[compliance-owasp-mapping.md](compliance-owasp-mapping.md) (M9, insecure data
+storage).