Release v11.4.3

Origin-SHA: 3643ebdaab0e2e9139ac9f609e6f2b810e7c743d

Author: ryanio

AGENTS.md

@@ -53,6 +53,8 @@ When reviewing changes to this package, verify:
 
 5. **No secret leakage**: API keys are passed via `OpenSeaAPIConfig.apiKey`. Never log or expose them. Integration tests read keys from environment variables.
 
+6. **OAuth session contract**: `OpenSeaOAuth` requests `offline_access`, so successful code and device flows must return a refresh token. Refresh responses may omit rotation; retain the previous refresh token in that case. The top-level `wallet` JWT claim is the only wallet identity source. Never substitute `sub`, which is an account identifier.
+
 ## Conventions
 
 - CommonJS (`"type": "commonjs"`). The SDK is consumed by both CJS and ESM projects.

CHANGELOG.md

@@ -1,5 +1,17 @@
 # @opensea/sdk
 
+## 11.4.3
+
+### Patch Changes
+
+- b64a4d5: Require complete OAuth wallet sessions, retain refresh tokens during rotation, validate the CLI auth store, and preserve case-sensitive wallet addresses.
+
+## 11.4.2
+
+### Patch Changes
+
+- 5966017: Keep the default SDK test suite offline by blocking unmocked network requests and running live API and RPC checks through the integration suite.
+
 ## 11.4.1
 
 ### Patch Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "11.4.1",
+  "version": "11.4.3",
   "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs, tokens, and our marketplace data",
   "license": "MIT",
   "author": "OpenSea Developers",

src/auth/oauth-types.ts

@@ -23,8 +23,8 @@ export interface OpenSeaOAuthConfig {
 export interface OAuthToken {
   /** JWT access token (bearer credential for the OpenSea API). */
   accessToken: string
-  /** Refresh token for obtaining a new access token, if granted. */
-  refreshToken?: string
+  /** Refresh token for obtaining a new access token. */
+  refreshToken: string
   /** OIDC ID token, if `openid` scope was granted. */
   idToken?: string
   /** When the access token expires. */

src/auth/oauth.ts

@@ -151,7 +151,7 @@ export class OpenSeaOAuth {
       refresh_token: refreshToken,
       client_id: this.clientId,
     })
-    return toOAuthToken(response)
+    return toOAuthToken(response, refreshToken)
   }
 
   /** Revoke an access or refresh token. */
@@ -376,15 +376,22 @@ function tokenOpenSeaScopes(response: OAuthTokenResponse): string[] {
     : extractOpenSeaScopes(response.access_token)
 }
 
