Authentication – Refresh, persistence & API

Data/AuthenticationClient/Sources/AuthenticationData.swift

@@ -0,0 +1,121 @@
+//
+//  AuthenticationData.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 27/12/2024.
+//
+
+import AppAuth
+import Combine
+import Foundation
+import VLogging
+
+enum AuthenticationStateError: Error {
+    /// Throws when the refresh token operation fails. Assume that the user is not authenticated anymore.
+    case failedToRefreshTokens(Error?)
+
+    /// Failed to decode the persisted state back.
+    case decodingError(Error?)
+}
+
+/// A wrapper for the authentication state's data.
+///
+/// The abstraction is mainly for testing purposes. The API has been designed to be in conjunction
+/// with the `AppAuth's OIDAuthState` class.
+class AuthenticationData: NSObject, Codable {
+    /// Invokes subscribers when the state changes. Usually happens during refreshing tokens.
+    var stateChangedPublisher: AnyPublisher<Void, Never> { fatalError() }
+
+    var isAuthorized: Bool {
+        fatalError()
+    }
+
+    /// Returns fresh access token to be used for API requests.
+    ///
+    /// - throws: `AuthenticationStateError.failedToRefreshTokens` if the
+    /// refresh operation fails for any reason.
+    func getFreshTokens() async throws -> String {
+        fatalError()
+    }
+
+    override init() { }
+
+    required init(from decoder: any Decoder) throws {
+        fatalError()
+    }
+}
+
+class AppAuthAuthenticationData: AuthenticationData {
+    private enum CodingKeys: String, CodingKey {
+        case state
+    }
+
+    private let stateChangedSubject: PassthroughSubject<Void, Never> = .init()
+    override var stateChangedPublisher: AnyPublisher<Void, Never> {
+        stateChangedSubject.eraseToAnyPublisher()
+    }
+
+    private var state: OIDAuthState {
+        didSet {
+            stateChangedSubject.send()
+        }
+    }
+
+    override var isAuthorized: Bool {
+        state.isAuthorized
+    }
+
+    init(state: OIDAuthState) {
+        self.state = state
+        super.init()
+        state.stateChangeDelegate = self
+    }
+
+    required init(from decoder: any Decoder) throws {
+        do {
+            let container = try decoder.container(keyedBy: CodingKeys.self)
+            let data = try container.decode(Data.self, forKey: .state)
+            guard let state = try NSKeyedUnarchiver.unarchivedObject(ofClass: OIDAuthState.self, from: data) else {
+                logger.error("Failed to decode OIDAuthState: Failed to unarchive data")
+                throw AuthenticationStateError.decodingError(nil)
+            }
+            self.state = state
+        } catch {
+            logger.error("Failed to decode OIDAuthState: \(error)")
+            throw AuthenticationStateError.decodingError(error)
+        }
+        super.init()
+        state.stateChangeDelegate = self
+    }
+
+    override func encode(to encoder: any Encoder) throws {
+        var container: KeyedEncodingContainer<CodingKeys> = encoder.container(keyedBy: CodingKeys.self)
+        let data = try NSKeyedArchiver.archivedData(withRootObject: state, requiringSecureCoding: true)
+        try container.encode(data, forKey: .state)
+    }
+
+    override func getFreshTokens() async throws -> String {
+        return try await withCheckedThrowingContinuation { continuation in
+            state.performAction { accessToken, clientID, error in
+                guard error == nil else {
+                    logger.error("Failed to refresh tokens: \(error!)")
+                    continuation.resume(throwing: AuthenticationStateError.failedToRefreshTokens(error))
+                    return
+                }
+                guard let accessToken else {
+                    logger.error("Failed to refresh tokens: No access token returned. An unexpected situation.")
+                    continuation.resume(throwing: AuthenticationStateError.failedToRefreshTokens(nil))
+                    return
+                }
+                continuation.resume(returning: accessToken)
+            }
+        }
+    }
+}
+
+extension AppAuthAuthenticationData: OIDAuthStateChangeDelegate {
+    func didChange(_ state: OIDAuthState) {
+        logger.info("OIDAuthState changed - isAuthorized: \(state.isAuthorized)")
+        stateChangedSubject.send()
+    }
+}

Data/OAuthClient/Sources/OAuthClient.swift → Data/AuthenticationClient/Sources/AuthentincationDataManager.swift

@@ -1,5 +1,5 @@
 //
-//  OAuthClient.swift
+//  AuthentincationDataManager.swift
 //  QuranEngine
 //
 //  Created by Mohannad Hassan on 19/12/2024.
