oauth4webapi 2.8.1 → 2.10.0

package/README.md

@@ -44,7 +44,7 @@ import * as oauth2 from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.8.1/mod.ts'
+import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.10.0/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,12 +1,20 @@
-/** JSON Object */
+/**
+ * JSON Object
+ */
 export type JsonObject = {
     [Key in string]?: JsonValue;
 };
-/** JSON Array */
+/**
+ * JSON Array
+ */
 export type JsonArray = JsonValue[];
-/** JSON Primitives */
+/**
+ * JSON Primitives
+ */
 export type JsonPrimitive = string | number | boolean | null;
-/** JSON Values */
+/**
+ * JSON Values
+ */
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 /**
  * Interface to pass an asymmetric private key and, optionally, its associated JWK Key ID to be
@@ -130,9 +138,6 @@ export type JWSAlgorithm = 'PS256' | 'ES256' | 'RS256' | 'EdDSA' | 'ES384' | 'PS
 export declare const clockSkew: unique symbol;
 export declare const clockTolerance: unique symbol;
 /**
- * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
- * compatible changes or removal may occur in any future release.
- *
  * When configured on an interface that extends {@link HttpRequestOptions}, that's every `options`
  * parameter for functions that trigger HTTP Requests, this replaces the use of global fetch. As a
  * fetch replacement the arguments and expected return are the same as fetch.
@@ -156,12 +161,13 @@ export declare const clockTolerance: unique symbol;
  *
  * - Expect Type-related issues when passing the inputs through to fetch-like modules, they hardly
  *   ever get their typings inline with actual fetch, you should `@ts-expect-error` them.
- * - Returning self-constructed {@link Response} instances prohibits AS-signalled DPoP Nonce caching.
+ * - Returning self-constructed {@link Response} instances prohibits AS/RS-signalled DPoP Nonce
+ *   caching.
  *
  * @example
  *
- * Using [sindresorhus/ky](https://github.com/sindresorhus/ky) hooks feature for logging outgoing
- * requests and their responses.
+ * Using [sindresorhus/ky](https://github.com/sindresorhus/ky) for retries and its hooks feature for
+ * logging outgoing requests and their responses.
  *
  * ```js
  * import ky from 'ky'
@@ -169,7 +175,7 @@ export declare const clockTolerance: unique symbol;
  *
  * // example use
  * await oauth.discoveryRequest(new URL('https://as.example.com'), {
- *   [oauth.experimental_customFetch]: (...args) =>
+ *   [oauth.customFetch]: (...args) =>
  *     ky(args[0], {
  *       ...args[1],
  *       hooks: {
@@ -195,7 +201,7 @@ export declare const clockTolerance: unique symbol;
  *
  * @example
  *
- * Using [nodejs/undici](https://github.com/nodejs/undici) for mocking.
+ * Using [nodejs/undici](https://github.com/nodejs/undici) to mock responses in tests.
  *
  * ```js
  * import * as undici from 'undici'
@@ -210,26 +216,19 @@ export declare const clockTolerance: unique symbol;
  *
  * // example use
  * await oauth.discoveryRequest(new URL('https://as.example.com'), {
- *   [oauth.experimental_customFetch]: undici.fetch,
+ *   [oauth.customFetch]: undici.fetch,
  * })
  * ```
- *
- * @group Experimental
  */
-export declare const experimental_customFetch: unique symbol;
-/** @ignore */
-export declare const experimentalCustomFetch: symbol;
+export declare const customFetch: unique symbol;
 /**
- * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
- * compatible changes or removal may occur in any future release.
- *
- * When combined with {@link experimental_customFetch} (to use a Fetch API implementation that
- * supports client certificates) this can be used to target FAPI 2.0 profiles that utilize
- * Mutual-TLS for either client authentication or sender constraining. FAPI 1.0 Advanced profiles
- * that use PAR and JARM can also be targetted.
+ * When combined with {@link customFetch} (to use a Fetch API implementation that supports client
+ * certificates) this can be used to target FAPI 2.0 profiles that utilize Mutual-TLS for either
+ * client authentication or sender constraining. FAPI 1.0 Advanced profiles that use PAR and JARM
+ * can also be targetted.
  *
- * When configured on an interface that extends {@link ExperimentalUseMTLSAliasOptions} this makes
- * the client prioritize an endpoint URL present in
+ * When configured on an interface that extends {@link UseMTLSAliasOptions} this makes the client
+ * prioritize an endpoint URL present in
  * {@link AuthorizationServer.mtls_endpoint_aliases `as.mtls_endpoint_aliases`}.
  *
  * @example
@@ -242,8 +241,8 @@ export declare const experimentalCustomFetch: symbol;
  * import * as oauth from 'oauth4webapi'
  *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
- *   [oauth.experimental_useMtlsAlias]: true,
- *   [oauth.experimental_customFetch]: (...args) => {
+ *   [oauth.useMtlsAlias]: true,
+ *   [oauth.customFetch]: (...args) => {
  *     return undici.fetch(args[0], {
  *       ...args[1],
  *       dispatcher: new undici.Agent({
@@ -272,8 +271,8 @@ export declare const experimentalCustomFetch: symbol;
  * })
  *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
- *   [oauth.experimental_useMtlsAlias]: true,
- *   [oauth.experimental_customFetch]: (...args) => {
+ *   [oauth.useMtlsAlias]: true,
+ *   [oauth.customFetch]: (...args) => {
  *     return fetch(args[0], {
  *       ...args[1],
  *       client: agent,
@@ -282,30 +281,38 @@ export declare const experimentalCustomFetch: symbol;
  * })
  * ```
  *
- * @group Experimental
- *
  * @see [RFC 8705 - OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
  */
