Release v0.28.2

Origin-SHA: 2d6d9bbf55d90c197f0b5a12033298ce555a5fdd

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,25 @@
 # @opensea/tool-sdk
 
+## 0.28.2
+
+### Patch Changes
+
+- 1c2df8f: Fix four lower-severity tool-sdk audit findings:
+
+  - Pin EIP-712 domain name/version to canonical USDC for canonical assets.
+  - Document and surface the default 10,000-block registry lookup window.
+  - Cache resolved manifests in `createToolHandler` after the first success.
+  - Decouple shared caller API-key provisioning from each request's abort signal.
+
+- 8e1b0dc: Validate `metadataURI` before fetching in `inspect` (SSRF): require http(s) and reject private/internal hosts. Harden the shared `isPrivateHostname` guard to numerically parse IP literals, closing alternate-encoding bypasses (decimal/octal/hex/partial dotted IPv4 and IPv4-mapped/compatible IPv6), and broaden the rejected ranges (0.0.0.0/8, 169.254.0.0/16 link-local, CGNAT 100.64.0.0/10, IPv6 unique-local fc00::/7). Thanks to @Nexory for reporting this SSRF (tool-sdk#12).
+- 83b406a: Security fix: `paidAuthenticatedFetch` now enforces `maxAmount` as a per-invocation spending cap. At most one nonzero payment authorization may be signed per call — a second 402 after a paid authorization is rejected instead of signed — and cumulative authorized value may never exceed `maxAmount`. Previously a malicious tool could return two paid x402 challenges, each individually under `maxAmount`, and obtain two independently-settleable EIP-3009 authorizations (up to 2x the configured cap). The legacy zero-value predicate-gate → paid challenge flow keeps working.
+- c7907d4: Security fix: harden `verifyXPaymentAuth` (used by `predicateGate` and `paidPredicateGate`) against replay/misuse of the EIP-3009 X-Payment identity proof:
+
+  - The free identity-only `predicateGate` now rejects (401) any X-Payment authorization with a non-zero `value` — a non-zero `TransferWithAuthorization` is a live, executable USDC pull the operator should never receive on a free gate. `paidPredicateGate` still accepts non-zero values (the facilitator settles them).
+  - `validBefore` is now capped to at most 1 hour (3600s) in the future (401 otherwise), so a captured X-Payment header can't act as a long-lived bearer token. Well-behaved clients sign now+300s/now+600s, so this is non-breaking.
+  - The authorization's resolved chainId is now pinned to the gate's configured chain (401 on mismatch), so e.g. a base-sepolia-signed authorization can't authenticate to a mainnet gate.
+  - The `to` (operator recipient) check is now unconditional and fails closed (500) when no operator address is configured, closing an unauthenticated-recipient hole.
+
 ## 0.28.1
 
 ### Patch Changes

README.md

@@ -601,9 +601,12 @@ they need to satisfy.
 
 Preferred auth mechanism: `X-Payment` header (zero-value EIP-3009 `TransferWithAuthorization` via the 402 challenge flow). Also accepts `Authorization: EIP-3009 <base64url(json)>` and deprecated `SIWE <base64url(message)>.<signature>` for backward compatibility.
 
-> **Note:** The gate enforces a short-lived `validBefore` window (the SDK
-> defaults to 5 minutes). Each authorization includes a random nonce bound
-> into the signature. The gate does not track nonces server-side.
+> **Note:** The gate bounds the `validBefore` window server-side: the
+> authorization must not be expired and must be at most 1 hour in the future
+> (SDK clients sign a much shorter window — 5 min zero-value / 10 min paid).
+> Each authorization includes a random nonce bound into the signature, but the
+> gate does **not** deduplicate nonces server-side, so an `X-Payment` header is
+> replayable within its validity window. See [Replay protection](#replay-protection) if you need single-use semantics.
 
 #### Delegated agent access (delegate.xyz)
 
@@ -1027,11 +1030,17 @@ Recommended approaches by platform:
 
 You can also implement a custom `GateMiddleware` that performs rate-limit checks in the `check()` hook and returns a 429 response when limits are exceeded.
 
+### Replay protection
+
+The `X-Payment` identity proof is a stateless bearer token: `predicateGate` verifies the EIP-3009 signature and fields but does **not** record which authorizations it has already accepted. The SDK bounds the replay window server-side — an authorization must not be expired and must be at most 1 hour in the future — but a captured header remains replayable until its `validBefore`. On the paid path this is limited further because the facilitator settling the onchain `TransferWithAuthorization` consumes the nonce, so a real payment can't be double-settled; the residual surface is identity/access on the free gate (the onchain predicate still gates who is allowed).
+
+The SDK deliberately does not ship server-side nonce tracking — single-use semantics require a shared, TTL'd store, and mandating one (e.g. Redis) would tie tool creators to a specific data store and break serverless/multi-instance deployments. If your tool needs stronger-than-window replay protection, implement it yourself in a custom `GateMiddleware`: on each request, read the authorization's `nonce` (bytes32), reject (401) if it is already present in your store, otherwise record it with a TTL equal to your `validBefore` window. Use whatever store fits your deployment (Cloudflare Durable Objects / KV, Upstash Redis on Vercel, DynamoDB, etc.).
+
 ### Sensitive Data Handling
 
 - **Private keys** are never handled directly by the SDK runtime. They flow through `@opensea/wallet-adapters`, which supports Privy, Turnkey, Fireblocks, and local key signing. The SDK accepts a `WalletAdapter` interface — it never reads or stores raw key material.
 - **Environment variables** — the `deploy` command detects sensitive env vars (names ending in `_KEY`, `_SECRET`, `_TOKEN`, `_PASSWORD`, `_PRIVATE`) and masks their values during interactive prompts.
-- **EIP-3009 auth** — the `predicateGate` middleware verifies EIP-3009 zero-value authorizations via `ecrecover` (no RPC call needed). The SDK defaults to a 5-minute `validBefore` window to limit replay.
+- **EIP-3009 auth** — the `predicateGate` middleware verifies EIP-3009 zero-value authorizations via `ecrecover` (no RPC call needed). It rejects a non-zero `value` on the free identity gate, pins the authorization to the gate's configured chain, and caps `validBefore` to at most 1 hour ahead to limit replay. See [Replay protection](#replay-protection) for nonce-dedupe guidance.
 - **x402 payments** — the `paidFetch` client validates payment parameters before signing: `maxAmount` caps the spend, `allowedRecipients` restricts payees, and `allowedAssets` defaults to the canonical USDC contract for the network. These guard against malicious 402 responses.
 
 ## Tips

docs/predicate-gating-guide.md

@@ -86,7 +86,7 @@ The middleware (`src/lib/middleware/predicate-gate.ts`) does the following on ea
 1. Checks for an `X-Payment` header (preferred) or `Authorization: EIP-3009 <token>` header (also accepts deprecated `Authorization: SIWE <token>` for backward compatibility)
 2. If no auth is present and `operatorAddress` is configured, returns 402 with `PaymentRequirements` (`payTo`=operator, `maxAmountRequired`=`"0"`, `scheme`=`"exact"`)
 3. Decodes and validates the authorization (from `X-Payment` or `Authorization` header)
-4. Checks `validBefore` (must be in the future) and `validAfter` (must be in the past)
+4. Checks `validBefore` (must be in the future, and at most 1 hour ahead) and `validAfter` (must be in the past)
 5. Recovers the signer via `ecrecover` on the EIP-712 typed data — no RPC call needed
 6. Calls `registry.tryHasAccess(toolId, recoveredAddress, data)` — a staticcall to the onchain `ToolRegistry`
 7. If `(ok=true, granted=true)`, sets `ctx.callerAddress` and `ctx.gates.predicate.granted = true`
@@ -104,7 +104,7 @@ Status code mapping:
 
 The `predicate` field in the 403 body is the registered access predicate's address, so callers can self-diagnose what they need to satisfy.
 
-The gate enforces a short-lived `validBefore` window (the SDK defaults to 5 minutes). Each EIP-3009 authorization includes a random `nonce` bound into the signature — the gate does not track nonces server-side, so callers should keep `validBefore` short to limit the replay window.
+The gate bounds the `validBefore` window server-side: the authorization must not be expired and must be at most 1 hour in the future (SDK clients sign a much shorter window — 5 min zero-value / 10 min paid). Each EIP-3009 authorization includes a random `nonce` bound into the signature, but the gate does **not** deduplicate nonces server-side, so the `X-Payment` header stays replayable within its validity window. The SDK does not mandate a nonce store (that would tie creators to a specific data store and break serverless deployments); if you need single-use semantics, dedupe the `nonce` in a custom `GateMiddleware` backed by whatever store fits your deployment. See the "Replay protection" section of the [tool-sdk README](../README.md#replay-protection).
 
 ## Step 2: Register with `--access-predicate`
 
@@ -176,11 +176,12 @@ The `X-Payment` header carries a base64-encoded JSON payload containing an EIP-3
 
 Key constraints enforced by the middleware:
 
-- **`validBefore`** must be in the future (the SDK defaults to `now + 5 minutes`)
+- **`validBefore`** must be in the future and at most 1 hour ahead (SDK clients default to `now + 5 minutes`)
 - **`validAfter`** must be in the past (typically `0`)
-- **`value`** must be `"0"` (zero-value transfer — used for identity proof, not payment)
+- **`value`** must be exactly the string `"0"` (zero-value transfer — used for identity proof, not payment; the free `predicateGate` rejects any non-`"0"` value, so third-party clients must emit the canonical `"0"`, not e.g. `"0x0"` or `"00"`)
 - **`from`** is recovered via `ecrecover` and used as the caller address
 - **`to`** must match the gate's `operatorAddress` (the 402 challenge advertises this as `payTo`)
+- the authorization's resolved **chainId** (from its declared `network`) must match the gate's configured chain
 
 ### Example client code (SDK)
 

package.json

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

src/__tests__/caller-reporter.test.ts

@@ -308,6 +308,86 @@ describe("reportCallerX402Usage", () => {
     expect(reportOpts.headers["x-api-key"]).toBe("auto-key")
   })
 
+  it("does not abort shared API-key provisioning when one caller times out", async () => {
+    vi.useFakeTimers()
+    try {
+      const abortError = () => {
+        const err = new Error("aborted")
+        err.name = "AbortError"
+        return err
+      }
+
+      let resolveProvision = (_response: Response) => {}
+      fetchSpy.mockImplementation((input, init) => {
+        const url = String(input)
+        const signal = init?.signal as AbortSignal | undefined
+
+        if (url.endsWith("/api/v2/auth/keys")) {
+          return new Promise<Response>((resolve, reject) => {
+            if (signal?.aborted) {
+              reject(abortError())
+              return
+            }
+            const onAbort = () => reject(abortError())
+            signal?.addEventListener("abort", onAbort, { once: true })
+            resolveProvision = response => {
+              signal?.removeEventListener("abort", onAbort)
+              resolve(response)
+            }
+          })
+        }
+
+        if (signal?.aborted) {
+          return Promise.reject(abortError())
+        }
+
+        return new Promise<Response>((resolve, reject) => {
+          queueMicrotask(() => {
+            if (signal?.aborted) {
+              reject(abortError())
+              return
+            }
+            resolve(
+              new Response(JSON.stringify({ verified: true }), {
+                status: 200,
+              }),
+            )
+          })
+        })
+      })
+
+      const origin = "https://shared-provision.example"
+      const first = reportCallerX402Usage(
+        makeX402Event({ toolEndpoint: "https://tool.example/api" }),
+        makeConfig({
+          aggregatorUrl: `${origin}/api/v2/tools/usage`,
+          timeoutMs: 1,
+        }),
+      )
+      const second = reportCallerX402Usage(
+        makeX402Event({ toolEndpoint: "https://tool.example/api" }),
+        makeConfig({
+          aggregatorUrl: `${origin}/api/v2/tools/usage`,
+          timeoutMs: 1_000,
+        }),
+      )
+
+      await vi.advanceTimersByTimeAsync(1)
+      resolveProvision(
+        new Response(JSON.stringify({ api_key: "shared-key" }), {
+          status: 200,
+        }),
+      )
+
+      const [, secondResult] = await Promise.all([first, second])
+
+      expect(secondResult.outcome).toBe("reported")
+      expect(fetchSpy).toHaveBeenCalledTimes(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it("skips report when auto-provisioning fails", async () => {
     fetchSpy.mockResolvedValueOnce(new Response("error", { status: 500 }))
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})

src/__tests__/handler.test.ts

@@ -39,6 +39,27 @@ function makeHandler(gates?: GateMiddleware[]) {
   })
 }
 
+function makeDynamicManifest(options: {
+  callCount: { value: number }
+  failFirst?: boolean
+}): ManifestDefinition {
+  return {
+    type: "https://ercs.ethereum.org/ERCS/erc-8257#tool-manifest-v1",
+    name: "dynamic-tool",
+    description: "A tool with dynamic manifest fields",
+    endpoint: env => {
+      options.callCount.value++
+      if (options.failFirst && options.callCount.value === 1) {
+        throw new Error("manifest resolution failed")
+      }
+      return env.TOOL_ENDPOINT ?? "https://dynamic.example.com"
+    },
+    inputs: {},
+    outputs: {},
+    creatorAddress: "0xabcdefabcdef1234567890abcdefabcdef123456",
+  }
+}
+
 describe("createToolHandler", () => {
   it("should return 405 for non-POST", async () => {
     const handler = makeHandler()
@@ -92,6 +113,60 @@ describe("createToolHandler", () => {
     expect(body.result).toBe("Echo: hello")
   })
 
+  it("should cache a resolved manifest after the first successful request", async () => {
+    const callCount = { value: 0 }
+    const handler = createToolHandler({
+      manifest: makeDynamicManifest({ callCount }),
+      inputSchema: InputSchema,
+      outputSchema: OutputSchema,
+      handler: async input => ({
+        result: `Echo: ${input.query}`,
+      }),
+    })
+    const makeRequest = () =>
+      new Request("https://test.example.com/api", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ query: "hello" }),
+      })
+
+    const first = await handler(makeRequest())
+    const second = await handler(makeRequest())
+
+    expect(first.status).toBe(200)
+    expect(second.status).toBe(200)
+    expect(callCount.value).toBe(1)
+  })
+
+  it("should retry manifest resolution after a failure", async () => {
+    const callCount = { value: 0 }
+    const handler = createToolHandler({
+      manifest: makeDynamicManifest({ callCount, failFirst: true }),
+      inputSchema: InputSchema,
+      outputSchema: OutputSchema,
+      handler: async input => ({
+        result: `Echo: ${input.query}`,
+      }),
+    })
+    const makeRequest = () =>
+      new Request("https://test.example.com/api", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ query: "hello" }),
+      })
+
+    const first = await handler(makeRequest())
+    const second = await handler(makeRequest())
+
+    expect(first.status).toBe(500)
+    expect(second.status).toBe(200)
+    expect(callCount.value).toBe(2)
+  })
+
   it("should run gates in order and short-circuit on response", async () => {
     const order: string[] = []
     const gate1: GateMiddleware = {

src/__tests__/inspect.test.ts

@@ -148,6 +148,48 @@ describe("inspect command", () => {
     errorSpy.mockRestore()
   })
 
+  it("refuses to fetch a metadata URI that points to a private address", async () => {
+    // metadataURI is read from the permissionlessly-writable onchain registry.
+    // A hostile entry pointing at the cloud-metadata endpoint must never be
+    // fetched from the machine/CI runner that runs `inspect`.
+    mockGetToolConfig.mockResolvedValueOnce({
+      creator: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+      metadataURI:
+        "http://169.254.169.254/latest/meta-data/iam/security-credentials/",
+      manifestHash: MANIFEST_HASH,
+      accessPredicate: "0x0000000000000000000000000000000000000000",
+    })
+
+    const fetchMock = vi.fn(
+      async () => new Response(JSON.stringify(VALID_MANIFEST), { status: 200 }),
+    )
+    vi.stubGlobal("fetch", fetchMock)
+
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit called")
+    }) as never)
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+    const { inspectCommand } = await import("../cli/commands/inspect.js")
+
+    try {
+      await inspectCommand.parseAsync(["node", "inspect", "--tool-id", "1"])
+    } catch {
+      // expected process.exit
+    }
+
+    // The link-local metadata address must never be fetched.
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(exitSpy).toHaveBeenCalledWith(1)
+    const errorOutput = errorSpy.mock.calls.map(c => c[0]).join("\n")
+    expect(errorOutput).toContain("private/internal address")
+
+    exitSpy.mockRestore()
+    logSpy.mockRestore()
+    errorSpy.mockRestore()
+  })
+
   it("shows predicate name and ERC-721 collections for non-zero predicate", async () => {
     const predicateAddress = "0x1111111111111111111111111111111111111111"
     const collectionA = "0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

src/__tests__/list-tools-by-creator.test.ts

@@ -85,6 +85,7 @@ describe("listToolsByCreator", () => {
   it("defaults fromBlock to latestBlock - 10_000", async () => {
     mockGetBlockNumber.mockResolvedValue(50_000n)
     mockGetLogs.mockResolvedValue([])
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
 
     const { ToolRegistryClient } = await import("../lib/onchain/registry.js")
     const client = new ToolRegistryClient({ rpcUrl: "http://localhost:8545" })
@@ -97,6 +98,10 @@ describe("listToolsByCreator", () => {
         args: { creator },
       }),
     )
+    expect(warnSpy).toHaveBeenCalledWith(
+      "[tool-sdk] showing registrations from the last 10,000 blocks; pass fromBlock to search further back",
+    )
+    warnSpy.mockRestore()
   })
 
   it("uses explicit fromBlock and toBlock when provided", async () => {