@stellar/typescript-wallet-sdk 1.5.0 → 1.6.0-beta.1719865729038

package/src/walletSdk/Customer/index.ts

@@ -17,10 +17,10 @@ import {
  * @class
  */
 export class Sep12 {
-  private authToken;
-  private baseUrl;
-  private httpClient;
-  private headers;
+  private authToken: AuthToken;
+  private baseUrl: string;
+  private httpClient: AxiosInstance;
+  private headers: { [key: string]: string };
 
   /**
    * Creates a new instance of the Sep12 class.
@@ -64,7 +64,7 @@ export class Sep12 {
     if (!resp.data.id) {
       throw new CustomerNotFoundError(params);
     }
-    return resp;
+    return resp.data;
   }
 
   /**
@@ -104,7 +104,7 @@ export class Sep12 {
           : this.headers,
       },
     );
-    return resp;
+    return resp.data;
   }
 
   /**
@@ -154,7 +154,7 @@ export class Sep12 {
           : this.headers,
       },
     );
-    return resp;
+    return resp.data;
   }
 
   /**

package/src/walletSdk/Exceptions/index.ts

@@ -306,6 +306,20 @@ export class InvalidJsonError extends Error {
   }
 }
 
+export class SigningKeypairMissingSecretError extends Error {
+  constructor() {
+    super("This keypair doesn't have a secret key and can't sign");
+    Object.setPrototypeOf(this, SigningKeypairMissingSecretError.prototype);
+  }
+}
+
+export class DefaultSignerDomainAccountError extends Error {
+  constructor() {
+    super("The DefaultSigner can't sign transactions with domain account");
+    Object.setPrototypeOf(this, DefaultSignerDomainAccountError.prototype);
+  }
+}
+
 export class AuthHeaderSigningKeypairRequiredError extends Error {
   constructor() {
     super("Must be SigningKeypair to sign auth header");
@@ -319,8 +333,31 @@ export class AuthHeaderSigningKeypairRequiredError extends Error {
 export class AuthHeaderClientDomainRequiredError extends Error {
   constructor() {
     super(
-      "This class should only be used for remote signing. For local signing use DefaultAuthHeaderSigner.",
+      "This class should only be used for remote signing. For local signing use DefaultAuthHeaderSigner",
     );
     Object.setPrototypeOf(this, AuthHeaderClientDomainRequiredError.prototype);
   }
 }
+
+export class Sep7InvalidUriError extends Error {
+  constructor(reason: string) {
+    super(`Invalid Stellar Sep-7 URI, reason: ${reason}`);
+    Object.setPrototypeOf(this, Sep7InvalidUriError.prototype);
+  }
+}
+
+export class Sep7LongMsgError extends Error {
+  constructor(msgMaxLength: number) {
+    super(`'msg' should be no longer than ${msgMaxLength} characters`);
+    Object.setPrototypeOf(this, Sep7LongMsgError.prototype);
+  }
+}
+
+export class Sep7UriTypeNotSupportedError extends Error {
+  constructor(type: string) {
+    super(
+      `Stellar Sep-7 URI operation type '${type}' is not currently supported`,
+    );
+    Object.setPrototypeOf(this, Sep7UriTypeNotSupportedError.prototype);
+  }
+}

package/src/walletSdk/Horizon/Account.ts

@@ -1,4 +1,5 @@
 import { Keypair, Transaction, FeeBumpTransaction } from "@stellar/stellar-sdk";
+import { SigningKeypairMissingSecretError } from "../Exceptions";
 
 export class AccountKeypair {
   keypair: Keypair;
@@ -28,7 +29,7 @@ export class PublicKeypair extends AccountKeypair {
 export class SigningKeypair extends AccountKeypair {
   constructor(keypair: Keypair) {
     if (!keypair.canSign()) {
-      throw new Error("This keypair doesn't have a secret key and can't sign");
+      throw new SigningKeypairMissingSecretError();
     }
     super(keypair);
   }

package/src/walletSdk/Types/anchor.ts

@@ -192,4 +192,8 @@ export enum TransactionStatus {
 
   /** Catch-all for any error not enumerated above. */
   error = "error",
+  /** deposit/withdrawal is currently on hold for additional checks after receiving user's funds.
+   * Anchor may use this status to indicate to the user that transaction is being reviewed (for example,
+   * for compliance reasons). Once this status cleared, transaction should follow the regular flow */
+  on_hold = "on_hold",
 }

package/src/walletSdk/Types/index.ts

@@ -46,6 +46,7 @@ export * from "./auth";
 export * from "./horizon";
 export * from "./recovery";
 export * from "./sep6";
+export * from "./sep7";
 export * from "./sep12";
 export * from "./sep24";
 export * from "./sep38";

package/src/walletSdk/Types/sep7.ts

@@ -0,0 +1,19 @@
+export const WEB_STELLAR_SCHEME = "web+stellar:";
+
+export enum Sep7OperationType {
+  tx = "tx",
+  pay = "pay",
+}
+
+export const URI_MSG_MAX_LENGTH = 300;
+
+export type Sep7Replacement = {
+  id: string;
+  path: string;
+  hint: string;
+};
+
+export type IsValidSep7UriResult = {
+  result: boolean;
+  reason?: string;
+};

package/src/walletSdk/Uri/Sep7Base.ts

@@ -0,0 +1,311 @@
+import { Keypair, Networks, StellarToml } from "@stellar/stellar-sdk";
+import { Sep7OperationType, URI_MSG_MAX_LENGTH } from "../Types";
+import { Sep7LongMsgError } from "../Exceptions";
+
+/**
+ * A base abstract class containing common functions that should be used by both
+ * Sep7Tx and Sep7Pay classes for parsing or constructing SEP-0007 Stellar URIs.
+ *
+ * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0007.md#specification
+ */
+export abstract class Sep7Base {
+  protected uri: URL;
+
+  /**
+   * Creates a new instance of the Sep7 class.
+   *
+   * @constructor
+   * @param {URL | string} uri - uri to initialize the Sep7 instance.
+   */
+  constructor(uri: URL | string) {
+    this.uri = new URL(uri.toString());
+
+    if (this.msg?.length > URI_MSG_MAX_LENGTH) {
+      throw new Sep7LongMsgError(URI_MSG_MAX_LENGTH);
+    }
+  }
+
+  /**
+   * Should return a deep clone of this instance.
+   *
+   * @returns {Sep7Base} a deep clone of the Sep7Base extended instance.
+   */
+  abstract clone(): Sep7Base;
+
+  /**
+   * Returns a stringfied URL-decoded version of the 'uri' object.
+   *
+   * @returns {string} the uri decoded string value.
+   */
+  toString(): string {
+    return this.uri.toString();
+  }
+
+  /**
+   * Returns uri's pathname as the operation type.
+   *
+   * @returns {Sep7OperationType} the operation type, either "tx" or "pay".
+   */
+  get operationType(): Sep7OperationType {
+    return this.uri.pathname as Sep7OperationType;
+  }
+
+  /**
+   * Returns a URL-decoded version of the uri 'callback' param without
+   * the 'url:' prefix.
+   *
+   * The URI handler should send the signed XDR to this callback url, if this
+   * value is omitted then the URI handler should submit it to the network.
+   *
+   * @returns {string | undefined} URL-decoded 'callback' param if present.
+   */
+  get callback(): string | undefined {
+    const callback = this.getParam("callback");
+
+    if (callback?.startsWith("url:")) {
+      return callback.replace("url:", "");
+    }
+
+    return callback;
+  }
+
+  /**
+   * Sets and URL-encodes the uri 'callback' param, appends the 'url:'
+   * prefix to it if not yet present.
+   *
+   * Deletes the uri 'callback' param if set as 'undefined'.
+   *
+   * The URI handler should send the signed XDR to this callback url, if this
+   * value is omitted then the URI handler should submit it to the network.
+   *
+   * @param {string | undefined} callback the uri 'callback' param to be set.
+   */
+  set callback(callback: string | undefined) {
+    if (!callback) {
+      this.setParam("callback", undefined);
+      return;
+    }
+
+    if (callback.startsWith("url:")) {
+      this.setParam("callback", callback);
+      return;
+    }
+
+    this.setParam("callback", `url:${callback}`);
+  }
+
+  /**
+   * Returns a URL-decoded version of the uri 'msg' param.
+   *
+   * This message should indicate any additional information that the website
+   * or application wants to show the user in her wallet.
+   *
+   * @returns {string | undefined} URL-decoded 'msg' param if present.
+   */
+  get msg(): string | undefined {
+    return this.getParam("msg");
+  }
+
+  /**
+   * Sets and URL-encodes the uri 'msg' param, the 'msg' param can't
+   * be larger than 300 characters.
+   *
+   * Deletes the uri 'msg' param if set as 'undefined'.
+   *
+   * This message should indicate any additional information that the website
+   * or application wants to show the user in her wallet.
+   *
+   * @param {string | undefined} msg the uri 'msg' param to be set.
+   * @throws {Sep7LongMsgError} if 'msg' length is bigger than 300.
+   */
+  set msg(msg: string | undefined) {
+    if (msg?.length > URI_MSG_MAX_LENGTH) {
+      throw new Sep7LongMsgError(URI_MSG_MAX_LENGTH);
+    }
+
+    this.setParam("msg", msg);
+  }
+
+  /**
+   * Returns uri 'network_passphrase' param, if not present returns
+   * the PUBLIC Network value by default: 'Public Global Stellar Network ; September 2015'.
+   *
+   * @returns {Networks} the Stellar network passphrase considered for this uri.
+   */
+  get networkPassphrase(): Networks {
+    return (this.getParam("network_passphrase") ?? Networks.PUBLIC) as Networks;
+  }
+
+  /**
+   * Sets the uri 'network_passphrase' param.
+   *
+   * Deletes the uri 'network_passphrase' param if set as 'undefined'.
+   *
+   * Only need to set it if this transaction is for a network other than
+   * the public network.
+   *
+   * @param {Networks | undefined} networkPassphrase the uri 'network_passphrase'
+   * param to be set.
+   */
+  set networkPassphrase(networkPassphrase: Networks | undefined) {
+    this.setParam("network_passphrase", networkPassphrase);
+  }
+
+  /**
+   * Returns a URL-decoded version of the uri 'origin_domain' param.
+   *
+   * This should be a fully qualified domain name that specifies the originating
+   * domain of the URI request.
+   *
+   * @returns {string | undefined} URL-decoded 'origin_domain' param if present.
+   */
+  get originDomain(): string | undefined {
+    return this.getParam("origin_domain");
+  }
+
+  /**
+   * Sets and URL-encodes the uri 'origin_domain' param.
+   *
+   * Deletes the uri 'origin_domain' param if set as 'undefined'.
+   *
+   * This should be a fully qualified domain name that specifies the originating
+   * domain of the URI request.
+   *
+   * @param {string | undefined} originDomain the uri 'origin_domain' param
+   * to be set.
+   */
+  set originDomain(originDomain: string | undefined) {
+    this.setParam("origin_domain", originDomain);
+  }
+
+  /**
+   * Returns a URL-decoded version of the uri 'signature' param.
+   *
+   * This should be a signature of the hash of the URI request (excluding the
+   * 'signature' field and value itself).
+   *
+   * Wallets should use the URI_REQUEST_SIGNING_KEY specified in the
+   * origin_domain's stellar.toml file to validate this signature.
+   * If the verification fails, wallets must alert the user.
+   *
+   * @returns {string | undefined} URL-decoded 'signature' param if present.
+   */
+  get signature(): string | undefined {
+    return this.getParam("signature");
+  }
+
+  /**
+   * Signs the URI with the given keypair, which means it sets the 'signature' param.
+   *
+   * This should be the last step done before generating the URI string,
+   * otherwise the signature will be invalid for the URI.
+   *
+   * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0007.md#request-signing
+   *
+   * @param {Keypair} keypair The keypair (including secret key), used to sign the request.
+   * This should be the keypair found in the URI_REQUEST_SIGNING_KEY field of the
+   * origin_domains' stellar.toml.
+   *
+   * @returns {string} the generated 'signature' param.
+   */
+  addSignature(keypair: Keypair): string {
+    const payload = this.createSignaturePayload();
+    const signature = keypair.sign(payload).toString("base64");
+    this.setParam("signature", signature);
+    return signature;
+  }
+
+  /**
+   * Verifies that the signature added to the URI is valid.
+   *
+   * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0007.md#request-signing
+   *
+   * @returns {Promise<boolean>} returns 'true' if the signature is valid for
+   * the current URI and origin_domain. Returns 'false' if signature verification
+   * fails, or if there is a problem looking up the stellar.toml associated with
+   * the origin_domain.
+   */
+  async verifySignature(): Promise<boolean> {
+    const originDomain = this.originDomain;
+    const signature = this.signature;
+
+    // we can fail fast if neither of them are set since we can't verify without both
+    if (!originDomain || !signature) {
+      return false;
+    }
+
+    try {
+      const toml = await StellarToml.Resolver.resolve(originDomain);
+      const signingKey = toml.URI_REQUEST_SIGNING_KEY;
+
+      if (!signingKey) {
+        return false;
+      }
+      const keypair = Keypair.fromPublicKey(signingKey);
+      const payload = this.createSignaturePayload();
+      return keypair.verify(payload, Buffer.from(signature, "base64"));
+    } catch (e) {
+      // if something fails we assume signature verification failed
+      return false;
+    }
+  }
+
+  /**
+   * Finds the uri param related to the inputted 'key', if any, and returns
+   * a URL-decoded version of it. Returns 'undefined' if key param not found.
+   *
+   * @param {string} key the uri param key.
+   *
+   * @returns {string | undefined} URL-decoded value of the uri param if found.
+   */
+  protected getParam(key: string): string | undefined {
+    // the searchParams.get() function automatically applies URL dencoding.
+    return this.uri.searchParams.get(key) || undefined;
+  }
+
+  /**
+   * Sets and URL-encodes a 'key=value' uri param.
+   *
+   * Deletes the uri param if 'value' set as 'undefined'.
+   *
+   * @param {string} key the uri param key.
+   * @param {string | undefined} value the uri param value to be set.
+   */
+  protected setParam(key: string, value: string | undefined) {
+    if (!value) {
+      this.uri.searchParams.delete(key);
+      return;
+    }
+
+    // the searchParams.set() function automatically applies URL encoding.
+    this.uri.searchParams.set(key, value);
+  }
+
+  /**
+   * Converts the URI request into the payload that will be signed by
+   * the 'addSignature' method.
+   *
+   * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0007.md#request-signing
+   *
+   * @returns {Buffer} array of bytes to be signed with given keypair on
+   * the 'addSignature' method.
+   */
+  private createSignaturePayload(): Buffer {
+    let data = this.toString();
+
+    const signature = this.signature;
+    if (signature) {
+      // the payload must be created without the signature on it
+      data = data.replace(`&signature=${encodeURIComponent(signature)}`, "");
+    }
+
+    // The first 35 bytes of the payload are all 0, the 36th byte is 4.
+    // Then we concatenate the URI request with the prefix 'stellar.sep.7 - URI Scheme'
+    // (no delimiter) and convert that to bytes to give use the final payload to be signed.
+    return Buffer.concat([
+      Buffer.alloc(35, 0),
+      Buffer.alloc(1, 4),
+      Buffer.from(`stellar.sep.7 - URI Scheme${data}`),
+    ]);
+  }
+}

package/src/walletSdk/Uri/Sep7Pay.ts

@@ -0,0 +1,169 @@
+import { MemoType } from "@stellar/stellar-sdk";
+import { Sep7Base } from "../Uri";
+import { Sep7OperationType, WEB_STELLAR_SCHEME } from "../Types";
+
+/**
+ * The Sep-7 'pay' operation represents a request to pay a specific address
+ * with a specific asset, regardless of the source asset used by the payer.
+ *
+ * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0007.md#operation-pay
+ */
+export class Sep7Pay extends Sep7Base {
+  /**
+   * Creates a Sep7Pay instance with given destination.
+   *
+   * @param {string} destination a valid Stellar address to receive the payment.
+   *
+   * @returns {Sep7Pay} the Sep7Pay instance.
+   */
+  static forDestination(destination: string): Sep7Pay {
+    const uri = new Sep7Pay();
+    uri.destination = destination;
+    return uri;
+  }
+
+  /**
+   * Creates a new instance of the Sep7Pay class.
+   *
+   * @constructor
+   * @param {URL | string} [uri] - uri to initialize the Sep7 instance.
+   */
+  constructor(uri?: URL | string) {
+    super(uri ?? new URL(`${WEB_STELLAR_SCHEME}${Sep7OperationType.pay}`));
+  }
+
+  /**
+   * Returns a deep clone of this instance.
+   *
+   * @returns {Sep7Pay} a deep clone of this Sep7Pay instance.
+   */
+  clone(): Sep7Pay {
+    return new Sep7Pay(this.uri);
+  }
+
+  /**
+   * Gets the destination of the payment request, which should be a valid
+   * Stellar address.
+   *
+   * @returns {string | undefined} the 'destination' uri param if present.
+   */
+  get destination(): string | undefined {
+    return this.getParam("destination");
+  }
+
+  /**
+   * Sets the destination of the payment request, which should be a valid
+   * Stellar address.
+   *
+   * Deletes the uri 'destination' param if set as 'undefined'.
+   *
+   * @param {string | undefined} destination the uri 'destination' param to be set.
+   */
+  set destination(destination: string | undefined) {
+    this.setParam("destination", destination);
+  }
+
+  /**
+   * Gets the amount that destination should receive.
+   *
+   * @returns {string | undefined} the 'amount' uri param if present.
+   */
+  get amount(): string | undefined {
+    return this.getParam("amount");
+  }
+
+  /**
+   * Sets the amount that destination should receive.
+   *
+   * Deletes the uri 'amount' param if set as 'undefined'.
+   *
+   * @param {string | undefined} amount the uri 'amount' param to be set.
+   */
+  set amount(amount: string | undefined) {
+    this.setParam("amount", amount);
+  }
+
+  /**
+   * Gets the code from the asset that destination should receive.
+   *
+   * @returns {string | undefined} the 'asset_code' uri param if present.
+   */
+  get assetCode(): string | undefined {
+    return this.getParam("asset_code");
+  }
+
+  /**
+   * Sets the code from the asset that destination should receive.
+   *
+   * Deletes the uri 'asset_code' param if set as 'undefined'.
+   *
+   * @param {string | undefined} assetCode the uri 'asset_code' param to be set.
+   */
+  set assetCode(assetCode: string | undefined) {
+    this.setParam("asset_code", assetCode);
+  }
+
+  /**
+   * Gets the account ID of asset issuer the destination should receive.
+   *
+   * @returns {string | undefined} the 'asset_issuer' uri param if present.
+   */
+  get assetIssuer(): string | undefined {
+    return this.getParam("asset_issuer");
+  }
+
+  /**
+   * Sets the account ID of asset issuer the destination should receive.
+   *
+   * Deletes the uri 'asset_issuer' param if set as 'undefined'.
+   *
+   * @param {string | undefined} assetIssuer the uri 'asset_issuer' param to be set.
+   */
+  set assetIssuer(assetIssuer: string | undefined) {
+    this.setParam("asset_issuer", assetIssuer);
+  }
+
+  /**
+   * Gets the memo to be included in the payment / path payment.
+   * Memos of type MEMO_HASH and MEMO_RETURN should be base64-decoded
+   * after returned from this function.
+   *
+   * @returns {string | undefined} the 'memo' uri param if present.
+   */
+  get memo(): string | undefined {
+    return this.getParam("memo");
+  }
+
+  /**
+   * Sets the memo to be included in the payment / path payment.
+   * Memos of type MEMO_HASH and MEMO_RETURN should be base64-encoded
+   * prior to being passed on this function.
+   *
+   * Deletes the uri 'memo' param if set as 'undefined'.
+   *
+   * @param {string | undefined} memo the uri 'memo' param to be set.
+   */
+  set memo(memo: string | undefined) {
+    this.setParam("memo", memo);
+  }
+
+  /**
+   * Gets the type of the memo.
+   *
+   * @returns {MemoType | undefined} the 'memo_type' uri param if present.
+   */
+  get memoType(): MemoType | undefined {
+    return this.getParam("memo_type") as MemoType | undefined;
+  }
+
+  /**
+   * Sets the type of the memo.
+   *
+   * Deletes the uri 'memo_type' param if set as 'undefined'.
+   *
+   * @param {MemoType | undefined} memoType the uri 'memo_type' param to be set.
+   */
+  set memoType(memoType: MemoType | undefined) {
+    this.setParam("memo_type", memoType);
+  }
+}