Release v0.28.1

Origin-SHA: ea733537b6c6689c63269bf5b2482be6e3a49dc0

Co-authored-by: Ryan Ghods <ryan@ryanio.com>

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,14 @@
 # @opensea/tool-sdk
 
+## 0.28.1
+
+### Patch Changes
+
+- c93fece: `eip3009AuthenticatedFetch` now validates the 402 challenge's `asset` and `network` before signing: the network must be supported and the asset must be the canonical USDC contract for that network. Previously a zero-value challenge could name an arbitrary verifying contract/EIP-712 domain and the SDK would still sign it, creating a signature-phishing surface for contracts that assign different semantics to a zero-value `TransferWithAuthorization`. Thanks to @Nexory for raising this x402-signing hardening (tool-sdk#11).
+- 6d0baa7: `eip3009AuthenticatedFetch` now enforces the documented zero-value guarantee: it only signs `X-Payment` authorizations with `value: 0`, and returns non-zero (or unparseable-amount) 402 challenges as-is instead of signing an authorization that could move USDC to the server's advertised `payTo`.
+- adc561d: Deduplicate CLI command boilerplate: extract a shared `WALLET_PROVIDER_OPTION_DESCRIPTION` constant and a `parseToolId()` helper (both in `cli/commands/shared.ts`), replacing the repeated `Wallet provider: …` `--wallet-provider` help text (10 commands) and the copy-pasted `try/catch` tool-id parsing blocks (10 commands). No behavior change — same option text, same error messages, same exit codes.
+- 6096c0d: Deduplicate predicate-client boilerplate in `lib/onchain/predicate-clients.ts`: extract a shared `openSeaAssetLinks(collection)` helper on `BasePredicateClient` (replacing the copy-pasted segment/normalized/`links` construction in 4 `toManifestAccess()` methods), and add typed `read()`/`write()` helpers on the base class (holding the ABI as a generic `const TAbi extends Abi`) so subclasses no longer repeat the `publicClient.readContract`/`requireWalletClient()` + `walletClient.writeContract` wiring. viem's per-function argument/return typing is preserved. No behavior change.
+
 ## 0.28.0
 
 ### Minor Changes

biome.json

@@ -12,6 +12,9 @@
       "**/*.json",
       "!**/.claude",
       "!**/typechain",