-export declare const experimental_useMtlsAlias: unique symbol;
-/** @ignore */
-export declare const experimentalUseMtlsAlias: symbol;
+export declare const useMtlsAlias: unique symbol;
 /**
  * Authorization Server Metadata
  *
  * @see [IANA OAuth Authorization Server Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata)
  */
 export interface AuthorizationServer {
-    /** Authorization server's Issuer Identifier URL. */
+    /**
+     * Authorization server's Issuer Identifier URL.
+     */
     readonly issuer: string;
-    /** URL of the authorization server's authorization endpoint. */
+    /**
+     * URL of the authorization server's authorization endpoint.
+     */
     readonly authorization_endpoint?: string;
-    /** URL of the authorization server's token endpoint. */
+    /**
+     * URL of the authorization server's token endpoint.
+     */
     readonly token_endpoint?: string;
-    /** URL of the authorization server's JWK Set document. */
+    /**
+     * URL of the authorization server's JWK Set document.
+     */
     readonly jwks_uri?: string;
-    /** URL of the authorization server's Dynamic Client Registration Endpoint. */
+    /**
+     * URL of the authorization server's Dynamic Client Registration Endpoint.
+     */
     readonly registration_endpoint?: string;
-    /** JSON array containing a list of the `scope` values that this authorization server supports. */
+    /**
+     * JSON array containing a list of the `scope` values that this authorization server supports.
+     */
     readonly scopes_supported?: string[];
     /**
      * JSON array containing a list of the `response_type` values that this authorization server
@@ -322,7 +329,9 @@ export interface AuthorizationServer {
      * supports.
      */
     readonly grant_types_supported?: string[];
-    /** JSON array containing a list of client authentication methods supported by this token endpoint. */
+    /**
+     * JSON array containing a list of client authentication methods supported by this token endpoint.
+     */
     readonly token_endpoint_auth_methods_supported?: string[];
     /**
      * JSON array containing a list of the JWS signing algorithms supported by the token endpoint for
@@ -350,7 +359,9 @@ export interface AuthorizationServer {
      * the authorization server's terms of service.
      */
     readonly op_tos_uri?: string;
-    /** URL of the authorization server's revocation endpoint. */
+    /**
+     * URL of the authorization server's revocation endpoint.
+     */
     readonly revocation_endpoint?: string;
     /**
      * JSON array containing a list of client authentication methods supported by this revocation
@@ -362,7 +373,9 @@ export interface AuthorizationServer {
      * for the signature on the JWT used to authenticate the client at the revocation endpoint.
      */
     readonly revocation_endpoint_auth_signing_alg_values_supported?: string[];
-    /** URL of the authorization server's introspection endpoint. */
+    /**
+     * URL of the authorization server's introspection endpoint.
+     */
     readonly introspection_endpoint?: string;
     /**
      * JSON array containing a list of client authentication methods supported by this introspection
@@ -375,20 +388,30 @@ export interface AuthorizationServer {
      * endpoint.
      */
     readonly introspection_endpoint_auth_signing_alg_values_supported?: string[];
-    /** PKCE code challenge methods supported by this authorization server. */
+    /**
+     * PKCE code challenge methods supported by this authorization server.
+     */
     readonly code_challenge_methods_supported?: string[];
-    /** Signed JWT containing metadata values about the authorization server as claims. */
+    /**
+     * Signed JWT containing metadata values about the authorization server as claims.
+     */
     readonly signed_metadata?: string;
-    /** URL of the authorization server's device authorization endpoint. */
+    /**
+     * URL of the authorization server's device authorization endpoint.
+     */
     readonly device_authorization_endpoint?: string;
-    /** Indicates authorization server support for mutual-TLS client certificate-bound access tokens. */
+    /**
+     * Indicates authorization server support for mutual-TLS client certificate-bound access tokens.
+     */
     readonly tls_client_certificate_bound_access_tokens?: boolean;
     /**
      * JSON object containing alternative authorization server endpoints, which a client intending to
      * do mutual TLS will use in preference to the conventional endpoints.
      */
     readonly mtls_endpoint_aliases?: MTLSEndpointAliases;
-    /** URL of the authorization server's UserInfo Endpoint. */
+    /**
+     * URL of the authorization server's UserInfo Endpoint.
+     */
     readonly userinfo_endpoint?: string;
     /**
      * JSON array containing a list of the Authentication Context Class References that this
@@ -415,11 +438,17 @@ export interface AuthorizationServer {
      * the ID Token.
      */
     readonly id_token_encryption_enc_values_supported?: string[];
-    /** JSON array containing a list of the JWS `alg` values supported by the UserInfo Endpoint. */
+    /**
+     * JSON array containing a list of the JWS `alg` values supported by the UserInfo Endpoint.
+     */
     readonly userinfo_signing_alg_values_supported?: string[];
-    /** JSON array containing a list of the JWE `alg` values supported by the UserInfo Endpoint. */
+    /**
+     * JSON array containing a list of the JWE `alg` values supported by the UserInfo Endpoint.
+     */
     readonly userinfo_encryption_alg_values_supported?: string[];
-    /** JSON array containing a list of the JWE `enc` values supported by the UserInfo Endpoint. */
+    /**
+     * JSON array containing a list of the JWE `enc` values supported by the UserInfo Endpoint.
+     */
     readonly userinfo_encryption_enc_values_supported?: string[];
     /**
      * JSON array containing a list of the JWS `alg` values supported by the authorization server for
@@ -441,7 +470,9 @@ export interface AuthorizationServer {
      * supports.
      */
     readonly display_values_supported?: string[];
-    /** JSON array containing a list of the Claim Types that the authorization server supports. */
+    /**
+     * JSON array containing a list of the Claim Types that the authorization server supports.
+     */
     readonly claim_types_supported?: string[];
     /**
      * JSON array containing a list of the Claim Names of the Claims that the authorization server MAY
@@ -478,9 +509,13 @@ export interface AuthorizationServer {
      * through either `request` or `request_uri` parameter.
      */
     readonly require_signed_request_object?: boolean;
-    /** URL of the authorization server's pushed authorization request endpoint. */
+    /**
+     * URL of the authorization server's pushed authorization request endpoint.
+     */
     readonly pushed_authorization_request_endpoint?: string;
-    /** Indicates whether the authorization server accepts authorization requests only via PAR. */
+    /**
+     * Indicates whether the authorization server accepts authorization requests only via PAR.
+     */
     readonly require_pushed_authorization_requests?: boolean;
     /**
      * JSON array containing a list of algorithms supported by the authorization server for
@@ -517,23 +552,31 @@ export interface AuthorizationServer {
      * introspection response encryption (`enc` value).
      */
     readonly authorization_encryption_enc_values_supported?: string[];
-    /** CIBA Backchannel Authentication Endpoint. */
+    /**
+     * CIBA Backchannel Authentication Endpoint.
+     */
     readonly backchannel_authentication_endpoint?: string;
     /**
      * JSON array containing a list of the JWS signing algorithms supported for validation of signed
      * CIBA authentication requests.
      */
     readonly backchannel_authentication_request_signing_alg_values_supported?: string[];
-    /** Supported CIBA authentication result delivery modes. */
+    /**
+     * Supported CIBA authentication result delivery modes.
+     */
     readonly backchannel_token_delivery_modes_supported?: string[];
-    /** Indicates whether the authorization server supports the use of the CIBA `user_code` parameter. */
+    /**
+     * Indicates whether the authorization server supports the use of the CIBA `user_code` parameter.
+     */
     readonly backchannel_user_code_parameter_supported?: boolean;
     /**
      * URL of an authorization server iframe that supports cross-origin communications for session
      * state information with the RP Client, using the HTML5 postMessage API.
      */
     readonly check_session_iframe?: string;
-    /** JSON array containing a list of the JWS algorithms supported for DPoP proof JWTs. */
+    /**
+     * JSON array containing a list of the JWS algorithms supported for DPoP proof JWTs.
+     */
     readonly dpop_signing_alg_values_supported?: string[];
     /**
      * URL at the authorization server to which an RP can perform a redirect to request that the
@@ -546,14 +589,18 @@ export interface AuthorizationServer {
      * `frontchannel_logout_uri` is used.
      */
     readonly frontchannel_logout_session_supported?: boolean;
-    /** Boolean value specifying whether the authorization server supports HTTP-based logout. */
+    /**
+     * Boolean value specifying whether the authorization server supports HTTP-based logout.
+     */
     readonly frontchannel_logout_supported?: boolean;
     /**
      * Boolean value specifying whether the authorization server can pass a `sid` (session ID) Claim
      * in the Logout Token to identify the RP session with the OP.
      */
     readonly backchannel_logout_session_supported?: boolean;
-    /** Boolean value specifying whether the authorization server supports back-channel logout. */
+    /**
+     * Boolean value specifying whether the authorization server supports back-channel logout.
+     */
     readonly backchannel_logout_supported?: boolean;
     readonly [metadata: string]: JsonValue | undefined;
 }
