Release v1.12.4

Origin-SHA: 3643ebdaab0e2e9139ac9f609e6f2b810e7c743d

Author: ryanio

.agents/rules.md

@@ -58,6 +58,13 @@ CLI (src/cli.ts)              SDK (src/sdk.ts)
 | `src/types/api.ts` | TypeScript interfaces matching OpenSea API v2 response shapes. |
 | `src/types/index.ts` | Re-exports API types plus internal config types. |
 
+### Auth Session Invariants
+
+- Persisted tokens are a strict prerelease contract. Every entry requires a non-empty access token, refresh token, wallet address, ISO expiration, scopes array, and explicit `oauth` or `siwe` auth method. Do not add legacy-field fallbacks; incompatible stores should require a new login.
+- OAuth login requires a JWT access token with the top-level `wallet` claim. Never substitute the OIDC `sub` claim, which is an account identifier, or save a token under a placeholder address.
+- Normalize only `0x`-prefixed EVM addresses to lowercase. Preserve all other wallet addresses exactly because Solana base58 addresses are case-sensitive.
+- The SDK owns refresh-token rotation semantics. CLI callers should persist the required `OAuthToken.refreshToken` exactly as returned.
+
 ### API Types
 
 API request/response types live in `src/types/api.ts` and are mostly thin re-exports of `components["schemas"]["..."]` from `@opensea/api-types`. **Never hand-roll types for OpenSea API v2 endpoints.** When adding a new endpoint:

CHANGELOG.md

@@ -1,5 +1,21 @@
 # @opensea/cli
 
+## 1.12.4
+
+### Patch Changes
+
+- b64a4d5: Require complete OAuth wallet sessions, retain refresh tokens during rotation, validate the CLI auth store, and preserve case-sensitive wallet addresses.
+- Updated dependencies [b64a4d5]
+  - @opensea/sdk@11.4.3
+
+## 1.12.3
+
+### Patch Changes
+
+- 3fba2be: Add `opensea drops eligibility <slug>` for checking the authenticated wallet's drop eligibility.
+- Updated dependencies [5966017]
+  - @opensea/sdk@11.4.2
+
 ## 1.12.2
 
 ### Patch Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.12.2",
+  "version": "1.12.4",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@opensea/api-types": "^0.8.0",
-    "@opensea/sdk": "^11.4.1",
+    "@opensea/sdk": "^11.4.3",
     "@opensea/wallet-adapters": "^0.3.2",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

src/auth/store.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { join } from "node:path"
-import { extractOpenSeaScopes } from "@opensea/sdk"
+import { z } from "zod"
 
 /**
  * Shape of a persisted auth token entry.
@@ -23,6 +23,24 @@ interface AuthStore {
   tokens: Record<string, StoredToken>
 }
 
+const storedTokenSchema = z
+  .object({
+    accessToken: z.string().min(1),
+    refreshToken: z.string().min(1),
+    expiresAt: z.iso.datetime(),
+    scopes: z.array(z.string().min(1)),
+    address: z.string().min(1),
+    authMethod: z.enum(["oauth", "siwe"]),
+  })
+  .strict()
+
+const authStoreSchema = z
+  .object({
+    currentAddress: z.string().min(1).optional(),
+    tokens: z.record(z.string(), storedTokenSchema),
+  })
+  .strict()
+
 const AUTH_DIR = join(homedir(), ".opensea")
 const AUTH_FILE = join(AUTH_DIR, "auth.json")
 
@@ -41,10 +59,21 @@ function readStore(): AuthStore {
   if (!existsSync(AUTH_FILE)) return { tokens: {} }
   try {
     const data = readFileSync(AUTH_FILE, "utf-8")
-    return JSON.parse(data) as AuthStore
+    const store = authStoreSchema.parse(JSON.parse(data))
+    for (const [key, token] of Object.entries(store.tokens)) {
+      if (key !== normalizeAddress(token.address)) {
+        throw new Error(
+          "Auth store token key does not match its wallet address",
+        )
+      }
+    }
+    if (store.currentAddress && !store.tokens[store.currentAddress]) {
+      throw new Error("Auth store current address has no matching token")
+    }
+    return store
   } catch {
     console.warn(
-      `Warning: ${AUTH_FILE} is corrupted. Starting with empty store.`,
+      `Warning: ${AUTH_FILE} is corrupted or incompatible. Run \`opensea login\` to authenticate again.`,
     )
     return { tokens: {} }
   }
@@ -60,19 +89,20 @@ function writeStore(store: AuthStore): void {
   }
 }
 
-function withDerivedScopes(token: StoredToken): StoredToken {
-  if (token.scopes.length > 0) return token
-  const scopes = extractOpenSeaScopes(token.accessToken)
-  return scopes.length > 0 ? { ...token, scopes } : token
+function normalizeAddress(address: string): string {
+  return address.slice(0, 2).toLowerCase() === "0x"
+    ? address.toLowerCase()
+    : address
 }
 
 /**
  * Save a token to the persistent store, keyed by wallet address.
  */
 export function saveToken(token: StoredToken): void {
   const store = readStore()
-  store.tokens[token.address.toLowerCase()] = token
-  store.currentAddress = token.address.toLowerCase()
+  const key = normalizeAddress(token.address)
+  store.tokens[key] = storedTokenSchema.parse(token)
+  store.currentAddress = key
   writeStore(store)
 }
 