+      "!**/dist",
+      "!**/coverage",
+      "!**/.vercel",
       "!**/package-lock.json",
       "!**/src/generated.ts",
       "!**/src/*-generated.ts"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {

src/__tests__/eip3009-auth.test.ts

@@ -221,6 +221,121 @@ describe("eip3009AuthenticatedFetch", () => {
     expect(secondHeaders.get("X-Payment")).toBeTruthy()
   })
 
+  it("signed X-Payment always authorizes value 0", async () => {
+    let callCount = 0
+    const capturedInits: RequestInit[] = []
+    const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
+      capturedInits.push(init ?? {})
+      callCount++
+      if (callCount === 1) {
+        return new Response(
+          JSON.stringify({
+            x402Version: 1,
+            accepts: [
+              {
+                scheme: "exact",
+                network: "base",
+                maxAmountRequired: "0",
+                payTo: OPERATOR,
+                asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                extra: { name: "USD Coin", version: "2" },
+              },
+            ],
+          }),
+          { status: 402 },
+        )
+      }
+      return new Response(JSON.stringify({ ok: true }), { status: 200 })
+    })
+    vi.stubGlobal("fetch", fetchMock)
+
+    const { eip3009AuthenticatedFetch } = await import(
+      "../lib/client/eip3009-auth.js"
+    )
+
+    await eip3009AuthenticatedFetch("https://tool.example.com/api", {
+      account,
+      method: "POST",
+      body: "{}",
+    })
+
+    const xPayment = new Headers(capturedInits[1].headers).get("X-Payment")
+    const decoded = JSON.parse(
+      Buffer.from(xPayment as string, "base64").toString("utf-8"),
+    ) as { payload: { authorization: { value: string } } }
+    expect(decoded.payload.authorization.value).toBe("0")
+  })
+
+  it("returns the 402 as-is without signing when the challenge requests a non-zero amount", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            x402Version: 1,
+            accepts: [
+              {
+                scheme: "exact",
+                network: "base",
+                maxAmountRequired: "1000000",
+                payTo: OPERATOR,
+                asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                extra: { name: "USD Coin", version: "2" },
+              },
+            ],
+          }),
+          { status: 402 },
+        ),
+    )
+    vi.stubGlobal("fetch", fetchMock)
+
+    const { eip3009AuthenticatedFetch } = await import(
+      "../lib/client/eip3009-auth.js"
+    )
+
+    const res = await eip3009AuthenticatedFetch(
+      "https://tool.example.com/api",
+      { account, method: "POST", body: "{}" },
+    )
+
+    expect(res.status).toBe(402)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it("returns the 402 as-is when the challenge amount is unparseable", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            x402Version: 1,
+            accepts: [
+              {
+                scheme: "exact",
+                network: "base",
+                maxAmountRequired: "not-a-number",
+                payTo: OPERATOR,
+                asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                extra: { name: "USD Coin", version: "2" },
+              },
+            ],
+          }),
+          { status: 402 },
+        ),
+    )
+    vi.stubGlobal("fetch", fetchMock)
+
+    const { eip3009AuthenticatedFetch } = await import(
+      "../lib/client/eip3009-auth.js"
+    )
+
+    const res = await eip3009AuthenticatedFetch(
+      "https://tool.example.com/api",
+      { account, method: "POST", body: "{}" },
+    )
+
+    expect(res.status).toBe(402)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
   it("throws when payTo is not in allowedRecipients", async () => {
     const fetchMock = vi.fn(
       async () =>
@@ -257,6 +372,115 @@ describe("eip3009AuthenticatedFetch", () => {
     ).rejects.toThrow(/not in allowedRecipients/)
   })
 
+  it("throws when payTo is not in allowedRecipients even for a non-zero challenge", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            x402Version: 1,
+            accepts: [
+              {
+                scheme: "exact",
+                network: "base",
+                maxAmountRequired: "1000000",
+                payTo: "0xDeAdBeEfDeAdBeEfDeAdBeEfDeAdBeEfDeAdBeEf",
+                asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                extra: { name: "USD Coin", version: "2" },
+              },
+            ],
+          }),
+          { status: 402 },
+        ),
+    )
+    vi.stubGlobal("fetch", fetchMock)
+
+    const { eip3009AuthenticatedFetch } = await import(
+      "../lib/client/eip3009-auth.js"
+    )
+
+    await expect(
+      eip3009AuthenticatedFetch("https://tool.example.com/api", {
+        account,
+        method: "POST",
+        body: "{}",
+        allowedRecipients: [OPERATOR],
+      }),
+    ).rejects.toThrow(/not in allowedRecipients/)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it("throws without signing when the zero-value challenge asset is not canonical USDC", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            x402Version: 1,
+            accepts: [
+              {
+                scheme: "exact",
+                network: "base",
+                maxAmountRequired: "0",
+                payTo: OPERATOR,
+                asset: "0x1111111111111111111111111111111111111111",
+                extra: { name: "Evil Contract", version: "1" },
+              },
+            ],
+          }),
+          { status: 402 },
+        ),
+    )
+    vi.stubGlobal("fetch", fetchMock)
+
+    const { eip3009AuthenticatedFetch } = await import(
+      "../lib/client/eip3009-auth.js"
+    )
+
+    await expect(
+      eip3009AuthenticatedFetch("https://tool.example.com/api", {
+        account,
+        method: "POST",
+        body: "{}",
+      }),
+    ).rejects.toThrow(/does not match expected USDC address/)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it("throws without signing when the challenge network is unsupported", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            x402Version: 1,
+            accepts: [
+              {
+                scheme: "exact",
+                network: "eip155:1",
+                maxAmountRequired: "0",
+                payTo: OPERATOR,
+                asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                extra: { name: "USD Coin", version: "2" },
+              },
+            ],
+          }),
+          { status: 402 },
+        ),
+    )
+    vi.stubGlobal("fetch", fetchMock)
+
+    const { eip3009AuthenticatedFetch } = await import(
+      "../lib/client/eip3009-auth.js"
+    )
+
+    await expect(
+      eip3009AuthenticatedFetch("https://tool.example.com/api", {
+        account,
+        method: "POST",
+        body: "{}",
+      }),
+    ).rejects.toThrow(/network eip155:1 is not supported/)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
   it("returns 402 as-is when no accepts in challenge body", async () => {
     const fetchMock = vi.fn(
       async () =>

src/cli/commands/auth.ts

@@ -13,11 +13,11 @@ import {
 import {
   createWalletForProvider,
   createWalletFromEnv,
-  WALLET_PROVIDERS,
   type WalletAdapter,
   type WalletProvider,
 } from "../../lib/wallet/index.js"
 import { readInput } from "./read-input.js"
+import { WALLET_PROVIDER_OPTION_DESCRIPTION } from "./shared.js"
 
 interface AuthOptions {
   body?: string
@@ -32,10 +32,7 @@ export const authCommand = new Command("auth")
   )
   .argument("<url>", "Tool endpoint URL")
   .option("--body <json>", "JSON body (inline string or @path/to/file.json)")
-  .option(
-    "--wallet-provider <provider>",
-    `Wallet provider: ${WALLET_PROVIDERS.join(", ")}`,
-  )
+  .option("--wallet-provider <provider>", WALLET_PROVIDER_OPTION_DESCRIPTION)
   .option(
     "--bankr-key <api-key>",
     "Bankr API key for agent wallet signing (defaults to BANKR_API_KEY env var)",

src/cli/commands/configure-erc20-gate.ts

@@ -9,11 +9,11 @@ import { ERC20BalancePredicateClient } from "../../lib/onchain/predicate-clients
 import {
   createWalletForProvider,
   createWalletFromEnv,
-  WALLET_PROVIDERS,
   type WalletProvider,
   walletAdapterToClient,
 } from "../../lib/wallet/index.js"
 import { getChain, NETWORK_OPTION_DESCRIPTION } from "./get-chain.js"
+import { parseToolId, WALLET_PROVIDER_OPTION_DESCRIPTION } from "./shared.js"
 
 interface ConfigureERC20GateOptions {
   network: string
@@ -38,10 +38,7 @@ export const configureERC20GateCommand = new Command("configure-erc20-gate")
     "Override the canonical ERC20BalancePredicate address",
   )
   .option("--network <network>", NETWORK_OPTION_DESCRIPTION, "base")
-  .option(
-    "--wallet-provider <provider>",
-    `Wallet provider: ${WALLET_PROVIDERS.join(", ")}`,
-  )
+  .option("--wallet-provider <provider>", WALLET_PROVIDER_OPTION_DESCRIPTION)
   .option("--rpc-url <url>", "RPC endpoint")
   .option("--dry-run", "Print summary without transacting")
   .action(
@@ -51,14 +48,7 @@ export const configureERC20GateCommand = new Command("configure-erc20-gate")
       minBalanceRaw: string,
       options: ConfigureERC20GateOptions,
     ) => {
-      let toolId: bigint
-      try {
-        toolId = BigInt(toolIdRaw)
-      } catch {
-        console.error(pc.red("Error: toolId must be a valid integer"))
-        process.exit(1)
-        return
-      }
+      const toolId = parseToolId(toolIdRaw)
 
       const chain = getChain(options.network)
 

src/cli/commands/configure-subscription.ts

@@ -9,11 +9,11 @@ import { SubscriptionPredicateClient } from "../../lib/onchain/predicate-clients
 import {
   createWalletForProvider,
   createWalletFromEnv,
-  WALLET_PROVIDERS,
   type WalletProvider,
   walletAdapterToClient,
 } from "../../lib/wallet/index.js"
 import { getChain, NETWORK_OPTION_DESCRIPTION } from "./get-chain.js"
+import { parseToolId, WALLET_PROVIDER_OPTION_DESCRIPTION } from "./shared.js"
 
 interface ConfigureSubscriptionOptions {
   network: string
@@ -33,10 +33,7 @@ export const configureSubscriptionCommand = new Command(
   .argument("<collection>", "Subscription NFT collection address")
   .option("--min-tier <tier>", "Minimum subscription tier (uint8, 0-255)", "0")
   .option("--network <network>", NETWORK_OPTION_DESCRIPTION, "base")
-  .option(
-    "--wallet-provider <provider>",
-    `Wallet provider: ${WALLET_PROVIDERS.join(", ")}`,
-  )
+  .option("--wallet-provider <provider>", WALLET_PROVIDER_OPTION_DESCRIPTION)
   .option("--rpc-url <url>", "RPC endpoint")
   .option("--dry-run", "Print summary without transacting")
   .action(
@@ -45,14 +42,7 @@ export const configureSubscriptionCommand = new Command(
       collectionRaw: string,
       options: ConfigureSubscriptionOptions,
     ) => {
-      let toolId: bigint
-      try {
-        toolId = BigInt(toolIdRaw)
-      } catch {
-        console.error(pc.red("Error: toolId must be a valid integer"))
-        process.exit(1)
-        return
-      }
+      const toolId = parseToolId(toolIdRaw)
 
       const chain = getChain(options.network)