@@ -10,8 +10,23 @@ import UIKit
 
 public enum OAuthClientError: Error {
     case oauthClientHasNotBeenSet
-    case errorFetchingConfiguration(Error?)
     case errorAuthenticating(Error?)
+
+    /// Thrown when an operation, that needs authentication, is attempted wheile the client
+    /// hasn't been authenticated or if the client's access has been revoked.
+    case clientIsNotAuthenticated
+}
+
+public enum AuthenticationState: Equatable {
+    /// Authentication is not available. Any action dependent on authentication
+    /// (such as logging in or invoking user APIs) should not be attempted..
+    case notAvailable
+
+    /// No user is currently authenticated, or access has been revoked or is expired.
+    /// Logging in is availble and is required for further APIs.
+    case notAuthenticated
+
+    case authenticated
 }
 
 public struct OAuthAppConfiguration {
@@ -32,13 +47,21 @@ public struct OAuthAppConfiguration {
 
 /// Handles the OAuth flow to Quran.com
 ///
-/// Note that the connection relies on dicvoering the configuration from the issuer service.
-public protocol OAuthClient {
+/// Expected to be configuered with the host app's OAuth configuration before further operations are attempted.
+public protocol AuthentincationDataManager {
+    /// Sets the app configuration to be used for authentication.
     func set(appConfiguration: OAuthAppConfiguration)
 
     /// Performs the login flow to Quran.com
     ///
     /// - Parameter viewController: The view controller to be used as base for presenting the login flow.
     /// - Returns: Nothing is returned for now. The client may return the profile infromation in the future.
     func login(on viewController: UIViewController) async throws
+
+    /// Returns `true` if the client is authenticated.
+    func restoreState() async throws -> Bool
+
+    func authenticate(request: URLRequest) async throws -> URLRequest
+
+    var authenticationState: AuthenticationState { get }
 }

Data/AuthenticationClient/Sources/AuthentincationDataManagerImpl.swift

@@ -0,0 +1,120 @@
+//
+//  AuthentincationDataManagerImpl.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 23/12/2024.
+//
+
+import AppAuth
+import Combine
+import Foundation
+import UIKit
+import VLogging
+
+public final class AuthentincationDataManagerImpl: AuthentincationDataManager {
+    // MARK: Lifecycle
+
+    init(caller: OAuthCaller, persistance: Persistance) {
+        self.caller = caller
+        self.persistance = persistance
+    }
+
+    // MARK: Public
+
+    public var authenticationState: AuthenticationState {
+        guard appConfiguration != nil else {
+            return .notAvailable
+        }
+        return state?.isAuthorized == true ? .authenticated : .notAuthenticated
+    }
+
+    public func set(appConfiguration: OAuthAppConfiguration) {
+        self.appConfiguration = appConfiguration
+    }
+
+    public func login(on viewController: UIViewController) async throws {
+        do {
+            try persistance.clear()
+            logger.info("Cleared previous authentication state before login")
+        } catch {
+            // If persisting the new state works, this error should be of little concern.
+            logger.warning("Failed to clear previous authentication state before login: \(error)")
+        }
+
+        guard let configuration = appConfiguration else {
+            logger.error("login invoked without OAuth client configurations being set")
+            throw OAuthClientError.oauthClientHasNotBeenSet
+        }
+
+        let state = try await caller.login(using: configuration, on: viewController)
+        self.state = state
+        logger.info("login succeeded with state. isAuthorized: \(state.isAuthorized)")
+        persist(state: state)
+    }
+
+    public func restoreState() async throws -> Bool {
+        guard appConfiguration != nil else {
+            logger.error("restoreState invoked without OAuth client configurations being set")
+            throw OAuthClientError.oauthClientHasNotBeenSet
+        }
+        guard let state = try persistance.retrieve() else {
+            logger.info("No previous authentication state found")
+            return false
+        }
+        // TODO: Called for the side effects!
+        _ = try await state.getFreshTokens()
+        self.state = state
+        logger.info("Restored previous authentication state. isAuthorized: \(state.isAuthorized)")
+        return state.isAuthorized
+    }
+
+    public func authenticate(request: URLRequest) async throws -> URLRequest {
+        guard let configuration = appConfiguration else {
+            logger.error("authenticate invoked without OAuth client configurations being set")
+            throw OAuthClientError.oauthClientHasNotBeenSet
+        }
+        guard authenticationState == .authenticated, let state else {
+            logger.error("authenticate invoked without client being authenticated")
+            throw OAuthClientError.clientIsNotAuthenticated
+        }
+        let token = try await state.getFreshTokens()
+        var request = request
+        request.setValue(token, forHTTPHeaderField: "x-auth-token")
+        request.setValue(configuration.clientID, forHTTPHeaderField: "x-client-id")
+        return request
+    }
+
+    // MARK: Private
+
+    private let caller: OAuthCaller
+    private let persistance: Persistance
+
+    private var cancellables = Set<AnyCancellable>()
+
+    private var appConfiguration: OAuthAppConfiguration?
+
+    private var state: AuthenticationData? {
+        didSet {
+            guard let state else { return }
+            state.stateChangedPublisher.sink { [weak self] _ in
+                self?.persist(state: state)
+            }.store(in: &cancellables)
+        }
+    }
+
+    private func persist(state: AuthenticationData) {
+        do {
+            try persistance.persist(state: state)
+        } catch {
+            // If this happens, the state will not nullified so to keep the current session usable
+            // for the user. As for now, no workaround is in hand.
+            logger.error("Failed to persist authentication state. No workaround in hand.: \(error)")
+        }
+    }
+}
+
+extension AuthentincationDataManagerImpl {
+    public convenience init() {
+        self.init(caller: AppAuthCaller(), persistance: KeychainPersistance())
+    }
+}