@@ -82,25 +112,23 @@ export function saveToken(token: StoredToken): void {
 export function loadCurrentToken(): StoredToken | undefined {
   const store = readStore()
   if (!store.currentAddress) return undefined
-  const token = store.tokens[store.currentAddress]
-  return token ? withDerivedScopes(token) : undefined
+  return store.tokens[store.currentAddress]
 }
 
 /**
  * Load a specific token by wallet address.
  */
 export function loadToken(address: string): StoredToken | undefined {
   const store = readStore()
-  const token = store.tokens[address.toLowerCase()]
-  return token ? withDerivedScopes(token) : undefined
+  return store.tokens[normalizeAddress(address)]
 }
 
 /**
  * List all stored tokens.
  */
 export function listTokens(): StoredToken[] {
   const store = readStore()
-  return Object.values(store.tokens).map(withDerivedScopes)
+  return Object.values(store.tokens)
 }
 
 /**
@@ -109,7 +137,7 @@ export function listTokens(): StoredToken[] {
  */
 export function removeToken(address: string): boolean {
   const store = readStore()
-  const key = address.toLowerCase()
+  const key = normalizeAddress(address)
   if (!store.tokens[key]) return false
   delete store.tokens[key]
   if (store.currentAddress === key) {

src/commands/auth.ts

@@ -323,14 +323,6 @@ export function authCommand(
         console.error("No stored token to refresh")
         process.exit(1)
       }
-      if (!token.refreshToken) {
-        throw new Error("Stored auth token has no refresh token")
-      }
-      if (!token.authMethod) {
-        throw new Error(
-          "Stored auth token has no auth method. Run `opensea login` again.",
-        )
-      }
       const authBase = getAuthBaseUrl?.() ?? DEFAULT_AUTH_BASE_URL
 
       if (token.authMethod === "oauth") {
@@ -339,10 +331,9 @@ export function authCommand(
           issuer: authBase,
         })
         const refreshed = await oauth.refresh(token.refreshToken)
-        const refreshToken = refreshed.refreshToken || token.refreshToken
         saveToken({
           accessToken: refreshed.accessToken,
-          refreshToken,
+          refreshToken: refreshed.refreshToken,
           expiresAt: refreshed.expiresAt.toISOString(),
           scopes: refreshed.scopes,
           address: token.address,

src/commands/drops.ts

@@ -7,6 +7,7 @@ import type {
   Chain,
   DropDeployRequest,
   DropDeployResponse,
+  DropEligibilityResponse,
   DropMintResponse,
 } from "../types/index.js"
 
@@ -56,6 +57,18 @@ export function dropsCommand(
       await outputGet(client, getFormat(), `/api/v2/drops/${slug}`)
     })
 
+  cmd
+    .command("eligibility")
+    .description("Check drop eligibility for the authenticated wallet")
+    .argument("<slug>", "Collection slug")
+    .action(async (slug: string) => {
+      const client = getClient()
+      const result = await client.get<DropEligibilityResponse>(
+        `/api/v2/drops/${slug}/eligibility`,
+      )
+      console.log(formatOutput(result, getFormat()))
+    })
+
   cmd
     .command("mint")
     .description("Build a mint transaction for a drop")

src/commands/login.ts

@@ -83,12 +83,17 @@ export function loginCommand(
               },
             })
 
-        const claims = safeDecodeClaims(token.accessToken)
-        const address = extractWalletAddress(claims) ?? "unknown"
+        const claims = decodeJwtPayload(token.accessToken)
+        const address = extractWalletAddress(claims)
+        if (!address) {
+          throw new Error(
+            "OAuth access token is missing the required wallet claim",
+          )
+        }
 
         saveToken({
           accessToken: token.accessToken,
-          refreshToken: token.refreshToken ?? "",
+          refreshToken: token.refreshToken,
           expiresAt: token.expiresAt.toISOString(),
           scopes: token.scopes,
           address,
@@ -110,21 +115,6 @@ export function loginCommand(
     )
 }
 
-/**
- * Decode token claims, tolerating opaque (non-JWT) access tokens. The
- * authorization server normally issues a JWT, but if it returns an opaque
- * token `decodeJwtPayload` throws — fall back to empty claims so
- * `extractWalletAddress` uses its `sub`/`unknown` path and the token is still
- * saved.
- */
-function safeDecodeClaims(accessToken: string): Record<string, unknown> {
-  try {
-    return decodeJwtPayload(accessToken)
-  } catch {
-    return {}
-  }
-}
-
 async function runDeviceFlow(
   oauth: OpenSeaOAuth,
   scopes: string[],

src/types/api.ts

@@ -64,6 +64,7 @@ export type DropStageResponse = Schemas["DropStageResponse"]
 export type DropPaginatedResponse = Schemas["DropPaginatedResponse"]
 export type DropMintRequest = Schemas["DropMintRequest"]
 export type DropMintResponse = Schemas["DropMintResponse"]
+export type DropEligibilityResponse = Schemas["DropEligibilityResponse"]
 export type DropDeployRequest = Schemas["DropDeployRequest"]
 export type DropDeployResponse = Schemas["DropDeployResponse"]
 export type DropDeployReceiptResponse = Schemas["DropDeployReceiptResponse"]