Migration & Legacy Stores

// ✅ 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 = [
                kSecClass: itemClass,
                kSecAttrSynchronizable: kSecAttrSynchronizableAny
            ]
            SecItemDelete(query)
        }
    }

    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()
                }
            }
        }
    }
}

// ❌ INCORRECT: No first-launch cleanup — stale keychain from previous install
@main
struct BrokenApp: 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)
        }
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

// ✅ CORRECT: Atomic per-key migration with verification and rollback
actor AtomicMigrator {
    struct MigrationResult {
        let key: String
        let succeeded: Bool
        let error: Error?
    }

    private let keychain: any MigrationKeychainProtocol

    init(keychain: any MigrationKeychainProtocol) {
        self.keychain = keychain
    }

    /// Failed keys remain in UserDefaults for retry on next launch.
    func migrateUserDefaultsKeys(
        _ keys: [String],
        service: String,
        accessible: CFString = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
    ) async -> [MigrationResult] {
        var results: [MigrationResult] = []

        for key in keys {
            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))
                    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))

            } catch {
                // ROLLBACK: Leave UserDefaults intact for this key
                results.append(.init(key: key, succeeded: false, error: error))
            }
        }
        return results
    }

    enum MigrationError: Error {
        case verificationFailed(key: String)
        case corruptArchive(path: String)
    }
}

// ❌ 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.
    }
}

// ✅ 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)
    }

    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")
        }

        let storedVersion = readSchemaVersion()
        guard storedVersion < Self.currentSchemaVersion else { return .upToDate }

        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()
            }

            // Update version ONLY after all steps succeed
            try saveSchemaVersion(Self.currentSchemaVersion)
            return .migrated(from: storedVersion, to: Self.currentSchemaVersion)
        } catch {
            // Do NOT update schema version — retry on next launch
            os_log(.error, log: .migration,
                   "Migration failed: %{public}@", error.localizedDescription)
            return .failed(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)
    }

    // 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)
        }
        // 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")

        // 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)
    }

    // 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)
        }
    }
}

private extension OSLog {
    static let migration = OSLog(
        subsystem: Bundle.main.bundleIdentifier ?? "com.myapp",
        category: "KeychainMigration"
    )
}

// ❌ 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
    }
}

// ❌ 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)

// ✅ 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"]

    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)
        }
        try keychainDelete(service: oldService, account: account)
    }
}

// ❌ 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)
    }
}

// ❌ 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.

// ✅ 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
]

// ✅ 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))
        }
        if let bundleID = Bundle.main.bundleIdentifier {
            UserDefaults.standard.removePersistentDomain(forName: bundleID)
        }
    }
}

// ✅ CORRECT: Complete launch sequence with migration
@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
    var body: some Scene { WindowGroup { ContentView() } }
}

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()

            // 4. NOW initialize Firebase, analytics, auth SDKs
            // Stale data cleared, migration complete or safely deferred
        }
        return true
    }
}

// ✅ 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()
}

// In-memory mock for unit tests
actor MockMigrationKeychain: MigrationKeychainProtocol {
    var store: [String: [String: Data]] = [:]
    var simulatedError: KeychainError?

    func save(_ data: Data, service: String, account: String,
              accessible: CFString) throws {
        if let error = simulatedError { throw error }
        store[service, 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 delete(service: String, account: String) throws {
        store[service]?[account] = nil
    }

    func deleteAll() { store.removeAll() }
}

// ✅ Example: verify atomic behavior — legacy data preserved on failure
@Test func migrationPreservesLegacyDataOnKeychainFailure() async {
    let mock = MockMigrationKeychain()
    mock.simulatedError = .unexpectedStatus(-25308) // Simulate locked device

    let defaults = UserDefaults(suiteName: "test")!
    defaults.set("secret-token", forKey: "authToken")

    let migrator = AtomicMigrator(keychain: mock)
    let results = await migrator.migrateUserDefaultsKeys(
        ["authToken"], service: "com.myapp"
    )

    #expect(results.contains(where: { !$0.succeeded }))
    #expect(defaults.string(forKey: "authToken") == "secret-token") // Still intact
}