@opensea/sdk 11.1.0 → 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 +46 -12
- 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 +51 -11
- 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,168 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.OpenSeaAuth = void 0;
|
|
4
|
+
exports.generateSiweMessage = generateSiweMessage;
|
|
5
|
+
const DEFAULT_AUTH_BASE_URL = "https://auth.opensea.io";
|
|
6
|
+
/** Buffer (in ms) before expiry at which auto-refresh triggers. */
|
|
7
|
+
const REFRESH_BUFFER_MS = 60_000;
|
|
8
|
+
/**
|
|
9
|
+
* SIWE-based authentication helper for OpenSea.
|
|
10
|
+
*
|
|
11
|
+
* Handles the full sign-in flow: nonce request, EIP-4361 message generation,
|
|
12
|
+
* signature exchange, token caching, and automatic refresh.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```ts
|
|
16
|
+
* import { OpenSeaAuth } from "@opensea/sdk"
|
|
17
|
+
*
|
|
18
|
+
* const auth = new OpenSeaAuth()
|
|
19
|
+
* const token = await auth.authenticate(signer, {
|
|
20
|
+
* scopes: ["read:eligibility", "write:orders"],
|
|
21
|
+
* })
|
|
22
|
+
*
|
|
23
|
+
* // Auto-refresh before expiry
|
|
24
|
+
* const freshToken = await auth.getValidToken()
|
|
25
|
+
*
|
|
26
|
+
* // Revoke
|
|
27
|
+
* await auth.revoke(token.accessToken)
|
|
28
|
+
* ```
|
|
29
|
+
*
|
|
30
|
+
* @category Authentication
|
|
31
|
+
*/
|
|
32
|
+
class OpenSeaAuth {
|
|
33
|
+
authBaseUrl;
|
|
34
|
+
cachedToken;
|
|
35
|
+
constructor(config = {}) {
|
|
36
|
+
this.authBaseUrl = (config.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Run the full SIWE authentication flow:
|
|
40
|
+
* 1. Request a nonce from the auth server
|
|
41
|
+
* 2. Build an EIP-4361 SIWE message
|
|
42
|
+
* 3. Sign it with the provided signer
|
|
43
|
+
* 4. Exchange the signature for a scoped JWT token
|
|
44
|
+
*
|
|
45
|
+
* The returned token is cached in memory and will be auto-refreshed
|
|
46
|
+
* by {@link getValidToken}.
|
|
47
|
+
*/
|
|
48
|
+
async authenticate(signer, options = {}) {
|
|
49
|
+
const address = await signer.getAddress();
|
|
50
|
+
const { nonce } = await this.requestNonce();
|
|
51
|
+
const message = generateSiweMessage(address, options.scopes ?? [], nonce, this.authBaseUrl);
|
|
52
|
+
const signature = await signer.signMessage(message);
|
|
53
|
+
const tokenResponse = await this.exchangeSignature(message, signature);
|
|
54
|
+
const token = toAuthToken(tokenResponse);
|
|
55
|
+
this.cachedToken = token;
|
|
56
|
+
return token;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Return a valid access token, refreshing automatically if the cached
|
|
60
|
+
* token is expired or about to expire.
|
|
61
|
+
*
|
|
62
|
+
* @throws If no token has been obtained yet via {@link authenticate}.
|
|
63
|
+
*/
|
|
64
|
+
async getValidToken() {
|
|
65
|
+
if (!this.cachedToken) {
|
|
66
|
+
throw new Error("No auth token available. Call authenticate() with a signer first.");
|
|
67
|
+
}
|
|
68
|
+
if (this.cachedToken.expiresAt.getTime() - Date.now() < REFRESH_BUFFER_MS) {
|
|
69
|
+
const tokenResponse = await this.refreshToken(this.cachedToken.refreshToken);
|
|
70
|
+
this.cachedToken = toAuthToken(tokenResponse);
|
|
71
|
+
}
|
|
72
|
+
return this.cachedToken;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Revoke an access token.
|
|
76
|
+
*/
|
|
77
|
+
async revoke(accessToken) {
|
|
78
|
+
const response = await fetch(`${this.authBaseUrl}/api/revoke`, {
|
|
79
|
+
method: "POST",
|
|
80
|
+
headers: { "Content-Type": "application/json" },
|
|
81
|
+
body: JSON.stringify({ token: accessToken }),
|
|
82
|
+
});
|
|
83
|
+
if (!response.ok) {
|
|
84
|
+
throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
|
|
85
|
+
}
|
|
86
|
+
if (this.cachedToken?.accessToken === accessToken) {
|
|
87
|
+
this.cachedToken = undefined;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
/** Request a nonce from the auth server. */
|
|
91
|
+
async requestNonce() {
|
|
92
|
+
const response = await fetch(`${this.authBaseUrl}/api/nonce`, {
|
|
93
|
+
method: "GET",
|
|
94
|
+
headers: { Accept: "application/json" },
|
|
95
|
+
});
|
|
96
|
+
if (!response.ok) {
|
|
97
|
+
throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
|
|
98
|
+
}
|
|
99
|
+
return response.json();
|
|
100
|
+
}
|
|
101
|
+
/** Exchange a signed SIWE message for a JWT token. */
|
|
102
|
+
async exchangeSignature(message, signature) {
|
|
103
|
+
const response = await fetch(`${this.authBaseUrl}/api/token`, {
|
|
104
|
+
method: "POST",
|
|
105
|
+
headers: { "Content-Type": "application/json" },
|
|
106
|
+
body: JSON.stringify({ message, signature }),
|
|
107
|
+
});
|
|
108
|
+
if (!response.ok) {
|
|
109
|
+
throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
|
|
110
|
+
}
|
|
111
|
+
return response.json();
|
|
112
|
+
}
|
|
113
|
+
/** Refresh an access token using a refresh token. */
|
|
114
|
+
async refreshToken(refreshTokenValue) {
|
|
115
|
+
const response = await fetch(`${this.authBaseUrl}/api/refresh`, {
|
|
116
|
+
method: "POST",
|
|
117
|
+
headers: { "Content-Type": "application/json" },
|
|
118
|
+
body: JSON.stringify({ refresh_token: refreshTokenValue }),
|
|
119
|
+
});
|
|
120
|
+
if (!response.ok) {
|
|
121
|
+
throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
|
|
122
|
+
}
|
|
123
|
+
return response.json();
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
exports.OpenSeaAuth = OpenSeaAuth;
|
|
127
|
+
/** Validity window (in ms) for a generated SIWE message. */
|
|
128
|
+
const SIWE_MESSAGE_VALIDITY_MS = 10 * 60_000;
|
|
129
|
+
/**
|
|
130
|
+
* Build an EIP-4361 (SIWE) message for OpenSea authentication.
|
|
131
|
+
*
|
|
132
|
+
* @see https://eips.ethereum.org/EIPS/eip-4361
|
|
133
|
+
*/
|
|
134
|
+
function generateSiweMessage(address, scopes, nonce, authBaseUrl, chainId = 1) {
|
|
135
|
+
const url = new URL(authBaseUrl);
|
|
136
|
+
const domain = url.host;
|
|
137
|
+
const uri = `${authBaseUrl}/api/token`;
|
|
138
|
+
const now = Date.now();
|
|
139
|
+
const issuedAt = new Date(now).toISOString();
|
|
140
|
+
const expirationTime = new Date(now + SIWE_MESSAGE_VALIDITY_MS).toISOString();
|
|
141
|
+
const resources = scopes.length > 0
|
|
142
|
+
? `\nResources:${scopes.map(s => `\n- ${s}`).join("")}`
|
|
143
|
+
: "";
|
|
144
|
+
return [
|
|
145
|
+
`${domain} wants you to sign in with your Ethereum account:`,
|
|
146
|
+
address,
|
|
147
|
+
"",
|
|
148
|
+
"Sign in to OpenSea",
|
|
149
|
+
"",
|
|
150
|
+
`URI: ${uri}`,
|
|
151
|
+
"Version: 1",
|
|
152
|
+
`Chain ID: ${chainId}`,
|
|
153
|
+
`Nonce: ${nonce}`,
|
|
154
|
+
`Issued At: ${issuedAt}`,
|
|
155
|
+
`Expiration Time: ${expirationTime}`,
|
|
156
|
+
...(resources ? [resources] : []),
|
|
157
|
+
].join("\n");
|
|
158
|
+
}
|
|
159
|
+
/** Convert a raw auth server response to a typed AuthToken. */
|
|
160
|
+
function toAuthToken(response) {
|
|
161
|
+
return {
|
|
162
|
+
accessToken: response.access_token,
|
|
163
|
+
refreshToken: response.refresh_token,
|
|
164
|
+
expiresAt: new Date(Date.now() + response.expires_in * 1000),
|
|
165
|
+
scopes: response.scopes,
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,69 @@
|
|
|
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
|
+
* A token set returned by the OAuth 2.1 code/PKCE or device flow.
|
|
21
|
+
*/
|
|
22
|
+
export interface OAuthToken {
|
|
23
|
+
/** JWT access token (bearer credential for the OpenSea API). */
|
|
24
|
+
accessToken: string;
|
|
25
|
+
/** Refresh token for obtaining a new access token, if granted. */
|
|
26
|
+
refreshToken?: string;
|
|
27
|
+
/** OIDC ID token, if `openid` scope was granted. */
|
|
28
|
+
idToken?: string;
|
|
29
|
+
/** When the access token expires. */
|
|
30
|
+
expiresAt: Date;
|
|
31
|
+
/** Scopes granted to this token. */
|
|
32
|
+
scopes: string[];
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Subset of the OIDC discovery document (`/.well-known/openid-configuration`)
|
|
36
|
+
* this helper relies on.
|
|
37
|
+
*/
|
|
38
|
+
export interface OAuthDiscoveryDocument {
|
|
39
|
+
issuer: string;
|
|
40
|
+
authorization_endpoint: string;
|
|
41
|
+
token_endpoint: string;
|
|
42
|
+
device_authorization_endpoint?: string;
|
|
43
|
+
revocation_endpoint?: string;
|
|
44
|
+
registration_endpoint?: string;
|
|
45
|
+
scopes_supported?: string[];
|
|
46
|
+
code_challenge_methods_supported?: string[];
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Raw token response from the OAuth token endpoint.
|
|
50
|
+
*/
|
|
51
|
+
export interface OAuthTokenResponse {
|
|
52
|
+
access_token: string;
|
|
53
|
+
refresh_token?: string;
|
|
54
|
+
id_token?: string;
|
|
55
|
+
token_type: string;
|
|
56
|
+
expires_in: number;
|
|
57
|
+
scope?: string;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Response from the device authorization endpoint (RFC 8628).
|
|
61
|
+
*/
|
|
62
|
+
export interface DeviceAuthorizationResponse {
|
|
63
|
+
device_code: string;
|
|
64
|
+
user_code: string;
|
|
65
|
+
verification_uri: string;
|
|
66
|
+
verification_uri_complete?: string;
|
|
67
|
+
expires_in: number;
|
|
68
|
+
interval?: number;
|
|
69
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"oauth-types.js","sourceRoot":"","sources":["../../src/auth/oauth-types.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import type { DeviceAuthorizationResponse, OAuthDiscoveryDocument, OAuthToken, OpenSeaOAuthConfig } from "./oauth-types";
|
|
2
|
+
/**
|
|
3
|
+
* OAuth 2.1 authorization-code + PKCE helper for OpenSea (OS2-33722).
|
|
4
|
+
*
|
|
5
|
+
* Runs the standard flow against the OpenSea authorization server (Zitadel at
|
|
6
|
+
* `auth.opensea.io`) using a public client — no client secret, no private key,
|
|
7
|
+
* no SIWE message signing. This is the same flow spec-compliant MCP clients
|
|
8
|
+
* discover via the MCP server's Protected Resource Metadata, exposed here for
|
|
9
|
+
* programmatic consumers (the CLI's keyless `opensea login` is built on it).
|
|
10
|
+
*
|
|
11
|
+
* Endpoints are resolved from OIDC discovery
|
|
12
|
+
* (`/.well-known/openid-configuration`) rather than hardcoded.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```ts
|
|
16
|
+
* const oauth = new OpenSeaOAuth({ clientId: "..." })
|
|
17
|
+
*
|
|
18
|
+
* // Authorization code + PKCE (browser-capable environments)
|
|
19
|
+
* const req = await oauth.createAuthorizationRequest({
|
|
20
|
+
* redirectUri: "http://127.0.0.1:8151/callback",
|
|
21
|
+
* scopes: ["read:eligibility"],
|
|
22
|
+
* })
|
|
23
|
+
* // ...direct the user to req.url, receive `code` + `state` on the redirect...
|
|
24
|
+
* const token = await oauth.exchangeCode({
|
|
25
|
+
* code,
|
|
26
|
+
* codeVerifier: req.codeVerifier,
|
|
27
|
+
* redirectUri: "http://127.0.0.1:8151/callback",
|
|
28
|
+
* })
|
|
29
|
+
*
|
|
30
|
+
* // Device flow (headless environments)
|
|
31
|
+
* const device = await oauth.requestDeviceAuthorization()
|
|
32
|
+
* // ...show device.user_code + device.verification_uri to the user...
|
|
33
|
+
* const token2 = await oauth.pollDeviceToken(device)
|
|
34
|
+
* ```
|
|
35
|
+
*
|
|
36
|
+
* @category Authentication
|
|
37
|
+
*/
|
|
38
|
+
export declare class OpenSeaOAuth {
|
|
39
|
+
private readonly issuer;
|
|
40
|
+
private readonly clientId;
|
|
41
|
+
private readonly timeoutMs;
|
|
42
|
+
private discovery;
|
|
43
|
+
constructor(config: OpenSeaOAuthConfig);
|
|
44
|
+
/**
|
|
45
|
+
* Fetch (and cache) the OIDC discovery document for the issuer, then
|
|
46
|
+
* validate it: the advertised `issuer` must match the configured issuer
|
|
47
|
+
* (OpenID Connect Discovery §4.3 / OAuth 2.1 mix-up defense) and the
|
|
48
|
+
* authorization/token endpoints must be secure (`https:`, or loopback for
|
|
49
|
+
* local testing). This prevents a compromised discovery response from
|
|
50
|
+
* redirecting the flow to an attacker-controlled endpoint.
|
|
51
|
+
*/
|
|
52
|
+
getDiscovery(): Promise<OAuthDiscoveryDocument>;
|
|
53
|
+
/**
|
|
54
|
+
* Build an authorization request for the code + PKCE flow. Returns the URL
|
|
55
|
+
* to open in a browser plus the `codeVerifier` and `state` the caller must
|
|
56
|
+
* hold on to for {@link exchangeCode} and redirect validation.
|
|
57
|
+
*/
|
|
58
|
+
createAuthorizationRequest(options: {
|
|
59
|
+
redirectUri: string;
|
|
60
|
+
scopes?: string[];
|
|
61
|
+
}): Promise<{
|
|
62
|
+
url: string;
|
|
63
|
+
codeVerifier: string;
|
|
64
|
+
state: string;
|
|
65
|
+
}>;
|
|
66
|
+
/** Exchange an authorization code (plus PKCE verifier) for tokens. */
|
|
67
|
+
exchangeCode(options: {
|
|
68
|
+
code: string;
|
|
69
|
+
codeVerifier: string;
|
|
70
|
+
redirectUri: string;
|
|
71
|
+
}): Promise<OAuthToken>;
|
|
72
|
+
/** Refresh an access token using a refresh token. */
|
|
73
|
+
refresh(refreshToken: string): Promise<OAuthToken>;
|
|
74
|
+
/** Revoke an access or refresh token. */
|
|
75
|
+
revoke(token: string): Promise<void>;
|
|
76
|
+
/**
|
|
77
|
+
* Start a device authorization flow (RFC 8628) — for headless environments
|
|
78
|
+
* where a browser redirect is not possible.
|
|
79
|
+
*/
|
|
80
|
+
requestDeviceAuthorization(options?: {
|
|
81
|
+
scopes?: string[];
|
|
82
|
+
}): Promise<DeviceAuthorizationResponse>;
|
|
83
|
+
/**
|
|
84
|
+
* Poll the token endpoint until the user completes device authorization.
|
|
85
|
+
* Respects the server-provided `interval` and `slow_down` responses, and
|
|
86
|
+
* stops when `expires_in` elapses.
|
|
87
|
+
*/
|
|
88
|
+
pollDeviceToken(device: DeviceAuthorizationResponse): Promise<OAuthToken>;
|
|
89
|
+
private postToken;
|
|
90
|
+
/**
|
|
91
|
+
* `fetch` wrapper that aborts the request after `this.timeoutMs`, so a hung
|
|
92
|
+
* authorization server can't stall the flow indefinitely.
|
|
93
|
+
*/
|
|
94
|
+
private fetchWithTimeout;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Read the wallet address from decoded JWT claims. Zitadel injects it as a
|
|
98
|
+
* top-level `wallet` claim (plaintext) via the `inject_wallet_claim` action —
|
|
99
|
+
* the same claim `opensea-mcp` and the os2-core REST API read. `sub` is the
|
|
100
|
+
* fallback identifier (the Zitadel account id) when no wallet claim is present.
|
|
101
|
+
* Returns `undefined` if neither is available.
|
|
102
|
+
*/
|
|
103
|
+
export declare function extractWalletAddress(claims: Record<string, unknown>): string | undefined;
|
|
104
|
+
/**
|
|
105
|
+
* Decode a JWT payload without verifying the signature. Intended for reading
|
|
106
|
+
* claims out of a token the authorization server just issued to us over TLS —
|
|
107
|
+
* NOT for validating inbound tokens.
|
|
108
|
+
*/
|
|
109
|
+
export declare function decodeJwtPayload(token: string): Record<string, unknown>;
|