Authentication – Refresh, persistence & API

Core/OAuthService/OAuthService.swift

@@ -0,0 +1,45 @@
+//
+//  OAuthService.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 08/01/2025.
+//
+
+import Foundation
+import UIKit
+
+public enum OAuthServiceError: Error {
+    case failedToRefreshTokens(Error?)
+
+    case stateDataDecodingError(Error?)
+
+    case failedToDiscoverService(Error?)
+
+    case failedToAuthenticate(Error?)
+}
+
+/// Encapsulates the OAuth state data. Should only be managed and mutated by `OAuthService.`
+public protocol OAuthStateData {
+    var isAuthorized: Bool { get }
+}
+
+/// An abstraction for handling the OAuth flow steps.
+///
+/// The service is assumed not to have any internal state. It's the responsibility of the client of this service
+/// to hold and persist the state data. Each call to the service returns an updated `OAuthStateData`
+/// that reflects the latest state.
+public protocol OAuthService {
+    func login(on viewController: UIViewController) async throws -> OAuthStateData
+
+    func getAccessToken(using data: OAuthStateData) async throws -> (String, OAuthStateData)
+
+    func refreshIfNeeded(data: OAuthStateData) async throws -> OAuthStateData
+}
+
+/// Encodes and decodes the `OAuthStateData`. A convneience to hide the conforming `OAuthStateData` type
+/// while preparing the state for persistence.
+public protocol OAuthStateDataEncoder {
+    func encode(_ data: OAuthStateData) throws -> Data
+
+    func decode(_ data: Data) throws -> OAuthStateData
+}

Data/AuthenticationClient/Sources/AppAuthOAuthService.swift

