@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/migration-legacy-stores.md

@@ -1,747 +1,509 @@
-# Migration & Legacy Stores
+# Migrating Secrets Out of Legacy Stores
 
-> **Scope:** Migrating sensitive data from UserDefaults, plists, NSCoding archives, and other insecure storage to Apple Keychain Services. Covers secure deletion of legacy data, first-launch keychain cleanup, versioned migration patterns, and the Team ID transfer edge case.
->
-> **Applies to:** iOS 15+ (actor support, pre-warming), iOS 17+ (recommended deployment target)
->
-> **Cross-references:** `keychain-fundamentals.md` (SecItem CRUD), `keychain-access-control.md` (accessibility classes), `common-anti-patterns.md` (UserDefaults secrets anti-pattern), `credential-storage-patterns.md` (token lifecycle post-migration), `testing-security-code.md` (protocol-based mocking)
+Scope: moving credentials that an older release kept in `UserDefaults`, property lists or `NSCoding` archives into the keychain, deleting the old copies safely, wiping keychain leftovers after a reinstall, running migrations by schema version, and surviving a Team ID change after an app transfer.
 
----
+Availability: the patterns rely on actors and on iOS 15 pre-warming behaviour, so they apply from iOS 15. Write new code against iOS 17 or later where you can.
 
