@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swift-security/references/testing-security-code.md

@@ -1,655 +1,462 @@
-# Testing Keychain, CryptoKit, and Biometric Code
+# Testing Security Code
 
-> Scope: Unit, integration, and CI patterns for validating keychain, CryptoKit, and biometric security code across simulator, CI runners, and physical devices.
+The pattern that makes keychain code testable is a protocol between the app and the Security framework. Unit tests run against an in-memory implementation; tests that need the real keychain, the Secure Enclave or biometric hardware run on devices.
 
-**Protocol-based abstraction is the single most important pattern for testable security code.** Wrapping Security framework calls behind a Swift protocol lets you inject an in-memory mock for unit tests while reserving real keychain integration tests for physical devices. The core challenge is that keychain behavior differs dramatically across three environments  -  Xcode simulator, CI runner, and physical device  -  and tests that ignore these differences produce flaky failures, crashes, or false confidence.
+The keychain does not behave the same on Simulator, on a headless CI runner and on a phone. Tests written without that in mind fail intermittently, crash on runners, or pass while proving nothing.
 
-This reference covers mock design, CryptoKit round-trip tests, Secure Enclave guards, biometric mocking, CI/CD keychain creation, simulator limitations, Swift Testing framework patterns, mutation testing, and OWASP MASTG validation. All code targets Swift 5.9+/6.0, iOS 17-18+, with iOS 26 post-quantum notes where applicable.
+Targets: Swift 5.9 and Swift 6, iOS 17 and 18, with notes for the iOS 26 post-quantum APIs. Background: TN3137 (macOS keychain APIs and implementations), WWDC19 session 413 "Testing in Xcode", the WWDC24 Swift Testing sessions (10179 and 10195), Apple Platform Security, and the OWASP MASTG.
 
-Key sources: Apple TN3137 "On Mac keychain APIs and implementations," WWDC19-413 "Testing in Xcode," WWDC24-10179/10195 "Meet/Go further with Swift Testing," Apple Platform Security Guide, OWASP MASTG.
-
----
+Related: [keychain-fundamentals.md](keychain-fundamentals.md), [cryptokit-public-key.md](cryptokit-public-key.md), [migration-legacy-stores.md](migration-legacy-stores.md), [common-anti-patterns.md](common-anti-patterns.md).
 
 ## Contents
 
