Credential Storage Patterns

// ❌ INCORRECT — AI-generated token storage in UserDefaults
// Tokens are written as plaintext XML plist, readable from device backups
func saveTokens(accessToken: String, refreshToken: String) {
    UserDefaults.standard.set(accessToken, forKey: "access_token")
    UserDefaults.standard.set(refreshToken, forKey: "refresh_token")
}

// ❌ INCORRECT — Hardcoded API key discoverable via `strings` on the Mach-O binary
struct APIConfig {
    static let stripeSecretKey = "sk_live_51ABC123DEF456..."
    static let firebaseAPIKey = "AIzaSyB1234567890abcdefg"
}
// Attacker runs: strings MyApp.app/MyApp | grep "sk_live"

// ❌ INCORRECT — .xcconfig value compiled into Info.plist as plaintext
// In Secrets.xcconfig:  MAPS_API_KEY = gm_pk_a1b2c3d4e5f6g7h8i9
// In Info.plist:         <key>MapsAPIKey</key><string>$(MAPS_API_KEY)</string>

let apiKey = Bundle.main.infoDictionary?["MapsAPIKey"] as? String
// Attacker: unzip App.ipa && plutil -p Payload/App.app/Info.plist | grep Maps

// ❌ INCORRECT — Partial cleanup leaves refresh token behind
func logout() {
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrService as String: "com.myapp.auth",
        kSecAttrAccount as String: "access_token"
    ]
    SecItemDelete(query as CFDictionary)
    // BUG: refresh_token, user_profile, cached API keys all remain
}

// ✅ CORRECT — Actor-based KeychainManager with proper kSecAttrAccessible
// Requires: iOS 13+ (actors), recommended iOS 17+ for mature concurrency
import Foundation
import Security

public actor KeychainManager {

    public enum KeychainError: Error {
        case unexpectedStatus(OSStatus), itemNotFound, encodingFailed, decodingFailed
    }

    let service: String
    private let accessGroup: String?
    private let accessibility: CFString

    public init(service: String, accessGroup: String? = nil,
                accessibility: CFString = kSecAttrAccessibleWhenUnlockedThisDeviceOnly) {
        self.service = service; self.accessGroup = accessGroup; self.accessibility = accessibility
    }

    func baseQuery(account: String) -> [CFString: Any] {
        var q: [CFString: Any] = [
            kSecClass: kSecClassGenericPassword, kSecAttrService: service,
            kSecAttrAccount: account, kSecAttrAccessible: accessibility
        ]
        if let accessGroup { q[kSecAttrAccessGroup] = accessGroup }
        #if os(macOS)
        q[kSecUseDataProtectionKeychain] = true   // iOS-style data protection on macOS
        #endif
        return q
    }

    /// Add-or-update semantics: try update first, fall back to add.
    public func save(account: String, data: Data) throws {
        var searchQ = baseQuery(account: account)
        searchQ.removeValue(forKey: kSecAttrAccessible)
        let attrs: [CFString: Any] = [kSecValueData: data, kSecAttrAccessible: accessibility]
        var status = SecItemUpdate(searchQ as CFDictionary, attrs as CFDictionary)
        if status == errSecItemNotFound {
            var addQ = baseQuery(account: account); addQ[kSecValueData] = data
            status = SecItemAdd(addQ as CFDictionary, nil)
        }
        guard status == errSecSuccess else { throw KeychainError.unexpectedStatus(status) }
    }

    public func load(account: String) throws -> Data {
        var q = baseQuery(account: account)
        q.removeValue(forKey: kSecAttrAccessible)
        q[kSecReturnData] = kCFBooleanTrue; q[kSecMatchLimit] = kSecMatchLimitOne
        var result: AnyObject?
        let status = SecItemCopyMatching(q as CFDictionary, &result)
        switch status {
        case errSecSuccess: guard let d = result as? Data else { throw KeychainError.decodingFailed }; return d
        case errSecItemNotFound: throw KeychainError.itemNotFound
        default: throw KeychainError.unexpectedStatus(status)
        }
    }

    public func delete(account: String) throws {
        var q = baseQuery(account: account); q.removeValue(forKey: kSecAttrAccessible)
        let s = SecItemDelete(q as CFDictionary)
        guard s == errSecSuccess || s == errSecItemNotFound else { throw KeychainError.unexpectedStatus(s) }
    }

    /// Delete ALL items for this service — used during logout.
    public func deleteAll() throws {
        var q: [CFString: Any] = [kSecClass: kSecClassGenericPassword, kSecAttrService: service as CFString]
        if let accessGroup { q[kSecAttrAccessGroup] = accessGroup as CFString }
        #if os(macOS)
        q[kSecUseDataProtectionKeychain] = true
        #endif
        let s = SecItemDelete(q as CFDictionary)
        guard s == errSecSuccess || s == errSecItemNotFound else { throw KeychainError.unexpectedStatus(s) }
    }
}

