From 0ac4f7d2c428bbe67dd9960c2fd605b518a99200 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Tue, 4 Jun 2024 22:15:56 -0500 Subject: [PATCH] some fixes to links, params, etc. in WebAuth module --- src/webauth/errors.ts | 32 +++++++------ src/webauth/utils.ts | 102 +++++++++++++++++++++++------------------- 2 files changed, 74 insertions(+), 60 deletions(-) diff --git a/src/webauth/errors.ts b/src/webauth/errors.ts index 653c13eb3..415248ce8 100644 --- a/src/webauth/errors.ts +++ b/src/webauth/errors.ts @@ -1,16 +1,22 @@ -/** @memberof module:WebAuth */ +/** + * InvalidChallengeError is raised when a challenge transaction does not meet + * the requirements for a SEP-10 challenge transaction (for example, a non-zero + * sequence number). + * + * @memberof module:WebAuth + */ export class InvalidChallengeError extends Error { - public __proto__: InvalidChallengeError; + public __proto__: InvalidChallengeError; - /** - * Create an InvalidChallengeError - * @param {string} message error message - */ - constructor(message: string) { - const trueProto = new.target.prototype; - super(message); - this.__proto__ = trueProto; - this.constructor = InvalidChallengeError; - this.name = "InvalidChallengeError"; - } + /** + * Create an InvalidChallengeError. + * @param {string} message Human-readable error message + */ + constructor(message: string) { + const trueProto = new.target.prototype; + super(message); + this.__proto__ = trueProto; + this.constructor = InvalidChallengeError; + this.name = "InvalidChallengeError"; } +} diff --git a/src/webauth/utils.ts b/src/webauth/utils.ts index 922764611..15d9bd331 100644 --- a/src/webauth/utils.ts +++ b/src/webauth/utils.ts @@ -20,10 +20,8 @@ import { ServerApi } from "../horizon/server_api"; /** @module WebAuth */ /** - * Returns a valid [SEP-10](https://stellar.org/protocol/sep-10) challenge - * transaction which you can use for Stellar Web Authentication. - * - * @function + * Returns a valid {@link https://stellar.org/protocol/sep-10 | SEP-10} + * challenge transaction which you can use for Stellar Web Authentication. * * @param {Keypair} serverKeypair Keypair for server's signing account. * @param {string} clientAccountID The stellar account (G...) or muxed account @@ -44,13 +42,17 @@ import { ServerApi } from "../horizon/server_api"; * @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 {@link https://stellar.org/protocol/sep-10|SEP-10: Stellar Web Auth} + * @throws {Error} Will throw if `clientAccountID is a muxed account, and `memo` + * is present. + * @throws {Error} Will throw if `clientDomain` is provided, but + * `clientSigningKey` is missing + * + * @see {@link https://stellar.org/protocol/sep-10 | SEP-10: Stellar Web Auth} * * @example - * import { Keypair, Networks, WebAuth } from 'stellar-sdk' + * import { Keypair, Networks, WebAuth } from 'stellar-sdk' * * let serverKeyPair = Keypair.fromSecret("server-secret") * let challenge = WebAuth.buildChallengeTx( @@ -135,7 +137,15 @@ export function buildChallengeTx( } /** - * Reads a SEP 10 challenge transaction and returns the decoded transaction and + * @typedef {Object} ChallengeTxParts A parsed and validated challenge transaction, and some of its constituent details. + * @property {Transaction} tx The challenge transaction. + * @property {string} clientAccountID The Stellar public key (master key) used to sign the Manage Data operation. + * @property {string} matchedHomeDomain The matched home domain. + * @property {string | null} [memo=null] The memo attached to the transaction, which will be null if not present + */ + +/** + * 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. @@ -143,28 +153,26 @@ export function buildChallengeTx( * 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} * - * @function + * - {@link module:WebAuth~verifyChallengeTxThreshold} + * - {@link module:WebAuth~verifyChallengeTxSigners} * * @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' (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 | Array.} 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, + * @returns {module:WebAuth~ChallengeTxParts} 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 {@link https://stellar.org/protocol/sep-10|SEP-10: Stellar Web Auth} + * @see {@link https://stellar.org/protocol/sep-10 | SEP-10: Stellar Web Auth} */ export function readChallengeTx( challengeTx: string, @@ -362,37 +370,39 @@ export function readChallengeTx( * ignored. * * Errors will be raised if: - * - The transaction is invalid according to {@link readChallengeTx}. + * - The transaction is invalid according to + * {@link 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. * - * @function - * * @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' (see {@link Networks}). * @param {number} threshold The required signatures threshold for verifying * this transaction. - * @param {ServerApi.AccountRecordSigners[]} signerSummary a map of all + * @param {Array.} 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 + * @param {string | Array.} 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 {Array.} The list of signers public keys that have signed + * the transaction, excluding the server account ID, given that the threshold + * was met. + * @throws {module:WebAuth.InvalidChallengeError} Will throw if the collective + * weight of the transaction's signers does not meet the necessary threshold + * to verify this transaction. * - * @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 {@link https://stellar.org/protocol/sep-10 | SEP-10: Stellar Web Auth} * - * @see {@link https://stellar.org/protocol/sep-10|SEP-10: Stellar Web Auth} * @example - * import { Networks, TransactionBuilder, WebAuth } from 'stellar-sdk'; + * import { Networks, TransactionBuilder, WebAuth } from 'stellar-sdk'; * * const serverKP = Keypair.random(); * const clientKP1 = Keypair.random(); @@ -489,27 +499,26 @@ export function verifyChallengeTxThreshold( * ignored. * * Errors will be raised if: - * - The transaction is invalid according to {@link readChallengeTx}. + * - The transaction is invalid according to + * {@link 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. * - * @function - * * @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' (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 + * @param {Array.} signers The signers public keys. This list should + * contain the public keys for all signers that have signed the transaction. + * @param {string | Array.} [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. + * @returns {Array.} The list of signers public keys that have signed + * the transaction, excluding the server account ID. * * @see {@link https://stellar.org/protocol/sep-10|SEP-10: Stellar Web Auth} * @example @@ -682,10 +691,10 @@ export function verifyChallengeTxSigners( /** * Verifies if a transaction was signed by the given account id. * - * @function - * @param {Transaction} transaction - * @param {string} accountID - * @returns {boolean}. + * @param {Transaction | FeeBumpTransaction} transaction The signed transaction. + * @param {string} accountID The signer's public key. + * @returns {boolean} Whether or not `accountID` was found to have signed the + * transaction. * * @example * let keypair = Keypair.random(); @@ -710,11 +719,10 @@ export function verifyTxSignedBy( * returning a list of non-repeated signers that were found to have signed the * given transaction. * - * @function - * @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. + * @param {Transaction | FeeBumpTransaction} transaction The signed transaction. + * @param {Array.} signers The signer's public keys. + * @returns {Array.} A list of signers that were found to have signed + * the transaction. * * @example * let keypair1 = Keypair.random();