-- [Protocol-Based Keychain Abstraction](#protocol-based-keychain-abstraction)
-  - [KeychainServiceProtocol with Real and Mock Implementations](#keychainserviceprotocol-with-real-and-mock-implementations)
-- [Seven Mistakes AI Generators Make in Keychain Tests](#seven-mistakes-ai-generators-make-in-keychain-tests)
-- [Simulator vs. Device Testing Matrix](#simulator-vs-device-testing-matrix)
-  - [Conditional Compilation and Runtime Guards](#conditional-compilation-and-runtime-guards)
-- [Essential Testing Patterns](#essential-testing-patterns)
-  - [setUp/tearDown Cleanup for Real Keychain Tests](#setupteardown-cleanup-for-real-keychain-tests)
-  - [No Cleanup  -  Flaky Across Runs](#no-cleanup-flaky-across-runs)
-  - [Testing Error Paths with Injected Failures](#testing-error-paths-with-injected-failures)
-  - [CryptoKit Round-Trip Tests (Simulator-Safe)](#cryptokit-round-trip-tests-simulator-safe)
-- [Secure Enclave Test Strategy  -  Protocol Fallback](#secure-enclave-test-strategy-protocol-fallback)
-  - [SigningKeyProvider Protocol with SE/Software Implementations](#signingkeyprovider-protocol-with-sesoftware-implementations)
-  - [Testing Secure Enclave Code](#testing-secure-enclave-code)
-- [Biometric Flow Testing  -  LAContext Mocking](#biometric-flow-testing-lacontext-mocking)
-  - [Protocol-Based Approach (Preferred)](#protocol-based-approach-preferred)
-  - [Biometric Scenarios to Cover](#biometric-scenarios-to-cover)
-- [CI/CD Pipeline Configuration](#cicd-pipeline-configuration)
-  - [GitHub Actions](#github-actions)
-  - [Common CI Error Reference](#common-ci-error-reference)
-  - [Test Host App Requirement](#test-host-app-requirement)
-- [Xcode Test Plans  -  Separating Simulator from Device](#xcode-test-plans-separating-simulator-from-device)
-- [Swift Testing Framework Patterns](#swift-testing-framework-patterns)
-- [Advanced Patterns](#advanced-patterns)
-  - [Migration Testing: UserDefaults to Keychain](#migration-testing-userdefaults-to-keychain)
-  - [Performance Testing](#performance-testing)
-  - [Mutation Testing](#mutation-testing)
-  - [OWASP MASTG Keychain Validation](#owasp-mastg-keychain-validation)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## Protocol-Based Keychain Abstraction
-
-The foundation of testable keychain code is a protocol abstracting the four Security framework operations. Every view model, service, or manager that touches the keychain depends on this protocol, never on the Security framework directly.
-
-### KeychainServiceProtocol with Real and Mock Implementations
+- [A protocol in front of the keychain](#a-protocol-in-front-of-the-keychain)
+- [Seven mistakes in generated keychain tests](#seven-mistakes-in-generated-keychain-tests)
+- [Simulator versus device](#simulator-versus-device)
+- [Core test patterns](#core-test-patterns)
+- [Secure Enclave tests](#secure-enclave-tests)
+- [Biometric flows](#biometric-flows)
+- [CI configuration](#ci-configuration)
+- [Test plans](#test-plans)
+- [Swift Testing](#swift-testing)
+- [Further techniques](#further-techniques)
+- [Takeaways](#takeaways)
+- [Checklist](#checklist)
+
+## A protocol in front of the keychain
 
 ```swift
 import Foundation
 import Security
 
-enum KeychainError: Error, Equatable {
-    case duplicateItem
-    case itemNotFound
-    case authFailed
-    case interactionNotAllowed
+enum VaultStoreError: Error, Equatable {
+    case duplicateItem, itemNotFound, authFailed, userCanceled, interactionNotAllowed
     case unexpectedData
-    case unhandledError(status: OSStatus)
+    case unhandled(status: OSStatus)
 
     init(status: OSStatus) {
         switch status {
-        case errSecDuplicateItem:          self = .duplicateItem
-        case errSecItemNotFound:           self = .itemNotFound
-        case errSecAuthFailed:             self = .authFailed
-        case errSecInteractionNotAllowed:  self = .interactionNotAllowed
-        default:                           self = .unhandledError(status: status)
+        case errSecDuplicateItem: self = .duplicateItem
+        case errSecItemNotFound: self = .itemNotFound
+        case errSecAuthFailed: self = .authFailed
+        case errSecUserCanceled: self = .userCanceled
+        case errSecInteractionNotAllowed: self = .interactionNotAllowed
+        default: self = .unhandled(status: status)
         }
     }
 }
 
-protocol KeychainServiceProtocol: Sendable {
-    func save(_ data: Data, forKey key: String) throws
-    func read(forKey key: String) throws -> Data?
-    func update(_ data: Data, forKey key: String) throws
-    func delete(forKey key: String) throws
-    func deleteAll() throws
+protocol SecretStore: Sendable {
+    func put(_ secret: Data, for name: String) throws
+    func value(for name: String) throws -> Data?
+    func replace(_ secret: Data, for name: String) throws
+    func remove(for name: String) throws
+    func removeAll() throws
 }
 ```
 
-The real `KeychainService` implementation wraps `SecItem*` calls with the add-or-update pattern and proper `OSStatus` mapping (see `keychain-fundamentals.md` for the full implementation). Key points: `save` attempts update first to avoid `errSecDuplicateItem`; `delete` treats `errSecItemNotFound` as success; the class conforms to `@unchecked Sendable` with immutable stored properties.
+The production implementation, `KeychainSecretStore`, follows the rules in [keychain-fundamentals.md](keychain-fundamentals.md): `put` calls `SecItemAdd` and, on `errSecDuplicateItem`, `SecItemUpdate` with the new data; `remove` treats `errSecItemNotFound` as success; it is a final class whose stored properties are all `let`, marked `@unchecked Sendable`.
 
-The mock replaces Security framework with a dictionary. Runs everywhere  -  simulator, CI, even Linux  -  with zero entitlement requirements. Supports injectable errors and call counting:
+The test double keeps everything in a dictionary, counts calls and throws on request. It runs on Simulator, on CI and even on Linux, and needs no entitlements.
 
 ```swift
-final class MockKeychainService: KeychainServiceProtocol, @unchecked Sendable {
-    var storage: [String: Data] = [:]
-    var saveCallCount = 0
-    var readCallCount = 0
-    var deleteCallCount = 0
-    var errorToThrow: KeychainError?
-
-    func save(_ data: Data, forKey key: String) throws {
-        if let error = errorToThrow { throw error }
-        saveCallCount += 1
-        storage[key] = data
-    }
-
-    func read(forKey key: String) throws -> Data? {
-        if let error = errorToThrow { throw error }
-        readCallCount += 1
-        return storage[key]
-    }
-
-    func update(_ data: Data, forKey key: String) throws {
-        if let error = errorToThrow { throw error }
-        guard storage[key] != nil else { throw KeychainError.itemNotFound }
-        storage[key] = data
-    }
-
-    func delete(forKey key: String) throws {
-        if let error = errorToThrow { throw error }
-        storage.removeValue(forKey: key)
-        deleteCallCount += 1
+final class InMemorySecretStore: SecretStore, @unchecked Sendable {
+    private let lock = NSLock()
+    private var rows: [String: Data] = [:]
+    private(set) var saveCount = 0
+    private(set) var readCount = 0
+    var failure: VaultStoreError?
+
+    func put(_ secret: Data, for name: String) throws {
+        try locked { saveCount += 1; rows[name] = secret }
+    }
+    func value(for name: String) throws -> Data? {
+        try locked { readCount += 1; return rows[name] }
+    }
+    func replace(_ secret: Data, for name: String) throws {
+        try locked {
+            guard rows[name] != nil else { throw VaultStoreError.itemNotFound }
+            rows[name] = secret
+        }
     }
+    func remove(for name: String) throws { try locked { rows[name] = nil } }
+    func removeAll() throws { try locked { rows.removeAll() } }
 
-    func deleteAll() throws {
-        if let error = errorToThrow { throw error }
-        storage.removeAll()
+    private func locked<T>(_ body: () throws -> T) throws -> T {
+        lock.lock(); defer { lock.unlock() }
+        if let failure { throw failure }
+        return try body()
     }
 }
 ```
 
-Business logic depends only on the protocol  -  never on `SecItem*` directly:
+Code under test depends only on the protocol:
 
 ```swift
-final class AuthenticationManager {
-    private let keychain: KeychainServiceProtocol
+struct SessionKeeper {
+    let store: any SecretStore
 
-    init(keychain: KeychainServiceProtocol) {
-        self.keychain = keychain
+    func remember(token: String) throws {
+        try store.put(Data(token.utf8), for: "session.token")
     }
-
-    func storeToken(_ token: String) throws {
-        guard let data = token.data(using: .utf8) else {
-            throw KeychainError.unexpectedData
-        }
-        try keychain.save(data, forKey: "auth_token")
-    }
-
-    func retrieveToken() throws -> String? {
-        guard let data = try keychain.read(forKey: "auth_token") else { return nil }
-        return String(data: data, encoding: .utf8)
+    func currentToken() throws -> String? {
+        try store.value(for: "session.token").map { String(decoding: $0, as: UTF8.self) }
     }
 }
 ```
 
----
-
-## Seven Mistakes AI Generators Make in Keychain Tests
-
-Both research providers independently identified overlapping anti-patterns. This merged list covers the full set:
-
-**1. Tests that use the real keychain without cleanup.** Tests calling `SecItemAdd` directly leave state across runs. Second run fails with `errSecDuplicateItem` (-25299). AI generators rarely include `setUp`/`tearDown` cleanup.
-
-**2. Assuming Secure Enclave exists on simulator.** `SecureEnclave.isAvailable` returns `false` on every simulator. Tests calling `SecureEnclave.P256.Signing.PrivateKey()` directly throw `CryptoKitError` on simulator and crash CI.
+## Seven mistakes in generated keychain tests
 
-**3. Not testing error paths.** Real keychain code must handle `errSecDuplicateItem` (-25299), `errSecItemNotFound` (-25300), `errSecAuthFailed` (-25293), and `errSecInteractionNotAllowed` (-25308). AI generators almost never test these failure modes.
+1. **No cleanup around real-keychain tests.** The first run passes; the second hits `errSecDuplicateItem` (-25299).
+2. **Expecting a Secure Enclave on Simulator.** The Simulator has no Secure Enclave. Branch at compile time with `#if targetEnvironment(simulator)` and treat `SecureEnclave.isAvailable` as the runtime check on real hardware only; do not build Simulator behaviour on what the flag reports there. Creating a Secure Enclave key without that guard throws a `CryptoKitError` or fails the test run.
+3. **Only testing the happy path.** Cover -25299, -25300 (`errSecItemNotFound`), -25293 (`errSecAuthFailed`), -128 (`errSecUserCanceled`) and -25308 (`errSecInteractionNotAllowed`).
+4. **Expecting biometric hardware.** `canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error:)` returns false on Simulator unless enrolment is simulated.
+5. **No host app.** From Xcode 9 on, a logic test bundle on the iOS Simulator has no keychain access of its own. Give it a host application; otherwise expect `SecItemAdd` to fail with -25300 or -34018 (`errSecMissingEntitlement`).
+6. **Unscoped items.** Tests must use their own `kSecAttrService` so they never touch app data or each other's rows.
+7. **Mixing up keychain types.** The `security` command-line tool works on file-based keychains. iOS apps, and macOS apps using the data protection keychain, use a different store, so `security create-keychain` on a CI runner creates the wrong kind of keychain for testing `SecItemAdd`.
 
-**4. Assuming biometric hardware.** Tests instantiating a real `LAContext` and asserting `canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)` returns `true` fail on simulator where no biometric hardware exists.
+## Simulator versus device
 
-**5. Missing test host app.** Since Xcode 9, test bundles on iOS simulator require a host app to access the keychain. Without one, `SecItemAdd` returns `-25300` or `-34018`. AI generators never mention this requirement.
+| Capability | Simulator | Device |
+| --- | --- | --- |
+| Keychain add, read, update, delete | Works | Works |
+| CryptoKit software algorithms | Works | Works, hardware accelerated |
+| `kSecAttrAccessible` | Accepted, not enforced by hardware | Enforced |
+| Secure Enclave | Not present; key creation fails | Present on A7 and later |
+| Biometric-protected items | Returned without any prompt | Prompt shown |
+| `canEvaluatePolicy` for biometrics | False, unless enrolment is simulated from the Simulator's Features menu | True when enrolled |
+| ML-KEM and ML-DSA (iOS 26) | Works in software | Works |
 
-**6. No service/account scoping.** Tests omitting `kSecAttrService` match items from other tests or even other apps. Every keychain operation in tests must use a unique, test-specific service identifier.
+The biometric row is the dangerous one: a Simulator test for a Face ID protected item passes without any authentication, which proves nothing about the real behaviour.
 
-**7. Confusing data protection keychain with file-based keychain.** Per Apple TN3137, macOS has two keychain implementations. The `security` CLI works with the file-based keychain; iOS apps use the data protection keychain. CI scripts using `security create-keychain` create the wrong type for `SecItemAdd` targets.
-
----
-
-## Simulator vs. Device Testing Matrix
-
-Understanding exactly what works where prevents entire categories of test failures:
-
-| Feature                                                       | Simulator                             | Physical Device              |
-| ------------------------------------------------------------- | ------------------------------------- | ---------------------------- |
-| Keychain CRUD (`SecItemAdd`, etc.)                            | ✅ Works                              | ✅ Works                     |
-| CryptoKit software crypto (AES-GCM, ChaChaPoly, P256, SHA256) | ✅ Software                           | ✅ Hardware-accelerated      |
-| `kSecAttrAccessible` values                                   | ✅ Accepted but not hardware-enforced | ✅ Hardware-enforced         |
-| `SecureEnclave.isAvailable`                                   | Returns **false**                     | Returns **true** (A7+)       |
-| `SecureEnclave.P256.Signing.PrivateKey()`                     | ❌ Throws                             | ✅ Works                     |
-| Biometric prompt on protected items                           | ❌ Skipped  -  value returned silently  | ✅ Shows prompt              |
-| `LAContext.canEvaluatePolicy(.biometrics)`                    | Returns **false**                     | Returns **true** if enrolled |
-| Face ID simulation via Xcode menu                             | ✅ Manual only                        | N/A (real hardware)          |
-| Post-quantum (ML-KEM, ML-DSA) iOS 26+                         | ✅ Software (iOS 26 runtime)          | ✅ Works                     |
-
-**Critical subtlety:** On simulator, keychain items protected with `kSecAttrAccessControl` and biometric flags return their value without showing a biometric prompt. Simulator tests that store biometric-protected items and read them succeed silently, giving false confidence the biometric gate works.
-
-### Conditional Compilation and Runtime Guards
+Guards:
 
 ```swift
-// Compile-time: exclude SE code on simulator
-#if targetEnvironment(simulator)
-    let signingKey = SoftwareSigningKey()
-#else
-    let signingKey = SecureEnclave.isAvailable
-        ? try SecureEnclaveSigningKey()
-        : SoftwareSigningKey()
-#endif
-
-// Runtime skip in XCTest
-func testDeviceOnlyFeature() throws {
+import CryptoKit
+import XCTest
+
+func makeSigner() throws -> any SigningKeyProvider {
     #if targetEnvironment(simulator)
-    throw XCTSkip("Requires physical device")
+    return SoftwareSigningKey()
+    #else
+    return SecureEnclave.isAvailable ? try SecureEnclaveSigningKey() : SoftwareSigningKey()
     #endif
-    // Device-only test code here
 }
 
-// Runtime detection via ProcessInfo
-struct EnvironmentDetector {
-    static var isSimulator: Bool {
-        ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil
-    }
-    static var isRunningTests: Bool {
-        ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
-    }
+func requireHardware() throws {
+    #if targetEnvironment(simulator)
+    throw XCTSkip("Requires a physical device")
+    #endif
 }
-```
 
----
+let runningInSimulator = ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil
+let runningUnderTests = ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+```
 
-## Essential Testing Patterns
+## Core test patterns
 
-### setUp/tearDown Cleanup for Real Keychain Tests
+Real-keychain integration test, with its own service and cleanup on both sides:
 
 ```swift
-final class KeychainIntegrationTests: XCTestCase {
-    private let testService = "com.tests.keychain-integration"
-    private var keychain: KeychainService!
-
-    override func setUp() {
-        super.setUp()
-        keychain = KeychainService(service: testService)
-        try? keychain.deleteAll()  // Clean slate
-    }
+final class KeychainSecretStoreTests: XCTestCase {
+    private var store: KeychainSecretStore!
 
-    override func tearDown() {
-        try? keychain.deleteAll()  // Leave no trace
-        super.tearDown()
+    override func setUpWithError() throws {
+        store = KeychainSecretStore(service: "tests.vault.\(name)")
+        try store.removeAll()
     }
 
-    func testSaveAndRetrieveToken() throws {
-        let token = "test-jwt-token-12345"
-        try keychain.save(token.data(using: .utf8)!, forKey: "access_token")
-        let retrieved = try keychain.read(forKey: "access_token")
-        XCTAssertEqual(String(data: retrieved!, encoding: .utf8), token)
+    override func tearDownWithError() throws {
+        try store.removeAll()
     }
-}
-```
 
-### No Cleanup  -  Flaky Across Runs
-
-```swift
-// ❌ INCORRECT: No cleanup, no isolation
-final class BadKeychainTests: XCTestCase {
-    func testSaveToken() {
-        let query: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: "token",
-            kSecValueData as String: "secret".data(using: .utf8)!
-        ]
-        let status = SecItemAdd(query as CFDictionary, nil)
-        XCTAssertEqual(status, errSecSuccess)
-        // First run: passes ✅
-        // Second run: FAILS with errSecDuplicateItem (-25299) ❌
+    func testSaveThenRead_ReturnsSameBytes() throws {
+        let secret = Data("pin-4821".utf8)
+        try store.put(secret, for: "pin")
+        XCTAssertEqual(try store.value(for: "pin"), secret)
     }
 }
 ```
 
-### Testing Error Paths with Injected Failures
-
-```swift
-final class KeychainErrorPathTests: XCTestCase {
-    var mockKeychain: MockKeychainService!
-    var authManager: AuthenticationManager!
-
-    override func setUp() {
-        mockKeychain = MockKeychainService()
-        authManager = AuthenticationManager(keychain: mockKeychain)
-    }
+What not to write: a test that calls `SecItemAdd` directly with no service attribute and no cleanup. It passes exactly once and then fails with -25299 forever.
 
-    func testStoreToken_whenDuplicateItem_throwsExpectedError() {
-        mockKeychain.errorToThrow = .duplicateItem
-        XCTAssertThrowsError(try authManager.storeToken("token")) { error in
-            XCTAssertEqual(error as? KeychainError, .duplicateItem)
-        }
-    }
+Error paths through the mock:
 
-    func testRetrieveToken_whenAuthFailed_throwsError() {
-        mockKeychain.errorToThrow = .authFailed
-        XCTAssertThrowsError(try authManager.retrieveToken()) { error in
-            XCTAssertEqual(error as? KeychainError, .authFailed)
-        }
-    }
+```swift
+func testSaveWhileLocked_SurfacesInteractionNotAllowed() {
+    let mock = InMemorySecretStore()
+    mock.failure = .interactionNotAllowed
+    let keeper = SessionKeeper(store: mock)
 
-    func testRetrieveToken_whenInteractionNotAllowed_throwsError() {
-        // Simulates the most common CI failure scenario
-        mockKeychain.errorToThrow = .interactionNotAllowed
-        XCTAssertThrowsError(try authManager.retrieveToken()) { error in
-            XCTAssertEqual(error as? KeychainError, .interactionNotAllowed)
-        }
+    XCTAssertThrowsError(try keeper.remember(token: "abc")) { error in
+        XCTAssertEqual(error as? VaultStoreError, .interactionNotAllowed)
     }
 }
 ```
 
-### CryptoKit Round-Trip Tests (Simulator-Safe)
+Repeat for `.duplicateItem`, `.authFailed` and `.userCanceled`. `interactionNotAllowed` deserves particular care: it is the failure CI runs hit most.
 
-All CryptoKit software operations work on simulator. These tests run everywhere:
+CryptoKit tests are Simulator-safe:
 
 ```swift
-import XCTest
-import CryptoKit
-
-final class CryptoKitTests: XCTestCase {
-
-    func testAESGCMRoundTrip() throws {
-        let key = SymmetricKey(size: .bits256)
-        let plaintext = "Sensitive credentials".data(using: .utf8)!
-        let sealedBox = try AES.GCM.seal(plaintext, using: key)
-        let ciphertext = sealedBox.combined!
-        XCTAssertNotEqual(ciphertext, plaintext)
-
-        let reopened = try AES.GCM.SealedBox(combined: ciphertext)
-        let decrypted = try AES.GCM.open(reopened, using: key)
-        XCTAssertEqual(decrypted, plaintext)
-    }
-
-    func testAESGCMWrongKeyFails() throws {
-        let correctKey = SymmetricKey(size: .bits256)
-        let wrongKey = SymmetricKey(size: .bits256)
-        let sealed = try AES.GCM.seal("secret".data(using: .utf8)!, using: correctKey)
-        XCTAssertThrowsError(try AES.GCM.open(sealed, using: wrongKey))
-    }
-
-    func testP256SignVerify() throws {
-        let privateKey = P256.Signing.PrivateKey()
-        let data = "Message to authenticate".data(using: .utf8)!
-        let signature = try privateKey.signature(for: data)
-        XCTAssertTrue(privateKey.publicKey.isValidSignature(signature, for: data))
-
-        let tampered = "Tampered message".data(using: .utf8)!
-        XCTAssertFalse(privateKey.publicKey.isValidSignature(signature, for: tampered))
-    }
-
-    func testCurve25519KeyAgreement() throws {
-        let alice = Curve25519.KeyAgreement.PrivateKey()
-        let bob = Curve25519.KeyAgreement.PrivateKey()
-        let aliceShared = try alice.sharedSecretFromKeyAgreement(with: bob.publicKey)
-        let bobShared = try bob.sharedSecretFromKeyAgreement(with: alice.publicKey)
+func testGCMRoundTripAndWrongKey() throws {
+    let key = SymmetricKey(size: .bits256)
+    let wire = try XCTUnwrap(try AES.GCM.seal(Data("ledger".utf8), using: key).combined)
+    let parsed = try AES.GCM.SealedBox(combined: wire)
+    XCTAssertEqual(try AES.GCM.open(parsed, using: key), Data("ledger".utf8))
+    let stranger = SymmetricKey(size: .bits256)
+    XCTAssertThrowsError(try AES.GCM.open(parsed, using: stranger))
+}
 
-        let aliceKey = aliceShared.hkdfDerivedSymmetricKey(
-            using: SHA256.self, salt: Data(), sharedInfo: Data(), outputByteCount: 32)
-        let bobKey = bobShared.hkdfDerivedSymmetricKey(
-            using: SHA256.self, salt: Data(), sharedInfo: Data(), outputByteCount: 32)
+func testP256SignatureRejectsTampering() throws {
+    let signer = P256.Signing.PrivateKey()
+    let signature = try signer.signature(for: Data("amount=10".utf8))
+    XCTAssertTrue(signer.publicKey.isValidSignature(signature, for: Data("amount=10".utf8)))
+    XCTAssertFalse(signer.publicKey.isValidSignature(signature, for: Data("amount=99".utf8)))
+}
 
-        // Both parties can decrypt each other's messages
-        let sealed = try AES.GCM.seal("test".data(using: .utf8)!, using: aliceKey)
-        XCTAssertEqual(try AES.GCM.open(sealed, using: bobKey), "test".data(using: .utf8)!)
-    }
+func testX25519PartiesDeriveMatchingKeys() throws {
+    let alice = Curve25519.KeyAgreement.PrivateKey()
+    let bob = Curve25519.KeyAgreement.PrivateKey()
+    let salt = Data("pairing-v1".utf8)
+    func derive(_ mine: Curve25519.KeyAgreement.PrivateKey,
+                _ theirs: Curve25519.KeyAgreement.PublicKey) throws -> SymmetricKey {
+        try mine.sharedSecretFromKeyAgreement(with: theirs)
+            .hkdfDerivedSymmetricKey(using: SHA384.self, salt: salt,
+                                     sharedInfo: Data("chat".utf8), outputByteCount: 32)
+    }
+    let aliceKey = try derive(alice, bob.publicKey)
+    let bobKey = try derive(bob, alice.publicKey)
+    let sealed = try ChaChaPoly.seal(Data("hello".utf8), using: aliceKey)
+    XCTAssertEqual(try ChaChaPoly.open(sealed, using: bobKey), Data("hello".utf8))
 }
 ```
 
-**iOS 26 note:** Post-quantum cryptography (ML-KEM, ML-DSA) is available via CryptoKit starting iOS 26. Gate these tests with `@available(iOS 26, *)` and use the same round-trip pattern. Software-based PQC works on simulator (see `cryptokit-public-key.md`).
-
----
+Post-quantum tests follow the same round-trip shape and are gated on availability; the software implementations run on the iOS 26 Simulator runtime.
 
-## Secure Enclave Test Strategy  -  Protocol Fallback
+```swift
+@available(iOS 26, *)
+func verifyMLKEMRoundTrip() throws {
+    let receiver = try MLKEM768.PrivateKey()
+    let result = try receiver.publicKey.encapsulate()
+    let recovered = try receiver.decapsulate(result.encapsulated)
+    let bytes = { (key: SymmetricKey) in key.withUnsafeBytes { Data($0) } }
+    XCTAssertEqual(bytes(recovered), bytes(result.sharedSecret))
+}
+```
 
-`SecureEnclave.P256.Signing.PrivateKey` and `P256.Signing.PrivateKey` are distinct types, so a single function should not promise to return one concrete type for both SE and software paths. Use a protocol-based abstraction:
+## Secure Enclave tests
 
-### SigningKeyProvider Protocol with SE/Software Implementations
+The enclave-backed signing key type and the software `P256.Signing.PrivateKey` share no common type, so a factory cannot return "one of them" directly. Put both behind a protocol.
 
 ```swift
-import CryptoKit
-
-protocol SigningKeyProvider {
-    func sign(_ data: Data) throws -> Data
-    func publicKeyData() -> Data
+protocol SigningKeyProvider: Sendable {
+    func signature(over payload: Data) throws -> Data
+    var publicKeyDER: Data { get }
 }
 
-final class SecureEnclaveSigningKey: SigningKeyProvider {
-    private let key: SecureEnclave.P256.Signing.PrivateKey
+struct SecureEnclaveSigningKey: SigningKeyProvider {
+    private let enclaveKey: SecureEnclave.P256.Signing.PrivateKey
 
     init() throws {
-        guard SecureEnclave.isAvailable else {
-            throw KeychainError.unhandledError(status: errSecUnimplemented)
+        guard SecureEnclave.isAvailable else { throw VaultStoreError.unhandled(status: errSecUnimplemented) }
+        guard let access = SecAccessControlCreateWithFlags(nil,
+                kSecAttrAccessibleWhenUnlockedThisDeviceOnly, [.privateKeyUsage], nil) else {
+            throw VaultStoreError.unhandled(status: errSecParam)
         }
-        self.key = try SecureEnclave.P256.Signing.PrivateKey()
+        enclaveKey = try .init(accessControl: access)
     }
-
-    func sign(_ data: Data) throws -> Data {
-        try key.signature(for: data).derRepresentation
+    func signature(over payload: Data) throws -> Data {
+        try enclaveKey.signature(for: payload).derRepresentation
     }
-
-    func publicKeyData() -> Data { key.publicKey.derRepresentation }
+    var publicKeyDER: Data { enclaveKey.publicKey.derRepresentation }
 }
 
-final class SoftwareSigningKey: SigningKeyProvider {
-    private let key = P256.Signing.PrivateKey()
-
-    func sign(_ data: Data) throws -> Data {
-        try key.signature(for: data).derRepresentation
+struct SoftwareSigningKey: SigningKeyProvider {
+    private let softwareKey = P256.Signing.PrivateKey()
+    func signature(over payload: Data) throws -> Data {
+        try softwareKey.signature(for: payload).derRepresentation
     }
-
-    func publicKeyData() -> Data { key.publicKey.derRepresentation }
+    var publicKeyDER: Data { softwareKey.publicKey.derRepresentation }
 }
 
-struct SigningKeyFactory {
-    static func make() -> SigningKeyProvider {
-        if SecureEnclave.isAvailable,
-           let seKey = try? SecureEnclaveSigningKey() {
-            return seKey
-        }
-        return SoftwareSigningKey()
+enum SignerFactory {
+    static func make() -> any SigningKeyProvider {
+        (try? makeSigner()) ?? SoftwareSigningKey()
     }
 }
 ```
 
-### Testing Secure Enclave Code
+`.privateKeyUsage` is always part of a Secure Enclave signing key's access control flags; add `.biometryCurrentSet` or `.userPresence` next to it when the key should require authentication.
+
+A test that creates a Secure Enclave key unconditionally crashes or fails on Simulator and CI. Skip it, or test through the protocol:
 
 ```swift
-// ❌ INCORRECT: Crashes on simulator and CI
-func testSecureEnclaveSigning_BROKEN() throws {
-    let key = try SecureEnclave.P256.Signing.PrivateKey() // throws on simulator
-    let sig = try key.signature(for: "data".data(using: .utf8)!)
-    XCTAssertTrue(key.publicKey.isValidSignature(sig, for: "data".data(using: .utf8)!))
+func testEnclaveSignature_VerifiesWithPublicKey() throws {
+    try requireHardware()
+    try XCTSkipUnless(SecureEnclave.isAvailable, "No Secure Enclave on this machine")
+    let signer = try SecureEnclaveSigningKey()
+    try assertVerifies(signer)
 }
 
-// ✅ CORRECT: Skip gracefully when SE unavailable
-func testSecureEnclaveSigning_withGuard() throws {
-    try XCTSkipUnless(SecureEnclave.isAvailable,
-                      "Secure Enclave not available  -  skipping on simulator")
-    let key = try SecureEnclave.P256.Signing.PrivateKey()
-    let data = "authenticated payload".data(using: .utf8)!
-    let sig = try key.signature(for: data)
-    XCTAssertTrue(key.publicKey.isValidSignature(sig, for: data))
+func testAnySigner_ProducesVerifiableSignatures() throws {
+    try assertVerifies(SignerFactory.make())
 }
 
-// ✅ CORRECT: Protocol-based test runs everywhere
-func testSigningWithFallback() throws {
-    let signer = SigningKeyFactory.make()
-    let data = "payload".data(using: .utf8)!
-    let sigBytes = try signer.sign(data)
-    XCTAssertFalse(sigBytes.isEmpty)
-
-    let publicKey = try P256.Signing.PublicKey(derRepresentation: signer.publicKeyData())
-    let signature = try P256.Signing.ECDSASignature(derRepresentation: sigBytes)
-    XCTAssertTrue(publicKey.isValidSignature(signature, for: data))
+private func assertVerifies(_ provider: any SigningKeyProvider) throws {
+    let challenge = Data("challenge-17".utf8)
+    let verifier = try P256.Signing.PublicKey(derRepresentation: provider.publicKeyDER)
+    let der = try provider.signature(over: challenge)
+    XCTAssertTrue(verifier.isValidSignature(try .init(derRepresentation: der), for: challenge))
 }
 ```
 
----
-
-## Biometric Flow Testing  -  LAContext Mocking
+## Biometric flows
 
-Wrap `LAContext` behind a protocol for full control over biometric outcomes in tests. Alternatively, subclass `LAContext` directly (simpler but tighter coupling).
-
-### Protocol-Based Approach (Preferred)
+Put `LAContext` behind a protocol so tests control the outcome. The quickest version copies `LAContext`'s own `canEvaluatePolicy(_:error:)` and `evaluatePolicy(_:localizedReason:reply:)` requirements into a `BiometricAuthContext` protocol and declares `extension LAContext: BiometricAuthContext {}`. A small adapter, shown here, keeps the protocol in your own vocabulary instead. Subclassing `LAContext` also works and is shorter, at the cost of coupling tests to the real class.
 
 ```swift
 import LocalAuthentication
 
 protocol BiometricAuthContext {
-    func canEvaluatePolicy(_ policy: LAPolicy, error: NSErrorPointer) -> Bool
-    func evaluatePolicy(_ policy: LAPolicy, localizedReason: String,
-                        reply: @escaping (Bool, Error?) -> Void)
+    func biometricsReady() -> Bool
+    func authenticate(reason: String, reply: @escaping @Sendable (Bool, Error?) -> Void)
 }
 
-extension LAContext: BiometricAuthContext {}
-
-final class BiometricAuthManager {
-    private let context: BiometricAuthContext
-
-    init(context: BiometricAuthContext = LAContext()) {
-        self.context = context
-    }
-
-    var isBiometricsAvailable: Bool {
+struct SystemBiometricContext: BiometricAuthContext {
+    private let context = LAContext()
+    func biometricsReady() -> Bool {
         context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)
     }
+    func authenticate(reason: String, reply: @escaping @Sendable (Bool, Error?) -> Void) {
+        context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, localizedReason: reason, reply: reply)
+    }
+}
+```
+
+```swift
+final class BiometricPrompt {
+    private let context: BiometricAuthContext
+    init(context: BiometricAuthContext) { self.context = context }
 
-    func authenticate(reason: String,
-                      completion: @escaping (Result<Void, Error>) -> Void) {
-        guard isBiometricsAvailable else {
-            completion(.failure(LAError(.biometryNotAvailable)))
+    func confirm(reason: String, then finish: @escaping @Sendable (Result<Void, Error>) -> Void) {
+        guard context.biometricsReady() else {
+            finish(.failure(LAError(.biometryNotAvailable)))
             return
         }
-        context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics,
-                               localizedReason: reason) { success, error in
-            completion(success ? .success(()) : .failure(error ?? LAError(.authenticationFailed)))
+        context.authenticate(reason: reason) { ok, error in
+            finish(ok ? .success(()) : .failure(error ?? LAError(.authenticationFailed)))
         }
     }
 }
 
-final class MockBiometricContext: BiometricAuthContext {
-    var canEvaluateResult = true
-    var evaluateResult = true
-    var evaluateError: Error?
-    var evaluateCalled = false
+final class StubBiometricContext: BiometricAuthContext {
+    var available = true
+    var succeeds = true
+    var error: Error?
+    private(set) var evaluateCalled = false
 
-    func canEvaluatePolicy(_ policy: LAPolicy, error: NSErrorPointer) -> Bool {
-        canEvaluateResult
-    }
-
-    func evaluatePolicy(_ policy: LAPolicy, localizedReason: String,
-                        reply: @escaping (Bool, Error?) -> Void) {
+    func biometricsReady() -> Bool { available }
+    func authenticate(reason: String, reply: @escaping @Sendable (Bool, Error?) -> Void) {
         evaluateCalled = true
-        reply(evaluateResult, evaluateError)
+        reply(succeeds, self.error)
     }
 }
 ```
 
-### Biometric Scenarios to Cover
+This tests UI gating only. A secret behind the prompt still has to live in a keychain item bound with `SecAccessControl`, as [biometric-authentication.md](biometric-authentication.md) explains.
 
-| Scenario     | canEvaluate | evaluatePolicy | Error                  | Expected App Behavior     |
-| ------------ | ----------- | -------------- | ---------------------- | ------------------------- |
-| Success      | true        | true           | nil                    | Proceed                   |
-| User cancel  | true        | false          | `.userCancel`          | Retry or abort gracefully |
-| Lockout      | true        | false          | `.biometryLockout`     | Fallback to passcode      |
-| Not enrolled | false       | n/a            | `.biometryNotEnrolled` | Show enrollment guidance  |
+Scenarios to cover:
+
+| Case | Error | Expected handling |
+| --- | --- | --- |
+| Success | none | Proceed |
+| User cancels | `.userCancel` | Offer retry or abort |
+| Too many failures | `.biometryLockout` | Fall back to the device passcode |
+| Nothing enrolled | `.biometryNotEnrolled` | Explain how to enrol |
 
 ```swift
-func testBiometricAuthSuccess() {
-    let mock = MockBiometricContext()
-    mock.canEvaluateResult = true
-    mock.evaluateResult = true
-    let manager = BiometricAuthManager(context: mock)
-
-    let exp = expectation(description: "auth")
-    manager.authenticate(reason: "Test") { result in
-        if case .failure = result { XCTFail("Expected success") }
-        exp.fulfill()
-    }
-    waitForExpectations(timeout: 1)
-    XCTAssertTrue(mock.evaluateCalled)
+func testUnavailableBiometrics_NeverEvaluates() async {
+    let stub = StubBiometricContext()
+    stub.available = false
+    let done = expectation(description: "completion")
+    BiometricPrompt(context: stub).confirm(reason: "Approve transfer") { outcome in
+        if case .success = outcome { XCTFail("Expected a failure") }
+        done.fulfill()
+    }
+    await fulfillment(of: [done], timeout: 1)
+    XCTAssertFalse(stub.evaluateCalled)
 }
+```
 
-func testBiometricAuthUnavailable() {
-    let mock = MockBiometricContext()
-    mock.canEvaluateResult = false
-    let manager = BiometricAuthManager(context: mock)
+The completion checks the result with `if case` rather than
+`XCTAssertThrowsError(try outcome.get())`: a `try` anywhere in a closure body
+makes Swift infer the closure as throwing, and `finish` is non-throwing. The
+test is `async` and awaits `fulfillment(of:)` because `waitForExpectations` is
+main-actor isolated.
 
-    let exp = expectation(description: "unavailable")
-    manager.authenticate(reason: "Test") { result in
-        if case .success = result { XCTFail("Expected failure") }
-        exp.fulfill()
-    }
-    waitForExpectations(timeout: 1)
-    XCTAssertFalse(mock.evaluateCalled)  // Should not attempt auth
-}
-```
+## CI configuration
 
----
-
-## CI/CD Pipeline Configuration
-
-Running keychain tests in CI is the most error-prone part. The `-25308` (`errSecInteractionNotAllowed`) error is the most common CI failure  -  keychain locked or requires GUI interaction in a headless environment.
-
-### GitHub Actions
-
-```yaml
-name: iOS CI
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: macos-latest
-    steps:
-      - uses: actions/checkout@v5
-      - name: Create temporary keychain
-        env:
-          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
-        run: |
-          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
-          security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
-          security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
-          security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
-          security list-keychain -d user -s $KEYCHAIN_PATH
-          # Import cert + CRITICAL partition list step
-          echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $RUNNER_TEMP/cert.p12
-          security import $RUNNER_TEMP/cert.p12 -P "$P12_PASSWORD" \
-            -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
-          security set-key-partition-list -S apple-tool:,apple: \
-            -k "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
-      - name: Run simulator-safe tests
-        run: |
-          xcodebuild test -scheme MyApp \
-            -destination 'platform=iOS Simulator,name=iPhone 16' \
-            -testPlan CITests
-      - name: Cleanup
-        if: always()
-        run: security delete-keychain $RUNNER_TEMP/app-signing.keychain-db
+`errSecInteractionNotAllowed` (-25308) is the error CI runs hit most: the runner's keychain is locked, or the operation wants a GUI that a headless session does not have.
+
+Signing setup on a hosted macOS runner:
+
+```sh
+KC="${RUNNER_TEMP:-$TMPDIR}/ci-signing.keychain-db"
+security create-keychain -p "$KC_PASSWORD" "$KC"
+security set-keychain-settings -l -u -t 21600 "$KC"
+security unlock-keychain -p "$KC_PASSWORD" "$KC"
+security list-keychains -s "$KC" -d user
+security import signing.p12 -k "$KC" -f pkcs12 -t cert -A -P "$P12_PASSWORD"
+security set-key-partition-list -s -k "$KC_PASSWORD" -S apple-tool:,apple: "$KC"
+
+xcodebuild test -scheme Vault -testPlan CITests \
+  -destination "platform=iOS Simulator,name=$SIM_NAME"
+
+# always-run cleanup step
+security delete-keychain "$KC"
 ```
 
-**`security set-key-partition-list` must be called after importing certificates**  -  this is the step most people miss. Without it, `codesign` hangs indefinitely waiting for a GUI prompt. The `-A` flag on import grants access to all applications, necessary in CI.
+`set-key-partition-list` after the import is the step people miss. Without it `codesign` waits for a GUI confirmation that never comes and the job hangs. `-A` on the import grants every application access to the key, which is acceptable only for a throwaway CI keychain.
 
-**Xcode Cloud:** Uses ephemeral environments  -  no manual `security create-keychain`. Apple manages signing automatically. Ensure Keychain Sharing capability is enabled. The `-25308` error is common when SPM tries to save credentials.
+Xcode Cloud builds on ephemeral machines with managed signing, so there is no keychain to configure by hand. Enable Keychain Sharing on the test host, and expect -25308 when Swift Package Manager tries to save repository credentials.
 
-**Fastlane:** `setup_ci` creates a temporary `fastlane_tmp_keychain` and sets it as default. On self-hosted runners, this can interfere with the host machine's keychain.
+fastlane's `setup_ci` creates a temporary keychain named `fastlane_tmp_keychain` and makes it the default, which can disturb the login keychain on a self-hosted runner.
 
 ```ruby
-lane :ci_test do
+lane :ci_tests do
   setup_ci(timeout: 3600)
   sync_code_signing(type: "development", readonly: is_ci)
-  run_tests(scheme: "MyApp", testplan: "CITests", device: "iPhone 16")
+  run_tests(scheme: "Vault", testplan: "CITests", device: "iPhone 16")
 end
 ```
 
-### Common CI Error Reference
-
-| Error                         | OSStatus | Cause                                 | Fix                                             |
-| ----------------------------- | -------- | ------------------------------------- | ----------------------------------------------- |
-| `errSecInteractionNotAllowed` | -25308   | Keychain locked / needs GUI           | Unlock keychain + `set-key-partition-list`      |
-| `errSecMissingEntitlement`    | -34018   | No keychain-access-groups entitlement | Add entitlements to test host app               |
-| `errSecItemNotFound`          | -25300   | No test host or missing entitlement   | Use test host app with keychain capability      |
-| `errSecInternalComponent`     | -67585   | Partition list not set after import   | Call `set-key-partition-list` after cert import |
-| Default keychain not found    | -25307   | No default keychain on CI runner      | Create and set default keychain                 |
-
-### Test Host App Requirement
-
-Since Xcode 9, test bundles on iOS simulator require a host app to access the keychain. Without one, `SecItemAdd` returns `-25300` or `-34018`. Create a minimal iOS app target, enable the Keychain Sharing capability, and set the test target's **Test Host** and **Bundle Loader** build settings to point at it.
-
----
+| Status | Meaning on CI | Fix |
+| --- | --- | --- |
+| -25308 | Keychain locked or needs UI | Unlock it and set the partition list |
+| -34018 | Missing entitlement | Give the test host the keychain entitlement |
+| -25300 | Item not found, often no host app | Run tests inside a host app with the Keychain capability |
+| -67585 | `errSecInternalComponent` | The import happened but no partition list was applied |
+| -25307 | No default keychain | Create one and set it as default |
 
-## Xcode Test Plans  -  Separating Simulator from Device
+For the test host, add an almost empty iOS app target and turn on Keychain Sharing for it. Then set `TEST_HOST` and `BUNDLE_LOADER` on the test target so the bundle loads inside that app.
 
-Create two test plans for CI/device split:
+## Test plans
 
-- **CITests.xctestplan**: Only tests using `MockKeychainService` and simulator-safe CryptoKit. Skips integration, biometric, and SE tests.
-- **DeviceTests.xctestplan**: Real keychain integration, Secure Enclave, and biometric hardware tests. Requires physical device.
+- `CITests.xctestplan`: mock keychain and Simulator-safe CryptoKit tests only.
+- `DeviceTests.xctestplan`: real keychain, Secure Enclave, biometric hardware; runs on a physical device.
 
-```bash
-# CI: simulator-safe tests on every push
-xcodebuild test -scheme MyApp \
-  -destination 'platform=iOS Simulator,name=iPhone 16' \
-  -testPlan CITests
-
-# Nightly: device farm runs everything
-xcodebuild test -scheme MyApp \
-  -destination 'platform=iOS,id=DEVICE_UDID' \
-  -testPlan DeviceTests
+```sh
+xcodebuild test -scheme Vault -testPlan CITests -destination "platform=iOS Simulator,name=$SIM_NAME"
+xcodebuild test -scheme Vault -testPlan DeviceTests -destination 'platform=iOS,id=<UDID>'
 ```
 
----
-
-## Swift Testing Framework Patterns
+Run the first on every push and the second nightly on a device farm.
 
-Swift Testing (WWDC24) introduces tags, traits, and parameterized tests that map well to security test organization:
+## Swift Testing
 
 ```swift
 import Testing
-@testable import MyApp
 
 extension Tag {
     @Tag static var keychain: Self
@@ -658,156 +465,89 @@ extension Tag {
 }
 
 @Suite(.serialized, .tags(.keychain))
-struct KeychainTests {
-
-    @Test("Save and retrieve round-trip", .tags(.ciSafe))
-    func saveAndRetrieve() throws {
-        let mock = MockKeychainService()
-        let manager = AuthenticationManager(keychain: mock)
-        try manager.storeToken("test-token")
-        let result = try #require(try manager.retrieveToken())
-        #expect(result == "test-token")
+struct VaultTests {
+    @Test(.tags(.ciSafe))
+    func rememberedTokenIsReadable() throws {
+        let keeper = SessionKeeper(store: InMemorySecretStore())
+        try keeper.remember(token: "t-1")
+        let token = try #require(try keeper.currentToken())
+        #expect(token == "t-1")
     }
 
-    @Test("Device-only: real keychain integration",
-          .enabled(if: ProcessInfo.processInfo.environment["CI"] == nil),
-          .tags(.deviceOnly))
-    func realKeychainIntegration() throws {
-        let keychain = KeychainService(service: "com.test.swift-testing")
-        try keychain.deleteAll()
-        defer { try? keychain.deleteAll() }
-        try keychain.save("token".data(using: .utf8)!, forKey: "key")
-        let data = try #require(try keychain.read(forKey: "key"))
-        #expect(String(data: data, encoding: .utf8) == "token")
+    static let onBuildServer = ProcessInfo.processInfo.environment["CI"] != nil
+
+    @Test(.tags(.deviceOnly), .enabled(if: !onBuildServer))
+    func realKeychainRoundTrip() throws {
+        let store = KeychainSecretStore(service: "tests.vault.swift-testing")
+        try store.removeAll()
+        defer { try? store.removeAll() }
+        try store.put(Data("x".utf8), for: "k")
+        #expect(try store.value(for: "k") == Data("x".utf8))
     }
 
-    @Test("Parameterized error paths",
-          arguments: [
-              KeychainError.duplicateItem,
-              KeychainError.itemNotFound,
-              KeychainError.authFailed,
-              KeychainError.interactionNotAllowed
-          ])
-    func errorPathHandling(expectedError: KeychainError) {
-        let mock = MockKeychainService()
-        mock.errorToThrow = expectedError
-        #expect(throws: KeychainError.self) {
-            try mock.read(forKey: "any-key")
-        }
+    @Test(arguments: [VaultStoreError.duplicateItem, .authFailed, .userCanceled, .interactionNotAllowed])
+    func injectedFailuresPropagate(_ failure: VaultStoreError) {
+        let mock = InMemorySecretStore()
+        mock.failure = failure
+        #expect(throws: VaultStoreError.self) { try SessionKeeper(store: mock).remember(token: "t") }
     }
 }
 ```
 
-The `.serialized` trait ensures keychain tests modifying shared state run sequentially. Tags integrate with test plans for filtering  -  `.ciSafe` tests run in CI, `.deviceOnly` tests run on device farms.
+`.serialized` keeps tests that share keychain state from running in parallel. Test plans can include or exclude by tag: `ciSafe` on CI, `deviceOnly` on the device farm.
 
----
+## Further techniques
 
-## Advanced Patterns
-
-### Migration Testing: UserDefaults to Keychain
-
-Migration code is security-critical  -  silent failure leaves credentials in UserDefaults (see `migration-legacy-stores.md`). The class under test accepts injected dependencies for both stores:
+**Migration tests.** Inject both stores: an isolated `UserDefaults(suiteName:)` cleared with `removePersistentDomain(forName:)` and the mock keychain. Assert the value arrived, was read back, and is gone from the source.
 
 ```swift
-final class StorageMigrationManager {
-    private let defaults: UserDefaults
-    private let keychain: KeychainServiceProtocol
-
-    init(defaults: UserDefaults = .standard,
-         keychain: KeychainServiceProtocol) {
-        self.defaults = defaults
-        self.keychain = keychain
-    }
+func testMigrationMovesAndVerifies() throws {
+    let suiteName = "tests.migration"
+    let defaults = try XCTUnwrap(UserDefaults(suiteName: suiteName))
+    defaults.removePersistentDomain(forName: suiteName)
+    defaults.set("legacy-token", forKey: "token")
+    let store = InMemorySecretStore()
 
-    func migrateIfNeeded() throws {
-        let version = defaults.integer(forKey: "migration_version")
-        if version < 1 {
-            if let token = defaults.string(forKey: "auth_token"),
-               let data = token.data(using: .utf8) {
-                try keychain.save(data, forKey: "auth_token")
-                defaults.removeObject(forKey: "auth_token")
-            }
-        }
-        defaults.set(1, forKey: "migration_version")
-    }
-}
-```
-
-Test with isolated `UserDefaults(suiteName:)` and mock keychain:
+    try LegacyTokenMigrator(defaults: defaults, store: store).run()
 
-```swift
-func testMigrationMovesTokenToKeychain() throws {
-    let defaults = UserDefaults(suiteName: "migration-test")!
-    defaults.removePersistentDomain(forName: "migration-test")
-    defaults.set("my-secret", forKey: "auth_token")
-    defaults.set(0, forKey: "migration_version")
-
-    let mock = MockKeychainService()
-    let migrator = StorageMigrationManager(defaults: defaults, keychain: mock)
-    try migrator.migrateIfNeeded()
-
-    // Token moved to keychain, removed from UserDefaults
-    XCTAssertEqual(String(data: mock.storage["auth_token"]!, encoding: .utf8), "my-secret")
-    XCTAssertNil(defaults.string(forKey: "auth_token"))
+    XCTAssertEqual(try store.value(for: "token"), Data("legacy-token".utf8))
+    XCTAssertNil(defaults.string(forKey: "token"))
 }
 ```
 
-### Performance Testing
+`LegacyTokenMigrator` saves, reads back and compares, and removes the `UserDefaults` value only after the comparison succeeds, as in [migration-legacy-stores.md](migration-legacy-stores.md).
 
-```swift
-func testKeychainWritePerformance() {
-    let keychain = KeychainService(service: "com.test.perf")
-    let options = XCTMeasureOptions()
-    options.iterationCount = 20
-
-    measure(metrics: [XCTClockMetric(), XCTCPUMetric()], options: options) {
-        let data = UUID().uuidString.data(using: .utf8)!
-        try? keychain.save(data, forKey: "perf-key")
-        try? keychain.delete(forKey: "perf-key")
-    }
-}
-```
-
-### Mutation Testing
-
-Mutation testing introduces deliberate bugs (flipping `==` to `!=`, removing `SecItemDelete` calls, swapping `&&` to `||`) and checks whether your tests catch them. A project can have 81% code coverage but only 16% mutation score  -  tests execute security code without validating it does the right thing.
-
-**Muter** (`brew install muter-mutation-testing/muter/muter`) is the primary Swift mutation testing tool. Its `RelationalOperatorReplacement` operator catches authentication bypasses; `RemoveSideEffects` catches missing `SecItemDelete` calls in logout flows. For security code, target mutation score above **80%**.
-
-### OWASP MASTG Keychain Validation
-
-MASTG-TEST-0052 requires that sensitive data use the Keychain, not `NSUserDefaults` or `.plist` files. OWASP also documents that keychain data persists after app uninstallation  -  the app sandbox is wiped but keychain items remain. Standard mitigation is a fresh-install detector (see `common-anti-patterns.md`):
+**Performance.**
 
 ```swift
-static func handleFreshInstall(keychain: KeychainServiceProtocol) {
-    let hasLaunched = UserDefaults.standard.bool(forKey: "has_launched")
-    if !hasLaunched {
-        try? keychain.deleteAll()
-        UserDefaults.standard.set(true, forKey: "has_launched")
+func testSaveDeleteCost() {
+    let runs = XCTMeasureOptions()
+    runs.iterationCount = 20
+    measure(metrics: [XCTCPUMetric(), XCTClockMetric()], options: runs) {
+        try? store.put(Data(count: 64), for: "perf")
+        try? store.remove(for: "perf")
     }
 }
 ```
 
----
-
-## Conclusion
+**Mutation testing.** Coverage says code ran, not that a test would notice it changing. Mutations such as flipping `==` and `!=`, deleting a `SecItemDelete` call or swapping `&&` and `||` expose the gap; a project can show 81% line coverage and a 16% mutation score. Muter, installed with Homebrew from the `muter-mutation-testing/muter` tap, provides the operators: `RelationalOperatorReplacement` finds inverted checks that would become authentication bypasses, and `RemoveSideEffects` finds logout paths whose deletes nobody verifies. Aim for a mutation score above 80%.
 
-Protocol-abstraction is non-negotiable for testable keychain code. Every `SecItem` call should be behind `KeychainServiceProtocol` so that 95%+ of your test suite runs against `MockKeychainService` with zero entitlement requirements and zero CI flakiness. Reserve real-keychain integration tests for a dedicated test plan on physical devices.
+**MASTG-TEST-0052.** Sensitive data must be in the keychain, not in `NSUserDefaults` or property lists, and because the keychain survives uninstall the app needs a fresh-install detector: a `has_launched` marker that triggers `removeAll()` when missing, run after protected data is available.
 
-Three insights most guides miss: (1) the simulator silently returns biometric-protected items without prompting  -  tests appear to validate biometric gates but test nothing; (2) TN3137's distinction between file-based and data protection keychains means `security create-keychain` in CI creates the wrong keychain type; (3) mutation testing reveals that even high-coverage suites fail to catch inverted conditionals and removed side effects  -  the exact mutations that create real vulnerabilities.
+## Takeaways
 
----
+Aim for more than 95% of the suite running against the mock with no entitlements at all, and keep real-keychain tests in the device test plan. Three facts are easy to miss: on Simulator a Face ID or Touch ID protected item comes back with no prompt at all, `security create-keychain` makes a keychain of the wrong type for iOS-style tests, and mutation testing finds inverted conditions and removed side effects that coverage does not.
 
-## Summary Checklist
+## Checklist
 
-1. **Protocol abstraction**  -  All keychain access goes through `KeychainServiceProtocol`; no direct `SecItem*` calls in business logic
-2. **Mock with injectable errors**  -  `MockKeychainService` supports `errorToThrow` for testing `errSecDuplicateItem`, `errSecAuthFailed`, `errSecInteractionNotAllowed`, and `errSecItemNotFound` paths
-3. **setUp/tearDown cleanup**  -  Every integration test using real keychain has both pre-test and post-test cleanup with a test-specific `kSecAttrService`
-4. **Secure Enclave guard**  -  All SE tests use `try XCTSkipUnless(SecureEnclave.isAvailable, ...)` or protocol-based fallback; never call `SecureEnclave.P256.*` unconditionally
-5. **Biometric mock**  -  `LAContext` wrapped behind protocol or subclass mock; tests cover success, user cancel, lockout, and not-enrolled scenarios
-6. **Simulator/device split**  -  Two Xcode test plans: `CITests` (mock-based, simulator-safe) and `DeviceTests` (real keychain, SE, biometrics on physical device)
-7. **CI keychain setup**  -  GitHub Actions calls `security set-key-partition-list` after cert import; test target has host app with Keychain Sharing capability enabled
-8. **CryptoKit round-trips**  -  Encrypt→decrypt and sign→verify tests for AES-GCM, ChaChaPoly, P256, Curve25519; wrong-key failure tests included
-9. **Error path coverage**  -  Every `OSStatus` code the app can encounter has a corresponding test with injected mock failure
-10. **Migration testing**  -  UserDefaults→Keychain migration tested with isolated `UserDefaults(suiteName:)` and mock keychain; verifies source cleared after migration
-11. **Mutation testing baseline**  -  Muter mutation score ≥80% for security-critical code paths; `RelationalOperatorReplacement` and `RemoveSideEffects` operators enabled
+- [ ] All keychain access goes through the `SecretStore` protocol.
+- [ ] The mock can inject duplicate, auth-failed, user-canceled, interaction-not-allowed and not-found failures.
+- [ ] Real-keychain tests use their own service and clean up in `setUp` and `tearDown`.
+- [ ] Secure Enclave tests are compiled out or skipped on Simulator, check `SecureEnclave.isAvailable` on hardware, or go through the protocol fallback.
+- [ ] `LAContext` is behind a protocol; success, cancel, lockout and not-enrolled are covered.
+- [ ] Two test plans: `CITests` and `DeviceTests`.
+- [ ] CI sets the key partition list after importing certificates; the test host has Keychain Sharing.
+- [ ] CryptoKit round trips for AES-GCM, ChaChaPoly, P256 and Curve25519, each with a wrong-key or tampered-input case.
+- [ ] Every reachable `OSStatus` has an injected-failure test.
+- [ ] Migration tests use an isolated suite and the mock, and check the source is cleared after verification.
+- [ ] Muter reports at least 80% with `RelationalOperatorReplacement` and `RemoveSideEffects`.