// ✅ Pattern: Global actor for cross-module Keychain serialization
// Requires: iOS 13.0+ (global actors via Swift 5.5+)
@globalActor
actor KeychainActor {
    static let shared = KeychainActor()
}

@KeychainActor
func saveCredential(_ data: Data, account: String) throws {
    let query: [CFString: Any] = [
        kSecClass: kSecClassGenericPassword,
        kSecAttrService: "com.myapp.auth" as CFString,
        kSecAttrAccount: account as CFString,
        kSecAttrAccessible: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
        kSecValueData: data
    ]
    let status = SecItemAdd(query as CFDictionary, nil)
    guard status == errSecSuccess else {
        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
    }
}

// ✅ CORRECT — Codable token model with expiry tracking
struct OAuthTokens: Codable {
    let accessToken: String
    let refreshToken: String
    let expiresAt: Date
    let tokenType: String

    var isExpired: Bool {
        Date() >= expiresAt
    }

    /// Proactive refresh before expiry.
    /// Both providers agree: refresh at 75–90% of lifetime or with a fixed
    /// buffer (e.g., 60 seconds) to account for network latency and clock skew.
    var shouldRefresh: Bool {
        let buffer: TimeInterval = 60
        return Date() >= expiresAt.addingTimeInterval(-buffer)
    }
}

// ✅ CORRECT — ASWebAuthenticationSession + PKCE + Keychain storage
// Requires: iOS 13.0+ (for prefersEphemeralWebBrowserSession)
import AuthenticationServices
import CryptoKit

final class OAuthManager: NSObject, ASWebAuthenticationPresentationContextProviding {

    private let keychain = KeychainManager(
        service: "com.myapp.auth",
        accessibility: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
    )
    private let clientID = "mobile-app-client" // public client, no secret needed
    private let redirectScheme = "com.myapp.auth"

    func startAuthentication() async throws -> OAuthTokens {
        let codeVerifier = generateCodeVerifier()  // RFC 7636 PKCE
        let codeChallenge = generateCodeChallenge(from: codeVerifier)

        var components = URLComponents(string: "https://auth.example.com/authorize")!
        components.queryItems = [
            URLQueryItem(name: "response_type", value: "code"),
            URLQueryItem(name: "client_id", value: clientID),
            URLQueryItem(name: "redirect_uri", value: "\(redirectScheme)://callback"),
            URLQueryItem(name: "scope", value: "openid profile offline_access"),
            URLQueryItem(name: "code_challenge", value: codeChallenge),
            URLQueryItem(name: "code_challenge_method", value: "S256"),
            URLQueryItem(name: "state", value: UUID().uuidString)
        ]

        let callbackURL: URL = try await withCheckedThrowingContinuation { continuation in
            let session = ASWebAuthenticationSession(
                url: components.url!, callbackURLScheme: redirectScheme
            ) { url, error in
                if let error { continuation.resume(throwing: error) }
                else if let url { continuation.resume(returning: url) }
            }
            session.prefersEphemeralWebBrowserSession = true  // iOS 13+: no cookie sharing
            session.presentationContextProvider = self
            session.start()
        }

        guard let code = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)?
            .queryItems?.first(where: { $0.name == "code" })?.value else {
            throw OAuthError.missingAuthorizationCode
        }

        let tokens = try await exchangeCodeForTokens(code: code, codeVerifier: codeVerifier)
        try await keychain.save(account: "oauth_tokens", data: JSONEncoder().encode(tokens))
        return tokens
    }

    // MARK: - PKCE helpers (RFC 7636)

    private func generateCodeVerifier() -> String {
        var buffer = [UInt8](repeating: 0, count: 32)
        _ = SecRandomCopyBytes(kSecRandomDefault, buffer.count, &buffer)
        return Data(buffer).base64EncodedString()
            .replacingOccurrences(of: "+", with: "-")
            .replacingOccurrences(of: "/", with: "_")
            .replacingOccurrences(of: "=", with: "")
    }

    private func generateCodeChallenge(from verifier: String) -> String {
        // CryptoKit SHA256 (iOS 13.0+) — replaces legacy CC_SHA256
        let hash = SHA256.hash(data: Data(verifier.utf8))
        return Data(hash).base64EncodedString()
            .replacingOccurrences(of: "+", with: "-")
            .replacingOccurrences(of: "/", with: "_")
            .replacingOccurrences(of: "=", with: "")
    }

    private func exchangeCodeForTokens(code: String, codeVerifier: String) async throws -> OAuthTokens {
        // Standard OAuth2 token exchange — implement with your authorization server
        fatalError("Implement token exchange")
    }

    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor { ASPresentationAnchor() }
    enum OAuthError: Error { case missingAuthorizationCode }
}

