WebAuthenticator

public final class WebAuthenticator : Sendable

Implements SEP-0010 - Stellar Web Authentication.

This class provides functionality for authenticating users through the Stellar Web Authentication protocol, which allows clients to prove they possess the signing key for a Stellar account. The authentication flow returns a JWT token that can be used for subsequent requests to SEP-compliant services (SEP-6, SEP-12, SEP-24, SEP-31).

SEP-0010 defines a standard protocol for proving account ownership without transmitting secret keys. The server generates a challenge transaction that the client signs with their account’s signing key, proving ownership without revealing the secret key itself.

Typical Workflow

1. Initialize from Domain: Create a WebAuthenticator instance using the anchor’s stellar.toml
2. Get JWT Token: Request and obtain a JWT token for authentication
3. Use Token: Include the JWT token in subsequent SEP service requests

Example Usage

// Step 1: Create WebAuthenticator from anchor domain
let result = await WebAuthenticator.from(
    domain: "https://testanchor.stellar.org",
    network: .testnet
)

switch result {
case .success(let webAuth):
    // Step 2: Get JWT token for user account
    let userKeyPair = try KeyPair(secretSeed: "S...")
    let jwtResult = await webAuth.jwtToken(
        forUserAccount: userKeyPair.accountId,
        signers: [userKeyPair],
        homeDomain: "testanchor.stellar.org"
    )

    switch jwtResult {
    case .success(let jwtToken):
        // Step 3: Use JWT token for SEP-24, SEP-6, SEP-12, etc.
        print("JWT Token: \(jwtToken)")
    case .failure(let error):
        print("JWT token error: \(error)")
    }
case .failure(let error):
    print("WebAuth initialization error: \(error)")
}

Advanced Features

Multi-Signature Accounts:

// Provide multiple signers for accounts requiring multiple signatures
let signers = [keyPair1, keyPair2, keyPair3]
let result = await webAuth.jwtToken(
    forUserAccount: accountId,
    signers: signers
)

Muxed Accounts:

// For muxed accounts starting with M, provide memo
let result = await webAuth.jwtToken(
    forUserAccount: "M...",
    memo: 12345,
    signers: [keyPair]
)

Client Domain Signing:

// For client domain verification (mutual authentication)
let clientDomainKeyPair = try KeyPair(accountId: "G...")
let result = await webAuth.jwtToken(
    forUserAccount: userAccountId,
    signers: [userKeyPair],
    clientDomain: "wallet.example.com",
    clientDomainAccountKeyPair: clientDomainKeyPair,
    clientDomainSigningFunction: { txXdr in
        // Sign on server and return signed transaction
        return try await signOnServer(txXdr)
    }
)

Authentication Flow Details

The SEP-0010 authentication process involves:

1. Client requests a challenge transaction from the server
2. Server returns a transaction with specific operations and time bounds
3. Client validates the challenge transaction
4. Client signs the transaction with their account key(s)
5. Client submits the signed transaction to the server
6. Server validates signatures and returns a JWT token

The JWT token typically expires after 24 hours and must be refreshed.

Error Handling

let result = await webAuth.jwtToken(forUserAccount: accountId, signers: signers)
switch result {
case .success(let token):
    // Use token
case .failure(let error):
    switch error {
    case .requestError(let horizonError):
        // Network or server error
    case .validationErrorError(let validationError):
        // Challenge validation failed
    case .signingError:
        // Transaction signing failed
    case .parsingError(let parseError):
        // Response parsing failed
    }
}

Security Considerations

• Never transmit secret keys to the server
• Validate the challenge transaction before signing
• Check time bounds to prevent replay attacks
• Store JWT tokens securely
• Refresh tokens before expiration

See also:

• SEP-0010 Specification
• [StellarToml] for discovering authentication endpoints