oauth4webapi 2.4.0 → 2.4.1

package/README.md

@@ -41,7 +41,7 @@ import * as oauth2 from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.4.0/mod.ts'
+import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.4.1/mod.ts'
 ```
 
 - Authorization Code Flow - OpenID Connect [source](examples/code.ts), or plain OAuth 2 [source](examples/oauth.ts)

package/build/index.d.ts

@@ -1,9 +1,13 @@
-type JsonObject = {
+/** JSON Object */
+export type JsonObject = {
     [Key in string]?: JsonValue;
 };
-type JsonArray = JsonValue[];
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/** JSON Array */
+export type JsonArray = JsonValue[];
+/** JSON Primitives */
+export type JsonPrimitive = string | number | boolean | null;
+/** JSON Values */
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 /**
  * Interface to pass an asymmetric private key and, optionally, its associated JWK Key ID to be
  * added as a `kid` JOSE Header Parameter.
@@ -45,7 +49,9 @@ export type ClientAuthenticationMethod = 'client_secret_basic' | 'client_secret_
 /**
  * Supported JWS `alg` Algorithm identifiers.
  *
- * @example CryptoKey algorithm for the `PS256`, `PS384`, or `PS512` JWS Algorithm Identifiers
+ * @example
+ *
+ * CryptoKey algorithm for the `PS256`, `PS384`, or `PS512` JWS Algorithm Identifiers
  *
  * ```ts
  * interface PS256 extends RsaHashedKeyAlgorithm {
@@ -64,7 +70,9 @@ export type ClientAuthenticationMethod = 'client_secret_basic' | 'client_secret_
  * }
  * ```
  *
- * @example CryptoKey algorithm for the `ES256`, `ES384`, or `ES512` JWS Algorithm Identifiers
+ * @example
+ *
+ * CryptoKey algorithm for the `ES256`, `ES384`, or `ES512` JWS Algorithm Identifiers
  *
  * ```ts
  * interface ES256 extends EcKeyAlgorithm {
@@ -83,7 +91,9 @@ export type ClientAuthenticationMethod = 'client_secret_basic' | 'client_secret_
  * }
  * ```
  *
- * @example CryptoKey algorithm for the `RS256`, `RS384`, or `RS512` JWS Algorithm Identifiers
+ * @example
+ *
+ * CryptoKey algorithm for the `RS256`, `RS384`, or `RS512` JWS Algorithm Identifiers
  *
  * ```ts
  * interface RS256 extends RsaHashedKeyAlgorithm {
@@ -102,9 +112,11 @@ export type ClientAuthenticationMethod = 'client_secret_basic' | 'client_secret_
  * }
  * ```
  *
- * @example CryptoKey algorithm for the `EdDSA` JWS Algorithm Identifier (Experimental)
+ * @example
  *
- * Runtime support for this algorithm is very limited, it depends on the [Secure Curves in the Web
+ * CryptoKey algorithm for the `EdDSA` JWS Algorithm Identifier (Experimental)
+ *
+ * Runtime support for this algorithm is limited, it depends on the [Secure Curves in the Web
  * Cryptography API](https://wicg.github.io/webcrypto-secure-curves/) proposal which is yet to be
  * widely adopted. If the proposal changes this implementation will follow up with a minor release.
  *
@@ -473,7 +485,7 @@ export interface Client {
      *
      * @ignore during Documentation generation but part of the public API
      *
-     * @example Tolerate 30 seconds clock skew when validating JWT claims like `exp` or `nbf`.
+     * @example Tolerate 30 seconds clock skew when validating JWT claims like exp or nbf.
      *
      * ```ts
      * const client: oauth.Client = {
@@ -486,9 +498,11 @@ export interface Client {
     [clockTolerance]?: number;
     [metadata: string]: JsonValue | undefined;
 }
+/** @group Errors */
 export declare class UnsupportedOperationError extends Error {
     constructor(message?: string);
 }
+/** @group Errors */
 export declare class OperationProcessingError extends Error {
     constructor(message: string, options?: {
         cause?: unknown;
@@ -499,7 +513,9 @@ export interface HttpRequestOptions {
      * An AbortSignal instance, or a factory returning one, to abort the HTTP Request(s) triggered by
      * this function's invocation.
      *
-     * @example A 5000ms timeout AbortSignal for every request
+     * @example
+     *
+     * A 5000ms timeout AbortSignal for every request
      *
      * ```js
      * const signal = () => AbortSignal.timeout(5_000) // Note: AbortSignal.timeout may not yet be available in all runtimes.
@@ -526,6 +542,9 @@ export interface DiscoveryRequestOptions extends HttpRequestOptions {
  *
  * @param issuerIdentifier Issuer Identifier to resolve the well-known discovery URI for.
  *
+ * @group Authorization Server Metadata
+ * @group OpenID Connect (OIDC) Discovery
+ *
  * @see [RFC 8414 - OAuth 2.0 Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414.html#section-3)
  * @see [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
  */
@@ -539,6 +558,9 @@ export declare function discoveryRequest(issuerIdentifier: URL, options?: Discov
  *
  * @returns Resolves with the discovered Authorization Server Metadata.
  *
+ * @group Authorization Server Metadata
+ * @group OpenID Connect (OIDC) Discovery
+ *
  * @see [RFC 8414 - OAuth 2.0 Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414.html#section-3)
  * @see [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
  */
@@ -546,18 +568,27 @@ export declare function processDiscoveryResponse(expectedIssuerIdentifier: URL,
 /**
  * Generate random `code_verifier` value.
  *
+ * @group Utilities
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group Proof Key for Code Exchange by OAuth Public Clients (PKCE)
+ *
  * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
  */
 export declare function generateRandomCodeVerifier(): string;
 /**
  * Generate random `state` value.
  *
+ * @group Utilities
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.1)
  */
 export declare function generateRandomState(): string;
 /**
  * Generate random `nonce` value.
  *
+ * @group Utilities
+ *
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)
  */
 export declare function generateRandomNonce(): string;
@@ -567,6 +598,10 @@ export declare function generateRandomNonce(): string;
  *
  * @param codeVerifier `code_verifier` value generated e.g. from {@link generateRandomCodeVerifier}.
  *
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group Proof Key for Code Exchange by OAuth Public Clients (PKCE)
+ *
  * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
  */
 export declare function calculatePKCECodeChallenge(codeVerifier: string): Promise<string>;
@@ -607,6 +642,10 @@ export interface PushedAuthorizationRequestOptions extends HttpRequestOptions, A
  * @param client Client Metadata.
  * @param privateKey Private key to sign the Request Object with.
  *
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group JWT-Secured Authorization Request (JAR)
+ *
  * @see [RFC 9101 - The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)](https://www.rfc-editor.org/rfc/rfc9101.html#name-request-object-2)
  */
 export declare function issueRequestObject(as: AuthorizationServer, client: Client, parameters: URLSearchParams | Record<string, string> | string[][], privateKey: CryptoKey | PrivateKey): Promise<string>;
@@ -618,7 +657,9 @@ export declare function issueRequestObject(as: AuthorizationServer, client: Clie
  * @param client Client Metadata.
  * @param parameters Authorization Request parameters.
  *
- * @see [RFC 9126 - OAuth 2.0 Pushed Authorization Requests](https://www.rfc-editor.org/rfc/rfc9126.html#name-pushed-authorization-reques)
+ * @group Pushed Authorization Requests (PAR)
+ *
+ * @see [RFC 9126 - OAuth 2.0 Pushed Authorization Requests (PAR)](https://www.rfc-editor.org/rfc/rfc9126.html#name-pushed-authorization-reques)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-dpop-with-pushed-authorizat)
  */
 export declare function pushedAuthorizationRequest(as: AuthorizationServer, client: Client, parameters: URLSearchParams | Record<string, string> | string[][], options?: PushedAuthorizationRequestOptions): Promise<Response>;
@@ -635,7 +676,19 @@ export interface OAuth2Error {
     readonly scope?: string;
     readonly [parameter: string]: JsonValue | undefined;
 }
-/** A helper function used to determine if a response processing function returned an OAuth2Error. */
+/**
+ * A helper function used to determine if a response processing function returned an OAuth2Error.
+ *
+ * @group Utilities
+ * @group Client Credentials Grant
+ * @group Device Authorization Grant
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group Token Introspection
+ * @group Token Revocation
+ * @group Refreshing an Access Token
+ * @group Pushed Authorization Requests (PAR)
+ */
 export declare function isOAuth2Error(input?: ReturnTypes): input is OAuth2Error;
 export interface WWWAuthenticateChallengeParameters {
     readonly realm?: string;
@@ -645,11 +698,11 @@ export interface WWWAuthenticateChallengeParameters {
     readonly algs?: string;
     readonly scope?: string;
     /** NOTE: because the parameter names are case insensitive they are always returned lowercased */
-    readonly [parameter: string]: string | undefined;
+    readonly [parameter: Lowercase<string>]: string | undefined;
 }
 export interface WWWAuthenticateChallenge {
     /** NOTE: because the value is case insensitive it is always returned lowercased */
-    readonly scheme: string;
+    readonly scheme: Lowercase<string>;
     readonly parameters: WWWAuthenticateChallengeParameters;
 }
 /**
@@ -657,6 +710,17 @@ export interface WWWAuthenticateChallenge {
  *
  * @returns Array of {@link WWWAuthenticateChallenge} objects. Their order from the response is
  *   preserved. `undefined` when there wasn't a `WWW-Authenticate` HTTP Header returned.
+ *
+ * @group Accessing Protected Resources
+ * @group Utilities
+ * @group Client Credentials Grant
+ * @group Device Authorization Grant
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group Token Introspection
+ * @group Token Revocation
+ * @group Refreshing an Access Token
+ * @group Pushed Authorization Requests (PAR)
  */
 export declare function parseWwwAuthenticateChallenges(response: Response): WWWAuthenticateChallenge[] | undefined;
 /**
@@ -671,7 +735,9 @@ export declare function parseWwwAuthenticateChallenges(response: Response): WWWA
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
- * @see [RFC 9126 - OAuth 2.0 Pushed Authorization Requests](https://www.rfc-editor.org/rfc/rfc9126.html#name-pushed-authorization-reques)
+ * @group Pushed Authorization Requests (PAR)
+ *
+ * @see [RFC 9126 - OAuth 2.0 Pushed Authorization Requests (PAR)](https://www.rfc-editor.org/rfc/rfc9126.html#name-pushed-authorization-reques)
  */
 export declare function processPushedAuthorizationResponse(as: AuthorizationServer, client: Client, response: Response): Promise<PushedAuthorizationResponse | OAuth2Error>;
 export interface ProtectedResourceRequestOptions extends Omit<HttpRequestOptions, 'headers'>, DPoPRequestOptions {
@@ -697,6 +763,8 @@ export interface ProtectedResourceRequestOptions extends Omit<HttpRequestOptions
  * @param headers Headers for the request.
  * @param body Request body compatible with the Fetch API and the request's method.
  *
+ * @group Accessing Protected Resources
+ *
  * @see [RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.1)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-protected-resource-access)
  */
@@ -713,6 +781,9 @@ export interface UserInfoRequestOptions extends HttpRequestOptions, DPoPRequestO
  * @param client Client Metadata.
  * @param accessToken Access Token value.
  *
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group OpenID Connect (OIDC) UserInfo
+ *
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-protected-resource-access)
  */
@@ -772,6 +843,9 @@ export declare const skipSubjectCheck: unique symbol;
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group OpenID Connect (OIDC) UserInfo
+ *
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
  */
 export declare function processUserInfoResponse(as: AuthorizationServer, client: Client, expectedSubject: string | typeof skipSubjectCheck, response: Response): Promise<UserInfoResponse>;
@@ -787,6 +861,8 @@ export interface TokenEndpointRequestOptions extends HttpRequestOptions, Authent
  * @param client Client Metadata.
  * @param refreshToken Refresh Token value.
  *
+ * @group Refreshing an Access Token
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-6)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-dpop-access-token-request)
@@ -798,6 +874,8 @@ export declare function refreshTokenGrantRequest(as: AuthorizationServer, client
  * @param ref Value previously resolved from {@link processAuthorizationCodeOpenIDResponse}.
  *
  * @returns JWT Claims Set from an ID Token.
+ *
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
  */
 export declare function getValidatedIdTokenClaims(ref: OpenIDTokenEndpointResponse): IDToken;
 /**
@@ -822,6 +900,8 @@ export declare function getValidatedIdTokenClaims(ref: TokenEndpointResponse): I
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Refreshing an Access Token
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-6)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens)
  */
@@ -837,6 +917,9 @@ export declare function processRefreshTokenResponse(as: AuthorizationServer, cli
  * @param redirectUri `redirect_uri` value used in the authorization request.
  * @param codeVerifier PKCE `code_verifier` to send to the token endpoint.
  *
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
  * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
@@ -870,7 +953,7 @@ export interface TokenEndpointResponse {
     readonly refresh_token?: string;
     readonly scope?: string;
     /** NOTE: because the value is case insensitive it is always returned lowercased */
-    readonly token_type: string;
+    readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
 export interface OpenIDTokenEndpointResponse {
@@ -880,7 +963,7 @@ export interface OpenIDTokenEndpointResponse {
     readonly refresh_token?: string;
     readonly scope?: string;
     /** NOTE: because the value is case insensitive it is always returned lowercased */
-    readonly token_type: string;
+    readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
 export interface OAuth2TokenEndpointResponse {
@@ -890,7 +973,7 @@ export interface OAuth2TokenEndpointResponse {
     readonly refresh_token?: string;
     readonly scope?: string;
     /** NOTE: because the value is case insensitive it is always returned lowercased */
-    readonly token_type: string;
+    readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
 export interface ClientCredentialsGrantResponse {
@@ -898,7 +981,7 @@ export interface ClientCredentialsGrantResponse {
     readonly expires_in?: number;
     readonly scope?: string;
     /** NOTE: because the value is case insensitive it is always returned lowercased */
-    readonly token_type: string;
+    readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
 /**
@@ -930,6 +1013,8 @@ export declare const skipAuthTimeCheck: unique symbol;
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
  */
@@ -946,6 +1031,8 @@ export declare function processAuthorizationCodeOpenIDResponse(as: Authorization
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Authorization Code Grant
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1)
  */
 export declare function processAuthorizationCodeOAuth2Response(as: AuthorizationServer, client: Client, response: Response): Promise<OAuth2TokenEndpointResponse | OAuth2Error>;
@@ -958,6 +1045,8 @@ export interface ClientCredentialsGrantRequestOptions extends HttpRequestOptions
  * @param as Authorization Server Metadata.
  * @param client Client Metadata.
  *
+ * @group Client Credentials Grant
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-dpop-access-token-request)
  */
@@ -974,6 +1063,8 @@ export declare function clientCredentialsGrantRequest(as: AuthorizationServer, c
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Client Credentials Grant
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4)
  */
 export declare function processClientCredentialsResponse(as: AuthorizationServer, client: Client, response: Response): Promise<ClientCredentialsGrantResponse | OAuth2Error>;
@@ -990,6 +1081,8 @@ export interface RevocationRequestOptions extends HttpRequestOptions, Authentica
  * @param token Token to revoke. You can provide the `token_type_hint` parameter via
  *   {@link RevocationRequestOptions.additionalParameters options}.
  *
+ * @group Token Revocation
+ *
  * @see [RFC 7009 - OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009.html#section-2)
  */
 export declare function revocationRequest(as: AuthorizationServer, client: Client, token: string, options?: RevocationRequestOptions): Promise<Response>;
@@ -1002,6 +1095,8 @@ export declare function revocationRequest(as: AuthorizationServer, client: Clien
  * @returns Resolves with `undefined` when the request was successful, or an object representing an
  *   OAuth 2.0 protocol style error.
  *
+ * @group Token Revocation
+ *
  * @see [RFC 7009 - OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009.html#section-2)
  */
 export declare function processRevocationResponse(response: Response): Promise<undefined | OAuth2Error>;
@@ -1028,6 +1123,8 @@ export interface IntrospectionRequestOptions extends HttpRequestOptions, Authent
  * @param token Token to introspect. You can provide the `token_type_hint` parameter via
  *   {@link IntrospectionRequestOptions.additionalParameters options}.
  *
+ * @group Token Introspection
+ *
  * @see [RFC 7662 - OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662.html#section-2)
  * @see [draft-ietf-oauth-jwt-introspection-response-12 - JWT Response for OAuth Token Introspection](https://www.ietf.org/archive/id/draft-ietf-oauth-jwt-introspection-response-12.html#section-4)
  */
@@ -1066,6 +1163,8 @@ export interface IntrospectionResponse {
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Token Introspection
+ *
  * @see [RFC 7662 - OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662.html#section-2)
  * @see [draft-ietf-oauth-jwt-introspection-response-12 - JWT Response for OAuth Token Introspection](https://www.ietf.org/archive/id/draft-ietf-oauth-jwt-introspection-response-12.html#section-5)
  */
@@ -1080,6 +1179,10 @@ export declare function processIntrospectionResponse(as: AuthorizationServer, cl
  *
  * @returns Validated Authorization Response parameters or Authorization Error Response.
  *
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ * @group JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)
+ *
  * @see [JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
  */
 export declare function validateJwtAuthResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedState?: string | typeof expectNoState | typeof skipStateCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
@@ -1111,6 +1214,9 @@ export declare const expectNoState: unique symbol;
  *
  * @returns Validated Authorization Response parameters or Authorization Error Response.
  *
+ * @group Authorization Code Grant
+ * @group Authorization Code Grant w/ OpenID Connect (OIDC)
+ *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.2)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
  * @see [RFC 9207 - OAuth 2.0 Authorization Server Issuer Identification](https://www.rfc-editor.org/rfc/rfc9207.html)
@@ -1127,6 +1233,8 @@ export interface DeviceAuthorizationRequestOptions extends HttpRequestOptions, A
  * @param client Client Metadata.
  * @param parameters Device Authorization Request parameters.
  *
+ * @group Device Authorization Grant
+ *
  * @see [RFC 8628 - OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628.html#section-3.1)
  */
 export declare function deviceAuthorizationRequest(as: AuthorizationServer, client: Client, parameters: URLSearchParams | Record<string, string> | string[][], options?: DeviceAuthorizationRequestOptions): Promise<Response>;
@@ -1151,6 +1259,8 @@ export interface DeviceAuthorizationResponse {
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Device Authorization Grant
+ *
  * @see [RFC 8628 - OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628.html#section-3.1)
  */
 export declare function processDeviceAuthorizationResponse(as: AuthorizationServer, client: Client, response: Response): Promise<DeviceAuthorizationResponse | OAuth2Error>;
@@ -1162,6 +1272,8 @@ export declare function processDeviceAuthorizationResponse(as: AuthorizationServ
  * @param client Client Metadata.
  * @param deviceCode Device Code.
  *
+ * @group Device Authorization Grant
+ *
  * @see [RFC 8628 - OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628.html#section-3.4)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-dpop-access-token-request)
  */
@@ -1178,6 +1290,8 @@ export declare function deviceCodeGrantRequest(as: AuthorizationServer, client:
  *   representing an OAuth 2.0 protocol style error. Use {@link isOAuth2Error} to determine if an
  *   OAuth 2.0 error was returned.
  *
+ * @group Device Authorization Grant
+ *
  * @see [RFC 8628 - OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628.html#section-3.4)
  */
 export declare function processDeviceCodeResponse(as: AuthorizationServer, client: Client, response: Response): Promise<TokenEndpointResponse | OAuth2Error>;
@@ -1193,6 +1307,8 @@ export interface GenerateKeyPairOptions {
  * Generates a CryptoKeyPair for a given JWS `alg` Algorithm identifier.
  *
  * @param alg Supported JWS `alg` Algorithm identifier.
+ *
+ * @group Utilities
  */
 export declare function generateKeyPair(alg: JWSAlgorithm, options?: GenerateKeyPairOptions): Promise<CryptoKeyPair>;
 export {};

package/build/index.js

@@ -1,7 +1,7 @@
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'oauth4webapi';
-    const VERSION = 'v2.4.0';
+    const VERSION = 'v2.4.1';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 export const clockSkew = Symbol();
@@ -194,12 +194,13 @@ export async function discoveryRequest(issuerIdentifier, options) {
     }
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
-    return fetch(url.href, {
+    const request = new Request(url.href, {
         headers,
         method: 'GET',
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    }).then(processDpopNonce);
+    });
+    return fetch(request).then(processDpopNonce);
 }
 function validateString(input) {
     return typeof input === 'string' && input.length !== 0;
@@ -654,13 +655,14 @@ export async function protectedResourceRequest(accessToken, method, url, headers
         await dpopProofJwt(headers, options.DPoP, url, 'GET', getClockSkew({ [clockSkew]: options?.clockSkew }), accessToken);
         headers.set('authorization', `DPoP ${accessToken}`);
     }
-    return fetch(url.href, {
+    const request = new Request(url.href, {
         body,
         headers,
         method,
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    }).then(processDpopNonce);
+    });
+    return fetch(request).then(processDpopNonce);
 }
 export async function userInfoRequest(as, client, accessToken, options) {
     assertAs(as);
@@ -820,13 +822,14 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
 async function authenticatedRequest(as, client, method, url, body, headers, options) {
     await clientAuthentication(as, client, body, headers, options?.clientPrivateKey);
     headers.set('content-type', 'application/x-www-form-urlencoded;charset=UTF-8');
-    return fetch(url.href, {
+    const request = new Request(url.href, {
         body,
         headers,
         method,
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    }).then(processDpopNonce);
+    });
+    return fetch(request).then(processDpopNonce);
 }
 async function tokenEndpointRequest(as, client, grantType, parameters, options) {
     if (typeof as.token_endpoint !== 'string') {
@@ -1186,12 +1189,13 @@ async function jwksRequest(as, options) {
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
     headers.append('accept', 'application/jwk-set+json');
-    return fetch(url.href, {
+    const request = new Request(url.href, {
         headers,
         method: 'GET',
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    }).then(processDpopNonce);
+    });
+    return fetch(request).then(processDpopNonce);
 }
 async function processJwksResponse(response) {
     if (!(response instanceof Response)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "auth",
@@ -63,22 +63,22 @@
     "test": "bash -c 'source .node_flags.sh && ava'"
   },
   "devDependencies": {
-    "@esbuild-kit/esm-loader": "^2.6.5",
-    "@types/node": "^20.9.0",
-    "@types/qunit": "^2.19.8",
+    "@types/node": "^20.10.6",
+    "@types/qunit": "^2.19.9",
     "ava": "^5.3.1",
     "edge-runtime": "^2.5.7",
-    "esbuild": "^0.19.5",
-    "jose": "^5.1.1",
+    "esbuild": "^0.19.11",
+    "jose": "^5.2.0",
     "patch-package": "^8.0.0",
-    "prettier": "^3.1.0",
-    "prettier-plugin-jsdoc": "^1.1.1",
+    "prettier": "^3.1.1",
+    "prettier-plugin-jsdoc": "^1.3.0",
     "qunit": "^2.20.0",
     "timekeeper": "^2.3.1",
-    "typedoc": "^0.25.3",
+    "tsx": "^4.7.0",
+    "typedoc": "^0.25.6",
     "typedoc-plugin-markdown": "^3.17.1",
-    "typedoc-plugin-mdn-links": "^3.1.0",
-    "typescript": "^5.2.2",
-    "undici": "^5.27.2"
+    "typedoc-plugin-mdn-links": "^3.1.10",
+    "typescript": "^5.3.3",
+    "undici": "^5.28.2"
   }
 }