Release v1.13.0

Origin-SHA: 827450af53927bfec7e89cb8b7f39d276e144a93

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

Author: devin-ai-integration[bot]

CHANGELOG.md

@@ -1,5 +1,19 @@
 # @opensea/cli
 
+## 1.13.0
+
+### Minor Changes
+
+- d10626b: Add an `opensea whoami` command that displays the current wallet identity,
+  scope source, and expiry, with unverified JWT diagnostics available through an
+  explicit flag. Expose whether OAuth scopes came from the authorization-server
+  response or a JWT fallback.
+
+### Patch Changes
+
+- Updated dependencies [d10626b]
+  - @opensea/sdk@11.4.5
+
 ## 1.12.5
 
 ### Patch Changes

README.md

@@ -56,6 +56,7 @@ Wallet-authenticated endpoints also require a scoped token:
 ```bash
 opensea login
 opensea auth status
+opensea whoami
 opensea api request GET /api/v2/account/0xYOUR_WALLET/favorites --params '{"limit":1}'
 ```
 
@@ -102,6 +103,7 @@ opensea --format table collections stats mfers
 | `tokens` | Get trending tokens, top tokens, and token details |
 | `swaps` | Get swap quotes for token trading |
 | `accounts` | Get account details |
+| `whoami` | Show the current wallet, scopes, and scope source |
 | `api request` | Call any API v2 endpoint with the active API key and scoped token |
 
 Global options: `--api-key`, `--chain` (default: ethereum), `--format` (json/table/toon), `--base-url`

docs/cli-reference.md

@@ -13,6 +13,17 @@ Full command reference for all `opensea` CLI commands.
 --verbose           Log request and response info to stderr
 ```
 
+## Authentication
+
+```bash
+opensea whoami
+```
+
+`whoami` reads the current local auth token and shows the wallet address,
+scopes, their source, and expiry. Use `opensea whoami --diagnostic` to inspect
+decoded JWT claims and scope differences. Those claims are unverified,
+provider-specific diagnostics only and never authorization data.
+
 ## Collections
 
 ```bash

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.12.5",
+  "version": "1.13.0",
   "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.4",
+    "@opensea/sdk": "^11.4.5",
     "@opensea/wallet-adapters": "^0.3.3",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

src/auth/store.ts

@@ -19,6 +19,11 @@ export interface StoredToken {
   scopedTokenId?: string
   expiresAt: string
   scopes: string[]
+  scopeSource?:
+    | "authorization_server"
+    | "token_exchange"
+    | "token_creation"
+    | "jwt_claim"
   address: string
   authMethod: "oauth" | "siwe"
 }
@@ -38,6 +43,14 @@ const storedTokenSchema = z
     scopedTokenId: z.string().min(1).optional(),
     expiresAt: z.iso.datetime(),
     scopes: z.array(z.string().min(1)),
+    scopeSource: z
+      .enum([
+        "authorization_server",
+        "token_exchange",
+        "token_creation",
+        "jwt_claim",
+      ])
+      .optional(),
     address: z.string().min(1),
     authMethod: z.enum(["oauth", "siwe"]),
   })

src/cli.ts

@@ -22,6 +22,7 @@ import {
   toolsCommand,
   transactionsCommand,
   walletCommand,
+  whoamiCommand,
 } from "./commands/index.js"
 import { type OutputFormat, setOutputOptions } from "./output.js"
 import { parseIntOption } from "./parse.js"
@@ -166,6 +167,7 @@ program.addCommand(toolsCommand(getClient, getFormat))
 program.addCommand(transactionsCommand(getClient, getFormat))
 program.addCommand(healthCommand(getClient, getFormat))
 program.addCommand(walletCommand(getFormat))
