@stellar/typescript-wallet-sdk 4.0.0 → 5.0.0-beta.1788566740000

package/src/walletSdk/Server/index.ts

@@ -6,8 +6,9 @@
 import {
   Transaction,
   TransactionBuilder,
-  Keypair,
   StellarToml,
+  WebAuth,
+  extractBaseAddress,
 } from "@stellar/stellar-sdk";
 
 import { parseToml } from "../Utils";
@@ -21,18 +22,35 @@ import {
 } from "../Types";
 import {
   ChallengeTxnIncorrectSequenceError,
-  ChallengeTxnInvalidSignatureError,
+  ChallengeTxnClientAccountMismatchError,
+  ChallengeValidationFailedError,
   UnknownAnchorTransactionError,
   InvalidJsonError,
 } from "../Exceptions";
 
 /**
  * Helper method for signing a SEP-10 challenge transaction if valid.
+ *
+ * The challenge is validated with `WebAuth.readChallengeTx` from
+ * `@stellar/stellar-sdk` — the same validator used by `Sep10.sign()` — which
+ * checks the full SEP-10 structure and binds the challenge to the expected
+ * anchor: the transaction source must be the anchor's `SIGNING_KEY`, the
+ * `<home domain> auth` operation must match the expected home domain, and any
+ * `web_auth_domain` operation must match the host of the anchor's
+ * `WEB_AUTH_ENDPOINT` (falling back to `anchorDomain` when the TOML omits it).
+ * The client account the challenge was issued for is then checked against
+ * `accountKp`, so this helper only signs challenges meant for it. Muxed client
+ * accounts are supported: the comparison is made on the underlying `G...`
+ * address, since that is the key that signs. The muxed id itself is not pinned
+ * — a caller that needs to bind a specific subaccount should check the
+ * challenge's client account itself.
+ *
  * @param {SignChallengeTxnParams} params - The Authentication params.
  * @param {AccountKeypair} params.accountKp - Keypair for the Stellar account signing the transaction.
  * @param {string} [params.challengeTx] - The challenge transaction given by an anchor for authentication.
  * @param {string} [params.networkPassphrase] - The network passphrase for the network authenticating on.
  * @param {string} [params.anchorDomain] - Domain hosting stellar.toml file containing `SIGNING_KEY`.
+ * @param {string|string[]} [params.homeDomain] - Expected home domain(s) of the challenge. Defaults to `anchorDomain`.
  * @returns {Promise<SignChallengeTxnResponse>} The signed transaction.
  */
 export const signChallengeTransaction = async ({
@@ -40,30 +58,55 @@ export const signChallengeTransaction = async ({
   challengeTx,
   networkPassphrase,
   anchorDomain,
+  homeDomain,
 }: SignChallengeTxnParams): Promise<SignChallengeTxnResponse> => {
-  const tx = TransactionBuilder.fromXDR(
+  const parsedTx = TransactionBuilder.fromXdr(
     challengeTx,
     networkPassphrase,
   ) as Transaction;
 
-  if (parseInt(tx.sequence) !== 0) {
+  if (parseInt(parsedTx.sequence) !== 0) {
     throw new ChallengeTxnIncorrectSequenceError();
   }
 
   const tomlResp = await StellarToml.Resolver.resolve(anchorDomain);
-  const parsedToml = parseToml(tomlResp);
-  const anchorKp = Keypair.fromPublicKey(parsedToml.signingKey);
+  const { signingKey, webAuthEndpoint } = parseToml(tomlResp);
 
-  const isValid =
-    tx.signatures.length &&
-    anchorKp.verify(tx.hash(), tx.signatures[0].signature());
-  if (!isValid) {
-    throw new ChallengeTxnInvalidSignatureError();
+  let tx: Transaction;
+  let clientAccountID: string;
+  try {
+    // Kept inside the try so a malformed WEB_AUTH_ENDPOINT surfaces as a
+    // ChallengeValidationFailedError rather than a raw TypeError.
+    const webAuthDomain = webAuthEndpoint
+      ? new URL(webAuthEndpoint).hostname
+      : anchorDomain;
+
+    ({ tx, clientAccountID } = WebAuth.readChallengeTx(
+      challengeTx,
+      signingKey,
+      networkPassphrase,
+      homeDomain ?? anchorDomain,
+      webAuthDomain,
+    ));
+  } catch (e) {
+    throw new ChallengeValidationFailedError(
+      e instanceof Error ? e : new Error(String(e)),
+    );
+  }
+
+  // readChallengeTx returns the operation source verbatim, which is an `M...`
+  // address for a muxed client account. accountKp.publicKey is always the
+  // underlying `G...` key, so compare base addresses.
+  if (extractBaseAddress(clientAccountID) !== accountKp.publicKey) {
+    throw new ChallengeTxnClientAccountMismatchError(
+      accountKp.publicKey,
+      clientAccountID,
+    );
   }
 
   accountKp.sign(tx);
   return {
-    transaction: tx.toXDR(),
+    transaction: tx.toXdr(),
     networkPassphrase,
   };
 };

package/src/walletSdk/Types/auth.ts

@@ -94,6 +94,11 @@ export type SignChallengeTxnParams = {
   challengeTx: string;
   networkPassphrase: string;
   anchorDomain: string;
+  /**
+   * The home domain(s) the challenge is expected to be scoped to. Defaults to
+   * `anchorDomain`. Pass an array for anchors that serve multiple home domains.
+   */
+  homeDomain?: string | string[];
 };
 
 export type SignChallengeTxnResponse = {

package/src/walletSdk/Types/horizon.ts

@@ -44,10 +44,21 @@ export type PathPayParams = {
   destinationAddress: string;
   sendAsset: StellarAssetId;
   destAsset: StellarAssetId;
-  sendAmount?: string;
-  destAmount?: string;
-  destMin?: string;
-  sendMax?: string;
-};
+} & (
+  | {
+      // Strict send: spend exactly sendAmount, receive at least destMin
+      sendAmount: string;
+      destMin: string;
+      destAmount?: never;
+      sendMax?: never;
+    }
+  | {
+      // Strict receive: deliver exactly destAmount, spend at most sendMax
+      destAmount: string;
+      sendMax: string;
+      sendAmount?: never;
+      destMin?: never;
+    }
+);
 
 export type CommonBuilder = TransactionBuilder | SponsoringBuilder;

package/src/walletSdk/Types/sep12.ts

@@ -3,7 +3,7 @@ export type CustomerInfoMap = {
 };
 
 export type CustomerBinaryInfoMap = {
-  [key: string]: Buffer;
+  [key: string]: Uint8Array;
 };
 
 export enum Sep12Status {

package/src/walletSdk/Uri/Sep7Base.ts

@@ -1,4 +1,5 @@
-import { Keypair, Networks, StellarToml } from "@stellar/stellar-sdk";
+import { Keypair, Networks, StellarToml, xdr } from "@stellar/stellar-sdk";
+import { concatUint8Arrays, stringToUint8Array } from "uint8array-extras";
 import {
   Sep7OperationType,
   URI_MSG_MAX_LENGTH,
@@ -214,7 +215,7 @@ export abstract class Sep7Base {
    */
   addSignature(keypair: Keypair): string {
     const payload = this.createSignaturePayload();
-    const signature = keypair.sign(payload).toString("base64");
+    const signature = xdr.encodeBytes(keypair.sign(payload), "base64");
     this.setParam("signature", signature);
     return signature;
   }
@@ -256,7 +257,7 @@ export abstract class Sep7Base {
       }
       const keypair = Keypair.fromPublicKey(signingKey);
       const payload = this.createSignaturePayload();
-      return keypair.verify(payload, Buffer.from(signature, "base64"));
+      return keypair.verify(payload, xdr.decodeBytes(signature, "base64"));
     } catch (e) {
       // if something fails we assume signature verification failed
       return false;
@@ -300,10 +301,10 @@ export abstract class Sep7Base {
    *
    * @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
+   * @returns {Uint8Array} array of bytes to be signed with given keypair on
    * the 'addSignature' method.
    */
-  private createSignaturePayload(): Buffer {
+  private createSignaturePayload(): Uint8Array {
     let data = this.toString();
 
     const signature = this.signature;
@@ -315,10 +316,10 @@ export abstract class Sep7Base {
     // 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}`),
+    return concatUint8Arrays([
+      new Uint8Array(35),
+      Uint8Array.of(4),
+      stringToUint8Array(`stellar.sep.7 - URI Scheme${data}`),
     ]);
   }
 }

package/src/walletSdk/Uri/Sep7Tx.ts

@@ -30,7 +30,7 @@ export class Sep7Tx extends Sep7Base {
    */
   static forTransaction(transaction: Transaction): Sep7Tx {
     const uri = new Sep7Tx();
-    uri.xdr = transaction.toEnvelope().toXDR().toString("base64");
+    uri.xdr = transaction.toEnvelope().toXdr("base64");
     uri.networkPassphrase = transaction.networkPassphrase as Networks;
     return uri;
   }

package/test/auth.test.ts

@@ -7,6 +7,7 @@ import {
   MuxedAccount,
   Networks,
   StellarToml,
+  StrKey,
   Transaction,
   TransactionBuilder as SdkTransactionBuilder,
   Operation,
@@ -15,8 +16,12 @@ import {
 import { randomBytes } from "crypto";
 import axios from "axios";
 import sinon from "sinon";
+import { base64ToString, base64ToUint8Array } from "uint8array-extras";
+import { encode as utf8Encode } from "@stablelib/utf8";
+import nacl from "tweetnacl";
 
 import { validateToken, Sep10, type WalletSigner } from "../src/walletSdk/Auth";
+import { DefaultAuthHeaderSigner } from "../src/walletSdk/Auth/AuthHeaderSigner";
 import {
   Config,
   StellarConfiguration,
@@ -837,3 +842,40 @@ describe("Anchor.sep10() signing key handling", () => {
     expect(sep10).toBeDefined();
   });
 });
+
+describe("auth header JWT encoding", () => {
+  it("signs with unpadded base64url and verifies against the public key", async () => {
+    const kp = SigningKeypair.fromSecret(Keypair.random().secret());
+    const signer = new DefaultAuthHeaderSigner();
+
+    const jwt = await signer.createToken({
+      claims: {
+        account: kp.publicKey,
+        home_domain: "test.com",
+        web_auth_endpoint: "https://test.com/auth",
+      },
+      issuer: kp,
+    });
+
+    const [header, payload, signature] = jwt.split(".");
+
+    // base64url: no +, / or = padding in any segment.
+    for (const segment of [header, payload, signature]) {
+      expect(segment).not.toMatch(/[+/=]/);
+    }
+
+    // The header must still decode to real JSON.
+    expect(JSON.parse(base64ToString(header))).toEqual({ alg: "EdDSA" });
+
+    // The signature must verify over "<header>.<payload>".
+    const naclKP = nacl.sign.keyPair.fromSeed(
+      StrKey.decodeEd25519SecretSeed(kp.secretKey),
+    );
+    const verified = nacl.sign.detached.verify(
+      utf8Encode(`${header}.${payload}`),
+      base64ToUint8Array(signature),
+      naclKP.publicKey,
+    );
+    expect(verified).toBe(true);
+  });
+});

package/test/e2e/reactNative.test.ts

@@ -0,0 +1,190 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as vm from "vm";
+
+/**
+ * React Native's Hermes runtime provides none of Buffer, Event, EventTarget or
+ * process. Loading each published bundle in a context without them catches the
+ * two failure modes this SDK has actually shipped: a reliance on the Buffer
+ * global, and dependencies that subclass the DOM Event globals at module scope.
+ *
+ * The sandbox also *grants* a few globals that a real RN app must supply
+ * itself, so this file is explicit about what environment it is modelling:
+ *
+ * - `crypto`: Hermes/RN does not provide this either. A real RN app needs
+ *   `react-native-get-random-values` (or equivalent) for stellar-sdk's RNG
+ *   path. This was already true under v16 and is not new to this migration.
+ * - `btoa`/`atob`: see the dedicated comment below.
+ * - `TextEncoder`/`TextDecoder`: see the dedicated comment below.
+ */
+const BANNED = ["Buffer", "Event", "EventTarget", "process"];
+
+const makeHermesLikeContext = ({
+  includeBase64 = true,
+  includeTextCodec = true,
+} = {}) => {
+  const sandbox: Record<string, unknown> = {
+    console,
+    URL,
+    URLSearchParams,
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+    crypto: globalThis.crypto,
+    fetch: globalThis.fetch,
+    module: { exports: {} },
+    exports: {},
+  };
+
+  if (includeTextCodec) {
+    // TextEncoder/TextDecoder are a real consumer requirement, not a test
+    // convenience, and the requirement is unavoidable: uint8array-extras@1.5.0
+    // — a direct dependency of ours and a transitive dependency of
+    // stellar-sdk — constructs both at module initialization, unguarded:
+    // `new globalThis.TextDecoder('utf8')` (index.js:113, inside a
+    // module-scope object literal) and `new globalThis.TextEncoder()`
+    // (index.js:128). By contrast, @exodus/bytes DOES guard this —
+    // fallback/platform.native.js only constructs them when
+    // `isNative(globalThis.TextDecoder)` holds, falling back to pure-JS
+    // decoding otherwise — so the requirement traces specifically to
+    // uint8array-extras, not to @exodus/bytes. Granting them here models an
+    // environment that satisfies this prerequisite. We cannot verify from
+    // here whether React Native itself provides them (this file makes no
+    // claim either way), but RN apps commonly polyfill TextEncoder/TextDecoder
+    // already for other libraries. Remove them and every bundle throws
+    // "TypeError: globalThis.TextDecoder is not a constructor" at load —
+    // before any of our own code runs. See the test below that enforces this.
+    sandbox.TextEncoder = TextEncoder;
+    sandbox.TextDecoder = TextDecoder;
+  }
+
+  if (includeBase64) {
+    // btoa/atob are a real consumer requirement of this release, not a test
+    // convenience. stellar-sdk v17's xdr.encodeBytes(bytes, "base64") routes
+    // through its own lib/cjs/base/util/base64.js, which calls the bare `btoa`
+    // identifier with no fallback, and Task 2 removed the browser bundle's
+    // Buffer polyfill that used to cover it. Hermes provides btoa/atob
+    // natively as of React Native 0.74 (facebook/hermes#1255, #1256); React
+    // Native's own JS layer has never defined them, so RN < 0.74 and
+    // non-Hermes engines (JSC, V8) need a polyfill such as `base-64`.
+    // Granting them here models a supported RN >= 0.74 Hermes app. Remove
+    // them and every base64 path throws "ReferenceError: btoa is not
+    // defined"; hex and base32/StrKey still work, being pure JS.
+    sandbox.btoa = globalThis.btoa;
+    sandbox.atob = globalThis.atob;
+  }
+
+  sandbox.global = sandbox;
+  sandbox.globalThis = sandbox;
+
+  const context = vm.createContext(sandbox);
+  for (const name of BANNED) {
+    vm.runInContext(
+      `if (typeof ${name} !== "undefined") { throw new Error("${name} leaked into the sandbox"); }`,
+      context,
+    );
+  }
+  return context;
+};
+
+const bundles = [
+  ["core SDK", "../../lib/bundle_browser.js"],
+  ["key manager", "../../../typescript-wallet-sdk-km/lib/bundle_browser.js"],
+  ["soroban", "../../../typescript-wallet-sdk-soroban/lib/bundle_browser.js"],
+] as const;
+
+describe("React Native (Hermes-like) bundle compatibility", () => {
+  for (const [name, relativePath] of bundles) {
+    it(`loads the ${name} bundle without Buffer/Event/EventTarget/process`, () => {
+      const bundlePath = path.resolve(__dirname, relativePath);
+      expect(fs.existsSync(bundlePath)).toBe(true);
+
+      const context = makeHermesLikeContext();
+      const code = fs.readFileSync(bundlePath, "utf8");
+
+      expect(() =>
+        vm.runInContext(code, context, { filename: `${name}.js` }),
+      ).not.toThrow();
+    });
+  }
+
+  for (const [name, relativePath] of bundles) {
+    it(`fails to load the ${name} bundle without TextEncoder/TextDecoder`, () => {
+      const bundlePath = path.resolve(__dirname, relativePath);
+      const context = makeHermesLikeContext({ includeTextCodec: false });
+      const code = fs.readFileSync(bundlePath, "utf8");
+
+      // uint8array-extras constructs its TextDecoder/TextEncoder at module
+      // initialization (see the comment in makeHermesLikeContext), so the
+      // failure happens at load time, before any of our own code runs. This
+      // turns the assumption granted above into an enforced, documented
+      // contract rather than a silent one.
+      expect(() =>
+        vm.runInContext(code, context, { filename: `${name}.js` }),
+      ).toThrow(/TextDecoder is not a constructor/);
+    });
+  }
+
+  it("exercises the core SDK public API in the sandbox", () => {
+    const context = makeHermesLikeContext();
+    const code = fs.readFileSync(
+      path.resolve(__dirname, "../../lib/bundle_browser.js"),
+      "utf8",
+    );
+    vm.runInContext(code, context, { filename: "bundle_browser.js" });
+
+    // Sep7Pay.addSignature is the densest no-Buffer path in our own code: it
+    // runs concatUint8Arrays + stringToUint8Array to build the payload, signs
+    // it, then base64-encodes via xdr.encodeBytes.
+    const result = vm.runInContext(
+      `(() => {
+        const { Wallet, Sep7Pay } = module.exports;
+        const kp = Wallet.TestNet().stellar().account().createKeypair();
+        const uri = Sep7Pay.forDestination(kp.publicKey);
+        return { publicKey: kp.publicKey, signature: uri.addSignature(kp.keypair) };
+      })()`,
+      context,
+    ) as { publicKey: string; signature: string };
+
+    expect(result.publicKey).toMatch(/^G[A-Z2-7]{55}$/);
+    // The decisive assertion: base64 encoding worked without Buffer. A broken
+    // encoder yields comma-joined decimals.
+    expect(result.signature).toMatch(/^[A-Za-z0-9+/]+={0,2}$/);
+    expect(result.signature).toHaveLength(88);
+  });
+
+  it("requires btoa/atob for base64 paths, while base32/StrKey keypair creation stays pure JS", () => {
+    const context = makeHermesLikeContext({ includeBase64: false });
+    const code = fs.readFileSync(
+      path.resolve(__dirname, "../../lib/bundle_browser.js"),
+      "utf8",
+    );
+    vm.runInContext(code, context, { filename: "bundle_browser.js" });
+
+    // Keypair generation and the public key's StrKey encoding are pure JS
+    // (base32, not base64), so they must work even without btoa/atob.
+    const publicKey = vm.runInContext(
+      `(() => {
+        const { Wallet } = module.exports;
+        return Wallet.TestNet().stellar().account().createKeypair().publicKey;
+      })()`,
+      context,
+    ) as string;
+    expect(publicKey).toMatch(/^G[A-Z2-7]{55}$/);
+
+    // Sep7Pay.addSignature's base64 encode step has no fallback: without
+    // btoa this must fail loudly rather than silently degrade.
+    expect(() =>
+      vm.runInContext(
+        `(() => {
+          const { Wallet, Sep7Pay } = module.exports;
+          const kp = Wallet.TestNet().stellar().account().createKeypair();
+          const uri = Sep7Pay.forDestination(kp.publicKey);
+          return uri.addSignature(kp.keypair);
+        })()`,
+        context,
+      ),
+    ).toThrow(/btoa is not defined/);
+  });
+});

package/test/sep7.test.ts

@@ -1,4 +1,13 @@
-import { Keypair, Networks, StellarToml } from "@stellar/stellar-sdk";
+import {
+  Account,
+  Asset,
+  BASE_FEE,
+  Keypair,
+  Networks,
+  Operation,
+  StellarToml,
+  TransactionBuilder,
+} from "@stellar/stellar-sdk";
 import {
   NativeAssetId,
   Sep7Pay,
@@ -360,7 +369,7 @@ describe("Sep7Tx", () => {
     txBuilder.transfer(testKp2.publicKey, new NativeAssetId(), "1");
     const tx = txBuilder.build();
 
-    const xdr = tx.toEnvelope().toXDR().toString("base64");
+    const xdr = tx.toEnvelope().toXdr("base64");
 
     const uri = Sep7Tx.forTransaction(tx);
     expect(uri.operationType).toBe("tx");
@@ -488,7 +497,7 @@ describe("Sep7Tx", () => {
     txBuilder.transfer(testKp2.publicKey, new NativeAssetId(), "1");
     const tx = txBuilder.build();
 
-    const xdr = tx.toEnvelope().toXDR().toString("base64");
+    const xdr = tx.toEnvelope().toXdr("base64");
 
     const uri = Sep7Tx.forTransaction(tx);
 
@@ -553,13 +562,11 @@ describe("Sep7Tx", () => {
     txBuilder.transfer(testKp2.publicKey, new NativeAssetId(), "1");
     const tx = txBuilder.build();
 
-    const xdr = tx.toEnvelope().toXDR().toString("base64");
+    const xdr = tx.toEnvelope().toXdr("base64");
 
     const uri = new Sep7Tx(`web+stellar:tx?xdr=${encodeURIComponent(xdr)}`);
 
-    expect(uri.getTransaction().toEnvelope().toXDR().toString("base64")).toBe(
-      xdr,
-    );
+    expect(uri.getTransaction().toEnvelope().toXdr("base64")).toBe(xdr);
   });
 });
 
@@ -1002,3 +1009,61 @@ describe("sep7Parser", () => {
     expect(actual).toBe(expected);
   });
 });
+
+describe("SEP-7 byte encoding regressions", () => {
+  const BASE64_ONLY = /^[A-Za-z0-9+/]+={0,2}$/;
+
+  it("produces a base64 signature, not comma-joined decimals", () => {
+    const keypair = Keypair.random();
+    const uri = Sep7Pay.forDestination(
+      "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO",
+    );
+
+    const signature = uri.addSignature(keypair);
+
+    expect(signature).toMatch(BASE64_ONLY);
+    expect(signature).not.toContain(",");
+    // An ed25519 signature is 64 bytes => 88 base64 characters with padding.
+    expect(signature).toHaveLength(88);
+  });
+
+  it("round-trips a signature through verification", async () => {
+    const keypair = Keypair.random();
+    const uri = Sep7Pay.forDestination(
+      "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO",
+    );
+    uri.originDomain = "place.domain.com";
+    uri.addSignature(keypair);
+
+    jest
+      .spyOn(StellarToml.Resolver, "resolve")
+      .mockResolvedValue({ URI_REQUEST_SIGNING_KEY: keypair.publicKey() });
+
+    await expect(uri.verifySignature()).resolves.toBe(true);
+  });
+
+  it("puts parseable XDR in the uri, not comma-joined decimals", () => {
+    const keypair = Keypair.random();
+    const account = new Account(keypair.publicKey(), "1");
+    const tx = new TransactionBuilder(account, {
+      fee: BASE_FEE,
+      networkPassphrase: Networks.TESTNET,
+    })
+      .addOperation(
+        Operation.payment({
+          destination: keypair.publicKey(),
+          asset: Asset.native(),
+          amount: "1",
+        }),
+      )
+      .setTimeout(30)
+      .build();
+
+    const uri = Sep7Tx.forTransaction(tx);
+
+    expect(uri.xdr).toMatch(BASE64_ONLY);
+    expect(uri.xdr).not.toContain(",");
+    // The decisive check: it must parse back into the same transaction.
+    expect(uri.getTransaction().toXdr()).toEqual(tx.toXdr());
+  });
+});