-## Contents
-
-- [Why Migrate  -  The Risk of Legacy Storage](#why-migrate-the-risk-of-legacy-storage)
-- [The Five Correctness Traps](#the-five-correctness-traps)
-- [First-Launch Keychain Cleanup](#first-launch-keychain-cleanup)
-- [Atomic Migration: Read → Write → Verify → Delete](#atomic-migration-read-write-verify-delete)
-- [Versioned Migration with Schema Tracking](#versioned-migration-with-schema-tracking)
-- [Orphaned Items: Why You Must Never Rename kSecAttrService](#orphaned-items-why-you-must-never-rename-ksecattrservice)
-- [Background Launch and the Locked-Device Trap](#background-launch-and-the-locked-device-trap)
-- [The Phantom Mismatch Bug](#the-phantom-mismatch-bug)
-- [Team ID Change: The App Transfer Edge Case](#team-id-change-the-app-transfer-edge-case)
-- [Deferred Legacy Cleanup with Rollback Window](#deferred-legacy-cleanup-with-rollback-window)
-- [Complete App Launch Sequence](#complete-app-launch-sequence)
-- [Thread Safety Note](#thread-safety-note)
-- [Testing Migration Paths](#testing-migration-paths)
-- [Handling Very Old Versions and Collapse Strategy](#handling-very-old-versions-and-collapse-strategy)
-- [Secure Deletion: Trust Cryptographic Erasure](#secure-deletion-trust-cryptographic-erasure)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## Why Migrate  -  The Risk of Legacy Storage
-
-UserDefaults, `.plist` files, and NSCoding archives store data as unencrypted plaintext within the app sandbox. This data is readable on jailbroken devices and included in unencrypted iTunes/Finder backups  -  anyone with backup access can extract tokens, passwords, and PII. OWASP ranks insecure data storage as a top-10 mobile risk (M9).
+Related references: [keychain-fundamentals.md](keychain-fundamentals.md) (add-or-update, OSStatus), [keychain-access-control.md](keychain-access-control.md) (accessibility classes), [common-anti-patterns.md](common-anti-patterns.md) (patterns 1 and 9), [credential-storage-patterns.md](credential-storage-patterns.md) (token lifecycles), [testing-security-code.md](testing-security-code.md) (mocks and device tests).
 
-| Store             | Encrypted at rest | In backups                         | Survives app uninstall | Suitable for secrets |
-| ----------------- | ----------------- | ---------------------------------- | ---------------------- | -------------------- |
-| UserDefaults      | No                | Yes                                | No                     | **No**               |
-| .plist files      | No (default)      | Yes                                | No                     | **No**               |
-| NSCoding archives | No (default)      | Yes                                | No                     | **No**               |
-| Keychain          | Yes (AES-256-GCM) | `ThisDeviceOnly` variants excluded | **Yes**                | **Yes**              |
-
-Keychain items are managed by the `securityd` daemon, encrypted with per-row keys protected by the Secure Enclave, and isolated from the app sandbox. This is the only appropriate location for tokens, passwords, API keys, and PII on Apple platforms.
+## Contents
 
----
+- [Why the old stores are not acceptable](#why-the-old-stores-are-not-acceptable)
+- [Five traps to avoid](#five-traps-to-avoid)
+- [Cleaning up after a reinstall](#cleaning-up-after-a-reinstall)
+- [Atomic migration: read, write, verify, delete](#atomic-migration-read-write-verify-delete)
+- [Versioned migration with a schema number](#versioned-migration-with-a-schema-number)
+- [Orphaned items after a rename](#orphaned-items-after-a-rename)
+- [Locked devices and background launches](#locked-devices-and-background-launches)
+- [The phantom mismatch](#the-phantom-mismatch)
+- [Team ID change after an app transfer](#team-id-change-after-an-app-transfer)
+- [Cleaning up legacy artefacts](#cleaning-up-legacy-artefacts)
+- [Launch order](#launch-order)
+- [Concurrency](#concurrency)
+- [Testing migrations](#testing-migrations)
+- [Very old versions](#very-old-versions)
+- [Deleting files](#deleting-files)
+- [Key decisions](#key-decisions)
+- [Checklist](#checklist)
 
-## The Five Correctness Traps
+## Why the old stores are not acceptable
 
-Most AI-generated migration code contains at least one of these errors. Each passes testing but fails catastrophically in production.
+`UserDefaults`, a hand-written `.plist` and a keyed archive are all plain files inside the app container. Nothing encrypts their contents beyond the file's data protection class, so anyone with a jailbroken device or an unencrypted Finder or iTunes backup can open them. OWASP files this under M9, Insecure Data Storage.
 
-**Trap 1  -  Legacy data survives after migration.** Calling `UserDefaults.standard.removeObject(forKey:)` removes the key-value pair from the in-memory cache and plist file, but does not securely overwrite NAND flash. However, iOS achieves secure deletion through _cryptographic erasure_: every file has a per-file AES-256 key, and standard deletion APIs destroy that key via Effaceable Storage, rendering physical bits permanently inaccessible. The real risk vector is **unencrypted backups** created before migration completes  -  the plist stays on disk until the filesystem reclaims space. **Always delete all legacy keys explicitly after verified keychain writes.**
+| Property | UserDefaults / plist / NSCoding archive | Keychain |
+| --- | --- | --- |
+| Encryption of the value | None beyond file protection | AES-256-GCM per item |
+| Included in backups | Yes | Yes, except `...ThisDeviceOnly` classes |
+| Removed when the app is deleted | Yes | No, items outlive the app |
+| Fit for secrets | No | Yes |
 
-**Trap 2  -  Keychain items survive app deletion.** When a user uninstalls your app, UserDefaults and sandbox files are wiped, but keychain items persist indefinitely. Apple attempted to change this in iOS 10.3 betas but reverted due to compatibility issues. On reinstall, stale keychain items (old tokens, expired credentials, outdated schemas) cause silent authentication failures or  -  worse  -  restore a _previous user's_ session.
+Keychain rows live in a database owned by the `securityd` daemon, outside the app sandbox. Each row is encrypted with its own key, and those keys are wrapped by class keys that the Secure Enclave protects.
 
-**Trap 3  -  Migration runs on every launch.** Checking UserDefaults for legacy data on every launch wastes cycles and risks data loss during iOS 15+ app pre-warming. When the system pre-warms your process before the device is unlocked, `UserDefaults` may return empty values (the encrypted plist is inaccessible). A migration that interprets empty results as "nothing to migrate" will skip real data or overwrite valid keychain entries with nil.
+## Five traps to avoid
 
-**Trap 4  -  Non-atomic migration leaves data in limbo.** Writing to keychain then deleting from UserDefaults as two independent operations creates a failure window. If the app is killed between write and delete  -  or the keychain write silently fails  -  users lose their data entirely.
+1. **Believing deletion is the risk.** `removeObject(forKey:)` does not scrub flash storage, but it does not need to: iOS protects each file with its own AES-256 key and destroys that key through Effaceable Storage when the file goes away, which is cryptographic erasure. The exposure that remains is backups taken, unencrypted, before the migration ran. Delete each legacy key explicitly once its keychain copy is verified.
+2. **Forgetting that keychain items outlive the app.** An iOS 10.3 beta briefly removed items on uninstall; the change was reverted and items still persist. After a reinstall, stale entries cause confusing authentication failures or silently resume the previous owner's session.
+3. **Migrating on every launch.** Besides wasted work, a pre-warmed launch on iOS 15 and later can start before first unlock, when the encrypted `UserDefaults` file cannot be read and returns nothing. Code that reads "empty" as "nothing to migrate" skips data or writes nil over good keychain values.
+4. **Treating write and delete as unrelated steps.** If the process dies between them, or the write failed silently, the secret is gone.
+5. **Renaming the item's identity.** Changing `kSecAttrService` or `kSecAttrAccount` produces a new item and strands the old one as a duplicate. `SecItemUpdate` cannot change primary-key attributes, so a rename is always read old, write new, verify, delete old.
 
-**Trap 5  -  Changing `kSecAttrService` or `kSecAttrAccount` orphans existing items.** These attributes form the primary key for `kSecClassGenericPassword`. Changing either in a new version doesn't update existing items  -  it creates new ones. The old items become invisible orphans that waste keychain space and cause `errSecDuplicateItem` in unexpected contexts. Critically, `SecItemUpdate` **cannot change primary key attributes**  -  the call will error. You must perform a full rekey migration: read old → write new → verify → delete old.
+## Cleaning up after a reinstall
 
----
+The two stores behave differently on uninstall: `UserDefaults` is removed, the keychain is not. A missing marker in `UserDefaults` together with keychain content therefore means "fresh install over old data".
 
-## First-Launch Keychain Cleanup
+Run this before anything else touches the keychain. Analytics, crash reporting, backend-as-a-service and authentication SDKs often read the keychain while they initialise, and would pick up the old session.
 
-The persistence asymmetry (UserDefaults deleted on uninstall, keychain not) enables a reliable reinstall detector. This pattern **must run before any other keychain or SDK initialization**  -  Firebase, analytics, and auth libraries all read keychain items during setup.
+Wait for protected data before reading the marker. During pre-warm both `UserDefaults` and `WhenUnlocked` keychain items are unreadable, so the marker looks unset and the guard would wipe a signed-in user. Widely used apps mass-logged-out their users on iOS 15 by treating that empty read as "no credentials".
 
 ```swift
-// ✅ CORRECT: First-launch cleanup with protected data guard
-// iOS 15+ required for isProtectedDataAvailable / pre-warming behavior
-
-actor FirstLaunchGuard {
-    static let shared = FirstLaunchGuard()
-    private let hasRunKey = "com.myapp.hasCompletedFirstLaunch"
-
-    /// Call at the very start of app lifecycle, before SDK initialization.
-    func performCleanupIfNeeded() async {
-        let isSubsequentRun = UserDefaults.standard.bool(forKey: hasRunKey)
-        guard !isSubsequentRun else { return }
-
-        // iOS 15+ pre-warming guard: device may still be locked
-        guard await isProtectedDataAvailable() else {
-            await waitForProtectedData()
-            return
-        }
-
-        // Wipe stale keychain items from a previous installation
-        deleteAllKeychainItems()
-
-        // Set flag so this only runs once per install
-        UserDefaults.standard.set(true, forKey: hasRunKey)
-    }
-
-    private func deleteAllKeychainItems() {
-        let classes: [CFString] = [
-            kSecClassGenericPassword, kSecClassInternetPassword,
-            kSecClassCertificate, kSecClassKey, kSecClassIdentity
-        ]
-        for itemClass in classes {
-            let query: NSDictionary = [
+import Security
+import UIKit
+
+actor ReinstallSweeper {
+    private let markerKey = "vault.installMarker"
+    private let itemClasses: [CFString] = [
+        kSecClassGenericPassword, kSecClassInternetPassword,
+        kSecClassCertificate, kSecClassKey, kSecClassIdentity
+    ]
+
+    func sweepIfFreshInstall() async {
+        await Self.waitUntilProtectedDataIsReadable()
+        guard !UserDefaults.standard.bool(forKey: markerKey) else { return }
+        for itemClass in itemClasses {
+            let scope: [CFString: Any] = [
                 kSecClass: itemClass,
                 kSecAttrSynchronizable: kSecAttrSynchronizableAny
             ]
-            SecItemDelete(query)
+            let status = SecItemDelete(scope as CFDictionary)
+            guard status == errSecSuccess || status == errSecItemNotFound else { return }
         }
+        UserDefaults.standard.set(true, forKey: markerKey)
     }
 
-    private func isProtectedDataAvailable() async -> Bool {
-        await MainActor.run {
-            UIApplication.shared.isProtectedDataAvailable
-        }
-    }
-
-    private func waitForProtectedData() async {
-        await withCheckedContinuation { continuation in
-            NotificationCenter.default.addObserver(
-                forName: UIApplication.protectedDataDidBecomeAvailableNotification,
-                object: nil, queue: .main
-            ) { _ in
-                Task {
-                    self.deleteAllKeychainItems()
-                    UserDefaults.standard.set(true, forKey: self.hasRunKey)
-                    continuation.resume()
-                }
-            }
-        }
+    @MainActor
+    static func waitUntilProtectedDataIsReadable() async {
+        guard !UIApplication.shared.isProtectedDataAvailable else { return }
+        let signals = NotificationCenter.default.notifications(
+            named: UIApplication.protectedDataDidBecomeAvailableNotification
+        )
+        for await _ in signals { return }
     }
 }
 ```
 
+`kSecAttrSynchronizable: kSecAttrSynchronizableAny` is required in every cleanup query. Without it `SecItemDelete` only matches non-synchronized items and leaves iCloud Keychain entries behind. If any delete fails, the marker stays unset and the sweep runs again next launch.
+
+What goes wrong without it:
+
 ```swift
-// ❌ INCORRECT: No first-launch cleanup  -  stale keychain from previous install
 @main
-struct BrokenApp: App {
+struct LedgerApp: App {
     init() {
-        // Reads keychain without checking for stale data
-        if let token = try? keychainRead(service: "com.myapp", account: "authToken") {
-            // This token might be from a PREVIOUS user who deleted the app.
-            // The new user inherits someone else's session.
-            AuthManager.shared.restoreSession(token: token)
-        }
+        SessionStore.shared.restoreTokenFromKeychain()
     }
-    var body: some Scene { WindowGroup { ContentView() } }
+    var body: some Scene { WindowGroup { RootView() } }
 }
 ```
 
-The `isProtectedDataAvailable` check is critical. iOS 15 introduced app pre-warming  -  the system can launch your process before the user unlocks the device. During pre-warming, both UserDefaults and keychain items with `kSecAttrAccessibleWhenUnlocked` are unavailable. Multiple high-profile apps (including Twitter) suffered mass user logouts on iOS 15 because their startup code interpreted empty data during pre-warm as "no credentials" and wiped sessions.
+Here the token is restored with no reinstall check, so a new owner of a resold device, or a different person on a reinstalled app, inherits the previous session.
 
-> **Include `kSecAttrSynchronizableAny`** in cleanup queries. Without it, `SecItemDelete` skips iCloud-synced items, leaving them as invisible ghosts.
+## Atomic migration: read, write, verify, delete
 
----
+The order never changes. Removing the plaintext before the keychain write is confirmed is the single most dangerous mistake in this area.
 
-## Atomic Migration: Read → Write → Verify → Delete
+```swift
+import Foundation
+import Security
 
-The most dangerous pattern is deleting legacy data before confirming the keychain write succeeded. The correct sequence is always: **read → write → verify → delete**.
+protocol MigrationKeychainProtocol: Actor {
+    func save(_ data: Data, account: String, accessibility: String) throws
+    func read(account: String) throws -> Data?
+    func delete(account: String) throws
+    func deleteAll() throws
+}
 
-```swift
-// ✅ CORRECT: Atomic per-key migration with verification and rollback
-actor AtomicMigrator {
-    struct MigrationResult {
-        let key: String
-        let succeeded: Bool
-        let error: Error?
-    }
+struct KeychainFailure: Error {
+    let status: OSStatus
+    init(_ status: OSStatus) { self.status = status }
+}
 
-    private let keychain: any MigrationKeychainProtocol
+enum KeyMigrationResult: Sendable, Equatable {
+    case moved, nothingToMove, failed(reason: String)
+}
 
-    init(keychain: any MigrationKeychainProtocol) {
-        self.keychain = keychain
-    }
+actor DefaultsToKeychainMover {
+    private let vault: any MigrationKeychainProtocol
+    private let defaults: UserDefaults
 
-    /// Failed keys remain in UserDefaults for retry on next launch.
-    func migrateUserDefaultsKeys(
-        _ keys: [String],
-        service: String,
-        accessible: CFString = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
-    ) async -> [MigrationResult] {
-        var results: [MigrationResult] = []
+    init(vault: any MigrationKeychainProtocol, defaults: UserDefaults = .standard) {
+        self.vault = vault
+        self.defaults = defaults
+    }
 
+    func move(keys: [String]) async -> [String: KeyMigrationResult] {
+        var report: [String: KeyMigrationResult] = [:]
         for key in keys {
+            guard let plaintext = defaults.string(forKey: key) else {
+                report[key] = .nothingToMove
+                continue
+            }
+            let payload = Data(plaintext.utf8)
             do {
-                // STEP 1: Read from legacy storage
-                guard let legacyValue = UserDefaults.standard.string(forKey: key),
-                      let data = legacyValue.data(using: .utf8) else {
-                    results.append(.init(key: key, succeeded: true, error: nil))
+                try await vault.save(payload, account: key,
+                                     accessibility: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly as String)
+                guard try await vault.read(account: key) == payload else {
+                    report[key] = .failed(reason: "read-back mismatch")
                     continue
                 }
-
-                // STEP 2: Write to keychain (add-or-update handles duplicates)
-                try await keychain.save(data, service: service,
-                                        account: key, accessible: accessible)
-
-                // STEP 3: Verify by reading back
-                let readBack = try await keychain.read(service: service, account: key)
-                guard readBack == data else {
-                    throw MigrationError.verificationFailed(key: key)
-                }
-
-                // STEP 4: Delete from UserDefaults ONLY after verified write
-                UserDefaults.standard.removeObject(forKey: key)
-                results.append(.init(key: key, succeeded: true, error: nil))
-
+                defaults.removeObject(forKey: key)
+                report[key] = .moved
             } catch {
-                // ROLLBACK: Leave UserDefaults intact for this key
-                results.append(.init(key: key, succeeded: false, error: error))
+                report[key] = .failed(reason: String(describing: error))
             }
         }
-        return results
-    }
-
-    enum MigrationError: Error {
-        case verificationFailed(key: String)
-        case corruptArchive(path: String)
+        return report
     }
 }
 ```
 
+`save` is the add-or-update helper from [keychain-fundamentals.md](keychain-fundamentals.md): `SecItemAdd` first, and on `errSecDuplicateItem` a `SecItemUpdate` with the new data. A failed key keeps its `UserDefaults` value, so the result is idempotent: moved keys read as absent next time and are skipped, failed keys are retried after a crash, a force quit or a memory kill.
+
+The protocol takes the accessibility class as a `String`. The `kSecAttrAccessible*` constants are `CFString` globals, which are not `Sendable`, and Swift 6 rejects handing one to another actor; `as String` makes a copy that is. The conforming type turns it back with `as CFString` when it builds the query.
+
+The version to avoid:
+
 ```swift
-// ❌ INCORRECT: Deletes legacy data BEFORE verifying keychain write
-func dangerousMigration() {
-    let keys = ["authToken", "refreshToken"]
-    for key in keys {
-        guard let value = UserDefaults.standard.string(forKey: key) else { continue }
-
-        // Deletes FIRST  -  if keychain write fails, data is gone forever
-        UserDefaults.standard.removeObject(forKey: key) // ← CATASTROPHIC
-
-        let query: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrService as String: "com.myapp",
-            kSecAttrAccount as String: key,
-            kSecValueData as String: value.data(using: .utf8)!
-        ]
-        let status = SecItemAdd(query as CFDictionary, nil)
-        // If status != errSecSuccess, the token is permanently lost.
-    }
-}
+let token = UserDefaults.standard.string(forKey: "authToken") ?? ""
+UserDefaults.standard.removeObject(forKey: "authToken")
+let item: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                             kSecAttrAccount: "authToken",
+                             kSecValueData: Data(token.utf8)]
+SecItemAdd(item as CFDictionary, nil)
 ```
 
-The migration is **idempotent by design**: already-migrated keys return `nil` from UserDefaults in Step 1 and are skipped. Failed keys retain their original values, ready for retry. This makes it safe to re-run after crash, app kill, or OOM termination.
-
----
+The plaintext is gone before the add, and the add's status is ignored, so any failure loses the token.
 
-## Versioned Migration with Schema Tracking
+## Versioned migration with a schema number
 
-A production system needs version tracking to avoid re-running completed migrations and to handle users who skip versions. The schema version belongs in the **keychain** (survives reinstalls), not UserDefaults.
+Store the schema version in the keychain, not in `UserDefaults`, so it survives a reinstall together with the items it describes.
 
 ```swift
-// ✅ CORRECT: Versioned chain migration with schema version in keychain
-actor MigrationCoordinator {
-    static let shared = MigrationCoordinator()
-
-    private let serviceName = "com.myapp.credentials"
-    private let schemaVersionAccount = "com.myapp.schema.version"
-    private static let currentSchemaVersion: Int = 3
-
-    enum MigrationState {
-        case upToDate
-        case migrated(from: Int, to: Int)
-        case deferred(reason: String)
-        case failed(Error)
-    }
+import OSLog
+import UIKit
+
+enum MigrationState: Sendable, Equatable {
+    case upToDate
+    case migrated(from: Int, to: Int)
+    case deferred(reason: String)
+    case failed(reason: String)
+}
 
-    func migrateIfNeeded() async -> MigrationState {
-        // Guard: protected data must be available (pre-warming defense)
-        let dataAvailable = await MainActor.run {
-            UIApplication.shared.isProtectedDataAvailable
-        }
-        guard dataAvailable else {
-            return .deferred(reason: "Device locked  -  protected data unavailable")
-        }
+enum MigrationError: Error { case keysLeftBehind(Int), corruptArchive, readBackMismatch }
 
-        let storedVersion = readSchemaVersion()
-        guard storedVersion < Self.currentSchemaVersion else { return .upToDate }
+actor SchemaMigrator {
+    static let targetVersion = 3
+    private let vault: any MigrationKeychainProtocol
+    private let versionAccount = "vault.schemaVersion"
+    private let log = OSLog(subsystem: "com.example.ledger", category: "KeychainMigration")
 
+    init(vault: any MigrationKeychainProtocol) { self.vault = vault }
+
+    func migrateIfNeeded() async -> MigrationState {
+        let readable = await MainActor.run { UIApplication.shared.isProtectedDataAvailable }
+        guard readable else { return .deferred(reason: "device locked") }
         do {
-            // Chain migration: each step runs sequentially
-            if storedVersion < 1 {
-                try await migrateV0toV1_UserDefaultsToKeychain()
-            }
-            if storedVersion < 2 {
-                try await migrateV1toV2_NSCodingArchivesToKeychain()
-            }
-            if storedVersion < 3 {
-                try await migrateV2toV3_UpgradeAccessibilityClass()
+            let current = try await storedVersion()
+            guard current < Self.targetVersion else { return .upToDate }
+            for step in current..<Self.targetVersion {
+                try await run(stepFrom: step)
             }
-
-            // Update version ONLY after all steps succeed
-            try saveSchemaVersion(Self.currentSchemaVersion)
-            return .migrated(from: storedVersion, to: Self.currentSchemaVersion)
+            try await vault.save(Data(String(Self.targetVersion).utf8), account: versionAccount,
+                                 accessibility: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly as String)
+            return .migrated(from: current, to: Self.targetVersion)
         } catch {
-            // Do NOT update schema version  -  retry on next launch
-            os_log(.error, log: .migration,
-                   "Migration failed: %{public}@", error.localizedDescription)
-            return .failed(error)
+            os_log("migration stopped: %{public}@", log: log, type: .error,
+                   String(describing: type(of: error)))
+            return .failed(reason: String(describing: error))
         }
     }
 
-    // MARK: - Schema Version (stored in keychain, survives reinstall)
-
-    private func readSchemaVersion() -> Int {
-        guard let data = try? keychainRead(
-                  service: serviceName, account: schemaVersionAccount),
-              let str = String(data: data, encoding: .utf8),
-              let version = Int(str) else { return 0 }
-        return version
-    }
-
-    private func saveSchemaVersion(_ version: Int) throws {
-        let data = "\(version)".data(using: .utf8)!
-        try keychainSave(data, service: serviceName,
-                         account: schemaVersionAccount)
+    private func storedVersion() async throws -> Int {
+        guard let raw = try await vault.read(account: versionAccount) else { return 0 }
+        return Int(String(decoding: raw, as: UTF8.self)) ?? 0
     }
 
-    // MARK: - V1: UserDefaults → Keychain
-
-    private func migrateV0toV1_UserDefaultsToKeychain() async throws {
-        let migrator = AtomicMigrator(keychain: KeychainManager.shared)
-        let results = await migrator.migrateUserDefaultsKeys(
-            ["authToken", "refreshToken", "apiSecret"],
-            service: serviceName
-        )
-        // Check for critical failures (non-nil keys that didn't migrate)
-        let failures = results.filter { !$0.succeeded }
-        if !failures.isEmpty {
-            os_log(.error, log: .migration,
-                   "V1 migration: %d keys failed", failures.count)
+    private func run(stepFrom version: Int) async throws {
+        switch version {
+        case 0: try await moveDefaults()
+        case 1: try await moveArchive()
+        case 2: try await tightenAccessibility()
+        default: break
         }
-        // Force-sync UserDefaults deletions to disk
-        UserDefaults.standard.synchronize()
     }
+}
+```
 
-    // MARK: - V2: NSCoding Archives → Keychain
-
-    private func migrateV1toV2_NSCodingArchivesToKeychain() async throws {
-        let documentsURL = FileManager.default.urls(
-            for: .documentDirectory, in: .userDomainMask).first!
-        let archiveURL = documentsURL.appendingPathComponent("UserSession.archive")
-
-        guard FileManager.default.fileExists(atPath: archiveURL.path) else { return }
-
-        let archiveData = try Data(contentsOf: archiveURL)
-        guard let session = try NSKeyedUnarchiver.unarchivedObject(
-            ofClass: LegacySession.self, from: archiveData) else {
-            throw AtomicMigrator.MigrationError.corruptArchive(path: archiveURL.path)
-        }
-
-        let sessionData = try JSONEncoder().encode(session.toModernSession())
-        try keychainSave(sessionData, service: serviceName, account: "userSession")
+The steps, one per version:
 
-        // Verify before deleting archive file
-        let verified = try keychainRead(service: serviceName, account: "userSession")
-        guard verified == sessionData else {
-            throw AtomicMigrator.MigrationError.verificationFailed(key: "userSession")
-        }
-        try FileManager.default.removeItem(at: archiveURL)
-    }
+- **v0 to v1, UserDefaults.** Run `DefaultsToKeychainMover` over the named keys, log how many failed, and throw if any did so the version does not advance. Older samples call `UserDefaults.standard.synchronize()` afterwards; it is harmless and no longer needed.
+- **v1 to v2, NSCoding archive.** If the archive file exists, decode it with `NSKeyedUnarchiver.unarchivedObject(ofClass:from:)` (a corrupt file throws), encode the modern session value as JSON, save it to the keychain, read it back, and only then call `FileManager.default.removeItem(at:)`.
+- **v2 to v3, stricter accessibility.** Re-save every existing item with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` through add-or-update; the duplicate branch runs `SecItemUpdate` with the new `kSecAttrAccessible` in the attributes dictionary. Items that carry a `SecAccessControl` are the exception: changing their access control means delete and re-add.
 
-    // MARK: - V3: Upgrade accessibility class on existing items
-
-    private func migrateV2toV3_UpgradeAccessibilityClass() async throws {
-        let accounts = ["authToken", "refreshToken", "apiSecret", "userSession"]
-        for account in accounts {
-            guard let data = try? keychainRead(
-                      service: serviceName, account: account) else { continue }
-            // Re-save with updated accessibility  -  add-or-update pattern
-            // updates the accessibility class via SecItemUpdate
-            try keychainSave(data, service: serviceName, account: account,
-                             accessible: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly)
+```swift
+extension SchemaMigrator {
+    private func moveArchive() async throws {
+        let file = URL.applicationSupportDirectory.appending(path: "Session.archive")
+        guard FileManager.default.fileExists(atPath: file.path()) else { return }
+        let raw = try Data(contentsOf: file)
+        guard let old = try NSKeyedUnarchiver.unarchivedObject(ofClass: LegacySession.self, from: raw) else {
+            throw MigrationError.corruptArchive
         }
+        let modern = try JSONEncoder().encode(SessionRecord(userID: old.userID, accessToken: old.token))
+        try await vault.save(modern, account: "session",
+                             accessibility: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly as String)
+        guard try await vault.read(account: "session") == modern else { throw MigrationError.readBackMismatch }
+        try FileManager.default.removeItem(at: file)
     }
 }
-
-private extension OSLog {
-    static let migration = OSLog(
-        subsystem: Bundle.main.bundleIdentifier ?? "com.myapp",
-        category: "KeychainMigration"
-    )
-}
 ```
 
-```swift
-// ❌ INCORRECT: Runs every launch, no version check, no verification, no legacy delete
-func brokenMigration() {
-    // No version check  -  runs every single launch
-    // No isProtectedDataAvailable check  -  fails during pre-warm
-    if let token = UserDefaults.standard.string(forKey: "authToken") {
-        let query: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrService as String: "com.myapp",
-            kSecAttrAccount as String: "authToken",
-            kSecValueData as String: token.data(using: .utf8)!
-        ]
-        // No errSecDuplicateItem handling  -  crashes on second launch
-        SecItemAdd(query as CFDictionary, nil)
-        // Never deletes from UserDefaults  -  plaintext secret persists
-        // No verification that write succeeded
-    }
-}
-```
+`LegacySession` stands for the app's existing `NSSecureCoding` class and `SessionRecord` for a new `Codable` struct.
 
-The chain migration approach (v1 → v2 → v3 sequentially) is deliberately chosen over direct migration because it reuses tested migration logic from each version. For users upgrading from v1.0 directly to v3.0, all three steps run. The schema version only advances after all steps succeed  -  a crash mid-migration leaves the version at the old number for clean retry.
+A migration that runs every launch, skips the protected-data check, ignores `errSecDuplicateItem`, never reads back and never removes the `UserDefaults` copy shows every defect this file warns about.
 
----
+Why a chain of single steps instead of direct jumps: each step is tested once and reused, a user skipping several releases simply runs every step in order, and a crash in the middle leaves the stored version at its old value so the next launch retries cleanly. Log through a dedicated `OSLog` subsystem with a `KeychainMigration` category so the steps can be filtered in Console.
 
-## Orphaned Items: Why You Must Never Rename kSecAttrService
+## Orphaned items after a rename
 
-```swift
-// ❌ INCORRECT: SecItemUpdate CANNOT change primary key attributes
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrService as String: "OldServiceName",
-    kSecAttrAccount as String: "authToken"
-]
-let update: [String: Any] = [
-    kSecAttrService as String: "com.mycompany.myapp" // ERROR: primary key
-]
-// SecItemUpdate returns an error  -  primary keys are immutable via Update
-SecItemUpdate(query as CFDictionary, update as CFDictionary)
-```
+`SecItemUpdate` with a new `kSecAttrService` in the attributes dictionary fails, because the service is part of the item's primary key. Rekey instead:
 
 ```swift
-// ✅ CORRECT: Full rekey migration when service name must change
-func migrateServiceName() async throws {
-    let oldService = "OldServiceName"
-    let newService = "com.mycompany.myapp"
-    let accounts = ["authToken", "refreshToken"]
-
+func rekey(accounts: [String], from oldService: String, to newService: String) throws {
     for account in accounts {
-        let oldData: Data
-        do {
-            oldData = try keychainRead(service: oldService, account: account)
-        } catch { continue } // Already migrated or never existed
-
-        try keychainSave(oldData, service: newService, account: account)
-
-        // Verify new location before deleting old
-        let verified = try keychainRead(service: newService, account: account)
-        guard verified == oldData else {
-            throw AtomicMigrator.MigrationError.verificationFailed(key: account)
+        let lookup: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                       kSecAttrService: oldService,
+                                       kSecAttrAccount: account,
+                                       kSecReturnData: true]
+        var found: CFTypeRef?
+        let status = SecItemCopyMatching(lookup as CFDictionary, &found)
+        if status == errSecItemNotFound { continue }
+        guard status == errSecSuccess, let secret = found as? Data else { throw KeychainFailure(status) }
+        try KeychainVault.upsert(secret, service: newService, account: account)
+        guard try KeychainVault.read(service: newService, account: account) == secret else {
+            throw KeychainFailure(errSecDecode)
         }
-        try keychainDelete(service: oldService, account: account)
+        let oldItem: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                        kSecAttrService: oldService,
+                                        kSecAttrAccount: account]
+        SecItemDelete(oldItem as CFDictionary)
     }
 }
 ```
 
-**Lock down your `kSecAttrService` value early and never change it.** Use your bundle identifier (e.g., `com.mycompany.myapp`)  -  it's unique, stable, and conventional.
+`KeychainVault` stands for the app's add-or-update helper described in [keychain-fundamentals.md](keychain-fundamentals.md). The better fix is to never need this: choose `kSecAttrService` once, typically the bundle identifier, and keep it forever.
 
----
+## Locked devices and background launches
 
-## Background Launch and the Locked-Device Trap
+Pre-warming and background work (remote notifications, background fetch, Live Activity updates) can run while the device is locked. The item's accessibility class decides whether reads succeed.
 
-iOS 15+ pre-warming and background execution (push notifications, background fetch, Live Activities) can launch your app while the device is locked. The `kSecAttrAccessible` value you choose determines whether keychain operations succeed in these contexts.
+| Class | Readable in the background | Notes |
+| --- | --- | --- |
+| `WhenUnlocked` (default) | No | Foreground only, backed up and eligible for sync |
+| `AfterFirstUnlockThisDeviceOnly` | Yes, after first unlock | Recommended; stays on this device |
+| `AfterFirstUnlock` | Yes, after first unlock | Also backed up and eligible for sync; use only when needed |
+| `WhenPasscodeSetThisDeviceOnly` | No | For biometric-gated items; removed if the passcode is removed |
+| `Always` | Yes | Deprecated in iOS 12; do not use |
 
-> For the complete accessibility constant selection matrix with data protection tiers and security trade-offs, see `keychain-access-control.md` section The "When" Layer: Seven Accessibility Constants. The table below summarizes the four constants most relevant to background migration scenarios.
+Migrated credentials default to `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`: usable from background code, never backed up, never synced.
 
-| Accessibility constant                             | Available when locked | Background safe | Notes                                                |
-| -------------------------------------------------- | --------------------- | --------------- | ---------------------------------------------------- |
-| `kSecAttrAccessibleWhenUnlocked` (default)         | No                    | No              | Foreground only                                      |
-| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | After first unlock    | Yes             | **Recommended**  -  background + device-bound          |
-| `kSecAttrAccessibleAfterFirstUnlock`               | After first unlock    | Yes             | Background + backup migration (use only when needed) |
-| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`  | No                    | No              | Biometric-gated items                                |
-| `kSecAttrAccessibleAlways`                         | Yes                   | Yes             | **Deprecated iOS 12**  -  do not use                   |
+On sync: every `...ThisDeviceOnly` class keeps the item on this device. Such an item is never restored to another device and never syncs through iCloud Keychain, and asking for both (`kSecAttrSynchronizable: true` with a `ThisDeviceOnly` class) is rejected by `SecItemAdd` with `errSecParam`. Pick a non-ThisDeviceOnly class only when the item is meant to sync.
 
-**Recommended default for migrated credentials:** `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`  -  background-safe, not synced to iCloud, not included in backups. Apple uses `AfterFirstUnlock` for Wi-Fi passwords and mail account credentials.
-
-A critical trap: **`SecItemDelete` does NOT require the item's protection-class key material**  -  it succeeds even when the item's data is unreadable due to lock state. This enables a devastating anti-pattern:
+`SecItemDelete` does not need the class key, so it succeeds even while the data is unreadable. That makes this pattern destructive:
 
 ```swift
-// ❌ DANGEROUS: Delete-on-read-failure destroys data during background launch
-func dangerousTokenRefresh() {
-    var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-
-    if status != errSecSuccess {
-        // "Can't read? Must be corrupted. Delete and start fresh."
-        SecItemDelete(query as CFDictionary) // ← DESTROYS VALID TOKEN
-        // During background launch with WhenUnlocked, the read fails
-        // with -25308 (interaction not allowed), but delete succeeds.
-    }
-}
-
-// ✅ CORRECT: Distinguish "not found" from "device locked"
-func safeTokenRead() throws -> Data? {
-    var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-
-    switch status {
-    case errSecSuccess:
-        return result as? Data
-    case errSecItemNotFound:
-        return nil // Genuinely absent
-    case errSecInteractionNotAllowed:
-        // Device locked  -  item exists but unreadable right now.
-        // Do NOT delete. Do NOT treat as missing. Retry later.
-        throw KeychainError.interactionNotAllowed
-    default:
-        throw KeychainError.unexpectedStatus(status)
-    }
+if SecItemCopyMatching(query as CFDictionary, &out) != errSecSuccess {
+    SecItemDelete(query as CFDictionary)
 }
 ```
 
-**Migration rule:** Always guard migration behind `UIApplication.shared.isProtectedDataAvailable`. If the device is locked, defer using `protectedDataDidBecomeAvailableNotification`. Never interpret an empty read during a locked state as "nothing to migrate."
-
----
-
-## The Phantom Mismatch Bug
-
-Including `kSecAttrAccessible` in a search query causes a "not-found then duplicate" paradox. The search filters by accessibility class, but the item was stored with a different class  -  so `SecItemCopyMatching` returns `errSecItemNotFound` while `SecItemAdd` sees the item via primary key and returns `errSecDuplicateItem`.
+During a locked background launch the read returns `errSecInteractionNotAllowed` (-25308), the delete succeeds, and a valid token is gone. Map the statuses instead:
 
 ```swift
-// ❌ INCORRECT: kSecAttrAccessible in search query causes phantom mismatches
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrService as String: service,
-    kSecAttrAccount as String: account,
-    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked, // ← BUG
-    kSecReturnData as String: kCFBooleanTrue as Any
-]
-// If stored with AfterFirstUnlock, query returns errSecItemNotFound.
-// But SecItemAdd sees the item via primary key → errSecDuplicateItem. Deadlock.
-```
+enum VaultError: Error { case lockedTryLater, unexpected(OSStatus) }
 
-**Rule:** Use **only primary key attributes** (`kSecClass`, `kSecAttrService`, `kSecAttrAccount`) in search queries. Set `kSecAttrAccessible` only during `SecItemAdd` or in the update dictionary of `SecItemUpdate`.
-
-```swift
-// ✅ CORRECT: search by primary key only
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrService as String: service,
-    kSecAttrAccount as String: account,
-    kSecReturnData as String: kCFBooleanTrue as Any
-]
+func readToken(_ query: [CFString: Any]) throws -> Data? {
+    var out: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &out)
+    switch status {
+    case errSecSuccess: return out as? Data
+    case errSecItemNotFound: return nil
+    case errSecInteractionNotAllowed: throw VaultError.lockedTryLater
+    default: throw VaultError.unexpected(status)
+    }
+}
 ```
 
----
+`errSecInteractionNotAllowed` is neither "missing" nor a reason to delete; retry once protected data is available. Gate migration on `isProtectedDataAvailable`, defer it through `protectedDataDidBecomeAvailableNotification`, and never interpret an empty read on a locked device as "nothing to migrate".
 
-## Team ID Change: The App Transfer Edge Case
+## The phantom mismatch
 
-When an app is transferred to a different Apple Developer account, the Team ID changes. Keychain access is permanently tied to the original Team ID  -  all existing keychain items become inaccessible under the new signing identity. Users are effectively logged out and lose all locally stored secrets on the first launch after updating.
+Putting `kSecAttrAccessible` into a search query turns it into a filter. If the stored item has a different class, `SecItemCopyMatching` reports `errSecItemNotFound` while `SecItemAdd` reports `errSecDuplicateItem` for the same item, and the code loops between the two. Search with primary-key attributes only (`kSecClass`, `kSecAttrService`, `kSecAttrAccount`). Accessibility belongs in the `SecItemAdd` dictionary or in the attributes-to-update dictionary of `SecItemUpdate`.
 
-**If a Team ID change is unavoidable**, you must release a "bridge" update under the **old** Team ID before the transfer:
+## Team ID change after an app transfer
 
-1. Bridge update reads all keychain items and exports them to a temporary, app-group-shared container (or encrypted file in the app sandbox)
-2. Transfer the app to the new developer account
-3. First release under the new Team ID reads from the temporary store, writes to the new keychain, verifies, and deletes the temporary data
+Moving the app to another developer account changes the Team ID, which is part of every keychain access group. All existing items become unreadable and every user is signed out. There is no recovery afterwards, so plan a bridge well before the transfer:
 
-This is a one-way operation and must be planned well in advance. There is no way to recover keychain items after a Team ID change without the bridge update.
+1. Ship an update under the old Team ID that exports the needed values into a temporary app-group container or an encrypted file in the sandbox.
+2. Transfer the app.
+3. In the first release under the new team, import the values, write them to the keychain, verify them, then delete the temporary copy.
 
----
+## Cleaning up legacy artefacts
 
-## Deferred Legacy Cleanup with Rollback Window
+Secret values are deleted as soon as their keychain copy is verified, in the same step that moved them. Keeping plaintext credentials around "just in case" preserves exactly the exposure the migration exists to remove, and Apple's guidance is that `UserDefaults` and plain files are not for sensitive data.
 
-The safest approach keeps legacy data as backup for one release cycle after migration. Track a migration timestamp in keychain:
+A rollback window is still useful for what is left: non-secret legacy files and preference domains that an older build or a support engineer might want. Record the migration date in the keychain and clear those artefacts after roughly one release cycle, such as 30 days.
 
 ```swift
-// ✅ CORRECT: Deferred cleanup with 30-day rollback window
-actor DeferredCleanup {
-    private let cleanupDelayDays = 30
-    private let timestampAccount = "com.myapp.migration.timestamp"
-    private let serviceName = "com.myapp.credentials"
-
-    func cleanupIfExpired() async {
-        guard let data = try? keychainRead(
-                  service: serviceName, account: timestampAccount),
-              let str = String(data: data, encoding: .utf8),
-              let migrationDate = ISO8601DateFormatter().date(from: str) else { return }
-
-        let days = Calendar.current.dateComponents(
-            [.day], from: migrationDate, to: Date()).day ?? 0
-        guard days >= cleanupDelayDays else { return }
-
-        // Past rollback window  -  safe to permanently delete legacy files
-        let documentsURL = FileManager.default.urls(
-            for: .documentDirectory, in: .userDomainMask).first!
-        for file in ["UserSession.archive", "Credentials.plist", "TokenCache.dat"] {
-            try? FileManager.default.removeItem(
-                at: documentsURL.appendingPathComponent(file))
+actor LegacyArtefactJanitor {
+    private let vault: any MigrationKeychainProtocol
+    private let window: TimeInterval = 30 * 24 * 60 * 60
+    private let leftovers = ["SessionCache.archive", "Preferences.plist", "FeedCache.dat"]
+
+    init(vault: any MigrationKeychainProtocol) { self.vault = vault }
+
+    func sweepIfWindowElapsed(now: Date = .now) async throws {
+        guard let stamp = try await vault.read(account: "vault.migratedAt"),
+              let migratedAt = ISO8601DateFormatter().date(from: String(decoding: stamp, as: UTF8.self)),
+              now.timeIntervalSince(migratedAt) > window else { return }
+        let base = URL.documentsDirectory
+        for name in leftovers {
+            try? FileManager.default.removeItem(at: base.appending(path: name))
         }
-        if let bundleID = Bundle.main.bundleIdentifier {
-            UserDefaults.standard.removePersistentDomain(forName: bundleID)
+        if let domain = Bundle.main.bundleIdentifier {
+            UserDefaults.standard.removePersistentDomain(forName: domain)
         }
     }
 }
 ```
 
----
-
-## Complete App Launch Sequence
-
-The correct ordering at app startup is critical. Keychain cleanup must happen before SDK initialization, migration must wait for protected data, and schema version gates all logic.
+## Launch order
 
 ```swift
-// ✅ CORRECT: Complete launch sequence with migration
-@main
-struct MyApp: App {
-    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
-    var body: some Scene { WindowGroup { ContentView() } }
-}
+import SwiftUI
+import OSLog
 
-class AppDelegate: NSObject, UIApplicationDelegate {
-    func application(
-        _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-    ) -> Bool {
-        Task {
-            // 1. First-launch cleanup (stale keychain from previous install)
-            await FirstLaunchGuard.shared.performCleanupIfNeeded()
-
-            // 2. Versioned migration
-            let state = await MigrationCoordinator.shared.migrateIfNeeded()
-            switch state {
-            case .upToDate: break
-            case .migrated(let from, let to):
-                os_log(.info, "Migrated schema v%d → v%d", from, to)
-            case .deferred(let reason):
-                os_log(.info, "Migration deferred: %{public}@", reason)
-            case .failed(let error):
-                os_log(.error, "Migration failed: %{public}@",
-                       error.localizedDescription)
-            }
-
-            // 3. Deferred cleanup of legacy files past rollback window
-            await DeferredCleanup().cleanupIfExpired()
+final class LaunchDelegate: NSObject, UIApplicationDelegate {
+    private let vault = LiveMigrationKeychain()
+    private let log = Logger(subsystem: "com.example.ledger", category: "KeychainMigration")
 
-            // 4. NOW initialize Firebase, analytics, auth SDKs
-            // Stale data cleared, migration complete or safely deferred
+    func application(_ application: UIApplication,
+                     didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
+        Task {
+            await ReinstallSweeper().sweepIfFreshInstall()
+            let state = await SchemaMigrator(vault: vault).migrateIfNeeded()
+            log.info("migration state: \(String(describing: state), privacy: .public)")
+            try? await LegacyArtefactJanitor(vault: vault).sweepIfWindowElapsed()
+            ThirdPartyServices.start()
         }
         return true
     }
 }
-```
-
----
 
-## Thread Safety Note
+@main
+struct LedgerApp: App {
+    @UIApplicationDelegateAdaptor(LaunchDelegate.self) private var delegate
+    var body: some Scene { WindowGroup { RootView() } }
+}
+```
 
-`SecItem*` functions are safe to call from concurrent code, but your wrapper's mutable state (caches, migration flags, version tracking) still needs synchronization. An `actor` provides this naturally in modern Swift concurrency; prefer actors over serial queues for new code when the deployment target allows it.
+The order is fixed: reinstall sweep, schema migration, artefact cleanup, and only then the analytics, crash reporting and authentication SDKs.
 
----
+## Concurrency
 
-## Testing Migration Paths
+The `SecItem*` functions are safe to call from any thread. The wrapper's own state (caches, flags, the stored version) is not, so protect it; an actor is the simplest choice when the deployment target allows it, otherwise a serial queue.
 
-Keychain behavior differs between Simulator and real devices:
+## Testing migrations
 
-| Aspect                        | Simulator                | Real device                            |
-| ----------------------------- | ------------------------ | -------------------------------------- |
-| Data Protection enforcement   | Not enforced             | Fully enforced (hardware)              |
-| Keychain entitlements         | Loosely enforced         | Strictly enforced                      |
-| `errSecInteractionNotAllowed` | Rarely triggered         | Triggered when locked                  |
-| Lock state testing            | Cannot meaningfully test | Essential for accessibility validation |
+| Aspect | Simulator | Device |
+| --- | --- | --- |
+| Data protection | Not enforced | Enforced |
+| Entitlement checks | Lenient | Strict |
+| `errSecInteractionNotAllowed` | Rare | Returned while locked |
+| Lock-state testing | Not possible | Required |
 
-Use **protocol-based abstraction** for unit tests (runs in CI on simulators) and real-device integration tests for accessibility-class validation:
+An in-memory mock that conforms to the same protocol lets unit tests inject failures:
 
 ```swift
-// ✅ Protocol-based keychain abstraction for testable migrations
-protocol MigrationKeychainProtocol: Actor {
-    func save(_ data: Data, service: String, account: String,
-              accessible: CFString) throws
-    func read(service: String, account: String) throws -> Data
-    func delete(service: String, account: String) throws
-    func deleteAll()
-}
+actor InMemoryMigrationKeychain: MigrationKeychainProtocol {
+    private var rows: [String: [String: Data]] = [:]
+    var injectedStatus: OSStatus?
 
-// In-memory mock for unit tests
-actor MockMigrationKeychain: MigrationKeychainProtocol {
-    var store: [String: [String: Data]] = [:]
-    var simulatedError: KeychainError?
+    func inject(_ status: OSStatus?) { injectedStatus = status }
 
-    func save(_ data: Data, service: String, account: String,
-              accessible: CFString) throws {
-        if let error = simulatedError { throw error }
-        store[service, default: [:]][account] = data
+    func save(_ data: Data, account: String, accessibility: String) throws {
+        if let status = injectedStatus { throw KeychainFailure(status) }
+        rows[accessibility, default: [:]][account] = data
     }
-
-    func read(service: String, account: String) throws -> Data {
-        if let error = simulatedError { throw error }
-        guard let data = store[service]?[account] else {
-            throw KeychainError.itemNotFound
-        }
-        return data
+    func read(account: String) throws -> Data? {
+        rows.values.lazy.compactMap { $0[account] }.first
     }
-
-    func delete(service: String, account: String) throws {
-        store[service]?[account] = nil
+    func delete(account: String) throws {
+        for key in rows.keys { rows[key]?[account] = nil }
     }
-
-    func deleteAll() { store.removeAll() }
+    func deleteAll() throws { rows.removeAll() }
 }
 ```
 
 ```swift
-// ✅ Example: verify atomic behavior  -  legacy data preserved on failure
-@Test func migrationPreservesLegacyDataOnKeychainFailure() async {
-    let mock = MockMigrationKeychain()
-    mock.simulatedError = .unexpectedStatus(-25308) // Simulate locked device
+import Testing
 
-    let defaults = UserDefaults(suiteName: "test")!
-    defaults.set("secret-token", forKey: "authToken")
+@Test func lockedWriteLeavesPlaintextForRetry() async throws {
+    let suite = try #require(UserDefaults(suiteName: "migration-test"))
+    suite.removePersistentDomain(forName: "migration-test")
+    suite.set("refresh-abc", forKey: "refreshToken")
+    let vault = InMemoryMigrationKeychain()
+    await vault.inject(errSecInteractionNotAllowed)
 
-    let migrator = AtomicMigrator(keychain: mock)
-    let results = await migrator.migrateUserDefaultsKeys(
-        ["authToken"], service: "com.myapp"
-    )
+    let mover = DefaultsToKeychainMover(vault: vault, defaults: try #require(UserDefaults(suiteName: "migration-test")))
+    let report = await mover.move(keys: ["refreshToken"])
 
-    #expect(results.contains(where: { !$0.succeeded }))
-    #expect(defaults.string(forKey: "authToken") == "secret-token") // Still intact
+    #expect(suite.string(forKey: "refreshToken") == "refresh-abc")
+    #expect(report["refreshToken"] != .moved)
 }
 ```
 
-Always clean up keychain items in `setUp()`/`tearDown()`  -  items persist between test runs on the same simulator. For integration tests hitting real keychain, create a Test Host app target with the Keychain capability enabled.
-
----
-
-## Handling Very Old Versions and Collapse Strategy
-
-The App Store always delivers the latest binary  -  a user jumping from v1.0 to v3.0 never installs v2.0. Your v3.0 binary must contain migration logic for every historical schema version.
-
-Pragmatically, after sufficient time (when analytics show <1% of users on legacy versions), **collapse old migrations into a single mega-migration** from v0 to current, reducing code maintenance. For users on versions so old that the legacy format is unknown or corrupted, the migration should **fail gracefully** and prompt a fresh login rather than crashing.
+The mover gets its own `UserDefaults` instance for the same suite. `UserDefaults` is not `Sendable`, so once `suite` has been handed to the actor the test could not read it afterwards.
 
----
+Clear the keychain in `setUp` and `tearDown` for any test that touches the real one, because Simulator keeps items between runs. Integration tests against the real keychain need a host app target with the Keychain Sharing capability. More in [testing-security-code.md](testing-security-code.md).
 
-## Secure Deletion: Trust Cryptographic Erasure
+## Very old versions
 
-Do **not** attempt to manually overwrite files with zeros or random bytes before deletion  -  NAND flash wear-leveling makes this ineffective and wastes write cycles. iOS handles secure deletion through cryptographic erasure: every file has a per-file AES-256 key, and when the file is deleted via standard APIs (`FileManager.removeItem`, `UserDefaults.removeObject`), iOS destroys the per-file key through Effaceable Storage, rendering the physical bits permanently unrecoverable.
+The App Store only serves the newest binary, so it must still carry every migration from every schema a user could be on. Once analytics show fewer than about 1% of users on the oldest versions, collapse the early steps into a single v0-to-current migration. An unknown or corrupt legacy format fails gracefully and sends the user to a fresh sign-in; it never crashes.
 
-Standard deletion APIs are sufficient. The residual risk is unencrypted backups created _before_ migration  -  encourage users to use encrypted backups, and delete legacy data promptly after verified migration.
+## Deleting files
 
----
+Do not overwrite a file with zeros or random bytes before deleting it. Wear levelling on NAND means the overwrite lands elsewhere, and it only burns write cycles. `FileManager.removeItem(at:)` and `UserDefaults.removeObject(forKey:)` are enough, because the per-file key is destroyed through Effaceable Storage. The residual risk is an unencrypted backup made before migration; encourage encrypted backups and remove the plaintext promptly once the migration is verified.
 
-## Conclusion
+## Key decisions
 
-The core insight of safe keychain migration: **deletion is the irreversible step, not the write**. Every pattern in this file follows from that principle  -  verify before deleting, defer when uncertain, and treat keychain persistence across reinstalls as a feature to plan for rather than a bug to fight. The five most impactful decisions are: using `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` for background-safe encrypted storage, implementing first-launch cleanup before SDK initialization, storing schema versions in keychain rather than UserDefaults, gating all migration behind `isProtectedDataAvailable`, and never changing `kSecAttrService` after shipping.
+The irreversible step is the delete, not the write: verify first, defer when in doubt, and assume keychain items outlive the app. The five decisions that matter most:
 
----
+1. `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` as the default class for migrated credentials.
+2. Reinstall cleanup before any SDK initialises.
+3. Schema version stored in the keychain.
+4. Migration gated on `isProtectedDataAvailable`.
+5. `kSecAttrService` never changes after the first release.
 
-## Summary Checklist
+## Checklist
 
-1. **First-launch cleanup runs before any SDK initialization**  -  uses UserDefaults flag to detect reinstall, wipes stale keychain items, includes `kSecAttrSynchronizableAny` to catch iCloud-synced items
-2. **Migration is atomic: read → write → verify → delete**  -  legacy data is never deleted until keychain write is confirmed by read-back; failed keys remain intact for retry
-3. **Schema version stored in keychain, not UserDefaults**  -  survives app reinstall; version only advances after all migration steps succeed
-4. **Protected data availability checked before any migration**  -  guards against iOS 15+ pre-warming and locked-device scenarios; defers via `protectedDataDidBecomeAvailableNotification`
-5. **`errSecInteractionNotAllowed` (-25308) is never treated as "item missing"**  -  distinguishes locked-device failures from genuine absence; never deletes on read failure without checking status code
-6. **`kSecAttrService` and `kSecAttrAccount` are immutable after shipping**  -  changing either orphans existing items; `SecItemUpdate` cannot modify primary keys; use full rekey migration if change is unavoidable
-7. **`kSecAttrAccessible` is never included in search queries**  -  causes phantom "not-found then duplicate" mismatches; set only during add or in update dictionary
-8. **Default accessibility is `AfterFirstUnlockThisDeviceOnly`**  -  background-safe, not synced, not backed up; matches Apple's own credential storage patterns
-9. **Deferred legacy cleanup with rollback window**  -  keep legacy data for 30 days post-migration as safety net; timestamp stored in keychain
-10. **Team ID changes sever all keychain access**  -  must release bridge update under old Team ID before app transfer; no recovery possible after transfer without bridge
-11. **Migration tested via protocol-based abstraction**  -  mock keychain in unit tests; real-device integration tests for accessibility class validation; clean up items in setUp/tearDown
+- [ ] Reinstall cleanup runs before SDK setup, after protected data is readable, and uses `kSecAttrSynchronizableAny`.
+- [ ] Each key moves read, write, verify, delete; failed keys keep their source value.
+- [ ] Schema version lives in the keychain and advances only after every step succeeds.
+- [ ] Migration checks protected-data availability and defers through the notification.
+- [ ] `errSecInteractionNotAllowed` (-25308) is never read as "missing" and never triggers a delete.
+- [ ] Service and account never change after shipping; an unavoidable rename uses a rekey migration.
+- [ ] Search queries never include `kSecAttrAccessible`.
+- [ ] Migrated credentials use `AfterFirstUnlockThisDeviceOnly` unless they are meant to sync.
+- [ ] Plaintext secrets are deleted right after verification; only non-secret artefacts wait for a 30-day window whose start date lives in the keychain.
+- [ ] A Team ID change is preceded by a bridge release.
+- [ ] Unit tests use a protocol mock; accessibility is tested on a device; real-keychain tests clean up in `setUp` and `tearDown`.