Release v11.4.1

Origin-SHA: 2309e696a4208c0d227fbb928967a1fdedfdcbfd

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/sdk
 
+## 11.4.1
+
+### Patch Changes
+
+- 71ae9ee: Keep OAuth scope status aligned with the OpenAPI scope catalog when the token endpoint omits its `scope` field.
+
 ## 11.4.0
 
 ### Minor Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "11.4.0",
+  "version": "11.4.1",
   "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.ts

@@ -1,3 +1,4 @@
+import { AUTH_SCOPES } from "@opensea/api-types"
 import type {
   DeviceAuthorizationResponse,
   OAuthDiscoveryDocument,
@@ -337,6 +338,44 @@ function buildScopeParam(scopes?: string[]): string {
 /** Fallback access-token lifetime when the server omits `expires_in`. */
 const DEFAULT_EXPIRES_IN_SECONDS = 3600
 
+const OPENAPI_AUTH_SCOPE_NAMES = AUTH_SCOPES.map(({ name }) => name)
+
+function canonicalOpenSeaScopes(scopes: string[]): string[] {
+  const granted = new Set(scopes)
+  return OPENAPI_AUTH_SCOPE_NAMES.filter(scope => granted.has(scope))
+}
+
+/**
+ * Read OpenSea API scopes from a JWT access token for client-side display and
+ * persistence. This does not verify the token and must not be used to make an
+ * authorization decision.
+ */
+export function extractOpenSeaScopes(accessToken: string): string[] {
+  try {
+    const claim = decodeJwtPayload(accessToken).opensea_scopes
+    if (typeof claim === "string") {
+      return canonicalOpenSeaScopes(claim.split(/\s+/).filter(Boolean))
+    }
+    if (Array.isArray(claim)) {
+      return canonicalOpenSeaScopes(
+        claim.filter((scope): scope is string => typeof scope === "string"),
+      )
+    }
+  } catch {
+    // Opaque access tokens cannot provide a scope fallback.
+  }
+  return []
+}
+
+function tokenOpenSeaScopes(response: OAuthTokenResponse): string[] {
+  const responseScopes = response.scope
+    ? canonicalOpenSeaScopes(response.scope.split(/\s+/).filter(Boolean))
+    : []
+  return responseScopes.length > 0
+    ? responseScopes
+    : extractOpenSeaScopes(response.access_token)
+}
+
 function toOAuthToken(response: OAuthTokenResponse): OAuthToken {
   const expiresIn =
     typeof response.expires_in === "number" &&
@@ -348,7 +387,7 @@ function toOAuthToken(response: OAuthTokenResponse): OAuthToken {
     refreshToken: response.refresh_token,
     idToken: response.id_token,
     expiresAt: new Date(Date.now() + expiresIn * 1000),
-    scopes: response.scope ? response.scope.split(" ") : [],
+    scopes: tokenOpenSeaScopes(response),
   }
 }
 

test/auth/oauth.spec.ts

@@ -33,6 +33,13 @@ function mockDiscovery(fetchMock: ReturnType<typeof vi.fn>) {
   )
 }
 
+function jwt(payload: Record<string, unknown>): string {
+  const encoded = Buffer.from(JSON.stringify(payload))
+    .toString("base64url")
+    .replace(/=+$/, "")
+  return `header.${encoded}.signature`
+}
+
 let fetchMock: ReturnType<typeof vi.fn>
 
 beforeEach(() => {
@@ -184,6 +191,107 @@ describe("OpenSeaOAuth", () => {
     ).rejects.toThrow(/Token request failed/)
   })
 
+  test("reads OpenSea scopes from the access token when scope is omitted", async () => {
+    mockDiscovery(fetchMock)
+    fetchMock.mockImplementationOnce(() =>
+      Promise.resolve(
+        jsonResponse({
+          access_token: jwt({
+            opensea_scopes:
+              "write:orders read:eligibility read:rewards unknown:scope",
+          }),
+          refresh_token: "rt",
+          token_type: "Bearer",
+          expires_in: 3600,
+        }),
+      ),
+    )
+
+    const oauth = new OpenSeaOAuth({ clientId: CLIENT_ID, issuer: ISSUER })
+    const token = await oauth.exchangeCode({
+      code: "the-code",
+      codeVerifier: "the-verifier",
+      redirectUri: "http://127.0.0.1:8151/callback",
+    })
+
+    expect(token.scopes).toEqual(["read:eligibility", "write:orders"])
+  })
+
+  test("reads array OpenSea scope claims in canonical API order", async () => {
+    mockDiscovery(fetchMock)
+    fetchMock.mockImplementationOnce(() =>
+      Promise.resolve(
+        jsonResponse({
+          access_token: jwt({
+            opensea_scopes: ["write:favorites", "read:favorites"],
+          }),
+          token_type: "Bearer",
+          expires_in: 3600,
+        }),
+      ),
+    )
+
+    const oauth = new OpenSeaOAuth({ clientId: CLIENT_ID, issuer: ISSUER })
+    const token = await oauth.exchangeCode({
+      code: "the-code",
+      codeVerifier: "the-verifier",
+      redirectUri: "http://127.0.0.1:8151/callback",
+    })
+
+    expect(token.scopes).toEqual(["read:favorites", "write:favorites"])
+  })
+
+  test("filters token response scopes through the OpenAPI catalog", async () => {
+    mockDiscovery(fetchMock)
+    fetchMock.mockImplementationOnce(() =>
+      Promise.resolve(
+        jsonResponse({
+          access_token: "opaque-token",
+          token_type: "Bearer",
+          expires_in: 3600,
+          scope: "read:eligibility read:rewards unknown:scope",
+        }),
+      ),
+    )
+
+    const oauth = new OpenSeaOAuth({ clientId: CLIENT_ID, issuer: ISSUER })
+    const token = await oauth.exchangeCode({
+      code: "the-code",
+      codeVerifier: "the-verifier",
+      redirectUri: "http://127.0.0.1:8151/callback",
+    })
+
+    expect(token.scopes).toEqual(["read:eligibility"])
+  })
+
+  test.each([
+    ["a JWT without the claim", jwt({ wallet: "0xabc" })],
+    [
+      "a JWT with only unknown claims",
+      jwt({ opensea_scopes: "unknown:scope" }),
+    ],
+  ])("returns no scopes for %s", async (_label, accessToken) => {
+    mockDiscovery(fetchMock)
+    fetchMock.mockImplementationOnce(() =>
+      Promise.resolve(
+        jsonResponse({
+          access_token: accessToken,
+          token_type: "Bearer",
+          expires_in: 3600,
+        }),
+      ),
+    )
+
+    const oauth = new OpenSeaOAuth({ clientId: CLIENT_ID, issuer: ISSUER })
+    const token = await oauth.exchangeCode({
+      code: "the-code",
+      codeVerifier: "the-verifier",
+      redirectUri: "http://127.0.0.1:8151/callback",
+    })
+
+    expect(token.scopes).toEqual([])
+  })
+
   test("refresh uses the refresh_token grant", async () => {
     mockDiscovery(fetchMock)
     fetchMock.mockImplementationOnce((_url: string, init: RequestInit) => {