@@ -0,0 +1,158 @@
+//
+//  AppAuthOAuthService.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 08/01/2025.
+//
+
+import AppAuth
+import Foundation
+import OAuthService
+import VLogging
+
+struct AppAuthStateData: OAuthStateData {
+    let state: OIDAuthState
+
+    var isAuthorized: Bool { state.isAuthorized }
+}
+
+struct AppAuthStateEncoder: OAuthStateDataEncoder {
+    func encode(_ data: any OAuthStateData) throws -> Data {
+        guard let data = data as? AppAuthStateData else {
+            fatalError()
+        }
+        let encoded = try NSKeyedArchiver.archivedData(
+            withRootObject: data.state,
+            requiringSecureCoding: true
+        )
+        return encoded
+    }
+
+    func decode(_ data: Data) throws -> any OAuthStateData {
+        guard let state = try NSKeyedUnarchiver.unarchivedObject(ofClass: OIDAuthState.self, from: data) else {
+            throw OAuthServiceError.stateDataDecodingError(nil)
+        }
+        return AppAuthStateData(state: state)
+    }
+}
+
+final class AppAuthOAuthService: OAuthService {
+    // MARK: Lifecycle
+
+    init(appConfigurations: AuthenticationClientConfiguration) {
+        self.appConfigurations = appConfigurations
+    }
+
+    // MARK: Internal
+
+    func login(on viewController: UIViewController) async throws -> any OAuthStateData {
+        // Quran.com relies on dicovering the service configuration from the issuer,
+        // and not using a static configuration.
+        let serviceConfiguration = try await discoverConfiguration(forIssuer: appConfigurations.authorizationIssuerURL)
+        let state = try await login(
+            withConfiguration: serviceConfiguration,
+            appConfiguration: appConfigurations,
+            on: viewController
+        )
+        return AppAuthStateData(state: state)
+    }
+
+    func getAccessToken(using data: any OAuthStateData) async throws -> (String, any OAuthStateData) {
+        guard let data = data as? AppAuthStateData else {
+            // This should be a fatal error.
+            fatalError()
+        }
+        return try await withCheckedThrowingContinuation { continuation in
+            data.state.performAction { accessToken, clientID, error in
+                guard error == nil else {
+                    logger.error("Failed to refresh tokens: \(error!)")
+                    continuation.resume(throwing: OAuthServiceError.failedToRefreshTokens(error))
+                    return
+                }
+                guard let accessToken else {
+                    logger.error("Failed to refresh tokens: No access token returned. An unexpected situation.")
+                    continuation.resume(throwing: OAuthServiceError.failedToRefreshTokens(nil))
+                    return
+                }
+                let updatedData = AppAuthStateData(state: data.state)
+                continuation.resume(returning: (accessToken, updatedData))
+            }
+        }
+    }
+
+    func refreshIfNeeded(data: any OAuthStateData) async throws -> any OAuthStateData {
+        try await getAccessToken(using: data).1
+    }
+
+    // MARK: Private
+
+    private let appConfigurations: AuthenticationClientConfiguration
+
+    // Needed mainly for retention.
+    private var authFlow: (any OIDExternalUserAgentSession)?
+
+    // MARK: - Authenication Flow
+
+    private func discoverConfiguration(forIssuer issuer: URL) async throws -> OIDServiceConfiguration {
+        logger.info("Discovering configuration for OAuth")
+        return try await withCheckedThrowingContinuation { continuation in
+            OIDAuthorizationService
+                .discoverConfiguration(forIssuer: issuer) { configuration, error in
+                    guard error == nil else {
+                        logger.error("Error fetching OAuth configuration: \(error!)")
+                        continuation.resume(throwing: OAuthServiceError.failedToDiscoverService(error))
+                        return
+                    }
+                    guard let configuration else {
+                        // This should not happen
+                        logger.error("Error fetching OAuth configuration: no configuration was loaded. An unexpected situtation.")
+                        continuation.resume(throwing: OAuthServiceError.failedToDiscoverService(nil))
+                        return
+                    }
+                    logger.info("OAuth configuration fetched successfully")
+                    continuation.resume(returning: configuration)
+                }
+        }
+    }
+
+    private func login(
+        withConfiguration configuration: OIDServiceConfiguration,
+        appConfiguration: AuthenticationClientConfiguration,
+        on viewController: UIViewController
+    ) async throws -> OIDAuthState {
+        let scopes = [OIDScopeOpenID, OIDScopeProfile] + appConfiguration.scopes
+        let request = OIDAuthorizationRequest(
+            configuration: configuration,
+            clientId: appConfiguration.clientID,
+            clientSecret: nil,
+            scopes: scopes,
+            redirectURL: appConfiguration.redirectURL,
+            responseType: OIDResponseTypeCode,
+            additionalParameters: [:]
+        )
+
+        logger.info("Starting OAuth flow")
+        return try await withCheckedThrowingContinuation { continuation in
+            DispatchQueue.main.async {
+                self.authFlow = OIDAuthState.authState(
+                    byPresenting: request,
+                    presenting: viewController
+                ) { [weak self] state, error in
+                    self?.authFlow = nil
+                    guard error == nil else {
+                        logger.error("Error authenticating: \(error!)")
+                        continuation.resume(throwing: OAuthServiceError.failedToAuthenticate(error))
+                        return
+                    }
+                    guard let state else {
+                        logger.error("Error authenticating: no state returned. An unexpected situtation.")
+                        continuation.resume(throwing: OAuthServiceError.failedToAuthenticate(nil))
+                        return
+                    }
+                    logger.info("OAuth flow completed successfully")
+                    continuation.resume(returning: state)
+                }
+            }
+        }
+    }
+}

Data/AuthenticationClient/Sources/AuthenticationClient.swift

@@ -0,0 +1,65 @@
+//
+//  AuthenticationClient.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 19/12/2024.
+//
+
+import Foundation
+import UIKit
+
+public enum AuthenticationClientError: Error {
+    case errorAuthenticating(Error?)
+
+    /// Thrown when an operation, that needs authentication, is attempted while the client
+    /// hasn't been authenticated or if the client's access has been revoked.
+    case clientIsNotAuthenticated(Error?)
+}
+
+public enum AuthenticationState: Equatable {
+    /// 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 AuthenticationClientConfiguration {
+    public let clientID: String
+    public let redirectURL: URL
+    /// Indicates the Quran.com specific scopes to be requested by the app.
+    /// The client requests the `offline` and `openid` scopes by default.
+    public let scopes: [String]
+    public let authorizationIssuerURL: URL
+
+    public init(clientID: String, redirectURL: URL, scopes: [String], authorizationIssuerURL: URL) {
+        self.clientID = clientID
+        self.redirectURL = redirectURL
+        self.scopes = scopes
+        self.authorizationIssuerURL = authorizationIssuerURL
+    }
+}
+
+/// Handles the OAuth flow to Quran.com
+///
+/// Expected to be configuered with the host app's OAuth configuration before further operations are attempted.
+public protocol AuthenticationClient {
+    /// 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 async }
+}
+
+public enum AuthentincationClientBuilder {
+    public static func make(withConfigurations config: AuthenticationClientConfiguration) -> AuthenticationClient {
+        AuthenticationClientImpl(configurations: config)
+    }
+}