-function toOAuthToken(response: OAuthTokenResponse): OAuthToken {
+function toOAuthToken(
+  response: OAuthTokenResponse,
+  previousRefreshToken?: string,
+): OAuthToken {
   const expiresIn =
     typeof response.expires_in === "number" &&
     Number.isFinite(response.expires_in)
       ? response.expires_in
       : DEFAULT_EXPIRES_IN_SECONDS
+  const refreshToken = response.refresh_token || previousRefreshToken
+  if (!refreshToken) {
+    throw new Error("OAuth token response is missing a refresh token")
+  }
   return {
     accessToken: response.access_token,
-    refreshToken: response.refresh_token,
+    refreshToken,
     idToken: response.id_token,
     expiresAt: new Date(Date.now() + expiresIn * 1000),
     scopes: tokenOpenSeaScopes(response),
@@ -393,20 +400,17 @@ function toOAuthToken(response: OAuthTokenResponse): OAuthToken {
 
 /**
  * Read the wallet address from decoded JWT claims. Zitadel injects it as a
- * top-level `wallet` claim (plaintext) via the `inject_wallet_claim` action —
- * the same claim `opensea-mcp` and the os2-core REST API read. `sub` is the
- * fallback identifier (the Zitadel account id) when no wallet claim is present.
- * Returns `undefined` if neither is available.
+ * top-level `wallet` claim (plaintext) via the `inject_wallet_claim` action,
+ * the same claim `opensea-mcp` and the os2-core REST API read. The `sub` claim
+ * is an account identifier, not a wallet address, so it must never be used as
+ * a fallback. Returns `undefined` when the wallet claim is absent.
  */
 export function extractWalletAddress(
   claims: Record<string, unknown>,
 ): string | undefined {
   if (typeof claims.wallet === "string" && claims.wallet.length > 0) {
     return claims.wallet
   }
-  if (typeof claims.sub === "string" && claims.sub.length > 0) {
-    return claims.sub
-  }
   return undefined
 }
 

test/api/api.spec.ts

@@ -77,13 +77,26 @@ describe("API", () => {
   })
 
   test("Includes API key in request", async () => {
-    // Restore real timers for this test since it makes a real API call
     vi.useRealTimers()
+    fetchStub = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          address: getOfferPaymentToken(Chain.Mainnet),
+          decimals: 18,
+          eth_price: "1",
+          name: "Wrapped Ether",
+          symbol: "WETH",
+          usd_price: "1",
+        }),
+        { status: 200 },
+      ),
+    )
 
     const oldLogger = api.logger
 
     // The API key is now deliberately sanitized from log output.
     // Verify the request is logged with the expected app-id header.
+    const offerPaymentToken = getOfferPaymentToken(Chain.Mainnet)
     const logPromise = new Promise<void>((resolve, reject) => {
       api.logger = log => {
         try {
@@ -95,23 +108,23 @@ describe("API", () => {
           api.logger = oldLogger
         }
       }
-      const offerPaymentToken = getOfferPaymentToken(Chain.Mainnet)
-      api.getPaymentToken(offerPaymentToken)
     })
 
-    await logPromise
+    await Promise.all([logPromise, api.getPaymentToken(offerPaymentToken)])
   })
 
   test("API handles errors", async () => {
-    // Restore real timers for this test since it makes a real API call
     vi.useRealTimers()
+    fetchStub = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ errors: ["not found"] }), {
+        status: 404,
+        statusText: "Not Found",
+      }),
+    )
 