@@ -566,9 +613,13 @@ export interface MTLSEndpointAliases extends Pick<AuthorizationServer, 'token_en
  * @see [IANA OAuth Client Registration Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#client-metadata)
  */
 export interface Client {
-    /** Client identifier. */
+    /**
+     * Client identifier.
+     */
     client_id: string;
-    /** Client secret. */
+    /**
+     * Client secret.
+     */
     client_secret?: string;
     /**
      * Client {@link ClientAuthenticationMethod authentication method} for the client's authenticated
@@ -608,7 +659,9 @@ export interface Client {
      * and fall back to `RS256` when the authorization server metadata is not set.
      */
     introspection_signed_response_alg?: string;
-    /** Default Maximum Authentication Age. */
+    /**
+     * Default Maximum Authentication Age.
+     */
     default_max_age?: number;
     /**
      * Use to adjust the client's assumed current time. Positive and negative finite values
@@ -658,11 +711,15 @@ export interface Client {
     [clockTolerance]?: number;
     [metadata: string]: JsonValue | undefined;
 }
-/** @group Errors */
+/**
+ * @group Errors
+ */
 export declare class UnsupportedOperationError extends Error {
     constructor(message?: string);
 }
-/** @group Errors */
+/**
+ * @group Errors
+ */
 export declare class OperationProcessingError extends Error {
     constructor(message: string, options?: {
         cause?: unknown;
@@ -682,20 +739,19 @@ export interface HttpRequestOptions {
      * ```
      */
     signal?: (() => AbortSignal) | AbortSignal;
-    /** Headers to additionally send with the HTTP Request(s) triggered by this function's invocation. */
+    /**
+     * Headers to additionally send with the HTTP Request(s) triggered by this function's invocation.
+     */
     headers?: [string, string][] | Record<string, string> | Headers;
     /**
-     * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
-     * compatible changes or removal may occur in any future release.
-     *
-     * See {@link experimental_customFetch} for its documentation.
-     *
-     * @group Experimental
+     * See {@link customFetch}.
      */
-    [experimental_customFetch]?: typeof fetch;
+    [customFetch]?: typeof fetch;
 }
 export interface DiscoveryRequestOptions extends HttpRequestOptions {
-    /** The issuer transformation algorithm to use. */
+    /**
+     * The issuer transformation algorithm to use.
+     */
     algorithm?: 'oidc' | 'oauth2';
 }
 /**
@@ -737,9 +793,9 @@ export declare function processDiscoveryResponse(expectedIssuerIdentifier: URL,
  * @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)
+ * @group Proof Key for Code Exchange (PKCE)
  *
- * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
+ * @see [RFC 7636 - Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
  */
 export declare function generateRandomCodeVerifier(): string;
 /**
@@ -766,9 +822,9 @@ export declare function generateRandomNonce(): string;
  *
  * @group Authorization Code Grant
  * @group Authorization Code Grant w/ OpenID Connect (OIDC)
- * @group Proof Key for Code Exchange by OAuth Public Clients (PKCE)
+ * @group Proof Key for Code Exchange (PKCE)
  *
- * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
+ * @see [RFC 7636 - Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
  */
 export declare function calculatePKCECodeChallenge(codeVerifier: string): Promise<string>;
 export interface DPoPOptions extends CryptoKeyPair {
@@ -778,7 +834,9 @@ export interface DPoPOptions extends CryptoKeyPair {
      * Its algorithm must be compatible with a supported {@link JWSAlgorithm JWS `alg` Algorithm}.
      */
     privateKey: CryptoKey;
-    /** The public key corresponding to {@link DPoPOptions.privateKey}. */
+    /**
+     * The public key corresponding to {@link DPoPOptions.privateKey}.
+     */
     publicKey: CryptoKey;
     /**
      * Server-Provided Nonce to use in the request. This option serves as an override in case the
@@ -788,21 +846,18 @@ export interface DPoPOptions extends CryptoKeyPair {
     nonce?: string;
 }
 export interface DPoPRequestOptions {
-    /** DPoP-related options. */
+    /**
+     * DPoP-related options.
+     */
     DPoP?: DPoPOptions;
 }
-export interface ExperimentalUseMTLSAliasOptions {
+export interface UseMTLSAliasOptions {
     /**
-     * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
-     * compatible changes or removal may occur in any future release.
-     *
-     * See {@link experimental_useMtlsAlias} for its documentation.
-     *
-     * @group Experimental
+     * See {@link useMtlsAlias}.
      */
-    [experimental_useMtlsAlias]?: boolean;
+    [useMtlsAlias]?: boolean;
 }
-export interface AuthenticatedRequestOptions extends ExperimentalUseMTLSAliasOptions {
+export interface AuthenticatedRequestOptions extends UseMTLSAliasOptions {
     /**
      * Private key to use for `private_key_jwt`
      * {@link ClientAuthenticationMethod client authentication}. Its algorithm must be compatible with
@@ -874,11 +929,15 @@ export interface WWWAuthenticateChallengeParameters {
     readonly error_uri?: string;
     readonly algs?: string;
     readonly scope?: string;
-    /** NOTE: because the parameter names are case insensitive they are always returned lowercased */
+    /**
+     * NOTE: because the parameter names are case insensitive they are always returned lowercased
+     */
     readonly [parameter: Lowercase<string>]: string | undefined;
 }
 export interface WWWAuthenticateChallenge {
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly scheme: Lowercase<string>;
     readonly parameters: WWWAuthenticateChallengeParameters;
 }
@@ -944,7 +1003,7 @@ export interface ProtectedResourceRequestOptions extends Omit<HttpRequestOptions
  * @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)
  */
 export declare function protectedResourceRequest(accessToken: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | string, url: URL, headers: Headers, body?: ReadableStream | Blob | ArrayBufferView | ArrayBuffer | FormData | URLSearchParams | string | null, options?: ProtectedResourceRequestOptions): Promise<Response>;
-export interface UserInfoRequestOptions extends HttpRequestOptions, DPoPRequestOptions, ExperimentalUseMTLSAliasOptions {
+export interface UserInfoRequestOptions extends HttpRequestOptions, DPoPRequestOptions, UseMTLSAliasOptions {
 }
 /**
  * Performs a UserInfo Request at the
@@ -1025,7 +1084,9 @@ export declare const skipSubjectCheck: unique symbol;
  */
 export declare function processUserInfoResponse(as: AuthorizationServer, client: Client, expectedSubject: string | typeof skipSubjectCheck, response: Response): Promise<UserInfoResponse>;
 export interface TokenEndpointRequestOptions extends HttpRequestOptions, AuthenticatedRequestOptions, DPoPRequestOptions {
-    /** Any additional parameters to send. This cannot override existing parameter values. */
+    /**
+     * Any additional parameters to send. This cannot override existing parameter values.
+     */
     additionalParameters?: URLSearchParams | Record<string, string> | string[][];
 }
 /**
@@ -1097,7 +1158,7 @@ export declare function processRefreshTokenResponse(as: AuthorizationServer, cli
  *
  * @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)
+ * @see [RFC 7636 - Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-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)
  */
 export declare function authorizationCodeGrantRequest(as: AuthorizationServer, client: Client, callbackParameters: URLSearchParams, redirectUri: string, codeVerifier: string, options?: TokenEndpointRequestOptions): Promise<Response>;
@@ -1123,13 +1184,25 @@ export interface IDToken extends JWTPayload {
     readonly azp?: string;
     readonly [claim: string]: JsonValue | undefined;
 }
+export interface AuthorizationDetails {
+    readonly type: string;
+    readonly locations?: string[];
+    readonly actions?: string[];
+    readonly datatypes?: string[];
+    readonly privileges?: string[];
+    readonly identifier?: string;
+    readonly [parameter: string]: JsonValue | undefined;
+}
 export interface TokenEndpointResponse {
     readonly access_token: string;
     readonly expires_in?: number;
     readonly id_token?: string;
     readonly refresh_token?: string;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    readonly authorization_details?: AuthorizationDetails[];
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1139,7 +1212,10 @@ export interface OpenIDTokenEndpointResponse {
     readonly id_token: string;
     readonly refresh_token?: string;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    readonly authorization_details?: AuthorizationDetails[];
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1149,7 +1225,10 @@ export interface OAuth2TokenEndpointResponse {
     readonly id_token?: undefined;
     readonly refresh_token?: string;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    readonly authorization_details?: AuthorizationDetails[];
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1157,7 +1236,10 @@ export interface ClientCredentialsGrantResponse {
     readonly access_token: string;
     readonly expires_in?: number;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    readonly authorization_details?: AuthorizationDetails[];
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1246,7 +1328,9 @@ export declare function clientCredentialsGrantRequest(as: AuthorizationServer, c
  */
 export declare function processClientCredentialsResponse(as: AuthorizationServer, client: Client, response: Response): Promise<ClientCredentialsGrantResponse | OAuth2Error>;
 export interface RevocationRequestOptions extends HttpRequestOptions, AuthenticatedRequestOptions {
-    /** Any additional parameters to send. This cannot override existing parameter values. */
+    /**
+     * Any additional parameters to send. This cannot override existing parameter values.
+     */
     additionalParameters?: URLSearchParams | Record<string, string> | string[][];
 }
 /**
@@ -1278,7 +1362,9 @@ export declare function revocationRequest(as: AuthorizationServer, client: Clien
  */
 export declare function processRevocationResponse(response: Response): Promise<undefined | OAuth2Error>;
 export interface IntrospectionRequestOptions extends HttpRequestOptions, AuthenticatedRequestOptions {
-    /** Any additional parameters to send. This cannot override existing parameter values. */
+    /**
+     * Any additional parameters to send. This cannot override existing parameter values.
+     */
     additionalParameters?: URLSearchParams | Record<string, string> | string[][];
     /**
      * Request a JWT Response from the
@@ -1311,8 +1397,6 @@ export interface ConfirmationClaims {
     readonly jkt?: string;
     readonly [claim: string]: JsonValue | undefined;
 }
-/** @ignore */
-export type IntrospectionConfirmationClaims = ConfirmationClaims;
 export interface IntrospectionResponse {
     readonly active: boolean;
     readonly client_id?: string;
@@ -1323,11 +1407,12 @@ export interface IntrospectionResponse {
     readonly jti?: string;
     readonly username?: string;
     readonly aud?: string | string[];
-    readonly scope: string;
+    readonly scope?: string;
     readonly sub?: string;
     readonly nbf?: number;
     readonly token_type?: string;
     readonly cnf?: ConfirmationClaims;
+    readonly authorization_details?: AuthorizationDetails[];
     readonly [claim: string]: JsonValue | undefined;
 }
 /**
@@ -1366,9 +1451,6 @@ export declare function processIntrospectionResponse(as: AuthorizationServer, cl
  */
 export declare function validateJwtAuthResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedState?: string | typeof expectNoState | typeof skipStateCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
- * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
- * compatible changes or removal may occur in any future release.
- *
  * Same as {@link validateAuthResponse} but for FAPI 1.0 Advanced Detached Signature authorization
  * responses.
  *
@@ -1387,11 +1469,10 @@ export declare function validateJwtAuthResponse(as: AuthorizationServer, client:
  * @returns Validated Authorization Response parameters or Authorization Error Response.
  *
  * @group FAPI 1.0 Advanced
- * @group Experimental
  *
  * @see [Financial-grade API Security Profile 1.0 - Part 2: Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html#id-token-as-detached-signature)
  */
-export declare function experimental_validateDetachedSignatureResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedNonce: string, expectedState?: string | typeof expectNoState, maxAge?: number | typeof skipAuthTimeCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
+export declare function validateDetachedSignatureResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedNonce: string, expectedState?: string | typeof expectNoState, maxAge?: number | typeof skipAuthTimeCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
  * DANGER ZONE
  *
@@ -1501,11 +1582,17 @@ export declare function deviceCodeGrantRequest(as: AuthorizationServer, client:
  */
 export declare function processDeviceCodeResponse(as: AuthorizationServer, client: Client, response: Response): Promise<TokenEndpointResponse | OAuth2Error>;
 export interface GenerateKeyPairOptions {
-    /** Indicates whether or not the private key may be exported. Default is `false`. */
+    /**
+     * Indicates whether or not the private key may be exported. Default is `false`.
+     */
     extractable?: boolean;
-    /** (RSA algorithms only) The length, in bits, of the RSA modulus. Default is `2048`. */
+    /**
+     * (RSA algorithms only) The length, in bits, of the RSA modulus. Default is `2048`.
+     */
     modulusLength?: number;
-    /** (EdDSA algorithms only) The EdDSA sub-type. Default is `Ed25519`. */
+    /**
+     * (EdDSA algorithms only) The EdDSA sub-type. Default is `Ed25519`.
+     */
     crv?: 'Ed25519' | 'Ed448';
 }
 /**
@@ -1524,20 +1611,25 @@ export interface JWTAccessTokenClaims extends JWTPayload {
     readonly iat: number;
     readonly jti: string;
     readonly client_id: string;
+    readonly authorization_details?: AuthorizationDetails[];
+    readonly scope?: string;
     readonly [claim: string]: JsonValue | undefined;
 }
 export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
-    /** Indicates whether DPoP use is required. */
+    /**
+     * Indicates whether DPoP use is required.
+     */
     requireDPoP?: boolean;
-    /** Same functionality as in {@link Client} */
+    /**
+     * Same functionality as in {@link Client}
+     */
     [clockSkew]?: number;
-    /** Same functionality as in {@link Client} */
+    /**
+     * Same functionality as in {@link Client}
+     */
     [clockTolerance]?: number;
 }
 /**
- * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
- * compatible changes or removal may occur in any future release.
- *
  * Validates use of JSON Web Token (JWT) OAuth 2.0 Access Tokens for a given {@link Request} as per
  * RFC 9068 and optionally also RFC 9449.
  *
@@ -1562,10 +1654,57 @@ export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
  * @param options
  *
  * @group JWT Access Tokens
- * @group Experimental
  *
  * @see [RFC 9068 - JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://www.rfc-editor.org/rfc/rfc9068.html)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html)
  */
-export declare function experimental_validateJwtAccessToken(as: AuthorizationServer, request: Request, expectedAudience: string, options?: ValidateJWTAccessTokenOptions): Promise<JWTAccessTokenClaims>;
+export declare function validateJwtAccessToken(as: AuthorizationServer, request: Request, expectedAudience: string, options?: ValidateJWTAccessTokenOptions): Promise<JWTAccessTokenClaims>;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link customFetch}.
+ */
+export declare const experimentalCustomFetch: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link customFetch}.
+ */
+export declare const experimental_customFetch: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link useMtlsAlias}.
+ */
+export declare const experimentalUseMtlsAlias: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link useMtlsAlias}.
+ */
+export declare const experimental_useMtlsAlias: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link UseMTLSAliasOptions}.
+ */
+export type ExperimentalUseMTLSAliasOptions = UseMTLSAliasOptions;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link ConfirmationClaims}.
+ */
+export type IntrospectionConfirmationClaims = ConfirmationClaims;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link validateDetachedSignatureResponse}.
+ */
+export declare const experimental_validateDetachedSignatureResponse: typeof validateDetachedSignatureResponse;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link validateJwtAccessToken}.
+ */
+export declare const experimental_validateJwtAccessToken: typeof validateJwtAccessToken;
 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.8.1';
+    const VERSION = 'v2.10.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -18,10 +18,8 @@ function looseInstanceOf(input, expected) {
 }
 export const clockSkew = Symbol();
 export const clockTolerance = Symbol();
-export const experimental_customFetch = Symbol();
-export const experimentalCustomFetch = experimental_customFetch;
-export const experimental_useMtlsAlias = Symbol();
-export const experimentalUseMtlsAlias = experimental_useMtlsAlias;
+export const customFetch = Symbol();
+export const useMtlsAlias = Symbol();
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 function buf(input) {
@@ -145,14 +143,13 @@ const SUPPORTED_JWS_ALGS = [
 ];
 function processDpopNonce(response) {
     try {
-        if (response.headers.has('dpop-nonce')) {
-            const url = new URL(response.url);
-            dpopNonces.set(url.origin, response.headers.get('dpop-nonce'));
+        const nonce = response.headers.get('dpop-nonce');
+        if (nonce) {
+            dpopNonces.set(new URL(response.url).origin, nonce);
         }
     }
-    finally {
-        return response;
-    }
+    catch { }
+    return response;
 }
 function normalizeTyp(value) {
     return value.toLowerCase().replace(/^application\//, '');
@@ -203,7 +200,7 @@ export async function discoveryRequest(issuerIdentifier, options) {
             break;
         case 'oauth2':
             if (url.pathname === '/') {
-                url.pathname = `.well-known/oauth-authorization-server`;
+                url.pathname = '.well-known/oauth-authorization-server';
             }
             else {
                 url.pathname = `.well-known/oauth-authorization-server/${url.pathname}`.replace('//', '/');
@@ -214,7 +211,7 @@ export async function discoveryRequest(issuerIdentifier, options) {
     }
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
-    return (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
@@ -344,21 +341,14 @@ function keyToJws(key) {
     }
 }
 function getClockSkew(client) {
-    if (client && clockSkew in client) {
-        if (Number.isFinite(client[clockSkew])) {
-            return client[clockSkew];
-        }
-    }
-    return 0;
+    const skew = client?.[clockSkew];
+    return typeof skew === 'number' && Number.isFinite(skew) ? skew : 0;
 }
 function getClockTolerance(client) {
-    if (client && clockTolerance in client) {
-        const tolerance = client[clockTolerance];
-        if (Number.isFinite(tolerance) && Math.sign(tolerance) !== -1) {
-            return tolerance;
-        }
-    }
-    return 30;
+    const tolerance = client?.[clockTolerance];
+    return typeof tolerance === 'number' && Number.isFinite(tolerance) && Math.sign(tolerance) !== -1
+        ? tolerance
+        : 30;
 }
 function epochTime() {
     return Math.floor(Date.now() / 1000);
@@ -491,8 +481,8 @@ export async function issueRequestObject(as, client, parameters, privateKey) {
         resource.length > 1) {
         claims.resource = resource;
     }
-    if (parameters.has('claims')) {
-        const value = parameters.get('claims');
+    let value = parameters.get('claims');
+    if (value) {
         if (value === '[object Object]') {
             throw new OPE('"claims" parameter must be passed as a UTF-8 encoded JSON');
         }
@@ -542,31 +532,27 @@ async function dpopProofJwt(headers, options, url, htm, clockSkew, accessToken)
     headers.set('dpop', proof);
 }
 let jwkCache;
-async function publicJwk(key) {
-    jwkCache || (jwkCache = new WeakMap());
-    if (jwkCache.has(key)) {
-        return jwkCache.get(key);
-    }
+async function getSetPublicJwkCache(key) {
     const { kty, e, n, x, y, crv } = await crypto.subtle.exportKey('jwk', key);
     const jwk = { kty, e, n, x, y, crv };
     jwkCache.set(key, jwk);
     return jwk;
 }
+async function publicJwk(key) {
+    jwkCache || (jwkCache = new WeakMap());
+    return jwkCache.get(key) || getSetPublicJwkCache(key);
+}
 function validateEndpoint(value, endpoint, options) {
     if (typeof value !== 'string') {
-        if (options?.[experimental_useMtlsAlias]) {
+        if (options?.[useMtlsAlias]) {
             throw new TypeError(`"as.mtls_endpoint_aliases.${endpoint}" must be a string`);
         }
-        else {
-            throw new TypeError(`"as.${endpoint}" must be a string`);
-        }
+        throw new TypeError(`"as.${endpoint}" must be a string`);
     }
     return new URL(value);
 }
 function resolveEndpoint(as, endpoint, options) {
-    if (options?.[experimental_useMtlsAlias] &&
-        as.mtls_endpoint_aliases &&
-        endpoint in as.mtls_endpoint_aliases) {
+    if (options?.[useMtlsAlias] && as.mtls_endpoint_aliases && endpoint in as.mtls_endpoint_aliases) {
         return validateEndpoint(as.mtls_endpoint_aliases[endpoint], endpoint, options);
     }
     return validateEndpoint(as[endpoint], endpoint);
@@ -625,10 +611,10 @@ export function parseWwwAuthenticateChallenges(response) {
     if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
-    if (!response.headers.has('www-authenticate')) {
+    const header = response.headers.get('www-authenticate');
+    if (header === null) {
         return undefined;
     }
-    const header = response.headers.get('www-authenticate');
     const result = [];
     for (const { 1: scheme, index } of header.matchAll(SCHEMES_REGEXP)) {
         result.push([scheme, index]);
@@ -696,7 +682,7 @@ 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 (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         body,
         headers: Object.fromEntries(headers.entries()),
         method,
@@ -795,7 +781,7 @@ async function getPublicSigKeyFromIssuerJwksUri(as, options, header) {
         }
         throw new OPE('error when selecting a JWT verification key, no applicable keys found');
     }
-    else if (length !== 1) {
+    if (length !== 1) {
         throw new OPE('error when selecting a JWT verification key, multiple applicable keys found, a "kid" JWT Header Parameter is required');
     }
     const key = await importJwk(alg, jwk);
@@ -859,7 +845,7 @@ 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 (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         body,
         headers: Object.fromEntries(headers.entries()),
         method,
@@ -1222,7 +1208,7 @@ async function jwksRequest(as, options) {
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
     headers.append('accept', 'application/jwk-set+json');
-    return (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
@@ -1472,7 +1458,7 @@ async function idTokenHashMatches(data, actual, alg, key) {
     const expected = await idTokenHash(alg, data, key);
     return actual === expected;
 }
-export async function experimental_validateDetachedSignatureResponse(as, client, parameters, expectedNonce, expectedState, maxAge, options) {
+export async function validateDetachedSignatureResponse(as, client, parameters, expectedNonce, expectedState, maxAge, options) {
     assertAs(as);
     assertClient(client);
     if (parameters instanceof URL) {
@@ -1775,8 +1761,9 @@ function normalizeHtu(htu) {
     url.hash = '';
     return url.href;
 }
-async function validateDPoP(as, request, accessTokenClaims, options) {
-    if (!request.headers.has('dpop')) {
+async function validateDPoP(as, request, accessToken, accessTokenClaims, options) {
+    const header = request.headers.get('dpop');
+    if (header === null) {
         throw new OPE('operation indicated DPoP use but the request has no DPoP HTTP Header');
     }
     if (request.headers.get('authorization')?.toLowerCase().startsWith('dpop ') === false) {
@@ -1786,7 +1773,7 @@ async function validateDPoP(as, request, accessTokenClaims, options) {
         throw new OPE('operation indicated DPoP use but the JWT Access Token has no jkt confirmation claim');
     }
     const clockSkew = getClockSkew(options);
-    const proof = await validateJwt(request.headers.get('dpop'), checkSigningAlgorithm.bind(undefined, undefined, as?.dpop_signing_alg_values_supported || SUPPORTED_JWS_ALGS), async ({ jwk, alg }) => {
+    const proof = await validateJwt(header, checkSigningAlgorithm.bind(undefined, undefined, as?.dpop_signing_alg_values_supported || SUPPORTED_JWS_ALGS), async ({ jwk, alg }) => {
         if (!jwk) {
             throw new OPE('DPoP Proof is missing the jwk header parameter');
         }
@@ -1811,7 +1798,6 @@ async function validateDPoP(as, request, accessTokenClaims, options) {
         throw new OPE('DPoP Proof htu mismatch');
     }
     {
-        const accessToken = request.headers.get('authorization').split(' ')[1];
         const expected = b64u(await crypto.subtle.digest('SHA-256', encoder.encode(accessToken)));
         if (proof.claims.ath !== expected) {
             throw new OPE('DPoP Proof ath mismatch');
@@ -1851,7 +1837,7 @@ async function validateDPoP(as, request, accessTokenClaims, options) {
         }
     }
 }
-export async function experimental_validateJwtAccessToken(as, request, expectedAudience, options) {
+export async function validateJwtAccessToken(as, request, expectedAudience, options) {
     assertAs(as);
     if (!looseInstanceOf(request, Request)) {
         throw new TypeError('"request" must be an instance of Request');
@@ -1860,7 +1846,7 @@ export async function experimental_validateJwtAccessToken(as, request, expectedA
         throw new OPE('"expectedAudience" must be a non-empty string');
     }
     const authorization = request.headers.get('authorization');
-    if (!authorization) {
+    if (authorization === null) {
         throw new OPE('"request" is missing an Authorization HTTP Header');
     }
     let { 0: scheme, 1: accessToken, length } = authorization.split(' ');
@@ -1915,7 +1901,13 @@ export async function experimental_validateJwtAccessToken(as, request, expectedA
         scheme === 'dpop' ||
         claims.cnf?.jkt !== undefined ||
         request.headers.has('dpop')) {
-        await validateDPoP(as, request, claims, options);
+        await validateDPoP(as, request, accessToken, claims, options);
     }
     return claims;
 }
+export const experimentalCustomFetch = customFetch;
+export const experimental_customFetch = customFetch;
+export const experimentalUseMtlsAlias = useMtlsAlias;
+export const experimental_useMtlsAlias = useMtlsAlias;
+export const experimental_validateDetachedSignatureResponse = validateDetachedSignatureResponse;
+export const experimental_validateJwtAccessToken = validateJwtAccessToken;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "access token",
@@ -67,20 +67,20 @@
   "devDependencies": {
     "@koa/cors": "^5.0.0",
     "@types/koa__cors": "^5.0.0",
-    "@types/node": "^20.11.6",
+    "@types/node": "^20.11.16",
     "@types/oidc-provider": "^8.4.3",
     "@types/qunit": "^2.19.10",
     "archiver": "^6.0.1",
     "ava": "^5.3.1",
     "chrome-launcher": "^1.1.0",
     "edge-runtime": "^2.5.8",
-    "esbuild": "^0.19.12",
-    "jose": "^5.2.0",
+    "esbuild": "^0.20.0",
+    "jose": "^5.2.1",
     "oidc-provider": "^8.4.5",
     "patch-package": "^8.0.0",
-    "prettier": "^3.2.4",
+    "prettier": "^3.2.5",
     "prettier-plugin-jsdoc": "^1.3.0",
-    "puppeteer-core": "^21.7.0",
+    "puppeteer-core": "^21.11.0",
     "qunit": "^2.20.0",
     "raw-body": "^2.5.2",
     "selfsigned": "^2.4.1",
@@ -88,7 +88,7 @@
     "tsx": "^4.7.0",
     "typedoc": "^0.25.7",
     "typedoc-plugin-markdown": "^3.17.1",
-    "typedoc-plugin-mdn-links": "^3.1.13",
+    "typedoc-plugin-mdn-links": "^3.1.15",
     "typescript": "^5.3.3",
     "undici": "^5.28.2"
   }