@stellar/typescript-wallet-sdk 1.2.0 → 1.3.0

package/src/walletSdk/Recovery/index.ts

@@ -1,9 +1,39 @@
-// TODO - https://stellarorg.atlassian.net/browse/WAL-815?atlOrigin=eyJpIjoiYTE4MTdlZDIwMDU1NGU2YjlhZjQ3MDFlYmJhZWM1NTciLCJwIjoiaiJ9
 import { AxiosInstance } from "axios";
-import { Server } from "stellar-sdk";
+import { Transaction } from "stellar-sdk";
 
 import { Config } from "walletSdk";
-import { Stellar } from "../Horizon";
+import {
+  AccountSigner,
+  AccountThreshold,
+  CommonBuilder,
+  RecoverableAccountInfo,
+  RecoverableWallet,
+  RecoverableWalletConfig,
+  RecoveryAccount,
+  RecoveryAccountInfoMap,
+  RecoveryAccountSigner,
+  RecoveryAuthMap,
+  RecoveryIdentityMap,
+  RecoveryServerKey,
+  RecoveryServerMap,
+} from "walletSdk/Types";
+import { AccountRecover } from "./AccountRecover";
+import { Sep10 } from "../Auth";
+import {
+  DeviceKeyEqualsMasterKeyError,
+  NoAccountAndNoSponsorError,
+  NoAccountSignersError,
+  RecoveryIdentityNotFoundError,
+  ServerRequestFailedError,
+} from "../Exceptions";
+import {
+  AccountKeypair,
+  PublicKeypair,
+  TransactionBuilder,
+  SponsoringBuilder,
+  Stellar,
+} from "../Horizon";
+import { camelToSnakeCaseObject } from "../Utils";
 
 // Let's prevent exporting this constructor type as
 // we should not create this Recovery class directly.
@@ -11,22 +41,293 @@ type RecoveryParams = {
   cfg: Config;
   stellar: Stellar;
   httpClient: AxiosInstance;
-  servers: Server[];
+  servers: RecoveryServerMap;
 };
 