-    // 404 Not found for random token id
-    try {
-      await api.getNFT(BAYC_CONTRACT_ADDRESS, "404040")
-    } catch (error) {
-      expect((error as Error).message).toContain("not found")
-    }
+    await expect(api.getNFT(BAYC_CONTRACT_ADDRESS, "404040")).rejects.toThrow(
+      "not found",
+    )
   })
 
   test("API handles rate limit errors with retry-after", async () => {

test/auth/oauth.spec.ts

@@ -191,6 +191,28 @@ describe("OpenSeaOAuth", () => {
     ).rejects.toThrow(/Token request failed/)
   })
 
+  test("exchangeCode requires the refresh token requested by offline_access", async () => {
+    mockDiscovery(fetchMock)
+    fetchMock.mockImplementationOnce(() =>
+      Promise.resolve(
+        jsonResponse({
+          access_token: "at",
+          token_type: "Bearer",
+          expires_in: 3600,
+        }),
+      ),
+    )
+    const oauth = new OpenSeaOAuth({ clientId: CLIENT_ID, issuer: ISSUER })
+
+    await expect(
+      oauth.exchangeCode({
+        code: "the-code",
+        codeVerifier: "the-verifier",
+        redirectUri: "http://127.0.0.1:8151/callback",
+      }),
+    ).rejects.toThrow("missing a refresh token")
+  })
+
   test("reads OpenSea scopes from the access token when scope is omitted", async () => {
     mockDiscovery(fetchMock)
     fetchMock.mockImplementationOnce(() =>
@@ -225,6 +247,7 @@ describe("OpenSeaOAuth", () => {
           access_token: jwt({
             opensea_scopes: ["write:favorites", "read:favorites"],
           }),
+          refresh_token: "rt",
           token_type: "Bearer",
           expires_in: 3600,
         }),
@@ -247,6 +270,7 @@ describe("OpenSeaOAuth", () => {
       Promise.resolve(
         jsonResponse({
           access_token: "opaque-token",
+          refresh_token: "rt",
           token_type: "Bearer",
           expires_in: 3600,
           scope: "read:eligibility read:rewards unknown:scope",
@@ -276,6 +300,7 @@ describe("OpenSeaOAuth", () => {
       Promise.resolve(
         jsonResponse({
           access_token: accessToken,
+          refresh_token: "rt",
           token_type: "Bearer",
           expires_in: 3600,
         }),
@@ -310,9 +335,28 @@ describe("OpenSeaOAuth", () => {
     const oauth = new OpenSeaOAuth({ clientId: CLIENT_ID, issuer: ISSUER })
     const token = await oauth.refresh("old-rt")
     expect(token.accessToken).toBe("at2")
+    expect(token.refreshToken).toBe("rt2")
     expect(token.scopes).toEqual([])
   })
 
+  test("refresh retains the previous token when rotation omits one", async () => {
+    mockDiscovery(fetchMock)
+    fetchMock.mockImplementationOnce(() =>
+      Promise.resolve(
+        jsonResponse({
+          access_token: "at2",
+          token_type: "Bearer",
+          expires_in: 3600,
+        }),
+      ),
+    )
+    const oauth = new OpenSeaOAuth({ clientId: CLIENT_ID, issuer: ISSUER })
+
+    const token = await oauth.refresh("old-rt")
+
+    expect(token.refreshToken).toBe("old-rt")
+  })
+
   test("revoke posts the token to the revocation endpoint", async () => {
     mockDiscovery(fetchMock)
     fetchMock.mockImplementationOnce((url: string, init: RequestInit) => {
@@ -394,6 +438,7 @@ describe("OpenSeaOAuth", () => {
         Promise.resolve(
           jsonResponse({
             access_token: "device-at",
+            refresh_token: "device-rt",
             token_type: "Bearer",
             expires_in: 3600,
             scope: "read:eligibility",
@@ -460,8 +505,8 @@ describe("extractWalletAddress", () => {
     )
   })
 
-  test("falls back to sub when no wallet claim is present", () => {
-    expect(extractWalletAddress({ sub: "acct-1" })).toBe("acct-1")
+  test("does not treat the account subject as a wallet address", () => {
+    expect(extractWalletAddress({ sub: "acct-1" })).toBeUndefined()
   })
 
   test("returns undefined when neither claim is present", () => {

test/api/fulfillment.spec.ts test/integration/fulfillment.spec.tstest/api/fulfillment.spec.ts renamed to test/integration/fulfillment.spec.ts

@@ -1,7 +1,7 @@
 import { ethers } from "ethers"
 import { describe, expect, test } from "vitest"
 import { OrderSide } from "../../src/types"
-import { api } from "../utils/sdk"
+import { api } from "../utils/liveSdk"
 
 describe("Generating fulfillment data", () => {
   test(`Generate fulfillment data for listing`, async () => {

test/sdk/getBalance.spec.ts test/integration/getBalance.spec.tstest/sdk/getBalance.spec.ts renamed to test/integration/getBalance.spec.ts

@@ -1,7 +1,7 @@
 import { ethers } from "ethers"
 import { describe, expect, test } from "vitest"
 import { TokenStandard } from "../../src/types"
-import { sdk } from "../utils/sdk"
+import { sdk } from "../utils/liveSdk"
 
 describe("SDK: getBalance", () => {
   const accountAddress = "0x000000000000000000000000000000000000dEaD"

test/sdk/orders.spec.ts test/integration/paymentTokens.spec.tstest/sdk/orders.spec.ts renamed to test/integration/paymentTokens.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest"
-import { sdk } from "../utils/sdk"
+import { sdk } from "../utils/liveSdk"
 
 describe("SDK: orders", () => {
   test("Fungible tokens filter", async () => {