@stellar/typescript-wallet-sdk 4.0.0 → 4.0.1

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

@@ -115,9 +115,18 @@ export declare class NetworkPassphraseMismatchError extends Error {
 export declare class ChallengeTxnIncorrectSequenceError extends Error {
     constructor();
 }
+/**
+ * @deprecated No longer thrown. `Server.signChallengeTransaction` now validates
+ * challenges with `WebAuth.readChallengeTx` and reports every failure, including
+ * an invalid server signature, as `ChallengeValidationFailedError`. This class
+ * will be removed in the next major release.
+ */
 export declare class ChallengeTxnInvalidSignatureError extends Error {
     constructor();
 }
+export declare class ChallengeTxnClientAccountMismatchError extends Error {
+    constructor(expected: string, received: string);
+}
 export declare class AllowHttpOnNonTestnetError extends Error {
     constructor();
 }

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

@@ -5,14 +5,30 @@
 import { SignChallengeTxnParams, SignChallengeTxnResponse, AnchorTransaction } from "../Types";
 /**
  * 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 declare const signChallengeTransaction: ({ accountKp, challengeTx, networkPassphrase, anchorDomain, }: SignChallengeTxnParams) => Promise<SignChallengeTxnResponse>;
+export declare const signChallengeTransaction: ({ accountKp, challengeTx, networkPassphrase, anchorDomain, homeDomain, }: SignChallengeTxnParams) => Promise<SignChallengeTxnResponse>;
 /**
  * Helper method for parsing a JSON string into an AnchorTransaction.
  * @param {string} transaction - The json string of an anchor transaction.

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

@@ -54,6 +54,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 = {
     transaction: XdrEncodedTransaction;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar/typescript-wallet-sdk",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "engines": {
     "node": ">=22"
   },

package/src/walletSdk/Exceptions/index.ts

@@ -312,6 +312,12 @@ export class ChallengeTxnIncorrectSequenceError extends Error {
   }
 }
 
+/**
+ * @deprecated No longer thrown. `Server.signChallengeTransaction` now validates
+ * challenges with `WebAuth.readChallengeTx` and reports every failure, including
+ * an invalid server signature, as `ChallengeValidationFailedError`. This class
+ * will be removed in the next major release.
+ */
 export class ChallengeTxnInvalidSignatureError extends Error {
   constructor() {
     super("Invalid signature for challenge transaction");
@@ -319,6 +325,19 @@ export class ChallengeTxnInvalidSignatureError extends Error {
   }
 }
 
+export class ChallengeTxnClientAccountMismatchError extends Error {
+  constructor(expected: string, received: string) {
+    super(
+      `Challenge transaction client account mismatch: expected "${expected}" ` +
+        `but challenge was issued for "${received}"`,
+    );
+    Object.setPrototypeOf(
+      this,
+      ChallengeTxnClientAccountMismatchError.prototype,
+    );
+  }
+}
+
 export class AllowHttpOnNonTestnetError extends Error {
   constructor() {
     super("Can only allow Http on Testnet");

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,25 +58,50 @@ 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);

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/test/server.test.ts

@@ -1,6 +1,21 @@
 import axios from "axios";
-import { TransactionBuilder } from "@stellar/stellar-sdk";
+import sinon from "sinon";
+import {
+  Account,
+  Asset,
+  Keypair,
+  MuxedAccount,
+  Operation,
+  StellarToml,
+  Transaction,
+  TransactionBuilder,
+  WebAuth,
+} from "@stellar/stellar-sdk";
 import { Wallet, Server } from "../src";
+import {
+  ChallengeTxnClientAccountMismatchError,
+  ChallengeValidationFailedError,
+} from "../src/walletSdk/Exceptions";
 
 let wallet;
 let account;
@@ -78,3 +93,206 @@ describe("Server helpers", () => {
     expect(parsed.kind).toBe("withdrawal");
   });
 });
+
+describe("signChallengeTransaction validation", () => {
+  const anchorA = "anchor-a.example.com";
+  const anchorB = "anchor-b.example.com";
+
+  let anchorAKp;
+  let anchorBKp;
+  let accountKp;
+
+  beforeEach(() => {
+    anchorAKp = Keypair.random();
+    anchorBKp = Keypair.random();
+    accountKp = Wallet.TestNet().stellar().account().createKeypair();
+
+    // anchorDomain always resolves to anchor A's stellar.toml
+    sinon.stub(StellarToml.Resolver, "resolve").resolves({
+      SIGNING_KEY: anchorAKp.publicKey(),
+      WEB_AUTH_ENDPOINT: `https://${anchorA}/auth`,
+      DOCUMENTATION: {},
+    } as StellarToml.Api.StellarToml);
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  // webAuthDomain defaults to anchor A, which is what the stubbed
+  // WEB_AUTH_ENDPOINT resolves to for anchorDomain.
+  const buildChallenge = (
+    serverKp,
+    homeDomain,
+    clientAccountID,
+    webAuthDomain = anchorA,
+  ) =>
+    WebAuth.buildChallengeTx(
+      serverKp,
+      clientAccountID,
+      homeDomain,
+      300,
+      networkPassphrase,
+      webAuthDomain,
+    );
+
+  it("should sign a challenge issued by the expected anchor", async () => {
+    const challengeTx = buildChallenge(anchorAKp, anchorA, accountKp.publicKey);
+
+    const signedResp = await Server.signChallengeTransaction({
+      accountKp,
+      challengeTx,
+      networkPassphrase,
+      anchorDomain: anchorA,
+    });
+
+    const signedTxn = TransactionBuilder.fromXDR(
+      signedResp.transaction,
+      networkPassphrase,
+    );
+    expect(signedTxn.signatures.length).toBe(2);
+  });
+
+  it("should reject a challenge issued by a different anchor", async () => {
+    // A relays a challenge that anchor B issued for the same account, ordering
+    // its own signature first so that signatures[0] matches the SIGNING_KEY
+    // published at anchorDomain. Only the home domain, web auth domain and
+    // transaction source bind the challenge to the anchor that issued it.
+    const relayed = TransactionBuilder.fromXDR(
+      buildChallenge(anchorBKp, anchorB, accountKp.publicKey, anchorB),
+      networkPassphrase,
+    ) as Transaction;
+
+    const anchorBSignature = relayed.signatures[0];
+    relayed.signatures.length = 0;
+    relayed.sign(anchorAKp);
+    relayed.signatures.push(anchorBSignature);
+
+    await expect(
+      Server.signChallengeTransaction({
+        accountKp,
+        challengeTx: relayed.toXDR(),
+        networkPassphrase,
+        anchorDomain: anchorA,
+      }),
+    ).rejects.toThrow(ChallengeValidationFailedError);
+  });
+
+  it("should sign a challenge issued for a muxed account of the signing key", async () => {
+    // readChallengeTx returns the M... source verbatim; the underlying G... key
+    // is the correct signer, so this must be accepted.
+    const muxed = new MuxedAccount(
+      new Account(accountKp.publicKey, "0"),
+      "1234",
+    ).accountId();
+    expect(muxed.startsWith("M")).toBe(true);
+
+    const challengeTx = buildChallenge(anchorAKp, anchorA, muxed);
+
+    const signedResp = await Server.signChallengeTransaction({
+      accountKp,
+      challengeTx,
+      networkPassphrase,
+      anchorDomain: anchorA,
+    });
+
+    const signedTxn = TransactionBuilder.fromXDR(
+      signedResp.transaction,
+      networkPassphrase,
+    );
+    expect(signedTxn.signatures.length).toBe(2);
+  });
+
+  it("should reject a muxed challenge whose underlying key is not the signer", async () => {
+    const otherMuxed = new MuxedAccount(
+      new Account(Keypair.random().publicKey(), "0"),
+      "1234",
+    ).accountId();
+
+    await expect(
+      Server.signChallengeTransaction({
+        accountKp,
+        challengeTx: buildChallenge(anchorAKp, anchorA, otherMuxed),
+        networkPassphrase,
+        anchorDomain: anchorA,
+      }),
+    ).rejects.toThrow(ChallengeTxnClientAccountMismatchError);
+  });
+
+  it("should reject a challenge issued for a different account", async () => {
+    const otherAccount = Keypair.random().publicKey();
+    const challengeTx = buildChallenge(anchorAKp, anchorA, otherAccount);
+
+    await expect(
+      Server.signChallengeTransaction({
+        accountKp,
+        challengeTx,
+        networkPassphrase,
+        anchorDomain: anchorA,
+      }),
+    ).rejects.toThrow(ChallengeTxnClientAccountMismatchError);
+  });
+
+  it("should reject a transaction that is not a SEP-10 challenge", async () => {
+    const notAChallenge = new TransactionBuilder(
+      new Account(anchorAKp.publicKey(), "-1"),
+      { fee: "100", networkPassphrase },
+    )
+      .addOperation(
+        Operation.payment({
+          destination: anchorAKp.publicKey(),
+          asset: Asset.native(),
+          amount: "1000",
+        }),
+      )
+      .setTimeout(300)
+      .build();
+    notAChallenge.sign(anchorAKp);
+
+    await expect(
+      Server.signChallengeTransaction({
+        accountKp,
+        challengeTx: notAChallenge.toXDR(),
+        networkPassphrase,
+        anchorDomain: anchorA,
+      }),
+    ).rejects.toThrow(ChallengeValidationFailedError);
+  });
+
+  it("should wrap a malformed WEB_AUTH_ENDPOINT as a validation failure", async () => {
+    sinon.restore();
+    sinon.stub(StellarToml.Resolver, "resolve").resolves({
+      SIGNING_KEY: anchorAKp.publicKey(),
+      WEB_AUTH_ENDPOINT: "not a url",
+      DOCUMENTATION: {},
+    } as StellarToml.Api.StellarToml);
+
+    await expect(
+      Server.signChallengeTransaction({
+        accountKp,
+        challengeTx: buildChallenge(anchorAKp, anchorA, accountKp.publicKey),
+        networkPassphrase,
+        anchorDomain: anchorA,
+      }),
+    ).rejects.toThrow(ChallengeValidationFailedError);
+  });
+
+  it("should accept an explicit homeDomain that differs from anchorDomain", async () => {
+    const homeDomain = "wallet-home.example.com";
+    const challengeTx = buildChallenge(
+      anchorAKp,
+      homeDomain,
+      accountKp.publicKey,
+    );
+
+    const signedResp = await Server.signChallengeTransaction({
+      accountKp,
+      challengeTx,
+      networkPassphrase,
+      anchorDomain: anchorA,
+      homeDomain,
+    });
+
+    expect(signedResp.networkPassphrase).toBe(networkPassphrase);
+  });
+});