WebAuth class

Implements SEP-0010 Web Authentication protocol for Stellar applications.

This class implements SEP-0010 version 3.4.1, which defines a standard protocol for authenticating users of Stellar applications using their Stellar account. This is commonly used by anchors and services to verify that a user controls a specific Stellar account before allowing access to services.

The authentication flow follows a challenge-response pattern:

Client requests a challenge transaction from the auth server
Server generates and signs a transaction with specific requirements
Client validates the challenge transaction
Client signs the transaction with their account key(s)
Client submits the signed transaction back to the server
Server validates the signatures and returns a JWT token

The JWT token can then be used to authenticate API requests to SEP-6, SEP-12, SEP-24, SEP-31, and other Stellar services.

Security considerations:

Always validate the challenge transaction before signing
Verify the server's signing key matches the stellar.toml configuration
Use HTTPS for all communication with the auth endpoint
JWT tokens have expiration times; refresh as needed
Never expose account secret keys in client-side code

CORS requirements for browser-based clients:

The authentication endpoints must return proper CORS headers
The server must set Access-Control-Allow-Origin: * for all responses
Preflight OPTIONS requests must be supported for all endpoints
This allows browser-based wallets to authenticate without CORS errors

Example - Basic authentication flow:

// Create WebAuth from a domain's stellar.toml
final webAuth = await WebAuth.fromDomain('testanchor.stellar.org', Network.TESTNET);

// User's keypair (in production, never hardcode this!)
final userKeyPair = KeyPair.fromSecretSeed('S...');

// Authenticate and get JWT token
final jwtToken = await webAuth.jwtToken(
  userKeyPair.accountId,
  [userKeyPair],
);

// Use the JWT token for authenticated requests
print('Authentication successful. Token: $jwtToken');

Example - Multi-signature account:

// For accounts requiring multiple signatures
final webAuth = await WebAuth.fromDomain('example.com', Network.PUBLIC);

final signer1 = KeyPair.fromSecretSeed('S...');
final signer2 = KeyPair.fromSecretSeed('S...');

final jwtToken = await webAuth.jwtToken(
  'GACCOUNT...',
  [signer1, signer2], // Provide all required signers
);

Example - Muxed account with memo:

// For muxed accounts or accounts using memos
final webAuth = await WebAuth.fromDomain('example.com', Network.PUBLIC);
final userKeyPair = KeyPair.fromSecretSeed('S...');

final jwtToken = await webAuth.jwtToken(
  userKeyPair.accountId,
  [userKeyPair],
  memo: BigInt.from(12345), // Required for some anchor configurations
);

Example - Client domain authentication:

// When your application wants to prove its domain ownership
final webAuth = await WebAuth.fromDomain('anchor.example.com', Network.PUBLIC);
final userKeyPair = KeyPair.fromSecretSeed('S...');
final clientDomainKeyPair = KeyPair.fromSecretSeed('S...'); // Your domain's signing key

final jwtToken = await webAuth.jwtToken(
  userKeyPair.accountId,
  [userKeyPair],
  clientDomain: 'wallet.mycompany.com',
  clientDomainAccountKeyPair: clientDomainKeyPair,
);

Constructors

WebAuth(String _authEndpoint, Network _network, String _serverSigningKey, String _serverHomeDomain, {Client? httpClient, Map<String, String>? httpRequestHeaders}): Creates a WebAuth instance with explicit configuration.

Properties

gracePeriod ↔ int: getter/setter pair
hashCode → int: The hash code for this object.
no setterinherited
httpClient ↔ Client: getter/setter pair
httpRequestHeaders ↔ Map<String, String>?: getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

getChallenge(String clientAccountId, [int? memo, String? homeDomain, String? clientDomain]) → Future<String>: Requests a challenge transaction from the WebAuth server.
getChallengeResponse(String accountId, [int? memo, String? homeDomain, String? clientDomain]) → Future<ChallengeResponse>: Requests a challenge response from the WebAuth server.
jwtToken(String clientAccountId, List<KeyPair> signers, {int? memo, String? homeDomain, String? clientDomain, KeyPair? clientDomainAccountKeyPair, Future<String> clientDomainSigningDelegate(String transactionXdr)?}) → Future<String>: Performs the complete SEP-0010 authentication flow and returns a JWT token.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
sendSignedChallengeTransaction(String base64EnvelopeXDR) → Future<String>: Submits a signed challenge transaction to obtain a JWT token.
signTransaction(String challengeTransaction, List<KeyPair> signers) → String: Signs a challenge transaction with the provided keypairs.
toString() → String: A string representation of this object.
inherited
validateChallenge(String challengeTransaction, String userAccountId, String? clientDomainAccountId, [int? timeBoundsGracePeriod, int? memo]) → void: Validates a challenge transaction according to SEP-0010 requirements.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

fromDomain(String domain, Network network, {Client? httpClient, Map<String, String>? httpRequestHeaders}) → Future<WebAuth>: Creates a WebAuth instance by automatically discovering configuration from stellar.toml.