-// Do not create this object directly, use the Wallet class.
-export class Recovery {
+/**
+ * Used for Account Recovery using Sep-30.
+ * @see {@link https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md}
+ * Do not create this object directly, use the Wallet class.
+ * @class
+ */
+export class Recovery extends AccountRecover {
   private cfg: Config;
-  private stellar: Stellar;
-  private httpClient: AxiosInstance;
-  private servers: Server[];
 
+  /**
+   * Creates a new instance of the Recovery class.
+   * @constructor
+   * @param {RecoveryParams} params - The params used for the Recovery instance.
+   */
   constructor(params: RecoveryParams) {
     const { cfg, stellar, httpClient, servers } = params;
-
+    super(stellar, httpClient, servers);
     this.cfg = cfg;
-    this.stellar = stellar;
-    this.httpClient = httpClient;
-    this.servers = servers;
+  }
+
+  /**
+   * Create new auth object to authenticate account with the recovery server using SEP-10.
+   * @param {RecoveryServerKey} key - The key mapping to a recovery server.
+   * @returns {Sep10} - The Sep-10 auth object.
+   */
+  sep10Auth(key: RecoveryServerKey): Sep10 {
+    const server = this.getServer(key);
+    return new Sep10({
+      cfg: this.cfg,
+      webAuthEndpoint: server.authEndpoint,
+      homeDomain: server.homeDomain,
+      httpClient: this.httpClient,
+    });
+  }
+
+  /**
+   * Create new recoverable wallet using
+   * [SEP-30](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md). It
+   * registers the account with recovery servers, adds recovery servers and device account as new
+   * account signers, and sets threshold weights on the account.
+   *
+   * **Warning**: This transaction will lock master key of the account. Make sure you have access to
+   * specified [RecoverableWalletConfig.deviceAddress]
+   *
+   * This transaction can be sponsored.
+   * @param {RecoverableWalletConfig} config - The configuration for recoverable wallet.
+   * @returns {Promise<RecoverableWallet>} The wallet.
+   */
+  async createRecoverableWallet(
+    config: RecoverableWalletConfig,
+  ): Promise<RecoverableWallet> {
+    if (config.deviceAddress.publicKey == config.accountAddress.publicKey) {
+      throw new DeviceKeyEqualsMasterKeyError();
+    }
+
+    const recoverySigners = await this.enrollWithRecoveryServer(
+      config.accountAddress,
+      config.accountIdentity,
+    );
+
+    const accountSigners: AccountSigner[] = recoverySigners.map((rs) => ({
+      address: PublicKeypair.fromPublicKey(rs),
+      weight: config.signerWeight.recoveryServer,
+    }));
+
+    accountSigners.push({
+      address: config.deviceAddress,
+      weight: config.signerWeight.device,
+    });
+
+    const transaction = await this.registerRecoveryServerSigners(
+      config.accountAddress,
+      accountSigners,
+      config.accountThreshold,
+      config.sponsorAddress,
+      config.builderExtra,
+    );
+
+    return {
+      transaction,
+      signers: recoverySigners,
+    };
+  }
+
+  /**
+   * Retrieves account information from multiple recovery servers for a specified account address.
+   * @param {AccountKeypair} accountAddress - The account address for which to retrieve information.
+   * @param {RecoveryAuthMap} auth - A map of recovery server keys to their respective authentication tokens.
+   * @throws {ServerRequestFailedError} If any of the requests to recovery servers fail.
+   * @returns {Promise<RecoveryAccountInfoMap>} A map of recovery server keys to their respective account information.
+   */
+  async getAccountInfo(
+    accountAddress: AccountKeypair,
+    auth: RecoveryAuthMap,
+  ): Promise<RecoveryAccountInfoMap> {
+    return Object.keys(auth).reduce(
+      async (
+        infoMapPromise: Promise<RecoveryAccountInfoMap>,
+        serverKey: RecoveryServerKey,
+      ) => {
+        const infoMap = await infoMapPromise;
+
+        const authToken = auth[serverKey];
+
+        const requestUrl = `${this.getServer(serverKey).endpoint}/accounts/${
+          accountAddress.publicKey
+        }`;
+
+        try {
+          const resp = await this.httpClient.get(requestUrl, {
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${authToken.token}`,
+            },
+          });
+
+          const accountInfo: RecoverableAccountInfo = resp.data;
+
+          return {
+            ...infoMap,
+            [serverKey]: accountInfo,
+          };
+        } catch (e) {
+          throw new ServerRequestFailedError(e);
+        }
+      },
+      Promise.resolve({}),
+    );
+  }
+
+  /**
+   * Add recovery servers and device account as new account signers, and set new threshold weights
+   * on the account.
+   *
+   * This transaction can be sponsored.
+   * @param {AccountKeypair} account - Stellar address of the account that is receiving new signers.
+   * @param {AccountSigner[]} accountSigners - A list of account signers and their weights.
+   * @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.
+   * @returns {Promise<Transaction>}  The built transaction.
+   */
+  async registerRecoveryServerSigners(
+    account: AccountKeypair,
+    accountSigners: AccountSigner[],
+    accountThreshold: AccountThreshold,
+    sponsorAddress?: AccountKeypair,
+    builderExtra?: (builder: CommonBuilder) => CommonBuilder,
+  ): Promise<Transaction> {
+    let accountInfo = undefined;
+
+    try {
+      accountInfo = await this.stellar
+        .account()
+        .getInfo({ accountAddress: account.publicKey });
+    } catch (e) {
+      // In case it's an "Account not found" error let the code continue
+      if (e?.response?.status !== 404) {
+        throw e;
+      }
+    }
+
+    const sourceAddress = accountInfo ? account : sponsorAddress;
+
+    if (!sourceAddress) {
+      throw new NoAccountAndNoSponsorError();
+    }
+
+    const builder: TransactionBuilder = await this.stellar.transaction({
+      sourceAddress,
+    });
+
+    if (sponsorAddress) {
+      if (accountInfo) {
+        const buildingFunction = (_builder: SponsoringBuilder) =>
+          this.register(
+            _builder,
+            accountSigners,
+            accountThreshold,
+            builderExtra,
+          ) as SponsoringBuilder;
+
+        builder.sponsoring(sponsorAddress, buildingFunction);
+      } else {
+        const buildingFunction = (_builder: SponsoringBuilder) => {
+          _builder.createAccount(account);
+          return this.register(
+            _builder,
+            accountSigners,
+            accountThreshold,
+            builderExtra,
+          ) as SponsoringBuilder;
+        };
+
+        builder.sponsoring(sponsorAddress, buildingFunction, account);
+      }
+    } else {
+      this.register(builder, accountSigners, accountThreshold, builderExtra);
+    }
+
+    return builder.build();
+  }
+
+  /**
+   * Register account with recovery servers using
+   * [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.
+   */
+  private async enrollWithRecoveryServer(
+    account: AccountKeypair,
+    identityMap: RecoveryIdentityMap,
+  ): Promise<string[]> {
+    return Promise.all(
+      Object.keys(this.servers).map(async (key) => {
+        const server = this.servers[key];
+
+        const accountIdentities = identityMap[key];
+
+        if (!accountIdentities) {
+          throw new RecoveryIdentityNotFoundError(key);
+        }
+
+        const authToken = await this.sep10Auth(key).authenticate({
+          accountKp: account,
+          walletSigner: server.walletSigner,
+          clientDomain: server.clientDomain,
+        });
+
+        const requestUrl = `${server.endpoint}/accounts/${account.publicKey}`;
+
+        let recoveryAccount: RecoveryAccount;
+        try {
+          const resp = await this.httpClient.post(
+            requestUrl,
+            {
+              identities: accountIdentities.map((ai) =>
+                camelToSnakeCaseObject(ai),
+              ),
+            },
+            {
+              headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${authToken.token}`,
+              },
+            },
+          );
+
+          recoveryAccount = resp.data;
+        } catch (e) {
+          throw new ServerRequestFailedError(e);
+        }
+
+        return this.getLatestRecoverySigner(recoveryAccount.signers);
+      }),
+    );
+  }
+
+  private getLatestRecoverySigner(signers: RecoveryAccountSigner[]): string {
+    if (signers.length === 0) {
+      throw new NoAccountSignersError();
+    }
+
+    return signers[0].key;
+  }
+
+  private register(
+    builder: CommonBuilder,
+    accountSigners: AccountSigner[],
+    accountThreshold: AccountThreshold,
+    builderExtra?: (builder: CommonBuilder) => CommonBuilder,
+  ): CommonBuilder {
+    builder.lockAccountMasterKey();
+
+    accountSigners.forEach(({ address, weight }) =>
+      builder.addAccountSigner(address, weight),
+    );
+
+    const { low, medium, high } = accountThreshold;
+    builder.setThreshold({ low, medium, high });
+
+    builderExtra?.(builder);
+
+    return builder;
   }
 }

