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.

    • 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, boolean useUpgradedAuth)
      Builds a SEP-45 challenge authorization entries for a client contract account, choosing the credential format of the challenge.

      Same as buildChallengeAuthorizationEntries(SorobanServer, KeyPair, String, String, String, String, Network, String, Long, String, String), but lets the server choose which authorization credentials the challenge carries.

      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.
      useUpgradedAuth - Whether the challenge carries address-bound ADDRESS_V2 (CAP-71) credentials instead of the legacy ADDRESS credentials, true in the shorter overloads. Unlike the other simulating APIs, the entries are signed by a remote client rather than by the caller, and SEP-45 does not specify a credential format: pass false to keep issuing legacy challenges to clients whose SDK cannot sign the address-bound payload. This flag is transitional: once the network returns ADDRESS_V2 credentials by default (protocol 28), it becomes a no-op.
      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.