Stellar Web Authentication

See:

SEP-10 Specification

View Source lib/webauth/utils.js, line 17

Classes

InvalidChallengeError

Methods

# inner buildChallengeTx(serverKeypair, clientAccountID, homeDomain, timeoutopt, networkPassphrase, webAuthDomain, memoopt, clientDomainopt, clientSigningKeyopt) → {string}

Returns a valid SEP-10 challenge transaction which you can use for Stellar Web Authentication.

Parameters:

Name	Type	Attributes	Default	Description
`serverKeypair`	`Keypair`			Keypair for server's signing account.
`clientAccountID`	`string`			The stellar account (G...) or muxed account (M...) that the wallet wishes to authenticate with the server.
`homeDomain`	`string`			The fully qualified domain name of the service requiring authentication
`timeout`	`number`	<optional>	300	Challenge duration (default to 5 minutes).
`networkPassphrase`	`string`			The network passphrase. If you pass this argument then timeout is required.
`webAuthDomain`	`string`			The fully qualified domain name of the service issuing the challenge.
`memo`	`string`	<optional>	null	The memo to attach to the challenge transaction. The memo must be of type `id`. If the `clientaccountID` is a muxed account, memos cannot be used.
`clientDomain`	`string`	<optional>	null	The fully qualified domain of the client requesting the challenge. Only necessary when the the 'client_domain' parameter is passed.
`clientSigningKey`	`string`	<optional>	null	The public key assigned to the SIGNING_KEY attribute specified on the stellar.toml hosted on the client domain. Only necessary when the 'client_domain' parameter is passed.

See:

SEP-10: Stellar Web Auth

View Source lib/webauth/utils.js, line 66

Throws:

