@okta/auth-foundation 0.6.0 → 0.9.0

package/dist/types/jwt/IDTokenValidator.d.ts

@@ -5,27 +5,70 @@
 import type { AcrValues } from '../types/index.ts';
 import type { JWT } from './JWT.ts';
 /**
+ * Contextual data, usually from the `/authorize` request, which resulted in an ID token
+ * needed to validate said `ID Token`
  * @group JWT
  */
 export interface IDTokenValidatorContext {
+    allowHTTP?: boolean;
     nonce?: string;
     maxAge?: number;
     acrValues?: AcrValues;
     supportedAlgs?: string[];
 }
 /**
+ * Performs ID token validation, conforming to {@link https://openid.net/specs/openid-connect-core-1_0.html | OIDC Spec}
+ *
+ * A default implementation is provided by this library. To override, set `OAuth2Client.idTokenValidator`
+ * ```ts
+ * const customValidator: IDTokenValidator = { ... };
+ * OAuth2Client.idTokenValidator = customValidator;
+ * ```
+ *
+ * @see
+ * * {@link https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation | OIDC Spec: ID Token Validation}
+ *
  * @group JWT
  */
 export interface IDTokenValidator {
+    /** Defines a grace period for when performing time-based validations */
     issuedAtGraceInterval: number;
+    /**
+     * By convention, a list of all validation checks performed within {@link IDTokenValidator.validate}.
+     *
+     * See {@link IDTokenValidator.validate} for more details.
+     */
     checks: IDTokenValidator.ValidationCheck[];
+    /**
+     * Validates ID tokens by performing a series of checks, listed by name in {@link IDTokenValidator.checks}
+     *
+     * @param token - The ID token to be validated
+     * @param issuer - The issuer (URL) from which the ID token was issued from
+     * @param clientId - The `client_id` from which the ID token was issued from
+     * @param context - Additional context needed to validate the ID token
+     * @throws {@link Core.JWTError | JWTError} if a validation check fails
+     *
+     * @remarks
+     * By design, {@link IDTokenValidator.checks} is a list of all validation checks performed within {@link IDTokenValidator.validate}.
+     * This is done to simplify disabling a specific check (as seen the example below). This is not a requirement however.
+     * If a custom {@link IDTokenValidator} is provided, the `validate` does not need to utilize this pattern.
+     *
+     * @example
+     * How to disable a specific validation check
+     * ```ts
+     * const currentChecks = OAuth2Client.idTokenValidator.checks;
+     * OAuth2Client.idTokenValidator.checks = currentChecks.filter(check !== 'expirationTime');
+     * // the 'expirationTime' validation check will now be skipped
+     * ```
+     *
+     * @see
+     * * {@link https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation | OIDC Spec: ID Token Validation}
+     */
     validate: (token: JWT, issuer: URL, clientId: string, context?: IDTokenValidatorContext) => void;
 }
 /**
+ * {@inheritDoc IDTokenValidator}
  * @group JWT
- *
- * @remarks
- * https://openid.net/specs/openid-connect-core-1_0-final.html#IDToken
  */
 export declare namespace IDTokenValidator {
     /**

package/dist/types/jwt/JWK.d.ts

@@ -4,18 +4,52 @@
  */
 import type { JWT } from './JWT.ts';
 /**
+ * Defines properties of a JSON Web Key
  * @group JWT
+ *
+ * @remarks
+ * Currently only `RSA`/`RS256` are supported.
+ *
+ * @see
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4 | RFC 7517 - JSON Web Key (JWK) Format}
  */
 export interface JWK extends JsonWebKey {
+    /**
+     * Key Type
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.1 | RFC 7517 - "kty" (Key Type) Parameter}
+     */
+    kty: 'RSA';
+    /**
+     * Algorithm
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.4 | RFC 7517 - "alg" (Algorithm) Parameter}
+     */
     alg: JWK.Algorithm;
+    /**
+     * Key ID
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.5 | RFC 7517 - "kid" (Key ID) Parameter}
+     */
     kid: string;
+    /**
+     * "Use" (public key use)
+     * @remarks
+     * According to RFC 7517, `sig` and `enc` are defined, but any value may be used.
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.2 | RFC 7517 - "use" (Public Key Use) Parameter}
+     */
+    use?: 'sig' | 'enc' | string;
 }
 /**
+ * Alias for `JWK[]`.
  * @group JWT
  */
 export type JWKS = JWK[];
 /**
+ * Verifies the signature of a {@link JWT} signed by a {@link JWK}.
+ * @remarks
+ * Accepts a {@link JWKS} (aka `JWK[]`) to ease use with the results of a `jwks_uri` request.
  * @group JWT
+ * @see
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7519| RFC 7519 - JSON Web Token (JWT)}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7517| RFC 7517 - JSON Web Key (JWK)}
  */
 export type JWKValidator = {
     validate: (token: JWT, keySet: JWKS) => Promise<boolean>;
@@ -23,6 +57,7 @@ export type JWKValidator = {
 /** @internal */
 export declare const DefaultJWKValidator: JWKValidator;
 /**
+ * {@inheritDoc JWK}
  * @group JWT
  */
 export declare namespace JWK {

package/dist/types/jwt/JWT.d.ts

@@ -6,41 +6,129 @@ import type { JsonRecord, RawRepresentable, Expires, TimeInterval } from '../typ
 import { JWKS } from './JWK.ts';
 import { IDTokenValidator } from './IDTokenValidator.ts';
 /**
+ * Defines registered `JWT` header parameters.
+ *
  * @group JWT
+ * @interface
+ * @useDeclaredType
+ * @see
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1 | RFC 7515 - Registered Header Parameter Names}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7519#section-5 | RFC 7519 - JOSE Header}
  */
 export interface JWTHeader {
+    /**
+     * Algorithm
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.1 | RFC 7515 - "alg" (Algorithm) Header Parameter}
+     */
     alg: string;
+    /**
+     * Key ID
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.4 | RFC 7515 - "kid" (Key ID) Header Parameter}
+     */
     kid?: string;
+    /**
+     * Type
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.9 | RFC 7515 - "typ" (Type) Header Parameter}
+     */
     typ?: string;
+    /**
+     * JWK Set URL
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2 | RFC 7515 - "jku" (JWK Set URL) Header Parameter}
+     */
+    jku?: string;
+    /**
+     * X.509 URL
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.5 | RFC 7515 - "x5u" (X.509 URL) Header Parameter}
+     */
+    x5u?: string;
+    /**
+     * X.509 Certificate SHA-1 Thumbprint
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.7 | RFC 7515 - "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter}
+     */
+    x5t?: string;
+    /**
+     * X.509 Certificate Chain
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.6 | RFC 7515 - "x5c" (X.509 Certificate Chain) Header Parameter}
+     */
+    x5c?: string;
 }
 /**
+ * Defines registered `JWT` claim names.
+ *
  * @group JWT
+ * @interface
+ * @useDeclaredType
+ * @see
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4 | RFC 7519 - Registered Claim Names}
  */
 export type JWTPayload = {
+    /**
+     * Audience
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3 | RFC 7519 - "aud" (Audience) Claim}
+     */
     aud?: string;
+    /**
+     * Issuer
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1 | RFC 7519 - "iss" (Issuer) Claim}
+     */
     iss?: string;
+    /**
+     * Subject
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2 | RFC 7519 - "sub" (Subject) Claim}
+     */
     sub?: string;
+    /**
+     * Expiration Time
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4 | RFC 7519 - "exp" (Expiration Time) Claim}
+     */
     exp?: number;
+    /**
+     * Issued At
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6 | RFC 7519 - "iat" (Issued At) Claim}
+     */
     iat?: number;
+    /**
+     * Not Before
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5 | RFC 7519 - "nbf" (Not Before) Claim}
+     */
     nbf?: number;
+    /**
+     * JWT ID
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7 | RFC 7519 - "jti" (JWT ID) Claim}
+     */
     jti?: string;
+    /**
+     * Scopes
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc8693#section-4.2 | RFC 8693 - "scope" (Scopes) Claim}
+     */
     scp?: string[];
+    /**
+     * Authentication Context Class Reference
+     * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#IDToken | OIDC Core - ID Token}
+     */
     acr?: string;
+    /**
+     * Access Token hash value
+     * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken | OIDC Core - "at_hash" Claim}
+     */
     at_hash?: string;
 } & JsonRecord;
 /**
- * A class representation of a JWT
+ * A class representation of a `JWT`
  *
  * @group JWT
  *
  * @see
- * https://datatracker.ietf.org/doc/html/rfc7519
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7519 | RFC 7519 - JSON Web Token (JWT)}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7515 | RFC 7515 - JSON Web Signature (JWS)}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7517 | RFC 7517 - JSON Web Key (JWK)}
  */
 export declare class JWT implements RawRepresentable, Expires {
     #private;
     constructor(jwtStr: string);
     /**
-     * Writes a signed JWT string
+     * Writes and signs a {@link JWT} as a `string`.
+     * @group Static Methods
      */
     static write(header: JWTHeader, claims: JsonRecord, signingKey: CryptoKey): Promise<string>;
     get header(): JWTHeader;
@@ -49,52 +137,85 @@ export declare class JWT implements RawRepresentable, Expires {
     /**
      * @remarks
      * `RawRepresentable`
-     * @returns stringified representation of the JWT
+     * @returns stringified representation of the {@link JWT}
      */
     get rawValue(): string;
     /**
+     * Alias for `JWT.claims.aud`.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3 | RFC 7519 - "aud" (Audience) Claim}
      */
     get audience(): string | undefined;
     /**
+     * Alias for `JWT.claims.exp`, converted to a {@link !Date}.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4 | RFC 7519 - "exp" (Expiration Time) Claim}
      */
     get expirationTime(): Date | undefined;
     /**
+     * Alias for `JWT.claims.exp`.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4 | RFC 7519 - "exp" (Expiration Time) Claim}
      */
     get expiresIn(): TimeInterval;
     /**
+     * Alias for `JWT.claims.iss`.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1 | RFC 7519 - "iss" (Issuer) Claim}
      */
     get issuer(): string | undefined;
     /**
+     * Alias for `JWT.claims.iat`, converted to a {@link !Date}.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6 | RFC 7519 - "iat" (Issued At) Claim}
      */
     get issuedAt(): Date | undefined;
     /**
+     * Alias for `JWT.claims.nbf`, converted to a {@link !Date}.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5 | RFC 7519 - "nbf" (Not Before) Claim}
      */
     get notBefore(): Date | undefined;
     /**
+     * Alias for `JWT.claims.scp` and `JWT.scopes`.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc8693#section-4.2 | RFC 8693 - "scope" (Scopes) Claim}
      */
     get scope(): string[] | undefined;
     /**
+     * Alias for `JWT.claims.scp` and `JWT.scope`.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc8693#section-4.2 | RFC 8693 - "scope" (Scopes) Claim}
      */
     get scopes(): string[] | undefined;
     /**
+     * Alias for `JWT.claims.sub`.
      * @group JWT Claim accessor
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2 | RFC 7519 - "sub" (Subject) Claim}
      */
     get subject(): string | undefined;
     /**
+     * Alias for `JWT.expirationTime`.
      * @group JWT Claim accessor
      */
     get expiresAt(): Date | undefined;
+    /**
+     * Compares the current time with the {@link JWT.expirationTime}.
+     *
+     * @see {@link Platform.TimeCoordinator}
+     */
     get isExpired(): boolean;
+    /**
+     * Returns `true`, if the token is not expired, compared to the {@link JWT.expirationTime}
+     */
     get isValid(): boolean;
+    /**
+     * Alias for {@link JWT.validate}.
+     */
     verifySignature(keySet: JWKS): Promise<boolean>;
+    /**
+     *
+     */
     validate(keySet: JWKS): Promise<boolean>;
     toJSON(): {
         rawValue: string;
@@ -103,5 +224,6 @@ export declare class JWT implements RawRepresentable, Expires {
 }
 /**
  * @group JWT
+ * @internal
  */
 export type JWTValidator = IDTokenValidator;

package/dist/types/jwt/TokenHashValidator.d.ts

@@ -4,7 +4,13 @@
  */
 import type { JWT } from './JWT.ts';
 /**
+ * A validator for validating tokens via hash claims. Used in OIDC to validate access tokens (`at_hash`) and
+ * device secrets (`ds_hash`) associated with an ID token
+ *
  * @group JWT
+ * @see
+ * * {@link https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowTokenValidation | OIDC Spec: Access Token Validation}
+ * * {@link https://openid.net/specs/openid-connect-native-sso-1_0.html#section-3.4.1-2.1.2.2 | OIDC Native SSO: ID Token Claims }
  */
 export interface TokenHashValidator {
     validate: (token: string, idToken: JWT) => Promise<void>;

package/dist/types/oauth2/client.d.ts

@@ -1,5 +1,21 @@
 /**
  * @module OAuth2
+ *
+ * @groupDescription DPoP
+ * Defined in {@link https://datatracker.ietf.org/doc/html/rfc9449 | RFC 9449}, Demonstrating Proof of Possession (DPoP)
+ * is a **significant** security improvement which binds OAuth2 tokens to a private/public key pair. The private key is only
+ * accessible to the requesting client. Any resource server (or `refresh_token` grant) requests made with bound tokens are
+ * required to be signed by the private key. Any requests which attempt to use bound tokens without a valid signature will be
+ * rejected. This results in a significantly improved security posture against token theft-based attacks, as tokens are nearly
+ * useless without access to the private key they are bound to.
+ *
+ * @groupDescription PKCE
+ * Defined in {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636}, Proof Key for Code Exchange (PKCE) helps protect
+ * authorization codes (returned as the query paramter `code`) when performing `Authorization Code Flow`.
+ * The client generates a cryptographically-random string and hashes it (the challenge). Both the challenge andhashing algorithm are
+ * provided to the authorization server as parameters to `/authorize`. When the client receives the `code` from the authorization server,
+ * it must provide a `code_verifier`, the orginial pre-hashed string when the `code` is exchanged for tokens. The token exchange will fail
+ * if an incorrect verifier is provided.
  */
 import type { OpenIdConfiguration, OAuth2ErrorResponse, JsonRecord } from '../types/index.ts';
 import { JWKS, IDTokenValidator, TokenHashValidator } from '../jwt/index.ts';
@@ -11,21 +27,30 @@ import { PromiseQueue } from '../utils/PromiseQueue.ts';
 import { EventEmitter } from '../utils/EventEmitter.ts';
 /**
  * @group OAuth2Client
+ * @typeParam E - Map of all events fired from {@link APIClient.emitter}
  * @noInheritDoc
  */
 export declare class OAuth2Client<E extends OAuth2Client.Events = OAuth2Client.Events> extends APIClient<E> {
     #private;
     /**
-     * @group Customizations
+     * @group Validators
      */
     static readonly idTokenValidator: IDTokenValidator;
     /**
-     * @group Customizations
+     * @group Validators
      */
     static readonly accessTokenValidator: TokenHashValidator;
     /** @internal */
     protected readonly queue: PromiseQueue;
+    /**
+     * Possible events: {@link OAuth2Client.Events}
+     */
     readonly emitter: EventEmitter<E>;
+    /**
+     * Configuration of client
+     *
+     * @remarks
+     */
     readonly configuration: OAuth2Client.Configuration;
     constructor(params: ConfigurationParams | OAuth2Client.Configuration);
     /** @internal */
@@ -43,16 +68,28 @@ export declare class OAuth2Client<E extends OAuth2Client.Events = OAuth2Client.E
     protected checkForDPoPNonceErrorResponse(response: Response): Promise<string | undefined>;
     /** @internal */
     protected prepareDPoPNonceRetry(request: APIRequest, nonce: string): Promise<void>;
+    /** @internal */
     protected signTokenRequestWithDPoP(request: APIRequest, nonce?: string): Promise<void>;
+    /** @internal */
     protected processResponse(response: Response, request: APIRequest): Promise<void>;
     /** @internal */
     protected getJson(url: URL, options?: OAuth2Client.GetJsonOptions): Promise<JsonRecord>;
+    /**
+     * Cleans up resources associated with the client instance to prevent leaks.
+     */
+    dispose(): void;
     /**
      * Retrieves the Authorization Server's OpenID configuration
+     *
+     * @see
+     * {@link https://datatracker.ietf.org/doc/html/rfc8414#section-3 | RFC 8414: Obtaining Authorization Server Metadata}
      */
     openIdConfiguration(options?: OAuth2Client.GetJsonOptions): Promise<OpenIdConfiguration>;
     /**
-     * Retrieves the Authorization Server's {@link Core.JWKS | JWKS} key configuration
+     * Retrieves authorization server's `jwks_uri` endpoint.
+     * Resulting {@link Core.JWKS | JWKS} are used to perform `id_token` validation
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc8414#section-2 | RFC 8414 - Authorization Server Metadata}
      */
     jwks(options?: OAuth2Client.GetJsonOptions): Promise<JWKS>;
     /** @internal */
@@ -60,29 +97,53 @@ export declare class OAuth2Client<E extends OAuth2Client.Events = OAuth2Client.E
     /** @internal */
     protected validateToken(request: Token.TokenRequest, keySet: JWKS, token: Token): Promise<Token | OAuth2ErrorResponse>;
     /**
-     * Attempts to exchange, and verify, a token from the provided request
+     * Attempts a `token_endpoint` request. If the request is sucessful, the resulting tokens are validated
+     *
+     * @see
+     * * {@link https://datatracker.ietf.org/doc/html/rfc8414#section-2 | RFC 8414 - Authorization Server Metadata}
+     * * {@link https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation | OIDC 1.0 - ID Token Validation}
      */
     exchange(request: Token.TokenRequest): Promise<Token | OAuth2ErrorResponse>;
     /**
-     * Attempts to refresh the provided token, using the {@link Token.Token.refreshToken | refreshToken} if it is available
+     * Attempts to refresh the provided token, using the {@link Token.refreshToken | refreshToken}
+     *
+     * @remarks
+     * Requires `offline_access` to a scope in the orginial authentication request
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc6749#section-6 | RFC 6749 - Refreshing an Access Token}
      */
     refresh(token: Token, scopes?: string[]): Promise<Token | OAuth2ErrorResponse>;
     /** @internal */
-    protected prepareRefreshRequest(token: Token, scopes?: string[]): Promise<Token | OAuth2ErrorResponse>;
+    protected sendRefreshRequest(request: Token.RefreshRequest, context: OAuth2Client.TokenRequestContext): Promise<OAuth2ErrorResponse | Token>;
     /** @internal */
     protected performRefresh(token: Token, scopes?: string[]): Promise<OAuth2ErrorResponse | Token>;
     /**
-     * Attempts to revoke the provided token
+     * Attempts a `revocation_endpoint` request with the provided {@link Token}
+     * @param token - The token to be revoked
+     * @param type - Possible values:<br/>
+     *   * `'ALL'` - revokes both the `access_token` and `refresh_token`.<br/>
+     *   * `'ACCESS'` - revokes **only** the `access_token`.<br/>
+     *   * `'REFRESH'` - revokes **only** the `refresh_token`.
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7009 | RFC 7009 - OAuth 2.0 Token Revocation }
      */
     revoke(token: Token, type: Token.RevokeType): Promise<void | OAuth2ErrorResponse>;
     /** @internal */
     protected revokeAll(token: Token): Promise<void | OAuth2ErrorResponse>;
     /**
-     * Introspects the provided token information
+     * Attempts an `introspection_endpoint` request with the provided {@link Token}
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7662 | RFC 7662 - OAuth 2.0 Token Introspection }
      */
     introspect(token: Token, kind: Token.Kind): Promise<Token.IntrospectResponse | OAuth2ErrorResponse>;
     /**
-     * Fetches the {@link UserInfo} associated with the provided token
+     * Attempts an `userinfo_endpoint` request with the provided {@link Token}
+     *
+     * @remarks
+     * The user profile returned by this method will vary based on user's profle data and organization settings
+     * @inlineType UserInfo
+     *
+     * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#UserInfo | OIDC 1.0 - UserInfo Endpoint}
      */
     userInfo(token: Token): Promise<UserInfo | OAuth2ErrorResponse>;
 }
@@ -90,8 +151,22 @@ export declare class OAuth2Client<E extends OAuth2Client.Events = OAuth2Client.E
  * @group OAuth2Client
  */
 export declare namespace OAuth2Client {
-    class Configuration extends ConfigurationConstructor {
-    }
+    /** @reexport */
+    const Configuration: typeof ConfigurationConstructor;
+    type Configuration = InstanceType<typeof ConfigurationConstructor>;
+    /**
+     * @interface
+     * Map of events fired from {@link OAuth2Client.emitter}
+     *
+     * @example
+     * ```ts
+     * // key = Event name
+     * // value = Event Type
+     * client.emitter.on('will_send', ({ request }) => {
+     *   console.log(request.url.href);
+     * });
+     * ```
+     */
     type Events = {
         /**
          * Triggered when a token refresh attempt begins
@@ -116,5 +191,14 @@ export declare namespace OAuth2Client {
     type GetJsonOptions = {
         skipCache?: boolean;
     };
+    /**
+     * When a client has the incorrect time, all DPoP JWTs signed by the client will be rejected by the
+     * authorization or resource server because the JWT's claims cannot be validated. This method checks
+     * server responses for this specific error condition.
+     *
+     * @remarks
+     * This method has only been tested against Okta authorization servers. Different IDPs may use a
+     * different `error_description`.
+     */
     function isDPoPProofClockSkewError(error: OAuth2ErrorResponse): boolean;
 }