Package org.stellar.sdk

Class Sep45Challenge

java.lang.Object
org.stellar.sdk.Sep45Challenge
public class Sep45Challenge extends Object
Stellar Web Authentication Utilities for Contract Accounts (SEP-0045).

This class provides utilities for building, reading, and verifying SEP-45 challenge authorization entries for contract account authentication on the Stellar network.

See Also:

  • Field Details

    • WEB_AUTH_VERIFY_FUNCTION_NAME

      public static final String WEB_AUTH_VERIFY_FUNCTION_NAME
      The expected function name for SEP-45 web authentication.
      See Also:

    • NULL_ACCOUNT

      public static final String NULL_ACCOUNT
      A null account used for simulation purposes. This is the account "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF".
      See Also:

    • DEFAULT_EXPIRE_IN_LEDGERS

      public static final long DEFAULT_EXPIRE_IN_LEDGERS
      Default number of ledgers until authorization expires (~15 minutes at 5 seconds/ledger).
      See Also:

  • Method Details

    • buildChallengeAuthorizationEntries

      public static SorobanAuthorizationEntries buildChallengeAuthorizationEntries(@NonNull @NonNull SorobanServer server, @NonNull @NonNull KeyPair serverSigner, @NonNull @NonNull String clientContractId, @NonNull @NonNull String homeDomain, @NonNull @NonNull String webAuthDomain, @NonNull @NonNull String webAuthContractId, @NonNull @NonNull Network network, @Nullable String nonce, @Nullable Long expireInLedgers)
      Builds a SEP-45 challenge authorization entries for a client contract account.

      This method creates challenge authorization entries that can be used to authenticate a contract account.

      Parameters:
      server - The Stellar RPC server to use for simulating the transaction.
      serverSigner - The server's signing keypair.
      clientContractId - The client's contract account ID (C... address).
      homeDomain - The home domain of the service requiring authentication.
      webAuthDomain - The domain of the web authentication service.
      webAuthContractId - The contract ID for the web authentication contract.
      network - The Stellar network.
      nonce - Optional nonce value. If null, a random 48-byte value will be generated and base64-encoded.
      expireInLedgers - Number of ledgers from current ledger until authorization expires. If null, defaults to DEFAULT_EXPIRE_IN_LEDGERS (~15 minutes).
      Returns:
      A SorobanAuthorizationEntries containing the authentication entries.
      Throws:
      InvalidSep45ChallengeException - If building the challenge fails.

    • buildChallengeAuthorizationEntries

      public static SorobanAuthorizationEntries buildChallengeAuthorizationEntries(@NonNull @NonNull SorobanServer server, @NonNull @NonNull KeyPair serverSigner, @NonNull @NonNull String clientContractId, @NonNull @NonNull String homeDomain, @NonNull @NonNull String webAuthDomain, @NonNull @NonNull String webAuthContractId, @NonNull @NonNull Network network, @Nullable String nonce, @Nullable Long expireInLedgers, @Nullable String clientDomain, @Nullable String clientDomainAccountId)
      Builds a SEP-45 challenge authorization entries for a client contract account with optional client domain verification.

      This method creates challenge authorization entries that can be used to authenticate a contract account, optionally including client domain verification.

      Parameters:
      server - The Stellar RPC server to use for simulating the transaction.
      serverSigner - The server's signing keypair.
      clientContractId - The client's contract account ID (C... address).
      homeDomain - The home domain of the service requiring authentication.
      webAuthDomain - The domain of the web authentication service.
      webAuthContractId - The contract ID for the web authentication contract.
      network - The Stellar network.
      nonce - Optional nonce value. If null, a random 48-byte value will be generated and base64-encoded.
      expireInLedgers - Number of ledgers from current ledger until authorization expires. If null, defaults to DEFAULT_EXPIRE_IN_LEDGERS (~15 minutes).
      clientDomain - Optional client domain for client domain verification.
      clientDomainAccountId - Optional client domain account ID (G... address) for verification.
      Returns:
      A SorobanAuthorizationEntries containing the authentication entries.
      Throws:
      InvalidSep45ChallengeException - If building the challenge fails.

    • readChallengeAuthorizationEntries

      public static Sep45Challenge.ChallengeAuthorizationEntries readChallengeAuthorizationEntries(@NonNull @NonNull String authorizationEntriesXdr, @NonNull @NonNull String serverAccountId, @NonNull @NonNull String webAuthContractId, @NonNull @NonNull String[] homeDomains, @NonNull @NonNull String webAuthDomain)
      Reads and validates a SEP-45 challenge authorization entries without verifying signatures.

      This method decodes the authorization entries, validates their structure, and extracts the challenge data. It does not verify the signatures; use verifyChallengeAuthorizationEntries(org.stellar.sdk.SorobanServer, java.lang.String, java.lang.String, java.lang.String, java.lang.String[], java.lang.String, org.stellar.sdk.Network) for full verification.

      Parameters:
      authorizationEntriesXdr - The base64 XDR-encoded authorization entries.
      serverAccountId - The expected server account ID (G... address).
      webAuthContractId - The expected web authentication contract ID (C... address).
      homeDomains - A list of acceptable home domains.
      webAuthDomain - The expected web auth domain.
      Returns:
      A Sep45Challenge.ChallengeAuthorizationEntries object containing the parsed challenge data.
      Throws:
      InvalidSep45ChallengeException - If the challenge is invalid.

    • readChallengeAuthorizationEntries

      public static Sep45Challenge.ChallengeAuthorizationEntries readChallengeAuthorizationEntries(@NonNull @NonNull String authorizationEntriesXdr, @NonNull @NonNull String serverAccountId, @NonNull @NonNull String webAuthContractId, @NonNull @NonNull String homeDomain, @NonNull @NonNull String webAuthDomain)
      Reads and validates a SEP-45 challenge authorization entries without verifying signatures.
      Parameters:
      authorizationEntriesXdr - The base64 XDR-encoded authorization entries.
      serverAccountId - The expected server account ID (G... address).
      webAuthContractId - The expected web authentication contract ID (C... address).
      homeDomain - The expected home domain.
      webAuthDomain - The expected web auth domain.
      Returns:
      A Sep45Challenge.ChallengeAuthorizationEntries object containing the parsed challenge data.
      Throws:
      InvalidSep45ChallengeException - If the challenge is invalid.

    • verifyChallengeAuthorizationEntries

      public static Sep45Challenge.ChallengeAuthorizationEntries verifyChallengeAuthorizationEntries(@NonNull @NonNull SorobanServer server, @NonNull @NonNull String authorizationEntriesXdr, @NonNull @NonNull String serverAccountId, @NonNull @NonNull String webAuthContractId, @NonNull @NonNull String[] homeDomains, @NonNull @NonNull String webAuthDomain, @NonNull @NonNull Network network)
      Verifies a SEP-45 challenge authorization entries by simulating the transaction.

      Since contract accounts cannot be queried for signers like traditional Stellar accounts, we verify signatures by simulating the transaction. A successful simulation indicates valid signatures.

      Parameters:
      server - The Stellar RPC server to use for simulating the transaction.
      authorizationEntriesXdr - The base64 XDR-encoded authorization entries.
      serverAccountId - The expected server account ID (G... address).
      webAuthContractId - The expected web authentication contract ID (C... address).
      homeDomains - A list of acceptable home domains.
      webAuthDomain - The expected web auth domain.
      network - The Stellar network.
      Returns:
      A Sep45Challenge.ChallengeAuthorizationEntries object containing the verified challenge data.
      Throws:
      InvalidSep45ChallengeException - If the challenge is invalid or verification fails.

    • verifyChallengeAuthorizationEntries

      public static Sep45Challenge.ChallengeAuthorizationEntries verifyChallengeAuthorizationEntries(@NonNull @NonNull SorobanServer server, @NonNull @NonNull String authorizationEntriesXdr, @NonNull @NonNull String serverAccountId, @NonNull @NonNull String webAuthContractId, @NonNull @NonNull String homeDomain, @NonNull @NonNull String webAuthDomain, @NonNull @NonNull Network network)
      Verifies a SEP-45 challenge authorization entries by simulating the transaction.
      Parameters:
      server - The Stellar RPC server to use for simulating the transaction.
      authorizationEntriesXdr - The base64 XDR-encoded authorization entries.
      serverAccountId - The expected server account ID (G... address).
      webAuthContractId - The expected web authentication contract ID (C... address).
      homeDomain - The expected home domain.
      webAuthDomain - The expected web auth domain.
      network - The Stellar network.
      Returns:
      A Sep45Challenge.ChallengeAuthorizationEntries object containing the verified challenge data.
      Throws:
      InvalidSep45ChallengeException - If the challenge is invalid or verification fails.