Fix formatting and cross-references in WebAuth jsdocs

src/webauth/utils.ts

@@ -18,27 +18,46 @@ import { InvalidChallengeError } from "./errors";
 import { ServerApi } from "../horizon/server_api";
 
 /**
- * Returns a valid [SEP0010](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md)
- * challenge transaction which you can use for Stellar Web Authentication.
+ * Returns a valid [SEP-10](https://stellar.org/protocol/sep-10) challenge
+ * transaction which you can use for Stellar Web Authentication.
  *
- * @see [SEP0010: Stellar Web Authentication](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md).
  * @function
- * @memberof Utils
+ * @memberof WebAuth
+ *
  * @param {Keypair} serverKeypair Keypair for server's signing account.
- * @param {string} clientAccountID The stellar account (G...) or muxed account (M...) that the wallet wishes to authenticate with the server.
- * @param {string} homeDomain The fully qualified domain name of the service requiring authentication
+ * @param {string} clientAccountID The stellar account (G...) or muxed account
+ *    (M...) that the wallet wishes to authenticate with the server.
+ * @param {string} homeDomain The fully qualified domain name of the service
+ *    requiring authentication
  * @param {number} [timeout=300] Challenge duration (default to 5 minutes).
- * @param {string} networkPassphrase The network passphrase. If you pass this argument then timeout is required.
- * @param {string} webAuthDomain The fully qualified domain name of the service issuing the challenge.
- * @param {string} [memo] 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.
- * @param {string} [clientDomain] The fully qualified domain of the client requesting the challenge. Only necessary when the the 'client_domain' parameter is passed.
- * @param {string} [clientSigningKey] 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.
+ * @param {string} networkPassphrase The network passphrase. If you pass this
+ *    argument then timeout is required.
+ * @param {string} webAuthDomain The fully qualified domain name of the service
+ *    issuing the challenge.
+ * @param {string} [memo] 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.
+ * @param {string} [clientDomain] The fully qualified domain of the client
+ *    requesting the challenge. Only necessary when the the 'client_domain'
+ *    parameter is passed.
+ * @param {string} [clientSigningKey] 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.
+ *
+ * @returns {string} A base64 encoded string of the raw TransactionEnvelope xdr
+ *    struct for the transaction.
+ * @see [SEP-10: Stellar Web Auth](https://stellar.org/protocol/sep-10).
+ *
  * @example
- * import { Utils, Keypair, Networks }  from 'stellar-sdk'
+ * import { Keypair, Networks, WebAuth }  from 'stellar-sdk'
  *
  * let serverKeyPair = Keypair.fromSecret("server-secret")
- * let challenge = Sep10.buildChallengeTx(serverKeyPair, "client-stellar-account-id", "stellar.org", 300, Networks.TESTNET)
- * @returns {string} A base64 encoded string of the raw TransactionEnvelope xdr struct for the transaction.
+ * let challenge = WebAuth.buildChallengeTx(
+ *    serverKeyPair,
+ *    "client-stellar-account-id",
+ *    "stellar.org",
+ *    300,
+ *    Networks.TESTNET);
  */
 export function buildChallengeTx(
   serverKeypair: Keypair,
@@ -115,26 +134,37 @@ export function buildChallengeTx(
 }
 
 /**
- * readChallengeTx reads a SEP 10 challenge transaction and returns the decoded
- * transaction and client account ID contained within.
+ * 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:
- * - verifyChallengeTxThreshold
- * - verifyChallengeTxSigners
+ * 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:
+ * - {@link verifyChallengeTxThreshold}
+ * - {@link verifyChallengeTxSigners}
  *
- * @see [SEP0010: Stellar Web Authentication](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md).
  * @function
- * @memberof Utils
+ * @memberof WebAuth
+ *
  * @param {string} challengeTx SEP0010 challenge transaction in base64.
  * @param {string} serverAccountID The server's stellar account (public key).
- * @param {string} networkPassphrase The network passphrase, e.g.: 'Test SDF Network ; September 2015'.
- * @param {string|string[]} [homeDomains] 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.
- * @param {string} webAuthDomain 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.
- * @returns {Transaction|string|string|string} 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.
+ * @param {string} networkPassphrase The network passphrase, e.g.: 'Test SDF
+ *    Network ; September 2015' (see {@link Networks})
+ * @param {string|string[]} [homeDomains] 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.
+ * @param {string} webAuthDomain 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.
+ *
+ * @returns {Transaction|string|string|string} 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.
+ *
+ * @see [SEP-10: Stellar Web Auth](https://stellar.org/protocol/sep-10).
  */
 export function readChallengeTx(
   challengeTx: string,
@@ -322,44 +352,55 @@ export function readChallengeTx(
 }
 
 /**
- * verifyChallengeTxThreshold 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.
+ * 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 ReadChallengeTx.
+ *  - The transaction is invalid according to {@link 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.
  *
- * @see [SEP0010: Stellar Web Authentication](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md).
  * @function
- * @memberof Utils
+ * @memberof WebAuth
+ *
  * @param {string} challengeTx SEP0010 challenge transaction in base64.
  * @param {string} serverAccountID The server's stellar account (public key).
- * @param {string} networkPassphrase The network passphrase, e.g.: 'Test SDF Network ; September 2015'.
- * @param {number} threshold The required signatures threshold for verifying this transaction.
- * @param {ServerApi.AccountRecordSigners[]} signerSummary a map of all authorized signers to their weights. It's used to validate if the transaction signatures have met the given threshold.
- * @param {string|string[]} [homeDomains] The home domain(s) that should be included in the first Manage Data operation's string key. Required in verifyChallengeTxSigners() => readChallengeTx().
- * @param {string} webAuthDomain 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().
- * @returns {string[]} The list of signers public keys that have signed the transaction, excluding the server account ID, given that the threshold was met.
- * @example
+ * @param {string} networkPassphrase The network passphrase, e.g.: 'Test SDF
+ *    Network ; September 2015' (see {@link Networks}).
+ * @param {number} threshold The required signatures threshold for verifying
+ *    this transaction.
+ * @param {ServerApi.AccountRecordSigners[]} signerSummary a map of all
+ *    authorized signers to their weights. It's used to validate if the
+ *    transaction signatures have met the given threshold.
+ * @param {string|string[]} [homeDomains] The home domain(s) that should be
+ *    included in the first Manage Data operation's string key. Required in
+ *    verifyChallengeTxSigners() => readChallengeTx().
+ * @param {string} webAuthDomain 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().
  *
- * import { Networks, TransactionBuilder, Utils }  from 'stellar-sdk';
+ * @returns {string[]} The list of signers public keys that have signed the
+ *    transaction, excluding the server account ID, given that the threshold was
+ *    met.
+ *
+ * @see [SEP-10: Stellar Web Auth](https://stellar.org/protocol/sep-10).
+ * @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 = Sep10.buildChallengeTx(
+ * const challenge = WebAuth.buildChallengeTx(
  *   serverKP,
  *   clientKP1.publicKey(),
  *   "SDF",
@@ -391,7 +432,13 @@ export function readChallengeTx(
  *  ];
  *
  * // The result below should be equal to [clientKP1.publicKey(), clientKP2.publicKey()]
- * Sep10.verifyChallengeTxThreshold(signedChallenge, serverKP.publicKey(), Networks.TESTNET, threshold, signerSummary);
+ * WebAuth.verifyChallengeTxThreshold(
+ *    signedChallenge,
+ *    serverKP.publicKey(),
+ *    Networks.TESTNET,
+ *    threshold,
+ *    signerSummary
+ * );
  */
 export function verifyChallengeTxThreshold(
   challengeTx: string,
@@ -430,42 +477,52 @@ export function verifyChallengeTxThreshold(
 }
 
 /**
- * verifyChallengeTxSigners 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.
+ * 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.
+ * 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 ReadChallengeTx.
+ *  - The transaction is invalid according to {@link 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.
  *
- * @see [SEP0010: Stellar Web Authentication](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md).
  * @function
- * @memberof Utils
+ * @memberof WebAuth
+ *
  * @param {string} challengeTx SEP0010 challenge transaction in base64.
  * @param {string} serverAccountID The server's stellar account (public key).
- * @param {string} networkPassphrase The network passphrase, e.g.: 'Test SDF Network ; September 2015'.
- * @param {string[]} signers The signers public keys. This list should contain the public keys for all signers that have signed the transaction.
- * @param {string|string[]} [homeDomains] The home domain(s) that should be included in the first Manage Data operation's string key. Required in readChallengeTx().
- * @param {string} webAuthDomain 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().
- * @returns {string[]} The list of signers public keys that have signed the transaction, excluding the server account ID.
- * @example
+ * @param {string} networkPassphrase The network passphrase, e.g.: 'Test SDF
+ *    Network ; September 2015' (see {@link Networks}).
+ * @param {string[]} signers The signers public keys. This list should contain
+ *    the public keys for all signers that have signed the transaction.
+ * @param {string|string[]} [homeDomains] The home domain(s) that should be
+ *    included in the first Manage Data operation's string key. Required in
+ *    readChallengeTx().
+ * @param {string} webAuthDomain 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().
+ * @returns {string[]} The list of signers public keys that have signed the
+ *    transaction, excluding the server account ID.
  *
- * import { Networks, TransactionBuilder, Utils }  from 'stellar-sdk';
+ * @see [SEP-10: Stellar Web Auth](https://stellar.org/protocol/sep-10).
+ * @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 = Sep10.buildChallengeTx(
+ * const challenge = WebAuth.buildChallengeTx(
  *   serverKP,
  *   clientKP1.publicKey(),
  *   "SDF",
@@ -484,7 +541,13 @@ export function verifyChallengeTxThreshold(
  *         .toString();
  *
  * // The result below should be equal to [clientKP1.publicKey(), clientKP2.publicKey()]
- * Sep10.verifyChallengeTxSigners(signedChallenge, serverKP.publicKey(), Networks.TESTNET, threshold, [clientKP1.publicKey(), clientKP2.publicKey()]);
+ * WebAuth.verifyChallengeTxSigners(
+ *    signedChallenge,
+ *    serverKP.publicKey(),
+ *    Networks.TESTNET,
+ *    threshold,
+ *    [clientKP1.publicKey(), clientKP2.publicKey()]
+ * );
  */
 export function verifyChallengeTxSigners(
   challengeTx: string,
@@ -622,9 +685,11 @@ export function verifyChallengeTxSigners(
  * Verifies if a transaction was signed by the given account id.
  *
  * @function
- * @memberof Sep10
+ * @memberof WebAuth
  * @param {Transaction} transaction
  * @param {string} accountID
+ * @returns {boolean}.
+ *
  * @example
  * let keypair = Keypair.random();
  * const account = new StellarSdk.Account(keypair.publicKey(), "-1");
@@ -634,8 +699,7 @@ export function verifyChallengeTxSigners(
  *    .build();
  *
  * transaction.sign(keypair)
- * Sep10.verifyTxSignedBy(transaction, keypair.publicKey())
- * @returns {boolean}.
+ * WebAuth.verifyTxSignedBy(transaction, keypair.publicKey())
  */
 export function verifyTxSignedBy(
   transaction: FeeBumpTransaction | Transaction,
@@ -645,15 +709,17 @@ export function verifyTxSignedBy(
 }
 
 /**
- *
- * gatherTxSigners 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.
+ * 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.
  *
  * @function
- * @memberof Sep10
+ * @memberof WebAuth
  * @param {Transaction} transaction the signed transaction.
  * @param {string[]} signers The signers public keys.
+ * @returns {string[]} a list of signers that were found to have signed the
+ * transaction.
+ *
  * @example
  * let keypair1 = Keypair.random();
  * let keypair2 = Keypair.random();
@@ -664,8 +730,7 @@ export function verifyTxSignedBy(
  *    .build();
  *
  * transaction.sign(keypair1, keypair2)
- * Sep10.gatherTxSigners(transaction, [keypair1.publicKey(), keypair2.publicKey()])
- * @returns {string[]} a list of signers that were found to have signed the transaction.
+ * WebAuth.gatherTxSigners(transaction, [keypair1.publicKey(), keypair2.publicKey()])
  */
 export function gatherTxSigners(
   transaction: FeeBumpTransaction | Transaction,