fix(anchor-sdk)!: validate SEP-10 challenges before handing them to a signer (#999)

`Sep10Client.authenticate()` fetched the anchor's challenge and passed the
raw XDR straight into the caller-supplied `sign` callback with no checks at
all. None of the SEP-10 mandated client-side validation ran: no verification
of the anchor's signature over the transaction, no source-account check, no
`sequence == 0`, no `<home_domain> auth` Manage Data operation check, no
operation-source check, no time bounds. `network_passphrase` was parsed by
the Zod schema and then never compared to anything.

The giveaway was in sep1.ts: `SIGNING_KEY` — the single value that can prove
a challenge came from the anchor — was parsed out of `stellar.toml` and never
read by any code path.

Impact: a hostile or compromised anchor, or an on-path attacker against a
plain-http WEB_AUTH_ENDPOINT (the constructor accepted one), could return an
ordinary transaction instead of a challenge — a payment, or a set_options
adding a signer — and have it blind-signed by the consumer's wallet, hardware
device, or KMS. The module docstring offered "this package never holds key
material" as a safety property; not holding the key does not make signing an
unchecked transaction safe, it just relocates the consequence to whoever does
hold it.

Fix: `verifyChallenge()` runs `WebAuth.readChallengeTx` — the reference
implementation of every required check — and `authenticate()` calls it BEFORE
`sign`. A `network_passphrase` that disagrees with the configured network is
rejected first, since otherwise the signature would be checked against the
wrong network's transaction hash. Non-https endpoints are refused at
construction.

`WebAuth` is re-exported from pulse-core rather than added as a direct
dependency of anchor-sdk, following the existing `StrKey` re-export at
pulse-core/src/index.ts:45. pulse-core already depends on
@stellar/stellar-sdk, so the runtime dependency tree is unchanged and the
bundle-size job is unaffected.

`Sep10Client.fromToml(toml, homeDomain)` is the recommended constructor: it
takes SIGNING_KEY and NETWORK_PASSPHRASE from the toml the caller already
fetches, so the verification key cannot be forgotten. Anchors publishing no
SIGNING_KEY are refused rather than trusted.

BREAKING CHANGE: `Sep10Client` now requires `serverAccountId`,
`networkPassphrase`, `homeDomain` and `webAuthDomain`. These cannot be
optional — an optional verification key is one callers omit, which is the
bug. Taken under the security exception in STABILITY.md ("if a covered
surface is itself the vulnerability"); anchor-sdk goes 0.1.0 -> 0.2.0 and
CHANGELOG.md carries the required `### Security` entry with migration.
A GitHub Security Advisory still needs publishing per SECURITY.md.

Tests: 14 new cases in test/sep10.test.ts built against real challenge
transactions. Each rejection case asserts `sign` was never called — that the
challenge is refused is secondary, that it never reached the signer is the
point. Verified as genuine regressions: with the `verifyChallenge` call
removed, 6 of them fail.

The three SEP-10 cases in test/sep24.test.ts moved here. They drove
authenticate() with placeholder XDR ("AAAA-challenge") and only passed
because nothing inspected it; they now use real challenges.

67 tests pass in anchor-sdk, 614 in pulse-core.

Co-authored-by: Salmatcre8 <118213044+Salmatcre8@users.noreply.github.com>

Author: determined-001

CHANGELOG.md

@@ -44,6 +44,45 @@ Per-package changelogs live in each package directory.
 
 ### Security
 
+- **`@orbital-stellar/anchor-sdk` 0.1.0 does not validate SEP-10 challenges
+  before signing them.** `Sep10Client.authenticate()` passed the anchor's
+  challenge XDR straight to the caller-supplied `sign` callback with no checks:
+  no verification of the anchor's signature, no source-account or `sequence == 0`
+  check, no `<home_domain> auth` Manage Data check, no time bounds. The
+  `network_passphrase` in the response was parsed and then ignored, and
+  `SIGNING_KEY` — the one value that can attribute a challenge to an anchor —
+  was read from `stellar.toml` and never used.
+
+  A hostile or compromised anchor, or an on-path attacker against a plain-`http`
+  `WEB_AUTH_ENDPOINT`, could return an ordinary transaction (a payment, or a
+  `set_options` adding a signer) and have it blind-signed by the consumer's
+  wallet, hardware device, or KMS.
+
+  Fixed in **0.2.0**. `Sep10Client` now verifies every challenge with
+  `WebAuth.readChallengeTx` before `sign` is invoked, rejects a
+  `network_passphrase` that disagrees with the configured network, and refuses a
+  non-`https` endpoint at construction.
+
+  This is a **breaking change to a surface that was itself the vulnerability**,
+  taken under the security exception in [`STABILITY.md`](./STABILITY.md).
+  A GitHub Security Advisory is to be published per [`SECURITY.md`](./SECURITY.md).
+
+  **Migration.** `Sep10Client` now requires the anchor's identity. The smallest
+  change is to build it from the anchor's own `stellar.toml`:
+
+  ```ts
+  // before - no way to tell whose challenge you were signing
+  const client = new Sep10Client(toml.WEB_AUTH_ENDPOINT);
+
+  // after - SIGNING_KEY and NETWORK_PASSPHRASE come from the toml you already fetch
+  const toml = await discoverAnchor("anchor.example");
+  const client = Sep10Client.fromToml(toml, "anchor.example");
+  ```
+
+  Or pass them explicitly: `new Sep10Client(endpoint, { serverAccountId,
+  networkPassphrase, homeDomain, webAuthDomain })`. Anchors that publish no
+  `SIGNING_KEY` are now refused rather than trusted.
+
 ---
 
 ## [0.1.0] - 2026-05-28

packages/anchor-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbital-stellar/anchor-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK for interacting with Stellar Anchors (SEP-12, SEP-24, SEP-31).",
   "license": "MIT",
   "engines": {
@@ -40,6 +40,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@stellar/stellar-sdk": "^16.1.0",
     "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "^4.1.10",
     "vite": "^8.1.5",

packages/anchor-sdk/src/sep10.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { WebAuth } from "@orbital-stellar/pulse-core";
+import type { StellarToml } from "./sep1.js";
 import { stripTrailingSlashes } from "./strings.js";
 
 /**
@@ -9,6 +11,12 @@ import { stripTrailingSlashes } from "./strings.js";
  * secret key. This package never holds key material: a consumer can sign with
  * a hardware wallet, a KMS, or `Keypair.sign` - the SDK only sees the signed
  * XDR that comes back.
+ *
+ * That delegation is only safe if the challenge is checked first. Not holding
+ * the key does not reduce the risk of signing the wrong transaction, it just
+ * moves the risk to whoever does hold it. So `Sep10Client` validates every
+ * challenge against the anchor's `SIGNING_KEY` before the signer ever sees it -
+ * see `verifyChallenge`.
  */
 
 /** Thrown when the anchor rejects the challenge or returns an unusable one. */
@@ -35,6 +43,21 @@ const Sep10TokenSchema = z.object({ token: z.string() });
 export type ChallengeSigner = (challenge: Sep10Challenge) => Promise<string> | string;
 
 export type Sep10ClientOptions = {
+  /**
+   * The anchor's `SIGNING_KEY` from its `stellar.toml` (see `discoverAnchor`).
+   * The challenge must carry a valid signature from this key or it is not the
+   * anchor's challenge and must never reach the signer.
+   */
+  serverAccountId: string;
+  /** Expected network passphrase, e.g. `Networks.TESTNET`. */
+  networkPassphrase: string;
+  /**
+   * Home domain(s) expected in the challenge's first Manage Data key. Pass an
+   * array when an anchor serves several.
+   */
+  homeDomain: string | string[];
+  /** Domain expected as the value of the `web_auth_domain` Manage Data entry. */
+  webAuthDomain: string;
   /** Transport override; defaults to the global `fetch`. */
   transport?: (input: string, init?: RequestInit) => Promise<Response>;
   /** Request timeout in milliseconds. Defaults to 10 000. */
@@ -54,15 +77,122 @@ export type Sep10AuthenticateParams = {
 
 export class Sep10Client {
   private readonly webAuthEndpoint: string;
+  private readonly serverAccountId: string;
+  private readonly networkPassphrase: string;
+  private readonly homeDomain: string | string[];
+  private readonly webAuthDomain: string;
   private readonly transport: (input: string, init?: RequestInit) => Promise<Response>;
   private readonly timeoutMs: number;
 
-  constructor(webAuthEndpoint: string, options: Sep10ClientOptions = {}) {
+  constructor(webAuthEndpoint: string, options: Sep10ClientOptions) {
+    // The challenge we are about to sign arrives over this connection. Without
+    // TLS an on-path attacker chooses the transaction, so refuse rather than
+    // authenticate over cleartext.
+    if (!/^https:\/\//i.test(webAuthEndpoint)) {
+      throw new Sep10AuthError(`WEB_AUTH_ENDPOINT must be https, got "${webAuthEndpoint}"`);
+    }
+    if (!options?.serverAccountId) {
+      throw new Sep10AuthError(
+        "serverAccountId is required - it is the anchor's SIGNING_KEY and the only way to prove a challenge came from the anchor",
+      );
+    }
+    if (!options.networkPassphrase) {
+      throw new Sep10AuthError("networkPassphrase is required");
+    }
+    if (!options.homeDomain || (Array.isArray(options.homeDomain) && !options.homeDomain.length)) {
+      throw new Sep10AuthError("homeDomain is required");
+    }
+    if (!options.webAuthDomain) {
+      throw new Sep10AuthError("webAuthDomain is required");
+    }
+
     this.webAuthEndpoint = stripTrailingSlashes(webAuthEndpoint);
+    this.serverAccountId = options.serverAccountId;
+    this.networkPassphrase = options.networkPassphrase;
+    this.homeDomain = options.homeDomain;
+    this.webAuthDomain = options.webAuthDomain;
     this.transport = options.transport ?? fetch.bind(globalThis);
     this.timeoutMs = options.timeoutMs ?? 10_000;
   }
 
+  /**
+   * Builds a client from a `stellar.toml` fetched with `discoverAnchor`, taking
+   * `WEB_AUTH_ENDPOINT`, `SIGNING_KEY` and `NETWORK_PASSPHRASE` from it.
+   *
+   * Prefer this over the constructor: it is the path that cannot forget to pass
+   * `SIGNING_KEY`, without which no challenge can be attributed to the anchor.
+   *
+   * @param toml - Parsed `stellar.toml` for `homeDomain`.
+   * @param homeDomain - The domain the toml was fetched from; also the value
+   *   expected in the challenge's Manage Data key.
+   * @throws {Sep10AuthError} if the toml omits `WEB_AUTH_ENDPOINT`,
+   *   `SIGNING_KEY`, or `NETWORK_PASSPHRASE`.
+   */
+  static fromToml(
+    toml: StellarToml,
+    homeDomain: string,
+    options: Partial<Omit<Sep10ClientOptions, "serverAccountId">> = {},
+  ): Sep10Client {
+    if (!toml.WEB_AUTH_ENDPOINT) {
+      throw new Sep10AuthError(`${homeDomain} stellar.toml has no WEB_AUTH_ENDPOINT`);
+    }
+    if (!toml.SIGNING_KEY) {
+      throw new Sep10AuthError(
+        `${homeDomain} stellar.toml has no SIGNING_KEY - challenges from this anchor cannot be verified, refusing to authenticate`,
+      );
+    }
+    const networkPassphrase = options.networkPassphrase ?? toml.NETWORK_PASSPHRASE;
+    if (!networkPassphrase) {
+      throw new Sep10AuthError(
+        `${homeDomain} stellar.toml has no NETWORK_PASSPHRASE - pass networkPassphrase explicitly`,
+      );
+    }
+
+    return new Sep10Client(toml.WEB_AUTH_ENDPOINT, {
+      ...options,
+      serverAccountId: toml.SIGNING_KEY,
+      networkPassphrase,
+      homeDomain: options.homeDomain ?? homeDomain,
+      webAuthDomain: options.webAuthDomain ?? new URL(toml.WEB_AUTH_ENDPOINT).host,
+    });
+  }
+
+  /**
+   * Runs every SEP-10 check the client is responsible for before the challenge
+   * is handed to a signer: the server's signature over the transaction, source
+   * account, sequence number 0, the `<home_domain> auth` Manage Data operation
+   * and its source, `web_auth_domain`, and time bounds.
+   *
+   * @throws {Sep10AuthError} if the challenge is not a well-formed challenge
+   *   from the configured anchor on the configured network.
+   */
+  verifyChallenge(challenge: Sep10Challenge): void {
+    // An anchor may echo the network it built the challenge for. If it does and
+    // it disagrees with ours, stop here - otherwise readChallengeTx would be
+    // checking the signature against the wrong network's transaction hash.
+    if (
+      challenge.network_passphrase !== undefined &&
+      challenge.network_passphrase !== this.networkPassphrase
+    ) {
+      throw new Sep10AuthError(
+        `challenge is for network "${challenge.network_passphrase}", expected "${this.networkPassphrase}"`,
+      );
+    }
+
+    try {
+      WebAuth.readChallengeTx(
+        challenge.transaction,
+        this.serverAccountId,
+        this.networkPassphrase,
+        this.homeDomain,
+        this.webAuthDomain,
+      );
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Sep10AuthError(`challenge failed validation (${reason})`);
+    }
+  }
+
   /** GET the challenge transaction the anchor wants signed. */
   async challenge(params: {
     account: string;
@@ -120,6 +250,12 @@ export class Sep10Client {
       ...(params.clientDomain !== undefined ? { clientDomain: params.clientDomain } : {}),
     });
 
+    // Validate BEFORE signing. `params.sign` may reach a hardware wallet or a
+    // KMS, and whatever we hand it can be signed and broadcast - a hostile or
+    // compromised anchor returning a payment or a set_options adding a signer
+    // must be rejected here, not noticed afterwards.
+    this.verifyChallenge(challenge);
+
     const signed = await params.sign(challenge);
     if (typeof signed !== "string" || signed === "") {
       throw new Sep10AuthError("signer returned an empty transaction");

packages/anchor-sdk/test/errorPaths.test.ts

@@ -3,6 +3,7 @@ import {
   Sep1DiscoveryError,
   Sep10AuthError,
   Sep10Client,
+  type Sep10ClientOptions,
   Sep24Client,
   Sep24Error,
   discoverAnchor,
@@ -25,6 +26,22 @@ function failingTransport(message: string) {
   });
 }
 
+/**
+ * Builds a Sep10Client for the transport-level cases below. These exercise
+ * `challenge()` / `token()` directly and never sign, so the verification
+ * parameters just need to be present and well-formed - `test/sep10.test.ts`
+ * covers what they actually do.
+ */
+function sep10ClientWith(options: Partial<Sep10ClientOptions> = {}): Sep10Client {
+  return new Sep10Client("https://a.example.com/auth", {
+    serverAccountId: "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
+    networkPassphrase: "Test SDF Network ; September 2015",
+    homeDomain: "a.example.com",
+    webAuthDomain: "a.example.com",
+    ...options,
+  });
+}
+
 describe("SEP-1 failure paths", () => {
   it("rejects an empty home domain before making a request", async () => {
     const transport = vi.fn();
@@ -69,28 +86,28 @@ describe("SEP-1 failure paths", () => {
 describe("SEP-10 failure paths", () => {
   it("reports a non-2xx challenge response", async () => {
     const transport = vi.fn(async () => new Response("no", { status: 400 }));
-    const client = new Sep10Client("https://a.example.com/auth", { transport });
+    const client = sep10ClientWith({ transport });
 
     await expect(client.challenge({ account: "GABC" })).rejects.toThrow(/returned 400/);
   });
 
   it("rejects a challenge body with no transaction", async () => {
     const transport = vi.fn(async () => jsonResponse({ nope: true }));
-    const client = new Sep10Client("https://a.example.com/auth", { transport });
+    const client = sep10ClientWith({ transport });
 
     await expect(client.challenge({ account: "GABC" })).rejects.toBeInstanceOf(Sep10AuthError);
   });
 
   it("surfaces the anchor's error message when the token exchange is rejected", async () => {
     const transport = vi.fn(async () => jsonResponse({ error: "invalid signature" }, 401));
-    const client = new Sep10Client("https://a.example.com/auth", { transport });
+    const client = sep10ClientWith({ transport });
 
     await expect(client.token("signed")).rejects.toThrow(/invalid signature/);
   });
 
   it("rejects a token response with no token", async () => {
     const transport = vi.fn(async () => jsonResponse({ jwt: "wrong-field" }));
-    const client = new Sep10Client("https://a.example.com/auth", { transport });
+    const client = sep10ClientWith({ transport });
 
     await expect(client.token("signed")).rejects.toThrow(/did not contain a token/);
   });
@@ -101,7 +118,7 @@ describe("SEP-10 failure paths", () => {
       calls.push(url);
       return jsonResponse({ transaction: "AAAA" });
     });
-    const client = new Sep10Client("https://a.example.com/auth", { transport });
+    const client = sep10ClientWith({ transport });
 
     await client.challenge({ account: "GABC", memo: "12345", clientDomain: "app.example.com" });
 
@@ -110,9 +127,7 @@ describe("SEP-10 failure paths", () => {
   });
 
   it("wraps a transport failure", async () => {
-    const client = new Sep10Client("https://a.example.com/auth", {
-      transport: failingTransport("ECONNRESET"),
-    });
+    const client = sep10ClientWith({ transport: failingTransport("ECONNRESET") });
 
     await expect(client.challenge({ account: "GABC" })).rejects.toThrow(/request to .* failed/);
   });
@@ -199,10 +214,7 @@ describe("request timeouts", () => {
   });
 
   it("aborts a stalled SEP-10 challenge", async () => {
-    const client = new Sep10Client("https://a.example.com/auth", {
-      transport: stallingTransport(),
-      timeoutMs: 5,
-    });
+    const client = sep10ClientWith({ transport: stallingTransport(), timeoutMs: 5 });
     await expect(client.challenge({ account: "GABC" })).rejects.toThrow(/request to .* failed/);
   });