@stxapp/stx-typescript 0.8.3 → 0.9.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/CHANGELOG.md +36 -0
- package/README.md +42 -0
- package/dist/{chunk-SIYERAKK.js → chunk-46XK6VDD.js} +406 -27
- package/dist/chunk-46XK6VDD.js.map +1 -0
- package/dist/{chunk-SI3EILHN.cjs → chunk-R77AZ5UH.cjs} +470 -91
- package/dist/chunk-R77AZ5UH.cjs.map +1 -0
- package/dist/{client-BrHjO1__.d.ts → client-B-MMKiRt.d.cts} +249 -17
- package/dist/{client-BrHjO1__.d.cts → client-B-MMKiRt.d.ts} +249 -17
- package/dist/index.cjs +14 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +13 -1
- package/dist/oauth.cjs +566 -94
- package/dist/oauth.cjs.map +1 -1
- package/dist/oauth.d.cts +264 -19
- package/dist/oauth.d.ts +264 -19
- package/dist/oauth.js +537 -65
- package/dist/oauth.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-SI3EILHN.cjs.map +0 -1
- package/dist/chunk-SIYERAKK.js.map +0 -1
package/dist/oauth.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export {
|
|
1
|
+
import { b3 as STXAuthenticationException, g as AuthProvider, h as AuthRequest, bE as WebSocketAuthContext, bi as STXOptions, b1 as STX } from './client-B-MMKiRt.cjs';
|
|
2
|
+
export { bb as STXForbiddenException, bd as STXIPNotAllowedException, be as STXInsufficientScopeException, bf as STXInvalidTokenException, bg as STXNotAvailableException, bm as STXTermsRequiredException } from './client-B-MMKiRt.cjs';
|
|
3
3
|
import 'node:crypto';
|
|
4
4
|
|
|
5
5
|
interface OAuthEndpoints$1 {
|
|
@@ -37,7 +37,56 @@ declare class STXOAuthException extends STXAuthenticationException {
|
|
|
37
37
|
readonly endpoint: string;
|
|
38
38
|
/** Seconds to wait when the endpoint answered 429 with Retry-After. */
|
|
39
39
|
readonly retryAfter: number | undefined;
|
|
40
|
-
|
|
40
|
+
/**
|
|
41
|
+
* STX's own, narrower reason, when the answer carries one. `account_pending`
|
|
42
|
+
* on an `invalid_grant` means the member's STX account is still being
|
|
43
|
+
* verified.
|
|
44
|
+
*/
|
|
45
|
+
readonly errorReason: string | undefined;
|
|
46
|
+
/**
|
|
47
|
+
* On an `invalid_scope` from the authorize callback, the scope the sign-in
|
|
48
|
+
* asked for (from the pending sign-in), so the cause can be named.
|
|
49
|
+
*/
|
|
50
|
+
requestedScope: string | undefined;
|
|
51
|
+
constructor(error: string, errorDescription: string | undefined, status: number, endpoint: string, retryAfter?: number, errorReason?: string);
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The member came back without connecting: the callback carries
|
|
55
|
+
* `error=access_denied`. Either the member declined on the consent screen, or
|
|
56
|
+
* their STX account cannot be connected (for example it is suspended or
|
|
57
|
+
* closed). A member whose account is only still being verified gets
|
|
58
|
+
* `STXAccountPendingException` instead, and one who left the STX terms page
|
|
59
|
+
* without agreeing gets `STXTermsNotAcceptedException`. Nothing was granted
|
|
60
|
+
* and no tokens exist; show your own "not connected" state.
|
|
61
|
+
*/
|
|
62
|
+
declare class STXAccessDeniedException extends STXOAuthException {
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* The member's STX account is still being verified, so STX issues no tokens
|
|
66
|
+
* for them yet. It arrives two ways:
|
|
67
|
+
*
|
|
68
|
+
* - On the callback (`error` is `account_pending`): the member signed in but
|
|
69
|
+
* cannot connect yet. No tokens exist. Show your own "we'll let you know"
|
|
70
|
+
* state and start again once STX has approved the account.
|
|
71
|
+
* - From the token endpoint (`error` is `invalid_grant`, `errorReason` is
|
|
72
|
+
* `account_pending`), on a code exchange or a refresh. On a refresh the
|
|
73
|
+
* connection has not ended: keep the stored tokens, because the same refresh
|
|
74
|
+
* token works once the member is verified. `OAuthSessionAuth` keeps them.
|
|
75
|
+
*/
|
|
76
|
+
declare class STXAccountPendingException extends STXOAuthException {
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* The member came back from the STX terms page without agreeing: the callback
|
|
80
|
+
* carries `error=terms_required`. STX shows that page during sign-in to a
|
|
81
|
+
* member who has not accepted the current terms. Nothing was granted and no
|
|
82
|
+
* tokens exist; show your own "not connected" state and let the member start
|
|
83
|
+
* again when they are ready.
|
|
84
|
+
*
|
|
85
|
+
* A member who is already connected when new terms take effect is a different
|
|
86
|
+
* case: their calls throw `STXTermsRequiredException`, which carries the page
|
|
87
|
+
* to send them to.
|
|
88
|
+
*/
|
|
89
|
+
declare class STXTermsNotAcceptedException extends STXOAuthException {
|
|
41
90
|
}
|
|
42
91
|
/**
|
|
43
92
|
* The OAuth grant is no longer valid: a refresh was rejected with
|
|
@@ -78,8 +127,10 @@ interface DiscoveryOptions {
|
|
|
78
127
|
fetch?: FetchLike;
|
|
79
128
|
}
|
|
80
129
|
/**
|
|
81
|
-
* `GET <baseUrl>/.well-known/oauth-authorization-server`. Throws
|
|
82
|
-
*
|
|
130
|
+
* `GET <baseUrl>/.well-known/oauth-authorization-server`. Throws
|
|
131
|
+
* `STXNotAvailableException` (feature `oauth`) when the exchange has no OAuth
|
|
132
|
+
* (404, or a 403 page from the edge in front of it), and `STXAPIException` on
|
|
133
|
+
* any other non-2xx or a body that is not the metadata document.
|
|
83
134
|
*/
|
|
84
135
|
declare function discoverMetadata(baseUrl?: string, opts?: DiscoveryOptions): Promise<AuthorizationServerMetadata>;
|
|
85
136
|
/** `GET <baseUrl>/.well-known/oauth-protected-resource`. */
|
|
@@ -119,6 +170,14 @@ interface StoredTokens {
|
|
|
119
170
|
expiresAt?: number;
|
|
120
171
|
/** Space-delimited effective scope granted, if the server returned it. */
|
|
121
172
|
scope?: string;
|
|
173
|
+
/**
|
|
174
|
+
* True when the last refresh said the member has not accepted the current
|
|
175
|
+
* STX terms. The tokens work; placing orders is refused until the member
|
|
176
|
+
* accepts at `termsUrl`. Absent once a later refresh no longer says so.
|
|
177
|
+
*/
|
|
178
|
+
termsRequired?: boolean;
|
|
179
|
+
/** The STX page where the member accepts the terms. Present with `termsRequired`. */
|
|
180
|
+
termsUrl?: string;
|
|
122
181
|
}
|
|
123
182
|
/**
|
|
124
183
|
* Persistence for one member's tokens. `memberKey` is any stable string the
|
|
@@ -158,6 +217,16 @@ interface TokenSet {
|
|
|
158
217
|
expiresAt?: number;
|
|
159
218
|
/** Space-delimited effective scope after STX's narrowing. */
|
|
160
219
|
scope?: string;
|
|
220
|
+
/** The OpenID Connect ID token, when `openid` was granted. Verify it before trusting it (`createConnect` does). */
|
|
221
|
+
idToken?: string;
|
|
222
|
+
/**
|
|
223
|
+
* True on a refresh when the member has not accepted the current STX terms.
|
|
224
|
+
* The refresh succeeded and the tokens work; placing orders is refused until
|
|
225
|
+
* the member accepts at `termsUrl`. Absent otherwise.
|
|
226
|
+
*/
|
|
227
|
+
termsRequired?: boolean;
|
|
228
|
+
/** The STX page where the member accepts the terms. Present with `termsRequired`. */
|
|
229
|
+
termsUrl?: string;
|
|
161
230
|
}
|
|
162
231
|
type OAuthEndpoints = Pick<OAuthEndpoints$1, "authorize" | "token" | "revoke" | "introspect">;
|
|
163
232
|
interface OAuthClientOptions {
|
|
@@ -178,6 +247,12 @@ interface OAuthClientOptions {
|
|
|
178
247
|
scope?: string | readonly string[];
|
|
179
248
|
/** Endpoint overrides; absolute URLs (from discovery) or paths. */
|
|
180
249
|
endpoints?: Partial<OAuthEndpoints>;
|
|
250
|
+
/**
|
|
251
|
+
* The exchange's discovery document, when you have it (`OAuthClient.discover()`
|
|
252
|
+
* and `fromMetadata()` set it). With it, an `invalid_scope` for a scope the
|
|
253
|
+
* exchange does not list becomes `STXNotAvailableException`.
|
|
254
|
+
*/
|
|
255
|
+
metadata?: AuthorizationServerMetadata;
|
|
181
256
|
fetch?: FetchLike;
|
|
182
257
|
}
|
|
183
258
|
/** Options for a store-backed member session adapter. */
|
|
@@ -188,6 +263,14 @@ interface SessionOptions {
|
|
|
188
263
|
onRefresh?: (tokens: StoredTokens) => void | Promise<void>;
|
|
189
264
|
/** Called once when the grant is found revoked; the store entry is already deleted. */
|
|
190
265
|
onGrantRevoked?: (err: STXGrantRevokedException) => void | Promise<void>;
|
|
266
|
+
/**
|
|
267
|
+
* Called after a refresh that says the member has not accepted the current
|
|
268
|
+
* STX terms (the new tokens are already persisted, and work). Send the
|
|
269
|
+
* member to `termsUrl` when they are next in your app.
|
|
270
|
+
*/
|
|
271
|
+
onTermsRequired?: (info: {
|
|
272
|
+
termsUrl: string;
|
|
273
|
+
}) => void | Promise<void>;
|
|
191
274
|
}
|
|
192
275
|
/** `STX` options for the `memberClient()` / `appClient()` shortcuts; host and auth come from the OAuth client. */
|
|
193
276
|
type OAuthRestOptions = Omit<STXOptions, "auth" | "keyId" | "privateKey" | "signer" | "profile" | "region" | "env" | "host">;
|
|
@@ -231,6 +314,10 @@ interface AuthorizationParams {
|
|
|
231
314
|
/** `none` for a silent background reconnect (RFC: prompt=none). */
|
|
232
315
|
prompt?: "none" | "login" | "consent";
|
|
233
316
|
redirectUri?: string;
|
|
317
|
+
/** Go straight to a sign-in provider instead of STX's login page: `google`, `apple` or `x`. */
|
|
318
|
+
connection?: string;
|
|
319
|
+
/** The member's email, if you know it, so the provider can preselect the account. */
|
|
320
|
+
loginHint?: string;
|
|
234
321
|
/** Extra authorize params, passed through verbatim. */
|
|
235
322
|
extraParams?: Record<string, string>;
|
|
236
323
|
}
|
|
@@ -241,6 +328,8 @@ declare class OAuthClient {
|
|
|
241
328
|
readonly redirectUri?: string;
|
|
242
329
|
readonly scope?: string;
|
|
243
330
|
readonly endpoints: OAuthEndpoints;
|
|
331
|
+
/** The discovery document this client was built from, if any. */
|
|
332
|
+
readonly metadata: AuthorizationServerMetadata | undefined;
|
|
244
333
|
private readonly fetch;
|
|
245
334
|
/**
|
|
246
335
|
* In-flight refreshes per token store and member, shared by every session
|
|
@@ -257,7 +346,22 @@ declare class OAuthClient {
|
|
|
257
346
|
* one the exchange advertised on the host you asked. The base URL is the
|
|
258
347
|
* issuer unless overridden.
|
|
259
348
|
*/
|
|
260
|
-
static fromMetadata(metadata: AuthorizationServerMetadata, opts: Omit<OAuthClientOptions, "endpoints">): OAuthClient;
|
|
349
|
+
static fromMetadata(metadata: AuthorizationServerMetadata, opts: Omit<OAuthClientOptions, "endpoints" | "metadata">): OAuthClient;
|
|
350
|
+
/**
|
|
351
|
+
* Fetch the exchange's discovery document and build a client from it. Throws
|
|
352
|
+
* `STXNotAvailableException` (feature `oauth`) on an exchange without OAuth,
|
|
353
|
+
* so an app can tell "not here yet" from a misconfiguration at start-up.
|
|
354
|
+
*
|
|
355
|
+
* const oauth = await OAuthClient.discover({
|
|
356
|
+
* baseUrl: "https://demo.stxapp.io",
|
|
357
|
+
* clientId: process.env.STX_CLIENT_ID!,
|
|
358
|
+
* clientSecret: process.env.STX_CLIENT_SECRET,
|
|
359
|
+
* redirectUri: "https://your.app/stx/callback",
|
|
360
|
+
* });
|
|
361
|
+
*/
|
|
362
|
+
static discover(opts: Omit<OAuthClientOptions, "endpoints" | "metadata">): Promise<OAuthClient>;
|
|
363
|
+
/** The exchange host, e.g. `"demo.stxapp.io"`. */
|
|
364
|
+
get host(): string;
|
|
261
365
|
/** True for a public client (no secret): PKCE-only, no app tokens. */
|
|
262
366
|
get isPublic(): boolean;
|
|
263
367
|
/**
|
|
@@ -279,7 +383,7 @@ declare class OAuthClient {
|
|
|
279
383
|
}): Promise<Authorization>;
|
|
280
384
|
/**
|
|
281
385
|
* Finish a sign-in from the callback's query. Checks for an `error` from
|
|
282
|
-
* the exchange (
|
|
386
|
+
* the exchange (`access_denied`, `account_pending`, `terms_required`), consumes the
|
|
283
387
|
* `state` (single use; unknown or expired throws `invalid_state`), exchanges
|
|
284
388
|
* the code with the stored PKCE verifier and, when `store` is given, saves
|
|
285
389
|
* the tokens under `memberKey` (a string, or a function of the `data` passed
|
|
@@ -291,6 +395,14 @@ declare class OAuthClient {
|
|
|
291
395
|
* for a used, expired or mismatched code).
|
|
292
396
|
*/
|
|
293
397
|
completeAuthorization(pending: PendingAuthorizationStore, callback: CallbackInput, opts?: RedeemOptions): Promise<CompletedAuthorization>;
|
|
398
|
+
/**
|
|
399
|
+
* `STXNotAvailableException` for the first scope in `requested` that the
|
|
400
|
+
* discovery document does not list, or undefined when every scope is listed
|
|
401
|
+
* or there is no document to check against.
|
|
402
|
+
*/
|
|
403
|
+
private unofferedScope;
|
|
404
|
+
/** `STXNotAvailableException` (feature `oauth`) for an OAuth endpoint the exchange does not have. */
|
|
405
|
+
private oauthMissing;
|
|
294
406
|
/**
|
|
295
407
|
* The second half of `completeAuthorization()`: exchange a callback already
|
|
296
408
|
* read with `readCallback()`. Use the pair when one callback URL serves
|
|
@@ -318,6 +430,9 @@ declare class OAuthClient {
|
|
|
318
430
|
* refresh (`invalid_grant`) means the grant was revoked, including STX's
|
|
319
431
|
* reuse detection tripping on a replayed/retired token, and surfaces as
|
|
320
432
|
* `STXGrantRevokedException`.
|
|
433
|
+
*
|
|
434
|
+
* While the member has not accepted the current STX terms the refresh still
|
|
435
|
+
* succeeds, and the result carries `termsRequired: true` and `termsUrl`.
|
|
321
436
|
*/
|
|
322
437
|
refreshToken(refreshToken: string): Promise<TokenSet>;
|
|
323
438
|
/** Alias of `refreshToken()` kept from 0.1. */
|
|
@@ -336,7 +451,10 @@ declare class OAuthClient {
|
|
|
336
451
|
* built from this OAuth client shares one token.
|
|
337
452
|
*/
|
|
338
453
|
appToken(scope?: string | readonly string[]): AppTokenProvider;
|
|
339
|
-
/**
|
|
454
|
+
/**
|
|
455
|
+
* Revoke a token. A refresh token ends the member's grant (every token on it);
|
|
456
|
+
* an access token revokes only its pair. Always resolves on a 200.
|
|
457
|
+
*/
|
|
340
458
|
revoke(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<void>;
|
|
341
459
|
/**
|
|
342
460
|
* Unlink a member: revoke their grant at the exchange (best effort) and
|
|
@@ -384,7 +502,10 @@ declare class OAuthClient {
|
|
|
384
502
|
appClient(scope?: string | readonly string[], opts?: OAuthRestOptions): STX;
|
|
385
503
|
/** @internal The in-flight refresh map for one store; see `OAuthSessionAuth`. */
|
|
386
504
|
_refreshesFor(store: TokenStore): Map<string, Promise<StoredTokens | null>>;
|
|
387
|
-
/**
|
|
505
|
+
/**
|
|
506
|
+
* `client_secret_basic` header, or undefined for a public client. Both parts
|
|
507
|
+
* are form-urlencoded before base64, as RFC 6749 section 2.3.1 requires.
|
|
508
|
+
*/
|
|
388
509
|
basicAuthHeader(): string | undefined;
|
|
389
510
|
private formHeaders;
|
|
390
511
|
/** A public client identifies with `client_id` in the form (RFC 6749 section 4.1.3). */
|
|
@@ -467,7 +588,11 @@ declare class OAuthSessionAuth implements AuthProvider {
|
|
|
467
588
|
* Refresh with rotation, single-flight. Persists the new pair (keeping the
|
|
468
589
|
* returned refresh token; the old one only if the server omitted it). On a
|
|
469
590
|
* revoked grant, deletes the store entry and throws
|
|
470
|
-
* `STXGrantRevokedException`.
|
|
591
|
+
* `STXGrantRevokedException`. While the member's account is still being
|
|
592
|
+
* verified, keeps the store entry and throws `STXAccountPendingException`.
|
|
593
|
+
* A refresh that says the member has terms to accept is a success: the pair
|
|
594
|
+
* is stored with `termsRequired` and `termsUrl`, and `onTermsRequired` runs.
|
|
595
|
+
* A transient failure resolves null.
|
|
471
596
|
*/
|
|
472
597
|
refresh(refreshToken: string): Promise<StoredTokens | null>;
|
|
473
598
|
}
|
|
@@ -492,12 +617,132 @@ declare class OAuthAppAuth implements AuthProvider {
|
|
|
492
617
|
}
|
|
493
618
|
/**
|
|
494
619
|
* Validate an OAuth callback and consume its pending sign-in. Throws
|
|
495
|
-
* `
|
|
496
|
-
*
|
|
497
|
-
*
|
|
620
|
+
* `STXAccessDeniedException` (`access_denied`: the member declined, or STX did
|
|
621
|
+
* not let them connect), `STXAccountPendingException` (`account_pending`: the
|
|
622
|
+
* member's STX account is still being verified),
|
|
623
|
+
* `STXTermsNotAcceptedException` (`terms_required`: the member left the STX
|
|
624
|
+
* terms page without agreeing), or `STXOAuthException` with
|
|
625
|
+
* any other redirect `error`, `invalid_request` (no code or state) or
|
|
626
|
+
* `invalid_state` (unknown, used or expired). The state is checked and used up
|
|
627
|
+
* first, so an error is reported only for a sign-in this app started. Does
|
|
628
|
+
* not call the exchange.
|
|
498
629
|
*/
|
|
499
630
|
declare function readCallback(pending: PendingAuthorizationStore, callback: CallbackInput, authorizeEndpoint?: string): Promise<ReadCallback>;
|
|
500
631
|
|
|
632
|
+
/**
|
|
633
|
+
* The URL to send the member's browser to so they can accept the current STX
|
|
634
|
+
* terms and come back to your app: `termsUrl` (from
|
|
635
|
+
* `STXTermsRequiredException.termsUrl`, or `termsUrl` on a refreshed token
|
|
636
|
+
* set) with `return_to` added.
|
|
637
|
+
*
|
|
638
|
+
* `returnTo` is the page in your app the member lands on afterwards. It must
|
|
639
|
+
* be one of your registered redirect URIs, or on the same origin as one. STX
|
|
640
|
+
* sends the member back to it unchanged.
|
|
641
|
+
*
|
|
642
|
+
* termsUrlWithReturn(
|
|
643
|
+
* "https://demo.stxapp.io/connect/terms?client_id=stxapp_client_9f2c41d7",
|
|
644
|
+
* "https://your.app/portfolio",
|
|
645
|
+
* );
|
|
646
|
+
* // https://demo.stxapp.io/connect/terms?client_id=stxapp_client_9f2c41d7&return_to=https%3A%2F%2Fyour.app%2Fportfolio
|
|
647
|
+
*/
|
|
648
|
+
declare function termsUrlWithReturn(termsUrl: string, returnTo: string): string;
|
|
649
|
+
|
|
650
|
+
/** The OpenID Connect discovery document, as far as `connect` uses it. */
|
|
651
|
+
interface OpenIDConfiguration {
|
|
652
|
+
issuer: string;
|
|
653
|
+
authorization_endpoint: string;
|
|
654
|
+
token_endpoint: string;
|
|
655
|
+
jwks_uri: string;
|
|
656
|
+
userinfo_endpoint?: string;
|
|
657
|
+
revocation_endpoint?: string;
|
|
658
|
+
id_token_signing_alg_values_supported?: string[];
|
|
659
|
+
[k: string]: unknown;
|
|
660
|
+
}
|
|
661
|
+
interface ConnectOptions {
|
|
662
|
+
/** The exchange's public URL, e.g. `https://demo.stxapp.io`. Must equal the discovery `issuer`. */
|
|
663
|
+
issuer: string;
|
|
664
|
+
clientId: string;
|
|
665
|
+
/** Your client secret. `connect` is for confidential (server-side) clients. */
|
|
666
|
+
clientSecret: string;
|
|
667
|
+
/** The redirect URI registered with STX (exact-matched). */
|
|
668
|
+
redirectUri: string;
|
|
669
|
+
/** Default scopes. `openid` is always added. */
|
|
670
|
+
scopes?: string | readonly string[];
|
|
671
|
+
/** Allowed clock skew when checking `exp` and `iat`, in seconds. Default 60. */
|
|
672
|
+
clockSkewSeconds?: number;
|
|
673
|
+
fetch?: FetchLike;
|
|
674
|
+
}
|
|
675
|
+
interface StartParams {
|
|
676
|
+
/** Go straight to a sign-in provider instead of STX's login page: `google`, `apple` or `x`. */
|
|
677
|
+
connection?: string;
|
|
678
|
+
/** The member's email, if you know it, so the provider can preselect the account. */
|
|
679
|
+
loginHint?: string;
|
|
680
|
+
/** Overrides the default scopes for this sign-in. `openid` is always added. */
|
|
681
|
+
scopes?: string | readonly string[];
|
|
682
|
+
/** Overrides the default redirect URI for this sign-in. */
|
|
683
|
+
redirectUri?: string;
|
|
684
|
+
/** `none` for a silent reconnect; `login` or `consent` to force those screens. */
|
|
685
|
+
prompt?: "none" | "login" | "consent";
|
|
686
|
+
}
|
|
687
|
+
/** What to keep in your server session between `start()` and `finish()`. */
|
|
688
|
+
interface SavedSignIn {
|
|
689
|
+
state: string;
|
|
690
|
+
codeVerifier: string;
|
|
691
|
+
nonce: string;
|
|
692
|
+
redirectUri?: string;
|
|
693
|
+
}
|
|
694
|
+
interface StartedSignIn extends SavedSignIn {
|
|
695
|
+
/** Send the member's browser here. */
|
|
696
|
+
url: string;
|
|
697
|
+
}
|
|
698
|
+
/** The member, from the verified ID token or the userinfo endpoint. */
|
|
699
|
+
interface ConnectIdentity {
|
|
700
|
+
/** Stable STX member id for your app. Key your user record on this, not on email. */
|
|
701
|
+
sub: string;
|
|
702
|
+
email?: string;
|
|
703
|
+
emailVerified?: boolean;
|
|
704
|
+
/** Every claim in the verified ID token, or in the userinfo answer. */
|
|
705
|
+
claims: Record<string, unknown>;
|
|
706
|
+
}
|
|
707
|
+
interface FinishedSignIn {
|
|
708
|
+
tokens: TokenSet & {
|
|
709
|
+
idToken: string;
|
|
710
|
+
};
|
|
711
|
+
identity: ConnectIdentity;
|
|
712
|
+
}
|
|
713
|
+
interface Connect {
|
|
714
|
+
start(params?: StartParams): Promise<StartedSignIn>;
|
|
715
|
+
finish(callback: CallbackInput, saved: SavedSignIn): Promise<FinishedSignIn>;
|
|
716
|
+
/** STX rotates refresh tokens: store whatever comes back. */
|
|
717
|
+
refresh(refreshToken: string): Promise<TokenSet>;
|
|
718
|
+
/**
|
|
719
|
+
* Revoke one token. A refresh token ends the member's whole connection (every
|
|
720
|
+
* token on it, and the next sign-in asks for consent again); an access token
|
|
721
|
+
* revokes only that pair.
|
|
722
|
+
*/
|
|
723
|
+
revoke(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<void>;
|
|
724
|
+
/**
|
|
725
|
+
* Disconnect the member: revokes the refresh token, which ends the connection
|
|
726
|
+
* at STX. Falls back to the access token when there is no refresh token.
|
|
727
|
+
*/
|
|
728
|
+
disconnect(tokens: Pick<TokenSet, "accessToken" | "refreshToken">): Promise<void>;
|
|
729
|
+
/**
|
|
730
|
+
* The member's claims from the userinfo endpoint, read with their access
|
|
731
|
+
* token (it must carry `openid`). The same claims `finish()` already
|
|
732
|
+
* verified in the ID token; use this to read them again later. Pass the
|
|
733
|
+
* `sub` you stored for the member and an answer about anyone else is
|
|
734
|
+
* refused. A dead token, or one without `openid`, throws `STXOAuthException`
|
|
735
|
+
* with `invalid_token`.
|
|
736
|
+
*/
|
|
737
|
+
userInfo(accessToken: string, expected?: {
|
|
738
|
+
sub?: string;
|
|
739
|
+
}): Promise<ConnectIdentity>;
|
|
740
|
+
/** The discovery document, fetched once and cached. */
|
|
741
|
+
configuration(): Promise<OpenIDConfiguration>;
|
|
742
|
+
}
|
|
743
|
+
/** Create a `connect` helper for one STX environment. */
|
|
744
|
+
declare function createConnect(opts: ConnectOptions): Connect;
|
|
745
|
+
|
|
501
746
|
type TokenEndpointAuthMethod = "client_secret_basic" | "none";
|
|
502
747
|
type GrantType = "authorization_code" | "refresh_token" | "client_credentials";
|
|
503
748
|
/** RFC 7591 section 2 client metadata accepted by the exchange. */
|
|
@@ -556,6 +801,7 @@ declare function registerClient(request: ClientRegistrationRequest, opts?: Regis
|
|
|
556
801
|
declare function rfcError(text: string): {
|
|
557
802
|
error: string;
|
|
558
803
|
error_description?: string;
|
|
804
|
+
error_reason?: string;
|
|
559
805
|
} | null;
|
|
560
806
|
|
|
561
807
|
/** Member scopes, in the exchange's canonical order. */
|
|
@@ -572,8 +818,6 @@ declare const MemberScopes: {
|
|
|
572
818
|
readonly TRANSFERS_READ: "transfers.read";
|
|
573
819
|
/** Place and cancel orders; arm `cancel_on_disconnect`. */
|
|
574
820
|
readonly ORDERS_WRITE: "orders.write";
|
|
575
|
-
/** Accept the terms and conditions. */
|
|
576
|
-
readonly TERMS_WRITE: "terms.write";
|
|
577
821
|
};
|
|
578
822
|
type MemberScope = (typeof MemberScopes)[keyof typeof MemberScopes];
|
|
579
823
|
/** App (machine) scopes for `client_credentials` tokens. */
|
|
@@ -606,8 +850,6 @@ declare const Scopes: {
|
|
|
606
850
|
readonly TRANSFERS_READ: "transfers.read";
|
|
607
851
|
/** Place and cancel orders; arm `cancel_on_disconnect`. */
|
|
608
852
|
readonly ORDERS_WRITE: "orders.write";
|
|
609
|
-
/** Accept the terms and conditions. */
|
|
610
|
-
readonly TERMS_WRITE: "terms.write";
|
|
611
853
|
};
|
|
612
854
|
type Scope = MemberScope | AppScope;
|
|
613
855
|
/** Every member scope, canonical order. */
|
|
@@ -622,7 +864,10 @@ declare const ALL_APP_SCOPES: readonly AppScope[];
|
|
|
622
864
|
declare const LEGACY_SCOPES: Readonly<Record<string, MemberScope>>;
|
|
623
865
|
/** The current name for a scope; legacy names map forward, anything else passes through. */
|
|
624
866
|
declare function canonicalScope(scope: string): string;
|
|
625
|
-
/**
|
|
867
|
+
/**
|
|
868
|
+
* Split a space-delimited `scope` string into canonical, de-duplicated scopes.
|
|
869
|
+
* Retired scopes (`terms.write` and its older name `onboarding`) are left out.
|
|
870
|
+
*/
|
|
626
871
|
declare function parseScopes(scope: string | null | undefined): string[];
|
|
627
872
|
/** Join scopes into the space-delimited wire form. */
|
|
628
873
|
declare function formatScopes(scopes: readonly string[]): string;
|
|
@@ -647,4 +892,4 @@ interface Pkce {
|
|
|
647
892
|
/** Generate a verifier + its S256 challenge in one call. */
|
|
648
893
|
declare function createPkce(): Promise<Pkce>;
|
|
649
894
|
|
|
650
|
-
export { ALL_APP_SCOPES, ALL_MEMBER_SCOPES, type AppScope, AppScopes, AppTokenProvider, type Authorization, type AuthorizationParams, type AuthorizationServerMetadata, type CallbackInput, type ClientRegistration, type ClientRegistrationRequest, type CompletedAuthorization, DEFAULT_ENDPOINTS, type DiscoveryOptions, type FetchLike, type GrantType, LEGACY_SCOPES, type MemberScope, MemberScopes, MemoryPendingAuthorizationStore, MemoryTokenStore, OAuthAppAuth, OAuthBearerAuth, OAuthClient, type OAuthClientOptions, type OAuthEndpoints$1 as OAuthEndpoints, type OAuthRestOptions, OAuthSessionAuth, type PendingAuthorization, type PendingAuthorizationStore, type Pkce, type ProtectedResourceMetadata, type ReadCallback, type RedeemOptions, type RegisterClientOptions, STXAuthenticationException, STXGrantRevokedException, STXOAuthException, type Scope, Scopes, type SessionOptions, type StoredTokens, type TokenEndpointAuthMethod, type TokenSet, type TokenStore, WELL_KNOWN, base64url, canonicalScope, codeChallengeS256, createPkce, discoverMetadata, discoverProtectedResource, formatScopes, generateCodeVerifier, generateState, isAppScope, isMemberScope, joinUrl, parseScopes, parseTokenResponse, readCallback, registerClient, rfcError, tokenSetToStored };
|
|
895
|
+
export { ALL_APP_SCOPES, ALL_MEMBER_SCOPES, type AppScope, AppScopes, AppTokenProvider, type Authorization, type AuthorizationParams, type AuthorizationServerMetadata, type CallbackInput, type ClientRegistration, type ClientRegistrationRequest, type CompletedAuthorization, type Connect, type ConnectIdentity, type ConnectOptions, DEFAULT_ENDPOINTS, type DiscoveryOptions, type FetchLike, type FinishedSignIn, type GrantType, LEGACY_SCOPES, type MemberScope, MemberScopes, MemoryPendingAuthorizationStore, MemoryTokenStore, OAuthAppAuth, OAuthBearerAuth, OAuthClient, type OAuthClientOptions, type OAuthEndpoints$1 as OAuthEndpoints, type OAuthRestOptions, OAuthSessionAuth, type OpenIDConfiguration, type PendingAuthorization, type PendingAuthorizationStore, type Pkce, type ProtectedResourceMetadata, type ReadCallback, type RedeemOptions, type RegisterClientOptions, STXAccessDeniedException, STXAccountPendingException, STXAuthenticationException, STXGrantRevokedException, STXOAuthException, STXTermsNotAcceptedException, type SavedSignIn, type Scope, Scopes, type SessionOptions, type StartParams, type StartedSignIn, type StoredTokens, type TokenEndpointAuthMethod, type TokenSet, type TokenStore, WELL_KNOWN, base64url, canonicalScope, codeChallengeS256, createConnect, createPkce, discoverMetadata, discoverProtectedResource, formatScopes, generateCodeVerifier, generateState, isAppScope, isMemberScope, joinUrl, parseScopes, parseTokenResponse, readCallback, registerClient, rfcError, termsUrlWithReturn, tokenSetToStored };
|