documentation

Author: MattKiazyk

README.md

@@ -1,5 +1,130 @@
 ## XcodesLoginKit
 
-An Swift API to log in to to Apple's developer website.
+A Swift API for signing in to Apple's developer services.
 
-More to come. 
+XcodesLoginKit handles Apple's SRP password login, federated Apple IDs, two-factor
+authentication, session validation, logout, and optional fastlane/Spaceship cookie import.
+
+### Getting started
+
+Add the package to your `Package.swift`:
+
+```swift
+.package(url: "https://github.com/XcodesOrg/XcodesLoginKit", branch: "main")
+```
+
+Then add the product you need:
+
+```swift
+.product(name: "XcodesLoginKit", package: "XcodesLoginKit")
+```
+
+Use `Client` when your app wants to drive its own sign-in UI:
+
+```swift
+import Foundation
+import XcodesLoginKit
+
+let client = Client()
+
+let state = try await client.authenticationState(
+    accountName: "name@example.com",
+    password: password
+)
+
+switch state {
+case .authenticated(let session):
+    print("Signed in as \(session.user.fullName ?? "Apple Developer")")
+
+case .waitingForFederatedAuthentication(let federation):
+    guard let idpURL = federation.idpURL else {
+        throw AuthenticationError.federatedAuthenticationRequired
+    }
+
+    // Open idpURL in a browser. After the user signs in, collect the redirected URL.
+    let callbackURLString = "... pasted or received callback URL ..."
+    try await client.validateFederatedCallbackURLString(callbackURLString)
+
+case .waitingForSecondFactor(let option, let authOptions, let sessionData):
+    switch option {
+    case .codeSent:
+        let code = "... code from trusted device ..."
+        try await client.submitSecurityCode(.device(code: code), sessionData: sessionData)
+
+    case .smsPendingChoice:
+        guard let phoneNumber = authOptions.trustedPhoneNumbers?.first else { return }
+        try await client.requestSMSSecurityCode(
+            to: phoneNumber,
+            authOptions: authOptions,
+            sessionData: sessionData
+        )
+
+    case .smsSent(let phoneNumber):
+        let code = "... code from SMS ..."
+        try await client.submitSecurityCode(
+            .sms(code: code, phoneNumberId: phoneNumber.id),
+            sessionData: sessionData
+        )
+
+    case .securityKey:
+        // Add the XcodesLoginKitSecurityKey product and call
+        // submitSecurityKeyPinCode(_:sessionData:authOptions:).
+        break
+    }
+
+case .unauthenticated, .notAppleDeveloper:
+    break
+}
+```
+
+### Main flow
+
+1. Create a `Client`. Pass a custom `URLSession` if you want isolated cookie storage.
+2. Call `authenticationState(accountName:password:)`.
+3. Switch on `AuthenticationState`.
+4. Complete any required federated authentication or second-factor challenge.
+5. Call `validateSession()` later to check whether stored cookies are still valid.
+6. Call `signout()` to clear the client's cookies.
+
+### Federated Apple IDs
+
+Federated accounts return `.waitingForFederatedAuthentication`. Open `FederationResponse.idpURL`
+in a browser, let the user finish identity-provider sign-in, then pass the final callback URL to
+`validateFederatedCallbackURL(_:)` or `validateFederatedCallbackURLString(_:)`.
+
+### Reusing fastlane sessions
+
+If the user already has a fastlane session, load its cookies into a session and pass that session
+to `Client`:
+
+```swift
+let loader = FastlaneSessionLoader()
+let session = try loader.session(
+    fastlaneUser: "name@example.com",
+    environmentValue: { ProcessInfo.processInfo.environment[$0] }
+)
+
+let client = Client(urlSession: session)
+let state = try await client.validateSession()
+```
+
+Use `FastlaneSessionLoader.Constants.fastlaneSessionEnvVarName` as `fastlaneUser` to load cookies
+from `FASTLANE_SESSION` instead of `~/.fastlane/spaceship/<apple-id>/cookie`.
+
+### Higher-level session management
+
+`AppleSessionService` wraps the low-level client with dependency-injected environment lookup,
+keychain storage, prompts, browser opening, validation, login, and logout. It is a good fit for
+command-line tools that want a "login if needed" workflow while still controlling where credentials
+are stored and how users are prompted.
+
+### Security keys
+
+Add the `XcodesLoginKitSecurityKey` product when you need FIDO2 security-key support:
+
+```swift
+.product(name: "XcodesLoginKitSecurityKey", package: "XcodesLoginKit")
+```
+
+When the login state is `.waitingForSecondFactor(.securityKey, authOptions, sessionData)`, call
+`submitSecurityKeyPinCode(_:sessionData:authOptions:)`.

