OathClient

public final class OathClient : @unchecked Sendable

Main public interface for OATH functionality. This client handles TOTP and HOTP credential management and code generation.

The OathClient provides a high-level interface for managing OATH credentials, including adding credentials from URIs, generating OTP codes, and managing credential storage with policy enforcement.

Example usage:

let client = try await OathClient.createClient { config in
    config.storage = OathKeychainStorage()
    config.enableCredentialCache = false
    config.logger = LogManager.logger
}

let credential = try await client.addCredentialFromUri("otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP")
let code = try await client.generateCode(credential.id)

Factory Methods

  • Factory method to create and initialize an OathClient instance.

    Throws

    OathError.initializationFailed if client initialization fails.

    Example usage:

    let client = try await OathClient.createClient { config in
    config.encryptionEnabled = false
    config.logger = LogManager.logger
    config.storage = OathKeychainStorage()
}

    Declaration

    Swift

    public static func createClient(
    configure: (OathConfiguration) -> Void = { _ in }
) async throws -> OathClient

    Parameters

    configure

    A closure to configure the OathConfiguration.

    Return Value

    A fully initialized OathClient instance.

Credential Management

  • Creates an OATH credential from a standard otpauth:// URI.

    Throws

    OathError.invalidUri if the URI is malformed.

    Throws

    OathError.policyViolation if credential policies are not met.

    Throws

    OathStorageError if storage operations fail.

    Supported URI formats:

    • otpauth://totp/Issuer:Account?secret=SECRET&issuer=Issuer&algorithm=SHA1&digits=6&period=30
    • otpauth://hotp/Issuer:Account?secret=SECRET&issuer=Issuer&algorithm=SHA1&digits=6&counter=0
    • mfauth://totp/Issuer:Account?secret=SECRET&issuer=Issuer&algorithm=SHA1&digits=6&period=30

    Declaration

    Swift

    public func addCredentialFromUri(_ uri: String) async throws -> OathCredential

    Parameters

    uri

    The otpauth:// or mfauth:// URI string.

    Return Value

    The created and stored OathCredential.

  • saveCredential(_:) Asynchronous

    Saves or updates an OATH credential in storage.

    Throws

    OathError.policyViolation if credential policies are not met.

    Throws

    OathStorageError if storage operations fail.

    Declaration

    Swift

    public func saveCredential(_ credential: OathCredential) async throws -> OathCredential

    Parameters

    credential

    The credential to save or update.

    Return Value

    The saved credential with any policy updates applied.

  • getCredentials() Asynchronous

    Retrieves all stored OATH credentials.

    Throws

    OathStorageError if storage operations fail.

    Declaration

    Swift

    public func getCredentials() async throws -> [OathCredential]

    Return Value

    An array of all stored OathCredential objects.

  • getCredential(_:) Asynchronous

    Retrieves a specific OATH credential by its ID.

    Throws

    OathStorageError if storage operations fail.

    Declaration

    Swift

    public func getCredential(_ credentialId: String) async throws -> OathCredential?

    Parameters

    credentialId

    The unique identifier of the credential.

    Return Value

    The OathCredential if found, nil otherwise.

  • deleteCredential(_:) Asynchronous

    Deletes an OATH credential by its ID.

    Throws

    OathStorageError if storage operations fail.

    Declaration

    Swift

    public func deleteCredential(_ credentialId: String) async throws -> Bool

    Parameters

    credentialId

    The unique identifier of the credential to delete.

    Return Value

    true if the credential was deleted, false if it wasn’t found.

Code Generation

  • generateCode(_:) Asynchronous

    Generates a one-time password (OTP) for a given credential.

    Throws

    OathError.credentialNotFound if the credential doesn’t exist.

    Throws

    OathError.credentialLocked if the credential is locked.

    Throws

    OathError.codeGenerationFailed if code generation fails.

    For HOTP credentials, this method will automatically increment the counter. For TOTP credentials, the code is valid for the current time period.

    Declaration

    Swift

    public func generateCode(_ credentialId: String) async throws -> String

    Parameters

    credentialId

    The unique identifier of the credential.

    Return Value

    The generated OTP code as a string.

  • Generates an OTP with additional information about its validity.

    Throws

    OathError.credentialNotFound if the credential doesn’t exist.

    Throws

    OathError.credentialLocked if the credential is locked.

    Throws

    OathError.codeGenerationFailed if code generation fails.

    This method provides additional information such as:

    • For TOTP: time remaining before expiration and progress through the time window
    • For HOTP: the counter value used for generation

    Declaration

    Swift

    public func generateCodeWithValidity(_ credentialId: String) async throws -> OathCodeInfo

    Parameters

    credentialId

    The unique identifier of the credential.

    Return Value

    OathCodeInfo containing the code and validity information.

Lifecycle Management

  • close() Asynchronous

    Clean up resources used by the OATH client. This method should be called when the client is no longer needed to ensure proper cleanup of resources and cached data.

    Throws

    OathError.cleanupFailed if cleanup operations fail.

    Declaration

    Swift

    public func close() async throws