Will throw if clientAccountID is a muxed account, and memo` is present.

Type: Error

Will throw if clientDomain is provided, but clientSigningKey is missing

Type: Error

Returns:

A base64 encoded string of the raw TransactionEnvelope xdr struct for the transaction.

Type: string

Example

import { Keypair, Networks, WebAuth } from 'stellar-sdk'

let serverKeyPair = Keypair.fromSecret("server-secret")
let challenge = WebAuth.buildChallengeTx(
   serverKeyPair,
   "client-stellar-account-id",
   "stellar.org",
   300,
   Networks.TESTNET);

# inner gatherTxSigners(transaction, signers) → {Array.<string>}

Checks if a transaction has been signed by one or more of the given signers, returning a list of non-repeated signers that were found to have signed the given transaction.

Parameters:

Name	Type	Description
`transaction`	`Transaction` \| `FeeBumpTransaction`	The signed transaction.
`signers`	`Array.<string>`	The signer's public keys.

View Source lib/webauth/utils.js, line 582

Returns:

A list of signers that were found to have signed the transaction.

Type: Array.<string>

Example

let keypair1 = Keypair.random();
let keypair2 = Keypair.random();
const account = new StellarSdk.Account(keypair1.publicKey(), "-1");

const transaction = new TransactionBuilder(account, { fee: 100 })
   .setTimeout(30)
   .build();

transaction.sign(keypair1, keypair2)
WebAuth.gatherTxSigners(transaction, [keypair1.publicKey(), keypair2.publicKey()])

# inner readChallengeTx(challengeTx, serverAccountID, networkPassphrase, homeDomains, webAuthDomain) → {module:WebAuth.ChallengeTxDetails}

Reads a SEP-10 challenge transaction and returns the decoded transaction and client account ID contained within.

It also verifies that the transaction has been signed by the server.

It does not verify that the transaction has been signed by the client or that any signatures other than the server's on the transaction are valid. Use one of the following functions to completely verify the transaction:

Parameters:

Name	Type	Description
`challengeTx`	`string`	SEP0010 challenge transaction in base64.
`serverAccountID`	`string`	The server's stellar account (public key).
`networkPassphrase`	`string`	The network passphrase, e.g.: 'Test SDF Network ; September 2015' (see Networks)
`homeDomains`	`string` \| `Array.<string>`	The home domain that is expected to be included in the first Manage Data operation's string key. If an array is provided, one of the domain names in the array must match.
`webAuthDomain`	`string`	The home domain that is expected to be included as the value of the Manage Data operation with the 'web_auth_domain' key. If no such operation is included, this parameter is not used.

See:

SEP-10: Stellar Web Auth

View Source lib/webauth/utils.js, line 148

Returns:

The actual transaction and the Stellar public key (master key) used to sign the Manage Data operation, the matched home domain, and the memo attached to the transaction, which will be null if not present.

Type: module:WebAuth.ChallengeTxDetails

# inner verifyChallengeTxSigners(challengeTx, serverAccountID, networkPassphrase, signers, homeDomainsopt, webAuthDomain) → {Array.<string>}

Verifies that for a SEP 10 challenge transaction all signatures on the transaction are accounted for. A transaction is verified if it is signed by the server account, and all other signatures match a signer that has been provided as an argument (as the accountIDs list). Additional signers can be provided that do not have a signature, but all signatures must be matched to a signer (accountIDs) for verification to succeed. If verification succeeds, a list of signers that were found is returned, not including the server account ID.

Signers that are not prefixed as an address/account ID strkey (G...) will be ignored.

Errors will be raised if:

The transaction is invalid according to module:WebAuth~readChallengeTx.
No client signatures are found on the transaction.
One or more signatures in the transaction are not identifiable as the server account or one of the signers provided in the arguments.

Parameters:

Name	Type	Attributes	Description
`challengeTx`	`string`		SEP0010 challenge transaction in base64.
`serverAccountID`	`string`		The server's stellar account (public key).
`networkPassphrase`	`string`		The network passphrase, e.g.: 'Test SDF Network ; September 2015' (see Networks).
`signers`	`Array.<string>`		The signers public keys. This list should contain the public keys for all signers that have signed the transaction.
`homeDomains`	`string` \| `Array.<string>`	<optional>	The home domain(s) that should be included in the first Manage Data operation's string key. Required in readChallengeTx().
`webAuthDomain`	`string`		The home domain that is expected to be included as the value of the Manage Data operation with the 'web_auth_domain' key, if present. Used in readChallengeTx().

See:

SEP-10: Stellar Web Auth

View Source lib/webauth/utils.js, line 440

Returns:

The list of signers public keys that have signed the transaction, excluding the server account ID.

Type: Array.<string>

Example

import { Networks, TransactionBuilder, WebAuth }  from 'stellar-sdk';

const serverKP = Keypair.random();
const clientKP1 = Keypair.random();
const clientKP2 = Keypair.random();

// Challenge, possibly built in the server side
const challenge = WebAuth.buildChallengeTx(
  serverKP,
  clientKP1.publicKey(),
  "SDF",
  300,
  Networks.TESTNET
);

// clock.tick(200);  // Simulates a 200 ms delay when communicating from server to client

// Transaction gathered from a challenge, possibly from the client side
const transaction = TransactionBuilder.fromXDR(challenge, Networks.TESTNET);
transaction.sign(clientKP1, clientKP2);
const signedChallenge = transaction
        .toEnvelope()
        .toXDR("base64")
        .toString();

// The result below should be equal to [clientKP1.publicKey(), clientKP2.publicKey()]
WebAuth.verifyChallengeTxSigners(
   signedChallenge,
   serverKP.publicKey(),
   Networks.TESTNET,
   threshold,
   [clientKP1.publicKey(), clientKP2.publicKey()]
);

# inner verifyChallengeTxThreshold(challengeTx, serverAccountID, networkPassphrase, threshold, signerSummary, homeDomains, webAuthDomain) → {Array.<string>}

Verifies that for a SEP-10 challenge transaction all signatures on the transaction are accounted for and that the signatures meet a threshold on an account. A transaction is verified if it is signed by the server account, and all other signatures match a signer that has been provided as an argument, and those signatures meet a threshold on the account.

Signers that are not prefixed as an address/account ID strkey (G...) will be ignored.

Errors will be raised if:

The transaction is invalid according to module:WebAuth~readChallengeTx.
No client signatures are found on the transaction.
One or more signatures in the transaction are not identifiable as the server account or one of the signers provided in the arguments.
The signatures are all valid but do not meet the threshold.

Parameters:

Name	Type	Description
`challengeTx`	`string`	SEP0010 challenge transaction in base64.
`serverAccountID`	`string`	The server's stellar account (public key).
`networkPassphrase`	`string`	The network passphrase, e.g.: 'Test SDF Network ; September 2015' (see Networks).
`threshold`	`number`	The required signatures threshold for verifying this transaction.
`signerSummary`	`Array.<ServerApi.AccountRecordSigners>`	a map of all authorized signers to their weights. It's used to validate if the transaction signatures have met the given threshold.
`homeDomains`	`string` \| `Array.<string>`	The home domain(s) that should be included in the first Manage Data operation's string key. Required in verifyChallengeTxSigners() => readChallengeTx().
`webAuthDomain`	`string`	The home domain that is expected to be included as the value of the Manage Data operation with the 'web_auth_domain' key, if present. Used in verifyChallengeTxSigners() => readChallengeTx().

See:

SEP-10: Stellar Web Auth

View Source lib/webauth/utils.js, line 355

Throws:

Will throw if the collective weight of the transaction's signers does not meet the necessary threshold to verify this transaction.

Type: module:WebAuth.InvalidChallengeError

Returns:

The list of signers public keys that have signed the transaction, excluding the server account ID, given that the threshold was met.

Type: Array.<string>

Example

import { Networks, TransactionBuilder, WebAuth } from 'stellar-sdk';

const serverKP = Keypair.random();
const clientKP1 = Keypair.random();
const clientKP2 = Keypair.random();

// Challenge, possibly built in the server side
const challenge = WebAuth.buildChallengeTx(
  serverKP,
  clientKP1.publicKey(),
  "SDF",
  300,
  Networks.TESTNET
);

// clock.tick(200);  // Simulates a 200 ms delay when communicating from server to client

// Transaction gathered from a challenge, possibly from the client side
const transaction = TransactionBuilder.fromXDR(challenge, Networks.TESTNET);
transaction.sign(clientKP1, clientKP2);
const signedChallenge = transaction
        .toEnvelope()
        .toXDR("base64")
        .toString();

// Defining the threshold and signerSummary
const threshold = 3;
const signerSummary = [
   {
     key: this.clientKP1.publicKey(),
     weight: 1,
   },
   {
     key: this.clientKP2.publicKey(),
     weight: 2,
   },
 ];

// The result below should be equal to [clientKP1.publicKey(), clientKP2.publicKey()]
WebAuth.verifyChallengeTxThreshold(
   signedChallenge,
   serverKP.publicKey(),
   Networks.TESTNET,
   threshold,
   signerSummary
);

# inner verifyTxSignedBy(transaction, accountID) → {boolean}

Verifies if a transaction was signed by the given account id.

Parameters:

Name	Type	Description
`transaction`	`Transaction` \| `FeeBumpTransaction`	The signed transaction.
`accountID`	`string`	The signer's public key.

View Source lib/webauth/utils.js, line 556

Returns:

Whether or not accountID was found to have signed the transaction.

Type: boolean

Example

let keypair = Keypair.random();
const account = new StellarSdk.Account(keypair.publicKey(), "-1");

const transaction = new TransactionBuilder(account, { fee: 100 })
   .setTimeout(30)
   .build();

transaction.sign(keypair)
WebAuth.verifyTxSignedBy(transaction, keypair.publicKey())

Type Definitions

Type: object

# ChallengeTxDetails

A parsed and validated challenge transaction, and some of its constituent details.

Properties:

Name	Type	Attributes	Description
`tx`	`Transaction`		The challenge transaction.
`clientAccountId`	`string`		The Stellar public key (master key) used to sign the Manage Data operation.
`matchedHomeDomain`	`string`		The matched home domain.
`memo`	`string`	<optional>	The memo attached to the transaction, which will be null if not present

View Source lib/minimal/webauth/utils.d.ts, line 50

Type: object

# ChallengeTxDetails

A parsed and validated challenge transaction, and some of its constituent details.

Properties:

Name	Type	Attributes	Description
`tx`	`Transaction`		The challenge transaction.
`clientAccountId`	`string`		The Stellar public key (master key) used to sign the Manage Data operation.
`matchedHomeDomain`	`string`		The matched home domain.
`memo`	`string`	<optional>	The memo attached to the transaction, which will be null if not present

View Source lib/no-axios/webauth/utils.d.ts, line 50

Type: object

# ChallengeTxDetails

A parsed and validated challenge transaction, and some of its constituent details.

Properties:

Name	Type	Attributes	Description
`tx`	`Transaction`		The challenge transaction.
`clientAccountId`	`string`		The Stellar public key (master key) used to sign the Manage Data operation.
`matchedHomeDomain`	`string`		The matched home domain.
`memo`	`string`	<optional>	The memo attached to the transaction, which will be null if not present

View Source lib/no-eventsource/webauth/utils.d.ts, line 50

Type: object

# ChallengeTxDetails

A parsed and validated challenge transaction, and some of its constituent details.

Properties:

Name	Type	Attributes	Description
`tx`	`Transaction`		The challenge transaction.
`clientAccountId`	`string`		The Stellar public key (master key) used to sign the Manage Data operation.
`matchedHomeDomain`	`string`		The matched home domain.
`memo`	`string`	<optional>	The memo attached to the transaction, which will be null if not present

View Source lib/webauth/utils.d.ts, line 50

@stellar/stellar-sdk

Classes

Methods

# inner buildChallengeTx(serverKeypair, clientAccountID, homeDomain, timeoutopt, networkPassphrase, webAuthDomain, memoopt, clientDomainopt, clientSigningKeyopt) → {string}

Parameters:

Example

# inner gatherTxSigners(transaction, signers) → {Array.<string>}

Parameters:

Example

# inner readChallengeTx(challengeTx, serverAccountID, networkPassphrase, homeDomains, webAuthDomain) → {module:WebAuth.ChallengeTxDetails}

Parameters:

# inner verifyChallengeTxSigners(challengeTx, serverAccountID, networkPassphrase, signers, homeDomainsopt, webAuthDomain) → {Array.<string>}

Parameters:

Example

# inner verifyChallengeTxThreshold(challengeTx, serverAccountID, networkPassphrase, threshold, signerSummary, homeDomains, webAuthDomain) → {Array.<string>}

Parameters:

Example

# inner verifyTxSignedBy(transaction, accountID) → {boolean}

Parameters:

Example

Type Definitions

# ChallengeTxDetails

Properties:

# ChallengeTxDetails

Properties:

# ChallengeTxDetails

Properties:

# ChallengeTxDetails

Properties: