Auth0.swift SDK

DocsVersions is a dependency-free Swift tool designed to organize DocC static sites into a versioned GitHub Pages layout.

Because DocC renders navigation as a client-side Vue app, DocsVersions does not rewrite HTML at build time. Instead, it injects a runtime script (version-selector.js) into every page. This script adds a version-switcher dropdown to the UI by reading a shared versions.json file.

Key features include:

• Automatic Versioning: Reads versions from Auth0/Version.swift or a provided flag.
• Retention Policy: Implements a 'keep-two-major-lines' policy to ensure the latest major release and the previous major's latest stable release remain available.
• Root Mirroring: For stable releases, it mirrors the content at the site root so the canonical, version-less URL always serves the latest stable documentation.
• Zero Dependencies: It uses only minimal SemVer requirements, making it portable.

When handling errors from the Auth0.authentication() flow (rather than the MFA client), use the following properties on AuthenticationError to identify MFA scenarios:

• isMultifactorRequired: MFA is required to authenticate.
• isMultifactorEnrollRequired: MFA is required and the user is not yet enrolled.
• isMultifactorCodeInvalid: The MFA code sent is invalid or expired (legacy).
• isMultifactorTokenInvalid: The MFA token is invalid or expired (legacy).

Warning: Do not rely on parsing error message strings. Always use the code property or the boolean flags provided by the API.

Auth0.authentication()
    .login(usernameOrEmail: "user@example.com", password: "password", realmOrConnection: "Username-Password-Authentication")
    .start { result in
        switch result {
        case .success(let credentials):
            print("Success: \(credentials)")
        case .failure(let error) where error.isMultifactorRequired:
            print("MFA is required")
            // Proceed with MFA flow using extracted token
        case .failure(let error):
            print("Failed with: \(error)")
        }
    }

The Auth0.swift SDK follows several consistent design patterns that you should be aware of when extending or interacting with the library:

• Protocol-based API: Every public API is defined as a protocol (e.g., Authentication, WebAuth, MFAClient). The concrete implementations (e.g., Auth0Authentication, Auth0WebAuth) are package-internal.
• Dual API (Callback + Async/Await): Every public method provides two ways to call it: a completion handler variant and a Swift concurrency (async throws) variant.
• Builder Pattern: The WebAuth API uses a fluent builder pattern for configuration, such as webAuth.scope("openid").connection("google-oauth2").start().
• Typed Result Aliases: Each subsystem uses specific typed result aliases, such as AuthenticationResult<T>, WebAuthResult<T>, CredentialsManagerResult<T>, and MyAccountResult<T>.
• Thread Safety: Components like CredentialsManager are Sendable and use NSLock internally to ensure thread safety during concurrent operations.

When a token exchange involves an actor token, Auth0 may include an act (actor) claim in the resulting ID token. This claim identifies the acting party and can represent a delegation chain. The act claim is exposed via the UserInfo type through the ActClaim class.

To read it, you may need to decode the ID token (e.g., using JWTDecode.swift) and map it to UserInfo:

• sub: The subject identifier of the acting party.
• act: A nested ActClaim for delegation chains.
• additionalClaims: Extra claims (e.g., org, role).

You can also access it directly from the CredentialsManager via credentialsManager.user?.act.

import JWTDecode

let jwt = try decode(jwt: credentials.idToken)
let userInfo = UserInfo(json: jwt.body)

if let act = userInfo?.act {
    print("Actor: \(act.sub)")
    print("Additional claims: \(act.additionalClaims)")

    // Check for delegation chain
    if let innerAct = act.act {
        print("Original actor: \(innerAct.sub)")
    }
}

In v3, all API variants (Callback, Combine, and Async/await) guarantee that results are delivered on the main thread.

Impact:

• You no longer need DispatchQueue.main.async or .receive(on: DispatchQueue.main) when consuming results for UI updates.
• If you need to perform CPU-intensive work with the results, you must explicitly dispatch to a background queue.

Affected APIs:

• All Authentication API methods
• All Credentials Manager methods
• All Web Auth methods
• All My Account API methods

// v3 - already on main thread
credentialsManager.credentials { result in
    self.updateUI(result)
}

// v3 - dispatch to background for CPU-intensive work
credentialsManager.credentials { result in
    DispatchQueue.global().async {
        let processed = self.performExpensiveOperation(result)
        DispatchQueue.main.async {
            self.updateUI(processed)
        }
    }
}