@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/biometric-authentication.md

@@ -1,595 +1,440 @@
 # Biometric Authentication
 
-> **Domain scope:** SecAccessControl + LAContext integration, the LAContext-only bypass vulnerability, hardware-bound biometric gating, fallback behavior, UI customization, enrollment change detection, thread safety.
->
-> **Risk level:** CRITICAL  -  #1 most dangerous AI-generated pattern. `LAContext.evaluatePolicy()` used alone is trivially bypassable at runtime.
+Severity when violated: **CRITICAL.** Of all the insecure patterns that code
+generators produce, a lone `LAContext.evaluatePolicy()` call guarding sensitive
+content is the most dangerous, because it can be defeated at runtime without
+any exploit.
 
----
+Before any Face ID prompt can appear, the app's `Info.plist` needs
+`NSFaceIDUsageDescription` with a sentence explaining why the app uses Face ID.
+Apple's LocalAuthentication documentation notes that requests can fail without
+it. This applies equally to `evaluatePolicy` and to keychain reads that trigger
+Face ID through an access control. Touch ID needs no usage string.
 
 ## Contents
 
-- [The Boolean Gate Vulnerability](#the-boolean-gate-vulnerability)
-  - [The Dangerous Pattern  -  Boolean Gate](#the-dangerous-pattern-boolean-gate)
-  - [How Attackers Bypass It](#how-attackers-bypass-it)
-- [The Secure Pattern  -  Hardware-Bound Secrets](#the-secure-pattern-hardware-bound-secrets)
-  - [Step 1  -  Create the Access Control Object](#step-1-create-the-access-control-object)
-  - [Step 2  -  Store a Secret Bound to Biometric Auth](#step-2-store-a-secret-bound-to-biometric-auth)
-  - [Step 3  -  Retrieve the Secret (Biometric Prompt Appears Automatically)](#step-3-retrieve-the-secret-biometric-prompt-appears-automatically)
-- [`evaluatePolicy` vs `evaluateAccessControl`](#evaluatepolicy-vs-evaluateaccesscontrol)
-- [Biometric Flag Selection](#biometric-flag-selection)
-  - [`.biometryCurrentSet`  -  Banking, Payments, Credential Storage](#biometrycurrentset-banking-payments-credential-storage)
-  - [`.biometryAny`  -  Convenience Features, Moderate Sensitivity](#biometryany-convenience-features-moderate-sensitivity)
-  - [`.userPresence`  -  Maximum Device Compatibility](#userpresence-maximum-device-compatibility)
-  - [Combining Flags](#combining-flags)
-- [Biometric Availability Checks and Graceful Degradation](#biometric-availability-checks-and-graceful-degradation)
-  - [Incomplete Availability Check](#incomplete-availability-check)
-  - [Complete Availability Evaluation](#complete-availability-evaluation)
-  - [Graceful Degradation Flow](#graceful-degradation-flow)
-- [Enrollment Change Detection](#enrollment-change-detection)
-- [Thread Safety and async/await](#thread-safety-and-asyncawait)
-  - [Actor-Isolated Biometric Keychain (iOS 15+)](#actor-isolated-biometric-keychain-ios-15)
-  - [SwiftUI ViewModel Integration](#swiftui-viewmodel-integration)
-- [Secure Enclave-Backed Keys with Biometric Protection](#secure-enclave-backed-keys-with-biometric-protection)
-- [SDLC Controls  -  Catching the Anti-Pattern in CI](#sdlc-controls-catching-the-anti-pattern-in-ci)
-- [Dynamic Verification  -  Proving Bypass Resistance](#dynamic-verification-proving-bypass-resistance)
-- [Key References](#key-references)
-- [Cross-References](#cross-references)
-- [Summary Checklist](#summary-checklist)
-
-## The Boolean Gate Vulnerability
-
-The most dangerous pattern AI coding assistants generate for iOS biometric authentication is `LAContext.evaluatePolicy()` used as a standalone authentication gate. This pattern appears in virtually every tutorial, Stack Overflow answer, and AI training corpus  -  and it is **trivially bypassable**.
-
-The attack requires no exploit. An attacker uses Frida or objection to hook the Objective-C callback and force `success = true`, bypassing Face ID or Touch ID entirely. The formal weakness classification is CWE-288: Authentication Bypass Using an Alternate Path or Channel.
-
-OWASP MASTG explicitly fails any app relying solely on `evaluatePolicy` (test MASTG-TEST-0266, requirements MSTG-AUTH-8 and MSTG-AUTH-12). The standard states: biometric authentication must not be event-bound (returning `true`/`false`); it must be based on unlocking the keychain/keystore.
-
-### The Dangerous Pattern  -  Boolean Gate
+- [Why a Boolean Gate Fails](#why-a-boolean-gate-fails)
+- [The Secure Pattern: Let the Keychain Ask](#the-secure-pattern-let-the-keychain-ask)
+- [evaluatePolicy and evaluateAccessControl](#evaluatepolicy-and-evaluateaccesscontrol)
+- [Which Flag](#which-flag)
+- [Availability and Degradation](#availability-and-degradation)
+- [Detecting Enrollment Changes](#detecting-enrollment-changes)
+- [Threads and async/await](#threads-and-asyncawait)
+- [Secure Enclave Keys Behind Biometrics](#secure-enclave-keys-behind-biometrics)
+- [Controls in the Development Process](#controls-in-the-development-process)
+- [Verifying at Runtime](#verifying-at-runtime)
+- [Checklist](#checklist)
+- [Sources and Related Files](#sources-and-related-files)
+
+## Why a Boolean Gate Fails
+
+`evaluatePolicy` asks the system to authenticate the user and then calls your
+closure with `true` or `false`. The Secure Enclave did the matching correctly,
+but all your app receives is a Boolean in ordinary process memory, and nothing
+cryptographic depends on it.
 
 ```swift
-// ❌ DANGEROUS: Trivially bypassable with Frida  -  do NOT use for security
-import LocalAuthentication
-
-func authenticateUser() {
-    let context = LAContext()
-    var error: NSError?
-
-    if context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) {
-        context.evaluatePolicy(
-            .deviceOwnerAuthenticationWithBiometrics,
-            localizedReason: "Authenticate to access your account"
-        ) { success, authError in
-            DispatchQueue.main.async {
-                if success {
-                    self.isAuthenticated = true   // ← Just a boolean in hookable memory
-                    self.showProtectedContent()   // ← No secret unlocked, no key released
-                }
+// Wrong: the only barrier is a Bool the attacker can flip.
+@MainActor
+final class StatementsGate {
+    var unlocked = false
+    func unlock(show: @escaping @MainActor () -> Void) {
+        let ctx = LAContext()
+        var probe: NSError?
+        guard ctx.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &probe) else { return }
+        ctx.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics,
+                           localizedReason: "View statements") { @Sendable ok, _ in
+            Task { @MainActor in
+                self.unlocked = ok
+                if ok { show() }
             }
         }
     }
 }
 ```
 
-**Why this fails:** `evaluatePolicy()` asks the OS "did the user authenticate?" and receives a boolean answer in user-space. No cryptographic material is involved. No secret is decrypted. The entire security model rests on a boolean that exists in hookable memory.
-
-### How Attackers Bypass It
-
-The objection tool (built on Frida) provides a one-command bypass:
-
-```bash
-objection -g "com.example.targetapp" explore
-ios ui biometrics_bypass
-```
-
-The hook listens for invocations of `-[LAContext evaluatePolicy:localizedReason:reply:]`, intercepts the reply block, and replaces the `success` boolean with `true`. The equivalent raw Frida script:
-
-```javascript
-// Frida script  -  forces evaluatePolicy success = true
-if (ObjC.available) {
-  var hook = ObjC.classes.LAContext["- evaluatePolicy:localizedReason:reply:"];
-  Interceptor.attach(hook.implementation, {
-    onEnter: function (args) {
-      var block = new ObjC.Block(args[4]);
-      const callback = block.implementation;
-      block.implementation = function (error, value) {
-        const result = callback(1, null); // 1 = true, null = no error
-        return result;
-      };
-    },
-  });
-}
-```
-
-The objection wiki confirms the attack boundary: this bypass **does not work** against keychain items protected with access control flags like `.biometryCurrentSet` or `.biometryAny`. That boundary is the entire basis of the secure pattern.
-
-✅ Correct pattern in this threat model: use biometrics only to unlock keychain-protected secrets (`SecAccessControl` + `SecItemCopyMatching`), never as a standalone boolean gate.
+On a jailbroken or instrumented device:
 
----
+- objection, a Frida-based toolkit, does it in two commands: attach with
+  `objection -g "<bundle id>" explore`, then run `ios ui biometrics_bypass`.
+- A hand-written Frida script hooks
+  `-[LAContext evaluatePolicy:localizedReason:reply:]`, swaps the reply block
+  (argument index 4 counting `self` and `_cmd`) for one that reports success
+  with a nil error, and the app proceeds.
 
-## The Secure Pattern  -  Hardware-Bound Secrets
+This weakness is CWE-288, Authentication Bypass Using an Alternate Path or
+Channel. OWASP MASTG fails apps whose only protection is `evaluatePolicy`
+(test MASTG-TEST-0266; requirements MSTG-AUTH-8 and MSTG-AUTH-12): biometrics
+must unlock something in the keychain, not flip an event-driven true or false.
 
-The correct architecture stores a secret in the iOS keychain with biometric access control. The secret's encryption key is held by the Secure Enclave  -  a dedicated processor running its own microkernel (sepOS), with its own encrypted memory, completely isolated from the application processor.
+The objection documentation states that its bypass does not work against
+keychain items protected with `.biometryCurrentSet` or `.biometryAny`. That
+limitation is exactly the defence.
 
-When the app requests the secret, the Secure Enclave independently verifies the biometric match and only then releases the decryption key. There is no boolean to hook. The data physically cannot be read without valid biometric authentication.
+## The Secure Pattern: Let the Keychain Ask
 
-WWDC 2014 Session 711 ("Keychain and Authentication with Touch ID") drew the critical distinction:
+Store the secret as a keychain item with a biometric access control. The
+item's key is held by the Secure Enclave, which runs its own microkernel
+(sepOS) and has its own encrypted memory. The enclave checks the biometric
+match itself and releases the decryption key only on success, so there is no
+Boolean in the app's process to patch.
 
-- **`evaluatePolicy`**: "Trust the OS"  -  vulnerable if runtime is compromised
-- **Keychain + SecAccessControl**: "Trust the Secure Enclave"  -  ACLs evaluated inside hardware
+WWDC 2014 Session 711 frames the difference as trusting the OS (the
+`evaluatePolicy` result) versus trusting the Secure Enclave (a keychain ACL
+evaluated in hardware).
 
-### Step 1  -  Create the Access Control Object
+### Step 1: an access control
 
 ```swift
 import LocalAuthentication
 import Security
 
-enum BiometricKeychainError: Error {
-    case accessControlCreationFailed
-    case keychainOperationFailed(status: OSStatus)
-    case dataConversionFailed
-    case biometryNotAvailable(reason: String)
+enum BioVaultError: Error {
+    case policyCreation(Error?)
+    case keychain(OSStatus)
+    case badData
+    case biometryUnavailable(LAError.Code?)
 }
 
-func createBiometricAccessControl() throws -> SecAccessControl {
-    var error: Unmanaged<CFError>?
-    guard let accessControl = SecAccessControlCreateWithFlags(
+func makeBiometricPolicy() throws -> SecAccessControl {
+    var cfError: Unmanaged<CFError>?
+    guard let acl = SecAccessControlCreateWithFlags(
         kCFAllocatorDefault,
-        kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,  // Strongest: requires passcode, device-only
-        .biometryCurrentSet,                               // Invalidates on enrollment change
-        &error
-    ) else {
-        throw BiometricKeychainError.accessControlCreationFailed
+        kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
+        .biometryCurrentSet,
+        &cfError) else {
+        throw BioVaultError.policyCreation(cfError?.takeRetainedValue())
     }
-    return accessControl
+    return acl
 }
 ```
 
-### Step 2  -  Store a Secret Bound to Biometric Auth
+### Step 2: store it
 
-```swift
-// ✅ SECURE: Secret is encrypted by Secure Enclave, released only on biometric match
-func storeSecretWithBiometric(secret: Data, account: String, service: String) throws {
-    let accessControl = try createBiometricAccessControl()
-
-    // Delete any existing item first (add-or-update pattern)
-    let deleteQuery: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: service
-    ]
-    SecItemDelete(deleteQuery as CFDictionary)
+Save with add, then update on duplicate. The update of a protected item needs
+the user to authenticate, so it runs with an `LAContext`. Changing the policy
+of an existing item (for example from `.biometryAny` to
+`.biometryCurrentSet`) is the one case for delete and re-add, because
+`SecItemUpdate` cannot alter access control; see
+[keychain-access-control.md](keychain-access-control.md).
 
-    let addQuery: [String: Any] = [
+```swift
+func storeAccountNumber(_ digits: Data, context: LAContext) throws {
+    let match: [String: Any] = [
         kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: service,
-        kSecValueData as String: secret,
-        kSecAttrAccessControl as String: accessControl,
-        kSecAttrSynchronizable as String: kCFBooleanFalse  // Never sync biometric-gated secrets
-        // NOTE: Do NOT set kSecAttrAccessible  -  it conflicts with kSecAttrAccessControl
+        kSecAttrService as String: "com.example.bank",
+        kSecAttrAccount as String: "account-number",
+        kSecAttrSynchronizable as String: kCFBooleanFalse as Any
     ]
-
-    let status = SecItemAdd(addQuery as CFDictionary, nil)
-    guard status == errSecSuccess else {
-        throw BiometricKeychainError.keychainOperationFailed(status: status)
-    }
+    var insert = match
+    insert[kSecAttrAccessControl as String] = try makeBiometricPolicy()
+    insert[kSecValueData as String] = digits
+
+    let added = SecItemAdd(insert as CFDictionary, nil)
+    if added == errSecSuccess { return }
+    guard added == errSecDuplicateItem else { throw BioVaultError.keychain(added) }
+
+    var existing = match
+    existing[kSecUseAuthenticationContext as String] = context
+    let changed = SecItemUpdate(existing as CFDictionary,
+                                [kSecValueData as String: digits] as CFDictionary)
+    guard changed == errSecSuccess else { throw BioVaultError.keychain(changed) }
 }
 ```
 
-**Critical detail:** Do NOT set both `kSecAttrAccessible` and `kSecAttrAccessControl` in the same query. They conflict  -  `SecAccessControl` already encodes the accessibility level. Setting both causes `errSecParam`.
+- The dictionary has `kSecAttrAccessControl` and no `kSecAttrAccessible`;
+  both together are `errSecParam`.
+- Biometric-protected secrets use a `ThisDeviceOnly` class and are never
+  synchronizable. Syncing would put the secret on devices whose biometrics the
+  policy never saw.
 
-**Critical detail:** Always use `ThisDeviceOnly` accessibility for biometric-gated secrets. The `ThisDeviceOnly` suffix ensures the secret is hardware-bound and excluded from iCloud backups. Syncing biometric-gated secrets across devices expands the attack surface.
-
-### Step 3  -  Retrieve the Secret (Biometric Prompt Appears Automatically)
+### Step 3: read it
 
 ```swift
-// ✅ SECURE: System presents biometric prompt; Secure Enclave gates decryption
-func retrieveSecretWithBiometric(account: String, service: String) throws -> Data {
-    let context = LAContext()
-    context.localizedReason = "Authenticate to access your credentials"
-
+func readAccountNumber() throws -> Data {
+    let ctx = LAContext()
+    ctx.localizedReason = "Show your account number"
     let query: [String: Any] = [
         kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: service,
+        kSecAttrService as String: "com.example.bank",
+        kSecAttrAccount as String: "account-number",
         kSecReturnData as String: true,
         kSecMatchLimit as String: kSecMatchLimitOne,
-        kSecUseAuthenticationContext as String: context
+        kSecUseAuthenticationContext as String: ctx
     ]
-
-    var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-
+    var out: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &out)
     switch status {
     case errSecSuccess:
-        guard let data = result as? Data else {
-            throw BiometricKeychainError.dataConversionFailed
-        }
-        return data  // Secret returned ONLY after Secure Enclave validates biometric
+        guard let digits = out as? Data else { throw BioVaultError.badData }
+        return digits
     case errSecItemNotFound:
-        throw BiometricKeychainError.keychainOperationFailed(status: status)
+        throw BioVaultError.keychain(status)
     case errSecUserCanceled:
-        throw BiometricKeychainError.keychainOperationFailed(status: status)
+        throw BioVaultError.keychain(status)
     case errSecAuthFailed:
-        throw BiometricKeychainError.keychainOperationFailed(status: status)
+        throw BioVaultError.keychain(status)
     default:
-        throw BiometricKeychainError.keychainOperationFailed(status: status)
+        throw BioVaultError.keychain(status)
     }
 }
 ```
 
-**Key insight:** Authentication and data protection are the same operation, not sequential ones. When `SecItemCopyMatching` encounters an item with biometric access control, the system presents the biometric prompt automatically. The Secure Enclave verifies the match internally and only then unwraps the AES-256-GCM decryption key. There is no callback to intercept.
-
----
-
-## `evaluatePolicy` vs `evaluateAccessControl`
-
-These two `LAContext` methods represent the two trust models from WWDC 2014 Session 711:
-
-**`evaluatePolicy(_:localizedReason:reply:)`** triggers biometric authentication and returns a boolean. The Secure Enclave validates the biometric correctly, but the result is communicated to user-space as `true`/`false`. No key is released. The app branches on a boolean in hookable memory. This is "trust the OS."
-
-**`evaluateAccessControl(_:operation:localizedReason:reply:)`** evaluates a `SecAccessControl` object for a specific cryptographic operation (`.useItem`, `.useKeySign`, `.useKeyDecrypt`). When used with keychain items, the authenticated `LAContext` is passed to `SecItemCopyMatching` via `kSecUseAuthenticationContext`, and the Secure Enclave recognizes the prior authentication. This is "trust the Secure Enclave."
-
-**In practice, you rarely call `evaluateAccessControl` directly.** The recommended flow: store data with `SecAccessControl` via `SecItemAdd`, then retrieve with `SecItemCopyMatching`. The system handles the biometric prompt automatically when the query encounters an ACL-protected item.
-
-The only legitimate use of `evaluatePolicy` is **non-security-critical UI gating**  -  deciding whether to show a "Sign in with Face ID" button. It must never protect sensitive data or gate access to secrets.
-
----
-
-## Biometric Flag Selection
-
-`SecAccessControlCreateFlags` provides three biometric-related flags. Choosing the wrong one is a common mistake even in otherwise-correct implementations.
-
-### `.biometryCurrentSet`  -  Banking, Payments, Credential Storage
-
-Ties the keychain item to the **exact biometric enrollment** at time of storage. If the user adds a fingerprint, re-enrolls Face ID, or removes a biometric entry, the item becomes **permanently inaccessible**.
-
-```swift
-// ✅ Strongest biometric binding  -  invalidates on enrollment change
-let access = SecAccessControlCreateWithFlags(
-    nil, kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
-    .biometryCurrentSet, nil
-)
-```
-
-**Tradeoff:** Users who change biometrics must re-authenticate via your app's password flow. Detect enrollment changes via `LAContext.evaluatedPolicyDomainState` (see Enrollment Change Detection below) and present graceful re-enrollment.
+`errSecUserCanceled` is -128 (the user backed out). `errSecAuthFailed` is -25293
+(the match failed, or the enrollment behind a `.biometryCurrentSet` item
+changed). Authentication and decryption are a single operation: the query
+itself raises the system prompt, the enclave unwraps the item's AES-256-GCM
+key, and there is no callback to intercept.
 
-### `.biometryAny`  -  Convenience Features, Moderate Sensitivity
+## evaluatePolicy and evaluateAccessControl
 
-Survives biometric enrollment changes. An attacker who enrolls their own biometrics on a compromised device can access the data.
+- `evaluatePolicy(_:localizedReason:reply:)`: the enclave checks the user, but
+  only a Boolean reaches your process. No key is released.
+- `evaluateAccessControl(_:operation:localizedReason:reply:)`: checks a
+  `SecAccessControl` for a given operation (`.useItem`, `.useKeySign`,
+  `.useKeyDecrypt`). You then pass the same context to `SecItemCopyMatching`
+  through `kSecUseAuthenticationContext`, and the enclave accepts the earlier
+  authentication.
 
-```swift
-// Survives re-enrollment  -  better UX, weaker security
-let access = SecAccessControlCreateWithFlags(
-    nil, kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
-    .biometryAny, nil
-)
-```
+You rarely need `evaluateAccessControl` directly. Store with an ACL through
+`SecItemAdd`, read with `SecItemCopyMatching`, and let the system prompt.
 
-**Use case:** "Remember me" features, non-critical app locks, preferences that benefit from biometric convenience without protecting financial data.
+`evaluatePolicy` still has one legitimate use: UI decisions that carry no
+security weight, such as whether to show an "Unlock with Face ID" button.
 
-### `.userPresence`  -  Maximum Device Compatibility
+## Which Flag
 
-Allows passcode fallback when biometrics are unavailable. Weaker because passcodes are susceptible to shoulder-surfing.
-
-```swift
-// Broadest compatibility  -  biometric or passcode
-let access = SecAccessControlCreateWithFlags(
-    nil, kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
-    .userPresence, nil
-)
-```
+| Flag | Behaviour | Fits | Pair with |
+| --- | --- | --- | --- |
+| `.biometryCurrentSet` | tied to the exact enrollment; adding a finger, re-enrolling Face ID or removing an entry makes the item unreadable forever | banking, payments, stored credentials | `WhenPasscodeSetThisDeviceOnly` |
+| `.biometryAny` | survives enrollment changes, so someone who enrols their own biometrics on a compromised device gets in | "remember me", non-critical app locks, preferences | `WhenUnlockedThisDeviceOnly` |
+| `.userPresence` | biometrics or passcode; the passcode can be shoulder-surfed | accessibility-first apps, devices without biometrics, degradation path | `WhenPasscodeSetThisDeviceOnly` |
 
-**Use case:** Accessibility-first apps, devices without biometric hardware, or as a `.biometryCurrentSet` degradation path.
+With `.biometryCurrentSet`, users who change their biometrics must re-verify
+through the app's own sign-in. Detect the change with
+`LAContext.evaluatedPolicyDomainState` (below).
 
-### Combining Flags
+For most production apps, `[.biometryCurrentSet, .or, .devicePasscode]` with
+`WhenPasscodeSetThisDeviceOnly` gives tight binding and still leaves a way in
+when Face ID fails.
 
-Flags can be combined with `.or` and `.and` conjunctions:
+## Availability and Degradation
 
 ```swift
-// ✅ Strong biometric binding WITH passcode escape hatch
-let access = SecAccessControlCreateWithFlags(
-    nil, kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
-    [.biometryCurrentSet, .or, .devicePasscode], nil
-)
-```
-
-This combination is practical for most production apps  -  strong biometric security with a recovery path when biometrics become unavailable.
-
----
-
-## Biometric Availability Checks and Graceful Degradation
-
-### Incomplete Availability Check
-
-```swift
-// ❌ WRONG: Ignores WHY biometrics failed  -  user gets no guidance
-func checkBiometrics() -> Bool {
-    let context = LAContext()
-    var error: NSError?
-    return context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error)
+// Wrong: a bare Bool hides why biometrics are unavailable.
+func biometricsReady() -> Bool {
+    LAContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)
 }
 ```
 
-### Complete Availability Evaluation
-
 ```swift
-// ✅ CORRECT: Evaluates every failure reason with actionable guidance
-enum BiometricAvailability {
-    case available(type: LABiometryType)
-    case notEnrolled          // Hardware exists, no biometrics registered
-    case lockedOut            // Too many failed attempts  -  passcode required
-    case notAvailable         // No hardware or restricted by MDM
-    case passcodeNotSet       // No device passcode  -  biometrics require one
+enum BiometricState {
+    case ready(LABiometryType)
+    case notEnrolled
+    case lockedOut
+    case unsupported
+    case noPasscode
 }
 
-func evaluateBiometricAvailability() -> BiometricAvailability {
-    let context = LAContext()
-    var error: NSError?
-
-    if context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) {
-        return .available(type: context.biometryType)
+func biometricState() -> BiometricState {
+    let ctx = LAContext()
+    var nsError: NSError?
+    if ctx.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &nsError) {
+        return .ready(ctx.biometryType)
     }
-
-    guard let laError = error as? LAError else { return .notAvailable }
-
-    switch laError.code {
-    case .biometryNotEnrolled:
-        return .notEnrolled     // → "Enable Face ID in Settings"
-    case .biometryLockout:
-        return .lockedOut       // → Prompt passcode to reset sensor
-    case .biometryNotAvailable:
-        return .notAvailable    // → Hide biometric UI entirely
-    case .passcodeNotSet:
-        return .passcodeNotSet  // → "Set a passcode to use Face ID"
-    default:
-        return .notAvailable
+    switch LAError.Code(rawValue: nsError?.code ?? 0) {
+    case .biometryNotEnrolled: return .notEnrolled
+    case .biometryLockout: return .lockedOut
+    case .passcodeNotSet: return .noPasscode
+    default: return .unsupported
     }
 }
 ```
 
-### Graceful Degradation Flow
+| State | What to do |
+| --- | --- |
+| `.biometryNotEnrolled` | explain how to turn on Face ID or Touch ID in Settings |
+| `.biometryLockout` | too many failures; entering the device passcode resets the sensor |
+| `.biometryNotAvailable` | no hardware, or restricted by MDM; hide biometric UI |
+| `.passcodeNotSet` | ask the user to set a passcode |
+| ready | `context.biometryType` (`LABiometryType`) says Face ID, Touch ID or Optic ID |
 
-```swift
-// ✅ Degrades from biometric → passcode → password login
-func authenticateWithGracefulDegradation() async throws -> Data {
-    let availability = evaluateBiometricAvailability()
-
-    switch availability {
-    case .available:
-        return try retrieveSecretWithBiometric(account: "user", service: "com.app.auth")
-
-    case .lockedOut:
-        // Biometrics locked  -  use .userPresence item for passcode fallback
-        return try retrieveSecretWithPasscodeFallback(account: "user", service: "com.app.auth")
-
-    case .notEnrolled:
-        throw BiometricKeychainError.biometryNotAvailable(
-            reason: "Please enable Face ID in Settings > Face ID & Passcode"
-        )
-
-    case .notAvailable, .passcodeNotSet:
-        throw BiometricKeychainError.biometryNotAvailable(
-            reason: "Biometric authentication is not available on this device"
-        )
-    }
-}
-```
-
-**Critical:** Failing to handle `.biometryLockout` strands users. The app cannot bypass this lockout  -  the user must successfully enter their device passcode to re-enable the biometric sensor. If your app has no fallback, users are permanently locked out until they leave your app and unlock with passcode.
+A degradation flow reads the biometric item when biometrics are ready, falls
+back to an item protected with `.userPresence` when the sensor is locked out
+(so the passcode works), and otherwise throws an error carrying guidance for the
+user. An unhandled `.biometryLockout` strands users: the app cannot clear a
+lockout, and only a successful passcode entry on the device does.
 
-**Important:** `canEvaluatePolicy()` is strictly for pre-flight UI decisions (showing or hiding a "Sign in with Face ID" button). It must never be used as a security control.
+`canEvaluatePolicy()` is for deciding what UI to show. It is never a security
+control.
 
----
-
-## Enrollment Change Detection
-
-When using `.biometryCurrentSet`, detect enrollment changes proactively so your app can guide the user through re-enrollment rather than presenting a cryptic keychain error.
+## Detecting Enrollment Changes
 
 ```swift
-// ✅ Detect biometric enrollment changes via domainState
-class BiometricEnrollmentMonitor {
-    private let domainStateKey = "com.app.biometric.domainState"
-
-    /// Call after successful biometric setup to snapshot current enrollment
-    func saveCurrentEnrollment() {
-        let context = LAContext()
-        guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil) else { return }
-
-        // domainState changes whenever biometric enrollment changes
-        if let domainState = context.evaluatedPolicyDomainState {
-            UserDefaults.standard.set(domainState, forKey: domainStateKey)
+struct EnrollmentWatcher {
+    private let storeKey = "bio.domainState"
+
+    private func currentState() -> Data? {
+        let ctx = LAContext()
+        guard ctx.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil) else { return nil }
+        if #available(iOS 18.0, macOS 15.0, *) {
+            return ctx.domainState.biometry.stateHash
         }
+        return ctx.evaluatedPolicyDomainState
     }
 
-    /// Call on app launch or before biometric retrieval
-    func hasEnrollmentChanged() -> Bool {
-        let context = LAContext()
-        guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil) else {
-            return true  // Can't evaluate  -  treat as changed
-        }
-
-        guard let currentState = context.evaluatedPolicyDomainState,
-              let savedState = UserDefaults.standard.data(forKey: domainStateKey) else {
-            return true  // No saved state  -  first run or data cleared
-        }
+    func remember() {
+        guard let state = currentState() else { return }
+        UserDefaults.standard.set(state, forKey: storeKey)
+    }
 
-        return currentState != savedState
+    func hasChanged() -> Bool {
+        guard let now = currentState(),
+              let before = UserDefaults.standard.data(forKey: storeKey) else { return true }
+        return now != before
     }
 }
 ```
 
-**Note:** `evaluatedPolicyDomainState` is an opaque `Data` blob. It changes whenever biometric enrollment changes but reveals no information about the biometrics themselves. Store it in `UserDefaults` (not keychain) since it is not sensitive  -  it's only used for change detection.
-
----
+The state hash is opaque `Data` that changes whenever the enrolled set changes
+and reveals nothing about the biometrics themselves, so `UserDefaults` is an
+acceptable place for it. When it cannot be read, or no earlier value was saved,
+treat that as a change. From iOS 18 it is `domainState.biometry.stateHash`;
+`evaluatedPolicyDomainState` is deprecated there and stays only as the fallback
+for older systems. Nothing promises the two values are equal, so the first check
+after an update past iOS 18 may report a change, which fails safe.
 
-## Thread Safety and async/await
+## Threads and async/await
 
-`SecItemCopyMatching` with biometric access control **blocks the calling thread** until the user completes authentication. Never run it on `@MainActor` or the main thread.
-
-`LAContext.evaluatePolicy`'s legacy completion handler executes on a private queue in an unspecified threading context. Direct UI updates from this callback cause crashes, especially on iOS 18 where threading strictness increased.
-
-### Actor-Isolated Biometric Keychain (iOS 15+)
+- A `SecItemCopyMatching` on a biometric item blocks until the user finishes
+  with the prompt. Never call it on `@MainActor` or the main thread.
+- The completion of the callback-based `evaluatePolicy` runs on a private queue.
+  Touching UI from there crashes, and iOS 18 is stricter about it.
 
 ```swift
-@available(iOS 15.0, *)
-actor BiometricKeychain {
-
-    func retrieveSecret(account: String, service: String) async throws -> Data {
-        return try await withCheckedThrowingContinuation { continuation in
+actor BiometricVault {
+    func read(account: String, reason: String) async throws -> Data {
+        try await withCheckedThrowingContinuation { continuation in
             DispatchQueue.global(qos: .userInitiated).async {
-                let context = LAContext()
-                context.localizedReason = "Authenticate to access your account"
-
+                let ctx = LAContext()
+                ctx.localizedReason = reason
                 let query: [String: Any] = [
                     kSecClass as String: kSecClassGenericPassword,
                     kSecAttrAccount as String: account,
-                    kSecAttrService as String: service,
                     kSecReturnData as String: true,
                     kSecMatchLimit as String: kSecMatchLimitOne,
-                    kSecUseAuthenticationContext as String: context
+                    kSecUseAuthenticationContext as String: ctx
                 ]
-
-                var result: AnyObject?
-                let status = SecItemCopyMatching(query as CFDictionary, &result)
-
-                switch status {
-                case errSecSuccess:
-                    if let data = result as? Data {
-                        continuation.resume(returning: data)
-                    } else {
-                        continuation.resume(throwing: BiometricKeychainError.dataConversionFailed)
-                    }
-                case errSecUserCanceled, errSecAuthFailed:
-                    continuation.resume(throwing: BiometricKeychainError.keychainOperationFailed(status: status))
-                default:
-                    continuation.resume(throwing: BiometricKeychainError.keychainOperationFailed(status: status))
+                var out: CFTypeRef?
+                let status = SecItemCopyMatching(query as CFDictionary, &out)
+                if status == errSecSuccess, let data = out as? Data {
+                    continuation.resume(returning: data)
+                } else {
+                    continuation.resume(throwing: BioVaultError.keychain(status))
                 }
             }
         }
     }
 }
-```
 
-### SwiftUI ViewModel Integration
-
-```swift
 @MainActor
-class AuthViewModel: ObservableObject {
-    @Published var isAuthenticated = false
-    @Published var errorMessage: String?
-
-    private let keychain = BiometricKeychain()
+@Observable
+final class RevealModel {
+    var revealed: String?
+    var problem: String?
+    private let vault = BiometricVault()
 
-    func authenticate() {
+    func reveal() {
         Task {
             do {
-                let secret = try await keychain.retrieveSecret(
-                    account: "user_token",
-                    service: "com.myapp.auth"
-                )
-                self.isAuthenticated = true
-                self.processToken(secret)
+                let data = try await vault.read(account: "account-number", reason: "Reveal")
+                revealed = String(decoding: data, as: UTF8.self)
             } catch {
-                self.errorMessage = error.localizedDescription
+                problem = "Could not unlock the account number."
             }
         }
     }
 }
 ```
 
-**Note on native async:** `LAContext` gained `evaluatePolicy(_:localizedReason:) async throws -> Bool` in iOS 15. However, this is only relevant for the non-security-critical UI gating use case. For the secure keychain pattern, you wrap `SecItemCopyMatching` as shown above  -  there is no native async overload for SecItem\* APIs.
+The continuation keeps the blocking call off the actor's executor. iOS 15 added
+`evaluatePolicy(_:localizedReason:) async throws -> Bool`, but it only helps
+with UI gating; SecItem has no async variant, hence the wrapper.
 
----
-
-## Secure Enclave-Backed Keys with Biometric Protection
-
-For asymmetric key operations (signing, key agreement), combine Secure Enclave key generation with biometric access control via CryptoKit. The private key **never leaves the Secure Enclave**  -  all operations happen in hardware.
+## Secure Enclave Keys Behind Biometrics
 
 ```swift
-// ✅ Secure Enclave P-256 key with biometric protection (WWDC 2019-709)
-let accessControl = SecAccessControlCreateWithFlags(
-    nil,
-    kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
-    [.privateKeyUsage, .biometryCurrentSet],
-    nil
-)!
-
-let privateKey = try SecureEnclave.P256.Signing.PrivateKey(
-    accessControl: accessControl
-)
-
-// Signing triggers biometric prompt automatically
-let signature = try privateKey.signature(for: dataToSign)
+import CryptoKit
+
+func makeApprovalKey() throws -> SecureEnclave.P256.Signing.PrivateKey {
+    var cfError: Unmanaged<CFError>?
+    guard let acl = SecAccessControlCreateWithFlags(
+        nil, kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+        [.privateKeyUsage, .biometryCurrentSet], &cfError) else {
+        throw BioVaultError.policyCreation(cfError?.takeRetainedValue())
+    }
+    return try SecureEnclave.P256.Signing.PrivateKey(accessControl: acl)
+}
 ```
 
-Frida operates in user-space on the application processor and has zero access to the Secure Enclave's internal state. The Secure Enclave's memory is encrypted with its own AES engine. Even a kernel-level compromise cannot extract the keys.
-
----
-
-## SDLC Controls  -  Catching the Anti-Pattern in CI
-
-Because AI coding assistants frequently generate the vulnerable `evaluatePolicy` pattern, teams should implement automated detection:
-
-**Conceptual SAST rule (`INSECURE_BIOMETRIC_GATE`):** Identify all calls to `LAContext.evaluatePolicy`. If the `success` boolean directly gates access to a resource AND there is no corresponding `SecItemCopyMatching` using a `SecAccessControl` object in the same flow, flag the code.
-
-**Security review sign-off criteria:**
-
-1. Zero instances of standalone `LAContext.evaluatePolicy` gating sensitive operations
-2. Evidence of `SecItemAdd` with `kSecAttrAccessControl` using `ThisDeviceOnly` accessibility
-3. Documented proof that objection bypass (`ios ui biometrics_bypass`) fails to unlock protected data
-4. All `LAError` cases handled with graceful degradation
-5. If `.biometryCurrentSet` is used, a tested re-enrollment recovery flow exists
-
----
-
-## Dynamic Verification  -  Proving Bypass Resistance
-
-Static code review alone is insufficient. Verification requires dynamic testing:
-
-**Test procedure:** On a jailbroken or instrumented device, inject a Frida script to hook `-[LAContext evaluatePolicy:localizedReason:reply:]` and force `success = true`.
-
-**Pass criteria:** The app prevents access to protected data despite the manipulated callback. The secret remains locked because `SecAccessControl` + Secure Enclave enforcement is independent of the boolean.
-
-**Fail criteria:** The app grants access after the hook forces success. This proves reliance on the vulnerable boolean gate.
-
----
-
-## Key References
-
-- **WWDC 2014 Session 711**  -  "Keychain and Authentication with Touch ID": Introduced the two trust models (evaluatePolicy vs keychain+ACL)
-- **WWDC 2019 Session 709**  -  "Cryptography and Your Apps": CryptoKit + Secure Enclave key generation with access control
-- **Apple Platform Security Guide**  -  Secure Enclave architecture, keychain encryption chain (metadata key + secret key), ACL evaluation in hardware
-- **OWASP MASTG MSTG-AUTH-8**  -  Biometric authentication must not be event-bound
-- **OWASP MASTG MSTG-AUTH-12**  -  Integrity of biometric mechanism must be verified
-- **OWASP MASTG MASTG-TEST-0266**  -  Test for local authentication bypass
-- **objection wiki**  -  "Understanding the iOS Biometrics Bypass": Confirms attack boundary at SecAccessControl
-- **TN3137**  -  "On Mac Keychain APIs and implementations" (macOS keychain unification)
-
----
-
-## Cross-References
-
-- `keychain-fundamentals.md`  -  SecItem CRUD patterns used by the keychain-bound biometric flow
-- `keychain-access-control.md`  -  `SecAccessControlCreateWithFlags`, accessibility constants, and flag composition rules
-- `secure-enclave.md`  -  Hardware-backed keys with biometric gating via `SecAccessControl`
-- `common-anti-patterns.md`  -  Anti-pattern #3 (LAContext-only biometric gate)
-- `credential-storage-patterns.md`  -  Biometric protection for high-value credentials (OAuth tokens, API keys)
-- `testing-security-code.md`  -  Protocol-based mocking for biometric flows, LAContext test strategies
-- `compliance-owasp-mapping.md`  -  M3 (Insecure Authentication/Authorization) biometric requirements
-
----
-
-## Summary Checklist
-
-1. **No standalone boolean gates**  -  `LAContext.evaluatePolicy()` is NEVER the sole authentication mechanism for sensitive data; secrets are always bound to keychain + `SecAccessControl`
-2. **Hardware-gated secrets**  -  All sensitive data protected by biometrics uses `SecAccessControlCreateWithFlags` with the Secure Enclave enforcing the ACL
-3. **Correct flag selection**  -  `.biometryCurrentSet` for high-security (banking, payments); `.biometryAny` for convenience; `.userPresence` for broad compatibility or fallback
-4. **No kSecAttrAccessible conflict**  -  `kSecAttrAccessible` and `kSecAttrAccessControl` are never set on the same keychain item
-5. **ThisDeviceOnly accessibility**  -  Biometric-gated secrets use `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` or `WhenUnlockedThisDeviceOnly`; never syncable
-6. **Complete error handling**  -  All `LAError` codes handled: `.biometryNotEnrolled`, `.biometryLockout`, `.biometryNotAvailable`, `.passcodeNotSet`, `.userCancel`, `.userFallback`
-7. **Graceful degradation**  -  App provides fallback path (passcode or password) when biometrics are unavailable or locked out
-8. **Enrollment change detection**  -  `evaluatedPolicyDomainState` monitored when using `.biometryCurrentSet`; re-enrollment flow implemented
-9. **Thread safety**  -  `SecItemCopyMatching` with biometric ACL never runs on `@MainActor`; actor-isolated or dispatched to background queue
-10. **Dynamic verification**  -  objection/Frida bypass test confirms protected data remains inaccessible when `evaluatePolicy` callback is hooked
-11. **SAST/linting**  -  CI pipeline includes rule to flag standalone `evaluatePolicy` without corresponding `SecAccessControl` keychain operations
+Each `signature(for:)` on that key raises the biometric prompt (WWDC 2019
+Session 709, "Cryptography and Your Apps"). The private key never leaves the
+enclave. Frida runs in user space on the Application Processor and has no path
+into the enclave; the enclave's memory is encrypted by its own AES engine, and
+even a kernel compromise cannot pull the key out. More in
+[secure-enclave.md](secure-enclave.md).
+
+## Controls in the Development Process
+
+- A static-analysis rule, call it `INSECURE_BIOMETRIC_GATE`, flags any
+  `evaluatePolicy` whose success value unlocks a resource when the same flow
+  has no `SecItemCopyMatching` against an item with `SecAccessControl`.
+- Sign-off requires: no standalone gates on sensitive operations; `SecItemAdd`
+  calls using `kSecAttrAccessControl` with a `ThisDeviceOnly` class; a recorded
+  run showing the objection bypass fails; every `LAError` case handled; a tested
+  re-enrollment path wherever `.biometryCurrentSet` is used;
+  `NSFaceIDUsageDescription` present.
+
+## Verifying at Runtime
+
+On a jailbroken or instrumented test device, hook
+`-[LAContext evaluatePolicy:localizedReason:reply:]` so it always reports
+success, then try to reach the protected data.
+
+- Pass: the data stays locked.
+- Fail: the hook grants access.
+
+## Checklist
+
+- No standalone Boolean gates; secrets sit in the keychain behind an ACL.
+- Every biometric-protected item is created with
+  `SecAccessControlCreateWithFlags`, so the enclave enforces the ACL.
+- Flag choice: `.biometryCurrentSet` for high security, `.biometryAny` for
+  convenience, `.userPresence` for compatibility and fallback.
+- Never both accessibility attributes on one item.
+- Biometric items use `WhenPasscodeSetThisDeviceOnly` or
+  `WhenUnlockedThisDeviceOnly` and are never synchronizable.
+- `Info.plist` contains `NSFaceIDUsageDescription`.
+- `LAError` cases handled: `.biometryNotEnrolled`, `.biometryLockout`,
+  `.biometryNotAvailable`, `.passcodeNotSet`, `.userCancel`, `.userFallback`.
+- A passcode or password fallback exists for when biometrics are unavailable or
+  locked out.
+- With `.biometryCurrentSet`, `evaluatedPolicyDomainState` is monitored and a
+  re-enrollment flow exists.
+- Biometric ACL reads never run on `@MainActor`.
+- The objection or Frida bypass test is part of release testing.
+- CI runs the static rule against standalone `evaluatePolicy`.
+
+## Sources and Related Files
+
+Sources: WWDC 2014 Session 711; WWDC 2019 Session 709; Apple Platform Security
+Guide; MSTG-AUTH-8, MSTG-AUTH-12 and MASTG-TEST-0266; the objection wiki page
+"Understanding the iOS Biometrics Bypass"; TN3137.
+
+Related: [keychain-fundamentals.md](keychain-fundamentals.md),
+[keychain-access-control.md](keychain-access-control.md),
+[secure-enclave.md](secure-enclave.md),
+[common-anti-patterns.md](common-anti-patterns.md) (the `LAContext`-only gate),
+[credential-storage-patterns.md](credential-storage-patterns.md),
+[testing-security-code.md](testing-security-code.md),
+[compliance-owasp-mapping.md](compliance-owasp-mapping.md) (M3).