Sources/XcodesLoginKit/AppleSessionService.swift

@@ -1,5 +1,11 @@
 import Foundation
 
+/// Coordinates credential lookup, prompting, login, validation, and logout for Apple Developer sessions.
+///
+/// `AppleSessionService` is the high-level API for command-line tools and apps that want an injectable
+/// workflow around ``Client``. It can read credentials from environment variables or a keychain, prompt
+/// when credentials are missing, open a browser for federated accounts, and remember the default username
+/// after a successful login.
 public actor AppleSessionService {
     public typealias EnvironmentValue = @Sendable (String) -> String?
     public typealias DefaultUsername = @Sendable () -> String?
@@ -19,25 +25,48 @@ public actor AppleSessionService {
     public typealias LoadData = @Sendable (URLRequest) async throws -> (Data, URLResponse)
     public typealias Log = @Sendable (String) -> Void
 
+    /// Dependencies used by ``AppleSessionService`` to interact with the host app and storage.
+    ///
+    /// Supply closures for environment lookup, keychain access, prompting, browser opening, networking,
+    /// and the underlying login operations. This keeps the service testable and lets each app decide how
+    /// credentials and user interaction should work.
     public struct Dependencies: Sendable {
+        /// Reads a process environment value.
         public var environmentValue: EnvironmentValue
+        /// Returns the remembered default Apple ID, if any.
         public var defaultUsername: DefaultUsername
+        /// Stores or clears the remembered default Apple ID.
         public var setDefaultUsername: SetDefaultUsername
+        /// Reads a string from secure storage for a username.
         public var keychainString: KeychainString
+        /// Stores a string in secure storage for a username.
         public var keychainSet: KeychainSet
+        /// Removes a username's stored secret.
         public var keychainRemove: KeychainRemove
+        /// Prompts for a single line of input.
         public var readLine: ReadLine
+        /// Prompts for a long line of input, such as a pasted browser callback URL.
         public var readLongLine: ReadLongLine
+        /// Prompts for hidden input, such as a password.
         public var readSecureLine: ReadSecureLine
+        /// Validates the current Apple session.
         public var validateSession: ValidateSession
+        /// Performs username and password login.
         public var login: Login
+        /// Checks whether an Apple ID uses federated authentication.
         public var checkIsFederated: CheckIsFederated
+        /// Completes federated login from a pasted callback URL string.
         public var validateFederatedCallbackURL: ValidateFederatedCallbackURL
+        /// Opens a URL in the host app or system browser.
         public var openURL: OpenURL
+        /// Signs out from the underlying Apple session.
         public var signout: Signout
+        /// Loads data for a URL request, used by developer-portal validation.
         public var loadData: LoadData
+        /// Receives user-visible progress or recovery messages.
         public var log: Log
 
+        /// Creates a dependency container for ``AppleSessionService``.
         public init(
             environmentValue: @escaping EnvironmentValue,
             defaultUsername: @escaping DefaultUsername,
@@ -81,6 +110,7 @@ public actor AppleSessionService {
     private let xcodesPassword = "XCODES_PASSWORD"
     private let dependencies: Dependencies
 
+    /// Creates a service with the host-provided dependencies.
     public init(dependencies: Dependencies) {
         self.dependencies = dependencies
     }
@@ -103,12 +133,24 @@ public actor AppleSessionService {
         return nil
     }
 
+    /// Validates that the current session is authorized to access an Apple Developer download path.
+    ///
+    /// - Parameter path: The developer download path to validate, such as a path from an Xcode release.
     public func validateADCSession(path: String) async throws {
         try await DeveloperPortalSessionService(
             loadData: dependencies.loadData
         ).validateADCSession(path: path)
     }
 
+    /// Ensures that a valid Apple session exists, prompting or signing in only when needed.
+    ///
+    /// The service first calls `validateSession`. If that fails, it looks for a username from the
+    /// provided argument, `XCODES_USERNAME`, or the remembered default username. Passwords are read from
+    /// `XCODES_PASSWORD`, secure storage, or `readSecureLine`. Federated accounts open the identity
+    /// provider URL and ask the user to paste the callback URL.
+    /// - Parameters:
+    ///   - providedUsername: A username to try before environment or default values.
+    ///   - shouldPromptForPassword: Pass `true` to ignore saved passwords and force a password prompt.
     public func loginIfNeeded(withUsername providedUsername: String? = nil, shouldPromptForPassword: Bool = false) async throws {
         do {
             try await dependencies.validateSession()
@@ -180,6 +222,9 @@ public actor AppleSessionService {
         }
     }
 
+    /// Logs in with an explicit username and password, then stores successful credentials.
+    ///
+    /// If Apple reports invalid credentials, the stored password for that username is removed.
     public func login(_ username: String, password: String) async throws {
         do {
             try await dependencies.login(username, password)
@@ -198,6 +243,7 @@ public actor AppleSessionService {
         }
     }
 
+    /// Signs out, removes the stored password, and clears the remembered default username.
     public func logout() async throws {
         guard let username = findUsername() else { throw Error.notAuthenticated }
 
@@ -208,10 +254,14 @@ public actor AppleSessionService {
 }
 
 public extension AppleSessionService {
+    /// Errors raised by the high-level session service before or after Apple authentication.
     enum Error: LocalizedError, Equatable {
+        /// No username or password was available from dependencies or prompting.
         case missingUsernameOrPassword
+        /// Logout was requested when no username could be found.
         case notAuthenticated
 
+        /// A user-visible description of the service error.
         public var errorDescription: String? {
             switch self {
             case .missingUsernameOrPassword:

Sources/XcodesLoginKit/AuthenticationError.swift

@@ -7,26 +7,46 @@
 
 import Foundation
 
+/// Errors returned by XcodesLoginKit's Apple authentication flow.
 public enum AuthenticationError: Swift.Error, LocalizedError, Equatable, Sendable {
+    /// The current cookies do not represent a valid Apple session.
     case invalidSession
+    /// Apple's hashcash challenge could not be solved or parsed.
     case invalidHashcash
+    /// Apple rejected the username and password combination.
     case invalidUsernameOrPassword(username: String)
+    /// Apple rejected the submitted two-factor verification code.
     case incorrectSecurityCode
+    /// Apple returned a sign-in response that XcodesLoginKit does not recognize.
     case unexpectedSignInResponse(statusCode: Int, message: String?)
+    /// The Apple ID & Privacy agreement must be acknowledged in App Store Connect.
     case appleIDAndPrivacyAcknowledgementRequired
+    /// The account uses legacy two-step authentication, which is not supported.
     case accountUsesTwoStepAuthentication
+    /// Apple reported an authentication kind that XcodesLoginKit cannot classify.
     case accountUsesUnknownAuthenticationKind(String?)
+    /// Apple reports that the account is locked.
     case accountLocked(String)
+    /// Apple returned an unexpected HTTP status code.
     case badStatusCode(statusCode: Int, data: Data?, response: HTTPURLResponse)
+    /// The Apple ID is not registered as an Apple Developer.
     case notDeveloperAppleId
+    /// The current session is not authorized for the requested operation.
     case notAuthorized
+    /// Apple returned an invalid or unexpected result payload.
     case invalidResult(resultString: String?)
+    /// The SRP public key or salt returned by Apple could not be decoded.
     case srpInvalidPublicKey
+    /// The user cancelled security-key authentication.
     case userCancelledSecurityKeyAuthentication
+    /// The account requires federated authentication via a browser.
     case federatedAuthenticationRequired
+    /// The federated callback URL did not include the required query parameters.
     case invalidFederatedAuthenticationCallback
+    /// A password is required because the account is not federated.
     case missingPasswordForNonFederatedAccount
 
+    /// A user-visible error description.
     public var errorDescription: String? {
         switch self {
         case .invalidSession: