@stxapp/stx-typescript 0.8.0 → 0.9.0-alpha.1
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 +23 -0
- package/README.md +42 -0
- package/dist/{chunk-L2DEU7R6.cjs → chunk-33AQCUGM.cjs} +53 -27
- package/dist/chunk-33AQCUGM.cjs.map +1 -0
- package/dist/{chunk-H7XZDE2U.js → chunk-4CSBA2YV.js} +53 -27
- package/dist/chunk-4CSBA2YV.js.map +1 -0
- package/dist/{client-E5Lg6k8d.d.cts → client-CNkaTuhG.d.cts} +121 -40
- package/dist/{client-E5Lg6k8d.d.ts → client-CNkaTuhG.d.ts} +121 -40
- package/dist/index.cjs +2 -2
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/oauth.cjs +374 -39
- package/dist/oauth.cjs.map +1 -1
- package/dist/oauth.d.cts +156 -11
- package/dist/oauth.d.ts +156 -11
- package/dist/oauth.js +349 -14
- package/dist/oauth.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-H7XZDE2U.js.map +0 -1
- package/dist/chunk-L2DEU7R6.cjs.map +0 -1
package/dist/oauth.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export {
|
|
1
|
+
import { av as STXAuthenticationException, g as AuthProvider, h as AuthRequest, a_ as WebSocketAuthContext, aF as STXOptions, at as STX } from './client-CNkaTuhG.cjs';
|
|
2
|
+
export { aA as STXForbiddenException, aC as STXInsufficientScopeException, aD as STXInvalidTokenException } from './client-CNkaTuhG.cjs';
|
|
3
3
|
import 'node:crypto';
|
|
4
4
|
|
|
5
5
|
interface OAuthEndpoints$1 {
|
|
@@ -37,7 +37,37 @@ 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
|
+
constructor(error: string, errorDescription: string | undefined, status: number, endpoint: string, retryAfter?: number, errorReason?: string);
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* The member came back without connecting: the callback carries
|
|
50
|
+
* `error=access_denied`. Either the member declined on the consent screen, or
|
|
51
|
+
* their STX account cannot be connected (for example it is suspended or
|
|
52
|
+
* closed). A member whose account is only still being verified gets
|
|
53
|
+
* `STXAccountPendingException` instead. Nothing was granted and no tokens
|
|
54
|
+
* exist; show your own "not connected" state.
|
|
55
|
+
*/
|
|
56
|
+
declare class STXAccessDeniedException extends STXOAuthException {
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* The member's STX account is still being verified, so STX issues no tokens
|
|
60
|
+
* for them yet. It arrives two ways:
|
|
61
|
+
*
|
|
62
|
+
* - On the callback (`error` is `account_pending`): the member signed in but
|
|
63
|
+
* cannot connect yet. No tokens exist. Show your own "we'll let you know"
|
|
64
|
+
* state and start again once STX has approved the account.
|
|
65
|
+
* - From the token endpoint (`error` is `invalid_grant`, `errorReason` is
|
|
66
|
+
* `account_pending`), on a code exchange or a refresh. On a refresh the
|
|
67
|
+
* connection has not ended: keep the stored tokens, because the same refresh
|
|
68
|
+
* token works once the member is verified. `OAuthSessionAuth` keeps them.
|
|
69
|
+
*/
|
|
70
|
+
declare class STXAccountPendingException extends STXOAuthException {
|
|
41
71
|
}
|
|
42
72
|
/**
|
|
43
73
|
* The OAuth grant is no longer valid: a refresh was rejected with
|
|
@@ -158,6 +188,8 @@ interface TokenSet {
|
|
|
158
188
|
expiresAt?: number;
|
|
159
189
|
/** Space-delimited effective scope after STX's narrowing. */
|
|
160
190
|
scope?: string;
|
|
191
|
+
/** The OpenID Connect ID token, when `openid` was granted. Verify it before trusting it (`createConnect` does). */
|
|
192
|
+
idToken?: string;
|
|
161
193
|
}
|
|
162
194
|
type OAuthEndpoints = Pick<OAuthEndpoints$1, "authorize" | "token" | "revoke" | "introspect">;
|
|
163
195
|
interface OAuthClientOptions {
|
|
@@ -231,6 +263,10 @@ interface AuthorizationParams {
|
|
|
231
263
|
/** `none` for a silent background reconnect (RFC: prompt=none). */
|
|
232
264
|
prompt?: "none" | "login" | "consent";
|
|
233
265
|
redirectUri?: string;
|
|
266
|
+
/** Go straight to a sign-in provider instead of STX's login page: `google`, `apple` or `x`. */
|
|
267
|
+
connection?: string;
|
|
268
|
+
/** The member's email, if you know it, so the provider can preselect the account. */
|
|
269
|
+
loginHint?: string;
|
|
234
270
|
/** Extra authorize params, passed through verbatim. */
|
|
235
271
|
extraParams?: Record<string, string>;
|
|
236
272
|
}
|
|
@@ -279,7 +315,7 @@ declare class OAuthClient {
|
|
|
279
315
|
}): Promise<Authorization>;
|
|
280
316
|
/**
|
|
281
317
|
* Finish a sign-in from the callback's query. Checks for an `error` from
|
|
282
|
-
* the exchange (
|
|
318
|
+
* the exchange (`access_denied`, `account_pending`), consumes the
|
|
283
319
|
* `state` (single use; unknown or expired throws `invalid_state`), exchanges
|
|
284
320
|
* the code with the stored PKCE verifier and, when `store` is given, saves
|
|
285
321
|
* the tokens under `memberKey` (a string, or a function of the `data` passed
|
|
@@ -336,7 +372,10 @@ declare class OAuthClient {
|
|
|
336
372
|
* built from this OAuth client shares one token.
|
|
337
373
|
*/
|
|
338
374
|
appToken(scope?: string | readonly string[]): AppTokenProvider;
|
|
339
|
-
/**
|
|
375
|
+
/**
|
|
376
|
+
* Revoke a token. A refresh token ends the member's grant (every token on it);
|
|
377
|
+
* an access token revokes only its pair. Always resolves on a 200.
|
|
378
|
+
*/
|
|
340
379
|
revoke(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<void>;
|
|
341
380
|
/**
|
|
342
381
|
* Unlink a member: revoke their grant at the exchange (best effort) and
|
|
@@ -384,7 +423,10 @@ declare class OAuthClient {
|
|
|
384
423
|
appClient(scope?: string | readonly string[], opts?: OAuthRestOptions): STX;
|
|
385
424
|
/** @internal The in-flight refresh map for one store; see `OAuthSessionAuth`. */
|
|
386
425
|
_refreshesFor(store: TokenStore): Map<string, Promise<StoredTokens | null>>;
|
|
387
|
-
/**
|
|
426
|
+
/**
|
|
427
|
+
* `client_secret_basic` header, or undefined for a public client. Both parts
|
|
428
|
+
* are form-urlencoded before base64, as RFC 6749 section 2.3.1 requires.
|
|
429
|
+
*/
|
|
388
430
|
basicAuthHeader(): string | undefined;
|
|
389
431
|
private formHeaders;
|
|
390
432
|
/** A public client identifies with `client_id` in the form (RFC 6749 section 4.1.3). */
|
|
@@ -467,7 +509,9 @@ declare class OAuthSessionAuth implements AuthProvider {
|
|
|
467
509
|
* Refresh with rotation, single-flight. Persists the new pair (keeping the
|
|
468
510
|
* returned refresh token; the old one only if the server omitted it). On a
|
|
469
511
|
* revoked grant, deletes the store entry and throws
|
|
470
|
-
* `STXGrantRevokedException`.
|
|
512
|
+
* `STXGrantRevokedException`. While the member's account is still being
|
|
513
|
+
* verified, keeps the store entry and throws `STXAccountPendingException`.
|
|
514
|
+
* A transient failure resolves null.
|
|
471
515
|
*/
|
|
472
516
|
refresh(refreshToken: string): Promise<StoredTokens | null>;
|
|
473
517
|
}
|
|
@@ -492,12 +536,112 @@ declare class OAuthAppAuth implements AuthProvider {
|
|
|
492
536
|
}
|
|
493
537
|
/**
|
|
494
538
|
* Validate an OAuth callback and consume its pending sign-in. Throws
|
|
495
|
-
* `
|
|
496
|
-
*
|
|
497
|
-
*
|
|
539
|
+
* `STXAccessDeniedException` (`access_denied`: the member declined, or STX did
|
|
540
|
+
* not let them connect), `STXAccountPendingException` (`account_pending`: the
|
|
541
|
+
* member's STX account is still being verified), or `STXOAuthException` with
|
|
542
|
+
* any other redirect `error`, `invalid_request` (no code or state) or
|
|
543
|
+
* `invalid_state` (unknown, used or expired). The state is checked and used up
|
|
544
|
+
* first, so an error is reported only for a sign-in this app started. Does
|
|
545
|
+
* not call the exchange.
|
|
498
546
|
*/
|
|
499
547
|
declare function readCallback(pending: PendingAuthorizationStore, callback: CallbackInput, authorizeEndpoint?: string): Promise<ReadCallback>;
|
|
500
548
|
|
|
549
|
+
/** The OpenID Connect discovery document, as far as `connect` uses it. */
|
|
550
|
+
interface OpenIDConfiguration {
|
|
551
|
+
issuer: string;
|
|
552
|
+
authorization_endpoint: string;
|
|
553
|
+
token_endpoint: string;
|
|
554
|
+
jwks_uri: string;
|
|
555
|
+
userinfo_endpoint?: string;
|
|
556
|
+
revocation_endpoint?: string;
|
|
557
|
+
id_token_signing_alg_values_supported?: string[];
|
|
558
|
+
[k: string]: unknown;
|
|
559
|
+
}
|
|
560
|
+
interface ConnectOptions {
|
|
561
|
+
/** The exchange's public URL, e.g. `https://demo.stxapp.io`. Must equal the discovery `issuer`. */
|
|
562
|
+
issuer: string;
|
|
563
|
+
clientId: string;
|
|
564
|
+
/** Your client secret. `connect` is for confidential (server-side) clients. */
|
|
565
|
+
clientSecret: string;
|
|
566
|
+
/** The redirect URI registered with STX (exact-matched). */
|
|
567
|
+
redirectUri: string;
|
|
568
|
+
/** Default scopes. `openid` is always added. */
|
|
569
|
+
scopes?: string | readonly string[];
|
|
570
|
+
/** Allowed clock skew when checking `exp` and `iat`, in seconds. Default 60. */
|
|
571
|
+
clockSkewSeconds?: number;
|
|
572
|
+
fetch?: FetchLike;
|
|
573
|
+
}
|
|
574
|
+
interface StartParams {
|
|
575
|
+
/** Go straight to a sign-in provider instead of STX's login page: `google`, `apple` or `x`. */
|
|
576
|
+
connection?: string;
|
|
577
|
+
/** The member's email, if you know it, so the provider can preselect the account. */
|
|
578
|
+
loginHint?: string;
|
|
579
|
+
/** Overrides the default scopes for this sign-in. `openid` is always added. */
|
|
580
|
+
scopes?: string | readonly string[];
|
|
581
|
+
/** Overrides the default redirect URI for this sign-in. */
|
|
582
|
+
redirectUri?: string;
|
|
583
|
+
/** `none` for a silent reconnect; `login` or `consent` to force those screens. */
|
|
584
|
+
prompt?: "none" | "login" | "consent";
|
|
585
|
+
}
|
|
586
|
+
/** What to keep in your server session between `start()` and `finish()`. */
|
|
587
|
+
interface SavedSignIn {
|
|
588
|
+
state: string;
|
|
589
|
+
codeVerifier: string;
|
|
590
|
+
nonce: string;
|
|
591
|
+
redirectUri?: string;
|
|
592
|
+
}
|
|
593
|
+
interface StartedSignIn extends SavedSignIn {
|
|
594
|
+
/** Send the member's browser here. */
|
|
595
|
+
url: string;
|
|
596
|
+
}
|
|
597
|
+
/** The member, from the verified ID token or the userinfo endpoint. */
|
|
598
|
+
interface ConnectIdentity {
|
|
599
|
+
/** Stable STX member id for your app. Key your user record on this, not on email. */
|
|
600
|
+
sub: string;
|
|
601
|
+
email?: string;
|
|
602
|
+
emailVerified?: boolean;
|
|
603
|
+
/** Every claim in the verified ID token, or in the userinfo answer. */
|
|
604
|
+
claims: Record<string, unknown>;
|
|
605
|
+
}
|
|
606
|
+
interface FinishedSignIn {
|
|
607
|
+
tokens: TokenSet & {
|
|
608
|
+
idToken: string;
|
|
609
|
+
};
|
|
610
|
+
identity: ConnectIdentity;
|
|
611
|
+
}
|
|
612
|
+
interface Connect {
|
|
613
|
+
start(params?: StartParams): Promise<StartedSignIn>;
|
|
614
|
+
finish(callback: CallbackInput, saved: SavedSignIn): Promise<FinishedSignIn>;
|
|
615
|
+
/** STX rotates refresh tokens: store whatever comes back. */
|
|
616
|
+
refresh(refreshToken: string): Promise<TokenSet>;
|
|
617
|
+
/**
|
|
618
|
+
* Revoke one token. A refresh token ends the member's whole connection (every
|
|
619
|
+
* token on it, and the next sign-in asks for consent again); an access token
|
|
620
|
+
* revokes only that pair.
|
|
621
|
+
*/
|
|
622
|
+
revoke(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<void>;
|
|
623
|
+
/**
|
|
624
|
+
* Disconnect the member: revokes the refresh token, which ends the connection
|
|
625
|
+
* at STX. Falls back to the access token when there is no refresh token.
|
|
626
|
+
*/
|
|
627
|
+
disconnect(tokens: Pick<TokenSet, "accessToken" | "refreshToken">): Promise<void>;
|
|
628
|
+
/**
|
|
629
|
+
* The member's claims from the userinfo endpoint, read with their access
|
|
630
|
+
* token (it must carry `openid`). The same claims `finish()` already
|
|
631
|
+
* verified in the ID token; use this to read them again later. Pass the
|
|
632
|
+
* `sub` you stored for the member and an answer about anyone else is
|
|
633
|
+
* refused. A dead token, or one without `openid`, throws `STXOAuthException`
|
|
634
|
+
* with `invalid_token`.
|
|
635
|
+
*/
|
|
636
|
+
userInfo(accessToken: string, expected?: {
|
|
637
|
+
sub?: string;
|
|
638
|
+
}): Promise<ConnectIdentity>;
|
|
639
|
+
/** The discovery document, fetched once and cached. */
|
|
640
|
+
configuration(): Promise<OpenIDConfiguration>;
|
|
641
|
+
}
|
|
642
|
+
/** Create a `connect` helper for one STX environment. */
|
|
643
|
+
declare function createConnect(opts: ConnectOptions): Connect;
|
|
644
|
+
|
|
501
645
|
type TokenEndpointAuthMethod = "client_secret_basic" | "none";
|
|
502
646
|
type GrantType = "authorization_code" | "refresh_token" | "client_credentials";
|
|
503
647
|
/** RFC 7591 section 2 client metadata accepted by the exchange. */
|
|
@@ -556,6 +700,7 @@ declare function registerClient(request: ClientRegistrationRequest, opts?: Regis
|
|
|
556
700
|
declare function rfcError(text: string): {
|
|
557
701
|
error: string;
|
|
558
702
|
error_description?: string;
|
|
703
|
+
error_reason?: string;
|
|
559
704
|
} | null;
|
|
560
705
|
|
|
561
706
|
/** Member scopes, in the exchange's canonical order. */
|
|
@@ -647,4 +792,4 @@ interface Pkce {
|
|
|
647
792
|
/** Generate a verifier + its S256 challenge in one call. */
|
|
648
793
|
declare function createPkce(): Promise<Pkce>;
|
|
649
794
|
|
|
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 };
|
|
795
|
+
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, 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, tokenSetToStored };
|
package/dist/oauth.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export {
|
|
1
|
+
import { av as STXAuthenticationException, g as AuthProvider, h as AuthRequest, a_ as WebSocketAuthContext, aF as STXOptions, at as STX } from './client-CNkaTuhG.js';
|
|
2
|
+
export { aA as STXForbiddenException, aC as STXInsufficientScopeException, aD as STXInvalidTokenException } from './client-CNkaTuhG.js';
|
|
3
3
|
import 'node:crypto';
|
|
4
4
|
|
|
5
5
|
interface OAuthEndpoints$1 {
|
|
@@ -37,7 +37,37 @@ 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
|
+
constructor(error: string, errorDescription: string | undefined, status: number, endpoint: string, retryAfter?: number, errorReason?: string);
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* The member came back without connecting: the callback carries
|
|
50
|
+
* `error=access_denied`. Either the member declined on the consent screen, or
|
|
51
|
+
* their STX account cannot be connected (for example it is suspended or
|
|
52
|
+
* closed). A member whose account is only still being verified gets
|
|
53
|
+
* `STXAccountPendingException` instead. Nothing was granted and no tokens
|
|
54
|
+
* exist; show your own "not connected" state.
|
|
55
|
+
*/
|
|
56
|
+
declare class STXAccessDeniedException extends STXOAuthException {
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* The member's STX account is still being verified, so STX issues no tokens
|
|
60
|
+
* for them yet. It arrives two ways:
|
|
61
|
+
*
|
|
62
|
+
* - On the callback (`error` is `account_pending`): the member signed in but
|
|
63
|
+
* cannot connect yet. No tokens exist. Show your own "we'll let you know"
|
|
64
|
+
* state and start again once STX has approved the account.
|
|
65
|
+
* - From the token endpoint (`error` is `invalid_grant`, `errorReason` is
|
|
66
|
+
* `account_pending`), on a code exchange or a refresh. On a refresh the
|
|
67
|
+
* connection has not ended: keep the stored tokens, because the same refresh
|
|
68
|
+
* token works once the member is verified. `OAuthSessionAuth` keeps them.
|
|
69
|
+
*/
|
|
70
|
+
declare class STXAccountPendingException extends STXOAuthException {
|
|
41
71
|
}
|
|
42
72
|
/**
|
|
43
73
|
* The OAuth grant is no longer valid: a refresh was rejected with
|
|
@@ -158,6 +188,8 @@ interface TokenSet {
|
|
|
158
188
|
expiresAt?: number;
|
|
159
189
|
/** Space-delimited effective scope after STX's narrowing. */
|
|
160
190
|
scope?: string;
|
|
191
|
+
/** The OpenID Connect ID token, when `openid` was granted. Verify it before trusting it (`createConnect` does). */
|
|
192
|
+
idToken?: string;
|
|
161
193
|
}
|
|
162
194
|
type OAuthEndpoints = Pick<OAuthEndpoints$1, "authorize" | "token" | "revoke" | "introspect">;
|
|
163
195
|
interface OAuthClientOptions {
|
|
@@ -231,6 +263,10 @@ interface AuthorizationParams {
|
|
|
231
263
|
/** `none` for a silent background reconnect (RFC: prompt=none). */
|
|
232
264
|
prompt?: "none" | "login" | "consent";
|
|
233
265
|
redirectUri?: string;
|
|
266
|
+
/** Go straight to a sign-in provider instead of STX's login page: `google`, `apple` or `x`. */
|
|
267
|
+
connection?: string;
|
|
268
|
+
/** The member's email, if you know it, so the provider can preselect the account. */
|
|
269
|
+
loginHint?: string;
|
|
234
270
|
/** Extra authorize params, passed through verbatim. */
|
|
235
271
|
extraParams?: Record<string, string>;
|
|
236
272
|
}
|
|
@@ -279,7 +315,7 @@ declare class OAuthClient {
|
|
|
279
315
|
}): Promise<Authorization>;
|
|
280
316
|
/**
|
|
281
317
|
* Finish a sign-in from the callback's query. Checks for an `error` from
|
|
282
|
-
* the exchange (
|
|
318
|
+
* the exchange (`access_denied`, `account_pending`), consumes the
|
|
283
319
|
* `state` (single use; unknown or expired throws `invalid_state`), exchanges
|
|
284
320
|
* the code with the stored PKCE verifier and, when `store` is given, saves
|
|
285
321
|
* the tokens under `memberKey` (a string, or a function of the `data` passed
|
|
@@ -336,7 +372,10 @@ declare class OAuthClient {
|
|
|
336
372
|
* built from this OAuth client shares one token.
|
|
337
373
|
*/
|
|
338
374
|
appToken(scope?: string | readonly string[]): AppTokenProvider;
|
|
339
|
-
/**
|
|
375
|
+
/**
|
|
376
|
+
* Revoke a token. A refresh token ends the member's grant (every token on it);
|
|
377
|
+
* an access token revokes only its pair. Always resolves on a 200.
|
|
378
|
+
*/
|
|
340
379
|
revoke(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<void>;
|
|
341
380
|
/**
|
|
342
381
|
* Unlink a member: revoke their grant at the exchange (best effort) and
|
|
@@ -384,7 +423,10 @@ declare class OAuthClient {
|
|
|
384
423
|
appClient(scope?: string | readonly string[], opts?: OAuthRestOptions): STX;
|
|
385
424
|
/** @internal The in-flight refresh map for one store; see `OAuthSessionAuth`. */
|
|
386
425
|
_refreshesFor(store: TokenStore): Map<string, Promise<StoredTokens | null>>;
|
|
387
|
-
/**
|
|
426
|
+
/**
|
|
427
|
+
* `client_secret_basic` header, or undefined for a public client. Both parts
|
|
428
|
+
* are form-urlencoded before base64, as RFC 6749 section 2.3.1 requires.
|
|
429
|
+
*/
|
|
388
430
|
basicAuthHeader(): string | undefined;
|
|
389
431
|
private formHeaders;
|
|
390
432
|
/** A public client identifies with `client_id` in the form (RFC 6749 section 4.1.3). */
|
|
@@ -467,7 +509,9 @@ declare class OAuthSessionAuth implements AuthProvider {
|
|
|
467
509
|
* Refresh with rotation, single-flight. Persists the new pair (keeping the
|
|
468
510
|
* returned refresh token; the old one only if the server omitted it). On a
|
|
469
511
|
* revoked grant, deletes the store entry and throws
|
|
470
|
-
* `STXGrantRevokedException`.
|
|
512
|
+
* `STXGrantRevokedException`. While the member's account is still being
|
|
513
|
+
* verified, keeps the store entry and throws `STXAccountPendingException`.
|
|
514
|
+
* A transient failure resolves null.
|
|
471
515
|
*/
|
|
472
516
|
refresh(refreshToken: string): Promise<StoredTokens | null>;
|
|
473
517
|
}
|
|
@@ -492,12 +536,112 @@ declare class OAuthAppAuth implements AuthProvider {
|
|
|
492
536
|
}
|
|
493
537
|
/**
|
|
494
538
|
* Validate an OAuth callback and consume its pending sign-in. Throws
|
|
495
|
-
* `
|
|
496
|
-
*
|
|
497
|
-
*
|
|
539
|
+
* `STXAccessDeniedException` (`access_denied`: the member declined, or STX did
|
|
540
|
+
* not let them connect), `STXAccountPendingException` (`account_pending`: the
|
|
541
|
+
* member's STX account is still being verified), or `STXOAuthException` with
|
|
542
|
+
* any other redirect `error`, `invalid_request` (no code or state) or
|
|
543
|
+
* `invalid_state` (unknown, used or expired). The state is checked and used up
|
|
544
|
+
* first, so an error is reported only for a sign-in this app started. Does
|
|
545
|
+
* not call the exchange.
|
|
498
546
|
*/
|
|
499
547
|
declare function readCallback(pending: PendingAuthorizationStore, callback: CallbackInput, authorizeEndpoint?: string): Promise<ReadCallback>;
|
|
500
548
|
|
|
549
|
+
/** The OpenID Connect discovery document, as far as `connect` uses it. */
|
|
550
|
+
interface OpenIDConfiguration {
|
|
551
|
+
issuer: string;
|
|
552
|
+
authorization_endpoint: string;
|
|
553
|
+
token_endpoint: string;
|
|
554
|
+
jwks_uri: string;
|
|
555
|
+
userinfo_endpoint?: string;
|
|
556
|
+
revocation_endpoint?: string;
|
|
557
|
+
id_token_signing_alg_values_supported?: string[];
|
|
558
|
+
[k: string]: unknown;
|
|
559
|
+
}
|
|
560
|
+
interface ConnectOptions {
|
|
561
|
+
/** The exchange's public URL, e.g. `https://demo.stxapp.io`. Must equal the discovery `issuer`. */
|
|
562
|
+
issuer: string;
|
|
563
|
+
clientId: string;
|
|
564
|
+
/** Your client secret. `connect` is for confidential (server-side) clients. */
|
|
565
|
+
clientSecret: string;
|
|
566
|
+
/** The redirect URI registered with STX (exact-matched). */
|
|
567
|
+
redirectUri: string;
|
|
568
|
+
/** Default scopes. `openid` is always added. */
|
|
569
|
+
scopes?: string | readonly string[];
|
|
570
|
+
/** Allowed clock skew when checking `exp` and `iat`, in seconds. Default 60. */
|
|
571
|
+
clockSkewSeconds?: number;
|
|
572
|
+
fetch?: FetchLike;
|
|
573
|
+
}
|
|
574
|
+
interface StartParams {
|
|
575
|
+
/** Go straight to a sign-in provider instead of STX's login page: `google`, `apple` or `x`. */
|
|
576
|
+
connection?: string;
|
|
577
|
+
/** The member's email, if you know it, so the provider can preselect the account. */
|
|
578
|
+
loginHint?: string;
|
|
579
|
+
/** Overrides the default scopes for this sign-in. `openid` is always added. */
|
|
580
|
+
scopes?: string | readonly string[];
|
|
581
|
+
/** Overrides the default redirect URI for this sign-in. */
|
|
582
|
+
redirectUri?: string;
|
|
583
|
+
/** `none` for a silent reconnect; `login` or `consent` to force those screens. */
|
|
584
|
+
prompt?: "none" | "login" | "consent";
|
|
585
|
+
}
|
|
586
|
+
/** What to keep in your server session between `start()` and `finish()`. */
|
|
587
|
+
interface SavedSignIn {
|
|
588
|
+
state: string;
|
|
589
|
+
codeVerifier: string;
|
|
590
|
+
nonce: string;
|
|
591
|
+
redirectUri?: string;
|
|
592
|
+
}
|
|
593
|
+
interface StartedSignIn extends SavedSignIn {
|
|
594
|
+
/** Send the member's browser here. */
|
|
595
|
+
url: string;
|
|
596
|
+
}
|
|
597
|
+
/** The member, from the verified ID token or the userinfo endpoint. */
|
|
598
|
+
interface ConnectIdentity {
|
|
599
|
+
/** Stable STX member id for your app. Key your user record on this, not on email. */
|
|
600
|
+
sub: string;
|
|
601
|
+
email?: string;
|
|
602
|
+
emailVerified?: boolean;
|
|
603
|
+
/** Every claim in the verified ID token, or in the userinfo answer. */
|
|
604
|
+
claims: Record<string, unknown>;
|
|
605
|
+
}
|
|
606
|
+
interface FinishedSignIn {
|
|
607
|
+
tokens: TokenSet & {
|
|
608
|
+
idToken: string;
|
|
609
|
+
};
|
|
610
|
+
identity: ConnectIdentity;
|
|
611
|
+
}
|
|
612
|
+
interface Connect {
|
|
613
|
+
start(params?: StartParams): Promise<StartedSignIn>;
|
|
614
|
+
finish(callback: CallbackInput, saved: SavedSignIn): Promise<FinishedSignIn>;
|
|
615
|
+
/** STX rotates refresh tokens: store whatever comes back. */
|
|
616
|
+
refresh(refreshToken: string): Promise<TokenSet>;
|
|
617
|
+
/**
|
|
618
|
+
* Revoke one token. A refresh token ends the member's whole connection (every
|
|
619
|
+
* token on it, and the next sign-in asks for consent again); an access token
|
|
620
|
+
* revokes only that pair.
|
|
621
|
+
*/
|
|
622
|
+
revoke(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<void>;
|
|
623
|
+
/**
|
|
624
|
+
* Disconnect the member: revokes the refresh token, which ends the connection
|
|
625
|
+
* at STX. Falls back to the access token when there is no refresh token.
|
|
626
|
+
*/
|
|
627
|
+
disconnect(tokens: Pick<TokenSet, "accessToken" | "refreshToken">): Promise<void>;
|
|
628
|
+
/**
|
|
629
|
+
* The member's claims from the userinfo endpoint, read with their access
|
|
630
|
+
* token (it must carry `openid`). The same claims `finish()` already
|
|
631
|
+
* verified in the ID token; use this to read them again later. Pass the
|
|
632
|
+
* `sub` you stored for the member and an answer about anyone else is
|
|
633
|
+
* refused. A dead token, or one without `openid`, throws `STXOAuthException`
|
|
634
|
+
* with `invalid_token`.
|
|
635
|
+
*/
|
|
636
|
+
userInfo(accessToken: string, expected?: {
|
|
637
|
+
sub?: string;
|
|
638
|
+
}): Promise<ConnectIdentity>;
|
|
639
|
+
/** The discovery document, fetched once and cached. */
|
|
640
|
+
configuration(): Promise<OpenIDConfiguration>;
|
|
641
|
+
}
|
|
642
|
+
/** Create a `connect` helper for one STX environment. */
|
|
643
|
+
declare function createConnect(opts: ConnectOptions): Connect;
|
|
644
|
+
|
|
501
645
|
type TokenEndpointAuthMethod = "client_secret_basic" | "none";
|
|
502
646
|
type GrantType = "authorization_code" | "refresh_token" | "client_credentials";
|
|
503
647
|
/** RFC 7591 section 2 client metadata accepted by the exchange. */
|
|
@@ -556,6 +700,7 @@ declare function registerClient(request: ClientRegistrationRequest, opts?: Regis
|
|
|
556
700
|
declare function rfcError(text: string): {
|
|
557
701
|
error: string;
|
|
558
702
|
error_description?: string;
|
|
703
|
+
error_reason?: string;
|
|
559
704
|
} | null;
|
|
560
705
|
|
|
561
706
|
/** Member scopes, in the exchange's canonical order. */
|
|
@@ -647,4 +792,4 @@ interface Pkce {
|
|
|
647
792
|
/** Generate a verifier + its S256 challenge in one call. */
|
|
648
793
|
declare function createPkce(): Promise<Pkce>;
|
|
649
794
|
|
|
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 };
|
|
795
|
+
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, 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, tokenSetToStored };
|