Release v0.16.1

Origin-SHA: 3c0bffc9cbe8efa5f105e702ac2ed8198fc7c337

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

Author: CodySearsOS

AGENTS.md

@@ -33,6 +33,7 @@ pnpm run type-check  # TypeScript type checking
 | `src/lib/middleware/` | Gating middleware (predicate gate, x402, x402 facilitators, well-known endpoint) |
 | `src/lib/wallet/` | Re-exports from `@opensea/wallet-adapters` (adapters, types, and viem bridge) |
 | `src/lib/client/` | Authenticated HTTP clients: EIP-3009 auth, x402 payment, external signer, paid authenticated fetch |
+| `src/lib/usage/` | Usage reporters — report tool invocations / x402 settlements to the OpenSea usage endpoint, plus EIP-3009 zero-value auth helpers |
 | `src/lib/adapters/` | Framework adapters (Vercel, Cloudflare, Express) |
 | `src/lib/utils.ts` | Shared utilities used across `lib/` |
 | `src/templates/` | Scaffolding templates for `init` command |

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/tool-sdk
 
+## 0.16.1
+
+### Patch Changes
+
+- 8812960: Require `validBefore` in predicate-gate authorizations. `verifyXPaymentAuth` previously left `validBefore` optional: a caller could sign a `TransferWithAuthorization` with `validBefore=0` and omit the field, so the expiry check was skipped and the gate accepted an unbounded, non-expiring proof. The field is now required in both the X-Payment and EIP-3009 auth paths, with the now-dead `validBefore !== undefined` guards and the `?? "0"` recovery fallback removed. Thanks @Nexory (ProjectOpenSea/tool-sdk#10).
+
 ## 0.16.0
 
 ### Minor Changes

package.json

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

src/__tests__/predicate-gate.test.ts

@@ -496,6 +496,39 @@ describe("predicateGate", () => {
     expect(body.error).toMatch(/missing required fields/i)
   })
 
+  it("EIP-3009: returns 401 when validBefore is missing", async () => {
+    const { predicateGate } = await import(
+      "../lib/middleware/predicate-gate.js"
+    )
+    const gate = predicateGate({ toolId: TEST_TOOL_ID })
+    const ctx: Partial<ToolContext> = { gates: {} }
+
+    // Omitting validBefore must be rejected at the required-field guard with a
+    // clear error, matching the X-Payment path. Without the guard the request
+    // is only incidentally rejected (BigInt(undefined) throws during recovery,
+    // surfacing as "invalid signature"); a future `?? "0"` fallback would let
+    // an unbounded proof through, so the field must be explicitly required.
+    const token = makeEip3009Token()
+    const payload = JSON.parse(
+      atob(token.replace(/-/g, "+").replace(/_/g, "/")),
+    )
+    delete payload.validBefore
+    const badToken = btoa(JSON.stringify(payload))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=/g, "")
+    const request = new Request("https://example.com/api", {
+      method: "POST",
+      headers: { Authorization: `EIP-3009 ${badToken}` },
+    })
+
+    const response = await gate.check(request, ctx)
+
+    expect(response?.status).toBe(401)
+    const body = await response?.json()
+    expect(body.error).toMatch(/missing required fields/i)
+  })
+
   it("EIP-3009: returns 401 when value !== '0'", async () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"
@@ -683,6 +716,54 @@ describe("predicateGate", () => {
     })
   })
 
+  it("X-Payment: rejects an authorization that omits validBefore", async () => {
+    const { predicateGate } = await import(
+      "../lib/middleware/predicate-gate.js"
+    )
+    const operator =
+      "0x5ECA0441311643608a8c9Ab8B250f695Dd32E2a8" as `0x${string}`
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: operator,
+    })
+    const ctx: Partial<ToolContext> = { gates: {} }
+
+    // Authorization with NO validBefore. The signer (recovery mock -> TEST_CALLER)
+    // matches `from`, so the expiry check is the only bound on this token. When
+    // validBefore is absent that check is skipped, so an unbounded (non-expiring)
+    // proof is accepted. The sibling EIP-3009 path (verifyEip3009Auth) requires
+    // validBefore, so the two auth paths must agree: reject when it is missing.
+    const header = Buffer.from(
+      JSON.stringify({
+        x402Version: 1,
+        scheme: "exact",
+        network: "base",
+        payload: {
+          signature: "0xabcd",
+          authorization: {
+            from: TEST_CALLER,
+            to: operator,
+            value: "0",
+            validAfter: "0",
+            // validBefore intentionally omitted
+            nonce:
+              "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+          },
+        },
+      }),
+    ).toString("base64")
+    const request = new Request("https://example.com/api", {
+      method: "POST",
+      headers: { "X-Payment": header },
+    })
+
+    const response = await gate.check(request, ctx)
+
+    expect(response?.status).toBe(401)
+    const body = await response?.json()
+    expect(body.error).toMatch(/missing required authorization fields/i)
+  })
+
   it("X-Payment: takes precedence over Authorization header", async () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"

src/lib/middleware/predicate-gate.ts

@@ -378,11 +378,12 @@ async function verifyEip3009Auth(
     !authorization.from ||
     !authorization.to ||
     !authorization.signature ||
-    !authorization.nonce
+    !authorization.nonce ||
+    !authorization.validBefore
   ) {
     return {
       error:
-        "Predicate gate: EIP-3009 token missing required fields (from, to, signature, nonce)",
+        "Predicate gate: EIP-3009 token missing required fields (from, to, signature, nonce, validBefore)",
       status: 401,
     }
   }
@@ -406,8 +407,8 @@ async function verifyEip3009Auth(
     }
   }
 
-  // Check expiry (validBefore)
-  if (authorization.validBefore !== undefined) {
+  // Check expiry (validBefore is required above, so it is always present here)
+  {
     const validBefore = BigInt(authorization.validBefore)
     const nowSec = BigInt(Math.floor(Date.now() / 1000))
     if (nowSec >= validBefore) {
@@ -522,7 +523,7 @@ async function verifyXPaymentAuth(
   const auth = paymentPayload.payload?.authorization
   const signature = paymentPayload.payload?.signature
 
-  if (!auth?.from || !auth?.to || !signature || !auth?.nonce) {
+  if (!auth?.from || !auth?.to || !signature || !auth?.nonce || !auth?.validBefore) {
     return {
       error:
         "Predicate gate: X-Payment missing required authorization fields",
@@ -557,7 +558,8 @@ async function verifyXPaymentAuth(
     }
   }
 
-  if (auth.validBefore !== undefined) {
+  // validBefore is required above, so it is always present here
+  {
     const validBefore = BigInt(auth.validBefore)
     const nowSec = BigInt(Math.floor(Date.now() / 1000))
     if (nowSec >= validBefore) {
@@ -595,7 +597,7 @@ async function verifyXPaymentAuth(
         to: auth.to as `0x${string}`,
         value: BigInt(auth.value ?? "0"),
         validAfter: BigInt(auth.validAfter ?? "0"),
-        validBefore: BigInt(auth.validBefore ?? "0"),
+        validBefore: BigInt(auth.validBefore),
         nonce: auth.nonce as `0x${string}`,
       },
       signature: signature as `0x${string}`,