+program.addCommand(whoamiCommand(getFormat))
 
 async function main() {
   try {

src/commands/auth.ts

@@ -250,6 +250,9 @@ export function authCommand(
         Date.now() + (tokenData.expiresIn ?? DEFAULT_TOKEN_TTL_SECONDS) * 1000,
       )
       const grantedScopes = tokenData.tokenScopes ?? scopedToken.scopes
+      const scopeSource = tokenData.tokenScopes
+        ? "token_exchange"
+        : "token_creation"
 
       // The PAT acts as the refresh credential. The store is mode 0600.
       saveToken({
@@ -258,6 +261,7 @@ export function authCommand(
         scopedTokenId: scopedToken.id,
         expiresAt: expiresAt.toISOString(),
         scopes: grantedScopes,
+        scopeSource,
         address,
         authMethod: "siwe",
       })
@@ -268,6 +272,7 @@ export function authCommand(
             status: "authenticated",
             address,
             scopes: grantedScopes,
+            scope_source: scopeSource,
             expires_at: expiresAt.toISOString(),
           },
           getFormat(),
@@ -444,6 +449,7 @@ export function authCommand(
           refreshToken: refreshed.refreshToken,
           expiresAt: refreshed.expiresAt.toISOString(),
           scopes: refreshed.scopes,
+          scopeSource: refreshed.scopeSource,
           address: token.address,
           authMethod: "oauth",
         })
@@ -453,6 +459,7 @@ export function authCommand(
               status: "refreshed",
               address: token.address,
               scopes: refreshed.scopes,
+              scope_source: refreshed.scopeSource,
               expires_at: refreshed.expiresAt.toISOString(),
             },
             getFormat(),
@@ -467,18 +474,23 @@ export function authCommand(
         Date.now() + (data.expiresIn ?? DEFAULT_TOKEN_TTL_SECONDS) * 1000,
       )
       const grantedScopes = data.tokenScopes ?? token.scopes
+      const scopeSource = data.tokenScopes
+        ? "token_exchange"
+        : (token.scopeSource ?? "unknown")
       saveToken({
         ...token,
         accessToken: data.accessToken,
         expiresAt: expiresAt.toISOString(),
         scopes: grantedScopes,
+        ...(scopeSource === "unknown" ? {} : { scopeSource }),
       })
       console.log(
         formatOutput(
           {
             status: "refreshed",
             address: token.address,
             scopes: grantedScopes,
+            scope_source: scopeSource,
             expires_at: expiresAt.toISOString(),
           },
           getFormat(),
@@ -560,6 +572,7 @@ export function authCommand(
       const output = tokens.map(t => ({
         address: t.address,
         scopes: t.scopes,
+        scope_source: t.scopeSource ?? "unknown",
         expires_at: t.expiresAt,
         expired: new Date(t.expiresAt) < new Date(),
         current: t.address.toLowerCase() === current?.address.toLowerCase(),

src/commands/index.ts

@@ -18,3 +18,4 @@ export { tokensCommand } from "./tokens.js"
 export { toolsCommand } from "./tools.js"
 export { transactionsCommand } from "./transactions.js"
 export { walletCommand } from "./wallet.js"
+export { whoamiCommand } from "./whoami.js"

src/commands/login.ts

@@ -22,6 +22,14 @@ import { formatOutput } from "../output.js"
  */
 const DEFAULT_SCOPES = AUTH_SCOPES.map(({ name }) => name)
 
+function scopesOutsideRequested(
+  requestedScopes: string[],
+  grantedScopes: string[],
+): string[] {
+  const requested = new Set(requestedScopes)
+  return grantedScopes.filter(scope => !requested.has(scope))
+}
+
 /**
  * Top-level `opensea login` — keyless OAuth 2.1 (authorization-code + PKCE)
  * login against the OpenSea authorization server. No private key, no SIWE
@@ -83,6 +91,13 @@ export function loginCommand(
               },
             })
 
+        const broaderScopes = scopesOutsideRequested(scopes, token.scopes)
+        if (broaderScopes.length > 0) {
+          console.error(
+            `Warning: the authorization server granted scopes outside the requested set: ${broaderScopes.join(", ")}`,
+          )
+        }
+
         const claims = decodeJwtPayload(token.accessToken)
         const address = extractWalletAddress(claims)
         if (!address) {
@@ -96,6 +111,7 @@ export function loginCommand(
           refreshToken: token.refreshToken,
           expiresAt: token.expiresAt.toISOString(),
           scopes: token.scopes,
+          ...(token.scopeSource ? { scopeSource: token.scopeSource } : {}),
           address,
           authMethod: "oauth",
         })
@@ -105,7 +121,17 @@ export function loginCommand(
             {
               status: "authenticated",
               address,
-              scopes: token.scopes,
+              requested_scopes: scopes,
+              granted_scopes: token.scopes,
+              scope_source: token.scopeSource,
+              ...(broaderScopes.length > 0
+                ? {
+                    scope_warning: {
+                      type: "broader_than_requested",
+                      scopes: broaderScopes,
+                    },
+                  }
+                : {}),
               expires_at: token.expiresAt.toISOString(),
             },
             getFormat(),

src/commands/whoami.ts

@@ -0,0 +1,104 @@
+import { Command } from "commander"
+import { loadCurrentToken } from "../auth/store.js"
+import type { OutputFormat } from "../output.js"
+import { formatOutput } from "../output.js"
+
+const PROJECT_ROLES_CLAIM = "urn:zitadel:iam:org:project:roles"
+
+function decodeJwtPayload(token: string): Record<string, unknown> {
+  const parts = token.split(".")
+  if (parts.length !== 3) {
+    throw new Error("Not a JWT")
+  }
+  const payload = Buffer.from(parts[1], "base64url").toString("utf8")
+  return JSON.parse(payload) as Record<string, unknown>
+}
+
+function readScopesClaim(value: unknown): string[] {
+  if (typeof value === "string") {
+    return value.split(/\s+/).filter(Boolean)
+  }
+  if (Array.isArray(value)) {
+    return value.filter((scope): scope is string => typeof scope === "string")
+  }
+  return []
+}
+
+function readJwtIdentity(accessToken: string): {
+  wallet?: string
+  opensea_scopes: string[]
+  project_roles?: unknown
+} {
+  const claims = decodeJwtPayload(accessToken)
+  const wallet = typeof claims.wallet === "string" ? claims.wallet : undefined
+  const projectRoles = claims[PROJECT_ROLES_CLAIM] ?? claims.project_roles
+
+  return {
+    wallet,
+    opensea_scopes: readScopesClaim(claims.opensea_scopes),
+    ...(projectRoles === undefined ? {} : { project_roles: projectRoles }),
+  }
+}
+
+function difference(left: string[], right: string[]): string[] {
+  const rightSet = new Set(right)
+  return left.filter(scope => !rightSet.has(scope))
+}
+
+export function whoamiCommand(getFormat: () => OutputFormat): Command {
+  return new Command("whoami")
+    .description("Show the current authenticated wallet and scopes")
+    .option(
+      "--diagnostic",
+      "Include unverified JWT claims for troubleshooting; claims are not authorization data",
+    )
+    .action((options: { diagnostic?: boolean }) => {
+      const token = loadCurrentToken()
+      if (!token) {
+        console.log(
+          formatOutput(
+            { status: "not_authenticated", message: "No stored token" },
+            getFormat(),
+          ),
+        )
+        return
+      }
+
+      const expired = new Date(token.expiresAt) < new Date()
+      let jwt: ReturnType<typeof readJwtIdentity> | undefined
+      let jwtError: string | undefined
+      try {
+        jwt = readJwtIdentity(token.accessToken)
+      } catch (error) {
+        jwtError = error instanceof Error ? error.message : String(error)
+      }
+
+      const jwtScopes = jwt?.opensea_scopes ?? []
+      const diagnostic = options.diagnostic
+        ? {
+            unverified: true,
+            jwt: jwt ?? { opensea_scopes: [] },
+            scope_difference: {
+              only_in_token: difference(token.scopes, jwtScopes),
+              only_in_jwt: difference(jwtScopes, token.scopes),
+            },
+            ...(jwtError ? { jwt_error: jwtError } : {}),
+          }
+        : undefined
+      console.log(
+        formatOutput(
+          {
+            status: expired ? "expired" : "authenticated",
+            address: token.address,
+            auth_method: token.authMethod,
+            scopes: token.scopes,
+            scope_source: token.scopeSource ?? "unknown",
+            ...(diagnostic ? { diagnostic } : {}),
+            expires_at: token.expiresAt,
+            expired,
+          },
+          getFormat(),
+        ),
+      )
+    })
+}