// ✅ CORRECT — Atomic token refresh with rotation support
// Requires: iOS 13.0+ (actor serialization guarantees no interleaving)
extension KeychainManager {
    func atomicTokenUpdate(oldAccount: String = "oauth_tokens", newTokens: OAuthTokens) throws {
        let newData = try JSONEncoder().encode(newTokens) // Encode BEFORE mutation

        var delQ: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
                                      kSecAttrService: self.service as CFString,
                                      kSecAttrAccount: oldAccount as CFString]
        #if os(macOS)
        delQ[kSecUseDataProtectionKeychain] = true
        #endif
        let delStatus = SecItemDelete(delQ as CFDictionary)
        guard delStatus == errSecSuccess || delStatus == errSecItemNotFound else {
            throw KeychainError.unexpectedStatus(delStatus)
        }

        var addQ = baseQuery(account: oldAccount); addQ[kSecValueData] = newData
        let addStatus = SecItemAdd(addQ as CFDictionary, nil)
        guard addStatus == errSecSuccess else { throw KeychainError.unexpectedStatus(addStatus) }
    }
}

// ✅ CORRECT — Single-flight refresh coordinator
// Requires: iOS 13.0+
actor TokenRefreshCoordinator {

    private let keychain: KeychainManager
    private let tokenEndpoint: URL
    private var refreshTask: Task<OAuthTokens, Error>?

    init(keychain: KeychainManager, tokenEndpoint: URL) {
        self.keychain = keychain; self.tokenEndpoint = tokenEndpoint
    }

    /// Returns a valid access token, refreshing if necessary.
    func validAccessToken() async throws -> String {
        guard let data = try? await keychain.load(account: "oauth_tokens"),
              let tokens = try? JSONDecoder().decode(OAuthTokens.self, from: data) else {
            throw TokenError.notAuthenticated
        }
        guard tokens.shouldRefresh else { return tokens.accessToken }

        // Coalesce: reuse in-flight refresh if one exists
        if let existing = refreshTask { return try await existing.value.accessToken }

        let task = Task<OAuthTokens, Error> {
            defer { refreshTask = nil }
            return try await performRefresh(currentRefreshToken: tokens.refreshToken)
        }
        refreshTask = task
        return try await task.value.accessToken
    }

    private func performRefresh(currentRefreshToken: String) async throws -> OAuthTokens {
        var request = URLRequest(url: tokenEndpoint)
        request.httpMethod = "POST"
        request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
        request.httpBody = "grant_type=refresh_token&refresh_token=\(currentRefreshToken)".data(using: .utf8)

        let (data, response) = try await URLSession.shared.data(for: request)
        guard let http = response as? HTTPURLResponse else { throw TokenError.networkError }

        switch http.statusCode {
        case 200:
            // Decode server response (access_token, refresh_token?, expires_in, token_type)
            let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
            let newTokens = OAuthTokens(
                accessToken: json["access_token"] as! String,
                refreshToken: (json["refresh_token"] as? String) ?? currentRefreshToken,
                expiresAt: Date().addingTimeInterval(json["expires_in"] as! TimeInterval),
                tokenType: json["token_type"] as! String
            )
            try await keychain.atomicTokenUpdate(newTokens: newTokens)
            return newTokens
        case 400, 401:
            try? await keychain.deleteAll()  // Refresh token revoked — force re-auth
            throw TokenError.refreshTokenExpired
        default:
            throw TokenError.serverError(http.statusCode)
        }
    }

    enum TokenError: Error {
        case notAuthenticated, refreshTokenExpired, networkError, serverError(Int)
    }
}

// ✅ CORRECT — Runtime secret fetching with TTL-based Keychain cache
// Requires: iOS 13.0+
actor RuntimeSecretManager {

    private struct CachedSecret: Codable {
        let value: String; let fetchedAt: Date; let ttlSeconds: TimeInterval
        var isExpired: Bool { Date().timeIntervalSince(fetchedAt) >= ttlSeconds }
    }

    private let keychain: KeychainManager
    private let secretsEndpoint: URL
    private let defaultTTL: TimeInterval
    private var memoryCache: [String: CachedSecret] = [:]

    init(keychain: KeychainManager, secretsEndpoint: URL, defaultTTL: TimeInterval = 3600) {
        self.keychain = keychain; self.secretsEndpoint = secretsEndpoint; self.defaultTTL = defaultTTL
    }

    /// Three-tier lookup: memory → Keychain → network
    func secret(forKey key: String) async throws -> String {
        if let c = memoryCache[key], !c.isExpired { return c.value }

        if let data = try? await keychain.load(account: "secret_\(key)"),
           let c = try? JSONDecoder().decode(CachedSecret.self, from: data), !c.isExpired {
            memoryCache[key] = c; return c.value
        }

        let freshValue = try await fetchFromBackend(key: key)
        let cached = CachedSecret(value: freshValue, fetchedAt: Date(), ttlSeconds: defaultTTL)
        try await keychain.save(account: "secret_\(key)", data: JSONEncoder().encode(cached))
        memoryCache[key] = cached
        return freshValue
    }

    private func fetchFromBackend(key: String) async throws -> String {
        var request = URLRequest(url: secretsEndpoint.appendingPathComponent(key))
        // Authenticate with App Attest (iOS 14.0+) before backend issues secret
        let (data, response) = try await URLSession.shared.data(for: request)
        guard let http = response as? HTTPURLResponse, http.statusCode == 200,
              let json = try? JSONDecoder().decode([String: String].self, from: data),
              let value = json["value"] else { throw SecretFetchError.serverError }
        return value
    }

    enum SecretFetchError: Error { case serverError }
}

