@opensea/sdk 11.1.1 → 11.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/api/accounts.d.ts +13 -1
- package/lib/api/accounts.js +18 -0
- package/lib/api/accounts.js.map +1 -1
- package/lib/api/api.d.ts +14 -1
- package/lib/api/api.js +22 -0
- package/lib/api/api.js.map +1 -1
- package/lib/api/apiPaths.d.ts +3 -0
- package/lib/api/apiPaths.js +13 -1
- package/lib/api/apiPaths.js.map +1 -1
- package/lib/api/types.d.ts +31 -1
- package/lib/auth/index.d.ts +65 -0
- package/lib/auth/index.js +168 -0
- package/lib/auth/index.js.map +1 -0
- package/lib/auth/oauth-types.d.ts +69 -0
- package/lib/auth/oauth-types.js +3 -0
- package/lib/auth/oauth-types.js.map +1 -0
- package/lib/auth/oauth.d.ts +109 -0
- package/lib/auth/oauth.js +342 -0
- package/lib/auth/oauth.js.map +1 -0
- package/lib/auth/types.d.ts +50 -0
- package/lib/auth/types.js +3 -0
- package/lib/auth/types.js.map +1 -0
- package/lib/index.d.ts +7 -1
- package/lib/index.js +9 -1
- package/lib/index.js.map +1 -1
- package/lib/scopes.d.ts +29 -0
- package/lib/scopes.js +27 -0
- package/lib/scopes.js.map +1 -0
- package/lib/sdk/base.d.ts +1 -0
- package/lib/sdk/base.js +6 -3
- package/lib/sdk/base.js.map +1 -1
- package/lib/sdk/cancellation.js +33 -23
- package/lib/sdk/cancellation.js.map +1 -1
- package/lib/types.d.ts +5 -1
- package/lib/types.js +1 -0
- package/lib/types.js.map +1 -1
- package/lib/utils/chain.d.ts +1 -1
- package/lib/utils/chain.js +29 -5
- package/lib/utils/chain.js.map +1 -1
- package/lib/utils/chainIds.generated.js +1 -0
- package/lib/utils/chainIds.generated.js.map +1 -1
- package/lib/viem.d.ts +1 -0
- package/lib/viem.js +1 -0
- package/lib/viem.js.map +1 -1
- package/package.json +2 -2
- package/src/api/accounts.ts +41 -0
- package/src/api/api.ts +36 -0
- package/src/api/apiPaths.ts +12 -0
- package/src/api/types.ts +36 -0
- package/src/auth/index.ts +230 -0
- package/src/auth/oauth-types.ts +73 -0
- package/src/auth/oauth.ts +428 -0
- package/src/auth/types.ts +55 -0
- package/src/index.ts +10 -0
- package/src/scopes.ts +39 -0
- package/src/sdk/base.ts +6 -4
- package/src/sdk/cancellation.ts +39 -25
- package/src/types.ts +4 -0
- package/src/utils/chain.ts +36 -5
- package/src/utils/chainIds.generated.ts +1 -0
- package/src/viem.ts +1 -0
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
AuthenticateOptions,
|
|
3
|
+
AuthNonceResponse,
|
|
4
|
+
AuthSigner,
|
|
5
|
+
AuthToken,
|
|
6
|
+
AuthTokenResponse,
|
|
7
|
+
OpenSeaAuthConfig,
|
|
8
|
+
} from "./types"
|
|
9
|
+
|
|
10
|
+
export type {
|
|
11
|
+
AuthenticateOptions,
|
|
12
|
+
AuthNonceResponse,
|
|
13
|
+
AuthSigner,
|
|
14
|
+
AuthToken,
|
|
15
|
+
AuthTokenResponse,
|
|
16
|
+
OpenSeaAuthConfig,
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const DEFAULT_AUTH_BASE_URL = "https://auth.opensea.io"
|
|
20
|
+
|
|
21
|
+
/** Buffer (in ms) before expiry at which auto-refresh triggers. */
|
|
22
|
+
const REFRESH_BUFFER_MS = 60_000
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* SIWE-based authentication helper for OpenSea.
|
|
26
|
+
*
|
|
27
|
+
* Handles the full sign-in flow: nonce request, EIP-4361 message generation,
|
|
28
|
+
* signature exchange, token caching, and automatic refresh.
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* import { OpenSeaAuth } from "@opensea/sdk"
|
|
33
|
+
*
|
|
34
|
+
* const auth = new OpenSeaAuth()
|
|
35
|
+
* const token = await auth.authenticate(signer, {
|
|
36
|
+
* scopes: ["read:eligibility", "write:orders"],
|
|
37
|
+
* })
|
|
38
|
+
*
|
|
39
|
+
* // Auto-refresh before expiry
|
|
40
|
+
* const freshToken = await auth.getValidToken()
|
|
41
|
+
*
|
|
42
|
+
* // Revoke
|
|
43
|
+
* await auth.revoke(token.accessToken)
|
|
44
|
+
* ```
|
|
45
|
+
*
|
|
46
|
+
* @category Authentication
|
|
47
|
+
*/
|
|
48
|
+
export class OpenSeaAuth {
|
|
49
|
+
private readonly authBaseUrl: string
|
|
50
|
+
private cachedToken: AuthToken | undefined
|
|
51
|
+
|
|
52
|
+
constructor(config: OpenSeaAuthConfig = {}) {
|
|
53
|
+
this.authBaseUrl = (config.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(
|
|
54
|
+
/\/$/,
|
|
55
|
+
"",
|
|
56
|
+
)
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Run the full SIWE authentication flow:
|
|
61
|
+
* 1. Request a nonce from the auth server
|
|
62
|
+
* 2. Build an EIP-4361 SIWE message
|
|
63
|
+
* 3. Sign it with the provided signer
|
|
64
|
+
* 4. Exchange the signature for a scoped JWT token
|
|
65
|
+
*
|
|
66
|
+
* The returned token is cached in memory and will be auto-refreshed
|
|
67
|
+
* by {@link getValidToken}.
|
|
68
|
+
*/
|
|
69
|
+
async authenticate(
|
|
70
|
+
signer: AuthSigner,
|
|
71
|
+
options: AuthenticateOptions = {},
|
|
72
|
+
): Promise<AuthToken> {
|
|
73
|
+
const address = await signer.getAddress()
|
|
74
|
+
const { nonce } = await this.requestNonce()
|
|
75
|
+
const message = generateSiweMessage(
|
|
76
|
+
address,
|
|
77
|
+
options.scopes ?? [],
|
|
78
|
+
nonce,
|
|
79
|
+
this.authBaseUrl,
|
|
80
|
+
)
|
|
81
|
+
const signature = await signer.signMessage(message)
|
|
82
|
+
const tokenResponse = await this.exchangeSignature(message, signature)
|
|
83
|
+
const token = toAuthToken(tokenResponse)
|
|
84
|
+
this.cachedToken = token
|
|
85
|
+
return token
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Return a valid access token, refreshing automatically if the cached
|
|
90
|
+
* token is expired or about to expire.
|
|
91
|
+
*
|
|
92
|
+
* @throws If no token has been obtained yet via {@link authenticate}.
|
|
93
|
+
*/
|
|
94
|
+
async getValidToken(): Promise<AuthToken> {
|
|
95
|
+
if (!this.cachedToken) {
|
|
96
|
+
throw new Error(
|
|
97
|
+
"No auth token available. Call authenticate() with a signer first.",
|
|
98
|
+
)
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
if (this.cachedToken.expiresAt.getTime() - Date.now() < REFRESH_BUFFER_MS) {
|
|
102
|
+
const tokenResponse = await this.refreshToken(
|
|
103
|
+
this.cachedToken.refreshToken,
|
|
104
|
+
)
|
|
105
|
+
this.cachedToken = toAuthToken(tokenResponse)
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
return this.cachedToken
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Revoke an access token.
|
|
113
|
+
*/
|
|
114
|
+
async revoke(accessToken: string): Promise<void> {
|
|
115
|
+
const response = await fetch(`${this.authBaseUrl}/api/revoke`, {
|
|
116
|
+
method: "POST",
|
|
117
|
+
headers: { "Content-Type": "application/json" },
|
|
118
|
+
body: JSON.stringify({ token: accessToken }),
|
|
119
|
+
})
|
|
120
|
+
if (!response.ok) {
|
|
121
|
+
throw new Error(
|
|
122
|
+
`Auth server error (${response.status}): ${response.statusText}`,
|
|
123
|
+
)
|
|
124
|
+
}
|
|
125
|
+
if (this.cachedToken?.accessToken === accessToken) {
|
|
126
|
+
this.cachedToken = undefined
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Request a nonce from the auth server. */
|
|
131
|
+
async requestNonce(): Promise<AuthNonceResponse> {
|
|
132
|
+
const response = await fetch(`${this.authBaseUrl}/api/nonce`, {
|
|
133
|
+
method: "GET",
|
|
134
|
+
headers: { Accept: "application/json" },
|
|
135
|
+
})
|
|
136
|
+
if (!response.ok) {
|
|
137
|
+
throw new Error(
|
|
138
|
+
`Auth server error (${response.status}): ${response.statusText}`,
|
|
139
|
+
)
|
|
140
|
+
}
|
|
141
|
+
return response.json() as Promise<AuthNonceResponse>
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Exchange a signed SIWE message for a JWT token. */
|
|
145
|
+
private async exchangeSignature(
|
|
146
|
+
message: string,
|
|
147
|
+
signature: string,
|
|
148
|
+
): Promise<AuthTokenResponse> {
|
|
149
|
+
const response = await fetch(`${this.authBaseUrl}/api/token`, {
|
|
150
|
+
method: "POST",
|
|
151
|
+
headers: { "Content-Type": "application/json" },
|
|
152
|
+
body: JSON.stringify({ message, signature }),
|
|
153
|
+
})
|
|
154
|
+
if (!response.ok) {
|
|
155
|
+
throw new Error(
|
|
156
|
+
`Auth server error (${response.status}): ${response.statusText}`,
|
|
157
|
+
)
|
|
158
|
+
}
|
|
159
|
+
return response.json() as Promise<AuthTokenResponse>
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Refresh an access token using a refresh token. */
|
|
163
|
+
private async refreshToken(
|
|
164
|
+
refreshTokenValue: string,
|
|
165
|
+
): Promise<AuthTokenResponse> {
|
|
166
|
+
const response = await fetch(`${this.authBaseUrl}/api/refresh`, {
|
|
167
|
+
method: "POST",
|
|
168
|
+
headers: { "Content-Type": "application/json" },
|
|
169
|
+
body: JSON.stringify({ refresh_token: refreshTokenValue }),
|
|
170
|
+
})
|
|
171
|
+
if (!response.ok) {
|
|
172
|
+
throw new Error(
|
|
173
|
+
`Auth server error (${response.status}): ${response.statusText}`,
|
|
174
|
+
)
|
|
175
|
+
}
|
|
176
|
+
return response.json() as Promise<AuthTokenResponse>
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** Validity window (in ms) for a generated SIWE message. */
|
|
181
|
+
const SIWE_MESSAGE_VALIDITY_MS = 10 * 60_000
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Build an EIP-4361 (SIWE) message for OpenSea authentication.
|
|
185
|
+
*
|
|
186
|
+
* @see https://eips.ethereum.org/EIPS/eip-4361
|
|
187
|
+
*/
|
|
188
|
+
export function generateSiweMessage(
|
|
189
|
+
address: string,
|
|
190
|
+
scopes: string[],
|
|
191
|
+
nonce: string,
|
|
192
|
+
authBaseUrl: string,
|
|
193
|
+
chainId = 1,
|
|
194
|
+
): string {
|
|
195
|
+
const url = new URL(authBaseUrl)
|
|
196
|
+
const domain = url.host
|
|
197
|
+
const uri = `${authBaseUrl}/api/token`
|
|
198
|
+
const now = Date.now()
|
|
199
|
+
const issuedAt = new Date(now).toISOString()
|
|
200
|
+
const expirationTime = new Date(now + SIWE_MESSAGE_VALIDITY_MS).toISOString()
|
|
201
|
+
const resources =
|
|
202
|
+
scopes.length > 0
|
|
203
|
+
? `\nResources:${scopes.map(s => `\n- ${s}`).join("")}`
|
|
204
|
+
: ""
|
|
205
|
+
|
|
206
|
+
return [
|
|
207
|
+
`${domain} wants you to sign in with your Ethereum account:`,
|
|
208
|
+
address,
|
|
209
|
+
"",
|
|
210
|
+
"Sign in to OpenSea",
|
|
211
|
+
"",
|
|
212
|
+
`URI: ${uri}`,
|
|
213
|
+
"Version: 1",
|
|
214
|
+
`Chain ID: ${chainId}`,
|
|
215
|
+
`Nonce: ${nonce}`,
|
|
216
|
+
`Issued At: ${issuedAt}`,
|
|
217
|
+
`Expiration Time: ${expirationTime}`,
|
|
218
|
+
...(resources ? [resources] : []),
|
|
219
|
+
].join("\n")
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** Convert a raw auth server response to a typed AuthToken. */
|
|
223
|
+
function toAuthToken(response: AuthTokenResponse): AuthToken {
|
|
224
|
+
return {
|
|
225
|
+
accessToken: response.access_token,
|
|
226
|
+
refreshToken: response.refresh_token,
|
|
227
|
+
expiresAt: new Date(Date.now() + response.expires_in * 1000),
|
|
228
|
+
scopes: response.scopes,
|
|
229
|
+
}
|
|
230
|
+
}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Configuration for the {@link OpenSeaOAuth} helper.
|
|
3
|
+
*/
|
|
4
|
+
export interface OpenSeaOAuthConfig {
|
|
5
|
+
/**
|
|
6
|
+
* Public OAuth client id (Zitadel `auth_method: none` + PKCE client).
|
|
7
|
+
* Provisioned via opensea-infrastructure; required.
|
|
8
|
+
*/
|
|
9
|
+
clientId: string
|
|
10
|
+
/** Authorization server issuer. Defaults to `https://auth.opensea.io`. */
|
|
11
|
+
issuer?: string
|
|
12
|
+
/**
|
|
13
|
+
* Per-request network timeout in milliseconds for calls to the
|
|
14
|
+
* authorization server. Defaults to 30000 (30s). Guards against a hung
|
|
15
|
+
* connection stalling `opensea login` (or an SDK consumer) indefinitely.
|
|
16
|
+
*/
|
|
17
|
+
timeoutMs?: number
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* A token set returned by the OAuth 2.1 code/PKCE or device flow.
|
|
22
|
+
*/
|
|
23
|
+
export interface OAuthToken {
|
|
24
|
+
/** JWT access token (bearer credential for the OpenSea API). */
|
|
25
|
+
accessToken: string
|
|
26
|
+
/** Refresh token for obtaining a new access token, if granted. */
|
|
27
|
+
refreshToken?: string
|
|
28
|
+
/** OIDC ID token, if `openid` scope was granted. */
|
|
29
|
+
idToken?: string
|
|
30
|
+
/** When the access token expires. */
|
|
31
|
+
expiresAt: Date
|
|
32
|
+
/** Scopes granted to this token. */
|
|
33
|
+
scopes: string[]
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Subset of the OIDC discovery document (`/.well-known/openid-configuration`)
|
|
38
|
+
* this helper relies on.
|
|
39
|
+
*/
|
|
40
|
+
export interface OAuthDiscoveryDocument {
|
|
41
|
+
issuer: string
|
|
42
|
+
authorization_endpoint: string
|
|
43
|
+
token_endpoint: string
|
|
44
|
+
device_authorization_endpoint?: string
|
|
45
|
+
revocation_endpoint?: string
|
|
46
|
+
registration_endpoint?: string
|
|
47
|
+
scopes_supported?: string[]
|
|
48
|
+
code_challenge_methods_supported?: string[]
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Raw token response from the OAuth token endpoint.
|
|
53
|
+
*/
|
|
54
|
+
export interface OAuthTokenResponse {
|
|
55
|
+
access_token: string
|
|
56
|
+
refresh_token?: string
|
|
57
|
+
id_token?: string
|
|
58
|
+
token_type: string
|
|
59
|
+
expires_in: number
|
|
60
|
+
scope?: string
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Response from the device authorization endpoint (RFC 8628).
|
|
65
|
+
*/
|
|
66
|
+
export interface DeviceAuthorizationResponse {
|
|
67
|
+
device_code: string
|
|
68
|
+
user_code: string
|
|
69
|
+
verification_uri: string
|
|
70
|
+
verification_uri_complete?: string
|
|
71
|
+
expires_in: number
|
|
72
|
+
interval?: number
|
|
73
|
+
}
|