@stellar/typescript-wallet-sdk 5.0.0 → 5.1.0

package/lib/walletSdk/Exceptions/index.d.ts

@@ -100,6 +100,18 @@ export declare class NoAccountSignersError extends Error {
 export declare class DeviceKeyEqualsMasterKeyError extends Error {
     constructor();
 }
+export declare class DuplicateRecoverySignerError extends Error {
+    constructor(serverKeys: string[], signerKey: string);
+}
+export declare class RecoverySignerEqualsDeviceKeyError extends Error {
+    constructor(serverKey: string, signerKey: string);
+}
+export declare class DuplicateAccountSignerError extends Error {
+    constructor(address: string);
+}
+export declare class SignerKeyEqualsMasterKeyError extends Error {
+    constructor(address: string);
+}
 export declare class NoAccountAndNoSponsorError extends Error {
     constructor();
 }

package/lib/walletSdk/Recovery/index.d.ts

@@ -40,8 +40,21 @@ export declare class Recovery extends AccountRecover {
      * **Warning**: This transaction will lock master key of the account. Make sure you have access to
      * specified [RecoverableWalletConfig.deviceAddress]
      *
+     * The returned transaction is unsigned — sign it and submit it yourself. It sets signers and
+     * thresholds, so it needs signatures meeting the account's current **high** threshold rather
+     * than the master key specifically, and the sponsor must sign too when
+     * [RecoverableWalletConfig.sponsorAddress] is set. See [RecoverableWallet] for the cases.
+     *
+     * The signer set returned by the recovery servers is validated before the transaction is built,
+     * because undoing the master key lock afterwards takes a further `SetOptions` meeting the
+     * account's high threshold, which the collapsed signer set may no longer be able to reach.
+     *
      * This transaction can be sponsored.
      * @param {RecoverableWalletConfig} config - The configuration for recoverable wallet.
+     * @throws {DeviceKeyEqualsMasterKeyError} If the device address is the account address.
+     * @throws {DuplicateRecoverySignerError} If two or more recovery servers return the same signer key.
+     * @throws {RecoverySignerEqualsDeviceKeyError} If a recovery server returns the device key.
+     * @throws {SignerKeyEqualsMasterKeyError} If a recovery server returns the account's own key.
      * @returns {Promise<RecoverableWallet>} The wallet.
      */
     createRecoverableWallet(config: RecoverableWalletConfig): Promise<RecoverableWallet>;
@@ -63,6 +76,9 @@ export declare class Recovery extends AccountRecover {
      * @param {AccountThreshold} accountThreshold - Low, medium, and high thresholds to set on the account.
      * @param {AccountKeypair} [sponsorAddress] - Stellar address of the account sponsoring this transaction.
      * @param {(builder: CommonBuilder) => CommonBuilder} [builderExtra] - Stellar address of the account sponsoring this transaction.
+     * @throws {DuplicateAccountSignerError} If the same address appears more than once in [accountSigners].
+     * @throws {SignerKeyEqualsMasterKeyError} If [accountSigners] contains [account] itself.
+     * @throws {NoAccountAndNoSponsorError} If the account does not exist and no sponsor is given.
      * @returns {Promise<Transaction>}  The built transaction.
      */
     registerRecoveryServerSigners(account: AccountKeypair, accountSigners: AccountSigner[], accountThreshold: AccountThreshold, sponsorAddress?: AccountKeypair, builderExtra?: (builder: CommonBuilder) => CommonBuilder): Promise<Transaction>;
@@ -71,9 +87,27 @@ export declare class Recovery extends AccountRecover {
      * [SEP-30](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md).
      * @param {AccountKeypair} account - Account being registerd.
      * @param {RecoveryIdentityMap} identityMap - map of identities to recovery keys.
-     * @returns {Promise<string[]>}  List of recovery signer public keys.
+     * @returns {Promise<EnrolledRecoverySigner[]>} Each recovery signer public key paired with the
+     * server that returned it. The pairing is kept so that cross-server validation can name the
+     * server responsible when two of them return the same key.
      */
     private enrollWithRecoveryServer;
+    /**
+     * Assert that the recovery servers collectively returned a usable signer set.
+     *
+     * SEP-30 has each server generate its own unique signing key for the account,
+     * so the same key coming back from two servers is a protocol violation, not a
+     * judgement call. Left unchecked it halves the recovery signer set while the
+     * thresholds sized for the full set are written anyway, which is only
+     * discovered when the device is lost and recovery is attempted.
+     * @private
+     * @param {EnrolledRecoverySigner[]} enrolled - Signer keys paired with the servers that returned them.
+     * @param {string} deviceAddress - Address being added as the device signer.
+     * @throws {DuplicateRecoverySignerError} If two or more servers returned the same key.
+     * @throws {RecoverySignerEqualsDeviceKeyError} If a server returned the device key.
+     * @returns {void}
+     */
+    private validateEnrolledSigners;
     private getLatestRecoverySigner;
     private register;
 }

package/lib/walletSdk/Types/recovery.d.ts

@@ -22,6 +22,33 @@ export type RecoverableWalletConfig = {
     sponsorAddress?: AccountKeypair;
     builderExtra?: (builder: CommonBuilder) => CommonBuilder;
 };
+/**
+ * The result of registering an account with SEP-30 recovery servers.
+ * @property {Transaction} transaction - The **unsigned** registration transaction. The SDK builds
+ * it but neither signs nor submits it.
+ *
+ * It sets signers and thresholds, which Stellar authorizes against the account's **high**
+ * threshold — not against the master key specifically:
+ *
+ * - For an account that already exists, whichever of its current signers together reach `high`
+ *   can authorize it. The master key is neither automatically sufficient (it may carry less
+ *   weight than `high`) nor necessarily required (an account whose master key is already locked
+ *   is enrolled by its other signers alone).
+ * - For an account created within this same transaction, i.e. the sponsored path where the
+ *   account does not exist yet, the new account's own key suffices: a new account starts with
+ *   master weight 1 and zeroed thresholds.
+ * - When `sponsorAddress` is supplied the sponsor must sign as well, being the source of the
+ *   `beginSponsoringFutureReserves` operation and of `createAccount`.
+ *
+ * For a newly funded account whose master key is still its only signer, that is just
+ * `transaction.sign(accountKp.keypair)` followed by `stellar.submitTransaction(transaction)`.
+ *
+ * Once submitted the master key is locked, so inspect the transaction before signing if you want
+ * to verify the signer set it installs.
+ * @property {string[]} signers - Public keys of the recovery server signers added to the account,
+ * one per configured server. These are the addresses to pass to `signWithRecoveryServers` when
+ * recovering the account later.
+ */
 export type RecoverableWallet = {
     transaction: Transaction;
     signers: string[];
@@ -41,6 +68,30 @@ export type AccountThreshold = {
     medium: number;
     high: number;
 };
+/**
+ * Weights assigned to the device signer and to each recovery server signer.
+ *
+ * These values only mean something relative to {@link AccountThreshold}. Together they decide
+ * three separate properties, and it is possible to satisfy some and silently lose the others:
+ *
+ * 1. The device can operate the account on its own — `device >= high`.
+ * 2. The recovery servers can recover the account without the device —
+ *    `recoveryServer * serverCount >= high`.
+ * 3. No single recovery server can act alone — `recoveryServer < low`. This is a choice, not a
+ *    protocol guarantee: SEP-30 supports both postures. Two or more servers weighted this way
+ *    means no individual server controls the account, but the spec equally supports a
+ *    single-server custodial setup where one deliberately does.
+ *
+ * With two servers, `{ device: 10, recoveryServer: 5 }` against thresholds `{ low: 10, medium: 10,
+ * high: 10 }` satisfies all three: the device alone reaches `high`, the two servers together reach
+ * `high`, and one server alone reaches nothing.
+ *
+ * Note that whether the device can act alone is decided by `device` against `high`, per property 1
+ * above — not by how `device` compares to `recoveryServer`. A device weighing less than a single
+ * recovery server still operates the account independently as long as it meets `high`.
+ * @property {number} device - Weight of the device signer, which replaces the master key.
+ * @property {number} recoveryServer - Weight given to each recovery server signer.
+ */
 export type SignerWeight = {
     device: number;
     recoveryServer: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar/typescript-wallet-sdk",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "engines": {
     "node": ">=22.12.0"
   },

package/src/walletSdk/Exceptions/index.ts

@@ -274,6 +274,57 @@ export class DeviceKeyEqualsMasterKeyError extends Error {
   }
 }
 
+export class DuplicateRecoverySignerError extends Error {
+  constructor(serverKeys: string[], signerKey: string) {
+    super(
+      `Recovery servers [${serverKeys.join(
+        ", ",
+      )}] all returned the signer key ${signerKey}. SEP-30 requires each ` +
+        `server to generate a unique signing key, so this is either one ` +
+        `endpoint configured under several keys in the recovery server map, ` +
+        `or a server returning a key it does not control. Registering this ` +
+        `set would install one signer where several were intended, so the ` +
+        `recovery servers would together carry less weight than the ` +
+        `thresholds written alongside them were sized for, and may no longer ` +
+        `reach the account's high threshold once the device is lost`,
+    );
+    Object.setPrototypeOf(this, DuplicateRecoverySignerError.prototype);
+  }
+}
+
+export class RecoverySignerEqualsDeviceKeyError extends Error {
+  constructor(serverKey: string, signerKey: string) {
+    super(
+      `Recovery server '${serverKey}' returned the device key ${signerKey} ` +
+        `as its signer. The recovery signer must differ from the device key, ` +
+        `otherwise the device and the server collapse into a single signer`,
+    );
+    Object.setPrototypeOf(this, RecoverySignerEqualsDeviceKeyError.prototype);
+  }
+}
+
+export class DuplicateAccountSignerError extends Error {
+  constructor(address: string) {
+    super(
+      `Account signer ${address} is listed more than once. Stellar stores ` +
+        `signers keyed by public key and SetOptions overwrites rather than ` +
+        `accumulates, so repeated entries would install one signer carrying ` +
+        `one weight, not several`,
+    );
+    Object.setPrototypeOf(this, DuplicateAccountSignerError.prototype);
+  }
+}
+
+export class SignerKeyEqualsMasterKeyError extends Error {
+  constructor(address: string) {
+    super(
+      `Account signer ${address} is the account's own master key, which ` +
+        `cannot be added as a signer of itself`,
+    );
+    Object.setPrototypeOf(this, SignerKeyEqualsMasterKeyError.prototype);
+  }
+}
+
 export class NoAccountAndNoSponsorError extends Error {
   constructor() {
     super(`Account does not exist and is not sponsored`);

package/src/walletSdk/Recovery/index.ts

@@ -21,10 +21,14 @@ import { AccountRecover } from "./AccountRecover";
 import { Sep10 } from "../Auth";
 import {
   DeviceKeyEqualsMasterKeyError,
+  DuplicateAccountSignerError,
+  DuplicateRecoverySignerError,
   NoAccountAndNoSponsorError,
   NoAccountSignersError,
   RecoveryIdentityNotFoundError,
+  RecoverySignerEqualsDeviceKeyError,
   ServerRequestFailedError,
+  SignerKeyEqualsMasterKeyError,
 } from "../Exceptions";
 import {
   AccountKeypair,
@@ -44,6 +48,50 @@ type RecoveryParams = {
   servers: RecoveryServerMap;
 };
 
+/** A signer key paired with the recovery server that returned it. */
+type EnrolledRecoverySigner = {
+  serverKey: RecoveryServerKey;
+  signerKey: string;
+};
+
+/**
+ * Assert that a signer set can be installed as written.
+ *
+ * Stellar stores account signers as a set keyed by public key, and `SetOptions`
+ * is an upsert rather than an append — it overwrites a repeated key instead of
+ * summing the weights. A set containing the same address twice therefore
+ * installs one signer, while the thresholds chosen for the intended set are
+ * written alongside it regardless. Because the same transaction also zeroes the
+ * master key, repairing that mismatch takes a further `SetOptions`, itself
+ * authorized at the account's high threshold — so it is possible only while the
+ * remaining signers can still reach `high`, and impossible once they cannot.
+ * @param {string} accountAddress - Address of the account whose master key is being locked.
+ * @param {AccountSigner[]} accountSigners - The signer set about to be installed.
+ * @throws {DuplicateAccountSignerError} If any address appears more than once.
+ * @throws {SignerKeyEqualsMasterKeyError} If any address is the account itself.
+ * @returns {void}
+ */
+const validateAccountSigners = (
+  accountAddress: string,
+  accountSigners: AccountSigner[],
+): void => {
+  const seen: { [address: string]: true } = {};
+
+  accountSigners.forEach(({ address }) => {
+    const { publicKey } = address;
+
+    if (publicKey === accountAddress) {
+      throw new SignerKeyEqualsMasterKeyError(publicKey);
+    }
+
+    if (seen[publicKey]) {
+      throw new DuplicateAccountSignerError(publicKey);
+    }
+
+    seen[publicKey] = true;
+  });
+};
+
 /**
  * Used for Account Recovery using Sep-30.
  * @see {@link https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md}
@@ -89,8 +137,21 @@ export class Recovery extends AccountRecover {
    * **Warning**: This transaction will lock master key of the account. Make sure you have access to
    * specified [RecoverableWalletConfig.deviceAddress]
    *
+   * The returned transaction is unsigned — sign it and submit it yourself. It sets signers and
+   * thresholds, so it needs signatures meeting the account's current **high** threshold rather
+   * than the master key specifically, and the sponsor must sign too when
+   * [RecoverableWalletConfig.sponsorAddress] is set. See [RecoverableWallet] for the cases.
+   *
+   * The signer set returned by the recovery servers is validated before the transaction is built,
+   * because undoing the master key lock afterwards takes a further `SetOptions` meeting the
+   * account's high threshold, which the collapsed signer set may no longer be able to reach.
+   *
    * This transaction can be sponsored.
    * @param {RecoverableWalletConfig} config - The configuration for recoverable wallet.
+   * @throws {DeviceKeyEqualsMasterKeyError} If the device address is the account address.
+   * @throws {DuplicateRecoverySignerError} If two or more recovery servers return the same signer key.
+   * @throws {RecoverySignerEqualsDeviceKeyError} If a recovery server returns the device key.
+   * @throws {SignerKeyEqualsMasterKeyError} If a recovery server returns the account's own key.
    * @returns {Promise<RecoverableWallet>} The wallet.
    */
   async createRecoverableWallet(
@@ -100,11 +161,15 @@ export class Recovery extends AccountRecover {
       throw new DeviceKeyEqualsMasterKeyError();
     }
 
-    const recoverySigners = await this.enrollWithRecoveryServer(
+    const enrolled = await this.enrollWithRecoveryServer(
       config.accountAddress,
       config.accountIdentity,
     );
 
+    this.validateEnrolledSigners(enrolled, config.deviceAddress.publicKey);
+
+    const recoverySigners = enrolled.map(({ signerKey }) => signerKey);
+
     const accountSigners: AccountSigner[] = recoverySigners.map((rs) => ({
       address: PublicKeypair.fromPublicKey(rs),
       weight: config.signerWeight.recoveryServer,
@@ -185,6 +250,9 @@ export class Recovery extends AccountRecover {
    * @param {AccountThreshold} accountThreshold - Low, medium, and high thresholds to set on the account.
    * @param {AccountKeypair} [sponsorAddress] - Stellar address of the account sponsoring this transaction.
    * @param {(builder: CommonBuilder) => CommonBuilder} [builderExtra] - Stellar address of the account sponsoring this transaction.
+   * @throws {DuplicateAccountSignerError} If the same address appears more than once in [accountSigners].
+   * @throws {SignerKeyEqualsMasterKeyError} If [accountSigners] contains [account] itself.
+   * @throws {NoAccountAndNoSponsorError} If the account does not exist and no sponsor is given.
    * @returns {Promise<Transaction>}  The built transaction.
    */
   async registerRecoveryServerSigners(
@@ -194,6 +262,8 @@ export class Recovery extends AccountRecover {
     sponsorAddress?: AccountKeypair,
     builderExtra?: (builder: CommonBuilder) => CommonBuilder,
   ): Promise<Transaction> {
+    validateAccountSigners(account.publicKey, accountSigners);
+
     let accountInfo = undefined;
 
     try {
@@ -253,12 +323,14 @@ export class Recovery extends AccountRecover {
    * [SEP-30](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md).
    * @param {AccountKeypair} account - Account being registerd.
    * @param {RecoveryIdentityMap} identityMap - map of identities to recovery keys.
-   * @returns {Promise<string[]>}  List of recovery signer public keys.
+   * @returns {Promise<EnrolledRecoverySigner[]>} Each recovery signer public key paired with the
+   * server that returned it. The pairing is kept so that cross-server validation can name the
+   * server responsible when two of them return the same key.
    */
   private async enrollWithRecoveryServer(
     account: AccountKeypair,
     identityMap: RecoveryIdentityMap,
-  ): Promise<string[]> {
+  ): Promise<EnrolledRecoverySigner[]> {
     return Promise.all(
       Object.keys(this.servers).map(async (key) => {
         const server = this.servers[key];
@@ -299,11 +371,55 @@ export class Recovery extends AccountRecover {
           throw new ServerRequestFailedError(e);
         }
 
-        return this.getLatestRecoverySigner(recoveryAccount.signers);
+        return {
+          serverKey: key,
+          signerKey: this.getLatestRecoverySigner(recoveryAccount.signers),
+        };
       }),
     );
   }
 
+  /**
+   * Assert that the recovery servers collectively returned a usable signer set.
+   *
+   * SEP-30 has each server generate its own unique signing key for the account,
+   * so the same key coming back from two servers is a protocol violation, not a
+   * judgement call. Left unchecked it halves the recovery signer set while the
+   * thresholds sized for the full set are written anyway, which is only
+   * discovered when the device is lost and recovery is attempted.
+   * @private
+   * @param {EnrolledRecoverySigner[]} enrolled - Signer keys paired with the servers that returned them.
+   * @param {string} deviceAddress - Address being added as the device signer.
+   * @throws {DuplicateRecoverySignerError} If two or more servers returned the same key.
+   * @throws {RecoverySignerEqualsDeviceKeyError} If a server returned the device key.
+   * @returns {void}
+   */
+  private validateEnrolledSigners(
+    enrolled: EnrolledRecoverySigner[],
+    deviceAddress: string,
+  ): void {
+    const serverKeysBySigner: { [signerKey: string]: RecoveryServerKey[] } = {};
+
+    enrolled.forEach(({ serverKey, signerKey }) => {
+      serverKeysBySigner[signerKey] = [
+        ...(serverKeysBySigner[signerKey] || []),
+        serverKey,
+      ];
+    });
+
+    Object.keys(serverKeysBySigner).forEach((signerKey) => {
+      const serverKeys = serverKeysBySigner[signerKey];
+
+      if (serverKeys.length > 1) {
+        throw new DuplicateRecoverySignerError(serverKeys, signerKey);
+      }
+
+      if (signerKey === deviceAddress) {
+        throw new RecoverySignerEqualsDeviceKeyError(serverKeys[0], signerKey);
+      }
+    });
+  }
+
   private getLatestRecoverySigner(signers: RecoveryAccountSigner[]): string {
     if (signers.length === 0) {
       throw new NoAccountSignersError();

package/src/walletSdk/Types/recovery.ts

@@ -25,6 +25,33 @@ export type RecoverableWalletConfig = {
   builderExtra?: (builder: CommonBuilder) => CommonBuilder;
 };
 
+/**
+ * The result of registering an account with SEP-30 recovery servers.
+ * @property {Transaction} transaction - The **unsigned** registration transaction. The SDK builds
+ * it but neither signs nor submits it.
+ *
+ * It sets signers and thresholds, which Stellar authorizes against the account's **high**
+ * threshold — not against the master key specifically:
+ *
+ * - For an account that already exists, whichever of its current signers together reach `high`
+ *   can authorize it. The master key is neither automatically sufficient (it may carry less
+ *   weight than `high`) nor necessarily required (an account whose master key is already locked
+ *   is enrolled by its other signers alone).
+ * - For an account created within this same transaction, i.e. the sponsored path where the
+ *   account does not exist yet, the new account's own key suffices: a new account starts with
+ *   master weight 1 and zeroed thresholds.
+ * - When `sponsorAddress` is supplied the sponsor must sign as well, being the source of the
+ *   `beginSponsoringFutureReserves` operation and of `createAccount`.
+ *
+ * For a newly funded account whose master key is still its only signer, that is just
+ * `transaction.sign(accountKp.keypair)` followed by `stellar.submitTransaction(transaction)`.
+ *
+ * Once submitted the master key is locked, so inspect the transaction before signing if you want
+ * to verify the signer set it installs.
+ * @property {string[]} signers - Public keys of the recovery server signers added to the account,
+ * one per configured server. These are the addresses to pass to `signWithRecoveryServers` when
+ * recovering the account later.
+ */
 export type RecoverableWallet = {
   transaction: Transaction;
   signers: string[];
@@ -47,6 +74,30 @@ export type AccountThreshold = {
   high: number;
 };
 
+/**
+ * Weights assigned to the device signer and to each recovery server signer.
+ *
+ * These values only mean something relative to {@link AccountThreshold}. Together they decide
+ * three separate properties, and it is possible to satisfy some and silently lose the others:
+ *
+ * 1. The device can operate the account on its own — `device >= high`.
+ * 2. The recovery servers can recover the account without the device —
+ *    `recoveryServer * serverCount >= high`.
+ * 3. No single recovery server can act alone — `recoveryServer < low`. This is a choice, not a
+ *    protocol guarantee: SEP-30 supports both postures. Two or more servers weighted this way
+ *    means no individual server controls the account, but the spec equally supports a
+ *    single-server custodial setup where one deliberately does.
+ *
+ * With two servers, `{ device: 10, recoveryServer: 5 }` against thresholds `{ low: 10, medium: 10,
+ * high: 10 }` satisfies all three: the device alone reaches `high`, the two servers together reach
+ * `high`, and one server alone reaches nothing.
+ *
+ * Note that whether the device can act alone is decided by `device` against `high`, per property 1
+ * above — not by how `device` compares to `recoveryServer`. A device weighing less than a single
+ * recovery server still operates the account independently as long as it meets `high`.
+ * @property {number} device - Weight of the device signer, which replaces the master key.
+ * @property {number} recoveryServer - Weight given to each recovery server signer.
+ */
 export type SignerWeight = {
   device: number;
   recoveryServer: number;

package/test/customer.test.ts

@@ -14,7 +14,7 @@ describe("Customer", () => {
     await axios.get(
       "https://friendbot.stellar.org/?addr=" + accountKp.publicKey,
     );
-  }, 10000);
+  }, 30000);
 
   // skipped: the testanchor changed its SEP-12 API behavior
   test.skip("Sep-12 methods work", async () => {
@@ -89,5 +89,5 @@ describe("Customer", () => {
 
     // Delete
     await sep12.delete();
-  }, 20000);
+  }, 30000);
 });