package/src/walletSdk/Types/anchor.ts

@@ -1,6 +1,8 @@
 import { MemoType } from "stellar-sdk";
 import { Optional } from "utility-types";
 
+import { AuthToken } from "./auth";
+
 export interface AnchorServiceInfo {
   deposit: AssetInfoMap;
   withdraw: AssetInfoMap;
@@ -37,6 +39,7 @@ export interface ProcessingAnchorTransaction extends BaseTransaction {
   amount_out_asset?: string;
   amount_out: string;
   amount_fee_asset?: string;
+  quote_id?: string;
   amount_fee: string;
   completed_at?: string;
   stellar_transaction_id?: string;
@@ -60,6 +63,24 @@ export interface WithdrawTransaction extends ProcessingAnchorTransaction {
   withdraw_anchor_account: string;
 }
 
+export type Sep6Transaction = DepositTransaction &
+  WithdrawTransaction & {
+    from?: string;
+    external_extra?: string;
+    external_extra_text?: string;
+    required_info_message?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    required_info_updates?: any;
+    required_customer_info_message?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    required_customer_info_updates?: any;
+    instructions?: {
+      value: string;
+      description: string;
+    };
+  };
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface ErrorTransaction
   extends Optional<DepositTransaction & WithdrawTransaction> {}
 
@@ -82,7 +103,7 @@ export interface Payment {
 }
 
 export type GetTransactionParams = {
-  authToken: string;
+  authToken: AuthToken;
   id?: string;
   stellarTransactionId?: string;
   externalTransactionId?: string;
@@ -90,7 +111,7 @@ export type GetTransactionParams = {
 };
 
 export type GetTransactionsParams = {
-  authToken: string;
+  authToken: AuthToken;
   assetCode: string;
   noOlderThan?: string;
   limit?: number;

package/src/walletSdk/Types/auth.ts

@@ -1,4 +1,6 @@
-import { Keypair, Transaction } from "stellar-sdk";
+import { Transaction } from "stellar-sdk";
+import { decode } from "jws";
+
 import { WalletSigner } from "../Auth/WalletSigner";
 import { AccountKeypair } from "../Horizon/Account";
 
@@ -9,7 +11,39 @@ export type AuthenticateParams = {
   clientDomain?: string;
 };
 
-export type AuthToken = string;
+export class AuthToken {
+  public token: string;
+  public issuer: string;
+  public issuedAt: string;
+  public expiresAt: string;
+  public clientDomain: string;
+  private principalAccount: string;
+
+  get account(): string {
+    return this.principalAccount.split(":")[0];
+  }
+
+  get memo(): string {
+    const split = this.principalAccount.split(":");
+    if (split.length !== 2) {
+      return null;
+    }
+    return split[1];
+  }
+
+  static from = (str: string): AuthToken => {
+    const authToken = new AuthToken();
+
+    const decoded = decode(str);
+    authToken.issuer = decoded.payload.iss;
+    authToken.principalAccount = decoded.payload.sub;
+    authToken.issuedAt = decoded.payload.iat;
+    authToken.expiresAt = decoded.payload.exp;
+    authToken.clientDomain = decoded.payload.client_domain;
+    authToken.token = str;
+    return authToken;
+  };
+}
 
 export type ChallengeParams = {
   accountKp: AccountKeypair;

package/src/walletSdk/Types/horizon.ts

@@ -1,6 +1,6 @@
-import { Memo, Server, xdr, Transaction } from "stellar-sdk";
+import { Memo, Horizon, Transaction } from "stellar-sdk";
 import { AccountKeypair } from "../Horizon/Account";
-import { TransactionBuilder } from "../Horizon/Transaction/TransactionBuilder";
+import { SponsoringBuilder, TransactionBuilder } from "walletSdk/Horizon";
 import { StellarAssetId } from "../Asset";
 
 export enum NETWORK_URLS {
@@ -12,7 +12,7 @@ export type TransactionParams = {
   sourceAddress: AccountKeypair;
   baseFee?: number;
   memo?: Memo;
-  timebounds?: Server.Timebounds | number;
+  timebounds?: Horizon.Server.Timebounds | number;
 };
 
 export type FeeBumpTransactionParams = {
@@ -25,8 +25,8 @@ export type SubmitWithFeeIncreaseParams = {
   sourceAddress: AccountKeypair;
   timeout: number;
   baseFeeIncrease: number;
-  buildingFunction: (TransactionBuilder) => TransactionBuilder;
-  signerFunction?: (Transaction) => Transaction;
+  buildingFunction: (builder: TransactionBuilder) => TransactionBuilder;
+  signerFunction?: (transaction: Transaction) => Transaction;
   baseFee?: number;
   memo?: Memo;
   maxFee?: number;
@@ -49,3 +49,5 @@ export type PathPayParams = {
   destMin?: string;
   sendMax?: string;
 };
+
+export type CommonBuilder = TransactionBuilder | SponsoringBuilder;

package/src/walletSdk/Types/index.ts

@@ -1,6 +1,7 @@
-import { AxiosRequestConfig } from "axios";
-import { Server, Networks } from "stellar-sdk";
+import { RawAxiosRequestHeaders } from "axios";
+import { Networks } from "stellar-sdk";
 import { ApplicationConfiguration, StellarConfiguration } from "walletSdk";
+import { RecoveryServerMap } from "./recovery";
 
 // Export types from root walletSdk/index.ts
 export type WalletParams = {
@@ -14,8 +15,8 @@ export type WalletAnchor = {
   language?: string;
 };
 
-export type WalletRecovery = {
-  servers: Server[];
+export type WalletRecoveryServers = {
+  servers: RecoveryServerMap;
 };
 
 export type ConfigParams = {
@@ -30,10 +31,22 @@ export type StellarConfigurationParams = {
   defaultTimeout?: number;
 };
 
+export type AxiosErrorData = {
+  status?: number;
+  statusText?: string;
+  // eslint-disable-next-line
+  responseData?: any;
+  headers?: RawAxiosRequestHeaders;
+};
+
 // Export all other types from walletSdk/Types.ts
 export * from "./anchor";
 export * from "./auth";
 export * from "./horizon";
+export * from "./recovery";
+export * from "./sep6";
+export * from "./sep12";
 export * from "./sep24";
+export * from "./sep38";
 export * from "./utils";
 export * from "./watcher";

package/src/walletSdk/Types/recovery.ts

@@ -0,0 +1,152 @@
+import { Transaction } from "stellar-sdk";
+
+import { WalletSigner } from "walletSdk/Auth";
+import { AccountKeypair, PublicKeypair } from "walletSdk/Horizon";
+import { AuthToken } from "./auth";
+import { CommonBuilder } from "./horizon";
+
+/**
+ * Configuration for recoverable wallet
+ * @param accountAddress Stellar address of the account that is registering
+ * @param deviceAddress Stellar address of the device that is added as a primary signer. It will
+ * replace the master key of [accountAddress]
+ * @param accountThreshold Low, medium, and high thresholds to set on the account
+ * @param accountIdentity A list of account identities to be registered with the recovery servers
+ * @param signerWeight Signer weight of the device and recovery keys to set
+ * @param sponsorAddress optional Stellar address of the account sponsoring this transaction
+ */
+export type RecoverableWalletConfig = {
+  accountAddress: AccountKeypair;
+  deviceAddress: AccountKeypair;
+  accountThreshold: AccountThreshold;
+  accountIdentity: RecoveryIdentityMap;
+  signerWeight: SignerWeight;
+  sponsorAddress?: AccountKeypair;
+  builderExtra?: (builder: CommonBuilder) => CommonBuilder;
+};
+
+export type RecoverableWallet = {
+  transaction: Transaction;
+  signers: string[];
+};
+
+export type AccountSigner = {
+  address: AccountKeypair;
+  weight: number;
+};
+
+/**
+ * Account weights threshold
+ * @param low Low threshold weight
+ * @param medium Medium threshold weight
+ * @param high High threshold weight
+ */
+export type AccountThreshold = {
+  low: number;
+  medium: number;
+  high: number;
+};
+
+export type SignerWeight = {
+  device: number;
+  recoveryServer: number;
+};
+
+/**
+ * Recovery server configuration
+ * @property {string} endpoint - Main endpoint (root domain) of SEP-30 recovery server. E.g. `https://testanchor.stellar.org`
+ * @property {string} authEndpoint - SEP-10 auth endpoint to be used. Should be in the format `<https://domain/auth>`. E.g. `https://testanchor.stellar.org/auth`
+ * @property {string} homeDomain - SEP-10 home domain. E.g. `testanchor.stellar.org`
+ * @property {WalletSigner} [walletSigner] - WalletSigner used to sign authentication
+ */
+export type RecoveryServer = {
+  endpoint: string;
+  authEndpoint: string;
+  homeDomain: string;
+  walletSigner?: WalletSigner;
+  clientDomain?: string;
+};
+
+export type RecoveryServerKey = string;
+
+export type RecoveryServerSigning = {
+  signerAddress: string;
+  authToken: AuthToken;
+};
+
+export type RecoveryServerSigningMap = {
+  [key: RecoveryServerKey]: RecoveryServerSigning;
+};
+
+export type RecoveryServerMap = {
+  [key: RecoveryServerKey]: RecoveryServer;
+};
+
+export type RecoveryAuthMap = {
+  [key: RecoveryServerKey]: AuthToken;
+};
+
+/**
+ * The role of the identity. This value is not used by the server and is stored and echoed back in
+ * responses as a way for a client to know conceptually who each identity represents
+ */
+export enum RecoveryRole {
+  OWNER = "owner",
+  SENDER = "sender",
+  RECEIVER = "receiver",
+}
+
+export enum RecoveryType {
+  STELLAR_ADDRESS = "stellar_address",
+  PHONE_NUMBER = "phone_number",
+  EMAIL = "email",
+}
+
+export type RecoveryAccountAuthMethod = {
+  type: RecoveryType;
+  value: string;
+};
+
+export type RecoveryAccountIdentity = {
+  role: RecoveryRole;
+  authMethods: RecoveryAccountAuthMethod[];
+};
+
+export type RecoveryIdentityMap = {
+  [key: RecoveryServerKey]: RecoveryAccountIdentity[];
+};
+
+export type RecoveryAccountRole = {
+  role: RecoveryRole;
+  authenticated?: boolean;
+};
+
+export type RecoveryAccountSigner = {
+  key: string;
+};
+
+export type RecoveryAccount = {
+  address: string;
+  identities: RecoveryAccountRole[];
+  signers: RecoveryAccountSigner[];
+};
+
+export type RecoverableIdentity = {
+  role: string;
+  authenticated?: boolean;
+};
+
+export type RecoverableSigner = {
+  key: PublicKeypair;
+  addedAt?: Date;
+};
+
+export type RecoverableAccountInfo = {
+  address: PublicKeypair;
+  identities: RecoverableIdentity[];
+  signers: RecoverableSigner[];
+};
+
+export type RecoveryAccountInfoMap = {
+  [key: RecoveryServerKey]: RecoverableAccountInfo;
+};