// ✅ CORRECT — Complete credential clearing on logout
// OWASP MASVS-STORAGE-1, MASVS-STORAGE-2 compliant | iOS 13.0+
actor SessionManager {

    private let keychain = KeychainManager(service: "com.myapp.auth",
                                            accessibility: kSecAttrAccessibleWhenUnlockedThisDeviceOnly)

    func logout() async {
        // 1. Server-side revocation (best-effort)
        if let data = try? await keychain.load(account: "oauth_tokens"),
           let tokens = try? JSONDecoder().decode(OAuthTokens.self, from: data) {
            try? await revoke(token: tokens.refreshToken)
            try? await revoke(token: tokens.accessToken)
        }
        // 2. Nuclear Keychain cleanup — ALL items for this service
        try? await keychain.deleteAll()
        // 3. Clear cookies for auth domain
        HTTPCookieStorage.shared.cookies(for: URL(string: "https://auth.example.com")!)?
            .forEach { HTTPCookieStorage.shared.deleteCookie($0) }
        // 4. Clear URL cache
        URLCache.shared.removeAllCachedResponses()
    }

    private func revoke(token: String) async throws {
        var req = URLRequest(url: URL(string: "https://auth.example.com/oauth/revoke")!)
        req.httpMethod = "POST"
        req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
        req.httpBody = "token=\(token)".data(using: .utf8)
        _ = try await URLSession.shared.data(for: req)
    }
}

// ✅ CORRECT — Versioned Keychain migration during rotation
// Requires: iOS 13.0+
actor TokenMigrationManager {

    private let keychain: KeychainManager
    private static let currentVersion = 2

    init(keychain: KeychainManager) { self.keychain = keychain }

    /// Call on app launch to migrate old token formats.
    func migrateIfNeeded() async throws {
        if let _ = try? await keychain.load(account: "oauth_tokens_v2") {
            return // Already current
        }
        if let oldData = try? await keychain.load(account: "oauth_tokens") {
            let migrated = try migrateV1ToV2(oldData)
            try await keychain.save(account: "oauth_tokens_v2", data: migrated)
            try await keychain.delete(account: "oauth_tokens") // Clean up old
        }
    }

    private func migrateV1ToV2(_ data: Data) throws -> Data {
        // Implement format conversion between versions
        return data
    }
}

// ✅ Pattern: Detect missing credentials after device restore
func handleAppLaunch() async {
    do {
        let _ = try await keychain.load(account: "oauth_tokens_v2")
        // Tokens present — proceed normally
    } catch KeychainManager.KeychainError.itemNotFound {
        // Likely a fresh install or device restore
        // Route to authentication flow
        await presentLoginScreen()
    } catch {
        // Unexpected error — log and route to auth
        logger.error("Keychain load failed: \(error)")
        await presentLoginScreen()
    }
}

// ✅ CORRECT — Maximum OWASP MASTG L2 compliance configuration
// Requires: iOS 11.3+ (for .or compound constraint)
func createHighSecurityKeychainItem(account: String, secret: Data) throws {
    var error: Unmanaged<CFError>?
    guard let accessControl = SecAccessControlCreateWithFlags(
        kCFAllocatorDefault,
        kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
        [.biometryCurrentSet, .or, .devicePasscode],
        &error
    ) else {
        throw error!.takeRetainedValue() as Error
    }

    let query: [CFString: Any] = [
        kSecClass: kSecClassGenericPassword,
        kSecAttrService: "com.myapp.auth" as CFString,
        kSecAttrAccount: account as CFString,
        kSecValueData: secret,
        kSecAttrAccessControl: accessControl,
        kSecUseDataProtectionKeychain: true
    ]

    let status = SecItemAdd(query as CFDictionary, nil)
    guard status == errSecSuccess else {
        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
    }
}